@petrarca/sonnet-forms 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1148 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import React__default, { ComponentType } from 'react';
+import { Input, Textarea, badgeVariants } from '@petrarca/sonnet-ui';
+import { JsonSchemaProperty, UILayoutConfig, JsonSchema, UISchema, UISchemaOptions, FormDiff } from '@petrarca/sonnet-core/schema';
+export { UISchema, UISchemaOptions } from '@petrarca/sonnet-core/schema';
+import { VariantProps } from 'class-variance-authority';
+
+interface FormFieldWrapperProps {
+    /** Field id -- wired to the label's htmlFor */
+    inputId: string;
+    /** Visible label text (false = explicitly hidden) */
+    label?: string | false;
+    /** Helper text shown below the control */
+    description?: string;
+    /** Validation error message (takes precedence over description for aria-describedby) */
+    error?: string;
+    /** Shows a required asterisk next to the label */
+    required?: boolean;
+    /**
+     * Compact mode -- suppresses label, description, and error text so the
+     * cell height stays fixed in horizontal grid layouts. Error state is
+     * still communicated via the control's own styling (e.g. red border).
+     */
+    compact?: boolean;
+    /** Additional class name for the outer wrapper div */
+    className?: string;
+    /** The form control(s) */
+    children: React__default.ReactNode;
+}
+/**
+ * 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;
+
+/**
+ * Shared utility functions for form field components.
+ * Kept separate from FormFieldWrapper so the wrapper file exports only
+ * components (required for React fast-refresh).
+ */
+/**
+ * Returns the correct aria-describedby id for a form control:
+ * - error id when there is an error (screen readers announce errors immediately)
+ * - description id when there is only a description
+ * - undefined when neither is present
+ */
+declare function getAriaDescribedBy(inputId: string, error: string | undefined, description: string | undefined): string | undefined;
+
+/**
+ * FormInput - Input wrapper with label, description, and error support
+ *
+ * Wraps shadcn Input with form field features to match Mantine TextInput API:
+ * - Label with required indicator
+ * - Description text
+ * - Error message display
+ * - Proper accessibility attributes
+ */
+
+interface FormInputProps extends React__default.ComponentPropsWithoutRef<typeof Input> {
+    /** Input label (false = hide label) */
+    label?: string | false;
+    /** Description text shown below label */
+    description?: string;
+    /** Error message to display */
+    error?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Additional class name for the wrapper */
+    wrapperClassName?: string;
+    /** Right section content (e.g., icons, buttons) */
+    rightSection?: React__default.ReactNode;
+    /** Width of the right section in pixels (for padding adjustment) */
+    rightSectionWidth?: number;
+    /**
+     * Compact mode -- suppresses label, description, and error text so the
+     * cell height stays fixed in horizontal grid layouts. Error state is
+     * still communicated via a red border on the input.
+     */
+    compact?: boolean;
+}
+/**
+ * FormInput component with label, description, and error handling
+ */
+declare const FormInput: React__default.ForwardRefExoticComponent<FormInputProps & React__default.RefAttributes<HTMLInputElement>>;
+
+/**
+ * FormTextarea - Textarea wrapper with label, description, error, and autosize support
+ *
+ * Wraps shadcn Textarea with form field features to match Mantine Textarea API:
+ * - Label with required indicator
+ * - Description text
+ * - Error message display
+ * - Auto-resize functionality (via useEffect)
+ * - Proper accessibility attributes
+ */
+
+interface FormTextareaProps extends React__default.ComponentPropsWithoutRef<typeof Textarea> {
+    /** Textarea label (false = hide label) */
+    label?: string | false;
+    /** Description text shown below label */
+    description?: string;
+    /** Error message to display */
+    error?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Additional class name for the wrapper */
+    wrapperClassName?: string;
+    /** Enable auto-resize behavior (default: false) */
+    autosize?: boolean;
+    /** Minimum number of rows when autosize is enabled (default: 3) */
+    minRows?: number;
+    /** Right section content (e.g., action buttons) */
+    rightSection?: React__default.ReactNode;
+    /** Width of the right section in pixels (for padding adjustment) */
+    rightSectionWidth?: number;
+}
+/**
+ * FormTextarea component with label, description, error, and autosize handling
+ */
+declare const FormTextarea: React__default.ForwardRefExoticComponent<FormTextareaProps & React__default.RefAttributes<HTMLTextAreaElement>>;
+
+/**
+ * FormNumberInput - Number input wrapper with label, description, error, and numeric constraints.
+ */
+
+interface FormNumberInputProps {
+    /** Input value */
+    value?: number | string;
+    /** Input label */
+    label?: string;
+    /** Description text shown below input */
+    description?: string;
+    /** Error message to display */
+    error?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Whether the input is read-only */
+    readOnly?: boolean;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Step increment/decrement value */
+    step?: number;
+    /** Allow decimal values (if false, only integers) */
+    allowDecimal?: boolean;
+    /** Change handler - receives number or undefined */
+    onChange?: (value: number | undefined) => void;
+    /** Blur handler */
+    onBlur?: React__default.FocusEventHandler<HTMLInputElement>;
+    /** Auto-focus on mount */
+    autoFocus?: boolean;
+    /** Additional class name for the wrapper */
+    wrapperClassName?: string;
+    /** Additional class name for the input */
+    className?: string;
+    /** Input ID */
+    id?: string;
+    /** Input name */
+    name?: string;
+}
+declare const FormNumberInput: React__default.ForwardRefExoticComponent<FormNumberInputProps & React__default.RefAttributes<HTMLInputElement>>;
+
+/**
+ * FormCheckbox - Checkbox wrapper with label, description, error, and indeterminate support
+ *
+ * Wraps shadcn Checkbox with form field features to match Mantine Checkbox API:
+ * - Inline label (checkbox + label on same line)
+ * - Description text
+ * - Error message display
+ * - Indeterminate state support (tri-state)
+ * - Proper accessibility attributes
+ */
+
+interface FormCheckboxProps {
+    /** Checkbox checked state (boolean or 'indeterminate') */
+    checked?: boolean | "indeterminate";
+    /** Checkbox label (displayed inline, false = hide label) */
+    label?: string | false;
+    /** Description text shown below checkbox */
+    description?: string;
+    /** Error message to display */
+    error?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Whether the checkbox is disabled */
+    disabled?: boolean;
+    /** Whether the checkbox is read-only */
+    readOnly?: boolean;
+    /** Change handler */
+    onChange?: (checked: boolean | "indeterminate") => void;
+    /** Blur handler */
+    onBlur?: React__default.FocusEventHandler<HTMLButtonElement>;
+    /** Auto-focus on mount */
+    autoFocus?: boolean;
+    /** Additional class name for the wrapper */
+    wrapperClassName?: string;
+    /** Additional class name for the checkbox */
+    className?: string;
+    /** Input ID */
+    id?: string;
+    /**
+     * Compact mode -- suppresses label, description, and error text so the
+     * cell height stays fixed in horizontal grid layouts. Error state is
+     * still communicated via a red border on the checkbox.
+     */
+    compact?: boolean;
+}
+/**
+ * FormCheckbox component with label, description, error, and indeterminate handling
+ */
+declare const FormCheckbox: React__default.ForwardRefExoticComponent<FormCheckboxProps & React__default.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Widget Type System
+ *
+ * Type definitions for the JSON Schema Form widget architecture.
+ * Based on react-jsonschema-form patterns with simplified Mantine-focused implementation.
+ */
+
+/**
+ * WidgetRegistry - Map of widget name to component
+ *
+ * @example
+ * ```typescript
+ * const registry: WidgetRegistry = {
+ *   TextWidget: TextWidget,
+ *   SelectWidget: SelectWidget,
+ *   CustomWidget: MyCustomWidget
+ * }
+ * ```
+ */
+type WidgetRegistry = {
+    [widgetName: string]: Widget;
+};
+/**
+ * WidgetProps - Props passed to every widget
+ *
+ * Widgets receive comprehensive context to make intelligent decisions.
+ * All widgets must accept these props.
+ *
+ * @example
+ * ```typescript
+ * export function MyWidget({
+ *   id,
+ *   value,
+ *   onChange,
+ *   label,
+ *   propertySchema,
+ *   options
+ * }: WidgetProps) {
+ *   const customOption = options?.myCustomOption ?? 'default';
+ *   // ...
+ * }
+ * ```
+ */
+interface WidgetProps {
+    /** Unique field ID */
+    id: string;
+    /** Field name */
+    name: string;
+    /** Full form schema */
+    schema: JsonSchema;
+    /** This field's schema */
+    propertySchema: JsonSchemaProperty;
+    /** UI configuration for this field */
+    uiSchema?: UISchema;
+    /** Access to all widgets */
+    registry: WidgetRegistry;
+    /** Current field value */
+    value: unknown;
+    /** Called when value changes */
+    onChange: (value: unknown) => void;
+    /** Called when field loses focus */
+    onBlur?: (id: string, value: unknown) => void;
+    /** Called when field gains focus */
+    onFocus?: (id: string, value: unknown) => void;
+    /** Current form data - all field values (for dependent/cascading widgets) */
+    formData?: Record<string, unknown>;
+    /** Field label (empty string = hidden) */
+    label: string;
+    /** Field description */
+    description?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Is field required */
+    required?: boolean;
+    /** Is field disabled */
+    disabled?: boolean;
+    /** Is field readonly */
+    readonly?: boolean;
+    /** Should field autofocus */
+    autofocus?: boolean;
+    /** Raw validation errors */
+    rawErrors?: string[];
+    /** Widget-specific options from x-ui-options */
+    options?: UISchemaOptions;
+}
+/**
+ * Widget - React component type for form widgets
+ *
+ * @example
+ * ```typescript
+ * const TextWidget: Widget = ({ id, value, onChange, label }) => (
+ *   <TextInput id={id} value={value} onChange={e => onChange(e.target.value)} label={label} />
+ * );
+ * ```
+ */
+type Widget = ComponentType<WidgetProps>;
+/**
+ * WidgetDescriptor - Extended information for widget registration
+ *
+ * Allows providing metadata along with the widget component.
+ *
+ * @example
+ * ```typescript
+ * const descriptor: WidgetDescriptor = {
+ *   component: MyWidget,
+ *   displayName: 'My Custom Widget',
+ *   description: 'A widget for custom input',
+ *   defaultOptions: { rows: 3 }
+ * }
+ * ```
+ */
+interface WidgetDescriptor {
+    /** The widget component */
+    component: Widget;
+    /** Display name for debugging */
+    displayName?: string;
+    /** Description of what the widget does */
+    description?: string;
+    /** Default options to apply */
+    defaultOptions?: UISchemaOptions;
+}
+/**
+ * WidgetMap - Type/format to widget name mapping
+ *
+ * Defines the default widget to use for each schema type and format.
+ *
+ * @example
+ * ```typescript
+ * const map: WidgetMap = {
+ *   string: {
+ *     default: 'TextWidget',
+ *     email: 'EmailWidget',
+ *     textarea: 'TextareaWidget'
+ *   }
+ * }
+ * ```
+ */
+type WidgetMap = {
+    [schemaType: string]: {
+        [variantOrFormat: string]: string;
+    };
+};
+/**
+ * Return the first validation error message, or undefined if there are none.
+ * Avoids repeating `rawErrors && rawErrors.length > 0 ? rawErrors[0] : undefined`
+ * in every widget.
+ */
+declare function firstError(rawErrors?: string[]): string | undefined;
+/**
+ * SelectOption - Single option in a select dropdown
+ */
+interface SelectOption {
+    value: string;
+    label: string;
+}
+/** Props passed to an ArrayItemTemplate */
+interface ArrayItemTemplateProps {
+    children: React.ReactNode;
+    index: number;
+    total: number;
+    canRemove: boolean;
+    orderable: boolean;
+    disabled?: boolean;
+    layout: UILayoutConfig;
+    fieldCount: number;
+    onRemove: () => void;
+    onMoveUp?: () => void;
+    onMoveDown?: () => void;
+}
+/** Props passed to an ArrayHeaderTemplate */
+interface ArrayHeaderTemplateProps {
+    itemSchema: JsonSchemaProperty;
+    layout: UILayoutConfig;
+    canRemove: boolean;
+    orderable: boolean;
+    fieldCount: number;
+}
+/** Props passed to an ObjectContainerTemplate */
+interface ObjectContainerTemplateProps {
+    children: React.ReactNode;
+    label: string;
+    description?: string;
+    variant?: string;
+    defaultOpen?: boolean;
+}
+type ArrayItemTemplate = (props: ArrayItemTemplateProps) => React.ReactElement;
+type ArrayHeaderTemplate = (props: ArrayHeaderTemplateProps) => React.ReactElement | null;
+type ObjectContainerTemplate = (props: ObjectContainerTemplateProps) => React.ReactElement;
+/**
+ * TemplateRegistry -- named rendering functions for structural layout.
+ *
+ * Built-in keys: ArrayItemTemplate, ArrayHeaderTemplate, ObjectContainerTemplate.
+ * Custom keys are allowed for per-field template overrides (looked up by name).
+ * The index signature uses `unknown` to avoid TypeScript variance conflicts with
+ * the specifically-typed named properties.
+ */
+type TemplateRegistry = {
+    ArrayItemTemplate?: ArrayItemTemplate;
+    HorizontalArrayItemTemplate?: ArrayItemTemplate;
+    ArrayHeaderTemplate?: ArrayHeaderTemplate;
+    ObjectContainerTemplate?: ObjectContainerTemplate;
+    [templateName: string]: unknown;
+};
+
+interface FormSelectProps {
+    label?: string | false;
+    description?: string;
+    error?: string;
+    required?: boolean;
+    wrapperClassName?: string;
+    /**
+     * Compact mode -- suppresses label, description, and error text so the
+     * cell height stays fixed in horizontal grid layouts. Error state is
+     * still communicated via a red border on the trigger button.
+     */
+    compact?: boolean;
+    options: SelectOption[];
+    value?: string | null;
+    onChange?: (value: string | null) => void;
+    onBlur?: () => void;
+    placeholder?: string;
+    searchPlaceholder?: string;
+    emptyMessage?: string;
+    clearable?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    loading?: boolean;
+    className?: string;
+    id?: string;
+    name?: string;
+    autoFocus?: boolean;
+}
+declare function FormSelect(props: FormSelectProps): react_jsx_runtime.JSX.Element;
+
+type BadgeColor = NonNullable<VariantProps<typeof badgeVariants>["badgeColor"]>;
+
+interface FormMultiSelectProps {
+    label?: string | false;
+    description?: string;
+    error?: string;
+    required?: boolean;
+    wrapperClassName?: string;
+    options: SelectOption[];
+    value?: string[];
+    onChange?: (value: string[]) => void;
+    onBlur?: () => void;
+    placeholder?: string;
+    searchPlaceholder?: string;
+    emptyMessage?: string;
+    clearable?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    loading?: boolean;
+    className?: string;
+    id?: string;
+    name?: string;
+    autoFocus?: boolean;
+    maxDisplay?: number;
+    badgeColor?: BadgeColor;
+}
+declare function FormMultiSelect(props: FormMultiSelectProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * FormTagsInput - Input field for managing tags with badges
+ *
+ * Allows adding tags by pressing Enter or comma, removing tags via X button
+ * or backspace. Displays tags as badges. Follows Form wrapper pattern with
+ * label, description, error support.
+ */
+
+interface FormTagsInputProps {
+    label?: string | false;
+    description?: string;
+    error?: string;
+    required?: boolean;
+    wrapperClassName?: string;
+    id?: string;
+    name?: string;
+    value: string[];
+    onChange?: (tags: string[]) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    maxTags?: number;
+    splitKeys?: string[];
+    allowDuplicates?: boolean;
+}
+declare const FormTagsInput: React$1.ForwardRefExoticComponent<FormTagsInputProps & React$1.RefAttributes<HTMLInputElement>>;
+
+/**
+ * FormQuantityInput - Compound input for a numeric value paired with a unit selector.
+ *
+ * Renders as a single visual control using InputGroup: the numeric input fills
+ * the left side; the unit selector (or static text) sits inside the right (or
+ * left) edge of the same border as an inline addon.
+ *
+ * Value shape: { value: number | undefined, unit: string }
+ *
+ * Decimal handling: uses inputMode="decimal" with type="text" to support
+ * international decimal separators (comma and period). Input is validated and
+ * normalized on blur, not on every keystroke, to allow intermediate states
+ * such as "37." or "-".
+ *
+ * NOTE on precision: toFixed() uses IEEE 754 rounding. For values where exact
+ * decimal representation matters (e.g. financial amounts), the caller should
+ * round the emitted number independently before storing it.
+ */
+
+/** Compound quantity value: numeric value + unit code */
+interface QuantityValue {
+    value: number | undefined;
+    unit: string;
+}
+/** Where the unit label renders relative to the numeric input */
+type UnitPosition = "prefix" | "suffix";
+/** A unit option with optional per-unit validation constraints and position */
+interface UnitOption extends SelectOption {
+    /** Minimum allowed value for this unit */
+    min?: number;
+    /** Maximum allowed value for this unit */
+    max?: number;
+    /** Where to render this unit relative to the value (default: "suffix") */
+    position?: UnitPosition;
+}
+interface FormQuantityInputProps {
+    /** Controlled compound value */
+    value?: QuantityValue;
+    /** Change handler -- receives the updated quantity */
+    onChange?: (value: QuantityValue) => void;
+    /** Blur handler */
+    onBlur?: () => void;
+    /** Available unit options. Single = static text, 2+ = dropdown, none = no addon. */
+    units?: UnitOption[];
+    /**
+     * Default position for all units. Individual UnitOption.position overrides
+     * this. Default: "suffix".
+     */
+    unitPosition?: UnitPosition;
+    /**
+     * Decimal places to format on blur (undefined = no formatting).
+     * Uses toFixed() -- see IEEE 754 note in file header.
+     */
+    precision?: number;
+    /** Arrow-key step increment */
+    step?: number;
+    /** Global minimum (overridden by per-unit min when present) */
+    min?: number;
+    /** Global maximum (overridden by per-unit max when present) */
+    max?: number;
+    /** Visible label */
+    label?: string;
+    /** Helper text shown below the control */
+    description?: string;
+    /** Validation error message */
+    error?: string;
+    /** Placeholder for the numeric input */
+    placeholder?: string;
+    /** Shows a required asterisk */
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    autoFocus?: boolean;
+    /** Additional class name for the outer wrapper */
+    wrapperClassName?: string;
+    /** Additional class name for the numeric input */
+    className?: string;
+    id?: string;
+    name?: string;
+}
+/**
+ * FormQuantityInput -- controlled compound numeric + unit input in a single
+ * InputGroup border. See file header for behavioural notes.
+ */
+declare const FormQuantityInput: React__default.ForwardRefExoticComponent<FormQuantityInputProps & React__default.RefAttributes<HTMLInputElement>>;
+
+/**
+ * FormActions - Save / Cancel button row for buffered forms
+ *
+ * Rendered only when the parent JsonSchemaFormRenderer is in buffered mode
+ * (showActions=true). Keeps button logic out of the orchestrator.
+ *
+ * @module components/Forms/FormActions
+ */
+interface FormActionsProps {
+    onSave: () => void;
+    onCancel: () => void;
+    disabled?: boolean;
+    hasChanges: boolean;
+    isValid: boolean;
+    saveLabel?: string;
+    cancelLabel?: string;
+    showCancel?: boolean;
+}
+declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveLabel, cancelLabel, showCancel, }: FormActionsProps): react_jsx_runtime.JSX.Element;
+
+type Props = {
+    properties: Record<string, any>;
+    schema: JsonSchema | null;
+};
+/**
+ * Displays properties that are not defined in the JSON Schema.
+ * Shown as a collapsible card, closed by default.
+ *
+ * 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;
+
+/**
+ * TextInputWidget - Standard text input widget
+ *
+ * Renders a single-line text input field using FormInput.
+ * Supports various input types via format (email, url, text).
+ */
+
+/**
+ * TextInputWidget renders a standard text input field.
+ *
+ * Supports:
+ * - Basic string input
+ * - Email input (format: 'email')
+ * - URL input (format: 'uri' or 'url')
+ * - Validation constraints (minLength, maxLength, pattern)
+ */
+declare function TextInputWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): React.ReactElement;
+
+/**
+ * TextareaWidget renders a multi-line text input field.
+ *
+ * Supports:
+ * - Multi-line text input
+ * - Autosize functionality
+ * - Configurable minimum rows via x-ui-options
+ * - Validation constraints (minLength, maxLength)
+ *
+ * @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;
+
+/**
+ * NumberWidget renders a number input field.
+ *
+ * Supports:
+ * - Number input (decimal allowed)
+ * - Integer input (step = 1, no decimals)
+ * - Min/max constraints from schema
+ * - Step configuration via x-ui-options
+ *
+ * @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;
+
+/**
+ * CheckboxWidget - Boolean checkbox widget
+ *
+ * Renders a checkbox input using FormCheckbox.
+ * Used for boolean type fields.
+ *
+ * Supports tri-state behavior for nullable boolean fields (anyOf[boolean, null]):
+ * - null (indeterminate) -> true (checked) -> false (unchecked) -> null
+ */
+
+/**
+ * CheckboxWidget renders a checkbox for boolean values.
+ *
+ * Supports:
+ * - Boolean true/false values (standard checkbox)
+ * - Tri-state true/false/null values (indeterminate checkbox)
+ * - Custom labels from schema or UISchema
+ * - Description text
+ *
+ * Tri-state behavior (when anyOf[boolean, null] is detected):
+ * - Click on null -> 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;
+
+/**
+ * TagsInputWidget - Free-text tag input widget
+ *
+ * Renders FormTagsInput for array-of-string fields where the user types
+ * free-text values (no predefined enum). Tags are entered by pressing
+ * Enter or comma and displayed as dismissible badges. Duplicates are
+ * rejected by default.
+ *
+ * Use via x-ui-widget: "tags" in a JSON Schema or Zod .meta().
+ */
+
+/**
+ * TagsInputWidget renders a free-text tag input field.
+ *
+ * Supports:
+ * - Free-text tag creation (Enter or comma)
+ * - Duplicate rejection (default)
+ * - Max tags limit (via x-ui-options.maxTags)
+ * - Custom split keys (via x-ui-options.splitKeys)
+ */
+declare function TagsInputWidget({ id, name, value, onChange, required, disabled, readonly, rawErrors, label, description, placeholder, options, }: WidgetProps): React__default.ReactElement;
+
+/**
+ * JsonEditorWidget - JSON document editor widget.
+ *
+ * Renders JsonEditor for object/any fields where the user authors raw JSON.
+ * The full document is editable. Invalid JSON is not propagated -- the last
+ * valid value is retained until the user fixes the syntax error.
+ *
+ * Use via x-ui-widget: "json-editor" in a JSON Schema or Zod .meta().
+ */
+
+/**
+ * JsonEditorWidget renders a full-document JSON editor.
+ *
+ * Supports:
+ * - Full document editing (no readonly regions)
+ * - Invalid JSON is silently retained until fixed
+ * - Height configurable via x-ui-options.height (default: "240px")
+ */
+declare function JsonEditorWidget({ id, value, onChange, label, description, required, options, }: WidgetProps): React__default.ReactElement;
+
+/**
+ * EntitySelectWidget -- form widget for async entity reference selection.
+ *
+ * Wraps EntitySelect and adapts it to the WidgetProps contract. Reads
+ * x-ui-options for fetcher configuration (REST or GraphQL) and uses the
+ * FetcherProvider context to create the appropriate fetcher.
+ *
+ * Schema usage:
+ *   x-ui-widget: "entity-select"
+ *   x-ui-options: {
+ *     endpoint: "/organizations",    // REST: relative to API base
+ *     valueKey: "org_id",
+ *     labelKey: "name",
+ *   }
+ *   -- or --
+ *   x-ui-options: {
+ *     query: "query Orgs($search: String, $limit: Int) { ... }",
+ *     dataPath: "organizations",
+ *     valueKey: "org_id",
+ *     labelKey: "name",
+ *   }
+ */
+
+declare function EntitySelectWidget({ id, name, value, onChange, onBlur, label, description, placeholder, required, disabled, readonly, rawErrors, options, }: WidgetProps): React__default.ReactElement;
+
+/**
+ * ObjectWidget -- renders a nested sub-form for type: "object" properties.
+ *
+ * Composes a JsonSchemaFormRenderer scoped to the sub-schema. The renderer
+ * is injected via NestedFormContext so there is no circular import.
+ *
+ * Presentation is delegated to ObjectContainerTemplate (resolved from context,
+ * defaulting to DefaultObjectContainerTemplate). The variant passed via
+ * options controls which container is used (section, card, collapsible,
+ * inline, borderless).
+ *
+ * When options.displayContents is true (set by ArrayWidget in horizontal mode)
+ * the sub-renderer uses display:contents so its field divs become direct grid
+ * cells in the parent row grid.
+ *
+ * When options.globalOptions is set, it is forwarded to the sub-renderer so
+ * 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;
+
+/**
+ * ArrayWidget -- renders a repeatable list of sub-forms for
+ * type: "array" properties whose items have type: "object".
+ *
+ * Layout is template-driven. The active templates are resolved from
+ * NestedFormContext (injected by JsonSchemaFormRenderer):
+ *   - ArrayItemTemplate    -- how each item is wrapped (default: vertical card)
+ *   - ArrayHeaderTemplate  -- column headers for horizontal mode (default: none)
+ *
+ * Horizontal layout is activated by x-ui-layout.direction: "horizontal" on
+ * the array property or UISchema. The HorizontalArrayItemTemplate renders a
+ * CSS grid row; ObjectWidget sets displayContents=true on the sub-renderer so
+ * field divs become direct grid cells.
+ *
+ * Each item carries a stable form-internal ID (_fid) assigned via generateId().
+ * IDs are used as React keys and for structural diffing at save time. They
+ * 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 QuantityWidget({ id, name, value, onChange, onBlur, propertySchema, required, disabled, readonly, rawErrors, label, description, placeholder, autofocus, options, }: WidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Widget Resolution Algorithm
+ *
+ * Determines which widget to use for a given field based on:
+ * 0. Schema x-ui-widget and x-ui-options (merged with uiSchema if present)
+ * 1. UISchema x-ui-widget (highest priority - overrides x-ui-widget)
+ * 2. Schema x-ui-widget (for widget name)
+ * 3. Schema enum (uses SelectWidget)
+ * 4. Schema format (email, date, color, etc.)
+ * 5. Schema type (string, number, boolean, etc.)
+ * 6. Fallback to TextWidget
+ *
+ * x-ui-widget is a simple string: 'textarea', 'select', etc.
+ * x-ui-options is an object with configuration: { rows: 5, etc. }
+ */
+
+/**
+ * Default widget mapping: schema type → format/variant → widget name
+ *
+ * This defines which widget to use for each combination of schema type and format.
+ * Follows the pattern established by react-jsonschema-form.
+ *
+ * Currently implemented widgets:
+ * - TextInputWidget: Basic text input (email, url formats supported)
+ * - TextareaWidget: Multi-line text input
+ * - NumberWidget: Number and integer input
+ * - CheckboxWidget: Boolean checkbox
+ * - SelectWidget: Dropdown for enum values
+ */
+declare const DEFAULT_WIDGET_MAP: WidgetMap;
+declare function resolveWidget(propertySchema: JsonSchemaProperty, uiSchema: UISchema | undefined, registry: WidgetRegistry): Widget;
+/**
+ * Get the default widget name for a schema type
+ *
+ * Helper function to determine the default widget for a given type
+ * without considering format or other factors.
+ *
+ * @param type - The JSON schema type
+ * @returns The default widget name for that type
+ *
+ * @example
+ * ```typescript
+ * getDefaultWidgetForType('string');  // 'TextInputWidget'
+ * getDefaultWidgetForType('number');  // 'NumberWidget'
+ * getDefaultWidgetForType('boolean'); // 'CheckboxWidget'
+ * ```
+ */
+declare function getDefaultWidgetForType(type: string): string;
+
+/**
+ * Form Widgets - Index and Registry
+ *
+ * Each widget is imported once and re-exported. The same binding is used in
+ * DEFAULT_WIDGETS to avoid the double-import anti-pattern.
+ */
+
+/**
+ * DEFAULT_WIDGETS - The default widget registry.
+ *
+ * Contains all built-in widgets mapped by their names.
+ * Use this as the base registry or extend it with custom widgets.
+ *
+ * @example
+ * ```typescript
+ * import { DEFAULT_WIDGETS } from './widgets';
+ * import MyCustomWidget from './MyCustomWidget';
+ *
+ * const registry = { ...DEFAULT_WIDGETS, MyCustomWidget };
+ * ```
+ */
+declare const DEFAULT_WIDGETS: WidgetRegistry;
+
+/**
+ * JsonSchemaFormRenderer - Generic form renderer based on JSON Schema
+ *
+ * Thin orchestrator: composes useFormEngine, FormFieldRenderer, and FormActions.
+ *
+ * Supports three update modes:
+ * 1. Real-time  (default) — onChange on every field change
+ * 2. Deferred   (deferChanges=true) — onChange on blur for text fields
+ * 3. Buffered   (showActions=true) — Save/Cancel managed by form; onUpdate on Save
+ *
+ * When rendered inside a HorizontalArrayItemTemplate (via ObjectWidget in an
+ * array row), the caller sets `displayContents=true` so this renderer's
+ * wrapper uses `display: contents`, making each field div a direct grid cell
+ * in the parent row grid.
+ *
+ * @module components/Forms/JsonSchemaFormRenderer
+ */
+
+type JsonSchemaFormRendererProps = {
+    /** JSON Schema defining the form fields */
+    schema: JsonSchema;
+    /** Current form data */
+    data: Record<string, any>;
+    /** Callback when any field changes (real-time updates) */
+    onChange?: (data: Record<string, any>) => void;
+    /** Callback when a field loses focus */
+    onBlur?: (fieldName: string, data: Record<string, any>) => void;
+    /** Optional callback for validation state changes */
+    onValidationChange?: (errors: string[], isValid: boolean) => void;
+    /**
+     * Defer onChange to blur for text fields (default: false).
+     * Checkboxes and selects always trigger immediately.
+     */
+    deferChanges?: boolean;
+    /**
+     * Defer internal state updates to blur for text fields (default: false).
+     * Only applies when showActions=true. The Save button enables only after
+     * leaving a modified text field.
+     */
+    deferStateUpdates?: boolean;
+    /**
+     * Callback when user saves changes -- only fired if data actually changed.
+     *
+     * - `data`: complete form data (all fields, _fid stripped)
+     * - `changedFields`: only fields that differ from the original baseline,
+     *   useful for PATCH-style APIs with exclude_unset semantics (_fid stripped)
+     * - `diff`: structured diff classifying each change as value/array add/remove/move/modify.
+     *   Array item changes carry `fid` tokens for correlation; these are form-internal
+     *   and are never sent to the server.
+     */
+    onUpdate?: (data: Record<string, any>, changedFields: Record<string, any>, diff: FormDiff) => void;
+    /** Callback when user clicks Cancel */
+    onCancel?: () => void;
+    /** Disable all fields */
+    disabled?: boolean;
+    /** Read-only mode — fields are not editable */
+    readOnly?: boolean;
+    /** Show Save/Cancel action buttons */
+    showActions?: boolean;
+    /** Label for Save button (default: "Save") */
+    saveLabel?: string;
+    /** Label for Cancel button (default: "Cancel") */
+    cancelLabel?: string;
+    /** Show the Cancel button (default: true) */
+    showCancel?: boolean;
+    /** Show extra properties card (default: true) */
+    showExtraProperties?: boolean;
+    /** Widget registry for custom widgets (default: DEFAULT_WIDGETS) */
+    widgets?: WidgetRegistry;
+    /**
+     * Template registry for custom layout templates (default: DEFAULT_TEMPLATES).
+     *
+     * Templates control structural rendering (array item rows, object containers).
+     * Widgets control input rendering. Override specific templates by providing
+     * a partial registry -- unspecified keys fall back to DEFAULT_TEMPLATES.
+     */
+    templates?: TemplateRegistry;
+    /**
+     * When true, renders with `display: contents` instead of a SimpleStack.
+     *
+     * Used by ObjectWidget when it is a direct child of a HorizontalArrayItemTemplate
+     * row grid. `display: contents` makes this renderer's wrapper invisible to the
+     * layout algorithm so each field div becomes a direct grid cell in the row.
+     */
+    displayContents?: boolean;
+    /**
+     * UISchema for customizing widget behavior and appearance.
+     *
+     * @example
+     * ```typescript
+     * uiSchema={{
+     *   'x-ui-globalOptions': { label: false },
+     *   'x-ui-order': ['email', 'name'],
+     *   name: { 'x-ui-widget': 'textarea' },
+     * }}
+     * ```
+     */
+    uiSchema?: {
+        [fieldName: string]: UISchema;
+    };
+};
+declare function JsonSchemaFormRenderer(props: JsonSchemaFormRendererProps): React__default.ReactElement;
+
+/**
+ * FormFieldRenderer - Renders a single form field via the widget system
+ *
+ * Replaces the `renderField` free function that previously lived in
+ * JsonSchemaFormRenderer. Moving it to a proper component ensures the `key`
+ * prop is set at the call site (in the parent's `.map()`), not buried inside
+ * the function, which is the idiomatic React pattern.
+ *
+ * @module components/Forms/FormFieldRenderer
+ */
+
+interface FormFieldRendererProps {
+    fieldName: string;
+    property: JsonSchemaProperty;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    onBlur?: (id: string, value: unknown) => void;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    schema: JsonSchema;
+    uiSchema?: UISchema;
+    registry: WidgetRegistry;
+    globalOptions?: UISchemaOptions;
+    formData?: Record<string, unknown>;
+}
+declare function FormFieldRenderer({ fieldName, property, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, }: FormFieldRendererProps): React__default.ReactElement | null;
+
+/**
+ * useFormEngine - Core form state, schema resolution, and update-mode logic
+ *
+ * Owns:
+ * - formData state (internal working copy)
+ * - resolvedSchema / orderedProperties (conditional schema + field ordering)
+ * - originalData baseline for dirty-tracking
+ * - nonSchemaData (fields not in the schema, preserved on save)
+ * - pendingChanges (deferred-state-update buffer)
+ * - isValid / validation errors
+ * - handleFieldChange, handleFieldBlur, handleSave, handleCancel
+ *
+ * Supports all three update modes:
+ *   1. Real-time  — onChange on every keystroke
+ *   2. Deferred   — onChange on blur for text fields (deferChanges)
+ *   3. Buffered   — Save/Cancel flow (showActions + onUpdate)
+ *
+ * @module components/Forms/hooks/useFormEngine
+ */
+
+interface UseFormEngineOptions {
+    schema: JsonSchema;
+    data: Record<string, any>;
+    uiSchema: {
+        [fieldName: string]: UISchema;
+    };
+    onChange?: (data: Record<string, any>) => void;
+    onBlur?: (fieldName: string, data: Record<string, any>) => void;
+    onValidationChange?: (errors: string[], isValid: boolean) => void;
+    onUpdate?: (data: Record<string, any>, changedFields: Record<string, any>, diff: FormDiff) => void;
+    onCancel?: () => void;
+    readOnly?: boolean;
+    showActions?: boolean;
+    deferChanges?: boolean;
+    deferStateUpdates?: boolean;
+}
+interface UseFormEngineResult {
+    /** The current working form data (for controlled field values) */
+    formData: Record<string, any>;
+    /**
+     * Display data — formData merged with pending deferred changes.
+     * Always use this for rendering field values.
+     */
+    displayData: Record<string, any>;
+    /** Schema resolved against the current formData (conditional fields evaluated) */
+    resolvedSchema: JsonSchema;
+    /** Properties ordered by x-ui-order, ready for rendering */
+    orderedProperties: [string, JsonSchemaProperty][];
+    hasChanges: boolean;
+    isValid: 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, }: UseFormEngineOptions): UseFormEngineResult;
+
+/**
+ * useResolvedSchema - Schema resolution and property ordering
+ *
+ * Resolves conditional schemas (if-then-else, allOf) based on the current
+ * form data, and applies x-ui-order to produce a stable ordered list of
+ * [fieldName, property] pairs for rendering.
+ *
+ * ## Relationship to useFormEngine
+ *
+ * `useFormEngine` already performs this same resolution internally so that
+ * validation and field-cleanup effects have access to the live schema.
+ * This hook exists as a **standalone composable** for consumers that need
+ * schema resolution without the full form-state machinery — for example:
+ *
+ * - A read-only schema viewer that renders fields without tracking changes
+ * - A field-count or schema-diff preview component
+ * - A future form builder that needs to inspect the resolved structure
+ *   before mounting a full form engine
+ *
+ * Do **not** import both this hook and `useFormEngine` in the same component
+ * for the same schema/data pair — that would resolve the schema twice.
+ * Prefer the values returned by `useFormEngine` when the engine is already
+ * in use.
+ *
+ * @module components/Forms/hooks/useResolvedSchema
+ */
+
+interface UseResolvedSchemaOptions {
+    schema: JsonSchema;
+    formData: Record<string, any>;
+    uiSchema: {
+        [fieldName: string]: UISchema;
+    };
+}
+interface UseResolvedSchemaResult {
+    resolvedSchema: JsonSchema;
+    orderedProperties: [string, JsonSchemaProperty][];
+}
+declare function useResolvedSchema({ schema, formData, uiSchema, }: UseResolvedSchemaOptions): UseResolvedSchemaResult;
+
+type NestedRenderer = (props: Omit<JsonSchemaFormRendererProps, "onUpdate" | "onCancel" | "showActions" | "showExtraProperties">) => React.ReactElement | null;
+interface NestedFormContextValue {
+    renderer: NestedRenderer;
+    templates: TemplateRegistry;
+}
+
+/**
+ * useNestedFormContext -- returns the renderer and templates injected by
+ * the nearest JsonSchemaFormRenderer via NestedFormContext.
+ *
+ * Used by ObjectWidget and ArrayWidget to render nested sub-forms and
+ * resolve layout templates without a circular import.
+ *
+ * Throws if called outside a JsonSchemaFormRenderer tree. This is
+ * intentional: ObjectWidget and ArrayWidget cannot function without
+ * the renderer context, and a clear error is better than a silent null.
+ */
+
+declare function useNestedFormContext(): NestedFormContextValue;
+
+/**
+ * Default templates for structural layout rendering.
+ *
+ * These are the pre-built implementations used by ArrayWidget and
+ * ObjectWidget when no custom template is injected. Callers override
+ * specific templates by passing a partial TemplateRegistry to the
+ * `templates` prop on JsonSchemaFormRenderer.
+ */
+
+/**
+ * DEFAULT_TEMPLATES -- the built-in template implementations.
+ *
+ * Pass a partial override to JsonSchemaFormRenderer's `templates` prop
+ * to replace specific templates globally, or use x-ui-options on a
+ * schema property for per-field overrides.
+ */
+declare const DEFAULT_TEMPLATES: TemplateRegistry;
+
+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 };