@json-render/core 0.9.0 → 0.10.0

package/dist/index.js

@@ -889,6 +889,16 @@ function isBindItemExpression(value) {
 function isCondExpression(value) {
   return typeof value === "object" && value !== null && "$cond" in value && "$then" in value && "$else" in value;
 }
+function isComputedExpression(value) {
+  return typeof value === "object" && value !== null && "$computed" in value && typeof value.$computed === "string";
+}
+function isTemplateExpression(value) {
+  return typeof value === "object" && value !== null && "$template" in value && typeof value.$template === "string";
+}
+var WARNED_COMPUTED_MAX = 100;
+var warnedComputedFns = /* @__PURE__ */ new Set();
+var WARNED_TEMPLATE_MAX = 100;
+var warnedTemplatePaths = /* @__PURE__ */ new Set();
 function resolveBindItemPath(itemPath, ctx) {
   if (ctx.repeatBasePath == null) {
     console.warn(`$bindItem used outside repeat scope: "${itemPath}"`);
@@ -923,6 +933,46 @@ function resolvePropValue(value, ctx) {
     const result = evaluateVisibility(value.$cond, ctx);
     return resolvePropValue(result ? value.$then : value.$else, ctx);
   }
+  if (isComputedExpression(value)) {
+    const fn = ctx.functions?.[value.$computed];
+    if (!fn) {
+      if (!warnedComputedFns.has(value.$computed)) {
+        if (warnedComputedFns.size < WARNED_COMPUTED_MAX) {
+          warnedComputedFns.add(value.$computed);
+        }
+        console.warn(`Unknown $computed function: "${value.$computed}"`);
+      }
+      return void 0;
+    }
+    const resolvedArgs = {};
+    if (value.args) {
+      for (const [key, arg] of Object.entries(value.args)) {
+        resolvedArgs[key] = resolvePropValue(arg, ctx);
+      }
+    }
+    return fn(resolvedArgs);
+  }
+  if (isTemplateExpression(value)) {
+    return value.$template.replace(
+      /\$\{([^}]+)\}/g,
+      (_match, rawPath) => {
+        let path = rawPath;
+        if (!path.startsWith("/")) {
+          if (!warnedTemplatePaths.has(path)) {
+            if (warnedTemplatePaths.size < WARNED_TEMPLATE_MAX) {
+              warnedTemplatePaths.add(path);
+            }
+            console.warn(
+              `$template path "${path}" should be a JSON Pointer starting with "/". Automatically resolving as "/${path}".`
+            );
+          }
+          path = "/" + path;
+        }
+        const resolved = getByPath(ctx.stateModel, path);
+        return resolved != null ? String(resolved) : "";
+      }
+    );
+  }
   if (Array.isArray(value)) {
     return value.map((item) => resolvePropValue(item, ctx));
   }
@@ -1087,6 +1137,10 @@ var ValidationConfigSchema = import_zod4.z.object({
   validateOn: import_zod4.z.enum(["change", "blur", "submit"]).optional(),
   enabled: VisibilityConditionSchema.optional()
 });
+var matchesImpl = (value, args) => {
+  const other = args?.other;
+  return value === other;
+};
 var builtInValidationFunctions = {
   /**
    * Check if value is not null, undefined, or empty string
@@ -1176,9 +1230,60 @@ var builtInValidationFunctions = {
   /**
    * Check if value matches another field
    */
-  matches: (value, args) => {
+  matches: matchesImpl,
+  /**
+   * Alias for matches with a more descriptive name for cross-field equality
+   */
+  equalTo: matchesImpl,
+  /**
+   * Check if value is less than another field's value.
+   * Supports numbers, strings (useful for ISO date comparison), and
+   * cross-type numeric coercion (e.g. string "3" vs number 5).
+   */
+  lessThan: (value, args) => {
     const other = args?.other;
-    return value === other;
+    if (value == null || other == null || value === "" || other === "")
+      return false;
+    if (typeof value === "number" && typeof other === "number")
+      return value < other;
+    if (typeof value === "string" && typeof other === "string")
+      return value < other;
+    const numVal = Number(value);
+    const numOther = Number(other);
+    if (!isNaN(numVal) && !isNaN(numOther)) return numVal < numOther;
+    return false;
+  },
+  /**
+   * Check if value is greater than another field's value.
+   * Supports numbers, strings (useful for ISO date comparison), and
+   * cross-type numeric coercion (e.g. string "7" vs number 5).
+   */
+  greaterThan: (value, args) => {
+    const other = args?.other;
+    if (value == null || other == null || value === "" || other === "")
+      return false;
+    if (typeof value === "number" && typeof other === "number")
+      return value > other;
+    if (typeof value === "string" && typeof other === "string")
+      return value > other;
+    const numVal = Number(value);
+    const numOther = Number(other);
+    if (!isNaN(numVal) && !isNaN(numOther)) return numVal > numOther;
+    return false;
+  },
+  /**
+   * Required only when a condition is met.
+   * Uses JS truthiness: 0, false, "", null, and undefined are all
+   * treated as "condition not met" (field not required), matching
+   * the visibility system's bare-condition semantics.
+   */
+  requiredIf: (value, args) => {
+    const condition = args?.field;
+    if (!condition) return true;
+    if (value === null || value === void 0) return false;
+    if (typeof value === "string") return value.trim().length > 0;
+    if (Array.isArray(value)) return value.length > 0;
+    return true;
   }
 };
 function runValidationCheck(check2, ctx) {
@@ -1186,7 +1291,7 @@ function runValidationCheck(check2, ctx) {
   const resolvedArgs = {};
   if (check2.args) {
     for (const [key, argValue] of Object.entries(check2.args)) {
-      resolvedArgs[key] = resolveDynamicValue(argValue, stateModel);
+      resolvedArgs[key] = resolvePropValue(argValue, { stateModel });
     }
   }
   const validationFn = builtInValidationFunctions[check2.type] ?? customFunctions?.[check2.type];
@@ -1270,10 +1375,34 @@ var check = {
     type: "url",
     message
   }),
+  numeric: (message = "Must be a number") => ({
+    type: "numeric",
+    message
+  }),
   matches: (otherPath, message = "Fields must match") => ({
     type: "matches",
     args: { other: { $state: otherPath } },
     message
+  }),
+  equalTo: (otherPath, message = "Fields must match") => ({
+    type: "equalTo",
+    args: { other: { $state: otherPath } },
+    message
+  }),
+  lessThan: (otherPath, message) => ({
+    type: "lessThan",
+    args: { other: { $state: otherPath } },
+    message: message ?? "Must be less than the compared field"
+  }),
+  greaterThan: (otherPath, message) => ({
+    type: "greaterThan",
+    args: { other: { $state: otherPath } },
+    message: message ?? "Must be greater than the compared field"
+  }),
+  requiredIf: (fieldPath, message = "This field is required") => ({
+    type: "requiredIf",
+    args: { field: { $state: fieldPath } },
+    message
   })
 };
 
@@ -1342,6 +1471,14 @@ function validateSpec(spec, options = {}) {
         code: "repeat_in_props"
       });
     }
+    if (props && "watch" in props && props.watch !== void 0) {
+      issues.push({
+        severity: "error",
+        message: `Element "${key}" has "watch" inside "props". It should be a top-level field on the element (sibling of type/props/children).`,
+        elementKey: key,
+        code: "watch_in_props"
+      });
+    }
   }
   if (checkOrphans) {
     const reachable = /* @__PURE__ */ new Set();
@@ -1409,6 +1546,16 @@ function autoFixSpec(spec) {
       };
       fixes.push(`Moved "repeat" from props to element level on "${key}".`);
     }
