@petrarca/sonnet-core 0.1.0

package/dist/schema/index.d.ts

@@ -0,0 +1,533 @@
+import { z } from 'zod';
+
+/**
+ * Generic JSON Schema type definitions.
+ *
+ * These types follow Draft 2020-12 and include x-ui-* extension points
+ * for form/widget integration. They are domain-agnostic -- no
+ * application-specific entity concepts live here.
+ */
+/**
+ * JSON Schema property definition following Draft 2020-12 specification.
+ * Supports basic types, validation constraints, conditionals, and custom extensions.
+ */
+type JsonSchemaProperty = {
+    type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "null";
+    title?: string;
+    description?: string;
+    default?: any;
+    const?: any;
+    enum?: any[];
+    pattern?: string;
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    items?: JsonSchemaProperty;
+    minItems?: number;
+    maxItems?: number;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    $ref?: string;
+    allOf?: JsonSchemaProperty[];
+    anyOf?: JsonSchemaProperty[];
+    oneOf?: JsonSchemaProperty[];
+    not?: JsonSchemaProperty;
+    if?: JsonSchemaProperty;
+    then?: JsonSchemaProperty;
+    else?: JsonSchemaProperty;
+    "x-ui-order"?: string[];
+    "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. */
+        order?: number;
+        /** Exclude this column from the table entirely. */
+        hidden?: boolean;
+        /** Fixed column width in pixels. */
+        width?: number;
+        /** Minimum column width in pixels. */
+        minWidth?: number;
+    };
+    /** Cell renderer name. Inferred from type+format when absent. */
+    "x-ui-cell"?: string;
+    /** Cell renderer configuration options (colors, href template, etc.). */
+    "x-ui-cell-options"?: Record<string, unknown>;
+};
+/**
+ * JSON Schema following Draft 2020-12 specification.
+ *
+ * This is the generic base type. Domain-specific consumers extend it
+ * with their own x-* extension keys via intersection types in their
+ * own type files.
+ */
+type JsonSchema = {
+    $schema?: string;
+    title: string;
+    type: "object";
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    allOf?: JsonSchemaProperty[];
+    anyOf?: JsonSchemaProperty[];
+    oneOf?: JsonSchemaProperty[];
+    not?: JsonSchemaProperty;
+    if?: JsonSchemaProperty;
+    then?: JsonSchemaProperty;
+    else?: JsonSchemaProperty;
+    $defs?: Record<string, JsonSchemaProperty>;
+    definitions?: Record<string, JsonSchemaProperty>;
+    "x-ui-order"?: string[];
+    [key: `x-${string}`]: unknown;
+};
+/**
+ * UISchema - User Interface Schema configuration.
+ *
+ * Defines how form fields should be rendered and behave in the UI.
+ * Separate from JSON Schema (which defines data structure) and focuses
+ * on presentation, widgets, and user interaction.
+ */
+interface UISchema {
+    /** Widget name (string) or direct component reference */
+    "x-ui-widget"?: string | object;
+    "x-ui-options"?: UISchemaOptions;
+    "x-ui-globalOptions"?: UISchemaOptions;
+    "x-ui-order"?: string[];
+    "x-ui-title"?: string | false;
+    "x-ui-description"?: string;
+    "x-ui-placeholder"?: string;
+    "x-ui-help"?: string;
+    /** Column override -- merged over schema-level x-ui-column, UI schema wins. */
+    "x-ui-column"?: JsonSchemaProperty["x-ui-column"] & {
+        label?: string;
+    };
+    /** Cell renderer override. */
+    "x-ui-cell"?: string;
+    /** Cell renderer options override -- shallow-merged over schema-level x-ui-cell-options. */
+    "x-ui-cell-options"?: Record<string, unknown>;
+    /** Per-field UISchema for nested sub-forms (ObjectWidget / ArrayWidget) */
+    "x-ui-fields"?: {
+        [fieldName: string]: UISchema;
+    };
+    /** Layout config forwarded to the active template (ObjectWidget / ArrayWidget) */
+    "x-ui-layout"?: UILayoutConfig;
+    /** Extension keys not yet enumerated above */
+    [key: `x-ui-${string}`]: unknown;
+}
+/**
+ * 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.
+ *
+ * Examples:
+ *   { fields: ["first_name", "last_name"], columns: "1fr 1fr" }
+ *   { fields: ["npi", "specialty", "email"], columns: "20% 1fr 1fr" }
+ *   { fields: ["start_date", "end_date"], columns: "200px 1fr", gap: 8 }
+ */
+interface UILayoutRowConfig {
+    fields: string[];
+    columns?: string;
+    gap?: number;
+}
+/**
+ * UILayoutConfig -- layout configuration for ObjectWidget and ArrayWidget.
+ *
+ * Configures the built-in default templates. Has no effect when a custom
+ * template is registered for the field.
+ */
+interface UILayoutConfig {
+    direction?: "vertical" | "horizontal";
+    rows?: UILayoutRowConfig[];
+    columns?: string;
+    gap?: number;
+    labels?: boolean;
+    compact?: boolean;
+}
+/**
+ * ValueChange -- a single scalar or nested-object field that changed value.
+ *
+ * `path` is a dot-separated field path: "name", "address.city".
+ */
+type ValueChange = {
+    type: "value";
+    path: string;
+    from: unknown;
+    to: unknown;
+};
+/**
+ * ArrayItemChange -- one item-level change within an array field.
+ *
+ * Items are identified by their form-internal `_fid` (never the server ID).
+ * A single item can appear as both "moved" and "modified" if it was
+ * repositioned and its values also changed -- these are emitted as two
+ * separate entries with the same `fid`.
+ */
+type ArrayItemChange = {
+    type: "added";
+    fid: string;
+    index: number;
+    item: unknown;
+} | {
+    type: "removed";
+    fid: string;
+    index: number;
+    item: unknown;
+} | {
+    type: "moved";
+    fid: string;
+    from: number;
+    to: number;
+} | {
+    type: "modified";
+    fid: string;
+    index: number;
+    changes: ValueChange[];
+};
+/**
+ * FieldDiff -- the diff for one top-level form field.
+ */
+type FieldDiff = ValueChange | {
+    type: "array";
+    field: string;
+    changes: ArrayItemChange[];
+};
+/**
+ * FormDiff -- structured diff produced by diffFormData().
+ *
+ * One entry per changed top-level field. Fields whose value is deeply
+ * equal between original and updated are omitted.
+ */
+type FormDiff = FieldDiff[];
+/**
+ * UISchemaOptions - Widget configuration options.
+ */
+interface UISchemaOptions {
+    label?: string | false;
+    disabled?: boolean;
+    readonly?: boolean;
+    compact?: boolean;
+    enumNames?: Record<string | number, string>;
+    inputType?: string;
+    rows?: number;
+    searchable?: boolean;
+    clearable?: boolean;
+    [key: string]: any;
+}
+
+/**
+ * Schema Service - Pure functions for JSON Schema manipulation.
+ *
+ * Generic, domain-agnostic utilities for reading and inspecting JSON
+ * Schema structures. No React, no HTTP, no side effects.
+ *
+ * Domain-specific accessors (x-entity, x-graph) live in the consumer's
+ * own service layer and import from here.
+ */
+
+declare function getSchemaProperties(schema: JsonSchema): Record<string, JsonSchemaProperty>;
+declare function isFieldRequired(schema: JsonSchema, fieldName: string): boolean;
+declare function getFieldDefault(property: JsonSchemaProperty): unknown;
+type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+/**
+ * Get the effective type of a property.
+ *
+ * Unwraps the nullable anyOf pattern produced by Zod / Pydantic Optional[T]:
+ * `{ anyOf: [{ type: T }, { type: "null" }] }` → T.
+ * Falls back to "string" when no type can be determined.
+ */
+declare function getFieldType(property: JsonSchemaProperty): JsonSchemaType;
+/**
+ * Returns true when a property uses the Pydantic Optional[bool] pattern:
+ * anyOf containing both a boolean member and a null member.
+ * Used for tri-state checkbox rendering.
+ */
+declare function isNullableBoolean(property: JsonSchemaProperty): boolean;
+/**
+ * Extract enum values from a property schema.
+ *
+ * Handles both the simple case (`{ enum: [...] }`) and the nullable
+ * pattern produced by Zod (`{ anyOf: [{ type: "string", enum: [...] }, { type: "null" }] }`).
+ *
+ * Returns the enum array if found, or an empty array.
+ */
+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). */
+declare function getFieldHelpText(property: JsonSchemaProperty): string | undefined;
+declare function getFieldPlaceholder(property: JsonSchemaProperty): string | undefined;
+declare function getFieldWidget(property: JsonSchemaProperty): string | undefined;
+declare function isFieldOptional(schema: JsonSchema, fieldName: string, property: JsonSchemaProperty): boolean;
+declare function getFieldConstraints(property: JsonSchemaProperty): {
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    format?: string;
+};
+declare function getRequiredFields(schema: JsonSchema): string[];
+declare function getOptionalFields(schema: JsonSchema): string[];
+declare function hasProperties(schema: JsonSchema): boolean;
+
+/**
+ * Schema Resolver - Resolves conditional schemas (if-then-else, allOf, etc.)
+ *
+ * This service handles JSON Schema conditionals by evaluating conditions
+ * based on form data and merging the appropriate schema branches.
+ *
+ * Based on react-jsonschema-form's retrieveSchema implementation.
+ *
+ * Supported features:
+ * - if-then-else conditionals
+ * - allOf schema merging
+ * - Nested conditionals (if-then-else inside allOf)
+ *
+ * @module services/schemaResolver
+ */
+
+/**
+ * Resolve conditional schema based on form data
+ *
+ * Evaluates if-then-else conditions and merges allOf schemas to produce
+ * a final schema with only the properties that should be visible given
+ * the current form data.
+ *
+ * @param schema - Original JSON Schema with conditionals
+ * @param formData - Current form data to evaluate conditions against
+ * @returns Resolved schema with conditionals merged
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   properties: { taxonomy: { type: 'string', enum: ['Tech', 'Arch'] } },
+ *   allOf: [
+ *     {
+ *       if: { properties: { taxonomy: { const: 'Tech' } } },
+ *       then: { properties: { tech_field: { type: 'string' } } }
+ *     }
+ *   ]
+ * };
+ *
+ * const resolved = resolveSchema(schema, { taxonomy: 'Tech' });
+ * // Result: { properties: { taxonomy: {...}, tech_field: {...} } }
+ * ```
+ */
+declare function resolveSchema(schema: JsonSchema, formData: Record<string, any>): JsonSchema;
+/**
+ * Validate formData against a schema
+ *
+ * Useful for checking if form data meets schema requirements,
+ * including type validation and format checking.
+ *
+ * @param schema - JSON Schema to validate against
+ * @param formData - Form data to validate
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateSchema(schema, { name: 'John', age: 'invalid' });
+ * if (!result.valid) {
+ *   errorLog(result.errors); // AJV error objects
+ * }
+ * ```
+ */
+declare function validateSchema(schema: JsonSchema, formData: Record<string, any>): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * Check if a value matches a const constraint
+ *
+ * Helper for evaluating const conditions in conditionals.
+ *
+ * @param value - Value to check
+ * @param constValue - Expected const value
+ * @returns true if value matches const
+ */
+declare function matchesConst(value: any, constValue: any): boolean;
+/**
+ * Check if a schema has conditionals
+ *
+ * Useful for determining if schema resolution is needed.
+ *
+ * @param schema - JSON Schema to check
+ * @returns true if schema contains if-then-else or allOf
+ */
+declare function hasConditionals(schema: JsonSchema): boolean;
+
+/**
+ * Schema utilities
+ *
+ * Pure functions for common JSON Schema operations:
+ * - Applying schema defaults to form data
+ * - Extracting default values from a schema
+ * - Generating a schema from a list of template variables
+ *
+ * All functions are side-effect free.
+ *
+ * @module services/schema/schemaUtils
+ */
+
+/**
+ * Merge schema default values into an existing data object.
+ *
+ * For each property in the schema that has a `default` value, if the
+ * corresponding key is absent (`undefined`) in `data`, the default is applied.
+ * Existing values — including `null` and `false` — are never overwritten.
+ *
+ * @param data - Existing form data (may be partial)
+ * @param schema - JSON Schema containing property defaults
+ * @returns New object with defaults filled in for missing keys
+ */
+declare function applySchemaDefaults(data: Record<string, unknown>, schema: JsonSchema | JsonSchemaProperty): Record<string, unknown>;
+/**
+ * Extract all default values declared in a JSON Schema.
+ *
+ * Walks the schema's top-level properties and collects any `default` values.
+ * Properties without a `default` are omitted from the result.
+ *
+ * @param schema - JSON Schema to extract defaults from
+ * @returns Record of field names to their default values
+ *
+ * @example
+ * ```ts
+ * extractSchemaDefaults({
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string', default: 'John' },
+ *     age:  { type: 'number' },
+ *   },
+ * });
+ * // => { name: 'John' }
+ * ```
+ */
+declare function extractSchemaDefaults(schema: JsonSchema): Record<string, unknown>;
+/**
+ * Generate a JSON Schema from a list of template variable names.
+ *
+ * Each variable becomes a required string property with a capitalised title.
+ * If an existing schema is provided, its property definitions are preserved
+ * for variables that still appear in the list; new variables are added as plain
+ * strings; properties no longer in the list are dropped.
+ *
+ * @param variables - Variable names to include in the schema
+ * @param existingSchema - Optional schema to merge with (preserves extensions)
+ * @returns A JSON Schema object with one property per variable
+ *
+ * @example
+ * ```ts
+ * generateJsonSchemaFromVariables(['productId', 'limit']);
+ * // => {
+ * //   type: 'object',
+ * //   properties: {
+ * //     productId: { type: 'string', title: 'ProductId' },
+ * //     limit:     { type: 'string', title: 'Limit' },
+ * //   },
+ * //   required: ['productId', 'limit'],
+ * // }
+ * ```
+ */
+declare function generateJsonSchemaFromVariables(variables: string[], existingSchema?: {
+    properties?: Record<string, JsonSchemaProperty>;
+}): JsonSchema;
+
+/**
+ * Zod-to-JSON-Schema conversion with x-ui-* metadata passthrough.
+ *
+ * Wraps z.toJSONSchema() with an override that copies all .meta() keys
+ * into the generated JSON Schema output, including x-ui-* extension keys
+ * used by the form renderer.
+ *
+ * @module lib/schema/zodSchema
+ */
+
+/**
+ * Convert a Zod schema to a JsonSchema compatible with the form renderer.
+ *
+ * All fields annotated with .meta() -- including x-ui-widget, x-ui-order,
+ * x-ui-options, title, description -- are passed through to the output.
+ *
+ * @example
+ * ```typescript
+ * const MySchema = z.object({
+ *   name: z.string().meta({ title: "Name" }),
+ *   notes: z.string().optional().meta({ "x-ui-widget": "textarea" }),
+ * });
+ *
+ * const jsonSchema = toJsonSchema(MySchema);
+ * type MyData = z.infer<typeof MySchema>;
+ * ```
+ */
+declare function toJsonSchema(schema: z.ZodType): JsonSchema;
+
+/**
+ * $ref Resolution -- resolves local 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.
+ *
+ * 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.
+ *
+ * Only local refs (starting with "#/") are supported. External URIs
+ * are left as-is -- a future pluggable SchemaResolver interface will
+ * handle those.
+ */
+
+/**
+ * Resolve all local $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.
+ */
+declare function resolveRefs(schema: JsonSchema): 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.
+ *
+ * Pure function -- no React, no side effects.
+ */
+
+interface ValidationResult {
+    errors: string[];
+    isValid: boolean;
+}
+/**
+ * Validate form data against a JSON Schema, recursing into nested objects
+ * and array items.
+ */
+declare function validateFormData(schema: JsonSchema, data: Record<string, unknown>): ValidationResult;
+
+/**
+ * diffFormData -- structural diff between two form data snapshots.
+ *
+ * Produces a FormDiff that classifies every change at field level (value
+ * changes, nested object changes) and at array item level (add, remove,
+ * move, modify). Array items are matched by their form-internal `_fid`
+ * field, which is assigned by ArrayWidget and never sent to the server.
+ *
+ * Items that lack a `_fid` (e.g. items that arrived before the form
+ * system assigned IDs) are matched by position as a fallback.
+ */
+
+/**
+ * Compute a structural diff between two form data snapshots.
+ */
+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 };