@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/select.md

@@ -0,0 +1,210 @@
+# Select
+
+> A form control that displays the current selection and reveals a list of predefined options when activated. Composed from parts (trigger, value, content, item); supports single or multiple selection. An alias of the next-gen `InputSelect` family, themed with the `--ui-input-select-*` token tier.
+
+**Status:** ready · **Category:** forms · **Since:** v0.10.0
+
+## Import
+
+```tsx
+import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectGroupLabel } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Select items={{ apple: 'Apple', banana: 'Banana' }} value={fruit} onValueChange={setFruit}>
+  <SelectTrigger aria-label="Fruit">
+    <SelectValue placeholder="Select an option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+A form control that shows the current selection and reveals a list of
+predefined options when activated. Single or multiple selection.
+
+## When to use
+
+- Choosing from a list of predefined options when screen space is limited.
+- Single selection (default) or multiple selection (`multiple`).
+
+## When not to use
+
+- A small number of options that should stay visible — use radio buttons
+  (single) or checkboxes (multiple) instead.
+- Free-text entry or filtering a large/remote dataset — use an input or a
+  combobox/autocomplete pattern.
+
+## Anatomy
+
+A composable set of parts:
+
+| Part               | Element    | Role       | Purpose                             |
+| ------------------ | ---------- | ---------- | ----------------------------------- |
+| `Select`           | — (no DOM) | —          | Owns open + selection state.        |
+| `SelectTrigger`    | `button`   | `combobox` | The control; opens the popup.       |
+| `SelectValue`      | `span`     | —          | Selected label or placeholder.      |
+| `SelectContent`    | `div`      | `listbox`  | Floating options panel (portaled).  |
+| `SelectItem`       | `div`      | `option`   | A single option (+ selected check). |
+| `SelectGroup`      | `div`      | `group`    | Optional labelled section.          |
+| `SelectGroupLabel` | `div`      | —          | Heading for a group.                |
+
+## Examples
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+} from '@acronis-platform/ui-react';
+
+// Pass `items` so the trigger can show the selected option's label while closed.
+<Select items={{ apple: 'Apple', banana: 'Banana' }} defaultValue="apple">
+  <SelectTrigger aria-label="Fruit">
+    <SelectValue placeholder="Select an option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+Controlled:
+
+```tsx
+<Select value={fruit} onValueChange={setFruit} items={items}>
+  …
+</Select>
+```
+
+Grouped options use `SelectGroup` + `SelectGroupLabel`. Label, description, and
+error messaging are composed by the consumer (a Field component is future work).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `string | string[]` | — | no | Controlled selected value(s). Pair with the change event. |
+| `default-value` | `string | string[]` | — | no | Initial selection when uncontrolled. |
+| `open` | `boolean` | — | no | Controlled open state of the options popup. |
+| `default-open` | `boolean` | `false` | no | Whether the popup is initially open when uncontrolled. |
+| `disabled` | `boolean` | `false` | no | Disables the control; applies the disabled tokens and blocks opening. |
+| `multiple` | `boolean` | `false` | no | Whether more than one option can be selected. |
+| `required` | `boolean` | `false` | no | Marks the control as required in a form. |
+| `name` | `string` | — | no | Form field name submitted with the form (via a hidden input). |
+| `placeholder` | `string` | — | no | Hint shown by the value part when nothing is selected. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `value-change` | `string | string[]` | Fired when the selection changes (React: `onValueChange`). Payload is the new value. |
+| `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 select. Author it from the parts: a trigger wrapping the value, then content wrapping the items (optionally grouped). Provide an `items` map on the root so the value part can render a selected option's label while the popup is closed. |
+
+## Behavior
+
+### Opening
+
+- **Given** an enabled, closed select
+  **When** the user presses the trigger (click, Space, Enter, or ArrowDown)
+  **Then** the popup opens (`open-change(true)`), the chevron rotates 180°, and
+  keyboard focus moves into the list.
+
+- **Given** a disabled select
+  **When** the user presses the trigger
+  **Then** nothing happens — the popup does not open.
+
+### Selecting
+
+- **Given** an open select
+  **When** the user clicks an option (or highlights it and presses Enter)
+  **Then** that option becomes the value, `value-change` fires with the new
+  value, the trigger shows the option's label, and — for a single select — the
+  popup closes.
+
+- **Given** `multiple` is set
+  **When** the user activates options
+  **Then** each toggles in/out of the selection and the popup stays open.
+
+- **Given** a selection exists
+  **When** the popup is open
+  **Then** the selected option shows its check indicator and is the initially
+  highlighted item.
+
+### Closing
+
+- **Given** an open select
+  **When** the user presses Escape, clicks outside, or makes a single selection
+  **Then** the popup closes (`open-change(false)`) and focus returns to the
+  trigger.
+
+### Value display
+
+- **Given** a value is selected but the popup is closed
+  **When** an `items` map is provided on the root
+  **Then** the trigger renders the selected option's **label** (not the raw
+  value). Without `items`, the raw value is shown.
+
+### Controlled vs uncontrolled
+
+- **Given** `value` (or `open`) is controlled
+  **When** the user makes a selection (or toggles open)
+  **Then** internal state does **not** change on its own; the component emits the
+  change event and the consumer must update the prop to reflect it.
+- **Given** only `default-value` / `default-open` is provided
+  **Then** the component manages the state itself.
+
+## Accessibility
+
+Provided by the Base UI Select primitive; verify these hold after styling.
+
+## Roles & ARIA
+
+- The trigger has `role="combobox"` with `aria-haspopup="listbox"` and
+  `aria-expanded` reflecting the open state.
+- The popup has `role="listbox"` (with `aria-multiselectable` when `multiple`).
+- Each option has `role="option"` with `aria-selected` reflecting selection;
+  a disabled option exposes `aria-disabled`.
+- A group uses `role="group"` labelled by its group label.
+- Provide an accessible name for the trigger (`aria-label` or a visible label
+  associated via `aria-labelledby`); the component ships no built-in label.
+- A hidden form input carries `name`/`value` for form submission.
+
+## Keyboard
+
+| Key                                 | Action                                            |
+| ----------------------------------- | ------------------------------------------------- |
+| Space / Enter / ArrowDown / ArrowUp | Open the popup when the trigger is focused.       |
+| ArrowUp / ArrowDown                 | Move the highlight between options while open.    |
+| Home / End                          | Highlight the first / last option.                |
+| Type-ahead                          | Jump to the option matching the typed characters. |
+| Enter / Space                       | Select the highlighted option.                    |
+| Escape                              | Close the popup without changing the selection.   |
+| Tab                                 | Move focus out (closes the popup).                |
+
+## Focus
+
+- The trigger is the single tab stop. Opening moves focus into the list;
+  closing returns focus to the trigger.
+- Keyboard focus paints a 3px `--ui-focus-primary` ring on the trigger
+  (`:focus-visible`), matching the Figma "Focused" state.
+
+## Contrast
+
+- Trigger value text, placeholder, border, and the chevron all resolve to
+  `--ui-input-select-*` tokens that meet contrast in both light and dark themes.
+- The disabled state uses the dedicated disabled tokens (not opacity), keeping
+  text legible.

