@petrarca/sonnet-forms 0.7.0 → 0.9.0

package/README.md

@@ -10,8 +10,8 @@ labelled, validated controls.
 flattening against the current values, schema defaults, nested objects and
 arrays, buffered or live editing, and a change set on save.
 
-**A widget registry.** Sixteen built-in controls covering text, numbers,
-quantities, enums, checkboxes, tags, arrays, objects, entity references and
+**A widget registry.** Twenty-two built-in controls covering text, numbers,
+quantities, coded values and codeable concepts, dates and times, enums, checkboxes, tags, arrays, objects, entity references and
 embedded JSON, plus your own controls keyed by `x-ui-widget`. A parallel
 template registry makes the structure around a field -- the array-item row, the
 object container, the group chrome -- replaceable without touching the widgets.
@@ -91,8 +91,8 @@ actually enforces are in [getting started](docs/usage/getting-started.md).
   [templates](docs/usage/templates.md),
   [field components](docs/usage/field-components.md) and
   [change tracking](docs/usage/change-tracking.md).
-- [Design docs](docs/design/index.md) -- form layout, nested fields and the
-  change-tracking model.
+- [Design docs](docs/design/index.md) -- form layout, nested fields, the
+  change-tracking model, and custom validation.
 - [Workspace documentation](../../docs/README.md) -- how the packages layer and
   the shared schema extension contract.
 

package/dist/index.d.ts

@@ -1,12 +1,23 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
 import React__default, { ComponentType, ReactNode } from 'react';
 import { Input, Textarea, badgeVariants } from '@petrarca/sonnet-ui';
-import { JsonSchemaProperty, UILayoutConfig, JsonSchema, UISchema, UISchemaOptions, FormDiff, RefResolver, FieldError } from '@petrarca/sonnet-core/schema';
+import { JsonSchema, JsonSchemaProperty, UISchema, UISchemaOptions, UILayoutConfig, FieldError, FormDiff, RefResolver } from '@petrarca/sonnet-core/schema';
 export { UISchema, UISchemaOptions } from '@petrarca/sonnet-core/schema';
 import { VariantProps } from 'class-variance-authority';
 import { SaveWhenInvalid, ValidationDisplay } from '@petrarca/sonnet-core/config';
 
