@nxgt/material 3.57.0 → 3.59.0

package/dist/{use-heading-spy-51GQw8tH.js → use-heading-spy-COxCWqWF.js}

@@ -1,4 +1,4 @@
-import { r as e } from "./i18n-provider-DBr59j1p.js";
+import { r as e } from "./i18n-provider-BJDI-A5w.js";
 import { _ as t, g as n, h as r, n as i, v as a, y as o } from "./number.utils-BG_eEt5g.js";
 import { useCallback as s, useEffect as c, useMemo as l, useRef as u, useState as d } from "react";
 import { busySettler as f, busySettler as p, createSubmitGuard as m, createSubmitGuard as h } from "@nxgt/material-core/submit-guard";

package/dist/{use-material-translation-BQOr4Oks.js → use-material-translation-BZAy_ffS.js}

@@ -1,5 +1,5 @@
-import { r as e } from "./i18n-provider-DBr59j1p.js";
-import { t } from "./translate-material-BkqnImND.js";
+import { r as e } from "./i18n-provider-BJDI-A5w.js";
+import { t } from "./translate-material-Q67GD4co.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/use-shape-morph-BKA_R5P5.js

@@ -0,0 +1,35 @@
+import { morph as e, morphAt as t, toSvgPath as n } from "@nxgt/material-core/shapes";
+import { useLayoutEffect as r, useRef as i } from "react";
+//#region lib/components/ui/display/shape/use-shape-morph.ts
+var a = .8, o = 14, s = o * Math.sqrt(1 - a * a);
+function c(e) {
+	let t = e / 1e3;
+	return 1 - Math.exp(-.8 * o * t) * (Math.cos(s * t) + a * o / s * Math.sin(s * t));
+}
+var l = () => typeof window.matchMedia == "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+function u(a, o, s) {
+	let u = i(o);
+	r(() => {
+		let r = a.current, i = u.current;
+		if (!r || i === o || !s || l()) {
+			r && i !== o && r.setAttribute("d", n(o)), u.current = o;
+			return;
+		}
+		let d = e(i, o), f = n(o), p = 0, m = performance.now(), h = (e) => {
+			let i = e - m;
+			if (i >= 520) {
+				u.current = o, r.setAttribute("d", f);
+				return;
+			}
+			let a = t(d, c(i));
+			u.current = a, r.setAttribute("d", n(a)), p = requestAnimationFrame(h);
+		};
+		return r.setAttribute("d", n(d.from)), p = requestAnimationFrame(h), () => cancelAnimationFrame(p);
+	}, [
+		a,
+		o,
+		s
+	]);
+}
+//#endregion
+export { u as n, c as t };

package/dist/{youtube-node-OWSNlYCc.js → youtube-node-A3NPAPgK.js}

