@acronis-platform/ui-react 4.1.0 → 5.1.0

package/dist/llms/sidebar-secondary.md

@@ -67,7 +67,7 @@ breadcrumb rail.
 | `SidebarSecondaryMenuSubContent`      | `Collapsible.Panel` `<div><ul>`      | Level-2 child list                                                                     |
 | `SidebarSecondaryMenuSubItem`         | `<li><a>`                            | Level-2 indented leaf                                                                  |
 | `SidebarSecondaryMenuItemExtras`      | `<span>`                             | Trailing shortcut / external-link / tag                                                |
-| `SidebarSecondaryCollapseTrigger`     | `<li><button>`                       | Footer "Collapse menu" button; toggles `expanded`                                      |
+| `SidebarSecondaryCollapseTrigger`     | `<li><button>`                       | Footer "Collapse menu" button; toggles `expanded` (`disabled` when not collapsible)    |
 
 ## Quick Examples
 
@@ -149,6 +149,44 @@ Author both the `SidebarSecondaryContent` (section list) and the
 `expanded` state via CSS — both stay in the DOM, so the breadcrumb is
 SSR-present and no JS branch is needed.
 
+## Locking the collapse state
+
+`collapsible` defaults to `true`. Pass `collapsible={false}` when the surface
+must not let the user change the panel's expanded/collapsed state. It locks that
+toggle only — **not the width**, which the user can still change by dragging or
+Arrow-shrinking while the panel is expanded. `resizable={false}` is what locks
+the width value itself; the two props are independent and compose:
+
+```tsx
+<SidebarSecondary collapsible={false}>{/* … */}</SidebarSecondary>
+```
+
+- Every user-initiated collapse/expand path is blocked — resize-edge click,
+  double-click-to-expand, drag past the collapse threshold, the resize edge's
+  Arrow/Enter/Space/Home keys, and the footer
+  `SidebarSecondaryCollapseTrigger` (which renders natively `disabled` and
+  shows no `expandTooltip`).
+- **Resizing still works while the panel is expanded.** A drag or Arrow-shrink
+  that would have collapsed the panel clamps to the minimum width instead. Pass
+  `resizable={false}` as well to lock the width outright.
+- It does **not** force `expanded`. `collapsible={false}` with
+  `defaultExpanded={false}` is valid and renders a permanently collapsed rail; a
+  controlled `expanded` prop still has full authority. On that permanently
+  collapsed rail the resize edge stays focusable and keeps its accessible name,
+  but it is inert — drag, click and the Arrow keys do nothing observable, and
+  only `Home` (or a double-click) still writes the default width, invisibly.
+- Every tooltip is adjusted for you, so the copy never advertises an inert
+  gesture. The footer collapse trigger's `expandTooltip` is suppressed outright
+  (a disabled control cannot expand anything; an explicit value does not bring
+  it back). The two resize-edge defaults narrow: **Expanded**, the default drops
+  the
+  "Collapse: Click" line and reads "Resize: Drag" / "Reset size: Double click".
+  **Collapsed**, the default narrows to "Reset size: Double click" alone —
+  dragging and clicking a permanently collapsed rail do nothing, but a
+  double-click still resets the width. An explicit `resizeTooltipExpanded` /
+  `resizeTooltipCollapsed` value always wins, including `null` to suppress the
+  tooltip entirely.
+
 ## Spec Files
 
 | File               | Contents                                                          |
@@ -177,10 +215,11 @@ SSR-present and no JS branch is needed.
 | `actions` | `ReactNode` | `undefined` | no | Trailing header actions on the section-label (e.g. a ghost ButtonIcon), rendered outside the toggle so they stay independently operable. |
 | `unreadRollup` | `ReactNode` | `undefined` | no | A rollup badge (e.g. a Tag with an unread count) shown in an expandable section's header only while it is collapsed. |
 | `resizable` | `boolean` | `true` | no | Enable the draggable resize edge on the right border. When `true`, the sidebar can be resized between the expanded-width token and twice that value. |
