@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/spinner.md

@@ -0,0 +1,100 @@
+# Spinner
+
+> An indeterminate loading indicator — a spinning ring in four sizes. Ported from the legacy shadcn-uikit `Spinner`; a CSS spinner (no primitive), colored by the shared brand token via currentColor. As of 0.58.0, deliberately NOT exported from `@acronis-platform/ui-react`'s public entry point — it is an internal primitive consumed by `Loading` (icon) and `Toast` (a small inline icon). Apps building a standalone loading state should use `Loading` instead.
+
+**Status:** deprecated · **Category:** feedback · **Since:** v0.15.0
+
+## Import
+
+```tsx
+Not exported from '@acronis-platform/ui-react' — internal only, used by `Loading`/`Toast`.
+```
+
+## Quick example
+
+```tsx
+// Internal usage only (packages/ui-react/src/components/ui/loading/loading.tsx,
+// .../toast/toast.tsx) — not importable by app code:
+<Spinner size="lg" className="text-muted-foreground" />
+```
+
+An indeterminate loading indicator — a spinning ring in four sizes.
+
+> **Status: deprecated (internal only).** As of 0.58.0, `Spinner` is
+> deliberately **not** exported from `@acronis-platform/ui-react`'s public
+> entry point — it's an internal primitive consumed by `Loading` (its icon)
+> and `Toast` (a small inline icon). Building a standalone loading state? Use
+> [`Loading`](../loading/README.md) instead; it wraps this same ring with a
+> label and placement-context container tokens. Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `Spinner`. No `--ui-spinner-*` tier; the
+> ring defaults to the brand blue (`text-secondary`) and is overridable via a
+> `text-*` class.
+
+## When to use
+
+- Nowhere directly — it's not part of the public component set. Compose it
+  only from inside another `ui-react` component that needs an icon-scale
+  spinning glyph (see `Loading`, `Toast`).
+
+## When not to use
+
+- For an app-facing standalone loading state — use `Loading`.
+- For determinate progress — use `Progress`.
+- For content placeholders — use a skeleton.
+
+## Example
+
+```tsx
+// Internal usage only — Spinner isn't exported for app code.
+import { Spinner } from '../spinner';
+
+<Spinner />
+<Spinner size="lg" />
+<Spinner size="sm" className="text-muted-foreground" />
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `size` | `'sm' | 'md' | 'lg' | 'xl'` | `'md'` | no | Diameter — sm 16 · md 24 · lg 32 · xl 48 (px). |
+
+## Behavior
+
+Spinner is an indeterminate loading indicator. It has no internal state and no
+interaction — it spins continuously while mounted.
+
+```gherkin
+Scenario: Sizing
+  Given a Spinner with size="lg"
+  Then it renders a 32px ring (sm 16 · md 24 · lg 32 · xl 48)
+```
+
+```gherkin
+Scenario: Color
+  Given a Spinner with no color override
+  Then the ring uses the brand blue (text-secondary via currentColor)
+  And a `text-*` className overrides it (e.g. text-muted-foreground on a busy surface)
+```
+
+```gherkin
+Scenario: Reduced motion
+  Given a user with prefers-reduced-motion
+  Then the platform animation honors that preference (the ring is still shown)
+```
+
+## Accessibility
+
+- The root is `role="status"` with `aria-label="Loading"` and an `sr-only`
+  "Loading…" label, so assistive tech announces the loading state when the
+  spinner appears.
+- `role="status"` is a polite live region — placing the spinner into the DOM
+  announces it without stealing focus. For a specific context, override the label
+  (e.g. `aria-label="Loading workloads"`).
+- The spinner is decorative motion; pair it with text when the wait is long.
+
+## Contrast
+
+The ring defaults to `--ui-background-brand-secondary` (brand blue), which meets
+non-text contrast against the page surface in light and dark. Override with a
+`text-*` class where the context needs it.

package/dist/llms/stack.md

@@ -0,0 +1,80 @@
+# Stack
+
+> A flexbox layout primitive — lay children out in a row or column with configurable gap, alignment, justification, and wrapping. Ported 1:1 from the legacy shadcn-uikit `stack`.
+
+**Status:** draft · **Category:** layout · **Since:** v0.51.0
+
+## Import
+
+```tsx
+import { Stack } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Stack direction="horizontal" gap="sm">{children}</Stack>
+```
+
+A flexbox layout primitive — arrange children in a row or column with a chosen
+gap, alignment, justification, and wrapping.
+
+> Design-pending v1, ported 1:1 from the legacy shadcn-uikit `stack`.
+
+## When to use
+
+- Quick one-dimensional layouts (toolbars, button rows, vertical form stacks)
+  without hand-writing flex utilities.
+
+## When not to use
+
+- Two-dimensional layouts — use `Grid`.
+
+## Parts
+
+`Stack` is a single component.
+
+## Example
+
+```tsx
+import { Stack } from '@acronis-platform/ui-react';
+
+<Stack direction="horizontal" gap="sm" align="center">
+  <Button>Save</Button>
+  <Button variant="ghost">Cancel</Button>
+</Stack>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `direction` | `'vertical' | 'horizontal'` | `'vertical'` | no | Main-axis direction (flex-col / flex-row). |
+| `gap` | `'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'` | `'md'` | no | Space between children. |
+| `align` | `'start' | 'center' | 'end' | 'stretch'` | `'stretch'` | no | Cross-axis alignment (align-items). |
+| `justify` | `'start' | 'center' | 'end' | 'between'` | `'start'` | no | Main-axis distribution (justify-content). |
+| `wrap` | `boolean` | `false` | no | Whether children wrap onto multiple lines. |
+
+## Behavior
+
+```gherkin
+Scenario: Arrange children
+  Given a Stack with direction / gap / align / justify
+  Then its children lay out as a flex row or column with that spacing and alignment
+```
+
+```gherkin
+Scenario: Wrap
+  Given wrap is set
+  Then children wrap onto multiple lines when they overflow
+```
+
+## Accessibility
+
+Stack is a presentational layout `<div>` with no semantics of its own. It does not
+change reading order — children are laid out in source order. Choose a semantic
+wrapper (e.g. `Section`, `<ul>`) where the content calls for one.
+
+## Contrast
+
+No color; nothing to evaluate.

