blocks-schema 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +79 -0
- package/dist/index.cjs +312 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +255 -0
- package/dist/index.d.ts +255 -0
- package/dist/index.js +275 -0
- package/dist/index.js.map +1 -0
- package/package.json +62 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Node-level types for the portable JSON UI document format.
|
|
5
|
+
*
|
|
6
|
+
* A document is a tree of typed nodes. A node's `type` is resolved to a
|
|
7
|
+
* component by the renderer's widget registry, so this package never imports
|
|
8
|
+
* React and stays usable on a server, in an agent, or in a validator.
|
|
9
|
+
*/
|
|
10
|
+
/** Field widget node types (a form's leaves). */
|
|
11
|
+
declare const WIDGET_NODE_TYPES: readonly ["Input", "Textarea", "Select", "RadioGroup", "Checkbox", "Switch", "NumberInput", "DatePicker", "DateTimePicker", "TimePicker", "PhoneInput", "CodeEditor", "MarkdownEditor", "JsonEditor", "FileUpload"];
|
|
12
|
+
/** Layout node types that own children. */
|
|
13
|
+
declare const CONTAINER_NODE_TYPES: readonly ["Page", "Form", "Grid", "GridColumn", "Section", "Tabs", "Tab"];
|
|
14
|
+
/** Document-level blocks (screens, not fields). */
|
|
15
|
+
declare const BLOCK_NODE_TYPES: readonly ["DataTable", "DetailPanel", "RelationList", "StatCard", "Chart", "ActionBar", "Markdown", "AgentChat", "Button", "Slot", "Fragment", "Custom"];
|
|
16
|
+
type WidgetNodeType = (typeof WIDGET_NODE_TYPES)[number];
|
|
17
|
+
type ContainerNodeType = (typeof CONTAINER_NODE_TYPES)[number];
|
|
18
|
+
type BlockNodeType = (typeof BLOCK_NODE_TYPES)[number];
|
|
19
|
+
/**
|
|
20
|
+
* Known node types. Unknown strings stay valid: a registry may satisfy node
|
|
21
|
+
* types this package has never heard of, and the renderer falls back to an
|
|
22
|
+
* `UnknownBlock` rather than throwing.
|
|
23
|
+
*/
|
|
24
|
+
type KnownNodeType = WidgetNodeType | ContainerNodeType | BlockNodeType;
|
|
25
|
+
type UINodeType = KnownNodeType | (string & {});
|
|
26
|
+
type InputType = 'text' | 'email' | 'url' | 'password' | 'tel' | 'search';
|
|
27
|
+
interface UINodeConstraints {
|
|
28
|
+
minLength?: number;
|
|
29
|
+
maxLength?: number;
|
|
30
|
+
minValue?: number;
|
|
31
|
+
maxValue?: number;
|
|
32
|
+
pattern?: string;
|
|
33
|
+
precision?: number;
|
|
34
|
+
scale?: number;
|
|
35
|
+
}
|
|
36
|
+
interface UINodePropsBase {
|
|
37
|
+
fieldId?: string;
|
|
38
|
+
name?: string;
|
|
39
|
+
label?: string;
|
|
40
|
+
description?: string;
|
|
41
|
+
placeholder?: string;
|
|
42
|
+
required?: boolean;
|
|
43
|
+
hidden?: boolean;
|
|
44
|
+
disabled?: boolean;
|
|
45
|
+
defaultValue?: string | number | boolean | null;
|
|
46
|
+
constraints?: UINodeConstraints;
|
|
47
|
+
className?: string;
|
|
48
|
+
}
|
|
49
|
+
type UINodeProps = UINodePropsBase & Record<string, unknown>;
|
|
50
|
+
/** Prop name → template expression, e.g. `{ label: '{{ row.title }}' }`. */
|
|
51
|
+
interface UIBinding {
|
|
52
|
+
[propName: string]: string;
|
|
53
|
+
}
|
|
54
|
+
interface UIAction {
|
|
55
|
+
type: 'flow' | 'handler';
|
|
56
|
+
flowId?: string;
|
|
57
|
+
handler?: string;
|
|
58
|
+
inputMapping?: Record<string, string>;
|
|
59
|
+
params?: Record<string, unknown>;
|
|
60
|
+
}
|
|
61
|
+
/** Event name → action, e.g. `{ submit: { type: 'flow', flowId } }`. */
|
|
62
|
+
interface UIActions {
|
|
63
|
+
[eventName: string]: UIAction;
|
|
64
|
+
}
|
|
65
|
+
interface UINode {
|
|
66
|
+
type: UINodeType;
|
|
67
|
+
key: string;
|
|
68
|
+
props: UINodeProps;
|
|
69
|
+
children: UINode[];
|
|
70
|
+
bindings?: UIBinding;
|
|
71
|
+
actions?: UIActions;
|
|
72
|
+
}
|
|
73
|
+
declare function isWidgetNodeType(type: string): type is WidgetNodeType;
|
|
74
|
+
declare function isContainerNodeType(type: string): type is ContainerNodeType;
|
|
75
|
+
declare function isKnownNodeType(type: string): type is KnownNodeType;
|
|
76
|
+
declare function isWidgetNode(node: UINode): boolean;
|
|
77
|
+
declare function isContainerNode(node: UINode): boolean;
|
|
78
|
+
/** Depth-first walk over a node and its descendants. */
|
|
79
|
+
declare function walkNodes(node: UINode): Generator<UINode>;
|
|
80
|
+
/** Named fields in document order; widget nodes without a `name` are skipped. */
|
|
81
|
+
declare function collectFieldNames(node: UINode): string[];
|
|
82
|
+
/** Default values declared by widget nodes, keyed by field name. */
|
|
83
|
+
declare function collectDefaultValues(node: UINode): Record<string, unknown>;
|
|
84
|
+
interface FieldConstraintEntry {
|
|
85
|
+
constraints?: UINodeConstraints;
|
|
86
|
+
required?: boolean;
|
|
87
|
+
}
|
|
88
|
+
/** Validation metadata declared by widget nodes, keyed by field name. */
|
|
89
|
+
declare function collectFieldConstraints(node: UINode): Record<string, FieldConstraintEntry>;
|
|
90
|
+
declare function findNodeByKey(node: UINode, key: string): UINode | undefined;
|
|
91
|
+
|
|
92
|
+
declare const UI_DOCUMENT_FORMAT_VERSION = "1.0";
|
|
93
|
+
declare const UI_DOCUMENT_TYPE = "UISchema";
|
|
94
|
+
interface UIDocumentMetadata {
|
|
95
|
+
title?: string;
|
|
96
|
+
description?: string;
|
|
97
|
+
[key: string]: unknown;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* A resolution source for node types: a shadcn-style registry URL template,
|
|
101
|
+
* e.g. `https://constructive-io.github.io/blocks/r/{name}.json`.
|
|
102
|
+
*/
|
|
103
|
+
interface UIRegistrySource {
|
|
104
|
+
name: string;
|
|
105
|
+
url: string;
|
|
106
|
+
}
|
|
107
|
+
/** A named, read-only query a document's blocks can bind against. */
|
|
108
|
+
interface UIDataSource {
|
|
109
|
+
name: string;
|
|
110
|
+
table?: string;
|
|
111
|
+
query?: string;
|
|
112
|
+
variables?: Record<string, unknown>;
|
|
113
|
+
select?: string;
|
|
114
|
+
where?: Record<string, unknown>;
|
|
115
|
+
orderBy?: unknown;
|
|
116
|
+
first?: number;
|
|
117
|
+
}
|
|
118
|
+
interface UIDocument {
|
|
119
|
+
formatVersion: typeof UI_DOCUMENT_FORMAT_VERSION;
|
|
120
|
+
type: typeof UI_DOCUMENT_TYPE;
|
|
121
|
+
id: string;
|
|
122
|
+
meta?: UIDocumentMetadata;
|
|
123
|
+
registries?: UIRegistrySource[];
|
|
124
|
+
dataSources?: UIDataSource[];
|
|
125
|
+
page: UINode;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* The name the deployed dashboard form builder uses for the same envelope.
|
|
129
|
+
* Kept as an alias so existing `UISchema` consumers migrate by import swap.
|
|
130
|
+
*/
|
|
131
|
+
type UISchema = UIDocument;
|
|
132
|
+
declare function isUIDocument(value: unknown): value is UIDocument;
|
|
133
|
+
/** @deprecated Use {@link isUIDocument}. */
|
|
134
|
+
declare const isUISchema: typeof isUIDocument;
|
|
135
|
+
declare function createDocument(page: UINode, options?: {
|
|
136
|
+
id?: string;
|
|
137
|
+
meta?: UIDocumentMetadata;
|
|
138
|
+
}): UIDocument;
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* A patch applied to the node with a given `key`. Composition is per node, not
|
|
142
|
+
* per document, so a generated default can be customized in a few places
|
|
143
|
+
* without giving up generation.
|
|
144
|
+
*/
|
|
145
|
+
interface NodeOverride {
|
|
146
|
+
type?: UINodeType;
|
|
147
|
+
props?: UINodeProps;
|
|
148
|
+
bindings?: UIBinding;
|
|
149
|
+
actions?: UIActions;
|
|
150
|
+
/** Drop the node (and its subtree) from the composed document. */
|
|
151
|
+
remove?: boolean;
|
|
152
|
+
}
|
|
153
|
+
type NodeOverrides = Record<string, NodeOverride>;
|
|
154
|
+
/** Reusable subtrees addressed by `Fragment` nodes via `props.ref`. */
|
|
155
|
+
type FragmentMap = Record<string, UINode>;
|
|
156
|
+
/** Subtrees that fill `Slot` nodes, addressed by `props.name`. */
|
|
157
|
+
type SlotMap = Record<string, UINode | UINode[]>;
|
|
158
|
+
interface ComposeOptions {
|
|
159
|
+
fragments?: FragmentMap;
|
|
160
|
+
slots?: SlotMap;
|
|
161
|
+
overrides?: NodeOverrides;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Compose a document: expand `Fragment` references, fill `Slot` nodes, then
|
|
165
|
+
* apply per-node overrides. Pure — the input document is never mutated.
|
|
166
|
+
*/
|
|
167
|
+
declare function composeDocument(document: UIDocument, options?: ComposeOptions): UIDocument;
|
|
168
|
+
declare function composeNodeTree(node: UINode, options?: ComposeOptions): UINode;
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* JSON Schema for the document envelope, for agents emitting documents as tool
|
|
172
|
+
* output and for registry/editor tooling that validates without importing zod.
|
|
173
|
+
*/
|
|
174
|
+
declare function toDocumentJsonSchema(): Record<string, unknown>;
|
|
175
|
+
declare function toNodeJsonSchema(): Record<string, unknown>;
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Validate a single field value against the constraints declared on its node.
|
|
179
|
+
* Returns a human-readable message, or `null` when the value is acceptable.
|
|
180
|
+
*/
|
|
181
|
+
declare function validateField(value: unknown, constraints?: UINodeConstraints, required?: boolean): string | null;
|
|
182
|
+
|
|
183
|
+
declare const uiNodeConstraintsSchema: z.ZodObject<{
|
|
184
|
+
minLength: z.ZodOptional<z.ZodNumber>;
|
|
185
|
+
maxLength: z.ZodOptional<z.ZodNumber>;
|
|
186
|
+
minValue: z.ZodOptional<z.ZodNumber>;
|
|
187
|
+
maxValue: z.ZodOptional<z.ZodNumber>;
|
|
188
|
+
pattern: z.ZodOptional<z.ZodString>;
|
|
189
|
+
precision: z.ZodOptional<z.ZodNumber>;
|
|
190
|
+
scale: z.ZodOptional<z.ZodNumber>;
|
|
191
|
+
}, z.core.$strip>;
|
|
192
|
+
declare const uiNodePropsSchema: z.ZodObject<{
|
|
193
|
+
fieldId: z.ZodOptional<z.ZodString>;
|
|
194
|
+
name: z.ZodOptional<z.ZodString>;
|
|
195
|
+
label: z.ZodOptional<z.ZodString>;
|
|
196
|
+
description: z.ZodOptional<z.ZodString>;
|
|
197
|
+
placeholder: z.ZodOptional<z.ZodString>;
|
|
198
|
+
required: z.ZodOptional<z.ZodBoolean>;
|
|
199
|
+
hidden: z.ZodOptional<z.ZodBoolean>;
|
|
200
|
+
disabled: z.ZodOptional<z.ZodBoolean>;
|
|
201
|
+
defaultValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
|
|
202
|
+
constraints: z.ZodOptional<z.ZodObject<{
|
|
203
|
+
minLength: z.ZodOptional<z.ZodNumber>;
|
|
204
|
+
maxLength: z.ZodOptional<z.ZodNumber>;
|
|
205
|
+
minValue: z.ZodOptional<z.ZodNumber>;
|
|
206
|
+
maxValue: z.ZodOptional<z.ZodNumber>;
|
|
207
|
+
pattern: z.ZodOptional<z.ZodString>;
|
|
208
|
+
precision: z.ZodOptional<z.ZodNumber>;
|
|
209
|
+
scale: z.ZodOptional<z.ZodNumber>;
|
|
210
|
+
}, z.core.$strip>>;
|
|
211
|
+
className: z.ZodOptional<z.ZodString>;
|
|
212
|
+
}, z.core.$loose>;
|
|
213
|
+
declare const uiBindingSchema: z.ZodRecord<z.ZodString, z.ZodString>;
|
|
214
|
+
declare const uiActionSchema: z.ZodObject<{
|
|
215
|
+
type: z.ZodEnum<{
|
|
216
|
+
flow: "flow";
|
|
217
|
+
handler: "handler";
|
|
218
|
+
}>;
|
|
219
|
+
flowId: z.ZodOptional<z.ZodString>;
|
|
220
|
+
handler: z.ZodOptional<z.ZodString>;
|
|
221
|
+
inputMapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
222
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
223
|
+
}, z.core.$strip>;
|
|
224
|
+
declare const uiActionsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
|
|
225
|
+
type: z.ZodEnum<{
|
|
226
|
+
flow: "flow";
|
|
227
|
+
handler: "handler";
|
|
228
|
+
}>;
|
|
229
|
+
flowId: z.ZodOptional<z.ZodString>;
|
|
230
|
+
handler: z.ZodOptional<z.ZodString>;
|
|
231
|
+
inputMapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
232
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
233
|
+
}, z.core.$strip>>;
|
|
234
|
+
declare const uiNodeSchema: z.ZodType<UINode>;
|
|
235
|
+
declare const uiRegistrySourceSchema: z.ZodObject<{
|
|
236
|
+
name: z.ZodString;
|
|
237
|
+
url: z.ZodString;
|
|
238
|
+
}, z.core.$strip>;
|
|
239
|
+
declare const uiDataSourceSchema: z.ZodObject<{
|
|
240
|
+
name: z.ZodString;
|
|
241
|
+
table: z.ZodOptional<z.ZodString>;
|
|
242
|
+
query: z.ZodOptional<z.ZodString>;
|
|
243
|
+
variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
244
|
+
}, z.core.$loose>;
|
|
245
|
+
declare const uiDocumentMetadataSchema: z.ZodObject<{
|
|
246
|
+
title: z.ZodOptional<z.ZodString>;
|
|
247
|
+
description: z.ZodOptional<z.ZodString>;
|
|
248
|
+
}, z.core.$loose>;
|
|
249
|
+
declare const uiDocumentSchema: z.ZodType<UIDocument>;
|
|
250
|
+
/** Throws a `ZodError` describing every problem in the document. */
|
|
251
|
+
declare function parseDocument(value: unknown): UIDocument;
|
|
252
|
+
declare function safeParseDocument(value: unknown): z.ZodSafeParseResult<UIDocument>;
|
|
253
|
+
declare function parseNode(value: unknown): UINode;
|
|
254
|
+
|
|
255
|
+
export { BLOCK_NODE_TYPES, type BlockNodeType, CONTAINER_NODE_TYPES, type ComposeOptions, type ContainerNodeType, type FieldConstraintEntry, type FragmentMap, type InputType, type KnownNodeType, type NodeOverride, type NodeOverrides, type SlotMap, type UIAction, type UIActions, type UIBinding, type UIDataSource, type UIDocument, type UIDocumentMetadata, type UINode, type UINodeConstraints, type UINodeProps, type UINodePropsBase, type UINodeType, type UIRegistrySource, type UISchema, UI_DOCUMENT_FORMAT_VERSION, UI_DOCUMENT_TYPE, WIDGET_NODE_TYPES, type WidgetNodeType, collectDefaultValues, collectFieldConstraints, collectFieldNames, composeDocument, composeNodeTree, createDocument, findNodeByKey, isContainerNode, isContainerNodeType, isKnownNodeType, isUIDocument, isUISchema, isWidgetNode, isWidgetNodeType, parseDocument, parseNode, safeParseDocument, toDocumentJsonSchema, toNodeJsonSchema, uiActionSchema, uiActionsSchema, uiBindingSchema, uiDataSourceSchema, uiDocumentMetadataSchema, uiDocumentSchema, uiNodeConstraintsSchema, uiNodePropsSchema, uiNodeSchema, uiRegistrySourceSchema, validateField, walkNodes };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Node-level types for the portable JSON UI document format.
|
|
5
|
+
*
|
|
6
|
+
* A document is a tree of typed nodes. A node's `type` is resolved to a
|
|
7
|
+
* component by the renderer's widget registry, so this package never imports
|
|
8
|
+
* React and stays usable on a server, in an agent, or in a validator.
|
|
9
|
+
*/
|
|
10
|
+
/** Field widget node types (a form's leaves). */
|
|
11
|
+
declare const WIDGET_NODE_TYPES: readonly ["Input", "Textarea", "Select", "RadioGroup", "Checkbox", "Switch", "NumberInput", "DatePicker", "DateTimePicker", "TimePicker", "PhoneInput", "CodeEditor", "MarkdownEditor", "JsonEditor", "FileUpload"];
|
|
12
|
+
/** Layout node types that own children. */
|
|
13
|
+
declare const CONTAINER_NODE_TYPES: readonly ["Page", "Form", "Grid", "GridColumn", "Section", "Tabs", "Tab"];
|
|
14
|
+
/** Document-level blocks (screens, not fields). */
|
|
15
|
+
declare const BLOCK_NODE_TYPES: readonly ["DataTable", "DetailPanel", "RelationList", "StatCard", "Chart", "ActionBar", "Markdown", "AgentChat", "Button", "Slot", "Fragment", "Custom"];
|
|
16
|
+
type WidgetNodeType = (typeof WIDGET_NODE_TYPES)[number];
|
|
17
|
+
type ContainerNodeType = (typeof CONTAINER_NODE_TYPES)[number];
|
|
18
|
+
type BlockNodeType = (typeof BLOCK_NODE_TYPES)[number];
|
|
19
|
+
/**
|
|
20
|
+
* Known node types. Unknown strings stay valid: a registry may satisfy node
|
|
21
|
+
* types this package has never heard of, and the renderer falls back to an
|
|
22
|
+
* `UnknownBlock` rather than throwing.
|
|
23
|
+
*/
|
|
24
|
+
type KnownNodeType = WidgetNodeType | ContainerNodeType | BlockNodeType;
|
|
25
|
+
type UINodeType = KnownNodeType | (string & {});
|
|
26
|
+
type InputType = 'text' | 'email' | 'url' | 'password' | 'tel' | 'search';
|
|
27
|
+
interface UINodeConstraints {
|
|
28
|
+
minLength?: number;
|
|
29
|
+
maxLength?: number;
|
|
30
|
+
minValue?: number;
|
|
31
|
+
maxValue?: number;
|
|
32
|
+
pattern?: string;
|
|
33
|
+
precision?: number;
|
|
34
|
+
scale?: number;
|
|
35
|
+
}
|
|
36
|
+
interface UINodePropsBase {
|
|
37
|
+
fieldId?: string;
|
|
38
|
+
name?: string;
|
|
39
|
+
label?: string;
|
|
40
|
+
description?: string;
|
|
41
|
+
placeholder?: string;
|
|
42
|
+
required?: boolean;
|
|
43
|
+
hidden?: boolean;
|
|
44
|
+
disabled?: boolean;
|
|
45
|
+
defaultValue?: string | number | boolean | null;
|
|
46
|
+
constraints?: UINodeConstraints;
|
|
47
|
+
className?: string;
|
|
48
|
+
}
|
|
49
|
+
type UINodeProps = UINodePropsBase & Record<string, unknown>;
|
|
50
|
+
/** Prop name → template expression, e.g. `{ label: '{{ row.title }}' }`. */
|
|
51
|
+
interface UIBinding {
|
|
52
|
+
[propName: string]: string;
|
|
53
|
+
}
|
|
54
|
+
interface UIAction {
|
|
55
|
+
type: 'flow' | 'handler';
|
|
56
|
+
flowId?: string;
|
|
57
|
+
handler?: string;
|
|
58
|
+
inputMapping?: Record<string, string>;
|
|
59
|
+
params?: Record<string, unknown>;
|
|
60
|
+
}
|
|
61
|
+
/** Event name → action, e.g. `{ submit: { type: 'flow', flowId } }`. */
|
|
62
|
+
interface UIActions {
|
|
63
|
+
[eventName: string]: UIAction;
|
|
64
|
+
}
|
|
65
|
+
interface UINode {
|
|
66
|
+
type: UINodeType;
|
|
67
|
+
key: string;
|
|
68
|
+
props: UINodeProps;
|
|
69
|
+
children: UINode[];
|
|
70
|
+
bindings?: UIBinding;
|
|
71
|
+
actions?: UIActions;
|
|
72
|
+
}
|
|
73
|
+
declare function isWidgetNodeType(type: string): type is WidgetNodeType;
|
|
74
|
+
declare function isContainerNodeType(type: string): type is ContainerNodeType;
|
|
75
|
+
declare function isKnownNodeType(type: string): type is KnownNodeType;
|
|
76
|
+
declare function isWidgetNode(node: UINode): boolean;
|
|
77
|
+
declare function isContainerNode(node: UINode): boolean;
|
|
78
|
+
/** Depth-first walk over a node and its descendants. */
|
|
79
|
+
declare function walkNodes(node: UINode): Generator<UINode>;
|
|
80
|
+
/** Named fields in document order; widget nodes without a `name` are skipped. */
|
|
81
|
+
declare function collectFieldNames(node: UINode): string[];
|
|
82
|
+
/** Default values declared by widget nodes, keyed by field name. */
|
|
83
|
+
declare function collectDefaultValues(node: UINode): Record<string, unknown>;
|
|
84
|
+
interface FieldConstraintEntry {
|
|
85
|
+
constraints?: UINodeConstraints;
|
|
86
|
+
required?: boolean;
|
|
87
|
+
}
|
|
88
|
+
/** Validation metadata declared by widget nodes, keyed by field name. */
|
|
89
|
+
declare function collectFieldConstraints(node: UINode): Record<string, FieldConstraintEntry>;
|
|
90
|
+
declare function findNodeByKey(node: UINode, key: string): UINode | undefined;
|
|
91
|
+
|
|
92
|
+
declare const UI_DOCUMENT_FORMAT_VERSION = "1.0";
|
|
93
|
+
declare const UI_DOCUMENT_TYPE = "UISchema";
|
|
94
|
+
interface UIDocumentMetadata {
|
|
95
|
+
title?: string;
|
|
96
|
+
description?: string;
|
|
97
|
+
[key: string]: unknown;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* A resolution source for node types: a shadcn-style registry URL template,
|
|
101
|
+
* e.g. `https://constructive-io.github.io/blocks/r/{name}.json`.
|
|
102
|
+
*/
|
|
103
|
+
interface UIRegistrySource {
|
|
104
|
+
name: string;
|
|
105
|
+
url: string;
|
|
106
|
+
}
|
|
107
|
+
/** A named, read-only query a document's blocks can bind against. */
|
|
108
|
+
interface UIDataSource {
|
|
109
|
+
name: string;
|
|
110
|
+
table?: string;
|
|
111
|
+
query?: string;
|
|
112
|
+
variables?: Record<string, unknown>;
|
|
113
|
+
select?: string;
|
|
114
|
+
where?: Record<string, unknown>;
|
|
115
|
+
orderBy?: unknown;
|
|
116
|
+
first?: number;
|
|
117
|
+
}
|
|
118
|
+
interface UIDocument {
|
|
119
|
+
formatVersion: typeof UI_DOCUMENT_FORMAT_VERSION;
|
|
120
|
+
type: typeof UI_DOCUMENT_TYPE;
|
|
121
|
+
id: string;
|
|
122
|
+
meta?: UIDocumentMetadata;
|
|
123
|
+
registries?: UIRegistrySource[];
|
|
124
|
+
dataSources?: UIDataSource[];
|
|
125
|
+
page: UINode;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* The name the deployed dashboard form builder uses for the same envelope.
|
|
129
|
+
* Kept as an alias so existing `UISchema` consumers migrate by import swap.
|
|
130
|
+
*/
|
|
131
|
+
type UISchema = UIDocument;
|
|
132
|
+
declare function isUIDocument(value: unknown): value is UIDocument;
|
|
133
|
+
/** @deprecated Use {@link isUIDocument}. */
|
|
134
|
+
declare const isUISchema: typeof isUIDocument;
|
|
135
|
+
declare function createDocument(page: UINode, options?: {
|
|
136
|
+
id?: string;
|
|
137
|
+
meta?: UIDocumentMetadata;
|
|
138
|
+
}): UIDocument;
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* A patch applied to the node with a given `key`. Composition is per node, not
|
|
142
|
+
* per document, so a generated default can be customized in a few places
|
|
143
|
+
* without giving up generation.
|
|
144
|
+
*/
|
|
145
|
+
interface NodeOverride {
|
|
146
|
+
type?: UINodeType;
|
|
147
|
+
props?: UINodeProps;
|
|
148
|
+
bindings?: UIBinding;
|
|
149
|
+
actions?: UIActions;
|
|
150
|
+
/** Drop the node (and its subtree) from the composed document. */
|
|
151
|
+
remove?: boolean;
|
|
152
|
+
}
|
|
153
|
+
type NodeOverrides = Record<string, NodeOverride>;
|
|
154
|
+
/** Reusable subtrees addressed by `Fragment` nodes via `props.ref`. */
|
|
155
|
+
type FragmentMap = Record<string, UINode>;
|
|
156
|
+
/** Subtrees that fill `Slot` nodes, addressed by `props.name`. */
|
|
157
|
+
type SlotMap = Record<string, UINode | UINode[]>;
|
|
158
|
+
interface ComposeOptions {
|
|
159
|
+
fragments?: FragmentMap;
|
|
160
|
+
slots?: SlotMap;
|
|
161
|
+
overrides?: NodeOverrides;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Compose a document: expand `Fragment` references, fill `Slot` nodes, then
|
|
165
|
+
* apply per-node overrides. Pure — the input document is never mutated.
|
|
166
|
+
*/
|
|
167
|
+
declare function composeDocument(document: UIDocument, options?: ComposeOptions): UIDocument;
|
|
168
|
+
declare function composeNodeTree(node: UINode, options?: ComposeOptions): UINode;
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* JSON Schema for the document envelope, for agents emitting documents as tool
|
|
172
|
+
* output and for registry/editor tooling that validates without importing zod.
|
|
173
|
+
*/
|
|
174
|
+
declare function toDocumentJsonSchema(): Record<string, unknown>;
|
|
175
|
+
declare function toNodeJsonSchema(): Record<string, unknown>;
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Validate a single field value against the constraints declared on its node.
|
|
179
|
+
* Returns a human-readable message, or `null` when the value is acceptable.
|
|
180
|
+
*/
|
|
181
|
+
declare function validateField(value: unknown, constraints?: UINodeConstraints, required?: boolean): string | null;
|
|
182
|
+
|
|
183
|
+
declare const uiNodeConstraintsSchema: z.ZodObject<{
|
|
184
|
+
minLength: z.ZodOptional<z.ZodNumber>;
|
|
185
|
+
maxLength: z.ZodOptional<z.ZodNumber>;
|
|
186
|
+
minValue: z.ZodOptional<z.ZodNumber>;
|
|
187
|
+
maxValue: z.ZodOptional<z.ZodNumber>;
|
|
188
|
+
pattern: z.ZodOptional<z.ZodString>;
|
|
189
|
+
precision: z.ZodOptional<z.ZodNumber>;
|
|
190
|
+
scale: z.ZodOptional<z.ZodNumber>;
|
|
191
|
+
}, z.core.$strip>;
|
|
192
|
+
declare const uiNodePropsSchema: z.ZodObject<{
|
|
193
|
+
fieldId: z.ZodOptional<z.ZodString>;
|
|
194
|
+
name: z.ZodOptional<z.ZodString>;
|
|
195
|
+
label: z.ZodOptional<z.ZodString>;
|
|
196
|
+
description: z.ZodOptional<z.ZodString>;
|
|
197
|
+
placeholder: z.ZodOptional<z.ZodString>;
|
|
198
|
+
required: z.ZodOptional<z.ZodBoolean>;
|
|
199
|
+
hidden: z.ZodOptional<z.ZodBoolean>;
|
|
200
|
+
disabled: z.ZodOptional<z.ZodBoolean>;
|
|
201
|
+
defaultValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
|
|
202
|
+
constraints: z.ZodOptional<z.ZodObject<{
|
|
203
|
+
minLength: z.ZodOptional<z.ZodNumber>;
|
|
204
|
+
maxLength: z.ZodOptional<z.ZodNumber>;
|
|
205
|
+
minValue: z.ZodOptional<z.ZodNumber>;
|
|
206
|
+
maxValue: z.ZodOptional<z.ZodNumber>;
|
|
207
|
+
pattern: z.ZodOptional<z.ZodString>;
|
|
208
|
+
precision: z.ZodOptional<z.ZodNumber>;
|
|
209
|
+
scale: z.ZodOptional<z.ZodNumber>;
|
|
210
|
+
}, z.core.$strip>>;
|
|
211
|
+
className: z.ZodOptional<z.ZodString>;
|
|
212
|
+
}, z.core.$loose>;
|
|
213
|
+
declare const uiBindingSchema: z.ZodRecord<z.ZodString, z.ZodString>;
|
|
214
|
+
declare const uiActionSchema: z.ZodObject<{
|
|
215
|
+
type: z.ZodEnum<{
|
|
216
|
+
flow: "flow";
|
|
217
|
+
handler: "handler";
|
|
218
|
+
}>;
|
|
219
|
+
flowId: z.ZodOptional<z.ZodString>;
|
|
220
|
+
handler: z.ZodOptional<z.ZodString>;
|
|
221
|
+
inputMapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
222
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
223
|
+
}, z.core.$strip>;
|
|
224
|
+
declare const uiActionsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
|
|
225
|
+
type: z.ZodEnum<{
|
|
226
|
+
flow: "flow";
|
|
227
|
+
handler: "handler";
|
|
228
|
+
}>;
|
|
229
|
+
flowId: z.ZodOptional<z.ZodString>;
|
|
230
|
+
handler: z.ZodOptional<z.ZodString>;
|
|
231
|
+
inputMapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
232
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
233
|
+
}, z.core.$strip>>;
|
|
234
|
+
declare const uiNodeSchema: z.ZodType<UINode>;
|
|
235
|
+
declare const uiRegistrySourceSchema: z.ZodObject<{
|
|
236
|
+
name: z.ZodString;
|
|
237
|
+
url: z.ZodString;
|
|
238
|
+
}, z.core.$strip>;
|
|
239
|
+
declare const uiDataSourceSchema: z.ZodObject<{
|
|
240
|
+
name: z.ZodString;
|
|
241
|
+
table: z.ZodOptional<z.ZodString>;
|
|
242
|
+
query: z.ZodOptional<z.ZodString>;
|
|
243
|
+
variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
244
|
+
}, z.core.$loose>;
|
|
245
|
+
declare const uiDocumentMetadataSchema: z.ZodObject<{
|
|
246
|
+
title: z.ZodOptional<z.ZodString>;
|
|
247
|
+
description: z.ZodOptional<z.ZodString>;
|
|
248
|
+
}, z.core.$loose>;
|
|
249
|
+
declare const uiDocumentSchema: z.ZodType<UIDocument>;
|
|
250
|
+
/** Throws a `ZodError` describing every problem in the document. */
|
|
251
|
+
declare function parseDocument(value: unknown): UIDocument;
|
|
252
|
+
declare function safeParseDocument(value: unknown): z.ZodSafeParseResult<UIDocument>;
|
|
253
|
+
declare function parseNode(value: unknown): UINode;
|
|
254
|
+
|
|
255
|
+
export { BLOCK_NODE_TYPES, type BlockNodeType, CONTAINER_NODE_TYPES, type ComposeOptions, type ContainerNodeType, type FieldConstraintEntry, type FragmentMap, type InputType, type KnownNodeType, type NodeOverride, type NodeOverrides, type SlotMap, type UIAction, type UIActions, type UIBinding, type UIDataSource, type UIDocument, type UIDocumentMetadata, type UINode, type UINodeConstraints, type UINodeProps, type UINodePropsBase, type UINodeType, type UIRegistrySource, type UISchema, UI_DOCUMENT_FORMAT_VERSION, UI_DOCUMENT_TYPE, WIDGET_NODE_TYPES, type WidgetNodeType, collectDefaultValues, collectFieldConstraints, collectFieldNames, composeDocument, composeNodeTree, createDocument, findNodeByKey, isContainerNode, isContainerNodeType, isKnownNodeType, isUIDocument, isUISchema, isWidgetNode, isWidgetNodeType, parseDocument, parseNode, safeParseDocument, toDocumentJsonSchema, toNodeJsonSchema, uiActionSchema, uiActionsSchema, uiBindingSchema, uiDataSourceSchema, uiDocumentMetadataSchema, uiDocumentSchema, uiNodeConstraintsSchema, uiNodePropsSchema, uiNodeSchema, uiRegistrySourceSchema, validateField, walkNodes };
|