@nxgt/material 3.19.0 → 3.21.0

package/docs/components/data-display.md

@@ -399,7 +399,7 @@ import { Avatar, Chip } from '@nxgt/material/components';
 | `aria-pressed` | `boolean` | — | a toggle chip: selected while pressed, with a check when nothing leads |
 | `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | 28px, 24px, or `lg`, a 44px box at every pointer (the touch target); every target stays at least 24px |
 | `color` | `'default' \| 'primary' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'error'` | neutral | tone: the edge (outlined), the fill and label (tonal, `filled`: a status look) or the dot and tint (tag). A `tag` without `color` (or with `default`) draws no dot |
-| `onDismiss` | `() => void` | — | adds the ✕ button, named "Remove {label}" (`material.chip.dismiss-label`), `{label}` being the text `label` shows, a node's included; "Remove" when it shows none; the ✕ is drawn 18px (16px small) with a 24px target |
+| `onDismiss` | `() => void` | — | adds the ✕ button, named "Remove {label}" (`material.chip.dismiss-label`), `{label}` being the text `label` shows, a node's included; "Remove" when it shows none; the ✕ is drawn 18px (16px small) in its own 24x24 box (44x44 on a coarse pointer) |
 | `dismissLabel` | `string \| ((label: string) => string)` | — | names the ✕ instead of "Remove {label}": a string as is, or a function of the text the chip shows |
 | `onClick` | `MouseEventHandler` | — | makes the chip (or its body, when dismissible) a button; without it the chip is a `<span>` |
 | `leading`, `avatar`, `trailing` | `ReactNode` | — | slots; `avatar` is shrunk to fit, `trailing` (a count) is never truncated |
@@ -633,7 +633,7 @@ the grid it is in; pass `className="col-start-full"` for a full-width row.
 
 ![EntityHeader](../previews/data-display-entityheader.webp)
 
-Page header with icon, title, status, metadata and actions.
+Page header with icon (or a `leading` control), title, status, metadata and actions.
 
 ```tsx
 import { Edit } from 'lucide-react';
@@ -651,13 +651,27 @@ import { Badge, EntityHeader } from '@nxgt/material/components';
 | --- | --- | --- | --- |
 | `title` | `ReactNode` | — | the heading (an `h1` unless `headingLevel` says otherwise); optional: without it no heading is rendered (see below) |
 | `headingLevel` | `1 \| 2 \| 3` | `1` | the title's heading level: pass `2` or `3` when the page already has its `h1` (a list title beside a detail header); the look does not change |
