@magicvr/schema-ui-renderer 0.3.0 → 0.3.2

package/renderer/render.types.d.ts

@@ -1,289 +0,0 @@
-import { type FormControlField, type FormControlGateError } from "@schema-ui/renderer/renderer/form-controls.types";
-import { type FormControlStateMap, type ReactionError } from "@schema-ui/renderer/renderer/reactions";
-/**
- * D-COMP page renderer (frozen §5 whitelist + I-PROTO-FULL-001 full registry
- * surface; resolve R4 F-002).
- *
- * The renderer walks a page document's node tree and dispatches whitelisted
- * node types to the components in this directory. It is deliberately minimal:
- * only the node types surfaced by the example pages are handled, and any
- * other type fails closed instead of rendering a silent fallback.
- *
- * A page document looks like the example pages' `PAGE_DOCUMENT`:
- *   { meta: { protocolVersion, requiredCapabilities }, body: Node }
- *
- * Node types supported (registry surface):
- *   - layout:  grid / section / tabs
- *   - data/action: text / table / recordView / actionButton / statCard / chart
- *   - form:    form → FormControls (with reactions applied to field state)
- * The form control whitelist itself is enforced by D-FORM
- * (isWhitelistedFormControl / checkFormCapabilities).
- */
-export type RenderNodeType = "form" | "section" | "table" | "grid" | "tabs" | "text" | "recordView" | "actionButton" | "statCard" | "chart" | "custom";
-export interface RenderMeta {
-    protocolVersion: string;
-    requiredCapabilities: string[];
-}
-export interface ReactionState {
-    /** fieldId → control state after reactions. */
-    state: FormControlStateMap;
-    errors: ReactionError[];
-}
-export interface RenderFormNode {
-    type: "form";
-    id?: string;
-    props: {
-        fields: Array<Record<string, unknown>>;
-        reactions?: unknown;
-        submitLabel?: string;
-        /** S2 (VP-007): i18n key resolved before `submitLabel` (local doc convention). */
-        submitLabelKey?: string;
-        /** Default-mode submit: the top-level action id to run on submit (S4). */
-        submitAction?: string;
-        /** Search-mode form: binds its fields to the target table's query (S4). */
-        mode?: "default" | "search";
-        targetTable?: string;
-        /** Section heading rendered above the fields (registry form `title`/`titleKey`). */
-        title?: string;
-        /** i18n key resolved before `title`. */
-        titleKey?: string;
-        /**
-         * ADR-0021 edit-form record GET prefill (registry since 2.1): loads current
-         * values from a detail GET and initializes the fields via `responseMapping`
-         * (field id → dot-path in the response). Requires capability
-         * `form.record.load`; search-mode forms forbid it.
-         */
-        recordSource?: Record<string, unknown>;
-        /** GOAL-014 D-002 §4: responsive form column count (>1 enables the grid). */
-        columns?: number;
-    };
-    children?: RenderNode[];
-}
-export interface RenderSectionNode {
-    type: "section";
-    id?: string;
-    props?: Record<string, unknown>;
-    children: RenderNode[];
-}
-export interface RenderGridNode {
-    type: "grid";
-    id?: string;
-    props?: Record<string, unknown>;
-    children?: RenderNode[];
-}
-export interface RenderTabsNode {
-    type: "tabs";
-    id?: string;
-    props?: Record<string, unknown>;
-    children?: RenderNode[];
-}
-export interface RenderTextNode {
-    type: "text";
-    id?: string;
-    props?: {
-        text?: string;
-        /** i18n key resolved before `text` (F-01 · GOAL-003 A-003 F-001). */
-        textKey?: string;
-    };
-    children?: RenderNode[];
-}
-/**
- * v2.9 DataRef subset consumed by data nodes (ADR-0039): source:api url +
- * params (literal scalars or whole $context.route.query.* / params.* bindings).
- */
-export interface RenderDataRef {
-    url: string;
-    params?: Record<string, unknown>;
-}
-export interface RenderTableNode {
-    type: "table";
-    id?: string;
-    /** v2.9 node-level DataRef (source:api). Preferred over props.dataSource. */
-    data?: RenderDataRef;
-    props: {
-        columns?: Array<Record<string, unknown>>;
-        actions?: Array<Record<string, unknown>>;
-        toolbar?: Array<Record<string, unknown>>;
-        dataSource?: string;
-        /** Table heading (literal fallback for titleKey). */
-        title?: string;
-        /** i18n key resolved before title. */
-        titleKey?: string;
-        /** Direct field name of each row's unique key (F-002 · I-010-001 v0.2.0 §3; default "id"). */
-        rowKey?: string;
-        /** ADR-0022 multi-select model (registry; mode: multiple only). */
-        selection?: {
-            mode?: string;
-        };
-        /** Schema-driven filters (select-only; see schemaTableFilters). */
-        filters?: Array<Record<string, unknown>>;
-    };
-    children?: RenderNode[];
-}
-/** Read-only field row on a recordView (registry `fields[]` since 2.4). */
-export interface RenderRecordViewField {
-    key: string;
-    label?: string;
-    labelKey?: string;
-}
-export interface RenderRecordViewNode {
-    type: "recordView";
-    id?: string;
-    props?: {
-        record?: Record<string, unknown>;
-        /** Detail panel heading (registry `title` since 2.4). */
-        title?: string;
-        /** i18n key resolved before `title`. */
-        titleKey?: string;
-        /** Declared display fields; when set, only these rows render. */
-        fields?: RenderRecordViewField[];
-    };
-    children?: RenderNode[];
-}
-export interface RenderActionButtonNode {
-    type: "actionButton";
-    id?: string;
-    props?: {
-        label?: string;
-        /** i18n key resolved before `label` (S3). */
-        labelKey?: string;
-        actionId?: string;
-        visibleWhen?: unknown;
-        disabledWhen?: unknown;
-        /** Permission-intent key (ADR-0023 D4b mount); gates the button target. */
-        permissionIntent?: string;
-        /** Target id for the permission target / action gate (falls back to node id). */
-        key?: string;
-        /** Confirm message (shown before executing the referenced action). */
-        confirm?: string;
-        /** i18n key resolved before `confirm`. */
-        confirmKey?: string;
-    };
-    children?: RenderNode[];
-}
-export interface RenderStatCardNode {
-    type: "statCard";
-    id?: string;
-    /** v2.9 node-level DataRef (source:api). Preferred over props.dataSource. */
-    data?: RenderDataRef;
-    props?: {
-        label?: string;
-        /** i18n key resolved before `label` (F-01 · GOAL-003 A-003 F-001). */
-        labelKey?: string;
-        unit?: string;
-        /** plain | currency | percent (registry enum). */
-        format?: string;
-        /** Field of the dataSource rows to display (registry, required since 0.2). */
-        valueField?: string;
-        /** Single-slash same-origin data path (same invariant as table.dataSource). */
-        dataSource?: string;
-    };
-    children?: RenderNode[];
-}
-export interface RenderChartNode {
-    type: "chart";
-    id?: string;
-    /** v2.9 node-level DataRef (source:api). Preferred over props.dataSource. */
-    data?: RenderDataRef;
-    props?: {
-        /** line | bar | pie (registry enum, required). */
-        chartType?: string;
-        xField?: string;
-        yField?: string;
-        /** Single-slash same-origin data path (same invariant as table.dataSource). */
-        dataSource?: string;
-    };
-    children?: RenderNode[];
-}
-export interface RenderCustomNode {
-    type: "custom";
-    id?: string;
-    /** Registered component key (GOAL-018: renderer custom-component registry). */
-    component: string;
-    props?: Record<string, unknown>;
-    children?: RenderNode[];
-}
-export type RenderNode = RenderFormNode | RenderSectionNode | RenderGridNode | RenderTabsNode | RenderTextNode | RenderTableNode | RenderRecordViewNode | RenderActionButtonNode | RenderStatCardNode | RenderChartNode | RenderCustomNode;
-/** Page-level action table entry (registry: modal | request | navigate). */
-export interface RenderPageAction {
-    type: string;
-    /** Modal content; required when type=modal. */
-    content?: RenderNode;
-    /** Request/navigate target URL. */
-    url?: string;
-    /** HTTP method for request-shaped actions. */
-    method?: string;
-    /** Permission intent name, gated against page-level permissionCascade. */
-    permissionIntent?: string;
-}
-export interface RenderPageDocument {
-    meta: RenderMeta;
-    body: RenderNode;
-    /** Page-level action table referenced by actionRef / actionId. */
-    actions?: Record<string, RenderPageAction>;
-}
-export type RenderErrorCode = "RENDER_UNKNOWN_NODE_TYPE" | "RENDER_INVALID_BODY" | "RENDER_META_INVALID" | "RENDER_FORM_FIELD_INVALID";
-export interface RenderError {
-    code: RenderErrorCode;
-    path: string;
-    message: string;
-}
-export type ActionGateErrorCode = "ACTION_GATE_EXPRESSION_INVALID";
-export interface ActionGateError {
-    code: ActionGateErrorCode;
-    path: string;
-    message: string;
-}
-export type ActionGateResult = {
-    kind: "ok";
-    value: boolean;
-} | {
-    kind: "error";
-    error: ActionGateError;
-};
-export interface RenderFormFieldGate {
-    /** Fields that passed the type whitelist and the version/capability gate. */
-    fields: FormControlField[];
-    /** Deterministic errors for rejected fields and gate failures. */
-    errors: FormControlGateError[];
-}
-/** Keeps only well-formed recordView field rows (key required). */
-export declare function parseRecordViewFields(raw: unknown): RenderRecordViewField[];
-export declare function isWhitelistedNodeType(type: string): type is RenderNodeType;
-/**
- * Resolves a dot-path on a record for `form.recordSource.responseMapping`
- * (e.g. `"customer.name"` → record.customer.name). Missing segments or a
- * non-object intermediate return `undefined` (field keeps its default/empty).
- */
-export declare function resolveResponsePath(record: unknown, path: string): unknown;
-/** Normalizes an unknown body value into a typed RenderNode, fail-closed. */
-export declare function parseRenderNode(value: unknown, path: string): RenderNode | RenderError;
-/** Collects all form fieldIds from a page document (for reaction resolution). */
-export declare function collectFieldIds(node: RenderNode, into?: string[]): string[];
-/** Resolves the reaction state for a form node's fields. */
-export declare function resolveFormReactions(form: RenderFormNode, context: Record<string, unknown>): ReactionState;
-/**
- * Resolves a table action gate expression.
- *
- * Distinguishes an absent property (→ `absentDefault`) from an explicit but
- * invalid expression (→ fail-closed `error`, no silent default). Valid $context
- * expressions are evaluated against the frozen engine; booleans pass through.
- */
-export declare function resolveActionGate(expression: unknown, context: Record<string, unknown>, absentDefault: boolean, path: string): ActionGateResult;
-/**
- * Evaluates a whitelisted table action's visibility/disabled gate.
- * Explicit invalid expressions fail closed (hidden / disabled) and are reported.
- */
-export declare function tableActionGate(action: Record<string, unknown>, context: Record<string, unknown>): {
-    visible: boolean;
-    disabled: boolean;
-    errors: ActionGateError[];
-};
-/**
- * Parses and gates a form node's raw fields against the D-FORM §5 whitelist
- * and the page meta version/capability rules (F-002 / F-003).
- *
- * Returns only the fields that pass every gate; rejected fields produce
- * deterministic errors instead of being silently rendered (or silently dropped).
- */
-export declare function gateRenderFormFields(metaValue: unknown, rawFields: unknown, path: string): RenderFormFieldGate;

