@nxgt/material-vue 0.21.0 → 0.22.0

package/docs/components/form-fields.md

@@ -0,0 +1,1044 @@
+# Form fields
+
+Labelled inputs with a value. Each one comes as a standalone field
+(`TextField`, bound with `v-model`) and a vee-validate wrapper
+(`TextFormField`) that takes a `name` inside a `useForm` form — 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-vue/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…).
+
+```vue
+<script setup lang="ts">
+import { useField, useForm } from 'vee-validate';
+import { Field, type FieldConfig } from '@nxgt/material-vue/components';
+
+const company: FieldConfig = { type: 'text', label: 'Company', placeholder: 'Acme Studio' };
+
+useForm({ initialValues: { company: '' } });
+const { value } = useField<string>('company');
+</script>
+
+<template>
+  <Field :config="company" v-model="value" />
+</template>
+```
+
+`Field` renders the component for `type` and passes the rest of the config to
+it as props; `v-model` and any other attribute fall through to that
+component, so the value is whatever that field emits (`text` → `string`,
+`number` → `number | null`, `chips-single` → `string[]`, …). 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`. `select` and `multi-select` render an `Autocomplete` in
+`single` / `multiple` mode; `switch` renders `SwitchField`, `slider`
+renders `SliderField`. `FieldType` also lists `location`, which has no
+config: the map is browser-only and lives on `@nxgt/material-vue/map`.
+`resolveField(config)` returns the `{ component, props }` pair if you need
+to render it yourself.
+
+Unlike React, there is no config-driven `FormField` wrapper: bind `Field`
+with `useField` as above (the error message is then yours to pass as
+`helperText` / `error`), or use the per-type wrapper (`TextFormField`,
+`SelectChipFormField`…) when you want the error shown for you.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `config` | `FieldConfig` | — | `{ type, ...props of that field }` |
+| `v-model` | per `type` | — | falls through to the rendered field |
+
+**Emits:** whatever the field for `type` emits, see
+[config-driven forms](../guides/forms.md#config-driven-forms).
+**Form wrapper:** none — `useField` + `v-model`, or the per-type wrapper, see
+[forms](../guides/forms.md#the-pair).
+**Storybook:** `Form fields/Field` · **React:** `Field`, `FormField`
+
+---
+
+## TextField
+
+![TextField](../previews/form-fields-textfield.webp)
+
+Labelled input with leading / trailing adornments and helper text.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { User } from '@lucide/vue';
+import { TextField } from '@nxgt/material-vue/components';
+
+const name = ref('');
+</script>
+
+<template>
+  <TextField v-model="name" label="Name" placeholder="Ada Lovelace" helper-text="As on your ID.">
+    <template #leading>
+      <span class="flex items-center justify-center"><User class="size-4" /></span>
+    </template>
+  </TextField>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `string \| number` | — | the input's value |
+| `label` | `string` | — | shown above the input, with `*` when `required` |
+| `helper-text` | `string` | — | hint under the input; the error message when `error` |
+| `error` | `boolean` | — | error outline and helper colour |
+| `type` | `string` | — | the native input type |
+| `#leading`, `#trailing` | slots | — | adornments inside the input (icon, unit, button) |
+
+Every other attribute goes to the native `<input>`.
+
+**Emits:** `update:modelValue` with `string | number`; `TextFormField`
+stores `string`.
+**Form wrapper:** `TextFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/TextField` · **React:** `TextField`, `TextFormField`
+
+---
+
+## TextareaField
+
+![TextareaField](../previews/form-fields-textareafield.webp)
+
+Labelled textarea with row sizing and a `maxLength` counter.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TextareaField } from '@nxgt/material-vue/components';
+
+const notes = ref('');
+</script>
+
+<template>
+  <TextareaField
+    v-model="notes"
+    label="Notes"
+    helper-text="Visible to the whole team."
+    :min-rows="3"
+    :max-rows="8"
+    :max-length="280"
+  />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `min-rows` | `number` | — | minimum height in lines |
+| `max-rows` | `number` | — | maximum height in lines, then it scrolls |
+| `max-length` | `number` | — | shows an `n/max` counter, red when over |
+| `show-count` | `boolean` | `true` when `max-length` is set | force the counter on or off |
+| `error` | `boolean` | — | error outline and helper colour |
+
+**Emits:** `update:modelValue` with `string | number`; `TextareaFormField`
+stores `string`.
+**Form wrapper:** `TextareaFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/TextareaField` · **React:** `TextareaField`, `TextareaFormField`
+
+---
+
+## EmailField
+
+![EmailField](../previews/form-fields-emailfield.webp)
+
+Validates on blur; shows a `mailto:` button once the address is valid.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { EmailField } from '@nxgt/material-vue/components';
+
+const email = ref('');
+</script>
+
+<template>
+  <EmailField v-model="email" label="Email" placeholder="ada@example.com" />
+</template>
+```
+
+Takes `TextField`'s props minus `type` (the leading mail icon and the
+trailing button fill both slots). After the first blur an invalid address
+shows "Enter a valid email" unless you pass your own `error`. `autocomplete`
+defaults to `email`. `isEmail` is exported for your own checks.
+
+**Emits:** `update:modelValue` with `string`; `EmailFormField` stores
+`string` (the raw text, not validated — validate in the schema).
+**Form wrapper:** `EmailFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/EmailField` · **React:** `EmailField`, `EmailFormField`
+
+---
+
+## PasswordField
+
+![PasswordField](../previews/form-fields-passwordfield.webp)
+
+Show / hide toggle and an optional strength meter (`scorePassword`).
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { PasswordField } from '@nxgt/material-vue/components';
+
+const password = ref('');
+</script>
+
+<template>
+  <PasswordField v-model="password" label="New password" autocomplete="new-password" show-strength />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `show-strength` | `boolean` | `false` | strength meter under the input, scored by `scorePassword` |
+| `default-visible` | `boolean` | `false` | start with the text shown |
+| `autocomplete` | `string` | `'current-password'` | use `'new-password'` on sign-up |
+
+**Emits:** `update:modelValue` with `string`; `PasswordFormField` stores
+`string`.
+**Form wrapper:** `PasswordFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/PasswordField` · **React:** `PasswordField`, `PasswordFormField`
+
+---
+
+## NumberField
+
+![NumberField](../previews/form-fields-numberfield.webp)
+
+Emits `number | null`, with min / max / step clamping, +/− buttons and a suffix.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { NumberField } from '@nxgt/material-vue/components';
+
+const quantity = ref<number | null>(2);
+</script>
+
+<template>
+  <NumberField v-model="quantity" label="Quantity" :min="1" :max="10" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `number \| null` | — | `null` when the input is empty |
+| `min`, `max` | `number` | — | clamps typed (on blur) and stepped values |
+| `step` | `number` | `1` | the +/− increment |
+| `hide-steppers` | `boolean` | `false` | hides the +/− buttons |
+| `#suffix` | slot | — | unit after the input |
+| `aria-label` | `string` | — | names the input when it has no `label` (a part of a larger field) |
+
+**Emits:** `update:modelValue` with `number | null`.
+**Form wrapper:** `NumberFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/NumberField` · **React:** `NumberField`, `NumberFormField`
+
+---
+
+## PercentField
+
+![PercentField](../previews/form-fields-percentfield.webp)
+
+`NumberField` with a `%` suffix.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { PercentField } from '@nxgt/material-vue/components';
+
+const discount = ref<number | null>(15);
+</script>
+
+<template>
+  <PercentField v-model="discount" label="Discount" helper-text="Off the list price." />
+</template>
+```
+
+Takes `NumberField`'s props, with `min` `0`, `max` `100` and `step` `1` by
+default; the `%` fills the `#suffix` slot. The value is the percentage itself
+(`15`), not a ratio (`0.15`).
+
+**Emits:** `update:modelValue` with `number | null`.
+**Form wrapper:** `PercentFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/PercentField` · **React:** `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).
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CurrencyField } from '@nxgt/material-vue/components';
+
+const amount = ref<number | null>(1234.5);
+</script>
+
+<template>
+  <CurrencyField v-model="amount" label="Amount" currency="USD" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `number \| null` | — | the amount; updated while typing and on blur |
+| `currency` | `string` | `'EUR'` | the suffix text; formatting follows the `I18nProvider` language |
+| `fraction-digits` | `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:** `update:modelValue` with `number | null` — never the formatted
+string.
+**Form wrapper:** `CurrencyFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/CurrencyField` · **React:** `CurrencyField`, `CurrencyFormField`
+
+---
+
+## PhoneField
+
+![PhoneField](../previews/form-fields-phonefield.webp)
+
+International number with a country picker; emits E.164.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { PhoneField } from '@nxgt/material-vue/components';
+
+const mobile = ref<string | null>('+33612345678');
+</script>
+
+<template>
+  <PhoneField v-model="mobile" label="Mobile" default-country="FR" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `string \| null` | — | an E.164 number (`+33612345678`); `null` until the typed number is possible for the country |
+| `default-country` | `string` (ISO 3166-1) | `'FR'` | the country used when the value has no `+` prefix |
+
+**Emits:** `update:modelValue` with an E.164 `string`, or `null` while the
+number is incomplete.
+**Form wrapper:** `PhoneFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/PhoneField` · **React:** `PhoneField`, `PhoneFormField`
+
+---
+
+## UrlField
+
+![UrlField](../previews/form-fields-urlfield.webp)
+
+Validates on blur; open-in-new-tab and copy buttons.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UrlField } from '@nxgt/material-vue/components';
+
+const website = ref('https://example.com');
+</script>
+
+<template>
+  <UrlField v-model="website" label="Website" />
+</template>
+```
+
+Takes `TextField`'s props minus `type`. After the first blur an invalid URL
+shows "Enter a valid URL" unless you pass your own `error`. `autocomplete`
+defaults to `url`.
+
+**Emits:** `update:modelValue` with `string`; `UrlFormField` stores `string`
+(the raw text).
+**Form wrapper:** `UrlFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/UrlField` · **React:** `UrlField`, `UrlFormField`
+
+---
+
+## SearchField
+
+![SearchField](../previews/form-fields-searchfield.webp)
+
+Search icon, clear button and spinner, with a debounced `value-change` event.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchField } from '@nxgt/material-vue/components';
+
+const query = ref('');
+</script>
+
+<template>
+  <SearchField
+    v-model="query"
+    placeholder="Search orders"
+    :debounce-ms="300"
+    @value-change="(value) => console.log(value)"
+  />
+</template>
+```
+
+| Prop / event | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `@value-change` | `(value: string) => void` | — | the text, debounced when `debounce-ms` is set |
+| `debounce-ms` | `number` | `0` | delay before `value-change`; `0` emits it on every key |
+| `loading` | `boolean` | `false` | spinner in the input |
+| `v-model` | `string` | — | still updated on every key, undebounced |
+
+**Emits:** `update:modelValue` and `value-change`, both `string`;
+`SearchFormField` stores `string`.
+**Form wrapper:** `SearchFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/SearchField` · **React:** `SearchField`, `SearchFormField`
+
+---
+
+## ColorField
+
+![ColorField](../previews/form-fields-colorfield.webp)
+
+Hex input with a colour picker in a popover.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ColorField } from '@nxgt/material-vue/components';
+
+const brand = ref('#2563eb');
+</script>
+
+<template>
+  <ColorField v-model="brand" label="Brand color" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `string` | `'#000000'` shown when unset | a hex colour, 3 or 6 digits |
+
+**Emits:** `update:modelValue` with a lowercase six-digit hex `string`
+(`#2563eb`) when a valid colour is committed; an invalid entry reverts and
+emits nothing.
+**Form wrapper:** `ColorFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/ColorField` · **React:** `ColorField`, `ColorFormField`
+
+---
+
+## OtpField
+
+![OtpField](../previews/form-fields-otpfield.webp)
+
+One-time code input of configurable length.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { OtpField } from '@nxgt/material-vue/components';
+
+const code = ref('');
+</script>
+
+<template>
+  <OtpField v-model="code" label="Enter OTP" :length="6" @complete="(value) => console.log(value)" />
+</template>
+```
+
+| Prop / event | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `length` | `number` | `6` | number of slots, split in two groups |
+| `v-model` | `string` | — | the digits typed so far |
+| `@complete` | `(value: string) => void` | — | once every slot is filled (from `vue-input-otp`) |
+| `error` | `boolean` | — | error colour on the slots |
+| `id` | `string` | from `useId()` | the input's id, which the label points to |
+
+`InputOTP`, `InputOTPGroup`, `InputOTPSlot` and `InputOTPSeparator` are the
+unlabelled primitives it is built from, for a hand-built layout:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from '@nxgt/material-vue/components';
+
+const pin = ref('');
+</script>
+
+<template>
+  <InputOTP v-model="pin" :maxlength="4">
+    <InputOTPGroup>
+      <InputOTPSlot :index="0" />
+      <InputOTPSlot :index="1" />
+    </InputOTPGroup>
+    <InputOTPSeparator />
+    <InputOTPGroup>
+      <InputOTPSlot :index="2" />
+      <InputOTPSlot :index="3" />
+    </InputOTPGroup>
+  </InputOTP>
+</template>
+```
+
+**Emits:** `update:modelValue` with `string` (the digits typed so far).
+**Form wrapper:** `OtpFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/OtpField` · **React:** `OtpField`, `OtpFormField`
+
+---
+
+## InputGroupField
+
+![InputGroupField](../previews/form-fields-inputgroupfield.webp)
+
+Labelled `InputGroup` with addons and helper text.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SearchIcon } from '@lucide/vue';
+import { InputGroupButton, InputGroupField, InputGroupText } from '@nxgt/material-vue/components';
+
+const price = ref('');
+</script>
+
+<template>
+  <InputGroupField v-model="price" label="Price" type="number" placeholder="0.00">
+    <template #leading>
+      <InputGroupText>$</InputGroupText>
+    </template>
+    <template #trailing>
+      <InputGroupButton aria-label="Search"><SearchIcon /></InputGroupButton>
+    </template>
+  </InputGroupField>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `#leading`, `#trailing` | slots | — | each is placed in an `InputGroupAddon`; wrap text in `InputGroupText` |
+| `v-model` | `string \| number` | — | the input's value |
+| `error` | `boolean` | — | error outline and helper colour |
+
+Other attributes (`type`, `inputmode`…) go to the input. React's
+`renderInput` has no Vue equivalent.
+
+**Emits:** `update:modelValue` with `string | number`; `InputGroupFormField`
+stores `string | number`.
+**Form wrapper:** `InputGroupFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/InputGroupField` · **React:** `InputGroupField`, `InputGroupFormField`
+
+---
+
+## InlineEdit
+
+![InlineEdit](../previews/form-fields-inlineedit.webp)
+
+Click-to-edit text with save and cancel.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { InlineEdit } from '@nxgt/material-vue/components';
+
+const title = ref('Spring catalogue');
+</script>
+
+<template>
+  <InlineEdit v-model="title" label="Title" @save="(value) => console.log(value)" />
+</template>
+```
+
+| Prop / event | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `string` | `''` | the committed text; updated on save only |
+| `@save` | `(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:** `update:modelValue` and `save`, both `string`, trimmed, on save
+only.
+**Form wrapper:** none — bind `v-model` to a `useField` value, see
+[forms](../guides/forms.md#the-pair).
+**Storybook:** `Form fields/InlineEdit` · **React:** `InlineEdit`, `InlineEditFormField`
+
+---
+
+## CountryField
+
+![CountryField](../previews/form-fields-countryfield.webp)
+
+Single or multiple country picker with flags.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { CountryField } from '@nxgt/material-vue/components';
+
+const countries = ref<string[]>(['FR', 'BE']);
+</script>
+
+<template>
+  <CountryField v-model="countries" label="Countries" mode="multiple" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mode` | `'single' \| 'multiple'` | `'single'` | one code or a list of chips |
+| `v-model` | `string \| string[] \| null` | — | ISO 3166-1 alpha-2 codes (`'FR'`), per `mode` |
+| `countries` | `PhoneCountry[]` | `PHONE_COUNTRIES` | restrict the list |
+
+**Emits:** `update:modelValue` with an ISO code `string | null` in `single`
+mode, `string[]` in `multiple`.
+**Form wrapper:** `CountryFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/CountryField` · **React:** `CountryField`, `CountryFormField`
+
+---
+
+## TimezoneField
+
+![TimezoneField](../previews/form-fields-timezonefield.webp)
+
+Searchable IANA timezone picker with localised labels.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimezoneField } from '@nxgt/material-vue/components';
+
+const zone = ref<string | null>('Europe/Paris');
+</script>
+
+<template>
+  <TimezoneField v-model="zone" label="Timezone" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `string \| null` | `null` | an IANA identifier; `null` when cleared |
+| `timezones` | `readonly string[]` | `TIMEZONES` | restrict the list |
+
+It is a `ComboboxField` over the zones and takes its other props.
+
+**Emits:** `update:modelValue` with an IANA identifier `string | null`
+(`'Europe/Paris'`).
+**Form wrapper:** `TimezoneFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/TimezoneField` · **React:** `TimezoneField`, `TimezoneFormField`
+
+---
+
+## RatingField
+
+![RatingField](../previews/form-fields-ratingfield.webp)
+
+Star rating with hover preview, click-to-clear and a read-only mode.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { RatingField } from '@nxgt/material-vue/components';
+
+const stars = ref(3);
+</script>
+
+<template>
+  <RatingField v-model="stars" label="Satisfaction" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `number` | `0` | clamped to `0…max`; `0` when cleared |
+| `max` | `number` | `5` | number of stars |
+| `allow-clear` | `boolean` | `true` | clicking the current star clears to `0` |
+| `read-only` | `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:** `update:modelValue` with `number` (`0` means no rating).
+**Form wrapper:** `RatingFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/RatingField` · **React:** `RatingField`, `RatingFormField`
+
+---
+
+## Slider
+
+![Slider](../previews/form-fields-slider.webp)
+
+Labelled single or range slider with a value readout.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SliderField } from '@nxgt/material-vue/components';
+
+const price = ref<number[]>([20, 70]);
+</script>
+
+<template>
+  <SliderField v-model="price" label="Price" :min="0" :max="100" />
+</template>
+```
+
+In Vue the labelled field is `SliderField`; `Slider` is the bare Reka UI
+slider (track, range and thumbs, `v-model` always `number[]`) it is built on.
+React's `ticks`, `leading` / `trailing` and editable readout inputs are not
+in `SliderField`: its readout is text.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` | `number \| number[]` | `[min]` shown when unset | a number for one thumb, an array for one thumb per entry: `[20, 70]` |
+| `min`, `max`, `step` | `number` | `0`, `100`, `1` | range and increment |
+| `show-readout` | `boolean` | `true` | the value(s) next to the label |
+| `required` | `boolean` | — | the asterisk, and `aria-required` on every thumb |
+| `aria-invalid` | `boolean \| 'true' \| 'false'` | follows `error` | on every thumb; wins over `error` |
+
+Each thumb (`role="slider"`) is named by the label; a range's thumbs add
+"Minimum" and "Maximum": `getByRole('slider', { name: 'Price Minimum' })`.
+The bare `Slider` does the same with `label-id` (the id of your label) and
+`required`, or with an `aria-labelledby` or `aria-label` you pass (they win
+over `label-id`): a vertical `Slider`, which has no field label, needs one.
+`aria-invalid` (`SliderField`'s `error`, or an `aria-invalid` you pass, which
+wins over `error` as on React's `Slider`) goes on every thumb, not on the root
+`span` nor the field's `div`.
+
+**Emits:** `update:modelValue` with the shape it was given: a `number` when
+`v-model` is a number, `number[]` when it is an array. `SliderFormField`
+stores the same — the initial value decides.
+**Form wrapper:** `SliderFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/Slider` · **React:** `Slider`, `SliderFormField`
+
+---
+
+## Switch
+
+![Switch](../previews/form-fields-switch.webp)
+
+Toggle switch, optionally in a labelled, bordered row.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Switch } from '@nxgt/material-vue/components';
+
+const notify = ref(true);
+</script>
+
+<template>
+  <Switch
+    v-model="notify"
+    label="Notifications"
+    placeholder="Email me when an order ships"
+    helper-text="You can change this at any time."
+  />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model` / `default-value` | `boolean` | — | Reka UI switch state |
+| `placeholder` | `string` | — | text inside the bordered row; with it, `label` sits above the row |
+| `label` | `string` | — | without `placeholder`, it is the row text instead |
+| `helper-text` | `string` | — | line under the row (or under the bare switch), with or without `placeholder` |
+| `error`, `required`, `disabled` | `boolean` | — | the row's state; `error` also sets `aria-invalid` on the `switch` (an `aria-invalid` you pass wins), `required` also sets `aria-required` and, with a `name` inside a `<form>`, the hidden input's `required` (an unchecked switch then blocks native submit) |
+
+The row's text is the switch's `<label>`, so a labelled switch has an
+accessible name (`getByRole('switch', { name: 'Newsletter' })`) and clicking the
+text toggles it. With a `placeholder`, the `label` above the row names the
+switch (`aria-labelledby`) and the row text describes it (`aria-describedby`):
+a screen reader says "Notifications, switch, Email me when an order ships". An
+`aria-label` or `aria-labelledby` you pass wins, and an `aria-describedby` you
+pass is kept beside the row text. The `helper-text` (the validation message,
+under `SwitchFormField`) describes the switch too. With `required`, the label's
+asterisk is hidden from screen readers, so the name stays "Terms", not
+"Terms*". Without an `id` one is generated. The row is
+tinted while the switch is on, from `v-model` or, uncontrolled, from
+`default-value` and each toggle, and carries `data-checked="true"` /
+`"false"`, as in `@nxgt/material`: select rows that are on with
+`[data-checked="true"]` (a bare `[data-checked]` also matches rows that are
+off). `data-filed`, present while on, is deprecated: it goes in 1.0.
+
+`SwitchField` (Storybook `Form fields/SwitchField`) is the same row with a
+plain `v-model: boolean` (`undefined` shows off; without `v-model` it toggles
+on its own) — the component the config
+`switch` type and `SwitchFormField` render:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { SwitchField } from '@nxgt/material-vue/components';
+
+const updates = ref(false);
+</script>
+
+<template>
+  <SwitchField v-model="updates" label="Notifications" placeholder="Email me about updates." />
+</template>
+```
+
+**Emits:** `update:modelValue` with `boolean`.
+**Form wrapper:** `SwitchFormField` — `name` inside a vee-validate form, see
+[forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
+**Storybook:** `Form fields/Switch`, `Form fields/SwitchField` · **React:** `Switch`, `SwitchFormField`
+
+---
+
+## Attributes
+
+![Attributes](../previews/form-fields-attributes.webp)
+
+Editor for typed custom attributes (string, number, date, select, rich text…).
+
+```vue
+<script setup lang="ts">
+import { AttributesField, type Attribute } from '@nxgt/material-vue/components';
+
+const attributes: Attribute[] = [
+  { name: 'color', label: 'Color', type: 'COLOR' },
+  { name: 'size', label: 'Size', type: 'SELECT', options: ['S', 'M', 'L'] },
+];
+
+function onChange(next: Attribute[]) {
+  console.log(next);
+}
+</script>
+
+<template>
+  <AttributesField label="Attributes" :attributes="attributes" :on-change="onChange" />
+</template>
+```
+
+Parts: `AttributesField` (the editable list), `AttributesList` (display with
+`on-add` / `on-edit`), `AttributeDialog` and `AttributeForm` (define one
+attribute), `AttributeValuesForm` (fill values for a set of attributes).
+Form wrappers: `AttributesFormField` (the definitions),
+`AttributeValuesFormFieldSet` and `AttributeValueFormField` (the values).
+Add and edit confirmations use a toast, so mount a `Toaster` once in the app.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `attributes` | `Attribute[]` | `[]` | the definitions; a new value (a form `resetForm()` or `setFieldValue()`) replaces the list |
+| `on-change` | `(values: Attribute[]) => void` | — | after each add, edit or delete; not called when `attributes` changes from outside |
+| `readonly` | `boolean` | — | hides add and edit |
+| `label` | `string` | — | required; the section title |
+| `helper-text` / `error` | `string` / `boolean` | — | text under the list; red when `error` (`AttributesFormField` sets both from the field's error, and shows your own `helper-text` while there is none) |
+
+A new array with the same content as the last one (a list rebuilt on each
+render) is not a change, so it does not undo the user's edits; and an edit
+never mutates the array you passed. Inside a vee-validate form, the list
+follows the form:
+
+```vue
+<script setup lang="ts">
+import { useForm } from 'vee-validate';
+import { AttributesFormField, Button, type Attribute } from '@nxgt/material-vue/components';
+
+const initial: Attribute[] = [{ name: 'color', label: 'Color', type: 'COLOR' }];
+const { resetForm } = useForm<{ attributes: Attribute[] }>({
+  initialValues: { attributes: initial },
+});
+</script>
+
+<template>
+  <AttributesFormField name="attributes" label="Attributes" helper-text="What each product can vary by." />
+  <Button variant="tonal" @click="resetForm()">Reset</Button>
+</template>
+```
+
+**Emits:** `Attribute[]` (`{ name, label, type, options?, unit?, defaultValue?, … }`)
+through `on-change`; `AttributeValuesFormFieldSet` writes an object keyed by
+attribute `name`.
+**Form wrapper:** `AttributesFormField` — `name` inside a vee-validate form, 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` · **React:** `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.
+
+```vue
+<script setup lang="ts">
+import { type Contact, Contacts, ContactType } from '@nxgt/material-vue/components';
+
+const contacts: Contact[] = [
+  { type: ContactType.Phone, value: '+33 1 23 45 67 89', label: 'Front desk' },
+  { type: ContactType.Email, value: 'contact@example.com' },
+];
+
+function onAdd() {}
+function onEdit(contact: Contact, index: number) {}
+</script>
+
+<template>
+  <Contacts label="Contacts" :data="contacts" :on-add="onAdd" :on-edit="onEdit" />
+</template>
+```
+
+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 vee-validate array, is **deprecated** and
+removed in 1.0: use `ContactsFormField`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `Contact[] \| null` | `[]` | `{ type, value, label? }`, `type` a `ContactType` |
+| `on-add` | `() => void` | — | shows the add button |
+| `on-edit` | `(contact: Contact, index: number) => void` | — | shows an edit button per row |
+| `disabled` | `boolean` | — | hides add and edit |
+
+**Emits:** `ContactsFormField` stores `Contact[]`, and shows the field's
+error message under the list.
+**Form wrapper:** `ContactsFormField` — `name` inside a vee-validate form, 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` · **React:** `Contacts`, `ContactItem`, `ContactDialog`, `ContactsFormField`
+
+---
+
+## PostalAddress
+
+![PostalAddress](../previews/form-fields-postaladdress.webp)
+
+Address card with an edit dialog.
+
+```vue
+<script setup lang="ts">
+import { PostalAddress, type PostalAddressFieldValue } from '@nxgt/material-vue/components';
+
+const address: PostalAddressFieldValue = {
+  street: '123 Rue Principale',
+  postalCode: '75001',
+  locality: 'Paris',
+  country: 'FR',
+};
+
+function onEdit() {}
+</script>
+
+<template>
+  <PostalAddress label="Address" :data="address" :on-edit="onEdit" />
+</template>
+```
+
+Parts: `PostalAddress` (the card), `PostalAddressDialog` (the edit form).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `PostalAddressFieldValue \| null` | — | `{ street?, locality?, region?, postalCode?, country? }`, `country` an ISO code |
+| `on-edit` | `() => void` | — | shows the edit button |
+| `disabled` | `boolean` | — | hides it |
+
+**Emits:** `PostalAddressFormField` stores a `PostalAddressFieldValue`
+object, and `{}` when the address is removed.
+**Form wrapper:** `PostalAddressFormField` — `name` inside a vee-validate form, 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` · **React:** `PostalAddress`, `PostalAddressDialog`, `PostalAddressFormField`
+
+---
+
+## OpeningHours
+
+![OpeningHours](../previews/form-fields-openinghours.webp)
+
+Weekly opening hours with an add / edit dialog.
+
+```vue
+<script setup lang="ts">
+import { type OpeningHour, OpeningHours } from '@nxgt/material-vue/components';
+
+const hours: OpeningHour[] = [
+  { dayOfWeek: 1, openTime: '09:00', closeTime: '18:00' },
+  { dayOfWeek: 6, isClosed: true },
+];
+
+function onAdd() {}
+function onEdit(value: OpeningHour, index: number) {}
+</script>
+
+<template>
+  <OpeningHours label="Opening hours" :data="hours" :on-add="onAdd" :on-edit="onEdit" />
+</template>
+```
+
+Parts: `OpeningHours` (the list) and `OpeningHoursDialog` (add / edit).
+`OpeningHoursItem`, a day row bound to a vee-validate array, is
+**deprecated** and removed in 1.0: use `OpeningHoursFormField`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `OpeningHour[] \| null` | `[]` | `{ dayOfWeek, openTime?, closeTime?, isClosed? }`, times as `'HH:mm'` |
+| `on-add` | `() => void` | — | shows the add button |
+| `on-add-all` | `() => void` | — | shows "Add all days" |
+| `on-edit` | `(value: OpeningHour, index: number) => void` | — | shows an edit button per day |
+
+`OpeningHoursFormField` takes `show-add-all-days` (default `false`) to offer
+the "Add all days" button.
+
+**Emits:** `OpeningHoursFormField` stores `OpeningHour[]`, and shows the
+field's error message under the list.
+**Form wrapper:** `OpeningHoursFormField` — `name` inside a vee-validate form, 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` · **React:** `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursItem`, `OpeningHoursFormField`