+/**
+ * FormFieldWrapper - Shared label / description / error chrome for form fields.
+ *
+ * Eliminates duplication across FormInput, FormNumberInput, FormQuantityInput,
+ * etc. Each field component renders its control as `children` and delegates
+ * the surrounding chrome here.
+ *
+ * Supports two modes:
+ * - Normal: label, children, description, error displayed vertically
+ * - Compact: suppresses label, description, error text (for grid layouts)
+ */
+
 interface FormFieldWrapperProps {
     /** Field id -- wired to the label's htmlFor */
     inputId: string;
@@ -39,7 +50,7 @@ interface FormFieldWrapperProps {
  * FormFieldWrapper renders label, children (the control), description, and
  * error in the standard vertical layout used by all form field components.
  */
-declare function FormFieldWrapper({ inputId, label, description, error, required, compact, labelPlacement, className, children, }: FormFieldWrapperProps): react_jsx_runtime.JSX.Element;
+declare function FormFieldWrapper({ inputId, label, description, error, required, compact, labelPlacement, className, children, }: FormFieldWrapperProps): React__default.JSX.Element;
 
 /**
  * Shared utility functions for form field components.
@@ -470,6 +481,14 @@ type TemplateRegistry = {
     [templateName: string]: unknown;
 };
 
+/**
+ * FormSelect - Searchable single-select dropdown with form field wrapper
+ *
+ * Composable select component using Popover + Command for searchable,
+ * keyboard-navigable dropdown. Follows Form wrapper pattern with
+ * label, description, error support.
+ */
+
 interface FormSelectProps {
     label?: string | false;
     description?: string;
@@ -509,7 +528,15 @@ interface FormSelectProps {
     /** Called with the trimmed search text when the create item is chosen. */
     onCreate?: (label: string) => void;
 }
-declare function FormSelect(props: FormSelectProps): react_jsx_runtime.JSX.Element;
+declare function FormSelect(props: FormSelectProps): React$1.JSX.Element;
+
+/**
+ * FormMultiSelect - Searchable multi-select dropdown with badges
+ *
+ * Multi-select component using Popover + Command with badge display
+ * for selected items. Follows Form wrapper pattern with label,
+ * description, error support.
+ */
 
 type BadgeColor = NonNullable<VariantProps<typeof badgeVariants>["badgeColor"]>;
 
@@ -539,7 +566,7 @@ interface FormMultiSelectProps {
     maxDisplay?: number;
     badgeColor?: BadgeColor;
 }
-declare function FormMultiSelect(props: FormMultiSelectProps): react_jsx_runtime.JSX.Element;
+declare function FormMultiSelect(props: FormMultiSelectProps): React$1.JSX.Element;
 
 /**
  * FormTagsInput - Input field for managing tags with badges
@@ -570,6 +597,59 @@ interface FormTagsInputProps {
 }
 declare const FormTagsInput: React$1.ForwardRefExoticComponent<FormTagsInputProps & React$1.RefAttributes<HTMLInputElement>>;
 
+/**
+ * FormKeyValueInput - Input for a map of string keys to string values
+ *
+ * Each pair is entered in two fields (key, value) and added with Enter or the
+ * add button. A key is unique: adding it again replaces its value. The entered
+ * pairs are displayed one of two ways (`display`):
+ *
+ *   tags (default)  as "key:value" tags -- for short labels. Clicking a tag
+ *                   loads it back into the fields to edit it; its X removes it.
+ *   rows            as a list, a row per pair: its key and value editable in
+ *                   place (taken on leaving the field or Enter), a remove
+ *                   button -- for values too long or too many to read as tags,
+ *                   such as templates or paths.
+
+ *   keys            only the keys, as badges, each value on hover -- a compact
+ *                   summary, not edited (the host edits the pairs elsewhere,
+ *                   e.g. as rows in a dialog).
+ *
+ * `valueSuggestions` offers values to pick in the value fields (still free to
+ * type) -- e.g. the references a value may name.
+ *
+ * Follows the Form wrapper pattern with label, description, error support.
+ */
+
+interface FormKeyValueInputProps {
+    label?: string | false;
+    description?: string;
+    error?: string;
+    required?: boolean;
+    wrapperClassName?: string;
+    labelPlacement?: "top" | "start";
+    id?: string;
+    name?: string;
+    value: Record<string, string>;
+    onChange?: (value: Record<string, string>) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Placeholders of the two fields. Default "Key" / "Value". */
+    keyPlaceholder?: string;
+    valuePlaceholder?: string;
+    /** How a pair is shown as a tag. Default ":" ("key:value"). */
+    separator?: string;
+    /** How the pairs are displayed: as tags (default), as rows, or only their
+     * keys (a summary, not edited). */
+    display?: "tags" | "rows" | "keys";
+    /** Values the value fields suggest; one may still type any other. */
+    valueSuggestions?: {
+        value: string;
+        label?: string;
+    }[];
+}
+declare const FormKeyValueInput: React$1.ForwardRefExoticComponent<FormKeyValueInputProps & React$1.RefAttributes<HTMLInputElement>>;
+
 /**
  * FormQuantityInput - Compound input for a numeric value paired with a unit selector.
  *
@@ -612,8 +692,10 @@ interface FormQuantityInputProps {
     onChange?: (value: QuantityValue) => void;
     /** Blur handler */
     onBlur?: () => void;
-    /** Available unit options. Single = static text, 2+ = dropdown, none = no addon. */
+    /** Available unit options. Single = static text, 2+ = dropdown, none = no addon (or a typed unit, with `freeUnit`). */
     units?: UnitOption[];
+    /** Without units, the unit is typed -- a code such as `kg`. Default false: no unit at all. */
+    freeUnit?: boolean;
     /**
      * Default position for all units. Individual UnitOption.position overrides
      * this. Default: "suffix".
@@ -673,13 +755,18 @@ interface FormActionsProps {
     saveLabel?: string;
     cancelLabel?: string;
     showCancel?: boolean;
+    /**
+     * True while an async validator is in flight. Save is disabled until it
+     * settles (validity is not yet known); Cancel stays enabled.
+     */
+    isValidating?: boolean;
     /**
      * Optional content rendered left-aligned in the action row (e.g. a secondary
      * action like "Test connection"). Cancel/Save stay grouped on the right.
      */
     leadingActions?: ReactNode;
 }
-declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveWhenInvalid, saveLabel, cancelLabel, showCancel, leadingActions, }: FormActionsProps): react_jsx_runtime.JSX.Element;
+declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveWhenInvalid, saveLabel, cancelLabel, showCancel, isValidating, leadingActions, }: FormActionsProps): React$1.JSX.Element;
 
 type Props = {
     properties: Record<string, any>;
@@ -692,7 +779,7 @@ type Props = {
  * This is a generic component that can be used anywhere a schema and properties
  * need to be compared to show additional/extra properties.
  */
-declare function ExtraPropertiesCard({ properties, schema }: Props): react_jsx_runtime.JSX.Element | null;
+declare function ExtraPropertiesCard({ properties, schema }: Props): React$1.JSX.Element | null;
 
 /**
  * TextInputWidget - Standard text input widget
@@ -723,7 +810,7 @@ declare function TextInputWidget({ id, name, value, onChange, onBlur, propertySc
  *
  * @param props - WidgetProps
  */
-declare function TextareaWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): react_jsx_runtime.JSX.Element;
+declare function TextareaWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): React$1.JSX.Element;
 
 /**
  * NumberWidget renders a number input field.
@@ -736,7 +823,7 @@ declare function TextareaWidget({ id, name, value, onChange, onBlur, propertySch
  *
  * @param props - WidgetProps
  */
