@juwel-development/design-system 3.9.1 → 3.10.0

package/dist/types/Display/Figure/Figure.d.ts

@@ -1,8 +1,8 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const figure: (props?: ({
-    ratio?: "portrait" | "square" | "landscape" | "wide" | null | undefined;
-    focus?: "center" | "top" | "bottom" | "left" | "right" | null | undefined;
+    ratio?: "square" | "portrait" | "landscape" | "wide" | null | undefined;
+    focus?: "center" | "left" | "right" | "bottom" | "top" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface IFigureProps extends VariantProps<typeof figure> {
     /** The image source. Produce it through the consuming build's image pipeline - see @UXGuidelines. */

package/dist/types/Display/Icon/Icon.d.ts

@@ -0,0 +1,26 @@
+import type { FunctionComponent } from 'react';
+declare const drawings: {
+    readonly sort: readonly ["M5.5 13V3", "M3 5.5l2.5-2.5L8 5.5", "M10.5 3v10", "M8 10.5l2.5 2.5 2.5-2.5"];
+    readonly 'sort-ascending': readonly ["M8 13V3", "M4 7l4-4 4 4"];
+    readonly 'sort-descending': readonly ["M8 3v10", "M4 9l4 4 4-4"];
+};
+export interface IIconProps {
+    /** Which drawing. A name selects a shape, never a state or a behaviour. */
+    name: keyof typeof drawings;
+    testId?: string;
+}
+/**
+ * A reusable visual glyph: the three sort indicators a consumer composes inside a header cell's
+ * plain Button, or beside any text that names what the icon reinforces.
+ *
+ * @Guarantees — enforced on every render
+ * - Hidden from assistive technology and out of the tab order: it adds no stop and no spoken name.
+ * - Scales with the surrounding font-size and takes the surrounding text colour.
+ * - The three drawings differ in shape, so the ordering is never carried by colour alone.
+ *
+ * @CallerMustEnsure
+ * - The control or text beside it carries the meaning: a `Button` label, a header cell's `ariaSort`.
+ *   An icon standing alone says nothing to a screen reader.
+ */
+export declare const Icon: FunctionComponent<IIconProps>;
+export {};

package/dist/types/Display/Table/Table.d.ts

@@ -1,33 +1,78 @@
 import type { VariantProps } from 'class-variance-authority';
-import type { FunctionComponent, ReactNode } from 'react';
+import { type FunctionComponent, type ReactNode } from 'react';
+import type { Observable, Subject } from 'rxjs';
+declare const table: (props?: ({
+    density?: "compact" | "comfortable" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare const tableCell: (props?: ({
-    variant?: "note" | "value" | null | undefined;
+    variant?: "value" | "note" | null | undefined;
     align?: "center" | "left" | "right" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare const tableHeaderCell: (props?: ({
     align?: "center" | "left" | "right" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-interface ITableRootProps {
+/** The width roles a column may take, as its fixed width or as a floor. Each names a column job the
+ *  consumer specification attests - the subject's name, a short comparison fact, a tabular figure
+ *  with its unit, one action control - and is read from the theme as `--table-column-<role>`. */
+type TableColumnWidthRole = 'name' | 'fact' | 'figure' | 'action';
+/**
+ * One column's allocation of a table's width, independent of the rows currently displayed: either
+ * fixed at a named width role, or a positive share of the width the fixed columns leave, with an
+ * optional named minimum as its floor. Declared once on `Table.Root`, in cell order.
+ */
+export type TableColumnAllocation = {
+    /** The role whose width this column takes exactly, at any available width. */
+    readonly width: TableColumnWidthRole;
+    readonly weight?: never;
+    /** A floor: a `width` smaller than its minimum resolves to the minimum. */
+    readonly minWidth?: TableColumnWidthRole;
+} | {
+    /** This column's share of the width the fixed columns leave, relative to its siblings' weights:
+     *  a positive finite number. `3` beside `1` is three quarters and one quarter of it. */
+    readonly weight: number;
+    readonly width?: never;
+    /** The least this column takes. While a minimum holds a column, the other proportional columns
+     *  share what is left; with none, the share may shrink to nothing. */
+    readonly minWidth?: TableColumnWidthRole;
+};
+export interface ITableRootProps extends VariantProps<typeof table> {
     /** The table's accessible name. Rendered as the first child; always present. */
     caption: string;
     /** What the note column is. Governs narrow-viewport behaviour; omit when there is none. */
     notes?: 'supplementary' | 'content';
+    /** The columns' allocations, in the order the cells of every row are written. Omit it and widths
+     *  follow content as before; declare it and every row shares one allocation the rows' content
+     *  cannot move, and the narrow-viewport `notes` behaviour is replaced by residual scrolling. */
+    columns?: readonly TableColumnAllocation[];
     children?: ReactNode;
     testId?: string;
 }
-interface ITableSectionProps {
+export interface ITableSectionProps {
     children?: ReactNode;
 }
-interface ITableRowProps {
+export interface ITableRowProps {
     children?: ReactNode;
     testId?: string;
+    /** Emits once per activation of the row body - a click, or Enter or Space while the row has
+     *  focus. Its presence is what makes the row interactive: a tab stop, a visible focus ring and a
+     *  pointer cursor. Nested links and controls keep their own operations and never emit here.
+     *  Activation changes nothing about the row; the consumer decides what the request means. */
+    onClick$?: Subject<void>;
+    /** The consumer's selection for this row. Rendered as `aria-selected` and the marker bar; omitted
+     *  or not yet emitted means unselected. Selection is independent of `onClick$`: a selected row
+     *  may be noninteractive, and an interactive row may be unselected. */
+    isSelected$?: Observable<boolean>;
 }
-interface ITableCellProps extends VariantProps<typeof tableCell> {
+export interface ITableCellProps extends VariantProps<typeof tableCell> {
     children?: ReactNode;
 }
-interface ITableHeaderCellProps extends VariantProps<typeof tableHeaderCell> {
+export interface ITableHeaderCellProps extends VariantProps<typeof tableHeaderCell> {
     /** Explicit, never inferred from Head/Body position - inference would need render-time context. */
     scope: 'row' | 'col';
+    /** The order the column is *currently* displayed in, as accessibility metadata only. Omit it on a
+     *  column that is not sortable; set it on the one ordered column. Changing it neither reorders rows
+     *  nor triggers anything - the consumer owns the sort and composes the action in `children`. */
+    ariaSort?: 'none' | 'ascending' | 'descending' | 'other';
     children?: ReactNode;
 }
 /**
@@ -41,9 +86,74 @@ interface ITableHeaderCellProps extends VariantProps<typeof tableHeaderCell> {
  * - The block reads as a table from two rule weights alone: the heavier `rule` above the first row,
  *   `border` hairlines between rows, and no bottom rule on the last. No cell borders, fill, zebra or hover.
  * - `Cell variant="value"` sets tabular figures; `variant="note"` does not. Both at the 15px small role.
- * - `HeaderCell` emits the `scope` it is given; none is inferred.
+ * - `HeaderCell` emits the `scope` it is given; none is inferred. It emits `ariaSort` the same way:
+ *   the attribute states the displayed order and the component never orders, cycles or requests one.
+ * - Residual horizontal overflow scrolls in every `notes` mode, with no opt-in. The wrapper is
+ *   keyboard-reachable while there is something to scroll - always, as a named region, with no note
+ *   column; as a named group only once the table overflows, with one. No vertical bound is ever set:
+ *   a long table sits inside a `ScrollContainer` with `axis="vertical"`, which owns that axis.
+ * - `Root columns` declares every column's allocation once, in cell order, and every row shares it:
+ *   a fixed column takes its named width role at any available width; proportional columns share
+ *   the width the fixed ones leave by their weights, each floored at its named minimum, and while a
+ *   minimum holds one column the others share what is left. A fixed width below its minimum is the
+ *   minimum. Nothing a row holds moves a boundary: filtering, sorting, paging, long or short content,
+ *   an empty body and its repopulation all leave the allocation as it was. Only the definitions, the
+ *   theme's `--table-column-*` values and the available width can. All-fixed columns do not stretch.
+ * - With `columns` declared, no narrow-viewport rule applies whatever `notes` says: the note column
+ *   stays, rows stay tabular, and what does not fit scrolls in the wrapper as above. Text wraps inside
+ *   its allocation, an unbroken run included; the table never truncates, hides or resizes content.
+ *   Without `columns`, widths follow content and both `notes` behaviours are exactly as before.
+ * - `Root density` insets every header and body cell from one theme pair: `comfortable` (the
+ *   default, the former spacing exactly) or `compact`, per table. It moves no type size and no
+ *   control's own dimensions. A non-positive or non-finite `weight` throws
+ *   {@link TableConfigurationError}, loud and early.
+ * - A `Row` given `onClick$` is interactive: a tab stop with the shared focus ring, activated by a
+ *   click on its body or by Enter or Space while focused, emitting exactly once per activation. A
+ *   nested link, button or other control - and anything inside one - performs its own operation and
+ *   never activates the row. Without `onClick$` the row body is inert and adds no tab stop; nested
+ *   controls stay operable. Activation never changes selection.
+ * - A `Row` given `isSelected$` carries `aria-selected` and, when true, the marker bar along its
+ *   leading edge in `foreground` - a shape, not a colour, and not the focus ring. Omitted or not yet
+ *   emitted reads unselected; a replaced source reads unselected until it emits; unmounting
+ *   unsubscribes. The selection input is independent of `onClick$`, so a row may be selected and
+ *   noninteractive, interactive and unselected, or both. Rendering and selection changes emit nothing.
+ * - The row stays a `tr` in a `table`: no grid role, no arrow-key navigation. `aria-selected` is a
+ *   WAI-ARIA 1.2 state of `row` and valid here, but Chromium exposes a row's selected state only
+ *   inside a `grid`, so Chrome and Edge screen readers do not announce it on these rows (accepted
+ *   limitation, #113). The marker bar is the one guaranteed selection cue.
+ * - A table holding a selection input anywhere insets every row's first cell by the cell padding,
+ *   head and foot included, so the marker has room and no column shifts as the selection moves. A
+ *   table holding an interactive row makes ring room around itself, so a focused row's ring is never
+ *   clipped by the scroll region. A table with neither keeps its static geometry exactly.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Every row writes exactly as many cells as there are `columns`, in the same order. A row with
+ *   fewer leaves tracks empty; one with more breaks onto a second line of its own row.
+ * - A cell whose content cannot wrap - a `Button`, an `Input`, an image - sits in a column whose
+ *   fixed width or minimum holds it: the `action` role holds one standard control at comfortable
+ *   density. The allocation never widens for content, so an under-allocated control overflows its
+ *   cell rather than moving its neighbours.
+ * - A cell's `align` and `variant` are the consumer's as before; an allocation sets neither.
+ * - Each row's `onClick$` and `isSelected$` are tied to that row's stable identity, so a reordered or
+ *   temporarily removed row keeps its association. Table holds no identity, registry or policy, and
+ *   removing a row never asks the consumer to clear or replace its selection.
+ * - What an activation means - select, open, toggle - is the consumer's answer, given by rerendering
+ *   from its own state. A request left unanswered leaves the rendered selection unchanged.
+ * - An interactive row announces no verb of its own; the caption, a row header or a nested link
+ *   should make the row's purpose plain.
  *
  * @UXGuidelines
+ * - Allocate by job, not by measurement: the subject's `name` first, proportional with a minimum so it
+ *   wraps rather than vanishes; comparison facts proportional at `fact`; figures fixed at `figure`,
+ *   right-aligned; the action column fixed at `action`, last. A theme that re-points a role moves
+ *   every table using it, which is the point of naming the role rather than the width.
+ * - `compact` is for a dense comparison the viewer scans, not for fitting more in: it changes air,
+ *   not type, so a table that overflows at `comfortable` mostly still overflows at `compact`.
+ * - A sortable column is composed, not configured: a `Button variant="plain"` inside the `HeaderCell`
+ *   carries the label and an `Icon` (`sort`, `sort-ascending`, `sort-descending`) that matches the
+ *   order the consumer currently displays, and `ariaSort` on the same cell says so to assistive
+ *   technology. Only the ordered column carries `ariaSort`; an action-only column carries no sort
+ *   control. Until the consumer's data arrives, both icon and `ariaSort` keep stating the old order.
  * - `align` is a cell property but reads as a column one: set the same `align` on a `HeaderCell` and
  *   every `Cell` beneath it, and keep them in sync - the component cannot align a column for you.
  * - Choose `notes` by what the note column *is*: `"supplementary"` drops it below 48rem for everyone

package/dist/types/Display/Table/TableConfigurationError.d.ts

@@ -0,0 +1,3 @@
+export declare class TableConfigurationError extends Error {
+    constructor(reason: string);
+}

package/dist/types/Display/Typography/Eyebrow/Eyebrow.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const eyebrow: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IEyebrowProps extends VariantProps<typeof eyebrow> {
     children: ReactNode;

package/dist/types/Display/Typography/H1/H1.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const h1: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IH1Props extends VariantProps<typeof h1> {
     children: ReactNode;
@@ -12,7 +12,8 @@ interface IH1Props extends VariantProps<typeof h1> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h1`; its outline level and the display role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-display`, led by `--leading-display` and optically
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-display`, led by `--leading-display` and optically
  *   corrected by `--tracking-optical`, the large-type correction every role from title up carries.
  * - Bounded at `--measure-display`, the display role's own measure — narrower than the reading column
  *   because bigger type wants fewer characters per line (docs/adr/0004). The bound is the recipe's,

package/dist/types/Display/Typography/H2/H2.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const h2: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IH2Props extends VariantProps<typeof h2> {
     children: ReactNode;
@@ -12,7 +12,8 @@ interface IH2Props extends VariantProps<typeof h2> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h2`; its outline level and the title role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-title`, led by `--leading-title` and optically corrected
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-title`, led by `--leading-title` and optically corrected
  *   by `--tracking-optical` — the title role is the smallest role that carries it, so `H3` and below
  *   take none.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else

package/dist/types/Display/Typography/H3/H3.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const h3: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IH3Props extends VariantProps<typeof h3> {
     children: ReactNode;
@@ -13,7 +13,8 @@ interface IH3Props extends VariantProps<typeof h3> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h3`; its outline level and the subtitle role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-subtitle` and led by `--leading-subtitle`.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-subtitle` and led by `--leading-subtitle`.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/dist/types/Display/Typography/H4/H4.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const h4: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IH4Props extends VariantProps<typeof h4> {
     children: ReactNode;
@@ -12,7 +12,8 @@ interface IH4Props extends VariantProps<typeof h4> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h4`; its outline level and the body role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-body`, and is bold so it stands apart from a paragraph.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-body`, and is bold so it stands apart from a paragraph.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/dist/types/Display/Typography/H5/H5.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const h5: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IH5Props extends VariantProps<typeof h5> {
     children: ReactNode;
@@ -13,7 +13,8 @@ interface IH5Props extends VariantProps<typeof h5> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h5`; its outline level and the body role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-body`, semibold so it stands apart from a paragraph.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-body`, semibold so it stands apart from a paragraph.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/dist/types/Display/Typography/H6/H6.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const h6: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IH6Props extends VariantProps<typeof h6> {
     children: ReactNode;
@@ -13,7 +13,8 @@ interface IH6Props extends VariantProps<typeof h6> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h6`; its outline level and the body role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-body`, medium so it stands apart from a paragraph.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-body`, medium so it stands apart from a paragraph.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/dist/types/Display/Typography/Note/Note.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const note: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface INoteProps extends VariantProps<typeof note> {
     /** The annotation. A `ReactNode` rather than a string, because these lines carry inline links. */

package/dist/types/Display/Typography/P/P.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const p: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IPProps extends VariantProps<typeof p> {
     children: ReactNode;
@@ -12,7 +12,8 @@ interface IPProps extends VariantProps<typeof p> {
  * table cell — because the reading measure belongs to whatever owns the reading column (Prose #21).
  *
  * @Guarantees — enforced on every render
- * - Renders a `p`, reading `--font-primary`, sized by `--text-body` and led by `--leading-body`.
+ * - Renders a `p`, reading `--font-body` (the body family, which follows `--font-primary` until a
+ *   theme re-points it, #120), sized by `--text-body` and led by `--leading-body`.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/dist/types/Display/Typography/Prose/Prose.d.ts

@@ -1,7 +1,7 @@
 import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const proseBody: (props?: ({
-    color?: "foreground" | "muted" | "success" | "warning" | "error" | "info" | null | undefined;
+    color?: "error" | "foreground" | "muted" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IProseRootProps {
     children?: ReactNode;

package/dist/types/Interaction/Button/Button.d.ts

@@ -2,7 +2,7 @@ import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 import type { Subject } from 'rxjs';
 declare const button: (props?: ({
-    variant?: "primary" | "secondary" | "ghost" | null | undefined;
+    variant?: "primary" | "secondary" | "ghost" | "outlined" | "destructive" | "plain" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface IButtonProps extends VariantProps<typeof button> {
     /** Optional: an icon-only button renders none, and names itself with `ariaLabel` instead. */
@@ -22,10 +22,27 @@ interface IButtonProps extends VariantProps<typeof button> {
  *
  * @component
  *
+ * @Variants
+ * - `primary` and `secondary`: the filled actions
+ * - `outlined`: the quiet secondary - `secondary` text and edge on an unfilled surface, for an
+ *   action beside a primary one that must not compete with it
+ * - `destructive`: an action that removes or ends something, filled with the `error` status tone
+ *   and inked with `errorForeground`. The tone reinforces words it never replaces: the label, or
+ *   the `ariaLabel` of a symbol-only button, must say what the action does
+ * - `ghost`: the padded text action with a hover underline and no floor
+ *
+ * The four faced variants share the control minimum width and inset, so a row of them aligns, and
+ * every one of them shrinks and wraps its label where its holder is narrower than that.
+ *
  * @UXGuidelines
  * - Use clear, action-oriented text (e.g., "Save" instead of "OK")
- * - Keep button text concise (1-3 words)
+ * - Keep button text short; a translated label that runs longer wraps where the layout constrains
+ *   it, so the words stay readable rather than overflowing
  * - Use primary buttons for main actions, secondary buttons for alternative actions
+ * - `plain` is a plain action (CONTEXT.md): an operable button in the typography and colour of the
+ *   text around it, with no face, padding, corner or hover underline of its own. Reach for it where
+ *   the action belongs to a line of content - a sortable column header composed with `Icon` - and
+ *   for `ghost` where a quiet but still button-shaped action is wanted
  * - Maintain consistent button styling throughout the application
  * - Provide visual feedback on hover/active states
  * - Ensure sufficient touch target size (minimum 44x44px) for mobile users
@@ -35,8 +52,11 @@ interface IButtonProps extends VariantProps<typeof button> {
  *
  * @Accessibility
  * - Ensure adequate color contrast (4.5:1 minimum ratio)
- * - Provide focus styles for keyboard navigation
+ * - Provide focus styles for keyboard navigation: every variant, `plain` included, draws the shared
+ *   focus ring and nothing else changes on focus
+ * - A disabled `plain` button is told apart by the `disabled` text tone and keeps native disabled semantics
  * - Use appropriate ARIA attributes when needed
+ * - Status colour never stands alone: a destructive action is named by its words or symbol
  */
 export declare const Button: FunctionComponent<IButtonProps>;
 export {};

package/dist/types/Interaction/Tabs/Tabs.d.ts

@@ -18,8 +18,10 @@ export interface ITabsTabProps {
     /** The stable identity connecting this tab to its panel and emitted by selection requests.
      *  Not React's `key`, and never inferred from the label or the position. */
     value: string;
-    /** The visible text label. Text only - no icons, no per-tab markup. */
-    children: string;
+    /** The label: visible text naming the view - a plain string still works - optionally with an
+     *  icon, a count or inline emphasis beside it. Decorative parts carry the consumer's own
+     *  `aria-hidden`; nothing in it is interactive, as the tab is the control. Rendered whole. */
+    children: ReactNode;
     testId?: string;
 }
 export interface ITabsPanelProps {
@@ -47,15 +49,31 @@ export interface ITabsPanelProps {
  *   immediately; focus stays on the operated tab. Up/Down are left to the browser.
  * - Roving tabindex: Tab enters the list at the active tab, then the active panel - a consistent
  *   Tab stop whether or not its content is focusable. Inactive panels add no stop.
- * - The row scrolls horizontally on overflow - one line, no wrap, no shrink - and holds its own
- *   ring room, so the focused tab's ring survives the scroll clip.
+ * - A label is rendered whole, text and markup alike, however long its translation runs: never
+ *   clipped, shortened, elided or replaced by a hint. The tab's accessible name is computed from
+ *   its content, so what the device reads is what the viewer sees, less what the consumer marked
+ *   `aria-hidden`. A rich label and a plain string are one and the same control.
+ * - The row is one line of controls. As it narrows, a label's text wraps inside its tab, down to
+ *   the tab's longest word; only when the controls still cannot fit does the row scroll
+ *   horizontally - the row, never the page. The row holds its own ring room so the focused tab's
+ *   ring survives the scroll clip, and focus reveals a scrolled-off tab, so every tab is reachable
+ *   by keyboard without scrolling first.
+ * - The tabs on the row share one height, so every marker sits on one line whether or not a
+ *   neighbour's label wrapped.
  * - Selection is marked by a persistent line under the active tab: `--tab-marker-thickness` in
  *   `foreground`, constant thickness in both states, so switching shifts no widths and no weights.
  *   Keyboard focus is the separate shared focus ring. Colour moves on the one motion token.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - One List with Tab elements as direct DOM children (arrays and fragments are supported),
- *   and sibling Panels under Root. Do not wrap tabs in host elements.
+ *   and the Panels under the same Root - as siblings of the List, or with it inside one
+ *   arrangement such as a `Stack` (see the separation guidance below). Do not wrap tabs in host
+ *   elements.
+ * - A label is a meaningful visible text name, with non-interactive decoration at most: no link,
+ *   button, input or other focusable descendant, since the tab is the one control and a nested
+ *   control inside a `button` is invalid. Decorative parts - an icon that repeats the text - carry
+ *   `aria-hidden` so they stay out of the name; the library does not guess which parts those are.
+ *   A count or an emphasis is meaning and stays in the name.
  * - At least two tabs, each `value` unique and stable, each with exactly one matching `Panel`
  *   under the same `Root`, and `active` naming a declared pair. Invalid input is a contract
  *   violation, not a request for a fallback.
@@ -66,10 +84,17 @@ export interface ITabsPanelProps {
  *
  * @UXGuidelines
  * - Labels are short names for views, not actions; the consuming app words and translates them.
+ *   A long translation wraps inside its tab and the row scrolls only when even the longest words
+ *   do not fit, so a label is never the reason to shorten a name.
  * - This is not a router: no location, no history, no deep links. Wire `onSelect$` to whatever
  *   owns the active key and pass that key back in.
+ * - Tabs sets no spacing between the row and the panel; the separation is a `Stack` between Root
+ *   and its members - `<Tabs.Root><Stack gap="region"><Tabs.List/>…<Tabs.Panel/>…</Stack>
+ *   </Tabs.Root>`. `gap="stack"` holds the row and its view together as one block; `gap="region"`
+ *   sets the view apart as a region of its own. Inactive panels are hidden, so the gap is exactly
+ *   one whichever panel is active, from the token the consumer's other groups already use.
  * - The panel is an opaque slot: compose the view's own rhythm inside it - a `Stack`, a `Prose` -
- *   as the view owns it; Tabs sets no spacing between the row and the panel.
+ *   as the view owns it.
  */
 export declare const Tabs: {
     readonly Root: FunctionComponent<ITabsRootProps>;

package/dist/types/Layout/Header/Header.d.ts

@@ -2,8 +2,14 @@ import type { VariantProps } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 declare const header: (props?: ({
     edge?: "none" | "rule" | null | undefined;
+    mode?: "navigation" | "statusAction" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-export interface IHeaderProps extends VariantProps<typeof header> {
+interface IHeaderShellProps extends Omit<VariantProps<typeof header>, 'mode'> {
+    testId?: string;
+}
+/** The navigation bar: the mode every existing caller is in, and the default. A standing link and a
+ *  `<nav>`, and never a status or an action slot - the other shape is `IHeaderStatusActionProps`. */
+export interface IHeaderNavigationProps extends IHeaderShellProps {
     /** The standing link: a place name, a mark, or a home link. The consumer supplies the whole anchor -
      *  Header renders no link of its own. A place name uses `<Link treatment="quiet" href="/">…</Link>`; a
      *  mark uses `<Link treatment="graphic" href="/"><Brandmark …/></Link>`, whose `graphic` treatment
@@ -13,15 +19,45 @@ export interface IHeaderProps extends VariantProps<typeof header> {
     navName?: string;
     /** The nav links. */
     children?: ReactNode;
-    testId?: string;
+    status?: never;
+    action?: never;
 }
+/** The status/action bar: a bar that reports and acts rather than navigates, for a product whose
+ *  shell carries a readout and a control and no links. It has no standing link and no `<nav>` - a
+ *  button is not navigation - and the two shapes cannot be mixed: the compiler rejects a call that
+ *  hands this bar a standing link, a nav name or nav children. */
+export interface IHeaderStatusActionProps extends IHeaderShellProps {
+    /** The readout - a date, a balance, a short note, or a `Cluster` of them - at the start edge, first
+     *  in reading order. A plain `div` with no role, no name and no live region: what it holds carries its
+     *  own semantics, and whether a change is announced is the consumer's decision, made by wrapping its
+     *  own live region. Long and unbroken wording wraps inside the slot. Omitted, nothing renders. */
+    status?: ReactNode;
+    /** The control - a `Button`, or a `Cluster` of them - at the end edge, last in reading and keyboard
+     *  order, on whichever line it lands when the bar breaks. A plain `div` like `status`. Header never
+     *  decides whether the control is available: pass it disabled, or withhold it (`{ready && <Button/>}`
+     *  renders no box). Omitted, nothing renders. */
+    action?: ReactNode;
+    standing?: never;
+    navName?: never;
+    children?: never;
+}
+export type IHeaderProps = IHeaderNavigationProps | IHeaderStatusActionProps;
 /**
- * The shell's top edge: a standing link and a nav, at the label type role. It renders the banner
- * landmark and a single `<nav>`, arranging nothing beyond the two slots, so it works with no hydration.
+ * The shell's top edge, at the label type role, in one of two mutually exclusive modes. The
+ * **navigation bar** - the default, and what every existing caller renders - is a standing link and a
+ * single `<nav>`. The **status/action bar** is a readout at the start edge and a control at the end
+ * edge, both plain boxes with no landmark of their own and no `<nav>` anywhere. The props type is a
+ * union of the two shapes, so a call that mixes them does not compile. Either bar arranges nothing
+ * beyond its slots and works with no hydration.
  *
  * @Guarantees — enforced on every render
  * - The header is set at the label role and carries no size of its own: `font-secondary text-label
  *   leading-label tracking-label text-muted`, so it never grows past that role whatever the page font size.
+ * - The shell's air is one value above, below and between: `--space-region` vertically, between the
+ *   nav's items and between the status/action bar's slots along a line, `--gutter` across, so the bar
+ *   aligns with every inset `Section`. It is never sticky and needs no JavaScript.
+ *
+ * The navigation bar, unchanged by #125:
  * - The nav's line box is the library's own rather than the consuming document's: the header leads
  *   itself at the label role, so the height it declares for its slot is the height it renders.
  * - The standing slot is floored, never fixed: its minimum height is that same line box - the label
@@ -31,10 +67,24 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *   grows the slot, on one line, and is never clamped or wrapped.
  * - A nav item marked `aria-current="page"` renders at `foreground` whatever supplied it - the treatment
  *   keys on the attribute, not on `Link`, so it holds against a bare anchor or any component.
- * - The shell's air is one value above, below and between: `--space-region` vertically and between nav
- *   items, `--gutter` across, so the bar aligns with every inset `Section`.
- * - It is never sticky and needs no JavaScript: there is no `sticky` variant and nothing to hydrate.
- * - Omitting `navName` emits no `aria-label` at all, not an empty one.
+ * - The standing slot and the `<nav>` are the bar's two children whatever the caller passes, the nav
+ *   flush with the end content edge and absorbing narrowing by wrapping its links. Omitting `navName`
+ *   emits no `aria-label` at all, not an empty one.
+ *
+ * The status/action bar:
+ * - It renders no `<nav>`, no standing slot, no role, no name and no live region of its own. Each
+ *   filled slot is one `div` directly inside the banner; an omitted or withheld slot (`false`, `null`)
+ *   renders no box and reserves no space, so a status-only bar starts with its readout and an action-only
+ *   bar is the control alone at the end edge.
+ * - Reading and keyboard order is status, then action, and the DOM order is the same at every width.
+ * - With both fitting, the readout sits at the start content edge and the control at the end content
+ *   edge on one line. When they cannot share a line, the control drops below the readout and stays
+ *   flush with the end edge; a readout then takes the whole line and wraps inside it, unbroken wording
+ *   included, so the bar never widens the page and never clips.
+ * - Breaking is CSS alone: a width change re-flows the same elements, so descendant state and focus
+ *   survive it.
+ * - What the consumer passes keeps its semantics: a heading stays a heading, a live region stays one, a
+ *   disabled control stays disabled. Header adds, removes and announces nothing.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - A mark that should *fill* the standing slot is given a **definite width** by whoever placed it -
@@ -47,6 +97,10 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *   width; `flex: 1 1 0; min-width: 0` only collapses the mark when the bar is already out of room, so
  *   it is not the rule to reach for. The library cannot apply either rule for you: the same width on a
  *   place name would clamp the name and wrap it.
+ * - Set the type of what fills a status/action slot: the bar sets the label role, so a bare string in
+ *   `status` reads as a label, while a `P` or a `Note` wears its own role and a `Button` its own.
+ * - Whether a changing readout interrupts is yours to decide: wrap your own live region inside `status`
+ *   where a change must be announced, and leave it out where it must not. Header takes neither side.
  *
  * @UXGuidelines
  * - Name the nav with `navName` once the page has more than one navigation landmark - a footer nav will
@@ -55,6 +109,11 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *   `aria-current`, so set `current` on the `Link` and style nothing yourself.
  * - The nav does not collapse into a menu: a disclosure needs JavaScript, so on a narrow viewport the
  *   items wrap. A mobile menu is out of scope, not a follow-up.
+ * - A bar that reports and acts is a status/action bar, never a navigation bar with a button among its
+ *   links: a Balance line or a Continue button inside a `<nav>` is announced as navigation. A product
+ *   whose shell needs links as well as a control has two bars, not one.
+ * - Several readouts or several actions go in a `Cluster` inside the slot: `gap="stack"` keeps them one
+ *   group, and the Cluster wraps inside the slot before the bar runs out of room.
  */
 export declare const Header: FunctionComponent<IHeaderProps>;
 export {};