Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
132 changes: 132 additions & 0 deletions resources/views/docs/mobile/4/digging-deeper/accessibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,138 @@ NavBarOptions::make()->actions([
```
@endverbatim

## Composing your own controls

When you draw a control yourself from `<native:pressable>`, `<native:column>`, `<native:row>`, `<native:stack>` or `<native:gesture-area>`, the screen reader can't tell what it is from how it looks. The props below let it describe the control the way it describes a native one. They apply to `pressable`, `column`, `row`, `stack`, `gesture-area`, `text`, `icon` and `image`; native controls such as `<native:button>` and `<native:toggle>` already announce their own role and state.

### Role

`a11y-role` says what the element is:

- `button`: the default for a `pressable` with `@press`.
- `checkbox` and `switch`: use with `a11y-checked`.
- `radio` and `tab`: use with `a11y-selected`. Put them in a `radiogroup` or `tablist` container with an `a11y-label`.
- `dropdown`: a control that opens a list of choices. Use with `a11y-value` for the current choice.
- `adjustable`: a slider or stepper. Use with a value and `@a11yIncrement` / `@a11yDecrement`.
- `progress`: use with `a11y-value`, and the numbers when you have them.
- `header`, `image`, and `none` (no role at all, for a pressable that shouldn't read as a button).

@verbatim
```blade static
<native:pressable @press="toggleTerms"
a11y-role="checkbox" :a11y-checked="$accepted" a11y-label="Accept the terms">
<native:icon :name="$accepted ? 'check_box' : 'check_box_outline_blank'" />
<native:text>Accept the terms</native:text>
</native:pressable>
```
@endverbatim

### State

- `a11y-checked`: `true`, `false` or `mixed`, for checkboxes and switches.
- `a11y-selected`: for radios, tabs and other selectable elements.
- `a11y-expanded`: for disclosure rows and dropdowns. TalkBack offers expand or collapse, which taps the element. Pass `false` rather than `null` while it's collapsed.
- `a11y-state`: a state in your own words when none of the above fits, such as "Downloading" or "3 unread".
- `a11y-error`: the element's error, such as a validation message. TalkBack reads it with the element's state; VoiceOver reads it after the value and announces it when it appears. Put it on an element with a label or a role, so the screen reader has an element to read it on. On a `radiogroup` or `tablist`, the screen reader stops on the group itself while it has an error, before its first option. If you also show the message as text, mark that text `a11y-hidden` so it isn't read twice.
- `disabled` (on `pressable`): stops `@press`, `@longPress`, `@doubleTap` and the press-down and press-up handlers, and announces the element as unavailable. The content is drawn as you wrote it, so style the disabled look yourself. On iOS, controls inside the pressable are disabled too.

@verbatim
```blade static
<native:column ref="priority" a11y-role="radiogroup" a11y-label="Priority"
:a11y-error="$errors->first('priority')">
@foreach ($priorities as $value => $label)
<native:pressable @press="choose('{{ $value }}')" a11y-role="radio"
:a11y-selected="$priority === $value" :disabled="$value === 'urgent' && ! $canEscalate">
<native:text>{{ $label }}</native:text>
</native:pressable>
@endforeach
</native:column>
```
@endverbatim

VoiceOver has no checkbox, expanded or mixed state of its own, so it speaks "Checked", "Unchecked", "Mixed", "On", "Off", "Expanded" and "Collapsed" as the element's value. Add those keys to your app's `Localizable.xcstrings` to translate them.

### Values and adjusting

- `a11y-value`: the spoken value, such as "40%" or "3 of 5".
- `a11y-value-now`, `a11y-value-min`, `a11y-value-max`: the numbers behind it. TalkBack uses them for its range; VoiceOver reads `a11y-value`, or the number when there's no text.
- `@a11yIncrement` and `@a11yDecrement`: called when a screen-reader user swipes up or down on an `adjustable` element. Your handler decides the step.

@verbatim
```blade static
<native:gesture-area :pan-x="$dx" @dragEnd="setVolume"
a11y-role="adjustable" a11y-label="Volume" a11y-value="{{ $volume }}%"
:a11y-value-now="$volume" a11y-value-min="0" a11y-value-max="100"
@a11yIncrement="louder" @a11yDecrement="quieter">
...
</native:gesture-area>
```
@endverbatim

### Actions for gestures

A swipe or a drag has no screen-reader equivalent. `:a11y-actions` takes the same `NavAction` items as `:context-menu` and offers them in the screen reader's actions menu:

@verbatim
```blade static
<native:gesture-area :pan-x="$dx" :snap-x="[-96, 0]"
:a11y-actions="[
NavAction::make('archive')->label('Archive')->press('archive('.$mail->id.')'),
NavAction::make('delete')->label('Delete')->press('delete('.$mail->id.')'),
]">
...
</native:gesture-area>
```
@endverbatim

### Hiding decoration

`a11y-hidden` hides an element and everything inside it from the screen reader, for decoration that would only add noise.

### Your own dialogs and sheets

A container with `a11y-modal` is an overlay: while it's on screen, the screen reader stays inside it. Give it an `a11y-label`, which TalkBack announces as its title, and an `@a11yDismiss` handler, which runs on VoiceOver's escape gesture (a two-finger scrub) and on Android's back gesture.

@verbatim
```blade static
@if ($confirming)
<native:stack a11y-modal a11y-label="Discard draft?" @a11yDismiss="cancel" class="absolute inset-0">
...
</native:stack>
@endif
```
@endverbatim

`a11y-pane-title` names a part of the screen that appears or changes as a whole without being modal, such as a step in a wizard. The screen reader announces the title when it appears or changes.

## Telling users about changes

When something changes on screen, describe it on the element that changed, in this order:

1. The element's own state, error or title: `a11y-checked`, `a11y-selected`, `a11y-state`, `a11y-error`, `a11y-pane-title`.
2. `a11y-live="polite"` (or `"assertive"`) on an element whose text changes and matters, such as a sync status. On a container, it reads the container's label, or its children's text when it has none. The screen reader reads the new text each time a render changes it, so keep it for updates people need to hear.
3. `Accessibility::focus($ref)` to move the screen reader to an element, such as the first error after a failed submit. It moves once your handler's changes are on screen, so the element is read with the error you just gave it. Call it last in the handler, since it waits only half a second for those changes. Use it for moves the person caused, not to pull focus elsewhere. The move interrupts whatever the screen reader is saying, including a live update from the same handler, so don't rely on both at once. It does nothing while no screen reader is running, and it leaves keyboard focus alone.
4. `Accessibility::announce($message)` only for a message that belongs to nothing on screen.

@verbatim
```php
use Native\Mobile\Facades\Accessibility;

public function submit(): void
{
if (! $this->validate()) {
Accessibility::focus('priority');

return;
}

Accessibility::announce(__('Draft saved'));
}
```
@endverbatim

Android 16 deprecated announcements that aren't tied to an element, because accessibility services may ignore them ([Android's guidance](https://developer.android.com/reference/android/view/View#announceForAccessibility(java.lang.CharSequence))). `announce()` uses a live region on Android rather than the deprecated call, but TalkBack may still read it differently from an element's own state.

## What you get for free

- **Font scaling** — All component text respects the user's system font size (Dynamic Type on iOS, font scale
Expand Down
2 changes: 2 additions & 0 deletions resources/views/docs/mobile/4/edge-components/pressable.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ All [shared layout and style attributes](layout) are supported, plus:

- `menu` - Attach a tap-to-open dropdown; opening the menu shadows `@press`. See [Menus](menus)
- `@navigate` - Navigate directly from the view, with no component method. See [Routing](../the-basics/routing#navigating-from-blade)
- `disabled` - Stops `@press`, `@longPress`, `@doubleTap` and the press-down and press-up handlers, and announces the pressable as unavailable (optional, boolean, default: `false`). Style the disabled look yourself.
- `a11y-role`, `a11y-checked`, `a11y-selected`, `a11y-expanded`, `a11y-state`, `a11y-error`, `a11y-value`, `:a11y-actions` - See [Composing your own controls](../digging-deeper/accessibility#composing-your-own-controls).

## Events

Expand Down
22 changes: 22 additions & 0 deletions resources/views/docs/mobile/4/testing/accessibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ Flags the same problems the audit rules define: icon-only buttons, chips, and ta
clickable icons and images without labels or `alt` text, pressables with neither visible text nor a label, form
controls with no label of any kind, and list items whose trailing icon button is unlabeled.

It also checks controls you've composed yourself, once they opt in with `a11y-role` or another of the props in [Composing your own controls](../digging-deeper/accessibility#composing-your-own-controls): a `checkbox` or `switch` without `a11y-checked`, an `adjustable` without a value or without both `@a11yIncrement` and `@a11yDecrement`, a `progress` without a value, a `radiogroup` or `tablist` without a label, an `a11y-modal` container without a label, and a role or state prop on a native control that ignores it.

```php
it('renders an accessible screen', function () {
Native::visit('/checkout')->assertAccessible();
Expand Down Expand Up @@ -79,6 +81,26 @@ it('has no unexpected accessibility violations', function () {
});
```

## Screen-reader actions and announcements

The harness can run what a screen reader would. `a11yIncrement()`, `a11yDecrement()` and `a11yDismiss()` call an element's handlers by its ref, and `a11yAction()` runs an entry from its actions menu by label. `tap()` refuses to tap a `disabled` pressable.

`assertFocused()` and `assertAnnounced()` check what `Accessibility::focus()` and `Accessibility::announce()` sent:

```php
it('takes the screen reader to the first error', function () {
Native::test(NewTicket::class)
->tap('submit')
->assertFocused('priority');
});

it('offers delete without the swipe', function () {
Native::test(Inbox::class)
->a11yAction('mail-42', 'Delete')
->assertSet('deleted', 42);
});
```

## Pest expectation sugar

With `PestExpectations::register()` (see [Advanced](advanced#pest-expectation-sugar)), the audit composes into
Expand Down