-declare function NumberWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): react_jsx_runtime.JSX.Element;
+declare function NumberWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): React$1.JSX.Element;
 
 /**
  * CheckboxWidget - Boolean checkbox widget
@@ -745,7 +832,8 @@ declare function NumberWidget({ id, name, value, onChange, onBlur, propertySchem
  * Used for boolean type fields.
  *
  * Supports tri-state behavior for nullable boolean fields (anyOf[boolean, null]):
- * - null (indeterminate) -> true (checked) -> false (unchecked) -> null
+ * - null or no value (indeterminate) -> true (checked) -> false (unchecked) -> null
+ * No value is shown as null is: not answered -- unchecked would read as "no".
  */
 
 /**
@@ -758,13 +846,13 @@ declare function NumberWidget({ id, name, value, onChange, onBlur, propertySchem
  * - Description text
  *
  * Tri-state behavior (when anyOf[boolean, null] is detected):
- * - Click on null -> becomes true
+ * - Click on null, or no value -> becomes true
  * - Click on true -> becomes false
  * - Click on false -> becomes null
  */
 declare function CheckboxWidget({ id, value, onChange, onBlur, disabled, readonly, rawErrors, label, description, autofocus, propertySchema, options, }: WidgetProps): React.ReactElement;
 
-declare function SelectWidget(props: WidgetProps): react_jsx_runtime.JSX.Element;
+declare function SelectWidget(props: WidgetProps): React$1.JSX.Element;
 
 /**
  * TagsInputWidget - Free-text tag input widget
@@ -805,9 +893,24 @@ declare function TagsInputWidget({ id, name, value, onChange, required, disabled
  * - Full document editing (no readonly regions)
  * - Invalid JSON is silently retained until fixed
  * - Height configurable via x-ui-options.height (default: "240px")
+ * - The editor loads on first use (a placeholder of that height meanwhile)
  */
 declare function JsonEditorWidget({ id, value, onChange, label, description, required, options, }: WidgetProps): React__default.ReactElement;
 
