@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/toolbar.md

@@ -0,0 +1,453 @@
+# Toolbar
+
+> A horizontal action row — list actions, an optional overflow control (e.g. a ButtonMenu), and an optional trailing area (a status text, or a selection counter + action) — typically shown above/below a list or table when rows are selected or bulk actions are available. Pure layout — no dedicated token tier; every action is an existing Button/ButtonMenu instance that brings its own tokens. Distinct from FilterSearch/DataTableToolbar (search + filter toolbars): Toolbar is a bulk-action/selection bar, not a filter bar.
+
+**Status:** ready · **Category:** layout · **Since:** v0.57.0
+
+## Import
+
+```tsx
+import { Toolbar, ToolbarActionList, ToolbarActions } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+// ToolbarActionList collapses trailing actions into "More actions"
+// once they no longer fit the row — no manual breakpoint wiring.
+<Toolbar disabled={selectedCount === 0}>
+  <ToolbarActionList
+    actions={[
+      { key: 'first', label: 'First action', onSelect: () => {} },
+      { key: 'second', label: 'Second action', onSelect: () => {} },
+    ]}
+  />
+  <ToolbarActions>
+    <span>{selectedCount} items selected:</span>
+    <Button variant="ghost" onClick={clearSelection}>
+      Deselect
+    </Button>
+  </ToolbarActions>
+</Toolbar>
+```
+
+A horizontal action row — list actions, an optional overflow control, and an
+optional trailing area — typically shown above/below a list or table when
+rows are selected or bulk actions are available.
+
+## When to Use
+
+- A bulk-action bar that appears when one or more rows in a table/list are
+  selected (e.g. "6 items selected: Deselect").
+- A row of always-available actions with an overflow "More actions" menu for
+  actions that don't fit.
+- A status row (e.g. "25 of 1250 items loaded") alongside action buttons.
+
+## When NOT to Use
+
+- **Search/filtering above a table** — use `FilterSearch` or
+  `DataTableToolbar`. Toolbar has no search field, filter popover, or
+  applied-filter chips.
+- **Navigation bars** — use a dedicated nav component.
+
+## Related Components
+
+- **FilterSearch** / **DataTableToolbar** — search-and-filter toolbars, not
+  bulk-action bars. Compose both above the same table if you need filtering
+  and a selection action bar (e.g. `FilterSearch` always visible,
+  `Toolbar` shown only while rows are selected).
+- **Button**, **ButtonMenu** — the action controls Toolbar arranges. Toolbar
+  itself renders no button; every action is a consumer-supplied instance.
+
+## Parts
+
+| Part                | Element / component | Role                                                       |
+| ------------------- | ------------------- | ---------------------------------------------------------- |
+| `Toolbar`           | `<fieldset>`        | Root flex container (16px gap, disabled cascade)           |
+| `ToolbarActionList` | `<div>`             | Figma's `ListActions` — self-collapsing action row (below) |
+| `ToolbarActions`    | `<div>`             | Right-aligned trailing area (8px gap)                      |
+
+## Behavior at a glance
+
+- Children render in source order; `ToolbarActions`, if present, is pushed to
+  the trailing edge via `grow shrink-0` (not `flex-1`, which also shrinks —
+  the actions area must never shrink below its own content's natural width).
+- `disabled` cascades to every nested Button/ButtonMenu via the native
+  `<fieldset disabled>` behavior — no prop-drilling required.
+- No dedicated token tier: every action brings its own tokens, and the
+  16px/8px gaps are un-tokenized Tailwind utilities (same precedent as
+  `FilterSearch`).
+- **`ToolbarActionList` auto-collapses.** The Figma breakpoints spec (node
+  `6262:28276`) requires that actions which don't fit the available width
+  move into a "More actions" menu. `ToolbarActionList` measures its own row
+  against a `ResizeObserver` on its parent `Toolbar` and moves trailing
+  actions into a `ButtonMenu` + `DropdownMenu` once they no longer fit — no
+  manual breakpoint wiring needed. Use plain `Button`/`ButtonMenu` children
+  directly on `Toolbar` instead when the action list is short and fixed and
+  auto-collapse isn't needed.
+
+## Quick Examples
+
+### React — auto-collapsing action list
+
+```tsx
+import {
+  Toolbar,
+  ToolbarActionList,
+  ToolbarActions,
+  Button,
+} from '@acronis-platform/ui-react';
+
+function SelectionToolbar({
+  selectedCount,
+  onDeselect,
+}: {
+  selectedCount: number;
+  onDeselect: () => void;
+}) {
+  return (
+    <Toolbar>
+      <ToolbarActionList
+        actions={[
+          { key: 'first', label: 'First action', onSelect: () => {} },
+          { key: 'second', label: 'Second action', onSelect: () => {} },
+          { key: 'third', label: 'Third action', onSelect: () => {} },
+        ]}
+      />
+      <ToolbarActions>
+        <span>{selectedCount} items selected:</span>
+        <Button variant="ghost" onClick={onDeselect}>
+          Deselect
+        </Button>
+      </ToolbarActions>
+    </Toolbar>
+  );
+}
+```
+
+### React — fixed, manually composed actions
+
+```tsx
+import {
+  Toolbar,
+  ToolbarActions,
+  Button,
+  ButtonMenu,
+} from '@acronis-platform/ui-react';
+
+<Toolbar>
+  <Button variant="ghost">First action</Button>
+  <Button variant="ghost">Second action</Button>
+  <ButtonMenu>More actions</ButtonMenu>
+  <ToolbarActions>
+    <span>25 of 1250 items loaded</span>
+  </ToolbarActions>
+</Toolbar>;
+```
+
+### Disabled
+
+```tsx
+<Toolbar disabled>
+  <ToolbarActionList actions={[{ key: 'first', label: 'First action' }]} />
+</Toolbar>
+```
+
+## Spec Files
+
+| File               | Contents                                                 |
+| ------------------ | -------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link     |
+| `anatomy.yaml`     | Root, parts, layout, prop states                         |
+| `api.yaml`         | Framework-agnostic contract + framework adapters         |
+| `tokens.yaml`      | No dedicated tier — see note in the file                 |
+| `behavior.md`      | Given/When/Then behavior scenarios                       |
+| `accessibility.md` | ARIA guidance (delegated to child components + fieldset) |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `disabled` | `boolean` | `false` | no | Disables every native form control nested inside (Button, ButtonMenu), via the platform's own fieldset-disables-descendants cascade. No prop-drilling into arbitrary children is required. |
+| `className` | `string` | `undefined` | no | Additional CSS classes for the root container. |
+| `actions` | `Array<{ key: string; label: Node; onSelect?: () => void; disabled?: boolean }>` | `undefined` | no | `ToolbarActionList`-only: the ordered action list it renders. As many leading actions as fit the row render as ghost Buttons; the rest move into the `more-actions` overflow menu, recomputed on resize (see `internal_state.visibleCount` in anatomy.yaml). `onSelect`/`disabled` are honored whichever way an action currently renders. |
+| `moreActionsLabel` | `Node` | `'More actions'` | no | ToolbarActionList-only: label for the overflow trigger. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The list-action controls — either a `ToolbarActionList` (self- collapsing, see `actions` prop) or plain Button/ButtonMenu instances for a short, fixed action list — and, as the last child, an optional `actions` part (ToolbarActions) for the trailing status text or selection counter. Order of children determines visual order. |
+| `actions` | ToolbarActions' children — a status text, or a selection counter + action (e.g. a "Deselect" Button). |
+
+## Behavior
+
+### Structure
+
+#### Renders a horizontal action row
+
+**Given** a Toolbar wrapping Button/ButtonMenu children
+**When** the component renders
+**Then** the root is a `<fieldset>` with a horizontal flex layout and 16px gap
+**And** children are vertically centered
+
+#### Renders with list actions only
+
+**Given** a Toolbar containing only Button children
+**When** it renders
+**Then** only those buttons are shown in the row, with no trailing spacer
+
+#### Renders with an overflow control and a trailing area
+
+**Given** a Toolbar containing Button children, a ButtonMenu, and a
+ToolbarActions child
+**When** it renders
+**Then** all three appear in order: list actions, overflow menu, trailing area
+
+---
+
+### Disabled
+
+#### Disables every nested control
+
+**Given** a Toolbar with `disabled` set to `true`, containing Button and
+ButtonMenu children (including inside a ToolbarActions child)
+**When** it renders
+**Then** every nested Button/ButtonMenu is disabled — via the native
+`<fieldset disabled>` cascade, with no explicit prop passed to each child
+
+#### Leaves nested controls enabled by default
+
+**Given** a Toolbar with no `disabled` prop
+**When** it renders
+**Then** every nested Button/ButtonMenu is enabled
+
+#### Closes an open overflow menu when the Toolbar becomes disabled
+
+**Given** a ToolbarActionList whose overflow menu is open
+**When** the ancestor Toolbar's `disabled` becomes `true`
+**Then** the menu closes and its items are disabled — the menu renders in a
+portal, outside the `<fieldset>` subtree the native cascade reaches, so the
+disabled state is carried to it in the same render rather than observed off
+the DOM afterwards
+
+#### Keeps the overflow menu closed once the Toolbar is re-enabled
+
+**Given** a Toolbar that was disabled while its overflow menu was open
+**When** `disabled` becomes `false` again
+**Then** the menu stays closed until the user opens it again
+
+---
+
+### Actions Area
+
+#### Pushes trailing content to the trailing edge
+
+**Given** a Toolbar with a ToolbarActions containing a status text
+**When** it renders
+**Then** the actions area grows to take remaining space but never shrinks
+below its own content's natural width (`grow shrink-0`, not `flex-1`)
+**And** its content is right-aligned
+
+#### Renders a selection counter with an action
+
+**Given** a Toolbar with a ToolbarActions containing a text node and a
+"Deselect" Button
+**When** it renders
+**Then** both are shown with an 8px gap between them, right-aligned
+
+#### Renders without a trailing area
+
+**Given** a Toolbar with no ToolbarActions child
+**When** it renders
+**Then** children are laid out from the leading edge with no trailing spacer
+
+---
+
+### Overflow (ToolbarActionList)
+
+#### Renders every action inline when they all fit
+
+**Given** a ToolbarActionList whose actions' combined width (plus gaps) fits
+the available row width
+**When** it renders
+**Then** every action renders as a ghost Button in source order
+**And** no "More actions" trigger is rendered
+
+#### Collapses trailing actions into an overflow menu once they no longer fit
+
+**Given** a ToolbarActionList whose actions no longer fit the available row
+width
+**When** it renders (or the row is resized narrower)
+**Then** as many leading actions as fit alongside a "More actions" trigger
+render inline
+**And** the remaining trailing actions render as items inside the
+`ButtonMenu` + `DropdownMenu` opened by that trigger
+
+#### Accounts for sibling width when measuring available space
+
+**Given** a ToolbarActionList rendered alongside a sibling ToolbarActions in
+the same Toolbar
+**When** it measures available width
+**Then** it subtracts the sibling's rendered width and the gap between them
+from the parent Toolbar's width, rather than assuming it owns the full row
+
+#### Re-measures on resize
+
+**Given** a mounted ToolbarActionList
+**When** its parent Toolbar's rendered width changes
+**Then** a `ResizeObserver` on the parent triggers a re-measurement and the
+visible/hidden split updates accordingly
+
+#### Preserves onSelect and disabled whether an action is inline or hidden
+
+**Given** a ToolbarActionList item with `onSelect` and/or `disabled` set
+**When** the item renders inline (a Button) or inside the overflow menu (a
+DropdownMenuItem), depending on available width
+**Then** `onSelect` fires from either rendering, and `disabled` is honored
+in either rendering
+
+#### Moves roving focus between visible actions with arrow keys
+
+**Given** a mounted ToolbarActionList with focus on a visible action
+**When** ArrowLeft/ArrowRight is pressed
+**Then** focus moves to the previous/next visible action, and tabindex rolls
+from that action to the newly-focused one (one Tab stop into the row overall)
+
+#### Moves roving focus into the overflow trigger with arrow keys
+
+**Given** a mounted ToolbarActionList with hidden actions and focus on the
+last visible action
+**When** ArrowRight is pressed
+**Then** focus moves into the "More actions" overflow trigger
+
+#### Skips a disabled action during roving-tabindex navigation
+
+**Given** a mounted ToolbarActionList with a `disabled` action among its
+visible actions
+**When** arrow keys move roving focus through the row
+**Then** the disabled action is unreachable — it is skipped, not merely
+focusable-but-inert
+
+---
+
+### Composition
+
+#### Supports arbitrary children
+
+**Given** a Toolbar with custom children (not just Button/ButtonMenu)
+**When** it renders
+**Then** all children appear in source order within the flex container
+
+#### Merges custom className
+
+**Given** a Toolbar with a custom className
+**When** it renders
+**Then** the custom class is merged onto the root element
+
+#### Spreads native fieldset attributes
+
+**Given** a Toolbar with `aria-label` or other native attributes
+**When** it renders
+**Then** those attributes are applied to the root `<fieldset>`
+
+## Accessibility
+
+`Toolbar` itself is a layout wrapper — most accessibility concerns are
+delegated to its composed children (Button, ButtonMenu). Its own contribution
+is the native `disabled` cascade. `ToolbarActionList`, when used, additionally
+implements the WAI-ARIA `toolbar` pattern (`role="toolbar"` + roving
+tabindex) on its own root — see below.
+
+## ARIA Roles and Attributes
+
+### Root (`fieldset`)
+
+The root renders as a `<fieldset>`, reset to look like a plain flex container
+(no border/margin/padding). A `<fieldset>` carries an implicit ARIA role of
+`group` — acceptable for a generic control grouping. `role="toolbar"` is
+**not** applied here: when the child action row needs the WAI-ARIA `toolbar`
+pattern, it lives one level down on `ToolbarActionList`'s own root (below),
+not on this fieldset. Plain Button/ButtonMenu children composed directly on
+`Toolbar` (not through `ToolbarActionList`) each keep their own natural Tab
+stop, matching `FilterSearch`'s and `DataTableToolbar`'s existing precedent
+in this kit.
+
+| Attribute    | Value    | Reason                                                    |
+| ------------ | -------- | --------------------------------------------------------- |
+| No `role`    | —        | Implicit `group` from `<fieldset>`                        |
+| `disabled`   | (opt-in) | Cascades to every nested form control                     |
+| `aria-label` | (opt-in) | Consumer may set this for a landmark-like accessible name |
+
+### List Actions (`ToolbarActionList`)
+
+`ToolbarActionList`'s own root implements the WAI-ARIA `toolbar` pattern via
+Base UI's `Toolbar.Root`/`Toolbar.Button` (`@base-ui/react/toolbar`):
+`role="toolbar"`, one Tab stop into the row, and roving `tabindex` between
+every visible action and the overflow trigger, driven by arrow keys. A
+disabled action opts out of Base UI's default APG toolbar
+treatment (`focusableWhenDisabled={false}`) so it matches every other
+disabled `Button` in this kit: unreachable via Tab or arrow keys, rather than
+focusable-but-inert. The invisible measurement clones used to compute
+collapse width are not registered in the roving-tabindex sequence.
+
+| Attribute        | Value   | Reason                                               |
+| ---------------- | ------- | ---------------------------------------------------- |
+| `role="toolbar"` | (fixed) | WAI-ARIA toolbar pattern for the action row          |
+| `tabindex`       | roving  | One Tab stop into the row; arrow keys move within it |
+
+---
+
+## Keyboard Navigation
+
+| Component                             | Key                  | Action                                                              |
+| ------------------------------------- | -------------------- | ------------------------------------------------------------------- |
+| `ToolbarActionList` visible action    | Enter/Space          | Activates the action                                                |
+| `ToolbarActionList` overflow trigger  | Enter/Space          | Opens/closes the overflow `DropdownMenu`                            |
+| `ToolbarActionList` row               | ArrowLeft/ArrowRight | Moves roving focus between visible actions and the overflow trigger |
+| Button/ButtonMenu (composed directly) | Enter/Space          | Activates the action / opens the menu it triggers                   |
+
+Plain Button/ButtonMenu children composed directly on `Toolbar` (not through
+`ToolbarActionList`) keep their natural individual Tab order — the fieldset
+itself does not manage their focus. When `disabled` is set, every nested
+Button/ButtonMenu is removed from the Tab order automatically (native
+`disabled` behavior), so no manual `tabIndex` management is needed.
+
+---
+
+## Screen Reader Requirements
+
+1. Each child component announces itself according to its own spec.
+2. Action buttons should have descriptive labels (e.g. "First action", not
+   an icon alone without an accessible name).
+3. A selection counter rendered inside `ToolbarActions` should state the
+   count in text (e.g. "6 items selected:") so it's announced, not conveyed
+   by an icon or color alone.
+4. When `disabled` is set, screen readers announce every nested control as
+   disabled — no additional `aria-disabled` wiring is required.
+
+---
+
+## Color and Contrast
+
+All contrast requirements are owned by the child components and their
+respective token tiers (`Button`, `ButtonMenu`). Any status/counter text the
+consumer renders inside `actions` should use the shared
+`--ui-text-on-surface-primary`/`-secondary` semantic tokens to remain
+compliant.
+
+---
+
+## Testing Checklist
+
+- [ ] Root renders as a `<fieldset>` with no unexpected ARIA role
+- [ ] Plain Button/ButtonMenu children composed directly on `Toolbar` are each
+      reachable via Tab
+- [ ] `ToolbarActionList` renders `role="toolbar"` and is reachable as a
+      single Tab stop, with arrow keys moving roving focus between its
+      visible actions and the overflow trigger
+- [ ] `disabled` removes every nested control from the Tab order
+- [ ] A disabled action inside `ToolbarActionList` is unreachable via Tab or
+      arrow keys, not merely `aria-disabled`
+- [ ] Action buttons have accessible names
+- [ ] A rendered selection counter states the count as text

package/dist/llms/tooltip.md

@@ -0,0 +1,164 @@
+# Tooltip
+
+> A contextual hint that appears on hover or focus of its trigger and disappears when the interaction ends. Used for supplementary information — not for critical content or actions.
+
+**Status:** ready · **Category:** overlay · **Since:** v0.12.0
+
+## Import
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Tooltip>
+  <TooltipTrigger render={<Button>Save</Button>} />
+  <TooltipContent>Save your changes</TooltipContent>
+</Tooltip>
+```
+
+A contextual hint shown on hover or focus of its trigger.
+
+## When to use
+
+- Supplementary information that clarifies an element or action (e.g. what an
+  icon button does) without cluttering the UI.
+
+## When not to use
+
+- Critical information or actions — tooltips aren't available to touch users and
+  disappear on blur. Use inline text, a Popover, or a Dialog.
+- Rich or interactive content — the popup is non-interactive. Use a Popover.
+
+## Anatomy
+
+A composable set of parts:
+
+| Part              | Element    | Role      | Purpose                        |
+| ----------------- | ---------- | --------- | ------------------------------ |
+| `Tooltip`         | — (no DOM) | —         | Owns open state.               |
+| `TooltipTrigger`  | `button`   | —         | The anchor (wrap any element). |
+| `TooltipContent`  | `div`      | `tooltip` | The floating hint bubble.      |
+| `TooltipProvider` | — (no DOM) | —         | Shares open/close delays.      |
+
+## Examples
+
+```tsx
+import {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  TooltipProvider,
+} from '@acronis-platform/ui-react';
+import { Button } from '@acronis-platform/ui-react';
+
+// Wrap your app (or a region) once to share delays:
+<TooltipProvider delay={300}>
+  <Tooltip>
+    <TooltipTrigger render={<Button>Save</Button>} />
+    <TooltipContent>Save your changes</TooltipContent>
+  </Tooltip>
+</TooltipProvider>;
+```
+
+`TooltipContent` accepts `side` / `align` / `sideOffset` to control placement. No
+arrow is rendered, matching the design.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `open` | `boolean` | — | no | Controlled open state of the popup. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Whether the popup is initially open when uncontrolled. |
+| `disabled` | `boolean` | `false` | no | Disables the tooltip — the popup never opens. |
+| `side` | `'top' | 'right' | 'bottom' | 'left'` | `top` | no | Which side of the trigger the popup is placed on (on the content). |
+| `delay` | `number` | — | no | Open delay in ms. Set on a `TooltipProvider` to share across tooltips. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the popup opens or closes (React: `onOpenChange`). Payload is the new open state. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed tooltip: a trigger (wrap any element via the trigger's `render` prop) and a content popup holding the hint text. |
+
+## Behavior
+
+### Opening
+
+- **Given** an enabled tooltip
+  **When** the user hovers the trigger or moves keyboard focus to it (after the
+  open delay)
+  **Then** the popup appears next to the trigger (`open-change(true)`).
+
+- **Given** a `disabled` tooltip
+  **When** the user hovers or focuses the trigger
+  **Then** nothing happens — the popup never opens.
+
+### Closing
+
+- **Given** an open tooltip
+  **When** the pointer leaves the trigger (and popup), focus moves away, or the
+  user presses Escape
+  **Then** the popup hides (`open-change(false)`).
+
+### Delay
+
+- **Given** a `TooltipProvider` wrapping several tooltips
+  **When** one opens after its delay
+  **Then** sibling tooltips can open without re-waiting the full delay (shared
+  delay), per the provider configuration.
+
+### Controlled vs uncontrolled
+
+- **Given** `open` is controlled
+  **When** the user hovers/focuses
+  **Then** internal state does not change on its own; the component emits
+  `open-change` and the consumer updates the `open` prop.
+- **Given** only `default-open`
+  **Then** the tooltip manages its own open state.
+
+### Placement
+
+- **Given** a `side` on the content
+  **When** the popup opens
+  **Then** it is placed on that side of the trigger, flipping to stay in view
+  when there isn't room.
+
+## Accessibility
+
+Provided by the Base UI Tooltip primitive; verify these hold after styling.
+
+## Roles & ARIA
+
+- The popup has `role="tooltip"`. The trigger references it via
+  `aria-describedby` while open, so screen readers announce the hint as a
+  description of the trigger.
+- The trigger must be a real, focusable element (a button by default, or any
+  focusable element via the trigger's `render` prop) so the tooltip is reachable
+  by keyboard, not just pointer.
+
+## Keyboard & focus
+
+- **Focus** the trigger opens the tooltip; **blur** closes it.
+- **Escape** closes an open tooltip.
+- The tooltip is supplementary — focus never moves into the popup, and the popup
+  contains no interactive content (use a Popover/Dialog for that).
+
+## Content guidance
+
+- Keep tooltips to short, non-essential text. Don't put critical information or
+  actions in a tooltip — it isn't available to touch users and vanishes on blur.
+- Don't rely on a tooltip as the only label for an icon-only control; give the
+  control its own accessible name (e.g. `aria-label`) as well.
+
+## Contrast
+
+- `--ui-tooltip-label-color` on `--ui-tooltip-container-color` meets contrast; the bubble's
+  ~90% opacity keeps text legible over varied backgrounds.