@silverpoint/core 0.6.0 → 0.8.0

package/dist/ui.d.ts

@@ -1,225 +1,37 @@
-import { n as Seed, t as GroundRef, u as SubstrateName, q as InkMode, ay as ToneLevel, o as Stroke, G as Geometry, aA as UiTokens, am as Ground, az as ToneSpec, v as ProviderConfig } from './props-Dq8FC8GG.js';
+import { S as StepStatus, a as StepItem, U as UiOrientation, b as UiItem, c as SpRadioGroupProps, d as SpRateProps, e as SpSegmentedProps, f as SpSliderProps, g as SpTabsProps, h as SpAlertProps, i as SpBadgeProps, j as SpProgressProps, k as SpSkeletonProps, l as SpStepsProps, m as SpTagProps, n as SpAvatarGroupProps, o as SpAvatarProps, p as SpBreadcrumbProps, q as SpCollapseProps, r as SpCollapseItemProps, s as SpDescriptionsProps, t as SpEmptyProps, u as SpGlyphProps, v as SpInputNumberProps, w as SpPaginationProps, x as SpResultProps, y as SpStatisticProps, z as SpSurfaceProps, A as SpTableProps, B as SpTextareaProps, D as SpTimelineListProps, E as SpDrawerProps, F as SpDropdownMenuProps, M as MenuEntry, G as SpModalProps, H as SpPopoverProps, I as SpSelectProps, J as SpToastProps, K as SpToasterProps, L as SpTooltipProps } from './types-D5ys35fF.js';
+export { N as AlertKind, O as BreadcrumbItem, C as CommonUiProps, P as DescriptionItem, Q as SpButtonProps, R as SpCardProps, T as SpCheckboxProps, V as SpDividerProps, W as SpInputProps, X as SpSwitchProps, Y as TableColumn, Z as TimelineListItem, _ as UI_FRAME_KINDS, $ as UiFrameKind, a0 as UiSize, a1 as UiToneLevel, a2 as UiVariant, a3 as uiFrameOutline, a4 as uiFrameVariant } from './types-D5ys35fF.js';
+import { o as Stroke, aB as UiTokens, am as Ground, aA as ToneSpec, x as Datum } from './props-BZ9CcrGv.js';
+import { U as UiResolved, a as UiElement } from './view-DteS9glE.js';
+export { b as UiAttrValue, c as UiBind, d as UiEnvironment, e as UiNode, f as UiSlot, r as resolveUi, u as uiButtonView, g as uiCardView, h as uiCheckboxView, i as uiDividerView, j as uiInputView, k as uiSwitchView } from './view-DteS9glE.js';
 
