@nxgt/material 3.5.0 → 3.7.0

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/docs/README.md

@@ -21,6 +21,7 @@ detail: every option, the second example, and the traps.
 | [Media players](guides/media.md) | You play video or audio: embedded, audio cards, playlists, chapters and transcript, sound across pages with `MediaPlayerHost`, the lightbox, CSP and keyboard |
 | [Streaming (HLS)](guides/media-streaming.md) | You play `.m3u8` streams in `MediaPlayer` with `@nxgt/material/media-hls` |
 | [Maps](guides/maps.md) | You render Leaflet maps or a location field with `@nxgt/material/map` |
+| [Drawing](guides/drawing.md) | You draw diagrams, badges or illustrations from code with `@nxgt/material/draw`: scenes and JSX primitives, roles and tones, a strict CSP, accessibility and events, sketch, animation, PNG, PDF and e-mail |
 | [Backgrounds](guides/backgrounds.md) | You want a gradient or patterned backdrop: tones, intensity, the opt-in `backgrounds.css`, custom colours, motion and CSP |
 | [SSR](guides/ssr.md) | Your app renders on a server and bundles this package |
 | [Content Security Policy](guides/csp.md) | Your app sends a strict CSP: the directives to use, the components that still inject a `<style>`, the zod and KaTeX settings, self-hosting a font, the per-request nonce |

package/docs/components/data-display.md

@@ -60,7 +60,7 @@ Parts: `Avatar` (the composed one), `AvatarBase`, `AvatarImage`,
 | `shape` | `ShapeName` | — | clips the photo to one of the expressive shapes instead of a circle; the fallback is framed by it when there is no `src` or it fails to load. `alt` names it. Unset: the round avatar, unchanged |
 | `tone` | the eight named tones, or a tone of your own declared in `AppTones` | neutral | the fallback fills with the tone's container, draws its initials or icon in the tone's text colour (`--nxgt-tone-text`, also when there is no `tone`) and a hairline in it (3:1 against the page or card). A loaded photo is not tinted |
 
