uidl-runtime 0.1.0

package/dist/components/primitives.d.ts

@@ -0,0 +1,411 @@
+import { default as React, ReactNode, HTMLAttributes, ButtonHTMLAttributes, ChangeEvent } from 'react';
+import { CellFormat } from '../utils/listCell';
+export interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function Container({ children, ...props }: ContainerProps): React.JSX.Element;
+export interface RowProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function Row({ children, ...props }: RowProps): React.JSX.Element;
+export interface ColumnProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function Column({ children, ...props }: ColumnProps): React.JSX.Element;
+export interface StackProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function Stack({ children, ...props }: StackProps): React.JSX.Element;
+export type SpacerProps = HTMLAttributes<HTMLDivElement>;
+export declare function Spacer(props: SpacerProps): React.JSX.Element;
+export type DividerProps = HTMLAttributes<HTMLHRElement>;
+/** Meridian separates every list row and dashboard section with a 1px gray-200 rule. */
+export declare function Divider({ children: _children, ...props }: DividerProps): React.JSX.Element;
+export interface TextProps extends HTMLAttributes<HTMLParagraphElement> {
+    value?: string;
+    /**
+     * Render as `<h1>`…`<h6>` instead of `<p>`. Meridian's page and form titles are real headings
+     * (PageHeader's `<h1>`, FormHeader's `<h1>`, Sidebar's `<h6>`), and a document
+     * that titles a page needs the same landmark rather than a styled paragraph.
+     */
+    heading?: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Print a bound numeric/date value the way a list cell would. A list's summary figures are
+     * the same money as the column they total, so they have to read the same way — an aggregate
+     * bound straight into a Text otherwise renders the raw `1500000`.
+     */
+    format?: CellFormat;
+    /** BCP 47 tag used when `format` is set. */
+    locale?: string;
+    /** ISO 4217 code used when `format` is `currency`. */
+    currency?: string;
+}
+export declare function Text({ value, heading, format, locale, currency, ...props }: TextProps): React.JSX.Element;
+export interface ImageProps extends HTMLAttributes<HTMLImageElement> {
+    src?: string;
+    alt?: string;
+}
+export declare function Image({ src, alt, children: _children, ...props }: ImageProps): React.JSX.Element;
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    label?: string;
+    /** Meridian's `type` prop, renamed to avoid colliding with the DOM `type` attribute. */
+    variant?: "primary" | "secondary";
+    /** Icon-only buttons get the narrower `px-3` instead of `px-6`. */
+    icon?: boolean;
+    /**
+     * Name of an outline icon (see `ICON_NAMES`) drawn beside the label — Meridian's Button
+     * keeps an icon slot ahead of its default slot for exactly this.
+     */
+    iconName?: string;
+    /** Which side of the label the icon sits on. */
+    iconPosition?: "start" | "end";
+    /** Drop the filled background (and the fixed `h-8`) for a bare text button. */
+    background?: boolean;
+    /** Drop horizontal padding entirely. */
+    padding?: boolean;
+}
+/** Button */
+export declare function Button({ label, children, variant, icon, iconName, iconPosition, background, padding, ...props }: ButtonProps): React.JSX.Element;
+/**
+ * Meridian's status colors — `getBgTextColorClass` in src/utils/colors.ts is
+ * `bg-{color}-200 dark:bg-{color}-800` + `text-{color}-700 dark:text-{color}-200`. Written
+ * out per color rather than interpolated, because a class assembled at runtime is invisible
+ * to Tailwind's scanner (the same reason src/style.css exists at all).
+ */
+export type BadgeColor = "gray" | "orange" | "green" | "red" | "yellow" | "blue" | "indigo" | "pink" | "purple" | "teal";
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    children?: ReactNode;
+    /** One of Meridian's status colors (src/utils/colors.ts). Anything else falls back to gray. */
+    color?: string;
+    /**
+     * `badge` is Meridian's Badge (`px-2 py-1`); `pill` is its StatusPill / `.pill`
+     * utility (`py-0.5 px-1.5`, `text-xs`, `font-medium`) used for document statuses.
+     */
+    variant?: "badge" | "pill";
+    label?: string;
+    /** Optional leading outline icon — used for statuses that read better with a mark ("Balanced"). */
+    iconName?: string;
+}
+/** {Badge,StatusPill} */
+export declare function Badge({ children, color, variant, label, iconName, ...props }: BadgeProps): React.JSX.Element;
+export interface TextFieldProps extends HTMLAttributes<HTMLInputElement> {
+    label?: string;
+    value?: string;
+    error?: string;
+    /** Meridian's Base sizes: `small` = px-2 py-1 (form rows), `large` = px-3 py-2. */
+    size?: "small" | "large";
+    /** Meridian draws the box only where the field isn't already inside a bordered form row. */
+    border?: boolean;
+    placeholder?: string;
+    readOnly?: boolean;
+}
+/** Controls/{Base,Data} */
+export declare function TextField({ label, value, error, children: _children, id, size, border, ...props }: TextFieldProps): React.JSX.Element;
+export interface CheckboxProps extends HTMLAttributes<HTMLInputElement> {
+    label?: string;
+    checked?: boolean;
+}
+/**
+ * Controls/Check — a 14px box with Meridian's #A1ABB4
+ * stroke. Meridian hand-draws the SVG; a native input keeps it keyboard- and
+ * screen-reader-operable, with `accent-color` set inline so no arbitrary Tailwind class
+ * (which would need safelisting) is involved.
+ */
+export declare function Checkbox({ label, checked, children: _children, ...props }: CheckboxProps): React.JSX.Element;
+export interface SwitchProps extends HTMLAttributes<HTMLDivElement> {
+    checked?: boolean;
+}
+/** Meridian has no switch control; this follows its blue-500 accent and 4px-radius language. */
+export declare function Switch({ checked, ...props }: SwitchProps): React.JSX.Element;
+export interface SliderProps extends HTMLAttributes<HTMLInputElement> {
+    value?: number;
+    min?: number;
+    max?: number;
+}
+export declare function Slider({ value, min, max, children: _children, ...props }: SliderProps): React.JSX.Element;
+export interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface SelectProps extends HTMLAttributes<HTMLSelectElement> {
+    label?: string;
+    value?: string;
+    placeholder?: string;
+    options?: SelectOption[];
+    error?: string;
+    size?: "small" | "large";
+    border?: boolean;
+    /** Key holding an option's stored value. A lookup binds rows keyed by the target's own id. */
+    optionValueKey?: string;
+    /** Key holding an option's visible text. */
+    optionLabelKey?: string;
+}
+/** Controls/Select */
+export declare function Select({ optionValueKey, optionLabelKey, label, value, placeholder, options, error, children: _children, id, size, border, ...props }: SelectProps): React.JSX.Element;
+export interface TextareaProps extends HTMLAttributes<HTMLTextAreaElement> {
+    label?: string;
+    value?: string;
+    rows?: number;
+    error?: string;
+    size?: "small" | "large";
+    border?: boolean;
+    placeholder?: string;
+}
+/** Controls/Text */
+export declare function Textarea({ label, value, rows, error, children: _children, id, size, border, ...props }: TextareaProps): React.JSX.Element;
+export interface RadioOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface RadioGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    label?: string;
+    name?: string;
+    value?: string;
+    options?: RadioOption[];
+    error?: string;
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+export declare function RadioGroup({ label, name, value, options, error, onChange, children: _children, ...props }: RadioGroupProps): React.JSX.Element;
+export interface FormProps extends HTMLAttributes<HTMLFormElement> {
+    children?: ReactNode;
+}
+export declare function Form({ children, onSubmit, ...props }: FormProps): React.JSX.Element;
+export interface ListViewProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function ListView({ children, ...props }: ListViewProps): React.JSX.Element;
+export interface GridViewProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function GridView({ children, ...props }: GridViewProps): React.JSX.Element;
+export interface DataTableColumn {
+    key: string;
+    label: string;
+    align?: "left" | "center" | "right";
+    /**
+     * ListCell's its column format rule — how this column's raw value is printed.
+     * `status` renders StatusPill's coloured pill instead of text. Numeric formats are
+     * right-aligned unless `align` says otherwise, matching Meridian's `isNumeric` rule.
+     */
+    format?: CellFormat;
+}
+export interface DataTableAction {
+    label: string;
+    event?: string;
+}
+export interface DataTableProps extends HTMLAttributes<HTMLDivElement> {
+    title?: string;
+    dataSource?: string;
+    columns?: DataTableColumn[];
+    rows?: Array<Record<string, unknown>>;
+    rowActions?: DataTableAction[];
+    emptyMessage?: string;
+    /** Meridian numbers every list row in a narrow leading column. */
+    showIndex?: boolean;
+    /** Meridian's Paginator: page sizes [50, 100, 500, All], first one active. */
+    paginate?: boolean;
+    pageSizes?: number[];
+    /**
+     * Fired when a row action button is clicked, with the full row data and which action was
+     * clicked (matched by `DataTableAction.event`, the JSON `events` key it maps to — wired by
+     * RenderNode.tsx's `resolveEvents`). Not fired for actions with no `event` set.
+     */
+    onRowAction?: (row: Record<string, unknown>, action: DataTableAction, index: number) => void;
+    /**
+     * Meridian's List makes the whole row the affordance and has no action
+     * column at all. Supplying this turns rows into buttons; `rowActions` stays for callers that
+     * genuinely need per-row verbs.
+     */
+    onRowOpen?: (row: Record<string, unknown>, index: number) => void;
+    /** BCP 47 tag used to format date and numeric cells. */
+    locale?: string;
+    /** ISO 4217 code used to format `currency` columns. */
+    currency?: string;
+}
+/**
+ * {List,ListCell} + components/Row.
+ *
+ * Meridian's list is not a `<table>` and not a card: it is a stack of CSS-grid rows on the page
+ * background, each `h-row-mid` (3rem) tall, separated by 1px `hr`s, with a 1rem grid gap and
+ * a `w-8` index gutter. Nothing is boxed, nothing is shadowed, and the only fill in the whole
+ * control is `hover:bg-gray-50` on a row. That flatness is the single biggest difference from
+ * a conventional bordered data table, so it is reproduced structurally here rather than
+ * approximated with table styling.
+ */
+export declare function DataTable({ title, dataSource: _dataSource, columns, rows, rowActions, emptyMessage, showIndex, paginate, pageSizes, onRowAction, onRowOpen, locale, currency, ...props }: DataTableProps): React.JSX.Element;
+export interface PageBarProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Rows in the whole result, not just the loaded page — a server total. */
+    total?: number;
+    page?: number;
+    pageSize?: number;
+    pageSizes?: number[];
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (size: number) => void;
+}
+/**
+ * Paginator as a document-addressable widget, for lists whose paging happens on the
+ * server. DataTable's built-in paginator slices the rows it was handed, which is the wrong
+ * answer when the query already returned exactly one page: it would report "1 - 1 / 1" no
+ * matter how many records exist. This one is told the real total and reports the state the
+ * document holds, so a generated list can page for real instead of carrying the fixed
+ * "Displaying records" caption and Previous/Next buttons that jumped to pages 1 and 2.
+ *
+ * The arithmetic (page count, clamping, the visible range) lives here because the JSON
+ * expression language has no arithmetic — and should not grow any just to count pages.
+ */
+export declare function PageBar({ total, page, pageSize, pageSizes, onPageChange, onPageSizeChange, ...props }: PageBarProps): React.JSX.Element;
+export interface ChartSeries {
+    key: string;
+    label?: string;
+    color?: string;
+}
+export interface ChartProps extends HTMLAttributes<HTMLDivElement> {
+    title?: string;
+    dataSource?: string;
+    chartType?: "bar" | "line" | "donut" | "area";
+    rows?: Array<Record<string, unknown>>;
+    xKey?: string;
+    yKey?: string;
+    series?: ChartSeries[];
+    emptyMessage?: string;
+    /** Meridian's dashboard sections pair the title with a period/filter control on the end edge. */
+    action?: ReactNode;
+    /** Donut only — the label inside the hole (Meridian: "Total Spending"). */
+    totalLabel?: string;
+    /**
+     * Drawn height in px for bar/line charts. Meridian's dashboard charts all land near 235px
+     * regardless of column width, because each call site picks an aspect ratio to make that
+     * true; here the ratio is derived from the measured width and this height instead.
+     */
+    height?: number;
+}
+/**
+ * {Cashflow,ProfitAndLoss,Expenses}.
+ *
+ * A Meridian dashboard widget is a `p-4` region on the page — no card, no border of its own
+ * (the neighbouring section supplies a `border-e`/`hr`) — made of `SectionHeader`
+ * (`flex items-baseline justify-between`, `font-semibold text-base`), an optional inline
+ * legend, and the SVG chart. Donuts sit beside their legend at half width each, which is how
+ * Top Expenses is laid out.
+ */
+export declare function Chart({ title, dataSource: _dataSource, chartType, rows, xKey, yKey, series, emptyMessage, action, totalLabel, height, ...props }: ChartProps): React.JSX.Element;
+export interface KanbanColumn {
+    id: string;
+    title: string;
+    color?: string;
+}
+export interface KanbanCardItem {
+    id: string;
+    columnId: string;
+    title: string;
+    subtitle?: string;
+    value?: string | number;
+    badge?: string;
+    route?: string;
+    meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface KanbanBoardProps extends HTMLAttributes<HTMLDivElement> {
+    title?: string;
+    dataSource?: string;
+    columns?: KanbanColumn[];
+    rows?: KanbanCardItem[];
+    emptyMessage?: string;
+    onCardClick?: (card: KanbanCardItem) => void;
+}
+export declare function KanbanBoard({ title, dataSource: _dataSource, columns, rows, emptyMessage, onCardClick, ...props }: KanbanBoardProps): React.JSX.Element;
+export interface TreeNodeItem {
+    id: string;
+    label: string;
+    value?: string | number;
+    badge?: string;
+    subtitle?: string;
+    defaultExpanded?: boolean;
+    children?: TreeNodeItem[];
+    route?: string;
+    [key: string]: unknown;
+}
+export interface TreeViewProps extends HTMLAttributes<HTMLDivElement> {
+    title?: string;
+    dataSource?: string;
+    items?: TreeNodeItem[];
+    rows?: TreeNodeItem[];
+    emptyMessage?: string;
+    onNodeClick?: (node: TreeNodeItem) => void;
+}
+export declare function TreeView({ title, dataSource: _dataSource, items, rows, emptyMessage, onNodeClick, ...props }: TreeViewProps): React.JSX.Element;
+export interface SidebarProps extends HTMLAttributes<HTMLElement> {
+    children?: ReactNode;
+}
+/** Sidebar — 14rem wide, gray-25, 0.5rem vertical inset. */
+export declare function Sidebar({ children, ...props }: SidebarProps): React.JSX.Element;
+export interface NavbarProps extends HTMLAttributes<HTMLElement> {
+    children?: ReactNode;
+}
+/**
+ * PageHeader — the 4rem (`h-row-largest`) page header:
+ * `px-4`, title and left slot on the start edge with `gap-4`, actions on the end edge with
+ * `gap-2`, one hairline rule underneath.
+ */
+export declare function Navbar({ children, ...props }: NavbarProps): React.JSX.Element;
+export interface ToolbarProps extends HTMLAttributes<HTMLDivElement> {
+    children?: ReactNode;
+}
+export declare function Toolbar({ children, ...props }: ToolbarProps): React.JSX.Element;
+export interface DrawerProps extends HTMLAttributes<HTMLDivElement> {
+    open?: boolean;
+    onClose?: () => void;
+    title?: string;
+    /** Which screen edge the drawer slides from. Defaults to "right". */
+    side?: "left" | "right" | "top" | "bottom";
+    /** Show the dimming backdrop (click-to-close). Defaults to true. */
+    backdrop?: boolean;
+    children?: ReactNode;
+}
+export declare function Drawer({ open, onClose, title, side, backdrop, children, ...props }: DrawerProps): React.JSX.Element | null;
+export interface PanelProps extends HTMLAttributes<HTMLDivElement> {
+    open?: boolean;
+    onClose?: () => void;
+    /** Show the dimming backdrop (click-to-close). Defaults to true. */
+    backdrop?: boolean;
+    children?: ReactNode;
+}
+export declare function Panel({ open, onClose, backdrop, children, ...props }: PanelProps): React.JSX.Element | null;
+export interface PopoverProps extends HTMLAttributes<HTMLDivElement> {
+    open?: boolean;
+    onClose?: () => void;
+    /** Which edge the panel hangs from. Meridian's FilterDropdown is `bottom-end`. */
+    align?: "start" | "end";
+    children?: ReactNode;
+}
+/**
+ * Popover, as Meridian actually uses it: a panel anchored to
+ * the control that opened it, not a centred modal.
+ *
+ * Deliberately *not* portalled. Meridian wraps trigger and panel in one `relative` element and
+ * positions the panel absolutely inside it (ListView's FilterDropdown, the Create dropdown),
+ * which needs no anchor math and keeps the panel inside the same stacking and shadow-root
+ * context as its trigger. A document places this node next to its trigger inside a container
+ * styled `position: relative`.
+ *
+ * Escape and click-outside close it through the same overlay stack the Drawer and Panel use, so
+ * a popover opened above a drawer still closes in the right order.
+ */
+export declare function Popover({ open, onClose, align, children, ...props }: PopoverProps): React.JSX.Element | null;
+export interface SnackbarProps extends HTMLAttributes<HTMLDivElement> {
+    message?: string;
+    duration?: number;
+    onClose?: () => void;
+    /** Leading outline icon. Toasts read as confirmations, so a check is the default. */
+    iconName?: string;
+}
+export declare function Snackbar({ message, duration, onClose, iconName, ...props }: SnackbarProps): React.JSX.Element | null;
+export interface DialogProps extends Omit<HTMLAttributes<HTMLDivElement>, "content"> {
+    title?: string;
+    content?: ReactNode;
+    open?: boolean;
+    onClose?: () => void;
+}
+export declare function Dialog({ title, content, open, onClose, ...props }: DialogProps): React.JSX.Element | null;

package/dist/data/adapters/http.d.ts

@@ -0,0 +1,37 @@
+import { DataAdapter, Mutation, Query, QueryResult, RecordMeta } from '../types';
+export interface HttpAdapterOptions {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+    headers?: HeadersInit;
+    timeoutMs?: number;
+}
+export declare class HttpAdapter implements DataAdapter {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly headers?;
+    private readonly timeoutMs;
+    constructor(options: HttpAdapterOptions);
+    query<T = Record<string, unknown>>(query: Query, signal?: AbortSignal): Promise<QueryResult<T>>;
+    get<T = Record<string, unknown>>(collection: string, id: string, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    } | undefined>;
+    create<T = Record<string, unknown>>(mutation: Mutation, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    update<T = Record<string, unknown>>(mutation: Mutation, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    remove(collection: string, id: string, signal?: AbortSignal): Promise<void>;
+    transition<T = Record<string, unknown>>(mutation: Mutation & {
+        transition: string;
+    }, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    report<T = unknown>(name: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    private request;
+}
+export declare function createHttpAdapter(options: HttpAdapterOptions): HttpAdapter;

package/dist/data/adapters/inMemory.d.ts

@@ -0,0 +1,62 @@
+import { DataAdapter, Mutation, Query, QueryResult, RecordMeta } from '../types';
+export interface InMemoryAdapterOptions {
+    /** Initial collections, e.g. `{ SalesInvoice: [...] }`. Copied on construction — the caller's
+     *  array is never mutated. */
+    seed?: Record<string, Array<Record<string, unknown>>>;
+    /** `"localStorage"` persists every mutation and reloads it on construction; `"none"` (default
+     *  in tests) keeps everything in memory only. */
+    persist?: "localStorage" | "none";
+    /** Key the store is saved under when `persist: "localStorage"`. */
+    storageKey?: string;
+    /** Artificial delay applied to every call, so loading/skeleton states are actually exercised
+     *  in mock mode instead of resolving instantly. Default 0. */
+    latencyMs?: number;
+    /** Fraction (0–1) of calls that fail with a synthetic `DataError("server")`, so error states
+     *  are exercised in mock mode too. Default 0. */
+    failureRate?: number;
+    /** Injectable clock/random for deterministic tests. */
+    now?: () => number;
+    random?: () => number;
+}
+/** In-memory `DataAdapter`. Default for demos and tests; every failure it raises is a real
+ *  `DataError` with the same `.code` an `HttpAdapter` would raise for the same situation — see
+ *  `src/data/__tests__/contract.test.ts` for the shared case matrix that keeps the two honest. */
+export declare class InMemoryAdapter implements DataAdapter {
+    private stores;
+    private readonly persist;
+    private readonly storageKey;
+    private readonly latencyMs;
+    private readonly failureRate;
+    private readonly now;
+    private readonly random;
+    constructor(options?: InMemoryAdapterOptions);
+    private simulate;
+    private collection;
+    query<T = Record<string, unknown>>(query: Query, signal?: AbortSignal): Promise<QueryResult<T>>;
+    get<T = Record<string, unknown>>(collection: string, id: string, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    } | undefined>;
+    create<T = Record<string, unknown>>(mutation: Mutation, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    update<T = Record<string, unknown>>(mutation: Mutation, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    remove(collection: string, id: string, signal?: AbortSignal): Promise<void>;
+    transition<T = Record<string, unknown>>(mutation: Mutation & {
+        transition: string;
+    }, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    report<T = unknown>(_name: string, _params: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    /** Test/demo-only escape hatch: reseed everything from scratch. Not part of `DataAdapter`. */
+    reset(seed?: Record<string, Array<Record<string, unknown>>>): void;
+    private generateId;
+    private saveToStorage;
+    private loadFromStorage;
+}
+export declare function createInMemoryAdapter(options?: InMemoryAdapterOptions): InMemoryAdapter;

package/dist/data/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A single failure shape both `InMemoryAdapter` and `HttpAdapter` are required to raise for the
+ * same situation (record missing, bad input, stale version, no permission, network/timeout, or
+ * server fault). A document/host that branches on `.code` behaves identically no matter which
+ * adapter is wired in — that's the whole point of the seam: switching mock → HTTP must not
+ * surface a failure mode the UI has never seen.
+ */
+export type DataErrorCode = "not_found" | "validation" | "conflict" | "forbidden" | "network" | "timeout" | "server";
+export declare class DataError extends Error {
+    readonly code: DataErrorCode;
+    /** Per-field messages, e.g. from server-side validation — maps directly to `state.formErrors.*`. */
+    readonly fields?: Record<string, string>;
+    constructor(message: string, code: DataErrorCode, fields?: Record<string, string>);
+}
+export declare function isDataError(value: unknown): value is DataError;

package/dist/data/index.d.ts

@@ -0,0 +1,7 @@
+export type { DataAdapter, Mutation, Query, QueryFilter, QueryOp, QueryPage, QueryResult, QuerySort, RecordMeta, } from './types';
+export { DataError, isDataError } from './errors';
+export type { DataErrorCode } from './errors';
+export { InMemoryAdapter, createInMemoryAdapter } from './adapters/inMemory';
+export type { InMemoryAdapterOptions } from './adapters/inMemory';
+export { HttpAdapter, createHttpAdapter } from './adapters/http';
+export type { HttpAdapterOptions } from './adapters/http';

package/dist/data/testing/mockHttpServer.d.ts

@@ -0,0 +1,16 @@
+import { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { DataAdapter } from '../types';
+export interface MockHttpServerOptions {
+    adapter?: DataAdapter;
+    seed?: Record<string, Array<Record<string, unknown>>>;
+    host?: string;
+    port?: number;
+    basePath?: string;
+}
+export interface RunningMockHttpServer {
+    server: Server;
+    url: string;
+    close: () => Promise<void>;
+}
+export declare function createDataAdapterHttpHandler(adapter: DataAdapter, basePath?: string): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare function startMockHttpServer(options?: MockHttpServerOptions): Promise<RunningMockHttpServer>;

package/dist/data/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The data contract every demo/document talks to instead of a specific storage. Two
+ * implementations exist — `InMemoryAdapter` (default, mock) and `HttpAdapter` (real backend) —
+ * and a shared contract test (`__tests__/contract.test.ts`) runs the same case matrix against
+ * both, so switching the adapter a host wires up is the only thing that changes.
+ */
+export type QueryOp = "eq" | "ne" | "in" | "gt" | "gte" | "lt" | "lte" | "like" | "between";
+export interface QueryFilter {
+    field: string;
+    op: QueryOp;
+    /** `in`/`between` take an array; every other op takes a scalar. */
+    value: unknown;
+}
+export interface QuerySort {
+    field: string;
+    dir: "asc" | "desc";
+}
+export interface QueryPage {
+    number: number;
+    size: number;
+}
+export interface Query {
+    collection: string;
+    filters?: QueryFilter[];
+    sort?: QuerySort[];
+    page?: QueryPage;
+    /** Free-text search across whatever fields the collection marks searchable. */
+    search?: string;
+    /** Column projection; omitted = every field. */
+    fields?: string[];
+}
+export interface QueryResult<T = Record<string, unknown>> {
+    rows: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface Mutation {
+    collection: string;
+    id?: string;
+    data?: Record<string, unknown>;
+    /** State-machine transition name, e.g. "submit" | "cancel" | "pay". */
+    transition?: string;
+    /** Optimistic-concurrency token: the version the client last read. */
+    version?: number;
+}
+export interface RecordMeta {
+    version: number;
+}
+export interface DataAdapter {
+    query<T = Record<string, unknown>>(query: Query, signal?: AbortSignal): Promise<QueryResult<T>>;
+    get<T = Record<string, unknown>>(collection: string, id: string, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    } | undefined>;
+    create<T = Record<string, unknown>>(mutation: Mutation, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    update<T = Record<string, unknown>>(mutation: Mutation, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    remove(collection: string, id: string, signal?: AbortSignal): Promise<void>;
+    transition<T = Record<string, unknown>>(mutation: Mutation & {
+        transition: string;
+    }, signal?: AbortSignal): Promise<{
+        record: T;
+        meta: RecordMeta;
+    }>;
+    report<T = unknown>(name: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+}
+export { DataError, isDataError } from './errors';
+export type { DataErrorCode } from './errors';

package/dist/editor/Canvas.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { UIDLDocument } from '../types';
+import { ApiAllowlist } from '../actions/interpreter';
+import { DocumentStateStore } from '../state/createDocumentState';
+import { CommandHandler, MutationHandler } from '../types/actions';
+export interface CanvasProps {
+    document: UIDLDocument;
+    selectedNodeId: string | null;
+    hoveredNodeId: string | null;
+    onSelectNode: (nodeId: string | null) => void;
+    onHoverNode: (nodeId: string | null) => void;
+    themeMode?: "light" | "dark";
+    stateStore?: DocumentStateStore;
+    dataSources?: Record<string, unknown>;
+    mutationHandler?: MutationHandler;
+    commandHandler?: CommandHandler;
+    apiAllowlist?: ApiAllowlist;
+    apiMaxResponseBytes?: number;
+    apiMaxConcurrentCalls?: number;
+    className?: string;
+}
+export declare function Canvas({ document, onSelectNode, onHoverNode, themeMode, stateStore, dataSources, mutationHandler, commandHandler, apiAllowlist, apiMaxResponseBytes, apiMaxConcurrentCalls, className, }: CanvasProps): React.JSX.Element;

package/dist/editor/Editor.d.ts

@@ -0,0 +1,18 @@
+import { UIDLDocument } from '../types';
+import { ApiAllowlist } from '../actions/interpreter';
+import { CommandHandler, MutationHandler } from '../types/actions';
+export interface EditorProps {
+    initialDocument?: UIDLDocument;
+    /** Host-owned handler for live-preview `mutate` actions; unset means mutations are disabled. */
+    mutationHandler?: MutationHandler;
+    /** Host-owned handler for live-preview `command` actions; unset means commands are disabled. */
+    commandHandler?: CommandHandler;
+    /** Hosts the live preview's `api` actions are allowed to call; unset means they're disabled. */
+    apiAllowlist?: ApiAllowlist;
+    /** Max `api` response body size in bytes before the request is aborted. Default 5MB. */
+    apiMaxResponseBytes?: number;
+    /** Max number of `api` actions to run concurrently; further calls fail fast. Default 6. */
+    apiMaxConcurrentCalls?: number;
+    className?: string;
+}
+export declare function Editor({ initialDocument, mutationHandler, commandHandler, apiAllowlist, apiMaxResponseBytes, apiMaxConcurrentCalls, className, }: EditorProps): import("react").JSX.Element;