@ahrowe/ui 0.1.16 → 0.1.17

package/dist/types/package/common/virtualList/useColumns.d.ts

@@ -13,6 +13,8 @@ interface UseColumnsArgs<T> {
     startIndex: number;
     endIndex: number;
     containerHeight: number;
+    /** Re-measure `fit` columns when the container width settles (e.g. after a route transition). */
+    containerWidth: number;
 }
 interface UseColumnsResult<T> {
     hasColumns: boolean;
@@ -33,5 +35,5 @@ interface UseColumnsResult<T> {
  * `fit`-column width measurement that pins one shared px track across the header
  * and every row grid so they stay aligned.
  */
-export declare function useColumns<T>({ columns, items, multiSelect, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, showColumnToggle, rootRef, startIndex, endIndex, containerHeight, }: UseColumnsArgs<T>): UseColumnsResult<T>;
+export declare function useColumns<T>({ columns, items, multiSelect, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, showColumnToggle, rootRef, startIndex, endIndex, containerHeight, containerWidth, }: UseColumnsArgs<T>): UseColumnsResult<T>;
 export {};

package/dist/types/package/common/virtualList/useVirtualWindow.d.ts

@@ -22,6 +22,7 @@ interface UseVirtualWindowResult {
     offsets: number[];
     totalHeight: number;
     containerHeight: number;
+    containerWidth: number;
     startIndex: number;
     endIndex: number;
     handleScroll: (e: React.UIEvent<HTMLDivElement>) => void;

package/docs/CLAUDE.md

@@ -37,7 +37,7 @@ const myTheme: Theme = {
 
 ## FormValidator (for form-connected components)
 
-Input, NumberInput, Dropdown, Checkbox all accept a `formValidator` prop. Use it to connect validation state.
+Input, NumberInput, Dropdown, Checkbox, DatePicker, IconPicker, InputDropdown, and Textarea all accept a `formValidator` prop. Use it to connect validation state.
 
 ```tsx
 import { FormValidator, Validators, Input } from '@ahrowe/ui';
@@ -47,38 +47,29 @@ const nameValidator = new FormValidator('', [Validators.required(), Validators.m
 
 // Pass to component — it tracks value, dirty, touched, errors internally
 <Input label="Name" formValidator={nameValidator} />
-
-// Read state
-nameValidator.value          // current value
-nameValidator.hasError()     // true if any error
-nameValidator.getCurrentErrorMessage()  // first error message or null
-nameValidator.touched        // user has blurred the field
-nameValidator.dirty          // value has changed
-
-// Validators available
-Validators.required()
-Validators.minLength(n)
-Validators.maxLength(n)
-Validators.email()
-Validators.mustBeNumber()
-Validators.date()
-Validators.website()
-Validators.password()        // min 8 chars, 1 letter, 1 digit
-Validators.oneOf([...])
-Validators.multiEmail()
-Validators.bic()
 ```
 
-For groups of fields:
+For multi-field forms with a single submit handler, use `useFormValidatorGroup`:
 
 ```tsx
-import { FormValidatorGroup, useFormValidatorGroup } from '@ahrowe/ui';
+import { useFormValidatorGroup, FormValidator, Validators } from '@ahrowe/ui';
+
+const form = useFormValidatorGroup(
+  {
+    name:  new FormValidator('', [Validators.required()]),
+    email: new FormValidator('', [Validators.required(), Validators.email()]),
+  },
+  { onSubmit: async (values) => save(values) }, // values is fully typed
+);
 
-const group = new FormValidatorGroup([nameValidator, emailValidator]);
-group.isValid()   // all fields valid
-group.validate()  // trigger all validators
+<form.Form>
+  <Input label="Name"  formValidator={form.group.name} />
+  <Input label="Email" formValidator={form.group.email} />
+</form.Form>
 ```
 
+Full reference: see **FormValidator.md** (single field, all built-in validators, custom validators) and **FormValidatorGroup.md** (whole-form submit, validate, reset, server-error mapping) below.
+
 ## Slot customisation (classNames / styles)
 
 Most components expose `classNames` and `styles` props for styling inner elements without fighting CSS specificity.
@@ -116,6 +107,8 @@ Slot keys per component are documented in each component's doc file below.
 @EmptyState.md
 @Fab.md
 @FloatingMenu.md
+@FormValidator.md
+@FormValidatorGroup.md
 @IconPicker.md
 @IdleManager.md
 @InfiniteBlock.md

package/docs/FormValidator.md

@@ -0,0 +1,146 @@
+# FormValidator
+
+**When to use:** Track and validate a single form field's value, dirty/touched state, and errors. Pass the instance to any form-connected component (`Input`, `NumberInput`, `Dropdown`, `Checkbox`, `DatePicker`, `IconPicker`, `InputDropdown`, `Textarea`) via its `formValidator` prop — the component then reads the value and surfaces validation errors automatically. For multi-field forms with submit handling, use `FormValidatorGroup` instead.
+
+**Import:** `import { FormValidator, Validators, useFormValidator } from '@ahrowe/ui'`
+**Types:** `import type { ValidatorFunction, ValidationError } from '@ahrowe/ui'`
+
+## Basic usage
+
+```tsx
+import { FormValidator, Validators, Input } from '@ahrowe/ui';
+
+// Create with a default (empty) value and an optional list of validators
+const nameValidator = new FormValidator('', [Validators.required(), Validators.minLength(2)]);
+
+// Hand it to a form component — it tracks value, dirty, touched, and errors internally
+<Input label="Name" formValidator={nameValidator} />
+
+// Read state at any time
+nameValidator.value                    // current value (typed as T)
+nameValidator.hasError()               // true if any error is present
+nameValidator.hasError('required')     // true if the error with id 'required' is present
+nameValidator.getCurrentErrorMessage() // first error message, or null
+nameValidator.touched                  // user has entered and left the field
+nameValidator.dirty                    // value has changed since creation
+```
+
+> **The first constructor argument is the field's _default (empty)_ value** — what the field holds when nothing has been entered, **not** an existing record's value. Use the type's natural empty value:
+>
+> | Field | Default value |
+> |-------|---------------|
+> | string (text, email, …) | `''` |
+> | `Date` | `null` |
+> | number | `undefined` (or `0`) |
+> | checkbox / boolean | `false` |
+> | single-select id | `null` |
+>
+> To pre-fill fields when **editing an existing entity**, don't seed values here — pass them as `initialValues` on a `FormValidatorGroup` (see [FormValidatorGroup.md](FormValidatorGroup.md)). That keeps the empty value as the validator's true default so `reset()` works correctly.
+
+## Re-rendering a function component when the value changes
+
+A `FormValidator` lives outside React state, so changing it does **not** by itself re-render a function component. When you read `validator.value` / `validator.hasError()` directly in render (rather than only handing the instance to a form component), subscribe with `useFormValidator` so the component re-renders on every change:
+
+```tsx
+import { useMemo } from 'react';
+import { FormValidator, Validators, useFormValidator, Input } from '@ahrowe/ui';
+
+function NameField() {
+  // Create once — never `new FormValidator(...)` inline in render without memoising
+  const validator = useMemo(() => new FormValidator('', [Validators.required()]), []);
+  useFormValidator(validator); // re-renders this component on value/error/touched/dirty changes
+
+  return (
+    <>
+      <Input label="Name" formValidator={validator} />
+      <button disabled={validator.hasError()}>Save</button>
+    </>
+  );
+}
+```
+
+`useFormValidator(validator)` returns the same instance for convenience and accepts `null`.
+
+## Typing the value
+
+`FormValidator<T>` is generic. Pass the value type for non-string fields, and give each its natural empty value as the default:
+
+```tsx
+const ageValidator    = new FormValidator<number | undefined>(undefined, [Validators.required()]);
+const dateValidator   = new FormValidator<Date | null>(null);
+const agreedValidator = new FormValidator<boolean>(false, [Validators.required()]);
+```
+
+## Instance API
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `value` | `T` (get/set) | Current value. The setter assigns **without** validating — prefer `set()` for user input. |
+| `set` | `(newValue: T, wasUser = true) => this` | Assign value, mark dirty when `wasUser`, then re-validate. Chainable. |
+| `validate` | `() => void` | Clear errors and run every validator against the current value. |
+| `touched` | `boolean` (get/set) | User has entered and left the field. |
+| `dirty` | `boolean` (get/set) | Value changed since creation. |
+| `errors` | `ValidationError[]` (get) | All current errors (`{ id, message }`). |
+| `hasError` | `(id?: string) => boolean` | Any error when called with no arg; a specific error by `id` otherwise. |
+| `getCurrentErrorMessage` | `() => string \| null` | First error message, or `null`. |
+| `addError` | `(error: ValidationError) => void` | Push an error manually (e.g. a server-side error). |
+| `removeErrors` | `(ids: string[]) => void` | Remove errors by id. |
+| `clearErrors` | `() => void` | Remove all errors. |
+| `label` | `string` (get/set) | Field label; form components set this and validators receive it (used by `required()` messages). |
+| `validators` | `ValidatorFunction[]` | The active validator list — mutable. |
+| `registerOnUpdateListener` | `(cb: () => void) => void` | Subscribe to changes (what `useFormValidator` uses internally). |
+| `removeOnUpdateListener` | `(cb: () => void) => void` | Unsubscribe. |
+
+> Validators run once in the constructor, so `hasError()` reflects the initial value immediately.
+
+## Built-in validators
+
+All live as static methods on `Validators`. Each returns a `ValidatorFunction` and accepts an optional custom `errorMsg` as the last argument to override the default message.
+
+```tsx
+Validators.required(errorMsg?)             // value must be present (0 counts as present)
+Validators.minLength(min, errorMsg?)       // string length >= min (also fails on empty)
+Validators.maxLength(max, errorMsg?)       // string length <= max
+Validators.email(errorMsg?)                // valid email address
+Validators.multiEmail(errorMsg?)           // comma/semicolon-separated list of emails
+Validators.mustBeNumber(errorMsg?)         // parses as a number
+Validators.oneOf(allowedValues, errorMsg?) // value is in the allowed array
+Validators.typeOf(allowedTypes, errorMsg?) // typeof value matches (string or string[])
+Validators.date(errorMsg?)                 // valid date string (DD.MM.YYYY or ISO)
+Validators.dateObject(errorMsg?)           // an object with an `isValid` flag (e.g. a date wrapper)
+Validators.website(errorMsg?)              // valid URL
+Validators.bic(errorMsg?)                  // valid BIC/SWIFT code
+Validators.minLetters(min, errorMsg?)      // at least `min` letters (a–z, incl. äöüß)
+Validators.minDigits(min, errorMsg?)       // at least `min` digits
+Validators.password(errorMsg?)             // min 8 chars, ≥1 letter, ≥1 digit
+```
+
+> **Empty values pass most validators.** Except `required()` and `minLength()`, every validator returns `null` for an empty value — so a field is "valid when empty" unless you also add `Validators.required()`. Combine them:
+> `new FormValidator('', [Validators.required(), Validators.email()])`.
+
+## Custom validators
+
+A validator is any `(value, label?) => ValidationError | null` — return `null` when valid, or `{ id, message }` when not:
+
+```tsx
+import type { ValidatorFunction } from '@ahrowe/ui';
+
+const mustBeEven: ValidatorFunction = (value) =>
+  Number(value) % 2 === 0 ? null : { id: 'even', message: 'Must be an even number' };
+
+const validator = new FormValidator<number>(0, [Validators.required(), mustBeEven]);
+```
+
+The `id` you choose is what `hasError('even')` and `removeErrors(['even'])` match against.
+
+## Reading server-side errors back into a field
+
+```tsx
+validator.addError({ id: 'taken', message: 'This email is already registered' });
+// later, once the user edits the field again:
+validator.removeErrors(['taken']);
+```
+
+When validating a whole form at once, prefer `FormValidatorGroup.parseError()` — see `FormValidatorGroup`.
+</content>
+</invoke>

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.17",
   "publishConfig": {
     "access": "public"
   },