@zhunam/form-builder 2.0.0 → 3.1.0

package/README.md

@@ -36,6 +36,95 @@ For a calculator-style form (no submit action, values used as you type):
 
 `formSubmit` stays available in `'live'` mode too; most `'live'` consumers just won't use it.
 
+### Presetting or replacing the form's value
+
+The `value` input patches the form in place, without rebuilding it, so
+whatever the user already typed in fields that stay unaffected is never
+lost. Useful for a "swap" action or restoring a draft:
+
+```typescript
+swapValue = signal<Partial<User> | undefined>(undefined);
+
+onSwap(): void {
+  this.swapValue.set({ name: this.currentLastValue.name /* ... */ });
+}
+```
+
+```html
+<lib-form-builder [fields]="fields" [value]="swapValue()" mode="live" (valueChange)="onValueChange($event)" />
+```
+
+Rebuilding `fields()` itself (e.g. a wizard changing steps) also keeps
+the current value of every control whose key still exists in the new
+array; only a control whose key disappears is dropped, and only a
+brand-new key falls back to its own `defaultValue`.
+
+### Submitting from outside the component
+
+```html
+<lib-form-builder #form [fields]="fields" [hideSubmit]="true" [loading]="saving()" (formSubmit)="onSave($event)" />
+<button (click)="form.submit()">Continue</button>
+```
+
+`submit()` runs the exact same logic the internal button would: it marks
+the form submitted, validates, and emits `formSubmit` if valid. It's a
+no-op while `loading` is `true`, the same guard that disables the
+internal button.
+
+### Switch and segmented appearance
+
+`appearance` changes only how a specific `type` looks, never the control underneath it: a real `<input type="checkbox">`/`<input type="radio">` is always there, visually hidden but focusable, clickable via its label, and fully native for validation, keyboard operation, and screen readers.
+
+```typescript
+fields: FieldConfig<Settings>[] = [
+  { key: 'notifications', label: 'Email notifications', type: 'checkbox', appearance: 'switch' },
+  {
+    key: 'plan',
+    label: 'Plan',
+    type: 'radio',
+    appearance: 'segmented',
+    options: [
+      { value: 'personal', label: 'Personal' },
+      { value: 'business', label: 'Business' },
+    ],
+  },
+];
+```
+
+`'switch'` only changes `type: 'checkbox'`; `'segmented'` only changes `type: 'radio'`. Setting `appearance` on any other `type` (or leaving it unset) has no effect at all, no error, no warning.
+
+### Field hints and option descriptions
+
+`hint` shows short helper text below a field, only while there's no active error: an error replaces it visually, and `aria-describedby` follows the same rule, always pointing at whichever one is currently shown, never both.
+
+```typescript
+{ key: 'password', label: 'Password', type: 'password', hint: 'At least 8 characters', validators: { required: true, minLength: 8 } }
+```
+
+`FieldOption.description` shows helper text below one specific `radio` option, independent of the field-level hint or error:
+
+```typescript
+{
+  key: 'plan',
+  label: 'Plan',
+  type: 'radio',
+  options: [
+    { value: 'personal', label: 'Personal', description: 'For individual use' },
+    { value: 'business', label: 'Business', description: 'For teams and invoicing' },
+  ],
+}
+```
+
+### Read-only fields
+
+`readonly` keeps a field's value visible and its validation running exactly as before, only direct editing is blocked. Unlike `disabled`, the underlying `FormControl` stays enabled, so its value is never excluded from anything.
+
+```typescript
+{ key: 'referenceCode', label: 'Reference code', type: 'text', readonly: true, defaultValue: 'REF-2026-001' }
+```
+
+Only applies to `text`, `number`, `email`, `password`, `date`, and `textarea`: the HTML `readonly` attribute doesn't apply to `select`, `radio`, or `checkbox` natively, and this library doesn't simulate it for those, setting `readonly` on one of them is simply ignored.
+
 ## API
 
 ### `FormBuilder<T>`
@@ -49,6 +138,11 @@ For a calculator-style form (no submit action, values used as you type):
 | `formSubmit`           | `output<T>`                                  | N/A          | Emitted with the typed form values, only when the native form and every `crossFieldValidators` check pass. |
 | `mode`                 | `input<'submit' \| 'live'>`                  | `'submit'`   | `'submit'`: only `formSubmit` fires, on submit. `'live'`: `valueChange` also fires continuously as the user edits, in addition to `formSubmit` staying available. |
 | `valueChange`          | `output<T>`                                  | N/A          | Emitted with the typed, valid values on every change, only when `mode` is `'live'`. Fires once immediately if the form starts valid with its defaults. |
