@nxgt/material 3.38.0 → 3.41.0

package/docs/guides/charts.md

@@ -63,7 +63,7 @@ export function SalesChart() {
   plot of the right height; the plot is drawn once the browser has measured its
   width, with its final geometry (the entry motion only runs after that).
   Nothing mismatches on hydration.
-- **Types:** `ChartRow`, `RowKey`, `ChartValue`, `ChartSeries`, `ChartAxis`, `ChartXAxis`,
+- **Types:** `ChartRow`, `RowKey`, `ChartValue`, `ChartSeries`, `ChartAxis`, `ChartXAxis`, `ChartBand`, `ChartThreshold`,
   `ChartPoint`, `ChartBaseProps`, `ChartColor`, `ChartShape`, `ChartSlice`,
   `ScatterSeries`, `ScatterPoint`, `ComboSeries`, `ChartRange`,
   `ChartZoomOptions`, `ChartScrollOptions`, `ChartRangeProps`, `HeatColumn`,
@@ -203,6 +203,80 @@ The funnel is one series, so it takes no `legend`, `hidden` or `grid`; the round
 charts take no `grid`, and the heat map no `hidden`, `grid` or `patterns` (these
 are left out of their props types).
 
+## Reading values against a reference
+
+`LineChart` (and `AreaChart`, which takes the same props) can draw the range a
+value is read against, so it is not painted outside the chart where the
+tooltip, the summary and the table would miss it.
+
+```tsx
+'use client';
+import { LineChart } from '@nxgt/material/charts';
+import type { ChartBand, ChartPoint, ChartThreshold } from '@nxgt/material/charts';
+
+// Module-level (or memoized): the arrays and the function key the summary and the table.
+const bands: ChartBand[] = [
+  { from: 40, to: 60, label: 'Normal range', tone: 'success' },
+];
+const thresholds: ChartThreshold[] = [
+  { value: 70, label: 'Upper limit', tone: 'error' },
+  { value: 30, label: 'Lower limit', tone: 'info', dash: false },
+];
+const toneOf = (point: ChartPoint) =>
+  point.value > 70 ? 'error' : point.value > 60 ? 'warning' : point.value < 40 ? 'info' : undefined;
+
+<LineChart
+  title="Daily readings"
+  data={readings}
+  x="day"
+  series={[{ key: 'reading', label: 'Reading' }]}
+  points
+  bands={bands}
+  thresholds={thresholds}
+  pointTone={toneOf}
+  toneLabels={{ error: 'Critical', warning: 'High', info: 'Low' }}
+/>;
+```
+
+| Prop | Effect |
+| --- | --- |
+| `bands` | `{ from, to, label, tone? }[]`: a wash across the plot behind the lines, with its `label` inside it at the left. `from` and `to` may come in either order. |
+| `thresholds` | `{ value, label, tone?, dash? }[]`: a horizontal line behind the series with its `label` above it at the right end; dashed unless `dash: false`. |
+| `pointTone` | `(point: ChartPoint, series: ChartSeries) => Tone \| undefined`: the tone of one value. It is given the point `onPointClick` gets, so `point.index` is the row of the full `data` even when the chart is zoomed. |
+| `toneLabels` | `{ [tone]: word }`: the word of each tone, in your language and domain. Unset, the library's neutral word ("Error", translated by `material.charts.tone.*`); an app tone you declared falls back to its own name. |
+
+**The value axis holds them.** Unless `yAxis.min` and `yAxis.max` pin it, the
+axis grows to include every band end and threshold, so none is out of view.
+With a pinned axis a band is clipped to the plot and a threshold outside it is
+not drawn (it stays in the summary and the table). The scales are the chart's
+own, so a `zoom` window, a phone `scroll` and a resize keep them right.
+
+**The words are carried everywhere the picture is.**
+
+- The **tooltip** and the **live status** add the tone's word to a toned
+  value: `Day 4: Reading 63 (High)`.
+- The **summary** lists the ranges and lines (`Reference ranges: Normal range:
+  40 to 60. Thresholds: Upper limit: 70`), says how many values of each series
+  lie outside each band (`Reading: 5 of 12 points outside Normal range.`) and
+  counts the tones (`Reading: 2 High, 1 Critical, 2 Low, of 12 points.`). Over
+  a `zoom` window it counts the window's rows.
+- **View data** gets a column after each toned series (`Reading tone`) and a
+  list of the ranges and lines under the table.
+
+**Never colour alone.** A toned point is drawn as a ring in the tone's colour
+round the value (the series' own shape inside the ring with `patterns`), so it
+differs from an untoned dot by its form. A band is a decorative tint: the
+label, the summary and the table carry its meaning. Labels use the tone's text
+colour (4.5:1) on a card-coloured halo, lines and rings hold 3:1, and in
+forced colours the band is outlined and the lines, labels and rings use system
+colours. Nothing animates: reduced motion changes nothing here. Labels are
+cut to 45% of the plot's width, and a label in a right-to-left script is set
+right to left (the plot itself is never mirrored, see
+[Right-to-left pages](#right-to-left-pages)).
+
+A custom `tooltip` function receives the points as before; read the tone from
+your own `pointTone` if it should show the word.
+
 ## Shared props
 
 Every chart takes the shared props (`ChartBaseProps`):
@@ -398,7 +472,9 @@ keyboard behaviour.
   contrast alone, so the heat map is exempt from the 3:1 non-text rule for that
   step, and **View data** (the whole matrix as a table) is the accessible
   fallback; the number in a cell keeps 4.5:1 against its own fill.
-- **Never colour alone:** `patterns` adds shapes, dashes and fill patterns.
+- **Never colour alone:** `patterns` adds shapes, dashes and fill patterns; a
+  toned point is a ring and its word is in the tooltip, the summary and the
+  table ([Reading values against a reference](#reading-values-against-a-reference)).
 - **Reduced motion:** with `prefers-reduced-motion`, the final geometry shows at
   once with a short 120ms fade; there is no bounce, draw-in or morph, and the
   crosshair jumps.

package/docs/guides/forms.md

@@ -508,9 +508,9 @@ or fails validation.
 
 | Field · wrapper | Form value | Empty default |
 | --- | --- | --- |
-| `DateField` · `DateFormField` | `Date \| undefined` (not an ISO string) | `undefined` |
+| `DateField` · `DateFormField` | `Date \| undefined` (not an ISO string). With `timeZone`, still the true instant (the field shows and edits that zone's wall clock); with `showTimePicker`, `undefined` until the date and the time are both complete | `undefined` |
 | `DateRangeField` · `DateRangeFormField` | `DateRange \| undefined`: `{ from: Date \| undefined; to?: Date }` | `undefined` |
-| `TimeField` · `TimeFormField` | `Date \| undefined`. With `asString`: `'HH:mm'`. While empty it shows its `placeholder` | `undefined` / `''` |
+| `TimeField` · `TimeFormField` | `Date \| undefined` (with `timeZone`, the true instant). With `asString`: `'HH:mm'`. While empty it shows its `placeholder` | `undefined` / `''` |
 | `DurationField` · `DurationFormField` | `number \| null`: total minutes (hours × 60 + minutes) | `null` |
 
 ### Selection & choice

package/docs/guides/i18n.md

@@ -371,7 +371,8 @@ date") and `material.dates.apply` on its Apply button ("Apply",
 "Appliquer"); the range itself is written by `Intl.DateTimeFormat`'s
 `formatRange` in the field's locale. On a phone's sheet, the switch to the
 large typed field is named `material.dates.type-date` ("Type the date",
-"Saisir la date") on `DateField` and `material.dates.type-range` ("Type the
+"Saisir la date") on `DateField` (`material.dates.type-date-time`, "Type the date and
+time", "Saisir la date et l’heure", with `showTimePicker`) and `material.dates.type-range` ("Type the
 dates", "Saisir les dates") on `DateRangeField`. Its hero says
 `material.dates.select-date` ("Select date", "Choisir la date") while the date
 is empty, `material.dates.select-dates` on `DateRangeField`, and the Cancel of
@@ -403,7 +404,7 @@ fichier.") when it cannot show it, `material.file-preview.download`
 "Seuls les premiers {size} de ce fichier sont affichés.") under a text cut
 by the size cap; the text or Markdown it shows scrolls in a region named by
 `material.file-preview.content` ("Contents of {name}", "Contenu de {name}").
-A `ServerTable` bulk action with a list entry reads `material.server-table.bulk-action` ("{label} ({count})", the same in French) and is named by `material.server-table.bulk-action-name` ("{label} {count, plural, one {# row} other {# rows}}"; "{label} : {count, plural, one {# ligne} other {# lignes}}").
+A `ServerTable` bulk action with a list entry reads `material.server-table.bulk-action` ("{label} ({count})", the same in French) and is named by `material.server-table.bulk-action-name` ("{label} {count, plural, one {# row} other {# rows}}"; "{label} : {count, plural, one {# ligne} other {# lignes}}"). Past the action's `max` the notice that replaces its button reads `material.server-table.bulk-max-notice` ("Select {max, plural, one {# row} other {# rows}} or fewer to {label}"; "Sélectionnez {max, plural, one {# ligne} other {# lignes}} ou moins pour {label}"), unless the action gives its `maxNotice`; an action's `name` replaces `bulk-action-name`.
 `ServerTable`'s own live region (without `filter`) says
 `material.server-table.results` once a new query is answered ("{count,
 plural, =0 {No results} one {# result} other {# results}}"; "{count, plural,

package/docs/roadmap.md

@@ -482,6 +482,13 @@ version they shipped in, and planned entries may name the major they target.
   slider handles) and a phone scroll that opens on the latest point. The
   light `--chart-4` is now a purple. Client-only, like `/editor`.
   ([Charts](guides/charts.md))
+- **Reference bands, thresholds and point tones on the line chart** — `bands`
+  shade a range of the value axis, `thresholds` draw labelled lines, and
+  `pointTone` rings the values that need a word (`toneLabels` gives the words).
+  The words reach the tooltip, the live status, the summary (values outside a
+  band, tone counts) and a tone column of "View data"; the axis grows to hold
+  them and a zoom window keeps them right.
+  ([Reading values against a reference](guides/charts.md#reading-values-against-a-reference))
 
 - **The page's title in the app bar, a text breadcrumb root and the tenant in the menu** —
   a route's `handle.title` (a node, or a function of the match like

package/docs/troubleshooting.md

@@ -6358,9 +6358,17 @@ names "Start time" and "End time". Every pick is committed as it is made, and
 OK only closes the picker. Cancel puts back the value the picker opened with
 (it fires `onValueChange` only if something changed); closing the picker in
 another way (Escape, a drag, a click outside) keeps what was picked.
-**Fix:** drive the tiles:
+A `DateField` with `showTimePicker` also types the time in the field itself
+(`spinbutton`s "Hours", "Minutes" and, on a 12-hour clock, "AM / PM", in the
+same group as the date's), so while the popover is open `getByRole('spinbutton',
+{ name: 'Hours' })` can match two: the field's and the tile's. A day clicked in
+the calendar keeps the time of day.
+**Fix:** drive the tiles, scoped to the popover (or type in the field's group):
 
 ```ts
+const popover = screen.getByRole('dialog');
+await user.click(within(popover).getByRole('button', { name: 'Increase hours' }));
+// or type: within(screen.getByRole('group', { name: 'Starts' })).getByRole('spinbutton', { name: 'Hours' })
 const start = screen.getByRole('group', { name: 'Start time' });
 await user.click(within(start).getByRole('button', { name: 'Increase hours' }));
 await user.click(screen.getByRole('button', { name: 'OK' }));

package/lib/components/components.css

@@ -150,6 +150,7 @@
 @import "./ui/widgets/native-charts/native-charts-round.css";
 @import "./ui/widgets/native-charts/native-charts-heat.css";
 @import "./ui/widgets/native-charts/native-charts-points.css";
+@import "./ui/widgets/native-charts/native-charts-reference.css";
 @import "./ui/widgets/native-charts/native-charts-zoom.css";
 /* The editor's documents: `.nxgt-prose`, shared with the viewer. */
 @import "./editor-prose.css";

package/lib/components/ui/widgets/native-charts/native-charts-reference.css

@@ -0,0 +1,102 @@
+/* A line chart's reference bands, threshold lines and toned points. Reached
+ * from components.css.
+ *
+ * A band is a wash across the plot, behind the lines: decorative, since its
+ * label (read aloud by the summary and listed under "View data") carries the
+ * meaning. A tone paints it with the tone itself at 12%; without one it is
+ * the foreground at 6%. Labels and threshold lines use the tone's text
+ * colour (4.5:1 on the card, both themes) or the foreground, and sit on a
+ * card-coloured halo so a line passing behind them does not cut the letters.
+ * A toned point is a ring round the value: a shape, never colour alone. */
+.nxgt-chart-ref-band {
+	fill: var(--foreground);
+	opacity: 0.06;
+}
+.nxgt-chart-ref-band[data-tone] {
+	fill: var(--nxgt-tone);
+	opacity: 0.12;
+}
+.nxgt-chart-ref-line {
+	stroke: var(--nxgt-chart-axis);
+	stroke-width: 1.5;
+	stroke-dasharray: 6 4;
+}
+.nxgt-chart-ref-line[data-dash="false"] {
+	stroke-dasharray: none;
+}
+.nxgt-chart-ref-line[data-tone] {
+	stroke: var(--nxgt-tone-text);
+}
+.nxgt-chart-ref-label {
+	fill: var(--foreground);
+	font-size: 11px;
+	font-weight: 600;
+	paint-order: stroke;
+	stroke: var(--card);
+	stroke-width: 3px;
+	stroke-linejoin: round;
+	pointer-events: none;
+}
+.nxgt-chart-ref-label[data-tone] {
+	fill: var(--nxgt-tone-text);
+}
+.nxgt-chart[data-phone] .nxgt-chart-ref-label {
+	font-size: 10px;
+}
+
+.nxgt-chart-tone-ring {
+	fill: var(--card);
+	stroke: var(--nxgt-tone-text);
+	stroke-width: 2;
+}
+.nxgt-chart-tone-dot {
+	fill: var(--nxgt-tone-text);
+}
+
+/* The tone's word in the tooltip, with the ring the plot draws. */
+.nxgt-chart-tip-tone {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	color: var(--nxgt-tone-text);
+	font-size: 12px;
+	font-weight: 600;
+}
+
+/* Under "View data": the ranges and lines read as a list. */
+.nxgt-chart-table-notes {
+	margin: 8px 0 0;
+	padding: 0;
+	list-style: none;
+	color: var(--muted-foreground);
+	font-size: 12px;
+}
+
+@media (forced-colors: active) {
+	.nxgt-chart-ref-band {
+		fill: Canvas;
+		stroke: GrayText;
+		stroke-width: 1;
+		stroke-dasharray: 2 3;
+		opacity: 1;
+	}
+	.nxgt-chart-ref-line,
+	.nxgt-chart-ref-line[data-tone] {
+		stroke: CanvasText;
+	}
+	.nxgt-chart-ref-label,
+	.nxgt-chart-ref-label[data-tone] {
+		fill: CanvasText;
+		stroke: Canvas;
+	}
+	.nxgt-chart-tone-ring {
+		fill: Canvas;
+		stroke: Highlight;
+	}
+	.nxgt-chart-tone-dot {
+		fill: Highlight;
+	}
+	.nxgt-chart-tip-tone {
+		color: CanvasText;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.38.0",
+	"version": "3.41.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -362,7 +362,7 @@
 		"docs:previews": "rm -rf node_modules/.cache/nxgt-preview-free/missing && NXGT_PREVIEW_FREE=1 vitest run --project previews && bun .storybook/preview-free-report.ts"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.39.0",
+		"@nxgt/material-core": "^0.40.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",