@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/llms/accordion-container.md

@@ -0,0 +1,181 @@
+# AccordionContainer
+
+> The shared disclosure primitive behind Card's and Section's `isCollapsable` variant. Built directly on Base UI's Collapsible — owns open state, the trigger button, chevron rotation, and panel animation — while imposing no visual styling beyond what the disclosure mechanic itself requires — the two exceptions are its trigger's chevron glyph color (the same neutral treatment Accordion's chevron uses) and, when `collapsible` is true, Root defaulting to `display: contents` so it stays transparent to the consumer's layout. Every other visual decision (header layout, spacing, background, borders) stays owned by the component composing it.
+
+**Status:** draft · **Category:** layout · **Since:** v1.1.0
+
+## Import
+
+```tsx
+import { AccordionContainer } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<AccordionContainer collapsible defaultOpen>
+  {({ open }) => (
+    <>
+      <div className="flex items-center justify-between">
+        <span>Title</span>
+        <AccordionContainer.Trigger />
+      </div>
+      <AccordionContainer.Content>
+        {open && <p>Body content</p>}
+      </AccordionContainer.Content>
+    </>
+  )}
+</AccordionContainer>
+```
+
+The shared disclosure primitive behind Card's and Section's `isCollapsable`
+variant. Owns open state, the trigger button, chevron rotation, and panel
+animation — nothing else. It never imposes visual styling beyond what the
+disclosure mechanic itself requires: no padding/background/border on `Root` or
+`Content`, no position/hover opinion on `Trigger` beyond the chevron's glyph
+color (the same neutral treatment Accordion's chevron uses). Every other
+visual decision (header layout, spacing, background, borders) stays owned by
+the component composing it.
+
+> **Status: draft.** No single Figma node maps 1:1 to this component — it's a
+> generic primitive factored out of Card's and Section's confirmed
+> `isCollapsable` contract (Figma file `lrU3ydIyvPYQNE6ixdsKtJ`, node
+> `10561:83806`). No Figma Code Connect file exists for this reason.
+
+## When to use
+
+- Composing a disclosure (expand/collapse) mechanic into your own component's
+  header layout, where you control the header's spacing, borders, and which
+  content varies by state.
+
+## When not to use
+
+- A standalone, generically-styled disclosure with no host component — use
+  **`Collapsible`** directly.
+- A vertical set of mutually-exclusive disclosure sections — use
+  **`Accordion`**.
+
+## Parts
+
+| Export                       | Purpose                                                                                                                                       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AccordionContainer`         | Root — holds the open state. Renders no wrapping element when `collapsible` is false, unless a ref/className/style/render/DOM prop is passed. |
+| `AccordionContainer.Trigger` | Toggles the panel; renders a rotating chevron with a default `aria-label`. Renders nothing when not collapsible.                              |
+| `AccordionContainer.Content` | The height-animating panel. Renders children unwrapped when not collapsible, with the same wrapper exception as Root.                         |
+
+## Example
+
+```tsx
+import { AccordionContainer } from '@acronis-platform/ui-react';
+
+function CollapsibleCard({ collapsible, title, children }) {
+  return (
+    <AccordionContainer collapsible={collapsible} defaultOpen>
+      {({ open }) => (
+        <>
+          <div className="flex items-center justify-between border-b p-4">
+            <span className="font-medium">{title}</span>
+            <AccordionContainer.Trigger
+              aria-label={open ? 'Collapse' : 'Expand'}
+              className="size-8 rounded-md hover:bg-[var(--ui-background-surface-hover)]"
+            />
+          </div>
+          <AccordionContainer.Content>
+            <div className="p-4">{children}</div>
+          </AccordionContainer.Content>
+        </>
+      )}
+    </AccordionContainer>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `collapsible` | `boolean` | `false` | no | Whether the disclosure exists at all. When false, `children` render directly with no trigger and no panel wrapper. |
+| `open` | `boolean` | — | no | Whether the panel is open (controlled). No trigger or panel renders when collapsible is false, but the value is still tracked internally and exposed via the `children` render-prop's `{ open }` state. |
+| `defaultOpen` | `boolean` | `false` | no | Whether the panel is initially open (uncontrolled). No trigger or panel renders when collapsible is false, but the value still seeds the internal state exposed via the `children` render-prop's `{ open }` state. |
+| `disabled` | `boolean` | `false` | no | Disables the trigger. Ignored when collapsible is false. |
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop on the root — replaces the rendered element while merging props and classes. When collapsible is false the root renders no wrapping element unless a ref, className, style, render, or other DOM prop is supplied — in which case it wraps children in a plain `div` so none of those are silently dropped. React-only; other frameworks use their own polymorphism. |
+| `children` | `ReactNode | ((state: { open: boolean }) => ReactNode)` | — | no | The composed content — typically a trigger placed by the consumer's own header layout plus a `Content` panel. May also be a function receiving the current `{ open }` state, for content outside `Content` that needs to vary by state even when this component owns the open state itself (uncontrolled). Not needed when the consumer already controls `open` — it already has the value in scope. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onOpenChange` | `(open: boolean, eventDetails) => void` | Fired when the open state changes. Ignored when collapsible is false. |
+
+## Behavior
+
+```gherkin
+Scenario: Not collapsible
+  Given an AccordionContainer with collapsible=false
+  When it renders
+  Then no Trigger renders
+  And Content renders its children directly, with no panel wrapper
+```
+
+```gherkin
+Scenario: Toggle (uncontrolled)
+  Given a collapsible AccordionContainer with a Trigger and Content
+  When the user activates the Trigger
+  Then the Content panel animates open (and closed on the next activation)
+  And the Trigger's chevron rotates 90° to reflect the open state
+```
+
+```gherkin
+Scenario: Initially open (uncontrolled)
+  Given collapsible is true and defaultOpen is set
+  Then the panel renders open on mount
+```
+
+```gherkin
+Scenario: Controlled
+  Given collapsible is true, open is passed explicitly, and onOpenChange is provided
+  When the user activates the Trigger
+  Then AccordionContainer does not change its own open state
+  And onOpenChange fires with the next open value
+  And the panel only reflects the new state once the consumer updates `open`
+```
+
+```gherkin
+Scenario: Render-prop children receive the open state
+  Given a collapsible AccordionContainer whose children is a function
+  When the panel's open state changes (controlled or uncontrolled)
+  Then the function is called with the current { open } value
+  And content outside Content (e.g. a header) can vary based on it
+```
+
+## Accessibility
+
+- Built on Base UI's Collapsible when `collapsible` is true: the trigger is a
+  `<button>` with `aria-expanded` and `aria-controls` pointing at the panel,
+  toggled with Enter/Space. Focus stays on the trigger.
+- The trigger renders only an icon (no text). It falls back to
+  `aria-label="Toggle"` when the consumer supplies neither `aria-label` nor
+  `aria-labelledby`, so the default rendering always has an accessible name —
+  but the consumer composing it into a header should still override it (e.g.
+  `aria-labelledby` pointing at the surrounding heading/title) for a
+  meaningful name.
+- When `collapsible` is false there is no interactive element at all — content
+  renders as if there were no disclosure.
+
+## Keyboard
+
+- Enter/Space toggles the trigger when focused.
+- No other keyboard behavior is added; focus order follows source order.
+
+## Screen reader
+
+- The trigger's `aria-expanded` state is announced on toggle. The panel's
+  content is only reachable via normal document flow (no `aria-hidden`
+  toggling beyond what Base UI's Collapsible manages internally).
+
+## Contrast
+
+The trigger's chevron uses `--ui-glyph-on-surface-neutral-dark`, which meets
+WCAG AA against a surface background in both light and dark themes.
+AccordionContainer adds no other color; contrast for everything else is
+governed by whatever the consumer places inside it.

package/dist/llms/accordion.md

@@ -0,0 +1,124 @@
+# Accordion
+
+> A vertical set of disclosure sections — each with a header trigger and a height-animating panel; single or multiple open at once. Built on Base UI's Accordion. Ported from the legacy shadcn-uikit `accordion`.
+
+**Status:** draft · **Category:** layout · **Since:** v0.49.0
+
+## Import
+
+```tsx
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Accordion>
+  <AccordionItem value="a">
+    <AccordionTrigger>Section</AccordionTrigger>
+    <AccordionContent>Content</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+A vertical set of disclosure sections — each a header trigger over a
+height-animating panel. Single open at a time by default; `multiple` allows
+several. Built on Base UI's Accordion.
+
+> Design-pending v1, ported from the legacy shadcn-uikit `accordion`.
+
+## When to use
+
+- Condense a long page into expandable sections (e.g. an FAQ, grouped settings).
+
+## When not to use
+
+- A single optional section — use `Collapsible`.
+- Navigating between views — use `Tabs`.
+
+## Parts
+
+| Export             | Purpose                                             |
+| ------------------ | --------------------------------------------------- |
+| `Accordion`        | Root — tracks open items; `multiple` to allow many. |
+| `AccordionItem`    | One section (needs a `value`).                      |
+| `AccordionTrigger` | The header button (title + chevron).                |
+| `AccordionContent` | The height-animating panel.                         |
+
+## Example
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@acronis-platform/ui-react';
+
+<Accordion defaultValue={['a']}>
+  <AccordionItem value="a">
+    <AccordionTrigger>What is included?</AccordionTrigger>
+    <AccordionContent>Backup, recovery, and anti-malware.</AccordionContent>
+  </AccordionItem>
+</Accordion>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `Value[]` | — | no | The open item value(s) (controlled). |
+| `defaultValue` | `Value[]` | — | no | The initially open item value(s) (uncontrolled). |
+| `multiple` | `boolean` | `false` | no | Whether multiple items can be open at the same time. |
+| `disabled` | `boolean` | `false` | no | Disables all items. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onValueChange` | `(value: Value[], eventDetails) => void` | Fired when the set of open items changes. |
+
+## Behavior
+
+```gherkin
+Scenario: Expand a section
+  Given an Accordion with items
+  When the user clicks a section's trigger
+  Then its panel animates open and the chevron rotates
+```
+
+```gherkin
+Scenario: Single (default)
+  Given the default (single) mode
+  When the user opens another section
+  Then the previously open section closes
+```
+
+```gherkin
+Scenario: Multiple
+  Given multiple is set
+  When the user opens several sections
+  Then they all stay open until individually toggled
+```
+
+```gherkin
+Scenario: Initially open
+  Given defaultValue lists item value(s)
+  Then those sections render open on mount
+```
+
+## Accessibility
+
+- Built on Base UI's Accordion: each trigger sits in an `Accordion.Header`
+  (heading role) and is a `<button>` with `aria-expanded` / `aria-controls`; the
+  panel is associated back via `aria-labelledby`. Arrow keys move between headers,
+  Enter/Space toggles, and Home/End jump to the first/last.
+- The chevron rotation is decorative — the open state is conveyed by
+  `aria-expanded`, so don't rely on the icon alone.
+- Give each trigger a clear, distinct label.
+
+## Contrast
+
+The divider (`--ui-border-on-surface-border`) and the muted chevron/panel text
+(`--ui-text-on-surface-secondary`) meet contrast in light and dark; trigger labels
+inherit the foreground.

package/dist/llms/alert.md

@@ -0,0 +1,225 @@
+# Alert
+
+> An inline status banner: a neutral surface carrying its severity through a status-colored border and a status line down the leading edge, with a fixed status icon per severity, composable title / description / action parts, and an optional dismiss control.
+
+**Status:** stable · **Category:** feedback · **Since:** v0.48.0
+
+## Import
+
+```tsx
+import { Alert, AlertIcon, AlertContent, AlertText, AlertTitle, AlertDescription, AlertActions, AlertClose } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Alert variant="danger">
+  <AlertIcon />
+  <AlertContent>
+    <AlertText>
+      <AlertTitle>Session expired</AlertTitle>
+      <AlertDescription>Sign in again to keep working.</AlertDescription>
+    </AlertText>
+    <AlertActions>
+      <Button variant="secondary">Sign in</Button>
+    </AlertActions>
+  </AlertContent>
+  <AlertClose onClick={dismiss} />
+</Alert>
+```
+
+An inline status banner. The surface is neutral in every severity; the severity
+is carried by a status-colored border and a 6px status line down the leading
+edge, plus a fixed icon per severity.
+
+## When to use
+
+- Surface a contextual status message (info, success, warning, critical, danger)
+  inline on a page or in a panel, where it stays until the condition changes or
+  the user dismisses it.
+- Give the user something to do about it — `AlertActions` is the intended place
+  for the remedy.
+
+## When not to use
+
+- Transient, auto-dismissing notifications — use `Toast`.
+- A blocking confirmation — use `Dialog`.
+- A page-wide, top-anchored announcement bar — that's `AlertRibbon`.
+- A field-level validation message — that belongs on the input.
+
+## Severity
+
+| Variant    | Icon                    | Use for                                        |
+| ---------- | ----------------------- | ---------------------------------------------- |
+| `info`     | `CircleInfoBlue`        | Neutral context the user should notice.        |
+| `success`  | `CircleCheckGreen`      | An operation completed.                        |
+| `warning`  | `TriangleWarningYellow` | Something needs attention soon.                |
+| `critical` | `CircleWarningOrange`   | Something is degraded and needs attention now. |
+| `danger`   | `DiamondWarningRed`     | A failure or destructive condition.            |
+
+## Parts
+
+| Export             | Purpose                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| `Alert`            | The banner root (`role="alert"`) + `variant`.                                         |
+| `AlertIcon`        | The leading status icon — defaults to the variant's own glyph.                        |
+| `AlertContent`     | The column beside the icon.                                                           |
+| `AlertText`        | Wraps the title + description; its padding aligns the first line with the icon.       |
+| `AlertTitle`       | A short heading.                                                                      |
+| `AlertDescription` | Optional supporting text.                                                             |
+| `AlertActions`     | Optional wrapping row of action buttons, inside `AlertContent` after `AlertText`.     |
+| `AlertClose`       | Optional trailing dismiss control — rendering it is what makes the alert dismissable. |
+
+Keep the title and description inside `AlertText` rather than directly under
+`AlertContent`: `AlertText`'s vertical padding is what keeps the first line of
+text aligned with the icon box.
+
+## Example
+
+```tsx
+import {
+  Alert,
+  AlertActions,
+  AlertClose,
+  AlertContent,
+  AlertDescription,
+  AlertIcon,
+  AlertText,
+  AlertTitle,
+  Button,
+} from '@acronis-platform/ui-react';
+
+<Alert variant="danger">
+  <AlertIcon />
+  <AlertContent>
+    <AlertText>
+      <AlertTitle>Session expired</AlertTitle>
+      <AlertDescription>Sign in again to keep working.</AlertDescription>
+    </AlertText>
+    <AlertActions>
+      <Button variant="secondary">Sign in</Button>
+    </AlertActions>
+  </AlertContent>
+  <AlertClose onClick={dismiss} />
+</Alert>;
+```
+
+A title-only, non-dismissable alert is just the parts you keep:
+
+```tsx
+<Alert variant="success">
+  <AlertIcon />
+  <AlertContent>
+    <AlertText>
+      <AlertTitle>Your changes were saved</AlertTitle>
+    </AlertText>
+  </AlertContent>
+</Alert>
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'info' | 'success' | 'warning' | 'critical' | 'danger'` | `'info'` | no | Severity. Sets the border color, the leading status-line color, and the default status icon. The surface stays neutral in every severity. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `children` | The composed parts — AlertIcon, AlertContent (AlertText wrapping AlertTitle / AlertDescription, optionally AlertActions), and AlertClose. |
+
+## Behavior
+
+```gherkin
+Scenario: Announce a status
+  Given an Alert with a title and description
+  Then it renders with role="alert" so assistive tech announces it
+```
+
+```gherkin
+Scenario: Severity variant
+  Given variant="success" (or info / warning / critical / danger)
+  Then the container border and the leading status line take that severity's color
+  And the surface stays neutral, identical across every severity
+  And AlertIcon renders that severity's own icon
+```
+
+```gherkin
+Scenario: Override the status icon
+  Given an AlertIcon with children
+  Then the supplied glyph replaces the variant's default icon
+```
+
+```gherkin
+Scenario: Title-only alert
+  Given an AlertText containing only an AlertTitle
+  Then the title's first line stays aligned with the status icon
+```
+
+```gherkin
+Scenario: Actions below the text
+  Given an AlertActions inside AlertContent, after AlertText
+  Then the buttons flow below the description
+  And the row wraps onto further lines when it runs out of width
+```
+
+```gherkin
+Scenario: Dismiss
+  Given an AlertClose with an onClick handler
+  When the control is activated by pointer or keyboard
+  Then the handler fires and the consumer removes the alert
+  # The component never removes itself — visibility is the consumer's state.
+```
+
+```gherkin
+Scenario: Not dismissable
+  Given an Alert with no AlertClose
+  Then no dismiss control renders and the content column takes that width
+```
+
+```gherkin
+Scenario: Right-to-left
+  Given dir="rtl" on an ancestor
+  Then the status line sits on the right edge and the dismiss control on the left
+  And the status icons are not mirrored (they are direction-agnostic)
+```
+
+## Accessibility
+
+- The root carries `role="alert"`, so screen readers announce its content when it
+  appears. Use it for important, time-sensitive messages; for non-urgent status,
+  pass `role="status"` so it is announced politely instead of assertively.
+- `role="alert"` implies `aria-live="assertive"`, which interrupts the user. Do
+  not render a batch of alerts at once, and do not re-mount one on every keystroke.
+- Don't rely on color alone to signal severity. Each variant pairs its color with
+  a distinct icon **shape** (circle-info, circle-check, triangle, circle-warning,
+  diamond) and the title text carries the meaning in words.
+- The status icons are decorative — the title and description carry the message —
+  so they contribute no accessible name. Supply your own labelled glyph via
+  `AlertIcon` children if it conveys something the text doesn't.
+
+## Keyboard
+
+| Key               | Action                                                                     |
+| ----------------- | -------------------------------------------------------------------------- |
+| `Tab`             | Moves through the action buttons, then the dismiss control (source order). |
+| `Enter` / `Space` | Activates the focused action or dismiss control.                           |
+
+The banner itself is not focusable — only its controls are.
+
+## Screen reader
+
+- The whole banner's text is announced on insertion, so keep the title short and
+  put detail in the description.
+- `AlertClose` needs an accessible name; it defaults to `"Close"` and is
+  overridable via the `ariaLabel` prop for localization.
+
+## Contrast
+
+Text sits on the neutral surface (`--ui-alert-global-container-background`) using
+the shared title/description colors, so contrast does not vary by severity. The
+severity colors are used only on the border and the status line — both
+non-text, so they are held to the 3:1 non-text contrast requirement rather than
+4.5:1. The status line's 6px width also makes severity distinguishable without
+reading color at all.