blocks-schema 0.2.0 → 0.4.1

package/README.md

@@ -1,9 +1,36 @@
 # blocks-schema
 
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/blocks/actions/workflows/ci.yml">
+    <img height="20" src="https://github.com/constructive-io/blocks/actions/workflows/ci.yml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/blocks/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/blocks-schema"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/blocks?filename=packages%2Fblocks-schema%2Fpackage.json"/></a>
+</p>
+
 Portable JSON UI document specification for Constructive Blocks: the storage
 format, runtime validators, JSON Schema export, and pure document-manipulation
 API. No React — this package is safe in servers, workers, and agents.
 
+## Install
+
+```bash
+pnpm add blocks-schema
+```
+
+The package is built with `makage` and published from `dist`, so every module is
+a root-level entry point and deep imports need no exports map:
+
+```ts
+import { parseDocument } from 'blocks-schema';
+import { composeDocument } from 'blocks-schema/compose';
+import { validateField } from 'blocks-schema/validation';
+```
+
 ## Overview
 
 | Layer | Purpose | File |

package/compose.d.ts

@@ -0,0 +1,40 @@
+import type { NodeOverride as GenericNodeOverride } from 'json-renderer';
+import type { UIDocument } from './envelope';
+import type { UIActions, UIBinding, UINode, UINodeProps, UINodeType } from './node';
+/**
+ * A patch applied to the node with a given `key`. Composition is per node, not
+ * per document, so a generated default can be customized in a few places
+ * without giving up generation.
+ */
+export interface NodeOverride extends GenericNodeOverride<UINodeType, UINodeProps> {
+    type?: UINodeType;
+    props?: UINodeProps;
+    bindings?: UIBinding;
+    actions?: UIActions;
+    /** Drop the node (and its subtree) from the composed document. */
+    remove?: boolean;
+}
+export type NodeOverrides = Record<string, NodeOverride>;
+/** Reusable subtrees addressed by `Fragment` nodes via `props.ref`. */
+export type FragmentMap = Record<string, UINode>;
+/** Subtrees that fill `Slot` nodes, addressed by `props.name`. */
+export type SlotMap = Record<string, UINode | UINode[]>;
+export interface ComposeOptions {
+    fragments?: FragmentMap;
+    slots?: SlotMap;
+    overrides?: NodeOverrides;
+}
+/**
+ * Compose a document: expand `Fragment` references, fill `Slot` nodes, then
+ * apply per-node overrides. Pure — the input document is never mutated.
+ */
+export declare function composeDocument(document: UIDocument, options?: ComposeOptions): UIDocument;
+export declare function composeNodeTree(node: UINode, options?: ComposeOptions): UINode;
+/**
+ * Merge an overlay document onto a generated one by node `key`: hand-authored
+ * content wins per node, not per document.
+ */
+export declare function mergeDocuments(base: UIDocument, overlay: Partial<Omit<UIDocument, 'page'>> & {
+    page?: UINode;
+}): UIDocument;
+export declare function mergeNodes(base: UINode, overlay: UINode): UINode;

package/compose.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeDocument = composeDocument;
+exports.composeNodeTree = composeNodeTree;
+exports.mergeDocuments = mergeDocuments;
+exports.mergeNodes = mergeNodes;
+/**
+ * Document composition for Constructive documents: the generic ops from
+ * `json-renderer`, typed over this package's `UINode`/`UIDocument` and its
+ * `Fragment`/`Slot` vocabulary.
+ */
+const json_renderer_1 = require("json-renderer");
+function genericOptions(options) {
+    return options;
+}
+/**
+ * Compose a document: expand `Fragment` references, fill `Slot` nodes, then
+ * apply per-node overrides. Pure — the input document is never mutated.
+ */
+function composeDocument(document, options = {}) {
+    return (0, json_renderer_1.composeEnvelope)(document, genericOptions(options));
+}
+function composeNodeTree(node, options = {}) {
+    return (0, json_renderer_1.composeNodeTree)(node, genericOptions(options));
+}
+/**
+ * Merge an overlay document onto a generated one by node `key`: hand-authored
+ * content wins per node, not per document.
+ */
+function mergeDocuments(base, overlay) {
+    return (0, json_renderer_1.mergeEnvelopes)(base, overlay);
+}
+function mergeNodes(base, overlay) {
+    return (0, json_renderer_1.mergeNodeTrees)(base, overlay);
+}

