morphicons 1.5.0 → 1.6.0

package/README.md

@@ -230,6 +230,44 @@ It *is* `createMorph` — only the write target differs — so springs, reduced
 
 **Cost.** A live inline `<path>` gets the cheapest possible write; a mask element additionally makes the browser re-rasterize the mask and repaint the masked box every frame (main thread, no compositor-only path). Great for toggles and short lists (menu↔close, chevrons, play↔pause); for icon-heavy views, the inline-SVG bindings remain the leanest option — same styling, one less indirection.
 
+### `canvasTarget` — 2D canvas out
+
+For surfaces where the DOM never enters: **the icon stops being a document node and becomes pixels you own.** The platform does the heavy lifting — `Path2D` parses `d` strings natively — so every frame is one `stroke(new Path2D(d))` on whatever you hand it: an `HTMLCanvasElement`, an `OffscreenCanvas`, or a bare 2D context (what a worker, or a host that already owns the context, has in hand).
+
+```ts
+import { canvasTarget } from "morphicons/adapters";
+import { createMorph } from "morphicons/dom";
+
+const m = createMorph(canvasTarget(canvas), MENU);
+m.morphTo(X, "snappy");
+// the canvas is a live texture: gl.texImage2D(gl.TEXTURE_2D, ..., canvas)
+```
+
+Once the icon is pixels, everything the SVG model can't reach opens up:
+
+- **Canvas-first apps** with no DOM to put an icon in: Konva, Fabric.js, PixiJS, games, chart draws, tldraw-style editors.
+- **`OffscreenCanvas` + workers**: the whole morph runs off the main thread.
+- **Native export**: `toBlob()` for PNG sprites, `captureStream()` + MediaRecorder for the morph as a video asset.
+- **An animated favicon**: draw, `toDataURL()`, swap the `<link>`.
+- **HUDs over video or fullscreen surfaces**: same buffer as the player or the game, no DOM layer on top.
+- **WebGL textures**: the canvas is a ready `texImage2D` source — shader effects over live icons are one branch of this list, not its headline.
+- Down the road, the same gesture (`PathEl` → `Path2D`) is `PathEl` → `SkPath`: a react-native-skia / CanvasKit target would consume the identical contract.
+
+It *is* `createMorph` — springs, mid-flight interruption and reduced motion behave identically. The target maps the icon grid onto whatever backing store it finds, per write: min-side scale, centered (the canvas equivalent of `preserveAspectRatio="xMidYMid meet"`), so non-square canvases letterbox and devicePixelRatio is simply whatever you sized the backing store to. Color cascades: the `color` option wins; without it, a CSS-styled canvas contributes its computed `color` (the moral equivalent of `currentColor`, which canvas lacks — read lazily, once); where CSS can't reach (OffscreenCanvas, workers) the context's current `strokeStyle` stands, which is the idiomatic canvas contract. `strokeWidth` and `viewBox` mirror the other adapters; `clear: false` skips the per-frame clear for manual compositing and trails.
+
+**Hosts with their own render loop.** Don't hand a Konva/Chart.js/game context to a morph — the driver writes on its own rAF and the two clocks fight over the frame. Give the icon a small dedicated canvas and composite it into the scene (`drawImage`, `Konva.Image`, a texture upload), with `onWrite` as the dirty signal:
+
+```ts
+const icon = new OffscreenCanvas(64, 64);
+const target = canvasTarget(icon, {
+  color: "#e8eaed",                      // CSS can't reach an OffscreenCanvas
+  onWrite: () => { textureDirty = true } // re-upload / blit on the host's next frame
+});
+const m = createMorph(target, PLAY);
+```
+
+**Cost.** The cheapest target of the three: no layout, no DOM paint — one native path parse and one stroke rasterization per frame, on a canvas that is typically small. 0.48 KB gzip standalone, the lightest adapter yet.
+
 ## Icon library compatibility
 
 morphicons has no per-library adapters — any icon set that meets these requirements works out of the box:
