@pantoken/icon-font 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @pantoken/icon-font
+
+Build an installable Instructure icon font from the Canvas by Instructure icon set. You get a WOFF2 file, a TTF file, a stylesheet, and a codepoint map. Install the font on a device and use the glyphs in design apps, documents, and offline contexts where the web tooling isn't reachable.
+
+## Why a font
+
+The other pantoken icon formats emit inline SVG or per-framework components. Those need a build step and a browser. A font doesn't. Once it's installed, every app that picks a font can use the icons: Figma, Sketch, Google Slides, Keynote, Word, and any native text field.
+
+## What it does
+
+Instructure ships two kinds of glyphs:
+
+- Fill glyphs (the custom Instructure set) already describe filled regions, so they pass straight through.
+- Stroke glyphs (the Lucide set) describe a centerline with a stroke width. A font glyph has no stroke, so this package outlines each stroke into a filled shape. It flattens every subpath to points, then offsets that polyline by half the stroke width with round joins and caps.
+
+The result is one filled path per icon, streamed through `svgicons2svgfont`, `svg2ttf`, and `ttf2woff2`.
+
+## Install
+
+```sh
+npm i -D @pantoken/icon-font
+```
+
+This package isn't part of the unscoped `pantoken` meta package. The font toolchain is heavy, so `npm i pantoken` stays lean. Install this one directly when you need a font.
+
+## CLI
+
+```sh
+pantoken generate icon-font --out ./fonts
+pantoken generate icon-font --out ./fonts --class Instructure --icons arrow-left,check-mark
+```
+
+Flags:
+
+- `--out` is the output directory (default `./pantoken-out`).
+- `--class` is the font family name (default `PanTokens`).
+- `--icons` is a comma-separated subset (default: every icon).
+- `--theme` is the source theme (default `rebrand`).
+
+The command writes four files: `<class>.woff2`, `<class>.ttf`, `icons.css`, and `codepoints.json`.
+
+## API
+
+```ts
+import { buildIconFont } from "@pantoken/icon-font";
+
+const font = await buildIconFont({ fontName: "PanTokens", icons: ["arrow-left"] });
+// font.woff2  → Uint8Array
+// font.ttf    → Uint8Array
+// font.css    → string (@font-face + .instui-icon-<name> rules)
+// font.codepoints → { "arrow-left": "e000", ... }
+```
+
+## Use the font on the web
+
+```html
+<link rel="stylesheet" href="./icons.css" /> <i class="instui-icon instui-icon-arrow-left"></i>
+```
+
+Each glyph lives in the Unicode Private Use Area, starting at U+E000. The `codepoints.json` map records the assignment for every icon, so you can also type a glyph directly once the font is installed.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,79 @@
+import { Theme } from "@pantoken/model";
+
+//#region src/build.d.ts
+/** The generated font artifacts. */
+interface IconFontResult {
+  /** The TrueType font bytes. */
+  ttf: Uint8Array;
+  /** The WOFF2 font bytes. */
+  woff2: Uint8Array;
+  /** The `@font-face` + `.instui-icon-<name>` stylesheet. */
+  css: string;
+  /** Icon name → hex codepoint (e.g. `"e001"`). */
+  codepoints: Record<string, string>;
+}
+/** Options for {@link buildIconFont}. */
+interface BuildIconFontOptions {
+  /** Icon names to include (default: the whole set). */
+  icons?: string[];
+  /** The font family name (default `"PanTokens"`). */
+  fontName?: string;
+  /** The theme to source glyphs from (default `"rebrand"`). */
+  theme?: Theme;
+}
+/**
+ * Build the icon font.
+ *
+ * @param options - {@link BuildIconFontOptions}.
+ * @returns The {@link IconFontResult}.
+ *
+ * @example Build the full font and write the artifacts
+ * ```ts
+ * import { buildIconFont } from "@pantoken/icon-font";
+ * import { writeFileSync } from "node:fs";
+ *
+ * const font = await buildIconFont();
+ * writeFileSync("PanTokens.woff2", font.woff2);
+ * writeFileSync("PanTokens.ttf", font.ttf);
+ * writeFileSync("icons.css", font.css);
+ * ```
+ *
+ * @example A custom font name and a subset of icons from another theme
+ * ```ts
+ * import { buildIconFont } from "@pantoken/icon-font";
+ *
+ * const font = await buildIconFont({
+ *   fontName: "Instructure",
+ *   icons: ["arrow-left", "check-mark"],
+ *   theme: "canvas",
+ * });
+ * font.codepoints; // { "arrow-left": "e000", "check-mark": "e001" }
+ * ```
+ */
+declare function buildIconFont(options?: BuildIconFontOptions): Promise<IconFontResult>;
+//#endregion
+//#region src/outline.d.ts
+/** A filled glyph path plus the SVG viewBox size to wrap it in. */
+interface GlyphPath {
+  d: string;
+  width: number;
+  height: number;
+}
+/**
+ * Produce a filled glyph path for an icon SVG.
+ *
+ * @param svg - Inline SVG markup.
+ * @returns The filled path `d` (in viewBox coordinates) and the viewBox size.
+ *
+ * @example Outline a stroke-based (Lucide) icon and a fill-based icon
+ * ```ts
+ * import { svgToGlyphPath } from "@pantoken/icon-font";
+ * import { getIcon } from "@pantoken/icons";
+ *
+ * const { d, width, height } = svgToGlyphPath(getIcon("arrow-left")!.svg);
+ * // d: a single filled path; width/height: the viewBox size (e.g. 24, 24)
+ * ```
+ */
+declare function svgToGlyphPath(svg: string): GlyphPath;
+//#endregion
+export { type BuildIconFontOptions, type GlyphPath, type IconFontResult, buildIconFont, svgToGlyphPath };

