@cdx-ui/components 0.3.4 → 0.3.6

package/docs/components/stepper/content.md

@@ -0,0 +1,599 @@
+# Stepper (https://design.candescent.com/docs/components/stepper)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/navigation-stepper--default)
+
+`Stepper` shows named steps beside a multi-step flow, such as a wizard or guided setup. For a compact meter without step labels, use [`ProgressSegmented`](https://design.candescent.com/docs/components/progress-segmented/content.md) instead.
+
+```tsx
+import { Stepper } from '@cdx-ui/components';
+```
+
+## Basic
+
+`currentStep` is zero-based, so `currentStep={1}` marks the second step as current. Steps before it are complete by default. This differs from `ProgressSegmented.step`, which is one-based.
+
+```tsx
+import { Box, Stepper } from '@cdx-ui/components';
+
+const steps = ['Role details', 'Permissions', 'Environments', 'Review'];
+
+export default function StepperBasicDemo() {
+  return (
+    <Box className="w-64">
+      <Stepper currentStep={1} accessibilityLabel="Create role progress">
+        {steps.map((title) => (
+          <Stepper.Step key={title}>
+            <Stepper.Indicator />
+            <Stepper.Title>{title}</Stepper.Title>
+            <Stepper.Separator />
+          </Stepper.Step>
+        ))}
+      </Stepper>
+    </Box>
+  );
+}
+```
+
+## Progress
+
+Pass `isComplete` to override the default completion in either direction, and `progress` (0–100) to draw a partial ring on an incomplete step. A step before `currentStep` is complete by default, so pass `isComplete={false}` to show it as visited but unfinished.
+
+```tsx
+import { Box, Stepper } from '@cdx-ui/components';
+
+export default function StepperProgressDemo() {
+  return (
+    <Box className="w-64">
+      <Stepper currentStep={2} accessibilityLabel="Marketplace onboarding progress">
+        <Stepper.Step>
+          <Stepper.Indicator />
+          <Stepper.Title>Company profile</Stepper.Title>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step isComplete={false} progress={60}>
+          <Stepper.Indicator />
+          <Stepper.Title>Contacts</Stepper.Title>
+          <Stepper.Description>3 of 5 fields done</Stepper.Description>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step progress={25}>
+          <Stepper.Indicator />
+          <Stepper.Title>Integration details</Stepper.Title>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step isComplete>
+          <Stepper.Indicator />
+          <Stepper.Title>Terms of service</Stepper.Title>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step>
+          <Stepper.Indicator />
+          <Stepper.Title>Review</Stepper.Title>
+          <Stepper.Separator />
+        </Stepper.Step>
+      </Stepper>
+    </Box>
+  );
+}
+```
+
+## Content
+
+`Stepper.Content` renders below the title, outside the step's accessible name, for detail such as a labelled progress bar per section. It always renders when passed, whatever the step's state, so render it only on the steps that need it.
+
+```tsx
+import { Box, ProgressBar, Stepper, Text } from '@cdx-ui/components';
+
+const sections = [
+  { label: 'Your company', done: 3, total: 6 },
+  { label: 'Primary contact', done: 0, total: 4 },
+  { label: 'Marketing contact', done: 0, total: 2 },
+  { label: 'Compliance contact', done: 0, total: 2 },
+];
+
+const fieldsDone = sections.reduce((sum, { done }) => sum + done, 0);
+const fieldsTotal = sections.reduce((sum, { total }) => sum + total, 0);
+
+export default function StepperContentDemo() {
+  return (
+    <Box className="w-72">
+      <Stepper currentStep={1} accessibilityLabel="Basic application progress">
+        <Stepper.Step>
+          <Stepper.Indicator />
+          <Stepper.Title>Existing integration</Stepper.Title>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step progress={(fieldsDone / fieldsTotal) * 100}>
+          <Stepper.Indicator />
+          <Stepper.Title>Company overview</Stepper.Title>
+          <Stepper.Content>
+            {sections.map(({ label, done, total }) => (
+              <Box key={label} className="gap-1.5">
+                <Box className="flex-row justify-between">
+                  <Text size="sm" color="secondary">
+                    {label}
+                  </Text>
+                  <Text size="sm" color="secondary">
+                    {done}/{total}
+                  </Text>
+                </Box>
+                <ProgressBar
+                  value={done}
+                  max={total}
+                  accessibilityLabel={`${label}, ${done} of ${total} fields complete`}
+                >
+                  <ProgressBar.Indicator />
+                </ProgressBar>
+              </Box>
+            ))}
+          </Stepper.Content>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step>
+          <Stepper.Indicator />
+          <Stepper.Title>Product & integration</Stepper.Title>
+          <Stepper.Separator />
+        </Stepper.Step>
+        <Stepper.Step>
+          <Stepper.Indicator />
+          <Stepper.Title>Compliance & documentation</Stepper.Title>
+        </Stepper.Step>
+      </Stepper>
+    </Box>
+  );
+}
+```
+
+## Horizontal
+
+Set `orientation="horizontal"` to lay the steps out in a row, for example above a wizard in a modal. By default each label sits after its indicator, steps take the width their labels need, and the separators stretch to fill the space between them. The layout uses logical start and end, so step order and separators mirror in right-to-left layouts.
+
+A horizontal stepper needs room for every label in one row. Keep labels short, and use a vertical stepper on small screens. When the row runs out of room, labels wrap and can collide with the separators. A compact mobile stepper is planned separately.
+
+```tsx
+import { Box, ScrollView, Stepper } from '@cdx-ui/components';
+
+const steps = ['Details', 'Permissions', 'Members', 'Review'];
+
+export default function StepperHorizontalDemo() {
+  return (
+    <ScrollView horizontal contentContainerClassName="grow">
+      <Box className="min-w-140 flex-1">
+        <Stepper currentStep={1} orientation="horizontal" accessibilityLabel="New role progress">
+          {steps.map((title, index) => (
+            <Stepper.Step key={title} progress={index === 1 ? 40 : 0}>
+              <Stepper.Indicator />
+              <Stepper.Title>{title}</Stepper.Title>
+              <Stepper.Separator />
+            </Stepper.Step>
+          ))}
+        </Stepper>
+      </Box>
+    </ScrollView>
+  );
+}
+```
+
+## Placement
+
+Set `labelPlacement="bottom"` to give every step an equal column, with the indicator and label centered and the separator running from one indicator to the next. It fits more steps in the same width than labels placed after the indicators. `labelPlacement` only applies to horizontal steppers. `Stepper.Content` renders below the step's label in either placement, but it is designed for vertical steppers.
+
+```tsx
+import { Box, ScrollView, Stepper } from '@cdx-ui/components';
+
+const steps = ['Details', 'Permissions', 'Members', 'Review'];
+
+export default function StepperHorizontalBottomDemo() {
+  return (
+    <ScrollView horizontal contentContainerClassName="grow">
+      <Box className="min-w-120 flex-1">
+        <Stepper
+          currentStep={1}
+          orientation="horizontal"
+          labelPlacement="bottom"
+          accessibilityLabel="New role progress, labels below"
+        >
+          {steps.map((title, index) => (
+            <Stepper.Step key={title} progress={index === 1 ? 40 : 0}>
+              <Stepper.Indicator />
+              <Stepper.Title>{title}</Stepper.Title>
+              <Stepper.Separator />
+            </Stepper.Step>
+          ))}
+        </Stepper>
+      </Box>
+    </ScrollView>
+  );
+}
+```
+
+## Clickable steps
+
+Pass `onStepChange` to let users press a step to jump back to it. By default only complete steps are pressable. Set `isLinear={false}` to allow any step, for example when every step can be edited in any order. The current step and steps with `isDisabled` are never pressable. Clickable steps work the same way in both orientations.
+
+Navigation stays yours. With `currentStep` set, a press calls `onStepChange` with the step's index, and the stepper does not move until you update `currentStep`. Without `currentStep`, the stepper starts at `defaultStep`, moves itself on a press, and then calls `onStepChange`.
+
+```tsx
+import { useState } from 'react';
+import { Box, Button, Stepper, Switch, Text } from '@cdx-ui/components';
+
+const steps = ['Role details', 'Permissions', 'Environments', 'Review'];
+
+export default function StepperClickableDemo() {
+  const [currentStep, setCurrentStep] = useState(2);
+  const [canSkipAhead, setCanSkipAhead] = useState(false);
+
+  return (
+    <Box className="gap-6">
+      <Box className="flex-row items-center gap-3">
+        <Switch
+          value={canSkipAhead}
+          onValueChange={setCanSkipAhead}
+          accessibilityLabel="Allow skipping ahead"
+        />
+        <Text>Allow skipping ahead</Text>
+      </Box>
+
+      <Box className="w-64">
+        <Stepper
+          currentStep={currentStep}
+          onStepChange={setCurrentStep}
+          isLinear={!canSkipAhead}
+          accessibilityLabel="Create role progress"
+        >
+          {steps.map((title) => (
+            <Stepper.Step key={title}>
+              <Stepper.Indicator />
+              <Stepper.Title>{title}</Stepper.Title>
+              <Stepper.Separator />
+            </Stepper.Step>
+          ))}
+        </Stepper>
+      </Box>
+
+      <Button
+        className="self-start"
+        isDisabled={currentStep >= steps.length - 1}
+        onPress={() => setCurrentStep((step) => step + 1)}
+      >
+        <Button.Label>Next</Button.Label>
+      </Button>
+    </Box>
+  );
+}
+```
+
+## Wizard
+
+Navigation stays in your form: drive `currentStep` from your own Back and Next buttons. When the step changes, move focus to the new step's heading so screen readers announce it.
+
+```tsx
+import { useEffect, useRef, useState, type ComponentRef } from 'react';
+import { Box, Button, Field, Heading, Input, Stepper, Text } from '@cdx-ui/components';
+
+const steps = [
+  { title: 'Role details', field: 'Role name', placeholder: 'Billing admin' },
+  { title: 'Permissions', field: 'Permission set', placeholder: 'Payments: read and write' },
+  { title: 'Review', field: null, placeholder: '' },
+] as const;
+
+export default function StepperWizardDemo() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [values, setValues] = useState<Record<number, string>>({});
+  const headingRef = useRef<ComponentRef<typeof Box>>(null);
+  const hasNavigated = useRef(false);
+
+  // Move focus to the new step's heading so screen readers announce the change.
+  useEffect(() => {
+    if (hasNavigated.current) {
+      headingRef.current?.focus();
+    }
+  }, [currentStep]);
+
+  const goTo = (index: number) => {
+    hasNavigated.current = true;
+    setCurrentStep(index);
+  };
+
+  const isFinished = currentStep >= steps.length;
+  const step = isFinished ? null : steps[currentStep];
+  const value = values[currentStep] ?? '';
+  const canContinue = step?.field === null || value.trim().length > 0;
+
+  return (
+    <Box className="w-full max-w-2xl flex-row flex-wrap gap-8">
+      <Box className="w-56">
+        <Stepper currentStep={currentStep} accessibilityLabel="Create role progress">
+          {steps.map(({ title }) => (
+            <Stepper.Step key={title}>
+              <Stepper.Indicator />
+              <Stepper.Title>{title}</Stepper.Title>
+              <Stepper.Separator />
+            </Stepper.Step>
+          ))}
+        </Stepper>
+      </Box>
+
+      <Box className="min-w-64 flex-1 gap-4">
+        <Box ref={headingRef} tabIndex={-1} className="web:outline-none">
+          <Heading size="sm">{step ? step.title : 'Role created'}</Heading>
+        </Box>
+
+        {step?.field ? (
+          <Field name={step.field} isRequired>
+            <Field.Label>{step.field}</Field.Label>
+            <Input>
+              <Input.Field
+                placeholder={step.placeholder}
+                value={value}
+                onChangeText={(text) => setValues((prev) => ({ ...prev, [currentStep]: text }))}
+              />
+            </Input>
+          </Field>
+        ) : null}
+
+        {step?.field === null ? (
+          <Box className="gap-1">
+            {steps
+              .filter((item) => item.field !== null)
+              .map((item, index) => (
+                <Text key={item.title} size="sm">
+                  {`${item.field}: ${values[index] ?? ''}`}
+                </Text>
+              ))}
+          </Box>
+        ) : null}
+
+        {isFinished ? <Text size="sm">The role is ready to assign.</Text> : null}
+
+        <Box className="flex-row gap-3">
+          {isFinished ? (
+            <Button
+              variant="outline"
+              onPress={() => {
+                setValues({});
+                goTo(0);
+              }}
+            >
+              <Button.Label>Start over</Button.Label>
+            </Button>
+          ) : (
+            <>
+              <Button
+                variant="outline"
+                isDisabled={currentStep === 0}
+                onPress={() => goTo(currentStep - 1)}
+              >
+                <Button.Label>Back</Button.Label>
+              </Button>
+              <Button isDisabled={!canContinue} onPress={() => goTo(currentStep + 1)}>
+                <Button.Label>
+                  {currentStep === steps.length - 1 ? 'Create role' : 'Next'}
+                </Button.Label>
+              </Button>
+            </>
+          )}
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Custom indicator
+
+Children of `Stepper.Indicator` replace the numeral or check inside the disc, while the disc color and progress ring still render. Read the step's state with `useStepperStep()` to tone the glyph.
+
+```tsx
+import { Box, Icon, Stepper, useStepperStep, type IconProps } from '@cdx-ui/components';
+import { AdminPanelSettings, Checklist, Group } from '@cdx-ui/icons';
+
+function StepGlyph({ as }: Pick<IconProps, 'as'>) {
+  const { isCurrent } = useStepperStep();
+
+  return (
+    <Icon
+      as={as}
+      className={
+        isCurrent ? 'size-4 text-content-brand-on-strong' : 'size-4 text-content-neutral-on-strong'
+      }
+    />
+  );
+}
+
+const steps = [
+  { title: 'Team details', icon: Group },
+  { title: 'Access', icon: AdminPanelSettings },
+  { title: 'Review', icon: Checklist },
+];
+
+export default function StepperCustomIndicatorDemo() {
+  return (
+    <Box className="w-64">
+      <Stepper currentStep={1} accessibilityLabel="Create team progress">
+        {steps.map(({ title, icon }) => (
+          <Stepper.Step key={title}>
+            <Stepper.Indicator>
+              <StepGlyph as={icon} />
+            </Stepper.Indicator>
+            <Stepper.Title>{title}</Stepper.Title>
+            <Stepper.Separator />
+          </Stepper.Step>
+        ))}
+      </Stepper>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Stepper
+
+The list root. It owns `currentStep` and numbers its steps by position. Every direct element child is a step: arrays and fragments are unwrapped, and `false` and `null` children are skipped, so conditional steps renumber automatically. A step nested inside another element is not counted.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | `Stepper.Step` elements. Every direct element child is a step and is numbered by position; arrays and fragments are unwrapped, and `false`/`null` children are skipped. |
+| `currentStep?` | `number` | — | Controlled, zero-based current step. A value outside `0…count-1` means no step is current; a value `>= count` makes every step complete by default. |
+| `defaultStep?` | `number` | `0` | Uncontrolled starting step. Ignored when `currentStep` is set. |
+| `onStepChange?` | `((index: number) => void)` | — | Called with the pressed step's index. Setting it makes eligible steps clickable. |
+| `isLinear?` | `boolean` | `true` | When `true`, only complete steps are clickable. When `false`, every non-current, non-disabled step is. |
+| `orientation?` | `'horizontal' \| 'vertical'` | `'vertical'` | `'horizontal'` lays the steps out in a row. `labelPlacement` chooses where each label sits. |
+| `labelPlacement?` | `'end' \| 'bottom'` | `'end'` | Horizontal only; ignored when `orientation` is `'vertical'`. `'end'` puts each label after its indicator, sizes steps to their labels and stretches the separators between them. `'bottom'` gives every step an equal column with the indicator and label centered. |
+| `getStepAccessibilityText?` | `((state: StepperStepState) => string)` | — | Returns the state phrase appended to each step's title for assistive technology, replacing the English default (for example `"current step, 40% complete"`). |
+| `asChild?` | `boolean` | `false` | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute              | Values                     | Description                                      |
+| ---------------------- | -------------------------- | ------------------------------------------------ |
+| `data-orientation`     | `vertical` \| `horizontal` | Layout direction                                 |
+| `data-label-placement` | `end` \| `bottom`          | Label position; only affects horizontal steppers |
+
+## Sub-components
+
+### Stepper.Step
+
+One step in the list. Completion defaults to `index < currentStep`, and an explicit `isComplete` wins in both directions. `progress` is clamped to 0–100 and draws a partial ring while the step is incomplete. It never completes the step on its own, even at 100.
+
+The parts below must be direct children of `Stepper.Step`, which arranges them into the indicator track, the label and the body. Only the first of each part is used, and anything else renders in the body after the title. A part wrapped in your own component is not recognized. Leave out `Stepper.Separator` for a compact list with no connector line.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | `Stepper.Indicator`, `Stepper.Title`, `Stepper.Description`, `Stepper.Content` and `Stepper.Separator`. They must be **direct** children: the step sorts them into regions by component identity, so a `memo()`/HOC wrapper is not recognized and renders as content. Only the first of each slot is used. `asChild` skips the sorting. |
+| `isComplete?` | `boolean` | `index < currentStep` | Whether the step is complete. An explicit value wins in both directions. |
+| `progress?` | `number` | `0` | Partial progress, 0–100. Values outside the range are clamped; non-finite values are `0`. |
+| `isDisabled?` | `boolean` | `false` | Only affects clickability. A disabled step still shows its state. |
+| `asChild?` | `boolean` | `false` | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute              | Values                     | Description                                      |
+| ---------------------- | -------------------------- | ------------------------------------------------ |
+| `data-orientation`     | `vertical` \| `horizontal` | Layout direction                                 |
+| `data-label-placement` | `end` \| `bottom`          | Label position; only affects horizontal steppers |
+| `data-current`         | `true` \| `false`          | Whether this is the current step                 |
+| `data-complete`        | `true` \| `false`          | Resolved completion                              |
+| `data-progress`        | `true` \| `false`          | `true` while the partial progress ring is drawn  |
+| `data-clickable`       | `true` \| `false`          | Whether the step can be pressed                  |
+| `data-disabled`        | `true` \| `false`          | Whether the step has `isDisabled`                |
+
+The step's indicator and label are wrapped in a trigger (`data-slot="stepper-step-trigger"`), which becomes the button on a clickable step. It emits `data-clickable` and `data-disabled`, plus these interaction attributes while the step is clickable:
+
+| Attribute            | Values            | Description              |
+| -------------------- | ----------------- | ------------------------ |
+| `data-hover`         | `true` \| `false` | Pointer is over the step |
+| `data-active`        | `true` \| `false` | Step is being pressed    |
+| `data-focus-visible` | `true` \| `false` | Step has keyboard focus  |
+
+### Stepper.Indicator
+
+The numbered disc. It shows a check when the step is complete, the 1-based step number otherwise, and a progress ring while the step has partial progress. Emits the same `data-current`, `data-complete` and `data-progress` attributes as `Stepper.Step`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Replaces the glyph inside the disc. The disc, tone and progress ring still render. Defaults to a check when the step is complete, otherwise the 1-based step number. |
+| `asChild?` | `boolean` | — | Replaces the whole indicator with the child element via `Slot`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Stepper.Title
+
+The step label. Emphasized on the current step, and emits `data-current`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Stepper.Description
+
+Secondary text below the title, read as part of the step's name.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Stepper.Content
+
+Detail below the label, such as section rows. Always rendered when passed.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Stepper.Separator
+
+The connector line to the next step. In a vertical stepper it stretches with the step's title and content. In a horizontal stepper it runs between this step's indicator, or its label when labels sit after the indicators, and the next step's indicator. It renders nothing on the last step.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### useStepperStep
+
+Returns the enclosing step's resolved state. Call it inside a `Stepper.Step`, for example in a custom indicator glyph. It throws outside one.
+
+```tsx
+const { index, isCurrent, isComplete } = useStepperStep();
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `index` | `number` | — | Zero-based position among the steps. |
+| `count` | `number` | — | Number of steps rendered. |
+| `isCurrent` | `boolean` | — | — |
+| `isComplete` | `boolean` | — | Resolved completion: the explicit `isComplete`, or `index < currentStep`. |
+| `progress` | `number` | — | Clamped to 0–100. Non-finite values are 0. |
+| `hasProgress` | `boolean` | — | True when the partial ring is drawn: `0 < progress` and not complete. |
+| `isLast` | `boolean` | — | — |
+| `isClickable` | `boolean` | — | True when the step renders as a button. |
+| `isDisabled` | `boolean` | — | — |
+| `orientation` | `'horizontal' \| 'vertical'` | — | — |
+| `labelPlacement` | `'end' \| 'bottom'` | — | — |
+
+## Anatomy
+
+| `data-slot`            | Element                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `stepper`              | List root                                                                      |
+| `stepper-step`         | List item for one step                                                         |
+| `stepper-step-trigger` | Indicator and label, which carry the step name. The button on a clickable step |
+| `stepper-indicator`    | Numbered disc, check and progress ring                                         |
+| `stepper-title`        | Step label                                                                     |
+| `stepper-description`  | Secondary label text                                                           |
+| `stepper-content`      | Detail below the label                                                         |
+| `stepper-separator`    | Connector line                                                                 |
+
+## Accessibility
+
+`Stepper` is a list and each step is a list item in either orientation, so web screen readers announce how many steps there are and each step's position. The list's `accessibilityLabel` defaults to `"Progress"`. Name the flow instead, for example `"Create role progress"`.
+
+On web, only the current step carries `aria-current="step"`. Native platforms have no equivalent, so the state is part of each step's accessible name.
+
+Each step's accessible name is its title, then its description, then a state phrase: `current step`, `completed`, `incomplete`, or `40% complete`, combined as in `current step, 40% complete`. The announced percentage is rounded and held between 1 and 99 while the step is incomplete. On web the phrase is visually hidden text after the label. On iOS and Android the indicator and label are grouped into one element and the phrase is its accessibility value. `getStepAccessibilityText` receives the step's `StepperStepState` and returns only the state phrase, not the title, so use it to localize or reword the phrase.
+
+When `onStepChange` is set, each clickable step's indicator and label become a button inside its list item. The button's name is the step's title and state phrase, as above. Users move between clickable steps with Tab and Shift+Tab and activate one with Enter or Space. Steps that are not clickable are not focusable and have no button role, so upcoming steps are not announced as dimmed buttons. Arrow keys are not handled, because the stepper is a list rather than a composite widget.
+
+`Stepper.Indicator` and `Stepper.Separator` are hidden from assistive technologies. `Stepper.Content` stays in the normal reading order, outside the step's name.
+
+The stepper does not announce step changes, and it has no live region. In a wizard, move focus to the new step's heading when the step changes, as the Wizard demo does. On web, wrap the heading in a `Box` with `tabIndex={-1}` and call its `focus()`. On iOS and Android, use `AccessibilityInfo.setAccessibilityFocus`.