docs(components): 📝 finish the docs for all components

adaptui · Dec 3, 2020 · fa658cd · fa658cd
1 parent 720cd5a
commit fa658cd
Show file tree

Hide file tree

Showing 34 changed files with 203 additions and 61 deletions.
diff --git a/docs-templates/breadcrumb.md b/docs-templates/breadcrumb.md
@@ -1,7 +1,7 @@
 # Breadcrumb
 
-`Breadcrumb` component provides the required aria attributes for it's links. It
-follows the
+`Breadcrumb` component is used for the page navigation and it provides the
+required aria attributes for it's links. It follows the
 [WAI-ARIA Breadcrumb Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#breadcrumb)
 for its
 [accessibility properties](https://www.w3.org/TR/wai-aria-practices-1.2/#wai-aria-roles-states-and-properties-2).
@@ -18,7 +18,7 @@ js: src/breadcrumbs/stories/__js/Breadcrumbs.component.jsx
 css: src/breadcrumbs/stories/Breadcrumbs.css
 -->
 
-## Accessibilty
+## Accessibility Requirement
 
 - `Breadcrumbs` should have `aria-label` or `aria-labelledby` attribute.
 - `BreadcrumbLink` should have `aria-current` set to `page` if the currenct page

diff --git a/docs-templates/calendar.md b/docs-templates/calendar.md
@@ -1,7 +1,8 @@
 # Calendar
 
-`Calendar` component provides a way to manipuldate data of Date easily like the
-native calendar. It follows the
+`Calendar` component provides a way to select a date or a range of dates while
+allowing you to style them however. All the date, month & year calculations are
+done internally to provide the ease of use. It follows the
 [Grid Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#grid) for the
 keyboard navigaiton & focus management.
 

diff --git a/docs-templates/datepicker.md b/docs-templates/datepicker.md
@@ -1,7 +1,7 @@
 # DatePicker
 
-`DatePicker` component provides a way to pick a date or range of dates with the
-help of [Calendar](./calendar.md) component. It follows the
+`DatePicker` component provides a way to select a date or a range of dates with
+the help of [Calendar](./calendar.md) component. It follows the
 [Native Input Date](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)
 for the keyboard navigation & accessibility features.
 

diff --git a/docs-templates/meter.md b/docs-templates/meter.md
@@ -1,6 +1,9 @@
 # Meter
 
-Accessible `Meter` component.
+`Meter` component can be used to provide a graphical display of a numeric value
+that varies within a defined range. It follows the
+[WAI-ARIA Meter Pattern](https://w3c.github.io/aria-practices/#meter) for it's
+[accessibility properties](https://w3c.github.io/aria-practices/#wai-aria-roles-states-and-properties-15)
 
 <!-- INJECT_TOC -->
 
@@ -14,6 +17,15 @@ js: src/meter/stories/__js/Meter.component.jsx
 deps: ['@emotion/css']
 -->
 
+## Accessibility Requirement
+
+- `Meter` should have `aria-label` or `aria-labelledby` attribute.
+- `Meter` should not be used to represent a value like the current world
+  population since it does not have a meaningful maximum limit.
+- `Meter` should not be used to indicate progress, such as loading or percent
+  completion of a task. To communicate progress, use the progressbar role
+  instead.
+
 <!-- INJECT_COMPOSITION src/meter -->
 
 <!-- INJECT_PROPS src/meter -->
diff --git a/docs-templates/number-input.md b/docs-templates/number-input.md
@@ -1,6 +1,11 @@
 # NumberInput
 
-Accessible `NumberInput` component.
+`NumberInput` component is a form element used to select a number while
+following the keyboard interactions & accessibility properties like the
+[Native Number Input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number).
+It follows
+[WAI-ARIA Spin Button Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#spinbutton)
+for the accessibility features.
 
 <!-- INJECT_TOC -->
 
@@ -13,6 +18,10 @@ link_title: NumberInput - Open On Sandbox
 js: src/number-input/stories/__js/NumberInput.component.jsx
 -->
 
+## Accessibility Requirement
+
+- `NumberInput` should have `aria-label` or `aria-labelledby` attribute.
+
 <!-- INJECT_COMPOSITION src/number-input -->
 
 <!-- INJECT_PROPS src/number-input -->
diff --git a/docs-templates/pagination.md b/docs-templates/pagination.md
@@ -1,6 +1,7 @@
 # Pagination
 
-Accessible `Pagination` component.
+`Pagination` component provides all the accessibility features for the page
+navigation.
 
 <!-- INJECT_TOC -->
 
@@ -13,6 +14,10 @@ link_title: Pagination - Open On Sandbox
 js: src/pagination/stories/__js/Pagination.component.jsx
 -->
 
+## Accessibility Requirement
+
+- `Pagination` should have `aria-label` or `aria-labelledby` attribute.
+
 <!-- INJECT_COMPOSITION src/pagination -->
 
 <!-- INJECT_PROPS src/pagination -->
diff --git a/docs-templates/picker-base.md b/docs-templates/picker-base.md
@@ -1,6 +1,8 @@
 # PickerBase
 
-Accessible `PickerBase` component.
+`PickerBase` component provides easier way to plug them into the
+[DatePicker](./datepicker.md) & [TimePicker](./timepicker.md). It follows
+[WAI-ARIA Disclosure Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#disclosure)
 
 <!-- INJECT_TOC -->
 

diff --git a/docs-templates/progress.md b/docs-templates/progress.md
@@ -1,6 +1,8 @@
 # Progress
 
-Accessible `Progress` component.
+`Progress` component provides a graphical status for tasks that take some amount
+of time to load. It follows
+[WAI-ARIA Progressbar Pattern](https://www.w3.org/TR/wai-aria-1.2/#progressbar)
 
 <!-- INJECT_TOC -->
 
@@ -9,17 +11,23 @@ Accessible `Progress` component.
 <!-- IMPORT_EXAMPLE src/progress/stories/__js/LinearProgress.component.jsx -->
 
 <!-- CODESANDBOX
-link_title: Progress Linear- Open On Sandbox
-js: src/progress/stories/__js/LinearProgress.component.jsx
+link_title: Progress Circular - Open On Sandbox
+js: src/progress/stories/__js/CircularProgress.component.jsx
 deps: ['@emotion/css']
 -->
 
 <!-- CODESANDBOX
-link_title: Progress Circular - Open On Sandbox
-js: src/progress/stories/__js/CircularProgress.component.jsx
+link_title: Progress Linear- Open On Sandbox
+js: src/progress/stories/__js/LinearProgress.component.jsx
 deps: ['@emotion/css']
 -->
 
+## Accessibility Requirement
+
+- If the `Progress` is describing the loading progress of a particular region of
+  a page, you should use `aria-describedby` to point to the status, and set the
+  `aria-busy `attribute to `true` on the region until it is finished loading.
+
 <!-- INJECT_COMPOSITION src/progress -->
 
 <!-- INJECT_PROPS src/progress -->
diff --git a/docs-templates/segment.md b/docs-templates/segment.md
@@ -1,6 +1,9 @@
 # Segment
 
-Accessible `Segment` component.
+`Segment` component provides the date calculations, keyboard navigation &
+accessibility properties necessary for the [DatePicker](./datepicker.md) &
+[TimePicker](./timepicker.md) Input segment. It follows
+[Native Input Date Segment Features](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)
 
 <!-- INJECT_TOC -->
 

diff --git a/docs-templates/select.md b/docs-templates/select.md
@@ -1,6 +1,10 @@
 # Select
 
-Accessible `Select` component.
+`Select` component follows all the accessibility features of
+[WAI-ARIA Combobox Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#listbox-popup-keyboard-interaction)
+for the Listbox navigation except that it follows
+[WAI-ARIA Disclosure Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#disclosure)
+for the show/hide.
 
 <!-- INJECT_TOC -->
 

diff --git a/docs-templates/slider.md b/docs-templates/slider.md
@@ -1,6 +1,12 @@
 # Slider
 
-Accessible `Slider` component.
+`Slider` component is a form element used to select a number by sliding through
+the given range with complete freedom of styling. It follows
+[WAI-ARIA Slider Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#slider)
+for the
+[keyboard navigation](https://www.w3.org/TR/wai-aria-practices-1.2/#slider_kbd_interaction)
+&
+[accessibility properties](https://www.w3.org/TR/wai-aria-practices-1.2/#slider_roles_states_props)
 
 <!-- INJECT_TOC -->
 
@@ -14,6 +20,10 @@ js: src/slider/stories/__js/components/Slider.component.jsx
 css: src/slider/stories/Slider.css
 -->
 
+## Accessibility Requirement
+
+- `SliderInput` should have `aria-label` or `aria-labelledby` attribute.
+
 <!-- INJECT_COMPOSITION src/slider -->
 
 <!-- INJECT_PROPS src/slider -->
diff --git a/docs-templates/timepicker.md b/docs-templates/timepicker.md
@@ -1,6 +1,9 @@
 # TimePicker
 
-Accessible `TimePicker` component.
+`TimePicker` component provides a way to select a time while giving the freedom
+to style. It follows the
+[Native Input Time](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time)
+for the keyboard navigation & accessibility features.
 
 <!-- INJECT_TOC -->
 

diff --git a/docs-templates/toast.md b/docs-templates/toast.md
@@ -1,6 +1,10 @@
 # Toast
 
-Accessible `Toast` component.
+`Toast` component provides a way to add notifications to the app with complete
+freedom of styling them. It follows
+[WAI-ARIA Alert Patter](https://www.w3.org/TR/wai-aria-practices-1.2/#alert) for
+the
+[accessibility properties](https://www.w3.org/TR/wai-aria-practices-1.2/#wai-aria-roles-states-and-properties-0)
 
 ## Usage
 

diff --git a/docs/accordion.md b/docs/accordion.md
@@ -65,10 +65,10 @@ export function App(props) {
 export default App;
 ```
 
-[Accordion Basic - Open on Sandbox](https://codesandbox.io/s/w4vcr)
-
 [Accordion Styled - Open on Sandbox](https://codesandbox.io/s/7l87v)
 
+[Accordion Basic - Open on Sandbox](https://codesandbox.io/s/w4vcr)
+
 ## Accessibility Requirements
 
 - Each `AccordionTrigger` should be wrapped in an element with role `heading`

diff --git a/docs/breadcrumb.md b/docs/breadcrumb.md
@@ -1,15 +1,15 @@
 # Breadcrumb
 
-`Breadcrumb` component provides the required aria attributes for it's links. It
-follows the
+`Breadcrumb` component is used for the page navigation and it provides the
+required aria attributes for it's links. It follows the
 [WAI-ARIA Breadcrumb Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#breadcrumb)
 for its
 [accessibility properties](https://www.w3.org/TR/wai-aria-practices-1.2/#wai-aria-roles-states-and-properties-2).
 
 ## Table of Contents
 
 - [Usage](#usage)
-- [Accessibilty](#accessibilty)
+- [Accessibility Requirement](#accessibility-requirement)
 - [Composition](#composition)
 - [Props](#props)
   - [`BreadcrumbLink`](#breadcrumblink)
@@ -24,7 +24,7 @@ import { Breadcrumbs, BreadcrumbLink } from "renderless-components";
 
 export const App = props => {
   return (
-    <Breadcrumbs className="breadcrumb">
+    <Breadcrumbs aria-label="Breadcrumb" className="breadcrumb">
       <ol>
         <li>
           <BreadcrumbLink href="https://www.w3.org/TR/wai-aria-practices-1.1/">
@@ -57,9 +57,9 @@ export const App = props => {
 export default App;
 ```
 
-[Breadcrumbs Basic - Open on Sandbox](https://codesandbox.io/s/ixpe7)
+[Breadcrumbs Basic - Open on Sandbox](https://codesandbox.io/s/vdmiv)
 
-## Accessibilty
+## Accessibility Requirement
 
 - `Breadcrumbs` should have `aria-label` or `aria-labelledby` attribute.
 - `BreadcrumbLink` should have `aria-current` set to `page` if the currenct page

diff --git a/docs/calendar.md b/docs/calendar.md
@@ -1,7 +1,8 @@
 # Calendar
 
-`Calendar` component provides a way to manipuldate data of Date easily like the
-native calendar. It follows the
+`Calendar` component provides a way to select a date or a range of dates while
+allowing you to style them however. All the date, month & year calculations are
+done internally to provide the ease of use. It follows the
 [Grid Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#grid) for the
 keyboard navigaiton & focus management.
 

diff --git a/docs/datepicker.md b/docs/datepicker.md
@@ -1,7 +1,7 @@
 # DatePicker
 
-`DatePicker` component provides a way to pick a date or range of dates with the
-help of [Calendar](./calendar.md) component. It follows the
+`DatePicker` component provides a way to select a date or a range of dates with
+the help of [Calendar](./calendar.md) component. It follows the
 [Native Input Date](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)
 for the keyboard navigation & accessibility features.
 
@@ -366,10 +366,10 @@ const DoubleChevronRight = props => (
 );
 ```
 
-[RangeDatePicker - Open On Sandbox](https://codesandbox.io/s/cqgs2)
-
 [DatePicker - Open On Sandbox](https://codesandbox.io/s/snelw)
 
+[RangeDatePicker - Open On Sandbox](https://codesandbox.io/s/cqgs2)
+
 ## Composition
 
 - DatePicker uses [usePickerBase](./picker-base.md)

diff --git a/docs/meter.md b/docs/meter.md
@@ -1,10 +1,14 @@
 # Meter
 
-Accessible `Meter` component.
+`Meter` component can be used to provide a graphical display of a numeric value
+that varies within a defined range. It follows the
+[WAI-ARIA Meter Pattern](https://w3c.github.io/aria-practices/#meter) for it's
+[accessibility properties](https://w3c.github.io/aria-practices/#wai-aria-roles-states-and-properties-15)
 
 ## Table of Contents
 
 - [Usage](#usage)
+- [Accessibility Requirement](#accessibility-requirement)
 - [Composition](#composition)
 - [Props](#props)
   - [`useMeterState`](#usemeterstate)
@@ -108,6 +112,15 @@ function meterBarStyle(meter, props) {
 
 [Meter - Open On Sandbox](https://codesandbox.io/s/ypo8h)
 
+## Accessibility Requirement
+
+- `Meter` should have `aria-label` or `aria-labelledby` attribute.
+- `Meter` should not be used to represent a value like the current world
+  population since it does not have a meaningful maximum limit.
+- `Meter` should not be used to indicate progress, such as loading or percent
+  completion of a task. To communicate progress, use the progressbar role
+  instead.
+
 ## Composition
 
 - Meter uses [useRole](https://reakit.io/docs/role)

diff --git a/docs/number-input.md b/docs/number-input.md
@@ -1,10 +1,16 @@
 # NumberInput
 
-Accessible `NumberInput` component.
+`NumberInput` component is a form element used to select a number while
+following the keyboard interactions & accessibility properties like the
+[Native Number Input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number).
+It follows
+[WAI-ARIA Spin Button Pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#spinbutton)
+for the accessibility features.
 
 ## Table of Contents
 
 - [Usage](#usage)
+- [Accessibility Requirement](#accessibility-requirement)
 - [Composition](#composition)
 - [Props](#props)
   - [`useNumberinputState`](#usenumberinputstate)
@@ -29,10 +35,11 @@ export const App = props => {
   const { clampValueOnBlur, allowMouseWheel } = props;
 
   return (
-    <label htmlFor="number-input">
+    <label htmlFor="number-input" id="numberinput-label">
       <NumberInputDecrementButton {...state}>-</NumberInputDecrementButton>
       <NumberInput
         id="number-input"
+        aria-labelledby="numberinput-label"
         clampValueOnBlur={clampValueOnBlur}
         allowMouseWheel={allowMouseWheel}
         {...state}
@@ -45,7 +52,11 @@ export const App = props => {
 export default App;
 ```
 
-[NumberInput - Open On Sandbox](https://codesandbox.io/s/jn8rl)
+[NumberInput - Open On Sandbox](https://codesandbox.io/s/b8pez)
+
+## Accessibility Requirement
+
+- `NumberInput` should have `aria-label` or `aria-labelledby` attribute.
 
 ## Composition