@acronis-platform/ui-react 5.0.0 → 5.1.0

package/dist/llms/tree-item.md

@@ -0,0 +1,359 @@
+# TreeItem
+
+> One flat row of a tree or nested-list UI — an optional expand chevron, an optional checkbox, an optional leading icon, the row title, and an optional trailing extras slot. It is a single row and nothing more: it renders no nested list and implements no expand/collapse, so `isExpandable` and `expanded` are purely visual affordances and `selected` is a prop the consumer drives. The tree itself — its ARIA roles, indentation, expand state, selection, and keyboard roving — belongs to the composition, the same way `Breadcrumb` ships the trail's primitives without owning the trail.
+
+**Status:** ready · **Category:** navigation · **Since:** v5.1.0
+
+## Import
+
+```tsx
+import { TreeItem } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ul role="tree" aria-label="Workloads">
+  <li role="treeitem" aria-expanded={open}>
+    <TreeItem
+      expanded={open}
+      hasIcon
+      icon={<FolderIcon size={16} />}
+      title="All workloads"
+      onClick={() => setOpen((v) => !v)}
+      onKeyDown={(event) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault();
+          setOpen((v) => !v);
+        }
+      }}
+    >
+      <Tag variant="info">24</Tag>
+    </TreeItem>
+    <ul role="group" className="ps-4">
+      <li role="treeitem" aria-selected>
+        <TreeItem
+          isExpandable={false}
+          hasIcon
+          selected
+          title="Cloud applications"
+        />
+      </li>
+    </ul>
+  </li>
+</ul>
+```
+
+One flat row of a tree or nested-list UI: an optional expand chevron, an optional
+checkbox, an optional leading icon, the row title, and an optional trailing
+extras slot. It is deliberately **one row** — it renders no nested list, owns no
+expand state, and selects nothing. You compose the rows, indent them, hold the
+open/selected state, and supply the ARIA tree semantics.
+
+## When to use
+
+- A file tree, a workload/resource hierarchy, a nested navigation panel — one
+  `TreeItem` per row.
+- A multi-select hierarchy: turn on `hasCheckbox` and drive the box through
+  `checkboxProps`.
+
+## When not to use
+
+- For a flat, non-hierarchical secondary nav — use
+  [`SidebarSecondary`](../sidebar-secondary/README.md).
+- For a path back to the current location — use
+  [`Breadcrumb`](../breadcrumb/README.md).
+- For collapsible **content** panels rather than a hierarchy of rows — use
+  `Accordion` / `AccordionContainer`.
+- As the whole tree. There is no `Tree` container component today; the row is the
+  primitive and the tree is assembled in the application.
+
+## Usage
+
+```tsx
+import { TreeItem } from '@acronis-platform/ui-react';
+
+const [open, setOpen] = React.useState(true);
+
+<ul role="tree" aria-label="Workloads">
+  <TreeItem
+    render={<li role="treeitem" aria-expanded={open} aria-level={1} />}
+    expanded={open}
+    hasIcon
+    icon={<FolderIcon size={16} />}
+    title="All workloads"
+    onClick={() => setOpen((v) => !v)}
+  >
+    <Tag variant="info">24</Tag>
+  </TreeItem>
+
+  {open && (
+    <ul role="group" className="ps-4">
+      <TreeItem
+        render={<li role="treeitem" aria-level={2} aria-selected />}
+        isExpandable={false}
+        hasIcon
+        selected
+        title="Cloud applications"
+      />
+      <TreeItem
+        render={<li role="treeitem" aria-level={2} />}
+        isExpandable={false}
+        hasIcon
+        title="Unmanaged workloads"
+      />
+    </ul>
+  )}
+</ul>;
+```
+
+Three things the row hands back to you on purpose:
+
+- **`isExpandable` and `expanded` are artwork, not behavior.** The first draws
+  the chevron, the second rotates it a quarter turn to point down. Neither
+  expands anything, and there is no change event: the Figma node's expandable
+  slot has no interaction either. Pass `expanded` from the same boolean that
+  feeds your `aria-expanded`, so the affordance and the announced state agree.
+- **`selected` is a look you drive.** The row never selects itself on click; it
+  only reflects the flag. Figma's `state=active` swatch paints the same fill,
+  which is why `active` is not wired to CSS `:active`.
+- **The ARIA tree is yours.** No `role="treeitem"`, no tab stop by default — see
+  [`accessibility.md`](./accessibility.md) for why a role on an orphan row would
+  make the tree invalid rather than accessible.
+
+## Parts
+
+| Part       | Element | Notes                                                                                             |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------- |
+| row (root) | `div`   | Polymorphic via `render`; carries the hover / `selected` fill and focus ring                      |
+| `expander` | `span`  | Optional (`isExpandable`, default on); `aria-hidden` chevron, flips in RTL, rotates on `expanded` |
+| `checkbox` | `span`  | Optional (`hasCheckbox`); the shared `Checkbox`, `aria-label` defaults to title                   |
+| `icon`     | `span`  | Optional (`hasIcon`); falls back to the design's square-dashed placeholder                        |
+| `title`    | `span`  | The row label; takes the remaining width and truncates                                            |
+| `extras`   | `span`  | Optional (`hasExtras`, default on); the trailing `children` slot                                  |
+
+## Design status
+
+**No dedicated token tier.** `tokens-pd` ships no `Tree` tier: the Figma node's
+variables still sit in the pre-next-gen `componentLegacy/tree/*` and
+`componentLegacy/sidebar/*` namespaces, which the `brand.components` migration
+has not reached. Every colour the row paints therefore comes from the semantic
+tier, and the layout numbers (8px gap/padding, 128px minimum row width, 4px slot
+inset, 16px minimum extras well) are plain utilities matching the design's pixel
+values — see [`tokens.yaml`](./tokens.yaml) for the full reasoning. Re-point both
+when a `--ui-tree-item-*` tier lands.
+
+**Deviation from the Figma frame — the extras well.** Figma measures the trailing
+slot as `min-w-[16px] w-[24px]`; the 24px is the resolved width of its
+placeholder content in a hug-content frame, not a constraint. The implementation
+keeps the 16px minimum and lets the slot grow, because a hard 24px would clip the
+action buttons and count badges the slot exists to hold.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `title` | `string` | `Title` | no | The row label. Truncates rather than wrapping. Note this shadows the native `title` tooltip attribute on the underlying element: the Figma component names the property `title`, and it is the row's visible label. |
+| `isExpandable` | `boolean` | `true` | no | Show the leading expand chevron. Purely a visual affordance — the row implements no expand/collapse and renders no nested list, and emits no change event. Set it false for a leaf row. |
+| `expanded` | `boolean` | `false` | no | Whether the row's nested list is currently expanded. Purely visual — like `isExpandable`, the row owns no expand/collapse state and renders no nested list. Rotates the leading chevron to reflect the state the consumer is already tracking (and should also be reflecting via `aria-expanded` on its own element, e.g. `<li role="treeitem" aria-expanded={open}>`). Has no effect when `isExpandable` is false. |
+| `hasCheckbox` | `boolean` | `false` | no | Show a leading checkbox, for a multi-select tree. |
+| `checkboxProps` | `CheckboxProps` | — | no | Props forwarded verbatim to the leading checkbox (`checked`, `onCheckedChange`, `indeterminate`, `aria-label`, …). The row keeps no checked state of its own, so the consumer controls the box exactly as it would a standalone `Checkbox`. `aria-label` defaults to `title`. |
+| `hasIcon` | `boolean` | `false` | no | Show the leading icon slot. |
+| `icon` | `ReactNode` | — | no | The leading icon. Only rendered when `hasIcon` is set; falls back to the design's square-dashed placeholder icon, which is what the Figma node draws. |
+| `hasExtras` | `boolean` | `true` | no | Render the trailing extras slot at all. When false, `children` are dropped entirely rather than merely hidden. |
+| `selected` | `boolean` | `false` | no | Whether the row is selected — the Figma `variant` axis. Paints the persistent highlighted background, the same fill the design's `state=active` swatch previews. Selection is the consumer's state to own; the row only reflects it. |
+| `render` | `RenderProp` | — | no | Base UI composition prop — replaces the rendered `<div>` while merging props and classes. This is how a real ARIA tree supplies the semantics the standalone row deliberately does not force (`<li role="treeitem" aria-expanded aria-level>`). React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onClick` | `(event: MouseEvent) => void` | Fired when the row is clicked. Expanding and selecting are the consumer's to implement — the row emits nothing of its own for either. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The trailing extras slot: action buttons, a count badge. Rendered only when `hasExtras` is true. |
+
+## Behavior
+
+### Renders one row
+
+- **Given** no props
+  **Then** the row renders the expand chevron (`isExpandable` defaults to true),
+  the default `title`, and an empty extras slot — exactly the Figma default.
+- **Given** a `title`
+  **Then** it renders in the row's remaining width and truncates rather than
+  wrapping or widening the row.
+- **Given** `hasIcon`
+  **Then** the leading icon slot renders, using `icon` if supplied and the
+  design's square-dashed placeholder otherwise.
+- **Given** an `icon` **but not** `hasIcon`
+  **Then** nothing renders — `hasIcon` is the gate, matching the Figma boolean.
+- **Given** `hasCheckbox`
+  **Then** the shared `Checkbox` renders before the icon, unlabelled, with its
+  `aria-label` defaulting to `title`.
+- **Given** `checkboxProps`
+  **Then** they are forwarded verbatim to that checkbox, including an
+  `aria-label` that overrides the `title` default. The row itself keeps no
+  checked state.
+- **Given** `isExpandable={false}`
+  **Then** the chevron is not rendered and the row reads as a leaf.
+- **Then** the slot order is always chevron, checkbox, icon, title, extras.
+
+### The extras slot is gated, not hidden
+
+- **Given** `children` **and** `hasExtras` (the default)
+  **Then** the trailing slot renders them, reserving a 16px minimum so an empty
+  slot still keeps a column of rows aligned.
+- **Given** `children` **and** `hasExtras={false}`
+  **Then** the slot and the children are removed from the DOM entirely — a
+  button in there is not merely invisible, it does not exist, so it cannot be
+  tabbed to.
+
+### Selection is a prop, not an interaction
+
+- **Given** `selected={false}` (the default)
+  **Then** the row background is transparent.
+- **Given** the pointer over the row
+  **Then** the background takes the hover token — regardless of `selected`,
+  since the design draws hover as its own swatch.
+- **Given** `selected`
+  **Then** the background takes the highlighted `--ui-background-surface-active`
+  fill persistently, and the row carries `data-selected` so a consumer can key
+  off it. This is the same fill the Figma `state=active` swatch previews.
+- **Given** a click
+  **Then** `onClick` fires and nothing else changes: the row does not select
+  itself. Selection belongs to the tree the consumer composes.
+
+### Expansion is reflected, not implemented
+
+- **Given** a click on the chevron
+  **Then** nothing expands. The chevron is `aria-hidden` artwork; the row renders
+  no nested list and emits no expand event, matching the Figma node, whose
+  expandable slot has no interaction either.
+- The consumer owns the expand state, renders the child level itself, and puts
+  `aria-expanded` on the element it supplies through `render`.
+- **Given** `expanded={false}` (the default)
+  **Then** the chevron points along the inline-end direction — the collapsed
+  affordance.
+- **Given** `expanded`
+  **Then** the chevron rotates a quarter turn to point down, so the affordance
+  agrees with the `aria-expanded` the consumer publishes. It is a reflection of
+  the consumer's state, not a state the row holds: nothing else about the row
+  changes, no nested list appears, and no event fires.
+- **Given** `expanded` **and** `isExpandable={false}`
+  **Then** it has no effect — there is no chevron to rotate.
+
+### Focus
+
+- **Given** the default rendering
+  **Then** the row is not in the tab order — it sets no `tabIndex` and no role.
+- **Given** a consumer-supplied `tabIndex` (or a composed focusable element)
+  **Then** keyboard focus paints the library's standard 3px `--ui-focus-primary`
+  ring, flush to the row's 2px radius. Mouse focus does not, because it is a
+  `:focus-visible` ring.
+
+### RTL
+
+- **Given** `dir="rtl"`
+  **Then** the whole row mirrors: the slot order, the gap, and the padding are
+  all logical, and the collapsed chevron artwork itself flips via an explicit
+  `rtl:rotate-180` — logical layout alone would leave it pointing the wrong way.
+- **Given** `dir="rtl"` **and** `expanded`
+  **Then** the chevron points down, the same as in LTR: "open" is a
+  direction-agnostic direction, so the expanded rotation replaces the RTL mirror
+  rather than compounding with it.
+
+### Composition
+
+- **Given** a `render` prop
+  **Then** the rendered element is replaced (e.g. by `<li role="treeitem">`) and
+  the row's props, classes, and data attributes merge onto it.
+- **Given** native `<div>` attributes (`onClick`, `tabIndex`, `aria-*`,
+  `className`)
+  **Then** they pass through, and `className` merges with the row's own classes.
+
+### Not owned here
+
+- The tree: its `role="tree"` owner, indentation, `aria-level`, keyboard roving,
+  and type-ahead. The consumer composes rows and supplies all of it.
+- Expand/collapse state and the nested list. The row only mirrors that state
+  visually, through `expanded`.
+- Selection state, single vs. multi-select, and the checkbox's checked value.
+
+## Accessibility
+
+- **No `role="treeitem"` is forced, on purpose.** A tree item is only valid
+  inside a `role="tree"` (or `role="group"`) owner, and to be announced usefully
+  it needs `aria-expanded`, `aria-level`, `aria-selected`, and a roving
+  `tabindex` — none of which a standalone row can know. Stamping the role on an
+  orphan row would produce an **invalid** tree, not an accessible one. The row is
+  a plain `<div>`, and `render` is how the consumer supplies the real semantics:
+
+  ```tsx
+  <ul role="tree" aria-label="Workloads">
+    <TreeItem render={<li role="treeitem" aria-expanded={open} aria-level={1} />} … />
+  </ul>
+  ```
+
+  This is the same boundary `Breadcrumb` draws — it ships `nav`/`ol`/`li` and the
+  current-page part, not the trail — and `StepperItem`, which documents that
+  sequence semantics belong to the container.
+
+- **Not in the tab order by default.** The row sets no `tabIndex`, so it never
+  becomes a silent tab stop inside a tree that manages focus itself. Pass
+  `tabIndex` (or compose a focusable element) when your tree wants the row
+  focusable; a roving `tabindex` — exactly one focusable row — is the pattern the
+  ARIA tree view calls for.
+
+- **Keyboard focus is visible.** The row carries the library's standard 3px
+  `--ui-focus-primary` `focus-visible` ring, the same one `Button` and
+  `BreadcrumbLink` use, so a focusable row is never focused invisibly.
+
+- **The chevron is `aria-hidden` decoration.** It is a visual affordance only:
+  the row implements no expand/collapse, so there is no state for it to announce.
+  Announce expansion with `aria-expanded` on the element you compose — that is
+  where the state actually lives. Do **not** give the chevron its own button
+  role; a row that only _looks_ expandable would then promise an action nothing
+  handles.
+
+- **Keep `expanded` and `aria-expanded` in step.** `expanded` rotates the chevron
+  but publishes nothing to assistive technology; `aria-expanded` on your `render`
+  element publishes the state but paints nothing. They are two renderings of the
+  one boolean you own, so drive both from it (`aria-expanded={open}` +
+  `expanded={open}`). Setting only one leaves the sighted affordance and the
+  announced state disagreeing — which is the bug `expanded` exists to close.
+
+- **The checkbox is always named.** Composed without a visible label, it would
+  otherwise be an unnamed control, so its `aria-label` defaults to `title`.
+  Override it through `checkboxProps` when the row title is not the right name
+  for the box (e.g. `aria-label="Select all workloads"`).
+
+- **Selection is announced by the consumer.** `selected` is a _visual_ fill.
+  Colour alone is not a status, so put `aria-selected` on the element you compose
+  via `render` (and `aria-current` if the row marks a location rather than a
+  selection). The row also exposes `data-selected` for styling and testing.
+
+- **One localizable string.** `title` is the only text the component renders on
+  its own, and the literal `'Title'` appears only as that prop's default —
+  callers pass a localized value. Everything else (`children`, `icon`,
+  `checkboxProps['aria-label']`) is consumer-supplied.
+
+- **RTL**: the slot order, gap, and padding are logical, so the row mirrors under
+  `dir="rtl"` on its own. The collapsed chevron is direction-sensitive
+  **artwork**, which logical properties cannot mirror, so it carries an explicit
+  `rtl:rotate-180`. The `expanded` chevron points down in both directions —
+  "open" has no inline direction to mirror.
+
+## Contrast
+
+The title uses `--ui-text-on-surface-primary` and the glyphs
+`--ui-glyph-on-surface-primary`, both over the row's transparent, hover, or
+`selected` background (`--ui-background-surface-hover` /
+`--ui-background-surface-active`). All are semantic-tier tokens defined per brand
+and light/dark mode via `light-dark()`. Re-check the title and glyph contrast
+against the **selected** fill specifically when a brand overrides either — the
+idle case sits on the page surface, the selected case does not. Should a
+dedicated `--ui-tree-item-*` tier land (see `tokens.yaml`), re-check all pairs.

package/dist/llms/treemap.md

@@ -28,13 +28,18 @@ it renders a themed recharts `Treemap` — cells sized by value, colored + label
 per name, with a tooltip — so you don't hand-compose recharts children.
 
 Cell colors come from the `palette` prop — a dataviz palette resolving to the
-`--ui-dataviz-*` tokens, `categorical` by default — not from `config`.
+`--ui-dataviz-*` tokens, `diverging` (blue-orange) by default — not from `config`.
 
-> **Design-pending v1.** Ported from the apps/demo `TreemapChartPlayground`.
-> On-cell labels still use `--ui-text-on-status-strong-neutral` — a generic
-> "text on a colored surface" color — over the palette's cell fills, so the
-> palette owes matched per-stop label colors. The chrome is reconciled with Figma
-> later; Code Connect is deferred.
+On-cell labels adapt their text color to three fill tones, decided structurally
+by the resolved token name suffix (not a runtime luminance check):
+
+- **dark** (diverging a3/b3, sequential 3–6, categorical, status): always white
+  text (`--ui-text-on-status-strong-neutral`).
+- **pale** (diverging a2/b2/a1/b1, sequential 1–2): theme-adaptive text via
+  `--ui-text-on-surface-primary` (dark in light, light in dark).
+- **inverts** (sequential 7–8, whose `light-dark()` values mirror across themes):
+  `--ui-text-on-status-strong-primary` — near-white in light (fill is dark),
+  near-black in dark (fill is pale).
 
 ## When to use
 
@@ -67,16 +72,10 @@ const data = [
 ];
 
 const config = {
-  React: { label: 'React', color: 'var(--ui-background-brand-secondary)' },
-  Vue: { label: 'Vue', color: 'var(--ui-background-status-strong-success)' },
-  Angular: {
-    label: 'Angular',
-    color: 'var(--ui-background-status-strong-danger)',
-  },
-  Svelte: {
-    label: 'Svelte',
-    color: 'var(--ui-background-status-strong-warning)',
-  },
+  React: { label: 'React' },
+  Vue: { label: 'Vue' },
+  Angular: { label: 'Angular' },
+  Svelte: { label: 'Svelte' },
 } satisfies ChartConfig;
 
 <Treemap
@@ -88,11 +87,9 @@ const config = {
 />;
 ```
 
