@nxgt/material 3.65.0 → 3.67.0

package/dist/{use-heading-spy-Brcn0l_J.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-C0nGUSCP.js";
-import { a as l } from "./button-D5k3K-gM.js";
-import { i as u } from "./translate-material-BHL4g2UB.js";
-import { t as d } from "./use-material-translation-mY3U83TV.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-mY3U83TV.js → use-material-translation-DkE9J5NE.js}

@@ -1,4 +1,4 @@
-import { i as e, t } from "./translate-material-BHL4g2UB.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-BQ413TNG.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-OQAweH2r.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

@@ -15,7 +15,9 @@ and language switches. Everything is imported from `@nxgt/material/components`.
 | <img src="../previews/buttons-actions-toolbar.webp" width="96" alt=""> | [Toolbar](#toolbar) | A row or column of icon actions, floating or docked, one tab stop, overflow into More |
 | <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-backlink.webp" width="96" alt=""> | [BackLink](#backlink) | A link to the parent page with a leading arrow |
 | <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 |
@@ -889,6 +891,26 @@ Needs a `react-router` router above it.
 
 ---
 
+## BackLink
+
+![BackLink](../previews/buttons-actions-backlink.webp)
+
+A link to the parent page, for the top of a record, settings or detail page: a ghost `LinkButton` with a leading arrow.
+
+```tsx
+import { BackLink } from '@nxgt/material/components';
+
+<BackLink to="/items">All items</BackLink>;
+```
+
+It renders one `<a>`. The label names the destination and is the link's accessible name; the arrow is hidden from assistive tech and turns in right-to-left pages. On a touch screen the link offers a 44px hit area, as every button does.
+
+It takes every [`LinkButton`](#linkbutton) prop (`to`, `variant`, `color`, `size`, `replace`, `state`, `linkComponent`, ...), so it follows the router or the [`LinkComponentProvider`](./primitives.md#linkcomponentprovider). Only the default differs: `variant` is `'ghost'`.
+
+**Storybook:** `Buttons & actions/BackLink` (`Default`, `LinkStyle`, `Rtl`) · **Vue:** none yet
+
+---
+
 ## CopyButton
 
 ![CopyButton](../previews/buttons-actions-copybutton.webp)
@@ -919,6 +941,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)

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

@@ -15,7 +15,7 @@ either can be used alone.
 | --- | --- | --- |
 | <img src="../previews/data-table-filter-lists-datatable.webp" width="96" alt=""> | [DataTable](#datatable) | TanStack Table v9 with sorting, selection, expansion and pagination, client-side or one server page at a time |
 | <img src="../previews/data-table-filter-lists-servertable.webp" width="96" alt=""> | [ServerTable](#servertable) | A server-mode `DataTable` driven by the URL, with the Filter in its top band (a title and a description, or neither): sort, cursor paging, the empty page with a scene, an action and removable chips, one count announced |
-| <img src="../previews/data-table-filter-lists-rowmenu.webp" width="96" alt=""> | [RowMenu](#rowmenu) | A row's "..." button named after its row ("Actions for Ada"), its menu aligned to the end with the destructive item last, a loading state while an action runs, and `rowMenuColumn` to drop both in a table |
+| <img src="../previews/data-table-filter-lists-rowmenu.webp" width="96" alt=""> | [RowMenu](#rowmenu) | A row's "..." button named after its row ("Actions for Ada"), its menu aligned to the end with the destructive item last, a loading state while an action runs, `rowMenuColumn` to drop both in a table, and `useRowMenuFocus` to hand the focus back to a row's button after an action |
 | <img src="../previews/data-table-filter-lists-listempty.webp" width="96" alt=""> | [ListEmpty](#listempty) | A list's empty page: nothing yet, with a scene and an action, or nothing matches and the way out |
 | <img src="../previews/data-table-filter-lists-pagefooter.webp" width="96" alt=""> | [PageFooter](#pagefooter) | The page footer of a feed that is not a table (cards, a news feed) under a FilterBar: the range and Previous / Next as links from the URL's cursor trail, `pageControls="icon"`; no `totalCount` for a feed with no total (no range, Previous / Next only); `hideOnSinglePage` hides it on a single page |
 | <img src="../previews/data-table-filter-lists-datagrid.webp" width="96" alt=""> | [DataGrid](#datagrid) | An editable grid: spreadsheet keys, paste, a fill handle with series, undo, totals, saving with versions and conflicts (lazy ones fetch theirs on "Keep mine"), `onRefuse` for a refused paste or fill, row selection (`enableRowSelection`), and resizable, hideable and reorderable columns (`columnControls`, `columnLayout`, `DataGridColumnsMenu`) |
@@ -1217,6 +1217,7 @@ and `ref`, so it is the child of a `DropdownMenuTrigger asChild`.
 | `loading` (`RowMenuTrigger`, `triggerProps.loading` of `RowMenu`) | `boolean` | `false` | an action chosen from this row's menu is running: `aria-busy`, a spinner in place of the dots (the button keeps its size), and the menu does not open again until it is over. The button stays focusable and keeps the focus. As `Button`'s `loading` |
 | `items` (`RowMenu`) | `{ label, icon?, onSelect?, disabled?, destructive?, id? }[]` | `[]` | the actions; `destructive` ones are drawn in the error colour and moved last, after a separator |
 | `children` (`RowMenu`) | `ReactNode` | — | menu content of your own, above `items` (put a destructive item last yourself); its menu items are 44px high on a coarse pointer too |
+| `rowId` (`RowMenu`) | `string` | — | the row's id, written on the button (`data-row-menu-id`) for `useRowMenuFocus`; `rowMenuColumn` sets it from the table's `getRowId` |
 | `triggerProps` (`RowMenu`) | button props | — | `disabled`, `className`, `data-*` on the button |
 | `open`, `onOpenChange` (`RowMenu`) | as `DropdownMenu` | — | controlled state |
 | `label`, `items`, `menu` (`rowMenuColumn`) | `(row) => string` / `(row) => RowMenuItem[]` / `(row) => ReactNode` | — | the row's name, its actions as data, or its menu content as nodes |
@@ -1233,9 +1234,72 @@ the focus, so the focus does not fall to the page when the menu closes:
 />
 ```
 
-Focus returns to the button when the menu closes, and when a dialog opened from
-an item (a `ConfirmDialog`, a `Dialog`, a `Sheet`) closes: the item is gone by
-then, so the dialog hands the focus back to the menu's button.
+### Handing the focus back to a row
+
+A toast or a dialog opened by an action takes the focus, and when it closes the
+focus is on the page's body. `useRowMenuFocus()` returns a `focusRef` for the
+table and `focusRowMenu(rowId)`, which focuses that row's button once the
+action has settled or the dialog has closed. The row is matched by its id
+(`getRowId`'s, written by `rowMenuColumn`; `rowId` on a bare `RowMenu`) exactly,
+never by its label, so two "Ada" rows are told apart. The focus is
+taken at once, and claimed again for two frames if a dialog's focus restore or
+a toast takes it, so it is safe to call right after the action settles or the
+dialog closes. For those two frames the focus is claimed back to the trigger
+whatever took it, so a deliberate focus move (Tab, or a dialog or toast opened
+right after the call) within them is overridden: call it once the follow-up UI
+is done. It returns `true` when the button was found and holds the focus,
+and `false` when the row is gone (archived) or the button cannot take it
+(disabled, inert); the focus then stays where it is.
+
+```tsx
+import { useMemo } from 'react';
+import {
+  DataTable,
+  rowMenuColumn,
+  toast,
+  useRowMenuFocus,
+} from '@nxgt/material/components';
+
+const { focusRef, focusRowMenu } = useRowMenuFocus();
+
+const columns = useMemo(
+  () => [
+    // …
+    rowMenuColumn<Person>({
+      label: (person) => person.name,
+      items: (person) => [
+        {
+          label: 'Rename',
+          onSelect: async () => {
+            await rename(person.id);
+            toast.success('Renamed');
+            focusRowMenu(person.id);
+          },
+        },
+      ],
+    }),
+  ],
+  [focusRowMenu],
+);
+
+<DataTable focusRef={focusRef} getRowId={(p) => p.id} columns={columns} data={people} />;
+```
+
+`focusRef` scopes the search to that table; without it the whole document is
+searched. For a dialog, [`onCloseAutoFocus`](#focus-after-a-bulk-action) with
+`preventDefault()` is the precise hook if you want to take the focus yourself.
+
+`findRowMenuTrigger(rowId, scope?)` is the lookup the hook uses: it returns the
+row's button (an `HTMLElement`) inside `scope` (default `document`), or `null`.
+Use it instead of the hook when you only need the element (to scroll it into
+view, to measure it) or when the rows are outside a React component.
+
+The focus returns to the button by itself when the menu closes, and when a
+dialog opened from an item (a `ConfirmDialog`, a `Dialog`, a `Sheet`) closes:
+the item is gone by then, so the dialog hands the focus back to the menu's
+button. `useRowMenuFocus` is for the focus that is lost after that: an async
+action that settles later, a toast, a dialog opened later or from elsewhere, or
+a table re-render that remounts the button.
 
 **Storybook:** `Data table, filter & lists/RowMenu`, `Guides/Accessibility/Touch targets/Row menu` · **Vue:** not yet (tracked as a `vue` issue)
 

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/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/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.
 

package/docs/troubleshooting.md

@@ -79,6 +79,8 @@ words in your error.
 
 **Buttons & actions**
 
+- [`useHref() may be used only in the context of a <Router> component` on a `TabsNav`, `SegmentedNav` or a `LinkButton`](#usehref-may-be-used-only-in-the-context-of-a-router-component-on-a-tabsnav-segmentednav-or-a-linkbutton)
+- [A tab switch reloads the route's data, or the default tab shows `?tab=` in the URL](#a-tab-switch-reloads-the-routes-data-or-the-default-tab-shows-tab-in-the-url)
 - [An `ActionCard` inside a button or a link is a button inside a button](#an-actioncard-inside-a-button-or-a-link-is-a-button-inside-a-button)
 - [A `Card` class or a `[data-slot=card]` selector no longer styles an `ActionCard`](#a-card-class-or-a-data-slotcard-selector-no-longer-styles-an-actioncard)
 - [A `[data-slot=button]` selector no longer finds a SplitButton's half, or a class should style the whole split button](#a-data-slotbutton-selector-no-longer-finds-a-splitbuttons-half-or-a-class-should-style-the-whole-split-button)
@@ -1908,6 +1910,30 @@ return <IconButton size="lg" {...rest} />;
 <Button size="xl">Save</Button>
 ```
 
+### `useHref() may be used only in the context of a <Router> component` on a `TabsNav`, `SegmentedNav` or a `LinkButton`
+
+**When:** a `TabsNavLink`, `SegmentedNavItem`, `LinkButton`, `IconLinkButton` or `ResponsiveLinkButton` renders in a test, a story or a tree with no router, and no `LinkComponentProvider`.
+**Why:** without a provider (or a `linkComponent` prop), they render React Router's `Link`, which reads the router's context.
+**Fix:** wrap the tree in your router (`MemoryRouter` in a test or a story), or set a `LinkComponentProvider` once.
+
+```tsx
+<MemoryRouter>
+	<TabsNav aria-label="Account" value="profile">
+		<TabsNavLink to="/profile" value="profile">Profile</TabsNavLink>
+	</TabsNav>
+</MemoryRouter>
+```
+
+### A tab switch reloads the route's data, or the default tab shows `?tab=` in the URL
+
+**When:** a route using `useTabParam` re-runs its loader on every tab click, or the first tab's link carries `?tab=overview`.
+**Why:** a search-param change revalidates the route's loaders unless `shouldRevalidate` says otherwise; and the default tab writes no param unless `explicitDefault` is on.
+**Fix:** export `skipTabChange()` as the route's `shouldRevalidate`, and leave `explicitDefault` off unless another param implies a tab. Parent routes' loaders still revalidate unless they export `skipTabChange` as well.
+
+```tsx
+export const shouldRevalidate = skipTabChange();
+```
+
 ## Feedback
 
 ### An `EmptyState` with no `kind` shows "No Data Found" where it showed "Something Went Wrong"
@@ -2085,9 +2111,22 @@ onClick }`, or a function that calls the `dismiss` it is given): the action
 gives the focus back to where it was before the toast first, then runs. The
 dialog keeps its control, and gives the focus back to that earlier control
 when it closes. A workaround that blurs the button and opens the dialog on
-the next frame can go. A button you render in a function action and that
-opens a dialog without calling `dismiss` is not covered: call `dismiss()`
-before opening the dialog.
+the next frame can go. For a row action's toast, see [The focus lands on the
+page after a row action](#the-focus-lands-on-the-page-after-a-row-action). A
+button you render in a function action and that opens a dialog without calling
+`dismiss` is not covered: call `dismiss()` before opening the dialog.
+
+### The focus lands on the page after a row action
+
+**When:** an item of a `RowMenu` runs an async action, then shows a toast or
+opens a dialog. When they close, `document.activeElement` is `document.body`.
+**Why:** the menu hands the focus back to the row's button when it closes (and
+when a dialog opened from an item closes), but a toast, a later dialog or a
+remounted row takes it afterwards.
+**Fix:** call `focusRowMenu(row.id)` from `useRowMenuFocus()` once the action
+settles, with `focusRef` on the table. It matches the row by id, not by label.
+See "Handing the focus back to a row" in
+[RowMenu](components/data-table-filter-and-lists.md#handing-the-focus-back-to-a-row).
 
 ### A `ConfirmationDialog` reopened with new content blocks clicks
 

package/lib/components/components.css

@@ -122,6 +122,8 @@
 @import "./ui/primitives/accordion/accordion.css";
 @import "./ui/primitives/accordion/accordion-surfaces.css";
 @import "./ui/primitives/collapsible/collapsible.css";
+/* TabsNav in forced colours (the current link's mark). */
+@import "./ui/primitives/tabs/tabs-nav-forced.css";
 /* ToggleGroup: shared rules, then one file per variant. */
 @import "./ui/primitives/toggle-group/toggle-group.css";
 @import "./ui/primitives/toggle-group/toggle-group-connected.css";

package/lib/components/ui/layout/app-shell/activity-backdrop.css

@@ -149,9 +149,10 @@
 		backdrop-filter: blur(var(--nxgt-backdrop-blur));
 	}
 
-	/* Tabs: the strip is a band, its top corners rounded. (The segmented look
-	 * has its own track.) */
-	[data-slot="activity-layout"][data-backdrop] [data-slot="tabs-list"] {
+	/* Tabs and route tabs (`TabsNav`): the strip is a band, its top corners
+	 * rounded. (The segmented look has its own track.) */
+	[data-slot="activity-layout"][data-backdrop]
+	:is([data-slot="tabs-list"], [data-slot="tabs-nav"]) {
 		border-start-start-radius: var(--radius);
 		border-start-end-radius: var(--radius);
 		background: var(--nxgt-backdrop-fill-nav);