@json-render/core - npm Package Compare versions

Comparing version 0.13.0 to 0.14.0

dist/index.d.mts

@@ -1,3 +0,3 @@
-import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec } from './store-utils-D98Czbil.mjs';
-export { Y as Action, X as ActionBinding, a4 as ActionBindingSchema, Z as ActionConfirm, a6 as ActionConfirmSchema, a1 as ActionDefinition, a3 as ActionExecutionContext, a0 as ActionHandler, $ as ActionOnError, a8 as ActionOnErrorSchema, _ as ActionOnSuccess, a7 as ActionOnSuccessSchema, a5 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, J as JsonPatch, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, a2 as ResolvedAction, Q as SPEC_DATA_PART, R as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, T as StoreAdapterConfig, m as StreamChunk, U as UIElement, i as ValidationMode, ad as action, ac as actionBinding, v as addByPath, B as applySpecPatch, z as applySpecStreamPatch, G as compileSpecStream, L as createJsonRenderTransform, K as createMixedStreamParser, H as createSpecStreamCompiler, W as createStateStore, aa as executeAction, x as findFormValue, t as getByPath, ab as interpolateString, E as nestedToFlat, y as parseSpecStreamLine, N as pipeJsonRender, w as removeByPath, a9 as resolveAction, s as resolveDynamicValue, u as setByPath } from './store-utils-D98Czbil.mjs';
+import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec, J as JsonPatch } from './store-utils-D98Czbil.mjs';
+export { Y as Action, X as ActionBinding, a4 as ActionBindingSchema, Z as ActionConfirm, a6 as ActionConfirmSchema, a1 as ActionDefinition, a3 as ActionExecutionContext, a0 as ActionHandler, $ as ActionOnError, a8 as ActionOnErrorSchema, _ as ActionOnSuccess, a7 as ActionOnSuccessSchema, a5 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, a2 as ResolvedAction, Q as SPEC_DATA_PART, R as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, T as StoreAdapterConfig, m as StreamChunk, U as UIElement, i as ValidationMode, ad as action, ac as actionBinding, v as addByPath, B as applySpecPatch, z as applySpecStreamPatch, G as compileSpecStream, L as createJsonRenderTransform, K as createMixedStreamParser, H as createSpecStreamCompiler, W as createStateStore, aa as executeAction, x as findFormValue, t as getByPath, ab as interpolateString, E as nestedToFlat, y as parseSpecStreamLine, N as pipeJsonRender, w as removeByPath, a9 as resolveAction, s as resolveDynamicValue, u as setByPath } from './store-utils-D98Czbil.mjs';
 import { z } from 'zod';
@@ -369,2 +369,35 @@
 /**
+ * Edit mode for modifying an existing spec.
+ *
+ * - `"patch"` — RFC 6902 JSON Patch. One operation per line.
+ * - `"merge"` — RFC 7396 JSON Merge Patch. Partial object deep-merged; `null` deletes.
+ * - `"diff"`  — Unified diff (POSIX). Line-level text edits against the serialized spec.
+ */
+type EditMode = "patch" | "merge" | "diff";
+interface EditConfig {
+    /** Which edit modes are enabled. When >1, the AI chooses per edit. */
+    modes: EditMode[];
+}
+/**
+ * Generate the prompt section describing available edit modes.
+ * Only documents the modes that are enabled.
+ */
+declare function buildEditInstructions(config: EditConfig | undefined, format: "json" | "yaml"): string;
+declare function isNonEmptySpec(spec: unknown): spec is Spec;
+interface BuildEditUserPromptOptions {
+    prompt: string;
+    currentSpec?: Spec | null;
+    config?: EditConfig;
+    format: "json" | "yaml";
+    maxPromptLength?: number;
+    /** Serialise the spec. Defaults to JSON.stringify for json, must be provided for yaml. */
+    serializer?: (spec: Spec) => string;
+}
+/**
+ * Generate the user prompt for edits, including the current spec
+ * (with line numbers when diff mode is enabled) and mode instructions.
+ */
+declare function buildEditUserPrompt(options: BuildEditUserPromptOptions): string;
+
+/**
  * Schema builder primitives
@@ -495,2 +528,4 @@ */
     mode?: "standalone" | "inline" | "generate" | "chat";
+    /** Edit modes to document in the system prompt. Default: `["patch"]`. */
+    editModes?: EditMode[];
 }