+    currentProps = fixed.props;
+    if (currentProps && "watch" in currentProps && currentProps.watch !== void 0) {
+      const { watch, ...restProps } = currentProps;
+      fixed = {
+        ...fixed,
+        props: restProps,
+        watch
+      };
+      fixes.push(`Moved "watch" from props to element level on "${key}".`);
+    }
     fixedElements[key] = fixed;
   }
   return {
@@ -1894,6 +2041,29 @@ Note: state patches appear right after the elements that use them, so the UI fil
     "Use $bindState for form inputs (text fields, checkboxes, selects, sliders, etc.) and $state for read-only data display. Inside repeat scopes, use $bindItem for form inputs bound to the current item. Use dynamic props instead of duplicating elements with opposing visible conditions when only prop values differ."
   );
   lines.push("");
+  lines.push(
+    '4. Template: `{ "$template": "Hello, ${/name}!" }` - interpolates `${/path}` references in the string with values from the state model.'
+  );
+  lines.push(
+    '   Example: `"label": { "$template": "Items: ${/cart/count} | Total: ${/cart/total}" }` renders "Items: 3 | Total: 42.00" when /cart/count is 3 and /cart/total is 42.00.'
+  );
+  lines.push("");
+  const catalogFunctions = catalog.data.functions;
+  if (catalogFunctions && Object.keys(catalogFunctions).length > 0) {
+    lines.push(
+      '5. Computed: `{ "$computed": "<functionName>", "args": { "key": <expression> } }` - calls a registered function with resolved args and returns the result.'
+    );
+    lines.push(
+      '   Example: `"value": { "$computed": "fullName", "args": { "first": { "$state": "/form/firstName" }, "last": { "$state": "/form/lastName" } } }`'
+    );
+    lines.push("   Available functions:");
+    for (const name of Object.keys(
+      catalogFunctions
+    )) {
+      lines.push(`   - ${name}`);
+    }
+    lines.push("");
+  }
   const hasChecksComponents = allComponents ? Object.entries(allComponents).some(([, def]) => {
     if (!def.props) return false;
     const formatted = formatZodType(def.props);
@@ -1919,7 +2089,19 @@ Note: state patches appear right after the elements that use them, so the UI fil
     lines.push("  - numeric \u2014 value must be a number");
     lines.push("  - url \u2014 valid URL format");
     lines.push(
-      '  - matches \u2014 must equal another field (args: { "other": "value" })'
+      '  - matches \u2014 must equal another field (args: { "other": { "$state": "/path" } })'
+    );
+    lines.push(
+      '  - equalTo \u2014 alias for matches (args: { "other": { "$state": "/path" } })'
+    );
+    lines.push(
+      '  - lessThan \u2014 value must be less than another field (args: { "other": { "$state": "/path" } })'
+    );
+    lines.push(
+      '  - greaterThan \u2014 value must be greater than another field (args: { "other": { "$state": "/path" } })'
+    );
+    lines.push(
+      '  - requiredIf \u2014 required only when another field is truthy (args: { "field": { "$state": "/path" } })'
     );
     lines.push("");
     lines.push("Example:");
@@ -1935,6 +2117,30 @@ Note: state patches appear right after the elements that use them, so the UI fil
     );
     lines.push("");
   }
