-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add
react-native missing package docs (#225)
* Add SwitchListItem doc * move hook docs * Add SwitchWrapper doc * update links * update extension * Add useExpandable hook docs * Add ExpandablePressable doc to packages * use mdx for files with jsx
- Loading branch information
Showing
8 changed files
with
314 additions
and
13 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| import { DevOnly, Required } from '@site/src/components'; | ||
|
|
||
| # ExpandablePressable | ||
|
|
||
| ExpandablePressable is the [Pressable](./Pressable.md) component that automatically handles the [expanded](https://reactnative.dev/docs/accessibility#accessibilitystate) `accessibilityState`. Under the hood it uses [useExpandable](./hooks/useExpandable.md) to achieve this. | ||
|
|
||
| ## Usage | ||
|
|
||
| ```tsx | ||
| import { ExpandablePressable } from 'react-native-ama'; | ||
|
|
||
| <ExpandablePressable | ||
| accessibilityLabel="I'm ExpandablePressable!" | ||
| expanded={isExpanded} | ||
| onPress={onPress}> | ||
| <Text>I'm pressable</Text> | ||
| </ExpandablePressable>; | ||
| ``` | ||
|
|
||
| #### Example | ||
|
|
||
| ```tsx | ||
| import { ExpandablePressable, Text } from '@react-native-ama/react-native'; | ||
|
|
||
| const Example = () => { | ||
| const [isExpanded, setIsExpanded] = React.useState(false); | ||
|
|
||
| return ( | ||
| <> | ||
| <ExpandablePressable | ||
| accessibilityLabel={isExpanded ? 'Less' : 'More'} | ||
| expanded={isExpanded} | ||
| onPress={() => setIsExpanded(expanded => !expanded)}> | ||
| {isExpanded ? <MiniumIcon /> : <PlusIcon />} | ||
| </ExpandablePressable> | ||
| {isExpanded ? <>{/* content goes here */}</> : null} | ||
| </> | ||
| ); | ||
| }; | ||
| ``` | ||
|
|
||
| # Accessibility | ||
|
|
||
| The hook automatically: | ||
|
|
||
| - Sets `accessibilityRole` to **button** | ||
| - Handles the `accessibilityState` for **expanded** | ||
|
|
||
| Compared to the default React Native component, this custom component: | ||
|
|
||
| - Forces the use of `accessibilityLabel` <DevOnly /> | ||
| - Performs a [Minimum Size](../../../website/guidelines/minimum-size.md) check <DevOnly /> | ||
| - Performs a [contrast checker](../../../website/guidelines/contrast.md) between its background color and its children color <DevOnly /> | ||
|
|
||
| ### accessibilityRole | ||
|
|
||
| The `accessibilityRole` property is used by the screen reader to announce the kind of element focused on. If the property is omitted, the user might have little to no clue what could happen if the element is triggered. | ||
|
|
||
| [Check here for more info](../../../website/guidelines/accessibility-role.md) | ||
|
|
||
| ### accessibilityLabel | ||
|
|
||
| The `accessibilityLabel` property is the first thing announced by the screen reader when the elements gain the focus; then, it announces its role. If the property is omitted, the user might have little to no clue what could happen if the element is triggered. | ||
|
|
||
| [Check here for more info](../../../website/guidelines/accessibility-label.md) | ||
|
|
||
| ### Contrast checker | ||
|
|
||
| The component performs a [contrast check](../../../website/guidelines/contrast.md) between its background colour and the children's foreground when in dev mode. | ||
|
|
||
| :::info | ||
| AMA does also perform a contrast check on disabled button, as a [poor contrast can make them hard to read](https://axesslab.com/disabled-buttons-suck/#they-are-hard-to-see). | ||
| ::: | ||
|
|
||
| ### Minimum size | ||
|
|
||
| The component uses the [onLayout](https://reactnative.dev/docs/layoutevent) prop to perform the [minium size check](../../../website/guidelines/minimum-size.md). | ||
|
|
||
| ## Props | ||
|
|
||
| ### <Required /> `accessibilityLabel` | ||
|
|
||
| The `accessibilityLabel` for the expandable button, this is announced by the screen reader when the element gains focus, then it announces its role. The accessibilityLabel is a required properties as if it is omitted, the user will have no context for the purpose of the button. | ||
|
|
||
| | Type | Default | | ||
| | ------ | --------- | | ||
| | string | undefined | | ||
|
|
||
| ### <Required /> `expanded` | ||
|
|
||
| Indicates whether an expandable element is currently expanded or collapsed. | ||
|
|
||
| | Type | Default | | ||
| | ------- | --------- | | ||
| | boolean | undefined | | ||
|
|
||
| ## Related guidelines | ||
|
|
||
| - [Accessibility Label](../../../website/guidelines/accessibility-label.md) | ||
| - [Accessibility Role](../../../website/guidelines/accessibility-role.md) | ||
| - [Contrast](../../../website/guidelines/contrast.md) | ||
| - [Minimum Size](../../../website/guidelines/minimum-size.md) | ||
|
|
||
| ## External resources | ||
|
|
||
| - [Disabled buttons suck](https://axesslab.com/disabled-buttons-suck/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| import { Required } from '@site/src/components'; | ||
|
|
||
| # SwitchListItem | ||
|
|
||
| It is a utility component that provides a list item with a customisable label and switch control [focused on accessibility](#accessibility). | ||
|
|
||
| ## Usage | ||
|
|
||
| ```jsx | ||
| <SwitchListItem | ||
| label={ | ||
| <Text style={styles.switchText}>I'm a switch</Text> | ||
| } | ||
| style={styles.switchListItem} | ||
| value={isSwitchOn} | ||
| onValueChange={toggleSwitch} | ||
| > | ||
| {...} | ||
| </SwitchListItem> | ||
| ``` | ||
| ## Accessibility | ||
| The component: | ||
| - is announced as a "switch" | ||
| - handles the `accessibilityState` **checked** | ||
| - user the label text as `accessibilityLabel` | ||
| ## Props | ||
| ### <Required /> `labelComponent` | ||
| The custom label to use for the component. | ||
| | Type | Default | | ||
| | ----------- | --------- | | ||
| | JSX.Element | undefined | | ||
| If no accessibilityLabel is provided, the component children are used to generate the one. | ||
| ### `labelPosition` | ||
| The position where to render the `label`, left or right of the switch. | ||
| | Type | Default | | ||
| | ----------------- | ------- | | ||
| | 'left' \| 'right' | 'left' | | ||
| ### <Required /> `value` | ||
| The switch state | ||
| | Type | Default | | ||
| | ------- | --------- | | ||
| | boolean | undefined | | ||
| ### <Required /> `onValueChange` | ||
| The callback to call when the list item is toggled | ||
| | Type | Default | | ||
| | ---------- | --------- | | ||
| | () => void | undefined | | ||
| ## Customisation | ||
| By default, the component uses the [React Native switch](https://reactnative.dev/docs/switch), but this behavior can be overridden by passing a child component: | ||
| ```jsx | ||
| <SwitchListItem | ||
| label={<Text style={styles.switchText}>I'm a switch</Text>} | ||
| style={styles.switchListItem} | ||
| value={isSwitchOn} | ||
| onValueChange={toggleSwitch}> | ||
| <CustomSwitch value={isSwitchOn} onValueChange={toggleSwitch} /> | ||
| </SwitchListItem> | ||
| ``` | ||
| In this case, the custom `CustomSwitch` component is used instead of the React Native one. | ||
| :::note | ||
| The `SwitchListItem` component, to avoid the switch being individually focusable on Android, the component automatically sets the following properties for all the children: | ||
| - `accessibilityElementsHidden={true}` | ||
| - `importantForAccessibility="no"` | ||
| ::: | ||
| ## Related guidelines | ||
| - [Forms](../../../website/guidelines/forms.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| import { DevOnly } from '@site/src/components'; | ||
|
|
||
| # SwitchWrapper | ||
|
|
||
| The component provides built-in accessibility implementation for creating a custom switch. | ||
|
|
||
| ## Usage | ||
|
|
||
| ```jsx pf | ||
| import {SwitchWrapper} from 'react-native-ama'; | ||
|
|
||
| <SwitchWrapper | ||
| accessibilityLabel={accessibilityLabel} | ||
| style={[allStyles.container, style]} | ||
| onPress={onValueChange} | ||
| checked={value}> | ||
| <CustomSwitcher checked={checked} onPress={onValueChanged}> | ||
| </SwitchWrapper> | ||
| ``` | ||
|
|
||
| ## Accessibility | ||
|
|
||
| The component uses the [useSwitch](./hooks/useSwitch.md) hook under the hood and: | ||
|
|
||
| - Sets the [accessibilityRole](../../../website/guidelines/accessibility-role.md) property to **switch** | ||
| - Handled the [accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) needed by the Screen Reader | ||
| - Performs a [Minimum Size](../../../website/guidelines/minimum-size.md) check <DevOnly /> | ||
| - Performs a check on the [accessibilityLabel](../../../website/guidelines/accessibility-label.md) <DevOnly /> | ||
|
|
||
| ## Related guidelines | ||
|
|
||
| - [Forms](../../../website/guidelines/forms.md) |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| import {DevOnly, Required} from '@site/src/components'; | ||
|
|
||
| # useExpandable | ||
|
|
||
| This hook allows creating custom Expandable elements with the [Accessibility checks](#accessibility-checks) needed. | ||
|
|
||
| ## Usage | ||
|
|
||
| ```jsx | ||
| import { PressableProps, useExpandable } from 'react-native-ama'; | ||
|
|
||
| const expandableProps = | ||
| useExpandable < | ||
| PressableProps > | ||
| { | ||
| ...props, | ||
| expanded: boolean, | ||
| }; | ||
| ``` | ||
|
|
||
| ## Example | ||
|
|
||
| ```jsx | ||
| import { useExpandable } from 'react-native-ama'; | ||
|
|
||
| type CustomExpandableProps = React.PropsWithChildren< | ||
| UseExpandable<PressableProps>, | ||
| >; | ||
|
|
||
| export const CustomExpandable = ({ | ||
| children, | ||
| ...rest | ||
| }: CustomExpandableProps) => { | ||
| const expandableProps = useExpandable(rest); | ||
|
|
||
| return <Pressable {...expandableProps}>{children}</Pressable>; | ||
| }; | ||
| ``` | ||
|
|
||
| ## Accessibility checks | ||
|
|
||
| The hook automatically: | ||
|
|
||
| - Sets `accessibilityRole` to **button** | ||
| - Handles the `accessibilityState` for **expanded** | ||
|
|
||
| At runtime, the hook: | ||
|
|
||
| - Forces the use of `accessibilityLabel` <DevOnly /> | ||
| - Performs a [Minimum Size](../../../../website/guidelines/minimum-size.md) check <DevOnly /> | ||
| - Performs a [contrast checker](../../../../website/guidelines/contrast.md) between its background color and its children color <DevOnly /> | ||
|
|
||
| ## Props | ||
|
|
||
| ### <Required /> `accessibilityLabel` | ||
|
|
||
| The `accessibilityLabel` property is the first thing announced by the screen reader when the elements gain the focus; | ||
| then, it announces its role. If the property is omitted, the user might have little to no clue what could happen if the | ||
| element is triggered. | ||
|
|
||
| ### <Required /> `expanded` | ||
|
|
||
| Indicates whether an expandable element is currently expanded or collapsed. | ||
|
|
||
| ## Related guidelines | ||
|
|
||
| - [Accessibility Label](../../../../website/guidelines/accessibility-label.md) | ||
| - [Accessibility Role](../../../../website/guidelines/accessibility-role.md) | ||
| - [Contrast](../../../../website/guidelines/contrast.md) | ||
| - [Minimum Size](../../../../website/guidelines/minimum-size.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters