@magicvr/schema-ui-renderer 0.3.2 → 0.3.4

package/renderer/resource.d.ts

@@ -0,0 +1,114 @@
+import type { SortOrder } from "@magicvr/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

@@ -0,0 +1,28 @@
+import { type ExecutionResult } from "@magicvr/schema-ui-renderer/renderer/permissions";
+import type { NavigationContext } from "@magicvr/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

@@ -0,0 +1,90 @@
+import { type ResourceItem } from "@magicvr/schema-ui-renderer/renderer/resource";
+import type { RenderTableNode } from "@magicvr/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;