@box-kite/react 2.0.1 → 2.1.0

package/utils/catalog/catalogManifest.d.ts

@@ -0,0 +1,8 @@
+import { CatalogManifest } from '@box-kite/core';
+/**
+ * Generated by `npm run docs:catalog` — never edited by hand. What a prop *means*, extracted from the
+ * same JSDoc the reference and the AI context come from; what it *accepts* is read off the live engine,
+ * so this file says nothing that could go stale against a `Box.extend()`.
+ */
+declare const catalogManifest: CatalogManifest;
+export default catalogManifest;

package/utils/dashboard/dashboardSchema.d.ts

@@ -0,0 +1,18 @@
+import { CatalogSchema } from '@box-kite/core';
+/**
+ * The layout's own shape, as a schema and the two numbers it quotes. Its own module because both the
+ * dashboard and `catalog()` want it and only one of them wants the model around it: reaching it through
+ * `dashboardUtils` would put the compaction, the drag arithmetic and the parser in the catalog entry.
+ * Plain exports rather than a namespace, so neither entry carries a wrapper for four constants.
+ */
+/** The layout format's own version, bumped when its shape changes and never when a dashboard does. */
+export declare const LAYOUT_VERSION = 1;
+/** Both ends of the column space a layout may declare, so a generated `columns: 400` cannot be rendered. */
+export declare const MIN_COLUMNS = 1;
+export declare const MAX_COLUMNS = 24;
+/**
+ * The layout as JSON Schema — what a model generates a dashboard under, and the half of the contract a
+ * prompt cannot carry. Deliberately inside the subset `catalog()` emits and `<SpecRenderer>` validates,
+ * so a host can hand it to the same machinery: the schema says the shape and `parse` says the sense.
+ */
+export declare const LAYOUT_SCHEMA: CatalogSchema;

package/utils/dashboard/dashboardUtils.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Where a widget sits, in cells. The unit is the whole point: a layout written in cells is the same
+ * layout at any width, and a drag moves by one of them rather than by a pixel somebody measured.
+ */
+export interface DashboardItem {
+    /** What this place belongs to — the `id` of the widget that fills it. */
+    id: string;
+    /** Column and row, both zero-based. */
+    x: number;
+    y: number;
+    /** How many columns and rows it spans, at least one of each. */
+    w: number;
+    h: number;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    /** Never moved and never resized — the rest of the layout flows around it. */
+    fixed?: boolean;
+}
+/**
+ * The artifact: one column space, one list of places, and a version in front of both. It is what a model
+ * emits, what a host stores and what a drag reports back, which is why it is plain JSON with no
+ * component, no callback and no measurement anywhere in it.
+ */
+export interface DashboardLayout {
+    version: number;
+    /** The space the items are written in. A narrower container renders a projection of it.  */
+    columns: number;
+    items: DashboardItem[];
+}
+/** What a layout that arrived as JSON got wrong, in the shape the spec renderer reports issues in. */
+export interface DashboardIssue {
+    code: 'not-an-object' | 'version' | 'columns' | 'items' | 'invalid-item' | 'duplicate-id';
+    /** Where it happened, printable: `items.2.w`. */
+    path: string;
+    message: string;
+}
+/** The pixel a cell steps by on each axis — one cell plus the gap after it. Measured once per drag. */
+export interface DashboardStep {
+    x: number;
+    y: number;
+}
+declare namespace DashboardUtils {
+    const VERSION = 1;
+    const MIN_COLUMNS = 1;
+    const MAX_COLUMNS = 24;
+    /** Whether two places want the same cell. Touching edges do not overlap — `x + w` is the first column past it. */
+    function overlaps(left: DashboardItem, right: DashboardItem): boolean;
+    /**
+     * Every item clamped, then floated up and pushed down until nothing overlaps — so a layout has no holes
+     * and a widget cannot be parked in mid-air. That is what makes two dashboards of the same items compare
+     * equal, and it is why a drop below a neighbour rises to meet it.
+     *
+     * It is reading order and nothing else. A widget a drag is holding gets no priority here: settling it
+     * first floats it to the top of a board with nothing on it yet, which is every drag's opening frame
+     * (#183). Where a drop lands on an occupied cell it is `displace` that decides, before this runs.
+     */
+    function resolve(items: readonly DashboardItem[], columns: number): DashboardItem[];
+    /** The same, as a layout. Every function here returns one of these: a change is always the whole artifact. */
+    function normalize(layout: DashboardLayout): DashboardLayout;
+    function itemOf(layout: DashboardLayout, id: string): DashboardItem | undefined;
+    /** Where a widget sits in reading order, which is the order a stacked dashboard renders in. */
+    function ranks(layout: DashboardLayout): Map<string, number>;
+    /** A widget sent to a cell. The rest of the layout moves around it rather than refusing the move. */
+    function moveTo(layout: DashboardLayout, id: string, x: number, y: number): DashboardLayout;
+    /** A widget given a size. Its own minimum and maximum are applied by `resolve`, so this only asks. */
+    function resizeTo(layout: DashboardLayout, id: string, w: number, h: number): DashboardLayout;
+    /** A widget added where there is room for it: under everything, which compaction then floats up. */
+    function add(layout: DashboardLayout, item: Omit<DashboardItem, 'x' | 'y'> & Partial<DashboardItem>): DashboardLayout;
+    function remove(layout: DashboardLayout, id: string): DashboardLayout;
+    /**
+     * The same layout in a narrower space — arithmetic, not a measurement, which is what lets every
+     * projection be a class the browser chooses between. Widths scale and round up to a cell, so a widget
+     * never projects to nothing; the compaction afterwards is what closes the holes that leaves.
+     */
+    function project(layout: DashboardLayout, columns: number): DashboardLayout;
+    /** Whether a layout says anything new — so a drag that crossed no cell costs no render and no callback. */
+    function same(left: DashboardLayout, right: DashboardLayout): boolean;
+    /** How many cells a pointer has travelled, rounded to the nearest one. The step is a cell plus its gap. */
+    function cellsMoved(dx: number, dy: number, step: DashboardStep): {
+        columns: number;
+        rows: number;
+    };
+    /**
+     * A layout read from somewhere it could be anything: a model's answer, a `localStorage` string, a
+     * column of a database written by a version that has since moved on. Everything unusable is dropped and
+     * reported rather than thrown — a dashboard missing one widget is a dashboard, and an exception is not.
+     */
+    function parse(value: unknown, fallbackColumns?: number): {
+        layout: DashboardLayout;
+        issues: DashboardIssue[];
+    };
+    /** The layout as JSON Schema: what a model generates a dashboard under, and what `<SpecRenderer>` validates. */
+    const SCHEMA: import("../../core").CatalogSchema;
+}
+export default DashboardUtils;

