@cssints/fonts 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @cssints/fonts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web fonts for [cssints](../../README.md): `font()` reads the font files at build time and gives two members of a
+`cssints/plugin` `scope()`. `family()` emits the `@font-face` rules, a fallback face whose metrics match the font, and
+`font-family`. `trim()` removes the space above the cap height and below the baseline. The metrics come from the files
+(fontkitten). No script ships.
+
+```ts
+// fonts.ts: a build-time module (it runs while the build runs, and never reaches the browser)
+import { font } from "@cssints/fonts" with { type: "cssints" };
+
+export const body = font("Atkinson Hyperlegible", { provider: "fontsource", weights: [400, 700] });
+export const brand = font("Brand", {
+  provider: "fs",
+  files: ["src/fonts/brand.woff2"],
+  fallback: "serif",
+});
+```
+
+```ts
+// a component imports them from there
+import { cn } from "cssints" with { type: "cssints" };
+import { body } from "./fonts.ts" with { type: "cssints" };
+
+export const text = body.family();
+export const heading = cn(body.family(), body.trim({ lineHeight: 1.2 }));
+```
+
+```css
+@layer _.k {
+  /* fontaine's formula (capsize's createFontStack): Arial scaled to the average width of the font, the vertical
+     metrics of the font */
+  @font-face {
+    font-family: "Atkinson Hyperlegible Fallback";
+    src: local("Arial"), local("Arimo"), local("Liberation Sans");
+    size-adjust: 99.3717%;
+    ascent-override: 95.6006%;
+    descent-override: 29.1833%;
+    line-gap-override: 0%;
+  }
+  /* one face per weight and subset of the package; Vite emits the files as assets */
+  @font-face {
+    font-family: "Atkinson Hyperlegible";
+    font-style: normal;
+    font-weight: 400;
+    font-display: swap;
+    src: url("/…/atkinson-hyperlegible-latin-400-normal.woff2") format("woff2");
+    unicode-range: U+0000-00FF, …;
+  }
+  /* … latin-ext 400, latin 700, latin-ext 700 */
+  ._fonts-native {
+    text-box: trim-both cap alphabetic;
+  }
+  /* only when a target lacks text-box */
+  @supports not (text-box: trim-both cap alphabetic) {
+    ._fonts-native::before,
+    ._fonts-native::after {
+      content: "";
+      display: table;
+    }
+    ._fonts-native::before {
+      margin-bottom: var(--fonts-t);
+    }
+    ._fonts-native::after {
+      margin-top: var(--fonts-b);
+    }
+  }
+}
+@layer _.a {
+  ._a {
+    font-family: "Atkinson Hyperlegible", "Atkinson Hyperlegible Fallback", sans-serif;
+  }
+  ._b {
+    line-height: 1.2;
+  }
+  ._c {
+    --fonts-t: -0.262em;
+  }
+  ._d {
+    --fonts-b: -0.27em;
+  }
+}
+```
+
+## Rules
+
+- **Providers.** `fontsource` reads the `@fontsource/<family>` package from the `node_modules` of the working directory
+  (`"Atkinson Hyperlegible"` is `@fontsource/atkinson-hyperlegible`): its `.woff2` files, one face per weight, style
+  and subset, each with the subset's `unicode-range`. `weights` and `styles` must be among those of the package (400 and
+  `normal` by default). `fs` takes font files (`.woff2`, `.woff`, `.ttf`, `.otf`, relative to the working directory),
+  one face each, with the weight and style read from the file.
+- **URLs.** A face's `src` is the absolute path of the file. Vite's CSS pipeline turns it into an asset in a build
+  (`/assets/…-[hash].woff2`) and into `/@fs/…` in dev.
+- **Fallback face.** `fallback` is a generic family (`sans-serif`, `serif` or `monospace`; by default the category of
+  the fontsource package, else `sans-serif`). Its local fonts are Arial, Times New Roman or Courier New, with their
+  metric-compatible clones (Arimo, Tinos, Cousine, the Liberation fonts). The face scales them to the font's average
+  latin width (`size-adjust`) and overrides `ascent`, `descent` and `line-gap` with the font's. This is fontaine's
+  formula. The numbers are those of `@capsizecss/core` `createFontStack` (checked in the test). The metrics come from
+  the 400 normal face (else the first) of the latin subset.
+- **trim().** `trim()` sets `line-height` (`normal`, or the number given) and the class of the kernel
+  `text-box: trim-both cap alphabetic` (Chrome 133, Safari 18.2, Firefox 154). When a target lacks `text-box`, the
+  sheet gets capsize's fallback: `::before` and `::after` with negative margins, in `em`, from the metrics of the font
+  and the line height (the numbers of `@capsizecss/core` `createStyleObject`, checked in the test). The fallback is
+  plain CSS, so every target gets it (Firefox 120 too), and there is no build warning. It is inside `@supports not`,
+  so a browser with `text-box` does not trim twice. When every target has `text-box`, the fallback is not in the sheet.
+- **Errors**, at build time: a package that is not installed (the message names it), a weight or a style the
+  package does not have, a file that cannot be read, a font collection, and a `lineHeight` that is not a number
+  (also a type error).
+- **Cache.** A file is parsed once per modification time in a process.
+
+## Limits
+
+- `lineHeight` is a number (a multiple of the font size). A length would make the trim depend on the font size.
+- The trim is right for the web font. The fallback face matches ascent and descent, but not the cap height, so the
+  trim is off by a little until the font loads.
+- Not yet: variable fonts (`@fontsource-variable/*`), remote providers (unifont, Google Fonts), the subsets option,
+  and `font-display` other than `swap`.
+- In dev, an edited file of `fs` updates the CSS of the modules that use it (`dependsOn` of `cssints/plugin`). The files
+  of `fontsource` are in `node_modules`, which Vite does not watch.
+
+```bash
+cd packages/fonts && bun run test   # fixtures through the engine (output, errors, warnings, a build), and the type test via bun run typecheck
+```
+
+## Credits
+
+Copied, with the notice below:
+
+- The characters and weights of the average width (`xWidthAvg`): the latin table of
+  [`@capsizecss/unpack`](https://github.com/seek-oss/capsize) (MIT, SEEK).
+- The metrics of Arial, Times New Roman and Courier New from `@capsizecss/metrics` (MIT, SEEK).
+
+Followed, not copied: the fallback face and the trim formulas of `@capsizecss/core` (the test checks the numbers
+against it), and [fontaine](https://github.com/unjs/fontaine) (MIT, Daniel Roe) for the fallback face. The font files
+are read with [fontkitten](https://github.com/delucis/fontkitten) (MIT), a dependency.
+
+The MIT notice of Capsize, Copyright (c) 2021 SEEK:
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+> documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+> rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+> persons to whom the Software is furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+> Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+> WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+> COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+> OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,96 @@
+//#region src/index.d.ts
+/** What the fallback face and `trim()` are computed from, in font units (capsize's names). */
+export interface Metrics {
+  ascent: number;
+  descent: number;
+  lineGap: number;
+  unitsPerEm: number;
+  capHeight: number;
+  /** The advance width of the latin letters, weighted by their frequency in English text (capsize's `xWidthAvg`). */
+  xWidthAvg: number;
+}
+/** A generic family: its local fonts (metric-compatible clones of one font) stand in until the web font loads. */
+export type Fallback = "sans-serif" | "serif" | "monospace";
+/**
+ * Where the files come from: the `@fontsource/<family>` package installed in the project (its `files/*.woff2`, every
+ * subset with its `unicode-range`), or font files (paths relative to the working directory; weight and style are read
+ * from each file).
+ */
+export type Options = {
+  fallback?: Fallback;
+} & ({
+  provider: "fontsource";
+  weights?: number[];
+  styles?: ("normal" | "italic")[];
+} | {
+  provider: "fs";
+  files: string[];
+});
+interface Face {
+  file: string;
+  weight: number;
+  style: string;
+  unicodeRange?: string;
+}
+interface Source {
+  faces: Face[];
+  /** The face the metrics come from: 400 normal, else the first. */
+  metrics: Metrics;
+  category: Fallback;
+}
+declare const fonts: (family: string, fallback: string, source: Source, globals: {
+  css: string;
+}[]) => import("cssints/plugin").Members<{
+  readonly "#native": {
+    readonly css: "&{text-box:trim-both cap alphabetic}";
+    readonly requires: ["css.properties.text-box"];
+  };
+  readonly "#capsize": {
+    readonly polyfills: ["css.properties.text-box"];
+    readonly css: string;
+  };
+  readonly family: {
+    readonly args: readonly [];
+  };
+  readonly trim: {
+    readonly args: readonly [{
+      readonly "lineHeight?": "<number [0,∞]>";
+    }];
+    readonly uses: readonly ["native", "capsize"];
+  };
+}>;
+/**
+ * What `font()` gives: call its members where the style is used. `family()` is `font-family` with the fallback face and
+ * carries the @font-face rules; `trim({ lineHeight? })` trims the space above the cap height and below the baseline.
+ */
+export type Font = ReturnType<typeof fonts>;
+/**
+ * A web font from the `@fontsource/<family>` package installed in the project (`provider: "fontsource"`, `weights`
+ * and `styles` among those it has, 400 normal by default), or from font files (`provider: "fs"`, paths relative to the
+ * working directory). The files are read when the module runs. Call `font()` in a module of its own, imported with the
+ * attribute, and its members where the style is used.
+ *
+ * @param {string} family the CSS family name (for fontsource, also the package: "Atkinson Hyperlegible" is `@fontsource/atkinson-hyperlegible`)
+ * @param {Options} options where the files come from, and the generic family of the fallback face (by default the font's category)
+ * @returns {Font} the members `family()` and `trim()`
+ */
+export declare const font: (family: string, options: Options) => import("cssints/plugin").Members<{
+  readonly "#native": {
+    readonly css: "&{text-box:trim-both cap alphabetic}";
+    readonly requires: ["css.properties.text-box"];
+  };
+  readonly "#capsize": {
+    readonly polyfills: ["css.properties.text-box"];
+    readonly css: string;
+  };
+  readonly family: {
+    readonly args: readonly [];
+  };
+  readonly trim: {
+    readonly args: readonly [{
+      readonly "lineHeight?": "<number [0,∞]>";
+    }];
+    readonly uses: readonly ["native", "capsize"];
+  };
+}>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,289 @@
+import { createRequire } from "node:module";
+import { readFileSync, statSync } from "node:fs";
+import { dirname, extname, join, resolve } from "node:path";
+import { create } from "fontkitten";
+import { dependsOn, scope } from "cssints/plugin";
+//#region src/index.ts
+const FALLBACKS = {
+	"sans-serif": {
+		locals: [
+			"Arial",
+			"Arimo",
+			"Liberation Sans"
+		],
+		metrics: {
+			ascent: 1854,
+			descent: -434,
+			lineGap: 67,
+			unitsPerEm: 2048,
+			capHeight: 1467,
+			xWidthAvg: 913
+		}
+	},
+	serif: {
+		locals: [
+			"Times New Roman",
+			"Tinos",
+			"Liberation Serif"
+		],
+		metrics: {
+			ascent: 1825,
+			descent: -443,
+			lineGap: 87,
+			unitsPerEm: 2048,
+			capHeight: 1356,
+			xWidthAvg: 832
+		}
+	},
+	monospace: {
+		locals: [
+			"Courier New",
+			"Cousine",
+			"Liberation Mono"
+		],
+		metrics: {
+			ascent: 1705,
+			descent: -615,
+			lineGap: 0,
+			unitsPerEm: 2048,
+			capHeight: 1170,
+			xWidthAvg: 1229
+		}
+	}
+};
+const SAMPLE = "0123456789, theofPpl'sRubicCnadywBrzGjT.Lkm]JFvgAN-HDMIE\"S()xWQYqVáKU=[Oé$:|/%Z;X";
+const WEIGHTS = [
+	.0053,
+	.0023,
+	.0026,
+	.001,
+	8e-4,
+	.0015,
+	7e-4,
+	5e-4,
+	7e-4,
+	6e-4,
+	.0083,
+	.154,
+	.0672,
+	.0351,
+	.0922,
+	.0571,
+	.017,
+	.0023,
+	.0163,
+	.0304,
+	.0014,
+	.0469,
+	.0015,
+	.0207,
+	.0114,
+	.0588,
+	.0232,
+	.0031,
+	.0578,
+	.0668,
+	.0298,
+	.0123,
+	.011,
+	.002,
+	.0526,
+	.0011,
+	.0011,
+	9e-4,
+	.0041,
+	.0079,
+	.0012,
+	.0046,
+	.0181,
+	7e-4,
+	9e-4,
+	.0015,
+	.0076,
+	.0155,
+	.004,
+	.0014,
+	.0018,
+	.0013,
+	.0013,
+	.0025,
+	.0022,
+	.0011,
+	.0012,
+	.0041,
+	.001,
+	.001,
+	.0025,
+	.0012,
+	1e-4,
+	3e-4,
+	8e-4,
+	5e-4,
+	1e-4,
+	7e-4,
+	.0016,
+	7e-4,
+	.0021,
+	9e-4,
+	1e-4,
+	2e-4,
+	8e-4,
+	.0038,
+	1e-4,
+	1e-4,
+	2e-4,
+	1e-4,
+	1e-4
+];
+const FORMATS = /* @__PURE__ */ new Map([
+	[".woff2", "woff2"],
+	[".woff", "woff"],
+	[".ttf", "truetype"],
+	[".otf", "opentype"]
+]);
+const fail = (message, cause) => {
+	throw new Error(`cssints: fonts: ${message}`, { cause });
+};
+const attempt = (f, message) => {
+	try {
+		return f();
+	} catch (e) {
+		return fail(message, e);
+	}
+};
+const g = globalThis;
+const read = (file) => {
+	const mtime = attempt(() => statSync(file).mtimeMs, `cannot read ${file}`);
+	const cache = g.__cssintsFonts ??= /* @__PURE__ */ new Map();
+	const hit = cache.get(file);
+	if (hit?.mtime === mtime) return hit.read;
+	const font = create(readFileSync(file));
+	if (font.isCollection) return fail(`${file} is a font collection: give one font file`);
+	const xWidthAvg = Math.round(font.glyphsForString(SAMPLE).reduce((sum, glyph, i) => glyph.isMark ? sum : sum + glyph.advanceWidth * WEIGHTS[i], 0));
+	const { ascent, descent, lineGap, unitsPerEm, capHeight } = font;
+	const out = {
+		metrics: {
+			ascent,
+			descent,
+			lineGap,
+			unitsPerEm,
+			capHeight,
+			xWidthAvg
+		},
+		weight: font["OS/2"].usWeightClass,
+		style: font["OS/2"].fsSelection.italic || font.italicAngle !== 0 ? "italic" : "normal"
+	};
+	cache.set(file, {
+		mtime,
+		read: out
+	});
+	return out;
+};
+const fontsource = (family, weights, styles = ["normal"]) => {
+	const pkg = `@fontsource/${family.toLowerCase().replace(/\s+/g, "-")}`;
+	const dir = attempt(() => dirname(createRequire(join(process.cwd(), "_")).resolve(pkg)), `cannot read ${pkg} from ${process.cwd()}: install ${pkg}`);
+	const meta = JSON.parse(readFileSync(join(dir, "metadata.json"), "utf8"));
+	const ranges = JSON.parse(readFileSync(join(dir, "unicode.json"), "utf8"));
+	const ws = weights ?? [meta.weights.includes(400) ? 400 : meta.weights[0]];
+	for (const w of ws) if (!meta.weights.includes(w)) fail(`${pkg} has no weight ${w} (it has ${meta.weights.join(", ")})`);
+	for (const s of styles) if (!meta.styles.includes(s)) fail(`${pkg} has no style ${s} (it has ${meta.styles.join(", ")})`);
+	const file = (subset, w, s) => join(dir, "files", `${meta.id}-${subset.replace(/^\[(\d+)\]$/, "$1")}-${w}-${s}.woff2`);
+	const faces = ws.flatMap((weight) => styles.flatMap((style) => Object.entries(ranges).map(([subset, unicodeRange]) => ({
+		file: file(subset, weight, style),
+		weight,
+		style,
+		unicodeRange
+	}))));
+	const main = file(meta.defSubset, ws.includes(400) ? 400 : ws[0], styles[0]);
+	return {
+		faces,
+		metrics: read(main).metrics,
+		category: meta.category === "serif" || meta.category === "monospace" ? meta.category : "sans-serif"
+	};
+};
+const files = (list) => {
+	if (!list.length) fail("fs takes at least one file");
+	const faces = list.map((f) => {
+		const file = resolve(f);
+		if (!FORMATS.has(extname(file))) fail(`${f}: not a .woff2, .woff, .ttf or .otf file`);
+		dependsOn(file);
+		const { weight, style } = read(file);
+		return {
+			file,
+			weight,
+			style
+		};
+	});
+	const main = faces.find((f) => f.weight === 400 && f.style === "normal") ?? faces[0];
+	return {
+		faces,
+		metrics: read(main.file).metrics,
+		category: "sans-serif"
+	};
+};
+const quote = (s) => `"${s.replace(/["\\]/g, "\\$&")}"`;
+const round = (n) => Number.parseFloat(n.toFixed(4));
+const percent = (n) => `${round(n * 100)}%`;
+const faceRule = (family, f) => `@font-face{font-family:${quote(family)};font-style:${f.style};font-weight:${f.weight};font-display:swap;src:url(${quote(f.file)}) format(${quote(FORMATS.get(extname(f.file)))})${f.unicodeRange ? `;unicode-range:${f.unicodeRange}` : ""}}`;
+const fallbackFace = (name, metrics, fallback) => {
+	const { locals, metrics: local } = FALLBACKS[fallback];
+	const sizeAdjust = metrics.xWidthAvg / metrics.unitsPerEm / (local.xWidthAvg / local.unitsPerEm);
+	const em = metrics.unitsPerEm * sizeAdjust;
+	return `@font-face{font-family:${quote(name)};src:${locals.map((l) => `local(${quote(l)})`).join(",")};size-adjust:${percent(sizeAdjust)};ascent-override:${percent(metrics.ascent / em)};descent-override:${percent(Math.abs(metrics.descent) / em)};line-gap-override:${percent(metrics.lineGap / em)}}`;
+};
+const trims = (m, lineHeight) => {
+	const scale = (n) => n / m.unitsPerEm;
+	const offset = lineHeight ? (scale(m.ascent + m.lineGap + Math.abs(m.descent)) - lineHeight) / 2 : 0;
+	const top = scale(m.ascent) - scale(m.capHeight) + scale(m.lineGap) / 2 - offset;
+	const bottom = scale(Math.abs(m.descent)) + scale(m.lineGap) / 2 - offset;
+	return {
+		top: `${round(-top)}em`,
+		bottom: `${round(-bottom)}em`
+	};
+};
+const NATIVE = "text-box:trim-both cap alphabetic";
+const fonts = (family, fallback, source, globals) => scope("fonts", {
+	"#native": {
+		css: `&{${NATIVE}}`,
+		requires: ["css.properties.text-box"]
+	},
+	"#capsize": {
+		polyfills: ["css.properties.text-box"],
+		css: `@supports not (${NATIVE}){&::before,&::after{content:"";display:table}&::before{margin-bottom:var(--_t)}&::after{margin-top:var(--_b)}}`
+	},
+	family: { args: [] },
+	trim: {
+		args: [{ "lineHeight?": "<number [0,∞]>" }],
+		uses: ["native", "capsize"]
+	}
+}).build({
+	family: () => ({
+		decls: [["font-family", `${quote(family)}, ${quote(`${family} Fallback`)}, ${fallback}`]],
+		globals
+	}),
+	trim: (o) => {
+		const { top, bottom } = trims(source.metrics, o.lineHeight ? Number(o.lineHeight) : void 0);
+		return { decls: [
+			["line-height", o.lineHeight ?? "normal"],
+			["--_t", top],
+			["--_b", bottom]
+		] };
+	}
+}).export();
+/**
+* A web font from the `@fontsource/<family>` package installed in the project (`provider: "fontsource"`, `weights`
+* and `styles` among those it has, 400 normal by default), or from font files (`provider: "fs"`, paths relative to the
+* working directory). The files are read when the module runs. Call `font()` in a module of its own, imported with the
+* attribute, and its members where the style is used.
+*
+* @param {string} family the CSS family name (for fontsource, also the package: "Atkinson Hyperlegible" is `@fontsource/atkinson-hyperlegible`)
+* @param {Options} options where the files come from, and the generic family of the fallback face (by default the font's category)
+* @returns {Font} the members `family()` and `trim()`
+*/
+const font = (family, options) => {
+	const source = options.provider === "fs" ? files(options.files) : fontsource(family, options.weights, options.styles);
+	const fallback = options.fallback ?? source.category;
+	return fonts(family, fallback, source, [...source.faces.map((f) => ({ css: faceRule(family, f) })), { css: fallbackFace(`${family} Fallback`, source.metrics, fallback) }]);
+};
+//#endregion
+export { font };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@cssints/fonts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Fonts for cssints: @font-face rules with a metric-matched fallback face, and cap-height trimming",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/fonts"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "fontkitten": "^1.0.3"
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}