@petrarca/sonnet-core 0.5.0 → 0.7.0

package/dist/schema/index.d.ts

@@ -1,3 +1,4 @@
+import Ajv from 'ajv';
 import { z } from 'zod';
 
 /**
@@ -7,6 +8,37 @@ import { z } from 'zod';
  * for form/widget integration. They are domain-agnostic -- no
  * application-specific entity concepts live here.
  */
+/**
+ * A declarative presentation rule (JSONForms-style) attached to a field.
+ *
+ * The rule lives on the field it controls (the target). Its `condition` points
+ * at another field's value via a JSON Pointer (RFC 6901) into the form DATA
+ * (rooted at the whole form), and validates that value against `condition.schema`.
+ * When the condition holds, `effect` is applied to the target:
+ *  - "show"   -- render only when the condition holds
+ *  - "hide"   -- render only when the condition does NOT hold
+ *  - "enable" -- interactive only when the condition holds
+ *  - "disable"-- non-interactive when the condition holds
+ *
+ * Example: show `pregnancy_status` when `gender` equals "female":
+ * ```json
+ * { "effect": "show",
+ *   "condition": { "scope": "/gender", "schema": { "const": "female" } } }
+ * ```
+ * Unlike if/then/else, the target field stays declared at its own position, so
+ * layout placement is stable.
+ */
+interface UIRuleCondition {
+    /** JSON Pointer (RFC 6901) into the form data, e.g. "/gender" or "/patient/gender". */
+    scope: string;
+    /** Schema the value at `scope` is validated against (e.g. { const: "female" }). */
+    schema: JsonSchemaProperty;
+}
+type UIRuleEffect = "show" | "hide" | "enable" | "disable";
+interface UIRule {
+    effect: UIRuleEffect;
+    condition: UIRuleCondition;
+}
 /**
  * JSON Schema property definition following Draft 2020-12 specification.
  * Supports basic types, validation constraints, conditionals, and custom extensions.
@@ -24,29 +56,45 @@ type JsonSchemaProperty = {
     maxLength?: number;
     minimum?: number;
     maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
     items?: JsonSchemaProperty;
     minItems?: number;
     maxItems?: number;
     properties?: Record<string, JsonSchemaProperty>;
     required?: string[];
     $ref?: string;
+    $defs?: Record<string, JsonSchemaProperty>;
+    definitions?: Record<string, JsonSchemaProperty>;
     allOf?: JsonSchemaProperty[];
     anyOf?: JsonSchemaProperty[];
     oneOf?: JsonSchemaProperty[];
     not?: JsonSchemaProperty;
+    /**
+     * Discriminator for a `oneOf` union (OpenAPI convention). `propertyName` is
+     * the shared property whose `const` value tags the active branch. When
+     * absent, the discriminator is auto-detected as the property that is const
+     * in every branch.
+     */
+    discriminator?: {
+        propertyName: string;
+    };
     if?: JsonSchemaProperty;
     then?: JsonSchemaProperty;
     else?: JsonSchemaProperty;
     "x-ui-order"?: string[];
+    "x-ui-rule"?: UIRule;
     "x-ui-widget"?: string;
     "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-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;
@@ -113,10 +161,11 @@ interface UISchema {
     "x-ui-options"?: UISchemaOptions;
     "x-ui-globalOptions"?: UISchemaOptions;
     "x-ui-order"?: string[];
+    /** Declarative show/hide or enable/disable rule (see UIRule). */
+    "x-ui-rule"?: UIRule;
     "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. */
@@ -180,6 +229,31 @@ interface UILayoutRowConfig {
      */
     arrange?: "grid" | "flow";
 }
+/**
+ * One named group of a grouped form layout. A group holds rows of fields under
+ * a label; the data stays flat (grouping is presentation only, like `group` on
+ * a single row). How groups are shown -- tabs, wizard steps, stacked sections
+ * -- is chosen by {@link UILayoutConfig.variant}, not by this structure.
+ *
+ * A group may carry an `x-ui-rule`-style {@link UIRule} to appear conditionally
+ * (e.g. show an "Address" group only when "provide address" is checked). The
+ * rule is evaluated against the form data exactly as a field-level rule is.
+ */
+interface UILayoutGroupConfig {
+    /** Label shown on the group's trigger or heading. */
+    label: string;
+    /** Rows of fields in this group (same shape as UILayoutConfig.rows). */
+    rows: UILayoutRowConfig[];
+    /**
+     * Optional show/hide rule for the whole group: a hidden group disappears
+     * along with its fields. Narrowed to the visibility effects -- a disabled
+     * group has no meaning, and permitting the effect would let it be authored
+     * and then silently ignored.
+     */
+    rule?: UIRule & {
+        effect: "show" | "hide";
+    };
+}
 /**
  * UILayoutConfig -- layout configuration for ObjectWidget and ArrayWidget.
  *
@@ -189,6 +263,8 @@ interface UILayoutRowConfig {
 interface UILayoutConfig {
     direction?: "vertical" | "horizontal";
     rows?: UILayoutRowConfig[];
+    groups?: UILayoutGroupConfig[];
+    variant?: "tabs" | "stepper" | "sections" | (string & {});
     columns?: string;
     gap?: number;
     labels?: boolean;
@@ -263,6 +339,8 @@ interface UISchemaOptions {
     rows?: number;
     searchable?: boolean;
     clearable?: boolean;
+    /** Allow the user to type and submit a value not in the enum list (combobox / open-choice). */
+    creatable?: boolean;
     /** Label placement: "top" (default, above) or "start" (inline, RTL-safe). */
     labelPlacement?: "top" | "start";
     /** Semantic field-slot width (default "full"). */
@@ -309,7 +387,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;
@@ -326,6 +411,38 @@ declare function getRequiredFields(schema: JsonSchema): string[];
 declare function getOptionalFields(schema: JsonSchema): string[];
 declare function hasProperties(schema: JsonSchema): boolean;
 
+/**
+ * oneOf (discriminated-union) helpers.
+ *
+ * A oneOf property is an object whose shape is one of several branches, modeled
+ * as `oneOf: [branchSchema, ...]`. Each branch shares a discriminator property
+ * -- a field with a `const` value that tags which branch is active. The
+ * discriminator is named by `discriminator.propertyName` (OpenAPI convention),
+ * or auto-detected as the property that carries a `const` in every branch.
+ *
+ * These helpers are pure and domain-agnostic.
+ */
+
+/** Whether a property is a oneOf union (has a non-empty `oneOf`). */
+declare function isOneOf(property: JsonSchemaProperty): boolean;
+/**
+ * Resolve the discriminator property name for a oneOf union.
+ *
+ * Uses `discriminator.propertyName` when set; otherwise auto-detects the single
+ * property that carries a `const` in every branch. Returns undefined when no
+ * consistent discriminator can be determined.
+ */
+declare function getDiscriminator(property: JsonSchemaProperty): string | undefined;
+/** The discriminator const value for a branch, or undefined. */
+declare function getBranchValue(branch: JsonSchemaProperty, discriminator: string): string | number | boolean | undefined;
+/** Human label for a branch: its `title`, else the discriminator value. */
+declare function getBranchLabel(branch: JsonSchemaProperty, discriminator: string | undefined, index: number): string;
+/**
+ * Find the branch that matches the current form data by comparing the
+ * discriminator value. Returns the branch index, or -1 when none match.
+ */
+declare function findActiveBranch(property: JsonSchemaProperty, data: Record<string, unknown> | undefined, discriminator: string | undefined): number;
+
 /**
  * Schema Resolver - Resolves conditional schemas (if-then-else, allOf, etc.)
  *
@@ -342,6 +459,7 @@ declare function hasProperties(schema: JsonSchema): boolean;
  * @module services/schemaResolver
  */
 
+declare const ajv: Ajv;
 /**
  * Resolve conditional schema based on form data
  *
@@ -412,6 +530,45 @@ declare function matchesConst(value: any, constValue: any): boolean;
  */
 declare function hasConditionals(schema: JsonSchema): boolean;
 
+/**
+ * Declarative UI rules (x-ui-rule): show/hide or enable/disable a field based
+ * on another field's value.
+ *
+ * The rule lives on the target field. Its condition references a value elsewhere
+ * in the form data via a JSON Pointer (RFC 6901) rooted at the whole form, and
+ * 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. */
+interface RuleState {
+    visible: boolean;
+    enabled: boolean;
+}
+/**
+ * Resolve a JSON Pointer against a data object. Returns the value at the pointer,
+ * or undefined when any segment is missing. "" (empty pointer) returns the root.
+ */
+declare function getAtPointer(data: unknown, pointer: string): unknown;
+/**
+ * Resolve a field's presentation state from its `x-ui-rule` (if any) against the
+ * current form data. Fields without a rule are visible and enabled.
+ */
+declare function evaluateUiRule(rule: UIRule | undefined, formData: unknown): RuleState;
+
 /**
  * Schema utilities
  *
@@ -518,42 +675,67 @@ declare function generateJsonSchemaFromVariables(variables: string[], existingSc
 declare function toJsonSchema(schema: z.ZodType): JsonSchema;
 
 /**
- * $ref Resolution -- resolves local JSON Schema references.
+ * $ref Resolution -- resolves JSON Schema references.
  *
- * Walks the schema tree and replaces { "$ref": "#/$defs/name" } nodes
- * with the corresponding sub-schema from the document's $defs (Draft
- * 2020-12) or definitions (Draft 7) block.
+ * Walks the schema tree and replaces `{ "$ref": ... }` nodes with the
+ * corresponding sub-schema. By default it resolves local, in-document refs:
+ * `#/$defs/name` (Draft 2020-12) or `#/definitions/name` (Draft 7).
  *
- * Properties on the referencing node are merged on top of the resolved
- * target, so context-specific overrides (e.g. a custom title) work
- * without duplicating the definition.
+ * A caller may inject a `RefResolver` to resolve ANY ref string (e.g. a schema
+ * registry id like `sdf_...`, or a canonical URI). The injected resolver is
+ * tried first; the in-document `$defs`/`definitions` lookup is the fallback, so
+ * both ref styles work together. The resolver is synchronous: consumers that
+ * fetch schemas asynchronously (e.g. from a registry over HTTP) pre-load them
+ * into a map and pass a `(ref) => map[ref]` lookup. This keeps the toolkit pure
+ * (no HTTP, no async).
  *
- * Only local refs (starting with "#/") are supported. External URIs
- * are left as-is -- a future pluggable SchemaResolver interface will
- * handle those.
+ * Properties on the referencing node are merged on top of the resolved target,
+ * so context-specific overrides (e.g. a custom title) work without duplicating
+ * the definition. Refs that no resolver can satisfy are left as-is.
  */
 
+/** Resolve a `$ref` string to its target sub-schema, or undefined if unknown. */
+type RefResolver = (ref: string) => JsonSchemaProperty | undefined;
 /**
- * Resolve all local $ref pointers in a JSON Schema document.
+ * Resolve `$ref` pointers in a JSON Schema document.
  *
- * Returns the schema unchanged if it contains no $defs/definitions
- * or no $ref nodes. The original schema object is never mutated.
+ * By default resolves in-document `#/$defs` / `#/definitions` refs. Pass a
+ * `resolve` to also resolve registry/URI refs; it is tried first and the
+ * in-document lookup is the fallback. The original schema is never mutated;
+ * a document with no refs to resolve is returned unchanged.
  */
-declare function resolveRefs(schema: JsonSchema): JsonSchema;
+declare function resolveRefs(schema: JsonSchema, resolve?: RefResolver): JsonSchema;
 
 /**
  * Recursive form data validation against a JSON Schema.
  *
  * Validates required fields at every nesting level: top-level properties,
  * nested objects (type: "object"), and array items (type: "array" with
- * items.type: "object"). Returns a flat list of human-readable error
- * strings and a boolean summary.
+ * items.type: "object"). Returns human-readable error strings, the same
+ * errors keyed by JSON Pointer, and a boolean summary.
+ *
+ * The pointer form lets callers attribute an error to a specific field --
+ * needed to surface errors that are not currently on screen (e.g. a badge on
+ * a form tab whose fields are hidden). `errors` remains the flat message list.
  *
  * Pure function -- no React, no side effects.
  */
 
+/** A validation error attributed to the field that produced it. */
+interface FieldError {
+    /**
+     * JSON Pointer (RFC 6901) to the offending field, e.g. `/email`,
+     * `/contact/email`, or `/tags/2/label` for the third array item.
+     */
+    pointer: string;
+    /** Human-readable message, e.g. "Contact > Email is required". */
+    message: string;
+}
 interface ValidationResult {
+    /** Flat, human-readable messages (in field declaration order). */
     errors: string[];
+    /** The same errors, each attributed to its field via a JSON Pointer. */
+    fieldErrors: FieldError[];
     isValid: boolean;
 }
 /**
@@ -579,4 +761,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 FormDiff, type JsonSchema, type JsonSchemaProperty, type UILayoutConfig, type UILayoutRowConfig, type UISchema, type UISchemaOptions, type ValidationResult, type ValueChange, WIDTH_TOKEN_REMS, type WidthToken, applySchemaDefaults, diffFormData, extractEnumValues, extractSchemaDefaults, generateJsonSchemaFromVariables, getFieldConstraints, getFieldDefault, getFieldHelpText, getFieldPlaceholder, getFieldTitle, getFieldType, getFieldWidget, getOptionalFields, getRequiredFields, getSchemaProperties, hasConditionals, hasProperties, isFieldOptional, isFieldRequired, isNullableBoolean, 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 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, resolveRefs, resolveSchema, toJsonSchema, validateFormData, validateSchema };