docs(api): add accessibility section for new htmlAttributes property (#…

…3064)
ionic-team · Aug 4, 2023 · a47e79f · a47e79f
1 parent f947b4a
commit a47e79f
Show file tree

Hide file tree

Showing 3 changed files with 403 additions and 25 deletions.
diff --git a/docs/api/action-sheet.md b/docs/api/action-sheet.md
@@ -1,6 +1,9 @@
 ---
 title: "ion-action-sheet"
 ---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 import Props from '@ionic-internal/component-api/v7/action-sheet/props.md';
 import Events from '@ionic-internal/component-api/v7/action-sheet/events.md';
 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-
 
 ## Accessibility
 
+### Screen Readers
+
+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.
+
+#### Role
+
 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.
 
+#### Action Sheet Description
+
 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.
 
+<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
+
+<TabItem value="angular">
+
+```javascript
+const actionSheet = await this.actionSheetController.create({
+  htmlAttributes: {
+    'aria-label': 'action sheet dialog',
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="javascript">
+
+```javascript
+const actionSheet = await this.actionSheetController.create({
+  htmlAttributes: {
+    'aria-label': 'action sheet dialog',
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="react">
+
+```javascript
+useIonActionSheet({
+  htmlAttributes: {
+    'aria-label': 'action sheet dialog',
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="vue">
+
+```javascript
+const actionSheet = await actionSheetController.create({
+  htmlAttributes: {
+    'aria-label': 'action sheet dialog',
+  },
+});
+```
+
+</TabItem>
+
+</Tabs>
+
+#### Action Sheet Buttons Description
+
+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.
+
+<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
+
+<TabItem value="angular">
+
+```javascript
+const actionSheet = await this.actionSheetController.create({
+  header: 'Header',
+  buttons: [
+    {
+      icon: 'close',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="javascript">
+
+```javascript
+const actionSheet = await this.actionSheetController.create({
+  header: 'Header',
+  buttons: [
+    {
+      icon: 'close',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="react">
+
+```javascript
+useIonActionSheet({
+  header: 'Header',
+  buttons: [
+    {
+      icon: 'close',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="vue">
+
+```javascript
+const actionSheet = await actionSheetController.create({
+  header: 'Header',
+  buttons: [
+    {
+      icon: 'close',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+</Tabs>
+
 ## Interfaces
 
 ### ActionSheetButton
@@ -108,6 +251,8 @@ interface ActionSheetButton<T = any> {
   role?: 'cancel' | 'destructive' | 'selected' | string;
   icon?: string;
   cssClass?: string | string[];
+  id?: string;
+  htmlAttributes?: { [key: string]: any };
   handler?: () => boolean | void | Promise<boolean | void>;
   data?: T;
 }
@@ -150,4 +295,4 @@ interface ActionSheetOptions {
 <CustomProps />
 
 ## Slots
-<Slots />
+<Slots />
diff --git a/docs/api/alert.md b/docs/api/alert.md
@@ -111,25 +111,173 @@ import Customization from '@site/static/usage/v7/alert/customization/index.md';
 
 ## Accessibility
 
+### Screen Readers
+
+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.
+
+#### Role
+
 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.
 
+#### Alert Description
+
 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.
 
 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.
 
+<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
+
+<TabItem value="angular">
+
+```javascript
+const alert = await this.alertController.create({
+  message: 'This is an alert with custom aria attributes.',
+  htmlAttributes: {
+    'aria-label': 'alert dialog',
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="javascript">
+
+```javascript
+const alert = await this.alertController.create({
+  message: 'This is an alert with custom aria attributes.',
+  htmlAttributes: {
+    'aria-label': 'alert dialog',
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="react">
+
+```javascript
+useIonAlert({
+  message: 'This is an alert with custom aria attributes.',
+  htmlAttributes: {
+    'aria-label': 'alert dialog',
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="vue">
+
+```javascript
+const alert = await alertController.create({
+  message: 'This is an alert with custom aria attributes.',
+  htmlAttributes: {
+    'aria-label': 'alert dialog',
+  },
+});
+```
+
+</TabItem>
+
+</Tabs>
+
+
 All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert.
 
+#### Alert Buttons Description
+
+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.
+
+<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
+
+<TabItem value="angular">
+
+```javascript
+const alert = await this.alertController.create({
+  header: 'Header',
+  buttons: [
+    {
+      text: 'Exit',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="javascript">
+
+```javascript
+const alert = await this.alertController.create({
+  header: 'Header',
+  buttons: [
+    {
+      text: 'Exit',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="react">
+
+```javascript
+useIonAlert({
+  header: 'Header',
+  buttons: [
+    {
+      text: 'Exit',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="vue">
+
+```javascript
+const alert = await alertController.create({
+  header: 'Header',
+  buttons: [
+    {
+      text: 'Exit',
+      htmlAttributes: {
+        'aria-label': 'close',
+      },
+    },
+  ],
+});
+```
+
+</TabItem>
+
+</Tabs>
 
 ## Interfaces
 
 ### AlertButton
 
 ```typescript
+type AlertButtonOverlayHandler = boolean | void | { [key: string]: any };
+
 interface AlertButton {
   text: string;
   role?: 'cancel' | 'destructive' | string;
   cssClass?: string | string[];
-  handler?: (value: any) => boolean | void | {[key: string]: any};
+  id?: string;
+  htmlAttributes?: { [key: string]: any };
+  handler?: (value: any) => AlertButtonOverlayHandler | Promise<AlertButtonOverlayHandler>;
 }
 ```
 
@@ -199,4 +347,4 @@ interface AlertOptions {
 <CustomProps />
 
 ## Slots
-<Slots />
+<Slots />