@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/page-content.md

@@ -0,0 +1,69 @@
+# PageContent
+
+> The page content region — the padded gutter for a page's body. A <div> meant to nest inside AppShellChatContentBody (so it doesn't duplicate the main landmark). Ported from the legacy shadcn-uikit `page-content`.
+
+**Status:** draft · **Category:** layout · **Since:** v0.52.0
+
+## Import
+
+```tsx
+import { PageContent } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<AppShellChatContentBody><PageContent>{children}</PageContent></AppShellChatContentBody>
+```
+
+The page content region — the padded gutter for a page's body. A `<div>` meant to
+nest inside `AppShellChatContentBody` (so it doesn't duplicate the `main` landmark).
+
+> Design-pending v1, ported from the legacy shadcn-uikit `page-content`.
+
+## When to use
+
+- Wrapping a page's body inside `AppShellChatContentBody` to get the standard page padding.
+
+## When not to use
+
+- As the scroll container / main landmark — that's `AppShellChatContentBody`.
+
+## Parts
+
+`PageContent` is a single component.
+
+## Example
+
+```tsx
+import {
+  AppShellChatContentBody,
+  PageContent,
+  PageHeader,
+} from '@acronis-platform/ui-react';
+
+<AppShellChatContentBody>
+  <PageContent>
+    <PageHeader>…</PageHeader>
+    {children}
+  </PageContent>
+</AppShellChatContentBody>;
+```
+
+## Behavior
+
+```gherkin
+Scenario: Padded body region
+  Given a PageContent inside AppShellChatContentBody
+  Then the page body renders with the standard page padding and fills the area
+```
+
+## Accessibility
+
+PageContent is a `<div>`, not a landmark — it nests inside `AppShellChatContentBody` (the
+`main` landmark) so a page has exactly one `main`. If you use PageContent without
+App Shell, wrap it in your own `<main>`.
+
+## Contrast
+
+No color of its own; content carries its own colors.

package/dist/llms/page-header.md

@@ -0,0 +1,182 @@
+# PageHeader
+
+> The page header region — a title row (title left, an optional edit icon-button, a tags slot, an actions slot) and an optional description row (text + an optional edit icon-button), capped at 512px. Sits at the top of a page's content; a breadcrumb is a separate sibling above it, not one of its parts. Mapped to the ui-react Figma "PageHeader" master component (node 2905-7678).
+
+**Status:** ready · **Category:** layout · **Since:** v0.52.0
+
+## Import
+
+```tsx
+import { PageHeader, PageHeaderRow, PageHeaderTitle, PageHeaderTags, PageHeaderActions, PageHeaderDescriptionRow, PageHeaderDescription } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<PageHeader>
+  <PageHeaderRow>
+    <PageHeaderTitle>Reports</PageHeaderTitle>
+    <PageHeaderTags><Tag variant="info">Customer</Tag></PageHeaderTags>
+    <PageHeaderActions><Button>New</Button></PageHeaderActions>
+  </PageHeaderRow>
+  <PageHeaderDescriptionRow>
+    <PageHeaderDescription>All scheduled reports.</PageHeaderDescription>
+  </PageHeaderDescriptionRow>
+</PageHeader>
+```
+
+The page header region — a title row (title left, an optional edit icon-button,
+a tags slot, an actions slot) and an optional description row, capped at
+512px. Mapped to the ui-react Figma "PageHeader" master component (node
+`2905-7678`).
+
+## When to use
+
+- The top of a page's content area, under the App Shell header.
+
+## When not to use
+
+- The app-wide top bar — that's `AppShellChatContentHeader` (global search +
+  account).
+- A breadcrumb trail — that's a separate `Breadcrumb` rendered as a sibling
+  above PageHeader, not one of its parts.
+
+## Parts
+
+| Export                     | Element | Purpose                                                                                                                                                         |
+| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PageHeader`               | `div`   | The banner region.                                                                                                                                              |
+| `PageHeaderRow`            | `div`   | Title row: title, optional edit button, tags, actions.                                                                                                          |
+| `PageHeaderTitle`          | `h1`    | The page title.                                                                                                                                                 |
+| `PageHeaderTags`           | `div`   | Optional tags slot (e.g. `Tag` chips). Collapses to the first tag + a "+#" tag (hover tooltip lists the hidden labels) when the full set doesn't fit.           |
+| `PageHeaderActions`        | `div`   | Trailing action buttons. Secondary-variant buttons collapse under a "More" `ButtonIcon` dropdown when the full set doesn't fit; primary buttons never collapse. |
+| `PageHeaderDescriptionRow` | `div`   | Optional description row (max 512px).                                                                                                                           |
+| `PageHeaderDescription`    | `p`     | Muted supporting text.                                                                                                                                          |
+
+## Example
+
+```tsx
+<PageHeader>
+  <PageHeaderRow>
+    <PageHeaderTitle>Reports</PageHeaderTitle>
+    <PageHeaderTags>
+      <Tag variant="info">Customer</Tag>
+    </PageHeaderTags>
+    <PageHeaderActions>
+      <Button>New report</Button>
+    </PageHeaderActions>
+  </PageHeaderRow>
+  <PageHeaderDescriptionRow>
+    <PageHeaderDescription>All scheduled reports.</PageHeaderDescription>
+  </PageHeaderDescriptionRow>
+</PageHeader>
+```
+
+### Editable title/description (full-page wizards)
+
+```tsx
+<PageHeaderRow>
+  <PageHeaderTitle>Untitled dashboard</PageHeaderTitle>
+  <ButtonIcon variant="secondary" aria-label="Edit title">
+    <PencilIcon size={16} />
+  </ButtonIcon>
+</PageHeaderRow>
+```
+
+### With a breadcrumb
+
+```tsx
+<div className="flex flex-col gap-2">
+  <Breadcrumb>{/* ... */}</Breadcrumb>
+  <PageHeader>{/* ... */}</PageHeader>
+</div>
+```
+
+## Behavior
+
+```gherkin
+Scenario: Title + actions
+  Given a PageHeader with a PageHeaderRow of a title and actions
+  Then the title sits at the left and the actions at the right edge
+```
+
+```gherkin
+Scenario: Tags share the row with actions
+  Given a PageHeaderRow with a title, a PageHeaderTags slot, and a PageHeaderActions slot
+  Then tags sit next to the title and actions stay flush right, even when tags are empty
+```
+
+```gherkin
+Scenario: Description under the title
+  Given a PageHeaderDescriptionRow below the title row
+  Then the muted description renders capped at 512px width
+```
+
+```gherkin
+Scenario: Editable title or description
+  Given a page that lets the user rename its title or description inline (e.g. a
+  full-page wizard like Create Dashboard)
+  Then render a ButtonIcon with the pencil icon as a sibling next to the title or
+  the description — PageHeader has no dedicated part for it, since it's the same
+  atom either row
+```
+
+```gherkin
+Scenario: Breadcrumb above PageHeader
+  Given a page that also shows a breadcrumb trail
+  Then render a Breadcrumb as a separate sibling above PageHeader, not nested inside it
+```
+
+```gherkin
+Scenario: Tags overflow
+  Given a PageHeaderTags slot with more than one tag
+  And the full set of tags doesn't fit the width available to the slot
+  Then show only the first tag and fold the rest under a single "+#" tag
+  And hovering or focusing the "+#" tag shows a tooltip listing the hidden tags' labels
+```
+
+```gherkin
+Scenario: Tags fit
+  Given a PageHeaderTags slot
+  When the full set of tags fits the width available to the slot
+  Then render every tag directly, with no overflow tag
+```
+
+```gherkin
+Scenario: Actions overflow
+  Given a PageHeaderActions slot with at least one secondary-variant Button action
+  And the full set of actions doesn't fit the width available to the slot
+  Then fold every secondary-variant Button action under a single "More" ButtonIcon that opens a dropdown menu of them, in their original order
+  And leave every primary-variant action visible — it is never folded into the menu
+  And leave any non-Button action (e.g. a ButtonMenu trigger) visible and unfolded, even with variant="secondary" — folding only covers a plain button with a single click action
+```
+
+```gherkin
+Scenario: Actions fit
+  Given a PageHeaderActions slot
+  When the full set of actions fits the width available to the slot
+  Then render every action directly, with no "More" ButtonIcon
+```
+
+## Accessibility
+
+- The region is a `banner` landmark and the title is an `<h1>` — one page title per
+  page; ensure it fits the document outline.
+- If a breadcrumb is composed above PageHeader, it's a separate `Breadcrumb` with
+  its own `<nav aria-label="breadcrumb">` — not a PageHeader part, so it carries
+  its own accessibility contract (see the Breadcrumb spec).
+- Don't rely on placement alone for actions — give icon-only action buttons labels.
+- The edit affordance next to the title or description is a plain `ButtonIcon`;
+  give it a descriptive `aria-label` (e.g. "Edit title", "Edit description") since
+  the pencil icon alone has no accessible name.
+- The tags overflow indicator is a `Tag` wrapped in a `Tooltip` — its hidden-label
+  list opens on hover _and_ keyboard focus (Tooltip's Base UI primitive handles
+  both), so the hidden tags' labels aren't hover-only information.
+- The actions overflow control is a `ButtonIcon` with `aria-label="More actions"`,
+  opening a `DropdownMenu` (Base UI `Menu`) of the hidden secondary actions — full
+  keyboard nav (arrow keys, typeahead, Esc) comes from the primitive.
+
+## Contrast
+
+Title uses `--ui-text-on-surface-primary`; description uses
+`--ui-text-on-surface-secondary`. Both meet contrast in light and dark.

package/dist/llms/pagination.md

@@ -0,0 +1,133 @@
+# Pagination
+
+> Navigation for paged content — previous / next controls, numbered page links with a current-page marker, and an ellipsis for skipped ranges. Markup-only (no Base UI primitive). Ported from the legacy shadcn-uikit `pagination`.
+
+**Status:** draft · **Category:** navigation · **Since:** v0.51.0
+
+## Import
+
+```tsx
+import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
+    <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationNext href="#" /></PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+Navigation for paged content — previous / next controls, numbered page links with
+a current-page marker, and an ellipsis for skipped ranges. Markup-only; you wire
+the navigation and decide the active page.
+
+> Design-pending v1, ported from the legacy shadcn-uikit `pagination`.
+
+## When to use
+
+- Splitting a long list/table across pages with direct page access.
+
+## When not to use
+
+- Inside a `DataTable` — use its built-in `DataTablePagination`.
+- Continuous loading — use infinite scroll / a "Load more" button.
+
+## Parts
+
+| Export               | Purpose                                          |
+| -------------------- | ------------------------------------------------ |
+| `Pagination`         | The `<nav>` landmark.                            |
+| `PaginationContent`  | The `<ul>` row of items.                         |
+| `PaginationItem`     | An `<li>` wrapper.                               |
+| `PaginationLink`     | A page link (`isActive` marks the current page). |
+| `PaginationPrevious` | Previous-page control (chevron).                 |
+| `PaginationNext`     | Next-page control (chevron).                     |
+| `PaginationEllipsis` | A skipped-range indicator.                       |
+
+## Example
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from '@acronis-platform/ui-react';
+
+<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="#" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#">1</PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" isActive>
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `isActive` | `boolean` | `false` | no | On PaginationLink — marks the current page (sets aria-current="page" and the selected treatment). |
+
+## Behavior
+
+Pagination is presentational — it renders the controls; the caller wires
+navigation (`href` or `onClick`) and decides which page is active.
+
+```gherkin
+Scenario: Mark the current page
+  Given a PaginationLink with isActive
+  Then it shows aria-current="page" and the selected treatment
+```
+
+```gherkin
+Scenario: Previous / next
+  Given PaginationPrevious / PaginationNext
+  Then they render labelled chevron controls the caller wires to navigate
+```
+
+```gherkin
+Scenario: Skipped range
+  Given a gap between page ranges
+  Then a PaginationEllipsis stands in for the skipped pages
+```
+
+## Accessibility
+
+- The root is a `<nav>` landmark labelled "pagination"; the items are a real
+  `<ul>` / `<li>` list of links.
+- The current page link carries `aria-current="page"`; previous / next links have
+  explicit labels ("Go to previous page" / "Go to next page").
+- The ellipsis is `aria-hidden` with an `sr-only` "More pages" so it isn't read as
+  an interactive control.
+- Render the page controls as real links (`href`) or buttons so they're keyboard
+  operable; don't rely on color alone for the current page (the `aria-current`
+  state conveys it).
+
+## Contrast
+
+Page links use the foreground over the page surface; the active page uses
+`--ui-background-surface-active` and hover uses `--ui-background-surface-hover` —
+both meet contrast in light and dark. The focus ring uses `--ui-focus-primary`.