-/** Control size; heights come from the ground's `ui.controlHeight` (Data Model §3.8). */
-type UiSize = 'sm' | 'md' | 'lg';
-/** Props every UI component takes, as `CommonChartProps` does for charts (API Spec §3). */
-interface CommonUiProps {
-    /** The frame variant and every related id derive from it (REQ-307, REQ-329). */
-    id?: string;
-    /** Overrides `id` for the frame variant only. */
-    seed?: Seed;
-    /** Style ground. Defaults to the dashboard's, then the app provider's, or `silverpoint` (REQ-311). */
-    ground?: GroundRef;
-    /** Prepared substrate within the ground (REQ-046). */
-    substrate?: SubstrateName;
-    /** `ink` by default; `precision` disables inking (REQ-021, REQ-306). */
-    mode?: InkMode;
-    /** Default `'md'`. */
-    size?: UiSize;
-    /** Added to the component's root element, after its own classes. */
-    className?: string;
-}
-/** An item of Tabs, Segmented or RadioGroup; keys are unique (REQ-325). */
-interface UiItem {
-    key: string;
-    label: string;
-    disabled?: boolean;
-}
-type StepStatus = 'wait' | 'process' | 'finish' | 'error';
-interface StepItem {
-    key: string;
-    title: string;
-    description?: string;
-    /** Derived from `current` when omitted; `'error'` must be explicit. */
-    status?: StepStatus;
-}
-/** Button emphasis. Not a tone: `tone` names only a level 1-4 of the ground's ramp (A-07). */
-type UiVariant = 'default' | 'primary' | 'danger';
-type AlertKind = 'info' | 'success' | 'warning' | 'error';
-type UiOrientation = 'horizontal' | 'vertical';
-/** A tonal level a component may ask for; 0 (no fill) is not one. */
-type UiToneLevel = Exclude<ToneLevel, 0>;
-interface SpButtonProps extends CommonUiProps {
-    /** Default `'default'`; `danger` also draws the exact ✕ glyph (REQ-310). */
-    variant?: UiVariant;
-    /** Default `'button'`. */
-    type?: 'button' | 'submit' | 'reset';
-    /** Not focusable, not submitted; drawn with the disabled tone. */
-    disabled?: boolean;
-    /** Accessible name of an icon-only button (REQ-319). */
-    label?: string;
-    /** Fills the width of its container. */
-    block?: boolean;
-    /** Renders an `<a>`. */
-    href?: string;
-}
-interface SpInputProps extends CommonUiProps {
-    /** Native input type. Default `'text'`. */
-    type?: 'text' | 'search' | 'email' | 'url' | 'tel' | 'password' | 'number';
-    /** Hint shown while empty; not a substitute for the accessible name. */
-    placeholder?: string;
-    /** Form field name; the native input submits under it (REQ-323). */
-    name?: string;
-    /** Not focusable and not submitted. */
-    disabled?: boolean;
-    /** Focusable and submitted, but not editable. */
-    readOnly?: boolean;
-    /** Sets `aria-invalid` and draws the exact ⚠ glyph (REQ-334). */
-    invalid?: boolean;
-    /** Help or error text under the control, referenced by `aria-describedby` (REQ-334). */
-    message?: string;
-    /** Accessible name, when no `<label for>` names the control. */
-    label?: string;
-}
-interface SpCheckboxProps extends CommonUiProps {
-    /** The visible text and accessible name. */
-    label: string;
-    /** Form field name; submitted as `on` when checked. */
-    name?: string;
-    /** Not focusable and not submitted. */
-    disabled?: boolean;
-    /** Draws the exact dash and sets the native `indeterminate` state. */
-    indeterminate?: boolean;
-}
-interface SpRadioGroupProps extends CommonUiProps {
-    /** The choices; each a native radio. Keys are unique (REQ-325). */
-    items: readonly UiItem[];
-    /** Required: the native radios submit under it (REQ-323). */
-    name: string;
-    /** The group's name, its `<legend>`. */
-    label: string;
-    /** Default `'vertical'`. */
-    orientation?: UiOrientation;
-}
-interface SpSwitchProps extends CommonUiProps {
-    /** The visible text and accessible name. */
-    label: string;
-    /** Form field name; submitted as `on` when on. */
-    name?: string;
-    /** Not focusable and not submitted. */
-    disabled?: boolean;
-}
-interface SpSliderProps extends CommonUiProps {
-    /** Accessible name of the native range input. */
-    label: string;
-    /** Default `0`. */
-    min?: number;
-    /** Default `100`. */
-    max?: number;
-    /** Default `1`. */
-    step?: number;
-    /** Form field name; the native input submits under it. */
-    name?: string;
-    /** Not focusable and not submitted. */
-    disabled?: boolean;
-    /** Values on the rail that get a labelled mark. */
-    marks?: readonly number[];
-}
-interface SpRateProps extends CommonUiProps {
-    /** The group's name, its `<legend>`. */
-    label: string;
-    /** Default `5`, in 1..10; each mark an exact lozenge. */
-    count?: number;
-    /** Form field name; the native radios submit under it. */
-    name?: string;
-    /** Not focusable and not submitted. */
-    disabled?: boolean;
-    /** Shows the value; the keyboard and the pointer do not change it. */
-    readOnly?: boolean;
-}
-interface SpSegmentedProps extends CommonUiProps {
-    /** The options; each a native radio. Keys are unique (REQ-325). */
-    items: readonly UiItem[];
-    /** The control's name, its `<legend>`. */
-    label: string;
-    /** Form field name; the native radios submit under it. */
-    name?: string;
-    /** Fills the width of its container. */
-    block?: boolean;
-}
-interface SpTabsProps extends CommonUiProps {
-    /** The tabs; a disabled one is skipped by the arrows. Keys are unique (REQ-325). */
-    items: readonly UiItem[];
-    /** Accessible name of the tab list. */
-    label?: string;
-    /** Default `'horizontal'`. */
-    orientation?: UiOrientation;
-    /** Default `'automatic'`: a tab is selected as focus reaches it. */
-    activation?: 'automatic' | 'manual';
-}
-interface SpStepsProps extends CommonUiProps {
-    /** The steps, in order; a status is derived from `current` unless set. */
-    items: readonly StepItem[];
-    /** 0-based. */
-    current: number;
-    /** Default `'horizontal'`. */
-    orientation?: UiOrientation;
-    /** Accessible name of the list. */
-    label?: string;
-}
-interface SpCardProps extends CommonUiProps {
-    /** Heading of the card; without it the card is a plain container. */
-    title?: string;
-    /** Default `3`. */
-    headingLevel?: 2 | 3 | 4 | 5 | 6;
-}
-interface SpTagProps extends CommonUiProps {
-    /** Tonal level, default `1`. */
-    tone?: UiToneLevel;
-    /** Adds a native close button; each adapter raises its close event. */
-    closable?: boolean;
-    /** Accessible name of the close button. Default `Remove <text>`. */
-    closeLabel?: string;
-}
-interface SpBadgeProps extends CommonUiProps {
-    /** The number shown, up to `max`. */
-    count?: number;
-    /** Default `99`; above it the badge reads `99+`. */
-    max?: number;
-    /** A dot with no number. */
-    dot?: boolean;
-    /** Accessible text of the badge, e.g. `unread messages`. */
-    label?: string;
-}
-interface SpDividerProps extends CommonUiProps {
-    /** Default `'horizontal'`. */
-    orientation?: UiOrientation;
-    /** A caption set in the rule. */
-    text?: string;
-    /** Default `'center'`. */
-    align?: 'start' | 'center' | 'end';
-}
-interface SpProgressProps extends CommonUiProps {
-    /** 0..100; omitted, the progress is indeterminate. */
-    value?: number;
-    /** Default `'line'`. */
-    shape?: 'line' | 'circle';
-    /** Accessible name (REQ-318). */
-    label: string;
-    /** Default `true`. */
-    showValue?: boolean;
-}
-interface SpAlertProps extends CommonUiProps {
-    /** Default `'info'`. */
-    kind?: AlertKind;
-    /** Bold first line of the alert. */
-    title?: string;
-    /** Adds a native close button; each adapter raises its close event. */
-    closable?: boolean;
-    /** Accessible name of the close button. Default `'Close'`. */
-    closeLabel?: string;
-}
-interface SpSkeletonProps extends CommonUiProps {
-    /** Default `3`, in 1..8. */
-    lines?: number;
-    /** Draws an avatar placeholder before the lines. */
-    avatar?: boolean;
-    /** Default `'Loading'`. */
-    label?: string;
-}
+/** Exact glyphs in a 16 × 16 box: their strokes are values, never inked (REQ-304, REQ-310). */
+declare const UI_GLYPHS: Readonly<{
+    tick: "M3.5,8.5L6.5,11.5L12.5,4.5";
+    dash: "M4,8H12";
+    cross: "M4.5,4.5L11.5,11.5M11.5,4.5L4.5,11.5";
+    warning: "M8,2.5L14.5,13.5H1.5Z M8,6.5V9.5 M8,11.5V11.5";
+    /** A radio's selection: filled by ui.css. */
+    dot: "M11,8A3,3 0 1,1 5,8A3,3 0 1,1 11,8Z";
+    /** A Rate mark (C-2). */
+    lozenge: "M8,1.5L14.5,8L8,14.5L1.5,8Z";
+    info: "M14.5,8A6.5,6.5 0 1,1 1.5,8A6.5,6.5 0 1,1 14.5,8Z M8,7.5V11.5 M8,4.75V4.75";
+    plus: "M8,3.5V12.5M3.5,8H12.5";
+    chevronDown: "M4,6L8,10L12,6";
+    chevronRight: "M6,4L10,8L6,12";
+    chevronLeft: "M10,4L6,8L10,12";
+    arrowUp: "M8,12.5V3.5M4.5,7L8,3.5L11.5,7";
+    arrowDown: "M8,3.5V12.5M4.5,9L8,12.5L11.5,9";
+    sortUp: "M5,9.5L8,5.5L11,9.5Z";
+    sortDown: "M5,6.5L8,10.5L11,6.5Z";
+    sort: "M5,7L8,3.5L11,7Z M5,9L8,12.5L11,9Z";
+    ellipsis: "M3.5,8V8 M8,8V8 M12.5,8V8";
+}>;
+type UiGlyph = keyof typeof UI_GLYPHS;
 
 /** The catalog's groups (PRD §6.11), in the order the documentation lists them. */