+| `collapsible` | `boolean` | `true` | no | Allow the user to collapse/expand the panel (resize-edge click, drag past the collapse threshold, keyboard, and the footer collapse trigger). When `false` those interactions never change `expanded` and the footer collapse trigger renders natively disabled with no `aria-expanded`; while the panel is expanded, dragging still resizes it, clamped to the minimum width. Independent of `expanded` — pair it with `defaultExpanded: false` for a permanently collapsed rail, on which the resize edge stays focusable but is inert apart from the (invisible) width reset, which `Home` and a double-click on the edge both still perform. |
 | `resizeAriaLabel` | `string` | `'Resize sidebar'` | no | Accessible label for the resize edge (`role="separator"`). Consumers should localize this string for i18n. |
-| `resizeTooltipExpanded` | `ReactNode` | `(English tooltip: Resize/Collapse/Reset)` | no | Tooltip content shown when the sidebar is expanded. Pass `null` to hide the tooltip entirely. Consumers should localize for i18n. |
-| `resizeTooltipCollapsed` | `ReactNode` | `(English tooltip: Resize/Expand)` | no | Tooltip content shown when the sidebar is collapsed. Pass `null` to hide the tooltip entirely. Consumers should localize for i18n. |
-| `expandTooltip` | `ReactNode` | `'Expand'` | no | Tooltip text shown on the collapse trigger when the sidebar is collapsed. Consumers should localize this string for i18n. |
+| `resizeTooltipExpanded` | `ReactNode` | `(English tooltip: Resize/Collapse/Reset; Resize/Reset when not collapsible)` | no | Tooltip content shown when the sidebar is expanded. The default depends on `collapsible`: with `collapsible: false` it drops the "Collapse: Click" line, since clicking the edge can no longer collapse the panel. Pass `null` to hide the tooltip entirely. Consumers should localize for i18n. |
+| `resizeTooltipCollapsed` | `ReactNode` | `(English tooltip: Resize/Expand; 'Reset size: Double click' only when not collapsible)` | no | Tooltip content shown when the sidebar is collapsed. The default depends on `collapsible`: with `collapsible: false` it narrows to the single "Reset size: Double click" line, because dragging and clicking a permanently collapsed rail have no effect while a double-click still resets the width. Pass `null` to hide the tooltip entirely, or an explicit node to replace it. Consumers should localize for i18n. |
+| `expandTooltip` | `ReactNode` | `'Expand'` | no | Tooltip text shown on the collapse trigger when the sidebar is collapsed. Suppressed entirely with `collapsible: false` — the trigger is disabled then, so the copy would advertise an action that cannot run. An explicit value does not override that suppression. Consumers should localize this string for i18n. |
 | `extras-variant` | `'tag' | 'externalLink' | 'shortcut' | 'tag-externalLink'` | — | yes | Which trailing affordance the extras part renders. React: the `variant` prop on `SidebarSecondaryMenuItemExtras`. (Named here without the bare `variant` key reserved for a root cva axis.) |
 | `shortcut` | `string` | `undefined` | no | Keyboard-shortcut text for the extras `shortcut` variant. |
 | `tag` | `ReactNode` | `undefined` | no | Tag content for the extras `tag` / `tag-externalLink` variants. |
@@ -256,6 +295,111 @@ SSR-present and no JS branch is needed.
 > DOM; visibility is toggled purely by `data-[state]` selectors (SSR-safe, no JS
 > branch).
 