+/**
+ * KeyValueWidget - Key-value pair input widget
+ *
+ * Renders FormKeyValueInput for an object of string values (a free map such as
+ * labels: `additionalProperties: { type: "string" }`, no declared properties).
+ * Pairs are entered in a key and a value field and shown as "key:value" tags,
+ * or -- `x-ui-options: { display: "rows" }` -- as rows edited in place, for long
+ * values such as templates or paths, or -- `display: "keys"` -- only the keys,
+ * a summary not edited. Chosen automatically for such maps;
+ * explicitly via x-ui-widget: "key-value".
+ */
+
+declare function KeyValueWidget({ id, name, value, onChange, required, disabled, readonly, rawErrors, label, description, options, }: WidgetProps): React__default.ReactElement;
+
 /**
  * EntitySelectWidget -- form widget for async entity reference selection.
  *
@@ -873,9 +976,68 @@ declare function ObjectWidget({ id, propertySchema, value, onChange, onBlur, reg
  * never leave the renderer boundary.
  */
 
-declare function ArrayWidget({ propertySchema, value, onChange, registry, uiSchema, disabled, readonly, label, description, options, schema, name, }: WidgetProps): React.ReactElement;
+declare function ArrayWidget({ propertySchema, value, onChange, registry, uiSchema, disabled, readonly, label, description, options, schema, name, onBlur, }: WidgetProps): React.ReactElement;
 
-declare function QuantityWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): react_jsx_runtime.JSX.Element;
+declare function QuantityWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): React$1.JSX.Element;
+
+/**
+ * CodedValueWidget -- a code from a list someone else maintains, asked of the
+ * application's terminology service (`TerminologyProvider`).
+ *
+ * The list is the field's binding (`x-binding`: a value set or a code system,
+ * its strength). What is stored the field's type decides: the core coding type
+ * stores `{ system, code, version?, display? }`; a string bound to a list stores
+ * the code alone, its label looked up to show it; a coding or a text (`anyOf`,
+ * an open list) stores a coding, or a text of one's own as a plain string --
+ * never a coding without its code. An array of any of them takes several
+ * answers, shown as chips. The first search decides whether the list is shown
+ * whole (it fits one page) or searched; a hit shows its code and, when the
+ * service gives it, its path. An open list -- a coding or a text, or an
+ * `extensible` binding on a string -- takes a typed text no code fits.
+ *
+ * Registered as x-ui-widget: "coded-value"; the core coding type carries that
+ * hint, and a string, a coding or a text, or an array bound to a list resolves
+ * to it without one.
+ *
+ * x-ui-options:
+ *   mode     - "list" | "search": overrides what the list's size decides
+ *   minChars - the characters a search waits for (default 1)
+ *   store    - the hit's property a code-only field stores (default "code")
+ *   keep     - properties of a hit a coding keeps beside its own -- an
+ *              application's, which its service returns on its hits
+ *
+ * See docs/design/coded-values.md (workspace).
+ */
+
+declare function CodedValueWidget(props: WidgetProps): React$1.ReactElement;
+
+/**
+ * CodeableConceptWidget -- one concept, coded in the field's lists, compact:
+ * the coded-value picker on the first list, and one line of chips for the
+ * codings of the others -- as clinical systems show a concept: its term, the
+ * other codes beside it.
+ *
+ *   [ Glucose [Mass/volume] in Serum or Plasma   2345-7        v ]
+ *     [Lab  GLU-S x]  [Registry *]   + Coding   + Text
+ *
+ * A chip -- or "+ Coding", for a list without one -- opens the same search on
+ * its list. What a person picks is stored as theirs (`userSelected`), with the
+ * list's purpose; a required list without a coding shows as an empty chip. A
+ * coding of a list the field does not name is shown and kept, never dropped.
+ *
+ * The lists are the field's binding (`x-binding`): the first, then
+ * `additional`. Registered as x-ui-widget: "codeable-concept"; the core
+ * codeable concept type carries that hint.
+ *
+ * x-ui-options:
+ *   text     - offer the text (default: when the first list is extensible)
+ *   mode     - "list" | "search", for every list (default: each list's size decides)
+ *   minChars - the characters a search waits for
+ *
+ * See docs/design/codeable-concepts.md (workspace).
+ */
+
+declare function CodeableConceptWidget(props: WidgetProps): React$1.ReactElement;
 
 /**
  * DateWidget - date field widget backed by the DateInput primitive.
@@ -884,6 +1046,9 @@ declare function QuantityWidget({ id, name, value, onChange, onBlur, propertySch
  * string (`YYYY`, `YYYY-MM`, or `YYYY-MM-DD`). Auto-resolves from schema
  * `format: "date"`, or `x-ui-widget: "date"`.
  *
+ * Its range is the schema's `formatMinimum` / `formatMaximum`: the calendar
+ * offers only the dates between; validation names a typed one outside.
+ *
  * x-ui-options:
  *   precision - "year" | "month" | "day" (default "day")
  *   locale    - BCP-47 locale override (defaults to the app locale)
@@ -892,7 +1057,7 @@ declare function QuantityWidget({ id, name, value, onChange, onBlur, propertySch
  * the inline error message and invalid border.
  */
 