-type UiGroup = 'actions' | 'data-entry' | 'navigation' | 'data-display' | 'feedback';
+type UiGroup = 'actions' | 'data-entry' | 'navigation' | 'data-display' | 'feedback' | 'building-blocks' | 'disclosure' | 'overlays';
+/** `ui`: the 17 of `0.3.0`; `composed` and `overlay`: feature-004's (API delta §2). */
+type UiFamily = 'ui' | 'composed' | 'overlay';
 /** One UI component: every gate, fixture set and example page iterates this list. */
 interface UiComponentRow {
     /** Catalog name, as the PRD writes it. */
@@ -229,12 +41,17 @@ interface UiComponentRow {
     /** The exported name, the same in the three adapters (OQ-U2). */
     readonly component: string;
     readonly group: UiGroup;
-    /** The batch of step 6c that implements it (plan-and-tasks.md). */
-    readonly batch: 'B1' | 'B2' | 'B3';
+    readonly family: UiFamily;
+    /** The batch that implements it: step 6c (`B*`) or step 8d (`A1`, `A2`, `B`) (plan-and-tasks.md). */
+    readonly batch: 'B1' | 'B2' | 'B3' | 'A1' | 'A2' | 'B';
     /** Declared states (Data Model §5); one fixture and one demo each. */
     readonly states: readonly string[];
 }
-/** The 17 components of `0.3.0` and their 45 declared states (REQ-300, Data Model §5). */
+/**
+ * The 17 components of `0.3.0` and their 45 declared states (REQ-300), then the 21 of feature-004
+ * and their 35 (REQ-470, Data Model delta §5). `SpTimeline` is not a row: it lives on its own
+ * subpath, with one fixture of its own.
+ */
 declare const UI_COMPONENTS: readonly UiComponentRow[];
 
 /** A linear value's domain. Without `step` the value is only clamped (Progress). */
@@ -332,30 +149,6 @@ declare function uiRovingKey(state: UiRovingState, key: UiRovingKey, orientation
 /** Whether a `KeyboardEvent.key` moves a roving focus: the arrows, Home and End (REQ-315). */
 declare const uiIsRovingKey: (key: string) => key is UiRovingKey;
 
-type UiFrameKind = 'control' | 'pill' | 'box' | 'card' | 'round';
-/**
- * Each frame kind is drawn once in a square box and cut into slices for the grounds build
- * (DD-022): four corners of `slice` px, and four edges between them when `size > 2 * slice`.
- * `round` and `box` have no edges; they frame fixed-size squares.
- */
-declare const UI_FRAME_KINDS: Readonly<Record<UiFrameKind, Readonly<{
-    size: number;
-    slice: number;
-    radius: number;
-}>>>;
-/**
- * The frame variant of a component: from `seed`, else `id`, by the charts' seed rule; `0` with
- * neither (REQ-307, I-21). Never from mount order, randomness or time (Art. 4). `variants` is read
- * as an integer in 1..6.
- */
-declare function uiFrameVariant(seed: Seed | undefined, id: string | undefined, variants: number): number;
-/**
- * The exact outline of a frame kind: the input the grounds build inks, once per variant, into the
- * pieces of `ui.css` (DD-022). It is an `ornament` stroke —a frame carries no value (Art. 1, as
- * amended)— so the ground's inker may draw it by hand, with its vertices preserved. Build time only.
- */
-declare function uiFrameOutline(kind: UiFrameKind): Geometry;
-
 /**
  * Keeps the first item of each key and skips later ones, and any item without a key, warning
  * `SP019` without throwing (REQ-325). Returns the input itself when every key is unique.
@@ -378,12 +171,17 @@ declare function uiRequireName(component: string, text: string | undefined, labe
 
 /** The `ui` tokens of a ground that declares none (Data Model §3.8). */
 declare const UI_TOKEN_DEFAULTS: UiTokens;
+type Level = 1 | 2 | 3 | 4;
 /**
  * A ground's `ui` tokens, or the defaults, held to their domain: heights ≥ 24 px, focus ≥ 2 px,
- * 1..6 variants. A `weight` ground has no inker that draws by hand, so its frame is always the
+ * 1..6 variants, backdrop and row tone a level 1..4 (2 and 1 when a section written before
+ * feature-004 has none). A `weight` ground has no inker that draws by hand, so its frame is always the
  * exact `css` one with a single variant (DD-022). Pure.
  */
-declare function resolveUiTokens(ground: Ground): UiTokens;
+declare function resolveUiTokens(ground: Ground): UiTokens & {
+    readonly backdrop: Level;
+    readonly rowTone: Level;
+};
 
 /** One repeating layer of a control's tone: a tile the grounds build inks and lays as a CSS mask. */
 interface UiToneLayer {
@@ -399,92 +197,207 @@ interface UiToneLayer {
  */
 declare function uiToneTile(spec: ToneSpec): readonly UiToneLayer[];
 
-/** Exact glyphs in a 16 × 16 box: their strokes are values, never inked (REQ-304, REQ-310). */
-declare const UI_GLYPHS: Readonly<{
-    tick: "M3.5,8.5L6.5,11.5L12.5,4.5";
-    dash: "M4,8H12";
-    cross: "M4.5,4.5L11.5,11.5M11.5,4.5L4.5,11.5";
-    warning: "M8,2.5L14.5,13.5H1.5Z M8,6.5V9.5 M8,11.5V11.5";
-    /** A radio's selection: filled by ui.css. */
-    dot: "M11,8A3,3 0 1,1 5,8A3,3 0 1,1 11,8Z";
-    /** A Rate mark (C-2). */
-    lozenge: "M8,1.5L14.5,8L8,14.5L1.5,8Z";
-    info: "M14.5,8A6.5,6.5 0 1,1 1.5,8A6.5,6.5 0 1,1 14.5,8Z M8,7.5V11.5 M8,4.75V4.75";
-}>;
-type UiGlyph = keyof typeof UI_GLYPHS;
+/**
+ * A table's rows in order of `key` (REQ-474, I-34): stable, `null` and missing values last in input
+ * order, `desc` reversing the present rows only. No locale, so the order is the same on every
+ * server. Pure: the input is never mutated.
+ */
+declare function uiSortRows<T extends Datum>(rows: readonly T[], key: string | undefined, order?: 'asc' | 'desc'): readonly T[];
 
+/** A page number, or a gap where pages are left out. */
+type UiPageEntry = number | 'start-gap' | 'end-gap';
+interface UiPagination {
+    /** Number of pages, at least 1. */
+    readonly count: number;
+    /** The current page as drawn, 1-based. */
+    readonly current: number;
+    /** First and last item shown, 1-based; 0 and 0 when there are none. */
+    readonly start: number;
+    readonly end: number;
+    /** An input was not drawable as given. */
+    readonly corrected: boolean;
+}
 /**
- * The markup contract of the UI components (API delta §4), as data: every adapter writes this tree
- * and nothing else, and the parity gate compares each adapter's server render with it (REQ-327).
- * An adapter binds behaviour —value, events, forms— to the elements marked `bind`, and puts the
- * consumer's content where a `slot` stands. It computes nothing (Art. 2).
+ * The pages a pagination shows (REQ-476, Data Model §2.27): the first, a gap, a window of
+ * `siblings` on each side of `current`, a gap, the last.
  */
-type UiAttrValue = string | true;
-interface UiElement {
-    readonly tag: string;
-    /** HTML attribute names; `true` is a boolean attribute. */
-    readonly attrs: Readonly<Record<string, UiAttrValue>>;
-    readonly children: readonly UiNode[];
-    /** What an adapter binds to the element: see `UiBind`. */
-    readonly bind?: UiBind;
+declare function uiPageWindow(count: number, current: number, siblings: number): readonly UiPageEntry[];
+/** Pages, the corrected current page and the `start–end of total` numbers; corrections warn `SP017` (REQ-486). */
+declare function uiPagination(total: number, pageSize: number, current: number, component?: string): UiPagination;
+
+/** The bounds, step and decimals of a number field; any of them may be absent. */
+interface UiNumberRange {
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    /** Decimals the value is rounded to. */
+    readonly precision?: number;
+}
+interface UiNumberValue {
+    /** The value to render; `null` for an empty field. */
+    readonly value: number | null;
+    readonly corrected: boolean;
+    /** The value sits on a bound: that stepper is disabled (REQ-485). */
+    readonly atMin: boolean;
+    readonly atMax: boolean;
+    /** The range as drawn: invalid bounds, step or precision left out. */
+    readonly range: UiNumberRange;
+}
+/** A number field's value clamped to `min`/`max` and rounded to `precision`; `null` stays `null` (REQ-485, REQ-486). */
+declare function uiNumberValue(value: number | null, range: UiNumberRange, component?: string): UiNumberValue;
+/** One stepper press: `value ± step` from the value, else from `min ?? 0`, then clamped and rounded (REQ-485). */
+declare function uiNumberStep(value: number | null, direction: 1 | -1, range: UiNumberRange, component?: string): number;
+
+/** An avatar's initials (REQ-478): the first letters of the first two words, upper-cased; '?' for none. */
+declare function uiInitials(name: string | undefined): string;
+
+/** The state an open or closed list overlay keeps: its active (highlighted) item and which are disabled. */
+interface UiListState {
+    /** The active item; `-1` when none is. */
+    readonly active: number;
+    readonly count: number;
+    readonly disabled: readonly boolean[];
+    readonly open: boolean;
+}
+/** The next active item, and what the adapter does: open the list, close it, or select the active item and close. */
+interface UiListResult {
+    readonly active: number;
+    readonly intent?: 'open' | 'close' | 'select';
 }
 /**
- * `native`: a control an adapter binds value, events and forms to —one, or one per item of a
- * composite, told apart by its `value` or `data-key`. `close`: the button that emits `close`.
+ * The WAI-ARIA APG transitions of a select-only combobox (`listbox`, REQ-494) and a menu button
+ * (`menu`, REQ-495), as a pure function of state and key (DD-039). Disabled items are skipped and
+ * never selected (REQ-326); a move with no enabled item to go to keeps the active one.
  */
-type UiBind = 'native' | 'close';
-type UiSlot = 'content' | 'prefix' | 'suffix' | 'extra' | 'footer';
-type UiNode = UiElement | {
-    readonly text: string;
-} | {
-    readonly slot: UiSlot;
-};
-/** What a component inherits around it: the provider, the dashboard cell, the environment. */
-interface UiEnvironment {
-    readonly provider?: ProviderConfig;
-    /** The configuration of the dashboard whose cell holds the component (REQ-311). */
-    readonly cell?: ProviderConfig;
-    /** `prefers-contrast: more` or `forced-colors: active` holds (REQ-123). */
-    readonly forcedPrecision?: boolean;
+declare function uiListKey(state: UiListState, key: string, kind: 'listbox' | 'menu'): UiListResult;
+/**
+ * Typeahead (REQ-494): the first enabled label that starts with `buffer`, searching from the item
+ * after `from` for one character (so repeating it cycles) and from `from` itself for several (so
+ * typing on stays put), wrapping; case-insensitive; `-1` when none matches. Pure.
+ */
+declare function uiTypeahead(labels: readonly string[], disabled: readonly boolean[], buffer: string, from: number): number;
+
+/** A box in viewport coordinates (`getBoundingClientRect`). */
+interface UiBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
 }
-interface UiResolved {
-    readonly ground: string;
-    readonly substrate: SubstrateName;
-    readonly mode: InkMode;
-    readonly size: UiSize;
-    /** 0..5: `ui.css` folds it onto the variants the ground draws. */
-    readonly frame: number;
+/** Logical sides: `start` and `end` are left and right in `ltr`, mirrored in `rtl` (REQ-523). */
+type UiSide = 'top' | 'end' | 'bottom' | 'start';
+type UiAlign = 'start' | 'center' | 'end';
+interface UiPlaceInput {
+    readonly anchor: UiBox;
+    readonly floating: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly side: UiSide;
+    readonly align: UiAlign;
+    /** Gap between the anchor and the overlay, px. */
+    readonly offset: number;
+    /** The overlay keeps this far from the viewport's edges, px. */
+    readonly padding: number;
+    readonly dir: 'ltr' | 'rtl';
+}
+interface UiPlacement {
+    /** The overlay's top-left corner, viewport px, 2 decimals. */
+    readonly x: number;
+    readonly y: number;
+    /** The side it ended on, after any flip. */
+    readonly side: UiSide;
+    readonly align: UiAlign;
 }
 /**
- * Ground, substrate and mode with the charts' precedence: prop, then dashboard, then provider,
- * then the library default; a forced `precision` applies after, and nothing overrides it (REQ-311).
+ * Where an anchored overlay goes (REQ-493, I-35): on the preferred side of its anchor, flipped to the
+ * opposite side when it does not fit there and fits there, aligned along the side, then shifted to
+ * stay in the viewport. Pure.
  */
-declare function resolveUi(props: CommonUiProps, env: UiEnvironment): UiResolved;
-/** `SpButton`: a native `<button>`, or `<a>` with `href` (REQ-314, REQ-310). */
-declare function uiButtonView(props: SpButtonProps, r: UiResolved, content: {
-    readonly text?: string;
-}): UiElement;
-/** `SpInput`: a native `<input>` in a framed box, its message after it (REQ-314, REQ-334). */
-declare function uiInputView(props: SpInputProps, r: UiResolved, state: {
-    readonly value: string;
-    readonly prefix?: boolean;
-    readonly suffix?: boolean;
-}): UiElement;
-/** `SpCheckbox`: native state; the tick and dash are drawn and shown by it (REQ-310). */
-declare function uiCheckboxView(props: SpCheckboxProps, r: UiResolved, state: {
-    readonly checked: boolean;
-}): UiElement;
-/** `SpSwitch`: a native checkbox with `role="switch"`, a pill track and an exact knob (REQ-314). */
-declare function uiSwitchView(props: SpSwitchProps, r: UiResolved, state: {
-    readonly checked: boolean;
-}): UiElement;
-/** `SpCard`: an `<article>` named by its heading, or a `<section>` without a title (REQ-318). */
-declare function uiCardView(props: SpCardProps, r: UiResolved, slots: {
-    readonly extra?: boolean;
-    readonly footer?: boolean;
-}): UiElement;
-/** `SpDivider`: a `separator`; with text, the text between two rules (REQ-318). */
-declare function uiDividerView(props: SpDividerProps, r: UiResolved): UiElement;
+declare function uiPlace(input: UiPlaceInput): UiPlacement;
+
+/** A measured rectangle, in viewport pixels. */
+interface UiRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** The window an overlay is placed in, as much of it as this reads; the core has no DOM types. */
+interface UiAnchorView {
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+    addEventListener(type: string, listener: () => void, options?: boolean | {
+        readonly capture?: boolean;
+        readonly passive?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: () => void, options?: boolean | {
+        readonly capture?: boolean;
+    }): void;
+    /** Absent in an engine without it: the overlay is then placed on scroll and resize only. */
+    readonly ResizeObserver?: new (callback: () => void) => {
+        observe(target: never): void;
+        disconnect(): void;
+    };
+}
+/** The trigger an overlay hangs from. */
+interface UiAnchorTarget {
+    getBoundingClientRect(): UiRect;
+    closest(selector: string): {
+        getAttribute(name: string): string | null;
+    } | null;
+}
+/** The overlay: measured, then given `--sp-ui-x`, `--sp-ui-y` and `data-side`. */
+interface UiAnchorFloating {
+    getBoundingClientRect(): UiRect;
+    setAttribute(name: string, value: string): void;
+    readonly style: {
+        setProperty(name: string, value: string): void;
+    };
+    readonly ownerDocument: {
+        readonly defaultView: UiAnchorView | null;
+    } | null;
+}
+interface UiAnchorOptions {
+    readonly side: UiSide;
+    readonly align: UiAlign;
+    /** Gap between the trigger and the overlay, px (`6`). */
+    readonly offset?: number;
+    /** Least distance to the viewport's edges, px (`8`). */
+    readonly padding?: number;
+}
+/**
+ * The DOM side of an anchored overlay, as `uiRovingFocus` is for REQ-315 (REQ-493): measures the
+ * trigger and the overlay, places it with `uiPlace` in the nearest `dir`, and writes `--sp-ui-x`,
+ * `--sp-ui-y` and `data-side`; again on every scroll and resize, and whenever the trigger or the
+ * overlay changes size (a web font replacing its fallback), until the returned cleanup runs.
+ * Client only, on open.
+ */
+declare function uiAnchor(anchor: UiAnchorTarget, floating: UiAnchorFloating, options: UiAnchorOptions): () => void;
+
+/** How an overlay opens: `showModal()`, `show()`, or the Popover API (DD-038). */
+type UiOverlayKind = 'modal' | 'dialog' | 'popover';
+/** A `<dialog>` or a `[popover]` element, as much of it as this reads; the core has no DOM types. */
+interface UiOverlayElement {
+    readonly open?: boolean;
+    showModal?(): void;
+    show?(): void;
+    close?(): void;
+    showPopover?(): void;
+    hidePopover?(): void;
+    matches(selector: string): boolean;
+}
+/**
+ * Opens or closes a native overlay as its state says (REQ-491, REQ-492): `showModal()` or `show()`
+ * and `close()` for a `<dialog>`, `showPopover()` and `hidePopover()` for a popover, each only when
+ * the element is in the other state, so no second `close` or `toggle` event is fired. Without the
+ * Popover API the popover stays in the page's flow. Client only, after mount (REQ-502).
+ */
+declare function uiOverlaySync(element: UiOverlayElement, kind: UiOverlayKind, open: boolean): void;
 
 /** `SpRadioGroup`: a `<fieldset>` of native radios; the value `null` checks none (REQ-314, REQ-322). */
 declare function uiRadioGroupView(props: SpRadioGroupProps, r: UiResolved, state: {
@@ -542,4 +455,112 @@ declare function uiAlertView(props: SpAlertProps, r: UiResolved, state: {
 /** `SpSkeleton`: `aria-busy`, a label for assistive technology, and hidden toned shapes (REQ-318). */
 declare function uiSkeletonView(props: SpSkeletonProps, r: UiResolved): UiElement;
 
-export { type AlertKind, type CommonUiProps, type SpAlertProps, type SpBadgeProps, type SpButtonProps, type SpCardProps, type SpCheckboxProps, type SpDividerProps, type SpInputProps, type SpProgressProps, type SpRadioGroupProps, type SpRateProps, type SpSegmentedProps, type SpSkeletonProps, type SpSliderProps, type SpStepsProps, type SpSwitchProps, type SpTabsProps, type SpTagProps, type StepItem, type StepStatus, UI_COMPONENTS, UI_FRAME_KINDS, UI_GLYPHS, UI_PROGRESS_VIEWBOX, UI_TOKEN_DEFAULTS, type UiAttrValue, type UiBind, type UiComponentRow, type UiElement, type UiEnvironment, type UiFrameKind, type UiGlyph, type UiGroup, type UiItem, type UiNode, type UiOrientation, type UiRange, type UiResolved, type UiRovingKey, type UiRovingRoot, type UiRovingState, type UiSize, type UiSlot, type UiStep, type UiToneLayer, type UiToneLevel, type UiValue, type UiVariant, resolveUi, resolveUiTokens, uiAlertView, uiBadgeView, uiButtonView, uiCardView, uiCheckboxView, uiDividerView, uiFrameOutline, uiFrameVariant, uiInputView, uiIsRovingKey, uiItems, uiProgressArc, uiProgressView, uiRadioGroupView, uiRange, uiRateCount, uiRateView, uiRequireName, uiRovingFocus, uiRovingKey, uiSegmentedView, uiSelectedKey, uiSkeletonView, uiSliderView, uiSteps, uiStepsView, uiSwitchView, uiTabPanelView, uiTabsView, uiTagView, uiToneTile, uiValue };
+/** `SpSurface`: the root contract on any element, with an optional frame and tone (REQ-472). */
+declare function uiSurfaceView(props: SpSurfaceProps, r: UiResolved): UiElement;
+/** `SpGlyph`: one exact mark of `UI_GLYPHS` (REQ-472). */
+declare function uiGlyphView(props: SpGlyphProps, r: UiResolved): UiElement;
+/** `SpTable`: a native table in a framed scroller; sortable headers are buttons that report the key (REQ-473, REQ-474). */
+declare function uiTableView(props: SpTableProps, r: UiResolved): UiElement;
+/** `SpPagination`: a labelled nav; pages are buttons, the current one a heightened span (REQ-476). */
+declare function uiPaginationView(props: SpPaginationProps, r: UiResolved, state: {
+    readonly current: number;
+}): UiElement;
+/** `SpBreadcrumb`: a labelled nav of an ordered list; the last item is the current page (REQ-477). */
+declare function uiBreadcrumbView(props: SpBreadcrumbProps, r: UiResolved): UiElement;
+/** `SpAvatar`: an image, or initials named as an image; a round or box frame (REQ-478). */
+declare function uiAvatarView(props: SpAvatarProps, r: UiResolved): UiElement;
+/** `SpAvatarGroup`: a labelled group of avatars (REQ-478). */
+declare function uiAvatarGroupView(props: SpAvatarGroupProps, r: UiResolved): UiElement;
+/** `SpStatistic`: the trend is carried by an exact arrow and by text, never by tone alone (REQ-479). */
+declare function uiStatisticView(props: SpStatisticProps, r: UiResolved): UiElement;
+/** `SpDescriptions`: a section named by its heading around a `<dl>` (REQ-480). */
+declare function uiDescriptionsView(props: SpDescriptionsProps, r: UiResolved): UiElement;
+/** `SpTimelineList`: an ordered list; each status by its mark's shape, one current (REQ-481). */
+declare function uiTimelineListView(props: SpTimelineListProps, r: UiResolved): UiElement;
+/** `SpCollapse`: a frame around its items; `accordion` gives them one `<details name>` (REQ-482). */
+declare function uiCollapseView(props: SpCollapseProps, r: UiResolved): UiElement;
+/** The `name` an accordion's items share, `${id}--accordion`, the same in every adapter (REQ-329, DD-040). */
+declare function uiCollapseGroup(props: SpCollapseProps): string | undefined;
+/** `SpCollapseItem`: a native `<details>`; `group` is its accordion's shared name (REQ-482). */
+declare function uiCollapseItemView(props: SpCollapseItemProps, r: UiResolved, state: {
+    readonly open: boolean;
+    readonly group?: string;
+}): UiElement;
+/** `SpEmpty`: a toned tray and a description (REQ-483). */
+declare function uiEmptyView(props: SpEmptyProps, r: UiResolved, slots: {
+    readonly extra?: boolean;
+}): UiElement;
+/** `SpResult`: the status glyph in a round frame; status or alert by its kind (REQ-483). */
+declare function uiResultView(props: SpResultProps, r: UiResolved, slots: {
+    readonly extra?: boolean;
+}): UiElement;
+/** `SpTextarea`: a native `<textarea>` on the `SpInput` contract, with an optional counter (REQ-484). */
+declare function uiTextareaView(props: SpTextareaProps, r: UiResolved, state: {
+    readonly value: string;
+}): UiElement;
+/** `SpInputNumber`: a native number input between exact − and + steppers (REQ-485, REQ-486). */
+declare function uiInputNumberView(props: SpInputNumberProps, r: UiResolved, state: {
+    readonly value: number | null;
+}): UiElement;
+
+type UiTriggerKind = 'dialog' | 'popover' | 'menu' | 'tooltip';
+/** Where a consumer's trigger goes: the adapter binds the element inside it (REQ-500). */
+declare function uiTriggerView(): UiElement;
+/**
+ * The ARIA an overlay sets on a consumer's trigger, at runtime (REQ-500): `aria-haspopup`,
+ * `aria-expanded` and `aria-controls` as its APG pattern asks; a tooltip's `aria-describedby`.
+ * The relations need the instance `id`.
+ */
+declare function uiTriggerAria(kind: UiTriggerKind, id: string | undefined, open: boolean): Readonly<Record<string, string>>;
+/** A Select's items: a string is its own key and label; repeated keys skipped, `SP019` (REQ-325). */
+declare function uiSelectItems(items: readonly (string | UiItem)[]): readonly UiItem[];
+/** A menu's actionable items, in order: what `uiListKey` and `uiTypeahead` move over (REQ-495). */
+declare function uiMenuItems(entries: readonly MenuEntry[]): readonly UiItem[];
+/** How long a toast stays: its own duration, the toaster's, or 5000 ms; at least 1000 or `Infinity` (Data Model §2.27). */
+declare function uiToastDuration(duration: number | undefined, toaster?: number): number;
+/** `SpModal`: a native dialog opened with `showModal()` (REQ-491). */
+declare function uiModalView(props: SpModalProps, r: UiResolved, s: {
+    readonly open: boolean;
+}, slots: {
+    readonly footer?: boolean;
+}): UiElement;
+/** `SpDrawer`: the same dialog on a logical side (REQ-491, REQ-523). */
+declare function uiDrawerView(props: SpDrawerProps, r: UiResolved, s: {
+    readonly open: boolean;
+}, slots: {
+    readonly footer?: boolean;
+}): UiElement;
+/** `SpPopover`: an `auto` popover with the dialog role (REQ-492). */
+declare function uiPopoverView(props: SpPopoverProps, r: UiResolved, s: {
+    readonly open: boolean;
+}): UiElement;
+/** `SpTooltip`: a `manual` popover, so it never closes an open `auto` one (REQ-492, REQ-496). */
+declare function uiTooltipView(props: SpTooltipProps, r: UiResolved, s: {
+    readonly open: boolean;
+}): UiElement;
+/** `SpSelect`: the APG select-only combobox; focus stays on the trigger (REQ-494, REQ-498, DD-039). */
+declare function uiSelectView(props: SpSelectProps, r: UiResolved, s: {
+    readonly value: string | null;
+    readonly open: boolean;
+    readonly active: string | null;
+}): UiElement;
+/** `SpDropdownMenu`: the APG menu button; DOM focus moves to the active item (REQ-495, REQ-498, DD-039). */
+declare function uiDropdownMenuView(props: SpDropdownMenuProps, r: UiResolved, s: {
+    readonly open: boolean;
+    readonly active: string | null;
+}, slots: {
+    readonly trigger?: boolean;
+}): UiElement;
+/**
+ * `SpToast`: its kind by glyph and text, announced politely or assertively (REQ-497). The live
+ * role is on the toast's body: a list item may not take another role.
+ */
+declare function uiToastView(props: SpToastProps, r: UiResolved, s: {
+    readonly open: boolean;
+}, slots: {
+    readonly action?: boolean;
+}): UiElement;
+/** `SpToaster`: a labelled region holding its toasts (REQ-497). */
+declare function uiToasterView(props: SpToasterProps, r: UiResolved): UiElement;
+
+export { MenuEntry, SpAlertProps, SpAvatarGroupProps, SpAvatarProps, SpBadgeProps, SpBreadcrumbProps, SpCollapseItemProps, SpCollapseProps, SpDescriptionsProps, SpDrawerProps, SpDropdownMenuProps, SpEmptyProps, SpGlyphProps, SpInputNumberProps, SpModalProps, SpPaginationProps, SpPopoverProps, SpProgressProps, SpRadioGroupProps, SpRateProps, SpResultProps, SpSegmentedProps, SpSelectProps, SpSkeletonProps, SpSliderProps, SpStatisticProps, SpStepsProps, SpSurfaceProps, SpTableProps, SpTabsProps, SpTagProps, SpTextareaProps, SpTimelineListProps, SpToastProps, SpToasterProps, SpTooltipProps, StepItem, StepStatus, UI_COMPONENTS, UI_GLYPHS, UI_PROGRESS_VIEWBOX, UI_TOKEN_DEFAULTS, type UiAlign, type UiAnchorFloating, type UiAnchorOptions, type UiAnchorTarget, type UiBox, type UiComponentRow, UiElement, type UiFamily, type UiGlyph, type UiGroup, UiItem, type UiListResult, type UiListState, type UiNumberRange, type UiNumberValue, UiOrientation, type UiOverlayElement, type UiOverlayKind, type UiPageEntry, type UiPagination, type UiPlaceInput, type UiPlacement, type UiRange, UiResolved, type UiRovingKey, type UiRovingRoot, type UiRovingState, type UiSide, type UiStep, type UiToneLayer, type UiTriggerKind, type UiValue, resolveUiTokens, uiAlertView, uiAnchor, uiAvatarGroupView, uiAvatarView, uiBadgeView, uiBreadcrumbView, uiCollapseGroup, uiCollapseItemView, uiCollapseView, uiDescriptionsView, uiDrawerView, uiDropdownMenuView, uiEmptyView, uiGlyphView, uiInitials, uiInputNumberView, uiIsRovingKey, uiItems, uiListKey, uiMenuItems, uiModalView, uiNumberStep, uiNumberValue, uiOverlaySync, uiPageWindow, uiPagination, uiPaginationView, uiPlace, uiPopoverView, uiProgressArc, uiProgressView, uiRadioGroupView, uiRange, uiRateCount, uiRateView, uiRequireName, uiResultView, uiRovingFocus, uiRovingKey, uiSegmentedView, uiSelectItems, uiSelectView, uiSelectedKey, uiSkeletonView, uiSliderView, uiSortRows, uiStatisticView, uiSteps, uiStepsView, uiSurfaceView, uiTabPanelView, uiTableView, uiTabsView, uiTagView, uiTextareaView, uiTimelineListView, uiToastDuration, uiToastView, uiToasterView, uiToneTile, uiTooltipView, uiTriggerAria, uiTriggerView, uiTypeahead, uiValue };