@dragonmastery/zinia-forms-core 0.3.12 → 0.3.15

package/dist/index.d.ts

@@ -148,40 +148,6 @@ interface CheckboxFieldProps<FormType> {
     variant?: string;
 }
 
-interface DateFieldProps<FormType> {
-    name: FlexiblePath<FormType>;
-    label?: string;
-    hideLabel?: boolean;
-    description?: string;
-    required?: boolean;
-    placeholder?: string;
-    disabled?: boolean;
-    readonly?: boolean;
-    class?: string | string[];
-    size?: string;
-    variant?: string;
-    min?: string;
-    max?: string;
-    formatter?: (date: string) => unknown;
-}
-
-interface NumberFieldProps<FormType> {
-    name: FlexiblePath<FormType>;
-    label?: string;
-    hideLabel?: boolean;
-    description?: string;
-    required?: boolean;
-    placeholder?: string;
-    disabled?: boolean;
-    readonly?: boolean;
-    class?: string | string[];
-    size?: string;
-    variant?: string;
-    min?: number;
-    max?: number;
-    step?: number;
-}
-
 /**
  * Option item for select fields
  * @template TData - Type of the optional data object for storing additional metadata
@@ -368,6 +334,186 @@ interface SelectFieldProps<FormType, P extends Path<FormType> = Path<FormType>,
  */
 declare const SELECT_FIELD_PROP_NAMES: readonly ["name", "selectOptions", "placeholder", "disabled", "readonly", "class", "label", "hideLabel", "description", "required", "size", "variant", "valueToLabel", "useSchemaOptions", "dependsOn", "optionFilterFn", "autoReset"];
 