-The hairline's strength is `--avatar-ring-share`, the share of the tone's text colour mixed into the surface (default `65%`, from `--nxgt-tone-ring-share`; 3:1 or more at that value). Override it in your CSS:
+The hairline's strength is `--avatar-ring-share`, the share of the tone's text colour mixed into the surface (default `68%`, from `--nxgt-tone-ring-share`; 3:1 or more at that value). Override it in your CSS:
 
 ```css
 :root { --avatar-ring-share: 80%; }
@@ -435,7 +435,7 @@ import { StatCard } from '@nxgt/material/components';
 
 Parts: the root carries `data-slot="stat-card"`, `data-variant` and, when a tone applies, `data-tone` (the tone, or `neutral` on a `tonal` or `filled` card without one); the icon wrapper carries `data-slot="stat-card-icon"`. The types `StatCardProps`, `StatCardVariant` and `StatCardValueSize` are exported.
 
-In `filled`, the delta and its trend arrow take the on-colour too (the arrow and the sign still say up or down). The outline's share is `--stat-card-ring-share` (`65%`, or `--nxgt-tone-ring-share` for every ring); it draws the tonal card's border, the filled card's edge in a calm zone and the hairline round the icon chip. Known limit: the dark theme's primary `filled` card has an edge of about 2.4:1 on a `Card` and 2.7:1 on the page (its text is 7:1); a `tonal` card avoids it. See [App tones](../guides/theming.md#app-tones-on-shape-fab-avatar-statcard-and-the-metric-cards).
+In `filled`, the delta and its trend arrow take the on-colour too (the arrow and the sign still say up or down). The outline's share is `--stat-card-ring-share` (`68%`, or `--nxgt-tone-ring-share` for every ring); it draws the tonal card's border, the filled card's edge in a calm zone and the hairline round the icon chip. Known limit: the dark theme's primary `filled` card has an edge of about 2.3:1 on a `Card` and 2.5:1 on the page (its text is 7:1); a `tonal` card avoids it. See [App tones](../guides/theming.md#app-tones-on-shape-fab-avatar-statcard-and-the-metric-cards).
 
 **Storybook:** `Data display/StatCard`, `Data display/StatCard/Tones` · **Vue:** `StatCard`
 

package/docs/components/rich-widgets.md

@@ -10,6 +10,7 @@ the app owns the data.
 | <img src="../previews/rich-widgets-kanban.webp" width="96" alt=""> | [Kanban](#kanban) | Board with columns, swimlanes, WIP limits and drag-and-drop |
 | <img src="../previews/rich-widgets-eventcalendar.webp" width="96" alt=""> | [EventCalendar](#eventcalendar) | Month / week / day / agenda calendar, 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 |
 | <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 |
@@ -309,6 +310,201 @@ Parts: `LineChart`, `AreaChart`, `BarChart`, `PieChart`, `DonutChart`, `Gauge`,
 
 ---
 
+## Drawing
+
+![Drawing](../previews/rich-widgets-drawing.webp)
+
+Vector drawings from `@nxgt/material/draw`: a **scene** of plain data (the
+builders `scene`, `rect`, `path`, `text`... of `@nxgt/material-core/draw`,
+re-exported here) or JSX **primitives** (`Rect`, `Ellipse`, `Circle`, `Line`,
+`Polygon`, `Path`, `Text`, `Group`, `Image`) inside a `Drawing`. Colours are
+theme roles (`primary-container`, `on-primary-container`, `surface`,
+`outline`...), `tone('success')` or free colours; roles are classes that
+`styles.css` maps to the theme's variables, so a drawing follows light and dark
+with no inline `style` (a strict CSP is satisfied). The names `text` and `image`
+clash with `@nxgt/material/print`'s: import one under
+another name. **Its own entry, client-only** (render `Drawing` from a
+`'use client'` file; the builders and `toSVG` run anywhere).
+
+```tsx
+'use client';
+
+import { Circle, Drawing, Rect, Text } from '@nxgt/material/draw';
+
+<Drawing w={200} h={80} title="Release status">
+	<Rect x={0} y={0} w={200} h={80} r={16} fill="primary-container" />
+	<Circle cx={36} cy={40} r={14} fill="primary" />
+	<Text x={64} y={46} fill="on-primary-container">Shipped</Text>
+</Drawing>;
+```
+
+The same drawing from a scene, which a server can send as JSON:
+
+```tsx
+import { Drawing, rect, scene, text } from '@nxgt/material/draw';
+
+const status = scene({ w: 200, h: 80 }, [
+	rect({ x: 0, y: 0, w: 200, h: 80, r: 16, fill: 'primary-container' }),
+	text('Shipped', { x: 100, y: 46, anchor: 'middle', fill: 'on-primary-container' }),
+]);
+
+<Drawing scene={status} title="Release status" />;
+```
+
+### Accessibility
+
+`Drawing` takes `title` **or** `decorative`, never neither: the type enforces it.
+A named drawing is `role="img"` with `aria-label={title}`, never a `<title>`
+element (React 19 would hoist it into the page's head); a `decorative` one is
+`aria-hidden`. A drawing with an interactive node is `role="group"` (an image
+cannot hold focusable children); set `interactive` on a JSX `Drawing` that is
+server rendered so the first markup says so too. An interactive node needs a
+`label`: it is a focusable `role="button"` (it has `onClick`) or `role="img"`,
+Enter and Space click it, and a focus ring (a second, unfilled copy of its
+outline, class `nxgt-draw-ring`) shows on `:focus-visible`; text, and a group with
+no shape, show a CSS outline instead. A decorative
+drawing cannot hold an interactive node: it throws.
+
+### Events
+
+In scene mode, set events by node `id`, or listen to all of them:
+
+```tsx
+<Drawing
+	scene={flow}
+	title="Release flow"
+	handlers={{ review: { onPointerEnter: preview, onFocus: preview } }}
+	onNodeClick={(id, event) => open(id)}
+/>
+```
+
+A node is interactive when its scene node has `interactive: true`, an entry in
+`handlers`, or (JSX) any of `onClick`, `onPointerEnter`, `onPointerLeave`,
+`onPointerDown`, `onPointerUp`, `onFocus`, `onBlur` or `onKeyDown`. A JSX `Group`
+with an event shows its focus as a CSS outline instead of an outline copy
+(a scene `group` keeps the outline copy).
+
+### Text
+
+Wrapped text (`maxWidth`) breaks with Inter's metrics, the same on the server
+and in the first client render. Once mounted, and again when the fonts load,
+the browser re-measures each wrapped text (`exactText`, on by default), so a
+fallback font cannot overflow its box; the lines may move at that point. Set
+`exactText={false}` to keep the metrics' breaks.
+
+### Shapes and layout
+
+`@nxgt/material/draw` re-exports `shape`, `morph`, `SHAPE_NAMES`, `toCubics` and
+`bbox`, `stack`, `grid`, `align`, `distribute` from `@nxgt/material-core`, by
+name (a bundler keeps only the ones you import; `Drawing` alone carries no
+shape library). `shape('cookie-9', { x, y, w, h, fill })` is a path node, so it
+goes to a scene or to `<Path node={...} />`; `morph(a, b, t)` is the path at `t`
+between two shapes or nodes; `stack` and `grid` place labelled boxes.
+
+```tsx
+import { Drawing, Path, shape } from '@nxgt/material/draw';
+
+<Drawing w={120} h={120} title="A cookie">
+	<Path node={shape('cookie-9', { x: 10, y: 10, w: 100, h: 100, fill: 'tertiary' })} />
+</Drawing>;
+```
+
+### Sketch
+
+`@nxgt/material/draw/sketch` draws a drawing by hand. `Sketch` wraps a `Drawing`
+(scene or JSX), or primitives inside a JSX one; `sketch(sceneOrNode, options)`
+does the same to plain data. Strokes are two wobbling passes with a bow,
+ellipses are loose loops, filled shapes are hatched (`fill`: `hachure`,
+`cross-hatch`, `solid`, `none`). Texts and images stay as they are. The wobble
+is seeded (`seed`, else the scene's, else 0): the markup is the same on the
+server and in the browser. Ids, labels, the focus ring and events keep working;
+the hatch lines are fill, so they get no focus ring.
+
+```tsx
+'use client';
+
+import { Drawing, Rect } from '@nxgt/material/draw';
+import { Sketch } from '@nxgt/material/draw/sketch';
+
+<Sketch seed={7} fill="cross-hatch">
+	<Drawing w={200} h={100} title="A sketchy button">
+		<Rect id="go" label="Go" x={10} y={10} w={180} h={80} r={12} fill="primary" stroke="primary" onClick={go} />
+	</Drawing>
+</Sketch>;
+```
+
+Options: `seed`, `roughness` (1; 0 is clean double strokes), `bowing` (1), `fill`
+(`hachure`), `hachureAngle` (-41), `hachureGap` (three stroke widths, at least 4),
+`strokeWidth` (1.5 for a shape that sets none). Types: `SketchProps`,
+`SketchOptions`, `SketchFill`.
+
+### Props
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` / `decorative` | `string` / `true` | required, one of two | the accessible name, or hidden from assistive technology |
+| `scene` | `Scene` | — | draw a scene of plain data (scene mode) |
+| `w`, `h`, `viewBox`, `background`, `children` | `number`, `[x, y, w, h]`, `Paint`, `ReactNode` | — | the size, the view and the primitives (JSX mode) |
+| `handlers`, `onNodeClick` | `Record<id, NodeHandlers>`, `(id, event) => void` | — | events by scene `id` (scene mode); `onNodeClick` in both modes |
+| `interactive` | `boolean` | `false` | JSX mode: the root is a group in the server's markup |
+| `exactText` | `boolean` | `true` | re-measure wrapped text in the browser |
+| `className` | `string` | — | on the `<svg>`; it scales to its container (`max-width: 100%`) |
+
+A `Path` takes `d` (SVG path data), `build` (`(p) => p.moveTo(0, 0).lineTo(10, 10)`)
+or `node` (a ready node, such as a shape; the other props override its style).
+`Text` takes strings and numbers as children (`\n` breaks a line). Every primitive takes the node's style (`fill`, `stroke`, `strokeWidth`, `opacity`,
+`transform`, `clip`, `mask`, `className`, `id`, `label`, `interactive`).
+
+### Animation
+
+`@nxgt/material/draw/animate` animates a drawing without inline style. Wrap a
+scene with `drawOn` (strokes trace themselves, fills fade in) or `appear`
+(nodes fade and grow in), one after the next; they only add class names that
+`styles.css` animates, so a server renders them and a strict CSP is satisfied.
+`useDrawingControls(ref)` replays, pauses, plays or finishes them through the
+Web Animations API, and `MorphDrawing` (or `useSceneMorph` with a `Drawing`)
+springs one scene into another when `active` changes. Under reduced motion
+nothing moves and the last frame shows at once.
+
+```tsx
+'use client';
+
+import { Drawing, scene, shape } from '@nxgt/material/draw';
+import { drawOn, MorphDrawing, useDrawingControls } from '@nxgt/material/draw/animate';
+import { useRef } from 'react';
+
+const flow = drawOn(scene({ w: 240, h: 80 }, [/* ... */]), { dur: 'l' }); // keep scenes stable
+const cookie = scene({ w: 120, h: 120 }, [shape('cookie-9', { id: 'blob', x: 10, y: 10, w: 100, h: 100, fill: 'primary-container' })]);
+const heart = scene({ w: 120, h: 120 }, [shape('heart', { id: 'blob', x: 10, y: 10, w: 100, h: 100, fill: 'tertiary-container' })]);
+
+export function Demo({ liked }: { liked: boolean }) {
+	const ref = useRef<SVGSVGElement>(null);
+	const { replay } = useDrawingControls(ref);
+	return (
+		<>
+			<Drawing ref={ref} scene={flow} title="Release flow" />
+			<button onClick={replay}>Replay</button>
+			<MorphDrawing from={cookie} to={heart} active={liked} title="Like" />
+		</>
+	);
+}
+```
+
+`MorphDrawing` animates the closed paths the two scenes share by `id` (`shape()`
+gives them); any other node (text, a line, an arrowed, interactive or sketched
+one) shows the scene being moved to at once, and `useSceneMorph` cross-fades
+everything. The options of `drawOn` and `appear`, the delay per step
+(`--nxgt-draw-stagger`, 60 ms) and `morphScenes` are in the
+[core drawing reference](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md#animation-nxgtmaterial-coredrawanimate).
+
+How to use it in an app (server rendering, CSP, colours, events, PNG, PDF, e-mail) is in the
+[Drawing guide](../guides/drawing.md). The scene model, colours, ids and the CSP rules are in the
+[vector drawing reference of `@nxgt/material-core`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/draw.md).
+
+**Storybook:** `Rich widgets/Drawing`, `Rich widgets/Drawing/Shapes and layout`, `Rich widgets/Drawing/Sketch`, `Rich widgets/Drawing/Animation`, `Rich widgets/Drawing/PNG export`, `Rich widgets/Drawing/Gallery` · **Vue:** React only for now; the engine is framework-free in core
+
+---
+
 ## EmojiPicker
 
 ![EmojiPicker](../previews/rich-widgets-emojipicker.webp)