@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/stepper.md

@@ -0,0 +1,251 @@
+# Stepper
+
+> The root of a step sequence. It renders the sequence two ways and lets CSS pick one: on wide viewports a start-aligned, wrapping row of `StepperItem` children; on narrow ones a two-line text summary — "Step 3 of 5: <current step>" and "Next: <next step>" — with no items at all. The switch is a real viewport media query (Tailwind's `lg:`, `min-width: 1024px`), not a JS measurement, so both subtrees are always in the DOM and only one is ever displayed. It owns that layout switch and the summary copy only: the steps, their order, which one is current, and all navigation belong to the application.
+
+**Status:** ready · **Category:** navigation · **Since:** v0.63.0
+
+## Import
+
+```tsx
+import { Stepper } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Stepper
+  currentStep={2}
+  totalSteps={3}
+  current="Choose a plan"
+  next="Confirm and pay"
+>
+  <StepperItem variant="completed" label="Create an account" avatar={…} />
+  <StepperItem variant="current" label="Choose a plan" avatar={…} />
+  <StepperItem variant="future" label="Confirm and pay" avatar={…} />
+</Stepper>
+```
+
+The root of a step sequence. It renders the sequence **two ways** and lets CSS
+pick one:
+
+- **At 1024px and above** — the `StepperItem` children you pass, in a
+  start-aligned row that wraps.
+- **Below 1024px** — a two-line text summary instead: "Step 3 of 5: Choose a
+  plan" and "Next: Confirm and pay". No step items at all.
+
+Both subtrees are always in the DOM; a real viewport media query (Tailwind's
+`lg:`) displays one and hides the other. So you supply **both** the children and
+the summary props — the component cannot derive one from the other.
+
+## When to use
+
+- Any wizard / checkout / onboarding flow that has to stay usable on a narrow
+  viewport, where a row of steps would not fit.
+- Whenever you would otherwise lay `StepperItem`s out by hand: this is that row,
+  plus the compact fallback.
+
+## When not to use
+
+- For a single step in isolation — that is `StepperItem`.
+- To show progress as one quantity — use `Progress` or `ProgressCircle`.
+- For a chronological log of things that already happened — use `Timeline`.
+
+## Usage
+
+```tsx
+<Stepper
+  currentStep={2}
+  totalSteps={3}
+  current="Choose a plan"
+  next="Confirm and pay"
+>
+  <StepperItem
+    variant="completed"
+    label="Create an account"
+    avatar={
+      <Avatar color="green" className="[box-shadow:none]">
+        <CheckIcon size={16} />
+      </Avatar>
+    }
+  />
+  <StepperItem
+    variant="current"
+    label="Choose a plan"
+    avatar={
+      <Avatar color="blue" className="[box-shadow:none]">
+        <AvatarFallback>2</AvatarFallback>
+      </Avatar>
+    }
+  />
+  <StepperItem
+    variant="future"
+    label="Confirm and pay"
+    avatar={
+      <Avatar color="gray" className="[box-shadow:none]">
+        <AvatarFallback>3</AvatarFallback>
+      </Avatar>
+    }
+  />
+</Stepper>
+```
+
+`Avatar`'s 2px outset ring (meant to separate overlapping avatars in an
+`AvatarGroup`) is switched off with `className="[box-shadow:none]"` on each
+composed avatar — Figma's Stepper avatars carry no stroke, and left on, the
+ring shows as an unwanted halo on a filled step container. See `StepperItem`'s
+own spec `README.md` for the full note.
+
+On the **last** step, omit `next` — the whole "Next: …" line is then left out
+rather than rendered empty.
+
+Every string the component generates itself is a prop so it can be translated —
+`stepLabel` ("Step"), `ofLabel` ("of"), `nextLabel` ("Next:"), and
+`separatorLabel` (": ", the punctuation before the step's name). Everything else
+it renders is yours.
+
+## Parts
+
+| Part           | Element | Notes                                                  |
+| -------------- | ------- | ------------------------------------------------------ |
+| root           | `div`   | Full width; holds both layouts                         |
+| `summary`      | `div`   | The compact layout, displayed below 1024px             |
+| `current-line` | `p`     | "Step N of M: {current}", two-tone                     |
+| `next-line`    | `p`     | "Next: {next}"; absent when `next` is omitted          |
+| `items-row`    | `div`   | The `StepperItem` children, displayed at 1024px and up |
+
+## Breakpoint boundary
+
+Figma names the two variants `0-1024` and `>1025`, which leaves 1024px itself
+ambiguous. The implementation uses the kit's pinned `lg` breakpoint — exactly
+1024px (64rem) — so **1024px renders the wide row**, one pixel lower than the
+Figma label implies. That is a deliberate choice to stay on the shared
+breakpoint scale rather than mint a bespoke `1025px` query for one component;
+the repo documents equivalent roundings elsewhere (see
+`src/stories/breakpoints-demo.stories.tsx`).
+
+## Design status
+
+As of the 2026-08-24 Figma sync, this component consumes a dedicated
+`--ui-stepper-breakpoint-*` token tier (see `tokens.yaml`) — the summary's line
+gap, the item row's gap, and both summary text colors are Stepper-owned
+tokens rather than borrowed from the semantic scale, the same treatment
+`StepperItem` already carries.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `currentStep` | `ReactNode` | — | yes | 1-based index of the step the user is on, e.g. `3`. Appears in the compact summary only; above the breakpoint the highlighted `StepperItem` carries the same information. |
+| `totalSteps` | `ReactNode` | — | yes | How many steps the sequence has, e.g. `5`. Compact summary only. |
+| `current` | `ReactNode` | — | yes | The current step's name. Compact summary only. |
+| `next` | `ReactNode` | — | no | The next step's name. Omit it — on the last step — and the whole "Next: …" line is left out rather than rendered empty. Compact summary only. |
+| `stepLabel` | `string` | `Step` | no | The word introducing the step counter. A prop rather than an inlined literal so the component ships no untranslatable copy; the default is English, and a localized application overrides it. |
+| `ofLabel` | `string` | `of` | no | The word joining the current step number to the total. Translatable — see `stepLabel`. |
+| `nextLabel` | `string` | `Next:` | no | The label introducing the next step's name. Translatable — see `stepLabel`. |
+| `separatorLabel` | `string` | `: ` | no | The punctuation joining the step counter to the current step's name. Translatable — see `stepLabel`; not every locale writes it as `": "` (French spaces before the colon, CJK uses a full-width one). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The `StepperItem` elements making up the sequence, laid out in the wide row. They are not rendered in the compact summary, which replaces the row with text. |
+
+## Behavior
+
+### Two layouts, chosen by the viewport
+
+- **Given** a viewport **at or above 1024px**
+  **Then** the `StepperItem` children render as a start-aligned row that wraps, and
+  the compact summary is `display: none`.
+- **Given** a viewport **below 1024px**
+  **Then** the two-line text summary renders, and the item row is
+  `display: none` — no step items are shown at all.
+- **Given** any viewport
+  **Then** _both_ subtrees are in the DOM. The switch is a CSS media query
+  (Tailwind's `lg:`, i.e. `@media (min-width: 1024px)`), not a JS measurement,
+  so nothing is mounted or unmounted as the window resizes and there is no
+  hydration mismatch, no `ResizeObserver`, and no measuring pass.
+- **Given** a viewport of exactly **1024px**
+  **Then** the wide row renders. Figma names the variants `0-1024` and `>1025`,
+  which makes 1024 itself ambiguous; the implementation follows the kit's pinned
+  `lg` breakpoint (1024px = 64rem) rather than inventing a one-off `1025px`
+  query, so the boundary sits one pixel lower than the Figma label suggests.
+- **Given** a `dir="rtl"` document
+  **Then** both layouts mirror without extra work: neither uses a physical
+  directional utility.
+
+### The compact summary
+
+- **Given** `currentStep`, `totalSteps`, and `current`
+  **Then** the first line reads "Step {currentStep} of {totalSteps}: {current}",
+  with the generated prefix in `--ui-stepper-breakpoint-default-label-color` and
+  the step's name in `--ui-stepper-breakpoint-default-value-color`.
+- **Given** a `next` step name
+  **Then** a second line reads "Next: {next}", with the same two-tone treatment.
+- **Given** no `next`
+  **Then** the second line is **not rendered at all** — no empty paragraph, no
+  dangling "Next:". This is how the last step in a sequence renders.
+- **Given** `stepLabel`, `ofLabel`, `nextLabel`, or `separatorLabel`
+  **Then** the corresponding generated string is replaced. The component ships
+  English defaults and no other copy of its own, so a localized application
+  overrides exactly these four. `separatorLabel` (default `": "`) is the
+  punctuation joining the counter to the step name — a prop rather than an inlined
+  literal because not every locale writes it that way.
+
+### The wide row
+
+- **Given** `children`
+  **Then** they are laid out in a flex row, start-aligned, wrapping onto further
+  lines when the sequence is too wide. Each wrapped line packs to the start
+  (left in LTR) rather than centering independently, so a lone trailing item on
+  the last line stays visually connected to the row above it instead of
+  floating under the container's midpoint.
+- **Given** more steps than fit
+  **Then** the row wraps rather than scrolling or truncating; below the
+  breakpoint the summary takes over instead.
+
+### Not owned here
+
+- The steps themselves — their number, order, labels, markers, and which one is
+  `current` are the application's, passed as `StepperItem` children.
+- Navigation: the component has no events. A completed step becomes clickable by
+  composing that `StepperItem` with its own `render` prop.
+- Keeping `currentStep` / `current` / `next` consistent with the children. The
+  compact summary and the wide row are two renderings of the same state, but the
+  component cannot inspect its children to derive one from the other — the
+  caller supplies both.
+
+## Accessibility
+
+- **Only one layout is ever announced.** Both subtrees are in the DOM at all
+  times, but the inactive one is `display: none`, which removes it from the
+  accessibility tree. A screen-reader user below 1024px hears the text summary;
+  above it, the step items. Nothing is duplicated. Do not "fix" this with
+  `aria-hidden` — which layout is live is a CSS decision the component cannot
+  observe, so any JS-set flag would be wrong half the time.
+- **The compact summary is the accessible progress statement.** "Step 3 of 5:
+  Choose a plan" is plain text in a `<p>`, so it is read verbatim, in order,
+  with no ARIA required. That is deliberately the same sentence a sighted user
+  reads.
+- **The wide row is not itself a list.** The root is a plain `<div>` with no
+  `role`. If the sequence should announce as an ordered list, or the current
+  step as `aria-current="step"`, the application composes that on the
+  `StepperItem` children — which are polymorphic via their own `render` prop.
+- **No tab stops of its own.** The root and both layouts are non-interactive.
+  Focusability comes only from whatever a `StepperItem` child is rendered as.
+- **Ships four English strings** — `stepLabel`, `ofLabel`, `nextLabel`,
+  `separatorLabel` — and nothing else. They are props, so a localized application replaces them; the
+  step names themselves are always consumer-supplied.
+- **RTL**: the summary is a plain block flow and the row uses logical flex
+  layout with a gap, so both mirror under `dir="rtl"` with no extra work and no
+  physical directional utility to correct.
+
+## Contrast
+
+The generated prefix uses `--ui-stepper-breakpoint-default-label-color` and the
+step names use `--ui-stepper-breakpoint-default-value-color` (see
+`tokens.yaml`) — both Stepper-owned tokens as of the 2026-08-24 tier sync.
+Contrast has been verified against the tier's resolved values in light and
+dark; the label-color/prefix pairing is the one to re-check first if a brand
+later defines a distinct value for it, as it is the lowest-contrast text the
+component renders.

package/dist/llms/switch.md

@@ -0,0 +1,140 @@
+# Switch
+
+> A binary on/off toggle. Wraps the Base UI Switch primitive; the change takes effect immediately (no separate submit).
+
+**Status:** ready · **Category:** forms · **Since:** v0.4.0
+
+## Import
+
+```tsx
+import { Switch } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Switch
+  aria-label="Wireless"
+  checked={enabled}
+  onCheckedChange={setEnabled}
+/>
+```
+
+A binary on/off toggle whose change takes effect immediately.
+
+## When to use
+
+- Toggling a single setting that applies instantly (e.g. "Enable notifications").
+
+## When not to use
+
+- A choice that only applies after submitting a form — use a checkbox.
+- Selecting one of several options — use radios or a segmented control.
+
+## Example (React — implemented)
+
+```tsx
+import { Switch } from '@acronis-platform/ui-react';
+
+const [enabled, setEnabled] = useState(false);
+
+{
+  /* Bare toggle — name it with aria-label */
+}
+<Switch aria-label="Wireless" checked={enabled} onCheckedChange={setEnabled} />;
+
+{
+  /* With a label — the whole row toggles */
+}
+<Switch
+  label="Enable notifications"
+  checked={enabled}
+  onCheckedChange={setEnabled}
+/>;
+```
+
+Pass `label` to compose the full field (the row becomes clickable and the toggle
+is named via aria-labelledby); omit it for a bare toggle named with `aria-label`.
+Vue and Web Component implementations are planned against the same contract.
+
+## Parts
+
+| Part        | Element  | Notes                                                   |
+| ----------- | -------- | ------------------------------------------------------- |
+| `root`      | `button` | The track (role `switch`); fill per off/on state        |
+| `thumb`     | `span`   | The sliding knob                                        |
+| `container` | `label`  | Wraps toggle + label, forwards clicks (only with label) |
+| `label`     | `span`   | Label text, names the control                           |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `checked` | `boolean` | — | no | Controlled checked state. Pair with the change event. |
+| `default-checked` | `boolean` | `false` | no | Initial checked state when uncontrolled. |
+| `disabled` | `boolean` | `false` | no | Disables interaction. |
+| `required` | `boolean` | `false` | no | Marks the control as required in a form. |
+| `name` | `string` | — | no | Form field name submitted with the form. |
+| `value` | `string` | — | no | Form field value when checked. |
+| `label` | `ReactNode` | — | no | Optional label rendered beside the toggle. When provided, the whole row becomes a clickable `<label>` and the toggle is named via aria-labelledby. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `checked-change` | `boolean` | Fired when the checked state changes (React: `onCheckedChange`). Payload is the new checked value. |
+
+## Behavior
+
+### Toggling
+
+#### Toggles on activation
+
+**Given** an enabled Switch
+**When** the user clicks it or presses Space/Enter while focused
+**Then** the checked state flips
+**And** a `checked-change` event fires with the new boolean value
+**And** the thumb slides to the new position.
+
+### Controlled vs uncontrolled
+
+#### Uncontrolled
+
+**Given** a Switch with `default-checked` and no `checked`
+**When** it renders
+**Then** it manages its own state, starting from `default-checked`.
+
+#### Controlled
+
+**Given** a Switch with `checked`
+**When** the user toggles it
+**Then** it emits `checked-change` but does not change visually until the owner
+updates `checked`.
+
+### Disabled
+
+**Given** a Switch with `disabled`
+**When** the user attempts to toggle it
+**Then** the state does not change and no event fires.
+
+### Known gap
+
+The current React implementation renders correctly but is **not yet wired to the
+`--ui-switch-*` tokens** (see `tokens.yaml`). It uses the shared semantic bridge
+and `opacity-50` for disabled. This spec is the target contract; aligning the
+implementation is tracked follow-up.
+
+## Accessibility
+
+- **Role:** `switch` (Base UI Switch.Root), with `aria-checked` reflecting the
+  on/off state.
+- **Accessible name:** associate a visible label (e.g. wrap with a `<label>` or
+  use `aria-labelledby`); when there is no visible label, provide `aria-label`.
+- **Keyboard:** Space (and Enter) toggle the switch while focused; Tab moves
+  focus. A `disabled` switch is not focusable.
+- **Focus visible:** 2px `--ui-focus-brand` ring with 2px offset via
+  `:focus-visible`.
+- **State, not color alone:** the on/off state is exposed via `aria-checked` and
+  the thumb position, not color alone.
+- **WCAG:** 2.1.1 (keyboard), 2.4.7 (focus visible), 4.1.2 (name/role/value),
+  1.4.11 (non-text contrast).