@datum-cloud/datum-ui 1.3.1 → 1.4.0

package/dist/components/features/form/types/index.d.ts

@@ -1,651 +1,9 @@
-import type { z } from 'zod';
-import type { ButtonProps } from '../../..';
-import type { NormalizedFieldMeta, NormalizedFieldState, NormalizedFormInstance } from '../adapter-types';
-/**
- * Optional telemetry interface for form lifecycle tracking.
- * When provided, callbacks fire on form events (submit, success, error, etc.).
- * When omitted, forms work silently without any tracking.
- *
- * @example Wiring Sentry in the consuming app
- * ```tsx
- * const sentryTelemetry: FormTelemetry = {
- *   onSubmit: ({ formName, formId }) => trackFormSubmit({ formName, formId }),
- *   onSuccess: ({ formName, formId }) => trackFormSuccess({ formName, formId }),
- *   onError: ({ formName, formId, error }) => trackFormError({ formName, formId, error }),
- *   onValidationError: ({ formName, formId, fieldErrors }) => trackFormValidationError({ formName, formId, fieldErrors }),
- *   captureError: (error, context) => Sentry.captureException(error, { extra: context }),
- * };
- *
- * <Form.Root schema={schema} telemetry={sentryTelemetry} onSubmit={handleSubmit} />
- * ```
- */
-export interface FormTelemetry {
-    /** Called when a form submission is attempted */
-    onSubmit?: (info: {
-        formName: string;
-        formId?: string;
-    }) => void;
-    /** Called after a successful form submission */
-    onSuccess?: (info: {
-        formName: string;
-        formId?: string;
-    }) => void;
-    /** Called when a form submission throws an error */
-    onError?: (info: {
-        formName: string;
-        formId?: string;
-        error: Error;
-    }) => void;
-    /** Called when form validation fails */
-    onValidationError?: (info: {
-        formName: string;
-        formId?: string;
-        fieldErrors: Record<string, string[]>;
-    }) => void;
-    /** Called to capture an error with additional context (e.g. Sentry) */
-    captureError?: (error: Error, context: Record<string, unknown>) => void;
-}
-/**
- * Render props passed to Form.Root when using render function pattern
- */
-export interface FormRootRenderProps {
-    /** Normalized form instance */
-    form: NormalizedFormInstance;
-    /** All form fields with their normalized metadata */
-    fields: Record<string, NormalizedFieldMeta>;
-    /** Whether the form is currently submitting */
-    isSubmitting: boolean;
-    /** Whether any field value differs from its default value */
-    isDirty: boolean;
-    /** Whether the form currently passes validation */
-    isValid: boolean;
-    /** Whether the form has been submitted at least once */
-    isSubmitted: boolean;
-    /** Number of times the form has been submitted */
-    submitCount: number;
-    /** Record of which fields have been modified from defaults */
-    dirtyFields: Record<string, boolean>;
-    /** Record of which fields have been focused and blurred */
-    touchedFields: Record<string, boolean>;
-    /** Validation mode controlling when errors are displayed */
-    mode: 'onChange' | 'onBlur' | 'onSubmit';
-    /** Programmatically submit the form */
-    submit: () => void;
-    /** Reset form to default values */
-    reset: () => void;
-}
-export interface FormRootProps<T extends z.ZodType> {
-    /** Zod schema for validation */
-    schema: T;
-    /**
-     * Form children - can be either:
-     * - ReactNode: Standard form content
-     * - Render function: For accessing form state (form, fields, isSubmitting, etc.)
-     *
-     * @example Standard usage
-     * ```tsx
-     * <Form.Root schema={schema}>
-     *   <Form.Field name="email"><Form.Input /></Form.Field>
-     *   <Form.Submit>Save</Form.Submit>
-     * </Form.Root>
-     * ```
-     *
-     * @example Render function for form state access
-     * ```tsx
-     * <Form.Root schema={schema}>
-     *   {({ form, fields, isSubmitting }) => (
-     *     <>
-     *       <Form.Field name="email"><Form.Input /></Form.Field>
-     *       <Button disabled={isSubmitting} onClick={() => form.update({...})}>
-     *         Cancel
-     *       </Button>
-     *     </>
-     *   )}
-     * </Form.Root>
-     * ```
-     */
-    children: React.ReactNode | ((props: FormRootRenderProps) => React.ReactNode);
-    /** Client-side submit handler */
-    onSubmit?: (data: z.infer<T>) => void | Promise<void>;
-    /** React Router action path for server-side submission */
-    action?: string;
-    /** HTTP method for form submission */
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /**
-     * Custom form component to render (defaults to native `<form>`).
-     * Use to integrate with framework-specific forms (e.g. React Router's `<Form>`).
-     */
-    formComponent?: React.ElementType;
-    /** Unique form ID */
-    id?: string;
-    /**
-     * Form name for analytics and error tracking.
-     * Used in telemetry callbacks to identify which form the user interacted with.
-     * @example "http-proxy-create", "dns-zone-edit", "project-settings"
-     */
-    name?: string;
-    /**
-     * Optional telemetry callbacks for form lifecycle tracking.
-     * When omitted, forms work silently without any tracking.
-     */
-    telemetry?: FormTelemetry;
-    /** Default values for form fields */
-    defaultValues?: Partial<z.infer<T>>;
-    /** When to validate: onBlur, onChange, or onSubmit */
-    mode?: 'onBlur' | 'onChange' | 'onSubmit';
-    /**
-     * External submitting state - use when submission is handled externally (e.g., with useFetcher)
-     * When provided, this overrides the internal isSubmitting state
-     */
-    isSubmitting?: boolean;
-    /** Called when validation fails */
-    onError?: (errors: z.ZodError<z.infer<T>>) => void;
-    /** Called after successful submission */
-    onSuccess?: (data: z.infer<T>) => void;
-    /** Additional CSS classes */
-    className?: string;
-}
-/**
- * Render props passed to Form.Field when using render function pattern
- */
-export interface FormFieldRenderProps {
-    /** Normalized field state with value and control methods */
-    field: NormalizedFieldState;
-    /** Input control for programmatic value updates */
-    control: {
-        value: unknown;
-        change: (value: unknown) => void;
-        blur: () => void;
-        focus: () => void;
-    };
-    /** Field meta information */
-    meta: {
-        name: string;
-        id: string;
-        errors: string[];
-        required: boolean;
-        disabled: boolean;
-    };
-    /** Access to all form fields */
-    fields: Record<string, NormalizedFieldMeta>;
-    /** Form instance */
-    form: NormalizedFormInstance;
-    /** Whether form is currently submitting */
-    isSubmitting: boolean;
-}
-export interface FormFieldProps {
-    /** Field name - supports nested paths like "address.city" */
-    name: string;
-    /**
-     * Form children - can be either:
-     * - ReactNode: Standard input components (Form.Input, Form.Select, etc.)
-     * - Render function: For custom components needing field access
-     *
-     * @example Standard usage
-     * ```tsx
-     * <Form.Field name="email" label="Email">
-     *   <Form.Input type="email" />
-     * </Form.Field>
-     * ```
-     *
-     * @example Render function for custom components
-     * ```tsx
-     * <Form.Field name="role" label="Role">
-     *   {({ control, meta, fields }) => (
-     *     <CustomSelect
-     *       value={control.value}
-     *       onChange={control.change}
-     *     />
-     *   )}
-     * </Form.Field>
-     * ```
-     */
-    children: React.ReactNode | ((props: FormFieldRenderProps) => React.ReactNode);
-    /** Field label */
-    label?: string | React.ReactNode;
-    /** Helper description below the field */
-    description?: string | React.ReactNode;
-    /** Tooltip information */
-    tooltip?: string | React.ReactNode;
-    /** Mark field as required (shows asterisk) */
-    required?: boolean;
-    /** Disable the field */
-    disabled?: boolean;
-    /** Whether to render field errors (default: true) */
-    showErrors?: boolean;
-    /** Additional CSS classes for the field wrapper */
-    className?: string;
-    /** Additional CSS classes for the label */
-    labelClassName?: string;
-}
-export interface FormFieldContextValue {
-    /** Field name */
-    name: string;
-    /** Field ID for accessibility */
-    id: string;
-    /** Field errors */
-    errors: string[];
-    /** Whether the field is required */
-    required: boolean;
-    /** Whether the field is disabled */
-    disabled: boolean;
-    /** Normalized field state (available when adapter provides it) */
-    fieldState: NormalizedFieldState | null;
-}
-export interface FormInputProps extends Omit<React.ComponentProps<'input'>, 'name'> {
-    /** Input type */
-    type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local';
-}
-export interface FormTextareaProps extends Omit<React.ComponentProps<'textarea'>, 'name'> {
-    /** Number of visible rows */
-    rows?: number;
-}
-export interface FormSelectProps {
-    /** Placeholder text when no value selected */
-    placeholder?: string;
-    /** Disable the select */
-    disabled?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-    /** Select options as children */
-    children: React.ReactNode;
-}
-export interface FormSelectItemProps {
-    /** Option value */
-    value: string;
-    /** Option label */
-    children: React.ReactNode;
-    /** Disable this option */
-    disabled?: boolean;
-}
-export interface FormCheckboxProps {
-    /** Inline label next to checkbox */
-    label?: string;
-    /** Disable the checkbox */
-    disabled?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface FormSwitchProps {
-    /** Inline label next to switch */
-    label?: string;
-    /** Disable the switch */
-    disabled?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface FormRadioGroupProps {
-    /** Layout orientation */
-    orientation?: 'horizontal' | 'vertical';
-    /** Disable all radio items */
-    disabled?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-    /** Radio items as children */
-    children: React.ReactNode;
-}
-export interface FormRadioItemProps {
-    /** Radio value */
-    value: string;
-    /** Radio label */
-    label: string;
-    /** Optional description */
-    description?: string;
-    /** Disable this radio item */
-    disabled?: boolean;
-}
-export interface FormCopyBoxProps {
-    /** Display variant: 'default' shows Copy button, 'icon-only' shows icon */
-    variant?: 'default' | 'icon-only';
-    /** Custom className for the wrapper */
-    className?: string;
-    /** Custom className for the content area */
-    contentClassName?: string;
-    /** Custom className for the button */
-    buttonClassName?: string;
-    /** Placeholder text when value is empty */
-    placeholder?: string;
-}
-export interface FormSubmitProps extends ButtonProps {
-    /** Button content */
-    children: React.ReactNode;
-    /** Text to show while loading */
-    loadingText?: string;
-}
-export interface FormButtonProps {
-    /** Button content */
-    children: React.ReactNode;
-    /** Click handler */
-    onClick?: () => void;
-    /** Button variant */
-    type?: ButtonProps['type'];
-    /** Button theme */
-    theme?: ButtonProps['theme'];
-    /** Button size */
-    size?: ButtonProps['size'];
-    /** Disable the button */
-    disabled?: boolean;
-    /** Additional CSS classes */
-    className?: string;
-    /** Whether to disable the button when form is submitting (default: true) */
-    disableOnSubmit?: boolean;
-}
-export interface FormErrorProps {
-    /** Error message or render function */
-    children?: React.ReactNode | ((errors: string[]) => React.ReactNode);
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface FormDescriptionProps {
-    /** Description content */
-    children: React.ReactNode;
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface FormWhenProps {
-    /** Field name to watch */
-    field: string;
-    /** Render when field equals this value */
-    is?: unknown;
-    /** Render when field does not equal this value */
-    isNot?: unknown;
-    /** Render when field value is in array */
-    in?: unknown[];
-    /** Render when field value is not in array */
-    notIn?: unknown[];
-    /** Children to render conditionally */
-    children: React.ReactNode;
-}
-export interface FormFieldArrayProps {
-    /** Array field name */
-    name: string;
-    /** Render function with array helpers */
-    children: (props: FormFieldArrayRenderProps) => React.ReactNode;
-}
-export interface FormFieldArrayRenderProps {
-    /** Array of field items with id and key */
-    fields: Array<{
-        id: string;
-        key: string;
-        name: string;
-    }>;
-    /** Add a new item to the array */
-    append: (value?: Record<string, unknown>) => void;
-    /** Remove an item at index */
-    remove: (index: number) => void;
-    /** Move an item from one index to another */
-    move: (from: number, to: number) => void;
-}
-export interface FormCustomProps {
-    /** Render function with form context */
-    children: (context: FormCustomRenderProps) => React.ReactNode;
-}
-export interface FormCustomRenderProps {
-    /** Normalized form instance */
-    form: NormalizedFormInstance;
-    /** All field metadata */
-    fields: Record<string, NormalizedFieldMeta>;
-    /** Whether form is currently submitting */
-    isSubmitting: boolean;
-    /** Whether any field value differs from its default value */
-    isDirty: boolean;
-    /** Whether the form currently passes validation */
-    isValid: boolean;
-    /** Whether the form has been submitted at least once */
-    isSubmitted: boolean;
-    /** Number of times the form has been submitted */
-    submitCount: number;
-    /** Record of which fields have been modified from defaults */
-    dirtyFields: Record<string, boolean>;
-    /** Record of which fields have been focused and blurred */
-    touchedFields: Record<string, boolean>;
-    /** Submit the form programmatically */
-    submit: () => void;
-    /** Reset the form */
-    reset: () => void;
-}
-export interface StepConfig {
-    /** Unique step identifier */
-    id: string;
-    /** Step label displayed in navigation */
-    label: string;
-    /** Optional step description */
-    description?: string;
-    /** Zod schema for this step's validation */
-    schema: z.ZodType;
-}
-/**
- * Render props context passed to Form.Stepper children function
- */
-export interface FormStepperRenderProps {
-    /** All step configurations */
-    steps: StepConfig[];
-    /** Current step config */
-    current: StepConfig;
-    /** Current step index (0-based) */
-    currentIndex: number;
-    /** Go to next step (triggers validation) */
-    next: () => void;
-    /** Go to previous step (no validation) */
-    prev: () => void;
-    /** Go to specific step by ID (only backwards without validation) */
-    goTo: (stepId: string) => void;
-    /** Whether current step is first */
-    isFirst: boolean;
-    /** Whether current step is last */
-    isLast: boolean;
-    /** Get data from a specific step by ID */
-    getStepData: (stepId: string) => Record<string, unknown> | undefined;
-    /** Get all data from all completed steps */
-    getAllStepData: () => Record<string, unknown>;
-}
-export interface FormStepperProps {
-    /** Step configurations */
-    steps: StepConfig[];
-    /** Form children - can be ReactNode or render function for accessing stepper context */
-    children: React.ReactNode | ((props: FormStepperRenderProps) => React.ReactNode);
-    /** Called when all steps are completed */
-    onComplete: (data: Record<string, unknown>) => void | Promise<void>;
-    /** Called when step changes */
-    onStepChange?: (stepId: string, direction: 'next' | 'prev') => void;
-    /** Initial step ID */
-    initialStep?: string;
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface FormStepProps {
-    /** Step ID - must match a step in steps array */
-    id: string;
-    /** Step content */
-    children: React.ReactNode;
-}
-export interface StepperNavigationProps {
-    /** Navigation variant */
-    variant?: 'horizontal' | 'vertical';
-    /** Label orientation */
-    labelOrientation?: 'horizontal' | 'vertical';
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface StepperControlsProps {
-    /** Previous button label */
-    prevLabel?: string | ((isFirst: boolean) => string);
-    /** Next button label */
-    nextLabel?: string | ((isLast: boolean) => string);
-    /** Loading text shown when submitting (only on last step) */
-    loadingText?: string;
-    /** Whether to show previous button */
-    showPrev?: boolean;
-    /** External loading state - overrides internal isSubmitting */
-    loading?: boolean;
-    /** Disable both buttons */
-    disabled?: boolean;
-    /** Callback when previous button is clicked (not on first step) */
-    onPrev?: () => void;
-    /** Callback when cancel is clicked (first step only) */
-    onCancel?: () => void;
-    /** Additional CSS classes */
-    className?: string;
-}
-export interface StepperContextValue {
-    /** All step configurations */
-    steps: StepConfig[];
-    /** Current step config */
-    current: StepConfig;
-    /** Current step index */
-    currentIndex: number;
-    /** Go to next step (triggers validation) */
-    next: () => void;
-    /** Go to previous step (no validation) */
-    prev: () => void;
-    /** Go to specific step by ID (only backwards without validation) */
-    goTo: (stepId: string) => void;
-    /** Whether current step is first */
-    isFirst: boolean;
-    /** Whether current step is last */
-    isLast: boolean;
-    /** Stepperize utils */
-    utils: {
-        getIndex: (id: string) => number;
-    };
-}
-export interface FormContextValue<_T extends Record<string, unknown> = Record<string, unknown>> {
-    /** Normalized form instance */
-    form: NormalizedFormInstance;
-    /** Field metadata accessor */
-    fields: Record<string, NormalizedFieldMeta>;
-    /** Whether form is currently submitting */
-    isSubmitting: boolean;
-    /** Whether any field value differs from its default value */
-    isDirty: boolean;
-    /** Whether the form currently passes validation */
-    isValid: boolean;
-    /** Whether the form has been submitted at least once */
-    isSubmitted: boolean;
-    /** Number of times the form has been submitted */
-    submitCount: number;
-    /** Record of which fields have been modified from defaults */
-    dirtyFields: Record<string, boolean>;
-    /** Record of which fields have been focused and blurred */
-    touchedFields: Record<string, boolean>;
-    /** Validation mode controlling when errors are displayed */
-    mode: 'onChange' | 'onBlur' | 'onSubmit';
-    /** Array of field names that are display-touched (for error filtering) */
-    displayTouchedFields: string[];
-    /** Mark a field as display-touched */
-    markFieldTouched: (fieldName: string) => void;
-    /** Mark all fields as display-touched */
-    markAllFieldsTouched: () => void;
-    /** Submit the form */
-    submit: () => void;
-    /** Reset the form */
-    reset: () => void;
-    /** Form ID */
-    formId: string;
-}
-export interface UseFieldReturn {
-    /** Normalized field state */
-    field: NormalizedFieldState;
-    /** Input control for programmatic updates */
-    control: {
-        value: unknown;
-        change: (value: unknown) => void;
-        blur: () => void;
-        focus: () => void;
-    };
-    /** Field meta information */
-    meta: {
-        name: string;
-        id: string;
-        errors: string[];
-        required: boolean;
-        disabled: boolean;
-    };
-    /** Field errors */
-    errors: string[];
-}
-export interface UseWatchReturn<T = unknown> {
-    /** Current field value */
-    value: T;
-}
-export interface FormDialogProps<T extends z.ZodType> {
-    /** Controlled open state */
-    open?: boolean;
-    /** Callback when open state changes */
-    onOpenChange?: (open: boolean) => void;
-    /** Default open state for uncontrolled usage */
-    defaultOpen?: boolean;
-    /** Dialog title */
-    title: string;
-    /** Dialog description (optional) */
-    description?: string;
-    /** Trigger element to open the dialog */
-    trigger?: React.ReactNode;
-    /** Zod schema for validation */
-    schema: T;
-    /** Default form values */
-    defaultValues?: Partial<z.infer<T>>;
-    /** Client-side submit handler */
-    onSubmit?: (data: z.infer<T>) => void | Promise<void>;
-    /** Called after successful submission */
-    onSuccess?: (data: z.infer<T>) => void;
-    /** Called when validation fails */
-    onError?: (error: z.ZodError<z.infer<T>>) => void;
-    /** Submit button text (default: "Submit") */
-    submitText?: string;
-    /** Submit button text while loading */
-    submitTextLoading?: string;
-    /** Cancel button text (default: "Cancel") */
-    cancelText?: string;
-    /** Whether to show cancel button (default: true) */
-    showCancel?: boolean;
-    /** Submit button type variant */
-    submitType?: ButtonProps['type'];
-    /**
-     * External loading state - use when submission is handled by external mutation.
-     * When provided, this overrides the internal isSubmitting state.
-     * @example
-     * ```tsx
-     * const mutation = useCreateUser();
-     * <Form.Dialog loading={mutation.isPending} ... />
-     * ```
-     */
-    loading?: boolean;
-    /** Custom form element (e.g., React Router's Form). Defaults to native <form>. */
-    formComponent?: React.ElementType;
-    /** Optional telemetry callbacks for form submission tracking */
-    telemetry?: FormTelemetry;
-    /** Whether to show the header close (X) button (default: true) */
-    showHeaderClose?: boolean;
-    /** Dialog content className */
-    className?: string;
-    /** Form className */
-    formClassName?: string;
-    /**
-     * Dialog form children - can be either:
-     * - ReactNode: Standard form fields
-     * - Render function: For accessing form state (form, fields, isSubmitting, etc.)
-     *
-     * @example Standard usage
-     * ```tsx
-     * <Form.Dialog title="Add User" schema={schema} onSubmit={handleSubmit}>
-     *   <Form.Field name="email"><Form.Input type="email" /></Form.Field>
-     * </Form.Dialog>
-     * ```
-     *
-     * @example Render function for form state access
-     * ```tsx
-     * <Form.Dialog title="Edit User" schema={schema} onSubmit={handleSubmit}>
-     *   {({ form, fields, isSubmitting, reset }) => (
-     *     <>
-     *       <Form.Field name="email"><Form.Input type="email" /></Form.Field>
-     *       <Button onClick={reset} disabled={isSubmitting}>Reset</Button>
-     *     </>
-     *   )}
-     * </Form.Dialog>
-     * ```
-     */
-    children: React.ReactNode | ((props: FormRootRenderProps) => React.ReactNode);
-}
-export type { AutocompleteGroup, AutocompleteOption, AutocompleteProps, FormAutocompleteProps, } from '../../autocomplete/autocomplete.types';
-//# sourceMappingURL=index.d.ts.map
+export type { AutocompleteGroup, AutocompleteOption, AutocompleteProps, FormAutocompleteProps, } from '../../autocomplete';
+export type { FormContextValue } from './context';
+export type { FormActions, FormStateFields } from './core';
+export type { FormDialogProps } from './dialog';
+export type { FormFieldContextValue, FormFieldProps, FormFieldRenderProps, UseFieldReturn, UseWatchReturn, } from './field';
+export type { FormButtonProps, FormCheckboxProps, FormCopyBoxProps, FormCustomProps, FormCustomRenderProps, FormDescriptionProps, FormErrorProps, FormFieldArrayProps, FormFieldArrayRenderProps, FormInputProps, FormRadioGroupProps, FormRadioItemProps, FormSelectItemProps, FormSelectProps, FormSubmitProps, FormSwitchProps, FormTextareaProps, FormWhenProps, } from './inputs';
+export type { FormRootProps, FormRootRenderProps } from './root';
+export type { FormStepperProps, FormStepperRenderProps, FormStepProps, StepConfig, StepperContextValue, StepperControlsProps, StepperNavigationProps, StepperState, } from './stepper';
+export type { FormTelemetry } from './telemetry';