-| `icon`, `status` | `ReactNode` | — | before and after the title; `icon` is decoration, shown in an `aria-hidden` badge, so put nothing meaningful or focusable there |
+| `icon`, `status` | `ReactNode` | — | before and after the title; `icon` is decoration, shown in an `aria-hidden` badge, so put nothing meaningful or focusable there; for a control, use `leading` |
+| `leading` | `ReactNode` | — | an interactive control at the band's start, such as a [Switcher](selection-and-choice.md#switcher) of either variant: drawn as it is, at its natural size (at most 18rem wide beside the title, from a 384px band; narrower, it takes the band's width), in the accessibility tree, with no badge and no `aria-hidden`; on a phone it takes the band's width above the title. **It replaces `icon` when both are given** (a development warning says so). Root `data-slot="entity-header-leading"` |
 | `metadata` | `{ label: string; value: ReactNode }[]` | `[]` | facts under the title, a description list: a muted label beside its value, no colon; a link in a value is drawn in the primary text colour (`text-primary-text`), not the prose link's info blue, and `nxgt-plain-link` still opts out |
 | `stats` | `EntityStat[]` | `[]` | figures (counts, a mean) as compact `size="sm"` [StatCard](#statcard) tiles in a `StatCardGroup` (2×2 on a phone, a wrapping row beside) under the metadata; a `tone` paints a tile, `0` is a figure, an empty value drops the tile (see Stats below) |
 | `actions` | `ResponsiveButtonProps[] \| ReactNode` | `[]` | an array becomes responsive buttons (icon-only on phones) |
 
 The root carries `data-slot="entity-header"`; the metadata is a `dl` with `data-slot="entity-metadata"` (a muted `dt` label beside its `dd` value, no colon), and the actions sit in `data-slot="entity-header-actions"` (absent when there are none). Inside an EntityHeader that replaces the old `summary-data` slot and its `Label:` text, so update a selector or a test that read "Label: value".
 
+**A control at the start.** `leading` takes a control, never `icon`: the icon badge is `aria-hidden`, which squashes a `Switcher` and makes axe report `aria-hidden-focus` (see [Troubleshooting](../troubleshooting.md#a-control-in-an-entityheaders-icon-is-hidden-from-assistive-tech-squashed-and-reports-aria-hidden-focus)).
+
+```tsx
+import { Badge, EntityHeader, Switcher } from '@nxgt/material/components';
+
+<EntityHeader
+  leading={<Switcher variant="expressive" label="Group" value={group} onValueChange={setGroup} options={groups} />}
+  title="Attendance"
+  status={<Badge variant="success">Active</Badge>}
+  metadata={[{ label: 'Year', value: '2026-2027' }]}
+/>
+```
+
 **Stats.** Figures (counts, a mean) go in `stats`, shown as compact [StatCard](#statcard) tiles (`size="sm"`) in a `StatCardGroup` (2×2 on a phone, a row that wraps beside) under the metadata; facts (dates, names) stay in `metadata`. A `tone` paints a tile (tonal), none leaves it outlined; `0` is a figure, an empty value drops the tile. The row is `data-slot="entity-stats"`, and the type `EntityStat` is exported.
 
 ```tsx

package/docs/components/date-and-time.md

@@ -186,10 +186,14 @@ export function Delivery() {
 The calendar opens on the month of `value`; with no value, `defaultMonth` sets
 it.
 
+**Migration:** a typed date outside `minDate`/`maxDate`/`disablePast`/`disableFuture` is no longer moved to the nearest allowed day on blur. It is kept, and the form refuses it. If your schema has no min/max rule, add one.
+
 Every other `Calendar` prop (`disablePast`, `minDate`, …) is passed to the
 calendar. A typed date outside `minDate`, `maxDate`, `disablePast` or
-`disableFuture` is no value while it is typed, and moves to the nearest day
-inside them once focus leaves the field. A typed day that `disabledDays`
+`disableFuture` is no value while it is typed, and is kept as entered once
+focus leaves the field (never moved to another day: the form's rule refuses
+it, the calendar keeps the day unpickable). A value you set from outside
+(`setValue`) is shown and kept the same way. A typed day that `disabledDays`
 rules out is refused: it stays on screen with no value (it is not moved to
 another day). An Invalid Date is no value. `id` goes on the first
 segment (the label's target); `aria-describedby` and `data-*` attributes on
@@ -362,8 +366,8 @@ is `{ from, to: undefined }`, and no start is `undefined`. An end before the
 start is no `to` (it stays on screen, and becomes the `to` once the start is
 moved before it), and a start typed past the end drops the end, as a click in
 the calendar does. A date outside `minDate`, `maxDate`, `disablePast` or
-`disableFuture` is no value while it is typed and moves to the nearest day
-inside them once focus leaves the field; a day `disabledDays` rules out is
+`disableFuture` is no value while it is typed and is kept as entered once
+focus leaves the field (the form refuses it); a day `disabledDays` rules out is
 refused, kept on screen with no value. Retyping the start keeps the end
 while the start is incomplete. Typing a day keeps the time of day
 of the end it replaces (`withTime`). The ends sit on one line while they fit

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

@@ -1197,7 +1197,17 @@ const RouterLink: AppShellLinkComponent = ({ href, ...props }) => <Link to={href
 />
 ```
 
-A title that does not fit the trigger is cut with an ellipsis: the span carries the full title in `aria-label` (what `expectNoTextOverflow` of `@nxgt/playwright` reads), hovering or focusing the trigger shows it with the subtitle in a tooltip, and the trigger's accessible name is the label, the full title and the subtitle.
+A title that does not fit the trigger is cut with an ellipsis: the span carries the full title in `aria-label` (what `expectNoTextOverflow` of `@nxgt/playwright` reads), hovering or focusing the trigger shows it with the subtitle in a tooltip, and the trigger's accessible name is the label, the full title and the subtitle. An option's subtitle that does not fit, in the trigger (default variant; the expressive pill keeps it for screen readers only), the menu or the panel, is treated the same way while it is cut: the full text in `aria-label` and, in the options, in `title`, and in the trigger's tooltip. The option's accessible name still reads the title and the subtitle once each.
+
+**Choosing a link closes the panel.** In link mode the popover or the phone sheet closes when an option (or a footer link) is activated, as in select mode, and focus is **not** handed back to the trigger: the navigation owns it, so a route's own focus on the new page's title runs. `open` and `onOpenChange` control the panel from the app (close it from a route effect, or open it from a shortcut):
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Switcher label="Group" value={id} options={groups} getHref={(g) => `/groups/${g.id}`} linkComponent={RouterLink} open={open} onOpenChange={setOpen} />;
+```
+
+To put a Switcher at the start of a page header, pass it as [EntityHeader](data-display.md#entityheader)'s `leading` (not `icon`).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
@@ -1213,6 +1223,8 @@ A title that does not fit the trigger is cut with an ellipsis: the span carries
 | `footer` | `{ label?, onSelect?, href? }` | — | a "Manage…" button (a link with `href`) at the end of the panel; `label` defaults to `material.switcher.manage` |
 | `emptyLabel` | `ReactNode` | `material.switcher.empty` | shown when the search matches nothing |
 | `sheet` | `boolean` | on a phone | `true` always opens a sheet, `false` never |
+| `open` | `boolean` | uncontrolled | controls the panel (popover, menu or sheet); pair with `onOpenChange` |
+| `onOpenChange` | `(open: boolean) => void` | — | called when the panel opens or closes, by the user or after a pick |
 | `name`, button props | `ComponentProps<'button'>` | — | spread on the trigger; `name` is its `data-pw` |
 
 `SwitcherItem`: `{ id, title, subtitle?, icon?, group?, initial?, tone?, badge?, href?, disabled? }`.

package/docs/troubleshooting.md

@@ -36,6 +36,8 @@ words in your error.
 - [`IconRefError` from `IconSpritesProvider`](#iconreferror-from-iconspritesprovider)
 - [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
 - [`ARIA hidden element must not be focusable or contain focusable elements`](#aria-hidden-element-must-not-be-focusable-or-contain-focusable-elements)
+- [A control in an `EntityHeader`'s `icon` is hidden from assistive tech, squashed, and reports `aria-hidden-focus`](#a-control-in-an-entityheaders-icon-is-hidden-from-assistive-tech-squashed-and-reports-aria-hidden-focus)
+- [A `Switcher` in link mode leaves focus on the trigger after a navigation, and the new page's title never gets it](#a-switcher-in-link-mode-leaves-focus-on-the-trigger-after-a-navigation-and-the-new-pages-title-never-gets-it)
 - [An accessibility audit reports low contrast on a tonal or outlined button, a selected list tile or a hovered badge link](#an-accessibility-audit-reports-low-contrast-on-a-tonal-or-outlined-button-a-selected-list-tile-or-a-hovered-badge-link)
 - [An accessibility audit reports low contrast on error text in the dark theme](#an-accessibility-audit-reports-low-contrast-on-error-text-in-the-dark-theme)
 - [An accessibility audit reports low contrast on primary text in the dark theme](#an-accessibility-audit-reports-low-contrast-on-primary-text-in-the-dark-theme)
@@ -180,6 +182,8 @@ words in your error.
 - [`Module '"@nxgt/material"' has no exported member 'formatAmount'`](#module-nxgtmaterial-has-no-exported-member-formatamount)
 - [An amount in yen shows no decimals, or one in dinars shows three](#an-amount-in-yen-shows-no-decimals-or-one-in-dinars-shows-three)
 - [A date shows the day before](#a-date-shows-the-day-before)
+- [A `DateField` with `disableFuture` (or `disablePast`, `minDate`, `maxDate`) moved my value to the previous day](#a-datefield-with-disablefuture-or-disablepast-mindate-maxdate-moved-my-value-to-the-previous-day)
+- [axe `target-size` flags a chip's ✕](#axe-target-size-flags-a-chips-)
 - [`Invalid hook call` in a `PrintDocument` `footer` function](#invalid-hook-call-in-a-printdocument-footer-function)
 - [Body text runs under the footer or the page number](#body-text-runs-under-the-footer-or-the-page-number)
 - [The `LOGO` box in `PrintHeader` is gone after upgrading](#the-logo-box-in-printheader-is-gone-after-upgrading)
@@ -956,6 +960,35 @@ Elements mounted after the layer opens are not made inert: mount them
 first, or pass them to `inertOthers` in `keep` when they must stay
 reachable.
 
+### A control in an `EntityHeader`'s `icon` is hidden from assistive tech, squashed, and reports `aria-hidden-focus`
+
+**When:** an `EntityHeader` gets a `Switcher`, a button or a link as its `icon`.
+The control is drawn small and clipped inside a filled square, a screen reader
+skips it, and an accessibility audit (axe) reports `aria-hidden-focus`.
+**Why:** `icon` is decoration: it is wrapped in a filled, icon-sized badge with
+`aria-hidden="true"`, so anything focusable inside it is an `aria-hidden`
+subtree the keyboard still reaches.
+**Fix:** put the control in `leading`: it is drawn as it is, at its natural
+size, beside the title, with no badge and no `aria-hidden`. When both are
+given, `leading` replaces `icon` (and warns in development).
+
+```tsx
+<EntityHeader
+	leading={<Switcher label="Group" value={group} onValueChange={setGroup} options={groups} />}
+	title="Attendance"
+/>
+```
+
+### A `Switcher` in link mode leaves focus on the trigger after a navigation, and the new page's title never gets it
+
+**When:** a `Switcher` with `getHref` and your router's `linkComponent`: you pick an option, the URL changes, but focus sits on the Switcher's trigger (or on the clicked link while the panel is open) instead of moving to the new page's title.
+**Why:** a closing overlay hands focus back to its trigger, which ran after your route's own focus handling. Older versions also gave you no way to close the panel yourself.
+**Fix:** update `@nxgt/material`: activating a link option closes the popover or sheet and no longer returns focus to the trigger, so the page's focus runs. To close it from the app, control it with `open` and `onOpenChange`.
+
+```tsx
+<Switcher label="Group" value={id} options={groups} getHref={(g) => `/groups/${g.id}`} linkComponent={RouterLink} open={open} onOpenChange={setOpen} />
+```
+
 ### An accessibility audit reports low contrast on a tonal or outlined button, a selected list tile or a hovered badge link
 
 **When:** axe (or Lighthouse) reports `color-contrast` on a `tonal` or
@@ -1062,7 +1095,7 @@ by default; `hitArea: false` brings back the box check), so these controls pass
 on a coarse pointer when their `::after` can be hit: not under a sticky bar or
 a toast, not clipped by an ancestor's `overflow`, and with its 44px square on
 screen. Rows, the app shell's triggers and the calendar's days are real 44px
-boxes and pass with either version.
+boxes and pass with either version. A chip's ✕ is a real box too (24x24, 44x44 on a coarse pointer).
 See [Theming, touch targets](./guides/theming.md#touch-targets).
 
 ### A Switch looks bigger, or a test reads `translate-x-*`
@@ -3230,6 +3263,37 @@ formatAmount(1234.5, 'JPY', { fractionDigits: 2 }); // '¥1,234.50'
 <CurrencyField label="Price" currency="JPY" fractionDigits={2} value={price} onChange={setPrice} />
 ```
 
+### A `DateField` with `disableFuture` (or `disablePast`, `minDate`, `maxDate`) moved my value to the previous day
+
+**When:** before the fix, a value past a bound (a `setValue` of "now + 1 h"
+shortly before midnight, or a date typed past `maxDate`) came back from the
+field about 24 hours earlier, and a form rule such as "not in the future"
+passed on a date nobody chose.
+**Why:** when focus left the field, it moved the value onto the bound's day and
+kept its time of day, so tomorrow 00:30 became today 00:30.
+**Fix:** upgrade: the field keeps the value it is given or that was typed, the
+calendar keeps the out-of-bounds days unpickable, and your form refuses the
+value. Add the rule to the schema (and a test that does not depend on the
+clock):
+
+```tsx
+const schema = z.object({
+  at: z.date().refine((d) => d <= new Date(), 'Must not be in the future'),
+});
+<DateFormField control={form.control} name="at" label="Recorded at" showTimePicker disableFuture />;
+```
+
+### axe `target-size` flags a chip's ✕
+
+**When:** before the fix, a scan of a desktop (fine-pointer) page flagged
+`[data-slot="chip-dismiss"]` (a `Chip` with `onDismiss`, the `Filter` bar's pills
+and active chips, the `ServerTable` chips) for a 16-18px box.
+**Why:** the 24px target was a `::after` pseudo-element, which axe does not
+measure.
+**Fix:** upgrade: the ✕ button's own box is 24x24 (44x44 on a coarse pointer),
+drawn and laid out as before. Remove any exclusion of `chip-dismiss` from your
+axe scan.
+
 ### A date shows the day before
 
 **When:** before 2.2.0, `formatDate('2026-03-01')` printed `Feb 28, 2026` on a

package/lib/components/ui/display/chip/chip-parts.css

@@ -1,5 +1,5 @@
 /* Chip: focus, the dismiss button (drawn
- * small, a 24x24 target through ::after, its own ring), disabled, the dashed
+ * small in a 24x24 box, 44x44 on a coarse pointer, its own ring), disabled, the dashed
  * "add" chip and the tones. */
 @layer components {
 	/* Focus: the chip's ring (2px primary-text, 2px away); the ✕ its own. */
@@ -8,54 +8,41 @@
 		outline-color: var(--primary-text);
 		outline-width: 2px;
 	}
+	/* The ✕ is drawn small (--chip-x), but its own box is the target (#1584):
+	 * axe's `target-size` reads the bounding box, never a pseudo-element. The
+	 * box is 24x24 (44x44 on a coarse pointer, #1067, #1102); the padding with
+	 * `background-clip: content-box` keeps the hover disc and the focus ring at
+	 * the drawn size, and the negative margin takes the extra back, so the chip
+	 * and the glyph are unchanged. */
 	.nxgt-chip > [data-slot="chip-dismiss"] {
+		--chip-hit: 24px;
+		--chip-pad: calc((var(--chip-hit) - var(--chip-x)) / 2);
 		position: relative;
 		display: inline-grid;
 		place-items: center;
 		flex: none;
-		width: var(--chip-x);
-		height: var(--chip-x);
-		padding: 0;
+		box-sizing: border-box;
+		width: var(--chip-hit);
+		height: var(--chip-hit);
+		margin: calc(-1 * var(--chip-pad));
+		padding: var(--chip-pad);
 		border: 0;
 		border-radius: 9999px;
 		background: transparent;
+		background-clip: content-box;
 		color: color-mix(in oklab, var(--foreground) 62%, transparent);
 		cursor: pointer;
 		/* Width 0 at rest: forced colours would paint a transparent outline. */
 		outline: 0 solid transparent;
-		outline-offset: 1px;
+		outline-offset: calc(1px - var(--chip-pad));
 		transition:
 			background-color 120ms ease-out,
 			color 120ms ease-out,
 			outline-color 120ms ease-out;
 	}
-	.nxgt-chip > [data-slot="chip-dismiss"]::after {
-		content: "";
-		position: absolute;
-		inset: calc((var(--chip-x) - 24px) / 2);
-		border-radius: 9999px;
-	}
-	/* Touch (#1067, #1102): on a coarse pointer the ✕ is a real 44x44 box,
-	 * not a pseudo-element, which a tap-target check and axe do not measure.
-	 * The negative margin takes the extra back, so the chip is unchanged, and
-	 * the padding with `background-clip: content-box` keeps the hover disc
-	 * and the focus ring at the drawn size (the outline is pulled in by the
-	 * padding). */
 	@media (pointer: coarse) {
 		.nxgt-chip > [data-slot="chip-dismiss"] {
-			--chip-pad: calc((44px - var(--chip-x)) / 2);
-			box-sizing: border-box;
-			width: 44px;
-			height: 44px;
-			margin: calc(-1 * var(--chip-pad));
-			padding: var(--chip-pad);
-			background-clip: content-box;
-			outline-offset: calc(1px - var(--chip-pad));
-		}
-		/* The box is the target now: the 24px pseudo-element would reach
-		 * past it. */
-		.nxgt-chip > [data-slot="chip-dismiss"]::after {
-			inset: 0;
+			--chip-hit: 44px;
 		}
 	}
 	.nxgt-chip > [data-slot="chip-dismiss"] > svg {

package/package.json

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