-declare function DateWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, placeholder, options, }: WidgetProps): React.ReactElement;
+declare function DateWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, placeholder, options, propertySchema, }: WidgetProps): React.ReactElement;
 
 /**
  * TimeWidget - time-of-day field widget backed by the TimeInput primitive.
@@ -925,7 +1090,7 @@ declare function TimeWidget({ id, value, onChange, onBlur, required, disabled, r
  * the inline error message and invalid border.
  */
 
-declare function DateTimeWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, options, }: WidgetProps): React.ReactElement;
+declare function DateTimeWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, options, propertySchema, }: WidgetProps): React.ReactElement;
 
 /**
  * DisplayWidget - read-only text block, no data binding.
@@ -954,6 +1119,55 @@ declare function DisplayWidget({ label, description, }: WidgetProps): React.Reac
 
 declare function OneOfWidget({ propertySchema, value, onChange, registry, uiSchema, disabled, readonly, label, description, id, options, }: WidgetProps): React.ReactElement | null;
 
+/**
+ * RadioWidget -- a single choice as radio buttons, every option in view.
+ *
+ * For an enum property, selected by `x-ui-widget: "radio"`. Labels come from
+ * x-ui-options.enumNames, as for the select. `x-ui-options.orientation`
+ * "horizontal" lays the options out in a row (default: a column).
+ */
+
+declare function RadioWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, options, }: WidgetProps): React.ReactElement;
+
+/**
+ * CheckboxGroupWidget -- a multiple choice as checkboxes, every option in view.
+ *
+ * For an array of enum items, selected by `x-ui-widget: "checkbox-group"`.
+ * Labels come from x-ui-options.enumNames, as for the select; the value keeps
+ * the options' order. `x-ui-options.orientation` "horizontal" lays them out in
+ * a row (default: a column).
+ */
+
+declare function CheckboxGroupWidget({ id, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, options, }: WidgetProps): React.ReactElement;
+
+/**
+ * ChoiceWithTextWidget -- a choice and a text as one answer: "one of these, and
+ * add detail".
+ *
+ * A container, selected by `x-ui-widget: "choice-with-text"` on an object of
+ * `choice` (an enum) and `text` (a string). It only arranges the two -- the
+ * choice beside the text, the choice unlabelled -- and renders them as any
+ * nested object is (ObjectWidget, inline, under the question's own label):
+ * each child by its own widget, resolved as
+ * for any field. So the choice is a select, radio buttons or an application's
+ * terminology picker, set on the child (`x-ui-fields.choice`), and the text a
+ * line or a textarea.
+ */
+
+declare function ChoiceWithTextWidget(props: WidgetProps): React.ReactElement | null;
+
+/**
+ * AbsentReasonsWidget -- the questions of a section left unanswered, and why:
+ * one row each, the question and its reason (*unknown*, *not applicable*).
+ *
+ * For an object property mapping question keys to reasons, selected by
+ * `x-ui-widget: "absent-reasons"`. The reasons are its `additionalProperties`
+ * enum, labelled by x-ui-options.enumNames; the questions are its siblings in
+ * the form schema it renders in -- every field but itself and static texts.
+ */
+
+declare function AbsentReasonsWidget(props: WidgetProps): React.ReactElement;
+
 /**
  * Widget Resolution Algorithm
  *
@@ -1026,6 +1240,71 @@ declare function getDefaultWidgetForType(type: string): string;
  */
 declare const DEFAULT_WIDGETS: WidgetRegistry;
 