package/utils/interop/a2uiInterop.d.ts

@@ -0,0 +1,82 @@
+import { BoxCatalog, CatalogSchema } from '@box-kite/core';
+import { SpecNode } from '../spec/specTypes';
+/** One component of a surface, flattened to v0.9's shape whichever version it arrived in. */
+export interface A2uiComponent {
+    id: string;
+    component: string;
+    [prop: string]: unknown;
+}
+/** One surface: its components, its own data model, and what the agent said about rendering it. */
+export interface A2uiSurface {
+    id: string;
+    catalogId?: string;
+    /** v0.8 names the root in its `beginRendering`; v0.9 settles it by convention, which is the id `root`. */
+    root?: string;
+    theme?: Record<string, unknown>;
+    components: Record<string, A2uiComponent>;
+    data: Record<string, unknown>;
+}
+/** Every surface an agent has opened, in the order it opened them. */
+export interface A2uiState {
+    surfaces: Record<string, A2uiSurface>;
+    order: string[];
+}
+export interface A2uiSpecOptions {
+    /** Which component to start from. Otherwise the surface's own root, and then the id `root`. */
+    root?: string;
+    /**
+     * `catalog()`, where the agent generated against this library's own components: a prop the catalog
+     * lists as an event becomes an `on` binding rather than a value. Without one, only A2UI's `action` is.
+     */
+    catalog?: {
+        components: Record<string, {
+            events?: string[];
+        }>;
+    };
+}
+export interface A2uiCatalogOptions {
+    /** The document's own id, which is what an agent's `createSurface.catalogId` names. */
+    catalogId?: string;
+    title?: string;
+    description?: string;
+}
+declare namespace A2uiInterop {
+    /** The id v0.9 settles the root by, since its `createSurface` does not carry one. */
+    const ROOT_ID = "root";
+    /** The surface a message means when it names none, which is what the published renderers call it. */
+    const DEFAULT_SURFACE = "main";
+    const EMPTY: A2uiState;
+    /**
+     * One message, whichever of v0.8 and v0.9 it is written in. The same state comes back where the
+     * message changed nothing or is not an A2UI message at all — a transport carries plenty that is not.
+     */
+    function apply(state: A2uiState, message: unknown): A2uiState;
+    /** A whole stream, oldest first. A JSONL transport is `applyAll(state, lines.map(JSON.parse))`. */
+    function applyAll(state: A2uiState, messages: readonly unknown[]): A2uiState;
+    /** A surface by id, or the first one opened — which is the whole of it for an agent that opens one. */
+    function surface(state: A2uiState, id?: string): A2uiSurface | null;
+    /**
+     * A surface as one `<SpecRenderer>` tree. A component nothing reaches from the root is not rendered —
+     * an agent streams a leaf before the branch that holds it, so a half-arrived surface is the ordinary
+     * case rather than an error, and the node appears when the message naming it does.
+     */
+    function toSpec(surface: A2uiSurface | null, options?: A2uiSpecOptions): SpecNode | null;
+    /**
+     * `catalog()` as an A2UI catalog document. The components and the values their props take are the
+     * same ones; what changes is the shape around them — a component carries its own `id`, its type is a
+     * property rather than the key above it, and its children are **ids** rather than nested nodes, which
+     * is the whole of what an adjacency list is.
+     *
+     * Every event the catalog names becomes a string, because a JSON message cannot carry a function: what
+     * an agent writes is the name of an action, and `onAction` is where the host decides what it does.
+     */
+    /**
+     * One component of a catalog document, self-contained. A `$ref` resolves against the *document*, so a
+     * component lifted out of one on its own points at nothing — which is what every consumer that
+     * converts a component at a time does (`z.fromJSONSchema` for CopilotKit's renderer and json-render
+     * alike). Measured against zod 4.6: it throws `Reference not found: #/$defs/color`.
+     */
+    function componentSchema(document: Record<string, unknown>, name: string): CatalogSchema | null;
+    function catalogDocument(catalog: BoxCatalog, options?: A2uiCatalogOptions): Record<string, unknown>;
+}
+export default A2uiInterop;

