@petrarca/sonnet-forms 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -2,9 +2,10 @@ 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 } from '@petrarca/sonnet-core/schema';
+import { JsonSchemaProperty, UILayoutConfig, JsonSchema, UISchema, UISchemaOptions, FormDiff, RefResolver, FieldError } 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';
 
 interface FormFieldWrapperProps {
     /** Field id -- wired to the label's htmlFor */
@@ -419,6 +420,33 @@ interface ObjectContainerTemplateProps {
     variant?: string;
     defaultOpen?: boolean;
 }
+/**
+ * One group of fields in a grouped layout (a tab, a wizard step, a section).
+ * `content` is already laid out -- the template only decides how groups are
+ * presented and navigated.
+ */
+interface FieldGroup {
+    /** Stable key for React and for the template's own selection state. */
+    key: string;
+    /** Label shown on the group's trigger, step header or section legend. */
+    label: string;
+    /** The group's rendered rows. */
+    content: React.ReactNode;
+    /** Validation errors owned by this group's fields (for a badge). */
+    errorCount: number;
+}
+/** Props passed to a GroupLayoutTemplate */
+interface GroupLayoutTemplateProps {
+    /** The visible groups, in declaration order. Never empty. */
+    groups: FieldGroup[];
+}
+/**
+ * Presents a set of field groups: as tabs, as a wizard, as an accordion --
+ * whatever the registered template renders. Selected by
+ * `x-ui-layout.variant`, which maps to a TemplateRegistry key, so consumers
+ * can register their own presentation without changing the renderer.
+ */
+type GroupLayoutTemplate = (props: GroupLayoutTemplateProps) => React.ReactElement;
 type ArrayItemTemplate = (props: ArrayItemTemplateProps) => React.ReactElement;
 type ArrayHeaderTemplate = (props: ArrayHeaderTemplateProps) => React.ReactElement | null;
 type ObjectContainerTemplate = (props: ObjectContainerTemplateProps) => React.ReactElement;
@@ -435,6 +463,10 @@ type TemplateRegistry = {
     HorizontalArrayItemTemplate?: ArrayItemTemplate;
     ArrayHeaderTemplate?: ArrayHeaderTemplate;
     ObjectContainerTemplate?: ObjectContainerTemplate;
+    /** Group presentations, selected by x-ui-layout.variant (default "tabs"). */
+    TabsGroupTemplate?: GroupLayoutTemplate;
+    StepperGroupTemplate?: GroupLayoutTemplate;
+    SectionsGroupTemplate?: GroupLayoutTemplate;
     [templateName: string]: unknown;
 };
 
@@ -632,6 +664,12 @@ interface FormActionsProps {
     disabled?: boolean;
     hasChanges: boolean;
     isValid: boolean;
+    /**
+     * Whether Save is available while invalid. `reveal` (default) keeps it
+     * enabled -- an invalid click reveals errors and does not submit; `disable`
+     * greys it out while invalid.
+     */
+    saveWhenInvalid?: SaveWhenInvalid;
     saveLabel?: string;
     cancelLabel?: string;
     showCancel?: boolean;
@@ -641,7 +679,7 @@ interface FormActionsProps {
      */
     leadingActions?: ReactNode;
 }
-declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveLabel, cancelLabel, showCancel, leadingActions, }: FormActionsProps): react_jsx_runtime.JSX.Element;
+declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveWhenInvalid, saveLabel, cancelLabel, showCancel, leadingActions, }: FormActionsProps): react_jsx_runtime.JSX.Element;
 
 type Props = {
     properties: Record<string, any>;
@@ -814,7 +852,7 @@ declare function EntitySelectWidget({ id, name, value, onChange, onBlur, label,
  * compact / label suppression propagates to all nested widgets.
  */
 
-declare function ObjectWidget({ propertySchema, value, onChange, registry, uiSchema, disabled, readonly, label, description, options, }: WidgetProps): React.ReactElement | null;
+declare function ObjectWidget({ id, propertySchema, value, onChange, onBlur, registry, uiSchema, disabled, readonly, label, description, options, }: WidgetProps): React.ReactElement | null;
 
 /**
  * ArrayWidget -- renders a repeatable list of sub-forms for
@@ -839,6 +877,83 @@ declare function ArrayWidget({ propertySchema, value, onChange, registry, uiSche
 
 declare function QuantityWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * DateWidget - date field widget backed by the DateInput primitive.
+ *
+ * Renders a text input with calendar popover. Value is a partial ISO 8601 date
+ * string (`YYYY`, `YYYY-MM`, or `YYYY-MM-DD`). Auto-resolves from schema
+ * `format: "date"`, or `x-ui-widget: "date"`.
+ *
+ * x-ui-options:
+ *   precision - "year" | "month" | "day" (default "day")
+ *   locale    - BCP-47 locale override (defaults to the app locale)
+ *
+ * The label/description chrome comes from FormFieldWrapper; the primitive owns
+ * the inline error message and invalid border.
+ */
+
+declare function DateWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, placeholder, options, }: WidgetProps): React.ReactElement;
+
+/**
+ * TimeWidget - time-of-day field widget backed by the TimeInput primitive.
+ *
+ * Zone-free time value as a normalized ISO string (`HH:mm` or `HH:mm:ss`).
+ * Auto-resolves from schema `format: "time"`, or `x-ui-widget: "time"`.
+ *
+ * x-ui-options:
+ *   granularity - "minute" | "second" (default "minute")
+ *
+ * The label/description chrome comes from FormFieldWrapper; the primitive owns
+ * the inline error message and invalid border.
+ */
+
+declare function TimeWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, placeholder, options, }: WidgetProps): React.ReactElement;
+
+/**
+ * DateTimeWidget - date + time field widget backed by the DateTimeInput primitive.
+ *
+ * Plain wall-clock value as an ISO string (`YYYY-MM-DDTHH:mm[:ss]`), no
+ * timezone. Auto-resolves from schema `format: "date-time"`, or
+ * `x-ui-widget: "date-time"`.
+ *
+ * x-ui-options:
+ *   granularity - "minute" | "second" (default "minute")
+ *   timeZone    - IANA id shown as a display-only hint (never applied)
+ *   locale      - BCP-47 locale override for the date part
+ *
+ * The label/description chrome comes from FormFieldWrapper; the primitive owns
+ * the inline error message and invalid border.
+ */
+
+declare function DateTimeWidget({ id, value, onChange, onBlur, required, disabled, rawErrors, label, description, options, }: WidgetProps): React.ReactElement;
+
+/**
+ * DisplayWidget - read-only text block, no data binding.
+ *
+ * Renders a property's title (and optional description) as static text --
+ * instructions, notes, disclaimers placed between fields. Collects no value.
+ * Auto-resolves from `type: "null"`, or `x-ui-widget: "display"`.
+ *
+ * Modeled as a value-less property so it participates in field ordering and
+ * layout (appears exactly where placed). It never contributes to form data.
+ */
+
+declare function DisplayWidget({ label, description, }: WidgetProps): React.ReactElement | null;
+
+/**
+ * OneOfWidget -- renders a discriminated union (oneOf).
+ *
+ * A branch selector (reusing the Select primitive) chooses one of the property's
+ * `oneOf` branches; the selected branch's object sub-schema is then rendered as
+ * a nested sub-form (same pattern as ObjectWidget). The active branch is tracked
+ * by the discriminator property (see the oneOf helpers in
+ * @petrarca/sonnet-core/schema).
+ *
+ * Auto-resolves when a property has `oneOf`, or via `x-ui-widget: "one-of"`.
+ */
+
+declare function OneOfWidget({ propertySchema, value, onChange, registry, uiSchema, disabled, readonly, label, description, id, options, }: WidgetProps): React.ReactElement | null;
+
 /**
  * Widget Resolution Algorithm
  *
@@ -977,6 +1092,23 @@ type JsonSchemaFormRendererProps = {
      * field validation still applies. Default false (edit semantics).
      */
     allowPristineSave?: boolean;