+#### `collapsible={false}` blocks every user collapse/expand path
+
+**Given** a SidebarSecondary with `collapsible={false}`
+**When** the user clicks the resize edge, double-clicks it while collapsed,
+drags it past the collapse threshold, presses the shrink Arrow at the minimum
+width, presses the grow Arrow while collapsed, presses Enter/Space on the resize
+edge, presses Home while collapsed, or activates the footer
+`SidebarSecondaryCollapseTrigger`
+**Then** `expanded` never changes and `data-state` stays as it was
+**And** the footer collapse trigger renders natively `disabled`
+
+> **The width reset is not inert while collapsed.** Blocking the expand does not
+> block the width reset: on the resize edge of a `collapsible={false}`, collapsed
+> panel, **`Home` and a double-click** both still reset the stored width to
+> `defaultWidth` — neither write is gated on `collapsible` (in
+> `handleDoubleClick`, only its `toggleExpanded()` call is). `onWidthChange`
+> fires **only when `defaultWidth` differs from the current stored width**:
+> `setWidth` returns early on `next === currentWidth`, so a width write that
+> resolves to the current value is a no-op, and on a panel whose width has never
+> moved these two gestures emit nothing. When the width _has_ moved, nothing
+> changes visually at that moment (the rail stays collapsed), but a
+> controlled consumer observes the new width, and it takes effect the moment the
+> panel is expanded by other means (a controlled `expanded` prop). Every _other_
+> expand-triggering gesture — a single click, a drag, the grow Arrow, Enter/Space
+> — is genuinely inert in that state.
+
+#### A disabled collapse trigger looks inert
+
+**Given** a SidebarSecondary with `collapsible={false}` (or an explicitly
+`disabled` `SidebarSecondaryCollapseTrigger`)
+**When** the footer collapse trigger renders
+**Then** it shows a `not-allowed` cursor instead of the pointer cursor
+**And** its label and icon use the disabled on-surface foreground token
+**And** hovering or pressing it produces no highlight — the hover and active
+fills stay pinned to the row's idle container color
+**And** this is in addition to the native `disabled` attribute above, so the
+row reads as visually inert exactly where it is functionally inert
+
+#### Resizing stays live and clamps at the minimum
+
+**Given** an expanded, `resizable` SidebarSecondary with `collapsible={false}`
+**When** the user drags the resize edge below the collapse threshold, or presses
+the shrink Arrow so the next step would fall under `minWidth`
+**Then** the width clamps to `minWidth` (the expanded-width token's shipped
+default, 256px) instead of collapsing
+**And** drag/Arrow resizing between `minWidth` and `maxWidth` behaves exactly as
+it does when `collapsible` is `true`
+
+#### A permanently collapsed rail is a valid combination
+
+**Given** `collapsible={false}` together with `defaultExpanded={false}`
+**When** the panel renders
+**Then** it renders as the collapsed breadcrumb rail (`data-state="collapsed"`)
+**And** no user interaction can expand it — only a controlled `expanded` prop can
+**And** the resize edge stays focusable and keeps its accessible name, but is
+inert: dragging it, clicking it, and the grow/shrink Arrow keys produce no
+observable change
+**And** the one exception is the width reset — `Home` **and** a double-click on
+the edge both still write `defaultWidth` while the rail stays visually
+unchanged, firing `onWidthChange` only when `defaultWidth` differs from the
+current stored width (see the width-reset note above)
+
+> `collapsible` never forces `expanded` to a value; it only gates the
+> user-initiated transitions. A controlled `expanded` prop keeps full authority
+> either way.
+
+#### The expanded default tooltip drops the click gesture
+
+**Given** `collapsible={false}`, an **expanded** panel, and no
+`resizeTooltipExpanded` override
+**When** the user hovers the resize edge
+**Then** the tooltip reads "**Resize:** Drag" and "**Reset size:** Double click"
+— the "**Collapse:** Click" line the `collapsible={true}` default carries is
+omitted, because clicking the edge can no longer collapse the panel
+**And** an explicit `resizeTooltipExpanded` value still wins, including `null`
+to suppress the tooltip
+
+#### A permanently collapsed rail's tooltip advertises only the double-click
+
+**Given** `collapsible={false}`, a **collapsed** panel, and no
+`resizeTooltipCollapsed` override
+**When** the user hovers the resize edge
+**Then** the tooltip reads "**Reset size:** Double click" — and nothing else
+**And** the other two lines the `collapsible={true}` collapsed default carries
+are dropped, because neither gesture is live: clicking the edge bails in
+`handleClick`, and the collapsed drag branch only ever calls `toggleExpanded()`
+(itself gated off) and never writes a width, so both "**Resize:** Drag" and
+"**Expand:** Click" would be false claims
+**And** the double-click line _is_ honest: `handleDoubleClick` writes
+`defaultWidth` unconditionally, so it stays a live pointer gesture — the pointer
+counterpart of `Home`
+**And** an explicit `resizeTooltipCollapsed` value still wins, including `null`
+to suppress the tooltip entirely
+
+#### The collapse trigger shows no tooltip at all
+
+**Given** `collapsible={false}` and a footer `SidebarSecondaryCollapseTrigger`
+**When** the user hovers or focuses that trigger while the panel is collapsed
+**Then** no tooltip appears — the trigger's own `Tooltip` is disabled whenever
+the panel is expanded **or** not collapsible
+**And** this holds even when an explicit `expandTooltip` value is passed, unlike
+the two resize-edge tooltips where an override still wins: the trigger is
+natively `disabled` here, so any "Expand" copy would advertise an action the
+user cannot perform
+
 ---
 
 ### Disclosure (expandable sections)
