@petrarca/sonnet-forms 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -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;
@@ -432,6 +450,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 +467,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 +487,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 +523,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 +613,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;
@@ -935,6 +970,13 @@ 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;
     /** Label for Save button (default: "Save") */
     saveLabel?: string;
     /** Label for Cancel button (default: "Cancel") */
@@ -981,6 +1023,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 +1057,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 +1101,13 @@ 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;
 }
 interface UseFormEngineResult {
     /** The current working form data (for controlled field values) */
@@ -1067,7 +1128,7 @@ interface UseFormEngineResult {
     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, }: UseFormEngineOptions): UseFormEngineResult;
 
 /**
  * useResolvedSchema - Schema resolution and property ordering