webfont 12.1.0 → 12.2.0

package/README.md

@@ -75,7 +75,7 @@ Full details, disclaimers, community attribution guidelines, and third-party lib
 
 ## Installation
 
-Requires **Node.js** >= 24.14.0. Install as a dev dependency and run at **build time** (CLI, npm script, or bundler plugin) — not from browser/React client bundles.
+Requires **Node.js** >= 24.14.0 (aligned with `svgicons2svgfont@16`). CI tests on Node 24.x and 26.x. Install as a dev dependency and run at **build time** (CLI, npm script, or bundler plugin) — not from browser/React client bundles.
 
 ```shell
 npm install --save-dev webfont
@@ -85,8 +85,26 @@ npm install --save-dev webfont
 
 Node.js only — do not import from client-side app code ([#198](https://github.com/itgalaxy/webfont/issues/198)).
 
+### Import (ESM and CommonJS)
+
+Use the **named export** — required for native ESM and recommended since webfont **10+**:
+
+```js
+import { webfont } from "webfont";
+```
+
+CommonJS:
+
+```js
+const { webfont } = require("webfont");
+```
+
+`import webfont from "webfont"` is callable in versions that ship the ESM build (**12.x+**), where the default export is the `webfont` function itself ([#618](https://github.com/itgalaxy/webfont/issues/618)). On older releases the default import resolved to the whole `module.exports` object and threw `TypeError: webfont is not a function` under `"type": "module"`. The named import remains the recommended form for new code. See the [migration notes](./docs/migration/issue-0618-esm-default-import.md).
+
+### Basic example
+
 ```js
-import webfont from "webfont";
+import { webfont } from "webfont";
 
 webfont({
   files: "src/svg-icons/**/*.svg",
@@ -106,7 +124,7 @@ webfont({
 or
 
 ```js
-const webfont = require("webfont").default;
+const { webfont } = require("webfont");
 
 webfont({
   files: "src/svg-icons/**/*.svg",
@@ -126,7 +144,7 @@ webfont({
 ### TTF encoding examples
 
 ```js
-import webfont from "webfont";
+import { webfont } from "webfont";
 
 // Single local TTF → WOFF + WOFF2 (default when formats unset)
 const encoded = await webfont({
@@ -150,7 +168,7 @@ const batch = await webfont({
 ### Webfont decompress examples
 
 ```js
-import webfont from "webfont";
+import { webfont } from "webfont";
 
 // Single local file
 const one = await webfont({
@@ -284,7 +302,7 @@ webfont "icons/*.svg" -d dist/icons -t scss --addHashInFontUrl
 ```
 
 ```js
-import webfont from "webfont";
+import { webfont } from "webfont";
 
 await webfont({
   files: "src/icons/**/*.svg",
@@ -332,7 +350,7 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 - Example:
 
   ```js
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   webfont({
     files: "src/svg-icons/**/*.svg",
@@ -363,7 +381,7 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 
   ```js
   import outlineStroke from "svg-outline-stroke";
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   await webfont({
     files: "src/svg-icons/**/*.svg",
@@ -382,7 +400,7 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 - Optional: `svgoConfig` — SVGO `Config` object; when `plugins` is set, it replaces the built-in conservative plugin list.
 
   ```js
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   await webfont({
     files: "src/icons/**/*.svg",
@@ -399,13 +417,13 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 - Type: `{ diagnose?: boolean; onMessage?: (message: string) => void }`
 - Default: `undefined` (disabled)
 - Description: **Alpha.** Scan SVG sources for icon-font incompatibilities before font generation (SVG pipeline only). Does **not** modify SVGs — use [`glyphContentTransformFn`](#glyphcontenttransformfn) to preprocess (for example stroke-to-fill with [`svg-outline-stroke`](https://github.com/elrumordelaluz/outline-stroke), installed in your project). See [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md).
-  - **`diagnose`:** log warnings for `fill-rule: evenodd`, stroke-only paths (`fill="none"` + `stroke`), and poorly supported elements (`<line>`, `<polyline>`, `<clipPath>`). Results are also returned on `result.svgDiagnostics` when enabled.
+  - **`diagnose`:** log warnings for `fill-rule: evenodd`, stroke-only paths (`fill="none"` + `stroke`), `<use>` symbol references ([#612](https://github.com/itgalaxy/webfont/issues/612)), and poorly supported elements (`<line>`, `<polyline>`, `<clipPath>`). Results are also returned on `result.svgDiagnostics` when enabled.
   - **`onMessage`:** optional sink for diagnostic log lines (tests, custom UIs).
 - CLI: `--svg-diagnose` (alpha).
 - Example:
 
   ```js
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   const result = await webfont({
     files: "src/icons/**/*.svg",
@@ -417,6 +435,24 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 
   See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — “Icon details missing after export”.
 
+#### `ttfPostProcess`
+
+- Type: `function`
+- Default: `undefined`
+- Description: Post-process the generated **TTF** buffer **after** it is built and **before** webfont derives WOFF/WOFF2/EOT from it (SVG pipeline only). The callback receives `(ttf, { fontName, formats })` and returns the new font bytes (`Buffer` or `Uint8Array`, sync or async). Every derived format is produced from the returned buffer. This is a **caller-owned** extension point — webfont bundles nothing here, so optional/native steps such as **autohinting** (`ttfautohint`) live in **your** project or a separate package, keeping the core free of native dependencies (same philosophy as [`glyphContentTransformFn`](#glyphcontenttransformfn) and [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md); see [#749](https://github.com/itgalaxy/webfont/issues/749)).
+- Example (autohinting — **install the hinting tool in your app**, not in webfont):
+
+  ```js
+  import { webfont } from "webfont";
+  import { autohint } from "some-ttfautohint-wrapper";
+
+  await webfont({
+    files: "src/svg-icons/**/*.svg",
+    formats: ["ttf", "woff2"],
+    ttfPostProcess: async (ttf) => autohint(ttf),
+  });
+  ```
+
 #### `metadataProvider`
 
 - Type: `function`
@@ -424,7 +460,7 @@ Do **not** use `Math.random()` in `fontName` — that renames both font files an
 - Description: Custom callback to resolve glyph metadata for each source file. Receives the file path and a Node-style callback `(error, metadata)` where `metadata` is `{ name: string, unicode?: string | string[] }`. When omitted, webfont uses its default metadata reader.
 
   ```js
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   webfont({
     files: "src/svg-icons/**/*.svg",
@@ -505,6 +541,12 @@ These can be appended to [webfont options](#options). These are passed directly
 - Default: `false`
 - Description: Calculate the bounds of a glyph and center it horizontally.
 
+#### `svgicons2svgfont.centerVertically`
+
+- Type: `boolean`
+- Default: `false`
+- Description: Center the glyphs vertically in the generated font.
+
 #### `svgicons2svgfont.normalize`
 
 - Type: `boolean`
@@ -675,6 +717,10 @@ If you're using cross-env:
 
             Calculate the bounds of a glyph and center it horizontally.
 
+        --center-vertically
+
+            Center the glyphs vertically in the generated font.
+
         --normalize
 
             Normalize icons by scaling them to the height of the highest icon.