@nxgt/material 3.6.0 → 3.7.1

package/docs/troubleshooting.md

@@ -389,6 +389,19 @@ words in your error.
 - [My gradient colour override stopped working](#my-gradient-colour-override-stopped-working)
 - [A preset's items use class names my own CSS also uses (`fl`, `d1`, `k1`, `mo`)](#a-presets-items-use-class-names-my-own-css-also-uses-fl-d1-k1-mo)
 
+**Drawing**
+
+- [`A decorative drawing has an interactive node: give the Drawing a title instead`](#a-decorative-drawing-has-an-interactive-node-give-the-drawing-a-title-instead)
+- [`Unsafe drawing at <tag>: <reason>` from a scene or a JSX drawing](#unsafe-drawing-at-tag-reason-from-a-scene-or-a-jsx-drawing)
+- [`Tones "a" and "b" meet on one element: use two nodes in a group`](#tones-a-and-b-meet-on-one-element-use-two-nodes-in-a-group)
+- [`No colour for "brand": pass palette: { "brand": "#rrggbb" }`](#no-colour-for-brand-pass-palette--brand-rrggbb-)
+- [`shapeOutline: unknown shape "x"; expected one of SHAPE_NAMES (…)`](#shapeoutline-unknown-shape-x-expected-one-of-shape_names-)
+- [`drawingToPng: cannot read the image "<url>" (<reason>)…`](#drawingtopng-cannot-read-the-image-url-reason)
+- [`drawingToPng: the canvas gave no PNG.` and its siblings](#drawingtopng-the-canvas-gave-no-png-and-its-siblings)
+- [A drawing is black, or its role colours do nothing](#a-drawing-is-black-or-its-role-colours-do-nothing)
+- [A Server Component that renders `Drawing` fails](#a-server-component-that-renders-drawing-fails)
+- [`Duplicate identifier 'text'` when importing from `/draw` and `/print`](#duplicate-identifier-text-when-importing-from-draw-and-print)
+
 **Content Security Policy**
 
 - [`[nxgt-material] html.cspNonce is set, but the CSP is in hash mode (the default): set nxgtMaterial({ csp: { mode: 'nonce' } }) or drop html.cspNonce.`](#nxgt-material-htmlcspnonce-is-set-but-the-csp-is-in-hash-mode-the-default-set-nxgtmaterial-csp--mode-nonce---or-drop-htmlcspnonce)
@@ -906,7 +919,7 @@ catalogue's own field messages pass.
 **Why:** it is drawn with `text-error`, the fill colour. The dark `--error` is
 kept dark enough for near-white text on a filled error surface, which makes it
 too dark to read as text on the dark surfaces. Error text has its own token,
-`--error-text`, lightened in the dark theme (5.4:1 on `--background`, 5.0:1 on
+`--error-text`, lightened in the dark theme (5.9:1 on `--background`, 5.3:1 on
 `--card`).
 **Fix:** draw text with `text-error-text`; keep `text-error` for fills,
 borders and icons that stand alone. On a `Button` or `IconButton` drop the
@@ -947,6 +960,15 @@ An app that overrides `--primary` under `:root` and `.dark, [data-theme="dark"]`
 gets `--primary-text` for free; set `--primary-text` after it to choose another
 colour. On an element below the root, set `--color-primary-text`.
 
+The same goes for a primary mark that is not text: a bar, a dot, a selected or
+focused border, a ring or a spinner arc. In dark, `--primary` is only 2.1 to
+2.5:1 on the surfaces, under the 3:1 of WCAG 1.4.11. Draw it with
+`bg-primary-indicator`, `border-primary-indicator`, `ring-primary-indicator` or
+`stroke-primary-indicator`: `--primary-indicator` is `--primary` in light and
+`--primary` mixed 25 % with white in dark (3.7:1 or more on `--background`,
+`--card` and `--muted`). It follows an app's own `--primary`; set
+`--primary-indicator` after it to choose another dark colour.
+
 ### `expectTapTargets` reports a checkbox, switch or chip remove button under 44px
 
 **When:** a phone project's `expectTapTargets` (`@nxgt/playwright`) lists a
@@ -6788,6 +6810,128 @@ import '@nxgt/material/backgrounds.css'; // every preset
 
 ---
 
+## Drawing
+
+How to use it is in the [Drawing guide](guides/drawing.md); the engine's own
+errors (`Invalid colour`, `Invalid path data`, `Unsupported scene version`,
+`[pdf] A drawing mask is not supported in a PDF: dropped.`) are in the
+[core troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#drawing).
+
+### `A decorative drawing has an interactive node: give the Drawing a title instead`
+
+**When:** a `Drawing` with `decorative` renders, or contains, a node with `onClick` (or any event), `interactive`, or an entry in `handlers`. It throws on the render.
+**Why:** `decorative` is `aria-hidden`, and a focusable node inside it would be reachable by keyboard and invisible to assistive technology.
+**Fix:** give the drawing a `title` (and each interactive node a `label`), or drop the events:
+
+```tsx
+<Drawing scene={board} title="Board columns" onNodeClick={open} />
+```
+
+### `Unsafe drawing at <tag>: <reason>` from a scene or a JSX drawing
+
+**When:** `Drawing`, `toSVG`, `compileScene` or `assertSafeDrawing` throws `Unsafe drawing at <image>: href must be http(s), relative or data:image (png, jpeg, gif, webp)` or another reason (`tag not allowed`, `style not allowed`, `<attribute> not finite`, `id used twice`...).
+**Why:** a strict CSP could not accept what the scene would write. From a scene loaded as JSON the cause is usually an `image` `href` (`javascript:`, `file:` or `data:image/svg+xml`), a `className` or node `id` with unusual characters, or a coordinate that is `NaN`.
+**Fix:** correct the value the message names. Check untrusted JSON before drawing it:
+
+```ts
+import { assertSafeDrawing } from '@nxgt/material/draw';
+
+assertSafeDrawing(scene); // throws with the element and the reason
+```
+
+The reasons are listed in the [core troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#unsafe-drawing-at-tag-reason).
+
+### `Tones "a" and "b" meet on one element: use two nodes in a group`
+
+**When:** a node has `fill: tone('brand')` and `stroke: tone('accent')` where both are app tones.
+**Why:** an app tone is carried by one `data-tone` attribute on the element, so an element can have only one.
+**Fix:** one node per tone, in a group, or name a theme tone for one of them:
+
+```tsx
+group({}, [
+	circle({ cx: 20, cy: 20, r: 14, fill: tone('brand', 'container') }),
+	circle({ cx: 20, cy: 20, r: 14, fill: 'transparent', stroke: tone('accent') }),
+]);
+```
+
+### `No colour for "brand": pass palette: { "brand": "#rrggbb" }`
+
+**When:** `toSVG` (the default `colors: 'literal'`) or a PDF meets an app tone or token that has no literal colour.
+**Why:** a standalone SVG has no theme to read, so every token needs a hex; only the theme's own roles have one.
+**Fix:** pass it, or use `colors: 'vars'` for an inline SVG:
+
+```ts
+toSVG(art, { palette: { brand: '#0a7c59' } });
+```
+
+### `shapeOutline: unknown shape "x"; expected one of SHAPE_NAMES (…)`
+
+**When:** `shape('cookie-99', …)` or `morph` is given a name the registry does not have.
+**Why:** a typo, or a name from another library. The message lists the valid ones.
+**Fix:** use a name of `SHAPE_NAMES`, with or without the `m3-` prefix:
+
+```ts
+import { SHAPE_NAMES, shape } from '@nxgt/material/draw';
+
+shape('cookie-9', { x: 0, y: 0, w: 80, h: 80 }); // or 'm3-cookie-9'
+console.log(SHAPE_NAMES);
+```
+
+### `drawingToPng: cannot read the image "<url>" (<reason>)…`
+
+**When:** `drawingToPng` or `downloadDrawingPng` rejects, and the drawing holds an `image` with a URL.
+**Why:** an SVG drawn as an image loads nothing external, so the function fetches each image and inlines its bytes; the browser refused the fetch, almost always CORS. Nothing is left to taint the canvas: the failure is reported before it can happen.
+**Fix:** serve the image with `Access-Control-Allow-Origin`, or put a `data:image/png|jpeg|gif|webp` URL in the scene:
+
+```ts
+image({ href: 'data:image/png;base64,…', x: 0, y: 0, w: 64, h: 64 });
+```
+
+### `drawingToPng: the canvas gave no PNG.` and its siblings
+
+**When:** a PNG fails with one of `drawingToPng: the canvas gave no PNG.`, `drawingToPng: no 2D canvas in this browser.`, `drawingToPng: scale must be above 0.`, `drawingToPng: the drawing has no size.` or `drawingToPng: the browser could not draw the SVG.`.
+**Why:** respectively a canvas the browser refused to encode (usually far too large: `scale` times the drawing's size), no canvas support, a zero or negative `scale`, a live `<svg>` with no `width`, `height` or `viewBox`, and an SVG that does not load as an image.
+**Fix:** lower the `scale`, pass a positive one, give the `<svg>` a `viewBox`, or draw from the scene instead of the live element:
+
+```ts
+await drawingToPng(scene, { scale: 1 });
+```
+
+### A drawing is black, or its role colours do nothing
+
+**When:** a `Drawing` renders in black (or the browser's default colours), whatever its `fill="primary"`.
+**Why:** role colours are classes of `styles.css` (`nxgt-draw-f-primary`...); without the stylesheet nothing maps them. A standalone `toSVG` file does not use classes: it writes hex.
+**Fix:** import the stylesheet once in the app:
+
+```ts
+import '@nxgt/material/styles.css';
+```
+
+### A Server Component that renders `Drawing` fails
+
+**When:** a Next.js or RSC page imports `Drawing`, a primitive, `Sketch` or the animate hooks and the build reports that a hook or a context only works in a Client Component.
+**Why:** `@nxgt/material/draw` is its own entry whose built files carry no `'use client'` directive (the components use hooks).
+**Fix:** render it from a file of yours that starts with `'use client'`; the builders and `toSVG` can stay in the Server Component and pass the scene as a prop:
+
+```tsx
+// drawing-client.tsx
+'use client';
+export { Drawing } from '@nxgt/material/draw';
+```
+
+### `Duplicate identifier 'text'` when importing from `/draw` and `/print`
+
+**When:** TypeScript reports `Duplicate identifier 'text'` (or `Import declaration conflicts with local declaration of 'text'`, or the same for `image`) in a file that imports from both entries.
+**Why:** `@nxgt/material/draw` and `@nxgt/material/print` each export a `text` and an `image`: the first builds a drawing node, the second a PDF block.
+**Fix:** rename one of them:
+
+```ts
+import { text as drawText } from '@nxgt/material/draw';
+import { text } from '@nxgt/material/print';
+```
+
+---
+
 ## Content Security Policy
 
 How to set up the policy is in the [Content Security Policy guide](guides/csp.md).

package/lib/components/animations/scroll.css

@@ -132,7 +132,7 @@
 		z-index: 50;
 		height: 0.25rem;
 		pointer-events: none;
-		background-color: var(--primary);
+		background-color: var(--primary-indicator);
 	}
 	transform-origin: 0 50%;
 	animation: nx-scroll-progress linear both;

package/lib/components/base-content.css

@@ -43,7 +43,7 @@
 				}
 
 				.column-resize-handle {
-					background-color: var(--color-primary);
+					background-color: var(--color-primary-indicator);
 					bottom: -2px;
 					pointer-events: none;
 					position: absolute;

package/lib/components/base.css

@@ -124,7 +124,7 @@
 			height: 0.55em;
 			transform: scale(0);
 			transition: 120ms transform ease-in-out;
-			box-shadow: inset 1em 1em var(--color-primary);
+			box-shadow: inset 1em 1em var(--color-primary-indicator);
 		}
 		input[type="checkbox"]:checked::before {
 			transform: scale(1);

package/lib/components/components.css

@@ -196,3 +196,5 @@
 @import "../backgrounds/css/base.css";
 @import "../backgrounds/css/gradient.css";
 @import "../backgrounds/css/motion.css";
+@import "./ui/widgets/drawing/drawing.css"; /* @nxgt/material/draw: role colours, focus ring */
+@import "./ui/widgets/drawing/drawing-animate.css";

package/lib/components/editor-field-expressive.css

@@ -37,6 +37,11 @@
 		border-color: color-mix(in oklab, var(--primary) 60%, transparent);
 		box-shadow: 0 0 0 3px color-mix(in oklab, var(--primary) 50%, transparent);
 	}
+	/* Dark: the 60 % border is under 3:1 on the card (WCAG 1.4.11). */
+	:is(.dark, [data-theme="dark"])
+	[data-slot="compact-editor"][data-look="expressive"]:focus-within {
+		border-color: var(--primary-indicator);
+	}
 	[data-slot="editor-field"][data-invalid]
 		:is(
 			[data-slot="compact-editor"],

package/lib/components/editor-prose.css

@@ -115,7 +115,7 @@
 		}
 
 		blockquote {
-			border-inline-start: 3px solid var(--primary);
+			border-inline-start: 3px solid var(--primary-indicator);
 			padding-inline-start: 1.1em;
 			color: var(--muted-foreground);
 			font-family: var(--nxgt-prose-heading-font);

package/lib/components/theme-tokens.css

@@ -17,6 +17,11 @@
 	   the violet page (7.9:1 on a Card; the colour itself gives 6.8:1 on the
 	   page); the dark theme lifts it. */
 	--primary-text: color-mix(in oklab, var(--primary) 96%, black);
+	/* Primary drawn as a non-text mark (WCAG 1.4.11, 3:1): an indicator bar or dot,
+	   a selected or focused border, a ring, a spinner arc, a progress fill
+	   (`bg-primary-indicator`, `border-primary-indicator`...). Light is --primary;
+	   the dark theme lifts it. */
+	--primary-indicator: var(--primary);
 	/* --secondary, --success and --info are 0.02 darker than before: on the
 	   violet page tint (--background, 97.3 %) their own 15 % tonal tint gave the
 	   text 4.3 to 4.5:1; now 4.7:1 or more on the page and on a Card. */
@@ -53,7 +58,9 @@
 	--destructive: var(--error);
 	--border: oklch(0.912 0.016 293.7);
 	--input: oklch(0.912 0.016 293.7);
-	--ring: oklch(0.704 0.04 291);
+	/* The focus indicator (WCAG 1.4.11, 3:1): 3.40:1 on --background, 3.69:1 on
+	   --card, 3.23:1 on --muted. */
+	--ring: oklch(0.62 0.04 291);
 	--chart-1: oklch(0.646 0.222 41.116);
 	--chart-2: oklch(0.6 0.118 184.704);
 	--chart-3: oklch(0.398 0.07 227.392);
@@ -86,7 +93,7 @@
 	--sidebar-accent: oklch(0.955 0.012 292);
 	--sidebar-accent-foreground: oklch(0.227 0.017 290);
 	--sidebar-border: oklch(0.912 0.016 293.7);
-	--sidebar-ring: oklch(0.704 0.04 291);
+	--sidebar-ring: oklch(0.62 0.04 291);
 }
 
 .dark,
@@ -102,6 +109,9 @@
 	/* Mixed 60 % toward white (the tonal Button labels' recipe): readable as text
 	   on --background and --card. */
 	--primary-text: color-mix(in oklab, var(--primary) 40%, white);
+	/* --primary itself is 2.5:1 on --background, 2.3:1 on --card and 2.1:1 on
+	   --muted. Mixed 25 % toward white: 4.5:1, 4.1:1 and 3.7:1. */
+	--primary-indicator: color-mix(in oklab, var(--primary) 75%, white);
 	/* Brighter than the light one: it is read as text on the dark surfaces (6.3:1
 	   on --background, 5.8:1 on --card; 4.6:1 on its own 15 % tonal tint over a
 	   Card). A filled secondary surface mixes it toward --background (the opaque
@@ -120,8 +130,10 @@
 	--error: oklch(0.577 0.245 27.325);
 	--error-foreground: oklch(0.995 0.002 291.3);
 	/* --error stays the fill under near-white text; as text it would give only
-	   3.9:1 on --background and 3.5:1 on --card. Lightened, 5.4 and 5.0:1. */
-	--error-text: color-mix(in oklab, var(--error) 80%, white);
+	   3.9:1 on --background and 3.5:1 on --card. Lightened (76 % --error), 5.85
+	   and 5.35:1, and 4.78:1 on a focused error menu item (bg-error/20 over the
+	   popover; 4.45:1 at the former 80 %, which missed 4.5:1 once rendered). */
+	--error-text: color-mix(in oklab, var(--error) 76%, white);
 	/* The light brights: on the dark surfaces they read as text and as the
 	   badge's 60% tint, which keeps its contrast under near-white text (success
 	   7.1:1, info 5.6:1, error 9.1:1). */
@@ -137,6 +149,7 @@
 	--destructive: oklch(0.704 0.191 22.216);
 	--border: oklch(0.301 0.025 291.4);
 	--input: oklch(0.34 0.027 291.4);
+	/* 3.78:1 on --background, 3.45:1 on --card, 3.09:1 on --muted. */
 	--ring: oklch(0.551 0.03 290);
 	--chart-1: oklch(0.488 0.243 264.376);
 	--chart-2: oklch(0.696 0.17 162.48);

package/lib/components/ui/display/period-cards/period-cards.css

@@ -49,8 +49,8 @@
 		pointer-events: none;
 	}
 	[data-slot="period-card"][data-state="current"] {
-		--card-bar: var(--primary);
-		border-color: var(--primary);
+		--card-bar: var(--primary-indicator);
+		border-color: var(--primary-indicator);
 		background: color-mix(in oklab, var(--primary) 7%, var(--card));
 	}
 	[data-slot="period-card"][data-state="past"] {

package/lib/components/ui/media/pdf-viewer/pdf-viewer.css

@@ -9,7 +9,7 @@
 }
 
 .pdf-highlight[data-current] {
-	outline: 2px solid var(--color-primary);
+	outline: 2px solid var(--color-primary-indicator);
 	outline-offset: 1px;
 }
 

package/lib/components/ui/widgets/drawing/drawing-animate.css

@@ -0,0 +1,123 @@
+/* Entry animations (`drawOn` and `appear` of @nxgt/material/draw/animate).
+ * A node carries `nxgt-draw-on` or `nxgt-draw-appear`, a delay step
+ * `nxgt-draw-d-<0..19>` and a duration `nxgt-draw-t-<s|m|l>`: never an inline
+ * style. The delay is the step times `--nxgt-draw-stagger` (60ms), set on the
+ * drawing or an ancestor to speed it up or slow it down. The animations fill
+ * both ways, so a replay (`useDrawingControls`) can find them and the last
+ * frame is the drawing itself: a stroke is traced with a dash as long as its
+ * path (`pathLength` 1), a fill fades in, a node fades and grows in. */
+.nxgt-draw-t-s {
+	--nxgt-draw-dur: 300ms;
+}
+.nxgt-draw-t-m {
+	--nxgt-draw-dur: 600ms;
+}
+.nxgt-draw-t-l {
+	--nxgt-draw-dur: 1000ms;
+}
+.nxgt-draw-d-0 {
+	--nxgt-draw-i: 0;
+}
+.nxgt-draw-d-1 {
+	--nxgt-draw-i: 1;
+}
+.nxgt-draw-d-2 {
+	--nxgt-draw-i: 2;
+}
+.nxgt-draw-d-3 {
+	--nxgt-draw-i: 3;
+}
+.nxgt-draw-d-4 {
+	--nxgt-draw-i: 4;
+}
+.nxgt-draw-d-5 {
+	--nxgt-draw-i: 5;
+}
+.nxgt-draw-d-6 {
+	--nxgt-draw-i: 6;
+}
+.nxgt-draw-d-7 {
+	--nxgt-draw-i: 7;
+}
+.nxgt-draw-d-8 {
+	--nxgt-draw-i: 8;
+}
+.nxgt-draw-d-9 {
+	--nxgt-draw-i: 9;
+}
+.nxgt-draw-d-10 {
+	--nxgt-draw-i: 10;
+}
+.nxgt-draw-d-11 {
+	--nxgt-draw-i: 11;
+}
+.nxgt-draw-d-12 {
+	--nxgt-draw-i: 12;
+}
+.nxgt-draw-d-13 {
+	--nxgt-draw-i: 13;
+}
+.nxgt-draw-d-14 {
+	--nxgt-draw-i: 14;
+}
+.nxgt-draw-d-15 {
+	--nxgt-draw-i: 15;
+}
+.nxgt-draw-d-16 {
+	--nxgt-draw-i: 16;
+}
+.nxgt-draw-d-17 {
+	--nxgt-draw-i: 17;
+}
+.nxgt-draw-d-18 {
+	--nxgt-draw-i: 18;
+}
+.nxgt-draw-d-19 {
+	--nxgt-draw-i: 19;
+}
+.nxgt-draw-on,
+.nxgt-draw-appear {
+	animation-duration: var(--nxgt-draw-dur, 600ms);
+	animation-delay: calc(var(--nxgt-draw-i, 0) * var(--nxgt-draw-stagger, 60ms));
+	animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
+	animation-fill-mode: both;
+}
+.nxgt-draw-on {
+	animation-name: nxgt-draw-trace, nxgt-draw-fill;
+}
+.nxgt-draw-appear {
+	animation-name: nxgt-draw-fade, nxgt-draw-grow;
+	transform-box: fill-box;
+	transform-origin: center;
+}
+@keyframes nxgt-draw-trace {
+	from {
+		stroke-dasharray: 1;
+		stroke-dashoffset: 1;
+	}
+	to {
+		stroke-dasharray: 1;
+		stroke-dashoffset: 0;
+	}
+}
+@keyframes nxgt-draw-fill {
+	from {
+		fill-opacity: 0;
+	}
+}
+@keyframes nxgt-draw-fade {
+	from {
+		opacity: 0;
+	}
+}
+@keyframes nxgt-draw-grow {
+	from {
+		scale: 0.92;
+	}
+}
+@media (prefers-reduced-motion: reduce) {
+	.nxgt-draw-on,
+	.nxgt-draw-appear {
+		animation: none;
+	}
+}