@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/card-section.md

@@ -0,0 +1,293 @@
+# CardSection
+
+> A band of content stacked inside a `Card`'s body, below `CardHeader`. Six variants pick the body shape — an arbitrary slot, a wrapping tag row, a title/description list, a flush table with row actions, or a nested `Card` on the primary or secondary surface. An optional 14px mini-header (distinct from `CardHeader`) carries a title, inline extras, and end-aligned actions; an optional bottom divider separates one section from the next.
+
+**Status:** ready · **Category:** layout · **Since:** v2.1.0
+
+## Import
+
+```tsx
+import { CardSection } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Card>
+  <CardHeader title="Workload" />
+  <CardContent className="p-0 pb-4">
+    <CardSection
+      variant="list"
+      hasHeader
+      title="Network details"
+      hasBottomBorder
+      contentList={rows}
+    />
+    <CardSection variant="tag" hasHeader title="Labels" contentTag={tags} />
+  </CardContent>
+</Card>
+
+// Nested card on the secondary surface.
+<CardSection variant="card-secondary" hasHeader title="Retention">
+  <CardHeader title="Policy" />
+  <CardContent>Keep daily backups for 30 days.</CardContent>
+</CardSection>
+```
+
+A band of content stacked inside a `Card`'s body, below `CardHeader`. Where
+`Card` owns the surface and the card-level header/footer, `CardSection` divides
+the body into labelled bands — a tag row here, a key-value list there, a flush
+table below — each with an optional 14px mini-header and an optional divider.
+
+## When to use
+
+- A card body that holds **several distinct groupings** that each deserve their
+  own small label (e.g. "Network details", "Labels", "Subnets").
+- A card that needs a **table running edge-to-edge** inside it — the
+  `table-actions` variant drops the horizontal inset for exactly this.
+- A card that **nests another card**, on either the primary or the secondary
+  surface (`card-primary` / `card-secondary`).
+
+## When not to use
+
+- A card with a single, undifferentiated body. Put the content straight in
+  `CardContent` — a lone section adds a wrapper and no meaning.
+- As a page-level section. This is card chrome; use `PageContent` / `Section`
+  for page structure.
+- As a standalone surface. `CardSection` paints no background of its own and
+  relies on the enclosing card's surface and inset rhythm.
+
+## Parts
+
+| Part            | Element | Notes                                                                                 |
+| --------------- | ------- | ------------------------------------------------------------------------------------- |
+| `root`          | `div`   | Flex column, 12px gap. Inset (`px-4 pt-4`) for every variant except `table-actions`.  |
+| `header`        | `div`   | Optional, shown by `hasHeader`. Re-applies the inset under `table-actions`.           |
+| `title`         | `p`     | 14px medium, truncating. Required whenever `hasHeader` is set.                        |
+| `extras`        | slot    | Inline after the title.                                                               |
+| `actions`       | slot    | End of the header row.                                                                |
+| `content`       | `div`   | Body of `variant="slot"` — arbitrary passthrough.                                     |
+| `content-tag`   | `div`   | Body of `variant="tag"` — wrapping tag row; no built-in default.                      |
+| `content-list`  | `div`   | Body of `variant="list"` — title/description rows; no built-in default.               |
+| `content-table` | `div`   | Body of `variant="table-actions"` — flush table with row actions.                     |
+| `nested-card`   | `div`   | Body of `card-primary` / `card-secondary` — a nested `Card` composed from `children`. |
+
+## Examples
+
+Stacked sections in one card body — every section but the last draws a divider:
+
+```tsx
+<Card>
+  <CardHeader title="Workload" />
+  <CardContent className="p-0 pb-4">
+    <CardSection
+      variant="list"
+      hasHeader
+      title="Network details"
+      hasBottomBorder
+      contentList={rows}
+    />
+    <CardSection variant="tag" hasHeader title="Labels" contentTag={tags} />
+  </CardContent>
+</Card>
+```
+
+A flush table with header actions:
+
+```tsx
+<CardSection
+  variant="table-actions"
+  hasHeader
+  title="Subnets"
+  actions={
+    <ButtonIcon variant="ghost" aria-label="More">
+      <EllipsisIcon size={16} />
+    </ButtonIcon>
+  }
+  contentTable={<SubnetsTable />}
+/>
+```
+
+A nested card on the secondary surface — compose the nested card from `Card`'s
+own parts:
+
+```tsx
+<CardSection variant="card-secondary" hasHeader title="Retention">
+  <CardHeader title="Policy" />
+  <CardContent>Keep daily backups for 30 days.</CardContent>
+</CardSection>
+```
+
+## Notes
+
+- **`hasHeader` requires `title`.** The two props are a discriminated union in
+  React, so turning the header on without a title (or passing a title with no
+  header) fails to compile rather than rendering a blank row.
+- **`card-primary` vs. `card-secondary`** differ in exactly one thing: the
+  nested card's surface token. Pick by how much the nested card should recede
+  from the parent surface.
+- **The `list` variant has no default rows.** Figma's `ListItem` fallback
+  references `--ui-card-body-section-item-*` variables that do not exist in
+  `@acronis-platform/design-tokens`; rather than hardcode those values, the
+  variant ships empty and the consumer supplies `contentList`. Once the design
+  team lands that token tier, a default row rendering can follow.
+- **The default tag row is example content.** Replace it with real, localized
+  tags via `contentTag` before shipping.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'slot' | 'tag' | 'list' | 'table-actions' | 'card-primary' | 'card-secondary'` | `slot` | no | Which body shape the section renders. `slot` takes arbitrary content; `tag` a wrapping row of tags; `list` title/description key-value rows; `table-actions` a table with row actions, rendered flush so its rows run edge-to-edge; `card-primary` / `card-secondary` a nested `Card` on the primary or secondary surface. Maps to Figma's `Slot` / `Tag` / `List` / `Table + Actions` / `Card (primary)` / `Card (secondary)`. |
+| `hasBottomBorder` | `boolean` | `false` | no | Adds a bottom divider plus the matching bottom padding, separating this section from the next one stacked below it in the same card body. |
+| `hasHeader` | `boolean` | `false` | no | Shows the section's own mini-header row (14px medium title), distinct from the card-level `CardHeader`. Requires `title`. |
+| `title` | `string` | `undefined` | no | The section header's title. Required whenever `hasHeader` is set, and rejected when it is not — the title has nowhere to render without the header row. |
+| `extras` | `ReactNode` | `undefined` | no | Content rendered inline next to the title in the header row. |
+| `actions` | `ReactNode` | `undefined` | no | Actions rendered at the end of the header row (e.g. a menu button). |
+| `content` | `ReactNode` | `undefined` | no | Body of the `slot` variant — arbitrary passthrough content. |
+| `contentTag` | `ReactNode` | `undefined` | no | Body of the `tag` variant. Has no built-in default: like `contentList`, the consumer supplies the tags. |
+| `contentList` | `ReactNode` | `undefined` | no | Body of the `list` variant — title/description key-value rows. Has no built-in default: the `ListItem` tokens the design references (`--ui-card-body-section-item-*`) do not exist in tokens-pd yet. |
+| `contentTable` | `ReactNode` | `undefined` | no | Body of the `table-actions` variant. |
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop — replaces the rendered element with another component (e.g. a `<section>`) while merging props and classes. React-only; other frameworks use their own polymorphism. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | For `card-primary` / `card-secondary`, the nested card's parts (`CardHeader`, `CardContent`, …). For every other variant, extra content appended after the variant body. |
+
+## Behavior
+
+### Rendering the body
+
+**Given** a `CardSection` with no `variant`
+**When** it renders
+**Then** it uses the `slot` variant and renders `content` as-is, with no
+built-in layout.
+
+**Given** `variant="tag"` and no `contentTag`
+**When** it renders
+**Then** the body is empty — this variant has no built-in fallback.
+
+**Given** `variant="tag"` and a `contentTag` slot
+**When** it renders
+**Then** the supplied tags are shown, wrapping onto further lines when the
+section is too narrow.
+
+**Given** `variant="list"` and a `contentList` slot
+**When** it renders
+**Then** the rows are stacked in a column. With no `contentList` the body is
+empty — this variant has no built-in fallback.
+
+**Given** `variant="table-actions"`
+**When** it renders
+**Then** the root drops its horizontal inset so the table rows run edge-to-edge
+inside the card, and the header row (if shown) re-applies the inset so the title
+stays aligned with the table's first cell.
+
+**Given** `variant="card-primary"` or `variant="card-secondary"`
+**When** it renders
+**Then** `children` are composed into a nested `Card` filling the section width.
+The two variants are identical apart from the nested card's surface token —
+primary uses the card surface, secondary the secondary surface.
+
+### The header
+
+**Given** `hasHeader` is not set
+**When** it renders
+**Then** no header row exists and the body is the section's only child.
+
+**Given** `hasHeader` is set
+**When** it renders
+**Then** a single row shows the title (truncating with an ellipsis when it
+overflows), `extras` inline after it, and `actions` pushed to the end.
+
+**Given** `hasHeader` is set
+**When** the consumer omits `title`
+**Then** this is a **compile-time error** in the React adapter — the two props
+form a discriminated union, because the header row always renders a title.
+Passing `title` without `hasHeader` is likewise rejected.
+
+### Stacking sections
+
+**Given** several sections stacked in one card body
+**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 against the card's own edge.
+
+**Given** a section with `hasBottomBorder` unset
+**When** it renders
+**Then** no border is painted and no bottom padding is reserved.
+
+### Composition
+
+**Given** a `render` prop
+**When** it renders
+**Then** the root element is replaced by the supplied element/component, with
+props and classes merged (Base UI composition) — e.g. to render the section as
+a semantic `<section>`.
+
+## Accessibility
+
+## Roles and semantics
+
+- The root is a plain `<div>` with no implicit role — the section is a visual
+  grouping inside a card, not a landmark. Nothing is announced for the wrapper
+  itself.
+- To expose the grouping to assistive technology, render it as a real region:
+
+  ```tsx
+  <CardSection render={<section aria-label="Network details" />} … />
+  ```
+
+  Prefer this only when the grouping is genuinely navigable content; a decorative
+  band of key-value rows does not need a landmark, and over-using regions makes
+  the landmark list noisy.
+
+- The header title is a `<p>`, not a heading. A section inside a card sits below
+  the card's own title in the document outline, and guessing at a heading level
+  (`h3`? `h4`?) would produce a broken hierarchy in most compositions. When the
+  section really is a document section, pair `render` with your own heading:
+
+  ```tsx
+  <CardSection render={<section aria-labelledby="net-heading" />} … />
+  ```
+
+- The `card-primary` / `card-secondary` variants nest a full `Card`. Its parts
+  carry their own semantics; see the `Card` spec.
+
+## Keyboard
+
+- The section itself is not focusable and has no keyboard behavior.
+- Focusable content is whatever the consumer places in `extras`, `actions`, or
+  the body slots. Those follow DOM order: title/extras first, then actions, then
+  the body. Nothing is trapped or re-ordered.
+
+## Screen reader
+
+- The `title` is read as ordinary text when the user reaches it. Because it may
+  be visually truncated, keep it short enough to be meaningful — truncation is
+  visual only, the full string stays in the accessible name/text.
+- Icon-only controls placed in `actions` must supply their own accessible name
+  (`aria-label` on the button); the section adds none.
+- `variant="tag"` has no built-in default content — the consumer always
+  supplies real, localized tags via `contentTag`.
+
+## Contrast
+
+- The title uses `--ui-text-on-surface-primary` against the enclosing card
+  surface, which meets 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 spacing.
+
+## Localization
+
+- Every string the component can render on its own — the `title` and the default
+  tag labels — is a prop, or a prop's default. The component ships no inlined
+  literals.
+- Layout uses logical spacing only, so the section mirrors correctly under
+  `dir="rtl"`: the title/extras group starts at the inline start and `actions`
+  sit at the inline end.