normalize-metrics 0.1.1 → 0.2.0

package/README.md

@@ -1,24 +1,52 @@
 # normalize-metrics
 
-Rewrite font vertical metrics so a word sits in the box.
+Fix font vertical metrics so a word sits in the box.
 
-The text within a button is not always centered. That is the font’s fault, not yours. You can already trim the line box in CSS with `text-box: trim-both cap alphabetic`. The default is still the untrimmed box, and most type ramps and component kits were written for that default.
+The text within a button is not always centered. That is the font’s fault, not yours. You can trim the line box in CSS with `text-box: trim-both cap alphabetic`. The default is still the untrimmed box, and most type ramps and component kits were written for that default.
 
-This CLI rewrites the font for that default case. It only changes how the word sits in the box — not the letters, the look of the font, or anything else.
+Trim cuts descenders. An input, a textarea, or any box that clips overflow will cut g, p, and y once the line stops at the cap and the baseline. Turn trim off on those controls and you are back to the font’s real metrics.
+
+For the web, fix those metrics in CSS and leave the file alone. Rewriting the font file is the other path, mostly for typographers who need that box everywhere the font is used, not only in one stylesheet.
+
+## Install
 
 ```
 npm i -g normalize-metrics
-normalize-metrics Inter-Regular.otf
-normalize-metrics ./fonts
+```
+
+Or in a repo:
+
+```
+npm i -D normalize-metrics
+```
+
+## CSS
+
+For the web, write a stylesheet and leave the font files alone. `--css` saves `style.css` with `ascent-override`, `descent-override`, and `line-gap-override`.
+
+A single file, a set of files, or a folder:
+
+```
+normalize-metrics Inter-Regular.woff2 Inter-Regular.otf --css
+normalize-metrics ./fonts --css
 ```
 
 Or once, without installing:
 
 ```
-npx normalize-metrics ./fonts
+npx normalize-metrics ./fonts --css
 ```
 
-A folder means every `.otf`, `.ttf`, `.woff`, and `.woff2` inside it. It writes a normalized copy next to the original. Fonts that already have good metrics are left alone. Variable fonts and TTC collections are skipped in v1.
+The stylesheet points at the original files. Do not add those descriptors to an already rewritten font.
+
+## Rewrite
+
+For typographers, and for anywhere a stylesheet cannot go. A folder means every `.otf`, `.ttf`, `.woff`, and `.woff2` inside it. It writes a normalized copy next to the original. Fonts that already have good metrics are left alone. Variable fonts and TTC collections are skipped in v1.
+
+```
+normalize-metrics Inter-Regular.woff2 Inter-Regular.otf
+normalize-metrics ./fonts
+```
 
 Rewriting a licensed font and redistributing the result may violate the EULA. This tool does not legalize the file.
 
@@ -30,13 +58,14 @@ Rewriting a licensed font and redistributing the result may violate the EULA. Th
 ## Usage
 
 ```
-normalize-metrics <file|folder> [options]
+normalize-metrics <file|folder> [more files] [options]
 ```
 
 | Option | What it does |
 | --- | --- |
 | `--check` | Report fonts that are still off; write nothing; exit 1 if any are off |
 | `--dry-run` | Same report; write nothing |
+| `--css [file]` | Write `ascent-override`, `descent-override`, and `line-gap-override` for the original files. Default file is `style.css`. Does not rewrite fonts |
 | `--in-place` | Overwrite the original (opt-in) |
 | `--out-dir <dir>` | Write copies into this directory |
 | `--suffix <text>` | Filename suffix for copies (default: `-normalized`) |
@@ -44,11 +73,7 @@ normalize-metrics <file|folder> [options]
 
 Never overwrites unless you pass `--in-place`.
 
-In a repo, add it as a dev dependency and list the folders in the config. `--check` reports fonts that are still off and exits without writing — useful in CI.
-
-```
-npm i -D normalize-metrics
-```
+In a repo, list the folders in the config. `--check` reports fonts that are still off and exits without writing — useful in CI.
 
 ## Config
 

package/dist/args.js