+/**
+ * Props for the ComboboxField component
+ * @template FormType - The form type
+ * @template P - The field path in the form
+ * @template TData - The type of the data property in SelectOption (for cascading dropdowns)
+ */
+interface ComboboxFieldProps<FormType, P extends Path<FormType> = Path<FormType>, TData = any> {
+    /**
+     * Field name (path in the form state)
+     * Accepts both static paths and dynamic paths for use in array fields
+     */
+    name: FlexiblePath<FormType>;
+    /**
+     * Field label
+     */
+    label?: string;
+    /**
+     * Whether to hide the label
+     */
+    hideLabel?: boolean;
+    /**
+     * Field description
+     */
+    description?: string;
+    /**
+     * Whether the field is required
+     */
+    required?: boolean;
+    /**
+     * Placeholder text
+     */
+    placeholder?: string;
+    /**
+     * Whether the field is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Whether the field is readonly
+     */
+    readonly?: boolean;
+    /**
+     * CSS classes to apply to the field
+     */
+    class?: string | string[];
+    /**
+     * Field size
+     */
+    size?: string;
+    /**
+     * Field variant
+     */
+    variant?: string;
+    /**
+     * Combobox options (overrides options from schema)
+     * Using selectOptions instead of options to avoid conflicts with HTML select element
+     *
+     * For async loading, use form-level dataLoaders and pass options via extraData:
+     * ```ts
+     * useForm(schema, {
+     *   dataLoaders: { products: loadProducts },
+     * });
+     * // Then: :selectOptions="form.extraData.products || []"
+     * ```
+     *
+     * @example
+     * // With typed data
+     * interface CityData { country: string; }
+     * const options: SelectOption<CityData>[] = [
+     *   { value: 'nyc', label: 'New York', data: { country: 'usa' } }
+     * ];
+     */
+    selectOptions?: SelectOption<TData>[];
+    /**
+     * Custom mapping function to convert values to labels
+     * This is useful when you want to customize how labels are displayed
+     * without providing a full options array
+     *
+     * Can be provided as either:
+     * 1. A function that takes a value and returns a label
+     * 2. An object map where keys are enum values and values are labels
+     */
+    valueToLabel?: ValueToLabelMapping<FieldPathToEnum$1<FormType, P>>;
+    /**
+     * Whether to use options from the schema (default: true)
+     * Set to false to ignore schema options even when no options prop is provided
+     */
+    useSchemaOptions?: boolean;
+    /**
+     * Field path that this field depends on for cascading dropdowns
+     * When the parent field changes, this field's options will be filtered
+     * and the field will be reset (unless autoReset is false)
+     *
+     * @example
+     * // City field depends on country field
+     * <ComboboxField name="city" dependsOn="country" :optionFilterFn="filterCitiesByCountry" />
+     */
+    dependsOn?: FlexiblePath<FormType>;
+    /**
+     * Function to filter options based on the parent field's value
+     * Receives the parent field value and all available options
+     * Should return the filtered options array
+     *
+     * The function signature is tied to the TData type parameter, ensuring type safety
+     * between selectOptions and optionFilterFn
+     *
+     * @example
+     * // With typed data - both props must use the same data type
+     * interface CityData { country: string; }
+     * const filterCitiesByCountry = (
+     *   countryValue: string,
+     *   allOptions: SelectOption<CityData>[]
+     * ): SelectOption<CityData>[] => {
+     *   return allOptions.filter(opt => opt.data?.country === countryValue);
+     * };
+     */
+    optionFilterFn?: (parentValue: any, allOptions: SelectOption<TData>[]) => SelectOption<TData>[];
+    /**
+     * Whether to automatically reset this field when the parent field changes (default: true)
+     * Set to false if you want to preserve the value when parent changes
+     */
+    autoReset?: boolean;
+    /**
+     * Whether to allow creating new values that don't exist in the options
+     * Default: false (must be explicitly set to true to allow creation)
+     *
+     * Note: This is specific to ComboboxField and not available in SelectField
+     */
+    allowCreate?: boolean;
+    /**
+     * Custom filter function for filtering options as user types
+     * Default: filters by case-insensitive substring match
+     *
+     * Note: This is specific to ComboboxField and not available in SelectField
+     * This is different from optionFilterFn which filters based on parent field values
+     */
+    filterFn?: (query: string, option: SelectOption<TData>) => boolean;
+}
+/**
+ * Array of prop names for ComboboxField component.
+ * This is derived from ComboboxFieldProps interface and ensures type safety.
+ * Used for prop normalization and filtering in component implementations.
+ *
+ * TypeScript ensures all entries are valid keys of ComboboxFieldProps.
+ */
+declare const COMBOBOX_FIELD_PROP_NAMES: readonly ["name", "selectOptions", "placeholder", "disabled", "readonly", "class", "label", "hideLabel", "description", "required", "size", "variant", "valueToLabel", "useSchemaOptions", "dependsOn", "optionFilterFn", "autoReset", "allowCreate", "filterFn"];
+
+interface DateFieldProps<FormType> {
+    name: FlexiblePath<FormType>;
+    label?: string;
+    hideLabel?: boolean;
+    description?: string;
+    required?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    class?: string | string[];
+    size?: string;
+    variant?: string;
+    min?: string;
+    max?: string;
+    formatter?: (date: string) => unknown;
+}
+
+interface NumberFieldProps<FormType> {
+    name: FlexiblePath<FormType>;
+    label?: string;
+    hideLabel?: boolean;
+    description?: string;
+    required?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    class?: string | string[];
+    size?: string;
+    variant?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+
 /**
  * Type to convert underscores to PascalCase
  * This helper type processes a single segment by capitalizing after underscores
@@ -429,11 +575,11 @@ type EnumFieldComponent<T, P extends Path<T>> = (props: Omit<SelectFieldProps<T>
     valueToLabel: Record<FieldPathToEnum<T, P>, string>;
 }, context?: any) => any;
 /**
- * Type for select field components (can work with string or enum fields)
- * Uses SelectFieldProps<T, P, TData> to preserve path-specific typing for props like dependsOn
- * and ensure type safety between selectOptions and optionFilterFn
+ * Type for combobox field components (searchable select with optional creation)
+ * Uses ComboboxFieldProps<T, P, TData> which extends SelectFieldProps with allowCreate and filterFn
+ * Preserves path-specific typing for props like dependsOn and ensures type safety
  */
-type SelectFieldComponent<T, P extends Path<T>> = <TData = any>(props: Omit<SelectFieldProps<T, P, TData>, 'name'>, context?: any) => any;
+type ComboboxFieldComponent<T, P extends Path<T>> = <TData = any>(props: Omit<ComboboxFieldProps<T, P, TData>, 'name'>, context?: any) => any;
 /**
  * Type for number field components
  */
@@ -461,14 +607,19 @@ type GenericFieldComponent = (props: any, context?: any) => any;
 type UnwrapOptional<T> = Exclude<T, undefined | null>;
 /**
  * Maps a field path to its component type based on the field's actual type
- * Enums are explicitly passed as FieldType = 'enum' since they can't be auto-detected
- * Everything else is inferred from the actual TypeScript type at the path
+ * FieldType can be 'enum', 'combobox', or 'string' (default)
+ * - 'enum': Uses EnumFieldComponent (requires valueToLabel)
+ * - 'combobox': Uses ComboboxFieldComponent (includes allowCreate and filterFn)
+ * - 'string': Uses ComboboxFieldComponent (superset of SelectField with allowCreate and filterFn)
  *
- * For string fields, we use SelectFieldComponent<T, P> which is a superset that includes
- * all TextField functionality plus additional props like dependsOn for cascading dropdowns.
- * This provides better type safety and autocomplete.
+ * We use ComboboxFieldComponent for all string fields because:
+ * 1. ComboboxFieldProps includes all SelectFieldProps (it's a superset)
+ * 2. This allows allowCreate to be available in types even if the field uses SelectField at runtime
+ * 3. ComboboxField can handle all SelectField use cases, so it's safe to use as the default
+ *
+ * Everything else is inferred from the actual TypeScript type at the path
  */
-type FieldComponentType<T, P extends Path<T>, FieldType extends string = 'string'> = FieldType extends 'enum' ? EnumFieldComponent<T, P> : P extends keyof T ? UnwrapOptional<T[P]> extends Array<any> | ReadonlyArray<any> ? ArrayFieldComponent<T, P> : UnwrapOptional<T[P]> extends number ? NumberFieldComponent<T> : UnwrapOptional<T[P]> extends boolean ? CheckboxFieldComponent<T> : UnwrapOptional<T[P]> extends Date ? DateFieldComponent<T> : UnwrapOptional<T[P]> extends string ? SelectFieldComponent<T, P> : GenericFieldComponent : GenericFieldComponent;
+type FieldComponentType<T, P extends Path<T>, FieldType extends string = 'string'> = FieldType extends 'enum' ? EnumFieldComponent<T, P> : FieldType extends 'combobox' ? ComboboxFieldComponent<T, P> : P extends keyof T ? UnwrapOptional<T[P]> extends Array<any> | ReadonlyArray<any> ? ArrayFieldComponent<T, P> : UnwrapOptional<T[P]> extends number ? NumberFieldComponent<T> : UnwrapOptional<T[P]> extends boolean ? CheckboxFieldComponent<T> : UnwrapOptional<T[P]> extends Date ? DateFieldComponent<T> : UnwrapOptional<T[P]> extends string ? ComboboxFieldComponent<T, P> : GenericFieldComponent : GenericFieldComponent;
 /**
  * Type for the components object with PascalCase keys derived from field paths
  * Each component gets the right type based on what the field actually is
@@ -580,152 +731,6 @@ type MetadataRegistry = Record<string, SchemaFieldMetadata>;
  */
 type PathsOf<T extends z.ZodTypeAny> = Path<z.infer<T>>;
 
-/**
- * Props for the ComboboxField component
- * @template FormType - The form type
- * @template P - The field path in the form
- * @template TData - The type of the data property in SelectOption (for cascading dropdowns)
- */
-interface ComboboxFieldProps<FormType, P extends Path<FormType> = Path<FormType>, TData = any> {
-    /**
-     * Field name (path in the form state)
-     * Accepts both static paths and dynamic paths for use in array fields
-     */
-    name: FlexiblePath<FormType>;
-    /**
-     * Field label
-     */
-    label?: string;
-    /**
-     * Whether to hide the label
-     */
-    hideLabel?: boolean;
-    /**
-     * Field description
-     */
-    description?: string;
-    /**
-     * Whether the field is required
-     */
-    required?: boolean;
-    /**
-     * Placeholder text
-     */
-    placeholder?: string;
-    /**
-     * Whether the field is disabled
-     */
-    disabled?: boolean;
-    /**
-     * Whether the field is readonly
-     */
-    readonly?: boolean;
-    /**
-     * CSS classes to apply to the field
-     */
-    class?: string | string[];
-    /**
-     * Field size
-     */
-    size?: string;
-    /**
-     * Field variant
-     */
-    variant?: string;
-    /**
-     * Combobox options (overrides options from schema)
-     * Using selectOptions instead of options to avoid conflicts with HTML select element
-     *
-     * For async loading, use form-level dataLoaders and pass options via extraData:
-     * ```ts
-     * useForm(schema, {
-     *   dataLoaders: { products: loadProducts },
-     * });
-     * // Then: :selectOptions="form.extraData.products || []"
-     * ```
-     *
-     * @example
-     * // With typed data
-     * interface CityData { country: string; }
-     * const options: SelectOption<CityData>[] = [
-     *   { value: 'nyc', label: 'New York', data: { country: 'usa' } }
-     * ];
-     */
-    selectOptions?: SelectOption<TData>[];
-    /**
-     * Custom mapping function to convert values to labels
-     * This is useful when you want to customize how labels are displayed
-     * without providing a full options array
-     *
-     * Can be provided as either:
-     * 1. A function that takes a value and returns a label
-     * 2. An object map where keys are enum values and values are labels
-     */
-    valueToLabel?: ValueToLabelMapping<FieldPathToEnum$1<FormType, P>>;
-    /**
-     * Whether to use options from the schema (default: true)
-     * Set to false to ignore schema options even when no options prop is provided
-     */
-    useSchemaOptions?: boolean;
-    /**
-     * Field path that this field depends on for cascading dropdowns
-     * When the parent field changes, this field's options will be filtered
-     * and the field will be reset (unless autoReset is false)
-     *
-     * @example
-     * // City field depends on country field
-     * <ComboboxField name="city" dependsOn="country" :optionFilterFn="filterCitiesByCountry" />
-     */
-    dependsOn?: FlexiblePath<FormType>;
-    /**
-     * Function to filter options based on the parent field's value
-     * Receives the parent field value and all available options
-     * Should return the filtered options array
-     *
-     * The function signature is tied to the TData type parameter, ensuring type safety
-     * between selectOptions and optionFilterFn
-     *
-     * @example
-     * // With typed data - both props must use the same data type
-     * interface CityData { country: string; }
-     * const filterCitiesByCountry = (
-     *   countryValue: string,
-     *   allOptions: SelectOption<CityData>[]
-     * ): SelectOption<CityData>[] => {
-     *   return allOptions.filter(opt => opt.data?.country === countryValue);
-     * };
-     */
-    optionFilterFn?: (parentValue: any, allOptions: SelectOption<TData>[]) => SelectOption<TData>[];
-    /**
-     * Whether to automatically reset this field when the parent field changes (default: true)
-     * Set to false if you want to preserve the value when parent changes
-     */
-    autoReset?: boolean;
-    /**
-     * Whether to allow creating new values that don't exist in the options
-     * Default: true
-     *
-     * Note: This is specific to ComboboxField and not available in SelectField
-     */
-    allowCreate?: boolean;
-    /**
-     * Custom filter function for filtering options as user types
-     * Default: filters by case-insensitive substring match
-     *
-     * Note: This is specific to ComboboxField and not available in SelectField
-     * This is different from optionFilterFn which filters based on parent field values
-     */
-    filterFn?: (query: string, option: SelectOption<TData>) => boolean;
-}
-/**
- * Array of prop names for ComboboxField component.
- * This is derived from ComboboxFieldProps interface and ensures type safety.
- * Used for prop normalization and filtering in component implementations.
- *
- * TypeScript ensures all entries are valid keys of ComboboxFieldProps.
- */
-declare const COMBOBOX_FIELD_PROP_NAMES: readonly ["name", "selectOptions", "placeholder", "disabled", "readonly", "class", "label", "hideLabel", "description", "required", "size", "variant", "valueToLabel", "useSchemaOptions", "dependsOn", "optionFilterFn", "autoReset", "allowCreate", "filterFn"];
-
 interface CurrencyFieldProps<FormType> {
     name: FlexiblePath<FormType>;
     label?: string;
@@ -1274,6 +1279,118 @@ interface StyleCreators {
     }, {}>;
 }
 
+/**
+ * Form state management hook
+ * Provides reactive form state with proper reactivity handling
+ */
+
+/**
+ * Form state interface
+ */
+interface FormState<T, CalcType = any, ExtraDataType = any> {
+    data: T;
+    calculatedValues: CalcType;
+    touched: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+    errors: Record<string, string>;
+    focused: Record<string, boolean>;
+    displayText: Record<string, string>;
+    selectedIndex: Record<string, number>;
+    collapsedFields: Record<string, {
+        isFieldCollapsed: boolean;
+        collapsedItems: number[];
+        defaultCollapsedInitialized: boolean;
+    }>;
+    undoHistory: Record<string, {
+        type: 'add' | 'remove' | 'swap';
+        previousState: any;
+        currentState: any;
+        timestamp: number;
+    }[]>;
+    redoHistory: Record<string, {
+        type: 'add' | 'remove' | 'swap';
+        previousState: any;
+        currentState: any;
+        timestamp: number;
+    }[]>;
+    pendingOperations: Record<string, {
+        type: 'add' | 'remove' | 'swap';
+        index?: number;
+        indexA?: number;
+        indexB?: number;
+        item?: any;
+        previousState: any;
+        currentState: any;
+        timestamp: number;
+        timeoutId?: number;
+    }[]>;
+    arrayItemIds: Record<string, string[]>;
+    isSubmitting: boolean;
+    hasAttemptedSubmit: boolean;
+    submitAttemptsCount: number;
+    submitError: string | null;
+    isReady: boolean;
+    isLoading: boolean;
+    loadError: string | null;
+    extraData: ExtraDataType;
+    fetchedOptions: Record<string, any[]>;
+    loadingOptions: Record<string, boolean>;
+    asyncCascadingParents: Record<string, string>;
+    loadingAutoPopulate: Record<string, boolean>;
+    populatingFields: Record<string, boolean>;
+}
+
+/**
+ * Type definitions for async cascading selection and auto-population
+ */
+
+/**
+ * Helper type to get the value type of a field path
+ */
+type FieldValue<FormType, P extends Path<FormType>> = P extends keyof FormType ? FormType[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof FormType ? FormType[K] extends Record<string, any> ? FieldValue<FormType[K], Rest & Path<FormType[K]>> : never : never : never;
+/**
+ * Configuration for async cascading selection (parent → child options fetching via API)
+ */
+interface AsyncCascadingSelectConfig<FormType, ParentField extends Path<FormType> = Path<FormType>, ChildField extends Path<FormType> = Path<FormType>> {
+    /** Parent field that triggers child options fetch */
+    parentField: ParentField;
+    /** Child field that will be populated with fetched options */
+    childField: ChildField;
+    /** Async function to fetch child options based on parent value */
+    fetchOptionsFn: (parentValue: FieldValue<FormType, ParentField>) => Promise<Array<SelectOption>>;
+    /** Whether to clear child field when parent changes (default: true) */
+    clearOnParentChange?: boolean;
+}
+/**
+ * Type for the async cascading selects configuration object
+ * Uses a mapped type to preserve field path type safety
+ */
+type AsyncCascadingSelectsConfig<FormType> = {
+    [K in string]: AsyncCascadingSelectConfig<FormType, Path<FormType>, Path<FormType>>;
+};
+/**
+ * Configuration for auto-population (select/combobox → other fields)
+ */
+interface AutoPopulateConfig<FormType, TData = any, SourceField extends Path<FormType> = Path<FormType>> {
+    /**
+     * Optional async function to fetch data when option is selected.
+     * If provided, this will be called instead of using option.data.
+     * Receives the selected option value and returns the data object.
+     */
+    fetchDataFn?: (selectedValue: FieldValue<FormType, SourceField>) => Promise<TData>;
+    /** Mapping of form fields to data properties for auto-population */
+    fields: {
+        [TargetField in Path<FormType>]?: string | ((data: TData) => FieldValue<FormType, TargetField>);
+    };
+}
+/**
+ * Type for the auto-populate configuration object
+ * Key is the select/combobox field name, value is the auto-populate config
+ */
+type AutoPopulateConfigs<FormType> = Partial<{
+    [SourceField in Path<FormType>]: AutoPopulateConfig<FormType, any>;
+}>;
+
 /**
  * Options for merging server data with local changes
  */
@@ -1337,6 +1454,8 @@ declare function useForm<T extends z.ZodObject<any>, CalcType = (values: z.infer
         [K in keyof ExtraDataType]?: () => Promise<ExtraDataType[K]>;
     };
     fetchData?: () => Promise<z.infer<typeof schema>>;
+    asyncCascadingSelects?: AsyncCascadingSelectsConfig<z.infer<T>>;
+    autoPopulate?: AutoPopulateConfigs<z.infer<T>>;
     calculationFn?: (values: z.infer<T>, extraData?: ExtraDataType) => CalcType;
     debug?: {
         all?: boolean;
@@ -1350,6 +1469,7 @@ declare function useForm<T extends z.ZodObject<any>, CalcType = (values: z.infer
     form: {
         storeName: string;
         values: z.TypeOf<T>;
+        state: FormState<z.TypeOf<T>, CalcType, ExtraDataType>;
         readonly calculatedValues: CalcType;
         readonly extraData: ExtraDataType;
         readonly isValid: boolean;
@@ -2051,6 +2171,9 @@ declare function useDataTable<TSchema extends z.ZodObject<any>>(schema: TSchema,
             sortDrawerOpen: vue.Ref<boolean, boolean>;
             openSortDrawer: () => boolean;
             closeSortDrawer: () => boolean;
+            filterDrawerOpen: vue.Ref<boolean, boolean>;
+            openFilterDrawer: () => boolean;
+            closeFilterDrawer: () => boolean;
         };
         fieldsMetadata: Record<string, FieldMetadata>;
         columns: (z.TypeOf<TSchema> extends infer T ? { [K in keyof T]?: ColumnDefinition<z.TypeOf<TSchema>, K> | undefined; } : never) & {
@@ -2216,6 +2339,9 @@ declare function useCursorDataTable<TSchema extends z.ZodObject<any>>(schema: TS
             sortDrawerOpen: vue.Ref<boolean, boolean>;
             openSortDrawer: () => boolean;
             closeSortDrawer: () => boolean;
+            filterDrawerOpen: vue.Ref<boolean, boolean>;
+            openFilterDrawer: () => boolean;
+            closeFilterDrawer: () => boolean;
         };
         fieldsMetadata: Record<string, FieldMetadata>;
         columns: (z.TypeOf<TSchema> extends infer T ? { [K in keyof T]?: ColumnDefinition<z.TypeOf<TSchema>, K> | undefined; } : never) & {