@nxgt/material 2.18.0 → 2.19.0

package/docs/components/selection-and-choice.md

@@ -294,8 +294,8 @@ Parts: `Autocomplete`, `AutocompleteChips` (the chips row it uses in
 | `onSearch` | `(query: string, { signal }: { signal: AbortSignal }) => Promise<T[]>` | — | server search: called once typing pauses; its results become the list. Each search aborts the previous one, and a response that lands after a newer one is dropped |
 | `onSearchError` | `(error: unknown) => void` | — | `onSearch` rejected (an abort is not a rejection) |
 | `minQueryLength` | `number` | `1` | `onSearch` waits for this many characters; below it the list says "Type at least N characters to search." |
-| `debounceMs` | `number` | `250` | the pause before `onSearch` and `onQueryChange` run |
-| `onQueryChange` | `(query: string) => void` | — | the query once typing pauses — fetch `options` yourself here |
+| `debounceMs` | `number` | `250` | the pause before `onSearch` and `onQueryChange` run on typed text; an emptied query is reported to `onQueryChange` at once, and `onSearch` never runs on it unless `minQueryLength` is `0` (then it follows the pause) |
+| `onQueryChange` | `(query: string) => void` | — | the query once typing pauses, and `''` at once when it empties (a pick, a clear) — fetch `options` yourself here |
 | `loading` | `boolean` | — | with `onQueryChange`: "Loading…" in the list, `aria-busy` on the listbox, announced |
 | `searchError` | `ReactNode` | — | shown and announced in place of the options; with `onSearch` it replaces the generic "The search failed. Try again." |
 | `empty` | `ReactNode` | "No option found." | text when nothing matches |
@@ -427,7 +427,7 @@ export function Frameworks() {
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `options` | `{ value: string; label: ReactNode }[]` | — | the boxes |
+| `options` | `{ value: string; label: ReactNode; count?: number }[]` | — | the boxes; `count`: see [option counts](#option-counts). |
 | `value` | `string[]` | `[]` | the checked values |
 | `onValueChange` | `(value: string[]) => void` | — | the new list on each toggle |
 | `orientation` | `'vertical' \| 'horizontal'` | `'horizontal'` | layout |
@@ -446,6 +446,10 @@ error with no message (`setError(name, { type: 'server' })`) keeps your
 the group's description is "<helperText> This value is not valid." and the error
 is not only a red colour.
 
+#### Option counts
+
+`count` on an option of `CheckboxGroup`, `RadioGroup` or `SelectChipField` shows a number after the label, in muted `tabular-nums` text, and joins the accessible name: the number as plain text plus a visually hidden unit word, so the option is named "CE1 24 results" (it starts with the visible label). The unit is the ICU plural `material.option-count.label` (`result` / `results`; `résultat` / `résultats` in French), so override it in your resources for another noun. `0` is a valid count.
+
 **Emits:** `string[]`.
 **Form wrapper:** `CheckboxGroupFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
@@ -482,7 +486,7 @@ full naming alignment is planned for 3.0.
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `options` | `{ value: string; label: ReactNode; disabled?: boolean }[]` | — | the radios; `disabled` on an option disables only it |
+| `options` | `{ value: string; label: ReactNode; disabled?: boolean; count?: number }[]` | — | the radios; `disabled` on an option disables only it; `count`: see [option counts](#option-counts). |
 | `value` / `defaultValue` | `string` | — | Radix radio group state |
 | `onValueChange` | `(value: string) => void` | — | |
 | `orientation` | `'vertical' \| 'horizontal'` | `'horizontal'` | layout |
@@ -610,12 +614,24 @@ export function Topics() {
 }
 ```
 
+With counts, and a single choice that stays chosen when pressed again:
+
+```tsx
+const levels = [
+	{ value: 'ce1', label: 'CE1', count: 24 },
+	{ value: 'ce2', label: 'CE2', count: 1 },
+];
+
+<SelectChipField label="Level" options={levels} value={value} onValueChange={setValue} deselectable={false} />
+```
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `mode` | `'single' \| 'multiple'` | `'single'` | clicking the selected chip in `single` mode clears it |
+| `mode` | `'single' \| 'multiple'` | `'single'` | clicking the selected chip in `single` mode clears it, unless `deselectable` is `false` |
+| `deselectable` | `boolean` | `true` | `false`: in `single` mode a second press keeps the chosen chip chosen, as a radio group does; another chip still replaces it |
 | `value` | `string[]` | `[]` | the selected values, even in `single` mode |
 | `onValueChange` | `(value: string[]) => void` | — | |
-| `options` | `{ value, label, icon? }[]` | — | the chips |
+| `options` | `{ value: string; label: string; icon?: ReactNode; count?: number }[]` | — | the chips; `count`: see [option counts](#option-counts). |
 
 **Accessibility:** the chips are toggle buttons in a `role="group"` named by
 `label` and described by the help text: a chosen chip is

package/docs/guides/forms.md

@@ -567,6 +567,41 @@ export function SupplierForm({ onSave }: { onSave: (values: Values) => void }) {
   renders one input per attribute and writes `{ [attribute.name]: value }` to
   its `name`.
 
+### Rows a user adds and removes
+
+When the rows are fields of their own — a school year'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
+wrappers:
+
+```tsx
+<RepeatableGroupFormField
+  control={form.control}
+  name="periods"
+  label="Periods"
+  rowLabel="period"
+  max={6}
+  reorderable
+  newRow={() => ({ name: '' })}
+  renderRow={({ index }) => (
+    <>
+      <TextFormField control={form.control} name={`periods.${index}.name`} label="Name" />
+      <DateFormField control={form.control} name={`periods.${index}.start`} label="Start date" />
+    </>
+  )}
+/>
+```
+
+- A row's field shows its own error (`periods.1.name`); the array's own error
+  (`.min(2)` on the array, or a `useFieldArray` rule) shows under the rows and
+  describes the group.
+- The group moves the focus as rows come and go (an added row's first field,
+  a removed row's neighbour or Add, a moved row's move button) and announces each change politely
+  ("Added period 3"). A row your own code appends takes
+  `{ shouldFocus: false }`
+  ([why](../troubleshooting.md#the-focus-jumps-away-from-a-new-row-of-a-repeatablegroupformfield)).
+
 ## Config-driven forms
 
 `FormField` renders the field that matches a config `type`, which is useful

package/docs/roadmap.md

@@ -157,6 +157,13 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Rows a user adds, removes and reorders** — `RepeatableGroup` and
+  `RepeatableGroupFormField` over the form library's field array: rows from
+  `renderRow`, a list for assistive tech, Remove and move buttons named after
+  the row ("Remove period 2"), `max` and `min`, an empty state, focus that
+  follows each change, polite announcements, and the array's own error under
+  the rows. One column on a phone. 2.19.0.
+
 - **Signed-out pages and two-step verification** — `AuthCard`, the frame of a
   sign-in page (one `main`, the card's title its `h1`, a status or alert
   notice, safe-area padding); `EnrolmentSecret`, a TOTP enrolment's QR code,

package/docs/troubleshooting.md

@@ -130,6 +130,7 @@ words in your error.
 - ["Required" shows as soon as the calendar opens, or while a date is being picked](#required-shows-as-soon-as-the-calendar-opens-or-while-a-date-is-being-picked)
 - [`TypeError: values.map is not a function` (a `SliderFormField`)](#typeerror-valuesmap-is-not-a-function)
 - [An end-to-end test no longer finds `aria-expanded` on a `ResponsiveButton`](#an-end-to-end-test-no-longer-finds-aria-expanded-on-a-responsivebutton)
+- [The focus jumps away from a new row of a `RepeatableGroupFormField`](#the-focus-jumps-away-from-a-new-row-of-a-repeatablegroupformfield)
 - [A multi-step form reopens at a later step](#a-multi-step-form-reopens-at-a-later-step)
 - [An end-to-end test no longer finds a `LinkButton` by the `button` role](#an-end-to-end-test-no-longer-finds-a-linkbutton-by-the-button-role)
 - [A test no longer finds a date or time picker by the `button` role, or a slider thumb by the exact name `Minimum`](#a-test-no-longer-finds-a-date-or-time-picker-by-the-button-role-or-a-slider-thumb-by-the-exact-name-minimum)
@@ -151,6 +152,7 @@ words in your error.
 - [A test no longer finds `aria-invalid` on a `Switch` row or an `Autocomplete`'s chips](#a-test-no-longer-finds-aria-invalid-on-a-switch-row-or-an-autocompletes-chips)
 - [An `Autocomplete` lists more options than before, or "ecole" finds "École"](#an-autocomplete-lists-more-options-than-before-or-ecole-finds-école)
 - [`onQueryChange` runs more often after upgrading](#onquerychange-runs-more-often-after-upgrading)
+- [A click on the next field right after an `Autocomplete` pick is lost](#a-click-on-the-next-field-right-after-an-autocomplete-pick-is-lost)
 - [An older search's results replace the newer ones in an `Autocomplete`](#an-older-searchs-results-replace-the-newer-ones-in-an-autocomplete)
 - [An `Autocomplete` option does nothing on click or Enter](#an-autocomplete-option-does-nothing-on-click-or-enter)
 - ["The search failed. Try again." no longer shows in an `Autocomplete`](#the-search-failed-try-again-no-longer-shows-in-an-autocomplete)
@@ -161,6 +163,7 @@ words in your error.
 - [A `className` on `ActivityLayout` now styles the whole shell](#a-classname-on-activitylayout-now-styles-the-whole-shell)
 - [A test finds a new heading or a second `main`, or no longer finds a title in a `div`](#a-test-finds-a-new-heading-or-a-second-main-or-no-longer-finds-a-title-in-a-div)
 - [`[data-test="typogaphy"]` finds nothing](#data-testtypogaphy-finds-nothing)
+- [Long text in `Typography` no longer scrolls](#long-text-in-typography-no-longer-scrolls)
 - [A test no longer finds a tooltip on an entry of an expanded sidebar](#a-test-no-longer-finds-a-tooltip-on-an-entry-of-an-expanded-sidebar)
 - [A test no longer finds a calendar day by its number, or by "Today" or "selected"](#a-test-no-longer-finds-a-calendar-day-by-its-number-or-by-today-or-selected)
 - [`#<name>` no longer finds a `SwitchFormField` or `CheckboxFormField`](#name-no-longer-finds-a-switchformfield-or-checkboxformfield)
@@ -2395,6 +2398,26 @@ On an older version, give the field an array default and keep an array:
 useForm({ defaultValues: { volume: [40] } }); // an array stays an array
 ```
 
+### The focus jumps away from a new row of a `RepeatableGroupFormField`
+
+**When:** a row is added to a `RepeatableGroupFormField` by your own code (a
+second "Add" button, a "Duplicate" action) through `useFieldArray`'s `append`,
+`prepend` or `insert` on the same `name`, and the focus lands on another field
+than the one you expected, or the page scrolls to it.
+**Why:** react-hook-form's `append` (and `prepend`, `insert`) default to
+`shouldFocus: true` and focus the new row's first registered field. The group
+moves the focus itself only after its own buttons (the new row's first field,
+a removed row's neighbour, a move button), so a second `useFieldArray` that
+focuses on its own fights with it.
+**Fix:** let the group's Add button add rows (`newRow` is what it appends).
+When your own code must add one, pass `{ shouldFocus: false }` and move the
+focus yourself if you want it moved:
+
+```tsx
+const { append } = useFieldArray({ control, name: 'periods' });
+append({ name: '' }, { shouldFocus: false });
+```
+
 ### A multi-step form reopens at a later step
 
 **When:** a wizard built on `createStepFormSlice` opens at the step (and with
@@ -2911,6 +2934,20 @@ was a fixed 1 s.
 **Fix:** set the pause you had, `debounceMs={1000}`, or move the fetch to `onSearch`, which
 also aborts the previous request and drops a stale response.
 
+### A click on the next field right after an `Autocomplete` pick is lost
+
+**When:** before 2.18.1, in a dialog, a `Select` (or any field) right below an
+`Autocomplete` whose `onQueryChange` shows or hides something (a line naming
+who is already linked, a result count): a click on that field's option just
+after a pick does nothing, now and then (more often in Firefox and on a slow
+machine; an end-to-end test flakes).
+**Why:** a pick empties the query, and `onQueryChange('')` came only after
+`debounceMs`. The line it removed then shrank the centred dialog, which moved
+the open list by half that height between the pointer's press and its release:
+the release landed on another option, and nothing was chosen.
+**Fix:** upgrade: an emptied query is reported at once, with the pick, before
+the next click. Waiting in a test until no `listbox` is left only hid it.
+
 ### An older search's results replace the newer ones in an `Autocomplete`
 
 **When:** you fetch `options` yourself from `onQueryChange`, and a slow response
@@ -3092,6 +3129,26 @@ with its own `<main>` passes `contentAs="div"`.
 **Fix:** select `[data-test="typography"]` — or better, the text or the role
 the user sees.
 
+### Long text in `Typography` no longer scrolls
+
+**When:** after upgrading, a `Typography` with a fixed height or width used to
+scroll its overflowing text; it now overflows its box (or `truncate` and
+`line-clamp-*` are the only things that clip it).
+**Why:** `Typography` always carried `overflow-auto`, which made every block
+`Typography` a scroll region: Firefox counted a subpixel overflow, and axe
+reported `scrollable-region-focusable`. It sets no `overflow` now, so it is no
+longer a block formatting context (its margins can collapse with its
+neighbours'), and a text flex or grid item no longer has the zero minimum width a scroll container has.
+**Fix:** where you want scrolling, wrap the text in an element that owns it,
+focusable and named so keyboard users can scroll it; where you want a flex
+item to shrink, give it `min-w-0`:
+
+```tsx
+<div className="max-h-40 overflow-auto" tabIndex={0} aria-label="Release notes">
+	<Typography>{longText}</Typography>
+</div>
+```
+
 ### A test no longer finds a tooltip on an entry of an expanded sidebar
 
 **When:** after upgrading, a test hovers or focuses a `SidebarMenuItem` of an

package/lib/components/base.css

@@ -55,7 +55,9 @@
 			font-size: var(--text-xs);
 			font-weight: var(--font-weight-medium);
 		}
-		a:not(:has(> button)) {
+		/* A sidebar entry is a link styled as a menu entry: the prose link style
+		   (underline, info tint on hover and focus) must not reach it (#566). */
+		a:not(:has(> button)):not([data-slot="sidebar-menu-item"]) {
 			@apply focus:underline underline-offset-4 hover:underline cursor-pointer;
 			@apply text-info [&_svg]:data-[slot=icon]:text-info hover:bg-info/10 active:bg-info/5 focus:bg-info/15;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "2.18.0",
+	"version": "2.19.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -119,7 +119,7 @@
 		"docs:previews": "vitest run --project previews"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.10.0",
+		"@nxgt/material-core": "^0.11.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",