+/**
+ * Custom validation registry -- named field and form validators referenced from
+ * the schema via `x-ui-validate` and implemented here.
+ *
+ * See the custom-validation design in docs/design/custom-validation.md. `field`
+ * and `form` are synchronous, invoked by `runValidators` every validation pass;
+ * `asyncField` and `asyncForm` return a promise and are invoked only by
+ * `useAsyncValidators`, keyed on their inputs so a remote check fires on
+ * change, never per render.
+ */
+
+/**
+ * Context handed to every validator so a rule can reach beyond its immediate
+ * value without the caller wiring it. `formData` is the ROOT form data (carried
+ * like x-ui-rule's rootData), so a validator on a nested field can still compare
+ * against a top-level field.
+ */
+interface ValidatorContext {
+    /** The whole current form data (root), for cross-field checks. */
+    formData: Record<string, unknown>;
+    /** RFC 6901 JSON Pointer of the field being validated (field validators). */
+    path: string;
+    /** Per-reference config from the `x-ui-validate` object form (`{ name, args }`). */
+    args?: Record<string, unknown>;
+}
+/**
+ * What a SYNC validator returns. A field validator may use the `string | null`
+ * shorthand (message attached to its own field, or null when valid); a form
+ * validator returns `FieldError[]` because it decides which field each error
+ * lands on (pointer "" = form-level).
+ */
+type ValidatorResult = string | null | FieldError[];
+/** A per-value sync validator: judges one field's value. */
+type FieldValidator = (value: unknown, ctx: ValidatorContext) => string | null | FieldError[];
+/** A whole-data sync validator: cross-field / form-level rules. */
+type FormValidator = (data: Record<string, unknown>, ctx: ValidatorContext) => FieldError[];
+/**
+ * An async per-value validator -- returns a promise. Declared in its own
+ * namespace (`asyncField`) so the engine knows it is async without calling it,
+ * and invokes it only when its field value changes (never per render). A failed
+ * promise means "could not check", not "invalid".
+ */
+type AsyncFieldValidator = (value: unknown, ctx: ValidatorContext) => Promise<string | null | FieldError[]>;
+/** An async whole-data validator -- returns a promise. See `dependsOn` on the
+ * `x-ui-validate` reference to control when it re-fires. */
+type AsyncFormValidator = (data: Record<string, unknown>, ctx: ValidatorContext) => Promise<FieldError[]>;
+/**
+ * The registry: sync and async namespaces, keeping the signatures -- and the
+ * invocation strategy -- apart. Sync validators run on every validation pass;
+ * async validators are invoked only when their inputs change (the engine can
+ * tell them apart because they are declared separately, so a remote check is
+ * never fired speculatively per render). A plain object, like the widget and
+ * template registries -- no factory, no lifecycle.
+ */
+interface ValidatorRegistry {
+    /** Sync per-field validators, referenced by `x-ui-validate` on a property. */
+    field?: Record<string, FieldValidator>;
+    /** Sync whole-data validators, referenced by `x-ui-validate` on the root. */
+    form?: Record<string, FormValidator>;
+    /** Async per-field validators (promise), referenced by `x-ui-validate`. */
+    asyncField?: Record<string, AsyncFieldValidator>;
+    /** Async whole-data validators (promise), referenced by `x-ui-validate`. */
+    asyncForm?: Record<string, AsyncFormValidator>;
+}
+
 /**
  * JsonSchemaFormRenderer - Generic form renderer based on JSON Schema
  *
@@ -1132,6 +1411,22 @@ type JsonSchemaFormRendererProps = {
      * a partial registry -- unspecified keys fall back to DEFAULT_TEMPLATES.
      */
     templates?: TemplateRegistry;