@@ -172,15 +172,7 @@ var mt = D.create({
 		return ["div", w(e)];
 	},
 	...A(Be, ft)
-}), ht = /^(https?:|mailto:|tel:)/i, gt = /^[a-z][a-z0-9+.-]*:/i;
-function _t(e) {
-	if (typeof e != "string") return;
-	let t = e.replace(/[\u0000-\u001f\u007f\s]+/g, "");
-	if (t) return ht.test(t) ? e.trim() : gt.test(t) ? void 0 : e.trim();
-}
-//#endregion
-//#region lib/components/ui/widgets/editor/extensions/custom/shared/icon-options.ts
-var vt = {
+}), ht = {
 	sparkles: Pe,
 	rocket: je,
 	star: Fe,
@@ -195,34 +187,42 @@ var vt = {
 	"trending-up": Le,
 	info: Ae,
 	settings: Me
-}, yt = Object.keys(vt), bt = "sparkles";
-function xt(e) {
+}, gt = Object.keys(ht), _t = "sparkles";
+function vt(e) {
 	return e.split("-").map((e) => e[0].toUpperCase() + e.slice(1)).join(" ");
 }
-function St(e) {
-	return vt[typeof e == "string" && yt.includes(e) ? e : bt];
+function yt(e) {
+	return ht[typeof e == "string" && gt.includes(e) ? e : _t];
 }
 //#endregion
 //#region lib/components/ui/widgets/editor/extensions/custom/action-card/const.ts
-var Ct = "actionCard", wt = [{
+var bt = "actionCard", xt = [{
 	value: "sm",
 	label: "Small"
 }, {
 	value: "md",
 	label: "Medium"
-}], Tt = [{
+}], St = [{
 	id: "card-1",
-	icon: bt,
+	icon: _t,
 	title: "Title",
 	description: "Description",
 	href: ""
 }, {
 	id: "card-2",
-	icon: bt,
+	icon: _t,
 	title: "Title",
 	description: "Description",
 	href: ""
-}], Et = /^\[((?:\\.|[^\]])*)\]\(([^)\s]*)\)$/, Dt = (e) => Array.isArray(e) ? e : [], Ot = (e) => j(e) ? [`  ${j(e).replace(/\n/g, " ")}`] : [], kt = {
+}], Ct = /^(https?:|mailto:|tel:)/i, wt = /^[a-z][a-z0-9+.-]*:/i;
+function Tt(e) {
+	if (typeof e != "string") return;
+	let t = e.replace(/[\u0000-\u001f\u007f\s]+/g, "");
+	if (t) return Ct.test(t) ? e.trim() : wt.test(t) ? void 0 : e.trim();
+}
+//#endregion
+//#region lib/components/ui/widgets/editor/format/codecs/cards.ts
+var Et = /^\[((?:\\.|[^\]])*)\]\(([^)\s]*)\)$/, Dt = (e) => Array.isArray(e) ? e : [], Ot = (e) => j(e) ? [`  ${j(e).replace(/\n/g, " ")}`] : [], kt = {
 	write: (e) => {
 		let t = new Set((Array.isArray(e.value) ? e.value : []).map(String));
 		return {
@@ -279,23 +279,23 @@ var Ct = "actionCard", wt = [{
 //#endregion
 //#region lib/components/ui/widgets/editor/extensions/custom/action-card/spec.ts
 function jt(e) {
-	if (!e) return Tt;
+	if (!e) return St;
 	try {
 		let t = JSON.parse(e);
-		return Array.isArray(t) ? t : Tt;
+		return Array.isArray(t) ? t : St;
 	} catch {
-		return Tt;
+		return St;
 	}
 }
 var Mt = D.create({
-	name: Ct,
+	name: bt,
 	group: "block",
 	atom: !0,
 	draggable: !0,
 	addAttributes() {
 		return {
 			items: {
-				default: Tt,
+				default: St,
 				parseHTML: (e) => jt(e.getAttribute("data-action-card-items")),
 				renderHTML: (e) => ({ "data-action-card-items": JSON.stringify(e.items) })
 			},
@@ -312,7 +312,7 @@ var Mt = D.create({
 	renderHTML({ HTMLAttributes: e }) {
 		return ["div", w(e)];
 	},
-	...A(Ct, At)
+	...A(bt, At)
 }), Nt = "callout", Pt = {
 	info: {
 		label: "Info",
@@ -4583,12 +4583,12 @@ var Ls = D.create({
 	value: "option-1",
 	title: "Option 1",
 	description: "",
-	icon: bt
+	icon: _t
 }, {
 	value: "option-2",
 	title: "Option 2",
 	description: "",
-	icon: bt
+	icon: _t
 }];
 //#endregion
 //#region lib/components/ui/widgets/editor/extensions/custom/select-card/spec.ts
@@ -6778,4 +6778,4 @@ var ru = nu(Ll), iu = nu(Rl), au = E.create({
 	})
 });
 //#endregion
-export { Ve as $, fr as A, It as B, Di as C, mr as D, vr as E, $t as F, Tt as G, Ft as H, Ut as I, vt as J, bt as K, zt as L, Ln as M, nr as N, dr as O, Xt as P, mt as Q, Bt as R, Ei as S, xr as T, Mt as U, Pt as V, wt as W, St as X, xt as Y, _t as Z, Ps as _, tu as a, ki as b, Js as c, Us as d, Bs as f, Ns as g, Fs as h, iu as i, Fn as j, ur as k, Ks as l, Ls as m, au as n, zl as o, zs as p, yt as q, ru as r, Z as s, gu as t, Gs as u, js as v, Cr as w, Oi as x, Ts as y, Rt as z };
+export { Ve as $, fr as A, It as B, Di as C, mr as D, vr as E, $t as F, xt as G, Ft as H, Ut as I, gt as J, St as K, zt as L, Ln as M, nr as N, dr as O, Xt as P, mt as Q, Bt as R, Ei as S, xr as T, Mt as U, Pt as V, Tt as W, vt as X, ht as Y, yt as Z, Ps as _, tu as a, ki as b, Js as c, Us as d, Bs as f, Ns as g, Fs as h, iu as i, Fn as j, ur as k, Ks as l, Ls as m, au as n, zl as o, zs as p, _t as q, ru as r, Z as s, gu as t, Gs as u, js as v, Cr as w, Oi as x, Ts as y, Rt as z };

package/docs/README.md

@@ -9,6 +9,7 @@ detail: every option, the second example, and the traps.
 | [Components](components/README.md) | You are looking for a component — one preview per category, then one page per category |
 | [Forms](guides/forms.md) | You are building a form: the field / `*FormField` pair, React Hook Form + Zod, what each field emits, server errors, multi-step forms |
 | [Themes for your app](guides/themes.md) | You define your own themes: `defineTheme` modules, the Vite plugin's `themes` option, the `nxgt-theme` command and its CI check, the tone warnings |
+| [Barcodes and label sheets](guides/barcode.md) | You draw a Code 128 or Data Matrix code and print a sheet of labels with `@nxgt/material/barcode`: `Barcode`, `LabelSheet` and `Label`, label size, columns, rows, gaps and a start offset, dark mode, print and accessibility |
 | [Charts](guides/charts.md) | You draw charts with `@nxgt/material/charts`: each chart, the shared props, reference bands, thresholds and point tones, zoom and phone scroll, the keyboard, accessibility, theming the `--chart-1..5` tokens, and moving off the Nivo charts, removed in 3.0 |
 | [Cards and tiles](guides/cards-and-tiles.md) | You want a `DataTable` as a list of cards or tiles: `layout`, `renderCard`, `renderTile`, the card's one link, selection, the sort control, columns by the list's width |
 | [DataGrid](guides/data-grid.md) | You are building an editable grid: columns and editors, save modes and conflicts, resizing, hiding and reordering columns, paste, fill and series, undo, totals, long lists, phones, custom editors, CSP |

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

@@ -18,6 +18,7 @@ and language switches. Everything is imported from `@nxgt/material/components`.
 | <img src="../previews/buttons-actions-copybutton.webp" width="96" alt=""> | [CopyButton](#copybutton) | Copies a value, shows a check mark |
 | <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 |
 | <img src="../previews/buttons-actions-scrolltotop.webp" width="96" alt=""> | [ScrollToTop](#scrolltotop) | Appears past a scroll threshold |
 | <img src="../previews/buttons-actions-scrolltolatestbutton.webp" width="96" alt=""> | [ScrollToLatestButton](#scrolltolatestbutton) | "Jump to latest" over a scroll box, counting what arrived |
 | <img src="../previews/buttons-actions-actioncard.webp" width="96" alt=""> | [ActionCard](#actioncard) | Clickable card, a button (`aria-pressed`) when it chooses or reacts, with an active indicator; `status`, `meta`, a trailing `action` and a `tile` variant |
@@ -969,6 +970,42 @@ buttons.
 
 ---
 
+
+## LoadMoreFooter
+
+![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.
+
+```tsx
+import { LoadMoreFooter } from '@nxgt/material/components';
+
+<LoadMoreFooter
+  shown={items.length}
+  total={totalCount}
+  hasMore={hasNextPage}
+  loading={isFetchingNextPage}
+  failed={isFetchNextPageError}
+  onLoad={() => fetchNextPage()}
+/>;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `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 |
+| `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 |
+| `label` | `string` | `"Load more"` (translated) | the load button's text; the button is expanded here |
+| `onLoad` | `() => void` | — | loads the next page; the retry calls it too |
+
+Texts are `material.load-more.shown`, `.shown-count`, `.failed` and `.retry` (English and French). It composes [`LoadMoreButton`](#loadmorebutton); keep that one for a pagination bar. For a page opened at a cursor that failed, see [`PageLoadFailed`](./feedback-and-status.md#pageloadfailed).
+
+**Storybook:** `Buttons & actions/LoadMoreFooter` · **Vue:** not yet (tracked as a `vue` issue)
+
+---
+
 ## ScrollToTop
 
 ![ScrollToTop](../previews/buttons-actions-scrolltotop.webp)

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

@@ -13,11 +13,12 @@ centre.
 | <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-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 |
 | <img src="../previews/feedback-status-progress.webp" width="96" alt=""> | [Progress](#progress) | Material 3 Expressive linear bar, circular ring and labelled progress field, flat or wavy |
 | <img src="../previews/feedback-status-scrollprogress.webp" width="96" alt=""> | [ScrollProgress](#scrollprogress) | Hairline tracking the window or a scrollable element |
 | <img src="../previews/feedback-status-stepdots.webp" width="96" alt=""> | [StepDots](#stepdots) | Segmented step progress, each step coloured by its state |
-| <img src="../previews/feedback-status-countdowntimer.webp" width="96" alt=""> | [CountdownTimer](#countdowntimer) | Countdown clock with a ring, amber then red as time runs out, with an icon and words in the warning |
+| <img src="../previews/feedback-status-countdowntimer.webp" width="96" alt=""> | [CountdownTimer](#countdowntimer) | Countdown clock with a ring, amber then red as time runs out, with an icon and words when time is low |
 | <img src="../previews/feedback-status-spinner.webp" width="96" alt=""> | [Spinner](#spinner) | Loading spinner in several styles and colours |
 | <img src="../previews/feedback-status-loadingindicator.webp" width="96" alt=""> | [LoadingIndicator](#loadingindicator) | Material 3 Expressive's loading indicator: a shape morphing while it turns |
 | <img src="../previews/feedback-status-typingindicator.webp" width="96" alt=""> | [TypingIndicator](#typingindicator) | Three dots in a wave: someone is writing |
@@ -502,6 +503,30 @@ The default description is the companion of its title: with your own `title` and
 
 ---
 
+## PageLoadFailed
+
+![PageLoadFailed](../previews/feedback-status-pageloadfailed.webp)
+
+An `EmptyState` for a list page opened at a cursor that failed to load (a stale link, a lost page): a title and a tonal "Back to the start" link. The link is rendered by the `LinkComponentProvider`'s component. For the next page of a list that is already shown, use [`LoadMoreFooter`](./buttons-and-actions.md#loadmorefooter), which keeps the rows.
+
+```tsx
+import { PageLoadFailed } from '@nxgt/material/components';
+
+<PageLoadFailed href="/orders" />;
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `href` | `string` | — | where "Back to the start" goes: the list without its cursor |
+| `linkLabel` | `string` | `"Back to the start"` (translated) | the link's text |
+| `title` | `ReactNode` | `"This page could not be loaded"` (translated) | the title |
+
+It takes the other `EmptyState` props (`size`, `illustration`, `description`, `headingLevel`) except `action`. Texts are `material.load-more.page-failed-title` and `.back-to-start`.
+
+**Storybook:** `Feedback & status/PageLoadFailed` · **Vue:** not yet (tracked as a `vue` issue)
+
+---
+
 ## ErrorState
 
 ![ErrorState](../previews/feedback-status-errorstate.webp)
@@ -747,7 +772,8 @@ import { CountdownTimer } from '@nxgt/material/components';
 
 <CountdownTimer duration={300} onExpire={() => submit()} />;
 
-// Past `warningAt` it shows a clock icon and "Little time left"; change or hide the words:
+// Past `warningAt` it shows a clock icon and "Little time left" ("Almost out of time" past
+// `criticalAt`); change (both tones) or hide the words:
 <CountdownTimer duration={300} warningText="Hurry up" />;
 <CountdownTimer duration={300} warningText={false} />;
 ```
@@ -759,12 +785,12 @@ import { CountdownTimer } from '@nxgt/material/components';
 | `onExpire` | `() => void` | — | called once, at zero |
 | `warningAt` / `criticalAt` | `number` | a quarter (≤ 60 s) / a tenth (≤ 10 s) | the seconds left when it turns amber / red |
 | `label` | `string` | `'Time remaining'` | its name |
-| `warningText` | `string \| false` | `'Little time left'` | the words shown with a clock icon in the warning tone, so low time is not told by colour alone; `false` hides them |
+| `warningText` | `string \| false` | `'Little time left'` / `'Almost out of time'` | the words shown with a clock icon in the warning and critical tones, so low time is not told by colour alone; a string replaces both phrases; `false` hides them |
 | `size` | `'sm' \| 'md'` | `'md'` | 28 or 36 px high |
 
 It ticks on the client only: the server renders the full time. The clock is a
 `role="timer"`; a polite live region speaks only when a threshold is crossed
-("Little time left. 1:00 left", the phrase being `warningText`) and when the time is up, never every second. `formatClock` and
+("Little time left. 1:00 left", the phrase being `warningText` or the critical one) and when the time is up, never every second. `formatClock` and
 `countdownTone` are exported too, and so is the clock itself as the
 [`useCountdown`](../guides/helpers.md#usecountdown) hook (`@nxgt/material/hooks`),
 for a button that waits without a ring.

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

@@ -12,6 +12,7 @@ documentation-site shell. Everything is imported from
 | <img src="../previews/navigation-layout-authcard.webp" width="96" alt=""> | [AuthCard](#authcard) | Signed-out page frame: one `main`, a centred card, its title the `h1` |
 | <img src="../previews/navigation-layout-sidebar.webp" width="96" alt=""> | [Sidebar](#sidebar) | Collapsible navigation sidebar |
 | <img src="../previews/navigation-layout-topappbar.webp" width="96" alt=""> | [TopAppBar, BottomAppBar](#topappbar) | Top and bottom bars |
+| <img src="../previews/navigation-layout-stickyactionbar.webp" width="96" alt=""> | [StickyActionBar](#stickyactionbar) | A page's main decision, stuck to the bottom on a phone, inline from `md` |
 | <img src="../previews/navigation-layout-breadcrumb.webp" width="96" alt=""> | [Breadcrumb](#breadcrumb) | Breadcrumb primitives |
 | <img src="../previews/navigation-layout-listdetailslayout.webp" width="96" alt=""> | [ListDetailsLayout, PaneLayout, ThreadLayout](#listdetailslayout) | Page layouts that adapt to phones |
 | <img src="../previews/navigation-layout-responsivegrid.webp" width="96" alt=""> | [ResponsiveGrid](#responsivegrid) | Container-query grid, 1 to 5 columns, or `auto-fill` columns by a minimum tile width (`minItem`) |
@@ -343,6 +344,52 @@ the one with `data-state="active"`.
 
 ---
 
+## StickyActionBar
+
+![StickyActionBar](../previews/navigation-layout-stickyactionbar.webp)
+
+The bar that holds a page's main decision (approve / send back). On a phone it
+sticks to the bottom of the scroll box, above the on-screen keyboard and clear
+of the safe areas; from `md` (768px) it is an inline row after the content.
+
+```tsx
+import { Button, StickyActionBar } from '@nxgt/material/components';
+
+<main>
+  {/* long content */}
+  <StickyActionBar aria-label="Review decision">
+    <Button variant="outlined">Send back</Button>
+    <Button>Approve</Button>
+  </StickyActionBar>
+</main>
+```
+
+Put it last in the scrolling content: it is `position: sticky`, not `fixed`, so
+it takes its own room (nothing hides behind it) and rests inline at the end of
+the page. It takes a `div`'s props.
+
+- **One primary action.** The last child is the primary: on a phone it takes
+  the room the others leave, which keep their size. Give it the one filled
+  `Button`; a second filled `Button` among the children warns once in
+  development, make the others `outlined` or `tonal`.
+- **Safe areas.** Under `viewport-fit=cover` the bar pads clear of
+  `env(safe-area-inset-left | right | bottom)`, as classes.
+- **Keyboard.** From the visual viewport (`visualViewport`), the bar rises by
+  the height the on-screen keyboard covers (`--nxgt-keyboard-inset` on the bar,
+  `data-keyboard="open"` while it is open) and drops the bottom safe-area
+  padding, which the keyboard covers. A browser that resizes the layout itself
+  (`interactive-widget=resizes-content`) needs no lift, and none is applied.
+  Pinch-zoom is not treated as a keyboard.
+- **Name.** With `aria-label` or `aria-labelledby` the bar is a `group`.
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `sticky` | `boolean` | `true` | `false`: inline on a phone too |
+
+**Storybook:** `Navigation & layout/StickyActionBar` · **Vue:** not yet
+
+---
+
 ## Breadcrumb
 
 ![Breadcrumb](../previews/navigation-layout-breadcrumb.webp)

package/docs/components/rich-widgets.md

@@ -11,6 +11,7 @@ the app owns the data.
 | <img src="../previews/rich-widgets-eventcalendar.webp" width="96" alt=""> | [EventCalendar](#eventcalendar) | Month / week / day / agenda calendar, a day view split by resource, a named time zone, phone to desktop |
 | <img src="../previews/rich-widgets-native-charts-linechart.webp" width="96" alt=""> | [Charts](#charts) | Native SVG charts (line, area, bar, pie, donut, gauge, radial, funnel, heat map, radar, scatter, combo) with keyboard, summary and View data; the Nivo ones were removed in 3.0 |
 | <img src="../previews/rich-widgets-drawing.webp" width="96" alt=""> | [Drawing](#drawing) | Vector drawing from a scene of plain data or JSX primitives: theme colours, accessible, focusable nodes, strict-CSP safe |
+| | [Barcode](#barcode) | Code 128 and Data Matrix as accessible SVG, themed and dark-aware, black on white in print, with `LabelSheet` for a printed sheet of labels |
 | <img src="../previews/rich-widgets-emojipicker.webp" width="96" alt=""> | [EmojiPicker](#emojipicker) | Shared emoji picker and list |
 | <img src="../previews/rich-widgets-mentionlist.webp" width="96" alt=""> | [MentionList](#mentionlist) | `@` mention list with local search |
 | <img src="../previews/rich-widgets-documenteditor.webp" width="96" alt=""> | [DocumentEditor](#documenteditor) | Rich text editor for long-form writing, built on a headless core |
@@ -615,6 +616,36 @@ How to use it in an app (server rendering, CSP, colours, events, PNG, PDF, e-mai
 
 ---
 
+## Barcode
+
+Code 128 and Data Matrix from `@nxgt/material/barcode`, drawn as SVG by the
+package (no runtime dependency). The symbol follows the theme and dark mode on
+screen (`appearance="paper"` keeps it dark on light), is black on white in
+print, is named by `label` (or its value) and writes no inline `style`. Its own
+entry, server-safe.
+
+```tsx
+import { Barcode, Label, LabelSheet } from '@nxgt/material/barcode';
+
+<Barcode value="TUBE-0042" label="Tube 0042" showText />
+<Barcode value="TUBE-0042" symbology="datamatrix" />
+
+<LabelSheet label={{ width: '50mm', height: '25mm' }} columns={3} rows={8} gap="2mm" offset={{ x: 5, y: 8 }}>
+	{items.map((i) => (
+		<Label key={i.id}>
+			<Barcode value={i.code} decorative />
+			{i.code}
+		</Label>
+	))}
+</LabelSheet>
+```
+
+`LabelSheet` takes `label` (`{ width, height }`), `columns`, `rows` (labels per
+page), `gap`, `offset` (margin before the first label) and `skip` (blank labels
+first); lengths are millimetres or a string with a unit. A value a symbology cannot hold throws a `BarcodeError`; `barcodeGeometry(value, options)` returns the `viewBox` size and path for an SVG of your own. See the
+[barcode guide](../guides/barcode.md) for printing a sheet and for the limits
+of each symbology.
+
 ## EmojiPicker
 
 ![EmojiPicker](../previews/rich-widgets-emojipicker.webp)
@@ -2412,7 +2443,7 @@ French bundle — see [i18n](../guides/i18n.md).
 | `onComplete` | `(result: QuizResult) => void` | — | `{ correct, total, percent, answers, timedOut }`, once per results screen |
 | `onAnswersChange` / `onIndexChange` | callbacks | — | follow progress |
 | `QuestionCard` `revealed` | `boolean` | `false` | marks right / wrong and shows the verdict and `explanation` |
-| `QuestionCard` `verdict` | `'correct' \| 'incorrect' \| 'pending'` | — | the server's verdict, shown as given (word and icon, never colour alone); reveals the card. `question.correct` is optional and only highlights the right choices. Without it, `revealed` compares in the browser as before |
+| `QuestionCard` `verdict` | `'correct' \| 'incorrect' \| 'pending' \| 'unanswered'` | — | the server's verdict, shown as given (word and icon, never colour alone); reveals the card; `unanswered` is a blank question ("No answer", no value shown, the correct answer and `explanation` shown, points read 0). `question.correct` is optional and only highlights the right choices. Without it, `revealed` compares in the browser as before |
 | `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 |
@@ -2424,7 +2455,7 @@ A server-graded answer, shown as given (no comparison in the browser):
 <QuestionCard
   question={{ id: 'q1', kind: 'text', prompt: 'Explain X' }}
   value="my answer"
-  verdict="incorrect" // or 'correct' | 'pending'
+  verdict="incorrect" // or 'correct' | 'pending' | 'unanswered'
   points={{ awarded: 2, possible: 3 }}
   feedback="Good, but cite a source"
 />
@@ -2436,7 +2467,7 @@ A server-graded answer, shown as given (no comparison in the browser):
 
 The numbered questions of a quiz or exam player: jump to one, see the current
 one and which are answered or flagged. Import it from
-`@nxgt/material/widgets/education`.
+`@nxgt/material/components`.
 
 ```tsx
 <QuestionNavigator

package/docs/guides/barcode.md

@@ -0,0 +1,203 @@
+# Barcodes and label sheets
+
+`@nxgt/material/barcode` draws a scannable code and lays labels out on a sheet
+to print. `Barcode` is a Code 128 or Data Matrix symbol as SVG: it follows the
+theme and dark mode on screen, is black on white in print, has an accessible
+name and writes no inline `style` (a strict CSP is satisfied). `LabelSheet`
+and `Label` set the label size, the columns, rows, gaps and a start offset.
+
+The encoders are in the package: no runtime dependency comes with it. Its
+tests read the symbols back with a real decoder (zxing-cpp) and compare the
+Data Matrix modules with bwip-js.
+
+- [Set up](#set-up)
+- [A barcode](#a-barcode)
+- [Code 128 or Data Matrix](#code-128-or-data-matrix)
+- [Colours, dark mode and print](#colours-dark-mode-and-print)
+- [Accessibility](#accessibility)
+- [A sheet of labels](#a-sheet-of-labels)
+- [Printing a sheet](#printing-a-sheet)
+- [Without React](#without-react)
+- [Troubleshooting](#troubleshooting)
+
+## Set up
+
+```tsx
+import { Barcode, Label, LabelSheet } from '@nxgt/material/barcode';
+```
+
+The entry is its own: it is not in `@nxgt/material` or
+`@nxgt/material/components`. The colours come from `styles.css`, which your app
+already imports. `Barcode` has no hooks and renders on the server; `LabelSheet`
+sets its lengths once mounted (see [Printing a sheet](#printing-a-sheet)).
+
+## A barcode
+
+```tsx
+<Barcode value="TUBE-0042" showText />
+```
+
+| Prop | Default | |
+| --- | --- | --- |
+| `value` | | The text to encode (required). |
+| `symbology` | `'code128'` | `'code128'` or `'datamatrix'`. |
+| `label` | the value | The accessible name. |
+| `decorative` | `false` | Hide the symbol from assistive technology. |
+| `showText` | `false` | Print the value under a Code 128, inside the SVG (a Data Matrix ignores it). |
+| `appearance` | `'themed'` | `'themed'` or `'paper'` ([Colours](#colours-dark-mode-and-print)). |
+| `moduleSize` | | Pixels per module: sets a fixed `width` and `height`. Without it the SVG fills its box and keeps its ratio. |
+| `quietZone` | 10 (Code 128), 2 (Data Matrix) | The blank margin, in modules. Scanners need it: keep at least 10 and 1. |
+| `barHeight` | 40 | The bar height of a Code 128, in modules. |
+
+Other SVG props (`className`, `data-*`...) pass to the `<svg>`. An invalid
+value throws a `BarcodeError` while rendering, with a message that names the
+limit.
+
+## Code 128 or Data Matrix
+
+| | Code 128 | Data Matrix |
+| --- | --- | --- |
+| Shape | bars, as wide as the text is long | a square |
+| Holds | ASCII, characters 0 to 127 | any text (UTF-8), up to about 3 100 digits |
+| Best for | an identifier a handheld laser or camera reads at 5 to 10 cm | a small label (a tube, a part) read by a camera, error correction included |
+| Digits | two per symbol character (code set C) | two per codeword |
+
+Code 128 switches between its three code sets to keep the symbol short. Data
+Matrix uses the ASCII encodation, with the smallest square symbol (10x10 to
+144x144) that holds the text; upper-case text may come out one size larger than
+a symbol made with the denser C40 encodation. Text outside ASCII goes through
+`symbology="datamatrix"` as UTF-8: tell your scanner's decoder to read UTF-8.
+
+## Colours, dark mode and print
+
+On screen the symbol is drawn with the theme: `--foreground` on `--background`,
+so it follows light and dark. Many scanners read **dark on light only**, so in
+dark mode a themed symbol may not scan from the screen: use
+`appearance="paper"` for a symbol that must be scanned from the screen, which
+stays black on white in dark mode too. In print every symbol is black on white,
+whatever the theme or `appearance`.
+
+## Accessibility
+
+A symbol is `role="img"` named by `label`, or by the value when there is no
+`label`, with the same text in a `<title>`. A code is not meant to be read aloud:
+name it with what it identifies (`label="Tube 0042"`). When the value is written
+beside the symbol, pass `decorative`: the symbol is then hidden, and the text
+carries the meaning. `showText` writes the value under a Code 128 in a
+`<text>` that is hidden from assistive technology (the image already carries
+the name).
+
+## A sheet of labels
+
+```tsx
+<LabelSheet
+  label={{ width: '50mm', height: '25mm' }}
+  columns={3}
+  rows={8}
+  gap="2mm"
+  offset={{ x: '5mm', y: '8mm' }}
+>
+  {items.map((i) => (
+    <Label key={i.id}>
+      <Barcode value={i.code} decorative barHeight={30} />
+      {i.code}
+    </Label>
+  ))}
+</LabelSheet>
+```
+
+| Prop | Default | |
+| --- | --- | --- |
+| `label` | | `{ width, height }` of one label (required). |
+| `columns` | | Labels per row (required). |
+| `rows` | all on one page | Rows per page: every `columns` x `rows` labels start a new page. |
+| `gap` | 0 | One length, or `{ x, y }`. |
+| `offset` | 0 | `{ x, y }`: the margin before the first label, for a printer's unprintable edge or a sheet's own margin. |
+| `skip` | 0 | Blank labels first: start on the fifth label of a sheet that is partly used. |
+
+`columns` and `rows` are whole numbers of at least 1, `skip` a whole number of at least 0. A length is a number of millimetres or a string with a unit (`'2.5cm'`,
+`'0.5in'`, `'8pt'`, `'12px'`, `'1rem'`); anything else throws a `BarcodeError`.
+A `Label` clips to the label size and never splits across two pages. A symbol
+inside a `Label` scales to fit it, leaving room for the text under it.
+
+## Printing a sheet
+
+A browser prints a page size that the page's CSS names. Add it to your print
+stylesheet, with the size of your sheet and no margin of its own (the sheet's
+`offset` is the margin):
+
+```css
+@media print {
+  @page {
+    size: A4;
+    margin: 0;
+  }
+}
+```
+
+Then call `window.print()`. The preview on screen draws a dashed outline around
+each page and a dotted one around each label; both disappear in print, and the
+symbols turn black on white. To print the sheet alone from a page with other
+content, use `printOnly` from `@nxgt/material/lib`.
+
+`LabelSheet` writes its lengths as custom properties (`--nxgt-label-w`...) from
+an effect, because a strict CSP blocks a `style` attribute in server markup.
+Print after the page has hydrated; the server's markup alone has no label size, so a sheet printed from it comes out wrong.
+Check the printed size once on your own printer: browsers scale a page to fit
+unless the print dialog says "100%" or "Actual size".
+
+## Without React
+
+`barcodeGeometry(value, options)` returns the `viewBox` size and one SVG path of
+the dark modules, in module units, for an SVG you assemble yourself (an e-mail,
+a PDF drawing). Options: `symbology`, `quietZone`, `barHeight` and
+`textHeight` (room under a Code 128 for text). The result is
+`{ symbology, width, height, path, textY }`; `textY` is where a Code 128's text
+baseline sits.
+
+```tsx
+const g = barcodeGeometry('TUBE-0042', { symbology: 'code128', barHeight: 30 });
+const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${g.width} ${g.height}">
+  <rect width="${g.width}" height="${g.height}" fill="#fff"/><path d="${g.path}"/></svg>`;
+```
+
+The types `BarcodeProps`, `BarcodeSymbology`, `BarcodeGeometry`,
+`BarcodeGeometryOptions`, `LabelSheetProps` and `LabelLength` are exported too.
+
+## Troubleshooting
+
+### `Code 128 holds ASCII only (0-127)`
+
+The value has a character such as `é` or `€`. Use `symbology="datamatrix"`, or
+remove the character.
+
+### `Code 128 needs a value` / `Data Matrix needs a value`
+
+The value is an empty string. Render the symbol only once there is a code.
+
+### `<name> must be a whole number`
+
+`columns`, `rows` or `skip` is zero, negative or fractional.
+
+### `Data Matrix holds at most 1558 codewords`
+
+The value is longer than the largest symbol (about 3 100 digits, fewer
+characters otherwise). Encode an identifier and look the rest up.
+
+### `<name> must be a number (millimetres) or a length such as "50mm"`
+
+A size or gap is a bare string (`'50'`) or an unsupported unit. Pass a number
+(millimetres) or a string like `'50mm'`.
+
+### `Unknown symbology "x"`
+
+`symbology` is neither `"code128"` nor `"datamatrix"`; TypeScript catches it, plain JS does not.
+
+### The code does not scan from the screen in dark mode
+
+Use `appearance="paper"`, and keep the quiet zone.
+
+### The printed labels are a little off
+
+The print dialog scaled the page. Choose "100%" / "Actual size", set the
+`@page` size to the sheet's, and set `offset` to move the first label.