package/utils/interop/assistantUiInterop.d.ts

@@ -0,0 +1,34 @@
+import { SpecNode } from '../spec/specTypes';
+/** assistant-ui's node: a string renders as text, an object is a component. */
+export type GenerativeUiNode = string | {
+    component: string;
+    props?: Record<string, unknown>;
+    children?: readonly GenerativeUiNode[];
+    key?: string;
+};
+/** assistant-ui's root, which is one node or several. */
+export interface GenerativeUiSpec {
+    root: GenerativeUiNode | readonly GenerativeUiNode[];
+}
+/** What `fromSpec` could not carry across, since their spec has nowhere to put it. */
+export interface GenerativeUiLoss {
+    /** `data-binding`, `repeat` or `event` — the three things their shape has no room for. */
+    code: 'data-binding' | 'repeat' | 'event';
+    path: string;
+}
+declare namespace AssistantUiInterop {
+    /**
+     * Their spec as ours. Several roots become the children of nothing, so a multi-root spec is rendered
+     * by mapping this over `spec.root` rather than being wrapped in a container nobody asked for.
+     */
+    function toSpec(spec: GenerativeUiSpec | null | undefined): SpecNode[];
+    /**
+     * Ours as theirs, with what could not come along reported rather than dropped in silence. A named
+     * slot has no counterpart either and is left out with the rest — their nodes have one children list.
+     */
+    function fromSpec(spec: SpecNode | readonly SpecNode[]): {
+        spec: GenerativeUiSpec;
+        losses: GenerativeUiLoss[];
+    };
+}
+export default AssistantUiInterop;

package/utils/interop/toolInterop.d.ts