@@ -1,9 +1,10 @@
 export const HELP = `normalize-metrics — rewrite vertical metrics so a word sits in the box
 
 Usage:
-  normalize-metrics <file|folder> [options]
+  normalize-metrics <file|folder> [more files] [options]
   normalize-metrics [options]
 
+Pass one file, a set of files, or a folder.
 A folder means every .otf, .ttf, .woff, and .woff2 inside it.
 Writes a normalized copy next to the original. Never overwrites unless --in-place.
 Fonts that already have good metrics are left alone.
@@ -11,6 +12,7 @@ Fonts that already have good metrics are left alone.
 Options:
   --check           report fonts that are still off; write nothing; exit 1 if any are off
   --dry-run         same report; write nothing
+  --css [file]      write metric overrides for the original files (default: style.css); do not rewrite fonts
   --in-place        overwrite the original (opt-in)
   --out-dir <dir>   write copies into this directory
   --suffix <text>   filename suffix for copies (default: -normalized)
@@ -23,19 +25,23 @@ Config (normalize-metrics.config.json or "normalize-metrics" in package.json):
 
 Examples:
   normalize-metrics Inter-Regular.otf
+  normalize-metrics Inter-Regular.woff2 GT-America-Regular.otf --css
   normalize-metrics ./fonts
+  normalize-metrics ./fonts --css
   npx normalize-metrics ./fonts --check
 `;
 const FLAGS_WITH_VALUE = new Set(["--out-dir", "--suffix", "--config"]);
