Skip to content

Commit bdff643

Browse files
liamdebeasiliamdebeasi
authored
docs(item): add best practices and usage guides (#3123)
1 parent 846bf99 commit bdff643

Some content is hidden

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

59 files changed

+2785
-79
lines changed

‎docs/api/input.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,8 @@ Material Design offers filled styles for an input. The `fill` property on the in
8585

8686
Since the `fill` styles visually defines the input container, inputs that use `fill` should not be used in `ion-item`.
8787

88+
Filled inputs can be used on iOS by setting Input's `mode` to `md`.
89+
8890
import Fill from '@site/static/usage/v7/input/fill/index.md';
8991

9092
<Fill />

‎docs/api/item.md

Lines changed: 142 additions & 19 deletions
Large diffs are not rendered by default.

‎docs/api/textarea.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ Material Design offers filled styles for a textarea. The `fill` property on the
6969

7070
Since the `fill` styles visually defines the textarea container, textareas that use `fill` should not be used in `ion-item`.
7171

72+
Filled textareas can be used on iOS by setting Textarea's `mode` to `md`.
73+
7274
import Fill from '@site/static/usage/v7/textarea/fill/index.md';
7375

7476
<Fill />

‎src/components/global/BestPracticeFigure/best-practice-figure.css

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
.best-practice__do_dont {
2+
display: grid;
3+
4+
grid-template-columns: 1fr 1fr;
5+
6+
gap: 12px;
7+
}
8+
9+
/* Collapse to 1 column per row on smaller viewports */
10+
@media (max-width: 996px) {
11+
.best-practice__do_dont {
12+
grid-template-columns: 1fr;
13+
}
14+
}
15+
16+
.best-practice__container figcaption {
17+
text-align: start;
18+
}
19+
20+
.best-practice__do p,
21+
.best-practice__dont p,
22+
.best-practice__caution p {
23+
padding: 8px 16px;
24+
}
25+
26+
.best-practice__image-wrapper {
27+
border-radius: 8px 8px 0px 0px;
28+
29+
overflow: hidden;
30+
}
31+
32+
.best-practice__dont-text,
33+
.best-practice__do-text,
34+
.best-practice__caution-text {
35+
padding: 12px 16px;
36+
37+
font-weight: 600;
38+
39+
border-radius: 0px 0px 8px 8px;
40+
}
41+
42+
.best-practice__do .best-practice__image-wrapper {
43+
border: 1px solid var(--c-blue-10);
44+
}
45+
46+
.best-practice__dont .best-practice__image-wrapper {
47+
border: 1px solid var(--c-red-10);
48+
}
49+
50+
.best-practice__caution .best-practice__image-wrapper {
51+
border: 1px solid var(--c-yellow-10);
52+
}
53+
54+
.best-practice__dont-text {
55+
color: var(--c-red-100);
56+
background: var(--c-red-10);
57+
}
58+
.best-practice__do-text {
59+
color: var(--c-blue-100);
60+
background: var(--c-blue-10);
61+
}
62+
63+
.best-practice__caution-text {
64+
/* --c-yellow-100 does not have enough contrast
65+
* placed on top of --c-yellow-10, so we manually
66+
* choose a darker text color here.
67+
*/
68+
color: #7e5e17;
69+
background: var(--c-yellow-10);
70+
}

‎src/components/global/BestPracticeFigure/index.tsx

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import React from 'react';
2+
3+
import './best-practice-figure.css';
4+
5+
/**
6+
Usage:
7+
8+
import BestPracticeFigure from '@components/global/BestPracticeFigure';
9+
10+
<BestPracticeFigure
11+
text="..."
12+
doText="..."
13+
dontText="..."
14+
doImage={<img alt="..." src={useBaseUrl(...)} />}
15+
dontImage={<img alt="..." src={useBaseUrl(...)} />}
16+
/>
17+
18+
All images must have alt text for screen readers.
19+
20+
Custom HTML can also be passed to any of the text properties by using curly braces:
21+
22+
text={<>My text with a <a href="#">link</a></>}
23+
24+
Markdown such as backticks will not be processed when using curly braces.
25+
The <code> tag can be used instead:
26+
27+
text={<>The <code>button</code> property</>}
28+
29+
This component also supports a caution option. Typically you should use
30+
either a "Don't" image or a "Caution" image but not both.
31+
32+
<BestPracticeFigure
33+
text="..."
34+
doText="..."
35+
cautionText="..."
36+
doImage={<img alt="..." src={useBaseUrl(...)} />}
37+
cautionImage={<img alt="..." src={useBaseUrl(...)} />}
38+
/>
39+
40+
@prop text - Text that describes the figure as a whole
41+
@prop doText - Text that describes a best practice
42+
@prop dontText - Text that describes an anti-pattern
43+
@prop cautionText - Text that describes something that could be an anti-pattern based on use case
44+
@prop doImage - Image associated with doText
45+
@prop dontImage - Image associated with dontText
46+
@prop cautionImage - Image associated with cautionText
47+
*/
48+
49+
export default function BestPracticeFigure({ text, doText, dontText, cautionText, doImage, dontImage, cautionImage }) {
50+
return (
51+
<div className="best-practice__container">
52+
<p>{text}</p>
53+
<div className="best-practice__do_dont">
54+
<figure className="best-practice__do">
55+
<div className="best-practice__image-wrapper">{doImage}</div>
56+
<figcaption>
57+
<div className="best-practice__do-text">Do</div>
58+
<p>{doText}</p>
59+
</figcaption>
60+
</figure>
61+
{dontText && dontImage && (
62+
<figure className="best-practice__dont">
63+
<div className="best-practice__image-wrapper">{dontImage}</div>
64+
<figcaption>
65+
<div className="best-practice__dont-text">Don't</div>
66+
<p>{dontText}</p>
67+
</figcaption>
68+
</figure>
69+
)}
70+
{cautionText && cautionImage && (
71+
<figure className="best-practice__caution">
72+
<div className="best-practice__image-wrapper">{cautionImage}</div>
73+
<figcaption>
74+
<div className="best-practice__caution-text">Caution</div>
75+
<p>{cautionText}</p>
76+
</figcaption>
77+
</figure>
78+
)}
79+
</div>
80+
</div>
81+
);
82+
}

‎static/img/item/actions-do.jpg

485 KB
Loading

‎static/img/item/actions-dont.jpg

784 KB
Loading

‎static/img/item/controls-count-do.jpg

471 KB
Loading

‎static/img/item/controls-count-dont.jpg

537 KB
Loading

‎static/img/item/controls-metadata-do.jpg

436 KB
Loading

‎static/img/item/controls-metadata-dont.jpg

408 KB
Loading

‎static/img/item/controls-metadata-list-do.jpg

559 KB
Loading

‎static/img/item/controls-metadata-list-dont.jpg

521 KB
Loading

‎static/img/item/long-text-do.jpg

845 KB
Loading

‎static/img/item/long-text-dont.jpg

950 KB
Loading

‎static/img/item/metadata-important-caution.jpg

733 KB
Loading

‎static/img/item/metadata-relevant-do.jpg

539 KB
Loading

‎static/img/item/metadata-relevant-dont.jpg

621 KB
Loading

‎static/img/item/visuals-do.jpg

311 KB
Loading

‎static/img/item/visuals-dont.jpg

330 KB
Loading

‎static/usage/v7/item/content-types/actions/angular.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
```html
2+
<ion-header>
3+
<ion-toolbar>
4+
<ion-title>Example</ion-title>
5+
</ion-toolbar>
6+
</ion-header>
7+
<ion-content color="light">
8+
<ion-list [inset]="true">
9+
<ion-item-sliding>
10+
<ion-item [button]="true">
11+
<ion-avatar aria-hidden="true" slot="start">
12+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
13+
</ion-avatar>
14+
<ion-label>Rick Astley</ion-label>
15+
</ion-item>
16+
<ion-item-options slot="end">
17+
<ion-item-option color="warning">
18+
<ion-icon slot="icon-only" name="pin"></ion-icon>
19+
</ion-item-option>
20+
<ion-item-option color="tertiary">
21+
<ion-icon slot="icon-only" name="share"></ion-icon>
22+
</ion-item-option>
23+
<ion-item-option color="danger" expandable="true">
24+
<ion-icon slot="icon-only" name="trash"></ion-icon>
25+
</ion-item-option>
26+
</ion-item-options>
27+
</ion-item-sliding>
28+
29+
<ion-item-sliding>
30+
<ion-item [button]="true">
31+
<ion-avatar aria-hidden="true" slot="start">
32+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
33+
</ion-avatar>
34+
<ion-label>Leeroy Jenkins</ion-label>
35+
</ion-item>
36+
<ion-item-options slot="end">
37+
<ion-item-option color="warning">
38+
<ion-icon slot="icon-only" name="pin"></ion-icon>
39+
</ion-item-option>
40+
<ion-item-option color="tertiary">
41+
<ion-icon slot="icon-only" name="share"></ion-icon>
42+
</ion-item-option>
43+
<ion-item-option color="danger" expandable="true">
44+
<ion-icon slot="icon-only" name="trash"></ion-icon>
45+
</ion-item-option>
46+
</ion-item-options>
47+
</ion-item-sliding>
48+
49+
<ion-item-sliding>
50+
<ion-item [button]="true">
51+
<ion-avatar aria-hidden="true" slot="start">
52+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
53+
</ion-avatar>
54+
<ion-label>Ionitron</ion-label>
55+
</ion-item>
56+
<ion-item-options slot="end">
57+
<ion-item-option color="warning">
58+
<ion-icon slot="icon-only" name="pin"></ion-icon>
59+
</ion-item-option>
60+
<ion-item-option color="tertiary">
61+
<ion-icon slot="icon-only" name="share"></ion-icon>
62+
</ion-item-option>
63+
<ion-item-option color="danger" expandable="true">
64+
<ion-icon slot="icon-only" name="trash"></ion-icon>
65+
</ion-item-option>
66+
</ion-item-options>
67+
</ion-item-sliding>
68+
69+
<ion-item-sliding>
70+
<ion-item [button]="true">
71+
<ion-avatar aria-hidden="true" slot="start">
72+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
73+
</ion-avatar>
74+
<ion-label>Wall-E</ion-label>
75+
</ion-item>
76+
<ion-item-options slot="end">
77+
<ion-item-option color="warning">
78+
<ion-icon slot="icon-only" name="pin"></ion-icon>
79+
</ion-item-option>
80+
<ion-item-option color="tertiary">
81+
<ion-icon slot="icon-only" name="share"></ion-icon>
82+
</ion-item-option>
83+
<ion-item-option color="danger" expandable="true">
84+
<ion-icon slot="icon-only" name="trash"></ion-icon>
85+
</ion-item-option>
86+
</ion-item-options>
87+
</ion-item-sliding>
88+
89+
<ion-item-sliding>
90+
<ion-item [button]="true">
91+
<ion-avatar aria-hidden="true" slot="start">
92+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
93+
</ion-avatar>
94+
<ion-label>Cortana</ion-label>
95+
</ion-item>
96+
<ion-item-options slot="end">
97+
<ion-item-option color="warning">
98+
<ion-icon slot="icon-only" name="pin"></ion-icon>
99+
</ion-item-option>
100+
<ion-item-option color="tertiary">
101+
<ion-icon slot="icon-only" name="share"></ion-icon>
102+
</ion-item-option>
103+
<ion-item-option color="danger" expandable="true">
104+
<ion-icon slot="icon-only" name="trash"></ion-icon>
105+
</ion-item-option>
106+
</ion-item-options>
107+
</ion-item-sliding>
108+
109+
<ion-item-sliding>
110+
<ion-item [button]="true">
111+
<ion-avatar aria-hidden="true" slot="start">
112+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
113+
</ion-avatar>
114+
<ion-label>Bender</ion-label>
115+
</ion-item>
116+
<ion-item-options slot="end">
117+
<ion-item-option color="warning">
118+
<ion-icon slot="icon-only" name="pin"></ion-icon>
119+
</ion-item-option>
120+
<ion-item-option color="tertiary">
121+
<ion-icon slot="icon-only" name="share"></ion-icon>
122+
</ion-item-option>
123+
<ion-item-option color="danger" expandable="true">
124+
<ion-icon slot="icon-only" name="trash"></ion-icon>
125+
</ion-item-option>
126+
</ion-item-options>
127+
</ion-item-sliding>
128+
129+
<ion-item-sliding>
130+
<ion-item [button]="true">
131+
<ion-avatar aria-hidden="true" slot="start">
132+
<img alt="" src="https://ionicframework.com/docs/img/demos/avatar.svg" />
133+
</ion-avatar>
134+
<ion-label>BB-8</ion-label>
135+
</ion-item>
136+
<ion-item-options slot="end">
137+
<ion-item-option color="warning">
138+
<ion-icon slot="icon-only" name="pin"></ion-icon>
139+
</ion-item-option>
140+
<ion-item-option color="tertiary">
141+
<ion-icon slot="icon-only" name="share"></ion-icon>
142+
</ion-item-option>
143+
<ion-item-option color="danger" expandable="true">
144+
<ion-icon slot="icon-only" name="trash"></ion-icon>
145+
</ion-item-option>
146+
</ion-item-options>
147+
</ion-item-sliding>
148+
</ion-list>
149+
</ion-content>
150+
```

0 commit comments

Comments
 (0)