@nxgt/material 3.62.0 → 3.64.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/buttons-and-actions.md

@@ -975,7 +975,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.
+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.
 
 ```tsx
 import { LoadMoreFooter } from '@nxgt/material/components';
@@ -994,7 +994,7 @@ import { LoadMoreFooter } from '@nxgt/material/components';
 | --- | --- | --- | --- |
 | `shown` | `number` | — | items shown now |
 | `total` | `number` | — | items in all; leave it out when unknown, the line then reads "20 shown" |
-| `hasMore` | `boolean` | — | `false` renders nothing, not even the count |
+| `hasMore` | `boolean` | — | `false` renders nothing, not even the count, unless a next page existed before: the status line then stays after the last page (`showCount={false}` drops it) |
 | `loading` | `boolean` | `false` | the button (or the retry) spins and ignores clicks |
 | `failed` | `boolean` | `false` | an error alert with a tonal "Try again" replaces the button |
 | `showCount` | `boolean` | `true` | `false` hides the "Showing N of M" line (keep it for a list whose header already announces the count in its own `role="status"`); the button and the failed alert stay |

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

@@ -1027,6 +1027,11 @@ Its props are `ServerTableProps<T>`; `filter` is a `ServerTableFilter`,
 | `actions` | `ReactNode` | — | the page's actions, at the band's end |
 | `bandDensity` | `'comfortable' \| 'compact'` | `'comfortable'` | (the same prop as [`Filter`](#a-compact-band-for-a-list-inside-a-page-section)'s bar) `'compact'` halves the room above the band (16px to 8px) and under it (12px to 6px), for a list under a sticky app bar and a breadcrumb; the controls keep their size (the Filter's own `density` is the controls') |
 | `pageControls` | `'labelled' \| 'icon'` | `'labelled'` | the footer's Previous / Next: `'icon'` is icon-only, with a tooltip and the names "Previous page" / "Next page" (`DataTable`'s default is unchanged); on a coarse pointer the icon controls are 44x44 boxes (still painted 32px) |
+| `footer` | `'paging' \| 'load-more'` | `'paging'` | `'load-more'` replaces Previous / Next with [`LoadMoreFooter`](./feedback-and-status.md): "Showing N of M" (`rows.length` of `totalCount`), the load button while `pageInfo.hasNextPage`, a failed alert with a retry. The page keeps the rows loaded so far in `rows` and fetches the next itself: the cursor params are not used. The selection count stays; `hideOnSinglePage` still hides the footer |
+| `onLoadMore` | `() => void` | — | with `footer="load-more"` (required): fetches the next page and appends it to `rows`; the retry of a failed page calls it too |
+| `isLoadingMore` | `boolean` | `false` | with `footer="load-more"`: the next page is being fetched, the button spins and ignores clicks |
+| `loadMoreFailed` | `boolean` | `false` | with `footer="load-more"`: the next page failed, an alert with "Try again" replaces the button, the rows stay |
+| `loadMoreLabel` | `string` | "Load more" | with `footer="load-more"`: the button's label |
 | `hideOnSinglePage` | `boolean` | `false` | hides the footer's range and Previous / Next when the result is one page (no previous, no next), in the table, cards and tiles layouts; the count is still announced by the live region but no longer shown, so put it in `description` or keep the footer. With `bulkActions` the footer stays for "N rows selected", without its pager |
 | `bandActions` | `'stacked' \| 'inline'` | `'stacked'` | with `filter`, where `actions` sit below 768px: `'stacked'` gives them a row above the search; `'inline'` keeps them on the search's row (the search takes the room left), for a lone icon action such as a "+". An action wider than 3.5rem wraps under the search. From 768px both are the same. With a cards or tiles list on a phone, neither applies: [the two-row header](#the-phone-header-of-a-list-in-cards-or-tiles) puts the actions on its second row |
 | `filterRef` | `Ref<ServerTableFilterHandle>` | — | with `filter`: `filterRef.current.focus()` focuses the Filter's first control, the search, else the first quick filter, "Add filter" or "Filters (N)" the width shows |
@@ -1830,6 +1835,97 @@ its lock only. The words are `material.filter.default.*`.
 <ServerTable filter={{ model: EVENT_FILTERS, defaults: { mine: ['1'] } }} {...table} />
 ```
 
