@cosmicdrift/kumiko-renderer 0.328.0 → 0.329.0

package/dist/primitives.d.ts

@@ -0,0 +1,1355 @@
+import type { ConfigCascade, ConfigScope, ConfigValueSource } from "@cosmicdrift/kumiko-framework/engine";
+import type { FieldIconKey, FormWidth, IconKey, NavIconKey, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FieldIssue, ListColumnViewModel, ListRowViewModel, RuntimeRenderer } from "@cosmicdrift/kumiko-headless";
+import { type ComponentType, type FormEvent, type KeyboardEvent, type ReactNode, type Ref } from "react";
+export type { RuntimeRenderer };
+/** Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't
+ *  warrant a dedicated typed prop. Web merges these onto the rendered
+ *  element; native impls ignore it (precedent: `className`). */
+export type DataAttributes = Readonly<Record<`data-${string}`, string>>;
+/** Structural marker a top-level `actions` node can carry so DefaultForm's
+ *  sticky-footer split (fw#1918) treats it as the pinned primary action even
+ *  though it isn't a `Button` with `type="submit"` — e.g. RenderEdit's
+ *  footer-slot mount, whose actual rendered button is opaque app code the
+ *  split can't inspect (see `ScreenSlots.footerPrimary`). */
+export declare const STICKY_PRIMARY_ACTION_PROP: "kumikoStickyPrimaryAction";
+export type StickyPrimaryActionMarker = Partial<Record<typeof STICKY_PRIMARY_ACTION_PROP, boolean>>;
+/** Standard-Button. `loading` zeigt einen Spinner statt der Children
+ *  und sollte mit `disabled` kombiniert werden, wenn die Action wirklich
+ *  blockiert bis das Loading durch ist (z.B. async submit). Native-
+ *  Impls können den Spinner als Activity-Indicator rendern. */
+export type ButtonProps = {
+    readonly type?: "button" | "submit";
+    readonly onClick?: () => void | Promise<void>;
+    readonly disabled?: boolean;
+    /** Spinner statt Children rendern. Caller sollte `disabled` mit-
+     *  setzen wenn die Action blockiert bis das Loading abgeschlossen
+     *  ist (verhindert Double-Submit). */
+    readonly loading?: boolean;
+    /** Semantic class — default="primary". Custom impls decide what this
+     *  becomes visually; the renderers use "primary" for Save, "danger" for
+     *  Delete, "secondary" for a Confirm state, "link" for inline actions in
+     *  running text (no background, underline), "danger-ghost" for a
+     *  destructive action as red text instead of a red fill, "ghost" for a
+     *  low-emphasis primary-colored text action beside a filled primary. */
+    readonly variant?: "primary" | "secondary" | "danger" | "link" | "danger-ghost" | "ghost";
+    /** Größe — default="md". "sm" für kompakte Inline-Aktionen (Toolbar,
+     *  Listen-Zeilen), "icon" für quadratische Icon-only-Buttons. */
+    readonly size?: "sm" | "md" | "icon";
+    /** Barrierefreies Label — Pflicht bei icon-only-Buttons (children ist nur
+     *  ein Icon/Zeichen), sonst hat der Button keinen zugänglichen Namen. */
+    readonly ariaLabel?: string;
+    /** Tooltip — web renders the native `title` attribute, native impls may ignore it. */
+    readonly title?: string;
+    /** Toggle state for toggle buttons — web sets `aria-pressed`; leave unset for plain buttons. */
+    readonly pressed?: boolean;
+    /** Breite — default="auto" (inhaltsbreit). "full" streckt CTA-Buttons auf
+     *  die Container-Breite (Karten/Panels). Andere Breiten sind Layout-Sache
+     *  des Containers, kein Button-Prop (Kit hält arbiträres Sizing draußen). */
+    readonly width?: "full" | "auto";
+    /** Optional for icon-only buttons (`size="icon"` with a resolved `icon`)
+     *  — the icon carries the content then, `ariaLabel` the accessible name.
+     *  Required in practice otherwise: without children and without `icon`
+     *  the button stays empty. */
+    readonly children?: ReactNode;
+    readonly testId?: string;
+    /** Layout extras — Web merges via cn(), native impls ignore it
+     *  (precedent: LinkProps.className). */
+    readonly className?: string;
+    /** DOM ref on the button — escape hatch for cases that need more than
+     *  a click (e.g. binding a drop-target handler). Web forwards it, native
+     *  impls ignore it (no native equivalent). */
+    readonly ref?: Ref<HTMLButtonElement>;
+    /** Icon before the label. */
+    readonly icon?: NavIconKey;
+    /** Icon after the label (e.g. "Continue →"). */
+    readonly iconEnd?: NavIconKey;
+    readonly dataAttributes?: DataAttributes;
+};
+/** Navigations-Link. `variant="button"` rendert die Button-Optik auf einem
+ *  semantischen Anchor (z.B. „Zum Login" nach Reset-Success), `muted` den
+ *  dezenten Sekundär-Link. Interne SPA-Navigation läuft über den Browser-
+ *  Default (History-Integration liegt beim Nav-Layer, nicht am Primitive). */
+export type LinkProps = {
+    readonly href: string;
+    readonly variant?: "default" | "button" | "muted";
+    /** `_blank` makes the web impl set `rel="noopener noreferrer"` unless
+     *  `rel` is set explicitly. */
+    readonly target?: "_blank" | "_self" | "_parent" | "_top";
+    readonly rel?: string;
+    /** Layout-Zusätze (self-center, text-xs) — Web merged via cn(),
+     *  Native-Impls ignorieren es (Präzedenz: CardProps.className). */
+    readonly className?: string;
+    readonly children: ReactNode;
+    readonly testId?: string;
+    readonly dataAttributes?: DataAttributes;
+};
+/** Banner für inline-Message ODER Page-State (z.B. "Loading…",
+ *  "Screen not found"). `padded` setzt einen Außenabstand damit der
+ *  Banner nicht edge-to-edge an den Main-Border klebt — relevant
+ *  seit `<main>` kein eigenes Padding mehr hat. */
+export type BannerProps = {
+    /** "error" for alerts (conflict, network error), "info" for neutral
+     *  placeholders (not-found, loading), "loading" for load states, "warning"
+     *  for a non-blocking but attention-grabbing notice (e.g. secretMint's
+     *  "this is shown only once"). */
+    readonly variant?: "error" | "info" | "loading" | "warning";
+    readonly children: ReactNode;
+    /** Optional — weitere Knöpfe/Elemente rechts vom Text (z.B. "Neu
+     *  laden"). Inline, nicht als eigener Block. */
+    readonly actions?: ReactNode;
+    /** Setzt einen Außenabstand um den Banner — für Page-States wo der
+     *  Banner alleine im Main rendert (KumikoScreen "not-found",
+     *  "loading", etc.). Web fügt p-6 als Margin um den Banner. */
+    readonly padded?: boolean;
+    readonly testId?: string;
+    /** Set when a `<Field>` wraps this Banner as its control (no actual
+     *  input exists for the label to target — see render-field.tsx's
+     *  unsupported-field-type fallback, #1834). The web implementation uses
+     *  it to derive `role="group"` + `aria-labelledby`, not `htmlFor`: a
+     *  `<label for>` on a non-labelable element like a `<div>` is inert for
+     *  screen readers. */
+    readonly id?: string;
+};
+export type FieldProps = {
+    readonly id: string;
+    readonly label: string;
+    readonly required?: boolean;
+    readonly issues?: readonly FieldIssue[];
+    readonly labelAppendix?: ReactNode;
+    readonly fieldAppendix?: ReactNode;
+    readonly children: ReactNode;
+    /** Label-Layout. `stacked` (Default): Label über dem Control. `inline`:
+     *  Control + Label nebeneinander (Box links, Label rechts) — für
+     *  Checkbox/Switch-Felder (boolean), wie das shadcn-Muster. */
+    readonly layout?: "stacked" | "inline";
+    /** Collapses the visible label to `sr-only` — stays associated via
+     *  `htmlFor` (no separate `aria-label` needed). For tables/grids whose
+     *  column header already carries the label for each row. */
+    readonly hideLabel?: boolean;
+    /** Marks the field as edited relative to its saved value — the label row
+     *  shows a "changed" marker. Set only in edit mode for fields present in
+     *  the form's change set. */
+    readonly changed?: boolean;
+    readonly testId?: string;
+};
+/** Discriminated union — jede Input-Sorte hat ihre eigene value/onChange
+ *  Signatur. Custom-Impls dispatchen intern, rendern anders (Toggle
+ *  statt Checkbox), oder nur einzelne kinds unterschiedlich. */
+export type InputProps = {
+    readonly kind: "text";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    /** Hint-Text wenn das Feld leer ist. Used für Search-Inputs in
+     *  Toolbars ("Suchen…") wo kein Label sinnvoll ist. */
+    readonly placeholder?: string;
+    /** Browser-Autofill / Native-Keyboard-Hint. Web setzt das auf
+     *  `<input autocomplete=...>`, Native auf `textContentType`. */
+    readonly autoComplete?: string;
+    /** `data-testid` aufs echte `<input>` — App-Tests adressieren das
+     *  Element direkt (getByTestId + readOnly/disabled-Assertions). */
+    readonly testId?: string;
+    /** Read-only Input (z.B. gewürfelter Free-Tier-Slug). Nicht `disabled`
+     *  — bleibt fokussier-/kopierbar. */
+    readonly readOnly?: boolean;
+    /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
+    readonly icon?: FieldIconKey;
+    readonly dataAttributes?: DataAttributes;
+    /** Raw keydown access (e.g. Enter-to-submit at the field instead of
+     *  the surrounding Form). Web forwards it, native impls ignore it
+     *  (precedent: `ButtonProps.ref`). */
+    readonly onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+} | {
+    readonly kind: "email";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    readonly placeholder?: string;
+    /** Default "email". Apps die "username" wollen (Login-Form mit
+     *  Username-or-Email) reichen das durch. */
+    readonly autoComplete?: string;
+    readonly testId?: string;
+} | {
+    readonly kind: "password";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    /** Hint text shown when the field is empty (analog to kind:"text"). */
+    readonly placeholder?: string;
+    /** "current-password" für Login, "new-password" für Reset/Signup —
+     *  Browser-Password-Manager nutzen das für die Speicherentscheidung.
+     *  Native: textContentType="password" / "newPassword". */
+    readonly autoComplete?: "current-password" | "new-password";
+    readonly testId?: string;
+} | {
+    readonly kind: "number";
+    readonly id: string;
+    readonly name: string;
+    readonly value: number | "";
+    readonly onChange: (v: number | undefined) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    /** Hint text shown when the field is empty (analog to kind:"text"). */
+    readonly placeholder?: string;
+    readonly testId?: string;
+    /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
+    readonly icon?: FieldIconKey;
+    /** `<input step>`. "any" disables the native stepMismatch constraint
+     *  (needed for decimal fields — integer fields leave this unset). */
+    readonly step?: number | "any";
+    /** Resolved display suffix (static or from a sibling field) — never
+     *  part of the numeric value. */
+    readonly unit?: string;
+} | {
+    readonly kind: "range";
+    readonly id: string;
+    readonly name: string;
+    readonly value: number;
+    readonly onChange: (v: number) => void;
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "boolean";
+    readonly id: string;
+    readonly name: string;
+    readonly value: boolean;
+    readonly onChange: (v: boolean) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "file" | "image";
+    readonly id: string;
+    readonly name: string;
+    /** FileRef-UUID (gespeicherte Datei) oder null (kein Upload). */
+    readonly value: string | null;
+    readonly onChange: (fileId: string | null) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    /** Erlaubte Extensions/MIME (z.B. ["jpg","png"]) → `accept`-Attribut. */
+    readonly accept?: readonly string[];
+    readonly maxSize?: string;
+    /** Für den Upload-POST `/api/files` — der Endpoint prüft maxSize/accept
+     *  gegen die Field-Def von (entityType, fieldName). */
+    readonly entityType?: string;
+    readonly fieldName?: string;
+    /** Only for kind:"image" — variant name for the preview
+     *  (`/api/files/:id/variant/:name`). Absent → the original. */
+    readonly imageVariant?: string;
+    /** Only for kind:"image" — forwarded to the file input's `capture`
+     *  attribute so a phone opens the camera instead of the file picker. */
+    readonly capture?: "environment" | "user";
+} | {
+    readonly kind: "date";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string | undefined) => void;
+    /** Locale für Anzeige UND Eingabe-Parsing. Default = Browser-Locale
+     *  via navigator.language. Apps mit eigenem LocaleResolver können
+     *  ihren current locale durchreichen. */
+    readonly locale?: string;
+    /** Datumsgrenzen als ISO `yyyy-mm-dd` — begrenzen Picker (Jahres-
+     *  Dropdown-Range + ausgegraute Tage). */
+    readonly min?: string;
+    readonly max?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "select";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    /** Erlaubte Werte. Leeres Array → Dropdown ohne Optionen, ein
+     *  required Field ist dann nicht erfüllbar (Author-Hinweis, nicht
+     *  Endnutzer). String-Form für statische Listen (Wert == Label),
+     *  {value,label}-Form für DB-getragene Refs (Tier 2.7e-3). */
+    readonly options: readonly string[] | readonly {
+        readonly value: string;
+        readonly label: string;
+        /** Second line under the label; shown by `radioVariant="card"`. */
+        readonly description?: string;
+    }[];
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    /** `"card"` renders the radio group as bordered cards with label plus
+     *  optional description per option and always uses the radio group,
+     *  regardless of option count or `display`. Default `"list"`. */
+    readonly radioVariant?: "list" | "card";
+    /** Requested presentation. `"radio"` renders the options as a visible
+     *  radio group (WAI-ARIA radiogroup, one click per choice),
+     *  `"dropdown"` renders the combobox. Omitted = the implementation
+     *  decides; the web impl keeps its short-option-set heuristic. Custom
+     *  impls may ignore it — it is a request, not a contract. */
+    readonly display?: "radio" | "dropdown";
+} | ({
+    readonly kind: "combobox";
+    readonly id: string;
+    readonly name: string;
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    readonly placeholder?: string;
+    readonly searchPlaceholder?: string;
+    readonly emptyText?: string;
+    /** Tier 2.7e Remote-Search: gesetzt = Combobox läuft im Remote-
+     *  Mode (cmdk-Local-Filter aus, Search-Input ruft onSearchChange
+     *  debounced an den Caller). */
+    readonly onSearchChange?: (q: string) => void;
+    readonly loading?: boolean;
+    /** Fixed "+ createLabel" footer row that fires instead of
+     *  selecting an option — omit for the plain select-existing
+     *  combobox (kumiko-framework#1681). */
+    readonly onCreate?: () => void;
+    readonly createLabel?: string;
+} & ({
+    readonly multiple?: false;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+} | {
+    readonly multiple: true;
+    readonly value: readonly string[];
+    readonly onChange: (v: readonly string[]) => void;
+})) | {
+    readonly kind: "money";
+    readonly id: string;
+    readonly name: string;
+    /** Internal-Format: Cents/Minor-Units als Integer (z.B. 1299 für
+     *  12,99 EUR). Renderer übersetzt fürs UI in Major-Units mit
+     *  Locale-formatierten Dezimalstellen. Empty-State = `""`. */
+    readonly value: number | "";
+    readonly onChange: (v: number | undefined) => void;
+    /** ISO-4217 Currency-Code, z.B. "EUR" / "USD" / "CHF". Default
+     *  "EUR". Renderer zeigt das Symbol als Suffix und formatiert die
+     *  Decimal-Stellen entsprechend (EUR/USD/CHF haben 2, JPY hat 0). */
+    readonly currency?: string;
+    /** Locale für Zahlen-Formatierung. Default "de-DE" (Komma als
+     *  Dezimaltrenner). Apps mit eigenem LocaleResolver können ihren
+     *  current locale durchreichen. */
+    readonly locale?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "timestamp";
+    readonly id: string;
+    readonly name: string;
+    /** ISO-8601 Datetime-String. UTC-Instant mit `Z`
+     *  ("2026-04-25T13:45:00Z") oder Wall-Clock ohne Offset
+     *  ("2026-04-25T13:45", nur bei wallClock). Empty-State = `""`.
+     *  Web rendert getrennte Datums- (tippbar + Kalender) und
+     *  Uhrzeit-Eingabe und konvertiert. */
+    readonly value: string;
+    readonly onChange: (v: string | undefined) => void;
+    /** true = locatedTimestamp (Wall-Clock ohne Offset, Server
+     *  validiert z.iso.datetime({local:true})). false/undefined =
+     *  UTC-Instant, onChange MUSS mit `Z`-Suffix emittieren. */
+    readonly wallClock?: boolean;
+    /** Locale für Anzeige UND Eingabe-Parsing des Datums-Teils.
+     *  Default = Browser-Locale. */
+    readonly locale?: string;
+    /** Datumsgrenzen als ISO-Datetime — begrenzen den Kalender auf
+     *  Tages-Granularität. */
+    readonly min?: string;
+    readonly max?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "locatedTimestamp";
+    readonly id: string;
+    readonly name: string;
+    /** Located-Timestamp-Wert: Wall-Clock `at` (ohne Offset) + IANA-`tz`.
+     *  `utc` ist beim Read da (server-berechnet) und wird beim Write
+     *  ignoriert. Empty-State = `""`. onChange emittiert `{ at, tz }`. */
+    readonly value: {
+        readonly at: string;
+        readonly tz: string;
+        readonly utc?: string;
+    } | "";
+    readonly onChange: (v: {
+        readonly at: string;
+        readonly tz: string;
+    } | undefined) => void;
+    /** Locale für den Datums-Teil. Default = Browser-Locale. */
+    readonly locale?: string;
+    /** Datumsgrenzen als ISO-Datetime — begrenzen den Kalender. */
+    readonly min?: string;
+    readonly max?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "tz";
+    readonly id: string;
+    readonly name: string;
+    /** IANA zone name, e.g. "Europe/Berlin". Empty-state = "". */
+    readonly value: string;
+    readonly onChange: (v: string | undefined) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+} | {
+    readonly kind: "textarea";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    /** Visible rows. Acts as a minimum height — the field starts this tall
+     *  and still grows with its content. Omitted, the default primitive
+     *  falls back to its own floor (#2677). */
+    readonly rows?: number;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    /** Hint text shown when the field is empty (analog to kind:"text"). */
+    readonly placeholder?: string;
+    /** Read-only Textarea. Nicht `disabled` — bleibt fokussier-/
+     *  kopierbar (analog zu kind:"text"). */
+    readonly readOnly?: boolean;
+    /** Ctrl/Cmd+Enter submits instead of inserting a newline. Plain
+     *  Enter still inserts a newline. */
+    readonly onSubmitShortcut?: () => void;
+    readonly dataAttributes?: DataAttributes;
+    /** Raw keydown access (e.g. plain-Enter-submits/Shift+Enter-newline at
+     *  the field instead of the surrounding Form). Composes with
+     *  `onSubmitShortcut` — both fire on the same keystroke when set. Web
+     *  forwards it, native impls ignore it (precedent: `ButtonProps.ref`). */
+    readonly onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+};
+export type DataTableSortDir = "asc" | "desc";
+export type DataTableSort = {
+    readonly field: string;
+    readonly dir: DataTableSortDir;
+};
+export type DataTableRowActionMode = "adaptive" | "inline";
+export type DataTableRowAction = {
+    /** Stable id für aria-labels und data-testids. */
+    readonly id: string;
+    /** Translated Label. */
+    readonly label: string;
+    /** Visual style — "danger" renders the red variant in the default
+     *  primitive. Whether it also forces a confirm dialog is governed by
+     *  `confirmRequired` (falls back to `style === "danger"` when unset). */
+    readonly style?: "primary" | "secondary" | "danger";
+    /** Translated Confirm-Prompt (Description im Dialog) — wenn gesetzt,
+     *  öffnet ein Modal vor der Ausführung. Bei style=danger ohne expliziten
+     *  confirm sollte der Renderer einen generischen Default zeigen. */
+    readonly confirm?: string;
+    /** Translated Confirm-Button-Label im Dialog. Default = `label`
+     *  (Action-Label wird wiederverwendet). */
+    readonly confirmLabel?: string;
+    /** Overrides the default "danger implies a confirm dialog" rule. Schema-driven
+     *  navigate/drawer actions set it to false: the colour marks the action as
+     *  destructive, but the target form is the confirmation. */
+    readonly confirmRequired?: boolean;
+    /** Wird mit der ListRowViewModel der geklickten Row aufgerufen. Async
+     *  erlaubt — der Renderer kann während der Promise-Resolution einen
+     *  Loading-State auf dem Button zeigen. */
+    readonly onTrigger: (row: ListRowViewModel) => Promise<void> | void;
+    /** Conditional Visibility pro Row (z.B. "Start" nur wenn status==="scheduled"). */
+    readonly isVisible?: (row: ListRowViewModel) => boolean;
+    /** This action is what a click on the row does. The card layout drops it
+     *  from the row menu, since the whole card is already the tap target. */
+    readonly rowClick?: boolean;
+    /** Resolved icon (author `RowAction.icon` or the id-derived default) —
+     *  drives both the icon-left-of-text render and the icon-only collapse
+     *  rule (see `shouldRenderActionsIconOnly`). */
+    readonly icon?: IconKey;
+};
+/** Teil-C action-icon collapse rule: a group of more than two actions where
+ *  every member carries an icon renders icon-only instead of wall-to-wall
+ *  text buttons; any icon-less member keeps the whole group on text so it
+ *  doesn't fall apart visually mid-group. */
+export declare function shouldRenderActionsIconOnly(actions: readonly {
+    readonly icon?: IconKey;
+}[]): boolean;
+export type DataTableFacet = {
+    /** Entity-Feldname (= URL-State-Key + payload.filters[].field). */
+    readonly field: string;
+    /** Translated Button-Label ("Status", "Active"). */
+    readonly label: string;
+    /** Auswählbare Werte mit Anzeige-Label. value = roher Filterwert
+     *  (select-option / "true"|"false"), als String transportiert. */
+    readonly options: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+};
+export type DataTableDateRangeFacet = {
+    /** The facet's namespace (its date field) — a key, not a filter value. */
+    readonly field: string;
+    /** Translated label ("When"). */
+    readonly label: string;
+    readonly from: string;
+    readonly to: string;
+};
+export type DataTableProps = {
+    readonly columns: readonly ListColumnViewModel[];
+    readonly rows: readonly ListRowViewModel[];
+    readonly onRowClick?: (row: ListRowViewModel) => void;
+    /** Aktuelle Sortierung (oder null = unsorted). Wenn columns ein
+     *  `sortable: true`-Feld haben und onSortChange gesetzt ist, rendert
+     *  der Renderer Click-Header mit Asc/Desc-Indikator. Ohne onSortChange
+     *  bleibt die Header-Click-Mechanik aus, columns.sortable ist dann nur
+     *  semantischer Hinweis. */
+    readonly sort?: DataTableSort | null;
+    /** Wird gerufen mit dem nächsten Sort-State nach einem Header-Klick.
+     *  3-State-Toggle (Convention): asc → desc → null. Caller setzt damit
+     *  seinen URL-State / Query-Param und triggert ein refetch. */
+    readonly onSortChange?: (next: DataTableSort | null) => void;
+    /** Pro-Row-Aktionen — eine Spalte am rechten Rand mit Inline-Buttons
+     *  (≤2 Aktionen) oder Kebab-Dropdown (>2). Caller liefert Resolved-
+     *  Form (Labels + onTrigger schon verdrahtet); DataTable kümmert
+     *  sich nur um Render + Confirm-Dialog. */
+    readonly rowActions?: readonly DataTableRowAction[];
+    /** How the row-action column renders:
+     *  - `"adaptive"` (default): with `onRowClick` all actions go in the kebab;
+     *    without it the primary action is a link button and the rest go in the
+     *    kebab (a single action gets no kebab).
+     *  - `"inline"`: ALWAYS inline buttons, left-aligned, even with >2 (no
+     *    kebab). Actions then sit at the same x-position across all rows
+     *    (no drifting with label width) and all lists in an app look alike. */
+    readonly rowActionMode?: DataTableRowActionMode;
+    /** Custom Empty-State-Inhalt (z. B. Icon + Heading + CTA-Button).
+     *  Default-Renderer rahmt ihn in einer dashed-border Box. */
+    readonly emptyState?: ReactNode;
+    /** Optionaler Titel-Slot ganz links der Toolbar — Screen-Titel
+     *  ("Items", "Bestellungen"). Web rendert als font-medium Heading. */
+    readonly toolbarTitle?: ReactNode;
+    /** Toolbar-Slot mittig (typisch Search-Input). Renderer entscheidet
+     *  das Layout — Web spreizt das Element als flex-1 mit max-Breite,
+     *  Native könnte es als Header-Suchleiste rendern. */
+    readonly toolbarStart?: ReactNode;
+    /** Toolbar-Slot rechts (typisch + Neu Button, Filter, View-Switch).
+     *  Web zieht den Cluster mit ml-auto an die rechte Kante. */
+    readonly toolbarEnd?: ReactNode;
+    /** Faceted-Filter-Dropdowns (select/boolean-Felder) — der Renderer
+     *  setzt sie neben das Search-Input. Leer/undefined → keine Filter. */
+    readonly filterFacets?: readonly DataTableFacet[];
+    /** Aktuell ausgewählte Werte je Facet-Feld (vom URL-State). */
+    readonly filterValues?: Readonly<Record<string, readonly string[]>>;
+    /** Toggle eines Facet-Werts → Caller schreibt URL-State + refetch. */
+    readonly onFilterChange?: (field: string, values: readonly string[]) => void;
+    /** Reset-Button: löscht alle aktiven Facets. Renderer zeigt ihn nur
+     *  wenn mindestens ein Facet aktiv ist. */
+    readonly onFilterReset?: () => void;
+    /** Time-range filters beside the facet dropdowns (fw#3104). */
+    readonly dateRangeFacets?: readonly DataTableDateRangeFacet[];
+    /** One bound changed ("" clears it) → caller writes URL state + refetch. */
+    readonly onDateRangeChange?: (field: string, bound: "from" | "to", value: string) => void;
+    /** Pagination-State + Callback. Wenn gesetzt, rendert der Renderer
+     *  einen Pager unter der Tabelle (Web: Footer-Bar mit ← 1 ... N →).
+     *  total/limit/page sind 1-basiert für die UI; Server-Translation
+     *  zu offset = (page-1)*limit liegt beim Caller. Wenn page > total/limit
+     *  würde, soll der Caller das vorab clampen. */
+    readonly pager?: {
+        readonly page: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly onPageChange: (next: number) => void;
+        /** Offered page sizes; with `onPageSizeChange` the footer shows a
+         *  "N pro Seite" select. */
+        readonly pageSizeOptions?: readonly number[];
+        readonly onPageSizeChange?: (next: number) => void;
+    };
+    /** Hint at the left of the toolbar (relatedList tab description). */
+    readonly toolbarDescription?: string;
+    /** Noun for the footer count ("1–19 of 19 leases", "1 position"),
+     *  resolved for the given count. Omitted = generic "entries" wording. */
+    readonly itemNoun?: (count: number) => string;
+    /** Infinite-Scroll Callback. Wenn gesetzt, rendert der Renderer einen
+     *  Bottom-Sentinel und ruft `onReachEnd` wenn der ins Viewport rückt
+     *  (Web: IntersectionObserver). Caller verwaltet accumulation +
+     *  cursor + hasMore. `loadingMore=true` zeigt einen Spinner unter
+     *  der Tabelle solange die nächste Page lädt. Inkompatibel mit
+     *  `pager` — entweder Pager ODER Infinite-Scroll, nicht beides. */
+    readonly onReachEnd?: () => void;
+    readonly loadingMore?: boolean;
+    /** Wenn false und onReachEnd gesetzt, rendert der Renderer einen
+     *  "Ende der Liste"-Hinweis statt des Sentinels. Default true. */
+    readonly hasMore?: boolean;
+    readonly testId?: string;
+    /** Wires an edit path into a component column-renderer: `DataTableCell`
+     *  passes this down as `ColumnRendererProps.onChange` for that cell,
+     *  bound to `(rowId, column.field)`. Renderers without a component
+     *  renderer (format-spec, type-default) ignore it — read-only stays
+     *  read-only unless the column has a custom renderer that reads
+     *  `onChange`. */
+    readonly onCellChange?: (rowId: string, field: string, value: unknown) => void;
+    /** Overrides the row `data-testid` (default `row-${row.id}`) — for a
+     *  screen that already has its own DOM-test/e2e naming scheme. */
+    readonly getRowTestId?: (row: ListRowViewModel) => string;
+    /** Overrides the cell `data-testid` (default `cell-${row.id}-${field}`). */
+    readonly getCellTestId?: (row: ListRowViewModel, field: string) => string;
+    /** Drops the table's own rounded/border/card background — for a host
+     *  that already provides the surrounding boundary (a tab panel, fw#2722)
+     *  and would otherwise show a card nested inside that boundary. Default
+     *  false: unchanged card-framed table. */
+    readonly chromeless?: boolean;
+    /** Fills the available height of its flex container and scrolls rows
+     *  internally instead of growing with row count — for a host that would
+     *  otherwise have a long table stretch the whole page, or a short table
+     *  leave dead space below it (a tab panel, fw#2722). Requires the same
+     *  flex-fill chain FormProps.fillHeight sets up above it; without that
+     *  ancestor chain this collapses to zero height (Web: `flex-1 min-h-0`
+     *  has no effect outside a sized flex-col ancestor). When true the table
+     *  also takes the full board layout: the wrapper fills its container
+     *  (`h-full`), toolbar and footer (pager or entry count) stay pinned
+     *  outside the scrolling body, no card frame and no outer padding.
+     *  Default false: unchanged document-flow table that grows with its
+     *  content, pager below the last row. */
+    readonly scrollBody?: boolean;
+    /** Uses the shared screen padding (wider bottom inset) instead of the
+     *  table's symmetric embedded inset — for a table that IS the screen body
+     *  (entityList/projectionList), so a list screen ends at the same footer
+     *  distance as a form or custom screen (fw#2640). Hosts set this or
+     *  `scrollBody`, not both: the wider bottom inset competes with
+     *  `scrollBody`'s flex-fill height budget.
+     *  Default false: unchanged symmetric inset for an embedded table. */
+    readonly screenPadding?: boolean;
+};
+/** Cell type for one column of an embedded-list field. Mirrors
+ *  EmbeddedListCellViewModel["type"] from `@cosmicdrift/kumiko-headless`. */
+export type EmbeddedListCellType = "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp";
+/** One column of an embedded-list table (one entry per key of the source
+ *  EmbeddedFieldDef's `schema`). */
+export type EmbeddedListColumn = {
+    readonly field: string;
+    readonly label: string;
+    readonly type: EmbeddedListCellType;
+    readonly required: boolean;
+    /** Read-only, value supplied by the caller (already computed from
+     *  sibling cells) — not directly user-editable. */
+    readonly derived: boolean;
+    /** Only for `type: "select"`. */
+    readonly options?: readonly string[];
+    readonly optionLabels?: Readonly<Record<string, string>>;
+    /** Only for `type: "reference"` — pre-fetched by the caller, ONE query
+     *  per column shared across every row (not one query per cell). */
+    readonly referenceOptions?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly referenceLoading?: boolean;
+};
+/** One entry of an embedded-list totals row (e.g. an invoice's total
+ *  amount, summed across all rows by the caller). */
+export type EmbeddedListTotal = {
+    readonly field: string;
+    readonly label: string;
+    readonly value: number;
+};
+/** Row-array + totals table for a `createEmbeddedListField` (invoice-
+ *  positions-style) field — structurally too different from `Input`'s
+ *  value/onChange union to fit there, so it's its own primitive, same as
+ *  `DataTable`. Controlled: the caller (the eventual form-field wrapper)
+ *  computes rows/derived values/issue groups and wires every callback;
+ *  this primitive only renders and reports interaction. */
+export type EmbeddedListInputProps = {
+    readonly id: string;
+    readonly columns: readonly EmbeddedListColumn[];
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly totals?: readonly EmbeddedListTotal[];
+    /** Currency for money cells and the totals row — one value for the whole
+     *  list (currency lives on the head aggregate, not the row). Web impl
+     *  falls back to "EUR" when absent. */
+    readonly currency?: string;
+    /** Whole-list read-only (e.g. a released invoice) — hides row-mutation
+     *  affordances and disables every cell. */
+    readonly disabled?: boolean;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    /** Shown under the whole list (e.g. under the totals row). */
+    readonly listIssues?: readonly FieldIssue[];
+    /** Keyed by row index. */
+    readonly rowIssues?: Readonly<Record<number, readonly FieldIssue[]>>;
+    /** Keyed `${rowIndex}.${field}`. */
+    readonly cellIssues?: Readonly<Record<string, readonly FieldIssue[]>>;
+    readonly onCellChange: (rowIndex: number, field: string, value: unknown) => void;
+    readonly onAddRow: () => void;
+    readonly onRemoveRow: (rowIndex: number) => void;
+    readonly onDuplicateRow: (rowIndex: number) => void;
+    readonly onMoveRow: (fromIndex: number, toIndex: number) => void;
+    /** Tab/newline-delimited clipboard paste starting at (rowIndex,
+     *  columnIndex) — parsed to a 2D string grid by the Web impl (paste
+     *  events are a browser-only concept); undefined caller = no paste
+     *  handling wired up. */
+    readonly onPasteCells?: (rowIndex: number, columnIndex: number, grid: readonly (readonly string[])[]) => void;
+    readonly addLabel: string;
+    readonly removeLabel: string;
+    readonly duplicateLabel: string;
+    readonly moveUpLabel: string;
+    readonly moveDownLabel: string;
+    readonly emptyLabel: string;
+    readonly emptyCtaLabel: string;
+    readonly testId?: string;
+};
+export type { FormWidth };
+/** One entry of a form's "on this page" navigation: `id` matches the
+ *  `SectionProps.id` of the section it scrolls to. */
+export type FormSectionNavItem = {
+    readonly id: string;
+    readonly title: string;
+};
+/** Submit wrapper. Web: `<form onSubmit>`, native: a View that triggers an
+ *  onSubmit callback via button press. `onSubmit` gets an abstract
+ *  signature (no FormEvent) so native impls can fill it meaningfully.
+ *
+ *  `title`: slot in the card header. `actions`: optional slot for the
+ *  primary form actions (Save, Cancel) — renders as a footer row at the
+ *  end of the card (normal document flow). Native impls may render the
+ *  same slot as a bottom bar instead. */
+export type FormProps = {
+    readonly onSubmit: (e?: FormEvent) => void;
+    readonly children: ReactNode;
+    readonly title?: ReactNode;
+    /** Optionaler muted Untertitel unter dem Titel (z.B. "Add a new item to
+     *  your catalog") — gibt dem Form-Header Kontext statt nur ein Label. */
+    readonly subtitle?: ReactNode;
+    readonly actions?: ReactNode;
+    /** Secondary, record-related actions — rendered on the left on desktop,
+     *  on their own row below the primary action on a narrow viewport. */
+    readonly secondaryActions?: ReactNode;
+    readonly testId?: string;
+    /** Max width of the form container. Default "full" — see FormWidth
+     *  (`packages/types/src/screen.ts`, EditLayout.width). Native impls may
+     *  ignore this prop (no width constraint there). */
+    readonly width?: FormWidth;
+    /** Pins `actions` to the viewport bottom on narrow screens (`<640px`)
+     *  instead of normal document flow, so it stays reachable when a virtual
+     *  keyboard shrinks the visible viewport (fw#1918). Desktop/tablet
+     *  unaffected. Native impls may ignore this prop (already bottom-bar by
+     *  convention there). */
+    readonly stickyActions?: boolean;
+    /** Extra content rendered above the card, inside the same page padding
+     *  the card itself sits in — for a host that needs its own header region
+     *  (title/metrics/tabs) to share the form's left padding and width
+     *  instead of rendering as unpadded siblings before it. Native impls may
+     *  ignore this prop. */
+    readonly headerRegion?: ReactNode;
+    /** Compact content on the right of the form title, same row — status
+     *  chips or allowance badges that belong to the screen, not to a field.
+     *  Native impls may ignore this prop. */
+    readonly titleAction?: ReactNode;
+    /** Sizes the form to fill its container's height (instead of the page's
+     *  natural content height) so a single scrolling child — a lone
+     *  relatedList tab's table — can scroll internally instead of stretching
+     *  the whole page (fw#2722). Set by RenderEdit for a lone relatedList tab
+     *  section and for screens that fill the shell height (together with
+     *  `stickyActions`: sections scroll, footer stays pinned without
+     *  `position: fixed`); every other caller leaves it unset and keeps normal
+     *  document-flow height. Native impls may ignore this prop (already a
+     *  bounded viewport there). */
+    readonly fillHeight?: boolean;
+    /** Drops the surrounding card (bg/border/rounded, title/subtitle block,
+     *  footer border) so sections+footer render as siblings of `headerRegion`
+     *  on the page background instead of inside a nested card — a tabbed
+     *  projectionDetail's tab content is a sibling of the head card, not its
+     *  child (bedienkonzept A1), so it must look like a standalone screen
+     *  instead of a form embedded in another card. Default false: unchanged
+     *  card chrome. Native impls may ignore this prop (no card chrome there
+     *  to begin with). */
+    readonly chromeless?: boolean;
+    /** Set by RenderEdit for entityEdit/actionForm screens that fill the shell
+     *  height: the form renders without a surrounding card, in a padded scroll
+     *  surface with a fixed-width form column. Requires `fillHeight`; projection
+     *  detail screens (which also fill the height) do not set it. Native impls
+     *  may ignore this prop. */
+    readonly screenForm?: boolean;
+    /** Number of unsaved changes, shown in the pinned footer. Omitted in create
+     *  mode and when nothing changed — the footer then shows no status. */
+    readonly unsavedCount?: number;
+    /** Drawer-hosted forms: context box above the fields. */
+    readonly summary?: {
+        readonly title: string;
+        readonly subtitle?: string;
+    };
+    /** Titled sections for the "on this page" navigation next to a
+     *  `screenForm`. The web impl shows it only with three or more entries. */
+    readonly sectionNav?: readonly FormSectionNavItem[];
+    /** Leading column next to the scroll surface of a `screenForm` (wizard step
+     *  navigation). Native impls may ignore this prop. */
+    readonly sideRail?: ReactNode;
+};
+/** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native:
+ *  View mit Header-Text. Native-Impls können den Title als Accordion
+ *  oder Collapsible rendern. */
+export type SectionProps = {
+    /** DOM id — the scroll target of a form's "on this page" navigation. */
+    readonly id?: string;
+    /** Optional — ohne Titel rendert die Section nur die Gruppierung
+     *  (kein Header). RenderEdit lässt ihn weg, wenn er den Screen-Titel
+     *  der Action-Bar 1:1 wiederholen würde. */
+    readonly title?: string;
+    /** Optionaler muted Untertitel unter dem Titel — gibt der Section
+     *  Kontext statt nur ein Label (analog FormProps.subtitle). */
+    readonly subtitle?: ReactNode;
+    readonly children: ReactNode;
+    /** Rendered top-right in the title row — never a footer. A
+     *  title-less/subtitle-less Section still draws the row when `actions`
+     *  is set, so a hideTitle tabs-Section with actions isn't stranded. */
+    readonly actions?: ReactNode;
+    /** "destructive" marks the Section as a warning/danger area (e.g. account
+     *  deletion, restrict processing) — border color only, no content change.
+     *  Default "default" (normal card border). */
+    readonly variant?: "default" | "destructive";
+    readonly testId?: string;
+    /** Rendered left of the title, `text-muted-foreground`, same optical
+     *  size as the title. No effect without a `title` — an icon alone would
+     *  have nothing to sit next to. */
+    readonly icon?: IconKey;
+};
+/** Chromeless flex-fill layout host — no title, no card frame, no padding,
+ *  just a container that sizes to its content and, once the ancestor chain
+ *  is height-constrained, shrinks so one scrolling child can scroll
+ *  internally instead of the page growing (fw#2722, height fw#2778). Web:
+ *  `<div className="flex min-h-0 flex-col">`. Native: Views are
+ *  already flex-column and the parent is already a bounded viewport there,
+ *  so a native impl may render this as a bare Fragment. Used only as the
+ *  terminal link in `RenderEdit`'s `fillHeight` chain (`RelatedListSection`'s
+ *  `hideTitle` branch) — `Section`/`Card` were rejected here because both
+ *  carry title/padding/border chrome this spot doesn't want and would double
+ *  up with the table's own padding. */
+export type FillContainerProps = {
+    readonly children: ReactNode;
+    readonly testId?: string;
+    /** Claims the remaining height of the flex chain (`flex-1`) instead of
+     *  sizing to its content, so a footer inside the child sits at the bottom
+     *  edge even with few rows. Set only when the screen fills the shell
+     *  height. */
+    readonly grow?: boolean;
+};
+/** Columns-basiertes Layout. Web: CSS grid, Native: Flex-Wrap mit
+ *  Width-%, oder react-native-grid. Jedes direkte Child kann eine
+ *  `GridCell`-Wrapping bekommen für span-Kontrolle.
+ *
+ *  `columns: "auto"` opts out of the N-column stretch layout entirely —
+ *  children keep their own content width and wrap onto new lines (e.g. a
+ *  metrics band of self-sized tiles, or an inline label+badge row) instead
+ *  of being stretched into equal-width tracks. `GridCell` span-wrapping is
+ *  meaningless in this mode and should be skipped. */
+export type GridProps = {
+    readonly columns: number | "auto";
+    readonly children: ReactNode;
+    readonly testId?: string;
+    /** Rows visible before the grid becomes vertically scrollable. Omitted =
+     *  the grid grows with its content and never scrolls. Ignored when
+     *  `columns` is "auto". */
+    readonly maxRows?: number;
+    /** Fields flow left to right in wrapping rows sized by `GridCell.width`
+     *  instead of equal-width tracks (screen forms and drawers). */
+    readonly flow?: boolean;
+};
+/** Width class of a field cell inside a `flow` grid: sized by what the field holds. */
+export type FieldCellWidth = "text" | "number" | "money" | "date" | "select" | "full" | "auto";
+/** Span-Wrapper für ein Kind innerhalb eines Grid. Web: `style={{gridColumn: span N}}`,
+ *  Native: eigenes Width-Rechnen. */
+export type GridCellProps = {
+    readonly span?: number;
+    /** Only read inside a `flow` grid. */
+    readonly width?: FieldCellWidth;
+    readonly children: ReactNode;
+};
+/** Semantischer Text. Variants bilden Standard-Typografie-Rollen ab —
+ *  `body` ist Default, `small` für sekundäre Labels, `code` für inline
+ *  monospace (entityId, screen-id), `required-mark` für das Sternchen
+ *  hinter Labels, `muted` für gedimmten Fließtext (text-sm muted-
+ *  foreground). Custom-Impls mappen auf ihren TypeScale. */
+export type TextProps = {
+    readonly variant?: "body" | "small" | "code" | "required-mark" | "muted";
+    readonly children: ReactNode;
+    readonly testId?: string;
+};
+/** Heading mit zwei Rollen — `page` als Page-Titel (Web: h1), `section`
+ *  als Sub-Header über einer Group (Web: h2 mit uppercase + muted).
+ *  Native-Impls mappen auf `<Text>` mit entsprechendem fontWeight/Size. */
+export type HeadingProps = {
+    readonly variant?: "page" | "section";
+    readonly children: ReactNode;
+    readonly testId?: string;
+};
+/** Modal-Dialog für Bestätigungen oder kompakte Sub-Forms. Web rendert
+ *  Radix-Dialog (Focus-Trap, Esc-Schließen, Overlay-Click); Native
+ *  würde ein Native-Modal nutzen. Apps öffnen den Dialog über einen
+ *  External-State (`open` + `onOpenChange`); Confirm-Action läuft
+ *  durch `onConfirm`, Cancel klappt zu via `onOpenChange(false)`.
+ *
+ *  Variant `danger` markiert destruktive Bestätigungen visuell
+ *  (rote Confirm-Button-Klasse), `default` für neutrale Dialoge. */
+export type DialogProps = {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    readonly title: string;
+    /** Optional Beschreibung — typisch ein Satz der die Konsequenz
+     *  erklärt ("Diese Aktion lässt sich nicht rückgängig machen."). */
+    readonly description?: string;
+    /** Confirm-Button-Label. Default kommt aus i18n
+     *  (`kumiko.dialog.confirm`). */
+    readonly confirmLabel?: string;
+    /** Cancel-Button-Label. Default `kumiko.dialog.cancel`. */
+    readonly cancelLabel?: string;
+    /** `default` = Confirm primary, `danger` = Confirm danger. */
+    readonly variant?: "default" | "danger";
+    /** Which button takes focus on open. Default: Confirm for a bare dialog,
+     *  the browser/Radix default when `children` are present. `"cancel"` for
+     *  dialogs where the safe choice must be the one Enter triggers. */
+    readonly initialFocus?: "confirm" | "cancel";
+    /** Wird gefeuert wenn der User Confirm drückt. Async-Funktion ist
+     *  ok — Dialog setzt automatisch loading-State, ruft danach
+     *  onOpenChange(false). */
+    readonly onConfirm: () => void | Promise<void>;
+    /** Optional zusätzlicher Inhalt zwischen description und Buttons
+     *  (z.B. ein Input wenn der Dialog auch Eingaben sammelt). */
+    readonly children?: ReactNode;
+    readonly testId?: string;
+};
+/** Bare content shell for hosting an existing self-contained form/widget
+ *  (own submit/cancel buttons) inside a modal overlay — unlike `Dialog`,
+ *  it renders no footer buttons of its own. Web renders the same
+ *  focus-trapped Radix overlay as `Dialog`, just without the button row. */
+export type ModalProps = {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    /** Screen-reader-only accessible title (required by the underlying
+     *  dialog primitive) — not shown visually since the hosted content
+     *  is expected to render its own heading. */
+    readonly title: string;
+    readonly children: ReactNode;
+    readonly testId?: string;
+};
+/** Side panel for hosting an existing self-contained form/widget (own
+ *  submit/cancel buttons) without leaving the underlying screen — e.g. a
+ *  toolbar action's `kind: "drawer"` mounts an actionForm here instead of
+ *  navigating to a full page (fw#2225). Same "bare content shell, no
+ *  footer buttons of its own" contract as `Modal`, slide-in instead of
+ *  centered overlay. */
+export type DrawerProps = {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    readonly title?: string;
+    readonly children: ReactNode;
+    readonly testId?: string;
+};
+/** Image lightbox — full-size preview on click. Web renders Radix overlay;
+ *  trigger (thumbnail) and open state live in the app. */
+export type LightboxProps = {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    readonly src: string;
+    readonly alt: string;
+    readonly testId?: string;
+};
+/** Source-badge for one cascade step (User / Tenant / System / …).
+ *  Used inline next to a config value to indicate where it came from.
+ *  Requires a LocaleProvider above it (labels run through useTranslation)
+ *  — createKumikoApp wires one; standalone consumers must wrap. */
+export type ConfigSourceBadgeProps = {
+    readonly source: ConfigValueSource;
+    /** Scope of the hosting screen. Non-system screens collapse sources
+     *  ABOVE their scope (system-row/app-override/computed) into the neutral
+     *  default badge — operator internals stay invisible to tenants, same
+     *  rule as ConfigCascadeView's toDisplayLevels. */
+    readonly screenScope?: ConfigScope;
+};
+/** Collapsible cascade-view for a config-edit field. Split into two slots
+ *  (#429): "trigger" is the collapsed ▶ + source + value line for the label
+ *  row; "panel" is the expanded cascade + reset shown below the input. In
+ *  split mode the screen owns the `expanded` state (both slots share it);
+ *  without `slot` the component renders both with its own state. */
+export type ConfigCascadeViewProps = {
+    readonly cascade: ConfigCascade;
+    readonly screenScope: ConfigScope;
+    readonly onReset?: (key: string, scope: ConfigScope) => void;
+    readonly qualifiedKey?: string;
+    readonly slot?: "trigger" | "panel";
+    readonly expanded?: boolean;
+    readonly onToggle?: () => void;
+};
+/** Card-Slots — benannte Inhalts-Regionen, alle optional. Neue Slots später =
+ *  rein additiv → Consumer müssen NIE migriert werden. `header` ist der Escape-
+ *  Hatch: ein roher Knoten ersetzt den Default-Header (title/subtitle/
+ *  headerActions) komplett, wenn die Convenience-Slots nicht reichen. */
+export type CardSlots = {
+    readonly header?: ReactNode;
+    readonly title?: ReactNode;
+    readonly subtitle?: ReactNode;
+    /** Free-form block content left of `headerActions`, below title/subtitle —
+     *  for a host-supplied header (projectionDetail `slots.header`) that must
+     *  share the action row instead of pushing actions into a row of their own. */
+    readonly headerContent?: ReactNode;
+    /** Rechtsbündiger Header-Slot (Range-Umschalter, Filter, Badge …). */
+    readonly headerActions?: ReactNode;
+    /** Footer-Inhalt, abgehoben (border-t). Default rechtsbündig. */
+    readonly footer?: ReactNode;
+};
+/** Card-Options — Verhalten/Optik, ebenfalls additiv erweiterbar. */
+export type CardOptions = {
+    /** Body-Padding (px-6 py-6). false = randlos (Tabelle/eigene Tiles). Default true. */
+    readonly padded?: boolean;
+    /** Eckenradius. Default "xl" (= Entity-Card). */
+    readonly radius?: "lg" | "xl";
+    /** Footer abgehoben mit border-t + bg-muted/30. Default true. */
+    readonly footerBordered?: boolean;
+    /** Joins the ancestor fillHeight flex chain (fw#2722/#2778 — a tabs-mode
+     *  relatedList table sizing to the panel instead of the page) instead of
+     *  normal document-flow height. Default false. */
+    readonly fillHeight?: boolean;
+};
+/** Generische Card-Chrome (border/bg/radius/shadow + Header/Body/Footer) als
+ *  Primitive — eine Quelle für alle Card-Flächen, statt pro App nachgebaut.
+ *  Slot- + Options-basiert, damit der Contract stabil bleibt. */
+export type CardProps = {
+    readonly slots?: CardSlots;
+    readonly options?: CardOptions;
+    /** Body-Inhalt (Normalfall; Header/Footer kommen über slots). */
+    readonly children?: ReactNode;
+    readonly className?: string;
+    readonly testId?: string;
+    readonly dataAttributes?: DataAttributes;
+};
+/** Determinate progress bar (e.g. wizard step progress). `value` is a
+ *  0..1 fraction, not a percentage — implementations scale for display.
+ *  `tone` controls the fill color; omitted defaults to "default" (backward
+ *  compatible with callers predating this field). */
+export type ProgressTone = "default" | "success" | "warn" | "danger";
+export type ProgressProps = {
+    readonly value: number;
+    readonly tone?: ProgressTone;
+    readonly ariaLabel?: string;
+    readonly testId?: string;
+};
+/** Wizard step overview — numbered chips, one per step label, with the
+ *  active step highlighted. With `onStepSelect`, completed steps (index
+ *  below `currentIndex`) become buttons for going back; forward jumps stay
+ *  impossible because step-jump validation is a separate concern
+ *  (kumiko-framework#1966). Implementations render a
+ *  narrow-viewport fallback showing `compactLabel` instead (caller
+ *  supplies it pre-translated, e.g. "Step 2 of 5 · Industry") — which of
+ *  the two is visible is a responsive layout choice owned by the
+ *  implementation, not this contract. */
+export type StepBarProps = {
+    readonly steps: readonly string[];
+    readonly currentIndex: number;
+    readonly compactLabel: string;
+    readonly onStepSelect?: (index: number) => void;
+    /** "label" (default) swaps the step row for `compactLabel` on narrow
+     *  viewports; "steps" keeps the row there too — for short wizards whose
+     *  labels fit a phone and whose done steps must stay tappable. */
+    readonly narrowLayout?: "label" | "steps";
+    /** "vertical" renders a step rail (from `lg`, with `compactLabel` as the
+     *  single line below it) instead of the chip row. Default "horizontal". */
+    readonly orientation?: "horizontal" | "vertical";
+    /** Vertical only: rail heading ("Step 4 of 6") and optional description. */
+    readonly heading?: string;
+    readonly description?: string;
+    readonly testId?: string;
+    readonly compactTestId?: string;
+};
+/** Wraps a single wizard step so it stays mounted but inert while off-
+ *  screen — `hidden` visually hides it, and implementations that have a
+ *  native constraint-validation concept (web: `<fieldset disabled>`, spec-
+ *  guaranteed to also bar descendants from participating) must bar it too,
+ *  or a `type="submit"` step-advance button triggers the browser's
+ *  full-form check against fields on unvisited, unfocusable steps
+ *  (kumiko-framework#1976). Implementations without that concept can gate
+ *  on `hidden` alone. */
+export type WizardStepGroupProps = {
+    readonly hidden: boolean;
+    /** Pads the step content (tab panels sit full-bleed under the tab strip). */
+    readonly inset?: boolean;
+    readonly children: ReactNode;
+};
+/** Tab strip for a projectionDetail `layout.mode: "tabs"`. Renders only the
+ *  strip, not the content — the caller mounts the active section separately.
+ *  Keyboard/ARIA (role=tablist/tab, arrow-key navigation) is the
+ *  implementation's job. */
+export type TabsProps = {
+    readonly items: readonly {
+        readonly id: string;
+        readonly label: string;
+        /** Shown dimmed after the label (e.g. an open-items count). Omit for
+         *  tabs without a counter. */
+        readonly count?: number;
+    }[];
+    readonly activeId: string;
+    readonly onSelect: (id: string) => void;
+    readonly testId?: string;
+};
+export type StatusTone = "ok" | "warn" | "bad" | "critical" | "muted";
+/** Status pill. `value` is the raw column value — tone-mapping is the app's job. */
+export type StatusBadgeProps = {
+    readonly value: string;
+    readonly tone?: StatusTone;
+    readonly testId?: string;
+};
+export declare function statusToneForOptionTone(tone: SelectOptionTone): StatusTone;
+export declare function statusToneForValue(value: string): StatusTone | undefined;
+/** Compact label/value tile (record-detail metrics band). `testId` is the
+ *  tile's own id — the impl derives `${testId}-label`/`${testId}-value` for
+ *  the two rendered nodes, so a caller only ever needs to know the base id. */
+export type MetricProps = {
+    readonly label: string;
+    readonly value: string;
+    readonly testId?: string;
+    /** Click handler — set when the metric declares a `navigate` target
+     *  (see `MetricSpec`). Omitted for a plain, non-interactive metric. */
+    readonly onPress?: () => void;
+};
+/** Structured JSON display (audit payload/metadata, job logs, unsupported
+ *  jsonb/embedded field fallback). Takes the raw value, not a pre-stringified
+ *  one — the implementation owns `JSON.stringify` (and must not throw on
+ *  circular refs / BigInt / other non-serializable input). `indent` mirrors
+ *  `JSON.stringify`'s space-count param, default 2. */
+export type JsonViewProps = {
+    readonly value: unknown;
+    readonly indent?: number;
+    readonly testId?: string;
+};
+/** Band above the tabs of a record detail: optional subtitle line plus the
+ *  metrics as a definition list. `children` are `Metric` tiles. */
+export type MetricBandProps = {
+    readonly subtitle?: ReactNode;
+    readonly children: ReactNode;
+    readonly testId?: string;
+};
+/** Page title area rendered by the app shell's header instead of inside the
+ *  screen: `title` replaces the last breadcrumb, `status` sits right after it,
+ *  `actions` at the right edge. Renders nothing itself; without a shell slot
+ *  (see `usePageHeaderSlotAvailable`) callers keep their previous placement. */
+export type PageHeaderProps = {
+    readonly title?: string;
+    readonly status?: ReactNode;
+    readonly actions?: ReactNode;
+};
+/** One item in an `ActionOverflowMenu` (A7: header/row actions beyond the
+ *  primary one collapse into this menu instead of a wall of buttons). */
+export type ActionMenuItemSpec = {
+    readonly id: string;
+    readonly label: string;
+    /** Icon name, resolved by the implementation (same names as row actions). */
+    readonly icon?: IconKey;
+    readonly disabled?: boolean;
+    readonly variant?: "default" | "danger";
+    readonly onSelect: () => void;
+};
+export type ActionOverflowMenuProps = {
+    readonly items: readonly ActionMenuItemSpec[];
+    /** aria-label for the three-dots trigger. */
+    readonly label: string;
+    readonly testId?: string;
+};
+/** One revealed value on a `secretMint` screen's confirm phase (fw#2548). */
+export type SecretRevealValue = {
+    readonly label: string;
+    readonly value: string;
+    readonly copyable: boolean;
+    readonly multiline: boolean;
+    /** Render `value` as a scannable QR code instead of monospaced text — for
+     *  an otpauth://-style enrollment URI. Platforms without a QR-capable
+     *  SecretReveal primitive fall back to the monospaced display. */
+    readonly qr?: boolean;
+};
+/** One-time secret reveal — mint-form confirm phase. Renders each value
+ *  monospaced (multiline splits it one line per entry, for recovery codes),
+ *  with a per-value copy control when `copyable`. */
+export type SecretRevealProps = {
+    readonly values: readonly SecretRevealValue[];
+    readonly copyLabel: string;
+    readonly copiedLabel: string;
+    readonly testId?: string;
+};
+/** Thumb-reach action row for custom screens: pinned to the bottom edge on
+ *  narrow viewports (above the device's safe-area inset), inline otherwise.
+ *  `children` are the forward actions and share the remaining width; `back`
+ *  renders an icon-only back control in front of them. */
+export type StickyActionBarProps = {
+    readonly children: ReactNode;
+    readonly back?: {
+        readonly onBack: () => void;
+        readonly label: string;
+    };
+    readonly testId?: string;
+};
+/** Copies `text` to the clipboard; the label flips to `copiedLabel` once
+ *  the platform confirmed the write. */
+export type CopyButtonProps = {
+    readonly text: string;
+    readonly label: string;
+    readonly copiedLabel: string;
+    readonly variant?: "primary" | "secondary";
+    /** Layout extras — web merges via cn(), native impls ignore it. */
+    readonly className?: string;
+    readonly testId?: string;
+};
+/** Hands `text` to another app. "whatsapp" opens a WhatsApp chat prefilled
+ *  with the text (to `phone` when given, otherwise the contact picker);
+ *  "system" opens the platform share sheet and renders nothing where the
+ *  platform has none. */
+export type ShareButtonProps = {
+    readonly text: string;
+    readonly label: string;
+    readonly variant?: "primary" | "secondary";
+    /** Layout extras — web merges via cn(), native impls ignore it. */
+    readonly className?: string;
+    readonly testId?: string;
+} & ({
+    readonly target: "whatsapp";
+    readonly phone?: string;
+} | {
+    readonly target: "system";
+    readonly title?: string;
+    readonly url?: string;
+});
+export type PromoPanelAction = {
+    readonly label: string;
+    readonly href: string;
+    readonly testId?: string;
+} | {
+    readonly label: string;
+    readonly onClick: () => void;
+    readonly testId?: string;
+};
+/** Offer surface for upsells (e.g. "create an account"): its own tinted
+ *  panel with eyebrow, headline, benefit content and one call to action, so
+ *  an offer never reads like an info or error banner. */
+export type PromoPanelProps = {
+    readonly title: string;
+    readonly eyebrow?: string;
+    readonly children?: ReactNode;
+    readonly action?: PromoPanelAction;
+    readonly testId?: string;
+};
+export type CorePrimitives = {
+    readonly Button: ComponentType<ButtonProps>;
+    readonly Banner: ComponentType<BannerProps>;
+    readonly Field: ComponentType<FieldProps>;
+    readonly Input: ComponentType<InputProps>;
+    readonly DataTable: ComponentType<DataTableProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly EmbeddedListInput?: ComponentType<EmbeddedListInputProps>;
+    readonly Form: ComponentType<FormProps>;
+    readonly Section: ComponentType<SectionProps>;
+    readonly Card: ComponentType<CardProps>;
+    readonly Grid: ComponentType<GridProps>;
+    readonly GridCell: ComponentType<GridCellProps>;
+    readonly Text: ComponentType<TextProps>;
+    readonly Heading: ComponentType<HeadingProps>;
+    readonly Dialog: ComponentType<DialogProps>;
+    readonly Modal: ComponentType<ModalProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly Drawer?: ComponentType<DrawerProps>;
+    readonly Lightbox: ComponentType<LightboxProps>;
+    readonly ConfigSourceBadge: ComponentType<ConfigSourceBadgeProps>;
+    readonly ConfigCascadeView: ComponentType<ConfigCascadeViewProps>;
+    readonly Link: ComponentType<LinkProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly Progress?: ComponentType<ProgressProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly StepBar?: ComponentType<StepBarProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly WizardStepGroup?: ComponentType<WizardStepGroupProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly Tabs?: ComponentType<TabsProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly StatusBadge?: ComponentType<StatusBadgeProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly Metric?: ComponentType<MetricProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly JsonView?: ComponentType<JsonViewProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly FillContainer?: ComponentType<FillContainerProps>;
+    /** Optional — additive rollout, see StickyActionBar. Without it, header
+     *  content stays where the screen always rendered it. */
+    readonly PageHeader?: ComponentType<PageHeaderProps>;
+    /** Optional — additive rollout, see StickyActionBar. */
+    readonly MetricBand?: ComponentType<MetricBandProps>;
+    /** Optional: without an implementation, callers with >2 header/row
+     *  actions fall back to today's all-buttons-inline rendering (A7). */
+    readonly ActionOverflowMenu?: ComponentType<ActionOverflowMenuProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly SecretReveal?: ComponentType<SecretRevealProps>;
+    /** Optional (unlike the other Core-Primitives) so existing partial
+     *  CorePrimitives mocks in tests keep compiling — additive rollout of
+     *  a new primitive shouldn't force every test double to grow a stub. */
+    readonly StickyActionBar?: ComponentType<StickyActionBarProps>;
+    /** Optional — additive rollout, see StickyActionBar. */
+    readonly CopyButton?: ComponentType<CopyButtonProps>;
+    /** Optional — additive rollout, see StickyActionBar. */
+    readonly ShareButton?: ComponentType<ShareButtonProps>;
+    /** Optional — additive rollout, see StickyActionBar. */
+    readonly PromoPanel?: ComponentType<PromoPanelProps>;
+};
+/** Offene Extension-Zone für App-eigene Primitives. Devs erweitern
+ *  dieses Interface via TypeScript Module-Augmentation:
+ *
+ *    declare module "@cosmicdrift/kumiko-renderer" {
+ *      interface AppPrimitives {
+ *        Chip: ComponentType<ChipProps>;
+ *        Accordion: ComponentType<AccordionProps>;
+ *      }
+ *    }
+ *
+ *  Nach der Augmentation tauchen die Keys in `PrimitivesRegistry`,
+ *  `createKumikoApp({ primitives: { Chip, Accordion } })`, und
+ *  `usePrimitives().Chip` auf — TypeScript-gestützt. Kumikos eigene
+ *  Components nutzen ausschließlich `CorePrimitives`; App-Primitives
+ *  sind ausschließlich für Dev-Code (Custom-Screens, Shell, eigene
+ *  Components). */
+export interface AppPrimitives {
+}
+export type PrimitivesRegistry = CorePrimitives & AppPrimitives;
+export type PrimitivesProviderProps = {
+    readonly children: ReactNode;
+    readonly value: PrimitivesRegistry;
+};
+export declare function PrimitivesProvider({ children, value }: PrimitivesProviderProps): ReactNode;
+export declare function usePrimitives(): PrimitivesRegistry;