@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/tag.md

@@ -0,0 +1,139 @@
+# Tag
+
+> A compact label that represents, categorizes, or highlights a piece of information — a status, attribute, or keyword. Six status variants across two sizes, with an optional leading icon.
+
+**Status:** ready · **Category:** data-display · **Since:** v0.12.0
+
+## Import
+
+```tsx
+import { Tag } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Tag variant="success">Active</Tag>
+<Tag variant="info" size="sm">Beta</Tag>
+<Tag variant="warning" icon={<TriangleWarningIcon />}>Degraded</Tag>
+```
+
+A compact label for a status, attribute, or keyword.
+
+## When to use
+
+- Show metadata, a category, or a status on content or an object (e.g. "Active",
+  "Beta", "Critical").
+- Keep the content short and meaningful.
+
+## When not to use
+
+- As a button or link — a Tag is presentational and non-interactive. Use a
+  **Button** / link for actions.
+- For long text — the label truncates at 256px.
+
+## Variants
+
+`info` · `success` · `warning` · `critical` · `danger` · `neutral` · `ai` — each
+maps to the dedicated `--ui-tag-<variant>-*` tier (container fill / border /
+label / icon). `ai` paints a gradient border over a tinted fill. Two sizes:
+`default` (24px) and `sm` (20px).
+
+## Examples
+
+```tsx
+import { Tag } from '@acronis-platform/ui-react';
+import { TriangleWarningIcon } from '@acronis-platform/icons-react/stroke-mono';
+
+<Tag variant="success">Active</Tag>
+<Tag variant="info" size="sm">Beta</Tag>
+<Tag variant="warning" icon={<TriangleWarningIcon />}>Degraded</Tag>
+```
+
+## Parts
+
+| Part    | Element | Purpose                                     |
+| ------- | ------- | ------------------------------------------- |
+| root    | `span`  | The pill (background, border, radius).      |
+| `icon`  | `svg`   | Optional 16px leading icon (Default size).  |
+| `label` | text    | The content (children); truncates at 256px. |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'info' | 'success' | 'warning' | 'critical' | 'danger' | 'neutral' | 'ai'` | `neutral` | no | Status style. Each maps to the dedicated `--ui-tag-<variant>-*` tier (container fill / border / label / icon). `ai` paints a gradient border over a tinted fill. |
+| `size` | `'default' | 'sm'` | `default` | no | Height and padding — 24px (`default`) or 20px (`sm`). |
+| `icon` | `ReactNode` | — | no | Optional leading icon, rendered at 16px before the label. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The tag label (children). Truncates at the 256px max width. |
+
+## Behavior
+
+### Variant
+
+**Given** a Tag with `variant` set to one of `info`, `success`, `warning`,
+`critical`, `danger`, `neutral`, or `ai`
+**When** it renders
+**Then** its fill, border, label, and icon resolve from that variant's
+`--ui-tag-<variant>-container-color` / `-container-border-color` /
+`-label-color` / `-icon-color` tokens (the `ai` border color is a gradient)
+**And** with no `variant` it defaults to `neutral`.
+
+### Size
+
+**Given** `size` of `default` or `sm`
+**When** it renders
+**Then** the height/padding change accordingly — 24px (`default`) or 20px
+(`sm`); both are fully rounded (pill).
+
+### Icon
+
+**Given** an `icon`
+**When** it renders
+**Then** the icon shows at 16px before the label and inherits the variant's text
+color via `currentColor`.
+**Given** no `icon`
+**Then** only the label renders.
+
+### Label overflow
+
+**Given** a label longer than the 256px max width
+**When** it renders
+**Then** the tag caps at 256px and the label truncates with an ellipsis.
+
+### Non-interactive
+
+**Given** a Tag
+**When** the user hovers or clicks it
+**Then** nothing happens — a Tag is a presentational label, not a control (it
+emits no events and has no interaction states).
+
+## Accessibility
+
+## Semantics
+
+- A Tag is a presentational inline `<span>` — non-interactive, with no role. It
+  is read as its text content.
+- **Don't rely on color alone.** The variant color signals status, but the
+  label text must carry the meaning (e.g. "Critical", "Beta") so it's clear to
+  colorblind users and screen-reader users alike.
+- If the icon is the only thing conveying meaning (rare — the label should), give
+  it an accessible name; otherwise it is decorative and may stay `aria-hidden`.
+
+## Keyboard & focus
+
+- Not focusable and not in the tab order — there is nothing to activate.
+- If a future use needs an interactive/removable tag, that affordance (e.g. a
+  remove button) must be a real focusable control with its own accessible name;
+  the Tag itself stays presentational.
+
+## Contrast
+
+- Each variant's text-on-background pair resolves from the `--ui-*-status-*`
+  tokens, which meet contrast in both light and dark themes; the border further
+  separates the pill from the surface.

package/dist/llms/timeline.md

@@ -0,0 +1,361 @@
+# Timeline
+
+> A presentational, chronological tree of events — an activity feed, audit log, or status history. `Timeline` + `Timeline.Item` render a semantic ordered list in which each row pairs an Avatar marker with a Card carrying the title, an optional tag, the timestamp, and a description; rows join their parent through an elbow and their next sibling through a vertical connector. Nesting is flat and explicit — a row declares its own `level` (1-3) — and the root reads those levels to place the connectors and, under `variant="tree"`, to give every row with descendants a disclosure control. It owns structure, connector geometry and branch collapsing only: it never sorts, groups, fetches, or interprets events, holds no tree model of its own, and ships no domain event types or icons. Not a temporal chart.
+
+**Status:** stable · **Category:** data-display
+
+## Import
+
+```tsx
+import { Timeline } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Timeline>
+  <Timeline.Item
+    icon={<CircleInfoIcon />}
+    title="Retention policy applied"
+    tag={<Tag variant="warning">Warning</Tag>}
+    timestamp={<time dateTime="2026-12-22T08:30:00+01:00">Dec 22, 08:30 AM</time>}
+    description="Weekly archives pruned"
+  />
+  <Timeline.Item
+    level={2}
+    icon={<CircleCheckIcon />}
+    color="green"
+    title="Archive pruned"
+    timestamp="Dec 22, 08:31 AM"
+  />
+</Timeline>
+```
+
+A presentational, chronological tree of events — an activity feed, audit log, or
+status history. `Timeline` + `Timeline.Item` render a semantic `<ol>` in which
+each row pairs an Avatar marker with a Card carrying the title, an optional tag,
+the timestamp, and a description. Rows join their parent through an elbow and
+their next sibling through a vertical connector.
+
+## When to use
+
+- Customer-health contributing events, audit logs, activity feeds, order/status
+  history, deployment/CI history.
+- Hierarchical event trails, where a top-level event expands into the steps that
+  produced it (up to three levels).
+
+## When not to use
+
+- To plot a metric over time — use a Line / Area / Composed chart / ConfidenceCone.
+- As a full stepper/wizard — a dedicated Stepper is a different component.
+- As a real tree widget — nesting here is visual only, and is not exposed to
+  assistive tech.
+- To sort, group, paginate, or virtualize — the app does that and passes ordered
+  rows. (Branch collapsing _is_ owned here: `variant="tree"` derives it from the
+  levels. Pass `expanded` if you want to own it instead.)
+
+## Usage
+
+```tsx
+<Timeline>
+  <Timeline.Item
+    icon={<CircleInfoIcon />}
+    title="Retention policy applied"
+    tag={<Tag variant="warning">Warning</Tag>}
+    timestamp={
+      <time dateTime="2026-12-22T08:30:00+01:00">Dec 22, 08:30 AM</time>
+    }
+    description="Weekly archives pruned"
+  />
+  <Timeline.Item
+    level={2}
+    icon={<CircleCheckIcon />}
+    color="green"
+    title="Archive pruned"
+    timestamp="Dec 22, 08:31 AM"
+    description="14 recovery points removed"
+  />
+</Timeline>
+```
+
+Collapsing is the variant, not a per-row flag — there is no `collapsible` prop.
+`variant="default"` never collapses; `variant="tree"` gives every row that has
+descendants a button ahead of its marker that drops the rows beneath it, with no
+wiring needed:
+
+```tsx
+<Timeline variant="tree">
+  <Timeline.Item title="Retention policy applied" />
+  <Timeline.Item level={2} title="Archive pruned" />
+  <Timeline.Item level={2} title="Index rebuilt" />
+  <Timeline.Item title="Next root event" />
+</Timeline>
+```
+
+Pass `expanded` + `onExpandedChange` to own the state instead, and
+`defaultExpanded={false}` to start collapsed. Items must be **direct** children —
+a fragment hides their `level` from the root.
+
+Separately, `collapsibleBody` gives a row's _card_ a chevron in its header that
+folds that card's body. It is orthogonal to `variant` — same behaviour in both, and
+a tree row can carry the branch button and the card chevron at once:
+
+```tsx
+<Timeline.Item collapsibleBody title="Nightly protection plan failed">
+  <BodySection />
+</Timeline.Item>
+```
+
+## Parts
+
+| Part                                          | Notes                                                              |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| `item`                                        | One `<li>` — marker column, card, connector geometry.              |
+| `toggle`                                      | Branch disclosure `ButtonIcon`; `tree` rows with descendants only. |
+| `body-toggle`                                 | Card-body chevron in the header; `collapsibleBody` rows only.      |
+| `marker`                                      | The `Avatar` holding `icon` or `initials`, tinted by `color`.      |
+| `connector`                                   | Vertical line to the next row. Derived — never dangles.            |
+| `elbow`                                       | Right angle joining a branch's first row to its parent. Derived.   |
+| `card`                                        | The bordered `Card` holding the row's content.                     |
+| `title` / `tag` / `timestamp` / `description` | The card header content.                                           |
+| `body`                                        | The item's `children`, below a divider. Hidden while collapsed.    |
+
+## Notes
+
+- `level` (1-3) drives the indent and the connector geometry: a row deeper than the
+  one above it opens a branch and draws the elbow (Figma's `Nesting` `-First`).
+  `branchStart` overrides that, and is ignored at level 1.
+- Connectors are derived from the same level sequence, so a branch's last row, the
+  list's last row, and a just-collapsed row never leave a dangling line — and a
+  level jump always draws both halves of the join. `connector` / `branchStart`
+  exist only to override that.
+- The indent step is the marker column plus the gap, so `variant="tree"` indents
+  further per level than `default` — every level still aligns.
+- `toggleLabel` and `bodyToggleLabel` default to distinct English strings — a tree
+  row can carry both controls, so a shared name would be ambiguous. Pass localized
+  values, and keep them distinct.
+- The marker takes an `icon` or `initials` (icon wins). Avatar's outset ring is
+  switched off here, matching the design's strokeless marker.
+- The Figma variables `components/Timeline/{connectorColor,gap}` ship as the
+  `--ui-timeline-*` tier and are consumed directly. `Timeline/gap` covers the
+  horizontal marker-to-card gap and the indent step derived from it; the
+  vertical rhythm between rows is unbound in the design and stays on
+  `--ui-gap-16`.
+- Composes `Avatar` (marker), `Card` (container), and `ButtonIcon` (disclosure);
+  compose `Tag` into `tag` and anything you like into `children`. The kit ships no
+  domain event types or icons.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'default' | 'tree'` | `default` | no | Whether the list collapses. `default` never does. `tree` gives every row that has descendants a disclosure button ahead of its marker, which hides those descendants, and widens the indent step to reserve the button on every row. Given via context. |
+| `title` | `ReactNode` | — | yes | (Timeline.Item) The event title — the primary line in the card header. |
+| `timestamp` | `ReactNode` | — | no | (Timeline.Item) Event time — pass a `<time dateTime>` for an accessible stamp. |
+| `tag` | `ReactNode` | — | no | (Timeline.Item) Slot beside the title, before the timestamp — e.g. a Tag. |
+| `description` | `ReactNode` | — | no | (Timeline.Item) Optional secondary description under the title. |
+| `icon` | `ReactNode` | — | no | (Timeline.Item) Icon rendered inside the marker Avatar. Takes precedence over `initials`. |
+| `initials` | `string` | — | no | (Timeline.Item) Initials rendered inside the marker Avatar when no `icon` is given. |
+| `color` | `'blue' | 'gray' | 'green' | 'teal' | 'violet' | 'red' | 'yellow' | 'orange'` | `blue` | no | (Timeline.Item) Marker Avatar color scheme. |
+| `level` | `1 | 2 | 3` | `1` | no | (Timeline.Item) Nesting depth — drives the indent, and (as a sequence across rows) the connector and elbow the root derives. |
+| `branchStart` | `boolean` | — | no | (Timeline.Item) Force the elbow joining this row to its parent's connector on or off. Leave it unset — the root derives it from the levels, drawing it whenever this row is deeper than the one above it. Ignored at `level` 1, which has no parent. |
+| `connector` | `boolean` | — | no | (Timeline.Item) Force the descending connector on or off. Leave it unset — the root derives it from the levels, drawing it only when the next visible row is at this row's depth or deeper. |
+| `expanded` | `boolean` | — | no | (Timeline.Item) Branch disclosure state (controlled). Only meaningful under `variant="tree"` on a row that has descendants. |
+| `defaultExpanded` | `boolean` | `true` | no | (Timeline.Item) Initial branch disclosure state when uncontrolled. |
+| `toggleLabel` | `string` | `Toggle nested events` | no | (Timeline.Item) Accessible name for the branch disclosure control — the one that drops this row's descendant rows. Distinct from `bodyToggleLabel` by default, because a tree row can carry both controls at once. |
+| `collapsibleBody` | `boolean` | `false` | no | (Timeline.Item) Give this row's card a chevron at the trailing edge of its header that folds the card's own body. Orthogonal to `variant` — it is the card's control, not the timeline's, so it works the same in `default` and `tree`, and a tree row can carry both. |
+| `bodyExpanded` | `boolean` | — | no | (Timeline.Item) Card-body disclosure state (controlled). |
+| `defaultBodyExpanded` | `boolean` | `true` | no | (Timeline.Item) Initial card-body disclosure state when uncontrolled. |
+| `bodyToggleLabel` | `string` | `Toggle event details` | no | (Timeline.Item) Accessible name for the card-body disclosure control — the one that folds this row's own body. Distinct from `toggleLabel` by default. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onExpandedChange` | `(expanded: boolean) => void` | (Timeline.Item) Fired with the requested branch disclosure state whenever the control is activated. Uncontrolled, the root also collapses the branch; pass `expanded` to own the state instead. |
+| `onBodyExpandedChange` | `(expanded: boolean) => void` | (Timeline.Item) Fired with the requested card-body disclosure state whenever the card's own chevron is activated. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | `Timeline` takes `Timeline.Item`s as direct children, in visual order — never wrapped in a fragment, or their levels cannot be read. Each `Timeline.Item` takes optional card-body content as its children, rendered below a divider. Collapsing a *branch* never hides it; only that row's own `collapsibleBody` chevron does. |
+
+## Behavior
+
+### Renders a semantic event list
+
+- **Given** `Timeline.Item`s
+  **Then** they render as `<li>`s inside an `<ol>`, top to bottom, in the order
+  they were passed; each row pairs an Avatar marker with a Card.
+- **Given** the last row
+  **Then** its trailing connector is hidden — nothing follows it.
+
+### Item content
+
+- **Given** `title`
+  **Then** it renders as the primary line of the card header.
+- **Given** `tag` / `timestamp`
+  **Then** they follow the title on the same row, tag first.
+- **Given** `description`
+  **Then** it renders under the title.
+- **Given** `children`
+  **Then** they render in the card below a 1px divider, in a region with vertical
+  padding only — horizontal padding belongs to the section the consumer supplies,
+  matching Figma's `Card > Body`. Collapsing a _branch_ never hides them; only this
+  row's own `collapsibleBody` chevron does.
+
+### Nesting is flat
+
+- `level` is `1 | 2 | 3` and drives the row's indent. The component never derives
+  depth from JSX nesting: the flat level sequence _is_ the tree, so a consumer
+  renders one row per entry and declares its level, and the root derives the
+  connector geometry from that sequence. Rows must be **direct** children of
+  `Timeline`, never wrapped in a fragment, or their levels cannot be read.
+- **Given** `level` greater than 1 **and** a shallower row above it
+  **Then** the row opens a branch, and an elbow joins it to that row's connector.
+  No second declaration is needed — the level jump already says it.
+- **Given** `level` greater than 1 **and** a row above it at the same level
+  **Then** the row continues the branch and draws no elbow.
+- **Given** an explicit `branchStart`
+  **Then** it overrides that derivation, in both directions.
+- **Given** `level` of 1 **and** `branchStart`
+  **Then** `branchStart` is ignored — there is no parent to join.
+- The indent step is the marker column plus the gap, so `variant="tree"` (which
+  reserves a disclosure button on every level) indents further per level than
+  `default` does.
+
+### Connector
+
+- **Given** the next visible row is at this row's level or deeper
+  **and** that row's marker sits in the same column
+  **Then** a vertical line descends from the marker into the row gap, meeting that
+  row's marker or elbow.
+- **Given** the next visible row is shallower, or there is none
+  **Then** no line is drawn — it would dangle in the margin. This covers the last
+  row of a branch, the last row of the list, and a row whose descendants were just
+  collapsed away.
+- **Given** the next visible row is a `tree` sibling whose marker sits in a
+  different column — one of the two has descendants and so reserves a disclosure
+  button, the other does not
+  **Then** no line is drawn either: a straight line between them is impossible, so
+  the kit omits it rather than drawing a crooked one. This is only reachable once a
+  row has been collapsed, since an expanded row with descendants is always followed
+  by one of them.
+- **Given** the next visible row is deeper **and** an explicit `branchStart={false}`
+  refuses its elbow
+  **Then** no line is drawn: the connector and the elbow are two halves of one
+  join, resolved together, so neither is ever drawn without the other.
+- **Given** an explicit `connector`
+  **Then** it overrides that derivation.
+- A row's connector tracks **its own** marker. A row that has descendants always
+  carries the disclosure button, so its connector starts from the same column the
+  elbow of its first child is drawn against — which is why an elbow always meets
+  its parent's line.
+
+### Disclosure and collapsing
+
+Collapsing is the **variant**, not a per-row opt-in. There is no `collapsible`
+property: a `tree` branch nobody can collapse would be indistinguishable from
+`default` with a wider indent.
+
+- **Given** `variant="default"`
+  **Then** nothing collapses and no disclosure control is rendered.
+- **Given** `variant="tree"` **and** a row that has descendants — the row authored
+  after it is deeper
+  **Then** that row gets a disclosure control ahead of its marker. Its chevron
+  points down when expanded and toward the inline end when collapsed.
+- **Given** `variant="tree"` **and** a row with no descendants
+  **Then** it gets no control, and its marker sits at the start of the indent step
+  rather than after the reserved button.
+- **Given** a collapsed row
+  **Then** the root drops every following row whose `level` is greater than the
+  collapsed row's, until the level rises back to it, and drops that row's
+  now-dangling connector. No consumer wiring is needed.
+- **Given** a collapsed row
+  **Then** it keeps its own control — "has descendants" is read from the authored
+  children, not the visible ones, so the branch can always be expanded again.
+- **Given** a collapsed row followed by a sibling at its own level
+  **Then** that sibling is unaffected.
+- **Given** the control is activated
+  **Then** `onExpandedChange` fires with the requested state. Uncontrolled, the
+  root also updates its own state; with `expanded` set, the consumer owns it and
+  the branch does not change on its own.
+- Branches default to **expanded**; pass `defaultExpanded={false}` to start
+  collapsed.
+
+### The card's own body disclosure
+
+A second, **orthogonal** control. `collapsibleBody` is not a variant and not tied
+to one: it is the card's chevron, so it behaves identically under `default` and
+`tree`, and a tree row that has descendants can carry both at once. (It lives on
+`Timeline.Item` only until `Card` grows the behaviour itself.)
+
+- **Given** `collapsibleBody`
+  **Then** a chevron renders at the trailing edge of the card header (Figma's
+  `Action Button`), and activating it shows or hides this row's `children`.
+- **Given** `collapsibleBody` **and** a `tree` row that has descendants
+  **Then** the row carries two controls: the branch button ahead of the marker
+  drops the rows below, the header chevron folds this card's body. Neither affects
+  the other, and their default accessible names differ so the two are
+  distinguishable to assistive tech without any override.
+- **Given** the header chevron is activated
+  **Then** `onBodyExpandedChange` fires with the requested state. Uncontrolled, the
+  row updates its own state; with `bodyExpanded` set, the consumer owns it.
+- Card bodies default to **shown**; pass `defaultBodyExpanded={false}` to start
+  folded.
+- **Given** no `collapsibleBody`
+  **Then** no chevron renders and the body is always shown.
+
+### What it does not do
+
+- It never sorts, groups, fetches, or de-duplicates events, and never decides an
+  event's icon, color, or timestamp format — the caller passes ordered rows with
+  resolved values.
+- It derives a collapsed row's descendants from the flat `level` sequence alone —
+  it holds no tree model, and cannot express a row whose depth jumps by more than
+  one level at a time.
+- It is not a temporal chart — use a Line / Area / Composed chart for trends.
+
+## Accessibility
+
+- **Semantic sequence**: rendered as an `<ol>` of `<li>`s, so assistive tech
+  announces an ordered list of events.
+- **Markers and connectors are decorative** (`aria-hidden`) — the meaning is in
+  the title / description / timestamp text, never in the marker color alone. The
+  marker Avatar carries the icon for visual scanning only.
+- **Nesting is visual, not structural**: because rows are a flat list with an
+  indent, depth is **not** conveyed to assistive tech. If hierarchy is meaningful
+  to the user, put it in the text (or use a real tree widget instead).
+- **Timestamps**: pass a `<time dateTime="…">` so the time is machine-readable
+  and clearly announced; the kit does not format or localize dates.
+- **Marker color is not information**: `color` only tints the marker; the event's
+  meaning must be carried by its text (and, if needed, a `Tag`).
+- **Disclosure control**: a real `<button>` with `aria-expanded` reflecting the
+  current state. Its accessible name comes from `toggleLabel`, which defaults to
+  an English string — pass a localized value. It is keyboard-reachable and
+  activates with Enter/Space; focus is visible via ButtonIcon's focus ring.
+- **Two controls on one row**: a `tree` row with descendants and `collapsibleBody`
+  renders both buttons inside the same `<li>`, performing different actions. Their
+  defaults (`toggleLabel` "Toggle nested events", `bodyToggleLabel` "Toggle event
+  details") name their own action, so the pair is never ambiguous out of the box —
+  keep them distinct when you localize.
+- **Collapsing removes rows from the DOM**, so assistive tech sees the same list a
+  sighted user does. It does not set `aria-controls`: the collapsed rows are
+  siblings of the control's own `<li>`, not a single wrapping region, so there is
+  no one element to point at.
+- **Marker content**: `icon` and `initials` both sit inside the decorative marker,
+  so neither is announced. Never put information there that isn't also in the text.
+- **Actions and links**: compose real `Link`/`Button`s in the card body, each with
+  its own accessible name; do not nest multiple interactive elements inside one
+  another, and don't make the whole row a single clickable target unless it's a
+  proper link.
+- Dynamically-added rows are not announced via `aria-live` unless the consumer
+  wraps them.
+
+## Contrast
+
+Title uses the primary surface-text token; timestamp and description use the
+secondary (muted) token; the connector and elbow use the shared border token; the
+marker and disclosure button inherit Avatar's and ButtonIcon's own token tiers —
+all meeting contrast in light and dark.