package/core.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The generic core this package specializes.
+ *
+ * `blocks-schema` is the Constructive *vocabulary* over `json-renderer`'s
+ * framework-agnostic document format. These re-exports let a consumer name the
+ * generic types (and the renderer adapter contract) without adding a second
+ * dependency, and without this package restating them.
+ */
+export type { AnyDocumentEnvelope, AnyDocumentNode, BindingScope, ComposeVocabulary, DocumentDataSource, DocumentEnvelope, DocumentMetadata, DocumentNode, EnvelopeKind, FieldNodePredicate, FieldStateAccess, NodeAction, NodeConstraints, NodeRegistry, NodeResolution, RegistrySource, RenderContext, RenderContextBase, RendererAdapter, UnknownNodePolicy, } from 'json-renderer';
+export { DOCUMENT_FORMAT_VERSION } from 'json-renderer';

package/core.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCUMENT_FORMAT_VERSION = void 0;
+var json_renderer_1 = require("json-renderer");
+Object.defineProperty(exports, "DOCUMENT_FORMAT_VERSION", { enumerable: true, get: function () { return json_renderer_1.DOCUMENT_FORMAT_VERSION; } });

package/envelope.d.ts

@@ -0,0 +1,48 @@
+import type { DocumentDataSource, DocumentEnvelope, DocumentMetadata, EnvelopeKind, RegistrySource } from 'json-renderer';
+import type { UINode } from './node';
+export declare const UI_DOCUMENT_FORMAT_VERSION = "1.0";
+export declare const UI_DOCUMENT_TYPE = "UISchema";
+/** The envelope kind this package specializes out of the generic core. */
+export declare const UI_DOCUMENT_KIND: EnvelopeKind<typeof UI_DOCUMENT_TYPE, typeof UI_DOCUMENT_FORMAT_VERSION>;
+export interface UIDocumentMetadata extends DocumentMetadata {
+    title?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * A resolution source for node types: a shadcn-style registry URL template,
+ * e.g. `https://constructive-io.github.io/blocks/r/{name}.json`.
+ */
+export type UIRegistrySource = RegistrySource;
+/** A named, read-only query a document's blocks can bind against. */
+export interface UIDataSource extends DocumentDataSource {
+    name: string;
+    table?: string;
+    query?: string;
+    variables?: Record<string, unknown>;
+    select?: string;
+    where?: Record<string, unknown>;
+    orderBy?: unknown;
+    first?: number;
+}
+/**
+ * The Constructive UI document: the generic `DocumentEnvelope` pinned to this
+ * package's node vocabulary, envelope discriminator, and format version.
+ */
+export interface UIDocument extends DocumentEnvelope<UINode, typeof UI_DOCUMENT_TYPE, typeof UI_DOCUMENT_FORMAT_VERSION> {
+    meta?: UIDocumentMetadata;
+    registries?: UIRegistrySource[];
+    dataSources?: UIDataSource[];
+}
+/**
+ * The name the deployed dashboard form builder uses for the same envelope.
+ * Kept as an alias so existing `UISchema` consumers migrate by import swap.
+ */
+export type UISchema = UIDocument;
+export declare function isUIDocument(value: unknown): value is UIDocument;
+/** @deprecated Use {@link isUIDocument}. */
+export declare const isUISchema: typeof isUIDocument;
+export declare function createDocument(page: UINode, options?: {
+    id?: string;
+    meta?: UIDocumentMetadata;
+}): UIDocument;

package/envelope.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUISchema = exports.UI_DOCUMENT_KIND = exports.UI_DOCUMENT_TYPE = exports.UI_DOCUMENT_FORMAT_VERSION = void 0;
+exports.isUIDocument = isUIDocument;
+exports.createDocument = createDocument;
+const json_renderer_1 = require("json-renderer");
+exports.UI_DOCUMENT_FORMAT_VERSION = '1.0';
+exports.UI_DOCUMENT_TYPE = 'UISchema';
+/** The envelope kind this package specializes out of the generic core. */
+exports.UI_DOCUMENT_KIND = {
+    documentType: exports.UI_DOCUMENT_TYPE,
+    formatVersion: exports.UI_DOCUMENT_FORMAT_VERSION,
+};
+function isUIDocument(value) {
+    return (0, json_renderer_1.isDocumentEnvelope)(value, exports.UI_DOCUMENT_KIND);
+}
+/** @deprecated Use {@link isUIDocument}. */
+exports.isUISchema = isUIDocument;
+function createDocument(page, options = {}) {
+    return (0, json_renderer_1.createEnvelope)(exports.UI_DOCUMENT_KIND, page, options);
+}

package/esm/compose.js

@@ -0,0 +1,29 @@
+/**
+ * Document composition for Constructive documents: the generic ops from
+ * `json-renderer`, typed over this package's `UINode`/`UIDocument` and its
+ * `Fragment`/`Slot` vocabulary.
+ */
+import { composeEnvelope, composeNodeTree as composeGenericNodeTree, mergeEnvelopes, mergeNodeTrees } from 'json-renderer';
+function genericOptions(options) {
+    return options;
+}
+/**
+ * Compose a document: expand `Fragment` references, fill `Slot` nodes, then
+ * apply per-node overrides. Pure — the input document is never mutated.
+ */
+export function composeDocument(document, options = {}) {
+    return composeEnvelope(document, genericOptions(options));
+}
+export function composeNodeTree(node, options = {}) {
+    return composeGenericNodeTree(node, genericOptions(options));
+}
+/**
+ * Merge an overlay document onto a generated one by node `key`: hand-authored
+ * content wins per node, not per document.
+ */
+export function mergeDocuments(base, overlay) {
+    return mergeEnvelopes(base, overlay);
+}
+export function mergeNodes(base, overlay) {
+    return mergeNodeTrees(base, overlay);
+}

package/esm/core.js

@@ -0,0 +1 @@
+export { DOCUMENT_FORMAT_VERSION } from 'json-renderer';

package/esm/envelope.js

@@ -0,0 +1,16 @@
+import { createEnvelope, isDocumentEnvelope } from 'json-renderer';
+export const UI_DOCUMENT_FORMAT_VERSION = '1.0';
+export const UI_DOCUMENT_TYPE = 'UISchema';
+/** The envelope kind this package specializes out of the generic core. */
+export const UI_DOCUMENT_KIND = {
+    documentType: UI_DOCUMENT_TYPE,
+    formatVersion: UI_DOCUMENT_FORMAT_VERSION,
+};
+export function isUIDocument(value) {
+    return isDocumentEnvelope(value, UI_DOCUMENT_KIND);
+}
+/** @deprecated Use {@link isUIDocument}. */
+export const isUISchema = isUIDocument;
+export function createDocument(page, options = {}) {
+    return createEnvelope(UI_DOCUMENT_KIND, page, options);
+}

package/esm/index.js

@@ -0,0 +1,7 @@
+export * from './compose';
+export * from './core';
+export * from './envelope';
+export * from './json-schema';
+export * from './node';
+export * from './validation';
+export * from './zod';

package/esm/json-schema.js

@@ -0,0 +1,12 @@
+import { toJsonSchema } from 'json-renderer';
+import { uiDocumentSchema, uiNodeSchema } from './zod';
+/**
+ * JSON Schema for the document envelope, for agents emitting documents as tool
+ * output and for registry/editor tooling that validates without importing zod.
+ */
+export function toDocumentJsonSchema() {
+    return toJsonSchema(uiDocumentSchema);
+}
+export function toNodeJsonSchema() {
+    return toJsonSchema(uiNodeSchema);
+}

package/esm/node.js

@@ -0,0 +1,83 @@
+/**
+ * Node-level types for the Constructive JSON UI document format.
+ *
+ * The tree model, the walk, and the field-collection primitives live in
+ * `json-renderer`; this module owns the Constructive *vocabulary* — which node
+ * types exist and which of them are fields — and specializes the generic
+ * helpers over it. A node's `type` is resolved to a component by the renderer's
+ * widget registry, so this package never imports React and stays usable on a
+ * server, in an agent, or in a validator.
+ */
+import { collectDefaultValues as collectNodeDefaultValues, collectFieldConstraints as collectNodeFieldConstraints, collectFieldNames as collectNodeFieldNames, findNodeByKey as findNodeInTreeByKey, walkNodes as walkNodeTree, } from 'json-renderer';
+/** Field widget node types (a form's leaves). */
+export const WIDGET_NODE_TYPES = [
+    'Input',
+    'Textarea',
+    'Select',
+    'RadioGroup',
+    'Checkbox',
+    'Switch',
+    'NumberInput',
+    'DatePicker',
+    'DateTimePicker',
+    'TimePicker',
+    'PhoneInput',
+    'CodeEditor',
+    'MarkdownEditor',
+    'JsonEditor',
+    'FileUpload',
+];
+/** Layout node types that own children. */
+export const CONTAINER_NODE_TYPES = ['Page', 'Form', 'Grid', 'GridColumn', 'Section', 'Tabs', 'Tab'];
+/** Document-level blocks (screens, not fields). */
+export const BLOCK_NODE_TYPES = [
+    'DataTable',
+    'DetailPanel',
+    'RelationList',
+    'StatCard',
+    'Chart',
+    'ActionBar',
+    'Markdown',
+    'AgentChat',
+    'Button',
+    'Slot',
+    'Fragment',
+    'Custom',
+];
+const widgetTypes = new Set(WIDGET_NODE_TYPES);
+const containerTypes = new Set(CONTAINER_NODE_TYPES);
+const blockTypes = new Set(BLOCK_NODE_TYPES);
+export function isWidgetNodeType(type) {
+    return widgetTypes.has(type);
+}
+export function isContainerNodeType(type) {
+    return containerTypes.has(type);
+}
+export function isKnownNodeType(type) {
+    return widgetTypes.has(type) || containerTypes.has(type) || blockTypes.has(type);
+}
+export function isWidgetNode(node) {
+    return isWidgetNodeType(node.type);
+}
+export function isContainerNode(node) {
+    return isContainerNodeType(node.type);
+}
+/** Depth-first walk over a node and its descendants. */
+export function walkNodes(node) {
+    return walkNodeTree(node);
+}
+/** Named fields in document order; widget nodes without a `name` are skipped. */
+export function collectFieldNames(node) {
+    return collectNodeFieldNames(node, isWidgetNode);
+}
+/** Default values declared by widget nodes, keyed by field name. */
+export function collectDefaultValues(node) {
+    return collectNodeDefaultValues(node, isWidgetNode);
+}
+/** Validation metadata declared by widget nodes, keyed by field name. */
+export function collectFieldConstraints(node) {
+    return collectNodeFieldConstraints(node, isWidgetNode);
+}
+export function findNodeByKey(node, key) {
+    return findNodeInTreeByKey(node, key);
+}

package/esm/validation.js

@@ -0,0 +1,11 @@
+import { validateValue } from 'json-renderer';
+/**
+ * Validate a single field value against the constraints declared on its node.
+ * Returns a human-readable message, or `null` when the value is acceptable.
+ *
+ * The check itself is `json-renderer`'s `validateValue`; this is the named,
+ * vocabulary-typed entry point Constructive consumers already import.
+ */
+export function validateField(value, constraints, required) {
+    return validateValue(value, constraints, required);
+}

package/esm/zod.js

@@ -0,0 +1,54 @@
+/**
+ * Runtime validation for Constructive documents. The tree and envelope rules
+ * come from `json-renderer`'s schema factories; this module narrows props and
+ * actions to the Constructive vocabulary.
+ */
+import { createDocumentSchema, createNodeSchema, dataSourceSchema, documentMetadataSchema, nodeBindingsSchema, nodeConstraintsSchema, nodePropsSchema, registrySourceSchema, } from 'json-renderer';
+import { z } from 'zod';
+import { UI_DOCUMENT_KIND } from './envelope';
+export const uiNodeConstraintsSchema = nodeConstraintsSchema;
+export const uiNodePropsSchema = nodePropsSchema.extend({
+    fieldId: z.string().optional(),
+    name: z.string().optional(),
+    label: z.string().optional(),
+    description: z.string().optional(),
+    placeholder: z.string().optional(),
+    required: z.boolean().optional(),
+    hidden: z.boolean().optional(),
+    disabled: z.boolean().optional(),
+    defaultValue: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+    constraints: uiNodeConstraintsSchema.optional(),
+    className: z.string().optional(),
+});
+export const uiBindingSchema = nodeBindingsSchema;
+export const uiActionSchema = z.object({
+    type: z.enum(['flow', 'handler']),
+    flowId: z.string().optional(),
+    handler: z.string().optional(),
+    inputMapping: z.record(z.string(), z.string()).optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+export const uiActionsSchema = z.record(z.string(), uiActionSchema);
+export const uiNodeSchema = createNodeSchema({
+    propsSchema: uiNodePropsSchema,
+    actionsSchema: uiActionsSchema,
+});
+export const uiRegistrySourceSchema = registrySourceSchema;
+export const uiDataSourceSchema = dataSourceSchema.extend({
+    table: z.string().optional(),
+});
+export const uiDocumentMetadataSchema = documentMetadataSchema;
+export const uiDocumentSchema = createDocumentSchema({
+    kind: UI_DOCUMENT_KIND,
+    nodeSchema: uiNodeSchema,
+});
+/** Throws a `ZodError` describing every problem in the document. */
+export function parseDocument(value) {
+    return uiDocumentSchema.parse(value);
+}
+export function safeParseDocument(value) {
+    return uiDocumentSchema.safeParse(value);
+}
+export function parseNode(value) {
+    return uiNodeSchema.parse(value);
+}

package/index.d.ts

@@ -0,0 +1,7 @@
+export * from './compose';
+export * from './core';
+export * from './envelope';
+export * from './json-schema';
+export * from './node';
+export * from './validation';
+export * from './zod';

package/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./compose"), exports);
+__exportStar(require("./core"), exports);
+__exportStar(require("./envelope"), exports);
+__exportStar(require("./json-schema"), exports);
+__exportStar(require("./node"), exports);
+__exportStar(require("./validation"), exports);
+__exportStar(require("./zod"), exports);

package/json-schema.d.ts

@@ -0,0 +1,6 @@
+/**
+ * JSON Schema for the document envelope, for agents emitting documents as tool
+ * output and for registry/editor tooling that validates without importing zod.
+ */
+export declare function toDocumentJsonSchema(): Record<string, unknown>;
+export declare function toNodeJsonSchema(): Record<string, unknown>;

package/json-schema.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDocumentJsonSchema = toDocumentJsonSchema;
+exports.toNodeJsonSchema = toNodeJsonSchema;
+const json_renderer_1 = require("json-renderer");
+const zod_1 = require("./zod");
+/**
+ * JSON Schema for the document envelope, for agents emitting documents as tool
+ * output and for registry/editor tooling that validates without importing zod.
+ */
+function toDocumentJsonSchema() {
+    return (0, json_renderer_1.toJsonSchema)(zod_1.uiDocumentSchema);
+}
+function toNodeJsonSchema() {
+    return (0, json_renderer_1.toJsonSchema)(zod_1.uiNodeSchema);
+}

package/node.d.ts

@@ -0,0 +1,79 @@
+import type { DocumentNode, FieldConstraintEntry, NodeActions, NodeBindings, NodeConstraints, NodeProps } from 'json-renderer';
+export type { FieldConstraintEntry } from 'json-renderer';
+/** Field widget node types (a form's leaves). */
+export declare const WIDGET_NODE_TYPES: readonly ["Input", "Textarea", "Select", "RadioGroup", "Checkbox", "Switch", "NumberInput", "DatePicker", "DateTimePicker", "TimePicker", "PhoneInput", "CodeEditor", "MarkdownEditor", "JsonEditor", "FileUpload"];
+/** Layout node types that own children. */
+export declare const CONTAINER_NODE_TYPES: readonly ["Page", "Form", "Grid", "GridColumn", "Section", "Tabs", "Tab"];
+/** Document-level blocks (screens, not fields). */
+export declare const BLOCK_NODE_TYPES: readonly ["DataTable", "DetailPanel", "RelationList", "StatCard", "Chart", "ActionBar", "Markdown", "AgentChat", "Button", "Slot", "Fragment", "Custom"];
+export type WidgetNodeType = (typeof WIDGET_NODE_TYPES)[number];
+export type ContainerNodeType = (typeof CONTAINER_NODE_TYPES)[number];
+export type BlockNodeType = (typeof BLOCK_NODE_TYPES)[number];
+/**
+ * Known node types. Unknown strings stay valid: a registry may satisfy node
+ * types this package has never heard of, and the renderer falls back to an
+ * `UnknownBlock` rather than throwing.
+ */
+export type KnownNodeType = WidgetNodeType | ContainerNodeType | BlockNodeType;
+export type UINodeType = KnownNodeType | (string & {});
+export type InputType = 'text' | 'email' | 'url' | 'password' | 'tel' | 'search';
+export interface UINodeConstraints extends NodeConstraints {
+    minLength?: number;
+    maxLength?: number;
+    minValue?: number;
+    maxValue?: number;
+    pattern?: string;
+    precision?: number;
+    scale?: number;
+}
+export interface UINodePropsBase {
+    fieldId?: string;
+    name?: string;
+    label?: string;
+    description?: string;
+    placeholder?: string;
+    required?: boolean;
+    hidden?: boolean;
+    disabled?: boolean;
+    defaultValue?: string | number | boolean | null;
+    constraints?: UINodeConstraints;
+    className?: string;
+}
+export type UINodeProps = UINodePropsBase & Record<string, unknown>;
+/** Prop name → template expression, e.g. `{ label: '{{ row.title }}' }`. */
+export interface UIBinding extends NodeBindings {
+    [propName: string]: string;
+}
+export interface UIAction {
+    type: 'flow' | 'handler';
+    flowId?: string;
+    handler?: string;
+    inputMapping?: Record<string, string>;
+    params?: Record<string, unknown>;
+}
+/** Event name → action, e.g. `{ submit: { type: 'flow', flowId } }`. */
+export interface UIActions {
+    [eventName: string]: UIAction;
+}
+/** The generic node tree pinned to the Constructive vocabulary and props. */
+export interface UINode extends DocumentNode<UINodeType, UINodeProps> {
+    children: UINode[];
+    bindings?: UIBinding;
+    actions?: UIActions;
+}
+export declare function isWidgetNodeType(type: string): type is WidgetNodeType;
+export declare function isContainerNodeType(type: string): type is ContainerNodeType;
+export declare function isKnownNodeType(type: string): type is KnownNodeType;
+export declare function isWidgetNode(node: UINode): boolean;
+export declare function isContainerNode(node: UINode): boolean;
+/** Depth-first walk over a node and its descendants. */
+export declare function walkNodes(node: UINode): Generator<UINode>;
+/** Named fields in document order; widget nodes without a `name` are skipped. */
+export declare function collectFieldNames(node: UINode): string[];
+/** Default values declared by widget nodes, keyed by field name. */
+export declare function collectDefaultValues(node: UINode): Record<string, unknown>;
+/** Validation metadata declared by widget nodes, keyed by field name. */
+export declare function collectFieldConstraints(node: UINode): Record<string, FieldConstraintEntry>;
+export declare function findNodeByKey(node: UINode, key: string): UINode | undefined;
+/** Re-exported so `UINodeProps` consumers can name the generic props shape. */
+export type { NodeActions, NodeBindings, NodeProps };

package/node.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOCK_NODE_TYPES = exports.CONTAINER_NODE_TYPES = exports.WIDGET_NODE_TYPES = void 0;
+exports.isWidgetNodeType = isWidgetNodeType;
+exports.isContainerNodeType = isContainerNodeType;
+exports.isKnownNodeType = isKnownNodeType;
+exports.isWidgetNode = isWidgetNode;
+exports.isContainerNode = isContainerNode;
+exports.walkNodes = walkNodes;
+exports.collectFieldNames = collectFieldNames;
+exports.collectDefaultValues = collectDefaultValues;
+exports.collectFieldConstraints = collectFieldConstraints;
+exports.findNodeByKey = findNodeByKey;
+/**
+ * Node-level types for the Constructive JSON UI document format.
+ *
+ * The tree model, the walk, and the field-collection primitives live in
+ * `json-renderer`; this module owns the Constructive *vocabulary* — which node
+ * types exist and which of them are fields — and specializes the generic
+ * helpers over it. A node's `type` is resolved to a component by the renderer's
+ * widget registry, so this package never imports React and stays usable on a
+ * server, in an agent, or in a validator.
+ */
+const json_renderer_1 = require("json-renderer");
+/** Field widget node types (a form's leaves). */
+exports.WIDGET_NODE_TYPES = [
+    'Input',
+    'Textarea',
+    'Select',
+    'RadioGroup',
+    'Checkbox',
+    'Switch',
+    'NumberInput',
+    'DatePicker',
+    'DateTimePicker',
+    'TimePicker',
+    'PhoneInput',
+    'CodeEditor',
+    'MarkdownEditor',
+    'JsonEditor',
+    'FileUpload',
+];
+/** Layout node types that own children. */
+exports.CONTAINER_NODE_TYPES = ['Page', 'Form', 'Grid', 'GridColumn', 'Section', 'Tabs', 'Tab'];
+/** Document-level blocks (screens, not fields). */
+exports.BLOCK_NODE_TYPES = [
+    'DataTable',
+    'DetailPanel',
+    'RelationList',
+    'StatCard',
+    'Chart',
+    'ActionBar',
+    'Markdown',
+    'AgentChat',
+    'Button',
+    'Slot',
+    'Fragment',
+    'Custom',
+];
+const widgetTypes = new Set(exports.WIDGET_NODE_TYPES);
+const containerTypes = new Set(exports.CONTAINER_NODE_TYPES);
+const blockTypes = new Set(exports.BLOCK_NODE_TYPES);
+function isWidgetNodeType(type) {
+    return widgetTypes.has(type);
+}
+function isContainerNodeType(type) {
+    return containerTypes.has(type);
+}
+function isKnownNodeType(type) {
+    return widgetTypes.has(type) || containerTypes.has(type) || blockTypes.has(type);
+}
+function isWidgetNode(node) {
+    return isWidgetNodeType(node.type);
+}
+function isContainerNode(node) {
+    return isContainerNodeType(node.type);
+}
+/** Depth-first walk over a node and its descendants. */
+function walkNodes(node) {
+    return (0, json_renderer_1.walkNodes)(node);
+}
+/** Named fields in document order; widget nodes without a `name` are skipped. */
+function collectFieldNames(node) {
+    return (0, json_renderer_1.collectFieldNames)(node, isWidgetNode);
+}
+/** Default values declared by widget nodes, keyed by field name. */
+function collectDefaultValues(node) {
+    return (0, json_renderer_1.collectDefaultValues)(node, isWidgetNode);
+}
+/** Validation metadata declared by widget nodes, keyed by field name. */
+function collectFieldConstraints(node) {
+    return (0, json_renderer_1.collectFieldConstraints)(node, isWidgetNode);
+}
+function findNodeByKey(node, key) {
+    return (0, json_renderer_1.findNodeByKey)(node, key);
+}