@json-render/core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -85,7 +85,7 @@ type LogicExpression = {
 /**
  * Flat UI tree structure (optimized for LLM generation)
  */
-interface UITree {
+interface Spec {
     /** Root element key */
     root: string;
     /** Flat map of elements by key */
@@ -131,9 +131,106 @@ declare function resolveDynamicValue<T>(value: DynamicValue<T>, dataModel: DataM
  */
 declare function getByPath(obj: unknown, path: string): unknown;
 /**
- * Set a value in an object by JSON Pointer path
+ * Set a value in an object by JSON Pointer path.
+ * Automatically creates arrays when the path segment is a numeric index.
  */
 declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Find a form value from params and/or data.
+ * Useful in action handlers to locate form input values regardless of path format.
+ *
+ * Checks in order:
+ * 1. Direct param key (if not a path reference)
+ * 2. Param keys ending with the field name
+ * 3. Data keys ending with the field name (dot notation)
+ * 4. Data paths using getByPath (slash notation)
+ *
+ * @example
+ * // Find "name" from params or data
+ * const name = findFormValue("name", params, data);
+ *
+ * // Will find from: params.name, params["form.name"], data["customerForm.name"], data.customerForm.name
+ */
+declare function findFormValue(fieldName: string, params?: Record<string, unknown>, data?: Record<string, unknown>): unknown;
+/**
+ * A SpecStream line - a single patch operation in the stream.
+ */
+type SpecStreamLine = JsonPatch;
+/**
+ * Parse a single SpecStream line into a patch operation.
+ * Returns null if the line is invalid or empty.
+ *
+ * SpecStream is json-render's streaming format where each line is a JSON patch
+ * operation that progressively builds up the final spec.
+ */
+declare function parseSpecStreamLine(line: string): SpecStreamLine | null;
+/**
+ * Apply a single SpecStream patch to an object.
+ * Mutates the object in place.
+ */
+declare function applySpecStreamPatch<T extends Record<string, unknown>>(obj: T, patch: SpecStreamLine): T;
+/**
+ * Compile a SpecStream string into a JSON object.
+ * Each line should be a patch operation.
+ *
+ * @example
+ * const stream = `{"op":"set","path":"/name","value":"Alice"}
+ * {"op":"set","path":"/age","value":30}`;
+ * const result = compileSpecStream(stream);
+ * // { name: "Alice", age: 30 }
+ */
+declare function compileSpecStream<T extends Record<string, unknown> = Record<string, unknown>>(stream: string, initial?: T): T;
+/**
+ * Streaming SpecStream compiler.
+ * Useful for processing SpecStream data as it streams in from AI.
+ *
+ * @example
+ * const compiler = createSpecStreamCompiler<MySpec>();
+ *
+ * // As chunks arrive:
+ * const { result, newPatches } = compiler.push(chunk);
+ * if (newPatches.length > 0) {
+ *   updateUI(result);
+ * }
+ *
+ * // When done:
+ * const finalResult = compiler.getResult();
+ */
+interface SpecStreamCompiler<T> {
+    /** Push a chunk of text. Returns the current result and any new patches applied. */
+    push(chunk: string): {
+        result: T;
+        newPatches: SpecStreamLine[];
+    };
+    /** Get the current compiled result */
+    getResult(): T;
+    /** Get all patches that have been applied */
+    getPatches(): SpecStreamLine[];
+    /** Reset the compiler to initial state */
+    reset(initial?: Partial<T>): void;
+}
+/**
+ * Create a streaming SpecStream compiler.
+ *
+ * SpecStream is json-render's streaming format. AI outputs patch operations
+ * line by line, and this compiler progressively builds the final spec.
+ *
+ * @example
+ * const compiler = createSpecStreamCompiler<TimelineSpec>();
+ *
+ * // Process streaming response
+ * const reader = response.body.getReader();
+ * while (true) {
+ *   const { done, value } = await reader.read();
+ *   if (done) break;
+ *
+ *   const { result, newPatches } = compiler.push(decoder.decode(value));
+ *   if (newPatches.length > 0) {
+ *     setSpec(result); // Update UI with partial result
+ *   }
+ * }
+ */
+declare function createSpecStreamCompiler<T = Record<string, unknown>>(initial?: Partial<T>): SpecStreamCompiler<T>;
 
 /**
  * Logic expression schema (recursive)
@@ -485,6 +582,200 @@ declare const check: {
     matches: (otherPath: string, message?: string) => ValidationCheck;
 };
 
+/**
+ * Schema builder primitives
+ */
+interface SchemaBuilder {
+    /** String type */
+    string(): SchemaType<"string">;
+    /** Number type */
+    number(): SchemaType<"number">;
+    /** Boolean type */
+    boolean(): SchemaType<"boolean">;
+    /** Array of type */
+    array<T extends SchemaType>(item: T): SchemaType<"array", T>;
+    /** Object with shape */
+    object<T extends Record<string, SchemaType>>(shape: T): SchemaType<"object", T>;
+    /** Record/map with value type */
+    record<T extends SchemaType>(value: T): SchemaType<"record", T>;
+    /** Any type */
+    any(): SchemaType<"any">;
+    /** Placeholder for user-provided Zod schema */
+    zod(): SchemaType<"zod">;
+    /** Reference to catalog key (e.g., 'catalog.components') */
+    ref(path: string): SchemaType<"ref", string>;
+    /** Props from referenced catalog entry */
+    propsOf(path: string): SchemaType<"propsOf", string>;
+    /** Map of named entries with shared shape */
+    map<T extends Record<string, SchemaType>>(entryShape: T): SchemaType<"map", T>;
+    /** Optional modifier */
+    optional(): {
+        optional: true;
+    };
+}
+/**
+ * Schema type representation
+ */
+interface SchemaType<TKind extends string = string, TInner = unknown> {
+    kind: TKind;
+    inner?: TInner;
+    optional?: boolean;
+}
+/**
+ * Schema definition shape
+ */
+interface SchemaDefinition<TSpec extends SchemaType = SchemaType, TCatalog extends SchemaType = SchemaType> {
+    /** What the AI-generated spec looks like */
+    spec: TSpec;
+    /** What the catalog must provide */
+    catalog: TCatalog;
+}
+/**
+ * Schema instance with methods
+ */
+interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
+    /** The schema definition */
+    readonly definition: TDef;
+    /** Custom prompt template for this schema */
+    readonly promptTemplate?: PromptTemplate;
+    /** Create a catalog from this schema */
+    createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog$1<TDef, TCatalog>;
+}
+/**
+ * Catalog instance with methods
+ */
+interface Catalog$1<TDef extends SchemaDefinition = SchemaDefinition, TCatalog = unknown> {
+    /** The schema this catalog is based on */
+    readonly schema: Schema<TDef>;
+    /** The catalog data */
+    readonly data: TCatalog;
+    /** Component names */
+    readonly componentNames: string[];
+    /** Action names */
+    readonly actionNames: string[];
+    /** Generate system prompt for AI */
+    prompt(options?: PromptOptions): string;
+    /** Export as JSON Schema for structured outputs */
+    jsonSchema(): object;
+    /** Validate a spec against this catalog */
+    validate(spec: unknown): SpecValidationResult<InferSpec<TDef, TCatalog>>;
+    /** Get the Zod schema for the spec */
+    zodSchema(): z.ZodType<InferSpec<TDef, TCatalog>>;
+    /** Type helper for the spec type */
+    readonly _specType: InferSpec<TDef, TCatalog>;
+}
+/**
+ * Prompt generation options
+ */
+interface PromptOptions {
+    /** Custom system message intro */
+    system?: string;
+    /** Additional rules to append */
+    customRules?: string[];
+}
+/**
+ * Context provided to prompt templates
+ */
+interface PromptContext<TCatalog = unknown> {
+    /** The catalog data */
+    catalog: TCatalog;
+    /** Component names from the catalog */
+    componentNames: string[];
+    /** Action names from the catalog (if any) */
+    actionNames: string[];
+    /** Prompt options provided by the user */
+    options: PromptOptions;
+    /** Helper to format a Zod type as a human-readable string */
+    formatZodType: (schema: z.ZodType) => string;
+}
+/**
+ * Prompt template function type
+ */
+type PromptTemplate<TCatalog = unknown> = (context: PromptContext<TCatalog>) => string;
+/**
+ * Schema options
+ */
+interface SchemaOptions<TCatalog = unknown> {
+    /** Custom prompt template for this schema */
+    promptTemplate?: PromptTemplate<TCatalog>;
+}
+/**
+ * Spec validation result
+ */
+interface SpecValidationResult<T> {
+    success: boolean;
+    data?: T;
+    error?: z.ZodError;
+}
+/**
+ * Extract the components map type from a catalog
+ * @example type Components = InferCatalogComponents<typeof myCatalog>;
+ */
+type InferCatalogComponents<C extends Catalog$1> = C extends Catalog$1<SchemaDefinition, infer TCatalog> ? TCatalog extends {
+    components: infer Comps;
+} ? Comps : never : never;
+/**
+ * Extract the actions map type from a catalog
+ * @example type Actions = InferCatalogActions<typeof myCatalog>;
+ */
+type InferCatalogActions<C extends Catalog$1> = C extends Catalog$1<SchemaDefinition, infer TCatalog> ? TCatalog extends {
+    actions: infer Acts;
+} ? Acts : never : never;
+/**
+ * Infer component props from a catalog by component name
+ * @example type ButtonProps = InferComponentProps<typeof myCatalog, 'Button'>;
+ */
+type InferComponentProps<C extends Catalog$1, K extends keyof InferCatalogComponents<C>> = InferCatalogComponents<C>[K] extends {
+    props: z.ZodType<infer P>;
+} ? P : never;
+/**
+ * Infer action params from a catalog by action name
+ * @example type ViewCustomersParams = InferActionParams<typeof myCatalog, 'viewCustomers'>;
+ */
+type InferActionParams<C extends Catalog$1, K extends keyof InferCatalogActions<C>> = InferCatalogActions<C>[K] extends {
+    params: z.ZodType<infer P>;
+} ? P : never;
+type InferCatalogInput<T> = T extends SchemaType<"object", infer Shape> ? {
+    [K in keyof Shape]: InferCatalogField<Shape[K]>;
+} : never;
+type InferCatalogField<T> = T extends SchemaType<"map", infer EntryShape> ? Record<string, InferMapEntryRequired<EntryShape> & Partial<InferMapEntryOptional<EntryShape>>> : T extends SchemaType<"zod"> ? z.ZodType : T extends SchemaType<"string"> ? string : T extends SchemaType<"number"> ? number : T extends SchemaType<"boolean"> ? boolean : T extends SchemaType<"array", infer Item> ? InferCatalogField<Item>[] : T extends SchemaType<"object", infer Shape> ? {
+    [K in keyof Shape]: InferCatalogField<Shape[K]>;
+} : unknown;
+type InferMapEntryRequired<T> = {
+    [K in keyof T as K extends "props" ? K : never]: InferMapEntryField<T[K]>;
+};
+type InferMapEntryOptional<T> = {
+    [K in keyof T as K extends "props" ? never : K]: InferMapEntryField<T[K]>;
+};
+type InferMapEntryField<T> = T extends SchemaType<"zod"> ? z.ZodType : T extends SchemaType<"string"> ? string : T extends SchemaType<"number"> ? number : T extends SchemaType<"boolean"> ? boolean : T extends SchemaType<"array", infer Item> ? InferMapEntryField<Item>[] : T extends SchemaType<"object", infer Shape> ? {
+    [K in keyof Shape]: InferMapEntryField<Shape[K]>;
+} : unknown;
+type InferSpec<TDef extends SchemaDefinition, TCatalog> = TDef extends {
+    spec: SchemaType<"object", infer Shape>;
+} ? InferSpecObject<Shape, TCatalog> : unknown;
+type InferSpecObject<Shape, TCatalog> = {
+    [K in keyof Shape]: InferSpecField<Shape[K], TCatalog>;
+};
+type InferSpecField<T, TCatalog> = T extends SchemaType<"string"> ? string : T extends SchemaType<"number"> ? number : T extends SchemaType<"boolean"> ? boolean : T extends SchemaType<"array", infer Item> ? InferSpecField<Item, TCatalog>[] : T extends SchemaType<"object", infer Shape> ? InferSpecObject<Shape, TCatalog> : T extends SchemaType<"record", infer Value> ? Record<string, InferSpecField<Value, TCatalog>> : T extends SchemaType<"ref", infer Path> ? InferRefType<Path, TCatalog> : T extends SchemaType<"propsOf", infer Path> ? InferPropsOfType<Path, TCatalog> : T extends SchemaType<"any"> ? unknown : unknown;
+type InferRefType<Path, TCatalog> = Path extends "catalog.components" ? TCatalog extends {
+    components: infer C;
+} ? keyof C : string : Path extends "catalog.actions" ? TCatalog extends {
+    actions: infer A;
+} ? keyof A : string : string;
+type InferPropsOfType<Path, TCatalog> = Path extends "catalog.components" ? TCatalog extends {
+    components: infer C;
+} ? C extends Record<string, {
+    props: z.ZodType<infer P>;
+}> ? P : Record<string, unknown> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Define a schema using the builder pattern
+ */
+declare function defineSchema<TDef extends SchemaDefinition>(builder: (s: SchemaBuilder) => TDef, options?: SchemaOptions): Schema<TDef>;
+/**
+ * Shorthand: Define a catalog directly from a schema
+ */
+declare function defineCatalog<TDef extends SchemaDefinition, TCatalog extends InferCatalogInput<TDef["catalog"]>>(schema: Schema<TDef>, catalog: TCatalog): Catalog$1<TDef, TCatalog>;
+
 /**
  * Component definition with visibility and validation support
  */
@@ -533,8 +824,8 @@ interface Catalog<TComponents extends Record<string, ComponentDefinition> = Reco
     readonly functions: TFunctions;
     /** Full element schema for AI generation */
     readonly elementSchema: z.ZodType<UIElement>;
-    /** Full UI tree schema */
-    readonly treeSchema: z.ZodType<UITree>;
+    /** Full UI spec schema */
+    readonly specSchema: z.ZodType<Spec>;
     /** Check if component exists */
     hasComponent(type: string): boolean;
     /** Check if action exists */
@@ -547,10 +838,10 @@ interface Catalog<TComponents extends Record<string, ComponentDefinition> = Reco
         data?: UIElement;
         error?: z.ZodError;
     };
-    /** Validate a UI tree */
-    validateTree(tree: unknown): {
+    /** Validate a UI spec */
+    validateSpec(spec: unknown): {
         success: boolean;
-        data?: UITree;
+        data?: Spec;
         error?: z.ZodError;
     };
 }
@@ -568,5 +859,19 @@ declare function generateCatalogPrompt<TComponents extends Record<string, Compon
 type InferCatalogComponentProps<C extends Catalog<Record<string, ComponentDefinition>>> = {
     [K in keyof C["components"]]: z.infer<C["components"][K]["props"]>;
 };
+/**
+ * Options for generating system prompts
+ */
+interface SystemPromptOptions {
+    /** System message intro (replaces default) */
+    system?: string;
+    /** Additional rules to append to the rules section */
+    customRules?: string[];
+}
+/**
+ * Generate a complete system prompt for AI that can generate UI from a catalog.
+ * This produces a ready-to-use prompt that stays in sync with the catalog definition.
+ */
+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;
 
-export { type Action, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type DataModel, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type InferCatalogComponentProps, type JsonPatch, type LogicExpression, LogicExpressionSchema, type PatchOp, type ResolvedAction, type UIElement, type UITree, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, builtInValidationFunctions, check, createCatalog, evaluateLogicExpression, evaluateVisibility, executeAction, generateCatalogPrompt, getByPath, interpolateString, resolveAction, resolveDynamicValue, runValidation, runValidationCheck, setByPath, visibility };
+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 DataModel, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, 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 ResolvedAction, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type Spec, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationResult, type SystemPromptOptions, type UIElement, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, applySpecStreamPatch, builtInValidationFunctions, check, compileSpecStream, createCatalog, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateLogicExpression, evaluateVisibility, executeAction, findFormValue, generateCatalogPrompt, generateSystemPrompt, getByPath, interpolateString, parseSpecStreamLine, resolveAction, resolveDynamicValue, runValidation, runValidationCheck, setByPath, visibility };