@dragonmastery/zinia-forms-core 0.3.11 → 0.3.12

package/dist/index.d.ts

@@ -580,17 +580,13 @@ type MetadataRegistry = Record<string, SchemaFieldMetadata>;
  */
 type PathsOf<T extends z.ZodTypeAny> = Path<z.infer<T>>;
 
-/**
- * Option item for combobox fields - can be a string or label/value object
- */
-type ComboboxOption = string | {
-    label: string;
-    value: string;
-};
 /**
  * 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>> {
+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
@@ -637,28 +633,89 @@ interface ComboboxFieldProps<FormType, P extends Path<FormType> = Path<FormType>
      */
     variant?: string;
     /**
-     * Combobox options (array of strings or label/value objects)
-     * If not provided, will use options from schema metadata
+     * 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: :options="form.extraData.products || []"
+     * // 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
      */
-    options?: ComboboxOption[];
+    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 options
+     * 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: ComboboxOption) => boolean;
+    filterFn?: (query: string, option: SelectOption<TData>) => boolean;
 }
 /**
  * Array of prop names for ComboboxField component.
@@ -667,7 +724,7 @@ interface ComboboxFieldProps<FormType, P extends Path<FormType> = Path<FormType>
  *
  * TypeScript ensures all entries are valid keys of ComboboxFieldProps.
  */
