@petrarca/sonnet-core 0.6.0 → 0.8.0

package/dist/schema/index.d.ts

@@ -39,6 +39,31 @@ interface UIRule {
     effect: UIRuleEffect;
     condition: UIRuleCondition;
 }
+/**
+ * A named validator reference carried by `x-ui-validate`. The bare-string form
+ * is the no-config common case (`"ibanValid"`); the object form supplies
+ * per-reference config and, for async form validators, the inputs that trigger
+ * a re-run (`dependsOn`). See the custom-validation design in sonnet-forms.
+ */
+interface UIValidateRef {
+    /** Registered validator name, resolved against the ValidatorRegistry. */
+    name: string;
+    /** Per-reference config, passed to the validator as `ctx.args`. */
+    args?: Record<string, unknown>;
+    /**
+     * For an async FORM validator: the field names whose values trigger a re-run.
+     * The engine keys/debounces the async result on these values. Ignored for
+     * sync validators and for field validators.
+     */
+    dependsOn?: string[];
+}
+/**
+ * The value of `x-ui-validate`: one validator or a list. On a property it
+ * selects field validators (`(value, ctx) => ...`); on the root object it
+ * selects form validators (`(data, ctx) => FieldError[]`). A bare string is
+ * shorthand for `{ name }`.
+ */
+type UIValidate = string | UIValidateRef | Array<string | UIValidateRef>;
 /**
  * JSON Schema property definition following Draft 2020-12 specification.
  * Supports basic types, validation constraints, conditionals, and custom extensions.
@@ -88,11 +113,14 @@ type JsonSchemaProperty = {
     "x-ui-options"?: Record<string, any>;
     "x-ui-layout"?: UILayoutConfig;
     "x-ui-title"?: string;
-    "x-ui-help"?: string;
     "x-ui-placeholder"?: string;
     "x-ui-description"?: string;
+    "x-ui-validate"?: UIValidate;
     "x-ui-column"?: {
-        /** Display order (ascending). Properties without order are appended sorted by key. */
+        /**
+         * Display order (ascending). Properties without an order are appended
+         * after the ordered ones, keeping their schema declaration order.
+         */
         order?: number;
         /** Exclude this column from the table entirely. */
         hidden?: boolean;
@@ -129,6 +157,7 @@ type JsonSchema = {
     $defs?: Record<string, JsonSchemaProperty>;
     definitions?: Record<string, JsonSchemaProperty>;
     "x-ui-order"?: string[];
+    "x-ui-validate"?: UIValidate;
     [key: `x-${string}`]: unknown;
 };
 /**
@@ -161,10 +190,11 @@ interface UISchema {
     "x-ui-order"?: string[];
     /** Declarative show/hide or enable/disable rule (see UIRule). */
     "x-ui-rule"?: UIRule;
+    /** Custom validators by name (override of the schema-level x-ui-validate). */
+    "x-ui-validate"?: UIValidate;
     "x-ui-title"?: string | false;
     "x-ui-description"?: string;
     "x-ui-placeholder"?: string;
-    "x-ui-help"?: string;
     /** Semantic field-slot width (default "full"). */
     "x-ui-width"?: WidthToken;
     /** Column override -- merged over schema-level x-ui-column, UI schema wins. */
@@ -386,7 +416,14 @@ declare function isNullableBoolean(property: JsonSchemaProperty): boolean;
 declare function extractEnumValues(property: JsonSchemaProperty): (string | number | boolean)[];
 /** Priority: x-ui-title > title > field name. */
 declare function getFieldTitle(fieldName: string, property: JsonSchemaProperty): string;
-/** Priority: x-ui-description > x-ui-help (legacy alias). */
+/**
+ * Help text for a field, rendered under the control.
+ *
+ * `x-ui-description` overrides the standard JSON Schema `description`. There is
+ * one help-text slot per field, so a schema that only carries `description` --
+ * anything generated from a typed model, or authored in the designer's Data tab
+ * -- shows it without needing a UI hint.
+ */
 declare function getFieldHelpText(property: JsonSchemaProperty): string | undefined;
 declare function getFieldPlaceholder(property: JsonSchemaProperty): string | undefined;
 declare function getFieldWidget(property: JsonSchemaProperty): string | undefined;
@@ -531,6 +568,18 @@ declare function hasConditionals(schema: JsonSchema): boolean;
  * validates that value against a schema. Evaluation yields presentation flags
  * (visible / enabled) the renderer applies -- the field itself stays declared at
  * its own position, so layout is stable (unlike if/then/else).