@@ -632,2 +667,4 @@ /**
     maxPromptLength?: number;
+    /** Edit modes to offer when refining an existing spec. Default: `["patch"]`. */
+    editModes?: EditMode[];
 }
@@ -639,3 +676,3 @@ /**
  * - Truncating the user's prompt to a max length
- * - Including the current spec for refinement (patch-only mode)
+ * - Including the current spec for refinement (edit mode)
  * - Including runtime state context
@@ -651,4 +688,4 @@ *
  *
- * // With state context
- * buildUserPrompt({ prompt: "show my data", state: { todos: [] } })
+ * // With multiple edit modes
+ * buildUserPrompt({ prompt: "change title", currentSpec: spec, editModes: ["patch", "merge"] })
  * ```
@@ -658,2 +695,26 @@ */
 
-export { AndCondition, type BuiltInAction, type Catalog, type ComputedFunction, DynamicValue, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonSchemaOptions, OrCondition, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, Spec, type SpecIssue, type SpecIssueSeverity, type SpecValidationIssues, type SpecValidationResult, StateCondition, StateModel, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationResult, VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, defineCatalog, defineSchema, evaluateVisibility, formatSpecIssues, resolveActionParam, resolveBindings, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, validateSpec, visibility };
+/**
+ * Deep-merge `patch` into `base`, returning a new object.
+ *
+ * Semantics (RFC 7396 JSON Merge Patch):
+ * - `null` values in `patch` delete the corresponding key from `base`
+ * - Arrays in `patch` replace (not concat) the corresponding array in `base`
+ * - Plain objects recurse
+ * - All other values replace
+ *
+ * Neither `base` nor `patch` is mutated.
+ */
+declare function deepMergeSpec(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Produce RFC 6902 JSON Patch operations that transform `oldObj` into `newObj`.
+ *
+ * - New keys → `add`
+ * - Changed scalar/array values → `replace`
+ * - Removed keys → `remove`
+ * - Arrays are compared shallowly and replaced atomically (not element-diffed)
+ * - Plain objects recurse
+ */
+declare function diffToPatches(oldObj: Record<string, unknown>, newObj: Record<string, unknown>, basePath?: string): JsonPatch[];
+
+export { AndCondition, type BuildEditUserPromptOptions, type BuiltInAction, type Catalog, type ComputedFunction, DynamicValue, type EditConfig, type EditMode, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, JsonPatch, type JsonSchemaOptions, OrCondition, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, Spec, type SpecIssue, type SpecIssueSeverity, type SpecValidationIssues, type SpecValidationResult, StateCondition, StateModel, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationResult, VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, autoFixSpec, buildEditInstructions, buildEditUserPrompt, buildUserPrompt, builtInValidationFunctions, check, deepMergeSpec, defineCatalog, defineSchema, diffToPatches, evaluateVisibility, formatSpecIssues, isNonEmptySpec, resolveActionParam, resolveBindings, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, validateSpec, visibility };

dist/index.d.ts

@@ -1,3 +0,3 @@
-import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec } from './store-utils-D98Czbil.js';
-export { Y as Action, X as ActionBinding, a4 as ActionBindingSchema, Z as ActionConfirm, a6 as ActionConfirmSchema, a1 as ActionDefinition, a3 as ActionExecutionContext, a0 as ActionHandler, $ as ActionOnError, a8 as ActionOnErrorSchema, _ as ActionOnSuccess, a7 as ActionOnSuccessSchema, a5 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, J as JsonPatch, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, a2 as ResolvedAction, Q as SPEC_DATA_PART, R as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, T as StoreAdapterConfig, m as StreamChunk, U as UIElement, i as ValidationMode, ad as action, ac as actionBinding, v as addByPath, B as applySpecPatch, z as applySpecStreamPatch, G as compileSpecStream, L as createJsonRenderTransform, K as createMixedStreamParser, H as createSpecStreamCompiler, W as createStateStore, aa as executeAction, x as findFormValue, t as getByPath, ab as interpolateString, E as nestedToFlat, y as parseSpecStreamLine, N as pipeJsonRender, w as removeByPath, a9 as resolveAction, s as resolveDynamicValue, u as setByPath } from './store-utils-D98Czbil.js';
+import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec, J as JsonPatch } from './store-utils-D98Czbil.js';
+export { Y as Action, X as ActionBinding, a4 as ActionBindingSchema, Z as ActionConfirm, a6 as ActionConfirmSchema, a1 as ActionDefinition, a3 as ActionExecutionContext, a0 as ActionHandler, $ as ActionOnError, a8 as ActionOnErrorSchema, _ as ActionOnSuccess, a7 as ActionOnSuccessSchema, a5 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, a2 as ResolvedAction, Q as SPEC_DATA_PART, R as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, T as StoreAdapterConfig, m as StreamChunk, U as UIElement, i as ValidationMode, ad as action, ac as actionBinding, v as addByPath, B as applySpecPatch, z as applySpecStreamPatch, G as compileSpecStream, L as createJsonRenderTransform, K as createMixedStreamParser, H as createSpecStreamCompiler, W as createStateStore, aa as executeAction, x as findFormValue, t as getByPath, ab as interpolateString, E as nestedToFlat, y as parseSpecStreamLine, N as pipeJsonRender, w as removeByPath, a9 as resolveAction, s as resolveDynamicValue, u as setByPath } from './store-utils-D98Czbil.js';
 import { z } from 'zod';
