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

docs/api/action-sheet.md

@@ -94,10 +94,14 @@ import CssCustomProperties from '@site/static/usage/v7/action-sheet/theming/css-
 
 ## Accessibility
 
+### Screen Readers
+
 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.
 
 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.
 
+Buttons containing text will be read by a screen reader. If a button contains only an icon, a label should be assigned to the button by passing `aria-label` or `aria-labelledby` to the `htmlAttributes` property. The `aria-label` property accepts a text description and `aria-labelledby` accepts an element that contains the description of the button.
+
 ## Interfaces
 
 ### ActionSheetButton
@@ -108,6 +112,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 +156,4 @@ interface ActionSheetOptions {
 <CustomProps />
 
 ## Slots
-<Slots />
+<Slots />

docs/api/alert.md

@@ -111,6 +111,8 @@ import Customization from '@site/static/usage/v7/alert/customization/index.md';
 
 ## Accessibility
 
+### Screen Readers
+
 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.
 
 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.
@@ -119,17 +121,22 @@ It is strongly recommended that your Alert have a `message`, as well as either a
 
 All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert.
 
+Buttons containing text will be read by a screen reader. If a description other than the existing text is desired, a label can be assigned to the button by passing `aria-label` or `aria-labelledby` to the `htmlAttributes` property. The `aria-label` property accepts a text description and `aria-labelledby` accepts an element that contains the description of the button.
 
 ## 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 +206,4 @@ interface AlertOptions {
 <CustomProps />
 
 ## Slots
-<Slots />
+<Slots />

docs/api/toast.md

@@ -86,6 +86,30 @@ import ThemingPlayground from '@site/static/usage/v7/toast/theming/index.md';
 
 <ThemingPlayground />
 
+## Accessibility
+
+### Focus Management
+
+Toasts are intended to be subtle notifications and are not intended to interrupt the user. User interaction should not be required to dismiss the toast. As a result, focus is not automatically moved to a toast when one is presented.
+
+### Screen Readers
+
+`ion-toast` has `role="status"` and `aria-live="polite"` set on the inner `.toast-content` element. This causes screen readers to only announce the toast message and header. Buttons and icons will not be announced.
+
+`aria-live` causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to `'polite'`, screen readers should not interrupt the current task.
+
+Since toasts are intended to be subtle notification, `aria-live` should never be set to `"assertive"`. If developers need to interrupt the user with an important message, we recommend using an [alert](./alert).
+
+Buttons containing text will be read by a screen reader. If a button contains only an icon, a label should be assigned to the button by passing `aria-label` or `aria-labelledby` to the `htmlAttributes` property. The `aria-label` property accepts a text description and `aria-labelledby` accepts an element that contains the description of the button.
+
+### Tips
+
+While this is not a complete list, here are some guidelines to follow when using toasts.
+
+* Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using an [alert](./alert) instead.
+
+* For toasts with long messages, consider adjusting the `duration` property to allow users enough time to read the content of the toast.
+
 ## Interfaces
 
 ### ToastButton
@@ -97,6 +121,7 @@ interface ToastButton {
   side?: 'start' | 'end';
   role?: 'cancel' | string;
   cssClass?: string | string[];
+  htmlAttributes?: { [key: string]: any };
   handler?: () => boolean | void | Promise<boolean | void>;
 }
 ```
@@ -126,28 +151,6 @@ interface ToastOptions {
 }
 ```
 
-## Accessibility
-
-### Focus Management
-
-Toasts are intended to be subtle notifications and are not intended to interrupt the user. User interaction should not be required to dismiss the toast. As a result, focus is not automatically moved to a toast when one is presented.
-
-### Screen Readers
-
-`ion-toast` has `role="status"` and `aria-live="polite"` set on the inner `.toast-content` element. This causes screen readers to only announce the toast message and header. Buttons and icons will not be announced.
-
-`aria-live` causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to `'polite'`, screen readers should not interrupt the current task.
-
-Since toasts are intended to be subtle notification, `aria-live` should never be set to `"assertive"`. If developers need to interrupt the user with an important message, we recommend using an [alert](./alert).
-
-### Tips
-
-While this is not a complete list, here are some guidelines to follow when using toasts.
-
-* Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using an [alert](./alert) instead.
-
-* For toasts with long messages, consider adjusting the `duration` property to allow users enough time to read the content of the toast.
-
 ## Properties
 <Props />