@@ -360,6 +504,33 @@ When collapsed, the section list is hidden and a vertical breadcrumb is shown
 (`aria-hidden`). Any menu-item labels that remain are kept in the DOM as
 `sr-only`, never `display:none`.
 
+### Collapse trigger (footer)
+
+`SidebarSecondaryCollapseTrigger` is a `<button>` that toggles the panel width.
+
+| `collapsible` | Exposed as                                                                                                 | `expandTooltip` while collapsed |
+| ------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `true`        | `aria-expanded` mirrors the panel's `expanded` state; button enabled unless the consumer passes `disabled` | shown on hover/focus            |
+| `false`       | **no** `aria-expanded`; button carries the native `disabled`                                               | **suppressed** (no tooltip)     |
+
+When `collapsible` is `false` the button has no state to expose or flip, so
+`aria-expanded` is omitted rather than pinned to a value a user cannot change,
+and `disabled` communicates the unavailable action to assistive tech. Its
+`expandTooltip` is suppressed for the same reason — under `collapsible={false}`
+the panel can never be expanded by the user, so an "Expand" hint would be a
+false affordance. (The tooltip is likewise suppressed whenever the panel is
+expanded, in either mode: there is nothing to expand.)
+
+The suppression keys off `collapsible`, not off the button's disabled state:
+passing `disabled` directly to the trigger while `collapsible` is `true` still
+disables the button, but the `expandTooltip` keeps showing on hover.
+
+### Resize edge
+
+When `resizable`, the panel renders a focusable handle on its inline-end border
+with `role="separator"`, `aria-orientation="vertical"`, `tabIndex={0}` and an
+overridable `aria-label` (default `'Resize sidebar'`).
+
 ---
 
 ## Keyboard Navigation
@@ -374,6 +545,55 @@ When collapsed, the section list is hidden and a vertical breadcrumb is shown
 No roving tabindex — this is a list of links plus disclosure buttons, not a
 `menu`/`menubar`.
 