@@ -369,2 +369,35 @@
 /**
+ * Edit mode for modifying an existing spec.
+ *
+ * - `"patch"` — RFC 6902 JSON Patch. One operation per line.
+ * - `"merge"` — RFC 7396 JSON Merge Patch. Partial object deep-merged; `null` deletes.
+ * - `"diff"`  — Unified diff (POSIX). Line-level text edits against the serialized spec.
+ */
+type EditMode = "patch" | "merge" | "diff";
+interface EditConfig {
+    /** Which edit modes are enabled. When >1, the AI chooses per edit. */
+    modes: EditMode[];
+}
+/**
+ * Generate the prompt section describing available edit modes.
+ * Only documents the modes that are enabled.
+ */
+declare function buildEditInstructions(config: EditConfig | undefined, format: "json" | "yaml"): string;
+declare function isNonEmptySpec(spec: unknown): spec is Spec;
+interface BuildEditUserPromptOptions {
+    prompt: string;
+    currentSpec?: Spec | null;
+    config?: EditConfig;
+    format: "json" | "yaml";
+    maxPromptLength?: number;
+    /** Serialise the spec. Defaults to JSON.stringify for json, must be provided for yaml. */
+    serializer?: (spec: Spec) => string;
+}
+/**
+ * Generate the user prompt for edits, including the current spec
+ * (with line numbers when diff mode is enabled) and mode instructions.
+ */
+declare function buildEditUserPrompt(options: BuildEditUserPromptOptions): string;
+
+/**
  * Schema builder primitives
@@ -495,2 +528,4 @@ */
     mode?: "standalone" | "inline" | "generate" | "chat";
+    /** Edit modes to document in the system prompt. Default: `["patch"]`. */
+    editModes?: EditMode[];
 }
@@ -632,2 +667,4 @@ /**
     maxPromptLength?: number;
+    /** Edit modes to offer when refining an existing spec. Default: `["patch"]`. */
+    editModes?: EditMode[];
 }
@@ -639,3 +676,3 @@ /**
  * - Truncating the user's prompt to a max length
- * - Including the current spec for refinement (patch-only mode)
+ * - Including the current spec for refinement (edit mode)
  * - Including runtime state context
@@ -651,4 +688,4 @@ *
  *
- * // With state context
- * buildUserPrompt({ prompt: "show my data", state: { todos: [] } })
+ * // With multiple edit modes
+ * buildUserPrompt({ prompt: "change title", currentSpec: spec, editModes: ["patch", "merge"] })
  * ```
@@ -658,2 +695,26 @@ */
 