@@ -0,0 +1,30 @@
+import { ApprovalDecision, ToolCallStatus } from '../agent/agentUtils';
+/** Which of the two cards a part belongs to. A call is shown; a question is answered. */
+export type ToolPartKind = 'call' | 'approval';
+/** A tool call in this library's words, whichever runtime's words arrived. */
+export interface ToolPart {
+    kind: ToolPartKind;
+    /** Where the call is, for `<ToolCallCard status>`. An approval waiting on a person is `pending`. */
+    status: ToolCallStatus;
+    /** What was decided, for `<ApprovalCard decision>`. `null` is a question nobody has answered yet. */
+    decision: ApprovalDecision | null;
+    /** The arguments, where the part carried them under any of its runtimes' names. */
+    input?: unknown;
+    output?: unknown;
+    /** The failure, as text, where the part reported one. */
+    error?: string;
+}
+declare namespace ToolInterop {
+    /**
+     * A part from any of the three runtimes that hand you one, in this library's words. `null` is a value
+     * that is not a tool part at all — the caller decides what that means, since a half-streamed message
+     * carrying nothing yet is ordinary.
+     */
+    function toolPart(value: unknown): ToolPart | null;
+    /**
+     * AG-UI is the odd one out: it reports *events*, not parts, so a card needs a fold rather than a
+     * mapping. One call per event, oldest first, keyed by `toolCallId`.
+     */
+    function applyEvent(parts: Readonly<Record<string, ToolPart>>, event: unknown): Record<string, ToolPart>;
+}
+export default ToolInterop;

package/utils/spec/specData.d.ts

@@ -0,0 +1,19 @@
+import { SpecRef, SpecScope } from './specTypes';
+declare namespace SpecData {
+    /** A reference is a plain object carrying exactly one of the three keys, and nothing beside it. */
+    function isRef(value: unknown): value is SpecRef;
+    /** What a reference points at, and whether it pointed at anything — `undefined` is an answer either way. */
+    function resolve(ref: SpecRef, scope: SpecScope): {
+        value: unknown;
+        found: boolean;
+    };
+    /** The text of a reference, for the message that says it resolved to nothing. */
+    function pathOf(ref: SpecRef): string;
+    /**
+     * A value with every reference inside it resolved — a prop is `{ $data: … }`, an array of them, or an
+     * object with one in a corner (a gradient's stops, a chart's series). Reported rather than dropped:
+     * the caller decides, because a reference that resolves to nothing mid-stream is ordinary.
+     */
+    function deep(value: unknown, scope: SpecScope, onMissing?: (path: string) => void, depth?: number): unknown;
+}
+export default SpecData;

package/utils/spec/specDefs.d.ts

@@ -0,0 +1,11 @@
+import { CatalogSchema } from '@box-kite/core';
+declare namespace SpecDefs {
+    /**
+     * A component's props, with its local `$defs` lifted into `defs` (which is mutated). The colour grammar
+     * is the same object for every component, so the twenty-six colour props across a whole catalog share
+     * one definition — and a host's custom schema that happens to name `color` something else is renamed
+     * rather than silently taking the palette's meaning.
+     */
+    function hoist(props: CatalogSchema, defs: Record<string, CatalogSchema>): CatalogSchema;
+}
+export default SpecDefs;

package/utils/spec/specProps.d.ts

@@ -0,0 +1,15 @@
+import { SpecAction, SpecIssue, SpecRules, SpecScope } from './specTypes';
+declare namespace SpecProps {
+    interface Resolved {
+        /** Everything the schema allowed, resolved. */
+        props: Record<string, unknown>;
+        /** The events the node bound, for the renderer to turn into functions. */
+        actions: Record<string, SpecAction>;
+        issues: SpecIssue[];
+        /** Required props that did not arrive, or were refused. A node with any of these cannot render. */
+        missing: string[];
+    }
+    /** The props pass for one node: resolved, validated, and an issue for everything left out. */
+    function resolve(node: Record<string, unknown>, rules: SpecRules, scope: SpecScope, path: string): Resolved;
+}
+export default SpecProps;

package/utils/spec/specSchema.d.ts

@@ -0,0 +1,23 @@
+import { CatalogSchema } from '@box-kite/core';
+/** A component, as much of it as a tree schema needs. A `catalog()` entry is one of these already. */
+export interface SpecSchemaComponent {
+    description?: string;
+    props?: CatalogSchema;
+    slots?: string[];
+    events?: string[];
+}
+export interface SpecSchemaSource {
+    components: Record<string, SpecSchemaComponent>;
+}
+export interface SpecSchemaOptions {
+    /** Which components may be the root of the tree. Every one of them by default. */
+    root?: string[];
+    /**
+     * Whether a prop may be a `{ $data: … }` reference and a node may `repeat`. Off by default: it widens
+     * every prop in the document with an `anyOf`, which is a cost a static view should not pay.
+     */
+    bindings?: boolean;
+}
+/** The JSON Schema a generated view has to conform to: a tree of the components this source allows. */
+export declare function specSchema(source: SpecSchemaSource, options?: SpecSchemaOptions): CatalogSchema;
+export default specSchema;

