@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/button-icon-input.md

@@ -0,0 +1,142 @@
+# ButtonIconInput
+
+> A smaller icon-only button (20×20, 16px glyph) meant to live inside an input's box (e.g. a clear or reveal affordance), as opposed to `ButtonIcon`'s standalone 32×32 sizing. `variant` (`normal` / `error`) mirrors the tone of the field it sits in.
+
+**Status:** ready · **Category:** actions · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { ButtonIconInput } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ButtonIconInput aria-label="Show password">
+  <EyeIcon />
+</ButtonIconInput>
+```
+
+A smaller icon-only button (20×20, 16px glyph) meant to live inside an input's
+box — e.g. `InputPassword`'s show/hide toggle. `variant` (`normal` / `error`)
+mirrors the tone of the field it's embedded in.
+
+## When to use
+
+- An affordance embedded inside a text field's box (reveal/hide password,
+  clear, etc.) that needs to visually match the field's current tone.
+
+## When not to use
+
+- A standalone icon-only action outside an input — use **ButtonIcon** (32×32).
+- An action that needs a text label — use **Button**.
+
+## Example (React — implemented)
+
+```tsx
+import { ButtonIconInput } from '@acronis-platform/ui-react';
+import { EyeIcon } from '@acronis-platform/icons-react/stroke-mono';
+
+<ButtonIconInput aria-label="Show password">
+  <EyeIcon />
+</ButtonIconInput>;
+
+// Error tone, matching a field in its error state
+<ButtonIconInput variant="error" aria-label="Show password">
+  <EyeIcon />
+</ButtonIconInput>;
+```
+
+Always provide an `aria-label` — the control has no text. Vue and Web Component
+implementations are planned against the same contract.
+
+## Parts
+
+| Part   | Element    | Description                                    |
+| ------ | ---------- | ---------------------------------------------- |
+| `root` | `<button>` | The 20×20 button surface (background, radius). |
+| `icon` | `<svg>`    | The single glyph, sized to 16px.               |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'normal' | 'error'` | `'normal'` | no | Visual tone — mirrors the field the button is embedded in. Each variant has its own idle/hover/active/disabled container + icon tokens and its own focus ring color (`--ui-focus-primary` for `normal`, `--ui-focus-error` for `error`). |
+| `disabled` | `boolean` | `false` | no | Disables interaction and applies the disabled token set. |
+| `type` | `'button' | 'submit' | 'reset'` | `'button'` | no | Native HTML button type. |
+| `aria-label` | `string` | — | no | Accessible name. Required in practice — this control is icon-only and has no text to name it. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation. Not fired while disabled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | A single icon (SVG), sized to 16px and tinted via currentColor. |
+
+## Behavior
+
+### Rendering
+
+#### Renders a compact icon-only button
+
+**Given** a ButtonIconInput with a single icon child
+**When** it renders
+**Then** it is a 20×20 square with the icon centered at 16px
+**And** background, glyph, and (for `error`) container/glyph tone resolve from
+`--ui-button-icon-input-*` for the current variant and state.
+
+### Interaction states
+
+#### Tracks each state from its own token, per variant
+
+**Given** the button is idle, hovered, or activated
+**When** it renders
+**Then** background and glyph each resolve from the matching `*-idle` /
+`*-hover` / `*-active` token **for the current `variant`** (`normal` or
+`error` — they don't share a token tier).
+
+#### Disabled always uses the `normal` disabled tokens
+
+**Given** a ButtonIconInput with `disabled`, regardless of `variant`
+**When** it renders
+**Then** background and glyph resolve from
+`--ui-button-icon-input-normal-container-color-disabled` /
+`-normal-icon-color-disabled` — the design defines no separate disabled
+treatment for `error`.
+
+#### Disabled suppresses click
+
+**Given** a ButtonIconInput with `disabled`
+**When** the user activates it
+**Then** no `click` is emitted.
+
+### Composition
+
+#### Renders as another element
+
+**Given** a `render` prop (React)
+**When** it renders
+**Then** the classes/props merge onto that element (e.g. an `<a>`).
+
+## Accessibility
+
+- **Role:** native `<button>`.
+- **Accessible name (required):** the control is icon-only, so it MUST be given
+  an `aria-label` (or `aria-labelledby`). The icon itself should be
+  `aria-hidden`. Without a label the button is unusable to screen readers.
+- **Keyboard:** Enter and Space activate (native). `disabled` removes it from
+  the tab order.
+- **Focus visible:** 3px ring, flush to the edge — `--ui-focus-primary` for the
+  `normal` variant, `--ui-focus-error` for `error`.
+- **Touch target:** 20×20 is well below the 44×44 guideline — this control is
+  meant to sit inside an input's box (e.g. a reveal/clear affordance), not to
+  stand alone as a primary touch target.
+- **Contrast:** glyph/background pairs come from the design tokens (authored for
+  contrast).
+- **WCAG:** 2.1.1, 2.4.7, 1.4.11, 4.1.2.

package/dist/llms/button-icon-menu.md

@@ -0,0 +1,209 @@
+# ButtonIconMenu
+
+> The kebab ("more options") trigger: a 32×32 bordered icon-only button holding a fixed 16px ellipsis glyph, across idle, hover, open, disabled, and focus states. Opens a menu of actions where there is no room for a label.
+
+**Status:** ready · **Category:** actions · **Since:** v0.63.0
+
+## Import
+
+```tsx
+import { ButtonIconMenu } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ButtonIconMenu
+  ariaLabel="Row actions"
+  open={open}
+  onClick={toggle}
+/>
+
+{/* Polymorphic: render as a menu trigger via the `render` prop */}
+<ButtonIconMenu render={<Menu.Trigger />} ariaLabel="Row actions" />
+```
+
+The kebab ("more options") trigger: a 32×32 bordered icon-only button holding a
+fixed 16px ellipsis glyph, across idle, hover, open, disabled, and focus states.
+
+It is the same surface as **ButtonIcon**'s `secondary` variant — the design draws
+it from the same `--ui-button-icon-*` tokens — with the ellipsis glyph pinned and
+menu-trigger semantics added.
+
+## When to use
+
+- A row, card, or toolbar needs a **menu of secondary actions** and there is no
+  room for a label.
+
+## When not to use
+
+- The trigger can carry a label — use **ButtonMenu**, which shows the label and a
+  chevron.
+- The action is a single command, not a menu — use **ButtonIcon**.
+- The glyph must be something other than the ellipsis — use **ButtonIcon** (this
+  component pins the glyph on purpose, so every kebab in the product looks the
+  same).
+- Picking one option from a list, showing the chosen value — use **Select**.
+
+## Example (React — implemented)
+
+```tsx
+import { ButtonIconMenu } from '@acronis-platform/ui-react';
+
+const [open, setOpen] = useState(false);
+
+<ButtonIconMenu
+  ariaLabel="Row actions"
+  open={open}
+  onClick={() => setOpen((v) => !v)}
+/>;
+```
+
+Composed as a real Base UI menu trigger:
+
+```tsx
+import { DropdownMenu, ButtonIconMenu } from '@acronis-platform/ui-react';
+
+<DropdownMenu>
+  <DropdownMenuTrigger render={<ButtonIconMenu ariaLabel="Row actions" />} />
+  <DropdownMenuContent>{/* items */}</DropdownMenuContent>
+</DropdownMenu>;
+```
+
+Keep `open` in sync with the menu the button controls so the active treatment and
+`aria-expanded` reflect the real state. Vue and Web Component implementations are
+planned against the same contract.
+
+## Parts
+
+| Part   | Element  | Notes                                                                   |
+| ------ | -------- | ----------------------------------------------------------------------- |
+| `root` | `button` | The surface; `aria-haspopup="menu"`, reflects `aria-expanded` when open |
+| `icon` | `svg`    | Fixed 16px ellipsis glyph, centered — not swappable                     |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `open` | `boolean` | `false` | no | Whether the associated menu is open. Applies the open (`*-active`) treatment to the container fill, glyph, and border, and reflects `aria-expanded`. Keep it in sync with the menu the button controls. |
+| `disabled` | `boolean` | `false` | no | Disables interaction. Applies the explicit disabled tokens (not opacity) and suppresses click. |
+| `ariaLabel` | `string` | `'More options'` | no | Accessible name. The control is icon-only and has no text to name it, so the default is only a fallback — pass a localized string. |
+| `type` | `'button' | 'submit' | 'reset'` | `'button'` | no | Native HTML button type. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation (pointer or keyboard). Typically toggles the associated menu. Not fired while disabled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `none` | Takes no content — the ellipsis glyph is fixed by the design. Use ButtonIcon when the glyph has to change. |
+
+## Behavior
+
+### Rendering
+
+#### Renders a bordered square carrying the ellipsis glyph
+
+**Given** a ButtonIconMenu
+**When** it renders
+**Then** it shows a 32×32 button with a 1px border and a centered 16px ellipsis
+glyph
+**And** background, glyph, and border resolve from the `--ui-button-icon-*`
+tokens for the current state.
+
+#### The glyph is fixed
+
+**Given** a consumer that needs a different icon
+**When** they reach for this component
+**Then** it offers no content slot — the design pins the ellipsis. Use
+**ButtonIcon** instead.
+
+### Open / closed
+
+#### Open applies the active treatment
+
+**Given** `open` is `false` (or unset)
+**When** it renders
+**Then** the idle tokens apply and `aria-expanded` is absent.
+
+**Given** `open` is `true`
+**When** it renders
+**Then** the container fill, glyph, and border take their `*-active` tokens and
+`aria-expanded="true"`.
+
+### Interaction states
+
+#### Tracks each state from its own token
+
+**Given** the button is idle, hovered, pressed, open, or disabled
+**When** it renders
+**Then** the container fill, glyph color, and border color resolve from the
+matching `*-idle` / `*-hover` / `*-active` / `*-disabled` token, so brand and
+theme overrides are honored per state. Pressed and open share the `*-active`
+tokens, as the design does.
+
+#### Disabled suppresses click
+
+**Given** a ButtonIconMenu with `disabled`
+**When** the user activates it
+**Then** no `click` is emitted and the disabled tokens apply (not opacity).
+
+### Composition
+
+#### Renders as another element
+
+**Given** a `render` prop (React)
+**When** it renders
+**Then** the classes and props merge onto that element (e.g. a Base UI menu
+trigger), so the button can drive a real menu while keeping its visual contract.
+
+## Accessibility
+
+## Role & name
+
+- Renders a native `<button>` (role `button`).
+- The control is **icon-only**, so it has no text to name it. The accessible name
+  comes from `ariaLabel` (or a native `aria-label` / `aria-labelledby`). The
+  built-in `'More options'` default is a fallback so the button is never
+  unnamed — pass a localized, context-specific name ("Row actions", "Backup plan
+  actions") whenever more than one of these sits on a screen.
+- The ellipsis glyph is decorative and carries no separate accessible name.
+
+## Expanded state
+
+- The button sets `aria-haspopup="menu"` so assistive technology announces it as
+  a menu trigger before activation — unlike a labelled trigger, there is no text
+  to imply it.
+- While `open`, it sets `aria-expanded="true"`; when closed the attribute is
+  absent (treated as not expanded). Keep `open` in sync with the menu it
+  controls.
+- When wired to a real menu, the trigger should also reference the popup it
+  controls (`aria-controls`). The menu component owns that; ButtonIconMenu owns
+  only the trigger. Composing via `render={<Menu.Trigger />}` lets Base UI
+  manage those attributes.
+
+## Keyboard
+
+- `Tab` / `Shift+Tab` — move focus to / from the button.
+- `Enter` / `Space` — activate the button (opens the associated menu).
+- Disabled buttons are skipped in the tab order and ignore activation.
+
+## Focus
+
+- `:focus-visible` paints a 3px ring in `--ui-focus-primary` flush to the button
+  edge (no offset); the ring is suppressed for pointer focus.
+
+## Contrast
+
+- Color pairs come from `@acronis-platform/tokens-pd` and are maintained against
+  WCAG AA at the design-token level. The disabled treatment uses dedicated
+  disabled tokens rather than an opacity dim, so contrast stays predictable.
+
+## Target size
+
+- The 32×32 box meets the 24×24 minimum of WCAG 2.2 **Target Size (Minimum)**.
+  In dense rows keep adjacent triggers spaced so their targets do not overlap.

package/dist/llms/button-icon.md

@@ -0,0 +1,128 @@
+# ButtonIcon
+
+> Icon-only button (32×32, 24px glyph) with idle, hover, active, and disabled states. Two variants share the same fill and icon colors: `ghost` (borderless) and `secondary` (a 1px container border). Use when an action is represented by an icon alone.
+
+**Status:** ready · **Category:** actions · **Since:** v0.4.0
+
+## Import
+
+```tsx
+import { ButtonIcon } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ButtonIcon aria-label="Add">
+  <PlusIcon />
+</ButtonIcon>
+```
+
+An icon-only button: 32×32 with a single 24px glyph and
+idle/hover/active/disabled states. Two variants share the same fill and icon
+colors — `ghost` (borderless, the default) and `secondary` (a 1px container
+border).
+
+## When to use
+
+- A compact action represented by an icon alone (e.g. a toolbar action) where a
+  text label would be redundant or there's no room for one.
+
+## When not to use
+
+- An action that needs a text label — use **Button** (it also sizes a leading
+  icon).
+- A toggle — use a toggle/switch control.
+
+## Example (React — implemented)
+
+```tsx
+import { ButtonIcon } from '@acronis-platform/ui-react';
+import { PlusIcon } from '@acronis-platform/icons-react/stroke-mono';
+
+<ButtonIcon aria-label="Add">
+  <PlusIcon />
+</ButtonIcon>;
+
+// Bordered treatment
+<ButtonIcon variant="secondary" aria-label="Add">
+  <PlusIcon />
+</ButtonIcon>;
+```
+
+Always provide an `aria-label` — the control has no text. Vue and Web Component
+implementations are planned against the same contract.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'ghost' | 'secondary'` | `'ghost'` | no | Visual style. Both share the `--ui-button-icon-global-*` fill and icon colors; `secondary` additionally paints a 1px container border from the `--ui-button-icon-secondary-container-border-color-*` tokens, `ghost` is borderless. |
+| `disabled` | `boolean` | `false` | no | Disables interaction. Applies the explicit disabled tokens (not opacity) and suppresses click. |
+| `type` | `'button' | 'submit' | 'reset'` | `'button'` | no | Native HTML button type. |
+| `aria-label` | `string` | — | no | Accessible name. Required in practice — this control is icon-only and has no text to name it. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation. Not fired while disabled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | A single icon (SVG), sized to 24px and tinted via currentColor. |
+
+## Behavior
+
+### Rendering
+
+#### Renders a square icon-only button
+
+**Given** a ButtonIcon with a single icon child
+**When** it renders
+**Then** it is a 32×32 square with the icon centered at 24px
+**And** background, glyph, and border resolve from `--ui-button-icon-*` for the
+current state.
+
+### Interaction states
+
+#### Tracks each state from its own token
+
+**Given** the button is idle, hovered, activated, or disabled
+**When** it renders
+**Then** background, glyph, and border each resolve from the matching
+`*-idle` / `*-hover` / `*-active` / `*-disabled` token (brand/theme overrides
+honored per state).
+
+#### Disabled suppresses click
+
+**Given** a ButtonIcon with `disabled`
+**When** the user activates it
+**Then** no `click` is emitted and the disabled tokens apply (not opacity).
+
+### Composition
+
+#### Renders as another element
+
+**Given** a `render` prop (React)
+**When** it renders
+**Then** the classes/props merge onto that element (e.g. an `<a>`).
+
+## Accessibility
+
+- **Role:** native `<button>`.
+- **Accessible name (required):** the control is icon-only, so it MUST be given
+  an `aria-label` (or `aria-labelledby`). The icon itself should be
+  `aria-hidden`. Without a label the button is unusable to screen readers.
+- **Keyboard:** Enter and Space activate (native). `disabled` removes it from
+  the tab order.
+- **Focus visible:** 3px `--ui-focus-primary` ring flush to the edge (no offset)
+  via `:focus-visible`.
+- **Touch target:** 32×32 is below the 44×44 guideline; place with adequate
+  spacing, or extend the hit area with transparent padding where touch is a
+  primary input.
+- **Contrast:** glyph/background pairs come from the design tokens (authored for
+  contrast).
+- **WCAG:** 2.1.1, 2.4.7, 1.4.11, 4.1.2.

package/dist/llms/button-menu.md

@@ -0,0 +1,172 @@
+# ButtonMenu
+
+> A button that opens a dropdown menu: a label followed by a chevron that points up while the menu is open. Two visual styles (primary, secondary) across idle, hover, open, and disabled states.
+
+**Status:** ready · **Category:** actions · **Since:** v0.17.0
+
+## Import
+
+```tsx
+import { ButtonMenu } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ButtonMenu variant="primary" open={open} onClick={toggle}>
+  Actions
+</ButtonMenu>
+
+{/* Polymorphic: render as a menu trigger via the `render` prop */}
+<ButtonMenu render={<Menu.Trigger />}>Actions</ButtonMenu>
+```
+
+A button that opens a dropdown menu: a label followed by a chevron that points up
+while the menu is open. Two visual styles — `primary` (solid) and `secondary`
+(bordered) — across idle, hover, open, and disabled states.
+
+## When to use
+
+- A control whose primary job is to **open a menu** of actions or options, where
+  the current selection isn't shown on the button itself.
+
+## When not to use
+
+- A plain action with no menu — use **Button**.
+- A form control for picking one option from a list (showing the chosen value) —
+  use **Select**.
+- An icon-only trigger with no label — use **ButtonIcon**.
+
+## Example (React — implemented)
+
+```tsx
+import { ButtonMenu } from '@acronis-platform/ui-react';
+
+const [open, setOpen] = useState(false);
+
+<ButtonMenu open={open} onClick={() => setOpen((v) => !v)}>
+  Actions
+</ButtonMenu>;
+
+// Bordered treatment
+<ButtonMenu variant="secondary">Actions</ButtonMenu>;
+```
+
+Keep `open` in sync with the menu the button controls so the chevron and
+`aria-expanded` reflect the real state. Use the `render` prop to compose it as a
+Base UI menu trigger. Vue and Web Component implementations are planned against
+the same contract.
+
+## Parts
+
+| Part    | Element  | Notes                                                  |
+| ------- | -------- | ------------------------------------------------------ |
+| `root`  | `button` | The button surface; reflects `aria-expanded` when open |
+| `label` | `span`   | Text content, rendered before the chevron              |
+| `icon`  | `svg`    | Trailing chevron — down when closed, up when open      |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'primary' | 'secondary'` | `'primary'` | no | Visual style. `primary` is a solid filled button; `secondary` is bordered with a transparent fill. Each maps to its dedicated `--ui-button-menu-<variant>-*` tokens. |
+| `open` | `boolean` | `false` | no | Whether the associated menu is open. Flips the trailing chevron (down → up), applies the open (`*-active`) treatment, and reflects `aria-expanded`. Keep it in sync with the menu the button controls. |
+| `disabled` | `boolean` | `false` | no | Disables interaction. Applies the explicit disabled tokens (not opacity) and suppresses click. |
+| `type` | `'button' | 'submit' | 'reset'` | `'button'` | no | Native HTML button type. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation (pointer or keyboard). Typically toggles the associated menu. Not fired while disabled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The label content, rendered before the chevron. Plain text or inline nodes. |
+
+## Behavior
+
+### Rendering
+
+#### Renders a label and a trailing chevron
+
+**Given** a ButtonMenu with label content
+**When** it renders
+**Then** it shows the label followed by a chevron icon (16px)
+**And** background, label, icon, and — for `secondary` — border resolve from
+`--ui-button-menu-*` for the current variant and state.
+
+### Open / closed
+
+#### Chevron reflects the open state
+
+**Given** `open` is `false` (or unset)
+**When** it renders
+**Then** the chevron points **down** and `aria-expanded` is absent.
+
+**Given** `open` is `true`
+**When** it renders
+**Then** the chevron points **up**, the container takes its `*-active` treatment,
+and `aria-expanded="true"`.
+
+### Interaction states
+
+#### Tracks each state from its own token
+
+**Given** the button is idle, hovered, pressed, open, or disabled
+**When** it renders
+**Then** the container fill (and `secondary`'s label/icon/border) resolve from
+the matching `*-idle` / `*-hover` / `*-active` / `*-disabled` token (brand/theme
+overrides honored per state). `primary` keeps a single label/icon color.
+
+#### Disabled suppresses click
+
+**Given** a ButtonMenu with `disabled`
+**When** the user activates it
+**Then** no `click` is emitted and the disabled tokens apply (not opacity).
+
+### Composition
+
+#### Renders as another element
+
+**Given** a `render` prop (React)
+**When** it renders
+**Then** the classes/props merge onto that element (e.g. a menu trigger), so the
+button can drive a Base UI menu while keeping its visual contract.
+
+## Accessibility
+
+## Role & name
+
+- Renders a native `<button>` (role `button`). Its accessible name comes from the
+  label text content — always provide a meaningful label.
+- The trailing chevron is decorative; it must not be the only thing conveying the
+  action and needs no separate accessible name.
+
+## Expanded state
+
+- While `open`, the button sets `aria-expanded="true"`; when closed the attribute
+  is absent (treated as not expanded). Keep `open` in sync with the menu the
+  button controls.
+- When wired to a real menu, the trigger should also reference the menu it
+  controls (e.g. `aria-haspopup="menu"` and `aria-controls` pointing at the
+  popup). The menu component owns those; ButtonMenu only owns the trigger.
+
+## Keyboard
+
+- `Tab` / `Shift+Tab` — move focus to / from the button.
+- `Enter` / `Space` — activate the button (toggles the associated menu).
+- Disabled buttons are skipped in the tab order and ignore activation.
+
+## Focus
+
+- `:focus-visible` paints a 3px ring in `--ui-focus-primary` flush to the button
+  edge (no offset); the ring is suppressed for pointer focus.
+
+## Contrast
+
+- Color pairs come from `@acronis-platform/tokens-pd` and are maintained against
+  WCAG AA at the design-token level. The disabled treatment uses dedicated
+  disabled tokens rather than an opacity dim, so contrast stays predictable.