@formos/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FormEngineOptions, FormEngine } from '@formos/kernel';
+import { NormalizedSchemaV1 } from '@formos/schema';
+
+/**
+ * React-specific type definitions
+ * These extend kernel types with React integration
+ */
+
+/**
+ * Configuration for FormProvider.
+ *
+ * Extends {@link FormEngineOptions} with React-specific options.
+ *
+ * @public
+ * @stable
+ */
+interface FormProviderProps extends FormEngineOptions {
+    /** Normalized schema from @formos/schema */
+    schema: NormalizedSchemaV1;
+    /** Optional initial values for fields */
+    initialValues?: Record<string, unknown>;
+    /** Children components */
+    children: React.ReactNode;
+}
+/**
+ * Options for useField hook.
+ *
+ * @public
+ * @stable
+ */
+interface UseFieldOptions {
+    /** Custom validation trigger (overrides schema default) */
+    validateOnChange?: boolean;
+    /** Custom blur trigger (overrides schema default) */
+    validateOnBlur?: boolean;
+}
+/**
+ * Return type of useField hook.
+ *
+ * @public
+ * @stable
+ */
+interface UseFieldResult {
+    /** Current field value */
+    value: unknown;
+    /** Current error message (undefined if valid) */
+    error: string | undefined;
+    /** Whether field has been touched */
+    touched: boolean;
+    /** Whether field value differs from initial */
+    dirty: boolean;
+    /** Set field value */
+    setValue: (value: unknown) => Promise<void>;
+    /** Set field error */
+    setError: (error: string) => void;
+    /** Clear field error */
+    clearError: () => void;
+    /** Mark field as touched */
+    markTouched: () => void;
+    /** Validate field */
+    validate: () => Promise<boolean>;
+}
+/**
+ * Return type of useFormState hook.
+ *
+ * @public
+ * @stable
+ */
+interface UseFormStateResult {
+    /** All form values */
+    values: Record<string, unknown>;
+    /** All form errors */
+    errors: Record<string, string | undefined>;
+    /** Whether form is valid */
+    isValid: boolean;
+    /** Whether any field is dirty */
+    isDirty: boolean;
+    /** Whether form is currently submitting */
+    isSubmitting: boolean;
+}
+/**
+ * Return type of useForm hook.
+ *
+ * Provides form-level operations and state access.
+ * All multi-step methods return undefined for single-step forms.
+ *
+ * @public
+ * @stable
+ */
+interface UseFormResult {
+    /** Submit form (validates all fields, calls onSubmit if valid) */
+    submit: () => Promise<boolean>;
+    /** Reset form to initial state */
+    reset: () => void;
+    /** Validate entire form with optional trigger */
+    validate: (trigger?: "onChange" | "onBlur" | "onSubmit" | "manual") => Promise<boolean>;
+    /** Get all form values */
+    getValues: () => Record<string, unknown>;
+    /** Get single field value */
+    getValue: (fieldName: string) => unknown;
+    /** Set field value programmatically (triggers validation) */
+    setValue: (fieldName: string, value: unknown) => Promise<void>;
+    /** Get all field errors */
+    getErrors: () => Record<string, string | undefined>;
+    /** Get single field error */
+    getError: (fieldName: string) => string | undefined;
+    /** Set field error manually (e.g., from server) */
+    setError: (fieldName: string, error: string) => void;
+    /** Clear field error */
+    clearError: (fieldName: string) => void;
+    /** Check if form is valid (no errors) */
+    isValid: () => boolean;
+    /** Check if form/field is dirty (changed from initial) */
+    isDirty: (fieldName?: string) => boolean;
+    /** Check if field has been touched */
+    isTouched: (fieldName: string) => boolean;
+    /** Mark field as touched */
+    markTouched: (fieldName: string) => void;
+    /** Get current step index (0-based) */
+    getCurrentStep: () => number | undefined;
+    /** Get total number of steps */
+    getTotalSteps: () => number | undefined;
+    /** Go to next step (validates current step first) */
+    nextStep: (() => Promise<boolean>) | undefined;
+    /** Go to previous step */
+    prevStep: (() => void) | undefined;
+    /** Jump to specific step (validates if moving forward) */
+    goToStep: ((stepIndex: number) => Promise<boolean>) | undefined;
+    /** Check if can navigate to step */
+    canGoToStep: ((stepIndex: number) => boolean) | undefined;
+    /** Direct access to form engine */
+    engine: FormEngine;
+    /** Direct access to normalized schema */
+    schema: NormalizedSchemaV1;
+}
+/**
+ * Return type of useStep hook (for multi-step forms).
+ *
+ * @public
+ * @stable
+ */
+interface UseStepResult {
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Go to next step (validates current step first) */
+    nextStep: () => Promise<boolean>;
+    /** Go to previous step */
+    prevStep: () => void;
+    /** Jump to specific step */
+    goToStep: (stepIndex: number) => Promise<boolean>;
+    /** Check if can navigate to step */
+    canGoToStep: (stepIndex: number) => boolean;
+}
+
+/**
+ * Form provider component that creates and manages a form engine instance.
+ *
+ * Wrap your form components with this provider to enable form hooks.
+ * The provider creates a single form engine instance and makes it available
+ * via React context.
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```tsx
+ * import { FormProvider } from '@formos/react';
+ * import { normalizeSchema } from '@formos/schema';
+ *
+ * const schema = { version: 'v1', fields: [...] };
+ * const normalized = normalizeSchema(schema);
+ *
+ * function App() {
+ *   return (
+ *     <FormProvider
+ *       schema={normalized}
+ *       validators={{
+ *         required: (value) => value ? null : 'Required'
+ *       }}
+ *       onSubmit={async (values) => {
+ *         await api.post('/submit', values);
+ *       }}
+ *     >
+ *       <MyForm />
+ *     </FormProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function FormProvider({ schema, initialValues, children, ...engineOptions }: FormProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useForm hook - primary hook for form-level operations
+ */
+
+/**
+ * Primary hook for form-level operations.
+ *
+ * Provides access to form engine and form-level actions like submit,
+ * reset, validation, and multi-step navigation. Wraps @formos/kernel
+ * with React-idiomatic API.
+ *
+ * @returns Form operations and state access methods
+ * @throws {Error} If used outside FormProvider
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * Single-step form:
+ * ```tsx
+ * function LoginForm() {
+ *   const { submit, reset, isValid, isDirty } = useForm();
+ *
+ *   const handleSubmit = async (e: React.FormEvent) => {
+ *     e.preventDefault();
+ *     const success = await submit();
+ *     if (success) {
+ *       console.log('Login successful');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <EmailField />
+ *       <PasswordField />
+ *       <button type="submit" disabled={!isValid()}>
+ *         Submit
+ *       </button>
+ *       <button type="button" onClick={reset} disabled={!isDirty()}>
+ *         Reset
+ *       </button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Multi-step form:
+ * ```tsx
+ * function SignupWizard() {
+ *   const {
+ *     submit,
+ *     getCurrentStep,
+ *     getTotalSteps,
+ *     nextStep,
+ *     prevStep,
+ *     isValid
+ *   } = useForm();
+ *
+ *   const currentStep = getCurrentStep() ?? 0;
+ *   const totalSteps = getTotalSteps() ?? 1;
+ *
+ *   const handleNext = async () => {
+ *     const moved = await nextStep?.();
+ *     if (!moved) {
+ *       alert('Fix errors before proceeding');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <div>Step {currentStep + 1} of {totalSteps}</div>
+ *       <button onClick={prevStep} disabled={currentStep === 0}>
+ *         Previous
+ *       </button>
+ *       <button onClick={handleNext}>
+ *         {currentStep === totalSteps - 1 ? 'Submit' : 'Next'}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useForm(): UseFormResult;
+
+/**
+ * useField hook - field-level operations and state
+ */
+
+/**
+ * Hook for field-level operations and state management.
+ *
+ * Provides field value, error, touched/dirty state, and actions.
+ * Automatically subscribes to field changes for reactive updates.
+ *
+ * @param fieldName - Name of the field to manage
+ * @param options - Optional configuration for validation triggers
+ * @returns Field state and actions
+ * @throws {Error} If used outside FormProvider
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```tsx
+ * function EmailField() {
+ *   const {
+ *     value,
+ *     error,
+ *     touched,
+ *     setValue,
+ *     markTouched
+ *   } = useField('email', {
+ *     validateOnChange: true,
+ *     validateOnBlur: true
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         type="email"
+ *         value={String(value || '')}
+ *         onChange={(e) => setValue(e.target.value)}
+ *         onBlur={() => markTouched()}
+ *       />
+ *       {touched && error && <span>{error}</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useField(fieldName: string, options?: UseFieldOptions): UseFieldResult;
+
+/**
+ * useFormState hook - observe form-level state
+ */
+
+/**
+ * Hook for observing form-level state.
+ *
+ * Returns reactive state for all form values, errors, and validation status.
+ * Use this for displaying form-level information like submit button state
+ * or global error summaries.
+ *
+ * @returns Form state object
+ * @throws {Error} If used outside FormProvider
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```tsx
+ * function SubmitButton() {
+ *   const { isValid, isDirty, isSubmitting } = useFormState();
+ *
+ *   return (
+ *     <button
+ *       type="submit"
+ *       disabled={!isValid || !isDirty || isSubmitting}
+ *     >
+ *       {isSubmitting ? 'Submitting...' : 'Submit'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useFormState(): UseFormStateResult;
+
+/**
+ * useStep hook - multi-step form navigation
+ */
+
+/**
+ * Hook for multi-step form navigation.
+ *
+ * Only works with multi-step forms (schemas with `steps` defined).
+ * Provides current step information and navigation methods.
+ *
+ * @returns Step state and navigation methods
+ * @throws {Error} If used outside FormProvider or in single-step form
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```tsx
+ * function StepNavigation() {
+ *   const {
+ *     currentStep,
+ *     totalSteps,
+ *     nextStep,
+ *     prevStep,
+ *     canGoToStep
+ *   } = useStep();
+ *
+ *   const handleNext = async () => {
+ *     const moved = await nextStep();
+ *     if (!moved) {
+ *       alert('Please fix errors before proceeding');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Step {currentStep + 1} of {totalSteps}</p>
+ *       <button onClick={prevStep} disabled={currentStep === 0}>
+ *         Previous
+ *       </button>
+ *       <button onClick={handleNext}>
+ *         {currentStep === totalSteps - 1 ? 'Submit' : 'Next'}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useStep(): UseStepResult;
+
+export { FormProvider, type FormProviderProps, type UseFieldOptions, type UseFieldResult, type UseFormResult, type UseFormStateResult, type UseStepResult, useField, useForm, useFormState, useStep };