Skip to content

docs(item): document the keyboard interactions with item #3788

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 12, 2024
Merged

docs(item): document the keyboard interactions with item #3788

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fb537f8
docs(api): update keyboard navigation to use kbd element
brandyscarney Aug 8, 2024
3e387e1
style: consistent spacing
brandyscarney Aug 8, 2024
52cbbc0
style: lint
brandyscarney Aug 8, 2024
5928dcd
docs(item): document the keyboard interactions for item
brandyscarney Aug 8, 2024
49f95d4
style: improve verbiage
brandyscarney Aug 9, 2024
143d4a6
revert(docs): revert v6 changes
brandyscarney Aug 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions docs/api/accordion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,19 +170,19 @@ import AccessibilityAnimations from '@site/static/usage/v8/accordion/accessibili

<AccessibilityAnimations />

### Keyboard Navigation
### Keyboard Interactions

When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard support for interacting with the component. The following table details what each key does:

| Key | Function |
| ------------------ | ------------------------------------------------------------ |
| `Space` or `Enter` | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. |
| `Tab` | Moves focus to the next focusable element. |
| `Shift` + `Tab` | Moves focus to the previous focusable element. |
| `Down Arrow` | - When focus is on an accordion header, moves focus to the next accordion header. <br />- When focus is on the last accordion header, moves focus to the first accordion header. |
| `Up Arrow` | - When focus is on an accordion header, moves focus to the previous accordion header. <br />- When focus is on the first accordion header, moves focus to the last accordion header. |
| `Home` | When focus is on an accordion header, moves focus to the first accordion header. |
| `End` | When focus is on an accordion header, moves focus to the last accordion header. |
| Key | Description |
| ------------------------------------ | ------------------------------------------------------------ |
| <kbd>Space</kbd> or <kbd>Enter</kbd> | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. |
| <kbd>Tab</kbd> | Moves focus to the next focusable element. |
| <kbd>Shift</kbd> + <kbd>Tab</kbd> | Moves focus to the previous focusable element. |
| <kbd>Down Arrow</kbd> | - When focus is on an accordion header, moves focus to the next accordion header. <br />- When focus is on the last accordion header, moves focus to the first accordion header. |
| <kbd>Up Arrow</kbd> | - When focus is on an accordion header, moves focus to the previous accordion header. <br />- When focus is on the first accordion header, moves focus to the last accordion header. |
| <kbd>Home</kbd> | When focus is on an accordion header, moves focus to the first accordion header. |
| <kbd>End</kbd> | When focus is on an accordion header, moves focus to the last accordion header. |

## Performance

Expand Down
36 changes: 18 additions & 18 deletions docs/api/datetime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,30 +416,30 @@ dates in JavaScript.

## Accessibility

### Keyboard Navigation
### Keyboard Interactions

`ion-datetime` has full keyboard support for navigating between focusable elements inside of the component. The following table details what each key does:

| Key | Function |
| ------------------ | ------------------------------------------------------------ |
| `Tab` | Moves focus to the next focusable element. |
| `Shift` + `Tab` | Moves focus to the previous focusable element. |
| `Space` or `Enter` | Clicks the focusable element. |
| Key | Description |
| ------------------------------------ | ---------------------------------------------- |
| <kbd>Tab</kbd> | Moves focus to the next focusable element. |
| <kbd>Shift</kbd> + <kbd>Tab</kbd> | Moves focus to the previous focusable element. |
| <kbd>Space</kbd> or <kbd>Enter</kbd> | Clicks the focusable element. |

#### Date Grid

| Key | Function |
| ------------------ | ------------------------------------------------------------ |
| `ArrowUp` | Moves focus to the same day of the previous week. |
| `ArrowDown` | Moves focus to the same day of the next week. |
| `ArrowRight` | Moves focus to the next day. |
| `ArrowLeft` | Moves focus to the previous day. |
| `Home` | Moves focus to the first day of the current week. |
| `End` | Moves focus to the last day of the current week. |
| `PageUp` | Changes the grid of dates to the previous month. |
| `PageDown` | Changes the grid of dates to the next month. |
| `Shift` + `PageUp` | Changes the grid of dates to the previous year. |
| `Shift` + `PageDown` | Changes the grid of dates to the next year. |
| Key | Description |
| -------------------------------------- | ------------------------------------------------- |
| <kbd>ArrowUp</kbd> | Moves focus to the same day of the previous week. |
| <kbd>ArrowDown</kbd> | Moves focus to the same day of the next week. |
| <kbd>ArrowRight</kbd> | Moves focus to the next day. |
| <kbd>ArrowLeft</kbd> | Moves focus to the previous day. |
| <kbd>Home</kbd> | Moves focus to the first day of the current week. |
| <kbd>End</kbd> | Moves focus to the last day of the current week. |
| <kbd>PageUp</kbd> | Changes the grid of dates to the previous month. |
| <kbd>PageDown</kbd> | Changes the grid of dates to the next month. |
| <kbd>Shift</kbd> + <kbd>PageUp</kbd> | Changes the grid of dates to the previous year. |
| <kbd>Shift</kbd> + <kbd>PageDown</kbd> | Changes the grid of dates to the next year. |