+#### Load more instead of paging
+
+A catalogue or a history that grows keeps its rows and asks for the next page
+(`footer="load-more"`). The page owns the accumulated rows: any change of
+`params` (a search, a filter chip, a sort) is a new query, which **drops the
+rows, the failure and any request still in flight, and starts again with the
+first page**; `onLoadMore` **appends only the next page**.
+
+```tsx
+function Quizzes() {
+  const [params, setParams] = useSearchParams();
+  const query = params.toString();
+  const [rows, setRows] = useState<Quiz[]>([]);
+  const [page, setPage] = useState({ cursor: null as string | null, hasNext: false, total: 0 });
+  const [isLoadingMore, setLoadingMore] = useState(false);
+  const [failed, setFailed] = useState(false);
+  // Bumped by every new query: an answer of an older one is dropped.
+  const generation = useRef(0);
+
+  useEffect(() => {
+    const mine = ++generation.current;
+    setRows([]); setFailed(false); setLoadingMore(false);
+    fetchQuizzes(new URLSearchParams(query), null).then((first) => {
+      if (mine !== generation.current) return;
+      setRows(first.nodes);
+      setPage({ cursor: first.endCursor, hasNext: first.hasNextPage, total: first.totalCount });
+    });
+  }, [query]);
+
+  const loadMore = async () => {
+    const mine = generation.current;
+    setFailed(false); setLoadingMore(true);
+    try {
+      const next = await fetchQuizzes(new URLSearchParams(query), page.cursor);
+      if (mine !== generation.current) return; // the query changed meanwhile
+      setRows((all) => [...all, ...next.nodes]); // only the next page
+      setPage({ cursor: next.endCursor, hasNext: next.hasNextPage, total: next.totalCount });
+    } catch {
+      if (mine === generation.current) setFailed(true); // the rows stay, "Try again"
+    } finally {
+      if (mine === generation.current) setLoadingMore(false);
+    }
+  };
+
+  return (
+    <ServerTable
+      params={params} onParamsChange={setParams}
+      rows={rows} totalCount={page.total} pageInfo={{ hasNextPage: page.hasNext }}
+      pageSize={20} getRowId={(q) => q.id} columns={columns}
+      filter={{ model: QUIZ_FILTERS }} // a chips-single field with inline: true
+      empty={{ none: 'No quiz yet', noMatch: 'No quiz matches' }}
+      footer="load-more" onLoadMore={loadMore}
+      isLoadingMore={isLoadingMore} loadMoreFailed={failed}
+    />
+  );
+}
+```
+
+The footer is [`LoadMoreFooter`](./buttons-and-actions.md#loadmorefooter): once
+the last page is in, its status line stays ("Showing 42 of 42", announced) and,
+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.
+
+#### An inline chip group
+
+A `chips-single` or `chips-multiple` field declared `inline: true` shows its
+options as a chip group in the bar itself, at every width, instead of a quick
+pill that opens an editor. It suits a short list of choices that is the main
+way to narrow a list (the topics of a catalogue).
+
+```ts
+{ id: 'topic', type: 'chips-single', label: 'Topic', options: TOPICS, inline: true }
+```
+
+- **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.
+- **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.
+- **Rules.** `defineFilterModel` throws without `options`, with another type,
+  with a `default`, with `scope` or with `addable: false`. A condition the
+  group cannot draw (another operator, or a value that is not an
+  option; the URL codec already drops both, so this guards a query written by
+  code) keeps its normal chip with its ✕, so an active filter
+  is never hidden; `inlineShows(field, condition)` is the rule.
+- **Core.** `isInline(field)`, `inlineShows(field, condition)`; `bandQuickFields` and the bar's `quickFields`
+  list inline fields after the scope ones.
+
 #### A scope field
 
 A list scoped by a value the user changes but never clears (the period or the

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,46 @@ 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, describedBy, language, maxLength, readOnly, disabled }`. Keeps Monaco out of the card's bundle |
+| `Question` `description` | `string` | — | `open`, `code`: a persistent helper line under the answer field ("A person will mark this answer"), linked to it by `aria-describedby` and passed to `renderCode` as `field.describedBy`; always shown, unlike `hint` (a reveal button). Its id is `${promptId}-description` |
+| `QuestionCard` `promptId` | `string` | generated | the id of the prompt text: point a wrapping section's `aria-labelledby` at it (and `aria-describedby` at `${promptId}-description`) |
+| `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 +2505,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 |