@json-render/core 0.4.4 → 0.5.0

package/README.md

@@ -173,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: