morphicons 1.0.0 → 1.1.1

package/README.md

@@ -13,7 +13,7 @@
   <a href="https://www.morphicons.com"><strong>morphicons.com</strong></a> — live playground
 </p>
 
-Universal morphing for stroke-based icons (Lucide, Feather, Tabler, or your own paths): **any icon morphs into any other** with spring physics. Rotations are never declared by hand — they emerge from the math (2D Procrustes + polar interpolation). Zero runtime dependencies.
+Universal morphing for stroke-based icons (Lucide, Tabler, Heroicons, Iconoir, or your own paths): **any icon morphs into any other** with spring physics. Rotations are never declared by hand — they emerge from the math (2D Procrustes + polar interpolation). Zero runtime dependencies.
 
 ```tsx
 import { MorphIcon } from "morphicons/react";
@@ -86,7 +86,7 @@ interpPolar(plan, 0.5, out);                                 // t ∈ [0, 1]
 const d = serialize(out, plan.items.map(it => it.closed));   // `d` attribute
 ```
 
-Accepts `IconNode` (Lucide's data format, structurally typed — Lucide is neither a dependency nor a peer) or a raw `d` attribute. Feather, Tabler and custom paths work the same.
+Accepts `IconNode` (Lucide's data format, structurally typed — Lucide is neither a dependency nor a peer) or a raw `d` attribute. Tabler, Heroicons, Iconoir and custom paths work the same.
 
 ## Icon library compatibility
 
@@ -94,10 +94,21 @@ morphicons has no per-library adapters — any icon set that meets these require
 
 1. **Stroke-drawn icons.** The geometry must be the stroked centerline (`fill="none"`, color via `stroke`). The whole pipeline — resampling, correspondence, in-flight polylines — assumes strokes; filled or outlined-fill glyphs (Material Symbols, Bootstrap Icons, Remix Icon, Phosphor, Heroicons *solid*) parse fine but won't read correctly in transit.
 2. **Geometry available as data.** Either a raw `d` attribute per icon, or a `[tag, attrs][]` node list (Lucide's IconNode shape) using only `path`, `line`, `circle`, `ellipse`, `rect`, `polyline`, `polygon`. No `<g>` wrappers and no `transform` attributes — coordinates must be literal. Any other tag throws a clear error.
-3. **A shared coordinate space per pair.** Both endpoints of a morph must live on the same grid. Lucide, Feather and Tabler all draw on 24×24 — that's why cross-library morphs just work. The React binding defaults to `viewBox="0 0 24 24"`, overridable via props.
+3. **A shared coordinate space per pair.** Both endpoints of a morph must live on the same grid. Lucide, Tabler, Heroicons and Iconoir all draw on 24×24 — that's why cross-library morphs just work. For a pack on another canvas (Heroicons *solid* on 20, Carbon on 32, Teenyicons on 15), re-grid it once with `fitIcon`:
+
+   ```ts
+   import { fitIcon } from "morphicons";
+
+   const search = fitIcon(carbonSearch, 32);   // 32×32 → the 24 grid
+   const bell   = fitIcon(teenySmallBell, 15); // also "0 0 15 15" or [0, 0, 15, 15]
+   ```
+
+   It returns a plain `d`, so it goes anywhere an icon is accepted. Call it at module scope, not per render. Skipping it doesn't throw — Procrustes is similarity-invariant, so the grid mismatch never reads as false rotation; it lands in σ as an unwanted zoom, and the target draws outside the canvas. The React binding defaults to `viewBox="0 0 24 24"`, overridable via props.
 4. **Uniform stroke.** Cosmetic rather than structural: a consistent stroke width and round caps/joins make in-flight shapes look native. These live on the `<svg>`, not in morphicons.
 
-Beyond the three libraries in the playground, sets known to qualify: **Heroicons** (outline style, 24×24), **Iconoir** (24×24, 1.5px stroke), **Akar Icons** (24×24), **Untitled UI** (24×24) and **Hugeicons** (stroke style, 24×24). **Teenyicons** qualifies too but draws on a 15×15 grid — keep both endpoints on that grid and pass the matching `viewBox`.
+Beyond the libraries in the playground, sets known to qualify on the 24×24 grid — no fitting needed: **Heroicons** (outline style), **Iconoir** (1.5px stroke), **Akar Icons**, **Untitled UI** and **Hugeicons** (stroke style). Off-grid packs work through `fitIcon`: **Teenyicons** (15×15), **Carbon** (32×32), **Heroicons solid** (20×20).
+
+This also covers the [shadcn registry](https://www.shadcn.io/icons), which re-publishes 200+ icon libraries as React components with an inline `<path d>` — pass that `d` straight in, adding `fitIcon` when the pack's `viewBox` isn't 24.
 
 ## Architecture
 
@@ -197,7 +208,7 @@ Let `aᶜᵢ = aᵢ − c_A` and `b̃ᵢ = R(−θ*)·(bᵢ − c_B)/σ*` (B bro
 ```
 P(t) = c(t) + σ*ᵗ · R(t·θ*) · [(1−t)·aᶜᵢ + t·b̃ᵢ]
 
-  c(t)  = lerp(c_A, c_B, t)        linear translation
+  c(t)  = lerp(c_A, c_B, t)        linear translation (block transport under the global hybrid — below)
   t·θ*  = linear angle             (θ* is already in (−π, π], short path)
   σ*ᵗ   = exp(t·ln σ*)             log-linear scale (geodesic in ℝ⁺)
 ```
@@ -209,6 +220,14 @@ Exact at both endpoints (max error ~3.6e-15 in tests). Properties:
 - Mixed cases do both simultaneously and continuously.
 - With spring overshoot (t > 1) the formula **extrapolates** naturally: rotation and scale overshoot slightly and come back — free juice.
 
+**Block transport (global hybrid).** When the whole icon is congruent (§4), lerping each subpath centroid reintroduces the chord disease one level up: every part spins with the shared θ*, but an off-center part travels the chord — inside the arc — and drifts toward the center mid-flight. An arrow's head sagged ~1 px toward its shaft at t = 0.5 (`r·(1 − cos(θ/2))` with r = 3.5, θ = 90°) while both parts rotated perfectly. Under the hybrid, each centroid rides the shared similarity around the global centroid `g_A` instead:
+
+```
+c_k(t) = c_{A,k} + t·d_k + (σ*ᵗ·R(t·θ*) − I)·(c_{A,k} − g_A)
+```
+
+`d_k` is fixed once so that `c_k(1) = c_{B,k}` exactly (it absorbs the tiny global residual). Every point of every subpath then moves under ONE similarity per frame: congruent icons are rigid through the whole flight, not only at the endpoints. With θ* = 0, or centroids sitting on `g_A`, or no hybrid at all, the formula degrades continuously to the plain lerp — no thresholds, no special cases.
+
 ### 6. Serialization and canonical snap
 
 In flight, each subpath is emitted as `M x y L x y …` (+ `Z` if the pair is closed↔closed; closed→open flies open, the loop opening at the cut chosen by the circular correspondence) with 2 decimals — invisible at 24px, and the frame's only allocation. On settle, the driver **snaps to the canonical `d`** of the target icon: exact fidelity at rest (real curves, not polylines), subpath count reset after duplications, and the DOM ends up identical to a static icon's. The jump is < 0.02px — imperceptible.
@@ -244,9 +263,9 @@ CI budget (size-limit, gzip) as an anti-regression tripwire — gates carry ~10%
 
 | entry | measured | gate |
 |---|---|---|
-| `morphicons` (core) | 6.32 KB | 7 KB |
-| `morphicons/dom` (core + driver) | 6.92 KB | 7.5 KB |
-| `morphicons/react` (all, react external) | 7.65 KB | 8.5 KB |
+| `morphicons` (core) | 6.60 KB | 7 KB |
+| `morphicons/dom` (core + driver) | 7.04 KB | 7.5 KB |
+| `morphicons/react` (all, react external) | 7.77 KB | 8.5 KB |
 
 ## Playground
 
@@ -259,7 +278,7 @@ bun run play   # → http://localhost:3000
 ## Development
 
 ```bash
-bun test          # 74 tests / ~13,400 asserts
+bun test          # 83 tests / ~13,400 asserts
 bun run typecheck # strict ×3: core+dom without lib DOM, playground, react
 bun run format    # biome
 bun run build     # tsdown → dist/ (entries index, dom, react)

package/dist/dom.js

@@ -1,4 +1,4 @@
-import { a as resampleIcon, c as iconToCubics, d as interpPolar, i as serialize, l as allocOutputs, n as Spring, r as cubicsToPathD, s as buildPlan, t as SPRING_PRESETS } from "./spring-Dbj7NCw2.js";
+import { a as buildPlan, c as cubicsToPathD, f as interpPolar, l as serialize, n as Spring, r as resampleIcon, s as iconToCubics, t as SPRING_PRESETS, u as allocOutputs } from "./spring-BTcHiHR5.js";
 //#region src/dom/index.ts
 const tickers = /* @__PURE__ */ new Set();
 let rafId = 0;

package/dist/index.d.ts

@@ -18,6 +18,13 @@ interface PlanItem {
   /** true if both endpoints are closed loops: the subpath flies with Z.
    *  Closed → open flies open: the loop opens at the chosen cut. */
   closed: boolean;
+  /** Block transport (set by the global hybrid, else null): mid-flight the
+   *  centroid rides the shared similarity around the global centroid instead
+   *  of lerping — off = c_A − g_A; drift closes c(1) = c_B exactly. */
+  block: {
+    off: readonly [number, number];
+    drift: readonly [number, number];
+  } | null;
 }
 interface MorphPlan {
   items: PlanItem[];
@@ -38,6 +45,17 @@ declare function interpLinear(plan: MorphPlan, t: number, out: Float64Array[]):
 //#region src/core/normalize.d.ts
 /** Icon (IconNode or `d` string) → list of cubic subpaths. */
 declare function iconToCubics(input: IconInput): CubicPath[];
+/** A source viewBox: `24`, `"0 0 20 20"` or `[minX, minY, w, h]`. */
+type ViewBox = number | string | readonly [number, number, number, number];
+/** Re-grids an icon drawn on `viewBox` onto the shared `grid` (24 by default),
+ *  centred and preserving aspect ratio — the SVG `xMidYMid meet` rule.
+ *
+ *  Both endpoints of a morph must live on the same coordinate space. Lucide and
+ *  Tabler already draw on 24×24; packs on 20 (Heroicons solid) or 32 (Carbon)
+ *  do not, and mixing them unfitted makes Procrustes read the scale/offset gap
+ *  as rotation. Apply once at module scope (not per render) and pass the
+ *  resulting `d` anywhere an icon is accepted. */
+declare function fitIcon(input: IconInput, viewBox: ViewBox, grid?: number): string;
 //#endregion
 //#region src/core/resample.d.ts
 /** Samples a cubic subpath at N points equidistant by arc length, anchoring
@@ -57,4 +75,4 @@ declare function serialize(subs: readonly Float64Array[], closed?: readonly bool
 /** Cubic subpaths → canonical `d` at full precision (round-trip). */
 declare function cubicsToPathD(paths: readonly CubicPath[]): string;
 //#endregion
-export { type CubicPath, type IconInput, type IconNode, type IconNodeAttrs, type MorphPlan, type PlanItem, SPRING_PRESETS, type Sampled, Spring, type SpringPreset, allocOutputs, buildPlan, cubicsToPathD, iconToCubics, interpLinear, interpPolar, resampleIcon, resamplePath, serialize };
+export { type CubicPath, type IconInput, type IconNode, type IconNodeAttrs, type MorphPlan, type PlanItem, SPRING_PRESETS, type Sampled, Spring, type SpringPreset, type ViewBox, allocOutputs, buildPlan, cubicsToPathD, fitIcon, iconToCubics, interpLinear, interpPolar, resampleIcon, resamplePath, serialize };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as resampleIcon, c as iconToCubics, d as interpPolar, i as serialize, l as allocOutputs, n as Spring, o as resamplePath, r as cubicsToPathD, s as buildPlan, t as SPRING_PRESETS, u as interpLinear } from "./spring-Dbj7NCw2.js";
-export { SPRING_PRESETS, Spring, allocOutputs, buildPlan, cubicsToPathD, iconToCubics, interpLinear, interpPolar, resampleIcon, resamplePath, serialize };
+import { a as buildPlan, c as cubicsToPathD, d as interpLinear, f as interpPolar, i as resamplePath, l as serialize, n as Spring, o as fitIcon, r as resampleIcon, s as iconToCubics, t as SPRING_PRESETS, u as allocOutputs } from "./spring-BTcHiHR5.js";
+export { SPRING_PRESETS, Spring, allocOutputs, buildPlan, cubicsToPathD, fitIcon, iconToCubics, interpLinear, interpPolar, resampleIcon, resamplePath, serialize };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { a as resampleIcon, d as interpPolar, i as serialize, l as allocOutputs, s as buildPlan } from "./spring-Dbj7NCw2.js";
+import { a as buildPlan, f as interpPolar, l as serialize, r as resampleIcon, u as allocOutputs } from "./spring-BTcHiHR5.js";
 import { canonicalD, createMorph } from "./dom.js";
 import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{spring-Dbj7NCw2.js → spring-BTcHiHR5.js}

@@ -8,12 +8,21 @@ function interpPolar(plan, t, out) {
 		const it = plan.items[k];
 		const o = out[k];
 		const n = plan.n;
-		const cx = it.ca[0] + (it.cb[0] - it.ca[0]) * t;
-		const cy = it.ca[1] + (it.cb[1] - it.ca[1]) * t;
 		const s = Math.exp(it.lnSigma * t);
 		const ang = it.theta * t;
 		const cos = Math.cos(ang) * s;
 		const sin = Math.sin(ang) * s;
+		let cx;
+		let cy;
+		if (it.block) {
+			const [ox, oy] = it.block.off;
+			const [dx, dy] = it.block.drift;
+			cx = it.ca[0] + dx * t + (ox * cos - oy * sin - ox);
+			cy = it.ca[1] + dy * t + (ox * sin + oy * cos - oy);
+		} else {
+			cx = it.ca[0] + (it.cb[0] - it.ca[0]) * t;
+			cy = it.ca[1] + (it.cb[1] - it.ca[1]) * t;
+		}
 		for (let i = 0; i < n; i++) {
 			const px = it.aC[2 * i] + (it.bT[2 * i] - it.aC[2 * i]) * t;
 			const py = it.aC[2 * i + 1] + (it.bT[2 * i + 1] - it.aC[2 * i + 1]) * t;
@@ -279,6 +288,34 @@ function parsePath(d) {
 	return subs.filter((s) => s.segs.length > 0);
 }
 //#endregion
+//#region src/core/serialize.ts
+function fmt(v) {
+	return String(Math.round(v * 100) / 100);
+}
+/** Sampled subpaths → polyline `d` attribute. `closed[k]` appends Z to
+*  subpath k (closed loops in flight); without flags everything is open. */
+function serialize(subs, closed) {
+	let d = "";
+	for (let k = 0; k < subs.length; k++) {
+		const o = subs[k];
+		const n = o.length / 2;
+		d += `M${fmt(o[0])} ${fmt(o[1])}`;
+		for (let i = 1; i < n; i++) d += `L${fmt(o[2 * i])} ${fmt(o[2 * i + 1])}`;
+		if (closed?.[k]) d += "Z";
+	}
+	return d;
+}
+/** Cubic subpaths → canonical `d` at full precision (round-trip). */
+function cubicsToPathD(paths) {
+	let d = "";
+	for (const { pts, closed } of paths) {
+		d += `M${pts[0]} ${pts[1]}`;
+		for (let i = 2; i < pts.length; i += 6) d += `C${pts[i]} ${pts[i + 1]} ${pts[i + 2]} ${pts[i + 3]} ${pts[i + 4]} ${pts[i + 5]}`;
+		if (closed) d += "Z";
+	}
+	return d;
+}
+//#endregion
 //#region src/core/normalize.ts
 /** Control-point offset for a quarter circle: (4/3)·tan(π/8) ≈ 0.5523. */
 const KAPPA = 4 / 3 * Math.tan(Math.PI / 8);
@@ -505,6 +542,42 @@ function iconToCubics(input) {
 	}
 	return out;
 }
+function parseViewBox(vb) {
+	const v = typeof vb === "number" ? [
+		0,
+		0,
+		vb,
+		vb
+	] : typeof vb === "string" ? vb.trim().split(/[\s,]+/).map(Number) : vb;
+	const [minX, minY, w, h] = v;
+	if (v.length !== 4 || !(w > 0) || !(h > 0) || !Number.isFinite(minX) || !Number.isFinite(minY)) throw new Error(`morphicons: invalid viewBox "${String(vb)}"`);
+	return [
+		minX,
+		minY,
+		w,
+		h
+	];
+}
+/** Re-grids an icon drawn on `viewBox` onto the shared `grid` (24 by default),
+*  centred and preserving aspect ratio — the SVG `xMidYMid meet` rule.
+*
+*  Both endpoints of a morph must live on the same coordinate space. Lucide and
+*  Tabler already draw on 24×24; packs on 20 (Heroicons solid) or 32 (Carbon)
+*  do not, and mixing them unfitted makes Procrustes read the scale/offset gap
+*  as rotation. Apply once at module scope (not per render) and pass the
+*  resulting `d` anywhere an icon is accepted. */
+function fitIcon(input, viewBox, grid = 24) {
+	const [minX, minY, w, h] = parseViewBox(viewBox);
+	const s = Math.min(grid / w, grid / h);
+	const tx = (grid - w * s) / 2 - minX * s;
+	const ty = (grid - h * s) / 2 - minY * s;
+	const paths = iconToCubics(input);
+	for (const { pts } of paths) for (let i = 0; i < pts.length; i += 2) {
+		pts[i] = pts[i] * s + tx;
+		pts[i + 1] = pts[i + 1] * s + ty;
+	}
+	return cubicsToPathD(paths);
+}
 //#endregion
 //#region src/core/plan.ts
 /** Weight of |ΔL| in the subpath pairing cost. */
@@ -742,7 +815,8 @@ function applyGlobal(items, n) {
 		ga.set(it.a, 2 * n * k);
 		gb.set(it.bO, 2 * n * k);
 	});
-	const g = procrustes(ga, gb, centroid(ga), centroid(gb));
+	const gca = centroid(ga);
+	const g = procrustes(ga, gb, gca, centroid(gb));
 	if (g.res >= GLOBAL_EPS) return;
 	const cos = Math.cos(-g.theta);
 	const sin = Math.sin(-g.theta);
@@ -764,6 +838,17 @@ function applyGlobal(items, n) {
 		it.theta = g.theta;
 		it.lnSigma = Math.log(g.sigma);
 		it.res = nb > 1e-12 ? Math.sqrt(e2 / nb) : 0;
+		const s1 = Math.exp(it.lnSigma);
+		const c1 = Math.cos(it.theta) * s1;
+		const n1 = Math.sin(it.theta) * s1;
+		const ox = it.ca[0] - gca[0];
+		const oy = it.ca[1] - gca[1];
+		const rx = ox * c1 - oy * n1 - ox;
+		const ry = ox * n1 + oy * c1 - oy;
+		it.block = {
+			off: [ox, oy],
+			drift: [it.cb[0] - it.ca[0] - rx, it.cb[1] - it.ca[1] - ry]
+		};
 	}
 }
 /** Builds the morph plan between two lists of sampled subpaths. The plan is
@@ -815,7 +900,8 @@ function buildPlan(srcSubs, dstSubs) {
 			theta: al.theta,
 			lnSigma: Math.log(al.sigma),
 			res: al.res,
-			closed: srcSubs[si].closed && dstSubs[di].closed
+			closed: srcSubs[si].closed && dstSubs[di].closed,
+			block: null
 		};
 	});
 	if (items.length > 1) applyGlobal(items, n);
@@ -1021,34 +1107,6 @@ function resampleIcon(input, N = 64) {
 	}));
 }
 //#endregion
-//#region src/core/serialize.ts
-function fmt(v) {
-	return String(Math.round(v * 100) / 100);
-}
-/** Sampled subpaths → polyline `d` attribute. `closed[k]` appends Z to
-*  subpath k (closed loops in flight); without flags everything is open. */
-function serialize(subs, closed) {
-	let d = "";
-	for (let k = 0; k < subs.length; k++) {
-		const o = subs[k];
-		const n = o.length / 2;
-		d += `M${fmt(o[0])} ${fmt(o[1])}`;
-		for (let i = 1; i < n; i++) d += `L${fmt(o[2 * i])} ${fmt(o[2 * i + 1])}`;
-		if (closed?.[k]) d += "Z";
-	}
-	return d;
-}
-/** Cubic subpaths → canonical `d` at full precision (round-trip). */
-function cubicsToPathD(paths) {
-	let d = "";
-	for (const { pts, closed } of paths) {
-		d += `M${pts[0]} ${pts[1]}`;
-		for (let i = 2; i < pts.length; i += 6) d += `C${pts[i]} ${pts[i + 1]} ${pts[i + 2]} ${pts[i + 3]} ${pts[i + 4]} ${pts[i + 5]}`;
-		if (closed) d += "Z";
-	}
-	return d;
-}
-//#endregion
 //#region src/core/spring.ts
 var Spring = class {
 	x = 1;
@@ -1096,4 +1154,4 @@ const SPRING_PRESETS = {
 	}
 };
 //#endregion
-export { resampleIcon as a, iconToCubics as c, interpPolar as d, serialize as i, allocOutputs as l, Spring as n, resamplePath as o, cubicsToPathD as r, buildPlan as s, SPRING_PRESETS as t, interpLinear as u };
+export { buildPlan as a, cubicsToPathD as c, interpLinear as d, interpPolar as f, resamplePath as i, serialize as l, Spring as n, fitIcon as o, resampleIcon as r, iconToCubics as s, SPRING_PRESETS as t, allocOutputs as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "morphicons",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Universal morphing for stroke-based icons with spring physics — zero runtime dependencies",
   "license": "MIT",
   "author": "Guillermo (https://guillermolg.com)",
@@ -23,8 +23,11 @@
     "spring",
     "lucide",
     "lucide-react",
-    "feather",
     "tabler",
+    "heroicons",
+    "iconoir",
+    "shadcn",
+    "feather",
     "react",
     "icon-animation"
   ],