@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/card.md

@@ -0,0 +1,447 @@
+# Card
+
+> A surface that groups related content and actions. A set of composable parts (header, content, footer) on a bordered, rounded container. The header carries the interactive surface: an optional drag handle, toggle switch, avatar, rename button, extras, end-aligned actions, and an optional collapse trigger. Collapsibility is composed by wrapping the header and content/footer in `AccordionContainer`.
+
+**Status:** ready · **Category:** layout · **Since:** v0.8.0
+
+## Import
+
+```tsx
+import { Card, CardHeader, CardContent, CardFooter } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Card>
+  <CardHeader title="Backup status" description="Last run 5 minutes ago" hasDescription />
+  <CardContent>All workloads protected.</CardContent>
+  <CardFooter>
+    <Button>View report</Button>
+  </CardFooter>
+</Card>
+
+// Collapsible: compose with AccordionContainer, and set
+// CardHeader's isCollapsible to render the trigger.
+<Card>
+  <AccordionContainer collapsible defaultOpen>
+    <CardHeader title="Backup policy" isCollapsible />
+    <AccordionContainer.Content>
+      <CardContent>Applies to 12 workloads.</CardContent>
+      <CardFooter>
+        <Button>Save</Button>
+      </CardFooter>
+    </AccordionContainer.Content>
+  </AccordionContainer>
+</Card>
+```
+
+A surface that groups related content and actions into a bordered, rounded
+container. Composable from parts (`Card`, `CardHeader`, `CardContent`,
+`CardFooter`); the header carries a rich, Figma-driven feature set.
+
+> Figma node: `10012-195993`. The design's `isCollapsable` variant
+> (expanded/collapsed) is implemented by composing `Card` with
+> `AccordionContainer` — see "Collapsible" below.
+
+## When to use
+
+- Grouping related information into a self-contained block (a stat, a
+  summary, a settings group, a reorderable list item).
+- A header that needs any combination of: a drag handle (reorderable lists), a
+  toggle switch, an avatar, a title with an optional rename affordance, extra
+  inline content (tags/badges), and end-aligned actions (e.g. a menu button).
+- Nesting cards (a "main" card containing one or more "secondary" cards as
+  content) — `Card` is the same component in both roles; there is no separate
+  primary/secondary variant.
+
+## When not to use
+
+- For a compact single-stat tile with built-in variants, use **`CardFilter`**
+  instead.
+- As a generic layout `<div>` with no visual surface — just use a styled
+  element.
+- For modal/overlay surfaces — use the dialog/popover components.
+
+## Parts
+
+| Part          | Element (default) | Purpose                                                                            |
+| ------------- | ----------------- | ---------------------------------------------------------------------------------- |
+| `Card`        | `div`             | The card surface (border, radius); `hasError` swaps the border to the error token. |
+| `CardHeader`  | `div`             | Title/description + drag handle, switch, avatar, rename, extras, actions.          |
+| `CardContent` | `div`             | Primary body region for arbitrary children.                                        |
+| `CardFooter`  | `div`             | Bottom region; horizontal action row.                                              |
+
+`Card` and `CardContent` accept a `render` prop for polymorphic composition.
+
+## Example
+
+```tsx
+import {
+  Button,
+  Card,
+  CardContent,
+  CardFooter,
+  CardHeader,
+} from '@acronis-platform/ui-react';
+
+<Card className="w-[350px]">
+  <CardHeader
+    title="Backup status"
+    description="Last successful run 5 minutes ago."
+    hasDescription
+  />
+  <CardContent>All 24 workloads are protected.</CardContent>
+  <CardFooter className="gap-2">
+    <Button>View report</Button>
+    <Button variant="secondary">Run now</Button>
+  </CardFooter>
+</Card>;
+```
+
+## Header features
+
+```tsx
+<CardHeader
+  title="Backup policy"
+  isDraggable
+  isSwitchable
+  defaultSwitchChecked
+  hasAvatar
+  avatarLabel="SB"
+  hasRename
+  onRename={() => setRenaming(true)}
+  extras={<Badge>Beta</Badge>}
+  actions={
+    <ButtonIcon aria-label="More actions">
+      <EllipsisIcon size={24} />
+    </ButtonIcon>
+  }
+/>
+```
+
+- `isDraggable` shows a grip handle for reorderable lists — wire your own
+  drag library (e.g. `@dnd-kit/sortable`) onto the header or handle.
+- `isSwitchable` renders a real `Switch`; control it with `switchChecked` /
+  `defaultSwitchChecked` / `onSwitchCheckedChange`.
+- `hasAvatar` defaults to an initials avatar (`avatarLabel`); pass `avatar`
+  to render a custom node (e.g. an image avatar) instead.
+- `hasRename` renders a pencil icon button; wire `onRename` to open your own
+  rename UI (an inline input, a dialog, …) — Card does not manage rename
+  state itself.
+- `hasError` (on `Card`, not `CardHeader`) only swaps the root border color.
+
+## Collapsible
+
+Compose `Card` with `AccordionContainer` (the shared disclosure primitive):
+wrap `CardContent`/`CardFooter` in `AccordionContainer.Content` and set
+`CardHeader`'s `isCollapsible` to render the trigger — restyled to match the
+Figma design's ghost `ButtonIcon` chrome rather than `AccordionContainer`'s
+own neutral default.
+
+```tsx
+import {
+  AccordionContainer,
+  Card,
+  CardContent,
+  CardFooter,
+  CardHeader,
+} from '@acronis-platform/ui-react';
+
+<Card className="w-[420px]">
+  <AccordionContainer collapsible defaultOpen>
+    <CardHeader
+      title="Backup policy"
+      description="Applies to 12 workloads."
+      hasDescription
+      isCollapsible
+      collapseLabel="Toggle backup policy"
+    />
+    <AccordionContainer.Content>
+      <CardContent>All 24 workloads are protected and up to date.</CardContent>
+      <CardFooter className="gap-2">
+        <Button>Save</Button>
+        <Button variant="secondary">Cancel</Button>
+      </CardFooter>
+    </AccordionContainer.Content>
+  </AccordionContainer>
+</Card>;
+```
+
+- `isCollapsible` on `CardHeader` only has an effect when the header renders
+  inside a collapsible `AccordionContainer` — it's a no-op otherwise.
+- The header itself (title, drag handle, switch, avatar, actions, …) stays
+  visible in both the open and closed state; only content wrapped in
+  `AccordionContainer.Content` is hidden when closed.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `hasError` | `boolean` | `false` | no | Switches the root border to the error token. Set on the root (`Card`), not the header. |
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop available on the root and every part — replaces the rendered element with another component (e.g. render the root as `<article>`) while merging props and classes. React-only; other frameworks use their own polymorphism. |
+| `header.title` | `string` | `undefined` | no | The card's title text. Renders nothing when omitted. |
+| `header.description` | `string` | `undefined` | no | Helper text shown under the title; only rendered when `header.hasDescription` is set. |
+| `header.hasDescription` | `boolean` | `false` | no | Shows `header.description` below the title. |
+| `header.isDraggable` | `boolean` | `false` | no | Shows a drag handle at the start of the header, for reorderable lists. |
+| `header.dragHandleLabel` | `string` | `Reorder` | no | Accessible label for the drag handle. |
+| `header.isSwitchable` | `boolean` | `false` | no | Shows a toggle switch at the start of the header. |
+| `header.switchChecked` | `boolean` | `undefined` | no | Controlled checked state of the header switch. |
+| `header.defaultSwitchChecked` | `boolean` | `undefined` | no | Uncontrolled initial checked state of the header switch. |
+| `header.switchDisabled` | `boolean` | `undefined` | no | Disables the header switch. |
+| `header.switchLabel` | `string` | `Toggle card` | no | Accessible label for the header switch. |
+| `header.hasAvatar` | `boolean` | `false` | no | Shows an avatar before the title. |
+| `header.avatarLabel` | `string` | `` | no | Initials shown in the default avatar; ignored if `header.avatar` is provided. |
+| `header.avatar` | `ReactNode` | `undefined` | no | Replaces the default initials avatar with custom content. |
+| `header.hasRename` | `boolean` | `false` | no | Shows a rename button next to the title. |
+| `header.renameLabel` | `string` | `Rename` | no | Accessible label for the rename button. |
+| `header.extras` | `ReactNode` | `undefined` | no | Extra content rendered inline next to the title (e.g. a tag or badge). |
+| `header.actions` | `ReactNode` | `undefined` | no | Actions rendered at the end of the header (e.g. a menu button). |
+| `header.isCollapsible` | `boolean` | `false` | no | Shows a disclosure trigger at the end of the header. Only has an effect when the header renders inside a collapsible `AccordionContainer` — see the collapsible composition example. |
+| `header.collapseLabel` | `string` | `Collapse card` | no | Accessible label for the collapse trigger. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `header.onSwitchCheckedChange` | `undefined` | Fires when the header switch is toggled. |
+| `header.onRename` | `undefined` | Fires when the rename button is activated. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed card. Author it from the parts: an optional header (title, description, drag handle, switch, avatar, rename, extras, actions), a content region, and an optional footer for actions. All parts are optional and may be used in any combination. |
+
+## Behavior
+
+Card is a compound component: `Card` (root) + `CardHeader` + `CardContent` +
+`CardFooter`. Any part may be omitted; the root has no minimum composition.
+`CardHeader` owns most of the interactive surface described below.
+
+### Composition
+
+```gherkin
+Scenario: A fully composed card
+  Given a Card wrapping a CardHeader, a CardContent, and a CardFooter
+  When the card renders
+  Then the header, content, and footer appear in source order
+  And the root carries the rounded border and surface background
+```
+
+```gherkin
+Scenario: Parts are optional
+  Given a Card wrapping only a CardContent
+  When the card renders
+  Then the card surface renders with just the content region
+  And no header or footer spacing is reserved
+```
+
+### Root — hasError
+
+```gherkin
+Scenario: Default border
+  Given a Card with hasError unset (or false)
+  When the card renders
+  Then the root border uses the on-surface-border token
+
+Scenario: Error border
+  Given a Card with hasError set to true
+  When the card renders
+  Then the root border uses the on-surface-border-error token
+  And the header divider and text colors are unchanged
+```
+
+### Header — title & description
+
+```gherkin
+Scenario: Default title
+  Given a CardHeader with no title prop
+  When the header renders
+  Then the title reads "Title"
+
+Scenario: Description hidden by default
+  Given a CardHeader with a description prop but hasDescription unset
+  When the header renders
+  Then the description text does not appear
+
+Scenario: Description shown
+  Given a CardHeader with a description prop and hasDescription set to true
+  When the header renders
+  Then the description appears below the title
+```
+
+### Header — drag handle
+
+```gherkin
+Scenario: Drag handle hidden by default
+  Given a CardHeader with isDraggable unset
+  When the header renders
+  Then no drag handle appears
+
+Scenario: Drag handle shown
+  Given a CardHeader with isDraggable set to true
+  When the header renders
+  Then a grip icon appears at the start of the header
+  And it carries the accessible name from dragHandleLabel (default "Reorder")
+```
+
+### Header — switch
+
+```gherkin
+Scenario: Switch shown and toggled
+  Given a CardHeader with isSwitchable set to true
+  When the user activates the switch
+  Then onSwitchCheckedChange fires with the new checked value
+```
+
+### Header — avatar
+
+```gherkin
+Scenario: Default avatar
+  Given a CardHeader with hasAvatar set to true and no avatar override
+  When the header renders
+  Then an avatar with avatarLabel's initials appears before the title
+
+Scenario: Custom avatar
+  Given a CardHeader with hasAvatar set to true and an avatar override
+  When the header renders
+  Then the provided avatar node renders instead of the default initials avatar
+```
+
+### Header — rename
+
+```gherkin
+Scenario: Rename button shown and activated
+  Given a CardHeader with hasRename set to true and an onRename handler
+  When the user activates the rename button
+  Then onRename fires
+```
+
+### Header — extras & actions
+
+```gherkin
+Scenario: Extras render next to the title
+  Given a CardHeader with an extras node
+  When the header renders
+  Then the extras node appears immediately after the title (and rename button, if shown)
+
+Scenario: Actions render at the end of the header
+  Given a CardHeader with an actions node
+  When the header renders
+  Then the actions node appears at the end of the header row
+```
+
+### Header — collapsible
+
+```gherkin
+Scenario: Collapse trigger hidden by default
+  Given a CardHeader with isCollapsible unset
+  When the header renders
+  Then no collapse trigger appears
+
+Scenario: Collapse trigger has no effect outside a collapsible AccordionContainer
+  Given a CardHeader with isCollapsible set to true, rendered with no
+    ancestor AccordionContainer
+  When the header renders
+  Then no collapse trigger appears
+
+Scenario: Collapse trigger shown and operated inside a collapsible AccordionContainer
+  Given a Card composed as: AccordionContainer(collapsible) wrapping a
+    CardHeader with isCollapsible set to true, and an AccordionContainer.Content
+    wrapping CardContent/CardFooter
+  When the user activates the collapse trigger
+  Then the AccordionContainer's onOpenChange fires with the new open value
+  And AccordionContainer.Content's children (CardContent, CardFooter) are
+    hidden when closed and shown when open
+  And the header itself remains visible in both states
+```
+
+### Pass-through
+
+```gherkin
+Scenario: Native attributes pass through
+  Given a Card with an id, data-* attribute, and aria-label
+  When the card renders
+  Then those attributes appear on the root element
+```
+
+```gherkin
+Scenario: A custom className is merged, not replaced
+  Given a Card with className="w-[350px]"
+  When the card renders
+  Then the root carries both "w-[350px]" and the card's base classes
+```
+
+### Polymorphism
+
+```gherkin
+Scenario: Rendering the root as a semantic element
+  Given a Card with render={<article />}
+  When the card renders
+  Then it renders as an <article> element
+  And it keeps the card's surface classes
+```
+
+## Accessibility
+
+Card is a presentational grouping container plus a header that composes real
+interactive controls (switch, rename button). Accessibility is partly a
+function of how the card is composed and partly built into `CardHeader`'s
+own controls.
+
+## Roles & semantics
+
+- The root is a generic `<div>` with no role by default. If the card
+  represents a meaningful standalone region, render it as a landmark/section
+  via the `render` prop (e.g. `render={<section aria-labelledby="…" />}`) so
+  assistive tech can navigate to it.
+- `CardHeader`'s title renders as a `<p>` by default, which has **no heading
+  semantics**. When the title is the heading of a content region, wrap the
+  card in a landmark and label it via `aria-labelledby` pointing at an
+  external heading, or render the root itself with an appropriate
+  `aria-label`.
+- The drag handle icon is decorative artwork with an accessible name (via the
+  icon's `title` prop, driven by `dragHandleLabel`) — it is not itself
+  operable; drag-and-drop keyboard/pointer behavior is the consumer's
+  responsibility (e.g. wiring `dnd-kit`/`@dnd-kit/sortable`'s listeners onto
+  the header or handle).
+
+## Keyboard
+
+- Card itself is not interactive and is not in the tab order.
+- The header switch (`isSwitchable`) is a real Base UI `Switch` — reachable by
+  Tab and toggled with Space, per its own component contract.
+- The rename button (`hasRename`) is a real `ButtonIconInput` — reachable by
+  Tab and activated with Enter/Space.
+- The collapse trigger (`isCollapsible`, composed with `AccordionContainer`)
+  is a real Base UI `Collapsible.Trigger` — reachable by Tab and activated
+  with Enter/Space; ARIA `aria-expanded`/`aria-controls` wiring is owned by
+  `AccordionContainer`, not Card.
+- Interactive children placed in `content` or `footer` retain their own
+  keyboard behavior and focus order — Card does not trap, reorder, or
+  intercept focus.
+
+## Screen reader
+
+- The switch, rename button, and collapse trigger each require an accessible
+  name: `switchLabel` (default `"Toggle card"`), `renameLabel` (default
+  `"Rename"`), and `collapseLabel` (default `"Collapse card"`) — override all
+  three with copy specific to what the card represents (e.g. `"Enable
+policy"`, `"Rename policy"`, `"Toggle backup policy"`) so they read
+  distinctly when more than one appears in the same header.
+- The default avatar (`hasAvatar`) renders initials as visible text
+  (`avatarLabel`); provide a full-word label via a wrapping `aria-label` if
+  the initials alone aren't a sufficient description.
+- With no landmark role on the root, the card's children are announced inline
+  in reading order.
+
+## Contrast
+
+- Title and body text use `--ui-text-on-surface-primary`; the description
+  uses `--ui-text-on-surface-secondary` — both against
+  `--ui-background-surface-primary`. These token pairings meet WCAG AA in
+  both light and dark themes.
+- The 1px border uses `--ui-border-on-surface-border` (or
+  `--ui-border-on-surface-border-error` when `hasError` is set) — border
+  contrast is decorative, not a text-contrast requirement.

package/dist/llms/carousel-dialog.md

@@ -0,0 +1,156 @@
+# CarouselDialog
+
+> The control row inside a `DialogFooterCarousel`: a `Back` button (hidden on the first slide), a dot slide indicator, and a `Next`/call-to-action button. Pure controls — no Embla import; the slide count/index/callbacks are threaded down from `DialogWelcome`, which owns the carousel engine. Deliberately NOT exported from `@acronis-platform/ui-react`'s public entry point — it is an internal primitive consumed only by `DialogFooterCarousel`. Apps building a welcome/onboarding carousel dialog should use `DialogWelcome` instead.
+
+**Status:** draft · **Category:** layout · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { CarouselDialog } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<CarouselDialog
+  variant="middle"
+  slideCount={3}
+  selectedIndex={1}
+  onSelectIndex={setSelectedIndex}
+  onBack={() => embla.scrollPrev()}
+  onNext={() => embla.scrollNext()}
+/>
+```
+
+The control row inside a `DialogFooterCarousel`: a `Back` button, a dot slide
+indicator, and a `Next`/call-to-action button. Pure controls with no Embla
+import of its own; the slide count/index/callbacks are threaded down from
+`DialogWelcome`, which owns the carousel engine.
+
+## When to use
+
+- Inside `DialogFooterCarousel`, which supplies the themed footer bar around
+  this row. Not meant to be used standalone.
+
+## When not to use
+
+- A standalone content carousel with no dialog footer chrome.
+- A dialog's ordinary action row (Cancel/Save) — use `DialogFooterDefault`.
+
+## Parts
+
+| Part          | Description                                                           |
+| ------------- | --------------------------------------------------------------------- |
+| boxLeft       | `Back` button. Hidden on the first slide (`variant="first"`).         |
+| listIndicator | One dot per slide; clicking a dot jumps to that slide.                |
+| boxRight      | `Next` (first/middle slide) or the call-to-action label (last slide). |
+
+## Example
+
+```tsx
+import { CarouselDialog } from '@acronis-platform/ui-react';
+
+<CarouselDialog
+  variant="middle"
+  slideCount={3}
+  selectedIndex={1}
+  onSelectIndex={setSelectedIndex}
+  onBack={() => embla.scrollPrev()}
+  onNext={() => embla.scrollNext()}
+/>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'first' | 'middle' | 'last'` | `'first'` | no | Which slide position this renders for. |
+| `slideCount` | `number` | `1` | no | Total number of slides, used to render the dot indicator. |
+| `selectedIndex` | `number` | `0` | no | The currently active slide index (0-based). |
+| `backLabel` | `string` | `'Back'` | no | `Back` button label. |
+| `nextLabel` | `string` | `'Next'` | no | `Next` button label (`variant="first" | "middle"`). |
+| `primaryLabel` | `string` | `'Call to action'` | no | Call-to-action button label (`variant="last"`). |
+| `goToSlideLabel` | `(index: number, count: number) => string` | — | no | Builds each dot's accessible name from its 0-based index and the slide count. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `select-index` | `number` | Fired when a dot is activated, with its slide index (React `onSelectIndex`). |
+| `back` | `undefined` | Fired when `Back` (hidden on `variant="first"`) is activated (React `onBack`). |
+| `next` | `undefined` | Fired when `Next` (`variant="first" | "middle"`) is activated (React `onNext`). |
+| `primary-action` | `undefined` | Fired when the call-to-action button (`variant="last"`) is activated (React `onPrimaryAction`). |
+
+## Behavior
+
+CarouselDialog is a pure function of its props — no internal state. The
+carousel engine (which slide is active, how to move between slides) lives in
+the caller — typically `DialogWelcome`'s Embla instance, threaded through
+`DialogFooterCarousel` — which passes `slideCount`/`selectedIndex` in and
+receives `onSelectIndex`/`onBack`/`onNext`/`onPrimaryAction` back out.
+
+```gherkin
+Scenario: First slide (variant="first")
+  Given a CarouselDialog with variant="first"
+  Then `Back` is not rendered
+  And `Next` is rendered in boxRight
+  And the dot indicator marks the first dot active
+```
+
+```gherkin
+Scenario: A middle slide (variant="middle")
+  Given a CarouselDialog with variant="middle"
+  Then `Back` is rendered in boxLeft
+  And `Next` is rendered in boxRight
+```
+
+```gherkin
+Scenario: The last slide (variant="last")
+  Given a CarouselDialog with variant="last"
+  Then `Back` is rendered in boxLeft
+  And the call-to-action label (default "Call to action") replaces `Next` in boxRight
+```
+
+```gherkin
+Scenario: Jumping to an arbitrary slide
+  Given a CarouselDialog with slideCount=3
+  When a dot other than the active one is activated
+  Then onSelectIndex fires with that dot's 0-based index
+  And the caller is responsible for actually moving the carousel and passing
+    back an updated `variant`/`selectedIndex`
+```
+
+```gherkin
+Scenario: A single-slide carousel
+  Given a CarouselDialog with slideCount=1
+  Then only one dot renders, always active
+  And the caller is responsible for choosing variant="last" for that single
+    slide (it is both the first and the last), so the call-to-action button
+    is reachable
+```
+
+## Accessibility
+
+- `Back`, `Next`, and the call-to-action control render as real `Button`
+  elements — native focus, keyboard activation (Enter/Space), and the
+  Button's own accessible name (its label) come for free.
+- Each dot in the indicator is a real `<button>` with an explicit
+  `aria-label` (default `"Go to slide N of M"`, overridable via
+  `goToSlideLabel`) — dots are never bare, unlabeled `<div>`s. The active dot
+  carries `aria-current="true"`. Dots have their own `focus-visible` ring
+  (`--ui-focus-primary`), matching the kit's other raw-`<button>` controls
+  (e.g. `Pagination`, `Tabs`).
+- CarouselDialog is a plain layout container — no landmark role of its own.
+  It's meant to live inside `DialogFooterCarousel` inside a dialog (e.g.
+  `DialogWelcome`), which owns the `role="dialog"` / focus-trap semantics.
+- Focus order follows DOM order: `Back` (when present) → dots → `Next`/
+  call-to-action.
+
+## Contrast
+
+The active dot uses `--ui-glyph-on-surface-primary`; inactive dots use
+`--ui-glyph-on-surface-disabled`. Both are guaranteed to meet contrast against
+the footer's own background in both light and dark (shared semantic
+glyph/surface pairing) — the same tokens `Breadcrumb`'s separator icon and
+`Switch`'s track use for the equivalent idle/disabled distinction.