@@ -407,9 +445,10 @@ CI budget (size-limit, gzip) as an anti-regression tripwire — gates carry ~10%
 |---|---|---|
 | `morphicons` (core) | 6.60 KB | 7 KB |
 | `morphicons/dom` (core + driver) | 7.12 KB | 7.5 KB |
-| `morphicons/adapters` (aggregate — grows by design) | 4.03 KB | 4.4 KB |
+| `morphicons/adapters` (aggregate — grows by design) | 4.32 KB | 4.8 KB |
 | `adapters` › `{ svgToIcon }` alone | 3.34 KB | 3.7 KB |
 | `adapters` › `{ maskTarget }` alone | 0.70 KB | 0.8 KB |
+| `adapters` › `{ canvasTarget }` alone | 0.48 KB | 0.55 KB |
 | `morphicons/react` (all, react external) | 8.01 KB | 8.5 KB |
 | `morphicons/react-native` (all, react/rn/rnsvg external) | 8.37 KB | 9 KB |
 | `morphicons/vue` (all, vue external) | 8.04 KB | 8.5 KB |

package/dist/adapters.d.ts

@@ -1,5 +1,49 @@
 import { n as IconInput } from "./types-JAF3s76Y.js";
 import { i as PathEl } from "./index-DXp5b6BU.js";
+//#region src/adapters/canvas.d.ts
+/** The 2D context surface the target drives — structural, so a real
+ *  CanvasRenderingContext2D, an OffscreenCanvasRenderingContext2D or a test
+ *  fake all satisfy it. Only what canvasTarget actually touches. */
+interface Canvas2DContext {
+  canvas: {
+    width: number;
+    height: number;
+  };
+  lineWidth: number;
+  lineCap: string;
+  lineJoin: string;
+  strokeStyle: string | object;
+  setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+  clearRect(x: number, y: number, w: number, h: number): void;
+  stroke(path: object): void;
+}
+/** Anything that can hand out a 2D context (an HTMLCanvasElement, an
+ *  OffscreenCanvas, or a fake in tests). */
+interface CanvasSurface {
+  getContext(contextId: "2d"): Canvas2DContext | null;
+}
+interface CanvasTargetOptions {
+  /** Grid the icon's coordinates live on (Lucide/Iconify default: "0 0 24 24").
+   *  Used to map the geometry onto the backing store. */
+  viewBox?: string;
+  /** Stroke width in grid units (Lucide's default is 2). */
+  strokeWidth?: number;
+  /** Stroke color. Defaults to the canvas' computed CSS color when it is a
+   *  styled element; otherwise the context's current `strokeStyle` stands. */
+  color?: string;
+  /** Clear the canvas before each frame. Turn off for manual compositing or
+   *  trails — every frame then draws on top of the last. Default true. */
+  clear?: boolean;
+  /** Called after every drawn frame — the texture consumer's dirty signal
+   *  (e.g. re-upload the canvas with `texImage2D`, or blit it into a scene). */
+  onWrite?: () => void;
+}
+/** Adapts a canvas (or its 2D context) into a `PathEl` whose writes stroke
+ *  the morph's geometry onto the canvas, so
+ *  `createMorph(canvasTarget(canvas), icon)` animates pixels instead of an
+ *  inline `<svg><path>`. */
+declare function canvasTarget(surface: CanvasSurface | Canvas2DContext, opts?: CanvasTargetOptions): PathEl;
+//#endregion
 //#region src/adapters/mask.d.ts
 /** The subset of an element's inline style the mask target writes — structural
  *  so a real HTMLElement's `.style` satisfies it (and a test fake supplies
@@ -52,4 +96,4 @@ declare function maskTarget(el: MaskEl, opts?: MaskTargetOptions): MaskPathEl;
  *  an IconNode. */
 declare function svgToIcon(markup: string): IconInput;
 //#endregion