package/dist/index.mjs

@@ -0,0 +1,229 @@
+import { Readable } from "node:stream";
+import { getIconSvgs } from "@pantoken/core";
+import { byTheme } from "@pantoken/tokens";
+import { SVGIcons2SVGFontStream } from "svgicons2svgfont";
+import svg2ttf from "svg2ttf";
+import ttf2woff2 from "ttf2woff2";
+import ClipperLib from "clipper-lib";
+import { pointsOnPath } from "points-on-path";
+//#region src/outline.ts
+/**
+* Turn an icon SVG into a single **filled** glyph path (what a font glyph needs). Fill-based icons
+* (Instructure custom glyphs) pass through; stroke-based icons (Lucide) are converted from a
+* centerline stroke to a filled outline by flattening each subpath to points and offsetting it by
+* half the stroke width with round joins/caps (`points-on-path` + `clipper-lib`, pure JS).
+*
+* @module
+*/
+const SCALE = 100;
+function attr(tag, name) {
+	return new RegExp(`\\b${name}=["']([^"']*)["']`).exec(tag)?.[1];
+}
+const STROKED_RE = /\bstroke=["'](?!none)[^"']+["']/;
+function nums(value) {
+	return (value ?? "").split(/[\s,]+/).filter(Boolean).map(Number);
+}
+/** Convert an SVG primitive element to a subpath `d` + closure. */
+function primitiveToSubpath(tag, el) {
+	switch (tag) {
+		case "line": {
+			const [x1, y1, x2, y2] = [
+				attr(el, "x1"),
+				attr(el, "y1"),
+				attr(el, "x2"),
+				attr(el, "y2")
+			].map(Number);
+			return {
+				d: `M${x1},${y1} L${x2},${y2}`,
+				closed: false
+			};
+		}
+		case "circle": {
+			const cx = Number(attr(el, "cx"));
+			const cy = Number(attr(el, "cy"));
+			const r = Number(attr(el, "r"));
+			return {
+				d: `M${cx - r},${cy} a${r},${r} 0 1,0 ${r * 2},0 a${r},${r} 0 1,0 ${-r * 2},0`,
+				closed: true
+			};
+		}
+		case "rect": {
+			const x = Number(attr(el, "x") ?? "0");
+			const y = Number(attr(el, "y") ?? "0");
+			const w = Number(attr(el, "width"));
+			return {
+				d: `M${x},${y} h${w} v${Number(attr(el, "height"))} h${-w} z`,
+				closed: true
+			};
+		}
+		case "polyline":
+		case "polygon": {
+			const pts = nums(attr(el, "points"));
+			if (pts.length < 4) return void 0;
+			const parts = [`M${pts[0]},${pts[1]}`];
+			for (let i = 2; i < pts.length; i += 2) parts.push(`L${pts[i]},${pts[i + 1]}`);
+			if (tag === "polygon") parts.push("z");
+			return {
+				d: parts.join(" "),
+				closed: tag === "polygon"
+			};
+		}
+		default: return;
+	}
+}
+/** Split a path `d` into its subpaths (at each M/m), marking each closed if it contains z/Z. */
+function splitSubpaths(d) {
+	return (d.match(/[Mm][^Mm]*/g) ?? []).map((chunk) => ({
+		d: chunk.trim(),
+		closed: /[Zz]/.test(chunk)
+	}));
+}
+/**
+* Produce a filled glyph path for an icon SVG.
+*
+* @param svg - Inline SVG markup.
+* @returns The filled path `d` (in viewBox coordinates) and the viewBox size.
+*
+* @example Outline a stroke-based (Lucide) icon and a fill-based icon
+* ```ts
+* import { svgToGlyphPath } from "@pantoken/icon-font";
+* import { getIcon } from "@pantoken/icons";
+*
+* const { d, width, height } = svgToGlyphPath(getIcon("arrow-left")!.svg);
+* // d: a single filled path; width/height: the viewBox size (e.g. 24, 24)
+* ```
+*/
+function svgToGlyphPath(svg) {
+	const vb = nums(/viewBox=["']([^"']+)["']/.exec(svg)?.[1]);
+	const [width, height] = vb.length === 4 ? [vb[2], vb[3]] : [24, 24];
+	const rootTag = /<svg\b[^>]*>/.exec(svg)?.[0] ?? "";
+	const strokeWidth = Number(attr(rootTag, "stroke-width") ?? "2");
+	const stroked = STROKED_RE.test(rootTag);
+	const subpaths = [];
+	for (const [, tag, el] of svg.matchAll(/<(path|line|circle|rect|polyline|polygon)\b([^>]*)>/g)) if (tag === "path") {
+		const d = attr(el, "d");
+		if (d) subpaths.push(...splitSubpaths(d));
+	} else {
+		const sub = primitiveToSubpath(tag, el);
+		if (sub) subpaths.push(sub);
+	}
+	if (!stroked) return {
+		d: subpaths.map((s) => s.d).join(" "),
+		width,
+		height
+	};
+	const offset = new ClipperLib.ClipperOffset(2, .25);
+	for (const sub of subpaths) for (const poly of pointsOnPath(sub.d, .2, .2)) {
+		if (poly.length < 2) continue;
+		const path = poly.map(([x, y]) => ({
+			X: Math.round(x * SCALE),
+			Y: Math.round(y * SCALE)
+		}));
+		offset.AddPath(path, ClipperLib.JoinType.jtRound, sub.closed ? ClipperLib.EndType.etClosedLine : ClipperLib.EndType.etOpenRound);
+	}
+	const solution = new ClipperLib.Paths();
+	offset.Execute(solution, strokeWidth / 2 * SCALE);
+	return {
+		d: solution.map((poly) => `M${poly.map((pt) => `${pt.X / SCALE},${pt.Y / SCALE}`).join(" L")} Z`).join(" "),
+		width,
+		height
+	};
+}
+//#endregion
+//#region src/build.ts
+/**
+* Build a full Instructure icon font. Stroke glyphs are outlined (see {@link svgToGlyphPath}), then
+* the glyph set is streamed through `svgicons2svgfont` → `svg2ttf` → `ttf2woff2`, with a matching
+* `icons.css` and `codepoints.json`. Codepoints start at the Unicode Private Use Area (U+E000).
+*
+* @module
+*/
+function css(fontName, codepoints) {
+	return `${[
+		[
+			"@font-face {",
+			`  font-family: "${fontName}";`,
+			`  src: url("./${fontName}.woff2") format("woff2"), url("./${fontName}.ttf") format("truetype");`,
+			"  font-weight: normal;",
+			"  font-style: normal;",
+			"  font-display: block;",
+			"}"
+		].join("\n"),
+		`.instui-icon { font-family: "${fontName}"; font-style: normal; font-weight: normal; line-height: 1; -webkit-font-smoothing: antialiased; }`,
+		Object.entries(codepoints).map(([name, hex]) => `.instui-icon-${name}::before { content: "\\${hex}"; }`).join("\n")
+	].join("\n\n")}\n`;
+}
+/**
+* Build the icon font.
+*
+* @param options - {@link BuildIconFontOptions}.
+* @returns The {@link IconFontResult}.
+*
+* @example Build the full font and write the artifacts
+* ```ts
+* import { buildIconFont } from "@pantoken/icon-font";
+* import { writeFileSync } from "node:fs";
+*
+* const font = await buildIconFont();
+* writeFileSync("PanTokens.woff2", font.woff2);
+* writeFileSync("PanTokens.ttf", font.ttf);
+* writeFileSync("icons.css", font.css);
+* ```
+*
+* @example A custom font name and a subset of icons from another theme
+* ```ts
+* import { buildIconFont } from "@pantoken/icon-font";
+*
+* const font = await buildIconFont({
+*   fontName: "Instructure",
+*   icons: ["arrow-left", "check-mark"],
+*   theme: "canvas",
+* });
+* font.codepoints; // { "arrow-left": "e000", "check-mark": "e001" }
+* ```
+*/
+async function buildIconFont(options = {}) {
+	const fontName = options.fontName ?? "PanTokens";
+	const svgs = getIconSvgs(byTheme(options.theme ?? "rebrand"));
+	const names = (options.icons?.length ? options.icons : [...svgs.keys()]).filter((n) => svgs.has(n)).sort();
+	const stream = new SVGIcons2SVGFontStream({
+		fontName,
+		fontHeight: 1e3,
+		normalize: true
+	});
+	let svgFont = "";
+	stream.on("data", (chunk) => {
+		svgFont += chunk.toString();
+	});
+	const done = new Promise((resolve, reject) => {
+		stream.on("end", resolve);
+		stream.on("error", reject);
+	});
+	const codepoints = {};
+	let codepoint = 57344;
+	for (const name of names) {
+		const svg = svgs.get(name);
+		if (!svg) continue;
+		const { d, width, height } = svgToGlyphPath(svg);
+		if (!d) continue;
+		const code = codepoint++;
+		codepoints[name] = code.toString(16);
+		const glyph = Readable.from([`<svg viewBox="0 0 ${width} ${height}"><path d="${d}"/></svg>`]);
+		glyph.metadata = {
+			unicode: [String.fromCodePoint(code)],
+			name
+		};
+		stream.write(glyph);
+	}
+	stream.end();
+	await done;
+	const ttf = new Uint8Array(svg2ttf(svgFont, { description: "Instructure icons (pantoken)" }).buffer);
+	return {
+		ttf,
+		woff2: new Uint8Array(ttf2woff2(ttf)),
+		css: css(fontName, codepoints),
+		codepoints
+	};
+}
+//#endregion
+export { buildIconFont, svgToGlyphPath };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pantoken/icon-font",
+  "version": "0.1.0",
+  "description": "Build an installable Instructure icon font (WOFF2 + TTF) with CSS and codepoints — stroke glyphs outlined to fills.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "clipper-lib": "^6.4.2",
+    "points-on-path": "^0.2.1",
+    "svg2ttf": "^6.1.0",
+    "svgicons2svgfont": "^16.0.0",
+    "ttf2woff2": "^8.0.1",
+    "@pantoken/core": "0.1.0",
+    "@pantoken/model": "0.1.0",
+    "@pantoken/tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}