Skip to content

Commit a47e79f

Browse files
brandyscarneybrandyscarney
authored
docs(api): add accessibility section for new htmlAttributes property (#3064)
1 parent f947b4a commit a47e79f

File tree

3 files changed

+403
-25
lines changed

3 files changed

+403
-25
lines changed

‎docs/api/action-sheet.md

+146-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
---
22
title: "ion-action-sheet"
33
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
47
import Props from '@ionic-internal/component-api/v7/action-sheet/props.md';
58
import Events from '@ionic-internal/component-api/v7/action-sheet/events.md';
69
import Methods from '@ionic-internal/component-api/v7/action-sheet/methods.md';
@@ -94,10 +97,150 @@ import CssCustomProperties from '@site/static/usage/v7/action-sheet/theming/css-
9497

9598
## Accessibility
9699

100+
### Screen Readers
101+
102+
Action Sheets set aria properties in order to be [accessible](../reference/glossary#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the action sheet is being used in an app.
103+
104+
#### Role
105+
97106
Action Sheets are given a `role` of [`dialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role). In order to align with the ARIA spec, either the `aria-label` or `aria-labelledby` attribute must be set.
98107

108+
#### Action Sheet Description
109+
99110
It is strongly recommended that every Action Sheet have the `header` property defined, as Ionic will automatically set `aria-labelledby` to point to the header element. However, if you choose not to include a `header`, an alternative is to use the `htmlAttributes` property to provide a descriptive `aria-label` or set a custom `aria-labelledby` value.
100111

112+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
113+
114+
<TabItem value="angular">
115+
116+
```javascript
117+
const actionSheet = await this.actionSheetController.create({
118+
htmlAttributes: {
119+
'aria-label': 'action sheet dialog',
120+
},
121+
});
122+
```
123+
124+
</TabItem>
125+
126+
<TabItem value="javascript">
127+
128+
```javascript
129+
const actionSheet = await this.actionSheetController.create({
130+
htmlAttributes: {
131+
'aria-label': 'action sheet dialog',
132+
},
133+
});
134+
```
135+
136+
</TabItem>
137+
138+
<TabItem value="react">
139+
140+
```javascript
141+
useIonActionSheet({
142+
htmlAttributes: {
143+
'aria-label': 'action sheet dialog',
144+
},
145+
});
146+
```
147+
148+
</TabItem>
149+
150+
<TabItem value="vue">
151+
152+
```javascript
153+
const actionSheet = await actionSheetController.create({
154+
htmlAttributes: {
155+
'aria-label': 'action sheet dialog',
156+
},
157+
});
158+
```
159+
160+
</TabItem>
161+
162+
</Tabs>
163+
164+
#### Action Sheet Buttons Description
165+
166+
Buttons containing text will be read by a screen reader. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing `aria-label` to the `htmlAttributes` property on the button.
167+
168+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
169+
170+
<TabItem value="angular">
171+
172+
```javascript
173+
const actionSheet = await this.actionSheetController.create({
174+
header: 'Header',
175+
buttons: [
176+
{
177+
icon: 'close',
178+
htmlAttributes: {
179+
'aria-label': 'close',
180+
},
181+
},
182+
],
183+
});
184+
```
185+
186+
</TabItem>
187+
188+
<TabItem value="javascript">
189+
190+
```javascript
191+
const actionSheet = await this.actionSheetController.create({
192+
header: 'Header',
193+
buttons: [
194+
{
195+
icon: 'close',
196+
htmlAttributes: {
197+
'aria-label': 'close',
198+
},
199+
},
200+
],
201+
});
202+
```
203+
204+
</TabItem>
205+
206+
<TabItem value="react">
207+
208+
```javascript
209+
useIonActionSheet({
210+
header: 'Header',
211+
buttons: [
212+
{
213+
icon: 'close',
214+
htmlAttributes: {
215+
'aria-label': 'close',
216+
},
217+
},
218+
],
219+
});
220+
```
221+
222+
</TabItem>
223+
224+
<TabItem value="vue">
225+
226+
```javascript
227+
const actionSheet = await actionSheetController.create({
228+
header: 'Header',
229+
buttons: [
230+
{
231+
icon: 'close',
232+
htmlAttributes: {
233+
'aria-label': 'close',
234+
},
235+
},
236+
],
237+
});
238+
```
239+
240+
</TabItem>
241+
242+
</Tabs>
243+
101244
## Interfaces
102245

103246
### ActionSheetButton
@@ -108,6 +251,8 @@ interface ActionSheetButton<T = any> {
108251
role?: 'cancel' | 'destructive' | 'selected' | string;
109252
icon?: string;
110253
cssClass?: string | string[];
254+
id?: string;
255+
htmlAttributes?: { [key: string]: any };
111256
handler?: () => boolean | void | Promise<boolean | void>;
112257
data?: T;
113258
}
@@ -150,4 +295,4 @@ interface ActionSheetOptions {
150295
<CustomProps />
151296

152297
## Slots
153-
<Slots />
298+
<Slots />

‎docs/api/alert.md

+150-2
Original file line numberDiff line numberDiff line change
@@ -111,25 +111,173 @@ import Customization from '@site/static/usage/v7/alert/customization/index.md';
111111

112112
## Accessibility
113113

114+
### Screen Readers
115+
116+
Alerts set aria properties in order to be [accessible](../reference/glossary#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the alert is being used in an app.
117+
118+
#### Role
119+
114120
Ionic automatically sets the Alert's `role` to either [`alertdialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) if there are any inputs or buttons included, or [`alert`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) if there are none.
115121

122+
#### Alert Description
123+
116124
If the `header` property is defined for the Alert, the `aria-labelledby` attribute will be automatically set to the header's ID. The `subHeader` element will be used as a fallback if `header` is not defined. Similarly, the `aria-describedby` attribute will be automatically set to the ID of the `message` element if that property is defined.
117125

118126
It is strongly recommended that your Alert have a `message`, as well as either a `header` or `subHeader`, in order to align with the ARIA spec. If you choose not to include a `header` or `subHeader`, an alternative is to provide a descriptive `aria-label` using the `htmlAttributes` property.
119127

128+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
129+
130+
<TabItem value="angular">
131+
132+
```javascript
133+
const alert = await this.alertController.create({
134+
message: 'This is an alert with custom aria attributes.',
135+
htmlAttributes: {
136+
'aria-label': 'alert dialog',
137+
},
138+
});
139+
```
140+
141+
</TabItem>
142+
143+
<TabItem value="javascript">
144+
145+
```javascript
146+
const alert = await this.alertController.create({
147+
message: 'This is an alert with custom aria attributes.',
148+
htmlAttributes: {
149+
'aria-label': 'alert dialog',
150+
},
151+
});
152+
```
153+
154+
</TabItem>
155+
156+
<TabItem value="react">
157+
158+
```javascript
159+
useIonAlert({
160+
message: 'This is an alert with custom aria attributes.',
161+
htmlAttributes: {
162+
'aria-label': 'alert dialog',
163+
},
164+
});
165+
```
166+
167+
</TabItem>
168+
169+
<TabItem value="vue">
170+
171+
```javascript
172+
const alert = await alertController.create({
173+
message: 'This is an alert with custom aria attributes.',
174+
htmlAttributes: {
175+
'aria-label': 'alert dialog',
176+
},
177+
});
178+
```
179+
180+
</TabItem>
181+
182+
</Tabs>
183+
184+
120185
All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert.
121186

187+
#### Alert Buttons Description
188+
189+
Buttons containing text will be read by a screen reader. If a description other than the existing text is desired, a label can be set on the button by passing `aria-label` to the `htmlAttributes` property on the button.
190+
191+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
192+
193+
<TabItem value="angular">
194+
195+
```javascript
196+
const alert = await this.alertController.create({
197+
header: 'Header',
198+
buttons: [
199+
{
200+
text: 'Exit',
201+
htmlAttributes: {
202+
'aria-label': 'close',
203+
},
204+
},
205+
],
206+
});
207+
```
208+
209+
</TabItem>
210+
211+
<TabItem value="javascript">
212+
213+
```javascript
214+
const alert = await this.alertController.create({
215+
header: 'Header',
216+
buttons: [
217+
{
218+
text: 'Exit',
219+
htmlAttributes: {
220+
'aria-label': 'close',
221+
},
222+
},
223+
],
224+
});
225+
```
226+
227+
</TabItem>
228+
229+
<TabItem value="react">
230+
231+
```javascript
232+
useIonAlert({
233+
header: 'Header',
234+
buttons: [
235+
{
236+
text: 'Exit',
237+
htmlAttributes: {
238+
'aria-label': 'close',
239+
},
240+
},
241+
],
242+
});
243+
```
244+
245+
</TabItem>
246+
247+
<TabItem value="vue">
248+
249+
```javascript
250+
const alert = await alertController.create({
251+
header: 'Header',
252+
buttons: [
253+
{
254+
text: 'Exit',
255+
htmlAttributes: {
256+
'aria-label': 'close',
257+
},
258+
},
259+
],
260+
});
261+
```
262+
263+
</TabItem>
264+
265+
</Tabs>
122266

123267
## Interfaces
124268

125269
### AlertButton
126270

127271
```typescript
272+
type AlertButtonOverlayHandler = boolean | void | { [key: string]: any };
273+
128274
interface AlertButton {
129275
text: string;
130276
role?: 'cancel' | 'destructive' | string;
131277
cssClass?: string | string[];
132-
handler?: (value: any) => boolean | void | {[key: string]: any};
278+
id?: string;
279+
htmlAttributes?: { [key: string]: any };
280+
handler?: (value: any) => AlertButtonOverlayHandler | Promise<AlertButtonOverlayHandler>;
133281
}
134282
```
135283

@@ -199,4 +347,4 @@ interface AlertOptions {
199347
<CustomProps />
200348

201349
## Slots
202-
<Slots />
350+
<Slots />

0 commit comments

Comments
 (0)