+### Resize edge (`role="separator"`)
+
+Arrow keys follow the writing direction: the **grow** key is `ArrowRight` in LTR
+and `ArrowLeft` in RTL; the **shrink** key is the mirror.
+
+| Key         | `collapsible: true`                                                                   | `collapsible: false`                                                                    |
+| ----------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Grow key    | Expanded: +16px. Collapsed: expands the panel                                         | Expanded: +16px. Collapsed: **inert**                                                   |
+| Shrink key  | Expanded: −16px; below the minimum width it collapses the panel. Collapsed: **inert** | Expanded: −16px, **clamps at the minimum width**, never collapses. Collapsed: **inert** |
+| Enter/Space | Toggles expanded/collapsed                                                            | **Inert**                                                                               |
+| Home        | Expands (if collapsed) and resets to the default width                                | Resets to the default width; never expands                                              |
+
+With `collapsible={false}` the edge stays focusable and keeps its accessible
+name. **While the panel is expanded**, resizing is still a real operation — only
+the collapse transition is suppressed. **While the panel is permanently
+collapsed** (`collapsible={false}` + collapsed) the edge is a focusable but
+visually inert tab stop: it keeps its `role="separator"` and accessible name,
+yet dragging, clicking, and both Arrow keys produce no observable change. Every
+**expand-triggering** gesture is inert here: dragging, a single click, the grow
+key and Enter/Space all fire no `toggleExpanded`, so `data-state` stays
+`collapsed`. **Two gestures remain live** — `Home` on the keyboard and a
+**double-click** on the edge. Both reset the stored width to `defaultWidth`, and
+neither is gated on `collapsible` (in `handleDoubleClick`, only the
+`toggleExpanded()` call is). They fire `onWidthChange` **only when
+`defaultWidth` differs from the current stored width** — `setWidth` returns
+early on `next === currentWidth`, so a width write that resolves to the current
+value is a no-op, and on a panel whose width has never moved these two gestures
+write nothing at all. When the width _has_ moved, the callback fires even though
+the rail is collapsed and looks unchanged at that moment; the reset only becomes
+visible if the panel is later expanded by other means (a controlled `expanded`
+prop flip), so a controlled consumer that mirrors `onWidthChange` must expect a
+width update while the panel is collapsed.
+
+> **Tooltip copy.** With `collapsible={false}` every tooltip on the panel is
+> adjusted for you, so the copy never advertises a gesture that is inert. The
+> footer collapse trigger's own `expandTooltip` is **suppressed outright** —
+> nothing can expand the panel, and an explicit value does not bring the
+> tooltip back — and both resize-edge tooltip defaults narrow.
+> **Expanded**, the resize-edge default drops the "**Collapse:** Click" line
+> and reads "**Resize:** Drag" / "**Reset size:** Double click". **Collapsed**,
+> the default
+> narrows to the single line "**Reset size:** Double click" — dragging and
+> clicking a permanently collapsed rail do nothing, but a double-click still
+> writes the default width, so that is the one pointer gesture the tooltip can
+> honestly advertise. An explicit `resizeTooltipExpanded` /
+> `resizeTooltipCollapsed` value always wins over the default (including `null`
+> to suppress the tooltip entirely), `collapsible` notwithstanding. All of these
+> strings are English by default and must be localized regardless.
+
 ---
 
 ## Focus
@@ -415,3 +635,14 @@ A keyboard-focused row shows a visible focus ring using the shared
 - [ ] Disclosure trigger exposes `aria-expanded` / `aria-controls`; toggles on click + Enter/Space
 - [ ] Level-2 sub-items are indented and reachable via Tab when open
 - [ ] Collapsed rows keep an accessible name (sr-only label, not removed)
+- [ ] Resize edge is `role="separator"`, focusable, and has an overridable `aria-label`
+- [ ] With `collapsible={false}`: the footer collapse trigger is `disabled`,
+      exposes no `aria-expanded`, and shows **no Expand tooltip** on hover or
+      focus; Enter/Space on the resize edge does not change
+      `data-state`; the shrink key clamps at the minimum width
+- [ ] With `collapsible={false}` while collapsed: Home **and a double-click on
+      the edge** leave `data-state` `collapsed` but still reset the stored width
+      (`onWidthChange` fires with `defaultWidth` only if that differs from the
+      current stored width)
+- [ ] With `collapsible={false}` while collapsed: the default resize tooltip
+      reads "Reset size: Double click" only

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.