@nxgt/material 3.103.0 → 3.105.0

package/docs/guides/field-look-refined.md

@@ -41,7 +41,7 @@ import { TextField } from '@nxgt/material/components';
 | --- | --- |
 | `TextField` and the `*Field` text wrappers | `leading` / `trailing` icons and actions are muted with no well fill; a text unit (`"/ 20"`, a currency code) sits inline at the end in muted text. `CurrencyField` follows |
 | `NumberField`, `PercentField`, `CalculatorField` | one `role="group"` box; the value is end-aligned in tabular figures, the suffix hugs it, the Decrease and Increase buttons are a tinted round pair at the end (the `DurationField` look), no dividers |
-| `QuantityField`, `AgeField` | the value, the unit and the pair share one box; the unit is a chip that opens a menu |
+| `QuantityField`, `AgeField` | the value, the unit and the pair share one box; the unit is a chip that opens a menu (no chip without `units` or `allowCustomUnit`) |
 | `NumberField variant="score"` | a big value with its maximum, no box at rest; see [the form fields page](../components/form-fields.md#numberfield) |
 | Date, time and duration fields | the shared focus ring, a dashed hairline when read-only, the recessed surface when disabled |
 
@@ -49,7 +49,7 @@ import { TextField } from '@nxgt/material/components';
 
 - The `NumberField` order is the input, Decrease, Increase (it was Decrease,
   input, Increase). With a `CalculatorField`: input, Open calculator,
-  Decrease, Increase. A `QuantityField` is value, unit, Decrease, Increase.
+  Decrease, Increase. A `QuantityField` is value, unit (when it has one), Decrease, Increase.
 - The number box is a `group`. A test that queries an unnamed
   `getByRole('group')` now also matches it: name the one you mean.
 - A `QuantityField` unit is a button named "Unit: mg", not a `combobox`:

package/docs/guides/keypad.md

@@ -170,6 +170,14 @@ written at `=`.
   is not called). `settlement` is `{ status: 'paid', change }` (change may be
   `'0'`) or `{ status: 'short', due }`, as exact decimal text. A short payment is a
   settlement, not an error. **The app owns the charge**: the keypad only reports.
+- The settlement row carries a tone: **success** while the payment covers the
+  total (change may be `0`), **warning** while an amount is still due, with the
+  figure emphasised (AA text on a tinted band, light and dark).
+- The keys follow one scheme: digits neutral, the editing keys (C, backspace)
+  one tone, the commit key filled primary, the quick amounts tonal chips in a
+  two-column grid (an odd last chip takes the full row; amounts never
+  truncate). Without a decimal key the 0 key spans nine of the twelve columns,
+  the commit key the other three.
 - `total` must be a valid, non-negative amount (a number or exact decimal text);
   without one the commit key does nothing.
 
@@ -211,7 +219,7 @@ taller keys. Colours and shapes follow the theme and dark mode through
 
 - The keys are native buttons in one `role="group"` (one tab stop, arrow keys
   over the grid), at least 44px on a coarse pointer at 360px and 320px.
-- Each key's glyph is decoration; its name is spoken (Plus, Minus, Double zero,
+- Each key's glyph is decoration; its name is spoken (Plus, Minus, "00, double zero",
   Clear all, Enter, "Amount €20.00" in English, "Amount 20,00 €" in French). `commitLabel` replaces the commit key's name.
 - Results and, in cash, the change or amount still due are announced in a
   polite live region; the display itself is not live, so typing is not read digit by digit.

package/docs/guides/printing.md

@@ -2,7 +2,9 @@
 
 This page covers building PDF documents with `@nxgt/material/print`, turning
 them into a download, a new tab or a server response in one call, and