+ *
+ * Scopes are root-anchored at every depth: a rule on a nested field reads its
+ * pointer from the top of the form, so `/country` means the form's `country`
+ * even from inside `address`, and a sibling is reached by its full path
+ * (`/address/city`). This matches every other JSON Pointer in the vocabulary
+ * (`editablePaths`, validation error pointers). The renderer is responsible for
+ * passing the root form data in -- see `useRootFormData` in sonnet-forms.
+ *
+ * A consequence worth knowing when authoring inside `$defs`: a definition is
+ * reusable, but a root-anchored scope is not. A rule inside a definition that
+ * references `/country` only holds for forms that have a top-level `country`.
+ * This is inherent to root-anchoring and is the same in comparable libraries.
  */
 
 /** The presentation state a rule resolves to for its target field. */
@@ -721,9 +770,69 @@ interface ValidationResult {
 /**
  * Validate form data against a JSON Schema, recursing into nested objects
  * and array items.
+ *
+ * Two layers: this function owns required-ness and array cardinality with
+ * human-authored messages; `validateContentConstraints` adds the JSON Schema
+ * content constraints (format, pattern, type, length, range, enum, const) via
+ * AJV. Both contribute to the same `FieldError[]`, so downstream attribution
+ * (per-field `rawErrors`, per-tab error badges) is unchanged.
  */
 declare function validateFormData(schema: JsonSchema, data: Record<string, unknown>): ValidationResult;
 
+/**
+ * Content-constraint validation, layered on top of validateFormData.
+ *
+ * validateFormData covers required-ness and array cardinality with
+ * human-authored messages. This module adds the JSON Schema *content*
+ * constraints it does not: `format`, `pattern`, `type`, `minLength` /
+ * `maxLength`, `minimum` / `maximum` (and their exclusive variants),
+ * `enum`, `const`, and `multipleOf`. It reuses the shared AJV instance
+ * (already configured with `ajv-formats`) and maps AJV's errors into the
+ * same `FieldError` shape the renderer consumes -- AJV's `instancePath` is
+ * already an RFC 6901 JSON Pointer, so per-field and per-tab attribution
+ * keep working unchanged.
+ *
+ * Required and array-cardinality keywords are intentionally excluded here so
+ * validateFormData stays the single source of those messages -- no field ever
+ * shows two errors for the same cause.
+ */
+
+/**
+ * Validate content constraints via AJV and return them as FieldErrors.
+ *
+ * Only content keywords are returned; required and array-cardinality errors
+ * are filtered out (validateFormData owns those). Returns an empty array when
+ * the schema compiles cleanly and the data satisfies every content rule, or
+ * when AJV cannot compile the schema (in which case the caller's structural
+ * validation still stands).
+ */
+declare function validateContentConstraints(schema: JsonSchema, data: Record<string, unknown>): FieldError[];
+
+/**
+ * Merge FieldError lists from several validation sources into one, de-duplicated
+ * by field so a field never shows two errors for the same cause.
+ *
+ * Sources are passed in precedence order (strongest first): structural/content
+ * from validateFormData, then custom validators, then external/extra errors.
+ * The first source to flag a given field (by its pointer's root segment) wins;
+ * later sources add errors only for fields not already flagged. This extends the
+ * existing rule inside validateFormData (a content error is skipped on a field
+ * that already has a structural error) across every source.
+ *
+ * Form-level errors (pointer "") are never de-duplicated against fields -- they
+ * belong to the form, not a field -- but identical form-level messages collapse.
+ *
+ * Pure function -- no React, no side effects.
+ */
+
+/**
+ * Merge ordered FieldError sources. Earlier sources take precedence per field.
+ *
+ * @param sources FieldError lists in precedence order (strongest first).
+ * @returns one de-duplicated list preserving each kept error's order.
+ */
+declare function mergeFieldErrors(...sources: FieldError[][]): FieldError[];
+
 /**
  * diffFormData -- structural diff between two form data snapshots.
  *
@@ -741,4 +850,29 @@ declare function validateFormData(schema: JsonSchema, data: Record<string, unkno
  */
 declare function diffFormData(original: Record<string, unknown>, updated: Record<string, unknown>): FormDiff;
 
-export { type ArrayItemChange, type FieldDiff, type FieldError, type FormDiff, type JsonSchema, type JsonSchemaProperty, type RefResolver, type RuleState, type UILayoutConfig, type UILayoutGroupConfig, type UILayoutRowConfig, type UIRule, type UIRuleCondition, type UIRuleEffect, type UISchema, type UISchemaOptions, type ValidationResult, type ValueChange, WIDTH_TOKEN_REMS, type WidthToken, ajv, applySchemaDefaults, diffFormData, evaluateUiRule, extractEnumValues, extractSchemaDefaults, findActiveBranch, generateJsonSchemaFromVariables, getAtPointer, getBranchLabel, getBranchValue, getDiscriminator, getFieldConstraints, getFieldDefault, getFieldHelpText, getFieldPlaceholder, getFieldTitle, getFieldType, getFieldWidget, getOptionalFields, getRequiredFields, getSchemaProperties, hasConditionals, hasProperties, isFieldOptional, isFieldRequired, isNullableBoolean, isOneOf, matchesConst, resolveRefs, resolveSchema, toJsonSchema, validateFormData, validateSchema };
+/**
+ * ensureFormItemIds -- stamp a stable `_fid` onto every array-of-object item
+ * in a form data snapshot, guided by the schema.
+ *
+ * The form system matches array items across a diff by their `_fid` (see
+ * diffFormData). ArrayWidget assigns one when it renders, but that only reaches
+ * the working copy. The dirty-tracking baseline is snapshotted from the
+ * incoming `data`, which has none -- so a loaded array diffs as a wholesale
+ * replace after a single-item edit.
+ *
+ * Stamping the incoming data once, before both the working copy and the
+ * baseline are derived from it, gives the two sides the *same* ids, so
+ * identity survives the diff. Items that already carry a `_fid` keep it.
+ *
+ * Only array-of-object fields declared in the schema are touched; scalar
+ * arrays and everything else pass through unchanged. Recurses into nested
+ * objects and into the items of nested arrays.
+ */
+
+/**
+ * Return `data` with a `_fid` on every array-of-object item the schema
+ * declares. Returns the input unchanged when nothing needed stamping.
+ */
+declare function ensureFormItemIds(data: Record<string, unknown>, schema: JsonSchema): Record<string, unknown>;
+
+export { type ArrayItemChange, type FieldDiff, type FieldError, type FormDiff, type JsonSchema, type JsonSchemaProperty, type RefResolver, type RuleState, type UILayoutConfig, type UILayoutGroupConfig, type UILayoutRowConfig, type UIRule, type UIRuleCondition, type UIRuleEffect, type UISchema, type UISchemaOptions, type UIValidate, type UIValidateRef, type ValidationResult, type ValueChange, WIDTH_TOKEN_REMS, type WidthToken, ajv, applySchemaDefaults, diffFormData, ensureFormItemIds, evaluateUiRule, extractEnumValues, extractSchemaDefaults, findActiveBranch, generateJsonSchemaFromVariables, getAtPointer, getBranchLabel, getBranchValue, getDiscriminator, getFieldConstraints, getFieldDefault, getFieldHelpText, getFieldPlaceholder, getFieldTitle, getFieldType, getFieldWidget, getOptionalFields, getRequiredFields, getSchemaProperties, hasConditionals, hasProperties, isFieldOptional, isFieldRequired, isNullableBoolean, isOneOf, matchesConst, mergeFieldErrors, resolveRefs, resolveSchema, toJsonSchema, validateContentConstraints, validateFormData, validateSchema };

package/dist/schema/index.js

@@ -3,6 +3,7 @@ import {
 } from "../chunk-XAEHYRXC.js";
 import {
   FORM_ITEM_ID_FIELD,
+  generateId,
   isEqual
 } from "../chunk-XCCOEUVC.js";
 
@@ -57,7 +58,7 @@ function getFieldTitle(fieldName, property) {
   return property["x-ui-title"] || property.title || fieldName;
 }
 function getFieldHelpText(property) {
-  return property["x-ui-description"] ?? property["x-ui-help"];
+  return property["x-ui-description"] ?? property.description;
 }
 function getFieldPlaceholder(property) {
   return property["x-ui-placeholder"];
@@ -146,7 +147,12 @@ var ajv = new Ajv({
   strict: false,
   validateFormats: true,
   // Allow unknown keywords (for x-ui-widget, x-ui-title, etc.)
-  strictSchema: false
+  strictSchema: false,
+  // Enable $data references so a keyword can reference another field's value,
+  // e.g. { "const": { "$data": "1/password" } } for "must equal password".
+  // This is the declarative path for simple cross-field rules (see the
+  // custom-validation design); complex cross-field logic uses form validators.
+  $data: true
 });
 addFormats(ajv);
 function resolveSchema(schema, formData) {
@@ -466,6 +472,63 @@ function resolveRefs(schema, resolve) {
   return resolved;
 }
 
+// src/schema/contentValidation.ts
+var OWNED_BY_VALIDATE_FORM_DATA = /* @__PURE__ */ new Set([
+  "required",
+  "minItems",
+  "maxItems"
+]);
+function unescapePointerToken(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function labelForPointer(schema, pointer) {
+  if (pointer === "") return "";
+  const tokens = pointer.split("/").slice(1).map(unescapePointerToken);
+  const parts = [];
+  let node = schema;
+  for (const token of tokens) {
+    if (/^\d+$/.test(token)) {
+      if (parts.length > 0) {
+        parts[parts.length - 1] = `${parts[parts.length - 1]}[${Number(token) + 1}]`;
+      }
+      node = node?.items;
+      continue;
+    }
+    const props = node?.properties;
+    const child = props?.[token];
+    parts.push(child ? getFieldTitle(token, child) : token);
+    node = child;
+  }
+  return parts.join(" > ");
+}
+function messageFor(label, keyword, message) {
+  const what = label || "Value";
+  const detail = message ?? "is invalid";
+  return `${what} ${detail}`;
+}
+function validateContentConstraints(schema, data) {
+  let validate;
+  try {
+    validate = ajv.compile(schema);
+  } catch {
+    return [];
+  }
+  if (validate(data)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const err of validate.errors ?? []) {
+    if (OWNED_BY_VALIDATE_FORM_DATA.has(err.keyword)) continue;
+    const pointer = err.instancePath;
+    const label = labelForPointer(schema, pointer);
+    const message = messageFor(label, err.keyword, err.message);
+    const key = `${pointer}\0${message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ pointer, message });
+  }
+  return out;
+}
+
 // src/schema/validateFormData.ts
 function escapePointerToken(token) {
   return token.replace(/~/g, "~0").replace(/\//g, "~1");
@@ -556,6 +619,11 @@ function validateFormData(schema, data) {
     { label: "", pointer: "" },
     fieldErrors
   );
+  const structurallyFlagged = new Set(fieldErrors.map((e) => e.pointer));
+  for (const err of validateContentConstraints(schema, data)) {
+    if (structurallyFlagged.has(err.pointer)) continue;
+    fieldErrors.push(err);
+  }
   return {
     errors: fieldErrors.map((e) => e.message),
     fieldErrors,
@@ -563,6 +631,34 @@ function validateFormData(schema, data) {
   };
 }
 
+// src/schema/mergeFieldErrors.ts
+function pointerRoot(pointer) {
+  const token = pointer.split("/")[1] ?? "";
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function mergeFieldErrors(...sources) {
+  const out = [];
+  const claimedFields = /* @__PURE__ */ new Set();
+  const seenFormMessages = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    for (const err of source) {
+      if (err.pointer === "") {
+        if (seenFormMessages.has(err.message)) continue;
+        seenFormMessages.add(err.message);
+        out.push(err);
+        continue;
+      }
+      const root = pointerRoot(err.pointer);
+      if (claimedFields.has(root)) continue;
+      out.push(err);
+    }
+    for (const err of source) {
+      if (err.pointer !== "") claimedFields.add(pointerRoot(err.pointer));
+    }
+  }
+  return out;
+}
+
 // src/schema/diffFormData.ts
 function areBothPlainObjects(a, b) {
   return a !== null && b !== null && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b);
@@ -705,11 +801,50 @@ function diffFormData(original, updated) {
   }
   return diff;
 }
+
+// src/schema/ensureFormItemIds.ts
+function isPlainObject2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isObjectArray2(property) {
+  return property.type === "array" && !!property.items?.properties;
+}
+function stampItem(item, itemSchema) {
+  if (!isPlainObject2(item)) return item;
+  const withChildren = stampObject(item, itemSchema.properties ?? {});
+  return FORM_ITEM_ID_FIELD in withChildren ? withChildren : { ...withChildren, [FORM_ITEM_ID_FIELD]: generateId() };
+}
+function stampValue(value, property) {
+  if (isObjectArray2(property) && Array.isArray(value)) {
+    return value.map((item) => stampItem(item, property.items));
+  }
+  if (property.type === "object" && property.properties && isPlainObject2(value)) {
+    return stampObject(value, property.properties);
+  }
+  return value;
+}
+function stampObject(data, properties) {
+  let changed = false;
+  const out = { ...data };
+  for (const [name, property] of Object.entries(properties)) {
+    if (!(name in data)) continue;
+    const next = stampValue(data[name], property);
+    if (next !== data[name]) {
+      out[name] = next;
+      changed = true;
+    }
+  }
+  return changed ? out : data;
+}
+function ensureFormItemIds(data, schema) {
+  return stampObject(data, getSchemaProperties(schema));
+}
 export {
   WIDTH_TOKEN_REMS,
   ajv,
   applySchemaDefaults,
   diffFormData,
+  ensureFormItemIds,
   evaluateUiRule,
   extractEnumValues,
   extractSchemaDefaults,
@@ -736,9 +871,11 @@ export {
   isNullableBoolean,
   isOneOf,
   matchesConst,
+  mergeFieldErrors,
   resolveRefs,
   resolveSchema,
   toJsonSchema,
+  validateContentConstraints,
   validateFormData,
   validateSchema
 };