package/dist/llms/separator.md

@@ -0,0 +1,87 @@
+# Separator
+
+> 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
+
+## Import
+
+```tsx
+import { Separator } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Separator className="my-4" />
+<Separator orientation="vertical" />
+```
+
+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.
+
+## When to use
+
+- To separate groups of content or controls (sections, toolbar items, menu groups).
+
+## When not to use
+
+- As spacing alone — use margins/padding.
+- Inside a menu — group items into `DropdownMenuGroup`s instead; non-first
+  groups render a top-border separator automatically.
+
+## Example
+
+```tsx
+import { Separator } from '@acronis-platform/ui-react';
+
+<Separator className="my-4" />
+
+<div className="flex h-5 items-center gap-4">
+  <span>Backup</span>
+  <Separator orientation="vertical" />
+  <span>Recovery</span>
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `orientation` | `'horizontal' | 'vertical'` | `'horizontal'` | no | Direction of the rule; sets aria-orientation and swaps the 1px dimension. |
+
+## Behavior
+
+Separator is a static divider. It has no props beyond `orientation`, no state,
+and no interaction.
+
+```gherkin
+Scenario: Horizontal rule (default)
+  Given a Separator with no orientation
+  Then it renders a full-width, 1px-tall rule
+```
+
+```gherkin
+Scenario: Vertical rule
+  Given a Separator with orientation="vertical"
+  Then it renders a full-height, 1px-wide rule and sets aria-orientation="vertical"
+  And it needs a sized (height-bearing) flex/inline context to be visible
+```
+
+## Accessibility
+
+- Renders `role="separator"` (Base UI), with `aria-orientation` reflecting the
+  `orientation` prop — so assistive tech announces a divider.
+- Use a separator to convey a _meaningful_ break between groups. For a purely
+  decorative line that should be ignored by assistive tech, hide it
+  (`aria-hidden`) instead.
+- It is non-interactive and not in the tab order.
+
+## Contrast
+
+The line uses `--ui-border-on-surface-border`, which meets non-text contrast
+against the page surface in light and dark themes.

package/dist/llms/sheet.md

@@ -0,0 +1,202 @@
+# Sheet
+
+> A modal side panel anchored to a screen edge — for showing or acting on detailed information without leaving the page. Composable parts (trigger, overlay, content, header, title, close, body, description, footer) on the Base UI Dialog primitive, with a slide transition. Was `Details` in the Vue kit (re-exported under `Details*` aliases). Initial version ported from the legacy shadcn-uikit `Sheet`; design reconciliation against Figma (Cyber-Compliance node 3442-31542) is pending.
+
+**Status:** draft · **Category:** overlays · **Since:** v0.42.0
+
+## Import
+
+```tsx
+import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetCloseButton, SheetBody, SheetDescription, SheetFooter } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Sheet>
+  <SheetTrigger render={<Button variant="secondary">Open details</Button>} />
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Workload details</SheetTitle>
+      <SheetCloseButton />
+    </SheetHeader>
+    <SheetBody>
+      <SheetDescription>Inspect the selected workload.</SheetDescription>
+    </SheetBody>
+    <SheetFooter>
+      <SheetClose render={<Button variant="ghost">Close</Button>} />
+      <Button>Edit</Button>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+// `Details*` aliases (e.g. <Details>/<DetailsContent>) are equivalent — the
+// Vue kit called this component Details.
+```
+
+A modal side panel anchored to a screen edge — for showing or acting on detailed
+information without leaving the page.
+
+> **Status: draft (design-pending v1).** Ported from the legacy
+> `@acronis-platform/shadcn-uikit` `Sheet` (the same Base UI Dialog primitive the
+> `Dialog` component uses, edge-anchored). Themes on the shared semantic tokens
+> like the Dialog family — no `--ui-sheet-*` tier yet. Reconcile with
+> `/figma-component Sheet <url> --update` (Cyber-Compliance node 3442-31542).
+
+## `Details` is an alias
+
+The Vue UI kit called this side panel **`Details`**. For a 1:1 migration the full
+part family is re-exported under `Details*` (`Details`, `DetailsContent`,
+`DetailsHeader`, `DetailsTitle`, `DetailsBody`, `DetailsFooter`, …). New code
+should prefer `Sheet`.
+
+## When to use
+
+- Inspecting or editing the details of a selected item (a row, a workload) beside
+  its list.
+- A focused, dismissible task that shouldn't navigate away from the page.
+
+## When not to use
+
+- A centered confirmation or short form — use `Dialog`.
+- Persistent, non-modal page chrome — use a sidebar (`SidebarSecondary`), not a
+  modal sheet.
+
+## Parts
+
+| Part               | Element | Purpose                                     |
+| ------------------ | ------- | ------------------------------------------- |
+| `Sheet`            | —       | Root; owns open state (`Details`).          |
+| `SheetTrigger`     | button  | Opens the sheet (polymorphic via `render`). |
+| `SheetContent`     | div     | The portaled panel; `side` picks the edge.  |
+| `SheetHeader`      | div     | Title + close bar.                          |
+| `SheetTitle`       | h2      | Accessible name.                            |
+| `SheetCloseButton` | button  | Dismiss (×) button.                         |
+| `SheetBody`        | div     | Scrollable content region.                  |
+| `SheetDescription` | p       | Supporting text.                            |
+| `SheetFooter`      | div     | Right-aligned action bar.                   |
+| `SheetClose`       | button  | Any element that dismisses (polymorphic).   |
+
+## Example
+
+```tsx
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetCloseButton,
+  SheetBody,
+  SheetDescription,
+  SheetFooter,
+} from '@acronis-platform/ui-react';
+
+<Sheet>
+  <SheetTrigger render={<Button variant="secondary">Open details</Button>} />
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Workload details</SheetTitle>
+      <SheetCloseButton />
+    </SheetHeader>
+    <SheetBody>
+      <SheetDescription>Inspect the selected workload.</SheetDescription>
+    </SheetBody>
+    <SheetFooter>
+      <Button>Edit</Button>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `open` | `boolean` | — | no | Controlled open state. Pair with the change event. |
+| `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled. |
+| `modal` | `boolean | 'trap-focus'` | `true` | no | Modal behavior — traps focus and locks background scroll while open. `'trap-focus'` keeps the focus trap but allows background interaction. |
+| `side` | `'top' | 'right' | 'bottom' | 'left'` | `'right'` | no | Screen edge the panel anchors to and slides in from (on the content part). Left/right are full-height; top/bottom are full-width. |
+| `portal` | `boolean` | `true` | no | Render the content inside a portal (the content part). Required by the underlying primitive for correct stacking; disable only when supplying your own portal ancestor. |
+| `render` | `RenderProp` | `undefined` | no | Composition prop available on the trigger, close, title, description, and other primitive parts — replaces the rendered element with another component (e.g. render the trigger as a Button) while merging props. React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `open-change` | `boolean` | Fired when the sheet opens or closes (React: `onOpenChange`). Payload is the new open value. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed sheet. Author it from the parts: an optional trigger, plus the content (panel) wrapping an optional header (title + close), a body (with a description), and an optional footer for actions. |
+
+## Behavior
+
+Sheet is a modal side panel built on the Base UI Dialog primitive. It owns one
+piece of state, `open`; `side` chooses the edge.
+
+```gherkin
+Scenario: Open from a trigger
+  Given a Sheet with a SheetTrigger
+  When the user activates the trigger
+  Then the panel slides in from its side and the overlay covers the page
+  And open-change(true) is emitted
+```
+
+```gherkin
+Scenario: Side
+  Given a SheetContent with side="left"
+  Then the panel anchors to the left edge and slides in from the left
+  (right is the default; top/bottom are full-width, left/right full-height)
+```
+
+```gherkin
+Scenario: Dismiss
+  Given an open Sheet
+  When the user clicks the close button, presses Esc, or clicks the overlay
+  Then the panel slides out and open-change(false) is emitted
+```
+
+```gherkin
+Scenario: Controlled
+  Given a Sheet with a controlled `open` prop
+  When a dismiss interaction occurs
+  Then open-change is emitted but the panel stays until the consumer updates `open`
+```
+
+```gherkin
+Scenario: Focus + scroll
+  Given an open modal Sheet
+  Then focus is trapped within the panel and background scroll is locked
+  And focus returns to the trigger on close
+```
+
+```gherkin
+Scenario: Details alias
+  Given the Vue kit's `Details` component
+  Then `Details*` (Details / DetailsContent / …) are aliases of `Sheet*` for a
+  1:1 drop-in migration
+```
+
+## Accessibility
+
+- The panel is a Base UI `Dialog.Popup`: `role="dialog"` + `aria-modal`, labelled
+  by `SheetTitle` (`aria-labelledby`) and described by `SheetDescription`
+  (`aria-describedby`). Always include a `SheetTitle` so the panel has an
+  accessible name.
+- Focus is trapped within the open panel and returns to the trigger on close;
+  background scroll is locked while open (Base UI). `Esc` and an outside press
+  dismiss an uncontrolled sheet.
+- The close button is a real button labelled "Close" (sr-only text) and shows a
+  visible focus ring (`--ui-focus-primary`).
+- A side panel is still a modal dialog — keep it for focused tasks/detail views;
+  don't trap the user in one for primary navigation.
+
+## Contrast
+
+Title uses `--ui-text-on-surface-primary` and description/close use
+`--ui-text-on-surface-secondary` over the `--ui-background-surface-secondary`
+panel; the header/footer bars use `--ui-background-surface-primary` divided by
+`--ui-border-on-surface-border`. All meet text/non-text contrast in light and
+dark.