@json-render/core 0.4.4 → 0.5.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/README.md +126 -0
- package/dist/index.d.mts +366 -166
- package/dist/index.d.ts +366 -166
- package/dist/index.js +467 -56
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +459 -56
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -1,7 +1,225 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
*
|
|
4
|
+
* Confirmation dialog configuration
|
|
5
|
+
*/
|
|
6
|
+
interface ActionConfirm {
|
|
7
|
+
title: string;
|
|
8
|
+
message: string;
|
|
9
|
+
confirmLabel?: string;
|
|
10
|
+
cancelLabel?: string;
|
|
11
|
+
variant?: "default" | "danger";
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Action success handler
|
|
15
|
+
*/
|
|
16
|
+
type ActionOnSuccess = {
|
|
17
|
+
navigate: string;
|
|
18
|
+
} | {
|
|
19
|
+
set: Record<string, unknown>;
|
|
20
|
+
} | {
|
|
21
|
+
action: string;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Action error handler
|
|
25
|
+
*/
|
|
26
|
+
type ActionOnError = {
|
|
27
|
+
set: Record<string, unknown>;
|
|
28
|
+
} | {
|
|
29
|
+
action: string;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* Action binding — maps an event to an action invocation.
|
|
33
|
+
*
|
|
34
|
+
* Used inside the `on` field of a UIElement:
|
|
35
|
+
* ```json
|
|
36
|
+
* { "on": { "press": { "action": "setState", "params": { "path": "/x", "value": 1 } } } }
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
interface ActionBinding {
|
|
40
|
+
/** Action name (must be in catalog) */
|
|
41
|
+
action: string;
|
|
42
|
+
/** Parameters to pass to the action handler */
|
|
43
|
+
params?: Record<string, DynamicValue>;
|
|
44
|
+
/** Confirmation dialog before execution */
|
|
45
|
+
confirm?: ActionConfirm;
|
|
46
|
+
/** Handler after successful execution */
|
|
47
|
+
onSuccess?: ActionOnSuccess;
|
|
48
|
+
/** Handler after failed execution */
|
|
49
|
+
onError?: ActionOnError;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* @deprecated Use ActionBinding instead
|
|
53
|
+
*/
|
|
54
|
+
type Action = ActionBinding;
|
|
55
|
+
/**
|
|
56
|
+
* Schema for action confirmation
|
|
57
|
+
*/
|
|
58
|
+
declare const ActionConfirmSchema: z.ZodObject<{
|
|
59
|
+
title: z.ZodString;
|
|
60
|
+
message: z.ZodString;
|
|
61
|
+
confirmLabel: z.ZodOptional<z.ZodString>;
|
|
62
|
+
cancelLabel: z.ZodOptional<z.ZodString>;
|
|
63
|
+
variant: z.ZodOptional<z.ZodEnum<{
|
|
64
|
+
default: "default";
|
|
65
|
+
danger: "danger";
|
|
66
|
+
}>>;
|
|
67
|
+
}, z.core.$strip>;
|
|
68
|
+
/**
|
|
69
|
+
* Schema for success handlers
|
|
70
|
+
*/
|
|
71
|
+
declare const ActionOnSuccessSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
72
|
+
navigate: z.ZodString;
|
|
73
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
74
|
+
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
75
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
76
|
+
action: z.ZodString;
|
|
77
|
+
}, z.core.$strip>]>;
|
|
78
|
+
/**
|
|
79
|
+
* Schema for error handlers
|
|
80
|
+
*/
|
|
81
|
+
declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
82
|
+
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
83
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
84
|
+
action: z.ZodString;
|
|
85
|
+
}, z.core.$strip>]>;
|
|
86
|
+
/**
|
|
87
|
+
* Full action binding schema
|
|
88
|
+
*/
|
|
89
|
+
declare const ActionBindingSchema: z.ZodObject<{
|
|
90
|
+
action: z.ZodString;
|
|
91
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
|
|
92
|
+
path: z.ZodString;
|
|
93
|
+
}, z.core.$strip>]>>>;
|
|
94
|
+
confirm: z.ZodOptional<z.ZodObject<{
|
|
95
|
+
title: z.ZodString;
|
|
96
|
+
message: z.ZodString;
|
|
97
|
+
confirmLabel: z.ZodOptional<z.ZodString>;
|
|
98
|
+
cancelLabel: z.ZodOptional<z.ZodString>;
|
|
99
|
+
variant: z.ZodOptional<z.ZodEnum<{
|
|
100
|
+
default: "default";
|
|
101
|
+
danger: "danger";
|
|
102
|
+
}>>;
|
|
103
|
+
}, z.core.$strip>>;
|
|
104
|
+
onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
|
|
105
|
+
navigate: z.ZodString;
|
|
106
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
107
|
+
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
108
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
109
|
+
action: z.ZodString;
|
|
110
|
+
}, z.core.$strip>]>>;
|
|
111
|
+
onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
|
|
112
|
+
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
113
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
114
|
+
action: z.ZodString;
|
|
115
|
+
}, z.core.$strip>]>>;
|
|
116
|
+
}, z.core.$strip>;
|
|
117
|
+
/**
|
|
118
|
+
* @deprecated Use ActionBindingSchema instead
|
|
119
|
+
*/
|
|
120
|
+
declare const ActionSchema: z.ZodObject<{
|
|
121
|
+
action: z.ZodString;
|
|
122
|
+
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
|
|
123
|
+
path: z.ZodString;
|
|
124
|
+
}, z.core.$strip>]>>>;
|
|
125
|
+
confirm: z.ZodOptional<z.ZodObject<{
|
|
126
|
+
title: z.ZodString;
|
|
127
|
+
message: z.ZodString;
|
|
128
|
+
confirmLabel: z.ZodOptional<z.ZodString>;
|
|
129
|
+
cancelLabel: z.ZodOptional<z.ZodString>;
|
|
130
|
+
variant: z.ZodOptional<z.ZodEnum<{
|
|
131
|
+
default: "default";
|
|
132
|
+
danger: "danger";
|
|
133
|
+
}>>;
|
|
134
|
+
}, z.core.$strip>>;
|
|
135
|
+
onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
|
|
136
|
+
navigate: z.ZodString;
|
|
137
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
138
|
+
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
139
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
140
|
+
action: z.ZodString;
|
|
141
|
+
}, z.core.$strip>]>>;
|
|
142
|
+
onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
|
|
143
|
+
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
144
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
145
|
+
action: z.ZodString;
|
|
146
|
+
}, z.core.$strip>]>>;
|
|
147
|
+
}, z.core.$strip>;
|
|
148
|
+
/**
|
|
149
|
+
* Action handler function signature
|
|
150
|
+
*/
|
|
151
|
+
type ActionHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
|
|
152
|
+
/**
|
|
153
|
+
* Action definition in catalog
|
|
154
|
+
*/
|
|
155
|
+
interface ActionDefinition<TParams = Record<string, unknown>> {
|
|
156
|
+
/** Zod schema for params validation */
|
|
157
|
+
params?: z.ZodType<TParams>;
|
|
158
|
+
/** Description for AI */
|
|
159
|
+
description?: string;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Resolved action with all dynamic values resolved
|
|
163
|
+
*/
|
|
164
|
+
interface ResolvedAction {
|
|
165
|
+
action: string;
|
|
166
|
+
params: Record<string, unknown>;
|
|
167
|
+
confirm?: ActionConfirm;
|
|
168
|
+
onSuccess?: ActionOnSuccess;
|
|
169
|
+
onError?: ActionOnError;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Resolve all dynamic values in an action binding
|
|
173
|
+
*/
|
|
174
|
+
declare function resolveAction(binding: ActionBinding, stateModel: StateModel): ResolvedAction;
|
|
175
|
+
/**
|
|
176
|
+
* Interpolate ${path} expressions in a string
|
|
177
|
+
*/
|
|
178
|
+
declare function interpolateString(template: string, stateModel: StateModel): string;
|
|
179
|
+
/**
|
|
180
|
+
* Context for action execution
|
|
181
|
+
*/
|
|
182
|
+
interface ActionExecutionContext {
|
|
183
|
+
/** The resolved action */
|
|
184
|
+
action: ResolvedAction;
|
|
185
|
+
/** The action handler from the host */
|
|
186
|
+
handler: ActionHandler;
|
|
187
|
+
/** Function to update state model */
|
|
188
|
+
setState: (path: string, value: unknown) => void;
|
|
189
|
+
/** Function to navigate */
|
|
190
|
+
navigate?: (path: string) => void;
|
|
191
|
+
/** Function to execute another action */
|
|
192
|
+
executeAction?: (name: string) => Promise<void>;
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Execute an action with all callbacks
|
|
196
|
+
*/
|
|
197
|
+
declare function executeAction(ctx: ActionExecutionContext): Promise<void>;
|
|
198
|
+
/**
|
|
199
|
+
* Helper to create action bindings
|
|
200
|
+
*/
|
|
201
|
+
declare const actionBinding: {
|
|
202
|
+
/** Create a simple action binding */
|
|
203
|
+
simple: (actionName: string, params?: Record<string, DynamicValue>) => ActionBinding;
|
|
204
|
+
/** Create an action binding with confirmation */
|
|
205
|
+
withConfirm: (actionName: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => ActionBinding;
|
|
206
|
+
/** Create an action binding with success handler */
|
|
207
|
+
withSuccess: (actionName: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => ActionBinding;
|
|
208
|
+
};
|
|
209
|
+
/**
|
|
210
|
+
* @deprecated Use actionBinding instead
|
|
211
|
+
*/
|
|
212
|
+
declare const action: {
|
|
213
|
+
/** Create a simple action binding */
|
|
214
|
+
simple: (actionName: string, params?: Record<string, DynamicValue>) => ActionBinding;
|
|
215
|
+
/** Create an action binding with confirmation */
|
|
216
|
+
withConfirm: (actionName: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => ActionBinding;
|
|
217
|
+
/** Create an action binding with success handler */
|
|
218
|
+
withSuccess: (actionName: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => ActionBinding;
|
|
219
|
+
};
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* Dynamic value - can be a literal or a path reference to state model
|
|
5
223
|
*/
|
|
6
224
|
type DynamicValue<T = unknown> = T | {
|
|
7
225
|
path: string;
|
|
@@ -45,6 +263,13 @@ interface UIElement<T extends string = string, P = Record<string, unknown>> {
|
|
|
45
263
|
children?: string[];
|
|
46
264
|
/** Visibility condition */
|
|
47
265
|
visible?: VisibilityCondition;
|
|
266
|
+
/** Event bindings — maps event names to action bindings */
|
|
267
|
+
on?: Record<string, ActionBinding | ActionBinding[]>;
|
|
268
|
+
/** Repeat children once per item in a state array */
|
|
269
|
+
repeat?: {
|
|
270
|
+
path: string;
|
|
271
|
+
key?: string;
|
|
272
|
+
};
|
|
48
273
|
}
|
|
49
274
|
/**
|
|
50
275
|
* Element with key and parentKey for use with flatToTree.
|
|
@@ -97,6 +322,9 @@ interface Spec {
|
|
|
97
322
|
root: string;
|
|
98
323
|
/** Flat map of elements by key */
|
|
99
324
|
elements: Record<string, UIElement>;
|
|
325
|
+
/** Optional initial state to seed the state model.
|
|
326
|
+
* Components using statePath will read from / write to this state. */
|
|
327
|
+
state?: Record<string, unknown>;
|
|
100
328
|
}
|
|
101
329
|
/**
|
|
102
330
|
* Auth state for visibility evaluation
|
|
@@ -106,9 +334,9 @@ interface AuthState {
|
|
|
106
334
|
user?: Record<string, unknown>;
|
|
107
335
|
}
|
|
108
336
|
/**
|
|
109
|
-
*
|
|
337
|
+
* State model type
|
|
110
338
|
*/
|
|
111
|
-
type
|
|
339
|
+
type StateModel = Record<string, unknown>;
|
|
112
340
|
/**
|
|
113
341
|
* Component schema definition using Zod
|
|
114
342
|
*/
|
|
@@ -133,9 +361,9 @@ interface JsonPatch {
|
|
|
133
361
|
from?: string;
|
|
134
362
|
}
|
|
135
363
|
/**
|
|
136
|
-
* Resolve a dynamic value against a
|
|
364
|
+
* Resolve a dynamic value against a state model
|
|
137
365
|
*/
|
|
138
|
-
declare function resolveDynamicValue<T>(value: DynamicValue<T>,
|
|
366
|
+
declare function resolveDynamicValue<T>(value: DynamicValue<T>, stateModel: StateModel): T | undefined;
|
|
139
367
|
/**
|
|
140
368
|
* Get a value from an object by JSON Pointer path (RFC 6901)
|
|
141
369
|
*/
|
|
@@ -271,7 +499,7 @@ declare const VisibilityConditionSchema: z.ZodType<VisibilityCondition>;
|
|
|
271
499
|
* Context for evaluating visibility
|
|
272
500
|
*/
|
|
273
501
|
interface VisibilityContext {
|
|
274
|
-
|
|
502
|
+
stateModel: StateModel;
|
|
275
503
|
authState?: AuthState;
|
|
276
504
|
}
|
|
277
505
|
/**
|
|
@@ -321,171 +549,29 @@ declare const visibility: {
|
|
|
321
549
|
};
|
|
322
550
|
|
|
323
551
|
/**
|
|
324
|
-
*
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
confirmLabel?: string;
|
|
330
|
-
cancelLabel?: string;
|
|
331
|
-
variant?: "default" | "danger";
|
|
332
|
-
}
|
|
333
|
-
/**
|
|
334
|
-
* Action success handler
|
|
335
|
-
*/
|
|
336
|
-
type ActionOnSuccess = {
|
|
337
|
-
navigate: string;
|
|
338
|
-
} | {
|
|
339
|
-
set: Record<string, unknown>;
|
|
340
|
-
} | {
|
|
341
|
-
action: string;
|
|
342
|
-
};
|
|
343
|
-
/**
|
|
344
|
-
* Action error handler
|
|
552
|
+
* A prop expression that resolves to a value based on state.
|
|
553
|
+
*
|
|
554
|
+
* - `{ $path: string }` reads a value from the state model
|
|
555
|
+
* - `{ $cond, $then, $else }` conditionally picks a value
|
|
556
|
+
* - Any other value is a literal (passthrough)
|
|
345
557
|
*/
|
|
346
|
-
type
|
|
347
|
-
|
|
558
|
+
type PropExpression<T = unknown> = T | {
|
|
559
|
+
$path: string;
|
|
348
560
|
} | {
|
|
349
|
-
|
|
561
|
+
$cond: VisibilityCondition;
|
|
562
|
+
$then: PropExpression<T>;
|
|
563
|
+
$else: PropExpression<T>;
|
|
350
564
|
};
|
|
351
565
|
/**
|
|
352
|
-
*
|
|
353
|
-
|
|
354
|
-
interface Action {
|
|
355
|
-
/** Action name (must be in catalog) */
|
|
356
|
-
name: string;
|
|
357
|
-
/** Parameters to pass to the action handler */
|
|
358
|
-
params?: Record<string, DynamicValue>;
|
|
359
|
-
/** Confirmation dialog before execution */
|
|
360
|
-
confirm?: ActionConfirm;
|
|
361
|
-
/** Handler after successful execution */
|
|
362
|
-
onSuccess?: ActionOnSuccess;
|
|
363
|
-
/** Handler after failed execution */
|
|
364
|
-
onError?: ActionOnError;
|
|
365
|
-
}
|
|
366
|
-
/**
|
|
367
|
-
* Schema for action confirmation
|
|
368
|
-
*/
|
|
369
|
-
declare const ActionConfirmSchema: z.ZodObject<{
|
|
370
|
-
title: z.ZodString;
|
|
371
|
-
message: z.ZodString;
|
|
372
|
-
confirmLabel: z.ZodOptional<z.ZodString>;
|
|
373
|
-
cancelLabel: z.ZodOptional<z.ZodString>;
|
|
374
|
-
variant: z.ZodOptional<z.ZodEnum<{
|
|
375
|
-
default: "default";
|
|
376
|
-
danger: "danger";
|
|
377
|
-
}>>;
|
|
378
|
-
}, z.core.$strip>;
|
|
379
|
-
/**
|
|
380
|
-
* Schema for success handlers
|
|
566
|
+
* Resolve a single prop value that may contain expressions.
|
|
567
|
+
* Recursively resolves $path and $cond/$then/$else expressions.
|
|
381
568
|
*/
|
|
382
|
-
declare
|
|
383
|
-
navigate: z.ZodString;
|
|
384
|
-
}, z.core.$strip>, z.ZodObject<{
|
|
385
|
-
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
386
|
-
}, z.core.$strip>, z.ZodObject<{
|
|
387
|
-
action: z.ZodString;
|
|
388
|
-
}, z.core.$strip>]>;
|
|
389
|
-
/**
|
|
390
|
-
* Schema for error handlers
|
|
391
|
-
*/
|
|
392
|
-
declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
|
|
393
|
-
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
394
|
-
}, z.core.$strip>, z.ZodObject<{
|
|
395
|
-
action: z.ZodString;
|
|
396
|
-
}, z.core.$strip>]>;
|
|
569
|
+
declare function resolvePropValue(value: unknown, ctx: VisibilityContext): unknown;
|
|
397
570
|
/**
|
|
398
|
-
*
|
|
571
|
+
* Resolve all prop values in an element's props object.
|
|
572
|
+
* Returns a new props object with all expressions resolved.
|
|
399
573
|
*/
|
|
400
|
-
declare
|
|
401
|
-
name: z.ZodString;
|
|
402
|
-
params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
|
|
403
|
-
path: z.ZodString;
|
|
404
|
-
}, z.core.$strip>]>>>;
|
|
405
|
-
confirm: z.ZodOptional<z.ZodObject<{
|
|
406
|
-
title: z.ZodString;
|
|
407
|
-
message: z.ZodString;
|
|
408
|
-
confirmLabel: z.ZodOptional<z.ZodString>;
|
|
409
|
-
cancelLabel: z.ZodOptional<z.ZodString>;
|
|
410
|
-
variant: z.ZodOptional<z.ZodEnum<{
|
|
411
|
-
default: "default";
|
|
412
|
-
danger: "danger";
|
|
413
|
-
}>>;
|
|
414
|
-
}, z.core.$strip>>;
|
|
415
|
-
onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
|
|
416
|
-
navigate: z.ZodString;
|
|
417
|
-
}, z.core.$strip>, z.ZodObject<{
|
|
418
|
-
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
419
|
-
}, z.core.$strip>, z.ZodObject<{
|
|
420
|
-
action: z.ZodString;
|
|
421
|
-
}, z.core.$strip>]>>;
|
|
422
|
-
onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
|
|
423
|
-
set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
424
|
-
}, z.core.$strip>, z.ZodObject<{
|
|
425
|
-
action: z.ZodString;
|
|
426
|
-
}, z.core.$strip>]>>;
|
|
427
|
-
}, z.core.$strip>;
|
|
428
|
-
/**
|
|
429
|
-
* Action handler function signature
|
|
430
|
-
*/
|
|
431
|
-
type ActionHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
|
|
432
|
-
/**
|
|
433
|
-
* Action definition in catalog
|
|
434
|
-
*/
|
|
435
|
-
interface ActionDefinition<TParams = Record<string, unknown>> {
|
|
436
|
-
/** Zod schema for params validation */
|
|
437
|
-
params?: z.ZodType<TParams>;
|
|
438
|
-
/** Description for AI */
|
|
439
|
-
description?: string;
|
|
440
|
-
}
|
|
441
|
-
/**
|
|
442
|
-
* Resolved action with all dynamic values resolved
|
|
443
|
-
*/
|
|
444
|
-
interface ResolvedAction {
|
|
445
|
-
name: string;
|
|
446
|
-
params: Record<string, unknown>;
|
|
447
|
-
confirm?: ActionConfirm;
|
|
448
|
-
onSuccess?: ActionOnSuccess;
|
|
449
|
-
onError?: ActionOnError;
|
|
450
|
-
}
|
|
451
|
-
/**
|
|
452
|
-
* Resolve all dynamic values in an action
|
|
453
|
-
*/
|
|
454
|
-
declare function resolveAction(action: Action, dataModel: DataModel): ResolvedAction;
|
|
455
|
-
/**
|
|
456
|
-
* Interpolate ${path} expressions in a string
|
|
457
|
-
*/
|
|
458
|
-
declare function interpolateString(template: string, dataModel: DataModel): string;
|
|
459
|
-
/**
|
|
460
|
-
* Context for action execution
|
|
461
|
-
*/
|
|
462
|
-
interface ActionExecutionContext {
|
|
463
|
-
/** The resolved action */
|
|
464
|
-
action: ResolvedAction;
|
|
465
|
-
/** The action handler from the host */
|
|
466
|
-
handler: ActionHandler;
|
|
467
|
-
/** Function to update data model */
|
|
468
|
-
setData: (path: string, value: unknown) => void;
|
|
469
|
-
/** Function to navigate */
|
|
470
|
-
navigate?: (path: string) => void;
|
|
471
|
-
/** Function to execute another action */
|
|
472
|
-
executeAction?: (name: string) => Promise<void>;
|
|
473
|
-
}
|
|
474
|
-
/**
|
|
475
|
-
* Execute an action with all callbacks
|
|
476
|
-
*/
|
|
477
|
-
declare function executeAction(ctx: ActionExecutionContext): Promise<void>;
|
|
478
|
-
/**
|
|
479
|
-
* Helper to create actions
|
|
480
|
-
*/
|
|
481
|
-
declare const action: {
|
|
482
|
-
/** Create a simple action */
|
|
483
|
-
simple: (name: string, params?: Record<string, DynamicValue>) => Action;
|
|
484
|
-
/** Create an action with confirmation */
|
|
485
|
-
withConfirm: (name: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => Action;
|
|
486
|
-
/** Create an action with success handler */
|
|
487
|
-
withSuccess: (name: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => Action;
|
|
488
|
-
};
|
|
574
|
+
declare function resolveElementProps(props: Record<string, unknown>, ctx: VisibilityContext): Record<string, unknown>;
|
|
489
575
|
|
|
490
576
|
/**
|
|
491
577
|
* Validation check definition
|
|
@@ -577,7 +663,7 @@ interface ValidationContext {
|
|
|
577
663
|
/** Current value to validate */
|
|
578
664
|
value: unknown;
|
|
579
665
|
/** Full data model for resolving paths */
|
|
580
|
-
|
|
666
|
+
stateModel: StateModel;
|
|
581
667
|
/** Custom validation functions from catalog */
|
|
582
668
|
customFunctions?: Record<string, ValidationFunction>;
|
|
583
669
|
}
|
|
@@ -608,6 +694,81 @@ declare const check: {
|
|
|
608
694
|
matches: (otherPath: string, message?: string) => ValidationCheck;
|
|
609
695
|
};
|
|
610
696
|
|
|
697
|
+
/**
|
|
698
|
+
* Severity level for validation issues.
|
|
699
|
+
*/
|
|
700
|
+
type SpecIssueSeverity = "error" | "warning";
|
|
701
|
+
/**
|
|
702
|
+
* A single validation issue found in a spec.
|
|
703
|
+
*/
|
|
704
|
+
interface SpecIssue {
|
|
705
|
+
/** Severity: errors should be fixed, warnings are informational */
|
|
706
|
+
severity: SpecIssueSeverity;
|
|
707
|
+
/** Human-readable description of the issue */
|
|
708
|
+
message: string;
|
|
709
|
+
/** The element key where the issue was found (if applicable) */
|
|
710
|
+
elementKey?: string;
|
|
711
|
+
/** Machine-readable issue code for programmatic handling */
|
|
712
|
+
code: "missing_root" | "root_not_found" | "missing_child" | "visible_in_props" | "orphaned_element" | "empty_spec" | "on_in_props" | "repeat_in_props";
|
|
713
|
+
}
|
|
714
|
+
/**
|
|
715
|
+
* Result of spec structural validation.
|
|
716
|
+
*/
|
|
717
|
+
interface SpecValidationIssues {
|
|
718
|
+
/** Whether the spec passed validation (no errors; warnings are OK) */
|
|
719
|
+
valid: boolean;
|
|
720
|
+
/** List of issues found */
|
|
721
|
+
issues: SpecIssue[];
|
|
722
|
+
}
|
|
723
|
+
/**
|
|
724
|
+
* Options for validateSpec.
|
|
725
|
+
*/
|
|
726
|
+
interface ValidateSpecOptions {
|
|
727
|
+
/**
|
|
728
|
+
* Whether to check for orphaned elements (elements not reachable from root).
|
|
729
|
+
* Defaults to false since orphans are harmless (just unused).
|
|
730
|
+
*/
|
|
731
|
+
checkOrphans?: boolean;
|
|
732
|
+
}
|
|
733
|
+
/**
|
|
734
|
+
* Validate a spec for structural integrity.
|
|
735
|
+
*
|
|
736
|
+
* Checks for common AI-generation errors:
|
|
737
|
+
* - Missing or empty root
|
|
738
|
+
* - Root element not found in elements map
|
|
739
|
+
* - Children referencing non-existent elements
|
|
740
|
+
* - `visible` placed inside `props` instead of on the element
|
|
741
|
+
* - Orphaned elements (optional)
|
|
742
|
+
*
|
|
743
|
+
* @example
|
|
744
|
+
* ```ts
|
|
745
|
+
* const result = validateSpec(spec);
|
|
746
|
+
* if (!result.valid) {
|
|
747
|
+
* console.log("Spec errors:", result.issues);
|
|
748
|
+
* }
|
|
749
|
+
* ```
|
|
750
|
+
*/
|
|
751
|
+
declare function validateSpec(spec: Spec, options?: ValidateSpecOptions): SpecValidationIssues;
|
|
752
|
+
/**
|
|
753
|
+
* Auto-fix common spec issues in-place and return a corrected copy.
|
|
754
|
+
*
|
|
755
|
+
* Currently fixes:
|
|
756
|
+
* - `visible` inside `props` → moved to element level
|
|
757
|
+
* - `on` inside `props` → moved to element level
|
|
758
|
+
* - `repeat` inside `props` → moved to element level
|
|
759
|
+
*
|
|
760
|
+
* Returns the fixed spec and a list of fixes applied.
|
|
761
|
+
*/
|
|
762
|
+
declare function autoFixSpec(spec: Spec): {
|
|
763
|
+
spec: Spec;
|
|
764
|
+
fixes: string[];
|
|
765
|
+
};
|
|
766
|
+
/**
|
|
767
|
+
* Format validation issues into a human-readable string suitable for
|
|
768
|
+
* inclusion in a repair prompt sent back to the AI.
|
|
769
|
+
*/
|
|
770
|
+
declare function formatSpecIssues(issues: SpecIssue[]): string;
|
|
771
|
+
|
|
611
772
|
/**
|
|
612
773
|
* Schema builder primitives
|
|
613
774
|
*/
|
|
@@ -664,6 +825,8 @@ interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
|
|
|
664
825
|
readonly definition: TDef;
|
|
665
826
|
/** Custom prompt template for this schema */
|
|
666
827
|
readonly promptTemplate?: PromptTemplate;
|
|
828
|
+
/** Default rules baked into the schema (injected before customRules) */
|
|
829
|
+
readonly defaultRules?: string[];
|
|
667
830
|
/** Create a catalog from this schema */
|
|
668
831
|
createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog$1<TDef, TCatalog>;
|
|
669
832
|
}
|
|
@@ -724,6 +887,8 @@ type PromptTemplate<TCatalog = unknown> = (context: PromptContext<TCatalog>) =>
|
|
|
724
887
|
interface SchemaOptions<TCatalog = unknown> {
|
|
725
888
|
/** Custom prompt template for this schema */
|
|
726
889
|
promptTemplate?: PromptTemplate<TCatalog>;
|
|
890
|
+
/** Default rules baked into the schema (injected before customRules in prompts) */
|
|
891
|
+
defaultRules?: string[];
|
|
727
892
|
}
|
|
728
893
|
/**
|
|
729
894
|
* Spec validation result
|
|
@@ -802,6 +967,41 @@ declare function defineSchema<TDef extends SchemaDefinition>(builder: (s: Schema
|
|
|
802
967
|
*/
|
|
803
968
|
declare function defineCatalog<TDef extends SchemaDefinition, TCatalog extends InferCatalogInput<TDef["catalog"]>>(schema: Schema<TDef>, catalog: TCatalog): Catalog$1<TDef, TCatalog>;
|
|
804
969
|
|
|
970
|
+
/**
|
|
971
|
+
* Options for building a user prompt.
|
|
972
|
+
*/
|
|
973
|
+
interface UserPromptOptions {
|
|
974
|
+
/** The user's text prompt */
|
|
975
|
+
prompt: string;
|
|
976
|
+
/** Existing spec to refine (triggers patch-only mode) */
|
|
977
|
+
currentSpec?: Spec | null;
|
|
978
|
+
/** Runtime state context to include */
|
|
979
|
+
state?: Record<string, unknown> | null;
|
|
980
|
+
/** Maximum length for the user's text prompt (applied before wrapping) */
|
|
981
|
+
maxPromptLength?: number;
|
|
982
|
+
}
|
|
983
|
+
/**
|
|
984
|
+
* Build a user prompt for AI generation.
|
|
985
|
+
*
|
|
986
|
+
* Handles common patterns that every consuming app needs:
|
|
987
|
+
* - Truncating the user's prompt to a max length
|
|
988
|
+
* - Including the current spec for refinement (patch-only mode)
|
|
989
|
+
* - Including runtime state context
|
|
990
|
+
*
|
|
991
|
+
* @example
|
|
992
|
+
* ```ts
|
|
993
|
+
* // Fresh generation
|
|
994
|
+
* buildUserPrompt({ prompt: "create a todo app" })
|
|
995
|
+
*
|
|
996
|
+
* // Refinement with existing spec
|
|
997
|
+
* buildUserPrompt({ prompt: "add a dark mode toggle", currentSpec: spec })
|
|
998
|
+
*
|
|
999
|
+
* // With state context
|
|
1000
|
+
* buildUserPrompt({ prompt: "show my data", state: { todos: [] } })
|
|
1001
|
+
* ```
|
|
1002
|
+
*/
|
|
1003
|
+
declare function buildUserPrompt(options: UserPromptOptions): string;
|
|
1004
|
+
|
|
805
1005
|
/**
|
|
806
1006
|
* Component definition with visibility and validation support
|
|
807
1007
|
*/
|
|
@@ -900,4 +1100,4 @@ interface SystemPromptOptions {
|
|
|
900
1100
|
*/
|
|
901
1101
|
declare function generateSystemPrompt<TComponents extends Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction>>(catalog: Catalog<TComponents, TActions, TFunctions>, options?: SystemPromptOptions): string;
|
|
902
1102
|
|
|
903
|
-
export { type Action, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog$1 as Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type
|
|
1103
|
+
export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog$1 as Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type InferActionParams, type InferCatalogActions, type InferCatalogComponentProps, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonPatch, type Catalog as LegacyCatalog, type LogicExpression, LogicExpressionSchema, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type ResolvedAction, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type Spec, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateModel, type SystemPromptOptions, type UIElement, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, actionBinding, addByPath, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createCatalog, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateLogicExpression, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, generateCatalogPrompt, generateSystemPrompt, getByPath, interpolateString, parseSpecStreamLine, removeByPath, resolveAction, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };
|