@ahrowe/ui 0.52.0 → 0.53.0

package/dist/types/common/otpInput/otpInput.types.d.ts

@@ -34,7 +34,7 @@ export interface OtpInputProps extends Omit<HtmlProps, 'onChange'> {
     label?: string;
     isValid?: boolean;
     /** Shown in an error Tooltip on focus/hover once `isValid` is `false` (or, with a
-     * `formValidator`, once it's touched and has an error). Persists until the value changes
+     * `formValidator`, once its `shouldShowError` is true). Persists until the value changes
      * `isValid`/`formValidator`'s error state itself — see `clearOnError` to auto-dismiss it. */
     errorMessage?: string;
     isRequired?: boolean;

package/dist/types/index.d.ts

@@ -170,6 +170,6 @@ export { default as Wizard } from './common/wizard/index.js';
 export * from './common/wizard/index.js';
 export * from './common/hooks/index.js';
 export { FormValidator, FormValidatorGroup, Validators, ValidatableComponent, useFormValidator, useFormValidatorGroup, } from './services/formValidation/index.js';
-export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues, } from './services/formValidation/index.js';
+export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues, ShowErrorsMode, FormValidatorOptions, } from './services/formValidation/index.js';
 export { mapLocale, setLocale, getLocale } from './services/localization.js';
 export { isNumber, isDate, isDay, isISODate, isEmail, isBic, isURL, hasEightPasswordChars, hasOnePasswordLetter, hasOnePasswordDigit, isPassword, } from '@ahrowe/form-validation';

package/dist/types/services/formValidation/index.d.ts

@@ -2,4 +2,4 @@ export { default as FormValidatorGroup } from './FormValidatorGroupWithForm.js';
 export { default as ValidatableComponent } from './validatableComponent.js';
 export { useFormValidatorGroup } from './useFormValidatorGroup.js';
 export { FormValidator, Validators, useFormValidator } from '@ahrowe/form-validation';
-export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues, } from '@ahrowe/form-validation';
+export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues, ShowErrorsMode, FormValidatorOptions, } from '@ahrowe/form-validation';

package/dist/types/services/formValidation/useFormValidatorGroup.d.ts

@@ -7,4 +7,4 @@ import { default as FormValidatorGroupWithForm } from './FormValidatorGroupWithF
  * (useFormValidatorGroupInstance) so this and the pure hook share one
  * implementation of "subscribe a function component to a group".
  */
-export declare function useFormValidatorGroup<TGroup extends FormGroup = FormGroup, TInitial = InferGroupValues<TGroup>>(groupDef: TGroup, { initialValues, onSubmit, onValidate, errorParser, onSubmitError }?: FormValidatorGroupOptions<TGroup, TInitial>): FormValidatorGroupWithForm<TGroup, TInitial>;
+export declare function useFormValidatorGroup<TGroup extends FormGroup = FormGroup, TInitial = InferGroupValues<TGroup>>(groupDef: TGroup, { onSubmit, onValidate, ...options }?: FormValidatorGroupOptions<TGroup, TInitial>): FormValidatorGroupWithForm<TGroup, TInitial>;

package/docs/FormValidator.md

@@ -5,7 +5,7 @@
 **Keywords:** form field validation, field validator
 
 **Import:** `import { FormValidator, Validators, useFormValidator } from '@ahrowe/ui'`
-**Types:** `import type { ValidatorFunction, ValidationError } from '@ahrowe/ui'`
+**Types:** `import type { ValidatorFunction, ValidationError, ShowErrorsMode, FormValidatorOptions } from '@ahrowe/ui'`
 
 ## Basic usage
 
@@ -39,6 +39,26 @@ nameValidator.dirty                    // value has changed since creation
 >
 > 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.
 
