@fogpipe/forma-react 0.17.0 → 0.18.0

package/README.md

@@ -199,13 +199,13 @@ The event system lets you observe form lifecycle events for side effects like an
 
 ### Available Events
 
-| Event          | Description                                             |
-| -------------- | ------------------------------------------------------- |
-| `fieldChanged` | Fires after a field value changes                       |
-| `preSubmit`    | Fires before validation; `data` is mutable              |
-| `postSubmit`   | Fires after submission (success, error, or invalid)     |
-| `pageChanged`  | Fires when wizard page changes                          |
-| `formReset`    | Fires after `resetForm()` completes                     |
+| Event          | Description                                         |
+| -------------- | --------------------------------------------------- |
+| `fieldChanged` | Fires after a field value changes                   |
+| `preSubmit`    | Fires before validation; `data` is mutable          |
+| `postSubmit`   | Fires after submission (success, error, or invalid) |
+| `pageChanged`  | Fires when wizard page changes                      |
+| `formReset`    | Fires after `resetForm()` completes                 |
 
 ### Declarative Registration
 
@@ -217,7 +217,10 @@ const forma = useForma({
   onSubmit: handleSubmit,
   on: {
     fieldChanged: (event) => {
-      analytics.track("field_changed", { path: event.path, source: event.source });
+      analytics.track("field_changed", {
+        path: event.path,
+        source: event.source,
+      });
     },
     preSubmit: async (event) => {
       event.data.token = await getCSRFToken();
@@ -302,28 +305,28 @@ formRef.current?.setValues({ name: "John" });
 
 ### useForma Methods
 
-| Method                            | Description                          |
-| --------------------------------- | ------------------------------------ |
-| `setFieldValue(path, value)`      | Set field value                      |
-| `setFieldTouched(path, touched?)` | Mark field as touched                |
-| `setValues(values)`               | Set multiple values                  |
-| `validateField(path)`             | Validate single field                |
-| `validateForm()`                  | Validate entire form                 |
-| `submitForm()`                    | Submit the form                      |
-| `resetForm()`                     | Reset to initial values              |
+| Method                            | Description                                  |
+| --------------------------------- | -------------------------------------------- |
+| `setFieldValue(path, value)`      | Set field value                              |
+| `setFieldTouched(path, touched?)` | Mark field as touched                        |
+| `setValues(values)`               | Set multiple values                          |
+| `validateField(path)`             | Validate single field                        |
+| `validateForm()`                  | Validate entire form                         |
+| `submitForm()`                    | Submit the form                              |
+| `resetForm()`                     | Reset to initial values                      |
 | `on(event, listener)`             | Register event listener; returns unsubscribe |
 
 ### useForma Options
 
-| Option                 | Type                             | Default  | Description               |
-| ---------------------- | -------------------------------- | -------- | ------------------------- |
-| `spec`                 | `Forma`                          | required | The Forma specification   |
-| `initialData`          | `Record<string, unknown>`        | `{}`     | Initial form values       |
-| `onSubmit`             | `(data) => void`                 | -        | Submit handler            |
-| `onChange`             | `(data, computed) => void`       | -        | Change handler            |
-| `validateOn`           | `"change" \| "blur" \| "submit"` | `"blur"` | When to validate          |
-| `referenceData`        | `Record<string, unknown>`        | -        | Additional reference data |
-| `validationDebounceMs` | `number`                         | `0`      | Debounce validation (ms)  |
+| Option                 | Type                             | Default  | Description                 |
+| ---------------------- | -------------------------------- | -------- | --------------------------- |
+| `spec`                 | `Forma`                          | required | The Forma specification     |
+| `initialData`          | `Record<string, unknown>`        | `{}`     | Initial form values         |
+| `onSubmit`             | `(data) => void`                 | -        | Submit handler              |
+| `onChange`             | `(data, computed) => void`       | -        | Change handler              |
+| `validateOn`           | `"change" \| "blur" \| "submit"` | `"blur"` | When to validate            |
+| `referenceData`        | `Record<string, unknown>`        | -        | Additional reference data   |
+| `validationDebounceMs` | `number`                         | `0`      | Debounce validation (ms)    |
 | `on`                   | `FormaEvents`                    | -        | Declarative event listeners |
 
 ## Error Boundary
@@ -351,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