webfont 11.2.20 → 12.0.0

package/NOTICE.md

@@ -0,0 +1,153 @@
+# webfont — Legal notice
+
+This document covers **copyright and licensing for fonts you process**, **disclaimers** about using the webfont software, **community attribution guidelines**, and **third-party open-source components** bundled with or used by this project.
+
+It does **not** replace the [MIT License](./LICENSE) for the webfont source code. If anything here conflicts with `LICENSE`, `LICENSE` governs the software itself.
+
+**This is not legal advice.** When in doubt about a font or icon license, consult the rights holder or qualified counsel.
+
+---
+
+## 1. webfont software license
+
+The **webfont** program (source code, CLI, and npm package) is licensed under the **[MIT License](./LICENSE)**.
+
+Copyright (c) 2016–present [itgalaxy](https://github.com/itgalaxy).
+
+You may use, copy, modify, and distribute the **software** under the terms of `LICENSE`, provided the copyright and permission notice are preserved in copies or substantial portions.
+
+---
+
+## 2. Disclaimer of warranties and limitation of liability
+
+THE WEBFONT 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.
+
+**You are solely responsible** for how you use webfont, what files you pass into it, and what you do with the output.
+
+---
+
+## 3. Fonts and icons you provide (user content)
+
+webfont is a **technical tool**. It does **not**:
+
+- grant any copyright, trademark, or distribution rights in fonts or icons;
+- change the license terms of input or output files;
+- verify that you have permission to use, modify, decompress, convert, or redistribute any font or SVG;
+- remove or replace copyright or license metadata embedded in font files (name tables, etc.).
+
+### 3.1 SVG icon input
+
+If you build a font from **`.svg` icons**, you must have the right to use those artworks (your own work, licensed stock, client assets with permission, open-source icons under compatible terms, etc.).
+
+Generated font files may be subject to the same restrictions as the source icons and to any third-party notices you embed via options such as `metadata` / `copyright`.
+
+### 3.2 WOFF / WOFF2 decompression
+
+If you **decompress** one or more `.woff` or `.woff2` files (from disk or from an `http(s)` URL) to `.ttf` or `.otf`, you are extracting the **SFNT payload** inside each container. That operation:
+
+- does **not** make a restricted or commercial font free to use or share;
+- does **not** bypass foundry EULAs, app terms of service, CDN hotlinking policies, or site download terms;
+- may produce files that are **easier to reuse** than the original webfonts — compliance with the **original font license** remains your obligation;
+- does **not** merge multiple weights into one font file — each input yields a separate output.
+
+**Only process fonts you are authorized to use and download** under their license. For remote URLs, you must also have permission to fetch and store those bytes.
+
+### 3.3 Redistribution of output
+
+Publishing, shipping, or sublicensing fonts produced or extracted with webfont (in apps, websites, PDFs, design assets, npm packages, etc.) is **your responsibility**. The MIT license on webfont does **not** apply to those font files.
+
+---
+
+## 4. Community attribution guidelines
+
+These guidelines help the community use and reference webfont fairly. They are **social expectations**, not additional legal terms beyond `LICENSE`.
+
+### 4.1 Using webfont in your project
+
+- **No attribution required** for normal use (install via npm, run in CI, internal tooling) under the MIT License.
+- **Appreciated** when webfont is a visible part of a product, tutorial, or open-source repo: mention [webfont](https://github.com/itgalaxy/webfont) and link to the repository or [npm package](https://www.npmjs.com/package/webfont).
+
+### 4.2 Tutorials, posts, and courses
+
+When documenting a workflow that centers on webfont, please:
+
+- name the tool (**webfont**) and link to the official repo or npm page;
+- distinguish **webfont the software** (MIT) from **fonts you demonstrate** (which may be proprietary);
+- avoid implying **endorsement** by itgalaxy unless you have written permission.
+
+### 4.3 Forks, wrappers, and hosted services
+
+If you redistribute webfont code, ship a fork, or offer a hosted “font converter” built on webfont:
+
+- comply with the **MIT License** (retain copyright and permission notice);
+- do **not** use the itgalaxy name, logo, or webfont branding to suggest official affiliation without permission;
+- provide **your own** terms and privacy policy for user-uploaded fonts; make clear that **users** must have rights to their files.
+
+### 4.4 Citing underlying libraries
+
+webfont builds on several open-source font libraries (see [Section 5](#5-third-party-open-source-dependencies)). If you publish academic work, a detailed case study, or compliance documentation that discusses **how** conversion is implemented, consider citing those libraries alongside webfont.
+
+---
+
+## 5. Third-party open-source dependencies
+
+webfont depends on the following **runtime** npm packages (direct dependencies). Versions follow `package.json` / `package-lock.json` at release time.
+
+| Package | Typical license | Role in webfont |
+|---------|-----------------|-----------------|
+| [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) | MIT | Configuration file discovery |
+| [deepmerge](https://github.com/TehShrike/deepmerge) | MIT | Option merging |
+| [fontverter](https://github.com/papandreou/fontverter) | BSD-3-Clause | WOFF/WOFF2 → SFNT decompression |
+| [globby](https://github.com/sindresorhus/globby) | MIT | Input file globbing |
+| [meow](https://github.com/sindresorhus/meow) | MIT | CLI argument parsing |
+| [nunjucks](https://github.com/mozilla/nunjucks) | BSD-2-Clause | CSS / SCSS / Styl templates |
+| [p-limit](https://github.com/sindresorhus/p-limit) | MIT | Concurrency limiting |
+| [resolve-from](https://github.com/sindresorhus/resolve-from) | MIT | Module resolution |
+| [svg2ttf](https://github.com/fontello/svg2ttf) | MIT | SVG font → TTF |
+| [svgicons2svgfont](https://github.com/nfroidure/svgicons2svgfont) | MIT | SVG icons → SVG font |
+| [ttf2eot](https://github.com/fontello/ttf2eot) | MIT | TTF → EOT |
+| [ttf2woff](https://github.com/fontello/ttf2woff) | MIT | TTF → WOFF |
+| [wawoff2](https://github.com/fontello/wawoff2) | MIT | TTF ↔ WOFF2 compression |
+| [xml2js](https://github.com/Leonidas-from-XIV/node-xml2js) | MIT | SVG XML parsing |
+
+Transitive dependencies (and their licenses) are recorded in `package-lock.json`. For a full license report after install, you can run:
+
+```shell
+npx license-checker --production --direct
+```
+
+(Third-party tool; not maintained by this project.)
+
+### BSD-licensed components
+
+**fontverter** (BSD-3-Clause) and **nunjucks** (BSD-2-Clause) are subject to their own copyright notices and license terms. Redistributions of webfont that include source or substantial portions of those dependencies should preserve their respective notices as required by those licenses.
+
+---
+
+## 6. Test fixtures and examples
+
+Font and SVG files under `src/fixtures/` are intended **for automated tests and documentation examples** only. They are not a grant of rights to use those assets outside this repository. Do not assume fixture fonts or icons are redistributable for your own products.
+
+---
+
+## 7. Keeping this document current
+
+Update **NOTICE.md** in the same pull request when you:
+
+- add or remove **runtime dependencies** that affect licensing or attribution;
+- change **user-facing behavior** around font decompression or output formats in ways that affect legal expectations;
+- publish new **community guidelines** for attribution or acceptable use.
+
+See also [FEATURES.md](./FEATURES.md) (product capabilities) and [CONTRIBUTING.md](./CONTRIBUTING.md) (documentation expectations).
+
+---
+
+## 8. Questions and reports
+
+- **Software bugs and features:** [GitHub Issues](https://github.com/itgalaxy/webfont/issues)
+- **Code of conduct:** [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+- **License of the webfont source:** [LICENSE](./LICENSE)
+
+For font licensing questions about **your** input files, contact the font foundry, vendor, or rights holder — maintainers cannot advise on third-party font EULAs.

package/README.md

@@ -4,25 +4,55 @@
 [![Travis Build Status](https://img.shields.io/travis/itgalaxy/webfont/master.svg?label=build)](https://travis-ci.org/itgalaxy/webfont)
 [![Build status](https://ci.appveyor.com/api/projects/status/a8absovr2r44w1oc?svg=true)](https://ci.appveyor.com/project/evilebottnawi/webfont)
 
-Generator of fonts from SVG icons.
+Generator of fonts from SVG icons, with a separate mode to **decompress** WOFF/WOFF2 containers to the TTF or OTF inside.
+
+See **[FEATURES.md](./FEATURES.md)** for the canonical capability list (what is stable, in progress, or planned).
+
+**Legal / licensing:** [NOTICE.md](./NOTICE.md) — font copyright, disclaimers, attribution guidelines, and third-party library notices.
 
 ## Features
 
-- Supported font formats: `WOFF2`, `WOFF`, `EOT`, `TTF` and `SVG`;
-- Support config files: use a `JavaScript`, `JSON` or `YAML` file to specify configuration information for an entire directory and all of its subdirectories;
-- Support all popular browsers, including IE8+;
-- Allows using custom templates (example `css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/) etc);
-- No extra dependencies as `gulp`, `grunt` or other big tools;
-- Tested on all platforms (`linux`, `windows` and `osx`);
-- CLI;
+- **SVG icon pipeline** (default): `.svg` icons → `svg`, `ttf`, `eot`, `woff`, `woff2` (not `otf`);
+- **Webfont decompression**: one `.woff` or `.woff2` file → `ttf` and/or `otf` matching the **embedded SFNT flavor** (decompress only — not TTF ↔ OTF transcoding);
+- Config files: `JavaScript`, `JSON`, or `YAML` via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig);
+- Built-in and custom CSS templates (`css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/));
+- CLI and programmatic API;
 - [Webpack plugin](https://github.com/itgalaxy/webfont-webpack-plugin).
 
+## Input modes
+
+webfont runs one of two pipelines depending on matched input files. They cannot be mixed in a single run.
+
+| Mode | Input | Outputs | Notes |
+|------|--------|---------|--------|
+| **SVG icons** | One or more `.svg` files | `svg`, `ttf`, `eot`, `woff`, `woff2` | Default. Builds TrueType via `svg2ttf`. **`otf` is rejected** — use `ttf`. |
+| **Webfont decompress** | One or more `.woff` / `.woff2` paths, globs, or `http(s)` URLs | `ttf` and/or `otf` per input | One output file per source (basename from filename; collisions get `-woff`/`-woff2`). Not a single merged font. |
+
+**Not supported today**
+
+- Renaming or re-wrapping without matching the real outline format (e.g. requesting `otf` when the WOFF2 holds TrueType).
+- Converting TTF to OTF (or OTF to TTF) — use [FontForge](https://fontforge.org/) or similar.
+- Templates, `glyphTransformFn`, or merged multi-weight SFNT output in webfont decompress mode.
+- Globs that match extension-less or unsupported files together with fonts (the run fails instead of silently ignoring extras).
+
+Every matched path must end in `.svg`, `.woff`, or `.woff2`. See [FEATURES.md](./FEATURES.md) for test-backed criteria.
+
+### Font licensing
+
+webfont is a technical tool. **Decompressing or generating fonts does not grant you any rights to those fonts.** You must have permission to use, convert, and redistribute every input file and every output file under the applicable license (commercial fonts, app-bundled webfonts, client icons, etc.). The MIT license applies to **this software only**, not to fonts you pass through it.
+
+Full details, disclaimers, community attribution guidelines, and third-party library notices: **[NOTICE.md](./NOTICE.md)**.
+
 ## Table Of Contents
 
 - [Webfont](#webfont)
+  - [Features](#features)
+  - [Input modes](#input-modes)
+  - [Font licensing](#font-licensing)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Options](#options)
+  - [Result](#result)
   - [svgicons2svgfont](#svgicons2svgfont)
 - [Command Line Interface (CLI)](#command-line-interface)
   - [Installation](#cli-installation)
@@ -32,6 +62,7 @@ Generator of fonts from SVG icons.
 - [Roadmap](#roadmap)
 - [Contribution](#contribution)
 - [Changelog](#changelog)
+- [Legal notice](#legal-notice)
 - [License](#license)
 
 ---
@@ -82,13 +113,42 @@ webfont({
   });
 ```
 
+### Webfont decompress examples
+
+```js
+import webfont from "webfont";
+
+// Single local file
+const one = await webfont({
+  files: "path/to/font.woff2",
+  formats: ["ttf"],
+});
+
+// Batch: multiple files in one run (one TTF/OTF output per input)
+const batch = await webfont({
+  files: ["fonts/Inter-Regular.woff2", "fonts/Inter-Bold.woff2"],
+  formats: ["ttf"],
+});
+// batch.decompressedFonts → [{ source, ttf }, …]
+
+// Remote URL (http or https)
+const remote = await webfont({
+  files: "https://cdn.example.com/fonts/Inter-Medium.woff2",
+  formats: ["ttf"],
+});
+```
+
 ### Options
 
 #### `files`
 
 - Type: `string` | `array`
 - Description: A file glob, or array of file globs. Ultimately passed to [fast-glob](https://github.com/mrmlnc/fast-glob) to figure out what files you want to get.
-- Note: `node_modules` and `bower_components` are always ignored.
+- **SVG mode**: one or more `.svg` icon paths or globs (default pipeline).
+- **Webfont decompress mode**: one or more `.woff` / `.woff2` paths, globs, or `https://…` URLs (see [`formats`](#formats) and [Input modes](#input-modes)).
+- Do not mix `.svg` with `.woff` / `.woff2` in the same run.
+- Every matched file must have a supported extension (`.svg`, `.woff`, `.woff2`); extension-less files such as `LICENSE` are not ignored when matched by a broad glob.
+- `node_modules` and `bower_components` are always ignored.
 
 #### `configFile`
 
@@ -99,6 +159,7 @@ webfont({
   2. a `.webfontrc` file (with or without filename extension: `.json`, `.yaml`, and `.js` are available)
   3. a `webfont.config.js` file exporting a JS `object`.
      The search will begin in the working directory and move up the directory tree until it finds a configuration file.
+- Note: When a configuration file is discovered or loaded, the resolved absolute path is available on `result.config.filePath` (see [Result](#result)).
 
 #### `fontName`
 
@@ -108,10 +169,13 @@ webfont({
 
 #### `formats`
 
-- Type: `array`,
-- Default: `['svg', 'ttf', 'eot', 'woff', 'woff2']`,
-- Possible values: `svg, ttf, eot, woff, woff2`,
+- Type: `array`
+- Default: `['svg', 'ttf', 'eot', 'woff', 'woff2']` (SVG input). For WOFF/WOFF2 input, defaults to `['ttf']` when SVG-pipeline formats are still configured.
+- Possible values: `svg`, `ttf`, `otf`, `eot`, `woff`, `woff2`
 - Description: Font file types to generate.
+  - **SVG input**: `svg`, `ttf`, `eot`, `woff`, `woff2` only. **`otf` is not supported** (pipeline uses TrueType outlines).
+  - **WOFF/WOFF2 input**: `ttf` and/or `otf` only — must match the decompressed SFNT flavor inside the file (not arbitrary transcoding). `eot`, `woff`, `woff2`, and `svg` are not produced in this mode.
+- CLI: pass `-f` / `--formats` as a JSON array (for example `'["woff2"]'`) or as a comma-separated list (for example `woff2` or `svg, ttf, woff2`). Invalid format names throw an error.
 
 #### `template`
 
@@ -160,6 +224,12 @@ webfont({
 - Default: Gets is from `fontName` if not set, but you can specify any value.
 - Description: Template font family name you want.
 
+#### `ligatures`
+
+- Type: `boolean`
+- Default: `true`
+- Description: Turn on/off adding ligature unicode
+
 #### `glyphTransformFn`
 
 - Type: `function`
@@ -190,12 +260,50 @@ webfont({
     });
   ```
 
+#### `metadataProvider`
+
+- Type: `function`
+- Default: built-in metadata service (reads icon names and unicode from SVG files)
+- 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";
+
+  webfont({
+    files: "src/svg-icons/**/*.svg",
+    metadataProvider: (srcPath, callback) => {
+      callback(null, { name: "custom-icon-name" });
+    },
+  });
+  ```
+
 #### `sort`
 
 - Type: `bool`
 - Default: `true`
 - Description: Whether you want to sort the icons sorted by name.
 
+### Result
+
+`webfont()` resolves to an object with generated font buffers (and optional `template` output). The `config` property contains the **effective options** used for the run (defaults, discovered config, and any options you passed in), plus optional **output metadata** when a configuration file was found or loaded.
+
+#### `result.config.filePath`
+
+- Type: `string` | `undefined`
+- Description: Absolute path to the configuration file that was discovered (`search`) or loaded (`configFile` / CLI `--config`). Omitted when no configuration file was found and defaults were used.
+- Note: Output-only metadata — not an input option. Do not set `filePath` in `.webfontrc`, `package.json`, or the `webfont()` call; values passed that way are ignored.
+- Example:
+
+  ```js
+  const result = await webfont({
+    files: "src/svg-icons/**/*.svg",
+  });
+
+  if (result.config?.filePath) {
+    console.log(`Loaded config from ${result.config.filePath}`);
+  }
+  ```
+
 ---
 
 ## svgicons2svgfont
@@ -277,12 +385,6 @@ These can be appended to [webfont options](#options). These are passed directly
 - Description: The font [metadata](http://www.w3.org/TR/SVG/metadata.html).
   You can set any character data in, but this is the recommended place for a copyright mention.
 
-#### `svgicons2svgfont.log`
-
-- Type: `function`
-- Default: `console.log`
-- Description: Allows you to provide your own logging function. Set to `function(){}` to disable logging.
-
 ---
 
 ## Command Line Interface
@@ -296,7 +398,7 @@ Add the `cli` script to your `package.json` file's `scripts` object:
 ```json
 {
   "scripts": {
-    "webfont": "node node_modules/webfont/dist/cli.js"
+    "webfont": "node node_modules/webfont/dist/cli.mjs"
   }
 }
 ```
@@ -306,7 +408,7 @@ If you're using cross-env:
 ```json
 {
   "scripts": {
-    "webfont": "cross-env node_modules/webfont/dist/cli.js"
+    "webfont": "cross-env node_modules/webfont/dist/cli.mjs"
   }
 }
 ```
@@ -336,7 +438,7 @@ If you're using cross-env:
             The search will begin in the working directory and move up the
             directory tree until a configuration file is found.
 
-        -f, --font-name
+        -u, --fontName
 
             The font family name you want, default: "webfont".
 
@@ -348,9 +450,12 @@ If you're using cross-env:
 
             Output the version number.
 
-        -r, --formats
+        -f, --formats
 
-            Only this formats generate.
+            Font formats to generate. Pass a JSON array (e.g. '["woff2"]') or a
+            comma-separated list (e.g. woff2 or svg, ttf, woff2).
+            SVG input: svg, ttf, eot, woff, woff2 (not otf).
+            WOFF/WOFF2 input: ttf and/or otf matching the embedded SFNT flavor.
 
         -d, --dest
 
@@ -468,10 +573,8 @@ The CLI can exit the process with the following exit codes:
 
 ## Roadmap
 
-- The ability to generate from any type to any type;
-- More tests, include CLI test;
-- Improved docs;
-- Reduce package size (maybe implement `ttf2woff2` with native js library);
+- Arbitrary format transcoding (e.g. TTF ↔ OTF outline conversion) — see [FEATURES.md](./FEATURES.md) (“Arbitrary format transcoding”, planned);
+- Reduce package size (maybe implement `ttf2woff2` with a native JS library);
 - Improve performance (maybe use cache for this).
 
 ## Contribution
@@ -482,6 +585,10 @@ Feel free to push your code if you agree with publishing under the MIT license.
 
 Check our [Changelog](CHANGELOG.md)
 
+## Legal notice
+
+Copyright, disclaimers, font licensing expectations (including WOFF/WOFF2 decompression), community attribution guidelines, and third-party open-source dependencies are documented in **[NOTICE.md](./NOTICE.md)**.
+
 ## License
 
-Check our [License](LICENSE)
+The **webfont software** is licensed under the [MIT License](./LICENSE). That license does **not** apply to fonts or icons you process with the tool — see [NOTICE.md](./NOTICE.md).