package/dist/llms/stepper-item.md

@@ -0,0 +1,309 @@
+# StepperItem
+
+> One step in a stepper — a consumer-composed avatar marker followed by the step name. `variant` is the step's structural role in the sequence (`current`, `completed`, `future`) and drives the container background, border, and label color; `state` is the interaction look and only changes anything on a completed step. The component owns the container and the label only: the marker is supplied and styled entirely by the caller, and the row layout, the step sequence, its ordering, and navigation belong to `Stepper` and the application.
+
+**Status:** ready · **Category:** navigation · **Since:** v0.63.0
+
+## Import
+
+```tsx
+import { StepperItem } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<StepperItem
+  variant="completed"
+  label="Create an account"
+  avatar={<Avatar color="green"><CheckIcon size={16} /></Avatar>}
+  render={<button type="button" onClick={goToStep(1)} />}
+/>
+<StepperItem
+  variant="current"
+  label="Choose a plan"
+  avatar={<Avatar color="blue"><AvatarFallback>2</AvatarFallback></Avatar>}
+/>
+```
+
+One step in a stepper: a consumer-composed avatar marker followed by the step
+name. `variant` says where the step sits in the sequence (`current`,
+`completed`, `future`) and drives the container fill, border, and the label
+color; `state` is the interaction look, and it only changes anything on a
+completed step. Compose the steps inside `Stepper`, which lays them out.
+
+## When to use
+
+- A wizard / checkout / onboarding progress indicator, one `StepperItem` per step.
+- Any short, ordered sequence where the user needs to see what is done, where they
+  are, and what is still ahead — and can jump back to a completed step.
+
+## When not to use
+
+- To show progress as a single quantity — use `Progress` or `ProgressCircle`.
+- For a chronological log of things that already happened — use `Timeline`.
+- As the whole stepper — that is `Stepper`, which lays the steps out in a row and
+  adds the compact, narrow-viewport summary. Don't hand-roll that row. The
+  application still decides each step's `variant` and owns the navigation.
+
+## 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>
+    }
+    render={<button type="button" onClick={() => goToStep(1)} />}
+  />
+  <StepperItem
+    variant="current"
+    label="Choose a plan"
+    avatar={
+      <Avatar
+        color="blue"
+        className="[box-shadow:none] text-[var(--ui-stepper-item-current-label-color)]"
+      >
+        <AvatarFallback>2</AvatarFallback>
+      </Avatar>
+    }
+  />
+  <StepperItem
+    variant="future"
+    label="Confirm and pay"
+    avatar={
+      <Avatar
+        color="gray"
+        className="[box-shadow:none] text-[var(--ui-stepper-item-future-label-color)]"
+      >
+        <AvatarFallback>3</AvatarFallback>
+      </Avatar>
+    }
+  />
+</Stepper>
+```
+
+The marker is entirely yours: color scheme, initials vs. icon vs. image, size
+overrides. The step renders the element verbatim and never restyles it — with
+two caveats the caller applies via `className`, both shown above:
+
+- Figma recolors the digit inside a `current`/`future` avatar to that step's
+  own label-color token, overriding `Avatar`'s usual per-scheme color
+  (`completed`'s checkmark is a fixed icon, so it needs none).
+- `Avatar`'s 2px outset ring (`box-shadow`, meant to separate overlapping
+  avatars in an `AvatarGroup`) is switched off with `[box-shadow:none]` —
+  Figma's `StepperItem` avatars carry no stroke, and left on, the ring shows
+  as an unwanted halo on `current`'s blue fill and on `completed`'s
+  hover/active fills. See "Design status" below.
+
+Only six `variant` x `state` combinations exist in the design, and the
+component reproduces exactly that: `current` is always highlighted with a
+border, `future` is always disabled, and only `completed` reads `state`
+(`idle`, `hover`, `active`, `focus`).
+
+`current` is the only variant that paints a visible border, but every variant
+reserves the same border box (transparent on `completed` and `future`), so the
+three render at the same size and a row of steps stays aligned.
+
+## Parts
+
+| Part             | Element | Notes                                                                                                             |
+| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| container (root) | `div`   | Polymorphic via `render`; carries the fill, the focus ring, and a future step's `aria-disabled` / `tabindex="-1"` |
+| `avatar-slot`    | —       | Required; the caller's `Avatar`, rendered verbatim                                                                |
+| `label`          | `span`  | The step name; truncates                                                                                          |
+
+## Design status
+
+The Figma component has a dedicated `--ui-stepper-item-*` token tier as of the
+2026-08-24 sync — see `tokens.yaml` for the full list.
+
+**Resolved quirk — `Avatar`'s 2px ring on colored step backgrounds.**
+`Avatar` always paints a 2px `--ui-avatar-global-avatar-border-color` ring
+(white in light mode), meant to separate overlapping avatars in an
+`AvatarGroup`. Figma's own `StepperItem` composition never draws this ring
+(verified in the raw reference markup — none of the `current`/`completed`/
+`future` avatar instances carry a border/box-shadow class), so it's invisible
+where a step's container fill is transparent but becomes a visible halo on
+`current`'s blue background and on `completed`'s hover/active fills. This is a
+pre-existing `Avatar`-wide behavior (present anywhere an avatar sits on a
+colored surface, e.g. `Timeline`'s marker), not something `StepperItem`
+introduces or can fix by itself — `StepperItem` is documented to render the
+marker verbatim, so the caller switches the ring off with
+`className="[box-shadow:none]"` on the composed `Avatar`, as shown in Usage
+above (the same pattern `Timeline`'s marker already used).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'current' | 'completed' | 'future'` | `current` | no | The step's structural role in the sequence. `current` is where the user is and always renders highlighted with a border; `completed` is already passed and is the only variant whose look responds to `state`; `future` is not reachable yet and always renders disabled and non-interactive. Defaults to `current` for prop ergonomics — in a real sequence every step declares its own. |
+| `state` | `'idle' | 'hover' | 'active' | 'focus'` | `idle` | no | The interaction look. Only observable when `variant` is `completed` (`idle`, `hover`, and `active` each paint their own fill token — `idle`'s resolves to `transparent` in the shipped brands, so it reads as no fill; `focus` draws a 3px ring — its token is byte-identical to `--ui-focus-primary`, i.e. the same look `focus-visible` already draws automatically on a composed control). Ignored for `current`, which is always highlighted, and for `future`, which is always disabled. It is a declarative prop, not a CSS pseudo-state, because the design models it as distinct token roles and a consumer may need to force it. |
+| `avatar` | `Element` | — | yes | The step's marker — an avatar element supplied and styled entirely by the caller (color scheme, initials / icon / image, size overrides). The step renders it verbatim and never restyles it. |
+| `label` | `ReactNode` | — | no | The step name. Truncates rather than wrapping. |
+| `render` | `RenderProp` | — | no | Base UI composition prop — replaces the rendered `<div>` with another element or component while merging props and classes. Use it to make a completed step a real `<button>` (or a router link) that jumps back. React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onClick` | `(event: MouseEvent) => void` | Fired on activation. Only meaningful once the step is rendered as a real control via `render` — the default `<div>` is not focusable, and a future step does not receive pointer events at all. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Optional trailing content rendered after the label (e.g. a status tag). The marker and the step name come from `avatar` and `label`, not children. |
+
+## Behavior
+
+### Renders a marker and a name
+
+- **Given** an `avatar`
+  **Then** it renders first inside the container, exactly as passed — the step
+  never sizes, tints, or recolors it.
+- **Given** a `label`
+  **Then** it renders after the marker and truncates rather than wrapping.
+- **Given** no `label`
+  **Then** only the marker renders; the container keeps its padding.
+- **Given** `children`
+  **Then** they render last, after the label.
+
+### Variant drives the step's role
+
+- **Given** `variant="current"`
+  **Then** the container is filled and bordered with the current-step tokens
+  and the name uses the current-step label color — regardless of `state`,
+  because the design draws the current step in exactly one look.
+- **Given** `variant="completed"`
+  **Then** the name uses the completed-step label color and the container takes
+  the fill token for its `state`.
+- **Given** `variant="future"`
+  **Then** the name uses the future-step label color, the container takes the
+  future-step container fill — `transparent` in every shipped brand, so nothing
+  paints today, but a brand that overrides it is honored — the element is marked
+  `aria-disabled`, it is removed from the tab order (`tabindex="-1"`), and it
+  receives no pointer events — again regardless of `state`. On the default
+  `<div>` it also carries `role="link"`, without which
+  `aria-disabled` would not be announced at all (see `accessibility.md`).
+- **Given** any `variant`
+  **Then** the container reserves the same border box, so all three variants
+  measure the same and a row of steps keeps its markers and names aligned. Only
+  `current` paints a visible border color; on `completed` and `future` the
+  reserved border is transparent.
+
+### State is only observable on a completed step
+
+- **Given** `variant="completed"` **and** `state="idle"`
+  **Then** the container is filled with the idle token, which resolves to
+  `transparent` in every shipped brand — so it reads as no fill today, but a
+  brand that overrides it is honored.
+- **Given** `variant="completed"` **and** `state="hover"`
+  **Then** the container is filled with the hover token.
+- **Given** `variant="completed"` **and** `state="active"`
+  **Then** the container is filled with the active token.
+- **Given** `variant="completed"` **and** `state="focus"`
+  **Then** the container shows a 3px ring in the focus-ring token — the same
+  look `focus-visible` already draws automatically on a composed control, since
+  the two share the identical color value.
+- **Given** any `state` **and** `variant` of `current` or `future`
+  **Then** nothing changes. `state` is not silently dropped from the contract: it
+  still appears as a data attribute, so a consumer can key off it.
+
+### RTL
+
+- **Given** `dir="rtl"`
+  **Then** the whole step mirrors: the marker/label order, the container padding,
+  and the gap are all logical, with no physical directional utility to correct.
+
+### Composition
+
+- **Given** a `render` prop
+  **Then** the rendered element is replaced (e.g. by a `<button>`) and the step's
+  props, classes, and data attributes merge onto it.
+- **Given** a `render` of a focusable control
+  **Then** focusing it by keyboard shows the library's 3px `--ui-focus-primary`
+  ring. The default `<div>` never focuses, so the ring never appears on it.
+- **Given** `variant="future"` **and** a `render` of a real control
+  **Then** the control still renders, but it is `aria-disabled`, inert to pointer
+  input, and removed from the tab order — so it cannot be tabbed to or activated
+  from the keyboard. It is **not** the native `disabled` attribute, so a
+  programmatic `.focus()` + `.click()` still works; the application should also
+  skip the step in its own navigation.
+
+### Not owned here
+
+- The row layout and the narrow-viewport summary — that is `Stepper`, which these
+  steps are meant to be composed inside.
+- The step sequence, its order, numbering, and which step is current — the
+  application decides and passes `variant` per step.
+- The marker's content and appearance — the caller composes the avatar.
+- Hover and press detection: `state` is declarative, so the consumer decides when
+  a step looks hovered, pressed, or focused (`Stepper` does not — it owns no
+  step state).
+
+## Accessibility
+
+- **Presentational by default.** The step renders a `<div>`: no role, no tab
+  stop. That is correct for the current and future steps, which are not actions.
+- **A completed step is usually a control** — compose it with `render` as a real
+  `<button>` (or a link, if it changes the URL). Doing so gives it keyboard focus,
+  Enter/Space activation, and a native accessible name for free. Never fake it
+  with a click handler on the default `<div>`.
+- **Keyboard focus is visible.** The step carries the library's standard 3px
+  `--ui-focus-primary` `focus-visible` ring (the same one `CardFilter` and
+  `BreadcrumbLink` use), so a step composed as a control is never focused
+  invisibly. The default `<div>` is not focusable, so the ring never shows there.
+- **The accessible name comes from the content you pass.** The step's name is the
+  `label`; the marker contributes whatever text the caller's avatar renders (a
+  number, initials). If the marker's digit would be noise, mark that avatar
+  `aria-hidden` in your own composition — the step cannot decide that for you.
+- **A future step is `aria-disabled`, not `disabled`.** It stays in the reading
+  order so a screen-reader user can see the whole sequence, but it announces as
+  unavailable. Three things make that true rather than aspirational:
+  - On the default rendering it also carries **`role="link"`**. `aria-disabled` on
+    an element with no widget role is not announced (ARIA 1.2), and the default
+    rendering is a plain `<div>` — so without a role the flag would be inert. This
+    is the same fix `BreadcrumbPage` applies to the non-navigable current page: a
+    destination that is in the sequence but cannot be gone to. The role is
+    **omitted** when the step is composed via `render`, because the element the
+    consumer supplies brings its own (more accurate) role.
+  - It is removed from the tab order (**`tabindex="-1"`**), so a step composed as
+    a real `<button>` cannot be tabbed to or activated with Enter/Space.
+  - It receives no pointer events, so it cannot be clicked.
+
+  What this does **not** give you is the native `disabled` guarantee: a
+  programmatic `.focus()` + `.click()` on a composed control still fires its
+  handler. Skip future steps in your own navigation logic too.
+
+- **Ships no strings.** Every piece of text is consumer-supplied (`label`, the
+  avatar's content), so there is nothing to localize inside the component and no
+  default English copy to override.
+- **`state` is not a live interaction state.** It is a declarative look, so a
+  step forced to `hover`, `active`, or `focus` conveys nothing to assistive
+  tech. Never use it as the only signal of the step a user is on — that is
+  `variant="current"`, and the application should also expose the position in
+  text ("Step 2 of 3").
+- **Sequence semantics belong to the container.** A single step is not a list. If
+  the whole stepper should announce as an ordered sequence, wrap the steps in an
+  `<ol>`/`<li>` (or a `role="list"`) at the application layer, and mark the
+  current step with `aria-current="step"` on the element you compose.
+- **RTL**: the marker, label, padding, and gap all use logical properties, so the
+  whole step mirrors under `dir="rtl"` with no extra work.
+
+## Contrast
+
+The step name uses the current/completed/future label-color tokens from the
+dedicated `--ui-stepper-item-*` tier (see `tokens.yaml`), each defined per brand
+and light/dark mode via `light-dark()`. Re-check contrast per brand when this
+tier changes, since a brand may define distinct values now that it is
+component-owned rather than borrowed from the semantic scale.