+  if (hasCustomActions || hasBuiltInActions) {
+    lines.push("STATE WATCHERS:");
+    lines.push(
+      "Elements can have an optional `watch` field to react to state changes and trigger actions. The `watch` field is a top-level field on the element (sibling of type/props/children), NOT inside props."
+    );
+    lines.push(
+      "Maps state paths (JSON Pointers) to action bindings. When the value at a watched path changes, the bound actions fire automatically."
+    );
+    lines.push("");
+    lines.push(
+      "Example (cascading select \u2014 country changes trigger city loading):"
+    );
+    lines.push(
+      `  ${JSON.stringify({ type: "Select", props: { value: { $bindState: "/form/country" }, options: ["US", "Canada", "UK"] }, watch: { "/form/country": { action: "loadCities", params: { country: { $state: "/form/country" } } } }, children: [] })}`
+    );
+    lines.push("");
+    lines.push(
+      "Use `watch` for cascading dependencies where changing one field should trigger side effects (loading data, resetting dependent fields, computing derived values)."
+    );
+    lines.push(
+      "IMPORTANT: `watch` is a top-level field on the element (sibling of type/props/children), NOT inside props. Watchers only fire when the value changes, not on initial render."
+    );
+    lines.push("");
+  }
   lines.push("RULES:");
   const baseRules = mode === "chat" ? [
     "When generating UI, wrap all JSONL patches in a ```spec code fence - one JSON object per line inside the fence",