@nxgt/material 3.64.0 → 3.66.0

package/dist/{use-heading-spy-mmcyEGmm.js → use-heading-spy-K-HUp4o_.js}

@@ -1,8 +1,8 @@
 import { t as e } from "./utils-BLfntITJ.js";
-import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-RHm6WtQj.js";
-import { a as l } from "./button-DfS_amfQ.js";
-import { i as u } from "./translate-material-CvZK8_S6.js";
-import { t as d } from "./use-material-translation-C_1cWRzW.js";
+import { a as t, c as n, d as r, i, n as a, r as o, t as s, u as c } from "./alert-dialog-BgQDxcYh.js";
+import { a as l } from "./button-2de_lrix.js";
+import { i as u } from "./translate-material-BlCQ6AW9.js";
+import { t as d } from "./use-material-translation-DkE9J5NE.js";
 import { _ as f, g as p, h as m, n as h, v as g, y as _ } from "./number.utils-BG_eEt5g.js";
 import { useCallback as v, useEffect as y, useMemo as b, useRef as x, useState as S } from "react";
 import { jsx as C, jsxs as w } from "react/jsx-runtime";

package/dist/{use-material-translation-C_1cWRzW.js → use-material-translation-DkE9J5NE.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-CvZK8_S6.js";
+import { i as e, t } from "./translate-material-BlCQ6AW9.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{use-return-focus-1ZIchrBM.js → use-return-focus-KypnR7vv.js}

@@ -1,6 +1,6 @@
 import { o as e, r as t } from "./dist-DVRQkaTK.js";
 import { a as n, c as r, i, l as a, o, r as s, s as c } from "./dist-lmHmz_bu.js";
-import { C as l, S as u, w as d } from "./spinner-CAnpF3RK.js";
+import { C as l, S as u, w as d } from "./spinner-PdSk7zEs.js";
 import { c as f, i as p, l as m, o as h, r as g, s as ee } from "./in-dialog-Vwkyp-M5.js";
 import { r as _ } from "./escape-owner-DpaP0lm1.js";
 import * as v from "react";

package/docs/components/README.md

@@ -14,10 +14,12 @@ What the stylesheet gives any element, not a component: the animation classes (`
 
 ## [Primitives](primitives.md)
 
-Building blocks with no opinion of their own: card surface, typography, label, input, textarea, input group, icon, kbd, separator, scroll area, table, tabs, toggle, accordion, collapsible. 20 entries.
+Building blocks with no opinion of their own: card surface, typography, label, input, textarea, input group, icon, kbd, separator, scroll area, table, tabs, route tabs, toggle, segmented route links, accordion, collapsible. 22 entries.
 
 [<img src="../previews/primitives-card.webp" height="72" alt="Card">](primitives.md#card)
 [<img src="../previews/primitives-tabs.webp" height="72" alt="Tabs">](primitives.md#tabs)
+[<img src="../previews/primitives-tabsnav.webp" height="72" alt="TabsNav">](primitives.md#tabsnav)
+[<img src="../previews/primitives-segmentednav.webp" height="72" alt="SegmentedNav">](primitives.md#segmentednav)
 [<img src="../previews/primitives-inputgroup.webp" height="72" alt="InputGroup">](primitives.md#inputgroup)
 [<img src="../previews/primitives-table.webp" height="72" alt="Table">](primitives.md#table)
 

package/docs/components/buttons-and-actions.md

@@ -16,6 +16,7 @@ and language switches. Everything is imported from `@nxgt/material/components`.
 | <img src="../previews/buttons-actions-responsivebutton.webp" width="96" alt=""> | [ResponsiveButton](#responsivebutton) | Label on desktop, icon-only on mobile |
 | <img src="../previews/buttons-actions-linkbutton.webp" width="96" alt=""> | [LinkButton](#linkbutton) | The button styles as `react-router` links |
 | <img src="../previews/buttons-actions-copybutton.webp" width="96" alt=""> | [CopyButton](#copybutton) | Copies a value, shows a check mark |
+| <img src="../previews/buttons-actions-sharebutton.webp" width="96" alt=""> | [ShareButton](#sharebutton) | Opens the system share sheet, copies the link where there is none |
 | <img src="../previews/buttons-actions-highlighttext.webp" width="96" alt=""> | [HighlightText](#highlighttext) | Marks matches of a query inside a string |
 | <img src="../previews/buttons-actions-loadmorebutton.webp" width="96" alt=""> | [LoadMoreButton](#loadmorebutton) | "Load more" for cursor pagination |
 | <img src="../previews/buttons-actions-loadmorefooter.webp" width="96" alt=""> | [LoadMoreFooter](#loadmorefooter) | Shown-of-total line, load button and a failed state with retry, for a paged list |
@@ -919,6 +920,34 @@ The write is awaited: "Copied" appears only once the clipboard accepted the text
 
 ---
 
+## ShareButton
+
+![ShareButton](../previews/buttons-actions-sharebutton.webp)
+
+Shares a link, a text or a title through the system share sheet (`navigator.share`) and copies the link instead where the sheet is missing, or when it fails for a reason other than the user closing it. A closed sheet (`AbortError`) does nothing. It reuses `CopyButton`'s status: "Copied" or "Copy failed" is announced through a visually hidden `role="status"` region, and the button keeps its name.
+
+```tsx
+import { ShareButton } from '@nxgt/material/components';
+
+<ShareButton title="Join the room" url="https://app.example.com/rooms/42" />;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `url`, `text`, `title` | `string` | — | what is shared; the copy fallback puts the `url`, else the `text`, else the `title` on the clipboard |
+| `label` | `string` | `"Share"` (translated, `material.share.share`) | the accessible name; it never changes after a click |
+| `copiedLabel`, `failedLabel` | `string` | `material.copy.copied` / `.failed` | announced after the fallback copy |
+| `icon` | `ReactNode` | `Share2` | the idle icon |
+| `onShare` | `(outcome) => void` | — | `'shared'`, `'cancelled'`, `'copied'` or `'failed'` |
+
+Other props pass through to `IconButton` (`variant` defaults to `ghost`, `color` to `default`). The types `ShareData` (`{ title?, text?, url? }`) and `ShareOutcome` (`'shared' | 'cancelled' | 'copied' | 'failed'`) are exported.
+
+`navigator` is read when the button is clicked, never while rendering, so the component is safe to server-render. The name is also exported as `SHARE_BUTTON_LABEL` for tests (`getByRole('button', { name: SHARE_BUTTON_LABEL })`).
+
+**Storybook:** `Buttons & actions/ShareButton` · **Vue:** not yet (tracked as a `vue` issue)
+
+---
+
 ## HighlightText
 
 ![HighlightText](../previews/buttons-actions-highlighttext.webp)
@@ -975,7 +1004,7 @@ buttons.
 
 ![LoadMoreFooter](../previews/buttons-actions-loadmorefooter.webp)
 
-The footer of a paged list: a "Showing N of M" line (a polite live region), the load button and, when the next page failed, an error alert whose "Try again" calls `onLoad`. The rows already shown stay on screen. It renders nothing when there is no next page. When the last page arrives it keeps the status line (so the final "Showing 85 of 85" is announced) and, if the button had the focus as it went away, takes the focus itself (the footer is `tabIndex={-1}`); a list that never had a next page renders nothing, and a list that restarts smaller (a new filter, `shown` or `total` dropping) drops the line. That is a heuristic: a restart at the same size or larger (a new query whose first page ends the list, `total` unknown) cannot be told from a real end, and `shown === 0` (a list being rebuilt) is ignored. Give a standalone footer a `key` that names the query (the search, filters and sort, not the page), `<LoadMoreFooter key={queryIdentity} … />`, so a new query starts it afresh; `ServerTable` does it for you.
+The footer of a paged list: a "Showing N of M" line (a polite live region), the load button and, when the next page failed, an error alert whose "Try again" calls `onLoad`. The rows already shown stay on screen. It renders nothing when there is no next page. When the last page arrives it keeps the status line (so the final "Showing 85 of 85" is announced) and, if the button had the focus as it went away, takes the focus itself (the footer is `tabIndex={-1}`); a list that never had a next page renders nothing, and a list that restarts smaller (a new filter, `shown` or `total` dropping) drops the line. That is a heuristic: a restart at the same size or larger (a new query whose first page ends the list, `total` unknown) cannot be told from a real end, and `shown === 0` (a list being rebuilt) is ignored. Give a standalone footer a `key` that names the query (the search, filters and sort, not the page), `<LoadMoreFooter key={queryIdentity} … />`, so a new query starts it afresh; `ServerTable` does it for you. `ServerTable` also takes no `totalCount` (an API with no total): its `footer="load-more"` then reads "20 shown" while a next page exists, never a made-up "N of N" ([ServerTable, load-more](./data-table-filter-and-lists.md#servertable)).
 
 ```tsx
 import { LoadMoreFooter } from '@nxgt/material/components';

package/docs/components/data-display.md

@@ -16,7 +16,7 @@ from `@nxgt/material/components`.
 | <img src="../previews/data-display-dayseparator.webp" width="96" alt=""> | [DaySeparator](#dayseparator) | "Today", "Yesterday" or the date between two hairlines |
 | <img src="../previews/data-display-periodcards.webp" width="96" alt=""> | [PeriodCards](#periodcards) | Consecutive date ranges (terms, sprints) as cards, with a current marker and an optional link per card |
 | <img src="../previews/data-display-chip.webp" width="96" alt=""> | [Chip](#chip) | Three looks and a dashed add pill, with slots, a selected state and a dismiss button |
-| <img src="../previews/data-display-statcard.webp" width="96" alt=""> | [StatCard](#statcard) | KPI tile with value, hint, icon and toned delta |
+| <img src="../previews/data-display-statcard.webp" width="96" alt=""> | [StatCard](#statcard) | KPI tile with value, hint, icon and toned delta; `href` makes it one link |
 | <img src="../previews/data-display-metric-cards.webp" width="96" alt=""> | [Metric cards](#metric-cards) | Sixteen dashboard tiles |
 | <img src="../previews/data-display-card-presets.webp" width="96" alt=""> | [Card presets](#card-presets) | Twenty-seven ready-made cards |
 | <img src="../previews/data-display-statusindicator.webp" width="96" alt=""> | [StatusIndicator](#statusindicator) | Coloured status dot with a label |
@@ -591,11 +591,24 @@ import { StatCard } from '@nxgt/material/components';
 | `variant` | `'outlined' \| 'tonal' \| 'filled'` | `'outlined'` | `tonal` paints the card with the tone's container and a fine outline in its text colour (3:1 against the page); `filled` paints it with the tone and draws everything on it in the on-colour. Both use `neutral` when there is no `tone`. Every text is 4.5:1 or more. In a [calm zone](../guides/theming.md#calm-zone), a `tonal` or `filled` card is the card's own surface with the tone's ring, and its icon chip a ring |
 | `valueSize` | `'default' \| 'display'` | `'default'` | `display` draws the value larger (`headline-large`) |
 | `size` | `'default' \| 'sm'` | `'default'` | `sm` is a compact tile for a band or a header (see below); it ignores `hint`, `delta` and `valueSize` |
+| `href` | `string` | — | the whole card is one link: an `<a>` around the card (one tab stop), named by its label and value, with a trailing chevron (so it reads as a link without hover), a hover border and a focus-visible ring. Without `href` the card is a plain `div`. An external address (`https://`, `mailto:`) is a plain `<a target="_blank" rel="noreferrer">`. `className` and the other props still go on the card |
+| `linkComponent` | `LinkComponent` | a plain `<a>`, or the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider)'s | with `href`: renders the link with your router's link, given `href`. It must spread every prop it receives (`className`, handlers, `data-*`) and forward `ref` |
 
 ```tsx
 <StatCard tone="success" variant="tonal" valueSize="display" label="Revenue" value="€48,200" delta={12.4} icon={<CreditCard />} />
 ```
 
+**A tile that leads somewhere.** `href` makes the whole card one link, so a count per category can open its list; the focus ring, hover border and chevron are the card's own, with nothing to restyle.
+
+```tsx
+<StatCard href="/revenue" label="Revenue" value="€48,200" />
+
+// With your router: wrap its Link so it takes `href`, once for every link in the app
+// with <LinkComponentProvider component={MyLink}>, or for this card only:
+const MyLink = ({ href, ...props }: LinkComponentProps) => <Link to={href} {...props} />;
+<StatCard linkComponent={MyLink} href="/items?state=a" label="Items" value={12} />
+```
+
 **Compact tile (`size="sm"`).** For figures in a header band: a tile 40 to 56 px tall that hugs its content, the optional icon chip, then the value (tabular figures) over its label. It takes the same `tone` and `variant` (`tonal`, `outlined`, `filled`); `hint`, `delta` and `valueSize` are ignored (nothing is drawn for them, and `loading` shows a skeleton in place of the value only). Tiles in a `flex flex-wrap gap-2` row sit side by side and wrap on a phone; for an even layout use `StatCardGroup`.
 
 ```tsx

package/docs/components/data-table-filter-and-lists.md

@@ -622,7 +622,12 @@ export default function Students() {
   announces "41–60 of 133" when the page changes. With neither `offset` nor
   `totalCount` the region is empty, and is kept in the DOM so a later change
   is still announced; on an empty page too, which never reads "0 rows" (see
-  [an empty server page](#an-empty-server-page)). The table already has a visually hidden status for
+  [an empty server page](#an-empty-server-page)). `ServerTable` with no
+  `totalCount` (a cursor feed) passes no `offset` and no `totalCount`: the
+  footer is Previous / Next from `pageInfo` and the cursor trail, and its live
+  region says the rows on the page ("20 shown"); a later page that comes back
+  empty is not announced as "0 results", since only the first page can say
+  there are none. The table already has a visually hidden status for
   "Loading data…" (a `<p role="status" aria-live="polite" aria-atomic="true">`,
   `data-slot="data-table-status"`; the page may have a toast region too), so a test finds the
   range with `getByRole('status', { name: 'Rows shown' })`, not a bare
@@ -706,6 +711,8 @@ For the TanStack API itself (column helpers, features, row models), see
 
 One server page of a list in a `manual` `DataTable`, its state in the URL's search params and no router imported: a top band (the title, the [filter bar](#filter-bar) and its active filters in one `search` landmark, the page's actions), the sort, forward cursor paging (`after` plus a `trail`), a selection that follows the user across pages but resets on a new query, the empty page, and the count announced once a new query is answered.
 
+`totalCount` is optional: an API that gives no total (an audit log, an event feed) leaves it out, and the paged footer is then Previous / Next from `pageInfo` and the cursor trail, with no "x of y" (the same footer as [PageFooter](#pagefooter) without a total); the live region says "N shown", and a later page that comes back empty is not announced as "0 results".
+
 The `filter` prop is the list's [`Filter`](#filter-bar) (over
 `@nxgt/material-core/filter`): `ServerTable` renders it in the band,
 reads its query from the params and writes it back on the first page. The
@@ -1017,7 +1024,7 @@ Its props are `ServerTableProps<T>`; `filter` is a `ServerTableFilter`,
 | --- | --- | --- | --- |
 | `params` | `URLSearchParams` | — | the URL's search params |
 | `onParamsChange` | `(next: URLSearchParams) => void` | — | the router's setter |
-| `rows`, `totalCount`, `pageInfo` | the connection's page | — | `pageInfo: { endCursor?, hasNextPage }`; `rows` stable per answer |
+| `rows`, `totalCount`, `pageInfo` | the connection's page | — | `pageInfo: { endCursor?, hasNextPage }`; `rows` stable per answer. `totalCount` is optional: leave it out when the API gives no total (an audit log, an event feed); the paging footer is then Previous / Next from `pageInfo` and the cursor trail, with no "x of y", and the live region says the rows on the page ("N shown") |
 | `pageSize` | `number` | — | the footer's range ("21–40 of 45") |
 | `getRowId` | `(row) => string` | — | the selection's key |
 | `filter` | `ServerTableFilter` | — | `{ model, locked?, fieldProps?, variant?, sheetTrigger?, quick?, density?, shortcuts?, previewCount?, counts?, liveDelayMs?, label?, searchLabel?, searchPlaceholder?, searchApply?, searchMinLength?, codec?, defaults?, errors? }` |
@@ -1899,6 +1906,10 @@ if the button had the focus as it went away, the footer takes it
 (`tabIndex={-1}`). `ServerTable` restarts the footer by itself whenever `params` change (the search, filters and sort, not a page), so a new query never keeps the old list's last line.
 `footer="load-more"` without `onLoadMore` warns in development.
 
+A list whose API returns no total leaves `totalCount` out: while a next page
+exists the footer says "N shown" (never a made-up "N of N"), and after the
+last page it keeps that line with the final count.
+
 #### An inline chip group
 
 A `chips-single` or `chips-multiple` field declared `inline: true` shows its
@@ -1913,7 +1924,9 @@ way to narrow a list (the topics of a catalogue).
 - **Pressing** a chip sets the condition in one query change (back on the
   first page); pressing the chosen chip of a single group clears it. A
   multiple group toggles each chip. The group is a `radiogroup` (or a `group`
-  of checkboxes) named by the field's label.
+  of checkboxes) named by the field's label, and described (`aria-describedby`,
+  visually hidden text, `material.filter.inline-clear-hint`) as "Pressing a
+  selected chip removes it from the filter", since there is no "All" chip.
 - **A plain filter.** It is counted, in the URL like any field, and cleared by
   "Clear all". It has no chip of its own (the group shows it) and is not in
   "Add filter" nor among the quick pills; the phone sheet still lists it.

package/docs/components/form-fields.md

@@ -463,6 +463,14 @@ export function Quantity() {
 | `onBlur` | `FocusEventHandler` | — | after the typed text is read and `onChange` called |
 | `ref` | `Ref<HTMLInputElement>` | — | reaches the text input (React Hook Form's `field.ref`) |
 
+**Stepper names.** Each +/− button is named after its field: "Increase
+Quantity" / "Decrease Quantity" (`material.number-field.increase-named` and
+`decrease-named`, with the `label` interpolated), so a form with several number
+fields never gives a screen reader identical buttons. The name comes from a
+plain-text `label`, else from `aria-label`; with neither (a field named only
+through `aria-labelledby` included), the buttons keep the bare "Increase" /
+"Decrease".
+
 **Decimal separator.** After blur (and after +/−) the value is shown with the
 active language's separator, from `I18nProvider`: `1,5` in French, `1.5` in
 English (no grouping, so it stays editable). Typing accepts both: `1,5` and
@@ -476,7 +484,7 @@ Form's `field.ref` the input itself: `setFocus('amount')` and
 **Emits:** `number | null`.
 **Form wrapper:** `NumberFormField` — `control` and `name`, see
 [forms](../guides/forms.md#the-pair) and [what each field emits](../guides/forms.md#what-each-field-emits).
-**Storybook:** `Form fields/NumberField` · **Vue:** `NumberField`, `NumberFormField` (the language separator is React only for now, #763)
+**Storybook:** `Form fields/NumberField` · **Vue:** `NumberField`, `NumberFormField` (the language separator is React only for now, #763; the stepper names, #2060)
 
 ---
 

package/docs/components/navigation-and-layout.md

@@ -373,6 +373,7 @@ the page. It takes a `div`'s props.
   the room the others leave, which keep their size. Give it the one filled
   `Button`; a second filled `Button` among the children warns once in
   development, make the others `outlined` or `tonal`.
+- **Surface.** Below `md` the bar paints `--background` (it is stuck over the content); from `md`, and with `sticky={false}`, it paints nothing and takes its parent's surface, such as a `Card`.
 - **Safe areas.** Under `viewport-fit=cover` the bar pads clear of
   `env(safe-area-inset-left | right | bottom)`, as classes.
 - **Keyboard.** From the visual viewport (`visualViewport`), the bar rises by
@@ -460,12 +461,15 @@ import { ListDetailsLayout, PaneLayout, ThreadLayout } from '@nxgt/material/comp
 </ThreadLayout>
 ```
 
-Below 648 px `ListDetailsLayout` shows one view at a time and
+At 648 px and narrower `ListDetailsLayout` shows one view at a time and
 `PaneLayout` moves its pane into a sheet; the `…Trigger` parts switch view or
-open the pane (`ListDetailsTrigger` takes the `view` to show), and their `children` / `className` can be functions of the
-layout state. A server, which has no screen width, renders the wide layout,
-as does a hydrating client; a phone switches right after hydrating. A page
-rendered only in the browser starts on the real layout. `ThreadLayout` is a centred column over the app
+open the pane (`ListDetailsTrigger` takes the `view` to show), and their
+`children` / `className` can be functions of the layout state. A server, which
+has no screen width, renders the wide layout, as does a hydrating client; a
+phone switches right after hydrating. `PaneLayout`'s inline pane is hidden by
+CSS at 648 px and narrower, so a phone never sees it flash before the sheet
+takes over. A page rendered only in the browser starts on the real layout.
+`ThreadLayout` is a centred column over the app
 [background](#background) on the page ground (`bg-ground`, so a `bg-card` card stands apart) for focused flows (sign-in, onboarding), with no
 app bar.
 

package/docs/components/primitives.md

@@ -24,6 +24,8 @@ other pages are built from these.
 | <img src="../previews/primitives-scrollarea.webp" width="96" alt=""> | [ScrollArea](#scrollarea) | Scroll container with a thin themed scrollbar |
 | <img src="../previews/primitives-table.webp" width="96" alt=""> | [Table](#table) | Styled semantic table inside a scrollable wrapper |
 | <img src="../previews/primitives-tabs.webp" width="96" alt=""> | [Tabs](#tabs) | Tabs whose triggers can take an icon |
+| <img src="../previews/primitives-tabsnav.webp" width="96" alt=""> | [TabsNav](#tabsnav) | Route tabs as links, with `aria-current` |
+| <img src="../previews/primitives-segmentednav.webp" width="96" alt=""> | [SegmentedNav](#segmentednav) | Segmented links, with `aria-current` and the pill |
 | <img src="../previews/primitives-toggle.webp" width="96" alt=""> | [Toggle](#toggle) | Pressable on / off button |
 | <img src="../previews/primitives-togglegroup.webp" width="96" alt=""> | [ToggleGroup](#togglegroup) | Connected, segmented or separate toggle group |
 | | [Activity](#activity) | React `<Activity>` switched by a boolean |
@@ -784,6 +786,8 @@ indicator is placed inside it, measured against it, so the child must render
 its children directly: a component child that wraps them in an inner element
 hides the indicator.
 
+For tabs that go to routes, use [TabsNav](#tabsnav): real links with `aria-current`, not tabs with panels.
+
 `TabsTrigger asChild` makes your link the tab (`<TabsTrigger value="a" asChild><Link to="/a">A</Link></TabsTrigger>`): the indicator and the icon and label spans go inside it. `ToggleGroupItem`, `AccordionTrigger`, `SelectTrigger` and `ExtendedLabel` take `asChild` the same way.
 
 `dir="rtl"` on `Tabs` (or Radix's `DirectionProvider`) runs the tabs from the
@@ -822,6 +826,211 @@ as `segmented`. Both still type-check and render; write `underline` or
 
 ---
 
+## TabsNav
+
+![TabsNav](../previews/primitives-tabsnav.webp)
+
+Route tabs as links: a `nav` of links in the `Tabs` look, with `aria-current="page"` on the current one, the sliding indicator and the phone scroll cue.
+
+```tsx
+import { TabsNav, TabsNavLink } from '@nxgt/material/components';
+
+<TabsNav aria-label="Account sections" value="billing">
+	<TabsNavLink to="/profile" value="profile">
+		Profile
+	</TabsNavLink>
+	<TabsNavLink to="/billing" value="billing">
+		Billing
+	</TabsNavLink>
+</TabsNav>;
+```
+
+Use `Tabs` when the panels are on the page and `TabsNav` when each tab is a
+place to go: every tab is a real link, so it opens in a new window and its
+address can be copied. `aria-label` names the navigation and is required.
+
+- **Current link**: `TabsNav`'s `value` is matched against each link's
+  `value`; a link's `current` boolean overrides it (`current={false}` to
+  switch one off). The current link carries `aria-current="page"` and
+  `data-state="active"`, which is what the indicator follows.
+- **Keyboard**: the links are plain links, so Tab moves from one to the next;
+  the arrow keys do nothing (they are not tabs, there is no `tablist`).
+- **Looks**: `variant="underline"` (the default) or `"segmented"`, as `Tabs`.
+  A nav wider than its container scrolls inside itself, with the same edge
+  fades and scroll buttons as `Tabs`. On a coarse pointer each link is 44px
+  tall at least.
+- **The link**: `TabsNavLink` takes `LinkButton`'s props (`to`, `replace`,
+  `state`, `target`, `reloadDocument`, `download`, `linkComponent`) and an
+  `icon`. It renders React Router's `Link`, or the `LinkComponentProvider`'s
+  component (given `href`). `preventScrollReset` is on by default, so changing
+  tab keeps the scroll position; pass `preventScrollReset={false}` to reset.
+- A tab bound to the URL's search params: [`useTabParam`](#route-tabs-in-the-url-usetabparam).
+
+**It needs a Router.** Without a `LinkComponentProvider`, `TabsNavLink` renders
+React Router's `Link`, as `LinkButton` does, so it throws outside a Router
+(`useHref() may be used only in the context of a <Router> component`): render
+it inside your router, or set a [`LinkComponentProvider`](#linkcomponentprovider).
+See [the troubleshooting entry](../troubleshooting.md#usehref-may-be-used-only-in-the-context-of-a-router-component-on-a-tabsnav-segmentednav-or-a-linkbutton).
+
+| Prop | On | Type | Default | Effect |
+| --- | --- | --- | --- | --- |
+| `aria-label` | `TabsNav` | `string` | — (required) | names the navigation |
+| `value` | `TabsNav` | `string` | — | the current link's `value` |
+| `variant` | `TabsNav` | `'underline' \| 'segmented'` | `'underline'` | the look, as `Tabs` |
+| `to` | `TabsNavLink` | `To` | — (required) | the route, as for `LinkButton` |
+| `value` | `TabsNavLink` | `string` | — | matched against the nav's `value` |
+| `current` | `TabsNavLink` | `boolean` | — | marks the link current or not, over `value` |
+| `icon` | `TabsNavLink` | `ReactNode` | — | shown before the label |
+| `preventScrollReset` | `TabsNavLink` | `boolean` | `true` | keeps the scroll position when the tab changes |
+
+### Route tabs in the URL: `useTabParam`
+
+`useTabParam({ param = 'tab', values, defaultValue?, explicitDefault?, keepHash? })` keeps
+the current tab in a search param and feeds `TabsNav` or `SegmentedNav`. It
+returns `value` (the param if it is one of `values`, else `defaultValue`, else
+the first value: an unknown value falls back) and `hrefFor(tab)`, the `to` of a
+tab. `hrefFor` keeps the path and the other params; the default tab writes
+**no** param. It **drops the hash**: React Router's `ScrollRestoration` jumps
+to a hash even with `preventScrollReset`, so a kept `#section` would scroll the
+page on every tab click. Pass `keepHash: true` when you want it kept.
+Each tab is a navigation, so Back walks the tabs and a
+router blocker sees them; `preventScrollReset` (on by default) keeps the scroll.
+
+`skipTabChange(param = 'tab')` is for the route's `shouldRevalidate`: it returns
+`false` when a navigation changed only that param, so the loader is not read
+again for a tab switch. A same-URL, fetcher or manual revalidation, and any
+submission, still return `defaultShouldRevalidate`. Parent routes' loaders
+still revalidate unless they export `skipTabChange` too. It is typed as a
+`ShouldRevalidateFunction`.
+
+`tabIds(value, prefix = 'tab')` returns the stable ids
+`{ tab: '<prefix>-<value>', panel: '<prefix>-panel-<value>' }` for `id` and
+`aria-labelledby`. The value must be id-safe (no spaces); give each tab set on a
+page its own `prefix` to keep them apart.
+
+`values` is a non-empty tuple read as literal types (`const` generic): `value`
+and `hrefFor`'s argument are the union of its entries, and a misspelled tab or a
+`defaultValue` outside `values` is a compile error.
+
+**A loader must not read the tab param**: a skipped revalidation leaves its
+data as it was, so anything derived from `?tab=` would go stale. Read the tab
+in the component (`useTabParam`) instead.
+
+```tsx
+import { type LoaderFunctionArgs, useLoaderData } from 'react-router';
+import { skipTabChange, TabsNav, TabsNavLink, tabIds, useTabParam } from '@nxgt/material/components';
+
+const TABS = ['overview', 'history', 'files'] as const;
+
+export async function loader({ params }: LoaderFunctionArgs) {
+	return getRecord(params.id); // does not read `?tab=`
+}
+
+// route module: a tab switch does not reload the record
+export const shouldRevalidate = skipTabChange();
+
+export default function Record() {
+	const record = useLoaderData<typeof loader>();
+	// `explicitDefault`: another param implies a tab, so spell the default out
+	const { value, hrefFor } = useTabParam({ values: TABS, explicitDefault: !!record.from });
+	return (
+		<>
+			<TabsNav aria-label="Record sections" value={value}>
+				{TABS.map((tab) => (
+					<TabsNavLink key={tab} id={tabIds(tab).tab} to={hrefFor(tab)} value={tab}>
+						{tab}
+					</TabsNavLink>
+				))}
+			</TabsNav>
+			<section id={tabIds(value).panel} aria-labelledby={tabIds(value).tab}>
+				{/* mount only the shown panel */}
+			</section>
+		</>
+	);
+}
+```
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `param` | `'tab'` | the search param |
+| `values` | — (required) | the tabs a URL may name, in order |
+| `defaultValue` | the first value | the tab shown without a param; writes no param |
+| `explicitDefault` | `false` | writes the default tab's param out too (another param implies a tab) |
+| `keepHash` | `false` | keeps the location's hash in `hrefFor` (it scrolls to it, see above) |
+
+**Storybook:** `Primitives/TabsNav` (story `TabParam` for `useTabParam`) · **Vue:** none yet (#2055, #2065)
+
+---
+
+## SegmentedNav
+
+![SegmentedNav](../previews/primitives-segmentednav.webp)
+
+The segmented `ToggleGroup` look as a `nav` of links: a period or a view kept in the address, with `aria-current="page"` and the selected pill on the current one.
+
+```tsx
+import { SegmentedNav, SegmentedNavItem, useTabParam } from '@nxgt/material/components';
+
+const PERIODS = ['day', 'week'] as const;
+
+function Period() {
+	const { value, hrefFor } = useTabParam({ param: 'p', values: PERIODS });
+	return (
+		<SegmentedNav aria-label="Period" value={value}>
+			<SegmentedNavItem to={hrefFor('day')} value="day">
+				Day
+			</SegmentedNavItem>
+			<SegmentedNavItem to={hrefFor('week')} value="week">
+				Week
+			</SegmentedNavItem>
+		</SegmentedNav>
+	);
+}
+```
+
+Use `ToggleGroup` for a choice that stays on the page and `SegmentedNav` when
+each segment is a place to go: every item is a real link, so it opens in a
+new window and its address can be copied. A `ToggleGroup` of links would
+announce each as a radio. `aria-label` names the navigation and is required.
+
+- **Current item**: `SegmentedNav`'s `value` is matched against each item's
+  `value`; an item's `current` boolean overrides it (`current={false}` to
+  switch one off). The current item carries `aria-current="page"` and
+  `data-state="active"`, and draws the selected pill (its label in
+  `primary-text`); it does not glide, since the nav may scroll.
+- **Keyboard**: the items are plain links, so Tab moves from one to the next;
+  the arrow keys do nothing (there is no radio group).
+- **On a phone**: a nav wider than its container scrolls inside itself (the
+  page does not), with a fade on the side with hidden items, and the current
+  item is scrolled into view. On a coarse pointer each item is 44px tall at
+  least.
+- **The link**: `SegmentedNavItem` takes `LinkButton`'s props (`to`, `replace`,
+  `state`, `target`, `reloadDocument`, `download`, `linkComponent`). It renders
+  React Router's `Link`, or the `LinkComponentProvider`'s component (given
+  `href`). `preventScrollReset` is on by default, so changing segment keeps
+  the scroll position; pass `preventScrollReset={false}` to reset.
+- A segment bound to the URL's search params: [`useTabParam`](#route-tabs-in-the-url-usetabparam) (`useTabParam({ param: 'p', values })`), as above.
+
+**It needs a Router.** Without a `LinkComponentProvider`, `SegmentedNavItem`
+renders React Router's `Link`, as `LinkButton` does, so it throws outside a
+Router (`useHref() may be used only in the context of a <Router> component`):
+render it inside your router, or set a [`LinkComponentProvider`](#linkcomponentprovider).
+See [the troubleshooting entry](../troubleshooting.md#usehref-may-be-used-only-in-the-context-of-a-router-component-on-a-tabsnav-segmentednav-or-a-linkbutton).
+
+| Prop | On | Type | Default | Effect |
+| --- | --- | --- | --- | --- |
+| `aria-label` | `SegmentedNav` | `string` | — (required) | names the navigation |
+| `value` | `SegmentedNav` | `string` | — | the current item's `value` |
+| `size` | `SegmentedNav` | `'sm' \| 'md' \| 'lg'` | `'md'` | 32, 36 or 44 px tall, as `ToggleGroup` |
+| `to` | `SegmentedNavItem` | `To` | — (required) | the route, as for `LinkButton` |
+| `value` | `SegmentedNavItem` | `string` | — | matched against the nav's `value` |
+| `current` | `SegmentedNavItem` | `boolean` | — | marks the item current or not, over `value` |
+| `preventScrollReset` | `SegmentedNavItem` | `boolean` | `true` | keeps the scroll position when the segment changes |
+
+**Storybook:** `Primitives/SegmentedNav` · **Vue:** none yet (#2059)
+
+---
+
 ## Toggle
 
 ![Toggle](../previews/primitives-toggle.webp)

package/docs/components/rich-widgets.md

@@ -2207,6 +2207,7 @@ function Config() {
 | `height` | `string \| number` | `300` | editor height |
 | `readOnly` | `boolean` | `false` | a reader: the code can be selected, searched and copied, not changed; no caret and no current line, a quiet gutter, a Read-only badge and the line count in the status bar, Copy filled and labelled, no Format or language menu. Not dimmed (unlike `disabled`) |
 | `disabled` | `boolean` | — | dimmed, read-only, its tools off |
+| `aria-describedby` | `string` | — | the id(s) of what describes the code (a question's description, `QuestionCodeField.describedBy`); set on Monaco's input before the `helperText` id, each id once |
 | `lineNumbers` | `boolean` | `true` | the line numbers in the gutter |
 | `minimap` | `boolean` | `false` | Monaco's minimap |
 | `wordWrap` / `defaultWordWrap` / `onWordWrapChange` | `boolean` | `false` | wraps long lines; the pill's Word wrap toggles it (controlled when `wordWrap` is given) |

package/docs/guides/charts.md

@@ -241,7 +241,7 @@ const toneOf = (point: ChartPoint) =>
 | Prop | Effect |
 | --- | --- |
 | `bands` | `{ from, to, label, tone? }[]`: a wash across the plot behind the lines, with its `label` inside it at the left. `from` and `to` may come in either order, and are a number, a row field or a function of the row (a stepped band; typed `ChartRowValue`). |
-| `thresholds` | `{ value, label, tone?, dash? }[]` (`value`: a number, a row field or a function of the row): a horizontal line behind the series with its `label` above it at the right end; dashed unless `dash: false`. |
+| `thresholds` | `{ value, label, tone?, dash? }[]` (`value`: a number, a row field or a function of the row): a horizontal line behind the series with its `label` above it at the right end (under it when a point of a series sits where the label would be, so it never covers a point or its marker); dashed unless `dash: false`. |
 | `pointTone` | `(point: ChartPoint, series: ChartSeries) => Tone \| undefined`: the tone of one value. It is given the point `onPointClick` gets, so `point.index` is the row of the full `data` even when the chart is zoomed. |
 | `toneLabels` | `{ [tone]: word }`: the word of each tone, in your language and domain. Unset, the library's neutral word ("Error", translated by `material.charts.tone.*`); an app tone you declared falls back to its own name. |
 

package/docs/guides/code-editor.md

@@ -24,12 +24,26 @@ screen ("Open in editor"); `fullscreen` and `onFullscreenChange` let your
 own button do the same
 ([CodeEditor](../components/rich-widgets.md#codeeditor)).
 
+- [Describing the code](#describing-the-code)
 - [Client-only](#client-only)
 - [Themes](#themes)
 - [Your own theme](#your-own-theme)
 - [Self-hosting Monaco](#self-hosting-monaco)
 - [Moving off the barrel import](#moving-off-the-barrel-import)
 
+## Describing the code
+
+`aria-describedby` takes the id of the element that describes the code, such
+as the description line of a question. It goes on Monaco's input, before the
+id of the field's own `helperText`, so a screen reader reads both.
+
+```tsx
+<CodeEditor label="Answer" aria-describedby="question-description" />
+
+// In a QuestionCard:
+<QuestionCard renderCode={(field) => <CodeEditor aria-describedby={field.describedBy} />} />
+```
+
 ## Client-only
 
 The entry's built files carry no `'use client'` directive: import the

package/docs/guides/i18n.md

@@ -303,7 +303,9 @@ value to enter." (an operator such as "is empty")),
 `material.filter.op.<id>.*` for each operator (`is`, `is_not`, `in`,
 `between`, `before`, `after`, `contains`, `empty`, `gt`, `lt`, `gte`, `lte`):
 its `label` ("is any of") and its words on a chip, `chip` and, for several
-values, `chip-many`. "Clear all" is `material.filter.clear-all`. The phone sheet
+values, `chip-many`. "Clear all" is `material.filter.clear-all`. An inline chip group
+is described by `material.filter.inline-clear-hint` ("Pressing a selected chip
+removes it from the filter"). The phone sheet
 has `material.filter.sheet.*`: `title` "Filters" (its trigger and its
 title), `show` "Show results", `show-count` (an ICU plural over `count`:
 "No results", "Show # result", "Show # results") and `locked` "Locked

package/docs/roadmap.md

@@ -6,6 +6,8 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
+- **Link navigation** — `TabsNav` and `SegmentedNav` render route tabs and segmented navigation as a `nav` of links with `aria-current="page"`, looking like Tabs and the segmented ToggleGroup, plus `useTabParam` to keep the current tab in the URL. Tracked in [#2029](https://github.com/softistx/nxgt-material/issues/2029).
+
 - **Barcodes and label sheets** — `@nxgt/material/barcode` draws Code 128
   and Data Matrix as accessible SVG (themed, dark-aware, black on white in
   print) and lays labels out on a sheet to print: label size, columns, rows,
@@ -241,7 +243,6 @@ version they shipped in, and planned entries may name the major they target.
   slot; the bar's `views` slot is planned with it. They are meant to replace
   the legacy `FilterPresets`. Tracked in [#1876](https://github.com/softistx/nxgt-material/issues/1876).
 
-- **Link navigation** — `TabsNav` and `SegmentedNav` render route tabs and segmented navigation as a `nav` of links with `aria-current="page"`, looking like Tabs and the segmented ToggleGroup, plus `useTabParam` to keep the current tab in the URL.
 - **RecordActionsMenu** — one menu for a record's lifecycle: archive with an Undo toast (or confirm first with `archivePolicy="confirm"`), restore, and delete that always confirms and shows the backend's refusal, with `ConfirmDialog` gaining `details` and `refusal` slots.
 - **Cursor trail cap** — `ServerTable` and `PageFooter` keep cursor URLs short: the trail is encoded once and capped by `maxTrail` (20 by default) with an exact page count, and `totalCount` becomes optional for APIs that do not count.