@nxgt/material 3.58.0 → 3.59.0

package/dist/{use-heading-spy-1Dqxj_JQ.js → use-heading-spy-COxCWqWF.js}

@@ -1,4 +1,4 @@
-import { r as e } from "./i18n-provider-C0uLEv0G.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-DLdQKdfw.js → use-material-translation-BZAy_ffS.js}

@@ -1,5 +1,5 @@
-import { r as e } from "./i18n-provider-C0uLEv0G.js";
-import { t } from "./translate-material-Bgtjuh85.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/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,6 +13,7 @@ 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 |
@@ -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)

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)

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.

package/docs/guides/printing.md

@@ -195,7 +195,7 @@ print English strings ("Total", "No rows") and `en` amounts and dates.
 | Component | Props | Renders |
 | --- | --- | --- |
 | `PrintHeader` | `title: string`, `subtitle?: string`, `reference?: string`, `referencePrefix?: string` (`'#'`), `logo?: string \| { src, width?, height? }`, `logoText?: string`, `qrDataUrl?: string \| null` | The title block: the logo (a PNG or JPEG URL or data URL, 72×48 pt unless you size it) or `logoText` in a box on the left, the title, subtitle and `#reference` centred, the QR image on the right. A side you leave empty draws nothing, and the title stays centred |