+    /**
+     * Optional resolver for non-local `$ref`s (schema-registry id / canonical
+     * URI). Tried before the in-document `$defs` fallback. Synchronous -- the
+     * caller pre-loads referenced schemas into a map and passes a lookup.
+     */
+    refResolver?: RefResolver;
+    /**
+     * When to reveal field validation errors. Overrides the app-wide default set
+     * in SonnetConfigProvider globals. Defaults to `onSubmit`.
+     */
+    validationDisplay?: ValidationDisplay;
+    /**
+     * Whether Save is available while the form is invalid. Overrides the app-wide
+     * default set in SonnetConfigProvider globals. Defaults to `reveal` (Save
+     * stays enabled; an invalid click reveals errors and does not submit).
+     */
+    saveWhenInvalid?: SaveWhenInvalid;
     /** Label for Save button (default: "Save") */
     saveLabel?: string;
     /** Label for Cancel button (default: "Cancel") */
@@ -1063,8 +1195,10 @@ interface FormFieldRendererProps {
      * to keep ids unique.
      */
     idPrefix?: string;
+    /** 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, }: FormFieldRendererProps): React__default.ReactElement | null;
+declare function FormFieldRenderer({ fieldName, property, 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
@@ -1108,6 +1242,12 @@ interface UseFormEngineOptions {
      * Validation (required fields) still applies. Default false (edit semantics).
      */
     allowPristineSave?: boolean;
+    /**
+     * Optional resolver for non-local `$ref`s (e.g. a schema-registry id or
+     * canonical URI). Tried before the in-document `$defs` fallback. Must be
+     * synchronous -- pre-load referenced schemas into a map and pass a lookup.
+     */
+    refResolver?: RefResolver;
 }
 interface UseFormEngineResult {
     /** The current working form data (for controlled field values) */
@@ -1123,12 +1263,21 @@ interface UseFormEngineResult {
     orderedProperties: [string, JsonSchemaProperty][];
     hasChanges: boolean;
     isValid: boolean;
+    /**
+     * Current validation errors, each attributed to its field by JSON Pointer.
+     * Lets the renderer surface problems for fields that are not on screen.
+     */
+    fieldErrors: FieldError[];
+    /** Fields the user has touched (focused then blurred). */
+    touched: Record<string, boolean>;
+    /** Whether a save has been attempted (reveals all errors under any policy). */
+    submitAttempted: boolean;
     handleFieldChange: (fieldName: string, value: any) => void;
     handleFieldBlur: (fieldName: string) => void;
     handleSave: () => void;
     handleCancel: () => void;
 }
-declare function useFormEngine({ schema, data, uiSchema, onChange, onBlur, onValidationChange, onUpdate, onCancel, readOnly, showActions, deferChanges, deferStateUpdates, allowPristineSave, }: UseFormEngineOptions): UseFormEngineResult;
+declare function useFormEngine({ schema, data, uiSchema, onChange, onBlur, onValidationChange, onUpdate, onCancel, readOnly, showActions, deferChanges, deferStateUpdates, allowPristineSave, refResolver, }: UseFormEngineOptions): UseFormEngineResult;
 
 /**
  * useResolvedSchema - Schema resolution and property ordering
@@ -1174,6 +1323,19 @@ type NestedRenderer = (props: Omit<JsonSchemaFormRendererProps, "onUpdate" | "on
 interface NestedFormContextValue {
     renderer: NestedRenderer;
     templates: TemplateRegistry;
+    /**
+     * The whole form's data, carried down so a nested renderer can evaluate an
+     * `x-ui-rule` scope against the form root rather than its own slice.
+     *
+     * Every other JSON Pointer in the vocabulary (`editablePaths`, validation
+     * error pointers) is root-anchored; without this, a rule on a nested field
+     * could only ever see its immediate object, so a rule referencing a
+     * top-level field silently never fired.
+     *
+     * The outermost renderer sets this to its own data; nested renderers inherit
+     * it unchanged.
+     */
+    rootData: Record<string, unknown>;
 }
 
 /**
@@ -1190,6 +1352,63 @@ interface NestedFormContextValue {
 
 declare function useNestedFormContext(): NestedFormContextValue;
 
+/**
+ * TabsGroupTemplate -- presents field groups as a tab bar (the default for
+ * `x-ui-layout.tabs`).
+ *
+ * Selection is controlled and clamped to a group that still exists, so hiding
+ * the group the user is on (via its rule) falls back to the first remaining one
+ * instead of leaving an empty body.
+ */
+
+declare function TabsGroupTemplate({ groups, }: GroupLayoutTemplateProps): React__default.ReactElement;
+
+/**
+ * StepperGroupTemplate -- presents field groups as a wizard
+ * (`x-ui-layout.variant: "stepper"`).
+ *
+ * Same group model as the tab presentation, different chrome: a numbered step
+ * rail plus Back/Next. Steps stay directly clickable so the user is never
+ * trapped; validation gating is deliberately not applied here, because a
+ * group's errors are advisory (the badge) rather than a hard barrier.
+ *
+ * Selection is controlled and clamped to a group that still exists, so hiding
+ * the step the user is on falls back to the first remaining one.
+ */
+
+declare function StepperGroupTemplate({ groups, }: GroupLayoutTemplateProps): React__default.ReactElement;
+
+/**
+ * SectionsGroupTemplate -- presents field groups as stacked titled sections
+ * (`x-ui-layout.variant: "sections"`).
+ *
+ * Unlike tabs and stepper, every group is visible at once. This is the
+ * multi-row counterpart to a row's `group` fieldset: a section holds as many
+ * rows as it likes, whereas `row.group` wraps exactly one.
+ *
+ * No selection state, so nothing to clamp -- a group hidden by its rule simply
+ * does not appear.
+ */
+
+declare function SectionsGroupTemplate({ groups, }: GroupLayoutTemplateProps): React__default.ReactElement;
+
+/**
+ * GroupErrorBadge -- marks a group's trigger (tab or step) as having
+ * validation errors. Shared by the built-in group templates.
+ *
+ * Deliberately just the icon: a trigger sits in a dense strip alongside its
+ * label and, in a stepper, a step number, so a second numeral reads as clutter
+ * and competes with the step index. The exact count stays available as the
+ * accessible name and the tooltip, and the form-level summary reports totals.
+ *
+ * The signal is a shape, not a colour, so it survives a colour-vision
+ * deficiency or a greyscale print.
+ */
+
+declare function GroupErrorBadge({ count, }: {
+    count: number;
+}): React__default.ReactElement | null;
+
 /**
  * Default templates for structural layout rendering.
  *
@@ -1207,5 +1426,12 @@ declare function useNestedFormContext(): NestedFormContextValue;
  * schema property for per-field overrides.
  */
 declare const DEFAULT_TEMPLATES: TemplateRegistry;
