@petrarca/sonnet-core 0.7.0 → 0.9.0

package/dist/schema/index.d.ts

@@ -1,353 +1,8 @@
+import { J as JsonSchemaProperty, a as JsonSchema, U as UIRule, A as AdditionalBinding, C as ConceptCoding, b as CodeableConcept, F as FormDiff } from '../types-HhzIKd1R.js';
+export { c as ArrayItemChange, B as Binding, d as BindingStrength, e as CODEABLE_CONCEPT_TYPE, f as CODEABLE_CONCEPT_TYPE_ID, g as CODING_TYPE, h as CODING_TYPE_ID, i as CORE_TYPES_BASE, j as CORE_VALUE_TYPES, k as Coding, l as CodingMatch, m as FieldDiff, Q as QUANTITY_TYPE, n as QUANTITY_TYPE_ID, o as Quantity, p as QuantityComparator, R as RefResolver, q as UCUM_SYSTEM, r as UILayoutConfig, s as UILayoutGroupConfig, t as UILayoutRowConfig, u as UIRuleCondition, v as UIRuleEffect, w as UISchema, x as UISchemaOptions, y as UIValidate, z as UIValidateRef, V as ValueChange, D as ValueType, W as WIDTH_TOKEN_REMS, E as WidthToken, G as bindingLists, H as bindingOf, I as codeToken, K as codingKey, L as coreType, M as coreTypeOf, N as parseCodeToken, O as resolveRefs, P as valueTypeResolver } from '../types-HhzIKd1R.js';
 import Ajv from 'ajv';
 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.
