@datum-cloud/datum-ui 1.3.2 → 1.5.0

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

@@ -0,0 +1,20 @@
+import type { NormalizedFormState } from '../adapter-types';
+/**
+ * The canonical set of reactive form-state fields, shared by every render-prop
+ * and context surface. Composes the adapter's {@link NormalizedFormState} and
+ * adds the Form-tracked `isSubmitting` flag so the shape is defined once instead
+ * of being hand-duplicated across Form.Root / Form.Custom / FormContext.
+ */
+export interface FormStateFields extends NormalizedFormState {
+    /** Whether the form is currently submitting */
+    isSubmitting: boolean;
+}
+/**
+ * Imperative form actions shared across render-prop / context surfaces.
+ */
+export interface FormActions {
+    /** Programmatically submit the form */
+    submit: () => void;
+    /** Reset form to default values */
+    reset: () => void;
+}

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

@@ -0,0 +1,83 @@
+import type { z } from 'zod';
+import type { ButtonProps } from '../../..';
+import type { FormRootRenderProps } from './root';
+import type { FormTelemetry } from './telemetry';
+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);
+}

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

@@ -0,0 +1,113 @@
+import type { NormalizedFieldMeta, NormalizedFieldState, NormalizedFormInstance } from '../adapter-types';
+/**
+ * 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 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;
+}