@nxgt/material 3.34.0 → 3.35.0

package/docs/components/form-fields.md

@@ -32,10 +32,10 @@ for the value type each one writes. Everything is imported from
 | <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-attributes.webp" width="96" alt=""> | [Attributes](#attributes) | Typed custom attributes edited in place, and a read-only summary |
+| <img src="../previews/form-fields-contacts.webp" width="96" alt=""> | [Contacts](#contacts) | Typed contacts edited in place, and a read-only summary |
 | <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 |
+| <img src="../previews/form-fields-openinghours.webp" width="96" alt=""> | [OpeningHours](#openinghours) | Opening hours edited in place, and an open-now summary |
 
 ## Field
 
@@ -180,8 +180,8 @@ row.
 
 ![RepeatableGroup](../previews/form-fields-repeatablegroup.webp)
 
-Rows of fields a user adds, removes and, optionally, reorders — a school
-year's periods, a list of contacts. `RepeatableGroupFormField` wires it to
+Rows of fields a user adds, removes and, optionally, reorders — a plan's
+periods, a list of contacts. `RepeatableGroupFormField` wires it to
 react-hook-form's `useFieldArray`; each row's fields are your own form
 wrappers, rendered by `renderRow`.
 
@@ -197,7 +197,7 @@ import {
 type Period = { name: string; start?: Date; end?: Date };
 type Values = { periods: Period[] };
 
-export function SchoolYearForm({ onSave }: { onSave: (values: Values) => void }) {
+export function PlanForm({ onSave }: { onSave: (values: Values) => void }) {
   const { control, handleSubmit } = useForm<Values>({
     defaultValues: { periods: [{ name: 'Term 1' }] },
   });
@@ -1312,41 +1312,150 @@ libraries; neither name is deprecated, and both keep working.
 
 ![Attributes](../previews/form-fields-attributes.webp)
 
-Editor for typed custom attributes (string, number, date, select, rich text…).
+Typed custom attributes (string, number, boolean, date, select, rich text…),
+edited in place or shown read-only. One value model throughout: `Attribute[]`,
+`{ name, label, type, options?, unit?, defaultValue?, description?, priority? }`.
+`type` is an `AttributeType`: `STRING`, `TEXT`, `NUMBER`, `BOOLEAN`, `COLOR`,
+`DATE`, `DATETIME`, `TIME`, `SELECT`, `MULTI_SELECT` or `RICH_TEXT`. The
+`BOOLEAN` default is a `boolean`. `priority` is the place in the list, `1`
+first.
+
+Three parts, each for one job:
+
+| Part | Use it for |
+| --- | --- |
+| `AttributesField` · `AttributesFormField` | the field, and its React Hook Form wrapper. Inline by default; `editing="dialog"` keeps the list and dialog |
+| `AttributesEditor` | the same inline editor, controlled (`value`, `onValueChange`), outside a form |
+| `AttributesSummary` | the read-only display: type icons, labels and default values |
+
+`AttributesList` (the list with `onAdd` / `onEdit`), `AttributeDialog` and
+`AttributeForm` stay: they are what `editing="dialog"` renders. `AttributeValuesForm`,
+`AttributeValuesFormFieldSet` and `AttributeValueFormField` fill the values of
+a set of attributes, and now draw a `BOOLEAN` attribute as a switch.
 
 ```tsx
-import { AttributesField, type Attribute } from '@nxgt/material/components';
+import { AttributesFormField } from '@nxgt/material/components';
+
+<AttributesFormField control={control} name="attributes" label="Attributes" />
+```
+
+**The inline editor** is one row per attribute: a grip, the type's icon, the
+label with `name · Type` under it, the unit as a badge and the default value
+(a Yes or No, a colour swatch, a number with its unit). A row opens to its
+fields: label, name, type, unit (for a number), options (for a select), the
+default value edited the way its type is, and a description; Delete removes
+it and Done closes it. Nothing is toasted: an edit is in the value at once.
+Changing the type resets the default value, and the options unless both types
+take options. "Add attribute" appends a row, opens it and focuses its label.
+
+Outside a form, control it yourself; `editing="dialog"` is the way back to
+the earlier list and dialog:
+
+```tsx
+import { useState } from 'react';
+import { AttributesEditor, AttributesFormField, type Attribute } from '@nxgt/material/components';
+
+const [attributes, setAttributes] = useState<Attribute[]>([]);
+<AttributesEditor label="Attributes" value={attributes} onValueChange={setAttributes} />
+
+<AttributesFormField control={control} name="attributes" label="Attributes" editing="dialog" />
+```
+
+*Reorder.* Drag the grip, or focus it and press Space (or Enter) to lift the
+row, the arrow keys to move it, Space (or Enter) to drop it and Escape to put
+it back. Each step is said in a live region ("Active moved to position 2 of
+6"). A drop rewrites the list in its new order and sets every `priority` to
+its place (`1`, `2`, `3`…); the editor shows the attributes by `priority`
+(lowest first, none after the others), so a list without priorities keeps its
+order until the first move.
+
+*Names.* A name must be unique and not empty (spaces around it are ignored;
+there is no minimum length any more). A name another attribute has is a
+`role="alert"` under the field at once ("Another attribute already has this
+name."); an empty one once the field was left. The header counts the problems
+("2 issues to fix"), and a row with a bad name shows a warning mark.
 
-const attributes: Attribute[] = [
-	{ name: 'color', label: 'Color', type: 'COLOR' },
-	{ name: 'size', label: 'Size', type: 'SELECT', options: ['S', 'M', 'L'] },
-];
+*Phone.* Below 640px each attribute is a row with its icon, title and a
+chevron; tapping it opens a bottom sheet with the same fields (and Delete and
+Done). The grip stays, so a row can be moved on a phone too.
 
-<AttributesField label="Attributes" attributes={attributes} onChange={(next) => console.log(next)} />
+**The summary** takes the same `data`:
+
+```tsx
+import { AttributesSummary } from '@nxgt/material/components';
+
+<AttributesSummary data={attributes} label="Item" />
 ```
 
-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).
-`AttributeForm` builds its zod schema when it first renders, not when the
-module loads ([CSP](../guides/csp.md#zod-and-unsafe-eval)).
+It is a description list in `priority` order (list order without one), each
+attribute with its type icon, its label and its default value, a dash when it
+has none. It is a new component, not a read-only mode of `AttributesList`, so
+the list keeps its callbacks. With nothing to list it shows a quiet "No attributes"
+(`empty` replaces the text, `empty={null}` renders nothing). A `DATETIME` or
+`TIME` default stored as an instant is written in UTC on the server and in the
+first client render, and in the viewer's time zone and locale once the page
+has mounted, so hydration matches; a bare `yyyy-MM-dd` or `HH:mm` reads the
+same everywhere.
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
+| `data` | `Attribute[] \| null` | `[]` | the attributes |
+| `label` | `string` | "Attributes" | names the region |
+| `empty` | `ReactNode` | "No attributes" | shown when there is nothing to list; `null` renders nothing |
+
+| Prop (field) | 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 |
+| `onChange` | `(values: Attribute[]) => void` | — | after each edit |
+| `editing` | `'inline' \| 'dialog'` | `'inline'` | in place, or the list and dialog |
+| `readonly` | `boolean` | — | the list without add and edit (also with `editing="inline"`) |
+| `disabled` | `boolean` | — | disables the controls |
 | `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) |
+| `helperText` / `error` | `ReactNode` / `boolean` | — | text under the field; red when `error` (`AttributesFormField` sets both from the field's error, and shows your own `helperText` while there is none) |
+
+| `AttributesEditor` prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `value` | `Attribute[]` | `[]` | the attributes |
+| `onValueChange` | `(value: Attribute[]) => void` | — | after each edit |
+| `label` | `ReactNode` | "Attributes" | the heading |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | the heading's level |
+| `disabled` | `boolean` | — | disables the controls |
+| `className` | `string` | — | on the section |
+
+`AttributesSummary` also takes `className`. `AttributesFormField` takes
+`control` and `name` in place of `attributes` and `onChange`, an optional
+`value` that overrides the form's, and the props above; its `disabled` also
+follows `useForm({ disabled })`.
+
+`AttributeDialog` and `AttributeForm` take `otherNames`: saving a
+name in it is an inline error on the name. `AttributeForm` builds its zod
+schema when it first renders, not when the module loads
+([CSP](../guides/csp.md#zod-and-unsafe-eval)); its `name` is only required to
+be non-empty (it was at least four characters).
+
+`attributesListSchema()` is the zod schema of a whole list, with the editor's
+own rules (the same functions): a name that is set and that no other attribute
+has (`[1, 'name']`), and a default value that fits the type, a listed option, a
+boolean, a number or a date (`[1, 'defaultValue']`). Built on the first call
+([CSP](../guides/csp.md#zod-and-unsafe-eval)). Each issue's `message` is an
+English default, and its `params.code` (`'empty'`, `'duplicate'`, `'option'`,
+`'boolean'`, `'number'`, `'date'`; typed as `AttributeIssueCode`) lets a form show its own translated text.
 
-**Emits:** `Attribute[]` (`{ name, label, type, options?, unit?, defaultValue?, … }`);
-`AttributeValuesFormFieldSet` writes an object keyed by attribute `name`.
+```ts
+import { attributesListSchema } from '@nxgt/material/components';
+import { z } from 'zod';
+
+const schema = z.object({ attributes: attributesListSchema() });
+```
+
+**Emits:** `Attribute[]`; the inline editor writes a date as `yyyy-MM-dd`, a
+date-time as an ISO instant and a time as `HH:mm`. `AttributeValuesFormFieldSet`
+writes an object keyed by attribute `name`; `AttributeValuesForm` reads a bare
+`yyyy-MM-dd` default as that local day.
 **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`
+**Storybook:** `Form fields/Attributes`, `Form fields/Attributes/Editor`, `Form fields/Attributes/Editor reorder`, `Form fields/Attributes/Editor on a phone`, `Form fields/Attributes/Summary` · **Vue:** `AttributesField`, `AttributesList`, `AttributeDialog`, `AttributeForm`, `AttributeValuesForm`, `AttributesFormField`, `AttributeValuesFormFieldSet`, `AttributeValueFormField`
 
 ---
 
@@ -1354,35 +1463,105 @@ and [composite values](../guides/forms.md#composite-values).
 
 ![Contacts](../previews/form-fields-contacts.webp)
 
-Typed contact list (phone, email, URL…) with an add / edit dialog.
+Typed contacts (phone, mobile, fax, email, website), edited in place or shown
+read-only. One value model throughout: `Contact[]`, `{ type, value, label?,
+primary? }` with `type` a `ContactType`. `primary` is optional and additive:
+**one per type**, the contact to use first among those of its type. A value
+that marks several of a type is read as marking the first only.
+
+Three parts, each for one job:
+
+| Part | Use it for |
+| --- | --- |
+| `ContactsFormField` | the React Hook Form field. Inline by default; `editing="dialog"` keeps the list and dialog |
+| `ContactsEditor` | the same inline editor, controlled (`value`, `onValueChange`), outside a form |
+| `ContactsSummary` | the read-only display: icons, values as links, copy, the primary one marked |
+
+`Contacts` (the list with `onAdd` / `onEdit`) and `ContactDialog` stay as they
+were: they are what `editing="dialog"` renders.
 
 ```tsx
-import { type Contact, Contacts, ContactType } from '@nxgt/material/components';
+import { ContactsFormField } 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' },
-];
+<ContactsFormField control={control} name="contacts" label="Contacts" />
+```
+
+**The inline editor** groups the contacts by type (phone, mobile, email,
+website, fax), the primary one first in its group. A row is the type icon, a
+type select, the value, an optional label and its actions: call (`tel:`),
+write (`mailto:`) or open the site (links, shown only when the value is
+well-formed), copy (announces "Copied"), a star that makes it the primary
+contact of its type, and remove. "Add Contact" chips add an empty contact of a
+type and focus its value. A wrong format (an email without a domain, a number
+that is not 7 to 15 digits, a website that is not `http(s)`) or a duplicate
+(the same type and value, ignoring case and number formatting) is a
+`role="alert"` under its value. A duplicate shows and counts at once; a wrong
+format shows and counts once its field was left. The header counts them
+("2 issues to fix").
+The editor checks the shape of a value, not that the line exists. Below 640px
+each contact is a summary row; tapping it opens a bottom sheet with the same
+fields and actions, and closing it with an empty value drops the contact.
+
+`variant="cards"` is the Expressive variant: each contact is its own tinted
+card with a round tile for the primary one. The fields keep the library's
+field radius in both. `variant` is on `ContactsFormField`, `ContactsEditor`
+and `ContactsSummary`; it is the only prop that picks the look, so the two
+are one component, not two.
+
+```tsx
+<ContactsFormField control={control} name="contacts" variant="cards" />
+```
+
+**The summary** takes the same `data`:
+
+```tsx
+import { ContactsSummary } from '@nxgt/material/components';
 
-<Contacts label="Contacts" data={contacts} onAdd={() => {}} onEdit={() => {}} />
+<ContactsSummary data={contacts} label="Acme headquarters" />
 ```
 
-Parts: `Contacts` (the list) and `ContactDialog` (add / edit). `Contacts` only
-displays and calls back; `ContactsFormField` owns the dialog and the array.
+It is a new component, not a read-only mode of `Contacts`, so the list keeps
+its callbacks and nothing changes for code that uses it. With nothing to list
+it shows a quiet "No contacts" (`empty` replaces the text, `empty={null}`
+renders nothing); it skips contacts without a value. A fax number offers copy
+only, and a value that fails its check is shown without a link.
 
 | 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 |
+| `data` | `Contact[] \| null` | `[]` | the contacts |
+| `label` | `string` | "Contacts" | names the region |
+| `variant` | `'list' \| 'cards'` | `'list'` | a bordered list, or tinted cards |
+| `empty` | `ReactNode` | "No contacts" | shown when there is nothing to list; `null` renders nothing |
+
+`ContactsEditor` takes `value`, `onValueChange`, `label`, `headingLevel` (`3`
+by default; the type headings sit one below it), `variant` and `disabled`. A
+wrong format is said once the field was left, a duplicate at once. `ContactsFormField` takes `editing` (`'inline' \| 'dialog'`,
+default `'inline'`) and `variant` (inline only). `Contacts` takes `data`,
+`onAdd`, `onEdit` and `disabled`.
+
+`contactsListSchema()` is the zod schema of a whole list, with the editor's
+own rules (the same functions): the value's format by type (an email, an
+`http(s)` address, 7 to 15 digits for a phone, mobile or fax) and no value
+repeated within a type, each issue on the entry's `value` (`[1, 'value']`). A
+blank value is not an issue, as in the editor. Each issue's `message` is an
+English default, and its `params.code` (`'email'`, `'phone'`, `'website'`,
+`'duplicate'`; typed as `ContactIssueCode`) lets a form show its own translated text.
 
-**Emits:** `ContactsFormField` stores `Contact[]`, and shows the array's
-error (`errors.<name>.message` or `.root.message`) under the list.
+```ts
+import { contactsListSchema } from '@nxgt/material/components';
+import { z } from 'zod';
+
+const schema = z.object({ contacts: contactsListSchema() });
+```
+
+**Emits:** `ContactsFormField` stores `Contact[]` (the inline editor writes
+`primary: true` on one contact per type and leaves the flag off elsewhere), and
+shows the array's error (`errors.<name>.message` or `.root.message`) under the
+editor.
 **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`, `ContactDialog`, `ContactsFormField`
+**Storybook:** `Form fields/Contacts`, `Form fields/Contacts/Editor`, `Form fields/Contacts/Summary` · **Vue:** `Contacts`, `ContactDialog`, `ContactsFormField`
 
 ---
 
@@ -1426,45 +1605,97 @@ and [composite values](../guides/forms.md#composite-values).
 
 ![OpeningHours](../previews/form-fields-openinghours.webp)
 
-Weekly opening hours with an add / edit dialog.
+A week of opening hours, edited in place or shown read-only. One value
+model throughout: `OpeningHour[]`, **one entry per range** (`{ dayOfWeek,
+openTime?, closeTime?, isClosed? }`, `dayOfWeek` `0` Sunday, times as
+`'HH:mm'`), so a day with a lunch break is two entries.
+
+Three parts, each for one job:
+
+| Part | Use it for |
+| --- | --- |
+| `OpeningHoursFormField` | the React Hook Form field. Inline by default; `editing="dialog"` keeps the list and dialog |
+| `OpeningHoursEditor` | the same inline editor, controlled (`value`, `onValueChange`), outside a form |
+| `OpeningHoursSummary` | the read-only display: open now, and the grouped week |
+
+`OpeningHours` (the list with `onAdd` / `onEdit`) and `OpeningHoursDialog`
+stay as they were: they are what `editing="dialog"` renders.
 
 ```tsx
-import { type OpeningHour, OpeningHours } from '@nxgt/material/components';
+import { OpeningHoursFormField } from '@nxgt/material/components';
+
+<OpeningHoursFormField control={control} name="hours" label="Opening hours" />
+```
+
+**The inline editor** shows the seven days. Each has an open / closed switch
+and one or more ranges (add and remove), and a "Copy to" menu: Monday to
+Friday, the weekend, or all days, with a "Copied to Sat, Sun" note. A range
+that is wrong says so under itself (`role="alert"`): the close is not after the
+open, it overlaps another range of the day, or a time is missing; the header
+counts them ("2 issues to fix"). Times are `TimeStringField`s at `size="sm"`.
+`weekStartsOn` (`0` Sunday to `6`) defaults to the locale's first day: pass `1`
+for a Monday start under `en`. Below 640px each day is a summary row with a
+chevron; tapping it opens a bottom sheet with the same controls and day chips
+to copy to.
 
-const hours: OpeningHour[] = [
-	{ dayOfWeek: 1, openTime: '09:00', closeTime: '18:00' },
-	{ dayOfWeek: 6, isClosed: true },
-];
+**The summary** takes the same `data`:
 
-<OpeningHours label="Opening hours" data={hours} onAdd={() => {}} onEdit={() => {}} />
+```tsx
+import { OpeningHoursSummary } from '@nxgt/material/components';
+
+<OpeningHoursSummary data={hours} timeZone="America/Toronto" label="Opening hours" />
 ```
 
-Parts: `OpeningHours` (the list) and `OpeningHoursDialog` (add / edit).
+It prints a status pill, "Open · closes at 6:00 PM" or "Closed · opens Monday
+at 9:00 AM", then the week with identical consecutive days grouped ("Mon–Fri
+9:00 AM – 6:00 PM"), today's group tagged "Today" with the selected-row look.
+It is a new component, not a mode of `OpeningHours`, so the list keeps its
+callbacks and nothing changes for code that uses it. Without `now` the status
+and the "Today" mark appear once the page has mounted (a server render and its
+hydration then match); pass `now` to render them on the server or in a test.
+The week starts on the language's first day until the page has mounted, then
+on the locale's own (`weekStartsOn` sets it for both). With no hours, the
+summary shows a quiet "Hours not set" (`empty` replaces the text,
+`empty={null}` renders nothing).
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `data` | `OpeningHour[] \| null` | `[]` | the hours |
+| `now` | `Date` | the clock | the moment read as now |
+| `timeZone` | `string` | the viewer's | the IANA zone of the place, resolved with `Intl.DateTimeFormat` |
+| `locale` | `string` | the `I18nProvider` language, else `en` | day and time names |
+| `weekStartsOn` | `0`-`6` | the locale's | first day of the week |
+| `label` | `string` | "Opening Hours" | names the region |
+| `empty` | `ReactNode` | "Hours not set" | shown when no day is open; `null` renders nothing |
+
+`OpeningHoursEditor` takes `value`, `onValueChange`, `label`, `headingLevel` (`3` by default), `weekStartsOn`,
+`locale` and `disabled`. `OpeningHoursFormField` takes `editing`
+(`'inline' \| 'dialog'`, default `'inline'`), `weekStartsOn` and `locale`
+(inline), and `showAddAllDays` (dialog, default `false`).
+
 `openingHoursSchema()` returns the zod schema of one `OpeningHour`
-(`dayOfWeek` coerced from a string), built on the first call. Under a
-strict CSP, call `z.config({ jitless: true })` first: see
+(`dayOfWeek` coerced from a string), built on the first call. It is unchanged.
+`openingHoursListSchema()` is the schema of the whole week: the entries, plus
+the cross-field rules of the editor (close after open, both times set, no
+overlap on a day), each issue on its entry and field (`[2, 'closeTime']`). A
+blank time (`''`) is accepted by the entry schema and reported once, as
+`missing`. Each issue's `message` is an English default, and its `params.code`
+(`'close'`, `'overlap'`, `'missing'`) lets a form show the translated
+`material.opening-hours.errors.*` text the editor uses.
+Under a strict CSP, call `z.config({ jitless: true })` first: see
 [CSP](../guides/csp.md#zod-and-unsafe-eval).
 
 ```ts
-import { openingHoursSchema } from '@nxgt/material/components';
+import { openingHoursListSchema } from '@nxgt/material/components';
 import { z } from 'zod';
 
-const schema = z.object({ hours: z.array(openingHoursSchema()) });
+const schema = z.object({ hours: openingHoursListSchema() });
 ```
 
-| 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.
+**Emits:** `OpeningHoursFormField` stores `OpeningHour[]`: the inline editor
+writes a closed day as one `{ dayOfWeek, isClosed: true }` entry, and shows the
+array's error (`errors.<name>.message` or `.root.message`) under the editor.
 **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`, `OpeningHoursFormField`
+**Storybook:** `Form fields/OpeningHours`, `Form fields/OpeningHours/Editor`, `Form fields/OpeningHours/Summary` · **Vue:** `OpeningHours`, `OpeningHoursDialog`, `OpeningHoursFormField`

package/docs/guides/forms.md

@@ -115,9 +115,9 @@ export function PlanForm() {
 | The field | Touched when |
 | --- | --- |
 | one input (`TextFormField`, `EmailFormField`, `TextareaFormField`, `SwitchFormField`, `CheckboxFormField`, …) | its input loses focus, as a native `blur` |
-| several controls (`PasswordFormField` and its eye button, `NumberFormField` and its steppers, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
+| several controls (`OpeningHoursFormField`, inline by default: focus leaves the week editor and its phone sheet; `ContactsFormField`, inline by default: focus leaves the rows and the phone sheet; `AttributesFormField`, inline by default: focus leaves the rows, their open fields and the phone sheet; `PasswordFormField` and its eye button, `NumberFormField` and its steppers, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
 | a picker (`SelectFormField`, `ComboboxFormField`, `AutocompleteFormField`, `TreeSelectFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is. A typed `DateFormField`, `DateRangeFormField` or `TimeFormField` is one trigger: moving between its segments (both ends of a range) and its buttons is not leaving |
-| a dialog editor (`PostalAddressFormField`, `ContactsFormField`, `OpeningHoursFormField`, `AttributesFormField`, and `LocationFormField` from `@nxgt/material/map`) | focus leaves its buttons and the dialog they open. Closing the dialog hands focus back to the button that opened it |
+| a dialog editor (`PostalAddressFormField`, `ContactsFormField` with `editing="dialog"`, `OpeningHoursFormField` with `editing="dialog"`, `AttributesFormField` with `editing="dialog"`, and `LocationFormField` from `@nxgt/material/map`) | focus leaves its buttons and the dialog they open. Closing the dialog hands focus back to the button that opened it |
 | an upload (`UploadFormField`, `NetworkUploadFormField`, `S3UploadFormField`, `ImageFormField`, `ImageS3FormField`, `FileListFormField`, `FileListS3FormField`) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
 | `RichTextEditorFormField`, `CodeEditorFormField` | focus leaves the editor and its toolbar |
 | `FormField` (config-driven) | the rule of the field its `type` renders |
@@ -308,16 +308,16 @@ shows them right under its fields.
   `p-4` are recognised) sets `--form-actions-fill` to it:
 
   ```css
-  .edit-school-form {
+  .edit-record-form {
     --form-actions-clearance: 9rem;
   }
-  .edit-school-dialog {
+  .edit-record-dialog {
     --form-actions-fill: 2rem; /* its pb-8 */
   }
   ```
 
   ```tsx
-  <form className="form-grid-layout edit-school-form">
+  <form className="form-grid-layout edit-record-form">
   ```
 - To scroll a form in a box of your own, give it a height and the scroll
   (`className="form-grid-layout max-h-[60vh] overflow-y-auto"`); to keep the
@@ -500,7 +500,7 @@ or fails validation.
 | `Slider` · `SliderFormField` | `number` when the default is a number; `number[]` when the default is an array (a range) | `0` / `[20, 80]` |
 | `Switch` · `SwitchFormField` | `boolean` | `false` |
 | `AttributesField` · `AttributesFormField` | `Attribute[]` | `[]` |
-| `ContactsFormField` | `Contact[]`: `{ type: ContactType; value: string; label?: string \| null }` | `[]` |
+| `ContactsFormField` | `Contact[]`: `{ type: ContactType; value: string; label?: string \| null; primary?: boolean \| null }` | `[]` |
 | `PostalAddressFormField` | `PostalAddressFieldValue`: `{ street?, locality?, region?, postalCode?, country? }`; `{}` after delete | `{}` |
 | `OpeningHoursFormField` | `OpeningHour[]`: `{ dayOfWeek: 0–6; openTime?: 'HH:mm'; closeTime?: 'HH:mm'; isClosed?: boolean }` | `[]` |
 
@@ -607,16 +607,22 @@ export function SupplierForm({ onSave }: { onSave: (values: Values) => void }) {
 
 | Wrapper | Value | Notes |
 | --- | --- | --- |
-| `ContactsFormField` | `Contact[]` | Add, edit and delete go through `ContactDialog`. `ContactType` is `EMAIL`, `FAX`, `MOBILE`, `PHONE`, `WEBSITE` |
-| `OpeningHoursFormField` | `OpeningHour[]` | `showAddAllDays` adds Monday–Friday 09:00–17:00 and a closed weekend in one click |
+| `ContactsFormField` | `Contact[]` | Edited in place by default (one `primary` per type); `editing="dialog"` goes through `ContactDialog`. `ContactType` is `EMAIL`, `FAX`, `MOBILE`, `PHONE`, `WEBSITE` |
+| `OpeningHoursFormField` | `OpeningHour[]` | Edits the week inline by default (`weekStartsOn` and `locale` apply there); `editing="dialog"` keeps the list and dialog, where `showAddAllDays` adds Monday–Friday 09:00–17:00 and a closed weekend in one click |
 | `PostalAddressFormField` | `PostalAddressFieldValue` | Deleting the address writes `{}`, not `null` |
-| `AttributesFormField` | `Attribute[]` | A typed attribute editor. Its `label` prop is required |
-
+| `AttributesFormField` | `Attribute[]` | A typed attribute editor, in place by default (rows that open, drag and keyboard reorder that sets `priority`, unique names); `editing="dialog"` keeps the list and dialog. Its `label` prop is required |
+
+- **The list schemas carry the editors' rules.** `contactsListSchema()`,
+  `attributesListSchema()` and `openingHoursListSchema()` are zod schemas of
+  the whole array (see [Contacts](../components/form-fields.md#contacts),
+  [Attributes](../components/form-fields.md#attributes) and
+  [OpeningHours](../components/form-fields.md#openinghours)). Each issue has an
+  English `message` and a `params.code` to translate from.
 - **The array's own error is shown under the field.** `ContactsFormField`,
   `OpeningHoursFormField` and `AttributesFormField` display
   `errors.<name>.message` (where a Zod `.min(1)` on the array lands) and
   `errors.<name>.root` (where a `useFieldArray` rule lands). Errors of one
-  item are shown in its dialog.
+  item are shown in its dialog, or under its range or name in the inline editor.
 - `AttributesFormField` follows the form value: `form.reset()` and
   `form.setValue()` replace the list it shows.
 - `AttributeValuesFormFieldSet` is the other half: given `attributes`, it
@@ -625,7 +631,7 @@ export function SupplierForm({ onSave }: { onSave: (values: Values) => void }) {
 
 ### Rows a user adds and removes
 
-When the rows are fields of their own — a school year's periods, each with a
+When the rows are fields of their own — a plan's periods, each with a
 name, a start date and an end date — use
 [`RepeatableGroupFormField`](../components/form-fields.md#repeatablegroup)
 over `useFieldArray`, and render each row's fields with the form's own

package/docs/guides/i18n.md

@@ -255,7 +255,7 @@ their chevron, "Show the options" / "Afficher les options"
 (`material.combobox.toggle`),
 the `ThemePicker`'s group and mode names (`material.theme-picker.label` "Theme" / "Thème", `material.theme-picker.mode` "Mode"; the Light, Dark and System names are `ThemeToggle`'s own), the `LocationPreview` trigger
 (`material.map.preview` / `preview-named`), and the delete buttons of the
-`Contacts` / `OpeningHours` rows. `FacetGroup`'s toggle is named "Level, 2 selected" / "Level, 2 sélectionnés" (`material.facet-group.name`, over `{title}` and `{count}`: plain in English, an ICU plural in French) and its Clear button "Clear Level" / "Effacer Level" (`material.facet-group.clear-label`, with the visible `material.facet-group.clear`). `AccountMenu`'s avatar button is named "Account menu, {name}" / "Menu du compte, {name}" (`material.account-menu.trigger`, over `{name}`) and its last item reads "Sign out" / "Se déconnecter" (`material.account-menu.sign-out`), unless you pass `signOutLabel`; with `themeChoice` its "Theme" group reads "Theme" / "Thème", "Light" / "Clair", "Dark" / "Sombre", "System" / "Système" (`material.account-menu.theme.label`, `light`, `dark`, `system`). `LocalizedTextFields`' reset button is named "Reset {language} to the default" / "Rétablir la valeur par défaut ({language})" (`material.localized-text-fields.reset`), its tooltip reads "Default: {value}" (`reset-tooltip`) and its polite status "{language}: back to the default" (`reset-done`). Its "Other languages" trigger reads "Other languages ({count})" / "Autres langues ({count})" (`others-count`; `others` names the folded rows' group), and while closed over errors it is described by "{count} errors" / "{count} erreurs" (`others-errors`, an ICU plural over `{count}`). The language names come from `material.language.<code>` (English and French ship), then `Intl.DisplayNames`. `PrintDocument`'s page numbers
+`Contacts` / `OpeningHours` rows, and the empty text of `ContactsSummary` and `AttributesSummary` (`material.contacts.labels.none` "No contacts" / "Aucun contact", `material.attributes.labels.none` "No attributes" / "Aucun attribut"; `@nxgt/material-vue` carries the same keys). `FacetGroup`'s toggle is named "Level, 2 selected" / "Level, 2 sélectionnés" (`material.facet-group.name`, over `{title}` and `{count}`: plain in English, an ICU plural in French) and its Clear button "Clear Level" / "Effacer Level" (`material.facet-group.clear-label`, with the visible `material.facet-group.clear`). `AccountMenu`'s avatar button is named "Account menu, {name}" / "Menu du compte, {name}" (`material.account-menu.trigger`, over `{name}`) and its last item reads "Sign out" / "Se déconnecter" (`material.account-menu.sign-out`), unless you pass `signOutLabel`; with `themeChoice` its "Theme" group reads "Theme" / "Thème", "Light" / "Clair", "Dark" / "Sombre", "System" / "Système" (`material.account-menu.theme.label`, `light`, `dark`, `system`). `LocalizedTextFields`' reset button is named "Reset {language} to the default" / "Rétablir la valeur par défaut ({language})" (`material.localized-text-fields.reset`), its tooltip reads "Default: {value}" (`reset-tooltip`) and its polite status "{language}: back to the default" (`reset-done`). Its "Other languages" trigger reads "Other languages ({count})" / "Autres langues ({count})" (`others-count`; `others` names the folded rows' group), and while closed over errors it is described by "{count} errors" / "{count} erreurs" (`others-errors`, an ICU plural over `{count}`). The language names come from `material.language.<code>` (English and French ship), then `Intl.DisplayNames`. `PrintDocument`'s page numbers
 read `material.print.page-of` ("Page {page} of {pages}", "Page {page} sur
 {pages}") and `material.print.page` ("Page {page}"), and a `PrintDataTable`
 reads `material.print.table.total` ("Total", "Total") for its totals row and

package/docs/guides/ssr.md

@@ -168,6 +168,7 @@ State the server cannot know must be resolved the same way on both sides:
 | Theme | no preference: light | An inline boot script in `<head>`, and `suppressHydrationWarning` on `<html>`. See [theming](theming.md#no-flash-on-load-a-boot-script) |
 | `formatAmount`, `formatDate` | the server's locale and time zone, unless you pass them | Use `useFormatters({ timeZone })`, which follows the `I18nProvider` language, or pass `locale` and `timeZone` (`createFormatters` binds them). A date-only `YYYY-MM-DD` is the same everywhere. See [printing](printing.md#formatamount-and-formatdate) |
 | Screen width, `prefers-color-scheme` (`useIsMobile`, `useTheme`, `AppHeader`, `DataTable`, `TimeField`, `Stepper`, `PaneLayout`, `ListDetailsLayout`, the code blocks, …) | no screen: a desktop, light | Nothing: a hydrating client renders the same, then switches on a phone or a dark screen |
+| An attribute's `DATETIME` / `TIME` instant (`AttributesSummary`, `AttributesEditor`), the opening hours' first day of the week | the server's time zone and Intl data differ from the browser's | Nothing: the instant is written in UTC and the week starts on the language's first day until mount, then the viewer's zone and the locale's week info take over, so hydration matches |
 | Step form (`createStepFormSlice`) | no `localStorage`: step 0 | Nothing with `useSliceReducer`: a hydrating client renders step 0, then resumes. A slice in a Redux store: see [forms](forms.md#a-multi-step-form) |
 | Zod messages | no `localStorage`: English | Pass the request's language, `zodLocaleError({ language })`, where the server formats messages. See [forms](forms.md#validation-messages) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.34.0",
+	"version": "3.35.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"