nuxt-ui-tools 0.1.2 → 1.0.0

package/dist/runtime/form/types/output.d.ts

@@ -1,5 +1,6 @@
 import type { DeepPrettify, DeepTransformNestedPaths, PathToObject, UnionToIntersection } from '../../shared/types/utils.js';
-import type { ArrayListFieldOutput, ArrayTableFieldOutput, ArrayTabsFieldOutput, ObjectFieldOutput, MatrixFieldOutput, ResolveFormFieldValue } from './field-output.js';
+import type { FormObject, FormValue } from './/index.js';
+import type { ArrayCollapseFieldOutput, ArrayListFieldOutput, ArrayPrimitiveFieldOutput, ArrayTableFieldOutput, ArrayTabsFieldOutput, ObjectFieldOutput, MatrixFieldOutput, ResolveFormFieldValue } from './field-output.js';
 import type { FormStateMode, TransformOutputValue } from './field-output-utils.js';
 export type { ExtractFormFieldInternalValue, NullableValue, ResolveFormFieldValue, } from './field-output.js';
 export type { FormStateMode } from './field-output-utils.js';
@@ -7,17 +8,23 @@ export type ExtractFormFieldOutputValue<TField> = TransformOutputValue<TField, R
 type FieldKey<TField> = TField extends {
     key: infer TKey;
 } ? TKey extends string ? TKey : never : never;
-type FieldValueObject<TField, TValue> = FieldKey<TField> extends infer TKey ? TKey extends string ? string extends TKey ? {} : PathToObject<TKey, TValue> : {} : {};
+type FieldValueObject<TField, TValue> = FieldKey<TField> extends infer TKey ? TKey extends string ? string extends TKey ? NonNullable<unknown> : PathToObject<TKey, TValue> : NonNullable<unknown> : NonNullable<unknown>;
 type OptionalPathToObject<Path extends string, Output> = Path extends `${infer First}.${infer Rest}` ? {
     [K in First]: OptionalPathToObject<Rest, Output>;
 } : {
     [K in Path]?: Output;
 };