#### Time, Month, and Year Wheels

Expand Down
47 changes: 39 additions & 8 deletions docs/api/item.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Supporting visuals are decorative icons or other adornments for an item. Common

If a visual is required to interact with the item, such as an icon button, then the visual is an [action](#actions) not a supporting visual.

<BestPracticeFigure
<BestPracticeFigure
text="Supporting visuals should be rendered in a consistent manner. This makes the information in each item easier to parse."
doText="Align visuals on the same side in a list"
doNotText="Don't render visuals with different alignments in the same list"
Expand All @@ -60,7 +60,7 @@ import SupportingVisuals from '@site/static/usage/v8/item/content-types/supporti

The text content type includes form control labels or other visible text. This text serves to indicate the intent of the item. Try to keep the text short and to the point.

<BestPracticeFigure
<BestPracticeFigure
text={<>If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a <a href={useBaseUrl('api/note')}>Note</a> at the bottom of the list. Adding the item to its own list makes it clear which item the text is associated with.</>}
doText="Move long text outside of the list"
doNotText="Don't try to fit long text in an item"
Expand All @@ -82,15 +82,15 @@ import Text from '@site/static/usage/v8/item/content-types/text/index.md';

Metadata provides additional context for an item such as status text or counts. Components like [Badge](./badge) or [Note](./note) are great ways of showing metadata.

<BestPracticeFigure
<BestPracticeFigure
text="Limit the amount of metadata you include to only the most relevant information."
doText="Add only the most important metadata"
doNotText="Don't add too much metadata as it can overwhelm or confuse the user."
doImage={<img alt="A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item." src={useBaseUrl('img/item/metadata-relevant-do.jpg')} />}
doNotImage={<img alt="A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today." src={useBaseUrl('img/item/metadata-relevant-do-not.jpg')} />}
/>

<BestPracticeFigure
<BestPracticeFigure
text="Developers should also consider how important the metadata is. Drawing attention to the metadata may be helpful for the user or it may distract them from the more important information depending on the use case."
doText="Prioritize the most important content."
cautionText="Prioritized metadata may distract from other important content."
Expand All @@ -112,7 +112,7 @@ Actions are interactive elements that do something when you activate them. An it

Developers should avoid creating <a href="https://dequeuniversity.com/rules/axe/4.4/nested-interactive">nested interactives</a> which can break the user experience with screen readers. For example, developers should avoid adding a button inside the main content of the Item if the `button` property is set to `true`.

<BestPracticeFigure
<BestPracticeFigure
text={<>Actions can be added by using the <a href={useBaseUrl('api/item-sliding')}>Item Sliding</a> component. Actions can also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more than 2 actions.</>}
doText={<>Use an <a href={useBaseUrl('api/item-sliding')}>Item Sliding</a> to reveal multiple actions by swiping on the Item.</>}
doNotText="Don't put more than 2 actions within an Item."
Expand All @@ -130,23 +130,23 @@ import Actions from '@site/static/usage/v8/item/content-types/actions/index.md';

Controls are form components such as checkboxes, inputs, radios, and more. Each item in a list should have at most two controls due to screen space constraints.

<BestPracticeFigure
<BestPracticeFigure
text={<>Metadata such as helper text or character counts should not be used on form controls in list views. If such metadata is needed, the form control should be placed outside of a list. <a href={useBaseUrl('api/input#filled-inputs')}>Filled Inputs</a> are a great way of visually defining the input container outside of a list.</>}
doText="Place inputs with metadata outside of the list."
doNotText="Don't put metadata for inputs in the list."
doImage={<img alt="There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with." src={useBaseUrl('img/item/controls-metadata-list-do.jpg')} />}
doNotImage={<img alt="There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with." src={useBaseUrl('img/item/controls-metadata-list-do-not.jpg')} />}
/>

<BestPracticeFigure
<BestPracticeFigure
text={<>Alternatively, the metadata can be placed in a <a href={useBaseUrl('api/note')}>Note</a> at the bottom of the list.</>}
doText="Place metadata for inputs at the end of a list."
doNotText="Don't put metadata for inputs in the list."
doImage={<img alt="There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above." src={useBaseUrl('img/item/controls-metadata-do.jpg')} />}
doNotImage={<img alt="There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with." src={useBaseUrl('img/item/controls-metadata-do-not.jpg')} />}
/>

<BestPracticeFigure
<BestPracticeFigure
text={<>Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a <a href="useBaseUrl('api/modal')">Modal</a> that is accessible from the item.</>}
doText="Move additional controls to a submenu accessible from the item."
doNotText="Don't use more than two controls within an item."
Expand Down Expand Up @@ -245,6 +245,37 @@ The following guidelines will help ensure your list items are easy to understand
3. Items should never render [nested interactives](https://dequeuniversity.com/rules/axe/4.4/nested-interactive). Screen readers are unable to select the correct interactive element when nested interactives are used. For example, avoid placing a button inside of an `ion-item` that has `button="true"`.
4. Use [content types](#content-types) correctly. The Item component is designed to be a row in a [List](./list) and should not be used as a general purpose container.

## Accessibility

### Keyboard Interactions

An `<ion-item>` has the following keyboard interactions when any of these conditions are met:
- The `button` property is set to `"true"`, rendering a native `<button>` element.
- The `href` property is set, rendering a native `<a>` element.
- The `routerLink` property is set, rendering a native `<a>` element.

| Key | Description |
| --------------------------------- | ---------------------------------------------- |
| <kbd>Tab</kbd> | Moves focus to the next focusable element. |
| <kbd>Shift</kbd> + <kbd>Tab</kbd> | Moves focus to the previous focusable element. |

#### Button

When an `<ion-item>` renders a native `<button>` element, the keyboard interactions follow the same pattern as the [button role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role#keyboard_interactions):

| Key | Description |
| ---------------- | --------------------------------------------------------------------------- |
| <kbd>Enter</kbd> | Activates the item, triggering its `click` event. If the item is within a form and has `type` set to `"submit"`, it submits the form. |
| <kbd>Space</kbd> | Activates the item, triggering its `click` event. Does not submit the form, even if the item `type` is `"submit"`. |

#### Anchor

When an `<ion-item>` renders a native `<a>` element, the keyboard interactions follow the same pattern as the [link role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/link_role):

| Key | Description |
| ---------------- | ---------------------------------------------------------------------------------------- |
| <kbd>Enter</kbd> | Activates the item, navigating to the linked page or moving focus to the in-page target. |

## Properties
<Props />

Expand Down
12 changes: 6 additions & 6 deletions docs/api/modal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ Here's a simplified example illustrating how a child component can interact with
import CanDismissChildStateExample from '@site/static/usage/v8/modal/can-dismiss/child-state/index.md';

<CanDismissChildStateExample />

## Card Modal

Developers can create a card modal effect where the modal appears as a card stacked on top of your app's main content. To create a card modal, developers need to set the `presentingElement` property on `ion-modal`.
Expand Down Expand Up @@ -170,7 +170,7 @@ Modals are presented at the root of your application so they overlay your entire
`ion-modal` works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of `0`. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the `--box-shadow` and `--backdrop-opacity` CSS variables:
:::

```
```
ion-modal.stack-modal {
--box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
--backdrop-opacity: var(--ion-backdrop-opacity, 0.32);
Expand Down Expand Up @@ -245,11 +245,11 @@ interface ModalCustomEvent extends CustomEvent {

## Accessibility

### Keyboard Navigation
### Keyboard Interactions

| Key | Function |
| ----- | ------------------- |
| `Esc` | Dismisses the modal |
| Key | Description |
| --------------- | ------------------- |
| <kbd>Esc</kbd> | Dismisses the modal |


### Labels
Expand Down
20 changes: 10 additions & 10 deletions docs/api/picker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Pickers can be displayed inside of overlays, such as `ion-modal` to create a pic
import ModalExample from '@site/static/usage/v8/picker/modal/index.md';

<ModalExample />

## Accessibility

### Screen Readers
Expand All @@ -67,18 +67,18 @@ Picker supports navigation using a screen reader by implementing the [`slider` r
The Swipe Up and Swipe Down gestures rely on the correct key events being synthesized as noted on the [`slider` documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role). [Chromium-based browsers do not synthesize keyboard events correctly](https://issues.chromium.org/issues/40816094), but the "Double Tap and Slide Up/Down" gesture can be used as an alternative until this has been implemented in Chromium-based browsers.
:::

### Keyboard Navigation
### Keyboard Interactions

Each [Picker Column](./picker-column) can be navigated using the keyboard when focused.

| Key | Function |
| ------------------ | ------------------------------------------------------------ |
| `ArrowUp` | Scroll to the previous option. |
| `ArrowDown` | Scroll to the next option. |
| `PageUp` | Scroll up by more than one option. |
| `PageDown` | Scroll down by more than one option. |
| `Home` | Scroll to the first option. |
| `End` | Scroll to the last option. |
| Key | Description |
| -------------------- | ------------------------------------ |
| <kbd>ArrowUp</kbd> | Scroll to the previous option. |
| <kbd>ArrowDown</kbd> | Scroll to the next option. |
| <kbd>PageUp</kbd> | Scroll up by more than one option. |
| <kbd>PageDown</kbd> | Scroll down by more than one option. |
| <kbd>Home</kbd> | Scroll to the first option. |
| <kbd>End</kbd> | Scroll to the last option. |

## Properties
<Props />
Expand Down
Loading