@nxgt/material 3.62.0 → 3.63.0

package/dist/use-return-focus-1ZIchrBM.js

@@ -0,0 +1,269 @@
+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 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";
+import { useCallback as y, useContext as te, useRef as b } from "react";
+import { Fragment as x, jsx as S } from "react/jsx-runtime";
+import { forwardEscape as C, keepListEscape as w } from "@nxgt/material-core/escape-forward";
+//#region ../../node_modules/@radix-ui/react-dialog/dist/index.mjs
+var T = Object.defineProperty, E = (e, t) => T(e, "name", {
+	value: t,
+	configurable: !0
+}), D = "Dialog", [O, ne] = r(D), [re, k] = O(D), A = /* @__PURE__ */ E((e) => {
+	let { __scopeDialog: t, children: r, open: i, defaultOpen: a, onOpenChange: o, modal: c = !0 } = e, l = v.useRef(null), u = v.useRef(null), [d, f] = n({
+		prop: i,
+		defaultProp: a ?? !1,
+		onChange: o,
+		caller: D
+	}), [p, m] = v.useState(0), [h, g] = v.useState(0);
+	return /* @__PURE__ */ S(re, {
+		scope: t,
+		triggerRef: l,
+		contentRef: u,
+		contentId: s(),
+		titleId: s(),
+		descriptionId: s(),
+		titlePresent: p > 0,
+		descriptionPresent: h > 0,
+		setTitleCount: m,
+		setDescriptionCount: g,
+		open: d,
+		onOpenChange: f,
+		onOpenToggle: v.useCallback(() => f((e) => !e), [f]),
+		modal: c,
+		children: r
+	});
+}, "Dialog"), j = "DialogTrigger", M = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(t, n) {
+	let { __scopeDialog: r, ...i } = t, o = k(j, r), s = e(n, o.triggerRef);
+	return /* @__PURE__ */ S(a.button, {
+		type: "button",
+		"aria-haspopup": "dialog",
+		"aria-expanded": o.open,
+		"aria-controls": o.open ? o.contentId : void 0,
+		"data-state": Z(o.open),
+		...i,
+		ref: s,
+		onClick: c(t.onClick, o.onOpenToggle)
+	});
+}, "DialogTrigger")), N = "DialogPortal", [P, F] = O(N, { forceMount: void 0 }), I = /* @__PURE__ */ E((e) => {
+	let { __scopeDialog: t, forceMount: n, children: r, container: a } = e, o = k(N, t);
+	return /* @__PURE__ */ S(P, {
+		scope: t,
+		forceMount: n,
+		children: v.Children.map(r, (e) => /* @__PURE__ */ S(i, {
+			present: n || o.open,
+			children: /* @__PURE__ */ S(u, {
+				asChild: !0,
+				container: a,
+				children: e
+			})
+		}))
+	});
+}, "DialogPortal"), L = "DialogOverlay", R = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let n = F(L, e.__scopeDialog), { forceMount: r = n.forceMount, ...a } = e, o = k(L, e.__scopeDialog);
+	return o.modal ? /* @__PURE__ */ S(i, {
+		present: r || o.open,
+		children: /* @__PURE__ */ S(B, {
+			...a,
+			ref: t
+		})
+	}) : null;
+}, "DialogOverlay")), z = t("DialogOverlay.RemoveScroll"), B = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(t, n) {
+	let { __scopeDialog: r, ...i } = t, o = k(L, r), s = e(n, d());
+	return /* @__PURE__ */ S(ee, {
+		as: z,
+		allowPinchZoom: !0,
+		shards: [o.contentRef],
+		children: /* @__PURE__ */ S(a.div, {
+			"data-state": Z(o.open),
+			...i,
+			ref: s,
+			style: {
+				pointerEvents: "auto",
+				...i.style
+			}
+		})
+	});
+}, "DialogOverlayImpl")), V = "DialogContent", H = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let n = F(V, e.__scopeDialog), { forceMount: r = n.forceMount, ...a } = e, o = k(V, e.__scopeDialog);
+	return /* @__PURE__ */ S(i, {
+		present: r || o.open,
+		children: o.modal ? /* @__PURE__ */ S(U, {
+			...a,
+			ref: t
+		}) : /* @__PURE__ */ S(W, {
+			...a,
+			ref: t
+		})
+	});
+}, "DialogContent")), U = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(t, n) {
+	let r = k(V, t.__scopeDialog), i = v.useRef(null), a = e(n, r.contentRef, i);
+	return v.useEffect(() => {
+		let e = i.current;
+		if (e) return h(e);
+	}, []), /* @__PURE__ */ S(G, {
+		...t,
+		ref: a,
+		trapFocus: r.open,
+		disableOutsidePointerEvents: r.open,
+		onCloseAutoFocus: c(t.onCloseAutoFocus, (e) => {
+			e.preventDefault(), r.triggerRef.current?.focus();
+		}),
+		onPointerDownOutside: c(t.onPointerDownOutside, (e) => {
+			let t = e.detail.originalEvent, n = t.button === 0 && t.ctrlKey === !0;
+			(t.button === 2 || n) && e.preventDefault();
+		}),
+		onFocusOutside: c(t.onFocusOutside, (e) => e.preventDefault())
+	});
+}, "DialogContentModal")), W = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let n = k(V, e.__scopeDialog), r = v.useRef(!1), i = v.useRef(!1);
+	return /* @__PURE__ */ S(G, {
+		...e,
+		ref: t,
+		trapFocus: !1,
+		disableOutsidePointerEvents: !1,
+		onCloseAutoFocus: (t) => {
+			e.onCloseAutoFocus?.(t), t.defaultPrevented || (r.current || n.triggerRef.current?.focus(), t.preventDefault()), r.current = !1, i.current = !1;
+		},
+		onInteractOutside: (t) => {
+			e.onInteractOutside?.(t), t.defaultPrevented || (r.current = !0, t.detail.originalEvent.type === "pointerdown" && (i.current = !0));
+			let a = t.target;
+			n.triggerRef.current?.contains(a) && t.preventDefault(), t.detail.originalEvent.type === "focusin" && i.current && t.preventDefault();
+		}
+	});
+}, "DialogContentNonModal")), G = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let { __scopeDialog: n, trapFocus: r, onOpenAutoFocus: i, onCloseAutoFocus: a, ...o } = e, s = k(V, n);
+	return f(), /* @__PURE__ */ S(x, { children: /* @__PURE__ */ S(m, {
+		asChild: !0,
+		loop: !0,
+		trapped: r,
+		onMountAutoFocus: i,
+		onUnmountAutoFocus: a,
+		children: /* @__PURE__ */ S(l, {
+			role: "dialog",
+			id: s.contentId,
+			"aria-describedby": s.descriptionPresent ? s.descriptionId : void 0,
+			"aria-labelledby": s.titlePresent ? s.titleId : void 0,
+			"data-state": Z(s.open),
+			...o,
+			ref: t,
+			deferPointerDownOutside: !0,
+			onDismiss: () => s.onOpenChange(!1)
+		})
+	}) });
+}, "DialogContentImpl")), K = "DialogTitle", q = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let { __scopeDialog: n, ...r } = e, i = k(K, n), { setTitleCount: s } = i;
+	return o(() => (s((e) => e + 1), () => s((e) => e - 1)), [s]), /* @__PURE__ */ S(a.h2, {
+		id: i.titleId,
+		...r,
+		ref: t
+	});
+}, "DialogTitle")), J = "DialogDescription", Y = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let { __scopeDialog: n, ...r } = e, i = k(J, n), { setDescriptionCount: s } = i;
+	return o(() => (s((e) => e + 1), () => s((e) => e - 1)), [s]), /* @__PURE__ */ S(a.p, {
+		id: i.descriptionId,
+		...r,
+		ref: t
+	});
+}, "DialogDescription")), X = "DialogClose", ie = /* @__PURE__ */ v.forwardRef(/* @__PURE__ */ E(function(e, t) {
+	let { __scopeDialog: n, ...r } = e, i = k(X, n);
+	return /* @__PURE__ */ S(a.button, {
+		type: "button",
+		...r,
+		ref: t,
+		onClick: c(e.onClick, () => i.onOpenChange(!1))
+	});
+}, "DialogClose"));
+function Z(e) {
+	return e ? "open" : "closed";
+}
+E(Z, "getState");
+//#endregion
+//#region lib/components/ui/overlays/dialog/use-escape-forward.ts
+function ae(t, n) {
+	let r = b(null);
+	return {
+		ref: e(r, n),
+		onEscapeKeyDown(e) {
+			w(e), _(e, r.current), t?.(e), C(r.current, e);
+		}
+	};
+}
+//#endregion
+//#region lib/components/ui/overlays/dialog/use-overlay-order.ts
+function oe(t) {
+	let n = b(null);
+	return {
+		overlayRef: y((e) => {
+			let t = n.current;
+			!e || !t?.isConnected || t.parentNode === e.parentNode && t.compareDocumentPosition(e) & Node.DOCUMENT_POSITION_FOLLOWING && t.before(e);
+		}, []),
+		contentRef: e(n, t)
+	};
+}
+//#endregion
+//#region lib/components/ui/overlays/dialog/use-modal-content.ts
+function se({ ref: e, onEscapeKeyDown: t, ...n }, r) {
+	let i = te(g) ?? !0, a = ae(t, p(r ?? i, e)), o = oe(a.ref);
+	return {
+		ref: o.contentRef,
+		overlayRef: o.overlayRef,
+		onEscapeKeyDown: a.onEscapeKeyDown,
+		outside: {
+			onPointerDownOutside: Q(n.onPointerDownOutside),
+			onFocusOutside: Q(n.onFocusOutside),
+			onInteractOutside: Q(n.onInteractOutside)
+		}
+	};
+}
+function Q(e) {
+	return (t) => {
+		e?.(t);
+		let n = t.target;
+		n instanceof Element && n.closest("[data-sonner-toaster]") && t.preventDefault();
+	};
+}
+//#endregion
+//#region lib/components/ui/overlays/dialog/menu-trigger.ts
+var $ = "[role=\"menu\"]", ce = 8;
+function le(e) {
+	let t = null, n = e?.closest($) ?? null;
+	for (let e = 0; n && e < ce; e++) {
+		let e = n.getAttribute("data-return-focus"), r = e ? n.ownerDocument.getElementById(e) : null;
+		if (r) return r;
+		let [i] = (n.getAttribute("aria-labelledby") ?? "").split(/\s+/), a = i ? n.ownerDocument.getElementById(i) : null;
+		if (!a) break;
+		t = a, n = a.closest($);
+	}
+	return t;
+}
+//#endregion
+//#region lib/components/ui/overlays/dialog/use-return-focus.ts
+var ue = "button:not([disabled]), input:not([disabled]):not([type=\"hidden\"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"]), [contenteditable=\"true\"]";
+function de(e) {
+	([...e.querySelectorAll(ue)].find((e) => e.tabIndex >= 0 && e.getClientRects().length > 0) ?? e).focus({ preventScroll: !0 });
+}
+function fe(e, { focusFallback: t = !1 } = {}) {
+	let n = b(null), r = b(null);
+	return {
+		onOpenAutoFocus(i) {
+			let a = document.activeElement;
+			n.current = a instanceof HTMLElement && a !== document.body ? a : null, r.current = le(n.current), e.onOpenAutoFocus?.(i);
+			let o = i.target;
+			!t || i.defaultPrevented || !(o instanceof HTMLElement) || queueMicrotask(() => {
+				o.isConnected && !o.contains(document.activeElement) && de(o);
+			});
+		},
+		onCloseAutoFocus(t) {
+			e.onCloseAutoFocus?.(t);
+			let i = n.current?.isConnected ? n.current : r.current;
+			if (n.current = null, r.current = null, t.defaultPrevented || !i?.isConnected) return;
+			let a = document.activeElement;
+			a && a !== document.body || (t.preventDefault(), i.focus());
+		}
+	};
+}
+//#endregion
+export { H as a, I as c, ne as d, ie as i, q as l, se as n, Y as o, A as r, R as s, fe as t, M as u };

package/docs/components/feedback-and-status.md

@@ -12,6 +12,7 @@ centre.
 | <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
 | <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
 | <img src="../previews/feedback-status-stepupdialog.webp" width="96" alt=""> | [StepUpDialog](#stepupdialog) | "Confirm it's you": a dialog that asks for a one-time code, driven by props |
+| <img src="../previews/feedback-status-unsaveddialog.webp" width="96" alt=""> | [UnsavedDialog](#unsaveddialog) | "Leave without saving?": a destructive confirm with Stay focused, used by the unsaved-changes guards |
 | <img src="../previews/feedback-status-emptystate.webp" width="96" alt=""> | [EmptyState](#emptystate) | Illustration, title, description and action, by kind (empty, search, not-found, unauthorized) |
 | <img src="../previews/feedback-status-pageloadfailed.webp" width="96" alt=""> | [PageLoadFailed](#pageloadfailed) | An empty state for a page opened at a cursor that failed, with a link back to the start |
 | <img src="../previews/feedback-status-errorstate.webp" width="96" alt=""> | [ErrorState](#errorstate) | Failure block with Retry and technical details |
@@ -468,6 +469,28 @@ dialog by `getByRole('dialog', { name: "Confirm it's you" })` and the lock by
 
 ---
 
+## UnsavedDialog
+
+![UnsavedDialog](../previews/feedback-status-unsaveddialog.webp)
+
+"Leave without saving?": a destructive `ConfirmDialog` whose default focus is **Stay**, so Enter keeps the work. [`useUnsavedGuard` and `useDiscardGuard`](../guides/helpers.md#useunsavedguard) render it; use it directly for a guard of your own.
+
+```tsx
+import { UnsavedDialog } from '@nxgt/material/components';
+
+<UnsavedDialog open={open} onOpenChange={setOpen} onLeave={() => navigate('/items')} />;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `open`, `onOpenChange` | `boolean`, `(open) => void` | — | controlled state |
+| `onLeave` | `() => void \| Promise<void>` | — | runs on "Leave"; the dialog closes after it |
+| `title`, `description`, `stayLabel`, `leaveLabel` | `string` | translated | texts (`material.unsaved.*`) |
+
+**Storybook:** `Feedback & status/UnsavedDialog` · **Vue:** not yet (`vue` issue #2019)
+
+---
+
 ## EmptyState
 
 ![EmptyState](../previews/feedback-status-emptystate.webp)

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

@@ -304,9 +304,10 @@ icon-only entry (no label) falls back to its `aria-label`:
 | `withToggleIcon` | `boolean` | `false` | built-in expand / collapse button, shown on hover or while focus is inside the sidebar, named "Toggle sidebar" (`material.sidebar.toggle`) with `aria-expanded` |
 
 The selected entry's shape (`--nxgt-item-radius`, 6px, in the expanded row; the collapsed rail keeps its pill icon), its hover and its label and icon colour are the
-tokens `--sidebar-active`, `--sidebar-active-hover` and
-`--sidebar-active-foreground` (light and dark); a theme sets them to recolour
-the rail. See [Theming](../guides/theming.md#the-active-entry-of-the-sidebar-and-the-rail).
+tokens `--sidebar-active`, `--sidebar-active-hover`,
+`--sidebar-active-foreground` and `--sidebar-active-edge` (the start bar,
+defaulting to the foreground), in light and dark; a theme sets any of them to
+recolour the rail. See [Theming](../guides/theming.md#the-active-entry-of-the-sidebar-and-the-rail).
 
 **Storybook:** `Navigation & layout/Sidebar` · **Vue:** `Sidebar` (same parts)
 

package/docs/components/rich-widgets.md

@@ -2434,7 +2434,7 @@ French bundle — see [i18n](../guides/i18n.md).
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `questions` | `Question[]` | — | `kind`: `'choice'`, `'multi'`, `'boolean'`, `'text'` or `'number'` |
+| `questions` | `Question[]` | — | `kind`: `'choice'`, `'multi'`, `'boolean'`, `'text'` or `'number'` (`'open'` and `'code'` are for `QuestionCard`: `Quiz` grades in the browser against `correct`, so an `open` or `code` question counts as wrong there; use `QuestionCard` on its own and pass the server's `verdict`) |
 | `mode` | `'exam' \| 'practice'` | `'exam'` | verdicts at the end, or after each Check |
 | `layout` | `'paged' \| 'list'` | `'paged'` | one question at a time, or all on one page |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | spacing and type size |
@@ -2451,8 +2451,44 @@ French bundle — see [i18n](../guides/i18n.md).
 | `QuestionCard` `points` / `feedback` | `{ awarded, possible }` / `string` | — | points earned and a grader's remark, in the verdict banner (with `verdict`) |
 | `Question` `media` | `{ src, alt?, kind?, type?, name? }` | — | an image (default), audio (`kind: 'audio'` or `type: 'audio/*'`, an `AudioPlayer`) or a document link (any other `type`, a `FilePreview`); `name` (else `alt`) is the text alternative |
 | `QuestionCard` `value` / `onValueChange` | `QuestionAnswer` | — | controlled answer |
+| `Question` `kind: 'open'` | `maxLength?` | — | a multi-line answer in a textarea named by the prompt; a counter shows while editable when `maxLength` is set. No `correct`: pass the grader's `verdict` |
+| `Question` `kind: 'code'` | `language?`, `maxLength?` | — | source code: drawn by `renderCode`, else a monospace textarea |
+| `QuestionCard` `renderCode` | `(field: QuestionCodeField) => ReactNode` | — | the code field of a `code` question; `field` is `{ value, onChange, label, labelledBy, language, maxLength, readOnly, disabled }`. Keeps Monaco out of the card's bundle |
+| `QuestionCard` `readOnly` / `busy` | `boolean` | `false` | `readOnly`: an answer already submitted, shown without the revealed marks; `busy`: read-only and `aria-busy` while it is saved; every kind honours both |
+| new strings | `material.education.kind-open`, `kind-code`, `code-placeholder` | — | English fallbacks and a French bundle |
 | `QuestionCard` `variant` / `density` / `showShortcuts` / `number` / `showFeedback` | — | `'card'`, `'comfortable'`, `false`, —, `true` | framed or plain, spacing, key badges, "Question 2", the verdict banner |
 
+An open answer and a code answer, with the code editor from its own subpath
+(it is client-only, so load it lazily in an SSR app):
+
+```tsx
+import { CodeEditor } from '@nxgt/material/code-editor';
+
+<QuestionCard
+  number={3}
+  question={{ id: 'q3', kind: 'open', prompt: 'Explain X', maxLength: 20000 }}
+  value={text}
+  onValueChange={setText}
+  busy={saving}
+/>
+
+<QuestionCard
+  question={{ id: 'q4', kind: 'code', prompt: 'Add two numbers', language: 'python' }}
+  value={source}
+  onValueChange={setSource}
+  renderCode={(f) => (
+    <CodeEditor
+      label={f.label}
+      language={f.language}
+      value={f.value}
+      onChange={(v) => f.onChange(v ?? '')}
+      readOnly={f.readOnly}
+      disabled={f.disabled}
+    />
+  )}
+/>
+```
+
 A server-graded answer, shown as given (no comparison in the browser):
 
 ```tsx
@@ -2467,6 +2503,42 @@ A server-graded answer, shown as given (no comparison in the browser):
 
 **Storybook:** `Rich widgets/Quiz`, `Rich widgets/QuestionCard` · **Vue:** `Quiz`, `QuestionCard` (the modes, results, number kind and shortcuts are React only for now, #890)
 
+### QuestionMediaView
+
+A question's file, picked by its type, with an error state for links that
+expire. It takes the shape of `Question.media` plus `size`, so
+`<QuestionMediaView media={question.media} />` works. It is named
+`QuestionMediaView` because `QuestionMedia` is the type of `Question.media`;
+`QuestionCard` still draws its own `media` without an error state and will
+reuse this view (#2021).
+
+```tsx
+import { QuestionMediaView } from '@nxgt/material/components';
+
+<QuestionMediaView
+  media={{ src, type: 'audio/mpeg', size: 4096 }}
+  onReload={refetch}
+  reloading={isRefetching}
+/>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `media` | `QuestionMedia & { size? }` | — | `kind`, else `type` (case-insensitive): `image/*` (also with no type) is an `<img>` named by `name` or `alt`, else "Image for this question"; `audio/*` an `AudioPlayer`; `video/*` a `<video controls>`; any other type a document |
+| `documents` | `'link' \| 'preview'` | `'link'` | `link`: an open-in-a-new-tab button showing the type and `size`, which fetches nothing (no `connect-src` or bucket CORS); `preview`: a `FilePreview`, which fetches the file |
+| `captions` | `{ src, srclang, label, default? }[]` | — | caption tracks of a video. A video with speech needs captions or a transcript next to it |
+| `onReload` | `() => void` | — | the Reload button of the error alert, shown when an image, audio or video fails to load; without it the alert has no button |
+| `reloading` | `boolean` | `false` | the Reload button is busy while the fresh link is fetched |
+
+A failure is forgotten when `src` changes, so reloading a presigned link and
+passing the new `src` brings the file back, and focus moves to the file when it
+was on the Reload button (the wrapper, `data-slot="question-media"`, stays
+mounted). A reload that returns the same `src` keeps the error. A document link cannot
+report an expired link; reload it from your own signal. There is no
+`kind: 'video'`: a video is picked by its `type` (`video/*`).
+
+**Storybook:** `Rich widgets/QuestionMediaView` · **Vue:** none (the `vue` issue #2020)
+
 ### QuestionNavigator
 
 The numbered questions of a quiz or exam player: jump to one, see the current

package/docs/guides/helpers.md

@@ -140,6 +140,7 @@ Vue: the Redux helpers are Pinia store factories: `defineLocalStore`
 | `useCountdown(duration, { paused?, onExpire?, key? })` | Seconds left of `duration` (the clock `CountdownTimer` draws), for a button or a message that waits: ticks on the client only, `duration` on the server and first render. A new `duration` **or a new `key`** starts over, so the same `retryAfter` twice restarts it. See [below](#usecountdown). |
 | `useSubmitOnce(busy?)` | One submit in flight: wraps a submit handler so a double click or a second Enter is dropped until the request ends (the handler's promise, or `busy` back to false). See [below](#usesubmitonce). |
 | `useDrafts<T>(storageKey, { serialize?, parse?, storage? })`, `clearDrafts(storageKey, storage?)` | Unsent values kept by key in `sessionStorage`: `{ get, set, drop, clear, keys, loaded }`. Read after the first render (no hydration mismatch), storage errors swallowed, `drop(key)` once saved; `clearDrafts` empties a store key without a hook (sign-out). See [below](#usedrafts). |
+| `useUnsavedGuard(dirty, { block, … })`, `useDiscardGuard(dirty)`, `useReactRouterBlock` | Stop losing a dirty form: a "Leave without saving?" dialog on in-app navigation and on closing a dialog form, plus the browser's own `beforeunload` prompt. See [below](#useunsavedguard). |
 | `createSubmitGuard()`, `busySettler(guard)` | The framework-free guard behind `useSubmitOnce` (`@nxgt/material-core/submit-guard`): `{ once(run, { settleSync? }), settle(run?), pendingRun() }`, and the function that settles it from a busy flag. |
 
 ```tsx
@@ -350,6 +351,68 @@ export function Answer({ save }: { save: (text: string) => Promise<void> }) {
 
 Storybook: `Guides/Hooks/useDrafts` (remount restores, `drop`, key change).
 
+### `useUnsavedGuard`
+
+Blocks in-app navigation while a form is dirty (an `UnsavedDialog`: "Leave
+without saving?", **Stay** focused so Enter keeps the work) and, while dirty,
+asks the browser to confirm closing or reloading the tab. The core is
+router-agnostic: the router comes in through a `block` adapter, a hook that
+takes `shouldBlock({ currentLocation, nextLocation })` and returns
+`{ state, proceed, reset }`. `useReactRouterBlock` (React Router's
+`useBlocker`) is the ready one. It needs a data router: under `<BrowserRouter>`
+it throws, so use `createBrowserRouter` + `RouterProvider`.
+
+```tsx
+import { useUnsavedGuard, useReactRouterBlock } from '@nxgt/material/hooks';
+
+const { release, dialog } = useUnsavedGuard(form.formState.isDirty, {
+  block: useReactRouterBlock,
+});
+async function onSubmit(values: Values) {
+  await save(values);
+  release(); // synchronous: the navigation below is not blocked
+  navigate('/items');
+}
+return <form onSubmit={form.handleSubmit(onSubmit)}>{/* fields */}{dialog}</form>;
+```
+
+| Option | Effect |
+| --- | --- |
+| `block` | the router adapter (required) |
+| `leaves(current, next)` | what counts as leaving; default: the pathname **or the query string** differs (a filter or period param remounts most pages). A hash-only change is never a leave |
+| `ignoreSearch` | only a pathname change counts: for a multi-step form whose steps are `?step=2` |
+| `onBlock()` | `boolean \| Promise<boolean>` run before the dialog: resolve `true` when nothing is left to lose (pending saves flushed) and the navigation goes through silently; `false` or a throw asks |
+| `title`, `description`, `stayLabel`, `leaveLabel` | the dialog's texts (`material.unsaved.*`, en and fr) |
+
+- **`dirty` is a boolean or a function.** A function, such as
+  `() => grid.hasPendingChanges()`, is read when the navigation or the unload
+  happens, so a keystroke just before the click is not missed.
+- **`release()`** is one-shot: the next navigation that really leaves (a
+  hash-only change, or a query change under `ignoreSearch`, does not count)
+  passes, and the tab unload prompt stays quiet until then; the guard then
+  re-arms by itself. A release no navigation consumed expires when the current
+  task ends, so call it right before `navigate()`; a later edit is guarded
+  again. A boolean `dirty` going true, false, true between `release()` and
+  `navigate()` re-arms it too. A submit on the same page is not a navigation
+  and is never blocked.
+- **Stay** resets the blocker; **Leave** proceeds.
+- `isLeaving(current, next, { ignoreSearch? })` and
+  `shouldBlockNavigation(…)` are the pure comparisons, for your own predicate
+  or a test.
+- **Another router.** Write the adapter in a few lines, for example
+  `const useMyBlock: BlockAdapter = (shouldBlock) => { const b = useMyRouterBlocker({ shouldBlockFn: ({ current, next }) => shouldBlock({ currentLocation: current.location, nextLocation: next.location }) }); return { state: b.status, proceed: b.proceed, reset: b.reset }; }`.
+- **A one-time secret** (shown once, never saved) does not fit a dialog: ask
+  for an explicit "I saved them" step and call `release()` after it.
+
+`useDiscardGuard(dirty)` is the twin for a form inside a dialog or a sheet:
+it returns `{ close(action), dialog }`; route the close button, Escape and the
+overlay click through `close(() => setOpen(false))` and it runs `action` at once
+when clean, after **Leave** when dirty. Compare with [`useDrafts`](#usedrafts):
+drafts keep what was typed, the guard asks before it is dropped; they combine.
+
+Storybook: `Guides/Hooks/useUnsavedGuard` (leave, stay, release after save,
+query change, flush, dialog form). No Vue twin yet (`vue` issue #2019).
+
 ## `@nxgt/material/i18n`
 
 | Export | What it does |

package/docs/guides/theming.md

@@ -620,15 +620,16 @@ descendant of it: an element that reads `--nxgt-tone-container` needs its own
 ## The active entry of the sidebar and the rail
 
 The selected `SidebarMenuItem` (and so the `AppSidebar` and `ActivityLayout`
-rail and menu sheet) is drawn with three tokens, in light and in dark:
+rail and menu sheet) is drawn with four tokens, in light and in dark:
 
 | Token | Tailwind | Default, light | Default, dark |
 | --- | --- | --- | --- |
 | `--sidebar-active` | `bg-sidebar-active` | primary at 15 % | primary at 30 % |
 | `--sidebar-active-hover` | `bg-sidebar-active-hover` | primary at 20 % | primary at 35 % |
 | `--sidebar-active-foreground` | `text-sidebar-active-foreground` | `oklch(from var(--primary) calc(l * 0.85) c h)`, 4.5:1 or more on the pill for every theme preset | `oklch(from var(--primary) 0.72 0.15 h)`, 6.3:1 or more on the pill |
+| `--sidebar-active-edge` | `bg-sidebar-active-edge` | the value of `--sidebar-active-foreground` | the value of `--sidebar-active-foreground` |
 
-The pill is the icon's (collapsed rail) or the whole row (expanded), a pill in the collapsed rail and, in the expanded row, an `--nxgt-item-radius` (6px) shape that carries the 3px start bar every chosen row has, drawn in `--sidebar-active-foreground` (a `Highlight` bar in forced colours); the
+The pill is the icon's (collapsed rail) or the whole row (expanded), a pill in the collapsed rail and, in the expanded row, an `--nxgt-item-radius` (6px) shape that carries the 3px start bar every chosen row has, drawn in `--sidebar-active-edge` (a `Highlight` bar in forced colours); the
 foreground is the label and the icon, whose duotone layers both follow it (in
 dark too: the icon of `AppSidebar` is the lifted lavender like its label). The
 label is read on the pill (expanded) or on the sidebar (collapsed rail); the
@@ -639,9 +640,18 @@ itself in light and dark, as both the light darkening and the dark lift need
 
 The defaults are derived where the entry is drawn, from the `--primary` it
 sits under, so a `--primary` set on a wrapper recolours the rail inside it.
-The three tokens are not declared on `:root`: setting one replaces its
+The four tokens are not declared on `:root`: setting one replaces its
 default wherever it is set.
 
+`--sidebar-active-edge` recolours the start bar alone; unset, the bar follows
+the foreground:
+
+```css
+:root {
+  --sidebar-active-edge: oklch(0.8 0.15 90);
+}
+```
+
 Set them after importing the stylesheet, under the same selectors as the
 theme, for example a rail in the `maths` colour:
 

package/lib/components/ui/layout/sidebar/sidebar-tokens.css

@@ -8,7 +8,9 @@
 	 * follow a `--primary` set below :root. To theme the rail set
 	 * `--sidebar-active`, `--sidebar-active-hover` and
 	 * `--sidebar-active-foreground` (all three, or the first two and the
-	 * foreground); the derived colours are not declared here, on purpose. */
+	 * foreground); the derived colours are not declared here, on purpose.
+	 * `--sidebar-active-edge` recolours the start bar alone; unset, the bar is
+	 * the foreground (`--sidebar-active-edge: gold` changes nothing else). */
 	--nxgt-sidebar-active-share: 15%;
 	/* Light: primary itself reads 4.5:1 on the page but not on its own 15 % pill
 	 * for every preset (corail 3.7:1), so the label is primary darkened to 85 %
@@ -71,4 +73,14 @@
 				var(--nxgt-sidebar-active-c, c) h
 		)
 	);
+	--color-sidebar-active-edge: var(
+		--sidebar-active-edge,
+		var(
+			--sidebar-active-foreground,
+			oklch(
+				from var(--primary) var(--nxgt-sidebar-active-l, l)
+					var(--nxgt-sidebar-active-c, c) h
+			)
+		)
+	);
 }

package/package.json

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