package/utils/spec/specTypes.d.ts

@@ -0,0 +1,71 @@
+import { CatalogSchema } from '@box-kite/core';
+/** A value read out of the data the spec is rendered against: `{ $data: 'user.name' }`. */
+export interface SpecDataRef {
+    /** A dot path (`stats.revenue.0`) or a JSON Pointer (`/stats/revenue/0`). Empty is the whole of it. */
+    $data: string;
+}
+/** The current item of the enclosing `repeat`. `{ $item: '' }` is the item itself. */
+export interface SpecItemRef {
+    $item: string;
+}
+/** The current index of the enclosing `repeat`, from zero. */
+export interface SpecIndexRef {
+    $index: true;
+}
+/** Anywhere a value can stand, a reference to one can stand instead. */
+export type SpecRef = SpecDataRef | SpecItemRef | SpecIndexRef;
+/** What an event does: it tells the host, which is the only thing that may decide what happens next. */
+export interface SpecAction {
+    action: string;
+    /** Sent back with the action, resolved the way a prop is. */
+    payload?: unknown;
+}
+/** One node of a generated tree, or a leaf that is text. */
+export type SpecChild = SpecNode | SpecRef | string | number | boolean | null;
+export interface SpecNode {
+    /** The component to render. A name the registry does not hold renders nothing. */
+    type: string;
+    /** React's key, where the host wants a node's identity to survive a re-order. */
+    key?: string;
+    /** Everything the component's own schema allows, and nothing else. */
+    props?: Record<string, unknown>;
+    /** The default slot. */
+    children?: SpecChild | SpecChild[];
+    /** The component's named slots — `Tooltip`'s `content`, a form control's `label`. */
+    slots?: Record<string, SpecChild | SpecChild[]>;
+    /** An event prop bound to an action the host handles: `{ onClick: 'refresh' }`. */
+    on?: Record<string, SpecAction | string>;
+    /** Render this node once per item of an array. `$item` and `$index` address the item inside it. */
+    repeat?: SpecRef;
+}
+/** Why a node, a prop or a child did not render. Advisory: the tree renders around every one of them. */
+export type SpecIssueCode = 'unknown-component' | 'unknown-prop' | 'invalid-prop' | 'missing-prop' | 'unknown-slot' | 'unknown-event' | 'unresolved-data' | 'invalid-child' | 'invalid-repeat' | 'too-deep' | 'too-many-nodes' | 'render-error';
+export interface SpecIssue {
+    code: SpecIssueCode;
+    /** Where in the spec it happened, as a path that can be printed: `children.1.props.bgColor`. */
+    path: string;
+    message: string;
+    /** The component the node named, where it named one. */
+    component?: string;
+    prop?: string;
+}
+/** What the renderer needs to know about one component. The implementation is the registry's half. */
+export interface SpecRules {
+    /** What its props may be. No schema at all means no props: a component is opened up on purpose. */
+    props?: CatalogSchema;
+    /** Where children may go. `default` is the ordinary children slot. */
+    slots: string[];
+    /** The props a spec may bind an action to. Nothing else can ever become a function. */
+    events: string[];
+    description?: string;
+}
+/** The data a reference is resolved against, plus whatever `repeat` put in scope. */
+export interface SpecScope {
+    data?: unknown;
+    item?: unknown;
+    index?: number;
+    /** Whether an `$item`/`$index` reference means anything here at all. */
+    repeating?: boolean;
+}
+/** The ordinary children slot, under the name the catalog gives it. */
+export declare const DEFAULT_SLOT = "default";

package/utils/spec/specValidate.d.ts

@@ -0,0 +1,10 @@
+import { CatalogSchema } from '@box-kite/core';
+declare namespace SpecValidate {
+    /** A name a spec may set at all. */
+    function isSafeKey(key: string): boolean;
+    /** An object a spec could have written: `JSON.parse` produces these and nothing else. */
+    function isPlainObject(value: unknown): value is Record<string, unknown>;
+    /** Whether a value is one this schema allows. The whole of it: an invalid part makes the value invalid. */
+    function matches(schema: CatalogSchema, value: unknown, root?: CatalogSchema): boolean;
+}
+export default SpecValidate;