-shipping them from a browser or from a server bundle that must not crash.
+shipping them from a browser or from a server bundle that must not crash. It
+also covers [`toCsv` and `csvResponse`](#a-csv-export-tocsv-and-csvresponse),
+the CSV export beside `pdfResponse`.
 
 ```bash
 bun add @react-pdf/renderer@^4.9 react-pdf-tailwind
@@ -619,6 +621,8 @@ export function DownloadInvoice({ invoice }: { invoice: Invoice }) {
 | `openPdf(doc \| blob, options?)` | `Promise<void>`: the file opens in a new tab | browser |
 | `usePdfFile(doc \| null, options?)` | `{ blob, url, loading, error, refresh }` | browser (a React hook) |
 | `pdfResponse(doc, options?)` | `Promise<Response>` with the PDF and its headers | Node 18+, Bun |
+| `toCsv(rows, columns, options?)` | `string`: the CSV text | everywhere |
+| `csvResponse(text, fileName?, options?)` | `Response` with the CSV and its headers | Node 18+, Bun |
 | `renderPdfBuffer(doc, options?)` | `Promise<Uint8Array>` | browser, Node 18+, Bun |
 | `renderPdfBlob(doc, options?)` | `Promise<Blob>` of type `application/pdf` | browser, Node 18+, Bun |
 | `renderPdfStream(doc, options?)` | `Promise<ReadableStream<Uint8Array>>` (a Web stream) | Node 18+, Bun |
@@ -825,6 +829,50 @@ of your own. A `PdfReader` in the browser opens the route by its URL, with
 <PdfReader file={{ url: `/invoices/${id}/pdf`, httpHeaders: { Authorization: `Bearer ${token}` } }} fileName={`${number}.pdf`} />
 ```
 
+### A CSV export: `toCsv` and `csvResponse`
+
+A list exported to a spreadsheet is the same job as a PDF: text, then a
+download response. `toCsv` writes the text (RFC 4180) and `csvResponse` wraps
+it, with the same `Content-Disposition` helper as `pdfResponse`. Both are pure
+and server-safe, and add nothing to a client bundle.
+
+```ts
+import { csvResponse, toCsv } from '@nxgt/material/print';
+
+export async function loader() {
+  const items = await getItems();
+  const text = toCsv(
+    items,
+    [
+      { header: 'Name', value: (item) => item.name },
+      { header: 'Amount', value: (item) => item.amount },
+    ],
+    { separator: ';', bom: true },
+  );
+  return csvResponse(text, 'items.csv');
+}
+```
+
+| `toCsv` option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `separator` | `','` \| `';'` \| `'\t'` | `','` | `';'` is what spreadsheets in comma-decimal locales (French, German) expect |
+| `bom` | `boolean` | `false` | Prefixes a UTF-8 byte order mark, which Excel needs to read accents |
+
+- The first line is the headers (`columns[].header`); each row then gives one
+  line from `columns[].value(row)`. Lines end with CRLF, with none after the last.
+- A field holding the separator, a quote, CR or LF is quoted and its quotes
+  doubled. `null` and `undefined` are empty fields; numbers and booleans are
+  written with `String()` and a `Date` as ISO 8601. Format amounts and dates in
+  `value` (see `formatAmount`) when the sheet should show them by locale.
+- A cell starting with `=`, `+`, `-` or `@` is written as it is: a
+  spreadsheet may read it as a formula, so prefix user-typed text yourself when
+  the file is opened by someone other than its author.
+
+`csvResponse(text, fileName?, options?)` answers with `Content-Type: text/csv;
+charset=utf-8`, an attachment `Content-Disposition` (an ASCII `filename` and a
+UTF-8 `filename*`, `.csv` added when missing) and `Cache-Control: private,
+no-store`, which `options.headers` can override.
+
 ### Bytes and streams: `renderPdfBuffer`, `renderPdfStream`
 
 For anything that is not a response (an email attachment, an upload to object
@@ -896,6 +944,8 @@ function renderPdfStream(input: PdfInput, options?: PdfRenderInputOptions): Prom
 function downloadPdf(input: PdfInput | Blob, options?: PdfOutputOptions): Promise<void>;
 function openPdf(input: PdfInput | Blob, options?: PdfOutputOptions): Promise<void>;
 function pdfResponse(input: PdfInput, options?: PdfResponseOptions & PdfRenderInputOptions): Promise<Response>;
+function toCsv<Row>(rows: readonly Row[], columns: readonly CsvColumn<Row>[], options?: CsvOptions): string;
+function csvResponse(text: string, fileName?: string, options?: { headers?: HeadersInit }): Response;
 function contentDisposition(disposition: 'inline' | 'attachment', fileName: string): string;
 function usePdfFile(input: PdfInput | null, options?: PdfRenderInputOptions): PdfFileState;
 

package/docs/roadmap.md

@@ -6,15 +6,6 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
-- **Keypad** — `@nxgt/material/keypad` is a touch and keyboard numeric keypad
-  you can use outside the Calculator widget, for quantity, price, percentage
-  and cash-tendered entry with change. Entry is a decimal or minor units, the
-  display is optional, and the keyboard is on `'focus'` by default (opt in to
-  `'global'`). `useKeypadNumber` and `useKeypadQuantity` bind it to
-  `NumberField`, `PercentField` and `CurrencyField`. A `cash` variant reports
-  `onTender(tendered, settlement)` and leaves the charge to your app. It is
-  styled by `calculator.css`, with no separate stylesheet
-  ([guide](guides/keypad.md)).
 - **Calculator** — `@nxgt/material/calculator` is an exact-decimal calculator
   (Standard, Scientific, point of sale, Financial, Conversion, Programmer;
   every variant but Standard loads on demand)
@@ -391,7 +382,16 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
-- **A status chip that opens its choices** — `StatusMenu` shows a record's
+- **Keypad (3.103.0)** — `@nxgt/material/keypad` is a touch and keyboard numeric keypad
+  you can use outside the Calculator widget, for quantity, price, percentage
+  and cash-tendered entry with change. Entry is a decimal or minor units, the
+  display is optional, and the keyboard is on `'focus'` by default (opt in to
+  `'global'`). `useKeypadNumber` and `useKeypadQuantity` bind it to
+  `NumberField`, `PercentField` and `CurrencyField`. A `cash` variant reports
+  `onTender(tendered, settlement)` and leaves the charge to your app. It is
+  styled by `calculator.css`, with no separate stylesheet
+  ([guide](guides/keypad.md)).
+- **A status chip that opens its choices (3.103.0)** — `StatusMenu` shows a record's
   status as a tone-and-icon chip and changes it in one tap: a menu on a wide
   screen, a bottom sheet on a phone. Statuses not reachable from the current
   one are greyed with the reason, a locked or read-only record explains why,

package/docs/troubleshooting.md

@@ -392,7 +392,7 @@ words in your error.
 - [An empty gap under the `ServerTable` band while nothing is selected](#an-empty-gap-under-the-servertable-band-while-nothing-is-selected)
 - [The focus falls to the page after a `DataTable` bulk action](#the-focus-falls-to-the-page-after-a-datatable-bulk-action)
 - [A test's `getByText('No data available')` finds two elements after a change](#a-tests-getbytextno-data-available-finds-two-elements-after-a-change)
-- [`` [@nxgt/material] DataTable: `virtual` needs `maxHeight`; the rows are not virtualized. ``](#nxgtmaterial-datatable-virtual-needs-maxheight-the-rows-are-not-virtualized)
+- [`` [@nxgt/material] DataTable: `virtual` needs `maxHeight` or `maxHeightClassName`; the rows are not virtualized. ``](#nxgtmaterial-datatable-virtual-needs-maxheight-or-maxheightclassname-the-rows-are-not-virtualized)
 - [`` [@nxgt/material] DataTable: `renderExpandedRow` is ignored while `virtual` is on. ``](#nxgtmaterial-datatable-renderexpandedrow-is-ignored-while-virtual-is-on)
 - [`` [@nxgt/material] DataTable: `virtual` does not apply to the `cards` layout and is ignored. ``](#nxgtmaterial-datatable-virtual-does-not-apply-to-the-cards-layout-and-is-ignored)
 - [`` [@nxgt/material] DataTable: `layout="cards"` needs `renderCard`; each card shows its first column. ``](#nxgtmaterial-datatable-layoutcards-needs-rendercard-each-card-shows-its-first-column)
@@ -7226,14 +7226,15 @@ expect(within(empty).getByText('No data available')).toBeVisible();
 const status = canvasElement.querySelector<HTMLElement>('[data-slot="data-table-status"]')!;
 expect(status).toHaveTextContent('No data available');
 ```
-### `` [@nxgt/material] DataTable: `virtual` needs `maxHeight`; the rows are not virtualized. ``
+### `` [@nxgt/material] DataTable: `virtual` needs `maxHeight` or `maxHeightClassName`; the rows are not virtualized. ``
 
-**When:** in development, a `DataTable` with `virtual` and no `maxHeight` logs this once, and renders its rows paged, as without `virtual`.
+**When:** in development, a `DataTable` with `virtual` and neither `maxHeight` nor `maxHeightClassName` logs this once, and renders its rows paged, as without `virtual`.
 **Why:** virtual rows scroll inside the table's own box; with no height cap there is no box to scroll, and the page would hold every row.
-**Fix:** give the table a height, in pixels or any CSS length:
+**Fix:** give the table a height, in pixels or any CSS length, or a Tailwind class (no inline `style`, for a strict CSP):
 
 ```tsx
 <DataTable data={people} columns={columns} virtual maxHeight="70vh" />
+<DataTable data={people} columns={columns} virtual maxHeightClassName="max-h-[28rem]" />
 ```
 
 ### `` [@nxgt/material] DataTable: `renderExpandedRow` is ignored while `virtual` is on. ``

package/lib/components/ui/display/chip/chip-soft.css

@@ -1,5 +1,5 @@
 /* Chip `tonal` and `filled`, "soft": no outline at all. A low tonal fill that reads as a
- * chip on any surface; selected = the library's primary tint, a hairline
+ * chip on any surface; selected = the library's primary tint (a toggle chip of a tone: the filled tone, last block), a hairline
  * ring in primary-text and a check (the ≥3:1 cue), the label unchanged. In
  * dark the tint is mixed from --primary-text, the light end of the primary,
  * 56 % at rest and 58 % on hover, and the label is white: in all 14 themes
@@ -91,7 +91,8 @@
  * (--nxgt-tone-text, 4.5:1 or more on it). It reads --nxgt-tint-status, not
  * --nxgt-tint-container: the container of a calm zone (calm.css) fades to
  * the surface through its flags, and a status chip keeps its tint there. Selected
- * keeps the primary tint and the foreground label above. */
+ * keeps the primary tint and the foreground label above, except a toggle chip of a
+ * tone (the last block). */
 @layer components {
 	.nxgt-chip[data-look="soft"]:not([data-tone="neutral"]) {
 		--chip-status-base: var(--nxgt-tone);
@@ -121,3 +122,27 @@
 		color: var(--nxgt-tone-text);
 	}
 }
+
+/* A coloured toggle chip, selected: the filled tone (--nxgt-tone) under the
+ * tone's on-colour (--nxgt-tone-on, 4.5:1 or more, light and dark), the ring
+ * in the on-colour so the edge holds on the page. The check stays the
+ * non-colour cue. A status chip (`active`, not a toggle) keeps the tint. */
+@layer components {
+	.nxgt-chip[data-look="soft"]:not([data-tone="neutral"])[data-selected]:is(
+		[aria-checked="true"],
+		[aria-pressed="true"]
+	) {
+		--chip-on: var(--nxgt-tone);
+		--chip-on-hover: color-mix(
+			in oklab,
+			var(--nxgt-tone-on) 10%,
+			var(--nxgt-tone)
+		);
+		--chip-on-ring: color-mix(
+			in oklab,
+			var(--nxgt-tone-on) 55%,
+			var(--nxgt-tone)
+		);
+		--chip-on-text: var(--nxgt-tone-on);
+	}
+}

package/lib/components/ui/primitives/collapsible/collapsible.css

@@ -73,6 +73,15 @@
 	.nxgt-collapsible-trigger[data-variant="tonal"][data-state="open"] {
 		border-radius: 0.75rem;
 	}
+	/* `flush` (text only): label at the left edge, the parent's font, so the
+	 * trigger can sit in a heading. */
+	.nxgt-collapsible-trigger[data-variant="text"][data-flush] {
+		min-height: 1.5rem;
+		padding: 0.25rem 0.25rem 0.25rem 0;
+		border-radius: 0.5rem;
+		font: inherit;
+		letter-spacing: inherit;
+	}
 	.nxgt-collapsible-trigger:hover:not(:disabled) {
 		background-color: color-mix(in oklab, var(--ct-fg) 8%, var(--ct-bg));
 	}

package/lib/components/ui/widgets/calculator/calculator-keys.css

@@ -32,6 +32,9 @@
 .nxgt-calc-key[data-span="3"] {
 	grid-column: span 3;
 }
+.nxgt-calc-key[data-span="9"] {
+	grid-column: span 9;
+}
 .nxgt-calc-key[data-span="6"] {
 	grid-column: span 6;
 }

package/lib/components/ui/widgets/calculator/calculator.css

@@ -137,9 +137,8 @@
 .nxgt-keypad-cash {
 	display: flex;
 	flex-direction: column;
-	gap: 0.25rem;
+	gap: 0.5rem;
 	margin: 0;
-	padding-inline: 0.5rem;
 	font-variant-numeric: tabular-nums;
 }
 .nxgt-keypad-cash > div {
@@ -147,6 +146,7 @@
 	align-items: baseline;
 	justify-content: space-between;
 	gap: 0.5rem;
+	padding-inline: 1.25rem;
 }
 .nxgt-keypad-cash dt {
 	color: var(--muted-foreground);
@@ -156,21 +156,49 @@
 	font-size: 1.25rem;
 	font-weight: 600;
 }
+/* The settlement row is the figure the cashier acts on: success while there
+ * is change to give back, warning while an amount is still due. The figure
+ * takes the tone's AA text colour on its own tinted band. */
+.nxgt-keypad-cash [data-status] {
+	align-items: baseline;
+	padding-block: 0.375rem;
+	border-radius: 1rem;
+}
+.nxgt-keypad-cash [data-status] dd {
+	font-size: 1.625rem;
+	font-weight: 700;
+}
+.nxgt-keypad-cash [data-status="paid"] {
+	background: color-mix(in oklab, var(--success) 20%, var(--background));
+}
+.nxgt-keypad-cash [data-status="paid"] dt,
+.nxgt-keypad-cash [data-status="paid"] dd {
+	color: var(--success-text);
+}
+.nxgt-keypad-cash [data-status="short"] {
+	background: color-mix(in oklab, var(--warning) 22%, var(--background));
+}
+.nxgt-keypad-cash [data-status="short"] dt,
 .nxgt-keypad-cash [data-status="short"] dd {
-	color: var(--destructive);
+	color: var(--warning-text);
 }
 .nxgt-keypad-shortcuts {
-	display: flex;
-	flex-wrap: wrap;
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
 	gap: var(--calc-gap);
 }
 .nxgt-keypad-shortcuts button {
-	flex: 1 1 4.5rem;
 	min-width: 0;
+	padding-inline: 0.875rem;
+	white-space: nowrap;
 	min-height: max(calc(var(--calc-key) * 0.8), 2.75rem);
 	border: 0;
 	border-radius: 9999px;
-	background: var(--secondary-container);
+	background: color-mix(
+		in oklab,
+		var(--primary) 16%,
+		color-mix(in oklab, var(--foreground) 3%, var(--background))
+	);
 	color: var(--foreground);
 	font: inherit;
 	font-weight: 500;
@@ -178,6 +206,9 @@
 	cursor: pointer;
 	touch-action: manipulation;
 }
+.nxgt-keypad-shortcuts button:last-child:nth-child(odd) {
+	grid-column: 1 / -1;
+}
 .nxgt-keypad-shortcuts button:focus-visible {
 	outline: 2px solid var(--ring);
 	outline-offset: 2px;

package/package.json

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