@acronis-platform/ui-react 5.0.0 → 5.1.0

package/dist/llms/separator.md

@@ -2,7 +2,7 @@
 
 > A thin rule that visually and semantically divides content. Built on the Base UI Separator primitive (sets the `separator` role + aria-orientation). Ported from the legacy shadcn-uikit `Separator`; uses the shared divider token.
 
-**Status:** draft · **Category:** layout · **Since:** v0.15.0
+**Status:** ready · **Category:** layout · **Since:** v0.15.0
 
 ## Import
 
@@ -15,14 +15,15 @@ import { Separator } from '@acronis-platform/ui-react'
 ```tsx
 <Separator className="my-4" />
 <Separator orientation="vertical" />
+<Separator size="S2" />
 ```
 
 A thin rule that divides content, horizontally or vertically.
 
-> **Status: draft (design-pending v1).** Ported from the legacy
-> `@acronis-platform/shadcn-uikit` `Separator`; uses the shared `bg-border`
-> divider token (no `--ui-separator-*` tier). Reconcile with
-> `/figma-component Separator <url> --update` once a mockup lands.
+> Ported from the legacy `@acronis-platform/shadcn-uikit` `Separator`; matched
+> to Figma's `DividerHorizontal` component set (node 788:15147). Uses the
+> shared `--ui-border-on-surface-divider` token directly (no `--ui-separator-*`
+> tier).
 
 ## When to use
 
@@ -46,6 +47,9 @@ import { Separator } from '@acronis-platform/ui-react';
   <Separator orientation="vertical" />
   <span>Recovery</span>
 </div>
+
+{/* size (S1/S2/S3, Figma default S1) applies built-in surrounding spacing */}
+<Separator size="S2" />
 ```
 
 ## Props
@@ -53,11 +57,12 @@ import { Separator } from '@acronis-platform/ui-react';
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | no | Direction of the rule; sets aria-orientation and swaps the 1px dimension. |
+| `size` | `'S1' | 'S2' | 'S3'` | `'S1'` | no | Surrounding spacing baked into the rule (Figma variant `Size`). `S1` (default) has none; `S2`/`S3` apply `--ui-gap-4`/`--ui-gap-8` as margin on the axis perpendicular to the line. |
 
 ## Behavior
 
-Separator is a static divider. It has no props beyond `orientation`, no state,
-and no interaction.
+Separator is a static divider. It has no state and no interaction; its only
+props are `orientation` and `size`.
 
 ```gherkin
 Scenario: Horizontal rule (default)
@@ -72,6 +77,20 @@ Scenario: Vertical rule
   And it needs a sized (height-bearing) flex/inline context to be visible
 ```
 
+```gherkin
+Scenario: Default size has no built-in spacing
+  Given a Separator with no size
+  Then it renders with size="S1" and applies no surrounding margin
+```
+
+```gherkin
+Scenario: S2/S3 apply built-in surrounding spacing
+  Given a Separator with size="S2" or size="S3"
+  Then it applies --ui-gap-4 or --ui-gap-8 as margin on the axis
+    perpendicular to the rule (vertical margin for horizontal, horizontal
+    margin for vertical)
+```
+
 ## Accessibility
 
 - Renders `role="separator"` (Base UI), with `aria-orientation` reflecting the
@@ -83,5 +102,5 @@ Scenario: Vertical rule
 
 ## Contrast
 
-The line uses `--ui-border-on-surface-border`, which meets non-text contrast
+The line uses `--ui-border-on-surface-divider`, which meets non-text contrast
 against the page surface in light and dark themes.

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