@fogpipe/forma-react 0.17.1 → 0.19.0

package/README.md

@@ -354,6 +354,88 @@ The error boundary supports:
 - `onError` callback for logging
 - `resetKey` prop to reset error state
 
+## Default Components
+
+Don't want to build every field component yourself? The default component library gives you a working form in 2 lines:
+
+```tsx
+import { DefaultFormRenderer } from "@fogpipe/forma-react/defaults";
+import "@fogpipe/forma-react/defaults/styles.css";
+
+<DefaultFormRenderer spec={formaSpec} onSubmit={handleSubmit} />;
+```
+
+This renders a fully styled, accessible form with all 18 field types, error handling, and wizard support — zero configuration.
+
+### Override Individual Components
+
+Swap any component while keeping the rest:
+
+```tsx
+import { FormRenderer } from "@fogpipe/forma-react";
+import {
+  defaultComponentMap,
+  defaultFieldWrapper,
+  defaultLayout,
+} from "@fogpipe/forma-react/defaults";
+import "@fogpipe/forma-react/defaults/styles.css";
+
+const components = { ...defaultComponentMap, select: MyFancySelect };
+
+<FormRenderer
+  spec={formaSpec}
+  components={components}
+  fieldWrapper={defaultFieldWrapper}
+  layout={defaultLayout}
+  onSubmit={handleSubmit}
+/>;
+```
+
+### Wizard Forms
+
+Enable wizard layout for multi-page forms:
+
+```tsx
+<DefaultFormRenderer spec={wizardSpec} onSubmit={handleSubmit} wizardLayout />
+```
+
+### Theming
+
+Override CSS variables to customize the look:
+
+```css
+:root {
+  --forma-color-primary: #7c3aed;
+  --forma-color-error: #e11d48;
+  --forma-radius: 12px;
+  --forma-font-family: "Inter", sans-serif;
+}
+```
+
+Dark mode works via `[data-theme="dark"]` attribute or `prefers-color-scheme: dark` media query.
+
+### Component Reference
+
+| Field Type | Component | Renders |
+|---|---|---|
+| `text`, `email`, `phone`, `url`, `password` | TextInput | `<input>` with type mapping |
+| `textarea` | TextareaInput | `<textarea>` |
+| `number` | NumberInput | `<input type="number">` with parseFloat |
+| `integer` | IntegerInput | `<input type="number">` with parseInt |
+| `boolean` | BooleanInput | Custom styled checkbox |
+| `date` | DateInput | `<input type="date">` |
+| `datetime` | DateTimeInput | `<input type="datetime-local">` |
+| `select` | SelectInput | Native `<select>` with custom arrow |
+| `multiselect` | MultiSelectInput | Checkbox group |
+| `array` | ArrayField | Item list with Add/Remove |
+| `object` | ObjectField | `<fieldset>` container |
+| `computed` | ComputedDisplay | Read-only `<output>` |
+| `display` | DisplayField | Static content `<div>` |
+| `matrix` | MatrixField | `<table>` with radio/checkbox cells |
+| `fallback` | FallbackField | Text input + dev warning |
+
+See the [full documentation](https://docs.formidable.fogpipe.com/forma-react/default-components) for theming details, all CSS variables, and advanced usage.
+
 ## License
 
 MIT

package/dist/FormRenderer-B7qwG4to.d.ts

@@ -0,0 +1,566 @@
+import React__default from 'react';
+import { FieldError, SelectOption, FieldDefinition, Forma, FormatOptions, MatrixColumn, ValidationResult } from '@fogpipe/forma-core';
+
+/**
+ * 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 (always populated — use visibleErrors for display) */
+    errors: FieldError[];
+    /**
+     * Errors filtered by interaction state (touched or submitted).
+     * Use this for displaying errors in the UI to avoid showing errors on untouched fields.
+     */
+    visibleErrors: 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;
+    /** Whether field is readonly (visible, not editable, value still submitted) */
+    readonly: boolean;
+    /** Display label from field definition */
+    label: string;
+    /** Help text or description from field definition */
+    description?: string;
+    /** Placeholder text from field definition */
+    placeholder?: string;
+    /** Prefix adorner text (e.g., "$") - only for adornable field types */
+    prefix?: string;
+    /** Suffix adorner text (e.g., "kg") - only for adornable field types */
+    suffix?: string;
+    /** Presentation variant hint (e.g., "slider", "radio", "nps") */
+    variant?: string;
+    /** Variant-specific configuration */
+    variantConfig?: Record<string, unknown>;
+}
+/**
+ * Props for text-based fields (text, email, password, url, textarea)
+ */
+interface TextFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "text" | "phone" | "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;
+    step?: 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>;
+    /** Explicit ordering for itemFields (jsonb does not preserve object key order) */
+    itemFieldOrder?: string[];
+    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;
+    /** Display format string (e.g., "currency", "percent", "decimal(2)") */
+    format?: string;
+    /** Resolved format options (locale, currency) for number/date formatting */
+    formatOptions?: FormatOptions;
+    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;
+}
+/**
+ * Props for display fields (read-only presentation content)
+ */
+interface DisplayFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "display";
+    /** Static content (markdown/text) */
+    content?: string;
+    /** Computed source value (resolved by useForma from display field's source property) */
+    sourceValue?: unknown;
+    /** Display format string */
+    format?: string;
+    /** Resolved format options (locale, currency) for number/date formatting */
+    formatOptions?: FormatOptions;
+    /** No onChange - display fields are read-only */
+    onChange?: never;
+    value?: never;
+}
+/**
+ * Props for matrix/grid fields
+ */
+interface MatrixFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "matrix";
+    /** Current matrix value: row ID → selected column value(s) */
+    value: Record<string, string | number | string[] | number[]> | null;
+    onChange: (value: Record<string, string | number | string[] | number[]>) => void;
+    /** Row definitions with visibility state */
+    rows: Array<{
+        id: string;
+        label: string;
+        visible: boolean;
+    }>;
+    /** Column definitions (shared options for all rows) */
+    columns: MatrixColumn[];
+    /** Whether multiple selections per row are allowed */
+    multiSelect: boolean;
+}
+/**
+ * Union of all field prop types
+ */
+type FieldProps = TextFieldProps | NumberFieldProps | IntegerFieldProps | BooleanFieldProps | DateFieldProps | DateTimeFieldProps | SelectFieldProps | MultiSelectFieldProps | ArrayFieldProps | ObjectFieldProps | ComputedFieldProps | DisplayFieldProps | MatrixFieldProps;
+/**
+ * Map of field types to React components
+ * Components receive wrapper props with { field, spec } structure
+ */
+interface ComponentMap {
+    text?: React.ComponentType<TextComponentProps>;
+    phone?: 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>;
+    display?: React.ComponentType<DisplayComponentProps>;
+    matrix?: React.ComponentType<MatrixComponentProps>;
+    fallback?: React.ComponentType<FieldComponentProps>;
+}
+/**
+ * Props for custom layout components
+ */
+interface LayoutProps {
+    children: React.ReactNode;
+    onSubmit: (e?: React.FormEvent) => 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;
+    /**
+     * Whether to show the required indicator in the UI.
+     * False for boolean fields since false is a valid answer.
+     */
+    showRequiredIndicator: 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;
+}
+interface DisplayComponentProps {
+    field: DisplayFieldProps;
+    spec: Forma;
+}
+interface MatrixComponentProps {
+    field: MatrixFieldProps;
+    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 readonly (visible, not editable, value still submitted) */
+    readonly: boolean;
+    /** Whether field is required (for validation) */
+    required: boolean;
+    /**
+     * Whether to show the required indicator in the UI.
+     * False for boolean fields since false is a valid answer.
+     */
+    showRequiredIndicator: boolean;
+    /** Whether field has been touched */
+    touched: boolean;
+    /** Validation errors for this field (always populated — use visibleErrors for display) */
+    errors: FieldError[];
+    /**
+     * Errors filtered by interaction state (touched or submitted).
+     * Use this for displaying errors in the UI to avoid showing errors on untouched fields.
+     */
+    visibleErrors: 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;
+    /** Options for select/multiselect fields (filtered by visibleWhen) */
+    options?: SelectOption[];
+    /** Prefix adorner text (e.g., "$") */
+    prefix?: string;
+    /** Suffix adorner text (e.g., "kg") */
+    suffix?: string;
+    /** Presentation variant hint */
+    variant?: string;
+    /** Variant-specific configuration */
+    variantConfig?: Record<string, unknown>;
+}
+/**
+ * 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;
+
+/**
+ * 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;
+    /** Format options for number/currency/date display (overrides spec.meta.locale/currency) */
+    formatOptions?: FormatOptions;
+}
+/**
+ * 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>>;
+
+export { type ArrayFieldProps as A, type BaseFieldProps as B, type ComponentMap as C, type DateFieldProps as D, type MatrixFieldProps as E, FormRenderer as F, type GetFieldPropsResult as G, type MatrixComponentProps as H, type IntegerFieldProps as I, type LayoutProps as J, type FieldWrapperProps as K, type LegacyFieldProps as L, type MultiSelectFieldProps as M, type NumberFieldProps as N, type ObjectFieldProps as O, type PageWrapperProps as P, type SelectFieldProps as S, type TextFieldProps as T, type GetSelectFieldPropsResult as a, type GetArrayHelpersResult as b, type FormRendererProps as c, type FormRendererHandle as d, type FieldProps as e, type BooleanFieldProps as f, type DateTimeFieldProps as g, type SelectionFieldProps as h, type ComputedFieldProps as i, type ArrayHelpers as j, type ArrayItemFieldProps as k, type ArrayItemFieldPropsResult as l, type FieldComponentProps as m, type TextComponentProps as n, type NumberComponentProps as o, type IntegerComponentProps as p, type BooleanComponentProps as q, type DateComponentProps as r, type DateTimeComponentProps as s, type SelectComponentProps as t, type MultiSelectComponentProps as u, type ArrayComponentProps as v, type ObjectComponentProps as w, type ComputedComponentProps as x, type DisplayFieldProps as y, type DisplayComponentProps as z };