-declare const COMBOBOX_FIELD_PROP_NAMES: readonly ["name", "options", "placeholder", "disabled", "readonly", "class", "label", "hideLabel", "description", "required", "size", "variant", "allowCreate", "filterFn"];
+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>;
@@ -1389,7 +1446,7 @@ declare function useForm<T extends z.ZodObject<any>, CalcType = (values: z.infer
         UrlField: vue.FunctionalComponent<UrlFieldProps<z.TypeOf<T>>, {}, any, {}>;
         TelField: vue.FunctionalComponent<TelFieldProps<z.TypeOf<T>>, {}, any, {}>;
         SearchField: vue.FunctionalComponent<SearchFieldProps<z.TypeOf<T>>, {}, any, {}>;
-        ComboboxField: vue.FunctionalComponent<ComboboxFieldProps<z.TypeOf<T>, Path<z.TypeOf<T>>>, {}, any, {}>;
+        ComboboxField: vue.FunctionalComponent<ComboboxFieldProps<z.TypeOf<T>, Path<z.TypeOf<T>>, any>, {}, any, {}>;
         ArrayField: vue.FunctionalComponent<ArrayFieldProps<z.TypeOf<T>, any>, {}, {
             itemRenderer: (props: {
                 item: any;
@@ -1485,28 +1542,15 @@ declare function createBaseComponents<T extends z.ZodObject<any>>(schema: T, sty
 };
 
 /**
- * Functions for creating type-safe select fields
- */
-
-/**
- * Create a factory function that returns a properly typed SelectField based on the field path
+ * Create base display components using registered styles
  *
- * @param baseSelectField The base select field component
- * @param fieldPath The field path to create a select field for
- * @returns A factory function that creates a type-safe select field
- */
-declare function createTypedSelectField<T, P extends Path<T>>(baseSelectField: FunctionalComponent<SelectFieldProps<T>>, fieldPath: P): <E extends FieldPathToEnum<T, P> = FieldPathToEnum<T, P>>(props: Omit<SelectFieldProps<T>, "name" | "valueToLabel"> & {
-    valueToLabel: Record<E, string>;
-}, context?: any) => any;
-/**
- * Type-safe select field component with valueToLabel based on field path
+ * @param schema The Zod schema for the data
+ * @param styleName The style to use for rendering
+ * @returns Base display components
  */
-interface TypedSelectFieldComponent<T> {
-    <P extends Path<T>>(props: Omit<SelectFieldProps<T>, 'valueToLabel'> & {
-        name: P;
-        valueToLabel?: Record<string, string>;
-    }): ReturnType<FunctionalComponent>;
-}
+declare function createBaseDisplayComponents<T extends z.ZodObject<any>>(schema: T, styleName?: RegisteredStyleName): {
+    ZiniaDisplay: vue.FunctionalComponent<DisplayProps<z.TypeOf<T>>, {}, any, {}>;
+};
 
 interface ArrayFieldSlots<ItemType> {
     itemRenderer: (props: {
@@ -1544,6 +1588,89 @@ interface ArrayFieldSlots<ItemType> {
  */
 declare function createTypedArrayField<T, P extends Path<T>>(baseArrayField: FunctionalComponent<ArrayFieldProps<T, any>, {}, any, {}>, fieldPath: P, metadata?: FieldMetadata): FunctionalComponent<Omit<ArrayFieldProps<T, ArrayItemType<T, P>>, "name">, {}, ArrayFieldSlots<ArrayItemType<T, P>>, {}>;
 
+/**
+ * Functions for creating type-safe combobox fields
+ */
+
+/**
+ * Create a factory function that returns a properly typed ComboboxField based on the field path
+ *
+ * @param baseComboboxField The base combobox field component
+ * @param fieldPath The field path to create a combobox field for
+ * @returns A factory function that creates a type-safe combobox field
+ *
+ * This preserves path-specific typing for features like dependsOn (cascading dropdowns)
+ * and ensures type safety between selectOptions and optionFilterFn
+ */
+declare function createTypedComboboxField<T, P extends Path<T>>(baseComboboxField: FunctionalComponent<ComboboxFieldProps<T>>, fieldPath: P): <TData = any>(props: Omit<ComboboxFieldProps<T, P, TData>, "name">, context?: any) => any;
+
+/**
+ * Functions for creating type-safe select fields
+ */
+
+/**
+ * Create a factory function that returns a properly typed SelectField based on the field path
+ *
+ * @param baseSelectField The base select field component
+ * @param fieldPath The field path to create a select field for
+ * @returns A factory function that creates a type-safe select field
+ */
+declare function createTypedSelectField<T, P extends Path<T>>(baseSelectField: FunctionalComponent<SelectFieldProps<T>>, fieldPath: P): <E extends FieldPathToEnum<T, P> = FieldPathToEnum<T, P>>(props: Omit<SelectFieldProps<T>, "name" | "valueToLabel"> & {
+    valueToLabel: Record<E, string>;
+}, context?: any) => any;
+/**
+ * Type-safe select field component with valueToLabel based on field path
+ */
+interface TypedSelectFieldComponent<T> {
+    <P extends Path<T>>(props: Omit<SelectFieldProps<T>, 'valueToLabel'> & {
+        name: P;
+        valueToLabel?: Record<string, string>;
+    }): ReturnType<FunctionalComponent>;
+}
+
+/**
+ * Type for display field components
+ */
+type DisplayFieldComponent<T, P extends Path<T>, _FieldType extends string = 'string'> = (props: {
+    name?: P;
+    label?: string;
+    hideLabel?: boolean;
+    description?: string;
+    format?: 'default' | 'currency' | 'date' | 'datetime' | 'boolean' | 'email' | 'url' | 'phone' | 'number';
+    emptyText?: string;
+    class?: string | string[];
+    size?: string;
+    variant?: string;
+    copyable?: boolean;
+    valueToLabel?: Record<string, string>;
+    separator?: string;
+    itemRenderer?: (item: any, index: number) => string;
+    maxItems?: number;
+}, context?: any) => any;
+/**
+ * Type for the display components object with PascalCase keys derived from field paths
+ * This mirrors the ComponentsType from the form system but with Display suffix
+ */
+type DisplayComponentsType<T> = {
+    [K in Path<T> as `${PathToPascalCase<K & string>}` extends `${infer Base}Field` ? `${Base}Display` : `${PathToPascalCase<K & string>}Display`]: DisplayFieldComponent<T, K>;
+};
+/**
+ * Generate display field components for a schema based on metadata
+ *
+ * @param schema The Zod schema for the data
+ * @param fieldsMetadata Metadata for fields
+ * @param renderStyle The style to use for rendering
+ * @returns Generated display field components
+ */
+declare function generateDisplayComponents<T extends z.ZodObject<any>>(schema: T, fieldsMetadata: Record<string, FieldMetadata>, styleName?: RegisteredStyleName): {
+    generic: {
+        DisplayField: vue.FunctionalComponent<DisplayFieldProps<z.TypeOf<T>>, {}, any, {}>;
+        fields: { [K in Path<z.TypeOf<T>>]: DisplayFieldComponent<z.TypeOf<T>, K, string>; };
+        field: <P extends Path<z.TypeOf<T>>>(path: P) => any;
+    };
+    typed: DisplayComponentsType<z.TypeOf<T>>;
+};
+
 /**
  * Generate field components for a schema based on metadata
  *
@@ -1570,7 +1697,7 @@ declare function generateFieldComponents<T extends z.ZodObject<any>>(schema: T,
         UrlField: vue.FunctionalComponent<UrlFieldProps<z.TypeOf<T>>, {}, any, {}>;
         TelField: vue.FunctionalComponent<TelFieldProps<z.TypeOf<T>>, {}, any, {}>;
         SearchField: vue.FunctionalComponent<SearchFieldProps<z.TypeOf<T>>, {}, any, {}>;
-        ComboboxField: vue.FunctionalComponent<ComboboxFieldProps<z.TypeOf<T>, Path<z.TypeOf<T>>>, {}, any, {}>;
+        ComboboxField: vue.FunctionalComponent<ComboboxFieldProps<z.TypeOf<T>, Path<z.TypeOf<T>>, any>, {}, any, {}>;
         ArrayField: vue.FunctionalComponent<ArrayFieldProps<z.TypeOf<T>, any>, {}, {
             itemRenderer: (props: {
                 item: any;
@@ -1642,60 +1769,6 @@ declare function generateFieldComponents<T extends z.ZodObject<any>>(schema: T,
     typed: ComponentsType<z.TypeOf<T>>;
 };
 
-/**
- * Create base display components using registered styles
- *
- * @param schema The Zod schema for the data
- * @param styleName The style to use for rendering
- * @returns Base display components
- */
-declare function createBaseDisplayComponents<T extends z.ZodObject<any>>(schema: T, styleName?: RegisteredStyleName): {
-    ZiniaDisplay: vue.FunctionalComponent<DisplayProps<z.TypeOf<T>>, {}, any, {}>;
-};
-
-/**
- * Type for display field components
- */
-type DisplayFieldComponent<T, P extends Path<T>, _FieldType extends string = 'string'> = (props: {
-    name?: P;
-    label?: string;
-    hideLabel?: boolean;
-    description?: string;
-    format?: 'default' | 'currency' | 'date' | 'datetime' | 'boolean' | 'email' | 'url' | 'phone' | 'number';
-    emptyText?: string;
-    class?: string | string[];
-    size?: string;
-    variant?: string;
-    copyable?: boolean;
-    valueToLabel?: Record<string, string>;
-    separator?: string;
-    itemRenderer?: (item: any, index: number) => string;
-    maxItems?: number;
-}, context?: any) => any;
-/**
- * Type for the display components object with PascalCase keys derived from field paths
- * This mirrors the ComponentsType from the form system but with Display suffix
- */
-type DisplayComponentsType<T> = {
-    [K in Path<T> as `${PathToPascalCase<K & string>}` extends `${infer Base}Field` ? `${Base}Display` : `${PathToPascalCase<K & string>}Display`]: DisplayFieldComponent<T, K>;
-};
-/**
- * Generate display field components for a schema based on metadata
- *
- * @param schema The Zod schema for the data
- * @param fieldsMetadata Metadata for fields
- * @param renderStyle The style to use for rendering
- * @returns Generated display field components
- */
-declare function generateDisplayComponents<T extends z.ZodObject<any>>(schema: T, fieldsMetadata: Record<string, FieldMetadata>, styleName?: RegisteredStyleName): {
-    generic: {
-        DisplayField: vue.FunctionalComponent<DisplayFieldProps<z.TypeOf<T>>, {}, any, {}>;
-        fields: { [K in Path<z.TypeOf<T>>]: DisplayFieldComponent<z.TypeOf<T>, K, string>; };
-        field: <P extends Path<z.TypeOf<T>>>(path: P) => any;
-    };
-    typed: DisplayComponentsType<z.TypeOf<T>>;
-};
-
 interface NoDataDisplayProps {
     message?: string;
     class?: string;
@@ -2478,4 +2551,4 @@ declare const DEBUG_CONFIG: {
  */
 declare function isDebugEnabled(area: keyof Omit<typeof DEBUG_CONFIG, 'all'>): boolean;
 
-export { ActionIcons, type ActionItem, type ActionsConfig, type ArrayFieldProps, type ArrayFieldSlots, type ButtonActionItem, COMBOBOX_FIELD_PROP_NAMES, type CheckboxFieldProps, type ColumnDefinition, type ComboboxFieldProps, type ComboboxOption, type CurrencyFieldProps, type CursorDataTableOptions, type CursorFetchParams, type CursorFetchResult, DEBUG_CONFIG, type DataTableColumns, type DataTableOptions, type DataTableProps, type DateFieldProps, type DateTimeLocalFieldProps, type DeleteModalProps, type DisplayComponentsType, type DisplayFieldComponent, type DisplayFieldProps, type DisplayProps, type EmailFieldProps, type EnumValueToLabelMap, type EnumValuesFromField, ErrorDisplay, type FetchDataParams, type FetchDataResult, type FieldPathToEnum$1 as FieldPathToEnum, type FieldType, type FileFieldProps, type FilterOptionItem, type FilterValue, type FormErrorsSummaryProps, type FormProps, type LinkActionItem, LoadingDisplay, NoDataDisplay, type NumberFieldProps, type PasswordFieldProps, type RadioFieldProps, type RangeFieldProps, type ResetButtonProps, SCHEMA_ID_SYMBOL, SELECT_FIELD_PROP_NAMES, type SearchFieldProps, type SelectFieldProps, type SelectOption, type SubmitButtonProps, type TelFieldProps, type TextFieldProps, type TextareaFieldProps, type TimeFieldProps, type ToppingsFieldProps, type TransferListFieldProps, type TypedSelectFieldComponent, type UrlFieldProps, type UseCursorDataTableType, type UseDataTableType, type UseDeleteModalType, type UseDisplayType, type UseFormType, type UseFormTyped, type ValueToLabelMapping, ZINIA_DATA_TABLE_ACTIONS_KEY, ZINIA_DATA_TABLE_COLUMNS_KEY, ZINIA_DATA_TABLE_FILTER_INPUTS_KEY, ZINIA_DATA_TABLE_FILTER_OPERATORS_KEY, ZINIA_DATA_TABLE_FILTER_OPTIONS_LOADING_KEY, ZINIA_DATA_TABLE_FILTER_OPTIONS_STATE_KEY, ZINIA_DATA_TABLE_KEY, ZINIA_DATA_TABLE_NAME_KEY, ZINIA_DATA_TABLE_OPTIONS_KEY, ZINIA_DATA_TABLE_SEARCH_INPUT_KEY, ZINIA_DELETE_MODAL_FIELDS_GENERIC_KEY, ZINIA_DELETE_MODAL_FIELDS_KEY, ZINIA_DELETE_MODAL_KEY, ZINIA_DELETE_MODAL_SCHEMA_KEY, ZINIA_DISPLAY_FIELDS_GENERIC_KEY, ZINIA_DISPLAY_FIELDS_KEY, ZINIA_DISPLAY_KEY, ZINIA_DISPLAY_SCHEMA_KEY, ZINIA_FIELDS_GENERIC_KEY, ZINIA_FIELDS_KEY, ZINIA_FORM_KEY, ZINIA_FORM_SCHEMA_KEY, type ZiniaDataTable, type ZiniaDeleteModal, type ZiniaDeleteModalFields, type ZiniaDeleteModalGenericFields, type ZiniaDisplay, type ZiniaDisplayFields, type ZiniaDisplayGenericFields, type ZiniaForm, type ZiniaFormFields, type ZiniaFormGenericFields, ZiniaPlugin, type ZiniaPluginOptions, type ZodEnumValues, clearAllMetadata, clearSchemaMetadata, createBaseComponents, createBaseDisplayComponents, createPartialStyle, createStyleTemplate, createTypedArrayField, createTypedSelectField, daisyUIStyle, extendStyle, generateDisplayComponents, generateFieldComponents, getAllSchemaMetadata, getDefaultStyle, getFieldMetadata, getRegisteredStyle, getRegisteredStyleNames, getSchemaId, hasRegisteredStyle, hasSchemaMetadata, isDebugEnabled, mergeStyles, plainStyle, registerSchemaMetadata, registerStyle, setSchemaMetadata, useCursorDataTable, useDataTable, useDeleteModal, useDisplay, useForm, withMetadata };
+export { ActionIcons, type ActionItem, type ActionsConfig, type ArrayFieldProps, type ArrayFieldSlots, type ButtonActionItem, COMBOBOX_FIELD_PROP_NAMES, type CheckboxFieldProps, type ColumnDefinition, type ComboboxFieldProps, type CurrencyFieldProps, type CursorDataTableOptions, type CursorFetchParams, type CursorFetchResult, DEBUG_CONFIG, type DataTableColumns, type DataTableOptions, type DataTableProps, type DateFieldProps, type DateTimeLocalFieldProps, type DeleteModalProps, type DisplayComponentsType, type DisplayFieldComponent, type DisplayFieldProps, type DisplayProps, type EmailFieldProps, type EnumValueToLabelMap, type EnumValuesFromField, ErrorDisplay, type FetchDataParams, type FetchDataResult, type FieldPathToEnum$1 as FieldPathToEnum, type FieldType, type FileFieldProps, type FilterOptionItem, type FilterValue, type FormErrorsSummaryProps, type FormProps, type LinkActionItem, LoadingDisplay, NoDataDisplay, type NumberFieldProps, type PasswordFieldProps, type RadioFieldProps, type RangeFieldProps, type ResetButtonProps, SCHEMA_ID_SYMBOL, SELECT_FIELD_PROP_NAMES, type SearchFieldProps, type SelectFieldProps, type SelectOption, type SubmitButtonProps, type TelFieldProps, type TextFieldProps, type TextareaFieldProps, type TimeFieldProps, type ToppingsFieldProps, type TransferListFieldProps, type TypedSelectFieldComponent, type UrlFieldProps, type UseCursorDataTableType, type UseDataTableType, type UseDeleteModalType, type UseDisplayType, type UseFormType, type UseFormTyped, type ValueToLabelMapping, ZINIA_DATA_TABLE_ACTIONS_KEY, ZINIA_DATA_TABLE_COLUMNS_KEY, ZINIA_DATA_TABLE_FILTER_INPUTS_KEY, ZINIA_DATA_TABLE_FILTER_OPERATORS_KEY, ZINIA_DATA_TABLE_FILTER_OPTIONS_LOADING_KEY, ZINIA_DATA_TABLE_FILTER_OPTIONS_STATE_KEY, ZINIA_DATA_TABLE_KEY, ZINIA_DATA_TABLE_NAME_KEY, ZINIA_DATA_TABLE_OPTIONS_KEY, ZINIA_DATA_TABLE_SEARCH_INPUT_KEY, ZINIA_DELETE_MODAL_FIELDS_GENERIC_KEY, ZINIA_DELETE_MODAL_FIELDS_KEY, ZINIA_DELETE_MODAL_KEY, ZINIA_DELETE_MODAL_SCHEMA_KEY, ZINIA_DISPLAY_FIELDS_GENERIC_KEY, ZINIA_DISPLAY_FIELDS_KEY, ZINIA_DISPLAY_KEY, ZINIA_DISPLAY_SCHEMA_KEY, ZINIA_FIELDS_GENERIC_KEY, ZINIA_FIELDS_KEY, ZINIA_FORM_KEY, ZINIA_FORM_SCHEMA_KEY, type ZiniaDataTable, type ZiniaDeleteModal, type ZiniaDeleteModalFields, type ZiniaDeleteModalGenericFields, type ZiniaDisplay, type ZiniaDisplayFields, type ZiniaDisplayGenericFields, type ZiniaForm, type ZiniaFormFields, type ZiniaFormGenericFields, ZiniaPlugin, type ZiniaPluginOptions, type ZodEnumValues, clearAllMetadata, clearSchemaMetadata, createBaseComponents, createBaseDisplayComponents, createPartialStyle, createStyleTemplate, createTypedArrayField, createTypedComboboxField, createTypedSelectField, daisyUIStyle, extendStyle, generateDisplayComponents, generateFieldComponents, getAllSchemaMetadata, getDefaultStyle, getFieldMetadata, getRegisteredStyle, getRegisteredStyleNames, getSchemaId, hasRegisteredStyle, hasSchemaMetadata, isDebugEnabled, mergeStyles, plainStyle, registerSchemaMetadata, registerStyle, setSchemaMetadata, useCursorDataTable, useDataTable, useDeleteModal, useDisplay, useForm, withMetadata };