+    /**
+     * Custom validator registry -- named field and form validators referenced
+     * from the schema via `x-ui-validate`, run alongside the built-in schema
+     * validation. `field`/`form` are synchronous; `asyncField`/`asyncForm`
+     * return a promise and gate Save while in flight. See
+     * docs/design/custom-validation.md.
+     */
+    validators?: ValidatorRegistry;
+    /**
+     * Externally-supplied errors (e.g. a server 422) shown as persistent field
+     * errors, keyed by JSON Pointer. Always displayed regardless of
+     * `validationDisplay`, and block Save. Should be stable/memoized. A
+     * higher-precedence error (built-in or a custom validator) on the same field
+     * wins over an extraError. See the custom-validation design.
+     */
+    extraErrors?: FieldError[];
     /**
      * When true, renders with `display: contents` instead of a SimpleStack.
      *
@@ -1198,7 +1493,7 @@ interface FormFieldRendererProps {
     /** Validation messages for this field, rendered inline by the widget. */
     rawErrors?: string[];
 }
-declare function FormFieldRenderer({ fieldName, property, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, idPrefix, rawErrors, }: FormFieldRendererProps): React__default.ReactElement | null;
+declare function FormFieldRenderer({ fieldName, property: declared, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, idPrefix, rawErrors, }: FormFieldRendererProps): React__default.ReactElement | null;
 
 /**
  * useFormEngine - Core form state, schema resolution, and update-mode logic
@@ -1248,6 +1543,29 @@ interface UseFormEngineOptions {
      * synchronous -- pre-load referenced schemas into a map and pass a lookup.
      */
     refResolver?: RefResolver;