package/renderer/resource.d.ts

@@ -1,114 +0,0 @@
-import type { SortOrder } from "@schema-ui/renderer/components/data-table";
-export declare const DEFAULT_PAGE_SIZE = 10;
-/**
- * Frozen list-endpoint rule (I-010-001 v0.2.0 · A-001 F-001): `table.props.dataSource`
- * must be a single-slash same-origin absolute path — starts with one `/`, no `//`
- * (no protocol-relative host), no scheme, no whitespace, backslash, `?` or `#`.
- * Query strings are appended by `buildResourceQuery`, never authored in dataSource;
- * fragments are never allowed. Validated before any (auth) fetch is attempted.
- * Mirrors `DataRef.url`'s `^/(?!/)[^\s\\]*$` but additionally rejects `?`/`#`.
- */
-export declare const DATASOURCE_URL_PATTERN: RegExp;
-/** A schema-driven resource row: any plain JSON object (no field whitelist). */
-export interface ResourceItem {
-    [key: string]: unknown;
-}
-/** Unified list envelope frozen across resources: `{items,total,page,pageSize}`. */
-export interface ResourceList {
-    items: ResourceItem[];
-    total: number;
-    page: number;
-    pageSize: number;
-}
-/** A generic resource list query. */
-export interface ResourceQuery {
-    q?: string;
-    sort?: string;
-    order?: SortOrder;
-    page?: number;
-    pageSize?: number;
-    /** Schema-driven table filters (table node props.filters): field to value. */
-    filters?: Record<string, string>;
-}
-/**
- * Shared query for display components (statCard/chart) that read the first
- * item + envelope of a list endpoint. The pageSize keeps the historical RPC
- * shape (one generous bucket); wallet-ensure uses the exact same query so its
- * existence probe coalesces with the statCards' request (per-page fetch cache).
- */
-export declare const DISPLAY_LIST_QUERY: ResourceQuery;
-/** One field-level validation failure (GOAL-014 D-002 §2.1). */
-export interface FieldError {
-    field: string;
-    reason: string;
-}
-/** A resource API failure carrying the frozen envelope `{error, message}`. */
-export declare class ResourceApiError extends Error {
-    readonly code: string;
-    readonly status: number;
-    /** VP-007 S4: stable catalog key when the server cataloged this error. */
-    readonly messageKey?: string;
-    /** VP-007 S4: interpolation params for messageKey. */
-    readonly params?: Record<string, unknown>;
-    /** GOAL-014: field-level validation failures, when the server attached them. */
-    readonly fieldErrors: FieldError[];
-    /** R1 correlation identifier for support/operator lookup. */
-    readonly correlationId?: string;
-    constructor(status: number, code: string, message: string, messageKey?: string, params?: Record<string, unknown>, fieldErrors?: FieldError[], correlationId?: string);
-}
-/** W19: missing self-wallet is an empty surface, not a hard page error. */
-export declare function isWalletNotFoundError(err: unknown): boolean;
-export declare const EMPTY_RESOURCE_LIST: ResourceList;
-export type ResourceCreateBody = ResourceItem;
-export type ResourcePatch = Partial<ResourceItem>;
-/** F-001: single executable rule for a table list endpoint (fail-closed on any violation). */
-export declare function isValidDataSource(url: string): boolean;
-/** Reads the frozen error envelope from a non-OK response. */
-export declare function readResourceApiError(response: Response, label: string): Promise<ResourceApiError>;
-/** Serializes a ResourceQuery into a URL query string (query-serialization). */
-/**
- * v2.9 dataSource params resolution (ADR-0039, capability data.route-binding).
- * Literal scalars pass through; whole `$context.route.query.*` /
- * `$context.route.params.*` bindings are resolved from the route snapshot;
- * a missing key (or absent route) is a tombstone — the parameter is dropped
- * (ADR-0010 semantics, same as null values). Returns the merged query string
- * (empty when nothing resolves).
- */
-export declare function resolveDataParamsQuery(params: Record<string, unknown> | undefined, route: {
-    query?: Record<string, string>;
-    params?: Record<string, string>;
-}): string;
-export declare function buildResourceQuery(query: ResourceQuery): string;
-/**
- * Maps an unknown list payload to the unified ResourceList envelope, fail-closed
- * on shape drift. Items are arbitrary JSON objects (F-002 rowKey is enforced at
- * the table surface, not here).
- */
-export declare function parseResourceList(value: unknown): ResourceList;
-/**
- * Builds the query-string portion of a resource list request — the exact
- * construction `fetchResourceList` sends on the wire. `extraQuery` carries
- * v2.9 ADR-0039 dataSource params that already resolved to literal key=value
- * pairs and is merged over the standard q/sort/order/page/pageSize query.
- */
-export declare function resourceListQueryString(query: ResourceQuery, extraQuery?: string): string;
-/**
- * The final URL for a resource list request (F-001-validated baseURL + query
- * string). Shared by `fetchResourceList` and the renderer's per-page fetch
- * cache so the cache key and the wire request can never drift apart.
- */
-export declare function resourceListURL(baseURL: string, query: ResourceQuery, extraQuery?: string): string;
-/**
- * Fetches a page of a schema-driven resource list (request-construction).
- *
- * `extraQuery` carries v2.9 ADR-0039 dataSource params that already resolved
- * to literal key=value pairs (e.g. `dictKey=order_status` from a
- * `$context.route.query.*` binding). It is merged with the standard
- * q/sort/order/page/pageSize query; baseURL itself must stay a bare
- * single-slash same-origin path (F-001).
- */
-export declare function fetchResourceList(fetcher: typeof fetch, baseURL: string, query: ResourceQuery, extraQuery?: string): Promise<ResourceList>;
-/** Creates a resource row via POST; returns the 201 row. */
-export declare function createResource(fetcher: typeof fetch, baseURL: string, body: ResourceCreateBody): Promise<ResourceItem>;
-export declare function updateResource(fetcher: typeof fetch, baseURL: string, id: string, patch: ResourcePatch): Promise<ResourceItem>;
-export declare function deleteResource(fetcher: typeof fetch, baseURL: string, id: string): Promise<void>;