- */
-/**
- * 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.
- */
-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;
-    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-placeholder"?: string;
-    "x-ui-description"?: string;
-    "x-ui-column"?: {
-        /**
-         * 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;
-        /** 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;
-};
-/**
- * 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.
- *
- * 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[];
-    /** 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;
-    /** 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;
-    };
-    /** 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.
- * 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"], widths: ["md", "full"] }
- *   { fields: ["npi", "specialty", "email"], columns: "20% 1fr 1fr" }
- *   { 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.
- *
- * 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[];
-    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.
- *
- * `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;
-    /** 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;
-}
-
 /**
  * Schema Service - Pure functions for JSON Schema manipulation.
  *
@@ -376,11 +31,28 @@ declare function getFieldType(property: JsonSchemaProperty): JsonSchemaType;
  * Used for tri-state checkbox rendering.
  */
 declare function isNullableBoolean(property: JsonSchemaProperty): boolean;
+/**
+ * Lift the non-null member of a nullable `anyOf` onto the property.
+ *
+ * Pydantic and Zod emit `Optional[T]` as `{ anyOf: [{ type: T, ...keywords },
+ * { type: "null" }], title, default }`: the keywords a widget reads (`minimum`,
+ * `maximum`, `minLength`, `pattern`, `format`, `items`) sit on the member, out of
+ * reach of `propertySchema.minimum`. This returns the property with the
+ * member's keywords merged in -- the property's own keys (title, description,
+ * default, x-ui-*) win -- and `anyOf` kept, so nullability checks
+ * (`isNullableBoolean`, `isFieldOptional`) still see it.
+ *
+ * Any other shape -- no anyOf, several non-null members, an object member -- is
+ * returned unchanged.
+ */
+declare function liftNullableMember(property: JsonSchemaProperty): JsonSchemaProperty;
 /**
  * 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" }] }`).
+ * Handles the simple case (`{ enum: [...] }`), the nullable pattern produced
+ * by Zod (`{ anyOf: [{ type: "string", enum: [...] }, { type: "null" }] }`),
+ * and an array of enum items (`{ type: "array", items: { enum: [...] } }`) --
+ * the choices of a multi-select.
  *
  * Returns the enum array if found, or an empty array.
  */
@@ -588,6 +260,8 @@ declare function evaluateUiRule(rule: UIRule | undefined, formData: unknown): Ru
  * 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.
+ * A nested object's properties are filled the same way, at any depth -- a
+ * group absent from `data` is added when one of its properties has a default.
  *
  * @param data - Existing form data (may be partial)
  * @param schema - JSON Schema containing property defaults
@@ -597,8 +271,9 @@ declare function applySchemaDefaults(data: Record<string, unknown>, schema: Json
 /**
  * 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.
+ * Walks the schema's properties and collects any `default` values -- a
+ * nested object's at any depth, under its key. 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
@@ -675,36 +350,80 @@ declare function generateJsonSchemaFromVariables(variables: string[], existingSc
 declare function toJsonSchema(schema: z.ZodType): JsonSchema;
 
 /**
- * $ref Resolution -- resolves JSON Schema references.
- *
- * 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).
- *
- * 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).
- *
- * 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.
+ * A codeable concept's codings by its lists -- shared by its widget and its
+ * validation. A list on a code system claims the coding of that system; a list
+ * on a value set -- whose codes carry the system of the code system they come
+ * from -- takes the codings left, in their order. A coding no list claims is
+ * one of a list the field does not name. See docs/design/codeable-concepts.md
+ * (workspace).
  */
 
-/** Resolve a `$ref` string to its target sub-schema, or undefined if unknown. */
-type RefResolver = (ref: string) => JsonSchemaProperty | undefined;
+/** A value as a codeable concept: an object, else an empty one. */
+declare function conceptOf(value: unknown): CodeableConcept;
+/** A value's codings by list -- the lists in their order -- and those of no list. */
+declare function codingsByList(value: unknown, lists: AdditionalBinding[]): {
+    byList: (ConceptCoding | undefined)[];
+    others: ConceptCoding[];
+};
+/** What a list is called beside the others: its title, its purpose's label, else its identifier's last part. */
+declare function listTitle(list: AdditionalBinding): string;
 /**
- * Resolve `$ref` pointers in a JSON Schema document.
- *
- * 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.
+ * The required lists a value has no coding of. Only a value with codings is
+ * held to them: a text alone is the answer when no code fits.
+ */
+declare function missingLists(prop: JsonSchemaProperty, value: unknown): AdditionalBinding[];
+
+/**
+ * A property of a value type: its `$ref` -- or, when it also takes a text of
+ * one's own, `anyOf: [{ $ref }, { type: "string" }]`. The second is the open
+ * question of FHIR (R4 `open-choice`, R5 `optionsOrString`) and openEHR's
+ * `DV_TEXT` where `DV_CODED_TEXT` is offered: the answer is a value of the
+ * type, or a text -- never a value of the type without its own content. See
+ * docs/design/coded-values.md (workspace).
+ */
+
+/** The value type a property is of, whether it also takes a text, and whether it takes several. */
+interface ValueRef {
+    ref: string;
+    orText: boolean;
+    /** Several answers: an array of the type (or of it or a text). */
+    multiple: boolean;
+}
+/**
+ * The value type of a property: its `$ref`, or that of a `$ref` or a text --
+ * or of an array of either, for several answers; undefined for none of them.
+ */
+declare function valueRefOf(prop: JsonSchemaProperty): ValueRef | undefined;
+/**
+ * The keywords of a property of a value type -- its `$ref`, or that or a text;
+ * several answers an array of it -- the others undefined, so writing them
+ * replaces the shape a property had.
+ */
+declare function valueRefKeywords(ref: string, orText: boolean, multiple?: boolean): Pick<JsonSchemaProperty, "$ref" | "anyOf" | "type" | "items">;
+
+/**
+ * A quantity's range per unit -- 0 to 300 kg, 0 to 660 lb -- in standard JSON
+ * Schema, beside the quantity's `$ref`: one `allOf` entry per unit, "if the
+ * unit is kg, then the value is in its range". A range is the unit's, as a
+ * number means nothing without one. See docs/design/core-types.md.
+ */
+
+/** A unit's range: its least and greatest value, either optional. */
+interface UnitRange {
+    min?: number;
+    max?: number;
+}
+/** The ranges of a quantity's units, by unit code. */
+type UnitRanges = Record<string, UnitRange>;
+/**
+ * The ranges a quantity's schema sets per unit; empty when it sets none, and
+ * undefined when its `allOf` says something else -- not ranges to edit.
  */
-declare function resolveRefs(schema: JsonSchema, resolve?: RefResolver): JsonSchema;
+declare function unitRangesOf(prop: JsonSchemaProperty): UnitRanges | undefined;
+/** The keywords that set a quantity's ranges, by unit; a unit without a bound sets none. */
+declare function unitRangesKeywords(ranges: UnitRanges): {
+    allOf?: JsonSchemaProperty[];
+};
 
 /**
  * Recursive form data validation against a JSON Schema.
@@ -741,9 +460,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.
  *
@@ -785,5 +564,14 @@ declare function diffFormData(original: Record<string, unknown>, updated: Record
  * declares. Returns the input unchanged when nothing needed stamping.
  */
 declare function ensureFormItemIds(data: Record<string, unknown>, schema: JsonSchema): Record<string, unknown>;
+/**
+ * Return `data` without any `_fid` -- the inverse of `ensureFormItemIds`.
+ *
+ * Item ids are the renderer's own bookkeeping: they must not reach a consumer
+ * nor be validated against the schema (an item schema with
+ * `additionalProperties: false` would reject them).
+ */
+declare function stripFormItemIds(data: Record<string, unknown>): 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 };
+export { AdditionalBinding, CodeableConcept, ConceptCoding, FormDiff, JsonSchema, JsonSchemaProperty, UIRule, ajv, applySchemaDefaults, codingsByList, conceptOf, 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, liftNullableMember, listTitle, matchesConst, mergeFieldErrors, missingLists, resolveSchema, stripFormItemIds, toJsonSchema, unitRangesKeywords, unitRangesOf, validateContentConstraints, validateFormData, validateSchema, valueRefKeywords, valueRefOf };
+export type { FieldError, RuleState, UnitRange, UnitRanges, ValidationResult, ValueRef };