-export { AndCondition, type BuiltInAction, type Catalog, type ComputedFunction, DynamicValue, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonSchemaOptions, OrCondition, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, Spec, type SpecIssue, type SpecIssueSeverity, type SpecValidationIssues, type SpecValidationResult, StateCondition, StateModel, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationResult, VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, defineCatalog, defineSchema, evaluateVisibility, formatSpecIssues, resolveActionParam, resolveBindings, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, validateSpec, visibility };
+/**
+ * Deep-merge `patch` into `base`, returning a new object.
+ *
+ * Semantics (RFC 7396 JSON Merge Patch):
+ * - `null` values in `patch` delete the corresponding key from `base`
+ * - Arrays in `patch` replace (not concat) the corresponding array in `base`
+ * - Plain objects recurse
+ * - All other values replace
+ *
+ * Neither `base` nor `patch` is mutated.
+ */
+declare function deepMergeSpec(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Produce RFC 6902 JSON Patch operations that transform `oldObj` into `newObj`.
+ *
+ * - New keys → `add`
+ * - Changed scalar/array values → `replace`
+ * - Removed keys → `remove`
+ * - Arrays are compared shallowly and replaced atomically (not element-diffed)
+ * - Plain objects recurse
+ */
+declare function diffToPatches(oldObj: Record<string, unknown>, newObj: Record<string, unknown>, basePath?: string): JsonPatch[];
+
+export { AndCondition, type BuildEditUserPromptOptions, type BuiltInAction, type Catalog, type ComputedFunction, DynamicValue, type EditConfig, type EditMode, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, JsonPatch, type JsonSchemaOptions, OrCondition, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, Spec, type SpecIssue, type SpecIssueSeverity, type SpecValidationIssues, type SpecValidationResult, StateCondition, StateModel, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationResult, VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, autoFixSpec, buildEditInstructions, buildEditUserPrompt, buildUserPrompt, builtInValidationFunctions, check, deepMergeSpec, defineCatalog, defineSchema, diffToPatches, evaluateVisibility, formatSpecIssues, isNonEmptySpec, resolveActionParam, resolveBindings, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, validateSpec, visibility };

package.json

 {
   "name": "@json-render/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "Apache-2.0",
@@ -5,0 +5,0 @@ "description": "JSON becomes real things. Define your catalog, register your components, let AI generate.",

README.md

@@ -213,4 +213,17 @@ # @json-render/core
 | `buildUserPrompt(options)` | Build a user prompt with optional spec refinement and state context |
+| `buildEditUserPrompt(options)` | Build a user prompt for editing an existing spec (used internally by `buildUserPrompt`) |
+| `buildEditInstructions(config, format)` | Generate the prompt section describing available edit modes |
+| `isNonEmptySpec(spec)` | Check whether a spec has a root and at least one element |
 | `UserPromptOptions` | Options type for `buildUserPrompt` |
+| `EditMode` | `"patch" \| "merge" \| "diff"` |
+| `EditConfig` | Configuration for edit modes (`{ modes: EditMode[] }`) |
+| `BuildEditUserPromptOptions` | Options type for `buildEditUserPrompt` |
 
+### Merge and Diff
+
+| Export | Purpose |
+|--------|---------|
+| `deepMergeSpec(base, patch)` | RFC 7396 deep merge (null deletes, arrays replace, objects recurse) |
+| `diffToPatches(oldObj, newObj)` | Generate RFC 6902 JSON Patch operations from object diff |
+
 ### Spec Validation
@@ -495,6 +508,7 @@
 
-// Refinement with existing spec (triggers patch-only mode)
+// Refinement with edit modes (default: patch-only)
 const refinementPrompt = buildUserPrompt({
   prompt: "add a dark mode toggle",
   currentSpec: existingSpec,
+  editModes: ["patch", "merge"],
 });
@@ -509,2 +523,23 @@
 
+When `currentSpec` is provided, the prompt instructs the AI to use the specified edit modes. Available modes:
+
+- **`"patch"`** — RFC 6902 JSON Patch. One operation per line. Best for precise, targeted single-field updates.
+- **`"merge"`** — RFC 7396 JSON Merge Patch. Partial object deep-merged; `null` deletes. Best for structural changes.
+- **`"diff"`** — Unified diff against the serialized spec. Best for small text-level changes.
+
+## Deep Merge and Diff
+
+Format-agnostic utilities for working with specs:
+
+```typescript
+import { deepMergeSpec, diffToPatches } from "@json-render/core";
+
+// RFC 7396 deep merge: null deletes, arrays replace, objects recurse
+const merged = deepMergeSpec(baseSpec, { elements: { main: { props: { title: "New" } } } });
+
+// RFC 6902 diff: generate JSON Patch operations from two objects
+const patches = diffToPatches(oldSpec, newSpec);
+// [{ op: "replace", path: "/elements/main/props/title", value: "New" }]
+```
+
 ## Spec Validation
@@ -511,0 +546,0 @@

No alert changes

Improved metrics

Total package byte prevSize

858138

7.62%

Lines of code

7454

9.55%

Number of lines in readme file

634

5.84%

No dependency changes