+    /**
+     * Externally-supplied errors (e.g. a server 422), keyed by JSON Pointer.
+     * Merged into `fieldErrors` (so they affect `isValid` and block Save) with
+     * the lowest precedence -- a built-in error on the same field wins. The
+     * renderer shows them regardless of `validationDisplay`; see the
+     * custom-validation design.
+     */
+    extraErrors?: FieldError[];
+    /**
+     * Custom validator registry. Field validators (named by `x-ui-validate` on a
+     * property) and, at the root, form/cross-field validators (named on the root
+     * object) run here and merge into `fieldErrors` between built-in errors and
+     * extraErrors. The sync `field`/`form` namespaces run every pass via
+     * `runValidators`; the async `asyncField`/`asyncForm` namespaces are invoked
+     * by `useAsyncValidators` and gate Save (`isValidating`) while in flight.
+     */
+    validators?: ValidatorRegistry;
+    /**
+     * Whether this engine is the ROOT form (not a nested sub-form). Root-only
+     * concerns -- currently the whole-form/cross-field validators -- run only when
+     * true, so a nested sub-form does not re-run them against its slice.
+     */
+    isRoot?: boolean;
 }
 interface UseFormEngineResult {
     /** The current working form data (for controlled field values) */
@@ -1263,6 +1581,8 @@ interface UseFormEngineResult {
     orderedProperties: [string, JsonSchemaProperty][];
     hasChanges: boolean;
     isValid: boolean;
+    /** True while any async validator's promise is in flight. */
+    isValidating: boolean;
     /**
      * Current validation errors, each attributed to its field by JSON Pointer.
      * Lets the renderer surface problems for fields that are not on screen.
@@ -1277,7 +1597,7 @@ interface UseFormEngineResult {
     handleSave: () => void;
     handleCancel: () => void;
 }
-declare function useFormEngine({ schema, data, uiSchema, onChange, onBlur, onValidationChange, onUpdate, onCancel, readOnly, showActions, deferChanges, deferStateUpdates, allowPristineSave, refResolver, }: UseFormEngineOptions): UseFormEngineResult;
+declare function useFormEngine({ schema, data, uiSchema, onChange, onBlur, onValidationChange, onUpdate, onCancel, readOnly, showActions, deferChanges, deferStateUpdates, allowPristineSave, refResolver, extraErrors, validators, isRoot, }: UseFormEngineOptions): UseFormEngineResult;
 
 /**
  * useResolvedSchema - Schema resolution and property ordering
@@ -1336,6 +1656,17 @@ interface NestedFormContextValue {
      * it unchanged.
      */
     rootData: Record<string, unknown>;
+    /**
+     * Whether the root form's save has been attempted. A nested sub-form is a
+     * separate form-engine instance with its own submit state, which the root's
+     * Save never flips -- so without this a required field inside a nested object
+     * would never reveal its error on submit (only on touch). Carried down so a
+     * nested renderer ORs it into its own error-visibility.
+     *
+     * The outermost renderer sets this to its own submitAttempted; nested
+     * renderers inherit it unchanged.
+     */
+    submitAttempted: boolean;
 }
 
 /**
@@ -1434,4 +1765,5 @@ declare const DEFAULT_TEMPLATES: TemplateRegistry;
  */
 declare function groupTemplateKey(variant: string | undefined): string;
 
-export { type ArrayHeaderTemplate, type ArrayHeaderTemplateProps, type ArrayItemTemplate, type ArrayItemTemplateProps, ArrayWidget, CheckboxWidget, DEFAULT_TEMPLATES, DEFAULT_WIDGETS, DEFAULT_WIDGET_MAP, DateTimeWidget, DateWidget, DisplayWidget, EntitySelectWidget, ExtraPropertiesCard, type FieldGroup, FormActions, FormCheckbox, FormFieldRenderer, FormFieldWrapper, type FormFieldWrapperProps, FormInput, FormMultiSelect, FormNumberInput, FormQuantityInput, FormSelect, FormTagsInput, FormTextarea, GroupErrorBadge, type GroupLayoutTemplate, type GroupLayoutTemplateProps, JsonEditorWidget, JsonSchemaFormRenderer, type JsonSchemaFormRendererProps, type NestedFormContextValue, type NestedRenderer, NumberWidget, type ObjectContainerTemplate, type ObjectContainerTemplateProps, ObjectWidget, OneOfWidget, type QuantityValue, QuantityWidget, SectionsGroupTemplate, type SelectOption, SelectWidget, StepperGroupTemplate, TabsGroupTemplate, TagsInputWidget, type TemplateRegistry, TextInputWidget, TextareaWidget, TimeWidget, type UnitOption, type UnitPosition, type Widget, type WidgetDescriptor, type WidgetMap, type WidgetProps, type WidgetRegistry, firstError, getAriaDescribedBy, getDefaultWidgetForType, groupTemplateKey, resolveWidget, useFormEngine, useNestedFormContext, useResolvedSchema };
+export { AbsentReasonsWidget, ArrayWidget, CheckboxGroupWidget, CheckboxWidget, ChoiceWithTextWidget, CodeableConceptWidget, CodedValueWidget, DEFAULT_TEMPLATES, DEFAULT_WIDGETS, DEFAULT_WIDGET_MAP, DateTimeWidget, DateWidget, DisplayWidget, EntitySelectWidget, ExtraPropertiesCard, FormActions, FormCheckbox, FormFieldRenderer, FormFieldWrapper, FormInput, FormKeyValueInput, FormMultiSelect, FormNumberInput, FormQuantityInput, FormSelect, FormTagsInput, FormTextarea, GroupErrorBadge, JsonEditorWidget, JsonSchemaFormRenderer, KeyValueWidget, NumberWidget, ObjectWidget, OneOfWidget, QuantityWidget, RadioWidget, SectionsGroupTemplate, SelectWidget, StepperGroupTemplate, TabsGroupTemplate, TagsInputWidget, TextInputWidget, TextareaWidget, TimeWidget, firstError, getAriaDescribedBy, getDefaultWidgetForType, groupTemplateKey, resolveWidget, useFormEngine, useNestedFormContext, useResolvedSchema };
+export type { ArrayHeaderTemplate, ArrayHeaderTemplateProps, ArrayItemTemplate, ArrayItemTemplateProps, AsyncFieldValidator, AsyncFormValidator, FieldGroup, FieldValidator, FormFieldWrapperProps, FormValidator, GroupLayoutTemplate, GroupLayoutTemplateProps, JsonSchemaFormRendererProps, NestedFormContextValue, NestedRenderer, ObjectContainerTemplate, ObjectContainerTemplateProps, QuantityValue, SelectOption, TemplateRegistry, UnitOption, UnitPosition, ValidatorContext, ValidatorRegistry, ValidatorResult, Widget, WidgetDescriptor, WidgetMap, WidgetProps, WidgetRegistry };