@petrarca/sonnet-forms 0.4.2 → 0.6.0

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 } 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';
 
@@ -23,6 +23,12 @@ interface FormFieldWrapperProps {
      * still communicated via the control's own styling (e.g. red border).
      */
     compact?: boolean;
+    /**
+     * Label placement: "top" (default) renders the label above the control;
+     * "start" renders the label inline on the reading-start side (RTL-safe: left
+     * in LTR, right in RTL). Logical values follow the MUI convention.
+     */
+    labelPlacement?: "top" | "start";
     /** Additional class name for the outer wrapper div */
     className?: string;
     /** The form control(s) */
@@ -32,7 +38,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, className, children, }: FormFieldWrapperProps): react_jsx_runtime.JSX.Element;
+declare function FormFieldWrapper({ inputId, label, description, error, required, compact, labelPlacement, className, children, }: FormFieldWrapperProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Shared utility functions for form field components.
@@ -78,6 +84,8 @@ interface FormInputProps extends React__default.ComponentPropsWithoutRef<typeof
      * still communicated via a red border on the input.
      */
     compact?: boolean;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
 }
 /**
  * FormInput component with label, description, and error handling
@@ -106,6 +114,8 @@ interface FormTextareaProps extends React__default.ComponentPropsWithoutRef<type
     required?: boolean;
     /** Additional class name for the wrapper */
     wrapperClassName?: string;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
     /** Enable auto-resize behavior (default: false) */
     autosize?: boolean;
     /** Minimum number of rows when autosize is enabled (default: 3) */
@@ -163,6 +173,8 @@ interface FormNumberInputProps {
     id?: string;
     /** Input name */
     name?: string;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
 }
 declare const FormNumberInput: React__default.ForwardRefExoticComponent<FormNumberInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
@@ -381,6 +393,12 @@ interface ArrayItemTemplateProps {
     disabled?: boolean;
     layout: UILayoutConfig;
     fieldCount: number;
+    /**
+     * Stable form-internal item id (_fid). Rendered as `data-fid` on the item
+     * container so tests can target a specific item across reorders (the
+     * positional `index` is not stable).
+     */
+    fid?: string;
     onRemove: () => void;
     onMoveUp?: () => void;
     onMoveDown?: () => void;
@@ -401,6 +419,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;
@@ -417,6 +462,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;
 };
 
@@ -432,6 +481,8 @@ interface FormSelectProps {
      * still communicated via a red border on the trigger button.
      */
     compact?: boolean;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
     options: SelectOption[];
     value?: string | null;
     onChange?: (value: string | null) => void;
@@ -447,6 +498,15 @@ interface FormSelectProps {
     id?: string;
     name?: string;
     autoFocus?: boolean;
+    /**
+     * Allow creating a new option from the search text. When set, a
+     * `+ Create "<text>"` item appears at the bottom of the list whenever the
+     * trimmed search matches no existing option label (case-insensitive).
+     * Selecting it calls `onCreate(text)`. Requires `onCreate`.
+     */
+    allowCreate?: boolean;
+    /** 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;
 
@@ -458,6 +518,8 @@ interface FormMultiSelectProps {
     error?: string;
     required?: boolean;
     wrapperClassName?: string;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
     options: SelectOption[];
     value?: string[];
     onChange?: (value: string[]) => void;
@@ -492,6 +554,8 @@ interface FormTagsInputProps {
     error?: string;
     required?: boolean;
     wrapperClassName?: string;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
     id?: string;
     name?: string;
     value: string[];
@@ -580,6 +644,8 @@ interface FormQuantityInputProps {
     autoFocus?: boolean;
     /** Additional class name for the outer wrapper */
     wrapperClassName?: string;
+    /** Label placement: "vertical" (default, above) or "horizontal" (inline). */
+    labelPlacement?: "top" | "start";
     /** Additional class name for the numeric input */
     className?: string;
     id?: string;
@@ -804,6 +870,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
  *
@@ -935,6 +1078,19 @@ type JsonSchemaFormRendererProps = {
     readOnly?: boolean;
     /** Show Save/Cancel action buttons */
     showActions?: boolean;
+    /**
+     * Allow Save when the form is pristine (no changes vs the baseline). Set for
+     * CREATE forms, where submitting default / empty values is valid -- the
+     * "must have changed something" dirty-check is an edit-only concept. Required-
+     * 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;
     /** Label for Save button (default: "Save") */
     saveLabel?: string;
     /** Label for Cancel button (default: "Cancel") */
@@ -981,6 +1137,12 @@ type JsonSchemaFormRendererProps = {
     uiSchema?: {
         [fieldName: string]: UISchema;
     };
+    /**
+     * Prefix for generated field control ids: `<idPrefix>-<fieldName>` (default
+     * "field"). Set a distinct prefix per form when rendering multiple forms on
+     * one page to avoid duplicate DOM ids.
+     */
+    idPrefix?: string;
 };
 declare function JsonSchemaFormRenderer(props: JsonSchemaFormRendererProps): React__default.ReactElement;
 
@@ -1009,8 +1171,14 @@ interface FormFieldRendererProps {
     registry: WidgetRegistry;
     globalOptions?: UISchemaOptions;
     formData?: Record<string, unknown>;
+    /**
+     * Prefix for generated control ids: `<idPrefix>-<fieldName>` (default
+     * "field"). Set a per-form prefix when rendering multiple forms on one page
+     * to keep ids unique.
+     */
+    idPrefix?: string;
 }
-declare function FormFieldRenderer({ fieldName, property, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, }: FormFieldRendererProps): React__default.ReactElement | null;
+declare function FormFieldRenderer({ fieldName, property, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, idPrefix, }: FormFieldRendererProps): React__default.ReactElement | null;
 
 /**
  * useFormEngine - Core form state, schema resolution, and update-mode logic
@@ -1047,6 +1215,19 @@ interface UseFormEngineOptions {
     showActions?: boolean;
     deferChanges?: boolean;
     deferStateUpdates?: boolean;
+    /**
+     * Allow saving when the form is pristine (no changes vs the baseline). Use for
+     * CREATE forms, where submitting default / empty values is valid -- the
+     * "must have changed something" dirty-check is an edit-only concept.
+     * 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) */
@@ -1062,12 +1243,17 @@ 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[];
     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, }: 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
@@ -1129,6 +1315,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.
  *
@@ -1146,5 +1389,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 };