package/renderer/row-action.d.ts

@@ -1,28 +0,0 @@
-import { type ExecutionResult } from "@schema-ui/renderer/renderer/permissions";
-import type { NavigationContext } from "@schema-ui/protocol/app-manifest";
-/**
- * R5 D-ACT non-batch row action execution (frozen Q1: batch excluded).
- *
- * Wraps the R4 executeAction engine so UI actions gate through the same
- * permission / confirm / disabled sequence as the frozen permission fixtures.
- * `page` is the R5 example page document; `targetId` is a table row action key.
- */
-export type RowActionOutcome = ExecutionResult["outcome"];
-export interface RowActionRequest {
-    page: Record<string, unknown>;
-    targetId: string;
-    context: NavigationContext;
-    /** Defaults to true; a hidden action fails closed as NOT_VISIBLE. */
-    visible?: boolean;
-    confirm?: boolean;
-    confirmed?: boolean;
-    disabled?: boolean;
-    requiresSelection?: boolean;
-}
-export interface RowActionResult {
-    outcome: RowActionOutcome;
-    reason?: ExecutionResult["reason"];
-    permissionDenied: boolean;
-    confirmed?: boolean;
-}
-export declare function runRowAction(request: RowActionRequest): RowActionResult;

package/renderer/schema-table.d.ts

