@ahrowe/ui 0.1.16 → 0.1.18

package/docs/FormValidatorGroup.md

@@ -0,0 +1,154 @@
+# FormValidatorGroup
+
+**When to use:** Manage a whole form — multiple fields, a single submit handler, validate-on-submit, dirty/touched tracking across the form, and mapping server-side errors back onto the right fields. Build it from a map of named `FormValidator` instances. For a single field, use `FormValidator` on its own.
+
+**Import:** `import { useFormValidatorGroup, FormValidatorGroup, FormValidator, Validators } from '@ahrowe/ui'`
+**Types:** `import type { FormValidatorGroupOptions, InferGroupValues, MergedValues } from '@ahrowe/ui'`
+
+## Recommended: the `useFormValidatorGroup` hook
+
+In function components, create the group with the hook. It instantiates the group once on mount, keeps `onSubmit`/`onValidate` fresh via refs, and re-renders the component whenever any field, the submit state, or validation state changes.
+
+```tsx
+import { useFormValidatorGroup, FormValidator, Validators, Input, InputType, ActionButtons } from '@ahrowe/ui';
+
+function ProfileForm({ user, onSaved }) {
+  const form = useFormValidatorGroup(
+    {
+      // Each FormValidator's first arg is the DEFAULT (empty) value, not the user's value
+      name:  new FormValidator('', [Validators.required(), Validators.minLength(2)]),
+      email: new FormValidator('', [Validators.required(), Validators.email()]),
+    },
+    {
+      // initialValues OVERRIDES those defaults with the existing record you're editing
+      initialValues: { name: user.name, email: user.email },
+      onSubmit: async (values) => {
+        // `values` is fully typed: { name: string; email: string }
+        await api.updateProfile(values);
+        onSaved();
+      },
+    },
+  );
+
+  // `form.Form` wires up onSubmit + noValidate for you
+  return (
+    <form.Form>
+      <Input label="Name"  formValidator={form.group.name} />
+      <Input label="Email" type={InputType.Email} formValidator={form.group.email} />
+      <ActionButtons
+        submitLabel="Save"
+        onSubmit={form.submit}
+        isSubmitButtonLoading={form.isSubmitting}
+        isSubmitButtonDisabled={!form.isDirty}
+      />
+    </form.Form>
+  );
+}
+```
+
+> The exported `FormValidatorGroup` is the form-aware subclass: every instance has a `Form` component (`form.Form`) that renders `<form onSubmit={form.submit} noValidate>`. You can also call `form.submit(event)` directly from a button.
+
+> **Defaults vs. `initialValues` — the editing pattern.** Each `FormValidator`'s first argument is the field's _empty default_ (`''`, `null`, `false`, …). When you load an existing entity to **edit** it (e.g. an existing user), put those current values in `initialValues` — not in the validator constructors. The group seeds each field from `initialValues` on creation, and that same set becomes the baseline `reset()` restores to. Keep the constructors as empty defaults so a "create new" form (no `initialValues`) and an "edit" form share the exact same field definitions.
+
+```tsx
+// Create form — no initialValues, fields stay at their empty defaults
+const createForm = useFormValidatorGroup(fields, { onSubmit: create });
+
+// Edit form — same `fields`, current record passed as initialValues
+const editForm = useFormValidatorGroup(fields, { initialValues: user, onSubmit: update });
+```
+
+## Submit flow
+
+`submit(event?)` does the following:
+
+1. `preventDefault` / `stopPropagation` on the event if present.
+2. Sets `isSubmitting` true.
+3. On the **first** submit, runs `validate()` (validates every field + marks them touched); on later submits, runs `onValidate` only.
+4. If any field error or a custom validation error exists → calls `onSubmitError` with it, increments `submitCount`, and stops (does **not** call `onSubmit`).
+5. Otherwise calls `onSubmit(values, group)`. If it throws, the error is passed to `parseError(err, true)` to surface field-level or generic errors.
+6. Sets `isSubmitting` false.
+
+By default `onSubmitError` shows the first error as an error **toast** (requires a `ToastProvider` in the tree — see `Toast`). Override it via `options.onSubmitError`.
+
+## Options
+
+```ts
+interface FormValidatorGroupOptions {
+  initialValues?: Record<string, unknown>;     // OVERRIDES the validators' empty defaults with an
+                                                // existing record's values (use when editing); also
+                                                // becomes the baseline reset() restores to
+  onSubmit?:   (values, group) => void | Promise<void>;
+  onValidate?: (group) => ValidationError | null | void;  // extra cross-field validation
+  errorParser?: (err: unknown) => ValidationError[];      // turn an API error into field errors
+  onSubmitError?: (errors: ValidationError[]) => void;    // default: error toast of the first message
+}
+```
+
+`onValidate` runs as part of `submit` — return a `{ id, message }` to block submission with a form-level error (e.g. "passwords must match"):
+
+```tsx
+useFormValidatorGroup(
+  { password: new FormValidator(''), confirm: new FormValidator('') },
+  {
+    onValidate: (group) =>
+      group.group.password.value === group.group.confirm.value
+        ? null
+        : { id: 'mismatch', message: 'Passwords do not match' },
+    onSubmit: async (values) => api.setPassword(values),
+  },
+);
+```
+
+## Instance API
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `group` | `Record<name, FormValidator>` | The field validators. Access a field via `form.group.<name>`. |
+| `Form` | `React.FC<FormHTMLAttributes>` | `<form>` pre-wired with `onSubmit={submit}` + `noValidate`. |
+| `submit` | `(event?) => Promise<void>` | Validate then run `onSubmit`. Safe to pass straight to a `<form onSubmit>` or button. |
+| `validate` | `() => ValidationError \| null \| void` | Validate every field, mark all touched, run `onValidate`. |
+| `getValues` | `() => MergedValues` | Typed snapshot: `initialValues` merged with every field's current value. |
+| `set` | `(name, value) => this` | Set one field's value (validates it). Chainable. |
+| `setValidator` | `(name, validator) => this` | Swap a field's `FormValidator` instance. |
+| `reset` | `(overrides?) => void` | Restore fields to their post-creation values (or `overrides`), clear dirty/touched, fire `onReset`. |
+| `resetDirtyAndTouched` | `() => void` | Clear dirty/touched on all fields without changing values. |
+| `parseError` | `(err, isInternal?) => void` | Run `errorParser` and push field errors onto matching validators; otherwise a generic error. |
+| `getFormError` | `() => ValidationError \| null` | First error across all fields, or `null`. |
+| `isSubmitting` | `boolean` (get) | True while `submit` is running. |
+| `isDirty` | `boolean` (get) | Any field changed since creation. |
+| `wasTouched` | `boolean` (get) | Any field entered and left. |
+| `hasErrors` | `boolean` (get) | Any field currently has an error. |
+| `initialValues` | `object` (get) | Copy of the initial values. |
+| `submitCount` | `number` | How many times `submit` has run (reset to 0 on any field change). |
+| `onDebounce` | `(values) => void` | Assignable callback fired 500ms after the last field change. |
+| `onReset` | `(group, valuesAfterCreation, initialValues) => void` | Assignable, fired by `reset()`. |
+
+## Mapping API errors back to fields
+
+If your API returns errors shaped like `{ errors: [{ <fieldName>: '<message>' }] }`, the default `errorParser` routes each message to the matching field. A thrown `onSubmit` error is parsed automatically; you can also call it manually:
+
+```tsx
+try {
+  await api.save(form.getValues());
+} catch (err) {
+  form.parseError(err); // pushes e.g. an "email already taken" error onto form.group.email
+}
+```
+
+Pass a custom `errorParser` in the options when your API uses a different shape.
+
+## Class components
+
+For legacy class components, instantiate directly and pass the component instance so the group can call `forceUpdate()`:
+
+```tsx
+this.form = new FormValidatorGroup(
+  { name: new FormValidator('', [Validators.required()]) },
+  this,                              // component instance — enables re-render via forceUpdate
+  { onSubmit: (values) => this.save(values) },
+);
+```
+
+`ValidatableComponent` (also exported) is the base class the built-in form components extend — subclass it when building your own validator-aware input.
+</content>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "publishConfig": {
     "access": "public"
   },