@rahdar/plugin-sdk 0.0.0-stage → 2026.10.50

package/types/ui/PageHeader.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+/**
+ * The page's one top-level heading, with what orients the operator beside it.
+ *
+ * <p>Every page renders exactly one of these; its sections follow it as `Section` (h2, then h3).
+ * The cluster a page belongs to goes in `meta`, next to the title, never as a second h1.
+ * The header wraps by its content's size, so it needs no breakpoints.
+ */
+export declare function PageHeader({ title, description, meta, actions, }: Readonly<{
+    /** Names the view; rendered as the page's h1. */
+    title: string;
+    /** One or two sentences on what the view shows. */
+    description?: ReactNode;
+    /** Context beside the title, such as the cluster and its environment. */
+    meta?: ReactNode;
+    /** The page's own actions, on the end side. */
+    actions?: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/Pager.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Previous/Next over a server-side page, with the position stated.
+ *
+ * One implementation rather than one per view: a paged view that does not say
+ * where it is leaves the operator unable to tell whether they are looking at
+ * everything, which is exactly the failure ADR-0056 is about.
+ *
+ * Rendered even on a single page, because "1–14 of 14" is the sentence that
+ * settles the question; hiding it leaves the same doubt a missing pager does. The Previous and Next
+ * buttons only exist from the second page on, and the pager holds their height either way, so the
+ * rows below it do not move as the total grows past one page or shrinks back.
+ */
+export declare function Pager({ page, pageSize, total, onChange, label, }: Readonly<{
+    /** 1-based. */
+    page: number;
+    pageSize: number;
+    total: number;
+    onChange: (page: number) => void;
+    /** Plural noun for the rows, e.g. `flows`. */
+    label: string;
+}>): import("react").JSX.Element;

package/types/ui/Section.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode, type Ref } from 'react';
+/**
+ * A titled block of a page. It is a region named by its heading, so a screen reader can jump to it.
+ *
+ * <p>The heading is an h2 by default, or an h3 inside another section; a page never skips a level.
+ * `variant="card"` frames the block as a raised panel, for content that should read as one unit.
+ *
+ * <p>`ref` and `tabIndex` let a page move focus into a section, such as to the one a skip link or a
+ * validation summary points at: `tabIndex={-1}` makes it focusable by script without a tab stop.
+ */
+export declare function Section({ title, headingLevel, description, actions, variant, ref, tabIndex, children, }: Readonly<{
+    title: string;
+    /** 2 for a section of the page, 3 for one nested in a section. */
+    headingLevel?: 2 | 3;
+    description?: ReactNode;
+    /** Controls for the section as a whole, on the end side of the heading. */
+    actions?: ReactNode;
+    variant?: 'plain' | 'card';
+    ref?: Ref<HTMLElement>;
+    tabIndex?: number;
+    children?: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/Stat.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+/**
+ * A labelled figure. A `null` value renders "Unavailable", with `unavailableReason` written out
+ * beneath it so the reason is read by every route (keyboard, screen reader, pointer), never "0":
+ * an absent number that reads as zero is the most dangerous misreading. A `0` value is a real zero.
+ *
+ * <p>Figures are tabular, so a change between refreshes is visible without reading digits. While
+ * `loading`, the figure's place is reserved at the size it will have, so what arrives does not move
+ * the page.
+ */
+export declare function Stat({ label, value, unit, unavailableReason, loading, }: Readonly<{
+    label: string;
+    /** The figure, or `null` when it is not known. */
+    value: ReactNode;
+    /** Shown after the figure, such as "msg/s". Omitted while the figure is unavailable. */
+    unit?: string;
+    /** Why the figure is not known; shown only when `value` is `null`. */
+    unavailableReason?: string;
+    loading?: boolean;
+}>): import("react").JSX.Element;

package/types/ui/StatusBadge.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A state, always in words. `children` is the word ("Degraded", "Stopped"); the tone only
+ * emphasises it, so the badge reads the same without colour. Healthy and neutral states stay quiet:
+ * colour appears for `warning` and `danger` only.
+ */
+export declare function StatusBadge({ tone, children, }: Readonly<{
+    /** `neutral` for a state that needs no attention, `info` for a notable one, `warning` and `danger` for a fault. */
+    tone?: 'neutral' | 'info' | 'warning' | 'danger';
+    /** The state, as a word or short phrase. */
+    children: string;
+}>): import("react").JSX.Element;

package/types/ui/Toolbar.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+/**
+ * The row of controls above a view.
+ *
+ * <p>By default it is a labelled group of controls, each its own tab stop. With `arrowNavigation` it
+ * is an ARIA toolbar: one tab stop for the whole row, the arrow keys, Home and End move between the
+ * controls, and the toolbar remembers the one last used. Use that only for a row of several
+ * controls that belong together; a toolbar of one or two is better as plain tab stops.
+ */
+export declare function Toolbar({ label, start, end, arrowNavigation, }: Readonly<{
+    /** Names the toolbar for assistive technology, such as "Queue filters". */
+    label: string;
+    /** Controls that act on the view, on the start side. */
+    start?: ReactNode;
+    /** Controls for the page's state or layout, on the end side. */
+    end?: ReactNode;
+    /** Makes it an ARIA toolbar with a single tab stop and arrow-key movement. */
+    arrowNavigation?: boolean;
+}>): import("react").JSX.Element;

package/types/ui/capabilityGate.d.ts

@@ -0,0 +1,43 @@
+import type { components } from '../kernel/api/schema.d.ts';
+type CapabilityView = components['schemas']['CapabilityView'];
+export type GateVerdict = {
+    kind: 'allowed';
+    uncertain: boolean;
+} | {
+    kind: 'blocked';
+    reason: string;
+    snippet?: string | null;
+};
+/** What a permission is held on: one cluster, or Rahdar itself. */
+export type GateScope = 'cluster' | 'installation';
+/** What is known of a refusal on one queue or address: the permission, and who owns it, to say who can grant it. */
+export interface ResourceDenial {
+    permission: string;
+    noun: 'queue' | 'address';
+    /** The name of the team that owns the resource; none when no team does. */
+    owner?: string | null;
+}
+/**
+ * Whether a lifecycle control may act, and why not when it may not.
+ *
+ * <p>Two independent gates, in the order the operator can do something about:
+ *
+ * <ul>
+ *   <li><b>Permission</b> — the caller's own grants. The server is the
+ *       enforcement point; this only explains, and never hides.
+ *   <li><b>Capability</b> — whether the broker connection can write at all. Only
+ *       a known refusal blocks. Since ADR-0049 D5 an unproven capability is
+ *       reported as unknown, and blocking on the absence of evidence would stop
+ *       an operator using a broker that works perfectly well.
+ * </ul>
+ *
+ * <p>`scope` is what the permission is held on, so the reason names the right place: `cluster` for
+ * an action on one cluster (the usual one), `installation` for one on Rahdar itself, such as its
+ * settings, users or plugins.
+ */
+export declare function gateFor(permitted: boolean, permissionLabel: string, capability: CapabilityView | undefined, 
+/** True while the caller's grants are still being fetched. */
+loading?: boolean, scope?: GateScope, 
+/** Given for a control on one queue or address the caller can see: the reason then names the permission and whom to ask. */
+denial?: ResourceDenial): GateVerdict;
+export {};

package/types/ui/codeDiagnostics.d.ts

@@ -0,0 +1,11 @@
+import type { Diagnostic } from '@codemirror/lint';
+import type { EditorState } from '@codemirror/state';
+/** A problem at a 1-based line and column, as a server validator reports it. */
+export interface CodeDiagnostic {
+    line: number;
+    column: number;
+    message: string;
+    severity: 'error' | 'warning';
+}
+/** A 1-based line and column, clamped into the document, as a one-character range. */
+export declare function toCodeMirror(state: EditorState, d: CodeDiagnostic): Diagnostic;

package/types/ui/codeMirrorTheme.d.ts

@@ -0,0 +1,11 @@
+import { HighlightStyle } from '@codemirror/language';
+/**
+ * Every colour comes from `theme.css`, so the editor follows the colour scheme
+ * with the rest of the console and neither scheme is inferred from the other
+ * (non-negotiable #6). A SQL identifier deliberately stays body text, so the eye
+ * lands on what was typed rather than on the syntax. A YAML or JSON document is
+ * mostly keys and values, so those two carry colour, and the punctuation that
+ * holds them together steps back.
+ */
+export declare const codeHighlight: HighlightStyle;
+export declare const codeTheme: import("@codemirror/state").Extension;

package/types/ui/diagram.d.ts

@@ -0,0 +1,49 @@
+/** The plain data `DiagramView` draws, and the words it reads out (ADR-0117). */
+/** One box of a `DiagramView`. Everything is plain data, shown as text. */
+export interface DiagramNode {
+    id: string;
+    /** The box's name, one line. */
+    label: string;
+    /** What kind of thing it is, in words ("Call a service"). Shown above the label. */
+    kind?: string;
+    /** A second line under the label ("inventory POST /reserve"). */
+    detail?: string;
+    /** Something is wrong with it: shown in words and colour, and read out with the node. */
+    state?: 'error' | 'warning';
+    /** Why, for a node with a state. */
+    reason?: string;
+}
+/** One arrow of a `DiagramView`, from `source` to `target`. */
+export interface DiagramEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+    /** Drawn dashed: a secondary path. Its meaning belongs in its label. */
+    dashed?: boolean;
+    /** Something can be inserted on this arrow: it offers the diagram's `insertChoices`. */
+    insertable?: boolean;
+}
+/** One thing a `DiagramView` offers to insert on an arrow ("Call a service"). */
+export interface DiagramChoice {
+    value: string;
+    label: string;
+    /** A heading the choice is listed under. */
+    group?: string;
+}
+/** One action in a box's menu. The diagram only reports it: the caller changes the nodes. */
+export interface DiagramAction {
+    id: string;
+    label: string;
+    /** Why it cannot be taken here. It stays listed, with the reason, rather than disappearing. */
+    disabledReason?: string;
+    /** Destroys something: shown in the danger colour. The label still says so in words. */
+    danger?: boolean;
+}
+/** What positions depend on: which nodes exist and how they connect. A new label moves nothing. */
+export declare function layoutSignature(nodes: DiagramNode[], edges: DiagramEdge[], direction: string): string;
+/**
+ * The accessible name of a node: kind, label and detail, the labels of the arrows into it (which a
+ * screen reader otherwise never meets), and any problem.
+ */
+export declare function nodeName(n: DiagramNode, via?: string[]): string;

package/types/ui/errorReading.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+/** What the failure is, why, and what the operator can do about it. */
+export interface Reading {
+    title: string;
+    cause: string;
+    next: ReactNode;
+    /** Whether trying again can help without the operator changing something first. */
+    retry: boolean;
+    fields?: readonly {
+        field: string;
+        message: string;
+    }[];
+    requestId?: string;
+    /** What the server said about this failure, when a mapping's own words win and would otherwise drop it. */
+    detail?: string;
+}
+/**
+ * The reading of an approval gate refusal, or `undefined` for any other error: for a mutation's toast,
+ * whose own cause and next step would otherwise read as an ordinary failure.
+ */
+export declare function readGateRefusal(error: unknown): Reading | undefined;
+/**
+ * Reads an error by its shape, for `ErrorState` and for a caller that needs only its title. An operation held
+ * for approval reads as sent, not failed; an approval gate refusal reads by its problem type. An `ApiError` carries `status`, `brokerErrorKind`, `fieldErrors` and
+ * the whole problem body as `problem` (`title`, `detail`, `hint`, `permission`, `retryAfter`,
+ * `requestId`); a string `hint` is the next step; a 422 with no field errors reads as its own title and
+ * detail; a failed
+ * fetch reads as the network being down; anything else with no status is an error inside the console.
+ */
+export declare function readError(error: unknown): Reading;

package/types/ui/formErrors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The second argument of `form.onSubmit`: on a rejected submit, move focus to the first invalid
+ * field in reading order, so the operator lands on what to fix rather than hunting for it.
+ */
+export declare function focusFirstInvalid(getInputNode: (path: string) => HTMLElement | null): (errors: Record<string, unknown>) => void;
+/**
+ * The server's field errors that name a field this form has, ready for `form.setErrors`. An error for
+ * a field the form does not show is left out, because a message with no field to sit beside is lost.
+ */
+export declare function serverFieldErrors(error: unknown, fields: readonly string[]): Record<string, string>;

package/types/ui/graph/ViewControls.d.ts

@@ -0,0 +1,19 @@
+import { type FitViewOptions } from '@xyflow/react';
+/**
+ * Zoom in, zoom out and fit, for a diagram drawn with React Flow. It replaces React Flow's own
+ * `<Controls>`, which brings its own colours and focus ring: these are Rahdar's buttons, named in words
+ * and themed by the tokens. Nothing animates (`duration: 0`), so reduced motion needs nothing more.
+ *
+ * <p>Render it inside the `ReactFlowProvider`, in a frame that is positioned. `fit` is how the diagram
+ * fits itself, so the button does what the diagram does when it first opens; `subject` names what is fitted.
+ * React Flow reports these moves with no event, as it does its own, so `onViewChange` says which the operator made.
+ */
+export declare function ViewControls({ fit, subject, className, onViewChange, }: Readonly<{
+    fit: FitViewOptions;
+    /** What the fit button fits, as a noun: "diagram", "topology". */
+    subject?: string;
+    /** Added to the group's own class, for a diagram that moves the controls aside. */
+    className?: string;
+    /** The operator zoomed or fitted the view with one of these buttons. */
+    onViewChange?: (change: 'zoom' | 'fit') => void;
+}>): import("react").JSX.Element;

package/types/ui/graph/elk.d.ts

@@ -0,0 +1,3 @@
+import type { ElkNode } from 'elkjs/lib/elk-api';
+/** Lay a graph out and return where each node goes. */
+export declare function runLayout(graph: ElkNode): Promise<ElkNode>;

package/types/ui/held.d.ts

@@ -0,0 +1,12 @@
+/** An operation held for approval, as read from the error a held request throws. */
+export interface Held {
+    id: string;
+    summary: string;
+}
+/**
+ * The held operation an error carries, read by its shape (the kernel's `OperationHeldError`), so the
+ * shared parts recognise it without importing the kernel. `undefined` for any other error.
+ */
+export declare function heldOf(error: unknown): Held | undefined;
+/** The in-app page of one approval request. */
+export declare const approvalPath: (id: string) => string;

package/types/ui/inAppNavigation.d.ts

@@ -0,0 +1,5 @@
+import type { MouseEvent } from 'react';
+/** Registers how to move to an in-app path. Returns the unregistration. */
+export declare function setInAppNavigate(next: (to: string) => void): () => void;
+/** A click handler for an anchor to `to`: a plain click navigates in the app, a modified one is left to the browser. */
+export declare function followInApp(event: MouseEvent<HTMLAnchorElement>, to: string): void;

package/types/ui/nodeOutcome.d.ts

@@ -0,0 +1,13 @@
+import type { components } from '../kernel/api/schema.d.ts';
+type LifecycleOutcomeView = components['schemas']['LifecycleOutcomeView'];
+/**
+ * Whether the command actually landed on every node it named — the one question a
+ * caller asks before treating the resource as changed.
+ *
+ * <p>Stated positively on purpose. `partial` is false both when everything worked
+ * and when nothing did (a cluster with no live node settles nowhere), so a caller
+ * that asks "not partial and nothing failed" concludes a delete succeeded against
+ * a cluster it never reached.
+ */
+export declare function appliedEverywhere(outcome: LifecycleOutcomeView): boolean;
+export {};

package/types/ui/notify.d.ts

@@ -0,0 +1,77 @@
+import { type Held } from './held.ts';
+/**
+ * The three forms of one action's verb, so a mutation's toast names it as its button does: the
+ * button "Delete" is followed by "Deleting…", then "Deleted". Written out rather than derived,
+ * because English inflection is irregular.
+ */
+export type ActionVerb = Readonly<{
+    /** As on the control, such as "Delete". */
+    verb: string;
+    /** The outcome, such as "Deleted". */
+    past: string;
+    /** While it runs, such as "Deleting". */
+    progressive: string;
+}>;
+type Notice = Readonly<{
+    action: ActionVerb;
+    /** What the action acts on, such as `queue "orders"`. */
+    subject: string;
+}>;
+/** Settles a toast that {@link notify.pending} returned: it is replaced by the outcome. */
+type Settles = Readonly<{
+    pendingId?: string;
+}>;
+/**
+ * One helper for the four outcomes of a mutation (pending, succeeded, failed, partial), over
+ * Mantine's notifications, which must be mounted once at the root.
+ *
+ * <ul>
+ *   <li>Every line names the outcome with the action's own verb ({@link ActionVerb}).
+ *   <li>Pending and succeeded are announced politely. Failed and partial are announced
+ *       assertively and stay until dismissed, because each carries a next step to act on.
+ *   <li>A failure states its cause and the next action; both are required.
+ *   <li>An operation held for approval is a fifth outcome, not a failure: {@link notify.held} says it was sent
+ *       and links to the request. {@link notify.settle} routes a mutation's error to it or to
+ *       {@link notify.failed}, so every mutation's error handler goes through `settle`.
+ *   <li>A toast that stays until dismissed can be dismissed by the caller with {@link notify.dismiss},
+ *       such as a failure the operator has since fixed by retrying.
+ * </ul>
+ */
+export declare const notify: {
+    /** The action is running. Returns the toast's id; pass it as `pendingId` to the outcome. */
+    pending({ action, subject }: Notice): string;
+    /** The action finished everywhere. */
+    succeeded({ action, subject, pendingId }: Notice & Settles): string;
+    /** The action did not happen. `cause` says why; `next` says what to do. */
+    failed({ action, subject, pendingId, cause, next }: Notice & Settles & Readonly<{
+        cause: string;
+        next: string;
+    }>): string;
+    /**
+     * The action reached some of what it was asked to. `reached` says how far, such as "2 of 3
+     * nodes"; `next` says what is left to do.
+     */
+    partial({ action, subject, pendingId, reached, next, }: Notice & Settles & Readonly<{
+        reached: string;
+        next: string;
+    }>): string;
+    /**
+     * The action was sent for approval instead of running: it waits for a second person, and the toast links to
+     * its request. Announced politely, because nothing went wrong.
+     */
+    held({ id, summary, pendingId }: Held & Settles): string;
+    /**
+     * Settles a mutation that threw: a held operation becomes {@link notify.held}, an approval gate refusal a
+     * failure in the gate's own words, and anything else {@link notify.failed} as given. `onHeld` runs when it was
+     * held, so a dialog that closes on success closes then too: the request waits elsewhere, and leaving the
+     * dialog open and armed invites submitting it again.
+     */
+    settle(error: unknown, failure: Notice & Settles & Readonly<{
+        cause: string;
+        next: string;
+        onHeld?: () => void;
+    }>): string;
+    /** Closes a toast by the id one of the outcomes returned. */
+    dismiss(id: string): void;
+};
+export {};

package/types/ui/safeHref.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The address to put in an `href`, `src` or `window.open` when it came from data (a plugin's vendor
+ * link, an identity provider's start path, a link in broker data), or `undefined` when it must not
+ * be linked. It allows `http:`, `https:`, `mailto:` and addresses on this page's own origin, which is
+ * how a relative path resolves. The check parses the value the way a browser does, so leading
+ * whitespace, tabs and newlines inside the scheme cannot hide one.
+ */
+export declare function safeHref(value: string | null | undefined): string | undefined;

package/types/ui/table/ColumnsMenu.d.ts

@@ -0,0 +1,26 @@
+import type { Density } from './density.ts';
+interface ColumnsMenuEntry {
+    id: string;
+    header: string;
+    visible: boolean;
+    /** A column that identifies a row or names a node is always shown. */
+    locked: boolean;
+}
+/**
+ * The Columns control, always in the table's toolbar with its space reserved so the table's width
+ * never depends on whether anything is hidden. Its name carries how many columns are hidden, whether
+ * the viewer or a narrow window hid them; it lets the viewer show or hide each, move each earlier or
+ * later, choose the density and put widths back to fitting. The first column stays first.
+ */
+export declare function ColumnsMenu({ columns, hiddenCount, onToggle, onMove, density, onDensity, canResetWidths, onResetWidths, }: Readonly<{
+    /** Every column in the order now shown. */
+    columns: ColumnsMenuEntry[];
+    hiddenCount: number;
+    onToggle: (id: string, visible: boolean) => void;
+    onMove: (id: string, by: -1 | 1) => void;
+    density: Density;
+    onDensity: (density: Density) => void;
+    canResetWidths: boolean;
+    onResetWidths: () => void;
+}>): import("react").JSX.Element;
+export {};

package/types/ui/table/DataTable.d.ts

@@ -0,0 +1,109 @@
+import { type ReactNode } from 'react';
+import type { Column } from './columns.ts';
+import { type GridOnlyProps } from './GridTable.tsx';
+/** Above this many rows a static table is drawn as the grid, so a list that grows never falls off a cliff. */
+export declare const STATIC_ROW_LIMIT = 200;
+/** The controls a table's toolbar carries beside its Columns control. */
+export interface TableToolbar {
+    start?: ReactNode;
+    end?: ReactNode;
+}
+interface DataTableBaseProps<T> {
+    columns: Column<T>[];
+    data: T[];
+    rowKey: (row: T) => string;
+    /** What the table lists, as its accessible name: "Queues", "Connections". */
+    label: string;
+    /** Shown in place of the rows when there are none: an `EmptyState`. */
+    empty: ReactNode;
+    /** The first load: the header and placeholder rows. Once there are rows it is a refetch, and they stay. */
+    loading?: boolean;
+    /** Shown below the rows in place of them when set: an `ErrorState`. */
+    error?: ReactNode;
+    /**
+     * Remembers the widths, hidden columns and order each viewer chooses, in this browser. Stable and
+     * unique per table; a plugin prefixes its id. Read again whenever it changes. Without one, the
+     * choices last as long as the table is shown.
+     */
+    storageKey?: string;
+    /** The current `sort` query value: a column's `sortKey`, with a leading `-` for descending. The URL owns it. */
+    sort?: string;
+    onSortChange?: (sort: string | undefined) => void;
+    /**
+     * An extra class per row, for state the caller owns, such as a live tail's fresh rows. A class that
+     * tints the row sets `--row-tint`, so the sticky cells carry the tint too.
+     */
+    rowClassName?: (row: T) => string | undefined;
+    /** `'fill'` takes the height its parent gives it; `{ maxRows }` is as tall as its rows, up to that many. */
+    height?: 'fill' | {
+        maxRows: number;
+    };
+    toolbar?: TableToolbar;
+}
+export interface GridVariantProps<T> extends DataTableBaseProps<T>, GridOnlyProps<T> {
+    variant?: 'grid';
+}
+interface StaticVariantProps<T> extends DataTableBaseProps<T> {
+    /** A small, read-only set in a native table. Above 200 rows it is drawn as the grid. */
+    variant: 'static';
+    caption?: ReactNode;
+    /**
+     * `false` drops the Columns control, for a short fixed set where every column is needed and there is
+     * nothing to hide, reorder or resize, such as a diff in a dialog. The grid always has it.
+     */
+    columnsMenu?: boolean;
+}
+export type DataTableProps<T> = GridVariantProps<T> | StaticVariantProps<T>;
+/** What the renderers share: the solved columns, the viewer's state and the ways to change it. */
+export interface TableModel<T> {
+    label: string;
+    data: T[];
+    rowKey: (row: T) => string;
+    rowClassName?: (row: T) => string | undefined;
+    sort?: string;
+    onSortChange?: (sort: string | undefined) => void;
+    /** The columns drawn: those that fit and that the viewer has not hidden, in their order. */
+    columns: Column<T>[];
+    /** Every column's id, in the viewer's order, hidden ones included. */
+    order: string[];
+    /** `grid-template-columns` for the drawn columns, and the px each gets. */
+    template: string;
+    solved: Record<string, number>;
+    overflow: boolean;
+    /** The inline size the tracks need, when they overflow. */
+    minInline: number;
+    /** The widths a viewer has set, including one being dragged. */
+    widths: Record<string, number>;
+    rowHeight: number;
+    maxRows: number | undefined;
+    loading: boolean;
+    measurer: ReactNode;
+    onWidth: (px: number) => void;
+    announce: (text: string) => void;
+    previewWidth: (id: string, width: number | undefined) => void;
+    setWidth: (id: string, width: number) => void;
+    fit: (id: string) => void;
+    interaction: {
+        set: (kind: 'pointer' | 'focus' | 'scrolled', on: boolean) => void;
+    };
+}
+/**
+ * The console's one data table (ADR-0160), in one of two renderers over one column model:
+ *
+ * <ul>
+ *   <li>`'grid'`, the default: interactive and always virtualised, with a roving-focus keyboard
+ *       model, a row menu, selection and resizable columns.
+ *   <li>`'static'`: a native `<table>` for a small read-only set, drawn as the grid above 200 rows.
+ * </ul>
+ *
+ * Columns are sized by what they hold, never by pixel widths (ADR-0161). When they do not fit, the
+ * longest values are shortened, then the least important columns are hidden (and counted in the
+ * Columns control), and only then does the table scroll sideways. Sorting is a round trip through
+ * the URL: pass `sort` and `onSortChange`.
+ *
+ * The frame is the toolbar, then the table, then a state slot, as siblings: an empty, error or
+ * loading state is never inside `role="grid"`. Build `columns` once (in a `useMemo`) so rows are not
+ * redrawn for nothing.
+ */
+export declare function DataTable<T>(props: Readonly<DataTableProps<T>>): import("react").JSX.Element;
+export {};

package/types/ui/table/GridFind.d.ts

@@ -0,0 +1,16 @@
+interface GridFindProps {
+    /** The grid's accessible name, which names the find. */
+    label: string;
+    query: string;
+    onQuery: (query: string) => void;
+    count: number;
+    current: number;
+    onStep: (by: 1 | -1) => void;
+    onClose: () => void;
+}
+/**
+ * The find of a virtualised grid: the browser's own cannot see rows that are not rendered. Enter
+ * and Shift+Enter move between matches, Escape closes it; the result is announced politely.
+ */
+export declare function GridFind({ label, query, onQuery, count, current, onStep, onClose }: Readonly<GridFindProps>): import("react").JSX.Element;
+export {};

package/types/ui/table/GridTable.d.ts

@@ -0,0 +1,49 @@
+import { type ReactNode } from 'react';
+import type { TableModel } from './DataTable.tsx';
+/** What a row menu's items get: a way to close the menu, and to put focus back on the row. */
+export interface RowMenuContext {
+    close: () => void;
+    /**
+     * Puts focus back on the row's Actions control, scrolling it into view if it has left; on the
+     * grid when the row is gone. For a dialog opened from the menu to call when it closes.
+     */
+    restoreFocus: () => void;
+}
+/** A per-row action menu (ADR-0107): its items are rendered only while it is open. */
+export interface RowMenu<T> {
+    /** Names the row in "Actions for <label>". */
+    label: (row: T) => string;
+    render: (row: T, context: RowMenuContext) => ReactNode;
+}
+export interface GridOnlyProps<T> {
+    /** Activating a row, by click or by Enter on any of its cells. */
+    onRowClick?: (row: T) => void;
+    /** A per-row action menu, opened by right-click, by the row's Actions control, or by Shift+F10. */
+    rowMenu?: RowMenu<T>;
+    /** Opt-in leading checkbox column. Selection state is owned by the caller. */
+    selectable?: boolean;
+    selected?: ReadonlySet<string>;
+    onToggleRow?: (key: string) => void;
+    /** Header select-all across the loaded page. `allSelected` is the current state; the caller flips it. */
+    onToggleAll?: (keys: string[], allSelected: boolean) => void;
+    /**
+     * Called when the grid's own scroll leaves or returns to the top. A live feed that prepends rows
+     * moves the content under a reader who has scrolled away, so the caller needs to know in order
+     * to hold new rows back.
+     */
+    onAtTopChange?: (atTop: boolean) => void;
+}
+/**
+ * The interactive renderer of `DataTable`: one CSS grid track list, declared once and shared by the
+ * header row and every body row, row-virtualised with `@tanstack/react-virtual` (ADR-0020).
+ *
+ * <p>The keyboard model is the WAI-ARIA grid (ADR-0108): the grid is one tab stop, the arrow keys
+ * move a roving focus between cells (the header row included), Enter activates a row, Space selects
+ * it, Shift+F10 opens its menu, Ctrl/Cmd+C copies a focused cell, and Ctrl+Shift+Left/Right on a
+ * header cell resizes its column. The active cell is remembered by row key and column id, so a
+ * refresh, a re-sort or a hidden column does not move it, and its row is always rendered however far
+ * it is scrolled.
+ */
+export declare function GridTable<T>({ model, onRowClick, rowMenu, selectable, selected, onToggleRow, onToggleAll, onAtTopChange, }: Readonly<{
+    model: TableModel<T>;
+} & GridOnlyProps<T>>): import("react").JSX.Element;