+| `submitLabel`          | `input<string>`                              | None         | Custom label for the submit button, instead of `messages.submit()`. |
+| `hideSubmit`           | `input<boolean>`                             | `false`      | Hides the internal submit button; use the public `submit()` method to trigger submission from your own UI. |
+| `loading`              | `input<boolean>`                             | `false`      | Disables the internal button and makes `submit()` a no-op while `true`. |
+| `value`                | `input<T>`                                   | None         | External value patched into the current form (no rebuild, no `valueChange` in `'live'` mode) every time it receives a new, non-`undefined` value. |
+| `submit()`             | `(): void`                                   | N/A          | Public method: runs the same submit logic as the internal button, works whether `hideSubmit` is `true` or `false`. |
 
 ### `FieldConfig<T>`
 
@@ -63,23 +157,57 @@ For a calculator-style form (no submit action, values used as you type):
 | `defaultValue`| `T[keyof T]`            | None      | Initial value assigned to the field before user interaction.                |
 | `colSpan`     | `1 \| 2`                | `1`          | How many grid columns this field spans, when the component's `columns` input is 2 or more. |
 | `disabled`    | `boolean`               | `false`      | Renders the control disabled from the start; still included in the value `formSubmit` emits. |
+| `showPasswordToggle` | `boolean`        | `true`       | For a `type: 'password'` field, whether it renders a show/hide toggle button. No effect on other field types. |
+| `appearance`  | `FieldAppearance` (`'default' \| 'switch' \| 'segmented'`) | `'default'` | Purely visual variant. `'switch'` only affects `type: 'checkbox'`, `'segmented'` only affects `type: 'radio'`. Any other combination is ignored, same as `'default'`. See "Switch and segmented appearance" below. |
+| `hint`        | `string`                | None      | Short helper text shown below the field when there's no active error. See "Field hints and option descriptions" below. |
+| `readonly`    | `boolean`               | `false`      | Native HTML `readonly`, for `text`/`number`/`email`/`password`/`date`/`textarea` only. No effect on `select`/`radio`/`checkbox`. See "Read-only fields" below. |
+
+`FieldOption` also gains an optional `description?: string`, shown below that specific option (for `radio`, see below); `select` has nowhere to render it, so it's ignored there.
+
+### `FormBuilderMessages`
+
+| Member | Type | Description |
+| ------ | ---- | ------------ |
+| `required()` | `() => string` | Shown when a required field is empty. |
+| `email()` | `() => string` | Shown when an `email` field isn't well-formed. |
+| `min(min)` | `(min: number) => string` | Shown when a numeric field is below `min`. |
+| `max(max)` | `(max: number) => string` | Shown when a numeric field is above `max`. |
+| `minLength(requiredLength)` | `(requiredLength: number) => string` | Shown when a field's value is shorter than `minLength`. |
+| `maxLength(requiredLength)` | `(requiredLength: number) => string` | Shown when a field's value is longer than `maxLength`. |
+| `pattern()` | `() => string` | Shown when a field's value doesn't match `pattern`. |
+| `submit()` | `() => string` | Label of the submit button. |
+| `showPassword()` | `() => string` | `aria-label` of the password toggle when the value is currently hidden. |
+| `hidePassword()` | `() => string` | `aria-label` of the password toggle when the value is currently shown. |
+
+| Export | Type | Description |
+| ------ | ---- | ------------ |
+| `FORM_BUILDER_MESSAGES` | `InjectionToken<FormBuilderMessages>` | Defaults to `FORM_BUILDER_MESSAGES_EN`. Prefer `provideFormBuilderMessages()` over providing this directly. |
+| `provideFormBuilderMessages(overrides)` | `(overrides: Partial<FormBuilderMessages>) => Provider` | Registers a message override, merged on top of the English defaults. |
+| `FORM_BUILDER_MESSAGES_EN` | `FormBuilderMessages` | English preset (the default). |
+| `FORM_BUILDER_MESSAGES_ES` | `FormBuilderMessages` | Spanish preset. |
 
 ### Theming
 
 `FormBuilder` sizes and colors itself via CSS custom properties, part of
 the shared `--zhunam-*` namespace used across every `@zhunam/*` library.