-Cell colors reference existing semantic `--ui-*` tokens, keyed by each leaf's
-`nameKey` value. `--ui-background-status-strong-*` is chromatic in every brand;
-`--ui-background-brand-secondary` is brand-dependent (blue in `default`, neutral
-in some white-label brands), so it is not color-stable across brands until the
-real data-viz palette lands.
+Cell colors are assigned automatically from the active `palette` (diverging
+blue-orange by default). The `--ui-dataviz-*` tokens are `light-dark()` pairs,
+so light/dark and brand overrides come for free.
 
 ## Props
 
@@ -104,7 +101,7 @@ real data-viz palette lands.
 | `nameKey` | `string` | — | yes | The field that keys each leaf (drives the legend, tooltip, and `--color-<name>` lookup). Values should be unique and CSS-safe (they become part of a custom-property name) — the human name shown on the tile is the leaf's config label. |
 | `aspectRatio` | `number` | `1.3333` | no | Width-to-height ratio the tiling targets (default 4 / 3). |
 | `showLabels` | `boolean` | `true` | no | Render each leaf's label inside its cell (when it fits). |
-| `labelAlign` | `'bottom-start' | 'top-start' | 'center'` | `'bottom-start'` | no | Where a cell's label block sits — anchored at the tile's bottom start corner (the design's placement), at its top start corner, or centered in the tile. Named for the start edge, not a physical one: the corner variants mirror under dir="rtl". |
+| `labelAlign` | `'bottom-start' | 'top-start' | 'center'` | `'center'` | no | Where a cell's label block sits — centered in the tile (the Figma-canonical default), anchored at the tile's bottom start corner, or at its top start corner. Named for the start edge, not a physical one: the corner variants mirror under dir="rtl". |
 | `secondaryKeys` | `ReadonlyArray<string>` | — | no | Fields whose values make up a second label line under the leaf's name (e.g. a value and a count). Dropped on cells too short to hold it. |
 | `secondaryFormatter` | `(value: number | string, index?: number) => string` | — | no | Format each secondary value. Receives the field's index in secondaryKeys, so one formatter can cover fields of different kinds. |
 | `secondarySeparator` | `string` | `' · '` | no | Separator drawn between multiple secondary values. |
@@ -134,7 +131,7 @@ Scenario: Render cells from data and config
 ```gherkin
 Scenario: On-cell labels
   Given showLabels is true
-  Then each cell large enough shows its name at the tile's bottom start corner
+  Then each cell large enough shows its name centered in the tile (the default)
   And the name shown is the leaf's config label, falling back to its nameKey value
   But small cells omit the label to avoid overflow
   And when showLabels is false no labels render
@@ -143,19 +140,29 @@ Scenario: On-cell labels
 ```gherkin
 Scenario: Tiles are separated by the surface, not a stroke
   Given any data
-  Then each tile is inset inside its node's rectangle and its corners are rounded
+  Then each tile is inset inside its node's rectangle (sharp corners, no rounding)
   And the gap between neighbouring tiles is the chart's surface showing through
 ```
 
 ```gherkin
 Scenario: Label alignment
-  Given labelAlign is "top-start" or "center"
-  Then the label block is anchored at the tile's top start corner, or centered in it
+  Given labelAlign is "bottom-start" or "top-start"
+  Then the label block is anchored at the tile's bottom or top start corner
+  And the default ("center") centers the block in the tile
   And what the alignment aligns is the block, not its first line
   And a corner-anchored block hugs the tile's start edge, so it mirrors under dir="rtl"
   And every alignment leaves each line as wide as the tile, so it can still ellipsize
 ```
 
+```gherkin
+Scenario: Adaptive text color (three tones)
+  Given a palette with dark, pale, and theme-inverting stops
+  Then "dark" fills (diverging a3/b3, sequential 3–6, categorical, status) use white text (--ui-text-on-status-strong-neutral)
+  And "pale" fills (diverging a2/b2/a1/b1, sequential 1–2) use on-surface-primary (dark in light, light in dark)
+  And "inverts" fills (sequential 7–8, which mirror across themes) use on-strong-primary (near-white in light, near-black in dark)
+  And the decision is structural (based on the resolved token name suffix), not a runtime luminance check
+```
+
 ```gherkin
 Scenario: A second label line
   Given secondaryKeys naming other fields on the row
@@ -236,19 +243,23 @@ Scenario: Reduced motion
 - Do **not** rely on color alone to distinguish cells. The on-cell labels name
   the larger cells; keep `showTooltip` on so small (unlabelled) cells are still
   identifiable on hover.
-- On-cell labels use the `--ui-text-on-status-strong-neutral` token ("text on a
-  strong colored surface", constant white in both themes) to read over the
-  saturated series colors. This is legible on the chromatic brand/status tokens
-  used here but is **not** guaranteed for arbitrary caller colors — pick cell
-  colors dark enough for the light label text (matched per-cell label colors are a
-  design-pending item for the `--ui-chart-*` palette). The tooltip chrome and cell
-  separators resolve to semantic `--ui-*` tokens that meet contrast in both themes.
+- On-cell labels **adapt their text color** to three fill tones (structural,
+  based on the token name suffix — not a runtime luminance check):
+  - **dark** (diverging a3/b3, sequential 3–6, categorical, status): white via
+    `--ui-text-on-status-strong-neutral`.
+  - **pale** (diverging a2/b2/a1/b1, sequential 1–2): dark/light via
+    `--ui-text-on-surface-primary`.
+  - **inverts** (sequential 7–8, whose fills mirror across themes): near-white
+    in light, near-black in dark via `--ui-text-on-status-strong-primary`.
+    The tooltip chrome and cell separators resolve to semantic `--ui-*` tokens
+    that meet contrast in both themes.
 - Watch recharts issue [#4809](https://github.com/recharts/recharts/issues/4809)
   on the a11y layer for heavily-customized charts.
 
 ## Contrast
 
 Tooltip chrome and the surface-colored cell separators meet contrast in both
-themes via the semantic tokens. Cell fills come from `config` and are the
-caller's responsibility — keep them dark enough for the white on-cell labels, and
-adjacent cells distinguishable from each other.
+themes via the semantic tokens. Cell fills come from the active palette's
+`--ui-dataviz-*` tokens. The adaptive label text ensures contrast on every
+palette-assigned stop; adjacent cells are kept distinguishable by the
+interleaved/ramp ordering of the palette.

package/dist/llms.txt

@@ -1,6 +1,6 @@
 # Acronis UI Kit for React — LLM Reference
 
-> `@acronis-platform/ui-react` v5.0.0
+> `@acronis-platform/ui-react` v5.1.0
 
 Machine-readable component reference compiled from framework-agnostic specs.
 Each entry links to a self-contained markdown file with props, behavior,
@@ -29,8 +29,9 @@ accessibility notes, and usage examples.
 
 - [AreaChart](./llms/area-chart.md): A typed area-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `AreaChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `layout` (single / stacked areas) and `fill` (solid flat fill / vertical gradient); single vs multi area is driven by the number of `dataKeys`. Ported from the apps/demo `AreaChartPlayground`.
 - [Avatar](./llms/avatar.md): A user or entity avatar — a circular badge showing a profile image, initials, or an icon. Eight color schemes; stack several with AvatarGroup for an overlapping row.
-- [BarChart](./llms/bar-chart.md): A typed bar-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `BarChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `orientation` (vertical / horizontal bars) and `layout` (grouped / stacked). Ported from the apps/demo `BarChartPlayground`.
+- [BarChart](./llms/bar-chart.md): Two renderings behind one name, selected by `orientation`. `vertical` (the default) is a typed bar-chart composition over the shared `Chart` primitives: `data` + `config` + a set of series `dataKeys` become a themed recharts `BarChart` inside a `ChartContainer`, with tooltip and legend chrome, grouped or stacked by `layout`. `horizontal` is a labelled proportional bar list — one row per `items` entry carrying its label, value, share of `max`, and a track bar — with no axes, grid, or recharts at all.
 - [CardFilter](./llms/card-filter.md): A compact stat/filter card: a caption label above a prominent value, with an optional leading icon. Three variants — `static` (presentational), `static-empty` (presentational placeholder with an em-dash), and `clickable` (an interactive filter that renders a button with hover / active / focus states).
+- [CardWidgetCarousel](./llms/card-widget-carousel.md): A horizontal scroll carousel that holds a row of action-widget cards and exposes floating Previous/Next chevron buttons to navigate the view. The carousel shell manages scroll; the individual cards are passed as `children`. Ships with a companion `CardWidget` component (same barrel) — a status-colored card with icon box, optional skeleton, and footer slot.
 - [CategoryBar](./llms/category-bar.md): A single horizontal bar split into proportional colored segments — one part-to-whole across a handful of categories in one row (onboarding stages, certification status, a pass/fail split). Each segment's width is its value over the sum of all values; segment colors are caller-supplied via `config`. A plain flex composition (not a recharts chart) with one CVA axis (`size`), an optional count/% legend, and per-segment hover tooltips. Design-pending v1 — no chart token tier exists yet.
 - [Chart](./llms/chart.md): A theming layer over recharts — a `ChartContainer` that supplies series colors and recharts class overrides, plus tooltip and legend chrome (`ChartTooltipContent`, `ChartLegendContent`). The chart type (bar / line / area / pie / …) is composed from recharts primitives by the caller. Ported from the legacy shadcn-uikit `chart`.
 - [ChartState](./llms/chart-state.md): A shared loading / empty / error placeholder for the chart types, rendered in place of the chart inside the same sized slot. A compact status block — a leading glyph over a centered label, with an optional retry action for the error state. The `empty` state draws the silhouette the design defines for each chart type (`variant`), plus an optional "Widget description" line; `loading` and `error` share one treatment. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a widget that isn't a chart — see behavior.md.
@@ -47,7 +48,6 @@ accessibility notes, and usage examples.
 - [FunnelChart](./llms/funnel-chart.md): A typed funnel-chart composition over the shared `Chart` primitives. The root is a row: a 120×120 square plot, a 16px gutter, then a stage-list legend taking every remaining pixel — the same composition `PieChart` and `RadialBarChart` use. The plot stacks one series of stages (`data` rows) as narrowing, 2px-gapped, 2px-rounded segments inside a `ChartContainer`, with a tooltip and optional on-plot labels. One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Stages are painted from the sequential blue ramp by default, because a funnel's stages are an ordered series rather than unrelated categories. Card-less by design: Figma's card, header and metric row are `ChartWidget`'s.
 - [Histogram](./llms/histogram.md): A frequency histogram — bins a set of continuous samples (`values`) into equal-width ranges and plots the count of each as contiguous bars. Distinct from `BarChart`, which plots pre-categorized rows: the binning is the component's own job (a pure helper). Built on the shared `Chart` primitives; design-pending v1 (no `--ui-chart-*` palette yet, no `apps/demo` playground).
 - [LineChart](./llms/line-chart.md): A typed line-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `LineChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `curve` (linear / monotone / step interpolation) and `lineStyle` (solid / dashed stroke); single vs multi line is driven by the number of `dataKeys`. Ported from the apps/demo `ChartPlayground`.
-- [Meter](./llms/meter.md): A labelled bar showing a scalar value within a known range — a fractional value / share (`role="meter"`, mirroring the HTML `<meter>` element), as opposed to `Progress` which tracks a task over time. One row: label + `value · %` over a proportional track bar, with a hover tooltip; designed to be stacked into a ranked breakdown (a "bar list"). Design-pending v1 (no `--ui-chart-*` palette; the fill color is caller-supplied per row).
 - [Metric](./llms/metric.md): A presentational stats strip: an optional info-tinted icon badge + primary value + unit on the left, an optional caption on the right, an optional trend row (auto-composed from `trend` + `trendValue` as a `TrendIndicator`), optional supporting text, and an optional `children` body (a chart, Separator, insight line, …). No Card wrapper, no size or status axes — nest inside `ChartWidget` or a `Card` when card chrome is needed. It owns visual hierarchy and layout only; it never computes or formats the value or decides whether a change is good or bad. Design-pending v1.
 - [PieChart](./llms/pie-chart.md): A typed pie/donut-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a `dataKey` (slice value) and `nameKey` (slice label) and renders a themed recharts `PieChart` inside a `ChartContainer`, with tooltip and legend chrome. One variant axis: `shape` (filled pie / hollow-centre donut). Ported from the apps/demo `PieChartPlayground`.
 - [RadarChart](./llms/radar-chart.md): A typed radar-chart composition over the shared `Chart` primitives (the first polar chart type). Plots a set of series `dataKeys` over one shared angular axis (`angleKey`) inside a `ChartContainer`, with a polar grid, tooltip, and legend. One variant axis: `gridType` (the web drawn as straight-edged `polygon` rings or smooth `circle` rings). Ported from the apps/demo `RadarChartPlayground`.
@@ -128,6 +128,7 @@ accessibility notes, and usage examples.
 - [Stepper](./llms/stepper.md): 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.
 - [StepperItem](./llms/stepper-item.md): 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.
 - [Tabs](./llms/tabs.md): Switches between related panels of content within the same context. A bordered segmented-control tab group (list, trigger, content) built on the Base UI Tabs primitive. Ported from the legacy shadcn-uikit `Tabs`; themed by the shared semantic tokens (no `--ui-tabs-*` tier yet).
+- [TreeItem](./llms/tree-item.md): One flat row of a tree or nested-list UI — an optional expand chevron, an optional checkbox, an optional leading icon, the row title, and an optional trailing extras slot. It is a single row and nothing more: it renders no nested list and implements no expand/collapse, so `isExpandable` and `expanded` are purely visual affordances and `selected` is a prop the consumer drives. The tree itself — its ARIA roles, indentation, expand state, selection, and keyboard roving — belongs to the composition, the same way `Breadcrumb` ships the trail's primitives without owning the trail.
 
 ## Overlay