+## When a component shows the error
+
+A form component marks the field red, and shows the message on hover or focus, while
+`shouldShowError` is true: the field has an error, and its `showErrors` mode allows it. The mode is
+the constructor's third argument:
+
+| `showErrors` | The error shows |
+|--------------|-----------------|
+| `'touched'` (default) | once the field is `touched`: left (blurred) by the user, a picker's panel closed, or marked by the group's `validate()` on submit |
+| `'dirty'` | once the field is `dirty` (changed by the user) or `touched`. Suits password rules; an email field would complain after the first letter |
+| `'always'` | from the start. For an edit form loaded with data that is already invalid |
+
+```tsx
+const password = new FormValidator('', [Validators.password()], { showErrors: 'dirty' });
+```
+
+Once shown, an error follows every edit and disappears as soon as the value is valid. A
+`FormValidatorGroup` takes `showErrors` too, as the default for every field that does not set its
+own (FormValidatorGroup.md).
+
 ## 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:
@@ -82,6 +102,8 @@ const agreedValidator = new FormValidator<boolean>(false, [Validators.required()
 | `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. |
+| `showErrors` | `ShowErrorsMode \| undefined` (get/set) | When errors show: `'touched'`, `'dirty'` or `'always'`. `undefined` falls back to the group's, then `'touched'`. |
+| `shouldShowError` | `boolean` (get) | Has an error that `showErrors` says to show now. What every form component reads. |
 | `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`. |

package/docs/FormValidatorGroup.md

@@ -69,7 +69,8 @@ const editForm = useFormValidatorGroup(fields, { initialValues: user, onSubmit:
 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.
+6. After a successful `onSubmit`, clears dirty/touched on every field.
+7. Sets `isSubmitting` false.
 
 By default `onSubmitError` shows the first error as an error **toast** (see `Toast`). Override it via `options.onSubmitError`.
 
@@ -84,6 +85,8 @@ interface FormValidatorGroupOptions {
   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
+  showErrors?: 'touched' | 'dirty' | 'always';             // default for every field that does not set
+                                                          // its own; see FormValidator.md
 }
 ```
 
@@ -115,7 +118,7 @@ useFormValidatorGroup(
 | `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. |
+| `parseError` | `(err, isInternal?) => void` | Run `errorParser`, push field errors onto matching validators and mark those touched; 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. |

package/docs/InputDropdown.md

@@ -64,7 +64,7 @@ interface InputDropdownItem {
 | `placeholder` | `string` | |
 | `readOnly` | `boolean` | Make the field read-only — typing is blocked, the list won't open, and keyboard navigation/selection is disabled. Default `false` |
 | `labels` | `InputDropdownLabels` | Text the component renders of its own, see **Labels** below |
-| `formValidator` | `FormValidator` | Connects to validation — shows the error state/message once the field has been touched (blurred), and the required mark (`*`) when the validator has a `required` validator |
+| `formValidator` | `FormValidator` | Connects to validation — shows the error state/message once the validator's `shouldShowError` is true (by default once the field has been blurred, see FormValidator.md), and the required mark (`*`) when the validator has a `required` validator |
 | `error` | `string` | Manual error message (used when no `formValidator` is given) |
 | `isRequired` | `boolean` | Shows the required mark (`*`) next to the label. Also inferred automatically when `formValidator` has a `required` validator. Default `false` |
 

package/docs/MultiSelect.md

@@ -49,7 +49,7 @@ import { Presentation } from '@ahrowe/ui';
 
 **The label floats like `Input`'s.** It rests vertically centred over the control and rises into a notch cut out of the border once the field is focused, open, or has a selection, using the same `fieldset`/`legend` construction and the same `--input-notch-height` geometry as `Input`. A `MultiSelect` sitting next to an `Input` in a form animates with it rather than against it. Set `alwaysFloatLabel` to pin it up, which is what you want when a `placeholder` should always be readable: with a label present the placeholder is otherwise faded in on a delay matching the label's animation, so the two never sit on top of each other. Without a label there is nothing to wait for and it fades in at once.
 
-**Errors:** with a `formValidator` the field stays quiet until it has been touched (the first time the panel closes), then shows the validator's message while the field is hovered or focused, and drops it as soon as the validator is happy again. Without a validator, `isValid` and `errorMessage` are plain props and nothing clears them for you: derive them from your own state, as in `isValid={picked.length > 0}`.
+**Errors:** with a `formValidator` the field stays quiet until the validator's `showErrors` lets the error through (by default once touched: the first time the panel closes, see FormValidator.md), then shows the validator's message while the field is hovered or focused, and drops it as soon as the validator is happy again. Without a validator, `isValid` and `errorMessage` are plain props and nothing clears them for you: derive them from your own state, as in `isValid={picked.length > 0}`.
 
 **Height:** a MultiSelect with one row of chips is exactly as tall as an `Input` or `Dropdown` beside it, so a form row lines up. It grows only when the chips wrap onto a second row. The chips render at `0.8em` to fit: a standalone `Chip` is nearly as tall as the whole field, because its remove button carries `ActionIcon`'s padding around a `1em` icon.
 

package/docs/OtpInput.md

@@ -60,7 +60,7 @@ const codeValidator = new FormValidator('', [Validators.required(), Validators.m
 
 **Interaction:** typing a character fills the focused box and jumps to the next one; on the last box, it blurs instead. Backspace on a filled box just clears it; on an already-empty box it clears and focuses the previous one. Left/Right arrow keys move focus without changing values. Pasting (or an SMS autofill suggestion landing in one box) distributes the pasted text across boxes starting from wherever it lands. Focusing a box selects its content, so typing immediately overwrites it rather than requiring a manual clear first.
 
-**Error display:** like `Input`/`RadioGroup`, the boxes get a red border once errored, and the message itself appears in an error `Tooltip` on focus or hover rather than sitting inline under the boxes all the time. With a `formValidator`, this only shows once the field has been *touched* (focus has left the group) **and** has an error — so a required-field error doesn't flash before the user has even had a chance to type. With manual `isValid`/`errorMessage`, there's no touched-gating (the consumer already controls when to set `isValid={false}`, e.g. only after a failed verification call). Either way, the error persists across renders until whatever's driving it — `isValid`, or the `formValidator`'s own error state — actually changes; `OtpInput` never silently clears it on its own. See `clearOnError` below for the one built-in exception.
+**Error display:** like `Input`/`RadioGroup`, the boxes get a red border once errored, and the message itself appears in an error `Tooltip` on focus or hover rather than sitting inline under the boxes all the time. With a `formValidator`, this shows once the validator's `shouldShowError` is true: by default once the field has been *touched* (focus has left the group) **and** has an error, so a required-field error doesn't flash before the user has even had a chance to type (`showErrors`, see FormValidator.md). With manual `isValid`/`errorMessage`, there's no touched-gating (the consumer already controls when to set `isValid={false}`, e.g. only after a failed verification call). Either way, the error persists across renders until whatever's driving it — `isValid`, or the `formValidator`'s own error state — actually changes; `OtpInput` never silently clears it on its own. See `clearOnError` below for the one built-in exception.
 
 **`onComplete`:** fires once per genuinely new completion — i.e. the code going from fewer than `length` characters to exactly `length`. Editing individual boxes of an already-complete code (retyping a digit that was wrong) does **not** refire it on every keystroke, since the code never drops below `length` in between; it fires again only after the code is cleared (manually, or via `clearOnError` below) and refilled.
 

package/docs/RadioGroup.md

@@ -71,7 +71,7 @@ interface RadioOption {
 | `errorMessage` | `string` | Manual error message (when not using a `formValidator`) |
 | `isValid` | `boolean` | Manual valid state (default `true`) |
 
-**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces only after the field is *touched* (focus leaves the group), then on focus or hover.
+**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces once the validator's `showErrors` allows it (by default after the field is *touched*: focus leaves the group, see FormValidator.md), then on focus or hover.
 
 **Global defaults:** adopts `ConfigProvider` — e.g. `defaultProps={{ RadioGroup: { orientation: RadioGroupOrientation.Horizontal } }}`. See [ConfigProvider.md](ConfigProvider.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",
@@ -106,7 +106,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@ahrowe/form-validation": "^0.3.0",
+    "@ahrowe/form-validation": "^0.4.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",