From 0947383cfd012a3fa4652dd7b7bf31688bfea6af Mon Sep 17 00:00:00 2001 From: Ryan Domingue Date: Sun, 11 Feb 2024 16:40:55 -0800 Subject: [PATCH] General docs cleanup --- CHANGELOG.md | 2 +- src/Dialog/README.md | 7 ++++--- src/Disclosure/README.md | 2 +- src/Listbox/README.md | 3 ++- src/Popup/README.md | 3 ++- src/Tablist/README.md | 2 +- src/shared/modules/README.md | 2 +- 7 files changed, 12 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b1930758..b9919a69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,7 @@ A complete rewrite. - Components track attributes they add and will only overwrite existing attribute values where required (#73) - Components are now exported from their own endpoint (#84) - MenuBar and MenuButton components are now deprecated (#75) -- Component state now uses setter/getter pattern (#83) +- Component state now uses a setter/getter pattern (#83) **Changed** diff --git a/src/Dialog/README.md b/src/Dialog/README.md index eb592255..7ad58e6f 100644 --- a/src/Dialog/README.md +++ b/src/Dialog/README.md @@ -1,7 +1,8 @@ Dialog ====== -Class for managing an interactive Dialog element. +Class for managing an interactive Dialog element, typically overlaid on inert +content, that traps focus and prevents interaction with the outside content. ## Contents @@ -157,7 +158,7 @@ Additionally, the close button may not be the most appropriate element to focus > When a dialog opens, focus moves to an element contained in the dialog. Generally, focus is initially set on the first focusable element. However, the most appropriate focus placement will depend on the nature and size of the content. -If the close button is not the most appropriate element to focus when the Dialog opens, we can omit the `closeButton` option to prevent the Dialog from managing focus. We can then manage focus and the close button ourselves. +If the close button is not the most appropriate element to focus when the Dialog opens, omit the `closeButton` option to prevent the Dialog from managing focus and manage focus and the close button manually. ```jsx // Set up the close button. @@ -174,7 +175,7 @@ dialog.on('dialog.stateChange', (event) => { **DOM Mutations** -We can use `dialog.setInteractiveChildren()` to refresh the component after markup changes. +Use `dialog.setInteractiveChildren()` to refresh the component after markup changes. ## References diff --git a/src/Disclosure/README.md b/src/Disclosure/README.md index fe46ec61..c5e8307d 100644 --- a/src/Disclosure/README.md +++ b/src/Disclosure/README.md @@ -104,7 +104,7 @@ Hides the target element with the `hidden` attribute, removing the need to do it ## Additional Information -The `loadOpen` option is removed, in part because it's possible to achieve the same result without the option: Add `aria-expanded="true"` to the controling element and `aria-hidden="false"` to the target element and the attribute will treat it as expanded by default. +Previously, there existsed a `loadOpen` option for initializing a Disclosure in the expanded state. To achieve the same result: Add `aria-expanded="true"` to the controling element and `aria-hidden="false"` to the target element. ## References diff --git a/src/Listbox/README.md b/src/Listbox/README.md index 831f8b10..34d374bc 100644 --- a/src/Listbox/README.md +++ b/src/Listbox/README.md @@ -1,7 +1,8 @@ Listbox ======= -Class for setting up an interactive Listbox element. +Class for setting up an interactive single-select Listbox for presenting a list +of options and allowing a user to select one of them. ## Contents diff --git a/src/Popup/README.md b/src/Popup/README.md index 66b5fc13..31c466e8 100644 --- a/src/Popup/README.md +++ b/src/Popup/README.md @@ -1,7 +1,8 @@ Popup ===== -Class for setting up an interactive popup button to activate a target element. +Class for setting up an interactive popup button to activate a target element +for displaying hidden content. ## Example diff --git a/src/Tablist/README.md b/src/Tablist/README.md index 5497b74e..f4ec503c 100644 --- a/src/Tablist/README.md +++ b/src/Tablist/README.md @@ -151,7 +151,7 @@ Authors are responsible for providing a label for the Tablist. See ["Role, Prope > If the tab list has a visible label, the element with role tablist has aria-labelledby set to a value that refers to the labelling element. Otherwise, the tablist element has a label provided by aria-label. -The recommendation is to only auto-active tabs as they're selected if the associated panel's content [isn't preloaded](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). Otherwise, we can use the `AutomaticActivation` module: +The recommendation is to only auto-active tabs as they're selected if the associated panel's content [isn't preloaded](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). Otherwise, use the `AutomaticActivation` module: ```jsx import Tablist, { AutomaticActivation } from 'aria-components/tablist'; diff --git a/src/shared/modules/README.md b/src/shared/modules/README.md index 69b26f6c..23f23466 100644 --- a/src/shared/modules/README.md +++ b/src/shared/modules/README.md @@ -55,7 +55,7 @@ export default function DoSomethingHelpful({ instance }) { } ``` -The following properties are passed to modules: +An object with the following properties is passed to modules: | Property | Type | Description | |:------------|:-------------:|:--------------------------------------|