-| `PrintSection` | `title: string`, `className?: string`, `children` | A titled block (`className` is a `tw` string, default `mb-3.5`) |
+| `PrintSection` | `title: string`, `className?: string`, `keepTogether?: boolean`, `children` | A titled block (`className` is a `tw` string, default `mb-3.5`); `keepTogether` keeps its title and rows on one page, see [Keeping a block on one page](#keeping-a-block-on-one-page) |
 | `PrintInfoRow` | `label: string`, `value?: ReactNode` | A label / value line. A `string` or `number` value is wrapped in `Text`; anything else is rendered as-is |
 | `PrintCard` | `className?: string`, `children` | A bordered row of fields |
 | `PrintCardField` | `label: string`, `value?: string \| null` | A label over a value. **Renders nothing when `value` is empty** |
@@ -1012,8 +1012,8 @@ it:
 | --- | --- | --- |
 | `heading` | `heading(text, level?)` | A title, level `1`, `2` or `3` |
 | `text` | `text(content, { variant?, style? })` | A paragraph: a string, or runs `{ text, bold?, italic?, color?, href? }`; `variant` is `'body'`, `'muted'`, `'caption'` or `'label'` |
-| `stack` / `row` | `stack(children, { gap?, style? })`, `row(children, { gap?, align?, justify?, style? })` | Children one under the other, or side by side |
-| `section` | `section(title, children)` | A titled block, as `PrintSection` |
+| `stack` / `row` | `stack(children, { gap?, style?, keepTogether? })`, `row(children, { gap?, align?, justify?, style? })` | Children one under the other, or side by side |
+| `section` | `section(title, children, { keepTogether? })` | A titled block, as `PrintSection`; `keepTogether` as on a `stack` |
 | `table` | `table({ columns, rows, footer?, labelTotals?, striped?, repeatHeader?, keepRowsWhole?, emptyText?, hideWhenEmpty? })`, or `dataTable(columns, rows, options?)` from [column definitions](#tables-from-column-definitions-datatable-and-keyvalueof) | A table of `PrintValue`s, as `PrintDataTable`; a row or a cell may carry a `style`, see [Row and cell styles](#row-and-cell-styles-in-a-table); with `labelTotals`, an empty first cell of a `footer` row reads "Total" in the document's language |
 | `keyValue` | `keyValue(items, { columns?, keepEmpty? })`, or `keyValueOf(fields, data, options?)` from column definitions | Label and value pairs, as `PrintKeyValue` |
 | `totals` | `totals(rows)` | Label and value rows; `emphasis` makes one bold |
@@ -1122,6 +1122,31 @@ without the footer row, put `pageNumber({ scope: 'group', format: 'page' })`
 in the page's `footer` ("Page 2"). The scope is typed `PdfPageNumberScope`
 (`'document' | 'group'`), exported from `@nxgt/material-core/pdf/model`.
 
+### Keeping a block on one page
+
+`keepTogether` on a `PrintSection`, or on a `section` or `stack` node of a
+document as data, moves the block to the next page whole when it would
+straddle a page break, so a group's title is never left apart from its rows.
+It maps to react-pdf's `wrap={false}`, and is off by default.
+
+```tsx
+<PrintSection title={group.title} keepTogether>
+  {group.rows.map((row) => <PrintInfoRow key={row.id} label={row.label} value={row.value} />)}
+</PrintSection>
+```
+
+```ts
+section(group.title, rows, { keepTogether: true });
+stack([heading('Result'), table(result)], { keepTogether: true });
+```
+
+Use it on a block you know is shorter than a page. react-pdf cannot split a
+block that opted out of wrapping: a block taller than the page area is not
+broken, it overflows the page and is cut off at the edge (react-pdf logs
+"can't wrap between pages and it's bigger than available page height").
+Leave `keepTogether` off for a block that may grow past a page, and use
+`keepRowsWhole` and `repeatHeader` on a long table instead.
+
 ### Row and cell styles in a table
 
 A `rows` or `footer` entry is a list of values, or `{ cells, style? }`; a

package/docs/roadmap.md

@@ -6,6 +6,12 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
+- **Barcodes and label sheets** — `@nxgt/material/barcode` draws Code 128
+  and Data Matrix as accessible SVG (themed, dark-aware, black on white in
+  print) and lays labels out on a sheet to print: label size, columns, rows,
+  gaps and a start offset
+  ([#1963](https://github.com/softistx/nxgt-material/issues/1963),
+  [guide](guides/barcode.md)).
 - **Toast texts follow app translations** — the toast presets read the
   app's `I18nProvider` `resources`, so an override under `material.*`
   changes their wording ([#1855](https://github.com/softistx/nxgt-material/issues/1855)).
@@ -13,13 +19,6 @@ version they shipped in, and planned entries may name the major they target.
   main decision at the bottom of a phone, above the keyboard and clear of the
   safe areas, and inline from `md`
   ([#1964](https://github.com/softistx/nxgt-material/issues/1964)).
-- **Smaller, easier-to-read components** — the library's own source is kept
-  to files under 200 lines and functions under 80, so a component is quicker to
-  read and to fix. No API or behaviour change: smaller modules that are easier
-  to review, and fewer regressions
-  ([#1865](https://github.com/softistx/nxgt-material/issues/1865), slices
-  [#1915](https://github.com/softistx/nxgt-material/issues/1915) to
-  [#1925](https://github.com/softistx/nxgt-material/issues/1925)).
 - **DataGrid: one column, several kinds of row** — `meta.rowEditor(row)` picks
   the built-in editor from the row, and `meta.options` and
   `meta.number.decimals` take the row, so a result column can be a bounded
@@ -317,6 +316,9 @@ version they shipped in, and planned entries may name the major they target.
   `@nxgt/material/print` are removed in favour of `definePdfDocument`, once the
   framework-free engine (see Next) ships. They work, and are not deprecated,
   today.
+- **Imports from the declaring file** — after the size split, internal
+  imports name the file that declares each moved name instead of going through
+  a re-export ([#1980](https://github.com/softistx/nxgt-material/issues/1980)).
 - **Ready-made documents** — invoice, quote, receipt, report, certificate and
   label-sheet templates that take your data and return a document, their labels
   translated.
@@ -356,6 +358,11 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Smaller, easier-to-read components (3.58.0)** — the library's own source
+  is kept to files under 200 lines and functions under 80, enforced by a
+  check, so a component is quicker to read and to fix. No API or behaviour
+  change ([#1865](https://github.com/softistx/nxgt-material/issues/1865)).
+
 - **Dark cards that separate from the page ground (3.54.0)** — in dark mode, cards,
   popovers and dialogs lift off the page ground (lighter surfaces and a `--card-edge`
   hairline), light unchanged ([#1676](https://github.com/softistx/nxgt-material/issues/1676)).

package/docs/troubleshooting.md

@@ -457,6 +457,15 @@ words in your error.
 
 - [Reporting a bug](#reporting-a-bug)
 
+**Barcodes**
+
+- [`Code 128 holds ASCII only (0-127)`](#code-128-holds-ascii-only-0-127)
+- [`Code 128 needs a value` / `Data Matrix needs a value`](#code-128-needs-a-value--data-matrix-needs-a-value)
+- [`Data Matrix holds at most 1558 codewords`](#data-matrix-holds-at-most-1558-codewords)
+- [`<name> must be a whole number`](#name-must-be-a-whole-number)
+- [`<name> must be a number (millimetres) or a length such as "50mm"`](#name-must-be-a-number-millimetres-or-a-length-such-as-50mm)
+- [`Unknown symbology "x": use "code128" or "datamatrix"`](#unknown-symbology-x-use-code128-or-datamatrix)
+
 ---
 
 ## Install
@@ -7820,6 +7829,59 @@ Before upgrading, precaching the illustration chunks in the service worker narro
 
 ---
 
+## Barcodes
+
+### `Code 128 holds ASCII only (0-127)`
+
+Raised by `@nxgt/material/barcode` while rendering. The value has a character above 127 (`é`, `€`). Use `symbology="datamatrix"`, which encodes UTF-8, or remove the character.
+
+```tsx
+<Barcode value="CAFE-42" />
+<Barcode value="Café" symbology="datamatrix" />
+```
+
+### `Code 128 needs a value` / `Data Matrix needs a value`
+
+Raised by `@nxgt/material/barcode` while rendering. `Barcode` or `barcodeGeometry` got an empty string. Render the symbol only when there is a code.
+
+```tsx
+{code ? <Barcode value={code} /> : null}
+```
+
+### `Data Matrix holds at most 1558 codewords`
+
+Raised by `@nxgt/material/barcode` while rendering. The value is longer than the largest 144x144 symbol (about 3 100 digits, fewer other characters). Encode an identifier and look the rest up.
+
+```tsx
+<Barcode value={record.id} symbology="datamatrix" />
+```
+
+### `<name> must be a whole number`
+
+Raised by `@nxgt/material/barcode` while rendering. `columns`, `rows` or `skip` of a `LabelSheet` is zero, negative or fractional (`columns` and `rows` need at least 1, `skip` at least 0).
+
+```tsx
+<LabelSheet label={{ width: 50, height: 25 }} columns={3} rows={8}>
+```
+
+### `<name> must be a number (millimetres) or a length such as "50mm"`
+
+Raised by `@nxgt/material/barcode` while rendering. A `LabelSheet` size, gap or offset is a bare string (`'50'`) or has an unsupported unit. Use a number (millimetres) or `'50mm'`, `'2cm'`, `'0.5in'`, `'8pt'`, `'12px'`, `'1rem'`.
+
+```tsx
+<LabelSheet label={{ width: '50mm', height: 25 }} columns={3} gap="2mm">
+```
+
+### `Unknown symbology "x": use "code128" or "datamatrix"`
+
+Raised by `@nxgt/material/barcode` while rendering. `symbology` is neither value (reachable from plain JS or an untyped string).
+
+```tsx
+<Barcode value="42" symbology="datamatrix" />
+```
+
+---
+
 ## Reporting a bug
 
 If an error comes from inside this package and none of the entries above

package/lib/components/components.css

@@ -206,3 +206,4 @@
 @import "./background-shared.css";
 @import "./ui/widgets/drawing/drawing.css"; /* @nxgt/material/draw: role colours, focus ring */
 @import "./ui/widgets/drawing/drawing-animate.css";
+@import "./ui/widgets/barcode/barcode.css"; /* @nxgt/material/barcode: symbol colours, label sheet */