@buildnbuzz/buzzform 0.1.6 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/{adapter-CpEUN0gt.d.mts → adapter-Bd0fYuAE.d.mts} +56 -5
- package/dist/{adapter-CpEUN0gt.d.ts → adapter-Bd0fYuAE.d.ts} +56 -5
- package/dist/{chunk-VXG7KGOZ.mjs → chunk-P5XPEIIF.mjs} +37 -2
- package/dist/chunk-P5XPEIIF.mjs.map +1 -0
- package/dist/index.d.mts +13 -4
- package/dist/index.d.ts +13 -4
- package/dist/index.js +62 -5
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +30 -7
- package/dist/index.mjs.map +1 -1
- package/dist/rhf.d.mts +1 -1
- package/dist/rhf.d.ts +1 -1
- package/dist/rhf.mjs +1 -1
- package/dist/schema.d.mts +3 -3
- package/dist/schema.d.ts +3 -3
- package/dist/schema.mjs +1 -1
- package/dist/{utils-DTtDPnVV.d.mts → utils-BsX0viz8.d.mts} +1 -1
- package/dist/{utils-YM0cIt68.d.ts → utils-DHF346op.d.ts} +1 -1
- package/dist/zod.d.mts +1 -1
- package/dist/zod.d.ts +1 -1
- package/package.json +1 -1
- package/dist/chunk-VXG7KGOZ.mjs.map +0 -1
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/types/adapter.ts","../src/context/form-context.ts","../src/providers/form-provider.tsx","../src/hooks/use-form.ts"],"sourcesContent":["import type { FormEvent } from 'react';\nimport type { FormSettings } from './form';\n\n// =============================================================================\n// FORM STATE\n// =============================================================================\n\n/**\n * Represents the current reactive state of a form.\n * Adapters must ensure this triggers re-renders when values change.\n * \n * This is the MINIMUM state required for BuzzForm to work.\n * Custom adapters must provide all these properties.\n */\nexport interface FormState {\n /** True while the form is being submitted */\n isSubmitting: boolean;\n\n /** True while validation is running (async validators) */\n isValidating: boolean;\n\n /** True if any field has been modified from its default value */\n isDirty: boolean;\n\n /** True if all validations pass (no errors) */\n isValid: boolean;\n\n /** True while async default values are being resolved */\n isLoading: boolean;\n\n /** \n * Field-level errors.\n * Key is the field path (e.g., \"email\", \"address.city\", \"items.0.name\")\n * Value is the error message(s)\n * \n * NOTE: Path format uses dot notation. Array indices use numbers (items.0.name).\n */\n errors: Record<string, string | string[] | undefined>;\n\n /** Map of field paths to whether they've been modified */\n dirtyFields: Record<string, boolean>;\n\n /** Map of field paths to whether they've been touched (blurred) */\n touchedFields: Record<string, boolean>;\n\n /** Number of times the form has been submitted */\n submitCount: number;\n}\n\n// =============================================================================\n// VALUE MANAGEMENT\n// =============================================================================\n\n/**\n * Options when programmatically setting a field value.\n */\nexport interface SetValueOptions {\n /** Run validation after setting the value (default: adapter-specific) */\n shouldValidate?: boolean;\n\n /** Mark the field as dirty (default: true) */\n shouldDirty?: boolean;\n\n /** Mark the field as touched (default: false) */\n shouldTouch?: boolean;\n}\n\n// =============================================================================\n// VALIDATION\n// =============================================================================\n\n/**\n * Represents a field-level error.\n */\nexport interface FieldError {\n /** Error type (e.g., 'required', 'pattern', 'server', 'custom') */\n type?: string;\n\n /** Human-readable error message */\n message: string;\n}\n\n/**\n * Result from a validation resolver.\n */\nexport interface ResolverResult<TData> {\n /** Parsed/transformed values (if validation passes) */\n values?: TData;\n\n /** Field errors (if validation fails) */\n errors?: Record<string, FieldError>;\n}\n\n/**\n * A validation resolver function.\n * Adapters use this to validate form values against a schema.\n * \n * @example\n * // Zod resolver\n * const zodResolver = (schema) => async (values) => {\n * const result = schema.safeParse(values);\n * if (result.success) return { values: result.data };\n * return { errors: mapZodErrors(result.error) };\n * };\n */\nexport type Resolver<TData> = (\n values: TData\n) => Promise<ResolverResult<TData>> | ResolverResult<TData>;\n\n// =============================================================================\n// ARRAY HELPERS\n// =============================================================================\n\n/**\n * Helper methods for manipulating array fields.\n * All methods operate on a field path (e.g., \"items\", \"users.0.tags\").\n * \n * This is REQUIRED for ArrayField to work. If your custom adapter doesn't\n * support arrays, you can implement these as no-ops or throw errors.\n */\nexport interface ArrayHelpers {\n /**\n * Get array items with stable IDs for React keys.\n * @param path - Field path to the array\n * @returns Array of items, each with an `id` property for React keys\n */\n fields: <T = unknown>(path: string) => Array<T & { id: string }>;\n\n /**\n * Add an item to the end of the array.\n */\n append: (path: string, value: unknown) => void;\n\n /**\n * Add an item to the beginning of the array.\n */\n prepend: (path: string, value: unknown) => void;\n\n /**\n * Insert an item at a specific index.\n */\n insert: (path: string, index: number, value: unknown) => void;\n\n /**\n * Remove an item at a specific index.\n */\n remove: (path: string, index: number) => void;\n\n /**\n * Move an item from one index to another.\n * Used for drag-and-drop reordering.\n */\n move: (path: string, from: number, to: number) => void;\n\n /**\n * Swap two items by their indices.\n */\n swap: (path: string, indexA: number, indexB: number) => void;\n\n /**\n * Replace the entire array with new values.\n */\n replace: (path: string, values: unknown[]) => void;\n\n /**\n * Update an item at a specific index.\n */\n update: (path: string, index: number, value: unknown) => void;\n}\n\n// =============================================================================\n// ADAPTER OPTIONS\n// =============================================================================\n\n/**\n * Base options passed to any adapter when creating a form instance.\n * Adapters can extend this with library-specific options.\n * \n * @typeParam TData - The shape of form data\n */\nexport interface AdapterOptions<TData = Record<string, unknown>> {\n /**\n * Initial values for the form.\n * Can be:\n * - A static object\n * - A sync function returning values\n * - An async function returning values (form shows loading state)\n */\n defaultValues?: TData | (() => TData) | (() => Promise<TData>);\n\n /**\n * Controlled values - when provided, form becomes controlled.\n * Changes to this prop will update form values.\n */\n values?: TData;\n\n /**\n * Validation resolver.\n * Called to validate form values before submission and optionally on change/blur.\n */\n resolver?: Resolver<TData>;\n\n /**\n * When to run validation.\n * - 'onChange': Validate on every value change\n * - 'onBlur': Validate when fields lose focus\n * - 'onSubmit': Validate only on submit\n * - 'all': Validate on all events\n * \n * NOTE: Not all adapters support all modes. Check adapter documentation.\n */\n mode?: 'onChange' | 'onBlur' | 'onSubmit' | 'all';\n\n /**\n * When to re-validate after initial error.\n * NOTE: This is optional. Some form libraries don't have this concept.\n */\n reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit';\n\n /**\n * Callback when form is submitted (after validation passes).\n */\n onSubmit?: (values: TData) => Promise<void> | void;\n}\n\n// =============================================================================\n// FORM ADAPTER INTERFACE\n// =============================================================================\n\n/**\n * The contract any form adapter must fulfill.\n * \n * ## Required vs Optional\n * \n * **Required methods** are the building blocks that BuzzForm needs to function.\n * If any are missing, forms will break.\n * \n * **Optional methods** (marked with `?`) provide enhanced functionality but\n * are not required. BuzzForm will gracefully degrade without them.\n * \n * ## Creating a Custom Adapter\n * \n * To create a custom adapter (e.g., for useActionState, Formik, or vanilla React):\n * \n * 1. Implement all required properties and methods\n * 2. Optionally implement enhanced features\n * 3. Return the adapter from a hook (factory function)\n * \n * @example\n * // Minimal custom adapter skeleton\n * function useMyAdapter<T>(options: AdapterOptions<T>): FormAdapter<T> {\n * const [values, setValues] = useState(options.defaultValues ?? {});\n * const [errors, setErrors] = useState({});\n * const [isSubmitting, setIsSubmitting] = useState(false);\n * \n * return {\n * control: null, // Your state/context\n * get formState() { return { ... } },\n * handleSubmit: async (e) => { ... },\n * getValues: () => values,\n * setValue: (name, value) => { ... },\n * reset: (vals) => setValues(vals ?? {}),\n * watch: (name) => name ? values[name] : values,\n * validate: async () => true,\n * setError: (name, error) => { ... },\n * clearErrors: () => setErrors({}),\n * array: createArrayHelpers(...),\n * };\n * }\n * \n * @typeParam TData - The shape of form data\n */\nexport interface FormAdapter<TData = Record<string, unknown>> {\n // =========================================================================\n // CORE PROPERTIES (Required)\n // =========================================================================\n\n /**\n * Form-level behavior settings.\n * Set by useForm after applying FormSettings.\n */\n settings?: FormSettings;\n\n /**\n * The underlying form library's control/instance.\n * \n * This is passed to field components that need direct access to the form\n * library (e.g., for React Hook Form's Controller).\n * \n * For custom adapters, this can be:\n * - Your state object\n * - A context value\n * - null (if not needed)\n */\n control: unknown;\n\n /**\n * Current form state.\n * MUST be implemented as a getter to ensure reactivity.\n * \n * @example\n * get formState() {\n * return {\n * isSubmitting: this._isSubmitting,\n * isValidating: false,\n * isDirty: Object.keys(this._touched).length > 0,\n * isValid: Object.keys(this._errors).length === 0,\n * isLoading: false,\n * errors: this._errors,\n * dirtyFields: this._dirty,\n * touchedFields: this._touched,\n * submitCount: this._submitCount,\n * };\n * }\n */\n formState: FormState;\n\n /**\n * Submit handler to attach to a form element.\n * Should prevent default, run validation, and call onSubmit if valid.\n * \n * @example\n * <form onSubmit={adapter.handleSubmit}>\n */\n handleSubmit: (e?: FormEvent) => Promise<void> | void;\n\n // =========================================================================\n // VALUE MANAGEMENT (Required)\n // =========================================================================\n\n /**\n * Get all current form values.\n */\n getValues: () => TData;\n\n /**\n * Set a single field's value.\n * \n * @param name - Field path (e.g., \"email\", \"address.city\", \"items.0.name\")\n * @param value - New value\n * @param options - Additional options\n */\n setValue: (\n name: string,\n value: unknown,\n options?: SetValueOptions\n ) => void;\n\n /**\n * Reset form to default values or provided values.\n * \n * @param values - Optional new values to reset to\n */\n reset: (values?: Partial<TData>) => void;\n\n /**\n * Watch one or more field values reactively.\n * Returns current value(s) and causes re-render when they change.\n * \n * @param name - Field path to watch, or undefined for all values\n * @returns Current value(s)\n */\n watch: <T = unknown>(name?: string) => T;\n\n // =========================================================================\n // VALIDATION (Required)\n // =========================================================================\n\n /**\n * Manually trigger validation.\n * \n * @param name - Field(s) to validate, or undefined for entire form\n * @returns True if validation passes\n */\n validate: (name?: string | string[]) => Promise<boolean>;\n\n /**\n * Set a field error programmatically.\n * Useful for server-side validation errors.\n * \n * @param name - Field path\n * @param error - Error details\n */\n setError: (name: string, error: FieldError) => void;\n\n /**\n * Clear validation errors.\n * \n * @param name - Field(s) to clear, or undefined for all errors\n */\n clearErrors: (name?: string | string[]) => void;\n\n // =========================================================================\n // ARRAYS (Required for ArrayField)\n // =========================================================================\n\n /**\n * Helpers for manipulating array fields.\n * Required if you use ArrayField component.\n */\n array: ArrayHelpers;\n\n // =========================================================================\n // OPTIONAL ENHANCED FEATURES\n // These provide better UX but are not required for basic functionality.\n // =========================================================================\n\n /**\n * Handle field blur event.\n * Triggers validation if mode is 'onBlur'.\n * \n * If not provided, BuzzForm will not trigger blur-based validation.\n * \n * @param name - Field path\n */\n onBlur?: (name: string) => void;\n\n /**\n * Get the state of a specific field.\n * More efficient than accessing the entire formState for single fields.\n * \n * @param name - Field path\n */\n getFieldState?: (name: string) => {\n isDirty: boolean;\n isTouched: boolean;\n invalid: boolean;\n error?: string;\n };\n\n /**\n * Programmatically focus a field.\n * Useful for accessibility and after adding array items.\n * \n * @param name - Field path\n * @param options - Focus options\n */\n setFocus?: (name: string, options?: { shouldSelect?: boolean }) => void;\n\n /**\n * Unregister a field from the form.\n * Called when conditional fields are hidden.\n * \n * If not provided, hidden fields will retain their values.\n * \n * @param name - Field path(s) to unregister\n */\n unregister?: (name: string | string[]) => void;\n}\n\n// =============================================================================\n// ADAPTER FACTORY TYPE\n// =============================================================================\n\n/**\n * Type for an adapter factory function (hook).\n * \n * @example\n * // Using the adapter\n * function MyApp() {\n * return (\n * <FormProvider adapter={useRhfAdapter}>\n * <MyForm />\n * </FormProvider>\n * );\n * }\n */\nexport type AdapterFactory<TData = Record<string, unknown>> = (\n options: AdapterOptions<TData>\n) => FormAdapter<TData>;\n\n// =============================================================================\n// VALIDATION HELPERS FOR CUSTOM ADAPTERS\n// =============================================================================\n\n/**\n * Validates that a FormAdapter has all required methods.\n * Call this in development to catch missing implementations early.\n * \n * @param adapter - The adapter to validate\n * @param adapterName - Name for error messages\n * @throws Error if required methods are missing\n */\nexport function validateAdapter(adapter: FormAdapter, adapterName = 'adapter'): void {\n const required = [\n 'control',\n 'formState',\n 'handleSubmit',\n 'getValues',\n 'setValue',\n 'reset',\n 'watch',\n 'validate',\n 'setError',\n 'clearErrors',\n 'array',\n ] as const;\n\n for (const key of required) {\n if (adapter[key] === undefined) {\n throw new Error(\n `Invalid FormAdapter: \"${adapterName}\" is missing required property \"${key}\". ` +\n `See FormAdapter interface for implementation requirements.`\n );\n }\n }\n\n // Validate array helpers\n const arrayMethods = [\n 'fields', 'append', 'prepend', 'insert',\n 'remove', 'move', 'swap', 'replace', 'update'\n ] as const;\n\n for (const method of arrayMethods) {\n if (typeof adapter.array[method] !== 'function') {\n throw new Error(\n `Invalid FormAdapter: \"${adapterName}.array.${method}\" must be a function.`\n );\n }\n }\n}\n","'use client';\n\nimport { createContext } from 'react';\nimport type { FormConfig } from '../types';\n\n/**\n * Context for global form configuration.\n * Set via FormProvider, consumed by useForm.\n */\nexport const FormConfigContext = createContext<FormConfig | null>(null);\n","\"use client\";\n\nimport React from \"react\";\nimport { FormConfigContext } from \"../context/form-context\";\nimport type { FormConfig } from \"../types\";\n\n/**\n * Provider for global form configuration.\n * Set the adapter, resolver, and default mode for all forms in the app.\n *\n * @example\n * import { FormProvider } from '@buildnbuzz/buzzform';\n * import { useRhfAdapter } from '@buildnbuzz/buzzform/rhf';\n * import { zodResolver } from '@buildnbuzz/buzzform/resolvers/zod';\n *\n * <FormProvider\n * adapter={useRhfAdapter}\n * resolver={zodResolver}\n * mode=\"onBlur\"\n * >\n * <App />\n * </FormProvider>\n */\nexport const FormProvider: React.FC<\n FormConfig & { children: React.ReactNode }\n> = ({ children, ...config }) => {\n return (\n <FormConfigContext.Provider value={config}>\n {children}\n </FormConfigContext.Provider>\n );\n};\n","'use client';\n\nimport { useContext, useMemo } from 'react';\nimport { FormConfigContext } from '../context/form-context';\nimport type { UseFormOptions, FormAdapter, AdapterOptions, Field, FormSettings } from '../types';\n\n/**\n * Extract default values from field definitions.\n */\nfunction extractDefaultsFromFields(fields?: Field[]): Record<string, unknown> | undefined {\n if (!fields || fields.length === 0) return undefined;\n\n const defaults: Record<string, unknown> = {};\n let hasDefaults = false;\n\n for (const field of fields) {\n if ('name' in field && 'defaultValue' in field && field.defaultValue !== undefined) {\n defaults[field.name] = field.defaultValue;\n hasDefaults = true;\n }\n // Handle nested fields\n if ('fields' in field && Array.isArray(field.fields)) {\n const nestedDefaults = extractDefaultsFromFields(field.fields);\n if (nestedDefaults) {\n Object.assign(defaults, nestedDefaults);\n hasDefaults = true;\n }\n }\n }\n\n return hasDefaults ? defaults : undefined;\n}\n\n// Apply FormSettings to a FormAdapter\nfunction applySettings<TData>(\n form: FormAdapter<TData>,\n settings?: FormSettings\n): FormAdapter<TData> {\n if (!settings) return form;\n\n if (settings.submitOnlyWhenDirty) {\n const originalHandleSubmit = form.handleSubmit;\n\n form.handleSubmit = (e?: React.FormEvent) => {\n if (!form.formState.isDirty) {\n e?.preventDefault?.();\n return;\n }\n return originalHandleSubmit(e);\n };\n }\n\n if (settings) {\n form.settings = settings;\n }\n\n return form;\n}\n\n/**\n * Create a form instance with the specified options.\n * Uses adapter and resolver from FormProvider context unless overridden.\n * \n * @example\n * const loginSchema = createSchema([\n * { type: 'email', name: 'email', required: true },\n * { type: 'password', name: 'password', required: true },\n * ]);\n * \n * const form = useForm({\n * schema: loginSchema,\n * onSubmit: async (data) => {\n * await auth.login(data);\n * },\n * settings: {\n * submitOnlyWhenDirty: true,\n * },\n * });\n * \n * return (\n * <form onSubmit={form.handleSubmit}>\n * ...\n * </form>\n * );\n */\nexport function useForm<TData extends Record<string, unknown> = Record<string, unknown>>(\n options: UseFormOptions<TData>\n): FormAdapter<TData> {\n const globalConfig = useContext(FormConfigContext);\n\n // Merge global config with overrides\n const adapter = options.adapter ?? globalConfig?.adapter;\n const resolverFn = globalConfig?.resolver;\n const mode = options.mode ?? globalConfig?.mode ?? 'onChange';\n const reValidateMode = options.reValidateMode ?? globalConfig?.reValidateMode ?? 'onChange';\n\n const resolver = options.schema && resolverFn ? resolverFn(options.schema) : undefined;\n\n // Extract default values (useMemo must be unconditional)\n const schemaWithFields = options.schema as (typeof options.schema & { fields?: Field[] }) | undefined;\n const fieldDefaults = useMemo(\n () => extractDefaultsFromFields(schemaWithFields?.fields),\n [schemaWithFields?.fields]\n );\n const defaultValues = options.defaultValues ?? fieldDefaults;\n\n // Call adapter unconditionally to maintain hook order\n const effectiveAdapter = adapter ?? ((_opts: AdapterOptions) => {\n throw new Error('useForm: No adapter configured.');\n });\n\n const form = effectiveAdapter({\n defaultValues,\n resolver,\n mode,\n reValidateMode,\n onSubmit: options.onSubmit,\n } as AdapterOptions) as FormAdapter<TData>;\n\n // Validation must happen after hooks\n if (!options.schema) {\n throw new Error(\n 'useForm: schema is required. ' +\n 'Use createSchema([...]) to create a schema from fields, or pass a Zod schema directly.'\n );\n }\n\n if (!adapter) {\n throw new Error(\n 'useForm: No adapter configured. ' +\n 'Either wrap your app in <FormProvider adapter={...}> or pass adapter in options.'\n );\n }\n\n return applySettings(form, options.settings);\n}\n"],"mappings":"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","names":[]}
|
|
1
|
+
{"version":3,"sources":["../src/types/adapter.ts","../src/context/form-context.ts","../src/providers/form-provider.tsx","../src/hooks/use-form.ts"],"sourcesContent":["import type { FormEvent } from 'react';\nimport type { FormSettings } from './form';\n\n// =============================================================================\n// FORM STATE\n// =============================================================================\n\n/**\n * Represents the current reactive state of a form.\n * Adapters must ensure this triggers re-renders when values change.\n * \n * This is the MINIMUM state required for BuzzForm to work.\n * Custom adapters must provide all these properties.\n */\nexport interface FormState {\n /** True while the form is being submitted */\n isSubmitting: boolean;\n\n /** True while validation is running (async validators) */\n isValidating: boolean;\n\n /** True if any field has been modified from its default value */\n isDirty: boolean;\n\n /** True if all validations pass (no errors) */\n isValid: boolean;\n\n /** True while async default values are being resolved */\n isLoading: boolean;\n\n /** \n * Field-level errors.\n * Key is the field path (e.g., \"email\", \"address.city\", \"items.0.name\")\n * Value is the error message(s)\n * \n * NOTE: Path format uses dot notation. Array indices use numbers (items.0.name).\n */\n errors: Record<string, string | string[] | undefined>;\n\n /** Map of field paths to whether they've been modified */\n dirtyFields: Record<string, boolean>;\n\n /** Map of field paths to whether they've been touched (blurred) */\n touchedFields: Record<string, boolean>;\n\n /** Number of times the form has been submitted */\n submitCount: number;\n}\n\n// =============================================================================\n// VALUE MANAGEMENT\n// =============================================================================\n\n/**\n * Options when programmatically setting a field value.\n */\nexport interface SetValueOptions {\n /** Run validation after setting the value (default: adapter-specific) */\n shouldValidate?: boolean;\n\n /** Mark the field as dirty (default: true) */\n shouldDirty?: boolean;\n\n /** Mark the field as touched (default: false) */\n shouldTouch?: boolean;\n}\n\n// =============================================================================\n// VALIDATION\n// =============================================================================\n\n/**\n * Represents a field-level error.\n */\nexport interface FieldError {\n /** Error type (e.g., 'required', 'pattern', 'server', 'custom') */\n type?: string;\n\n /** Human-readable error message */\n message: string;\n}\n\n/**\n * Result from a validation resolver.\n */\nexport interface ResolverResult<TData> {\n /** Parsed/transformed values (if validation passes) */\n values?: TData;\n\n /** Field errors (if validation fails) */\n errors?: Record<string, FieldError>;\n}\n\n/**\n * A validation resolver function.\n * Adapters use this to validate form values against a schema.\n * \n * @example\n * // Zod resolver\n * const zodResolver = (schema) => async (values) => {\n * const result = schema.safeParse(values);\n * if (result.success) return { values: result.data };\n * return { errors: mapZodErrors(result.error) };\n * };\n */\nexport type Resolver<TData> = (\n values: TData\n) => Promise<ResolverResult<TData>> | ResolverResult<TData>;\n\n// =============================================================================\n// ARRAY HELPERS\n// =============================================================================\n\n/**\n * Helper methods for manipulating array fields.\n * All methods operate on a field path (e.g., \"items\", \"users.0.tags\").\n * \n * This is REQUIRED for ArrayField to work. If your custom adapter doesn't\n * support arrays, you can implement these as no-ops or throw errors.\n */\nexport interface ArrayHelpers {\n /**\n * Get array items with stable IDs for React keys.\n * @param path - Field path to the array\n * @returns Array of items, each with an `id` property for React keys\n */\n fields: <T = unknown>(path: string) => Array<T & { id: string }>;\n\n /**\n * Add an item to the end of the array.\n */\n append: (path: string, value: unknown) => void;\n\n /**\n * Add an item to the beginning of the array.\n */\n prepend: (path: string, value: unknown) => void;\n\n /**\n * Insert an item at a specific index.\n */\n insert: (path: string, index: number, value: unknown) => void;\n\n /**\n * Remove an item at a specific index.\n */\n remove: (path: string, index: number) => void;\n\n /**\n * Move an item from one index to another.\n * Used for drag-and-drop reordering.\n */\n move: (path: string, from: number, to: number) => void;\n\n /**\n * Swap two items by their indices.\n */\n swap: (path: string, indexA: number, indexB: number) => void;\n\n /**\n * Replace the entire array with new values.\n */\n replace: (path: string, values: unknown[]) => void;\n\n /**\n * Update an item at a specific index.\n */\n update: (path: string, index: number, value: unknown) => void;\n}\n\n// =============================================================================\n// ADAPTER OPTIONS\n// =============================================================================\n\n/**\n * Base options passed to any adapter when creating a form instance.\n * Adapters can extend this with library-specific options.\n * \n * @typeParam TData - The shape of form data\n */\nexport interface AdapterOptions<TData = Record<string, unknown>> {\n /**\n * Initial values for the form.\n * Can be:\n * - A static object\n * - A sync function returning values\n * - An async function returning values (form shows loading state)\n */\n defaultValues?: TData | (() => TData) | (() => Promise<TData>);\n\n /**\n * Controlled values - when provided, form becomes controlled.\n * Changes to this prop will update form values.\n */\n values?: TData;\n\n /**\n * Validation resolver.\n * Called to validate form values before submission and optionally on change/blur.\n */\n resolver?: Resolver<TData>;\n\n /**\n * When to run validation.\n * - 'onChange': Validate on every value change\n * - 'onBlur': Validate when fields lose focus\n * - 'onSubmit': Validate only on submit\n * - 'all': Validate on all events\n * \n * NOTE: Not all adapters support all modes. Check adapter documentation.\n */\n mode?: 'onChange' | 'onBlur' | 'onSubmit' | 'all';\n\n /**\n * When to re-validate after initial error.\n * NOTE: This is optional. Some form libraries don't have this concept.\n */\n reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit';\n\n /**\n * Callback when form is submitted (after validation passes).\n */\n onSubmit?: (values: TData) => Promise<void> | void;\n}\n\n// =============================================================================\n// FORM ADAPTER INTERFACE\n// =============================================================================\n\n/**\n * The contract any form adapter must fulfill.\n * \n * ## Required vs Optional\n * \n * **Required methods** are the building blocks that BuzzForm needs to function.\n * If any are missing, forms will break.\n * \n * **Optional methods** (marked with `?`) provide enhanced functionality but\n * are not required. BuzzForm will gracefully degrade without them.\n * \n * ## Creating a Custom Adapter\n * \n * To create a custom adapter (e.g., for useActionState, Formik, or vanilla React):\n * \n * 1. Implement all required properties and methods\n * 2. Optionally implement enhanced features\n * 3. Return the adapter from a hook (factory function)\n * \n * @example\n * // Minimal custom adapter skeleton\n * function useMyAdapter<T>(options: AdapterOptions<T>): FormAdapter<T> {\n * const [values, setValues] = useState(options.defaultValues ?? {});\n * const [errors, setErrors] = useState({});\n * const [isSubmitting, setIsSubmitting] = useState(false);\n * \n * return {\n * control: null, // Your state/context\n * get formState() { return { ... } },\n * handleSubmit: async (e) => { ... },\n * getValues: () => values,\n * setValue: (name, value) => { ... },\n * reset: (vals) => setValues(vals ?? {}),\n * watch: (name) => name ? values[name] : values,\n * validate: async () => true,\n * setError: (name, error) => { ... },\n * clearErrors: () => setErrors({}),\n * array: createArrayHelpers(...),\n * };\n * }\n * \n * @typeParam TData - The shape of form data\n */\nexport interface FormAdapter<TData = Record<string, unknown>> {\n // =========================================================================\n // CORE PROPERTIES (Required)\n // =========================================================================\n\n /**\n * Form-level behavior settings.\n * Set by useForm after applying FormSettings.\n */\n settings?: FormSettings;\n\n /**\n * The underlying form library's control/instance.\n * \n * This is passed to field components that need direct access to the form\n * library (e.g., for React Hook Form's Controller).\n * \n * For custom adapters, this can be:\n * - Your state object\n * - A context value\n * - null (if not needed)\n */\n control: unknown;\n\n /**\n * Current form state.\n * MUST be implemented as a getter to ensure reactivity.\n * \n * @example\n * get formState() {\n * return {\n * isSubmitting: this._isSubmitting,\n * isValidating: false,\n * isDirty: Object.keys(this._touched).length > 0,\n * isValid: Object.keys(this._errors).length === 0,\n * isLoading: false,\n * errors: this._errors,\n * dirtyFields: this._dirty,\n * touchedFields: this._touched,\n * submitCount: this._submitCount,\n * };\n * }\n */\n formState: FormState;\n\n /**\n * Submit handler to attach to a form element.\n * Should prevent default, run validation, and call onSubmit if valid.\n * \n * @example\n * <form onSubmit={adapter.handleSubmit}>\n */\n handleSubmit: (e?: FormEvent) => Promise<void> | void;\n\n // =========================================================================\n // VALUE MANAGEMENT (Required)\n // =========================================================================\n\n /**\n * Get all current form values.\n */\n getValues: () => TData;\n\n /**\n * Set a single field's value.\n * \n * @param name - Field path (e.g., \"email\", \"address.city\", \"items.0.name\")\n * @param value - New value\n * @param options - Additional options\n */\n setValue: (\n name: string,\n value: unknown,\n options?: SetValueOptions\n ) => void;\n\n /**\n * Reset form to default values or provided values.\n * \n * @param values - Optional new values to reset to\n */\n reset: (values?: Partial<TData>) => void;\n\n /**\n * Watch one or more field values reactively.\n * Returns current value(s) and causes re-render when they change.\n * \n * @param name - Field path to watch, or undefined for all values\n * @returns Current value(s)\n */\n watch: <T = unknown>(name?: string) => T;\n\n // =========================================================================\n // VALIDATION (Required)\n // =========================================================================\n\n /**\n * Manually trigger validation.\n * \n * @param name - Field(s) to validate, or undefined for entire form\n * @returns True if validation passes\n */\n validate: (name?: string | string[]) => Promise<boolean>;\n\n /**\n * Set a field error programmatically.\n * Useful for server-side validation errors.\n * \n * @param name - Field path\n * @param error - Error details\n */\n setError: (name: string, error: FieldError) => void;\n\n /**\n * Clear validation errors.\n * \n * @param name - Field(s) to clear, or undefined for all errors\n */\n clearErrors: (name?: string | string[]) => void;\n\n // =========================================================================\n // ARRAYS (Required for ArrayField)\n // =========================================================================\n\n /**\n * Helpers for manipulating array fields.\n * Required if you use ArrayField component.\n */\n array: ArrayHelpers;\n\n // =========================================================================\n // OPTIONAL ENHANCED FEATURES\n // These provide better UX but are not required for basic functionality.\n // =========================================================================\n\n /**\n * Handle field blur event.\n * Triggers validation if mode is 'onBlur'.\n * \n * If not provided, BuzzForm will not trigger blur-based validation.\n * \n * @param name - Field path\n */\n onBlur?: (name: string) => void;\n\n /**\n * Get the state of a specific field.\n * More efficient than accessing the entire formState for single fields.\n * \n * @param name - Field path\n */\n getFieldState?: (name: string) => {\n isDirty: boolean;\n isTouched: boolean;\n invalid: boolean;\n error?: string;\n };\n\n /**\n * Programmatically focus a field.\n * Useful for accessibility and after adding array items.\n * \n * @param name - Field path\n * @param options - Focus options\n */\n setFocus?: (name: string, options?: { shouldSelect?: boolean }) => void;\n\n /**\n * Unregister a field from the form.\n * Called when conditional fields are hidden.\n * \n * If not provided, hidden fields will retain their values.\n * \n * @param name - Field path(s) to unregister\n */\n unregister?: (name: string | string[]) => void;\n}\n\n// =============================================================================\n// ADAPTER FACTORY TYPE\n// =============================================================================\n\n/**\n * Type for an adapter factory function (hook).\n * \n * @example\n * // Using the adapter\n * function MyApp() {\n * return (\n * <FormProvider adapter={useRhfAdapter}>\n * <MyForm />\n * </FormProvider>\n * );\n * }\n */\nexport type AdapterFactory<TData = Record<string, unknown>> = (\n options: AdapterOptions<TData>\n) => FormAdapter<TData>;\n\n// =============================================================================\n// VALIDATION HELPERS FOR CUSTOM ADAPTERS\n// =============================================================================\n\n/**\n * Validates that a FormAdapter has all required methods.\n * Call this in development to catch missing implementations early.\n * \n * @param adapter - The adapter to validate\n * @param adapterName - Name for error messages\n * @throws Error if required methods are missing\n */\nexport function validateAdapter(adapter: FormAdapter, adapterName = 'adapter'): void {\n const required = [\n 'control',\n 'formState',\n 'handleSubmit',\n 'getValues',\n 'setValue',\n 'reset',\n 'watch',\n 'validate',\n 'setError',\n 'clearErrors',\n 'array',\n ] as const;\n\n for (const key of required) {\n if (adapter[key] === undefined) {\n throw new Error(\n `Invalid FormAdapter: \"${adapterName}\" is missing required property \"${key}\". ` +\n `See FormAdapter interface for implementation requirements.`\n );\n }\n }\n\n // Validate array helpers\n const arrayMethods = [\n 'fields', 'append', 'prepend', 'insert',\n 'remove', 'move', 'swap', 'replace', 'update'\n ] as const;\n\n for (const method of arrayMethods) {\n if (typeof adapter.array[method] !== 'function') {\n throw new Error(\n `Invalid FormAdapter: \"${adapterName}.array.${method}\" must be a function.`\n );\n }\n }\n}\n","'use client';\n\nimport { createContext } from 'react';\nimport type { FormConfig } from '../types';\n\n/**\n * Context for global form configuration.\n * Set via FormProvider, consumed by useForm.\n */\nexport const FormConfigContext = createContext<FormConfig | null>(null);\n","\"use client\";\n\nimport React from \"react\";\nimport { FormConfigContext } from \"../context/form-context\";\nimport type { FormConfig } from \"../types\";\n\n/**\n * Provider for global form configuration.\n * Set the adapter, resolver, and default mode for all forms in the app.\n *\n * @example\n * import { FormProvider } from '@buildnbuzz/buzzform';\n * import { useRhfAdapter } from '@buildnbuzz/buzzform/rhf';\n * import { zodResolver } from '@buildnbuzz/buzzform/resolvers/zod';\n *\n * <FormProvider\n * adapter={useRhfAdapter}\n * resolver={zodResolver}\n * mode=\"onBlur\"\n * >\n * <App />\n * </FormProvider>\n */\nexport const FormProvider: React.FC<\n FormConfig & { children: React.ReactNode }\n> = ({ children, ...config }) => {\n return (\n <FormConfigContext.Provider value={config}>\n {children}\n </FormConfigContext.Provider>\n );\n};\n","\"use client\";\n\nimport { useContext, useMemo } from \"react\";\nimport { FormConfigContext } from \"../context/form-context\";\nimport type {\n UseFormOptions,\n FormAdapter,\n AdapterOptions,\n Field,\n FormSettings,\n OutputConfig,\n} from \"../types\";\nimport { transformFormOutput } from \"../lib\";\n\n/**\n * Extract default values from field definitions.\n */\nfunction extractDefaultsFromFields(\n fields?: Field[],\n): Record<string, unknown> | undefined {\n if (!fields || fields.length === 0) return undefined;\n\n const defaults: Record<string, unknown> = {};\n let hasDefaults = false;\n\n for (const field of fields) {\n if (\n \"name\" in field &&\n \"defaultValue\" in field &&\n field.defaultValue !== undefined\n ) {\n defaults[field.name] = field.defaultValue;\n hasDefaults = true;\n }\n // Handle nested fields\n if (\"fields\" in field && Array.isArray(field.fields)) {\n const nestedDefaults = extractDefaultsFromFields(field.fields);\n if (nestedDefaults) {\n Object.assign(defaults, nestedDefaults);\n hasDefaults = true;\n }\n }\n }\n\n return hasDefaults ? defaults : undefined;\n}\n\n// Apply FormSettings to a FormAdapter\nfunction applySettings<TData>(\n form: FormAdapter<TData>,\n settings?: FormSettings,\n outputConfig?: OutputConfig,\n): FormAdapter<TData> {\n if (!settings && !outputConfig) return form;\n\n if (settings?.submitOnlyWhenDirty) {\n const originalHandleSubmit = form.handleSubmit;\n\n form.handleSubmit = (e?: React.FormEvent) => {\n if (!form.formState.isDirty) {\n e?.preventDefault?.();\n return;\n }\n return originalHandleSubmit(e);\n };\n }\n\n if (settings) {\n form.settings = settings;\n }\n\n // Wrap getValues and watch to return transformed output\n if (outputConfig?.type === \"path\") {\n const originalGetValues = form.getValues;\n form.getValues = () => {\n const values = originalGetValues();\n return transformFormOutput(values, outputConfig);\n };\n\n const originalWatch = form.watch;\n form.watch = <T = unknown>(name?: string): T => {\n const values = originalWatch<T>(name);\n // Only transform when watching the entire form (name is undefined)\n if (!name) {\n return transformFormOutput(values, outputConfig) as T;\n }\n return values;\n };\n }\n\n return form;\n}\n\n/**\n * Create a form instance with the specified options.\n * Uses adapter and resolver from FormProvider context unless overridden.\n *\n * @example\n * const loginSchema = createSchema([\n * { type: 'email', name: 'email', required: true },\n * { type: 'password', name: 'password', required: true },\n * ]);\n *\n * const form = useForm({\n * schema: loginSchema,\n * onSubmit: async (data) => {\n * await auth.login(data);\n * },\n * settings: {\n * submitOnlyWhenDirty: true,\n * },\n * });\n *\n * return (\n * <form onSubmit={form.handleSubmit}>\n * ...\n * </form>\n * );\n */\nexport function useForm<\n TData extends Record<string, unknown> = Record<string, unknown>,\n>(options: UseFormOptions<TData>): FormAdapter<TData> {\n const globalConfig = useContext(FormConfigContext);\n\n // Merge global config with overrides\n const adapter = options.adapter ?? globalConfig?.adapter;\n const resolverFn = globalConfig?.resolver;\n const mode = options.mode ?? globalConfig?.mode ?? \"onChange\";\n const reValidateMode =\n options.reValidateMode ?? globalConfig?.reValidateMode ?? \"onChange\";\n const outputConfig = options.output ?? globalConfig?.output;\n\n const resolver =\n options.schema && resolverFn ? resolverFn(options.schema) : undefined;\n\n // Extract default values (useMemo must be unconditional)\n const schemaWithFields = options.schema as\n | (typeof options.schema & { fields?: Field[] })\n | undefined;\n const fieldDefaults = useMemo(\n () => extractDefaultsFromFields(schemaWithFields?.fields),\n [schemaWithFields?.fields],\n );\n const defaultValues = options.defaultValues ?? fieldDefaults;\n\n // Wrap onSubmit to apply output transformation before calling user's handler\n const userOnSubmit = options.onSubmit;\n const wrappedOnSubmit =\n userOnSubmit && outputConfig?.type === \"path\"\n ? (data: TData) => {\n const transformed = transformFormOutput(data, outputConfig);\n return userOnSubmit(transformed);\n }\n : userOnSubmit;\n\n // Call adapter unconditionally to maintain hook order\n const effectiveAdapter =\n adapter ??\n ((_opts: AdapterOptions) => {\n throw new Error(\"useForm: No adapter configured.\");\n });\n\n const form = effectiveAdapter({\n defaultValues,\n resolver,\n mode,\n reValidateMode,\n onSubmit: wrappedOnSubmit,\n } as AdapterOptions) as FormAdapter<TData>;\n\n // Validation must happen after hooks\n if (!options.schema) {\n throw new Error(\n \"useForm: schema is required. \" +\n \"Use createSchema([...]) to create a schema from fields, or pass a Zod schema directly.\",\n );\n }\n\n if (!adapter) {\n throw new Error(\n \"useForm: No adapter configured. \" +\n \"Either wrap your app in <FormProvider adapter={...}> or pass adapter in options.\",\n );\n }\n\n return applySettings(form, options.settings, outputConfig);\n}\n"],"mappings":"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","names":[]}
|
package/dist/rhf.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { FieldValues, Control } from 'react-hook-form';
|
|
2
2
|
export { UseFormReturn as RhfForm } from 'react-hook-form';
|
|
3
|
-
import { f as AdapterOptions, b as FormAdapter } from './adapter-
|
|
3
|
+
import { f as AdapterOptions, b as FormAdapter } from './adapter-Bd0fYuAE.mjs';
|
|
4
4
|
import 'react';
|
|
5
5
|
import 'zod';
|
|
6
6
|
|
package/dist/rhf.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { FieldValues, Control } from 'react-hook-form';
|
|
2
2
|
export { UseFormReturn as RhfForm } from 'react-hook-form';
|
|
3
|
-
import { f as AdapterOptions, b as FormAdapter } from './adapter-
|
|
3
|
+
import { f as AdapterOptions, b as FormAdapter } from './adapter-Bd0fYuAE.js';
|
|
4
4
|
import 'react';
|
|
5
5
|
import 'zod';
|
|
6
6
|
|
package/dist/rhf.mjs
CHANGED
package/dist/schema.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { T as TextField, o as TextareaField, E as EmailField, P as PasswordField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, w as RadioField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, y as UploadField, x as TagsField, z as ArrayField, F as Field, G as GroupField } from './adapter-
|
|
2
|
-
export { g as AdapterFactory, f as AdapterOptions, A as ArrayHelpers, B as BaseField,
|
|
3
|
-
export { F as FieldToZod, u as FieldValidator, a as FieldsToShape, c as InferSchema, I as InferType, S as SchemaBuilder, b as SchemaBuilderMap, h as coerceToDate, g as coerceToNumber, q as collectFieldValidators, l as createArrayHelpers, d as createSchema, e as extractValidationConfig, f as fieldsToZodSchema, p as formatBytes, n as generateFieldId, o as getNestedValue, i as getPatternErrorMessage, r as getSiblingData, t as getValueByPath, j as isFileLike, k as isFileTypeAccepted, m as makeOptional, s as setNestedValue } from './utils-
|
|
1
|
+
import { T as TextField, o as TextareaField, E as EmailField, P as PasswordField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, w as RadioField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, y as UploadField, x as TagsField, z as ArrayField, F as Field, G as GroupField } from './adapter-Bd0fYuAE.mjs';
|
|
2
|
+
export { g as AdapterFactory, f as AdapterOptions, A as ArrayHelpers, B as BaseField, W as BuzzFormSchema, K as CollapsibleField, C as ConditionContext, M as DataField, k as FieldComponentProps, j as FieldCondition, d as FieldError, l as FieldInputProps, m as FieldInputRenderFn, n as FieldStyle, L as FieldType, b as FormAdapter, a as FormConfig, X as FormSettings, c as FormState, Q as LayoutField, e as Resolver, R as ResolverResult, H as RowField, q as SelectOption, S as SetValueOptions, I as Tab, J as TabsField, U as UseFormOptions, V as ValidationContext, i as ValidationFn, h as ValidationResult } from './adapter-Bd0fYuAE.mjs';
|
|
3
|
+
export { F as FieldToZod, u as FieldValidator, a as FieldsToShape, c as InferSchema, I as InferType, S as SchemaBuilder, b as SchemaBuilderMap, h as coerceToDate, g as coerceToNumber, q as collectFieldValidators, l as createArrayHelpers, d as createSchema, e as extractValidationConfig, f as fieldsToZodSchema, p as formatBytes, n as generateFieldId, o as getNestedValue, i as getPatternErrorMessage, r as getSiblingData, t as getValueByPath, j as isFileLike, k as isFileTypeAccepted, m as makeOptional, s as setNestedValue } from './utils-BsX0viz8.mjs';
|
|
4
4
|
import { z } from 'zod';
|
|
5
5
|
import 'react';
|
|
6
6
|
|
package/dist/schema.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { T as TextField, o as TextareaField, E as EmailField, P as PasswordField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, w as RadioField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, y as UploadField, x as TagsField, z as ArrayField, F as Field, G as GroupField } from './adapter-
|
|
2
|
-
export { g as AdapterFactory, f as AdapterOptions, A as ArrayHelpers, B as BaseField,
|
|
3
|
-
export { F as FieldToZod, u as FieldValidator, a as FieldsToShape, c as InferSchema, I as InferType, S as SchemaBuilder, b as SchemaBuilderMap, h as coerceToDate, g as coerceToNumber, q as collectFieldValidators, l as createArrayHelpers, d as createSchema, e as extractValidationConfig, f as fieldsToZodSchema, p as formatBytes, n as generateFieldId, o as getNestedValue, i as getPatternErrorMessage, r as getSiblingData, t as getValueByPath, j as isFileLike, k as isFileTypeAccepted, m as makeOptional, s as setNestedValue } from './utils-
|
|
1
|
+
import { T as TextField, o as TextareaField, E as EmailField, P as PasswordField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, w as RadioField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, y as UploadField, x as TagsField, z as ArrayField, F as Field, G as GroupField } from './adapter-Bd0fYuAE.js';
|
|
2
|
+
export { g as AdapterFactory, f as AdapterOptions, A as ArrayHelpers, B as BaseField, W as BuzzFormSchema, K as CollapsibleField, C as ConditionContext, M as DataField, k as FieldComponentProps, j as FieldCondition, d as FieldError, l as FieldInputProps, m as FieldInputRenderFn, n as FieldStyle, L as FieldType, b as FormAdapter, a as FormConfig, X as FormSettings, c as FormState, Q as LayoutField, e as Resolver, R as ResolverResult, H as RowField, q as SelectOption, S as SetValueOptions, I as Tab, J as TabsField, U as UseFormOptions, V as ValidationContext, i as ValidationFn, h as ValidationResult } from './adapter-Bd0fYuAE.js';
|
|
3
|
+
export { F as FieldToZod, u as FieldValidator, a as FieldsToShape, c as InferSchema, I as InferType, S as SchemaBuilder, b as SchemaBuilderMap, h as coerceToDate, g as coerceToNumber, q as collectFieldValidators, l as createArrayHelpers, d as createSchema, e as extractValidationConfig, f as fieldsToZodSchema, p as formatBytes, n as generateFieldId, o as getNestedValue, i as getPatternErrorMessage, r as getSiblingData, t as getValueByPath, j as isFileLike, k as isFileTypeAccepted, m as makeOptional, s as setNestedValue } from './utils-DHF346op.js';
|
|
4
4
|
import { z } from 'zod';
|
|
5
5
|
import 'react';
|
|
6
6
|
|
package/dist/schema.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import { F as Field, T as TextField, E as EmailField, P as PasswordField, o as TextareaField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, w as RadioField, x as TagsField, y as UploadField, G as GroupField, z as ArrayField, H as RowField, J as TabsField, K as CollapsibleField, V as ValidationContext, L as FieldType, i as ValidationFn, A as ArrayHelpers } from './adapter-
|
|
2
|
+
import { F as Field, T as TextField, E as EmailField, P as PasswordField, o as TextareaField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, w as RadioField, x as TagsField, y as UploadField, G as GroupField, z as ArrayField, H as RowField, J as TabsField, K as CollapsibleField, V as ValidationContext, L as FieldType, i as ValidationFn, A as ArrayHelpers } from './adapter-Bd0fYuAE.mjs';
|
|
3
3
|
|
|
4
4
|
type ExtractL1<F> = F extends {
|
|
5
5
|
type: "row" | "collapsible";
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import { F as Field, T as TextField, E as EmailField, P as PasswordField, o as TextareaField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, w as RadioField, x as TagsField, y as UploadField, G as GroupField, z as ArrayField, H as RowField, J as TabsField, K as CollapsibleField, V as ValidationContext, L as FieldType, i as ValidationFn, A as ArrayHelpers } from './adapter-
|
|
2
|
+
import { F as Field, T as TextField, E as EmailField, P as PasswordField, o as TextareaField, N as NumberField, D as DateField, p as DatetimeField, r as SelectField, s as CheckboxGroupField, t as CheckboxField, u as SwitchField, w as RadioField, x as TagsField, y as UploadField, G as GroupField, z as ArrayField, H as RowField, J as TabsField, K as CollapsibleField, V as ValidationContext, L as FieldType, i as ValidationFn, A as ArrayHelpers } from './adapter-Bd0fYuAE.js';
|
|
3
3
|
|
|
4
4
|
type ExtractL1<F> = F extends {
|
|
5
5
|
type: "row" | "collapsible";
|
package/dist/zod.d.mts
CHANGED
package/dist/zod.d.ts
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@buildnbuzz/buzzform",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"description": "Simple React form library for shadcn/ui. Declare fields, customize rendering, get live validation with minimal boilerplate.",
|
|
5
5
|
"author": "Parth Lad <parth@buildnbuzz.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/utils/array.ts","../src/lib/utils.ts","../src/lib/field.ts"],"sourcesContent":["import { nanoid } from 'nanoid';\nimport type { ArrayHelpers } from '../types';\n\n/**\n * Creates a standardized set of array field manipulation methods.\n * Abstracts the difference between getting/setting values in different form libraries.\n * \n * @param getArray - Function to get current array value at a path\n * @param setArray - Function to set array value at a path\n */\nexport function createArrayHelpers(\n getArray: (path: string) => unknown,\n setArray: (path: string, value: unknown[]) => void\n): ArrayHelpers {\n const readArray = (path: string): unknown[] => {\n const value = getArray(path);\n return Array.isArray(value) ? value : [];\n };\n\n return {\n fields: <T = unknown>(path: string): Array<T & { id: string }> => {\n const arr = readArray(path);\n return arr.map((item, index) => {\n const itemObject =\n typeof item === 'object' && item !== null\n ? (item as Record<string, unknown>)\n : ({ value: item } as Record<string, unknown>);\n\n return {\n id: (itemObject.id as string) || `${path}-${index}`,\n ...(itemObject as T),\n };\n });\n },\n\n append: (path: string, value: unknown) => {\n const current = readArray(path);\n const itemWithId = ensureId(value);\n setArray(path, [...current, itemWithId]);\n },\n\n prepend: (path: string, value: unknown) => {\n const current = readArray(path);\n const itemWithId = ensureId(value);\n setArray(path, [itemWithId, ...current]);\n },\n\n insert: (path: string, index: number, value: unknown) => {\n const current = [...readArray(path)];\n const itemWithId = ensureId(value);\n current.splice(index, 0, itemWithId);\n setArray(path, current);\n },\n\n remove: (path: string, index: number) => {\n const current = [...readArray(path)];\n current.splice(index, 1);\n setArray(path, current);\n },\n\n move: (path: string, from: number, to: number) => {\n const current = [...readArray(path)];\n const [item] = current.splice(from, 1);\n current.splice(to, 0, item);\n setArray(path, current);\n },\n\n swap: (path: string, indexA: number, indexB: number) => {\n const current = [...readArray(path)];\n const temp = current[indexA];\n current[indexA] = current[indexB];\n current[indexB] = temp;\n setArray(path, current);\n },\n\n replace: (path: string, values: unknown[]) => {\n const itemsWithIds = values.map(ensureId);\n setArray(path, itemsWithIds);\n },\n\n update: (path: string, index: number, value: unknown) => {\n const current = [...readArray(path)];\n // Preserve existing ID if present\n const existingId = (current[index] as Record<string, unknown>)?.id;\n current[index] = {\n ...(typeof value === 'object' && value !== null ? value : {}),\n id: existingId || nanoid(),\n };\n setArray(path, current);\n },\n };\n}\n\n/**\n * Ensures an item has a unique ID for React keys.\n */\nfunction ensureId(value: unknown): unknown {\n if (typeof value === 'object' && value !== null) {\n const obj = value as Record<string, unknown>;\n if (!obj.id) {\n return { ...obj, id: nanoid() };\n }\n return obj;\n }\n return { value, id: nanoid() };\n}\n","// =============================================================================\n// COMMON UTILITIES\n// These are used by both the core package and registry field components.\n// =============================================================================\n\n/**\n * Generate a unique field ID from the field path.\n * Converts dot notation to dashes and prefixes with 'field-'.\n * Used for accessibility (htmlFor, id attributes).\n * \n * @example\n * generateFieldId('user.profile.email') => 'field-user-profile-email'\n * generateFieldId('items[0].name') => 'field-items-0-name'\n */\nexport function generateFieldId(path: string): string {\n return `field-${path.replace(/\\./g, \"-\").replace(/\\[/g, \"-\").replace(/\\]/g, \"\")}`;\n}\n\n/**\n * Safely retrieve a nested value from an object using a dot-notation path.\n * \n * @example\n * getNestedValue({ user: { name: 'John' } }, 'user.name') => 'John'\n * getNestedValue({ items: [{ id: 1 }] }, 'items.0.id') => 1\n */\nexport function getNestedValue(obj: unknown, path: string): unknown {\n if (!obj || !path) return undefined;\n return path.split(\".\").reduce<unknown>((acc: unknown, key: string) => {\n if (acc && typeof acc === \"object\" && acc !== null) {\n return (acc as Record<string, unknown>)[key];\n }\n return undefined;\n }, obj);\n}\n\n/**\n * Set a nested value in an object using a dot-notation path.\n * Creates intermediate objects/arrays as needed.\n * \n * @example\n * setNestedValue({}, 'user.name', 'John') => { user: { name: 'John' } }\n */\nexport function setNestedValue<T extends Record<string, unknown>>(\n obj: T,\n path: string,\n value: unknown\n): T {\n const keys = path.split(\".\");\n const result = { ...obj } as Record<string, unknown>;\n let current = result;\n\n for (let i = 0; i < keys.length - 1; i++) {\n const key = keys[i];\n if (!(key in current) || typeof current[key] !== \"object\") {\n // Check if next key is numeric (array index)\n const nextKey = keys[i + 1];\n current[key] = /^\\d+$/.test(nextKey) ? [] : {};\n } else {\n current[key] = Array.isArray(current[key])\n ? [...(current[key] as unknown[])]\n : { ...(current[key] as Record<string, unknown>) };\n }\n current = current[key] as Record<string, unknown>;\n }\n\n current[keys[keys.length - 1]] = value;\n return result as T;\n}\n\n/**\n * Format bytes into a human-readable string.\n * \n * @example\n * formatBytes(1024) => '1 KB'\n * formatBytes(1234567) => '1.18 MB'\n */\nexport function formatBytes(bytes: number, decimals = 2): string {\n if (bytes === 0) return '0 Bytes';\n\n const k = 1024;\n const dm = decimals < 0 ? 0 : decimals;\n const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];\n\n const i = Math.floor(Math.log(bytes) / Math.log(k));\n\n return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;\n}\n\n/**\n * Flatten a nested object to dot-notation paths.\n * Useful for converting form library state (like dirtyFields, touchedFields)\n * to the flat format expected by FormState.\n * \n * @example\n * flattenNestedObject({ user: { name: true, email: true } })\n * // => { 'user.name': true, 'user.email': true }\n * \n * flattenNestedObject({ items: { 0: { title: true } } })\n * // => { 'items.0.title': true }\n */\nexport function flattenNestedObject(\n obj: Record<string, unknown>,\n prefix = ''\n): Record<string, boolean> {\n const result: Record<string, boolean> = {};\n\n for (const key in obj) {\n const path = prefix ? `${prefix}.${key}` : key;\n const value = obj[key];\n\n if (typeof value === 'boolean') {\n result[path] = value;\n } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {\n Object.assign(result, flattenNestedObject(value as Record<string, unknown>, path));\n }\n }\n\n return result;\n}\n\n","import type { ReactNode } from 'react';\nimport type { Field } from '../types';\n\n// =============================================================================\n// FIELD PATH UTILITIES\n// These utilities help work with nested field definitions and form data.\n// =============================================================================\n\n/**\n * Recursively extracts all field paths from a field definition tree.\n * Handles nested groups, arrays, and layout fields (rows, tabs, collapsibles).\n * \n * @param fields - Array of field definitions\n * @param basePath - Base path prefix (e.g., \"contacts.0\" for array items)\n * @returns Array of all field paths\n * \n * @example\n * const fields = [\n * { type: 'text', name: 'name' },\n * { type: 'group', name: 'address', fields: [\n * { type: 'text', name: 'city' },\n * { type: 'text', name: 'zip' }\n * ]}\n * ];\n * getNestedFieldPaths(fields, 'contact')\n * // => ['contact.name', 'contact.address', 'contact.address.city', 'contact.address.zip']\n */\nexport function getNestedFieldPaths(fields: Field[], basePath: string): string[] {\n const paths: string[] = [];\n\n for (const field of fields) {\n // Data fields with names\n if ('name' in field && field.name) {\n const fieldPath = basePath ? `${basePath}.${field.name}` : field.name;\n paths.push(fieldPath);\n\n // Recurse into group/array fields\n if (field.type === 'group' && 'fields' in field) {\n paths.push(...getNestedFieldPaths(field.fields, fieldPath));\n }\n if (field.type === 'array' && 'fields' in field) {\n paths.push(...getNestedFieldPaths(field.fields, fieldPath));\n }\n }\n\n // Layout fields (row, tabs, collapsible) - pass through without adding to path\n if ('fields' in field && field.type !== 'group' && field.type !== 'array') {\n const layoutField = field as Field & { fields: Field[] };\n paths.push(...getNestedFieldPaths(layoutField.fields, basePath));\n }\n\n // Tabs field - iterate through tabs\n if (field.type === 'tabs' && 'tabs' in field) {\n for (const tab of field.tabs) {\n const tabPath = tab.name ? (basePath ? `${basePath}.${tab.name}` : tab.name) : basePath;\n paths.push(...getNestedFieldPaths(tab.fields, tabPath));\n }\n }\n }\n\n return paths;\n}\n\n/**\n * Count validation errors in nested fields.\n * Useful for showing error badges on collapsible sections, array rows, tabs, etc.\n * \n * @param errors - Form errors object from FormAdapter.formState.errors\n * @param fields - Field definitions to check\n * @param basePath - Base path for the fields\n * @returns Number of fields with errors\n * \n * @example\n * const errorCount = countNestedErrors(form.formState.errors, arrayField.fields, `items.0`);\n */\nexport function countNestedErrors(\n errors: Record<string, unknown>,\n fields: Field[],\n basePath: string\n): number {\n const paths = getNestedFieldPaths(fields, basePath);\n return paths.filter((path) => errors[path]).length;\n}\n\n/**\n * Resolve a potentially dynamic field property (disabled, readOnly, hidden).\n * These properties can be boolean or a function that receives form data.\n * \n * @param value - The property value (boolean or function)\n * @param formData - Current form data\n * @param siblingData - Data at the same level (for arrays, this is the row data)\n * @returns Resolved boolean value\n * \n * @example\n * const isDisabled = resolveFieldState(field.disabled, formData, siblingData);\n */\nexport function resolveFieldState<TData = Record<string, unknown>>(\n value: boolean | ((data: TData, siblingData: Record<string, unknown>) => boolean) | undefined,\n formData: TData,\n siblingData: Record<string, unknown> = formData as Record<string, unknown>\n): boolean {\n if (typeof value === 'function') {\n return value(formData, siblingData);\n }\n return Boolean(value);\n}\n\n/**\n * Get the label value for an array row based on field configuration.\n * First checks for a specific rowLabelField in ui options, then falls back\n * to the first named field's value.\n * \n * @param rowData - Data for the row\n * @param fields - Field definitions for the array\n * @param uiOptions - UI options that may contain rowLabelField\n * @param fallbackLabel - Default label if no value found\n * @returns Label string for the row\n * \n * @example\n * const label = getArrayRowLabel(rowData, field.fields, field.ui, `Item ${index + 1}`);\n */\nexport function getArrayRowLabel(\n rowData: Record<string, unknown> | undefined,\n fields: Field[],\n uiOptions: { rowLabelField?: string } | undefined,\n fallbackLabel: string\n): string {\n // First try explicit rowLabelField\n if (uiOptions?.rowLabelField && rowData?.[uiOptions.rowLabelField]) {\n return String(rowData[uiOptions.rowLabelField]);\n }\n\n // Fall back to first named field\n const firstNamedField = fields.find((f) => 'name' in f && f.name);\n if (firstNamedField && 'name' in firstNamedField) {\n const value = rowData?.[firstNamedField.name];\n if (value) {\n return String(value);\n }\n }\n\n return fallbackLabel;\n}\n\n// =============================================================================\n// FIELD STYLE UTILITIES\n// Helpers for computing field styling props.\n// =============================================================================\n\n/**\n * Compute the inline style object for a field's width.\n * Handles both numeric (px) and string (CSS) width values.\n * \n * @param style - Field style configuration\n * @returns CSS properties object or undefined if no width specified\n * \n * @example\n * <Field style={getFieldWidthStyle(field.style)}>\n * ...\n * </Field>\n */\nexport function getFieldWidthStyle(\n style: { width?: number | string } | undefined\n): { width: string } | undefined {\n if (!style?.width) return undefined;\n return {\n width: typeof style.width === 'number'\n ? `${style.width}px`\n : style.width,\n };\n}\n\n// =============================================================================\n// SELECT OPTION UTILITIES\n// Helpers for normalizing and extracting data from SelectOption | string.\n// =============================================================================\n\ntype SelectOptionLike = { value: string | number | boolean; label?: ReactNode; description?: ReactNode; icon?: ReactNode; disabled?: boolean } | string;\n\n/**\n * Normalize a select option to always be an object.\n * Converts string options to { value, label } objects.\n * \n * @param option - String or SelectOption object\n * @returns Normalized SelectOption object\n * \n * @example\n * normalizeSelectOption('foo') // => { value: 'foo', label: 'foo' }\n * normalizeSelectOption({ value: 'bar', label: 'Bar' }) // => { value: 'bar', label: 'Bar' }\n */\nexport function normalizeSelectOption(option: SelectOptionLike): {\n value: string | number | boolean;\n label: ReactNode;\n description?: ReactNode;\n icon?: ReactNode;\n disabled?: boolean;\n} {\n if (typeof option === 'string') {\n return { value: option, label: option };\n }\n return {\n value: option.value,\n label: option.label ?? String(option.value),\n description: option.description,\n icon: option.icon,\n disabled: option.disabled,\n };\n}\n\n/**\n * Get the value from a select option (handles string or object).\n * \n * @param option - String or SelectOption object\n * @returns The option's value as a string\n * \n * @example\n * getSelectOptionValue('foo') // => 'foo'\n * getSelectOptionValue({ value: 123, label: 'One Two Three' }) // => '123'\n */\nexport function getSelectOptionValue(option: SelectOptionLike): string {\n if (typeof option === 'string') return option;\n const val = option.value;\n if (typeof val === 'boolean') return val ? 'true' : 'false';\n return String(val);\n}\n\n/**\n * Get the label from a select option (handles string or object).\n * Returns ReactNode to support JSX labels.\n * \n * @param option - String or SelectOption object\n * @returns The option's label for display\n * \n * @example\n * getSelectOptionLabel('foo') // => 'foo'\n * getSelectOptionLabel({ value: 'bar', label: <strong>Bar</strong> }) // => <strong>Bar</strong>\n */\nexport function getSelectOptionLabel(option: SelectOptionLike): ReactNode {\n if (typeof option === 'string') return option;\n return option.label ?? String(option.value);\n}\n\n/**\n * Get the string label from a select option (for filtering/comparison).\n * Always returns a string, not ReactNode.\n * \n * @param option - String or SelectOption object\n * @returns The option's label as a string\n */\nexport function getSelectOptionLabelString(option: SelectOptionLike): string {\n if (typeof option === 'string') return option;\n if (typeof option.label === 'string') return option.label;\n return String(option.value);\n}\n\n/**\n * Check if a select option is disabled.\n * \n * @param option - String or SelectOption object\n * @returns true if option is disabled\n */\nexport function isSelectOptionDisabled(option: SelectOptionLike): boolean {\n if (typeof option === 'string') return false;\n return option.disabled === true;\n}\n\n// =============================================================================\n// NUMBER UTILITIES\n// Helpers for number field operations.\n// =============================================================================\n\n/**\n * Clamp a number between min and max bounds.\n * \n * @param value - The number to clamp\n * @param min - Minimum bound (optional)\n * @param max - Maximum bound (optional)\n * @returns Clamped number\n * \n * @example\n * clampNumber(5, 0, 10) // => 5\n * clampNumber(-5, 0, 10) // => 0\n * clampNumber(15, 0, 10) // => 10\n */\nexport function clampNumber(value: number, min?: number, max?: number): number {\n let result = value;\n if (min !== undefined && result < min) result = min;\n if (max !== undefined && result > max) result = max;\n return result;\n}\n\n/**\n * Apply numeric precision (decimal places) to a number.\n * \n * @param value - The number to format\n * @param precision - Number of decimal places\n * @returns Formatted number or undefined if input is undefined\n * \n * @example\n * applyNumericPrecision(3.14159, 2) // => 3.14\n * applyNumericPrecision(10, 2) // => 10\n */\nexport function applyNumericPrecision(\n value: number | undefined,\n precision?: number\n): number | undefined {\n if (value === undefined || precision === undefined) return value;\n return parseFloat(value.toFixed(precision));\n}\n\n/**\n * Format a number with thousand separators.\n * \n * @param value - The number to format\n * @param separator - Separator character (default: ',')\n * @returns Formatted string or empty string if value is undefined/NaN\n * \n * @example\n * formatNumberWithSeparator(1234567.89) // => '1,234,567.89'\n * formatNumberWithSeparator(1234567, ' ') // => '1 234 567'\n */\nexport function formatNumberWithSeparator(\n value: number | undefined,\n separator: string = ','\n): string {\n if (value === undefined || value === null || isNaN(value)) return '';\n const [intPart, decPart] = value.toString().split('.');\n const formattedInt = intPart.replace(/\\B(?=(\\d{3})+(?!\\d))/g, separator);\n return decPart !== undefined ? `${formattedInt}.${decPart}` : formattedInt;\n}\n\n/**\n * Parse a formatted number string back to a number.\n * \n * @param str - Formatted string with separators\n * @param separator - Separator character to remove\n * @returns Parsed number or undefined if invalid\n * \n * @example\n * parseFormattedNumber('1,234,567.89') // => 1234567.89\n * parseFormattedNumber('1 234 567', ' ') // => 1234567\n */\nexport function parseFormattedNumber(\n str: string,\n separator: string = ','\n): number | undefined {\n if (!str || str === '') return undefined;\n const cleaned = str.split(separator).join('');\n const num = parseFloat(cleaned);\n return isNaN(num) ? undefined : num;\n}\n\n// =============================================================================\n// DATE UTILITIES\n// Helpers for date field operations.\n// =============================================================================\n\n/**\n * Safely parse a value to a Date object.\n * Handles Date objects, ISO strings, and timestamps.\n * \n * @param value - Value to parse (Date, string, number, or unknown)\n * @returns Date object or undefined if invalid\n * \n * @example\n * parseToDate(new Date()) // => Date\n * parseToDate('2024-01-15') // => Date\n * parseToDate(null) // => undefined\n */\nexport function parseToDate(value: unknown): Date | undefined {\n if (!value) return undefined;\n if (value instanceof Date) {\n return isNaN(value.getTime()) ? undefined : value;\n }\n if (typeof value === 'number') {\n const date = new Date(value);\n return isNaN(date.getTime()) ? undefined : date;\n }\n if (typeof value === 'string') {\n const date = new Date(value);\n return isNaN(date.getTime()) ? undefined : date;\n }\n return undefined;\n}\n"],"mappings":"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","names":[]}
|