@nxgt/material 3.19.0 → 3.20.0

package/docs/components/data-display.md

@@ -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/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)
@@ -956,6 +958,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

package/package.json

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