@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/scroll-area.md

@@ -0,0 +1,183 @@
+# ScrollArea
+
+> A scrollable region with a custom overlay scrollbar built on the Base UI Scroll Area primitive. The bar floats over the content and reserves no layout space, so full-bleed content is never cropped by a scrollbar gutter, on every OS and browser. The bar is revealed on hover/scroll and hidden at rest. Ported from the legacy shadcn-uikit `ScrollArea`.
+
+**Status:** draft · **Category:** layout · **Since:** v0.53.0
+
+## Import
+
+```tsx
+import { ScrollArea, ScrollBar } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<ScrollArea className="h-72">
+  {longContent}
+</ScrollArea>
+<ScrollArea orientation="both" className="h-72 w-96">
+  {wideTallContent}
+</ScrollArea>
+```
+
+A scrollable region with a custom **overlay** scrollbar built on the Base UI
+Scroll Area primitive. The bar floats over the content and reserves **no**
+layout space, so full-bleed content is never cropped by a scrollbar gutter — on
+every OS and browser, not just where the platform happens to provide overlay
+scrollbars. It is hidden at rest and revealed on hover/scroll.
+
+> Design-pending v1: ported from the legacy shadcn-uikit `ScrollArea`. No Figma
+> node yet; reconcile with `/figma-component ScrollArea <url> --update` once a
+> design lands.
+
+## When to use
+
+- A fixed-height (or fixed-width) region whose content can overflow — sidebars,
+  menus, popovers, lists, code blocks, image strips.
+- Anywhere a native `overflow: auto` scrollbar's **reserved gutter** would crop
+  edge-to-edge content (e.g. a sidebar's full-width selected row) or shift the
+  layout when the scrollbar appears.
+
+## When not to use
+
+- Page-level / document scrolling — let the browser own that.
+- Very large/virtualized data sets — pair a virtualizer with the viewport, or
+  use a component designed for virtualization.
+
+## Examples
+
+```tsx
+import { ScrollArea } from '@acronis-platform/ui-react';
+
+<ScrollArea className="h-72 w-64 rounded-md border border-border">
+  {longList}
+</ScrollArea>;
+```
+
+```tsx
+// Both axes (renders the corner too)
+<ScrollArea orientation="both" className="h-72 w-96">
+  {wideTallContent}
+</ScrollArea>
+```
+
+```tsx
+// Compose the parts directly for custom scrollbar placement
+import { ScrollArea, ScrollBar } from '@acronis-platform/ui-react';
+
+<ScrollArea orientation="horizontal">
+  {row}
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>;
+```
+
+## Parts
+
+| Part         | Element | Notes                                                         |
+| ------------ | ------- | ------------------------------------------------------------- |
+| `ScrollArea` | `div`   | Root + viewport + content + built-in scrollbar(s) (+ corner). |
+| `ScrollBar`  | `div`   | Standalone overlay scrollbar (track + thumb); `orientation`.  |
+
+## Props
+
+- `orientation` — `'vertical'` (default) · `'horizontal'` · `'both'`. Selects
+  the built-in scrollbar(s); `'both'` also renders the corner.
+- All other props pass through to the Base UI `ScrollArea.Root`.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `orientation` | `'vertical' | 'horizontal' | 'both'` | `'vertical'` | no | Which scrollbar(s) the all-in-one `ScrollArea` renders. `both` also renders the corner. For finer control, compose the exported `ScrollBar` part directly. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `children` | The content to be scrolled, wrapped in the viewport/content parts. |
+
+## Behavior
+
+Given/When/Then scenarios for the scroll area.
+
+### Overlay scrollbar — no reserved gutter
+
+- **Given** content taller than the scroll area
+  **When** it renders
+  **Then** the content fills the full width of the viewport (the scrollbar
+  floats over it and reserves **no** layout space), so edge-to-edge content is
+  not cropped by a scrollbar gutter.
+
+### Reveal on hover / scroll
+
+- **Given** a scrollable area at rest
+  **Then** the scrollbar is hidden (opacity 0).
+- **When** the pointer hovers the area, or the viewport is scrolled
+  **Then** the scrollbar fades in (driven by the primitive's `data-hovering` /
+  `data-scrolling` state), and fades back out when the interaction ends.
+
+### Orientation
+
+- **Given** `orientation="vertical"` (default)
+  **Then** only a vertical scrollbar is rendered.
+- **Given** `orientation="horizontal"`
+  **Then** only a horizontal scrollbar is rendered.
+- **Given** `orientation="both"`
+  **Then** both scrollbars are rendered plus the corner that fills the gap where
+  they meet.
+
+### Dragging the thumb
+
+- **When** the user presses and drags the thumb
+  **Then** the viewport scrolls proportionally; the thumb darkens
+  (`--ui-border-on-surface-border-active`) on hover.
+
+### Keyboard
+
+- **Given** the viewport is focused
+  **When** the user presses arrow keys / Page Up / Page Down / Home / End
+  **Then** the viewport scrolls accordingly (native scrolling on the focusable
+  viewport).
+
+## Accessibility
+
+## Roles & semantics
+
+- The parts are plain `<div>`s; the component adds no landmark role. The
+  scrollable **viewport** is focusable so the region is reachable and operable
+  by keyboard.
+- Content semantics are entirely the caller's — `ScrollArea` is a transparent
+  scroll container around arbitrary children.
+
+## Keyboard
+
+| Key                          | Action                     |
+| ---------------------------- | -------------------------- |
+| `Tab`                        | Move focus to the viewport |
+| `Arrow Up` / `Arrow Down`    | Scroll vertically          |
+| `Arrow Left` / `Arrow Right` | Scroll horizontally        |
+| `Page Up` / `Page Down`      | Scroll by a page           |
+| `Home` / `End`               | Scroll to start / end      |
+
+## Focus
+
+- The viewport shows a visible focus ring (`--ui-focus-brand`) on
+  `:focus-visible`, so keyboard users can see when the scroll region holds focus.
+
+## Screen readers
+
+- No content is hidden from assistive tech: the scrollbar and corner are
+  decorative overlays; the scrolled children remain in the normal reading order.
+
+## Pointer / motion
+
+- The scrollbar reveal is an opacity transition only (no layout shift, no
+  parallax). The thumb remains operable by mouse drag and by the native
+  scroll gestures (wheel, trackpad, touch).
+
+## Contrast
+
+- The thumb uses the shared border token at rest and a darker active token on
+  hover, both of which meet non-text contrast against the page surfaces in the
+  shipped themes.

package/dist/llms/section.md

@@ -0,0 +1,401 @@
+# Section
+
+> A titled band that groups cards — or a table — on a page. Four content layouts pick the body shape: one full-width column, a 70/30 split, a three-column card grid, or a flush table that bleeds to the page edges. The header carries a title, optional description, an optional toggle switch, inline extras, and end-aligned actions; an optional bottom divider separates one band from the next. Collapsing is a composition with `AccordionContainer`, the same as `Card`.
+
+**Status:** ready · **Category:** layout · **Since:** v3.0.0
+
+## Import
+
+```tsx
+import { Section, SectionHeader, SectionContent } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Section variant="grid3" hasBottomBorder>
+  <SectionHeader
+    title="Protection"
+    description="3 plans applied to 24 workloads."
+    hasDescription
+  />
+  <SectionContent>
+    <Card>…</Card>
+    <Card>…</Card>
+    <Card>…</Card>
+  </SectionContent>
+</Section>
+
+// A 70/30 split.
+<Section variant="column2-70-30">
+  <SectionHeader title="Storage" />
+  <SectionContent secondaryContent={<Card>…</Card>}>
+    <Card>…</Card>
+  </SectionContent>
+</Section>
+
+// Collapsible — a composition, not a prop.
+<Section>
+  <AccordionContainer collapsible defaultOpen>
+    <SectionHeader title="Protection" isCollapsible />
+    <AccordionContainer.Content>
+      <SectionContent>…</SectionContent>
+    </AccordionContainer.Content>
+  </AccordionContainer>
+</Section>
+```
+
+A titled band that groups content on a page. Where `Card` owns a single surface
+and `CardSection` divides a card's body, `Section` is the layer above both: it
+labels a run of cards — or a table — and separates it from the next run.
+
+## When to use
+
+- A page that reads as **several labelled bands** ("General", "Protection",
+  "Danger zone"), each holding one or more cards.
+- A **row of cards** that needs a shared title and a consistent three-column
+  grid (`grid3`).
+- A **primary/secondary split** where a wide main area is paired with a narrow
+  companion column (`column2-70-30`).
+- A **full-bleed table** with a page-level title above it (`table`).
+
+## When not to use
+
+- Inside a card. Use `CardSection` — it is card chrome, with the smaller 14px
+  header and the card's own inset rhythm.
+- As a bare layout wrapper with no title. Use `Stack` / `Grid`; a section with
+  no header adds a band with no meaning.
+- As a surface. `Section` paints no background of its own; the page surface
+  shows through.
+
+## Parts
+
+| Part             | Element   | Notes                                                                       |
+| ---------------- | --------- | --------------------------------------------------------------------------- |
+| `Section`        | `section` | Owns `variant` + `hasBottomBorder` and publishes the layout to its parts.   |
+| `SectionHeader`  | `div`     | Optional. Switch, title, description, extras, `children`, actions, trigger. |
+| `SectionContent` | `div`     | The body. Its layout comes from the root's `variant`.                       |
+
+## Layouts
+
+| `variant`       | Body                                                        |
+| --------------- | ----------------------------------------------------------- |
+| `column1`       | One full-width area (default).                              |
+| `column2-70-30` | 3-column grid; children span 2, `secondaryContent` spans 1. |
+| `grid3`         | 3-column grid the children flow into.                       |
+| `table`         | Flush — no root padding, so rows bleed to the page edges.   |
+
+## Examples
+
+A row of cards under one title:
+
+```tsx
+<Section variant="grid3">
+  <SectionHeader title="Recent activity" />
+  <SectionContent>
+    <Card>…</Card>
+    <Card>…</Card>
+    <Card>…</Card>
+  </SectionContent>
+</Section>
+```
+
+A 70/30 split:
+
+```tsx
+<Section variant="column2-70-30">
+  <SectionHeader
+    title="Storage"
+    description="Usage across every connected location."
+    hasDescription
+  />
+  <SectionContent secondaryContent={<QuotaCard />}>
+    <LocationsCard />
+  </SectionContent>
+</Section>
+```
+
+A full-bleed table:
+
+```tsx
+<Section variant="table">
+  <SectionHeader
+    title="Workloads"
+    actions={
+      <ButtonIcon aria-label="More actions">
+        <EllipsisIcon size={24} />
+      </ButtonIcon>
+    }
+  />
+  <SectionContent>
+    <WorkloadsTable />
+  </SectionContent>
+</Section>
+```
+
+Collapsible — a composition with the shared disclosure primitive, not a prop:
+
+```tsx
+<Section variant="grid3">
+  <AccordionContainer collapsible defaultOpen>
+    <SectionHeader
+      title="Protection"
+      isCollapsible
+      collapseLabel="Toggle protection section"
+    />
+    <AccordionContainer.Content>
+      <SectionContent>…</SectionContent>
+    </AccordionContainer.Content>
+  </AccordionContainer>
+</Section>
+```
+
+## Notes
+
+- **No bottom padding without `hasBottomBorder`.** Stacked unbordered sections
+  would otherwise double their vertical gap, since the next one already opens
+  with its own top inset. Set `hasBottomBorder` on every section but the last
+  when you want visible separators.
+- **The `table` variant is flush on purpose.** It has no padding on any side so
+  its rows reach the page edges; only the header re-applies the horizontal
+  inset. `hasBottomBorder` adds the divider without reintroducing padding.
+- **`variant` is set once, on the root.** The header and content parts read it
+  from context, so there is nothing to keep in sync.
+- **Collapsing lives in `AccordionContainer`.** `isCollapsible` only renders the
+  trigger; the open/closed state, ARIA wiring, and height animation belong to
+  the container — the same split `Card` uses.
+- **Override `collapseLabel` / `switchLabel`** whenever a page stacks several
+  collapsible or switchable sections; the defaults are generic by necessity.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'column1' | 'column2-70-30' | 'grid3' | 'table'` | `column1` | no | Root. Which content layout the section uses. `column1` is one full-width area; `column2-70-30` splits the body into a wide and a narrow column; `grid3` flows children into a three-column card grid; `table` drops the root inset entirely so a table's rows run edge-to-edge. The root publishes this to its header and content parts, so the consumer sets it in exactly one place. |
+| `hasBottomBorder` | `boolean` | `false` | no | Root. Draws a bottom divider plus the matching bottom padding, separating this band from the next one stacked below it. Without it the root reserves no bottom padding at all, because the next section opens with its own top inset. The `table` variant stays flush either way and only gains the divider. |
+| `title` | `string` | `undefined` | no | Header. The section title, at the 20px medium "headings/section" scale. Renders nothing when omitted. |
+| `description` | `string` | `undefined` | no | Header. Supporting text under the title; shown only with `hasDescription`. |
+| `hasDescription` | `boolean` | `false` | no | Header. Shows `description` below the title. |
+| `isSwitchable` | `boolean` | `false` | no | Header. Shows a toggle switch at the start of the header, for turning the whole grouping on or off. |
+| `switchChecked` | `boolean` | `undefined` | no | Header. Controlled checked state of the header switch. |
+| `defaultSwitchChecked` | `boolean` | `undefined` | no | Header. Uncontrolled initial checked state of the header switch. |
+| `switchDisabled` | `boolean` | `undefined` | no | Header. Disables the header switch. |
+| `switchLabel` | `string` | `Toggle section` | no | Header. Accessible label for the header switch. |
+| `extras` | `ReactNode` | `undefined` | no | Header. Content rendered inline next to the title (e.g. a tag). |
+| `actions` | `ReactNode` | `undefined` | no | Header. Actions rendered at the end of the header row. |
+| `isCollapsible` | `boolean` | `false` | no | Header. Renders the disclosure trigger at the end of the header. Only has an effect inside a collapsible `AccordionContainer`, which owns the open/closed state. |
+| `collapseLabel` | `string` | `Collapse section` | no | Header. Accessible label for the collapse trigger. |
+| `secondaryContent` | `ReactNode` | `undefined` | no | Content. The narrow (~30%) second column of the `column2-70-30` layout. Ignored by every other variant, which has a single content area. |
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop — replaces the rendered element with another component while merging props and classes. Available on every part. React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `switch-checked-change` | `boolean` | Header. Fires when the header switch is toggled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | On the root, the section's parts (header, content). On the header, an additional slot rendered after the title/description block and before `actions` — used to supply a custom heading element (see accessibility.md). On the content part, the body itself — the wide column under `column2-70-30`, the grid items under `grid3`, and everything under `column1` / `table`. |
+
+## Behavior
+
+### Choosing a content layout
+
+**Given** a `Section` with no `variant`
+**When** it renders
+**Then** it uses `column1`: the content part is one full-width area with no
+imposed grid.
+
+**Given** `variant="column2-70-30"`
+**When** it renders
+**Then** the content part is a three-column grid; the children span two columns
+(~70%) and `secondaryContent` the remaining one (~30%). With no
+`secondaryContent` the narrow column is not rendered at all and the wide column
+keeps its 2:1 span rather than stretching.
+
+**Given** `variant="grid3"`
+**When** it renders
+**Then** the content part is a three-column grid the children flow into. No row
+count is imposed — four children wrap onto a second row.
+
+**Given** `variant="table"`
+**When** it renders
+**Then** the root drops its padding entirely so the table's rows bleed to the
+page edges, and the header re-applies the horizontal inset so the title still
+lines up with the first column.
+
+**Given** `secondaryContent` under any variant other than `column2-70-30`
+**When** it renders
+**Then** it is ignored — those layouts have a single content area.
+
+### Stacking sections down a page
+
+**Given** a section with `hasBottomBorder` unset
+**When** it renders
+**Then** no divider is painted and **no bottom padding is reserved**. This is
+deliberate: the next section down opens with its own top inset, so reserving
+bottom padding here would double the gap between two unbordered bands.
+
+**Given** several sections stacked on one page
+**When** every section except the last sets `hasBottomBorder`
+**Then** each is separated by a divider with matching bottom padding, and the
+last one closes flush.
+
+**Given** `variant="table"` together with `hasBottomBorder`
+**When** it renders
+**Then** only the divider is added — the root stays flush, with no padding on
+any side.
+
+### The header
+
+**Given** no `SectionHeader` child
+**When** the section renders
+**Then** there is no header row and the content is the section's only child.
+There is no `hasHeader` flag: the part is simply omitted.
+
+**Given** a `title` and `description` but no `hasDescription`
+**When** it renders
+**Then** only the title is shown — the description is opt-in.
+
+**Given** `isSwitchable`
+**When** it renders
+**Then** a toggle switch appears at the start of the header, before the title,
+carrying `switchLabel` as its accessible name. Toggling it emits
+`switch-checked-change`; it never expands or collapses the section.
+
+**Given** `extras` and `actions`
+**When** it renders
+**Then** `extras` sit inline immediately after the title and `actions` are
+pushed to the inline end of the row, before the collapse trigger. The push
+comes from the flex-grow wrapper around `title` / `description` / `extras`.
+
+**Given** a header with `children` but no `title`, `description`, or `extras`
+**When** it renders
+**Then** that wrapper is not rendered at all, so `children` start at the inline
+start of the row — this is what lets a consumer-supplied heading take the
+title's place (see accessibility). Because nothing then grows, `actions`
+follow `children` immediately rather than sitting at the inline end, unless the
+consumer's own content grows (`flex-1`).
+
+### Collapsing
+
+**Given** `isCollapsible` on a header that is **not** inside a collapsible
+`AccordionContainer`
+**When** it renders
+**Then** no trigger appears — `AccordionContainer.Trigger` renders `null`
+outside a collapsible container, matching the design's `isCollapsable=false`
+state, which has no disclosure UI at all.
+
+**Given** a header with `isCollapsible` inside
+`<AccordionContainer collapsible defaultOpen>`
+**When** it renders
+**Then** the trigger is shown expanded (`aria-expanded="true"`) and the content
+wrapped in `AccordionContainer.Content` is visible — the design's
+`true-expanded` state.
+
+**Given** the same composition with `defaultOpen={false}`
+**When** it renders
+**Then** the trigger reads `aria-expanded="false"` and the panel is collapsed —
+the design's `true-collapsed` state.
+
+**When** the trigger is activated
+**Then** the panel animates its height and the chevron rotates; the header,
+including the switch and actions, stays visible throughout.
+
+### Composition
+
+**Given** a `render` prop on any part
+**When** it renders
+**Then** the element is replaced by the supplied element/component with props
+and classes merged (Base UI composition) — e.g. rendering the root as an
+`<article>`.
+
+**Given** a `SectionHeader` or `SectionContent` rendered outside a `Section`
+**When** it renders
+**Then** it falls back to the `column1` layout rather than failing.
+
+## Accessibility
+
+## Roles and semantics
+
+- The root renders a real `<section>` element. A `<section>` only becomes a
+  `region` landmark once it has an accessible name, so give it one whenever the
+  band is genuinely navigable content:
+
+  ```tsx
+  <Section aria-labelledby="protection-heading">…</Section>
+  ```
+
+  Do not name every section — an unnamed `<section>` is a generic grouping and
+  stays out of the landmark list, which is the right default for decorative
+  bands.
+
+- The header title is a `<p>`, not a heading. A section's place in the document
+  outline depends on the page around it, so guessing a level (`h2`? `h3`?)
+  would produce a broken hierarchy in most compositions. When the band really
+  is a document section, supply your own heading through the header's
+  `children` slot (not `render` — that replaces the entire header row,
+  wrapping the switch, title, description, actions, and collapse trigger in
+  the heading element), omit `title` so you don't render two titles, match the
+  title's text scale yourself (`text-xl leading-6 font-medium
+text-[var(--ui-text-on-surface-primary)]` — no exported class), and point
+  the root's `aria-labelledby` at it. With `title`, `description`, and `extras`
+  all omitted, the header renders no flex-grow wrapper at all, so give the
+  heading `min-w-0 flex-1` if the header also carries `actions` and they should
+  stay at the inline end.
+
+- The `description` is ordinary text, not a description role. If it should name
+  or describe the region for assistive technology, wire it up explicitly with
+  `aria-describedby`.
+
+## Keyboard
+
+- The section itself is not focusable and imposes no keyboard behavior.
+- Focus order follows DOM order: the header switch, then anything focusable in
+  `extras`, then anything in the header's `children` slot, then `actions`,
+  then the collapse trigger, then the content. Nothing is trapped or
+  re-ordered.
+- The collapse trigger is a real `<button>` supplied by `AccordionContainer`
+  (Base UI Collapsible): `Tab` reaches it and `Enter` / `Space` toggle the
+  panel. Its `aria-expanded` and `aria-controls` are managed by the primitive.
+- Collapsed content is hidden from the accessibility tree, so it is skipped by
+  both `Tab` and virtual-cursor navigation.
+
+## Screen reader
+
+- Icon-only controls in `actions` must supply their own accessible name; the
+  section adds none.
+- The collapse trigger has no visible label, so it relies on `collapseLabel`
+  (default `'Collapse section'`). Override it with something specific when a
+  page stacks several collapsible sections — "Collapse section" three times in
+  a row is not navigable.
+- The header switch likewise relies on `switchLabel` (default
+  `'Toggle section'`); override it per section for the same reason.
+- The title may be visually truncated. Truncation is visual only — the full
+  string stays in the accessible text — but keep it short enough to be
+  meaningful.
+
+## Contrast
+
+- The title uses `--ui-text-on-surface-primary` and the description
+  `--ui-text-on-surface-secondary`, both against the page surface. Both meet
+  WCAG AA in every shipped brand and in both light and dark themes.
+- The `hasBottomBorder` divider uses `--ui-border-on-surface-divider`. It is a
+  decorative separator, not a meaningful boundary, so it is exempt from the 3:1
+  non-text contrast requirement — the grouping is also conveyed by the header
+  and the spacing.
+
+## Localization
+
+- Every string the component renders on its own — `switchLabel` and
+  `collapseLabel` — is a prop whose literal exists only as that prop's default.
+  `title`, `description`, `extras`, `actions`, and the content are all
+  consumer-supplied.
+- Layout uses logical spacing and a logical grid only, so the band mirrors
+  correctly under `dir="rtl"`: the switch and title sit at the inline start,
+  actions and the collapse trigger at the inline end, and the 70/30 split
+  reverses. The trigger's chevron flips through `AccordionContainer`'s own
+  `rtl:` variant.