-Set any of them from the consuming app's own stylesheet, scoped to
-`lib-form-builder` or wider:
+None of them are declared on the component's own `:host`, so you can set
+any of them from `:root`, from a wrapping element, or scoped directly to
+`lib-form-builder`, whichever is more convenient for your app; the
+closest ancestor that sets a given property wins, same as any other
+inherited CSS custom property.
 
 | Custom property | Default | Description |
 | ------------------------------- | -------- | -------------------------------------------------- |
-| `--zhunam-primary`               | `#3b82f6` | Submit button background, radio/checkbox accent color. |
+| `--zhunam-primary`               | `#3b82f6` | Submit button background, radio/checkbox accent color fallback. |
+| `--zhunam-accent`                | `var(--zhunam-primary)` | Radio/checkbox accent color specifically, independent from `--zhunam-primary`. Falls back to it when unset. |
+| `--zhunam-submit-width`          | `auto`    | Submit button width. |
 | `--zhunam-primary-content`       | `#fff`    | Submit button text/icon color, always painted on top of `--zhunam-primary`. |
 | `--zhunam-focus`                 | `var(--zhunam-primary)` | Focus outline and border on controls, independent from `--zhunam-primary` so a high-contrast focus ring doesn't require changing your brand color. |
 | `--zhunam-text`                  | `#1f2937` | Base text color, radio/checkbox option labels. |
 | `--zhunam-text-secondary`        | `#374151` | Field label text. |
 | `--zhunam-border`                | `#d1d5db` | Control borders. |
-| `--zhunam-error`                 | `#dc2626` | Validation/server error message text. |
+| `--zhunam-error`                 | `#dc2626` | Validation/server error message background/border, where used. See `--zhunam-error-text` for the message's own text color. |
+| `--zhunam-error-text`            | `var(--zhunam-error)` | Validation/server error message text color specifically. Falls back to `--zhunam-error` when unset, so most apps only ever need to set one of the two. |
 | `--zhunam-radius`                | `0.5rem`  | Control and submit button corner radius. |
 | `--zhunam-font-family`           | `system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif` | Font for the whole component. |
 | `--zhunam-font-size`             | `0.9375rem` | Base font size. |
@@ -87,11 +215,48 @@ Set any of them from the consuming app's own stylesheet, scoped to
 | `--zhunam-transition-duration`   | `150ms`   | Duration of border/opacity transitions. |
 | `--zhunam-form-control-padding-x` | `0.75rem` | Horizontal padding inside inputs/selects/textareas. |
 | `--zhunam-form-control-padding-y` | `0.5rem`  | Vertical padding inside inputs/selects/textareas. |
+| `--zhunam-segmented-bg`           | `#fff`    | Inactive pill background for a `'segmented'` radio group. The active pill reuses `--zhunam-primary`/`--zhunam-primary-content` instead, same as the submit button. |
 
 `--fb-columns` is an internal implementation detail (it carries the
 `columns` input's value into the field grid's CSS), not a themeable
 custom property; setting it manually has no supported effect.
 
+### Internationalization
+
+Every message `FormBuilder` renders on its own (validation text, the
+submit button label) comes from `FORM_BUILDER_MESSAGES`, an injectable
+token that defaults to English. A per-field `FieldValidatorConfig.errorMessages`
+override always takes precedence over this token for that specific field.
+
+```typescript
+import { provideFormBuilderMessages, FORM_BUILDER_MESSAGES_ES } from '@zhunam/form-builder';
+
+// app.config.ts, or any component's own `providers`:
+providers: [provideFormBuilderMessages(FORM_BUILDER_MESSAGES_ES)]
+```
+
+A partial override only replaces the messages you specify, the rest stay
+in English:
+
+```typescript
+providers: [provideFormBuilderMessages({ submit: () => 'Send' })]
+```
+
+Every message is a function, called on every render rather than once at
+startup, so one that reads a signal updates live:
+
+```typescript
+const language = signal<'en' | 'es'>('en');
+
+providers: [
+  provideFormBuilderMessages({
+    required: () => (language() === 'en' ? 'This field is required.' : 'Este campo es obligatorio.'),
+    min: (min) =>
+      language() === 'en' ? `The value must be at least ${min}.` : `El valor debe ser como mínimo ${min}.`,
+  }),
+]
+```
+
 ## Compatibility
 
 `@angular/core` and `@angular/forms` `^20.0.0 || ^21.0.0 || ^22.0.0`.