+/**
+ * The TemplateRegistry key for a group-layout variant. The variant name maps
+ * directly to a template name, so a consumer can register
+ * `WizardGroupTemplate` and select it with `variant: "wizard"` -- no library
+ * change needed. Unknown variants fall back to the tab presentation.
+ */
+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, EntitySelectWidget, ExtraPropertiesCard, FormActions, FormCheckbox, FormFieldRenderer, FormFieldWrapper, type FormFieldWrapperProps, FormInput, FormMultiSelect, FormNumberInput, FormQuantityInput, FormSelect, FormTagsInput, FormTextarea, JsonEditorWidget, JsonSchemaFormRenderer, type JsonSchemaFormRendererProps, type NestedFormContextValue, type NestedRenderer, NumberWidget, type ObjectContainerTemplate, type ObjectContainerTemplateProps, ObjectWidget, type QuantityValue, QuantityWidget, type SelectOption, SelectWidget, TagsInputWidget, type TemplateRegistry, TextInputWidget, TextareaWidget, type UnitOption, type UnitPosition, type Widget, type WidgetDescriptor, type WidgetMap, type WidgetProps, type WidgetRegistry, firstError, getAriaDescribedBy, getDefaultWidgetForType, resolveWidget, useFormEngine, useNestedFormContext, useResolvedSchema };
+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 };