@petrarca/sonnet-forms 0.7.0 → 0.8.0

package/README.md

@@ -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

@@ -2,7 +2,7 @@ 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 { JsonSchemaProperty, UILayoutConfig, JsonSchema, UISchema, UISchemaOptions, 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';
@@ -673,13 +673,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_jsx_runtime.JSX.Element;
 
 type Props = {
     properties: Record<string, any>;
@@ -1026,6 +1031,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 +1202,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.
      *
@@ -1248,6 +1334,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 +1372,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 +1388,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 +1447,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 +1556,4 @@ 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 { type ArrayHeaderTemplate, type ArrayHeaderTemplateProps, type ArrayItemTemplate, type ArrayItemTemplateProps, ArrayWidget, type AsyncFieldValidator, type AsyncFormValidator, CheckboxWidget, DEFAULT_TEMPLATES, DEFAULT_WIDGETS, DEFAULT_WIDGET_MAP, DateTimeWidget, DateWidget, DisplayWidget, EntitySelectWidget, ExtraPropertiesCard, type FieldGroup, type FieldValidator, FormActions, FormCheckbox, FormFieldRenderer, FormFieldWrapper, type FormFieldWrapperProps, FormInput, FormMultiSelect, FormNumberInput, FormQuantityInput, FormSelect, FormTagsInput, FormTextarea, type FormValidator, 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 ValidatorContext, type ValidatorRegistry, type ValidatorResult, type Widget, type WidgetDescriptor, type WidgetMap, type WidgetProps, type WidgetRegistry, firstError, getAriaDescribedBy, getDefaultWidgetForType, groupTemplateKey, resolveWidget, useFormEngine, useNestedFormContext, useResolvedSchema };