@@ -1,90 +0,0 @@
-import { type ResourceItem } from "@schema-ui/renderer/renderer/resource";
-import type { RenderTableNode } from "@schema-ui/renderer/renderer/render.types";
-/**
- * Default schema-driven table surface (R1 · GOAL-004 / D-004) + S4 CRUD wiring
- * + A-002 generic adapter (GOAL-010 S3).
- *
- * Renders a whitelisted table node's `props.columns` over its `props.dataSource`.
- * Fails closed when the node declares no columns, no (valid) data source, or a
- * response that violates the frozen rowKey invariant (F-001 / F-002).
- *
- * F-001 (I-010-001 v0.2.0 §2): `dataSource` must be a single-slash same-origin
- * path; invalid/absent sources render an observable fail-closed state and never
- * reach the (auth) fetcher.
- *
- * F-002 (I-010-001 v0.2.0 §3): `props.rowKey` (default `"id"`) is the direct
- * field name of each row's unique, non-empty scalar key (string / finite
- * number). A missing / empty / non-scalar / duplicate key stops rendering the
- * table data and forbids row actions and selection.
- *
- * S4 (GOAL-007 · I-007-003 v0.2.2 §9): when rendered inside a `RenderPage`
- * (which always wraps content in the SchemaCrudProvider), the table surfaces
- * `props.toolbar` (create trigger) and `props.actions` (row edit/delete),
- * participates in row selection for the page's recordView / edit-form prefill,
- * reads its query from the shared per-table query state (so the search-form
- * binding and the post-write reload both reach it), and registers its injected
- * fetcher so modal form submits / row actions use the same transport. All of
- * this is fixture-driven: no record-specific logic lives here.
- */
-export interface SchemaTableProps {
-    node: RenderTableNode;
-    /** Injectable fetch (defaults to `globalThis.fetch`). */
-    fetcher?: typeof fetch;
-}
-export interface SchemaTableColumnSpec {
-    field: string;
-    label?: string;
-    sortable?: boolean;
-    /** W4 · GOAL-005: single-line truncate + title affordance for long values. */
-    truncate?: boolean;
-    /** Column width hint (px number or CSS length). */
-    width?: number | string;
-    /** Minimum column width (px number or CSS length). */
-    minWidth?: number | string;
-    /** W16-F04: render a cent-valued number as a localized currency string. */
-    format?: "currency";
-    /** W16-F09: render this cell as a colored badge using the row field value. */
-    badgeStyleField?: string;
-}
-/** Structured row predicate used by Schema actions; malformed predicates fail closed. */
-export declare function rowActionDisabled(action: unknown, row: ResourceItem): boolean;
-/** Extracts the table node's column specs, fail-closed on malformed entries. */
-export declare function schemaTableColumns(node: RenderTableNode): SchemaTableColumnSpec[];
-/**
- * Resolves the table node's list endpoint (F-001). v2.9 prefers the node-level
- * DataRef (ADR-0039, source:api url); the legacy props.dataSource string stays
- * supported. Returns null when absent or not a single-slash same-origin path;
- * the table then fails closed and never fetches (the fixture fallback was
- * removed in GOAL-010 S3).
- */
-export declare function schemaTableDataSource(node: RenderTableNode): string | null;
-/** v2.9 node-level DataRef params (ADR-0039 route bindings), else empty. */
-export declare function schemaTableDataParams(node: RenderTableNode): Record<string, unknown> | undefined;
-/** F-002: the direct field name used as each row's unique key (default "id"). */
-export declare function schemaTableRowKey(node: RenderTableNode): string;
-/** One select option of a schema-driven table filter. */
-export interface SchemaTableFilterOptionSpec {
-    value: string;
-    label?: string;
-    labelKey?: string;
-}
-/** A schema-driven table filter (table node `props.filters`; select-only). */
-export interface SchemaTableFilterSpec {
-    field: string;
-    type: "select";
-    label?: string;
-    labelKey?: string;
-    options: SchemaTableFilterOptionSpec[];
-}
-/**
- * Extracts the table node's filter specs (fail-closed on malformed entries).
- * Only `select` filters are supported; other/unknown types are dropped so a
- * schema typo never renders a broken control.
- */
-export declare function schemaTableFilters(node: RenderTableNode): SchemaTableFilterSpec[];
-/**
- * Windowed pager page list: 1 … current±1 … total, with gap markers for
- * long page runs (stable shape for tests and a11y).
- */
-export declare function pagerPages(current: number, total: number): Array<number | "gap">;
-export declare function SchemaTable({ node, fetcher }: SchemaTableProps): import("react").JSX.Element;