@json-render/core 0.4.3 → 0.5.0

package/README.md

@@ -116,14 +116,16 @@ while (streaming) {
 const finalSpec = compiler.getResult();
 ```
 
-SpecStream format (each line is a JSON patch):
+SpecStream format uses [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations (each line is a patch):
 
 ```jsonl
-{"op":"set","path":"/root/type","value":"Card"}
-{"op":"set","path":"/root/props","value":{"title":"Hello"}}
-{"op":"set","path":"/root/children/0","value":{"type":"Button","props":{"label":"Click"}}}
+{"op":"add","path":"/root/type","value":"Card"}
+{"op":"add","path":"/root/props","value":{"title":"Hello"}}
+{"op":"add","path":"/root/children/0","value":{"type":"Button","props":{"label":"Click"}}}
 ```
 
+All six RFC 6902 operations are supported: `add`, `remove`, `replace`, `move`, `copy`, `test`.
+
 ### Low-Level Utilities
 
 ```typescript
@@ -134,8 +136,8 @@ import {
 } from "@json-render/core";
 
 // Parse a single line
-const patch = parseSpecStreamLine('{"op":"set","path":"/root","value":{}}');
-// { op: "set", path: "/root", value: {} }
+const patch = parseSpecStreamLine('{"op":"add","path":"/root","value":{}}');
+// { op: "add", path: "/root", value: {} }
 
 // Apply a patch to an object
 const obj = {};
@@ -171,15 +173,141 @@ const spec = compileSpecStream<MySpec>(jsonlString);
 | `applySpecStreamPatch(obj, patch)` | Apply patch to object |
 | `compileSpecStream<T>(jsonl)` | Compile entire JSONL string |
 
+### Dynamic Props
+
+| Export | Purpose |
+|--------|---------|
+| `resolvePropValue(value, ctx)` | Resolve a single prop expression |
+| `resolveElementProps(props, ctx)` | Resolve all prop expressions in an element |
+| `PropExpression<T>` | Type for prop values that may contain expressions |
+
+### User Prompt
+
+| Export | Purpose |
+|--------|---------|
+| `buildUserPrompt(options)` | Build a user prompt with optional spec refinement and state context |
+| `UserPromptOptions` | Options type for `buildUserPrompt` |
+
+### Spec Validation
+
+| Export | Purpose |
+|--------|---------|
+| `validateSpec(spec, catalog?)` | Validate spec structure and return issues |
+| `autoFixSpec(spec)` | Auto-fix common spec issues (returns corrected copy) |
+| `formatSpecIssues(issues)` | Format validation issues as readable strings |
+
 ### Types
 
 | Export | Purpose |
 |--------|---------|
 | `Spec` | Base spec type |
 | `Catalog` | Catalog type |
+| `VisibilityCondition` | Visibility condition type (used by `$cond`) |
+| `VisibilityContext` | Context for evaluating visibility and prop expressions |
 | `SpecStreamLine` | Single patch operation |
 | `SpecStreamCompiler` | Streaming compiler interface |
 
+## Dynamic Prop Expressions
+
+Any prop value can be a dynamic expression that resolves based on data state at render time. Expressions are resolved by the renderer before props reach components.
+
+### Data Binding (`$path`)
+
+Read a value directly from the state model:
+
+```json
+{
+  "color": { "$path": "/theme/primary" },
+  "label": { "$path": "/user/name" }
+}
+```
+
+### Conditional (`$cond` / `$then` / `$else`)
+
+Evaluate a condition (same syntax as visibility conditions) and pick a value:
+
+```json
+{
+  "color": {
+    "$cond": { "eq": [{ "path": "/activeTab" }, "home"] },
+    "$then": "#007AFF",
+    "$else": "#8E8E93"
+  },
+  "name": {
+    "$cond": { "eq": [{ "path": "/activeTab" }, "home"] },
+    "$then": "home",
+    "$else": "home-outline"
+  }
+}
+```
+
+`$then` and `$else` can themselves be expressions (recursive):
+
+```json
+{
+  "label": {
+    "$cond": { "path": "/user/isAdmin" },
+    "$then": { "$path": "/admin/greeting" },
+    "$else": "Welcome"
+  }
+}
+```
+
+### API
+
+```typescript
+import { resolvePropValue, resolveElementProps } from "@json-render/core";
+
+// Resolve a single value
+const color = resolvePropValue(
+  { $cond: { eq: [{ path: "/active" }, "yes"] }, $then: "blue", $else: "gray" },
+  { stateModel: myState }
+);
+
+// Resolve all props on an element
+const resolved = resolveElementProps(element.props, { stateModel: myState });
+```
+
+## User Prompt Builder
+
+Build structured user prompts for AI generation, with support for refinement and state context:
+
+```typescript
+import { buildUserPrompt } from "@json-render/core";
+
+// Fresh generation
+const prompt = buildUserPrompt({ prompt: "create a todo app" });
+
+// Refinement with existing spec (triggers patch-only mode)
+const refinementPrompt = buildUserPrompt({
+  prompt: "add a dark mode toggle",
+  currentSpec: existingSpec,
+});
+
+// With runtime state context
+const contextPrompt = buildUserPrompt({
+  prompt: "show my data",
+  state: { todos: [{ text: "Buy milk" }] },
+});
+```
+
+## Spec Validation
+
+Validate spec structure and auto-fix common issues:
+
+```typescript
+import { validateSpec, autoFixSpec, formatSpecIssues } from "@json-render/core";
+
+// Validate a spec
+const { valid, issues } = validateSpec(spec, catalog);
+
+// Format issues for display
+console.log(formatSpecIssues(issues));
+
+// Auto-fix common issues (returns a corrected copy)
+const fixed = autoFixSpec(spec);
+```
+
 ## Custom Schemas
 
 json-render supports completely different spec formats for different renderers: