@petrarca/sonnet-core 0.4.2 → 0.6.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,20 +56,34 @@ 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;
@@ -85,6 +131,21 @@ type JsonSchema = {
     "x-ui-order"?: string[];
     [key: `x-${string}`]: unknown;
 };
+/**
+ * WidthToken -- the shared semantic sizing vocabulary used across the form
+ * layout system: per-field slot width (x-ui-width) and per-column width
+ * (UILayoutRowConfig.widths). "full" fills available space; sm/md/lg are
+ * fixed inline sizes. Raw CSS remains available as an advanced escape hatch.
+ */
+type WidthToken = "sm" | "md" | "lg" | "full";
+/**
+ * The fixed rem values for each non-full WidthToken. This is the single source
+ * of truth for token sizing used by:
+ *  - the CSS grid track map in JsonSchemaFormRenderer (sm -> "8rem" track)
+ *  - the Tailwind class map in FormFieldRenderer (sm -> w-32 = 8rem)
+ * Consumers that need px can multiply by 16.
+ */
+declare const WIDTH_TOKEN_REMS: Record<WidthToken, string>;
 /**
  * UISchema - User Interface Schema configuration.
  *
@@ -98,10 +159,14 @@ 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. */
     "x-ui-column"?: JsonSchemaProperty["x-ui-column"] & {
         label?: string;
@@ -123,18 +188,70 @@ interface UISchema {
  * UILayoutRowConfig -- one horizontal row in a multi-column object form layout.
  *
  * `fields` lists the field names to place in this row, left to right.
- * `columns` is a raw CSS grid-template-columns string (default: equal 1fr
- * per field). `gap` overrides the parent layout gap for this row only.
+ * Column sizing (grid mode) is resolved in this precedence:
+ *   1. `columns` -- raw CSS grid-template-columns (advanced escape hatch).
+ *   2. `widths`  -- per-cell semantic tokens (the designer-friendly path).
+ *   3. default   -- equal 1fr per field.
+ * `gap` overrides the parent layout gap for this row only.
+ *
+ * `group` renders the row inside a titled fieldset (presentation-only grouping
+ * over flat schema fields -- the data shape is unchanged).
  *
  * Examples:
- *   { fields: ["first_name", "last_name"], columns: "1fr 1fr" }
+ *   { fields: ["first_name", "last_name"], widths: ["md", "full"] }
  *   { fields: ["npi", "specialty", "email"], columns: "20% 1fr 1fr" }
- *   { fields: ["start_date", "end_date"], columns: "200px 1fr", gap: 8 }
+ *   { group: "Contact", fields: ["email", "phone"] }
  */
 interface UILayoutRowConfig {
     fields: string[];
     columns?: string;
+    /**
+     * Per-cell semantic widths, aligned to `fields` by index. Translated to grid
+     * tracks: sm/md/lg -> fixed rem tracks, full -> 1fr. Ignored when `columns`
+     * is set (raw CSS wins) or in "flow" mode. Missing/short entries default to
+     * "full".
+     */
+    widths?: WidthToken[];
     gap?: number;
+    /**
+     * Optional title. When set, the row renders inside a <fieldset> with a
+     * <legend>, grouping its fields visually without nesting them in the schema.
+     */
+    group?: string;
+    /**
+     * How this row arranges its fields:
+     *  - "grid" (default): CSS grid using `columns`/`widths` (equal 1fr per field
+     *    when neither is set).
+     *  - "flow": flex row, fields at their natural width, left-to-right, wrapping.
+     *    Use for compact toolbars / tight field groups. `columns`/`widths` are
+     *    ignored.
+     */
+    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.
@@ -145,10 +262,13 @@ interface UILayoutRowConfig {
 interface UILayoutConfig {
     direction?: "vertical" | "horizontal";
     rows?: UILayoutRowConfig[];
+    groups?: UILayoutGroupConfig[];
+    variant?: "tabs" | "stepper" | "sections" | (string & {});
     columns?: string;
     gap?: number;
     labels?: boolean;
     compact?: boolean;
+    labelPlacement?: "top" | "start";
 }
 /**
  * ValueChange -- a single scalar or nested-object field that changed value.
@@ -218,6 +338,12 @@ 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"). */
+    width?: WidthToken;
     [key: string]: any;
 }
 
@@ -277,6 +403,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.)
  *
@@ -293,6 +451,7 @@ declare function hasProperties(schema: JsonSchema): boolean;
  * @module services/schemaResolver
  */
 
+declare const ajv: Ajv;
 /**
  * Resolve conditional schema based on form data
  *
@@ -363,6 +522,33 @@ 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).
+ */
+
+/** 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
  *
@@ -469,42 +655,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;
 }
 /**
@@ -530,4 +741,4 @@ 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, 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 };
+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 };