@nxgt/material 2.0.1 → 2.2.0

package/docs/components/form-fields.md

@@ -0,0 +1,816 @@
+# Form fields
+
+Labelled inputs with a value. Each one comes as a standalone field
+(`TextField`) and a React Hook Form wrapper (`TextFormField`) that takes
+`control` and `name` — see the [forms guide](../guides/forms.md) for wiring
+them into a form, and [what each field emits](../guides/forms.md#what-each-field-emits)
+for the value type each one writes. Everything is imported from
+`@nxgt/material/components`.
+
+| | Component | What it does |
+| --- | --- | --- |
+| <img src="../previews/form-fields-field.webp" width="96" alt=""> | [Field](#field) | Renders the field matching a config `type` |
+| <img src="../previews/form-fields-textfield.webp" width="96" alt=""> | [TextField](#textfield) | Labelled input with adornments and helper text |
+| <img src="../previews/form-fields-textareafield.webp" width="96" alt=""> | [TextareaField](#textareafield) | Labelled textarea with row sizing and a counter |
+| <img src="../previews/form-fields-emailfield.webp" width="96" alt=""> | [EmailField](#emailfield) | Validates on blur, `mailto:` button |
+| <img src="../previews/form-fields-passwordfield.webp" width="96" alt=""> | [PasswordField](#passwordfield) | Show / hide toggle and a strength meter |
+| <img src="../previews/form-fields-numberfield.webp" width="96" alt=""> | [NumberField](#numberfield) | `number \| null` with clamping and +/− buttons |
+| <img src="../previews/form-fields-percentfield.webp" width="96" alt=""> | [PercentField](#percentfield) | `NumberField` with a `%` suffix |
+| <img src="../previews/form-fields-currencyfield.webp" width="96" alt=""> | [CurrencyField](#currencyfield) | Locale-formatted amount with a currency suffix |
+| <img src="../previews/form-fields-phonefield.webp" width="96" alt=""> | [PhoneField](#phonefield) | International number, emits E.164 |
+| <img src="../previews/form-fields-urlfield.webp" width="96" alt=""> | [UrlField](#urlfield) | Validates on blur, open and copy buttons |
+| <img src="../previews/form-fields-searchfield.webp" width="96" alt=""> | [SearchField](#searchfield) | Clear button, spinner, debounced value |
+| <img src="../previews/form-fields-colorfield.webp" width="96" alt=""> | [ColorField](#colorfield) | Hex input with a picker |
+| <img src="../previews/form-fields-otpfield.webp" width="96" alt=""> | [OtpField](#otpfield) | One-time code input |
+| <img src="../previews/form-fields-inputgroupfield.webp" width="96" alt=""> | [InputGroupField](#inputgroupfield) | Labelled `InputGroup` with addons |
+| <img src="../previews/form-fields-inlineedit.webp" width="96" alt=""> | [InlineEdit](#inlineedit) | Click-to-edit text |
+| <img src="../previews/form-fields-countryfield.webp" width="96" alt=""> | [CountryField](#countryfield) | Country picker with flags |
+| <img src="../previews/form-fields-timezonefield.webp" width="96" alt=""> | [TimezoneField](#timezonefield) | Searchable IANA timezone picker |
+| <img src="../previews/form-fields-ratingfield.webp" width="96" alt=""> | [RatingField](#ratingfield) | Star rating |
+| <img src="../previews/form-fields-slider.webp" width="96" alt=""> | [Slider](#slider) | Single or range slider with a readout |
+| <img src="../previews/form-fields-switch.webp" width="96" alt=""> | [Switch](#switch) | Toggle switch, optionally in a labelled row |
+| <img src="../previews/form-fields-attributes.webp" width="96" alt=""> | [Attributes](#attributes) | Editor for typed custom attributes |
+| <img src="../previews/form-fields-contacts.webp" width="96" alt=""> | [Contacts](#contacts) | Typed contact list with a dialog |
+| <img src="../previews/form-fields-postaladdress.webp" width="96" alt=""> | [PostalAddress](#postaladdress) | Address card with an edit dialog |
+| <img src="../previews/form-fields-openinghours.webp" width="96" alt=""> | [OpeningHours](#openinghours) | Weekly opening hours with a dialog |
+
+## Field
+
+![Field](../previews/form-fields-field.webp)
+
+Renders the field matching a config `type` (text, select, date, upload, otp…).
+
+```tsx
+import { Field, FormField, type FieldConfig } from '@nxgt/material/components';
+import { useForm } from 'react-hook-form';
+
+const company: FieldConfig = { type: 'text', label: 'Company', placeholder: 'Acme Studio' };
+
+export function Standalone() {
+	return <Field config={company} />;
+}
+
+export function InAForm() {
+	const { control } = useForm({ defaultValues: { company: '' } });
+	return <FormField control={control} name="company" config={company} />;
+}
+```
+
+`Field` only renders; `FormField` is the one that reads and writes the form
+value, converting per `type` (`text` → `string`, `number` → `number | null`,
+`chips-single` → `string | null`, …). The `type` union is `FieldType`: `text`,
+`number`, `textarea`, `select`, `multi-select`, `chips-single`,
+`chips-multiple`, `radio-group`, `checkbox-group`, `switch`, `date`,
+`date-range`, `slider`, `time`, `image`, `upload`, `network-upload`, `otp`,
+`autocomplete`, `rich-text-editor`, `code-editor`, `check-card`,
+`select-card`. The rest of each config is that field's own props, and a
+config's `helperText` shows until `FormField` has an error message to show
+instead. A field is disabled by its config's `disabled` or by
+`useForm({ disabled })`. For `upload` and `network-upload`, `FormField` renders
+`UploadFormField` / `NetworkUploadFormField`, so the form holds the `File` or
+what `onUpload` resolved. `FieldType` also lists `location`, which has no
+config: the map is browser-only and lives on `@nxgt/material/map`, so use
+`LocationFormField` from there.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `config` | `FieldConfig` | — | `{ type, ...props of that field }` |
+| `control`, `name` | React Hook Form | — | `FormField` only |
+
+**Emits:** whatever the field for `type` emits, see
+[config-driven forms](../guides/forms.md#config-driven-forms).
+**Form wrapper:** `FormField` — `control`, `name` and `config`, see
+[forms](../guides/forms.md#the-pair).
+**Storybook:** `Form fields/Field` · **Vue:** `Field`
+
+---
+
+## TextField
+
+![TextField](../previews/form-fields-textfield.webp)
+
+Labelled input with leading / trailing adornments and helper text.
+
+```tsx
+import { TextField } from '@nxgt/material/components';
+import { User } from 'lucide-react';
+
+<TextField label="Name" placeholder="Ada Lovelace" helperText="As on your ID." leading={<User />} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `label` | `ReactNode` | — | shown above the input |
+| `helperText` | `ReactNode` | — | hint under the input; the error message when `error` |
+| `error` | `boolean` | — | error outline and helper colour |
+| `leading`, `trailing` | `ReactNode` | — | adornments inside the input (icon, unit, button) |
+
+Every other prop is the native `<input>`'s.
+
+**Emits:** the native `ChangeEvent<HTMLInputElement>`; `TextFormField` stores
+`string`, or `number | null` when `type="number"`.
+**Form wrapper:** `TextFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/TextField` · **Vue:** `TextField`, `TextFormField`
+
+---
+
+## TextareaField
+
+![TextareaField](../previews/form-fields-textareafield.webp)
+
+Labelled textarea with row sizing and a `maxLength` counter.
+
+```tsx
+import { TextareaField } from '@nxgt/material/components';
+
+<TextareaField label="Notes" helperText="Visible to the whole team." minRows={3} maxRows={8} maxLength={280} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `minRows` | `number` | — | minimum height in lines |
+| `maxRows` | `number` | — | maximum height in lines, then it scrolls |
+| `maxLength` | `number` | — | shows an `n/max` counter, red when over |
+| `showCount` | `boolean` | `true` when `maxLength` is set | force the counter on or off |
+| `error` | `boolean` | — | error outline and helper colour |
+
+**Emits:** the native `ChangeEvent<HTMLTextAreaElement>`; `TextareaFormField`
+stores `string`.
+**Form wrapper:** `TextareaFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/TextareaField` · **Vue:** `TextareaField`, `TextareaFormField`
+
+---
+
+## EmailField
+
+![EmailField](../previews/form-fields-emailfield.webp)
+
+Validates on blur; shows a `mailto:` button once the address is valid.
+
+```tsx
+import { EmailField } from '@nxgt/material/components';
+
+<EmailField label="Email" placeholder="ada@example.com" />
+```
+
+Takes `TextField`'s props minus `type`, `leading` and `trailing`. After the
+first blur an invalid address shows "Enter a valid email" unless you pass
+your own `error`. `autoComplete` defaults to `email`.
+
+**Emits:** the native `ChangeEvent<HTMLInputElement>`; `EmailFormField` stores
+`string` (the raw text, not validated — validate in the schema).
+**Form wrapper:** `EmailFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/EmailField` · **Vue:** `EmailField`, `EmailFormField`
+
+---
+
+## PasswordField
+
+![PasswordField](../previews/form-fields-passwordfield.webp)
+
+Show / hide toggle and an optional strength meter (`scorePassword`).
+
+```tsx
+import { PasswordField } from '@nxgt/material/components';
+
+<PasswordField label="New password" autoComplete="new-password" showStrength />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `showStrength` | `boolean` | `false` | strength meter under the input, scored by `scorePassword` |
+| `defaultVisible` | `boolean` | `false` | start with the text shown |
+| `autoComplete` | `string` | `'current-password'` | use `'new-password'` on sign-up |
+
+**Emits:** the native `ChangeEvent<HTMLInputElement>`; `PasswordFormField`
+stores `string`.
+**Form wrapper:** `PasswordFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/PasswordField` · **Vue:** `PasswordField`, `PasswordFormField`
+
+---
+
+## NumberField
+
+![NumberField](../previews/form-fields-numberfield.webp)
+
+Emits `number | null`, with min / max / step clamping, +/− buttons and a suffix.
+
+```tsx
+import { NumberField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Quantity() {
+	const [value, setValue] = useState<number | null>(2);
+	return <NumberField label="Quantity" value={value} onChange={setValue} min={1} max={10} />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number \| null` | `null` | controlled / uncontrolled amount |
+| `onChange` | `(value: number \| null) => void` | — | `null` when the input is empty |
+| `min`, `max` | `number` | — | clamps typed and stepped values |
+| `step` | `number` | `1` | the +/− increment |
+| `hideSteppers` | `boolean` | `false` | hides the +/− buttons |
+| `suffix` | `ReactNode` | — | unit after the input |
+| `aria-label` | `string` | — | names the input when it has no `label` (a part of a larger field) |
+
+**Emits:** `number | null`.
+**Form wrapper:** `NumberFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/NumberField` · **Vue:** `NumberField`, `NumberFormField`
+
+---
+
+## PercentField
+
+![PercentField](../previews/form-fields-percentfield.webp)
+
+`NumberField` with a `%` suffix.
+
+```tsx
+import { PercentField } from '@nxgt/material/components';
+
+<PercentField label="Discount" defaultValue={15} helperText="Off the list price." />
+```
+
+Takes `NumberField`'s props minus `suffix`, with `min` `0`, `max` `100` and
+`step` `1` by default. The value is the percentage itself (`15`), not a
+ratio (`0.15`).
+
+**Emits:** `number | null`.
+**Form wrapper:** `PercentFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/PercentField` · **Vue:** `PercentField`, `PercentFormField`
+
+---
+
+## CurrencyField
+
+![CurrencyField](../previews/form-fields-currencyfield.webp)
+
+Amount formatted to the locale on blur, with the currency's own decimals and
+a currency suffix (EUR by default).
+
+```tsx
+import { CurrencyField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Amount() {
+	const [value, setValue] = useState<number | null>(1234.5);
+	return <CurrencyField label="Amount" currency="USD" value={value} onChange={setValue} />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number \| null` | `null` | the amount |
+| `onChange` | `(value: number \| null) => void` | — | called while typing and on blur |
+| `currency` | `string` | `'EUR'` | the suffix text; formatting follows the `I18nProvider` language |
+| `fractionDigits` | `number` | the currency's own | decimals shown once the amount is committed (on blur): ISO 4217 by default — `JPY` 0, `EUR` 2, `KWD` 3 (2 for a code `Intl` does not know). Pass `2` to keep two decimals whatever the currency; the value is clamped to 0–20 (the range every `Intl` accepts), and `NaN` or `Infinity` counts as not given. What is typed is not rounded, on screen until blur nor in the emitted number: a `JPY` field shows `1,235` for `1234.5` and emits `1234.5` |
+
+**Emits:** `number | null` — never the formatted string.
+**Form wrapper:** `CurrencyFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/CurrencyField` · **Vue:** `CurrencyField`, `CurrencyFormField`
+
+---
+
+## PhoneField
+
+![PhoneField](../previews/form-fields-phonefield.webp)
+
+International number with a country picker; emits E.164.
+
+```tsx
+import { PhoneField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Mobile() {
+	const [value, setValue] = useState<string | null>('+33612345678');
+	return <PhoneField label="Mobile" value={value} onChange={setValue} defaultCountry="FR" />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string \| null` | `null` | an E.164 number (`+33612345678`) |
+| `onChange` | `(value: string \| null) => void` | — | `null` until the typed number is possible for the country |
+| `defaultCountry` | `string` (ISO 3166-1) | `'FR'` | the country used when the value has no `+` prefix |
+
+**Emits:** E.164 `string`, or `null` while the number is incomplete.
+**Form wrapper:** `PhoneFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/PhoneField` · **Vue:** `PhoneField`, `PhoneFormField`
+
+---
+
+## UrlField
+
+![UrlField](../previews/form-fields-urlfield.webp)
+
+Validates on blur; open-in-new-tab and copy buttons.
+
+```tsx
+import { UrlField } from '@nxgt/material/components';
+
+<UrlField label="Website" defaultValue="https://example.com" />
+```
+
+Takes `TextField`'s props minus `type`, `leading` and `trailing`. After the
+first blur an invalid URL shows "Enter a valid URL" unless you pass your own
+`error`. `autoComplete` defaults to `url`.
+
+**Emits:** the native `ChangeEvent<HTMLInputElement>`; `UrlFormField` stores
+`string` (the raw text).
+**Form wrapper:** `UrlFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/UrlField` · **Vue:** `UrlField`, `UrlFormField`
+
+---
+
+## SearchField
+
+![SearchField](../previews/form-fields-searchfield.webp)
+
+Search icon, clear button and spinner, with a debounced `onValueChange`.
+
+```tsx
+import { SearchField } from '@nxgt/material/components';
+
+<SearchField placeholder="Search orders" debounceMs={300} onValueChange={(query) => console.log(query)} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `onValueChange` | `(value: string) => void` | — | the text, debounced when `debounceMs` is set |
+| `debounceMs` | `number` | `0` | delay before `onValueChange`; `0` calls it on every key |
+| `loading` | `boolean` | `false` | spinner in place of the clear button |
+| `onChange` | native handler | — | still fires on every key, undebounced |
+
+**Emits:** `string` through `onValueChange`; `SearchFormField` stores `string`.
+**Form wrapper:** `SearchFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/SearchField` · **Vue:** `SearchField`, `SearchFormField`
+
+---
+
+## ColorField
+
+![ColorField](../previews/form-fields-colorfield.webp)
+
+Hex input with a colour picker in a popover.
+
+```tsx
+import { ColorField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function BrandColor() {
+	const [value, setValue] = useState('#2563eb');
+	return <ColorField label="Brand color" value={value} onChange={setValue} />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | `'#000000'` | a hex colour, 3 or 6 digits |
+| `onChange` | `(value: string) => void` | — | called when a valid colour is committed |
+
+**Emits:** a lowercase six-digit hex `string` (`#2563eb`); an invalid entry
+reverts and emits nothing.
+**Form wrapper:** `ColorFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/ColorField` · **Vue:** `ColorField`, `ColorFormField`
+
+---
+
+## OtpField
+
+![OtpField](../previews/form-fields-otpfield.webp)
+
+One-time code input of configurable length.
+
+```tsx
+import { OtpField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Code() {
+	const [value, setValue] = useState('');
+	return <OtpField label="Enter OTP" length={6} value={value} onChange={setValue} />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `length` | `number` | `6` | number of slots, split in two groups |
+| `value` / `onChange` | `string` / `(value: string) => void` | — | from `input-otp` |
+| `onComplete` | `(value: string) => void` | — | once every slot is filled |
+| `error` | `boolean` | — | error colour on the slots |
+| `id` | `string` | from `useId()` | the input's id, which the label points to; the generated one is the same on the server and the client |
+
+**Emits:** `string` (the digits typed so far).
+**Form wrapper:** `OtpFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/OtpField` · **Vue:** `OtpField`, `OtpFormField`, `InputOTP`
+
+---
+
+## InputGroupField
+
+![InputGroupField](../previews/form-fields-inputgroupfield.webp)
+
+Labelled `InputGroup` with addons and helper text.
+
+```tsx
+import { InputGroupButton, InputGroupField } from '@nxgt/material/components';
+import { SearchIcon } from 'lucide-react';
+
+<InputGroupField
+	label="Price"
+	type="number"
+	placeholder="0.00"
+	leading="$"
+	trailing={
+		<InputGroupButton variant="ghost">
+			<SearchIcon />
+		</InputGroupButton>
+	}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `leading`, `trailing` | `ReactNode` | — | text is wrapped in `InputGroupText`; an `InputGroupButton` is kept as is |
+| `renderInput` | `(input: ReactNode) => ReactNode` | identity | wrap the input (a tooltip, a mask) |
+| `error` | `boolean` | — | error outline and helper colour |
+
+**Emits:** the native `ChangeEvent<HTMLInputElement>`; `InputGroupFormField`
+stores `string`, or `number | null` when `type="number"`.
+**Form wrapper:** `InputGroupFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/InputGroupField` · **Vue:** `InputGroupField`, `InputGroupFormField`
+
+---
+
+## InlineEdit
+
+![InlineEdit](../previews/form-fields-inlineedit.webp)
+
+Click-to-edit text with save and cancel.
+
+```tsx
+import { InlineEdit } from '@nxgt/material/components';
+
+<InlineEdit label="Title" defaultValue="Spring catalogue" onSave={(title) => console.log(title)} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | `''` | the committed text |
+| `onSave` | `(value: string) => void` | — | on save (Enter or the check button), not on each key |
+| `placeholder` | `string` | "Click to edit" | shown while empty |
+| `disabled` | `boolean` | `false` | read-only text |
+
+**Emits:** `string`, trimmed, on save only.
+**Form wrapper:** `InlineEditFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/InlineEdit` · **Vue:** `InlineEdit`
+
+---
+
+## CountryField
+
+![CountryField](../previews/form-fields-countryfield.webp)
+
+Single or multiple country picker with flags.
+
+```tsx
+import { CountryField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Countries() {
+	const [value, setValue] = useState<string[]>(['FR', 'BE']);
+	return (
+		<CountryField
+			label="Countries"
+			mode="multiple"
+			value={value}
+			onValueChange={(next) => setValue(next ?? [])}
+		/>
+	);
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | `'single'` | one code or a list of chips |
+| `value` | `string` / `string[]` | — | ISO 3166-1 alpha-2 codes (`'FR'`) |
+| `onValueChange` | `(value?: string \| null) => void` / `(value?: string[] \| null) => void` | — | per `mode` |
+| `countries` | `PhoneCountry[]` | `PHONE_COUNTRIES` | restrict the list |
+
+**Emits:** ISO code `string | null` in `single` mode, `string[]` in `multiple`.
+**Form wrapper:** `CountryFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/CountryField` · **Vue:** `CountryField`, `CountryFormField`
+
+---
+
+## TimezoneField
+
+![TimezoneField](../previews/form-fields-timezonefield.webp)
+
+Searchable IANA timezone picker with localised labels.
+
+```tsx
+import { TimezoneField } from '@nxgt/material/components';
+import { useState } from 'react';
+
+export function Zone() {
+	const [value, setValue] = useState<string | null>('Europe/Paris');
+	return <TimezoneField label="Timezone" value={value} onChange={setValue} />;
+}
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` | `string \| null` | `null` | an IANA identifier |
+| `onChange` | `(value: string \| null) => void` | — | `null` when cleared |
+| `timezones` | `readonly string[]` | `TIMEZONES` | restrict the list |
+
+**Emits:** IANA identifier `string | null` (`'Europe/Paris'`).
+**Form wrapper:** `TimezoneFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/TimezoneField` · **Vue:** `TimezoneField`, `TimezoneFormField`
+
+---
+
+## RatingField
+
+![RatingField](../previews/form-fields-ratingfield.webp)
+
+Star rating with hover preview, click-to-clear and a read-only mode.
+
+```tsx
+import { RatingField } from '@nxgt/material/components';
+
+<RatingField label="Satisfaction" defaultValue={3} onChange={(stars) => console.log(stars)} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number` | `0` | clamped to `0…max` |
+| `onChange` | `(value: number) => void` | — | `0` when cleared |
+| `max` | `number` | `5` | number of stars |
+| `allowClear` | `boolean` | `true` | clicking the current star clears to `0` |
+| `readOnly` | `boolean` | — | display only, no hover |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'default'` | `'warning'` | star colour |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on the `radiogroup` |
+
+The stars are a `radiogroup` named by the label: `getByRole('radiogroup', {
+name: 'Satisfaction' })`.
+
+**Emits:** `number` (`0` means no rating).
+**Form wrapper:** `RatingFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/RatingField` · **Vue:** `RatingField`, `RatingFormField`
+
+---
+
+## Slider
+
+![Slider](../previews/form-fields-slider.webp)
+
+Labelled single or range slider with an editable value and ticks.
+
+```tsx
+import { Slider } from '@nxgt/material/components';
+
+<Slider label="Price" leading={0} trailing={100} defaultValue={[20, 70]} max={100} ticks={5} />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number[]` | `[min]` | one thumb per entry: `[40]` or `[20, 70]` |
+| `onValueChange` | `(value: number[]) => void` | — | always an array |
+| `min`, `max`, `step` | `number` | `0`, `100`, `1` | range and increment |
+| `ticks` | `boolean \| number` | — | tick marks, or that many |
+| `showReadout` | `boolean` | `true` | editable number inputs next to the label |
+| `leading`, `trailing` | `ReactNode` | — | text at each end of the track |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on every thumb |
+
+Each thumb (`role="slider"`) is named by an `aria-labelledby` or `aria-label`
+you pass, else by the label (a vertical slider does not show it, and it still
+names the thumbs); a range's thumbs add "Minimum" and "Maximum":
+`getByRole('slider', { name: 'Price Minimum' })`. `aria-invalid` (or `error`)
+goes on every thumb too, not on the root `span`.
+
+**Emits:** `number[]`. `SliderFormField` stores a plain `number` when the
+form's value is a number, and `number[]` when it is an array — the default
+value decides.
+**Form wrapper:** `SliderFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/Slider` · **Vue:** `Slider`, `SliderField`, `SliderFormField`
+
+---
+
+## Switch
+
+![Switch](../previews/form-fields-switch.webp)
+
+Toggle switch, optionally in a labelled, bordered row.
+
+```tsx
+import { Switch } from '@nxgt/material/components';
+
+<Switch label="Notifications" placeholder="Email me when an order ships" helperText="You can change this at any time." defaultChecked />
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `checked` / `defaultChecked` | `boolean` | — | Radix switch state |
+| `onCheckedChange` | `(checked: boolean) => void` | — | |
+| `placeholder` | `ReactNode` | — | text inside the bordered row; with it, `label` sits above the row |
+| `label` | `ReactNode` | — | without `placeholder`, it is the row text instead |
+| `helperText` | `ReactNode` | — | line under the row (or under the bare switch), with or without `placeholder`; `SwitchFormField` puts the validation message here |
+| `error` | `boolean` | — | error border on the row, error helper text, `aria-invalid` on the `switch` (a passed `aria-invalid` wins) |
+| `className` | `string` | — | on the outermost element: the field, else the row, else the switch |
+
+The row's text is the switch's `<label>`: clicking it toggles the switch.
+Without a `placeholder` it is also the name (`getByRole('switch', { name:
+'Notifications' })`). With a `placeholder`, the `label` above names the switch
+and the row text is its description, so a screen reader says "Notifications,
+switch, Email me when an order ships" and `getByRole('switch', { name:
+'Notifications' })` finds it. An `aria-label` or `aria-labelledby` you pass
+wins. The `helperText` (the validation message, under `SwitchFormField`)
+describes the switch too, and an `aria-describedby` you pass is kept beside
+these. With `required`, the switch has `aria-required` and the label's asterisk
+is hidden from screen readers, so the name stays "Terms", not "Terms*".
+Without an `id` one is generated, under `SwitchFormField` too (it used to be
+the field's `name`, which two forms on one page shared). The row is tinted
+while the switch is on, from `checked` or, uncontrolled, from `defaultChecked` and each toggle, and carries
+`data-checked="true"` / `"false"`, so select rows that are on with
+`[data-checked="true"]` (a bare `[data-checked]` also matches rows that are
+off). `data-filed` says the same and is deprecated: it goes in 3.0.
+
+**Emits:** `boolean`.
+**Form wrapper:** `SwitchFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/Switch` · **Vue:** `Switch`, `SwitchField`, `SwitchFormField`
+
+---
+
+## Attributes
+
+![Attributes](../previews/form-fields-attributes.webp)
+
+Editor for typed custom attributes (string, number, date, select, rich text…).
+
+```tsx
+import { AttributesField, type Attribute } from '@nxgt/material/components';
+
+const attributes: Attribute[] = [
+	{ name: 'color', label: 'Color', type: 'COLOR' },
+	{ name: 'size', label: 'Size', type: 'SELECT', options: ['S', 'M', 'L'] },
+];
+
+<AttributesField label="Attributes" attributes={attributes} onChange={(next) => console.log(next)} />
+```
+
+Parts: `AttributesField` (the editable list), `AttributesList` (display with
+`onAdd` / `onEdit`), `AttributeDialog` and `AttributeForm` (define one
+attribute), `AttributeValuesForm` (fill values for a set of attributes).
+Form wrappers: `AttributesFormField` (the definitions),
+`AttributeValuesFormFieldSet` and `AttributeValueFormField` (the values).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `attributes` | `Attribute[]` | `[]` | the definitions; a new value (a form `reset`) replaces the list |
+| `onChange` | `(values: Attribute[]) => void` | — | after each add, edit or delete |
+| `readonly` | `boolean` | — | hides add and edit |
+| `label` | `ReactNode` | — | required; the section title |
+| `helperText` / `error` | `ReactNode` / `boolean` | — | text under the list; red when `error` (`AttributesFormField` sets both from the field's error, and shows your own `helperText` while there is none) |
+
+**Emits:** `Attribute[]` (`{ name, label, type, options?, unit?, defaultValue?, … }`);
+`AttributeValuesFormFieldSet` writes an object keyed by attribute `name`.
+**Form wrapper:** `AttributesFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair), [what each field emits](../guides/forms.md#what-each-field-emits)
+and [composite values](../guides/forms.md#composite-values).
+**Storybook:** `Form fields/Attributes` · **Vue:** `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm`, `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField`
+
+---
+
+## Contacts
+
+![Contacts](../previews/form-fields-contacts.webp)
+
+Typed contact list (phone, email, URL…) with an add / edit dialog.
+
+```tsx
+import { type Contact, Contacts, ContactType } from '@nxgt/material/components';
+
+const contacts: Contact[] = [
+	{ type: ContactType.Phone, value: '+33 1 23 45 67 89', label: 'Front desk' },
+	{ type: ContactType.Email, value: 'contact@example.com' },
+];
+
+<Contacts label="Contacts" data={contacts} onAdd={() => {}} onEdit={() => {}} />
+```
+
+Parts: `Contacts` (the list) and `ContactDialog` (add / edit). `Contacts` only
+displays and calls back; `ContactsFormField` owns the dialog and the array.
+`ContactItem`, a row bound to a react-hook-form array, is **deprecated** and
+removed in 3.0: use `ContactsFormField`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `Contact[] \| null` | `[]` | `{ type, value, label? }`, `type` a `ContactType` |
+| `onAdd` | `() => void` | — | shows the add button |
+| `onEdit` | `(contact: Contact, index: number) => void` | — | shows an edit button per row |
+| `disabled` | `boolean` | — | hides add and edit |
+
+**Emits:** `ContactsFormField` stores `Contact[]`, and shows the array's
+error (`errors.<name>.message` or `.root.message`) under the list.
+**Form wrapper:** `ContactsFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair), [what each field emits](../guides/forms.md#what-each-field-emits)
+and [composite values](../guides/forms.md#composite-values).
+**Storybook:** `Form fields/Contacts` · **Vue:** `Contacts`, `ContactItem`, `ContactDialog`, `ContactsFormField`
+
+---
+
+## PostalAddress
+
+![PostalAddress](../previews/form-fields-postaladdress.webp)
+
+Address card with an edit dialog.
+
+```tsx
+import { PostalAddress, type PostalAddressFieldValue } from '@nxgt/material/components';
+
+const address: PostalAddressFieldValue = {
+	street: '123 Rue Principale',
+	postalCode: '75001',
+	locality: 'Paris',
+	country: 'FR',
+};
+
+<PostalAddress label="Address" data={address} onEdit={() => {}} />
+```
+
+Parts: `PostalAddress` (the card), `PostalAddressDialog` (the edit form).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `PostalAddressFieldValue \| null` | — | `{ street?, locality?, region?, postalCode?, country? }`, `country` an ISO code |
+| `onEdit` | `() => void` | — | shows the edit button |
+| `disabled` | `boolean` | — | hides it |
+
+**Emits:** `PostalAddressFormField` stores a `PostalAddressFieldValue`
+object, and `{}` when the address is removed.
+**Form wrapper:** `PostalAddressFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair), [what each field emits](../guides/forms.md#what-each-field-emits)
+and [composite values](../guides/forms.md#composite-values).
+**Storybook:** `Form fields/PostalAddress` · **Vue:** `PostalAddress`, `PostalAddressDialog`, `PostalAddressFormField`
+
+---
+
+## OpeningHours
+
+![OpeningHours](../previews/form-fields-openinghours.webp)
+
+Weekly opening hours with an add / edit dialog.
+
+```tsx
+import { type OpeningHour, OpeningHours } from '@nxgt/material/components';
+
+const hours: OpeningHour[] = [
+	{ dayOfWeek: 1, openTime: '09:00', closeTime: '18:00' },
+	{ dayOfWeek: 6, isClosed: true },
+];
+
+<OpeningHours label="Opening hours" data={hours} onAdd={() => {}} onEdit={() => {}} />
+```
+
+Parts: `OpeningHours` (the list) and `OpeningHoursDialog` (add / edit).
+`OpeningHoursItem`, a day row bound to a react-hook-form array, is
+**deprecated** and removed in 3.0: use `OpeningHoursFormField`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `OpeningHour[] \| null` | `[]` | `{ dayOfWeek, openTime?, closeTime?, isClosed? }`, times as `'HH:mm'` |
+| `onAdd` | `() => void` | — | shows the add button |
+| `onAddAll` | `() => void` | — | shows "Add all days" |
+| `onEdit` | `(value: OpeningHour, index: number) => void` | — | shows an edit button per day |
+
+`OpeningHoursFormField` takes `showAddAllDays` (default `false`) to offer the
+"Add all days" button.
+
+**Emits:** `OpeningHoursFormField` stores `OpeningHour[]`, and shows the
+array's error (`errors.<name>.message` or `.root.message`) under the list.
+**Form wrapper:** `OpeningHoursFormField` — `control` and `name`, see
+[forms](../guides/forms.md#the-pair), [what each field emits](../guides/forms.md#what-each-field-emits)
+and [composite values](../guides/forms.md#composite-values).
+**Storybook:** `Form fields/OpeningHours` · **Vue:** `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem`, `OpeningHoursFormField`