-type OptionalFieldValueObject<TField, TValue> = FieldKey<TField> extends infer TKey ? TKey extends string ? string extends TKey ? {} : OptionalPathToObject<TKey, TValue> : {} : {};
+type OptionalFieldValueObject<TField, TValue> = FieldKey<TField> extends infer TKey ? TKey extends string ? string extends TKey ? NonNullable<unknown> : OptionalPathToObject<TKey, TValue> : NonNullable<unknown> : NonNullable<unknown>;
 type ChildFields<TField> = TField extends {
     readonly fields: infer TFields;
-} ? TFields extends readonly unknown[] ? number extends TFields['length'] ? readonly [] : TFields : never : never;
-type FieldsValue<TFields, TMode extends FormStateMode> = TFields extends readonly unknown[] ? DeepTransformNestedPaths<UnionToIntersection<FieldObject<TFields[number], TMode>>> : {};
+} ? TFields extends readonly FormValue[] ? number extends TFields['length'] ? readonly [] : TFields : never : never;
+type TabObject<TTab, TMode extends FormStateMode> = TTab extends {
+    readonly fields: infer TFields;
+} ? FieldsValue<TFields, TMode> : never;
+type TabsFieldsValue<TField, TMode extends FormStateMode> = TField extends {
+    readonly tabs: readonly (infer TTab)[];
+} ? DeepTransformNestedPaths<UnionToIntersection<TabObject<TTab, TMode>>> : NonNullable<unknown>;
+type FieldsValue<TFields, TMode extends FormStateMode> = TFields extends readonly FormValue[] ? number extends TFields['length'] ? FormObject : DeepTransformNestedPaths<UnionToIntersection<FieldObject<TFields[number], TMode>>> : NonNullable<unknown>;
 type VariantValue<TVariant, TVariantKey extends string, TMode extends FormStateMode> = TVariant extends {
     readonly key: infer TKey;
     readonly fields: infer TFields;
@@ -26,11 +33,11 @@ type VirtualFieldsValue<TField> = TField extends {
     readonly virtualFields: infer TVirtualFields;
 } ? {
     [TKey in keyof TVirtualFields]: TVirtualFields[TKey] extends (...args: never[]) => infer TValue ? TValue : never;
-} : {};
+} : NonNullable<unknown>;
 type ArrayVariantValue<TField, TMode extends FormStateMode> = TField extends {
     readonly variantKey: infer TVariantKey extends string;
     readonly variants: readonly (infer TVariant)[];
-} ? readonly VariantValue<TVariant, TVariantKey, TMode>[] : readonly unknown[];
+} ? readonly VariantValue<TVariant, TVariantKey, TMode>[] : readonly FormValue[];
 type ArrayFieldValue<TField, TMode extends FormStateMode> = TField extends {
     type: 'array-list';
 } ? ArrayListFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : TField extends {
@@ -39,7 +46,9 @@ type ArrayFieldValue<TField, TMode extends FormStateMode> = TField extends {
     type: 'array-tabs';
 } ? ArrayTabsFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : TField extends {
     type: 'array-variant';
-} ? ArrayVariantValue<TField, TMode> : never;
+} ? ArrayVariantValue<TField, TMode> : TField extends {
+    type: 'array-collapse';
+} ? ArrayCollapseFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : never;
 type ApplyOutputMode<TField, TMode extends FormStateMode, TValue> = TMode extends 'output' ? TransformOutputValue<TField, TValue> : TValue;
 type ObjectFieldValue<TField, TMode extends FormStateMode> = ApplyOutputMode<TField, TMode, ObjectFieldOutput<FieldsValue<ChildFields<TField>, TMode>>>;
 type MatrixRows<TField> = TField extends {
@@ -52,27 +61,31 @@ type StatefulFieldObject<TField, TMode extends FormStateMode> = TMode extends 'o
     submit: {
         omit: true;
     };
-} ? {} : TField extends {
+} ? NonNullable<unknown> : TField extends {
     condition: infer _TCondition;
 } ? OptionalFieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>> : FieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>> : FieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>>;
 type FieldObject<TField, TMode extends FormStateMode> = TField extends {
     type: 'info' | 'divider' | 'button';
-} ? {} : TField extends {
+} ? NonNullable<unknown> : TField extends {
+    type: 'tabs';
+} ? TabsFieldsValue<TField, TMode> : TField extends {
     type: 'input-group' | 'card' | 'column';
 } ? FieldsValue<ChildFields<TField>, TMode> : TField extends {
     type: 'object' | 'group';
 } ? FieldValueObject<TField, ObjectFieldValue<TField, TMode>> : TField extends {
     type: 'matrix';
 } ? FieldValueObject<TField, MatrixFieldValue<TField, TMode>> : TField extends {
-    type: 'array-list' | 'array-table' | 'array-tabs' | 'array-variant';
-} ? FieldValueObject<TField, ArrayFieldValue<TField, TMode>> : StatefulFieldObject<TField, TMode>;
+    type: 'array-list' | 'array-table' | 'array-tabs' | 'array-variant' | 'array-collapse';
+} ? FieldValueObject<TField, ArrayFieldValue<TField, TMode>> : TField extends {
+    type: 'array-primitive';
+} ? FieldValueObject<TField, ApplyOutputMode<TField, TMode, ArrayPrimitiveFieldOutput<TField>>> : StatefulFieldObject<TField, TMode>;
 type StepFields<TStep> = TStep extends {
     readonly fields: infer TFields;
 } ? TFields : never;
-type StepObject<TStep, TMode extends FormStateMode> = TStep extends unknown ? TStep extends {
+type StepObject<TStep, TMode extends FormStateMode> = TStep extends FormValue ? TStep extends {
     readonly root: infer TRoot;
 } ? TRoot extends string ? string extends TRoot ? FieldsValue<StepFields<TStep>, TMode> : PathToObject<TRoot, FieldsValue<StepFields<TStep>, TMode>> : FieldsValue<StepFields<TStep>, TMode> : FieldsValue<StepFields<TStep>, TMode> : never;
-type StepsValue<TSteps, TMode extends FormStateMode> = TSteps extends readonly unknown[] ? DeepTransformNestedPaths<UnionToIntersection<StepObject<TSteps[number], TMode>>> : {};
+type StepsValue<TSteps, TMode extends FormStateMode> = TSteps extends readonly FormValue[] ? DeepTransformNestedPaths<UnionToIntersection<StepObject<TSteps[number], TMode>>> : NonNullable<unknown>;
 /**
  * Extracts the complete internal form value from a raw authored schema.
  */
@@ -80,7 +93,7 @@ export type ExtractFormInternalValue<TSchema> = TSchema extends {
     readonly fields: infer TFields;
 } ? DeepPrettify<FieldsValue<TFields, 'internal'>> : TSchema extends {
     readonly steps: infer TSteps;
-} ? DeepPrettify<StepsValue<TSteps, 'internal'>> : {};
+} ? DeepPrettify<StepsValue<TSteps, 'internal'>> : NonNullable<unknown>;
 /**
  * Extracts the complete submitted output value from a raw authored schema.
  */