+export const DEFAULT_CSS_FILE = "style.css";
 export function parseArgs(argv) {
     const args = {
-        path: null,
+        paths: [],
         check: false,
         dryRun: false,
         inPlace: false,
         outDir: null,
         suffix: null,
         configPath: null,
+        cssPath: null,
         help: false,
         version: false,
     };
@@ -61,6 +67,17 @@ export function parseArgs(argv) {
             args.inPlace = true;
             continue;
         }
+        if (token === "--css") {
+            const value = argv[i + 1];
+            if (value && !value.startsWith("-")) {
+                args.cssPath = value;
+                i += 1;
+            }
+            else {
+                args.cssPath = DEFAULT_CSS_FILE;
+            }
+            continue;
+        }
         if (FLAGS_WITH_VALUE.has(token)) {
             const value = argv[i + 1];
             if (!value || value.startsWith("-")) {
@@ -78,17 +95,22 @@ export function parseArgs(argv) {
         if (token.startsWith("-")) {
             throw new Error(`Unknown flag: ${token}`);
         }
-        if (args.path) {
-            throw new Error("Pass one file or one folder.");
-        }
-        args.path = token;
+        args.paths.push(token);
     }
     if (args.inPlace && args.outDir) {
         throw new Error("Use either --in-place or --out-dir, not both.");
     }
+    if (args.cssPath && !args.cssPath.toLowerCase().endsWith(".css")) {
+        throw new Error("--css needs a .css file.");
+    }
+    if (args.cssPath && (args.check || args.dryRun || args.inPlace || args.outDir)) {
+        throw new Error("--css writes a stylesheet and no font. Leave off --check, --dry-run, --in-place, and --out-dir.");
+    }
     return args;
 }
 export function modeOf(args) {
+    if (args.cssPath)
+        return "css";
     if (args.check)
         return "check";
     if (args.dryRun)

package/dist/css.js

@@ -0,0 +1,134 @@
+import { dirname, extname, relative } from "node:path";
+const HEADER = `/* Generated by normalize-metrics.
+   Line-box overrides for the original files. Does not rewrite the fonts. */`;
+export function metricPercent(units, upm) {
+    if (!Number.isFinite(upm) || upm <= 0) {
+        throw new Error("Font has no units per em.");
+    }
+    const trimmed = ((Math.abs(units) / upm) * 100).toFixed(4).replace(/\.?0+$/, "");
+    return `${trimmed}%`;
+}
+export function fontSrc(cssFile, fontFile) {
+    const rel = relative(dirname(cssFile), fontFile).split("\\").join("/");
+    if (!rel || rel.startsWith("."))
+        return rel || ".";
+    return `./${rel}`;
+}
+export function fontFormat(fontFile) {
+    switch (extname(fontFile).toLowerCase()) {
+        case ".woff2":
+            return "woff2";
+        case ".woff":
+            return "woff";
+        case ".otf":
+            return "opentype";
+        case ".ttf":
+            return "truetype";
+        default:
+            return null;
+    }
+}
+function cssString(value) {
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, " ");
+    return `"${escaped}"`;
+}
+function cssStyle(style) {
+    if (style === "italic" || style === "oblique")
+        return style;
+    return "normal";
+}
+function cssWeight(weight) {
+    if (!weight || weight < 1 || weight > 1000)
+        return 400;
+    return Math.round(weight);
+}
+const FORMAT_ORDER = ["woff2", "woff", "truetype", "opentype"];
+function faceKey(face) {
+    return [
+        face.family,
+        cssWeight(face.weight),
+        cssStyle(face.style),
+        face.ascent,
+        face.descent,
+        face.lineGap,
+        face.upm,
+    ].join("\0");
+}
+function srcRank(fontFile) {
+    const format = fontFormat(fontFile);
+    const index = format ? FORMAT_ORDER.indexOf(format) : -1;
+    return index === -1 ? FORMAT_ORDER.length : index;
+}
+export function groupFaces(faces) {
+    const groups = [];
+    const indexByKey = new Map();
+    for (const face of faces) {
+        const key = faceKey(face);
+        const existing = indexByKey.get(key);
+        if (existing == null) {
+            indexByKey.set(key, groups.length);
+            groups.push([face]);
+            continue;
+        }
+        groups[existing].push(face);
+    }
+    return groups.map((group) => [...group].sort((a, b) => srcRank(a.fontPath) - srcRank(b.fontPath)));
+}
+function srcList(faces, cssFile) {
+    return faces
+        .map((face) => {
+        const url = `url(${cssString(fontSrc(cssFile, face.fontPath))})`;
+        const format = fontFormat(face.fontPath);
+        return format ? `${url} format(${cssString(format)})` : url;
+    })
+        .join(",\n       ");
+}
+export function formatFontFace(faces, cssFile) {
+    const face = faces[0];
+    if (!face)
+        throw new Error("No font faces to write.");
+    return [
+        "@font-face {",
+        `  font-family: ${cssString(face.family)};`,
+        `  src: ${srcList(faces, cssFile)};`,
+        `  font-weight: ${cssWeight(face.weight)};`,
+        `  font-style: ${cssStyle(face.style)};`,
+        `  ascent-override: ${metricPercent(face.ascent, face.upm)};`,
+        `  descent-override: ${metricPercent(face.descent, face.upm)};`,
+        `  line-gap-override: ${metricPercent(face.lineGap, face.upm)};`,
+        "}",
+    ].join("\n");
+}
+export function formatStylesheet(faces, cssFile) {
+    const blocks = groupFaces(faces).map((group) => formatFontFace(group, cssFile));
+    return `${HEADER}\n\n${blocks.join("\n\n")}\n`;
+}
+export function cssFaces(files, outcomes) {
+    const faces = [];
+    files.forEach((file, index) => {
+        const outcome = outcomes[index];
+        if (!outcome || outcome.status !== "css")
+            return;
+        const after = outcome.result.after;
+        if (!after)
+            return;
+        faces.push(faceFromResult(file, outcome.result));
+    });
+    return faces;
+}
+function faceFromResult(file, result) {
+    const after = result.after;
+    if (!after) {
+        throw new Error(`No metrics for ${file.name}`);
+    }
+    return {
+        family: result.family?.trim() || file.name,
+        weight: result.weight ?? 400,
+        style: result.style ?? "normal",
+        fontPath: file.abs,
+        ascent: after.ascent,
+        descent: after.descent,
+        lineGap: after.lineGap,
+        upm: after.upm,
+    };
+}

package/dist/index.js

@@ -1,4 +1,5 @@
-import { basename, resolve } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { HELP, modeOf, parseArgs } from "./args.js";
 import { emptyConfig, findConfig, mergeConfig } from "./config.js";
@@ -7,6 +8,7 @@ import { runEngine } from "./engine.js";
 import { formatOffset, outputPath } from "./paths.js";
 import { formatReports } from "./report.js";
 import { ProgressStack } from "./progress.js";
+import { cssFaces, formatStylesheet } from "./css.js";
 import { EULA, invocationDir, packageVersion, resolvePython } from "./runtime.js";
 import { pathExists } from "./fs-exists.js";
 function phaseFromEngine(phase) {
@@ -58,8 +60,18 @@ async function processFile(file, options) {
 function alreadyGoodDetail(result) {
     return `already good  ${formatOffset(result.before?.offset ?? result.after?.offset)}`;
 }
+const CSS_NOTICE = "This stylesheet overrides the line box in CSS. It does not rewrite the font file.";
 function finishResult(id, dest, result, mode, stack) {
     const offset = formatOffset(result.before?.offset);
+    if (mode === "css") {
+        const good = result.off === false;
+        stack.update(id, {
+            percent: 100,
+            phase: good ? "ok" : "done",
+            detail: good ? alreadyGoodDetail(result) : `${offset} → ${formatOffset(result.after?.offset)}`,
+        });
+        return { status: "css", result };
+    }
     if (result.off === false) {
         stack.update(id, { percent: 100, phase: "ok", detail: alreadyGoodDetail(result) });
         return { status: "ok", result };
@@ -88,6 +100,7 @@ function summarize(outcomes, mode) {
         wrote: outcomes.filter((item) => item.status === "wrote").length,
         would: outcomes.filter((item) => item.status === "would-write").length,
         ok: outcomes.filter((item) => item.status === "ok").length,
+        css: outcomes.filter((item) => item.status === "css").length,
         off: outcomes.filter((item) => item.status === "off").length,
         skipped: outcomes.filter((item) => item.status === "skipped").length,
         failed: outcomes.filter((item) => item.status === "failed").length,
@@ -107,6 +120,9 @@ function summarize(outcomes, mode) {
         parts.push(`${counts.off} off`);
         parts.push(`${counts.ok} ok`);
     }
+    if (mode === "css") {
+        parts.push(`${counts.css} measured`);
+    }
     if (counts.skipped)
         parts.push(`${counts.skipped} skipped`);
     if (counts.failed)
@@ -118,22 +134,35 @@ function exitCode(outcomes, mode) {
         return 1;
     if (mode === "check" && outcomes.some((item) => item.status === "off"))
         return 1;
+    if (mode === "css" && !outcomes.some((item) => item.status === "css"))
+        return 1;
     if (outcomes.length === 0)
         return 1;
     return 0;
 }
 async function resolveTargets(args, cwd, config) {
-    if (args.path) {
-        const target = resolve(cwd, args.path);
-        if (!(await pathExists(target))) {
-            throw new Error(`Not found: ${args.path}`);
+    if (args.paths.length) {
+        const found = [];
+        const seen = new Set();
+        for (const entry of args.paths) {
+            const target = resolve(cwd, entry);
+            if (!(await pathExists(target))) {
+                throw new Error(`Not found: ${entry}`);
+            }
+            const files = await discover(target, config);
+            for (const file of files) {
+                if (seen.has(file.abs))
+                    continue;
+                seen.add(file.abs);
+                found.push(file);
+            }
         }
-        return discover(target, config);
+        return found;
     }
     if (config.include.length) {
         return discoverFromInclude(cwd, config);
     }
-    throw new Error("Point it at a file or a folder. See --help.");
+    throw new Error("Point it at a file, a set of files, or a folder. See --help.");
 }
 export async function main(argv = process.argv.slice(2)) {
     let args;
@@ -161,7 +190,7 @@ export async function main(argv = process.argv.slice(2)) {
         console.error(error instanceof Error ? error.message : error);
         return 2;
     }
-    if (!config.suffix && !args.inPlace) {
+    if (!config.suffix && !args.inPlace && !args.cssPath) {
         console.error("A suffix is required unless you pass --in-place. Default is -normalized.");
         return 2;
     }
@@ -193,7 +222,7 @@ export async function main(argv = process.argv.slice(2)) {
     };
     process.on("SIGINT", onInterrupt);
     process.on("SIGTERM", onInterrupt);
-    stack.identify(files.map((file) => ({ id: file.abs, label: files.length > 1 ? file.rel : file.name })), EULA);
+    stack.identify(files.map((file) => ({ id: file.abs, label: files.length > 1 ? file.rel : file.name })), mode === "css" ? CSS_NOTICE : EULA);
     const outcomes = [];
     for (const file of files) {
         outcomes.push(await processFile(file, { python, mode, inPlace: args.inPlace, config, stack }));
@@ -204,6 +233,19 @@ export async function main(argv = process.argv.slice(2)) {
     const reports = formatReports(outcomes);
     if (reports)
         process.stdout.write(`\n${reports}\n`);
+    if (mode === "css" && args.cssPath) {
+        const faces = cssFaces(files, outcomes);
+        if (!faces.length) {
+            console.error("No faces to write.");
+        }
+        else {
+            const cssFile = resolve(cwd, args.cssPath);
+            await mkdir(dirname(cssFile), { recursive: true });
+            await writeFile(cssFile, formatStylesheet(faces, cssFile), "utf8");
+            const wrote = process.stderr.isTTY ? process.stderr : process.stdout;
+            wrote.write(`\nWrote ${cssFile}\n`);
+        }
+    }
     const summary = summarize(outcomes, mode);
     if (summary) {
         const stream = process.stderr.isTTY ? process.stderr : process.stdout;

package/lib/engine.py

@@ -86,6 +86,13 @@ def measure_bbox(font: TTFont, progress: Progress | None = None) -> tuple[int, i
     return y_min, y_max
 
 
+def units_percent(units: float, upm: int) -> float:
+    """CSS ascent-override / descent-override: |units| as a percent of the em."""
+    if upm <= 0:
+        return 0.0
+    return round(abs(units) / upm * 100, 1)
+
+
 def snapshot(font: TTFont, cap: int, x_height: int) -> dict:
     upm = font["head"].unitsPerEm
     hhea = font["hhea"]
@@ -108,10 +115,35 @@ def snapshot(font: TTFont, cap: int, x_height: int) -> dict:
         "below": round(below / upm * 1000, 1),
         "offset": round(offset_pm, 1),
         "centered": centered,
+        "ascentOverride": units_percent(hhea.ascent, upm),
+        "descentOverride": units_percent(hhea.descent, upm),
         "grade": grade,
     }
 
 
+ITALIC = 1 << 0
+OBLIQUE = 1 << 9
+
+
+def face_style(font: TTFont) -> str:
+    selection = int(getattr(font["OS/2"], "fsSelection", 0))
+    if selection & ITALIC:
+        return "italic"
+    if selection & OBLIQUE:
+        return "oblique"
+    subfamily = (font["name"].getDebugName(2) or "").lower()
+    if "italic" in subfamily:
+        return "italic"
+    if "oblique" in subfamily:
+        return "oblique"
+    return "normal"
+
+
+def face_weight(font: TTFont) -> int:
+    weight = int(getattr(font["OS/2"], "usWeightClass", 400) or 400)
+    return weight
+
+
 def set_name_suffix(font: TTFont, suffix: str = " Normalized") -> None:
     name = font["name"]
     for rec in list(name.names):
@@ -225,6 +257,8 @@ def normalize(font: TTFont, progress: Progress | None = None) -> dict:
     family = font["name"].getDebugName(1) or "Font"
     return {
         "family": family.replace(" Normalized", ""),
+        "weight": face_weight(font),
+        "style": face_style(font),
         "before": before,
         "after": after,
         "off": off,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "normalize-metrics",
-  "version": "0.1.1",
-  "description": "Rewrite font vertical metrics so a word sits in the box",
+  "version": "0.2.0",
+  "description": "Fix font vertical metrics so a word sits in the box, as CSS overrides or a rewritten file",
   "license": "MIT",
   "author": {
     "name": "Oles Gergun",
@@ -9,12 +9,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/gerguno/normalize-metrics-cli.git"
+    "url": "git+https://github.com/gerguno/normalize-metrics.git"
   },
   "bugs": {
-    "url": "https://github.com/gerguno/normalize-metrics-cli/issues"
+    "url": "https://github.com/gerguno/normalize-metrics/issues"
   },
-  "homepage": "https://github.com/gerguno/normalize-metrics-cli#readme",
+  "homepage": "https://normalize-metrics.olesgergun.com",
   "keywords": [
     "font",
     "fonts",
@@ -23,6 +23,8 @@
     "otf",
     "ttf",
     "woff",
+    "woff2",
+    "css",
     "typography",
     "cli"
   ],
@@ -41,14 +43,27 @@
     "access": "public"
   },
   "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "deploy": "next build && next start -p 3014",
     "cli": "node --experimental-strip-types --experimental-default-type=module --no-warnings=ExperimentalWarning cli/index.ts",
-    "test": "node --experimental-strip-types --experimental-default-type=module --test cli/*.test.ts",
-    "build": "tsc -p cli/tsconfig.build.json && printf '{\"type\":\"module\"}\\n' > dist/package.json",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm test"
+    "test:cli": "node --experimental-strip-types --experimental-default-type=module --test cli/*.test.ts",
+    "build:cli": "tsc -p cli/tsconfig.build.json && printf '{\"type\":\"module\"}\\n' > dist/package.json",
+    "prepack": "npm run build:cli",
+    "prepublishOnly": "npm run test:cli"
   },
   "devDependencies": {
     "@types/node": "^22.18.1",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "motion": "^13.4.0",
+    "next": "^15.5.3",
+    "overlayscrollbars": "^2.16.0",
+    "overlayscrollbars-react": "^0.5.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "sass": "^1.104.1",
     "typescript": "^5.9.2"
   }
 }