-export { type MaskEl, type MaskPathEl, type MaskStyle, type MaskTargetOptions, maskTarget, svgToIcon };
+export { type Canvas2DContext, type CanvasSurface, type CanvasTargetOptions, type MaskEl, type MaskPathEl, type MaskStyle, type MaskTargetOptions, canvasTarget, maskTarget, svgToIcon };

package/dist/adapters.js

@@ -1,4 +1,46 @@
 import { t as fitIcon } from "./normalize-CYnN3Npw.js";
+//#region src/adapters/canvas.ts
+/** Adapts a canvas (or its 2D context) into a `PathEl` whose writes stroke
+*  the morph's geometry onto the canvas, so
+*  `createMorph(canvasTarget(canvas), icon)` animates pixels instead of an
+*  inline `<svg><path>`. */
+function canvasTarget(surface, opts = {}) {
+	if (typeof Path2D === "undefined") throw new Error("morphicons: canvasTarget needs Path2D (browser or worker)");
+	const ctx = "getContext" in surface ? surface.getContext("2d") : surface;
+	if (!ctx) throw new Error("morphicons: canvasTarget needs a 2D context");
+	const vb = (opts.viewBox ?? "0 0 24 24").trim().split(/[\s,]+/).map(Number);
+	const [mx, my, vw, vh] = [
+		vb[0] || 0,
+		vb[1] || 0,
+		vb[2] || 24,
+		vb[3] || vb[2] || 24
+	];
+	const stroke = opts.strokeWidth ?? 2;
+	const clear = opts.clear !== false;
+	let color = opts.color;
+	let cssPending = color === void 0 && "style" in ctx.canvas;
+	return { setAttribute(name, value) {
+		if (name !== "d") return;
+		if (cssPending) {
+			cssPending = false;
+			color = getComputedStyle?.(ctx.canvas).color || void 0;
+		}
+		const c = ctx.canvas;
+		const s = Math.min(c.width / vw, c.height / vh);
+		if (clear) {
+			ctx.setTransform(1, 0, 0, 1, 0, 0);
+			ctx.clearRect(0, 0, c.width, c.height);
+		}
+		ctx.setTransform(s, 0, 0, s, (c.width - vw * s) / 2 - mx * s, (c.height - vh * s) / 2 - my * s);
+		ctx.lineWidth = stroke;
+		ctx.lineCap = "round";
+		ctx.lineJoin = "round";
+		if (color !== void 0) ctx.strokeStyle = color;
+		ctx.stroke(new Path2D(value));
+		opts.onWrite?.();
+	} };
+}
+//#endregion
 //#region src/adapters/mask.ts
 const SVG_NS = "http://www.w3.org/2000/svg";
 let seq = 0;
@@ -136,4 +178,4 @@ function svgToIcon(markup) {
 	return vb ? fitIcon(node, vb[1]) : node;
 }
 //#endregion
-export { maskTarget, svgToIcon };
+export { canvasTarget, maskTarget, svgToIcon };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "morphicons",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Universal morphing for stroke-based icons with spring physics — zero runtime dependencies",
   "license": "MIT",
   "author": "Guillermo (https://guillermolg.com)",
@@ -129,7 +129,7 @@
       "name": "adapters (aggregate — grows by design, see per-export gates)",
       "path": "dist/adapters.js",
       "import": "*",
-      "limit": "4.4 KB",
+      "limit": "4.8 KB",
       "gzip": true
     },
     {
@@ -146,6 +146,13 @@
       "limit": "0.8 KB",
       "gzip": true
     },
+    {
+      "name": "adapters › canvasTarget (per-export shakeability gate)",
+      "path": "dist/adapters.js",
+      "import": "{ canvasTarget }",
+      "limit": "0.55 KB",
+      "gzip": true
+    },
     {
       "name": "core + dom + react (MorphIcon, react external)",
       "path": "dist/react.js",