@@ -88,4 +101,4 @@ export type ExtractFormOutput<TSchema> = TSchema extends {
     readonly fields: infer TFields;
 } ? DeepPrettify<FieldsValue<TFields, 'output'>> : TSchema extends {
     readonly steps: infer TSteps;
-} ? DeepPrettify<StepsValue<TSteps, 'output'>> : {};
+} ? DeepPrettify<StepsValue<TSteps, 'output'>> : NonNullable<unknown>;

package/dist/runtime/form/types/overlay.d.ts

@@ -1,4 +1,5 @@
 import type { ComputedRef, Ref } from 'vue';
+import type { FormValue } from './/index.js';
 import type { FormSubmitHandlerResult } from './api.js';
 import type { FormRendererController } from './controller.js';
 import type { FormDrawerConfig, FormFullscreenConfig, FormModalConfig } from './schema.js';
@@ -27,7 +28,7 @@ export interface FormOverlayLayoutEmits {
 export type FormOverlayResolution = {
     type: 'complete';
     formData: FormObject;
-    submitData?: unknown;
+    submitData?: FormValue;
 } | {
     type: 'cancel';
     formData: FormObject;
@@ -39,6 +40,6 @@ export interface FormOverlayController {
     description: ComputedRef<string | undefined>;
     dismissible: ComputedRef<boolean>;
     handleOpenUpdate: (value: boolean) => void;
-    handleSubmitted: (formData: FormObject, result: FormSubmitHandlerResult<unknown>) => void;
+    handleSubmitted: (formData: FormObject, result: FormSubmitHandlerResult<FormValue>) => void;
     resolveAfterClose: () => void;
 }

package/dist/runtime/form/types/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { ComputedRef, Ref } from 'vue';
-import type { FormFieldApi } from './api.js';
-import type { FormSubmitAction, FormSubmitHandler, FormSubmitHandlerResult } from './api.js';
+import type { FormValue } from './/index.js';
+import type { FormErrorOptions, FormFieldApi, FormSubmitAction, FormSubmitHandler, FormSubmitHandlerResult } from './api.js';
 import type { FormFieldCallbackParams } from './callbacks.js';
 import type { FormRuntimeContext } from './context.js';
 import type { FormField } from './field.js';
@@ -15,7 +15,7 @@ import type { FormValidationError, FormValidationMode, FormValidationOptions } f
  */
 export interface UseFormRuntimeParams {
     /** Authored schema currently rendered by the form. */
-    schema: ComputedRef<unknown>;
+    schema: ComputedRef<FormValue>;
     /** Optional initial internal state provided by a controller or direct form usage. */
     input?: ComputedRef<FormObject | undefined>;
     syncInput?: ComputedRef<boolean | readonly string[]>;
@@ -44,7 +44,7 @@ export interface FormRuntimeStep {
  * exposed as top-level consumer API without deliberate design.
  */
 export interface FormRuntime {
-    schema: ComputedRef<unknown>;
+    schema: ComputedRef<FormValue>;
     state: FormObject;
     output: ComputedRef<FormObject>;
     dirtyPaths: ComputedRef<readonly string[]>;
@@ -63,8 +63,11 @@ export interface FormRuntime {
     isLastStep: ComputedRef<boolean>;
     canGoPrevious: ComputedRef<boolean>;
     canGoNext: ComputedRef<boolean>;
-    getValue: (path: string | readonly string[]) => unknown;
-    setValue: (path: string | readonly string[], value: unknown) => void;
+    getValue: (path: string | readonly string[]) => FormValue;
+    getInitialValue: (path: string | readonly string[]) => FormValue;
+    trackEffect: (effect: FormValue) => void;
+    settleEffects: () => Promise<void>;
+    setValue: (path: string | readonly string[], value: FormValue) => void;
     getFieldApi: (path: readonly string[], field?: FormField) => FormFieldApi;
     getFieldCallbackParams: (path: readonly string[], field: FormField) => FormFieldCallbackParams;
     registerFieldOptions: (path: readonly string[], state: FormOptionRuntimeState) => () => void;
@@ -76,7 +79,7 @@ export interface FormRuntime {
     shouldRender: (field: FormField, path: readonly string[]) => boolean;
     validate: (options?: FormValidationOptions) => Promise<boolean>;
     validateCurrentStep: (options?: FormValidationOptions) => Promise<boolean>;
-    setError: (path: string | readonly string[], message: string) => void;
+    setError: (path: string | readonly string[], message: string, options?: FormErrorOptions) => void;
     clearError: (path?: string | readonly string[]) => void;
     focusRequest: Ref<FormFocusRequest | null>;
     registerFieldElement: (path: string | readonly string[], element: HTMLElement) => () => void;
@@ -85,7 +88,7 @@ export interface FormRuntime {
     clearErrors: () => void;
     submitHandler: (submitHandler?: FormSubmitHandler<FormObject>) => Promise<FormSubmitHandlerResult>;
     submit: () => Promise<boolean>;
-    reset: () => void;
+    reset: () => Promise<void>;
     nextStep: () => Promise<boolean>;
     previousStep: () => Promise<boolean>;
     goToStep: (index: number) => Promise<boolean>;

package/dist/runtime/form/types/schema.d.ts

@@ -1,8 +1,9 @@
+import type { FormValue } from './/index.js';
 import type { FormAction } from './actions.js';
 import type { FormApi, FormSubmitHandler } from './api.js';
 import type { FormContextData, FormContextDefinition } from './context.js';
 import type { FormField, FormFieldType } from './field.js';
-import type { FormLayoutConfig } from './layout.js';
+import type { FormLayoutConfig, FormRenderShell } from './layout.js';
 import type { FormUiConfig } from './ui.js';
 import type { FormMaybePromise, FormObject, FormText } from './utils.js';
 import type { FormValidationMode } from './validation.js';
@@ -13,6 +14,8 @@ export interface FormDirtyNavigationConfig {
 export interface FormControlsConfig {
     /** Enables dirty metadata and field reset affordances. */
     dirtyCheck?: boolean;
+    /** Paths whose changes never make the form dirty. Matches the path and everything nested under it. */
+    ignoreDirtyPaths?: readonly string[];
     /** Focuses the first field after mount, or a specific raw field path. */
     autoFocus?: boolean | string;
     /** Warns before an inline dirty form is closed or navigated away from. */
@@ -22,7 +25,22 @@ export interface FormControlsConfig {
     /** Selects required, custom-rule, all, or no validation. */
     validate?: FormValidationMode;
 }
+/** Where the schema header renders: only in overlay shells, everywhere, never, or in listed shells. */
+export type FormHeaderDisplay = 'overlay' | 'always' | 'never' | readonly FormRenderShell[];
+export interface FormHeaderConfig {
+    /** Small caption above the title, typically the entity or domain name. */
+    eyebrow?: FormText;
+    /** Form title. Also used as the overlay's accessible name. */
+    title?: FormText;
+    /** Supporting copy under the title. */
+    description?: FormText;
+    /** Defaults to `'overlay'`. */
+    display?: FormHeaderDisplay;
+}
+export type FormModalSize = 'md' | 'lg' | 'xl';
 export interface FormModalConfig {
+    /** Preset width: 600, 760 or 920px. `maxWidth` wins when both are set. */
+    size?: FormModalSize;
     maxWidth?: number | string;
     maxHeight?: number | string;
     allowOutsideClick?: boolean;
@@ -55,7 +73,7 @@ export interface FormStepLifecycleParams<TOutput = FormObject> {
 /**
  * Step in a multi-step form schema.
  */
-export interface FormStep<TContext = {}, TFields extends readonly FormField<TContext>[] = readonly FormField<TContext>[]> {
+export interface FormStep<TContext = NonNullable<unknown>, TFields extends readonly FormField<TContext>[] = readonly FormField<TContext>[]> {
     /** Stable step key used by navigation state and test selectors. */
     key?: string;
     /** Optional title rendered by stepper-aware layouts. */
@@ -79,8 +97,8 @@ export interface FormStep<TContext = {}, TFields extends readonly FormField<TCon
 export interface FormSchema<TContext extends FormContextDefinition | undefined = FormContextDefinition | undefined, TFields extends readonly FormField<FormContextData<TContext>>[] = readonly FormField<FormContextData<TContext>>[], TSteps extends readonly FormStep<FormContextData<TContext>>[] = readonly FormStep<FormContextData<TContext>>[]> {
     /** Stable key used by persistence, diagnostics, and test selectors. */
     formKey?: string;
-    /** Optional user-facing title for full-form renderers. */
-    title?: FormText;
+    /** Header rendered by form shells. Shown in overlays by default, see `header.display`. */
+    header?: FormHeaderConfig;
     /** Form-scoped data sources exposed to fields as `ctx`. */
     context?: TContext;
     /** Form-level field grid layout. */
@@ -104,28 +122,28 @@ export interface FormSchema<TContext extends FormContextDefinition | undefined =
     /** Form action configuration. Omit to use built-in reset/submit or previous/next/submit actions. */
     actions?: readonly FormAction[];
     /** Runs after validation and before the external submit handler. Return `false` to cancel submit. */
-    onBeforeSubmit?: FormSubmitHandler<unknown, never>;
+    onBeforeSubmit?: FormSubmitHandler<FormValue, never>;
     /** Submit lifecycle hook. */
     submit?: (params: {
-        value: unknown;
+        value: FormValue;
         api: FormApi;
         ctx: FormContextData<TContext>;
     }) => Promise<void> | void;
     /** Runs after current-step validation and before advancing to the next step. Return `false` to stop navigation. */
-    onBeforeNext?: (params: FormStepLifecycleParams<unknown>) => FormMaybePromise<boolean | void>;
+    onBeforeNext?: (params: FormStepLifecycleParams<FormObject>) => FormMaybePromise<boolean | void>;
     /** Runs before moving to the previous step. */
-    onBeforePrevious?: (params: FormStepLifecycleParams<unknown>) => FormMaybePromise<void>;
+    onBeforePrevious?: (params: FormStepLifecycleParams<FormObject>) => FormMaybePromise<void>;
     /** Returns true when a step should be skipped during previous/next navigation. */
-    skipStep?: (params: FormStepLifecycleParams<unknown>) => boolean;
+    skipStep?: (params: FormStepLifecycleParams<FormObject>) => boolean;
     /** Runs when `skipStep` skips a step. */
-    onStepSkipped?: (params: Omit<FormStepLifecycleParams<unknown>, 'stepData'>) => void;
+    onStepSkipped?: (params: Omit<FormStepLifecycleParams<FormObject>, 'stepData'>) => void;
 }
 /**
  * Extracts the typed context object exposed by a form schema.
  */
 export type ExtractFormContext<TSchema> = TSchema extends {
     readonly context?: infer TContext extends FormContextDefinition | undefined;
-} ? FormContextData<TContext> : {};
+} ? FormContextData<TContext> : NonNullable<unknown>;
 /**
  * Extracts the authored fields from a form schema.
  */
@@ -149,7 +167,7 @@ type NoExtraFieldProperties<TField, TExpected> = Exclude<keyof TField, keyof TEx
 /**
  * Strict authored field shape used by schema helpers.
  */
-export type StrictFormField<TField, TContext = {}> = TField extends {
+export type StrictFormField<TField, TContext = NonNullable<unknown>> = TField extends {
     type: infer TType;
 } ? TType extends FormFieldType ? NoExtraFieldProperties<TField, FormFieldByType<TType, TContext>> : never : never;
 /**
@@ -157,7 +175,7 @@ export type StrictFormField<TField, TContext = {}> = TField extends {
  */
 export type StrictFormFields<TFields extends readonly {
     type: FormFieldType;
-}[], TContext = {}> = {
+}[], TContext = NonNullable<unknown>> = {
     readonly [TKey in keyof TFields]: StrictFormField<TFields[TKey], TContext>;
 };
 export {};

package/dist/runtime/form/types/transform.d.ts

@@ -1,8 +1,9 @@
+import type { FormValue } from './/index.js';
 import type { FormFieldCallbackParams } from './callbacks.js';
 /**
  * Input/output transform hooks for a stateful field.
  */
-export interface FormTransformConfig<TInternal = unknown, TExternal = TInternal, TContext = {}, TDeps = {}> {
+export interface FormTransformConfig<TInternal = FormValue, TExternal = TInternal, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> {
     /** Converts an incoming raw value into the internal form value. Replaces legacy `preformat`. */
     input?: (value: TExternal, params: FormFieldCallbackParams<TContext, TDeps, TInternal>) => TInternal;
     /** Converts the internal form value into the submitted output value. Replaces legacy `transform`. */

package/dist/runtime/form/types/ui.d.ts

@@ -18,7 +18,9 @@ export interface FormRootUi {
     header?: FormUiClass;
     headerContent?: FormUiClass;
     heading?: FormUiClass;
+    eyebrow?: FormUiClass;
     title?: FormUiClass;
+    description?: FormUiClass;
     stepper?: FormUiClass;
     step?: FormUiClass;
     viewport?: FormUiClass;
@@ -44,10 +46,23 @@ export interface FormFieldUi {
     help?: FormUiClass;
     body?: FormUiClass;
     content?: FormUiClass;
+    pending?: FormUiClass;
     collapsible?: FormUiClass;
     collapseTrigger?: FormUiClass;
     reset?: FormUiClass;
 }
+export interface FormSectionUi {
+    root?: FormUiClass;
+    label?: FormUiClass;
+    description?: FormUiClass;
+}
+export interface FormTabsUi {
+    root?: FormUiClass;
+    list?: FormUiClass;
+    trigger?: FormUiClass;
+    content?: FormUiClass;
+    fields?: FormUiClass;
+}
 export interface FormActionsUi {
     root?: FormUiClass;
     left?: FormUiClass;
@@ -112,8 +127,41 @@ export interface FormArrayListUi {
     add?: FormUiClass;
     action?: FormUiClass;
 }
+export interface FormArrayCollapseUi {
+    root?: FormUiClass;
+    header?: FormUiClass;
+    title?: FormUiClass;
+    description?: FormUiClass;
+    empty?: FormUiClass;
+    list?: FormUiClass;
+    item?: FormUiClass;
+    itemHeader?: FormUiClass;
+    trigger?: FormUiClass;
+    arrow?: FormUiClass;
+    itemTitle?: FormUiClass;
+    summary?: FormUiClass;
+    itemActions?: FormUiClass;
+    body?: FormUiClass;
+    fields?: FormUiClass;
+    add?: FormUiClass;
+    action?: FormUiClass;
+}
+export interface FormArrayPrimitiveUi {
+    root?: FormUiClass;
+    empty?: FormUiClass;
+    list?: FormUiClass;
+    item?: FormUiClass;
+    preview?: FormUiClass;
+    control?: FormUiClass;
+    action?: FormUiClass;
+    add?: FormUiClass;
+}
 export interface FormArrayTableUi {
     root?: FormUiClass;
+    header?: FormUiClass;
+    title?: FormUiClass;
+    description?: FormUiClass;
+    frame?: FormUiClass;
     viewport?: FormUiClass;
     table?: FormUiClass;
     head?: FormUiClass;
@@ -125,7 +173,9 @@ export interface FormArrayTableUi {
     cell?: FormUiClass;
     control?: FormUiClass;
     actionsCell?: FormUiClass;
+    error?: FormUiClass;
     empty?: FormUiClass;
+    addCell?: FormUiClass;
     add?: FormUiClass;
     action?: FormUiClass;
 }
@@ -156,12 +206,16 @@ export interface FormUiConfig {
     root?: FormUiPartConfig<FormRootUi>;
     field?: FormUiPartConfig<FormFieldUi>;
     actions?: FormUiPartConfig<FormActionsUi>;
+    section?: FormUiPartConfig<FormSectionUi>;
+    tabs?: FormUiPartConfig<FormTabsUi>;
     group?: FormUiPartConfig<FormGroupUi>;
     tree?: FormUiPartConfig<FormTreeUi>;
     treeSelect?: FormUiPartConfig<FormTreeSelectUi>;
     matrix?: FormUiPartConfig<FormMatrixUi>;
     arrayList?: FormUiPartConfig<FormArrayListUi>;
     arrayTable?: FormUiPartConfig<FormArrayTableUi>;
+    arrayCollapse?: FormUiPartConfig<FormArrayCollapseUi>;
+    arrayPrimitive?: FormUiPartConfig<FormArrayPrimitiveUi>;
     modal?: FormUiPartConfig<FormOverlayUi>;
     drawer?: FormUiPartConfig<FormOverlayUi>;
     fullscreen?: FormUiPartConfig<FormOverlayUi>;

package/dist/runtime/form/types/upload-runtime.d.ts

@@ -1,6 +1,7 @@
+import type { FormValue } from './/index.js';
 export interface FormUploadRuntimeState {
     start: () => Promise<void>;
     cancel: () => Promise<void>;
     retry: () => Promise<void>;
-    remove: (value?: unknown) => Promise<void>;
+    remove: (value?: FormValue) => Promise<void>;
 }

package/dist/runtime/form/types/utils.d.ts

@@ -19,6 +19,8 @@ export type FormRenderable = LazyRenderableValue;
  * Generic object used for UI-library props and other intentionally open extension bags.
  */
 export type FormObject = GenericObject;
+/** Value crossing a form runtime boundary before its owning parser narrows it. */
+export type FormValue = FormObject[string];
 /**
  * A value that can be static or derived from the current field callback context.
  */

package/dist/runtime/form/types/validation.d.ts

@@ -1,5 +1,7 @@
+import type { RegleRuleRaw } from '@regle/core';
+import type { FormValue } from './/index.js';
 import type { FormFieldCallback } from './callbacks.js';
-import type { FormMaybePromise, FormText } from './utils.js';
+import type { FormMaybePromise, FormObject, FormText } from './utils.js';
 /**
  * Result returned by a form validation rule.
  */
@@ -7,7 +9,7 @@ export type FormValidationResult = boolean | string | null | undefined;
 /**
  * A single validation rule.
  */
-export interface FormValidationRule<TValue = unknown, TContext = {}, TDeps = {}> {
+export interface FormValidationRule<TValue = FormValue, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> {
     /** Stable rule name used for debugging, i18n, and external error mapping. */
     name: string;
     /** Returns true for valid values, false/string for invalid values. */
@@ -34,6 +36,8 @@ export interface FormValidationError {
     path: string;
     /** Resolved message safe to display in the UI. */
     message: string;
+    /** External errors only block submit when set with `blocking: true`. */
+    blocking?: boolean;
 }
 /**
  * Options accepted by form-level validation calls.
@@ -52,7 +56,7 @@ export interface FormValidationOptions {
 /**
  * Field validation configuration.
  */
-export interface FormValidationConfig<TValue = unknown, TContext = {}, TDeps = {}> {
+export interface FormValidationConfig<TValue = FormValue, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> {
     /** Defines when the field starts showing validation feedback while editing. */
     trigger?: FormValidationTrigger;
     /** Marks the field as required. */
@@ -62,3 +66,7 @@ export interface FormValidationConfig<TValue = unknown, TContext = {}, TDeps = {
     /** Additional field rules. */
     rules?: readonly FormValidationRule<TValue, TContext, TDeps>[];
 }
+/** Native Regle rules keyed by their validation name. */
+export type FormValidators = Record<string, RegleRuleRaw>;
+/** Static or dependency-aware native Regle rules for one field. */
+export type FormValidatorsConfig<TContext = NonNullable<unknown>> = FormValidators | FormFieldCallback<FormValidators, TContext, FormObject>;

package/dist/runtime/form/utils/api.js

@@ -1,15 +1,16 @@
 import { pathSegments } from "./path.js";
 export function createPublicFormApi(runtime) {
   return {
-    get: runtime.getValue,
-    set: runtime.setValue,
-    validate: runtime.validate,
-    setError: (path, message) => runtime.setError(pathSegments(path), message),
     clearError: (path) => runtime.clearError(path ? pathSegments(path) : void 0),
     focus: runtime.focusField,
+    get: runtime.getValue,
+    initial: runtime.getInitialValue,
+    reset: runtime.reset,
+    set: runtime.setValue,
+    setError: (path, message, options) => runtime.setError(pathSegments(path), message, options),
     submit: async () => {
       await runtime.submit();
     },
-    reset: runtime.reset
+    validate: runtime.validate
   };
 }

package/dist/runtime/form/utils/array.d.ts

@@ -1,2 +1,2 @@
-import type { FormObject } from '../types/index.js';
-export declare function syncFormArrayItems(target: unknown, source: readonly FormObject[]): boolean;
+import type { FormValue, FormObject } from '../types/index.js';
+export declare function syncFormArrayItems(target: FormValue, source: readonly FormObject[]): boolean;

package/dist/runtime/form/utils/array.js

@@ -1,6 +1,8 @@
 import { cloneFormValue, isRecord } from "./path.js";
 export function syncFormArrayItems(target, source) {
-  if (!Array.isArray(target)) return false;
+  if (!Array.isArray(target)) {
+    return false;
+  }
   const snapshots = source.map((item) => {
     const cloned = cloneFormValue(item);
     return isRecord(cloned) ? cloned : {};
@@ -11,8 +13,14 @@ export function syncFormArrayItems(target, source) {
       target[index] = snapshot;
       continue;
     }
-    for (const key of Object.keys(current)) if (!(key in snapshot)) delete current[key];
-    for (const [key, value] of Object.entries(snapshot)) current[key] = value;
+    for (const key of Object.keys(current)) {
+      if (!(key in snapshot)) {
+        delete current[key];
+      }
+    }
+    for (const [key, value] of Object.entries(snapshot)) {
+      current[key] = value;
+    }
   }
   target.splice(snapshots.length);
   return true;

package/dist/runtime/form/utils/compare.d.ts

@@ -0,0 +1,2 @@
+import type { FormValue } from '../types/index.js';
+export declare function isEqualFormValue(left: FormValue, right: FormValue): boolean;

package/dist/runtime/form/utils/compare.js

@@ -0,0 +1,27 @@
+import { isRecord } from "./path.js";
+function isPlainRecord(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+export function isEqualFormValue(left, right) {
+  if (Object.is(left, right)) {
+    return true;
+  }
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() === right.getTime();
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((item, index) => isEqualFormValue(item, right[index]));
+  }
+  if (isPlainRecord(left) && isPlainRecord(right)) {
+    const keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length) {
+      return false;
+    }
+    return keys.every((key) => key in right && isEqualFormValue(left[key], right[key]));
+  }
+  return false;
+}

package/dist/runtime/form/utils/dependencies.js

@@ -1,11 +1,16 @@
 import { getScopedPathValue } from "./path.js";
+import { isString } from "./predicate.js";
 export function resolveFieldDependencies(params) {
   const output = {};
   const dependencies = Object.getOwnPropertyDescriptor(params.field, "dependencies")?.value;
-  if (!Array.isArray(dependencies)) return output;
+  if (!Array.isArray(dependencies)) {
+    return output;
+  }
   for (const dependency of dependencies) {
     const normalized = normalizeFieldDependency(dependency);
-    if (!normalized) continue;
+    if (!normalized) {
+      continue;
+    }
     output[normalized.target] = getScopedPathValue(
       params.state,
       normalized.source,
@@ -15,9 +20,15 @@ export function resolveFieldDependencies(params) {
   return output;
 }
 function normalizeFieldDependency(value) {
-  if (typeof value === "string") return { source: value, target: value };
-  if (!Array.isArray(value)) return null;
+  if (isString(value)) {
+    return { source: value, target: value };
+  }
+  if (!Array.isArray(value)) {
+    return null;
+  }
   const [source, target] = value;
-  if (typeof source !== "string" || typeof target !== "string") return null;
+  if (!isString(source) || !isString(target)) {
+    return null;
+  }
   return { source, target };
 }

package/dist/runtime/form/utils/field-instance.d.ts

@@ -1,6 +1,6 @@
 import type { FormField, FormFieldCapability, FormFieldKindDefinition, FormFieldState, FormFieldType } from '../types/index.js';
+export { type FormFieldCapability, type FormFieldState } from '../types/index.js';
 export type FormFieldKind = FormFieldKindDefinition;
-export type { FormFieldCapability, FormFieldState };
 /**
  * Internal public instance for checking authored field behavior against the field-kind registry.
  *