Skip to content

Commit ee33c0b

Browse files
sean-perkinssean-perkins
authored
docs(picker): new documentation pages for picker and picker-legacy (#3321)
1 parent 1a164ca commit ee33c0b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1318
-227
lines changed

‎docs/api/picker-column-option.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: "ion-picker-column-option"
3+
---
4+
import Props from '@ionic-internal/component-api/v8/picker-column-option/props.md';
5+
import Events from '@ionic-internal/component-api/v8/picker-column-option/events.md';
6+
import Methods from '@ionic-internal/component-api/v8/picker-column-option/methods.md';
7+
import Parts from '@ionic-internal/component-api/v8/picker-column-option/parts.md';
8+
import CustomProps from '@ionic-internal/component-api/v8/picker-column-option/custom-props.md';
9+
import Slots from '@ionic-internal/component-api/v8/picker-column-option/slots.md';
10+
11+
<head>
12+
<title>ion-picker-column-option: The individual options within a column in a picker.</title>
13+
<meta name="description" content="An individual column option in a picker." />
14+
</head>
15+
16+
import EncapsulationPill from '@components/page/api/EncapsulationPill';
17+
18+
<EncapsulationPill type="shadow" />
19+
20+
An individual column option in a picker. Visit the [`ion-picker`](./picker.md) documentation for more details.
21+
22+
## Properties
23+
<Props />
24+
25+
## Events
26+
<Events />
27+
28+
## Methods
29+
<Methods />
30+
31+
## CSS Shadow Parts
32+
<Parts />
33+
34+
## CSS Custom Properties
35+
<CustomProps />
36+
37+
## Slots
38+
<Slots />

‎docs/api/picker-column.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: "ion-picker-column"
3+
---
4+
import Props from '@ionic-internal/component-api/v8/picker-column/props.md';
5+
import Events from '@ionic-internal/component-api/v8/picker-column/events.md';
6+
import Methods from '@ionic-internal/component-api/v8/picker-column/methods.md';
7+
import Parts from '@ionic-internal/component-api/v8/picker-column/parts.md';
8+
import CustomProps from '@ionic-internal/component-api/v8/picker-column/custom-props.md';
9+
import Slots from '@ionic-internal/component-api/v8/picker-column/slots.md';
10+
11+
<head>
12+
<title>ion-picker-column: Individual columns within a picker</title>
13+
<meta name="description" content="An individual column within a picker." />
14+
</head>
15+
16+
import EncapsulationPill from '@components/page/api/EncapsulationPill';
17+
18+
<EncapsulationPill type="shadow" />
19+
20+
An individual column within a picker. Visit the [`ion-picker`](./picker.md) documentation for more details.
21+
22+
## Properties
23+
<Props />
24+
25+
## Events
26+
<Events />
27+
28+
## Methods
29+
<Methods />
30+
31+
## CSS Shadow Parts
32+
<Parts />
33+
34+
## CSS Custom Properties
35+
<CustomProps />
36+
37+
## Slots
38+
<Slots />

‎docs/api/picker-legacy.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: "ion-picker-legacy"
3+
---
4+
import Props from '@ionic-internal/component-api/v8/picker-legacy/props.md';
5+
import Events from '@ionic-internal/component-api/v8/picker-legacy/events.md';
6+
import Methods from '@ionic-internal/component-api/v8/picker-legacy/methods.md';
7+
import Parts from '@ionic-internal/component-api/v8/picker-legacy/parts.md';
8+
import CustomProps from '@ionic-internal/component-api/v8/picker-legacy/custom-props.md';
9+
import Slots from '@ionic-internal/component-api/v8/picker-legacy/slots.md';
10+
11+
<head>
12+
<title>ion-picker-legacy: A Dialog That Displays Buttons and Columns</title>
13+
<meta name="description" content="A Picker is a dialog that displays a row of buttons and columns underneath. Ion-picker-legacy appears on top of the app's content, and at the bottom of the viewport." />
14+
</head>
15+
16+
import EncapsulationPill from '@components/page/api/EncapsulationPill';
17+
18+
<EncapsulationPill type="scoped" />
19+
20+
:::warning Deprecation Notice
21+
22+
`ion-picker-legacy` is deprecated and will be removed in the next major release. Migrate to [`ion-picker`](./picker.md) as soon as possible.
23+
24+
:::
25+
26+
A Picker is a dialog that displays a row of buttons and columns underneath. It appears on top of the app's content, and at the bottom of the viewport.
27+
28+
## Inline Pickers (Recommended)
29+
30+
`ion-picker-legacy` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Picker.
31+
32+
import Trigger from '@site/static/usage/v8/picker-legacy/inline/trigger/index.md';
33+
34+
<Trigger />
35+
36+
### Using `isOpen`
37+
38+
The `isOpen` property on `ion-picker-legacy` allows developers to control the presentation state of the Picker from their application state. This means when `isOpen` is set to `true` the Picker will be presented, and when `isOpen` is set to `false` the Picker will be dismissed.
39+
40+
`isOpen` uses a one-way data binding, meaning it will not automatically be set to `false` when the Picker is dismissed. Developers should listen for the `ionPickerDidDismiss` or `didDismiss` event and set `isOpen` to `false`. The reason for this is it prevents the internals of `ion-picker` from being tightly coupled with the state of the application. With a one way data binding, the Picker only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Picker needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.
41+
42+
import IsOpen from '@site/static/usage/v8/picker-legacy/inline/isOpen/index.md';
43+
44+
<IsOpen />
45+
46+
## Controller Pickers
47+
48+
The `pickerController` can be used in situations where more control is needed over when the Picker is presented and dismissed.
49+
50+
import Controller from '@site/static/usage/v8/picker-legacy/controller/index.md';
51+
52+
<Controller />
53+
54+
## Multiple Columns
55+
56+
The `columns` property can be used to display a Picker with multiple columns of different options.
57+
58+
import MultipleColumn from '@site/static/usage/v8/picker-legacy/multiple-column/index.md';
59+
60+
<MultipleColumn />
61+
62+
## Interfaces
63+
64+
### PickerButton
65+
66+
```typescript
67+
interface PickerButton {
68+
text?: string;
69+
role?: string;
70+
cssClass?: string | string[];
71+
handler?: (value: any) => boolean | void;
72+
}
73+
```
74+
75+
### PickerColumn
76+
77+
```typescript
78+
interface PickerColumn {
79+
name: string;
80+
align?: string;
81+
/**
82+
* Changing this value allows the initial value of a picker column to be set.
83+
*/
84+
selectedIndex?: number;
85+
prevSelected?: number;
86+
prefix?: string;
87+
suffix?: string;
88+
options: PickerColumnOption[];
89+
cssClass?: string | string[];
90+
columnWidth?: string;
91+
prefixWidth?: string;
92+
suffixWidth?: string;
93+
optionsWidth?: string;
94+
}
95+
```
96+
97+
### PickerColumnOption
98+
99+
```typescript
100+
interface PickerColumnOption {
101+
text?: string;
102+
value?: any;
103+
disabled?: boolean;
104+
duration?: number;
105+
transform?: string;
106+
selected?: boolean;
107+
/**
108+
* The optional text to assign as the aria-label on the picker column option.
109+
*/
110+
ariaLabel?: string;
111+
}
112+
```
113+
114+
### PickerOptions
115+
116+
```typescript
117+
interface PickerOptions {
118+
columns: PickerColumn[];
119+
buttons?: PickerButton[];
120+
cssClass?: string | string[];
121+
showBackdrop?: boolean;
122+
backdropDismiss?: boolean;
123+
animated?: boolean;
124+
125+
mode?: Mode;
126+
keyboardClose?: boolean;
127+
id?: string;
128+
htmlAttributes?: { [key: string]: any };
129+
130+
enterAnimation?: AnimationBuilder;
131+
leaveAnimation?: AnimationBuilder;
132+
}
133+
```
134+
135+
## Properties
136+
<Props />
137+
138+
## Events
139+
<Events />
140+
141+
## Methods
142+
<Methods />
143+
144+
## CSS Shadow Parts
145+
<Parts />
146+
147+
## CSS Custom Properties
148+
<CustomProps />
149+
150+
## Slots
151+
<Slots />

‎docs/api/picker.md

Lines changed: 19 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -9,122 +9,45 @@ import CustomProps from '@ionic-internal/component-api/v8/picker/custom-props.md
99
import Slots from '@ionic-internal/component-api/v8/picker/slots.md';
1010

1111
<head>
12-
<title>ion-picker: A Dialog That Displays Buttons and Columns</title>
13-
<meta name="description" content="A Picker is a dialog that displays a row of buttons and columns underneath. Ion-picker appears on top of the app's content, and at the bottom of the viewport." />
12+
<title>ion-picker: Display a list of options in columns</title>
13+
<meta name="description" content="A Picker displays one or more columns with options for users to choose from." />
1414
</head>
1515

1616
import EncapsulationPill from '@components/page/api/EncapsulationPill';
1717

18-
<EncapsulationPill type="scoped" />
18+
<EncapsulationPill type="shadow" />
1919

20-
A Picker is a dialog that displays a row of buttons and columns underneath. It appears on top of the app's content, and at the bottom of the viewport.
20+
A Picker displays one or more columns with options for users to choose from.
2121

22-
## Inline Pickers (Recommended)
22+
import Basic from '@site/static/usage/v8/picker/basic/index.md';
2323

24-
`ion-picker` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Picker.
24+
<Basic />
2525

26-
import Trigger from '@site/static/usage/v8/picker/inline/trigger/index.md';
26+
## Prefix & Suffix Content
2727

28-
<Trigger />
28+
Use the `prefix` and `suffix` slots to add additional content to the picker.
2929

30-
### Using `isOpen`
30+
import PrefixSuffix from '@site/static/usage/v8/picker/prefix-suffix/index.md';
3131

32-
The `isOpen` property on `ion-picker` allows developers to control the presentation state of the Picker from their application state. This means when `isOpen` is set to `true` the Picker will be presented, and when `isOpen` is set to `false` the Picker will be dismissed.
32+
<PrefixSuffix />
3333

34-
`isOpen` uses a one-way data binding, meaning it will not automatically be set to `false` when the Picker is dismissed. Developers should listen for the `ionPickerDidDismiss` or `didDismiss` event and set `isOpen` to `false`. The reason for this is it prevents the internals of `ion-picker` from being tightly coupled with the state of the application. With a one way data binding, the Picker only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the Picker needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.
34+
## Theming
3535

36-
import IsOpen from '@site/static/usage/v8/picker/inline/isOpen/index.md';
36+
### CSS Variables
3737

38-
<IsOpen />
38+
The picker highlight and fade can be customized using CSS variables on `ion-picker`. Developers can customize the individual appearance of `ion-picker-column-options` by targeting them directly and using host level styling.
3939

40-
## Controller Pickers
40+
import CSSProps from '@site/static/usage/v8/picker/theming/css-properties/index.md';
4141

42-
The `pickerController` can be used in situations where more control is needed over when the Picker is presented and dismissed.
42+
<CSSProps />
4343

44-
import Controller from '@site/static/usage/v8/picker/controller/index.md';
44+
## Picker in Modal
4545

46-
<Controller />
46+
Pickers can be displayed inside of overlays, such as `ion-modal` to create a picker experience with confirmation or cancellation buttons.
4747

48-
## Multiple Columns
48+
import ModalExample from '@site/static/usage/v8/picker/modal/index.md';
4949

50-
The `columns` property can be used to display a Picker with multiple columns of different options.
51-
52-
import MultipleColumn from '@site/static/usage/v8/picker/multiple-column/index.md';
53-
54-
<MultipleColumn />
55-
56-
## Interfaces
57-
58-
### PickerButton
59-
60-
```typescript
61-
interface PickerButton {
62-
text?: string;
63-
role?: string;
64-
cssClass?: string | string[];
65-
handler?: (value: any) => boolean | void;
66-
}
67-
```
68-
69-
### PickerColumn
70-
71-
```typescript
72-
interface PickerColumn {
73-
name: string;
74-
align?: string;
75-
/**
76-
* Changing this value allows the initial value of a picker column to be set.
77-
*/
78-
selectedIndex?: number;
79-
prevSelected?: number;
80-
prefix?: string;
81-
suffix?: string;
82-
options: PickerColumnOption[];
83-
cssClass?: string | string[];
84-
columnWidth?: string;
85-
prefixWidth?: string;
86-
suffixWidth?: string;
87-
optionsWidth?: string;
88-
}
89-
```
90-
91-
### PickerColumnOption
92-
93-
```typescript
94-
interface PickerColumnOption {
95-
text?: string;
96-
value?: any;
97-
disabled?: boolean;
98-
duration?: number;
99-
transform?: string;
100-
selected?: boolean;
101-
/**
102-
* The optional text to assign as the aria-label on the picker column option.
103-
*/
104-
ariaLabel?: string;
105-
}
106-
```
107-
108-
### PickerOptions
109-
110-
```typescript
111-
interface PickerOptions {
112-
columns: PickerColumn[];
113-
buttons?: PickerButton[];
114-
cssClass?: string | string[];
115-
showBackdrop?: boolean;
116-
backdropDismiss?: boolean;
117-
animated?: boolean;
118-
119-
mode?: Mode;
120-
keyboardClose?: boolean;
121-
id?: string;
122-
htmlAttributes?: { [key: string]: any };
123-
124-
enterAnimation?: AnimationBuilder;
125-
leaveAnimation?: AnimationBuilder;
126-
}
127-
```
50+
<ModalExample />
12851

12952
## Properties
13053
<Props />

‎plugins/docusaurus-plugin-ionic-component-api/index.js

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,15 @@ module.exports = function (context, options) {
4545

4646
for (const version of options.versions) {
4747
const npmTag = version.slice(1);
48+
4849
await generateMarkdownForVersion(version, npmTag, false);
4950
}
5051

5152
let npmTag = 'latest';
5253
if (currentVersion.banner === 'unreleased') {
53-
npmTag = 'next';
54+
// TODO create a ticket to re-enable this once v8 is released.
55+
// npmTag = 'next';
56+
npmTag = '7.5.8-dev.11702398696.1ab62ea9';
5457
} else if (currentVersion.path !== undefined) {
5558
npmTag = currentVersion.path.slice(1);
5659
}

0 commit comments

Comments
 (0)