@fogpipe/forma-react 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,668 @@
+import { FieldError, SelectOption, FieldDefinition, Forma, ValidationResult } from '@fogpipe/forma-core';
+export { ComputedField, FieldDefinition, FieldError, FieldType, Forma, PageDefinition, SelectOption, ValidationResult, ValidationRule } from '@fogpipe/forma-core';
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Type definitions for forma-react components
+ */
+
+/**
+ * Base props shared by all field components
+ */
+interface BaseFieldProps {
+    /** Field path/name */
+    name: string;
+    /** Field definition from the Forma spec */
+    field: FieldDefinition;
+    /** Current field value */
+    value: unknown;
+    /** Whether the field has been touched */
+    touched: boolean;
+    /** Whether the field is required */
+    required: boolean;
+    /** Whether the field is disabled */
+    disabled: boolean;
+    /** Validation errors for this field */
+    errors: FieldError[];
+    /** Handler for value changes */
+    onChange: (value: unknown) => void;
+    /** Handler for blur events */
+    onBlur: () => void;
+    /** Whether field is visible (always true since FormRenderer handles visibility) */
+    visible: boolean;
+    /** Whether field is enabled (inverse of disabled) */
+    enabled: boolean;
+    /** Display label from field definition */
+    label: string;
+    /** Help text or description from field definition */
+    description?: string;
+    /** Placeholder text from field definition */
+    placeholder?: string;
+}
+/**
+ * Props for text-based fields (text, email, password, url, textarea)
+ */
+interface TextFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "text" | "email" | "password" | "url" | "textarea";
+    value: string;
+    onChange: (value: string) => void;
+}
+/**
+ * Props for number fields
+ */
+interface NumberFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "number";
+    value: number | null;
+    onChange: (value: number | null) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Props for integer fields
+ */
+interface IntegerFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "integer";
+    value: number | null;
+    onChange: (value: number | null) => void;
+    min?: number;
+    max?: number;
+}
+/**
+ * Props for boolean fields
+ */
+interface BooleanFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "boolean";
+    value: boolean;
+    onChange: (value: boolean) => void;
+}
+/**
+ * Props for date fields
+ */
+interface DateFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "date";
+    value: string | null;
+    onChange: (value: string | null) => void;
+}
+/**
+ * Props for datetime fields
+ */
+interface DateTimeFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "datetime";
+    value: string | null;
+    onChange: (value: string | null) => void;
+}
+/**
+ * Props for select fields (single selection)
+ */
+interface SelectFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "select";
+    value: string | null;
+    onChange: (value: string | null) => void;
+    options: SelectOption[];
+}
+/**
+ * Props for multi-select fields
+ */
+interface MultiSelectFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "multiselect";
+    value: string[];
+    onChange: (value: string[]) => void;
+    options: SelectOption[];
+}
+/**
+ * Union type for all selection-based field props
+ */
+type SelectionFieldProps = SelectFieldProps | MultiSelectFieldProps;
+/**
+ * Array item field props returned by getItemFieldProps
+ */
+interface ArrayItemFieldPropsResult {
+    /** Field path/name */
+    name: string;
+    /** Current field value */
+    value: unknown;
+    /** Field type */
+    type: string;
+    /** Display label */
+    label: string;
+    /** Help text or description */
+    description?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether field is visible */
+    visible: boolean;
+    /** Whether field is enabled */
+    enabled: boolean;
+    /** Whether field is required */
+    required: boolean;
+    /** Whether field has been touched */
+    touched: boolean;
+    /** Validation errors for this field */
+    errors: FieldError[];
+    /** Handler for value changes */
+    onChange: (value: unknown) => void;
+    /** Handler for blur events */
+    onBlur: () => void;
+    /** Item index in the array */
+    itemIndex: number;
+    /** Field name within the item */
+    fieldName: string;
+    /** Options for select fields */
+    options?: SelectOption[];
+}
+/**
+ * Array manipulation helpers
+ */
+interface ArrayHelpers {
+    /** Current array items */
+    items: unknown[];
+    /** Add item to end of array */
+    push: (item?: unknown) => void;
+    /** Insert item at specific index */
+    insert: (index: number, item: unknown) => void;
+    /** Remove item at index */
+    remove: (index: number) => void;
+    /** Move item from one index to another */
+    move: (from: number, to: number) => void;
+    /** Swap items at two indices */
+    swap: (indexA: number, indexB: number) => void;
+    /** Get field props for an item field */
+    getItemFieldProps: (index: number, fieldName: string) => ArrayItemFieldPropsResult;
+    /** Minimum number of items allowed */
+    minItems: number;
+    /** Maximum number of items allowed */
+    maxItems: number;
+    /** Whether more items can be added */
+    canAdd: boolean;
+    /** Whether items can be removed */
+    canRemove: boolean;
+}
+/**
+ * Props for array fields
+ */
+interface ArrayFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "array";
+    value: unknown[];
+    onChange: (value: unknown[]) => void;
+    helpers: ArrayHelpers;
+    /** Item field definitions keyed by field name */
+    itemFields: Record<string, FieldDefinition>;
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * Props for object fields
+ */
+interface ObjectFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "object";
+    value: Record<string, unknown>;
+    onChange: (value: Record<string, unknown>) => void;
+}
+/**
+ * Props for computed fields (read-only)
+ */
+interface ComputedFieldProps extends Omit<BaseFieldProps, "onChange"> {
+    fieldType: "computed";
+    value: unknown;
+    expression: string;
+    onChange?: never;
+}
+/**
+ * Props for array item fields (within array context)
+ */
+interface ArrayItemFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    /** The field type */
+    fieldType: string;
+    /** Current value */
+    value: unknown;
+    /** Change handler */
+    onChange: (value: unknown) => void;
+    /** Item index in the array */
+    itemIndex: number;
+    /** Field name within the item */
+    fieldName: string;
+}
+/**
+ * Union of all field prop types
+ */
+type FieldProps = TextFieldProps | NumberFieldProps | IntegerFieldProps | BooleanFieldProps | DateFieldProps | DateTimeFieldProps | SelectFieldProps | MultiSelectFieldProps | ArrayFieldProps | ObjectFieldProps | ComputedFieldProps;
+/**
+ * Map of field types to React components
+ * Components receive wrapper props with { field, spec } structure
+ */
+interface ComponentMap {
+    text?: React.ComponentType<TextComponentProps>;
+    email?: React.ComponentType<TextComponentProps>;
+    password?: React.ComponentType<TextComponentProps>;
+    url?: React.ComponentType<TextComponentProps>;
+    textarea?: React.ComponentType<TextComponentProps>;
+    number?: React.ComponentType<NumberComponentProps>;
+    integer?: React.ComponentType<IntegerComponentProps>;
+    boolean?: React.ComponentType<BooleanComponentProps>;
+    date?: React.ComponentType<DateComponentProps>;
+    datetime?: React.ComponentType<DateTimeComponentProps>;
+    select?: React.ComponentType<SelectComponentProps>;
+    multiselect?: React.ComponentType<MultiSelectComponentProps>;
+    array?: React.ComponentType<ArrayComponentProps>;
+    object?: React.ComponentType<ObjectComponentProps>;
+    computed?: React.ComponentType<ComputedComponentProps>;
+    fallback?: React.ComponentType<FieldComponentProps>;
+}
+/**
+ * Props for custom layout components
+ */
+interface LayoutProps {
+    children: React.ReactNode;
+    onSubmit: () => void;
+    isSubmitting: boolean;
+    isValid: boolean;
+}
+/**
+ * Props for custom field wrapper components
+ */
+interface FieldWrapperProps {
+    /** Field path/identifier */
+    fieldPath: string;
+    /** Field definition from the Forma spec */
+    field: FieldDefinition;
+    children: React.ReactNode;
+    errors: FieldError[];
+    touched: boolean;
+    required: boolean;
+    visible: boolean;
+}
+/**
+ * Props for page wrapper components (multi-page forms)
+ */
+interface PageWrapperProps {
+    title: string;
+    description?: string;
+    children: React.ReactNode;
+    pageIndex: number;
+    totalPages: number;
+}
+/**
+ * Wrapper type that includes spec alongside field props
+ * Components receive { field, spec } instead of just FieldProps
+ */
+interface TextComponentProps {
+    field: TextFieldProps;
+    spec: Forma;
+}
+interface NumberComponentProps {
+    field: NumberFieldProps;
+    spec: Forma;
+}
+interface IntegerComponentProps {
+    field: IntegerFieldProps;
+    spec: Forma;
+}
+interface BooleanComponentProps {
+    field: BooleanFieldProps;
+    spec: Forma;
+}
+interface DateComponentProps {
+    field: DateFieldProps;
+    spec: Forma;
+}
+interface DateTimeComponentProps {
+    field: DateTimeFieldProps;
+    spec: Forma;
+}
+interface SelectComponentProps {
+    field: SelectFieldProps;
+    spec: Forma;
+}
+interface MultiSelectComponentProps {
+    field: MultiSelectFieldProps;
+    spec: Forma;
+}
+interface ArrayComponentProps {
+    field: ArrayFieldProps;
+    spec: Forma;
+}
+interface ObjectComponentProps {
+    field: ObjectFieldProps;
+    spec: Forma;
+}
+interface ComputedComponentProps {
+    field: ComputedFieldProps;
+    spec: Forma;
+}
+/**
+ * Generic field component props (for fallback/dynamic components)
+ */
+interface FieldComponentProps {
+    field: FieldProps;
+    spec: Forma;
+}
+
+/**
+ * Field props returned by getFieldProps()
+ * Contains all field information needed for rendering
+ */
+interface GetFieldPropsResult {
+    /** Field path/name */
+    name: string;
+    /** Current field value */
+    value: unknown;
+    /** Field type */
+    type: string;
+    /** Display label */
+    label: string;
+    /** Help text or description */
+    description?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether field is visible */
+    visible: boolean;
+    /** Whether field is enabled (not disabled) */
+    enabled: boolean;
+    /** Whether field is required */
+    required: boolean;
+    /** Whether field has been touched */
+    touched: boolean;
+    /** Validation errors for this field */
+    errors: FieldError[];
+    /** Handler for value changes */
+    onChange: (value: unknown) => void;
+    /** Handler for blur events */
+    onBlur: () => void;
+    /** ARIA: Indicates the field has validation errors */
+    "aria-invalid"?: boolean;
+    /** ARIA: ID of element(s) describing validation errors */
+    "aria-describedby"?: string;
+    /** ARIA: Indicates the field is required */
+    "aria-required"?: boolean;
+}
+/**
+ * Select field props returned by getSelectFieldProps()
+ */
+interface GetSelectFieldPropsResult extends GetFieldPropsResult {
+    /** Available options for selection */
+    options: SelectOption[];
+}
+/**
+ * Array helpers returned by getArrayHelpers()
+ */
+interface GetArrayHelpersResult {
+    /** Current array items */
+    items: unknown[];
+    /** Add item to end of array */
+    push: (item: unknown) => void;
+    /** Remove item at index */
+    remove: (index: number) => void;
+    /** Move item from one index to another */
+    move: (from: number, to: number) => void;
+    /** Swap items at two indices */
+    swap: (indexA: number, indexB: number) => void;
+    /** Insert item at specific index */
+    insert: (index: number, item: unknown) => void;
+    /** Get field props for an item field */
+    getItemFieldProps: (index: number, fieldName: string) => GetFieldPropsResult;
+    /** Minimum number of items allowed */
+    minItems: number;
+    /** Maximum number of items allowed */
+    maxItems: number;
+    /** Whether more items can be added */
+    canAdd: boolean;
+    /** Whether items can be removed */
+    canRemove: boolean;
+}
+/**
+ * @deprecated Use GetFieldPropsResult instead
+ */
+type LegacyFieldProps = GetFieldPropsResult;
+
+/**
+ * useForma Hook
+ *
+ * Main hook for managing Forma form state.
+ * This is a placeholder - the full implementation will be migrated from formidable.
+ */
+
+/**
+ * Options for useForma hook
+ */
+interface UseFormaOptions {
+    /** The Forma specification */
+    spec: Forma;
+    /** Initial form data */
+    initialData?: Record<string, unknown>;
+    /** Submit handler */
+    onSubmit?: (data: Record<string, unknown>) => void | Promise<void>;
+    /** Change handler */
+    onChange?: (data: Record<string, unknown>, computed?: Record<string, unknown>) => void;
+    /** When to validate: on change, blur, or submit only */
+    validateOn?: "change" | "blur" | "submit";
+    /** Additional reference data to merge with spec.referenceData */
+    referenceData?: Record<string, unknown>;
+    /**
+     * Debounce validation by this many milliseconds.
+     * Useful for large forms to improve performance.
+     * Set to 0 (default) for immediate validation.
+     */
+    validationDebounceMs?: number;
+}
+/**
+ * Page state for multi-page forms
+ */
+interface PageState {
+    id: string;
+    title: string;
+    description?: string;
+    visible: boolean;
+    fields: string[];
+}
+/**
+ * Wizard navigation helpers
+ */
+interface WizardHelpers {
+    pages: PageState[];
+    currentPageIndex: number;
+    currentPage: PageState | null;
+    goToPage: (index: number) => void;
+    nextPage: () => void;
+    previousPage: () => void;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    canProceed: boolean;
+    isLastPage: boolean;
+    touchCurrentPageFields: () => void;
+    validateCurrentPage: () => boolean;
+}
+/**
+ * Return type of useForma hook
+ */
+interface UseFormaReturn {
+    /** Current form data */
+    data: Record<string, unknown>;
+    /** Computed field values */
+    computed: Record<string, unknown>;
+    /** Field visibility map */
+    visibility: Record<string, boolean>;
+    /** Field required state map */
+    required: Record<string, boolean>;
+    /** Field enabled state map */
+    enabled: Record<string, boolean>;
+    /** Field touched state map */
+    touched: Record<string, boolean>;
+    /** Validation errors */
+    errors: FieldError[];
+    /** Whether form is valid */
+    isValid: boolean;
+    /** Whether form is submitting */
+    isSubmitting: boolean;
+    /** Whether form has been submitted */
+    isSubmitted: boolean;
+    /** Whether any field has been modified */
+    isDirty: boolean;
+    /** The Forma spec */
+    spec: Forma;
+    /** Wizard helpers (if multi-page) */
+    wizard: WizardHelpers | null;
+    /** Set a field value */
+    setFieldValue: (path: string, value: unknown) => void;
+    /** Set a field as touched */
+    setFieldTouched: (path: string, touched?: boolean) => void;
+    /** Set multiple values */
+    setValues: (values: Record<string, unknown>) => void;
+    /** Validate a single field */
+    validateField: (path: string) => FieldError[];
+    /** Validate entire form */
+    validateForm: () => ValidationResult;
+    /** Submit the form */
+    submitForm: () => Promise<void>;
+    /** Reset the form */
+    resetForm: () => void;
+    /** Get props for any field */
+    getFieldProps: (path: string) => GetFieldPropsResult;
+    /** Get props for select field (includes options) */
+    getSelectFieldProps: (path: string) => GetSelectFieldPropsResult;
+    /** Get array helpers for array field */
+    getArrayHelpers: (path: string) => GetArrayHelpersResult;
+}
+/**
+ * Main Forma hook
+ */
+declare function useForma(options: UseFormaOptions): UseFormaReturn;
+
+/**
+ * FormRenderer Component
+ *
+ * Renders a complete form from a Forma specification.
+ * Supports single-page and multi-page (wizard) forms.
+ */
+
+/**
+ * Props for FormRenderer component
+ */
+interface FormRendererProps {
+    /** The Forma specification */
+    spec: Forma;
+    /** Initial form data */
+    initialData?: Record<string, unknown>;
+    /** Submit handler */
+    onSubmit?: (data: Record<string, unknown>) => void | Promise<void>;
+    /** Change handler */
+    onChange?: (data: Record<string, unknown>, computed?: Record<string, unknown>) => void;
+    /** Component map for rendering fields */
+    components: ComponentMap;
+    /** Custom layout component */
+    layout?: React__default.ComponentType<LayoutProps>;
+    /** Custom field wrapper component */
+    fieldWrapper?: React__default.ComponentType<FieldWrapperProps>;
+    /** Custom page wrapper component */
+    pageWrapper?: React__default.ComponentType<PageWrapperProps>;
+    /** When to validate */
+    validateOn?: "change" | "blur" | "submit";
+    /** Current page for controlled wizard */
+    page?: number;
+}
+/**
+ * Imperative handle for FormRenderer
+ */
+interface FormRendererHandle {
+    submitForm: () => Promise<void>;
+    resetForm: () => void;
+    validateForm: () => ValidationResult;
+    focusField: (path: string) => void;
+    focusFirstError: () => void;
+    getValues: () => Record<string, unknown>;
+    setValues: (values: Record<string, unknown>) => void;
+    isValid: boolean;
+    isDirty: boolean;
+}
+/**
+ * FormRenderer component
+ */
+declare const FormRenderer: React__default.ForwardRefExoticComponent<FormRendererProps & React__default.RefAttributes<FormRendererHandle>>;
+
+/**
+ * Props for FieldRenderer component
+ */
+interface FieldRendererProps {
+    /** Field path (e.g., "firstName" or "address.city") */
+    fieldPath: string;
+    /** Component map for rendering fields */
+    components: ComponentMap;
+    /** Optional class name for the wrapper */
+    className?: string;
+}
+/**
+ * FieldRenderer component
+ *
+ * @example
+ * ```tsx
+ * // Render a specific field with custom components
+ * <FieldRenderer fieldPath="email" components={componentMap} />
+ * ```
+ */
+declare function FieldRenderer({ fieldPath, components, className }: FieldRendererProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * FormaErrorBoundary Component
+ *
+ * Error boundary for catching render errors in form components.
+ * Provides graceful error handling and recovery options.
+ */
+
+/**
+ * Props for FormaErrorBoundary component
+ */
+interface FormaErrorBoundaryProps {
+    /** Child components to render */
+    children: React__default.ReactNode;
+    /** Custom fallback UI to show when an error occurs */
+    fallback?: React__default.ReactNode | ((error: Error, reset: () => void) => React__default.ReactNode);
+    /** Callback when an error is caught */
+    onError?: (error: Error, errorInfo: React__default.ErrorInfo) => void;
+    /** Key to reset the error boundary (change this to reset) */
+    resetKey?: string | number;
+}
+/**
+ * State for FormaErrorBoundary component
+ */
+interface FormaErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for Forma forms
+ *
+ * Catches JavaScript errors in child component tree and displays
+ * a fallback UI instead of crashing the entire application.
+ *
+ * @example
+ * ```tsx
+ * <FormaErrorBoundary
+ *   fallback={<div>Form error occurred</div>}
+ *   onError={(error) => logError(error)}
+ * >
+ *   <FormRenderer spec={spec} components={components} />
+ * </FormaErrorBoundary>
+ * ```
+ */
+declare class FormaErrorBoundary extends React__default.Component<FormaErrorBoundaryProps, FormaErrorBoundaryState> {
+    constructor(props: FormaErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): FormaErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React__default.ErrorInfo): void;
+    componentDidUpdate(prevProps: FormaErrorBoundaryProps): void;
+    reset: () => void;
+    render(): React__default.ReactNode;
+}
+
+/**
+ * Context for sharing form state across components
+ */
+declare const FormaContext: React$1.Context<UseFormaReturn | null>;
+/**
+ * Hook to access Forma context
+ * @throws Error if used outside of FormaContext.Provider
+ */
+declare function useFormaContext(): UseFormaReturn;
+
+export { type ArrayComponentProps, type ArrayFieldProps, type ArrayHelpers, type ArrayItemFieldProps, type ArrayItemFieldPropsResult, type BaseFieldProps, type BooleanComponentProps, type BooleanFieldProps, type ComponentMap, type ComputedComponentProps, type ComputedFieldProps, type DateComponentProps, type DateFieldProps, type DateTimeComponentProps, type DateTimeFieldProps, type FieldComponentProps, type FieldProps, FieldRenderer, type FieldRendererProps, type FieldWrapperProps, FormRenderer, type FormRendererHandle, type FormRendererProps, type UseFormaReturn as FormState, FormaContext, FormaErrorBoundary, type FormaErrorBoundaryProps, type GetArrayHelpersResult, type GetFieldPropsResult, type GetSelectFieldPropsResult, type IntegerComponentProps, type IntegerFieldProps, type LayoutProps, type LegacyFieldProps, type MultiSelectComponentProps, type MultiSelectFieldProps, type NumberComponentProps, type NumberFieldProps, type ObjectComponentProps, type ObjectFieldProps, type PageState, type PageWrapperProps, type SelectComponentProps, type SelectFieldProps, type SelectionFieldProps, type TextComponentProps, type TextFieldProps, type UseFormaOptions, type UseFormaReturn, type WizardHelpers, useForma, useFormaContext };