@featherk/icons 0.13.9 → 0.14.1

package/dist/fontawesome/cli.d.ts

@@ -0,0 +1,6 @@
+export interface FontAwesomeCliIO {
+    cwd?: string;
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+}
+export declare function runFontAwesomeCli(args: readonly string[], io?: FontAwesomeCliIO): Promise<number>;

package/dist/fontawesome/cli.mjs

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { g as generateFaIcons } from "./chunks/generate-Bp92GTVi.mjs";
+const usage = `Usage: featherk-fontawesome --manifest <icons.json> [--root <project>] [--source-root <installed-sources>] [--out <icons.mjs>] [--virtual-types <types.d.ts>]
+
+The JSON manifest must contain { "icons": [...] } with exact installed selections.
+Provide --out, --virtual-types, or both. Paths are relative to the project root.
+This command does not download assets or authenticate; install licensed packages first.
+Generated assets belong to the consuming project, never the @featherk/icons package.`;
+async function runFontAwesomeCli(args, io = {}) {
+  const stdout = io.stdout ?? console.log;
+  const stderr = io.stderr ?? console.error;
+  try {
+    const { values } = parseArgs({
+      args: [...args],
+      options: {
+        manifest: { type: "string" },
+        root: { type: "string" },
+        "source-root": { type: "string" },
+        out: { type: "string" },
+        "virtual-types": { type: "string" },
+        help: { type: "boolean", short: "h" }
+      },
+      strict: true,
+      allowPositionals: false
+    });
+    if (values.help) {
+      stdout(usage);
+      return 0;
+    }
+    if (!values.manifest?.trim() || !values.out?.trim() && !values["virtual-types"]?.trim()) {
+      throw new Error(
+        "Provide --manifest and at least one of --out or --virtual-types. Use --help for usage."
+      );
+    }
+    const root = resolve(io.cwd ?? process.cwd(), values.root ?? ".");
+    const manifest = JSON.parse(
+      await readFile(resolve(root, values.manifest), "utf8")
+    );
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest) || !Array.isArray(manifest.icons)) {
+      throw new Error(
+        'Font Awesome manifest must be a JSON object with an "icons" array'
+      );
+    }
+    const result = await generateFaIcons({
+      root,
+      sourceRoot: values["source-root"],
+      icons: manifest.icons,
+      outFile: values.out,
+      virtualTypesFile: values["virtual-types"]
+    });
+    stdout(
+      `Prepared ${result.provenance.length} selected Font Awesome icon(s). Preserve generated license notices in application distribution.`
+    );
+    return 0;
+  } catch (error) {
+    stderr(
+      `Font Awesome generation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+    return 1;
+  }
+}
+export {
+  runFontAwesomeCli
+};

package/dist/fontawesome/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fontawesome/fontawesome-service.d.ts

@@ -0,0 +1,5 @@
+import type { FontAwesomeIcon } from "./types";
+export interface FontAwesomeService<Key extends string = string> {
+    getFaIcon(key: Key): FontAwesomeIcon;
+}
+export declare function createFontAwesomeService<Key extends string>(icons: Readonly<Record<Key, FontAwesomeIcon>>): FontAwesomeService<Key>;

package/dist/fontawesome/fontawesome-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fontawesome/generate.d.ts

@@ -0,0 +1,18 @@
+import type { FontAwesomeOptions, FontAwesomeSelection } from "./types";
+export interface GenerateFaIconsOptions extends FontAwesomeOptions {
+    outFile?: string;
+    virtualTypesFile?: string;
+}
+export interface FontAwesomeProvenance extends FontAwesomeSelection {
+    sourcePackage: string;
+    exportName: string;
+}
+export interface GeneratedFaIcons {
+    moduleCode: string;
+    declarationCode: string;
+    virtualDeclarationCode: string;
+    notices: string;
+    provenance: readonly FontAwesomeProvenance[];
+    dependencies: readonly string[];
+}
+export declare function generateFaIcons(options: GenerateFaIconsOptions): Promise<GeneratedFaIcons>;

package/dist/fontawesome/generate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fontawesome/index.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function createFontAwesomeService(icons) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(icons)) {
+    registry.set(key, { ...icons[key] });
+  }
+  return {
+    getFaIcon(key) {
+      const icon = registry.get(key);
+      if (!icon) {
+        throw new Error(
+          `Font Awesome icon "${key}" is not in this project's selections`
+        );
+      }
+      return { ...icon };
+    }
+  };
+}
+exports.createFontAwesomeService = createFontAwesomeService;

package/dist/fontawesome/index.d.ts

@@ -0,0 +1,3 @@
+export { createFontAwesomeService } from "./fontawesome-service";
+export type { FontAwesomeService } from "./fontawesome-service";
+export type { FontAwesomeIcon, FontAwesomeFamily, FontAwesomeStyle, FontAwesomeSelection, FontAwesomeOptions, } from "./types";

package/dist/fontawesome/index.mjs

@@ -0,0 +1,20 @@
+function createFontAwesomeService(icons) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(icons)) {
+    registry.set(key, { ...icons[key] });
+  }
+  return {
+    getFaIcon(key) {
+      const icon = registry.get(key);
+      if (!icon) {
+        throw new Error(
+          `Font Awesome icon "${key}" is not in this project's selections`
+        );
+      }
+      return { ...icon };
+    }
+  };
+}
+export {
+  createFontAwesomeService
+};

package/dist/fontawesome/normalize.d.ts

@@ -0,0 +1,3 @@
+import type { FontAwesomeIcon, FontAwesomeSelection } from "./types";
+export declare function expectedPrefix(selection: FontAwesomeSelection): string;
+export declare function normalizeIcon(selection: FontAwesomeSelection, definition: unknown): FontAwesomeIcon;

package/dist/fontawesome/normalize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fontawesome/types.d.ts

@@ -0,0 +1,21 @@
+export interface FontAwesomeIcon {
+    name: string;
+    content: string;
+    viewBox: string;
+}
+export type FontAwesomeFamily = "classic" | "sharp" | "duotone" | "sharp-duotone";
+export type FontAwesomeStyle = "solid" | "regular" | "light" | "thin" | "brands";
+export interface FontAwesomeSelection {
+    key: string;
+    name: string;
+    version: string;
+    family: FontAwesomeFamily;
+    style: FontAwesomeStyle;
+    package: string;
+    exportName?: string;
+}
+export interface FontAwesomeOptions {
+    icons: readonly FontAwesomeSelection[];
+    root?: string;
+    sourceRoot?: string;
+}

package/dist/fontawesome/vite.cjs

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const node_path = require("node:path");
+const promises = require("node:fs/promises");
+const generate = require("./chunks/generate-Bobf_ghm.cjs");
+const virtualId = "virtual:featherk/fontawesome";
+const resolvedId = `\0${virtualId}`;
+function dependencyKey(file) {
+  const path = node_path.resolve(file).replaceAll("\\", "/");
+  return process.platform === "win32" ? path.toLowerCase() : path;
+}
+function featherkFontAwesome(options) {
+  let root = node_path.resolve(options.root ?? process.cwd());
+  let generation;
+  let dependencies = /* @__PURE__ */ new Set();
+  function regenerate() {
+    generation = generate.generateFaIcons({
+      icons: options.icons,
+      root,
+      sourceRoot: options.sourceRoot,
+      virtualTypesFile: options.virtualTypesFile === false ? void 0 : options.virtualTypesFile ?? "src/featherk-fontawesome.d.ts"
+    }).then((result) => {
+      dependencies = new Set(result.dependencies.map(dependencyKey));
+      return result;
+    });
+    return generation;
+  }
+  return {
+    name: "featherk-fontawesome",
+    enforce: "pre",
+    async configResolved(config) {
+      root = node_path.resolve(config.root, options.root ?? ".");
+      await regenerate();
+    },
+    async buildStart() {
+      const result = await regenerate();
+      for (const file of result.dependencies) this.addWatchFile(file);
+    },
+    resolveId(id) {
+      return id === virtualId ? resolvedId : void 0;
+    },
+    async load(id) {
+      if (id !== resolvedId) return void 0;
+      return (await (generation ?? regenerate())).moduleCode;
+    },
+    async configureServer(server) {
+      const result = await (generation ?? regenerate());
+      server.watcher.add(result.dependencies);
+    },
+    async handleHotUpdate(context) {
+      const file = await promises.realpath(context.file).catch(() => context.file);
+      if (!dependencies.has(dependencyKey(file))) return void 0;
+      const result = await regenerate();
+      context.server.watcher.add(result.dependencies);
+      const module2 = context.server.moduleGraph.getModuleById(resolvedId);
+      if (module2) context.server.moduleGraph.invalidateModule(module2);
+      context.server.ws.send({ type: "full-reload" });
+      return [];
+    },
+    async generateBundle() {
+      const result = await (generation ?? regenerate());
+      if (result.notices) {
+        this.emitFile({
+          type: "asset",
+          fileName: "featherk-fontawesome.licenses.txt",
+          source: result.notices
+        });
+      }
+    }
+  };
+}
+exports.featherkFontAwesome = featherkFontAwesome;

package/dist/fontawesome/vite.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "vite";
+import type { FontAwesomeOptions } from "./types";
+export interface FontAwesomeViteOptions extends FontAwesomeOptions {
+    virtualTypesFile?: string | false;
+}
+export declare function featherkFontAwesome(options: FontAwesomeViteOptions): Plugin;

package/dist/fontawesome/vite.mjs

@@ -0,0 +1,72 @@
+import { resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { g as generateFaIcons } from "./chunks/generate-Bp92GTVi.mjs";
+const virtualId = "virtual:featherk/fontawesome";
+const resolvedId = `\0${virtualId}`;
+function dependencyKey(file) {
+  const path = resolve(file).replaceAll("\\", "/");
+  return process.platform === "win32" ? path.toLowerCase() : path;
+}
+function featherkFontAwesome(options) {
+  let root = resolve(options.root ?? process.cwd());
+  let generation;
+  let dependencies = /* @__PURE__ */ new Set();
+  function regenerate() {
+    generation = generateFaIcons({
+      icons: options.icons,
+      root,
+      sourceRoot: options.sourceRoot,
+      virtualTypesFile: options.virtualTypesFile === false ? void 0 : options.virtualTypesFile ?? "src/featherk-fontawesome.d.ts"
+    }).then((result) => {
+      dependencies = new Set(result.dependencies.map(dependencyKey));
+      return result;
+    });
+    return generation;
+  }
+  return {
+    name: "featherk-fontawesome",
+    enforce: "pre",
+    async configResolved(config) {
+      root = resolve(config.root, options.root ?? ".");
+      await regenerate();
+    },
+    async buildStart() {
+      const result = await regenerate();
+      for (const file of result.dependencies) this.addWatchFile(file);
+    },
+    resolveId(id) {
+      return id === virtualId ? resolvedId : void 0;
+    },
+    async load(id) {
+      if (id !== resolvedId) return void 0;
+      return (await (generation ?? regenerate())).moduleCode;
+    },
+    async configureServer(server) {
+      const result = await (generation ?? regenerate());
+      server.watcher.add(result.dependencies);
+    },
+    async handleHotUpdate(context) {
+      const file = await realpath(context.file).catch(() => context.file);
+      if (!dependencies.has(dependencyKey(file))) return void 0;
+      const result = await regenerate();
+      context.server.watcher.add(result.dependencies);
+      const module = context.server.moduleGraph.getModuleById(resolvedId);
+      if (module) context.server.moduleGraph.invalidateModule(module);
+      context.server.ws.send({ type: "full-reload" });
+      return [];
+    },
+    async generateBundle() {
+      const result = await (generation ?? regenerate());
+      if (result.notices) {
+        this.emitFile({
+          type: "asset",
+          fileName: "featherk-fontawesome.licenses.txt",
+          source: result.notices
+        });
+      }
+    }
+  };
+}
+export {
+  featherkFontAwesome
+};

package/dist/fontawesome/vite.test.d.ts

@@ -0,0 +1 @@
+export {};

package/docs/ICONS.md

@@ -211,4 +211,4 @@
 |rating_star_selected|switch_left|switch_off|switch_on|switch_right| |
 <!-- markdownlint-enable MD033-->
 
-> Generated: 2026-09-30T20:08:36.243Z
+> Generated: 2026-10-06T00:13:29.670Z

package/docs/fontawesome/CreateFontAwesomeManifest.md

@@ -0,0 +1,109 @@
+# Choose Font Awesome Icons and Create a Manifest
+
+This is the UX/Design starting point for choosing the exact Font Awesome variants an application intends to use and recording them in its selection manifest. It covers icon selection, approval, naming, and manifest fields. For integration and build setup, continue to [Font Awesome Build Integration](FontAwesome.md); CLI and non-Vite workflows are in [the CLI supplement](FontAwesomeCLI.md).
+
+## Quick Start
+
+1. Select the exact catalog icon, family, and style; note whether the variant is Free or Pro.
+2. Agree on the exact release and obtain the required UX and license approvals.
+3. Assign a unique application key and identify the package that supplies the variant and release.
+4. Add or update the selection in the application's manifest and review the full selection set.
+
+The steps below help UX/Design create a precise handoff. Do not assume every icon exists in every family, style, or release.
+
+## Where Each Field Comes From
+
+| Field     | Who supplies it                         | Meaning                                                                                                             |
+| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `key`     | UX/application convention               | Unique application lookup identifier, such as `pro-house-light`; passed to `getFaIcon()`                            |
+| `name`    | Font Awesome catalog                    | Canonical icon name, such as `house`, without the `fa-` CSS prefix                                                  |
+| `version` | Approved release policy                 | Exact source-package release, such as `7.0.0`, not `latest`, a range, or the first version that introduced the icon |
+| `family`  | Selected Font Awesome family            | Supported family identifier, such as `classic` or `sharp`                                                           |
+| `style`   | Selected Font Awesome style             | Supported style identifier, such as `solid`, `regular`, or `light`                                                  |
+| `package` | Engineering confirms the source mapping | Exact installed package name or alias that supplies the selected family, style, and version                         |
+
+The catalog identifies the canonical `name`, `family`, `style`, and Free/Pro availability. UX/Design proposes the application `key` and approved release. Engineering confirms the exact npm package or alias for `package`; Dev installs that package at the manifest's exact `version`. Do not guess package names. A catalog page alone does not establish historical release availability or license entitlement.
+
+## Step 1: Select and Approve the Catalog Variant
+
+Open the [Font Awesome catalog](https://fontawesome.com/search), select an icon, and open its details. Select the exact family/style rather than approving only the icon name. Confirm whether that variant is Free or Pro.
+
+Copied markup can help identify the selection:
+
+```html
+<!-- Step 1: This identifies Classic Regular heart, not a package version. -->
+<i class="fa-regular fa-heart"></i>
+```
+
+For this example, the canonical name is `heart`, family is `classic`, and style is `regular`. Confirm those values for the desired release; old CSS names may be compatibility aliases rather than that release's canonical name.
+
+UX should hand off the catalog link, canonical name, approved exact release, family, style, and approval record. Agree on an application key separately. Any package/download entitlement must also be confirmed for Pro.
+
+Important distinctions:
+
+- "Added in v5" describes first availability; it does not mean the installed package is version `5.0.0`.
+- Regular is not Light. Classic Light is Pro-only, and not every Solid icon has a Free Regular counterpart.
+- Outlined Regular artwork can still use filled SVG path shapes; do not replace its path fill with `none` or synthesize an outline with strokes.
+- A current catalog page may describe newer artwork than an approved historical release.
+- Exact v4 font artwork is not supported by the current installed SVG-definition generator.
+
+## Step 2: Confirm the Package Mapping
+
+Common Classic package mappings are:
+
+| Availability                 | `family`  | `style`   | Source package                        |
+| ---------------------------- | --------- | --------- | ------------------------------------- |
+| Free                         | `classic` | `solid`   | `@fortawesome/free-solid-svg-icons`   |
+| Free, where a variant exists | `classic` | `regular` | `@fortawesome/free-regular-svg-icons` |
+| Free brands                  | `classic` | `brands`  | `@fortawesome/free-brands-svg-icons`  |
+| Pro                          | `classic` | `solid`   | `@fortawesome/pro-solid-svg-icons`    |
+| Pro                          | `classic` | `regular` | `@fortawesome/pro-regular-svg-icons`  |
+| Pro                          | `classic` | `light`   | `@fortawesome/pro-light-svg-icons`    |
+| Pro                          | `classic` | `thin`    | `@fortawesome/pro-thin-svg-icons`     |
+
+The `classic`/`brands` rows show common package mappings. Other families include `sharp`, `duotone`, and `sharp-duotone`; confirm their package names and release availability in the [official package documentation](https://docs.fontawesome.com/web/setup/packages). Do not construct package names by guesswork. Pro+ collections requiring Kits are outside this integration.
+
+For Pro variants, confirm entitlement and release approval with the license owner before adding them. See [Pro licensing and setup](LICENSING.md). Engineering should confirm that the package recorded in the manifest is installed and supplies the requested variant.
+
+## Step 3: Write the Complete Manifest Entry
+
+Add the selection to an `icons` array. The filename is project-owned; this example uses a Free selection manifest:
+
+```json
+{
+  "icons": [
+    {
+      "key": "heart-outline",
+      "name": "heart",
+      "version": "7.0.0",
+      "family": "classic",
+      "style": "regular",
+      "package": "@fortawesome/free-regular-svg-icons"
+    }
+  ]
+}
+```
+
+This example records the selected Pro variant. In this repository, Free selections live in `demos/fontawesome.icons.json` and optional licensed selections in `demos/fontawesome.pro.icons.json`; other applications may choose their own manifest filenames.
+
+The `key` is the application's identifier and does not need to match the canonical `name`. Use a unique key for each distinct selection. For example, the same canonical icon can be selected with different styles or versions as long as each entry has a different key.
+
+## Naming and Uniqueness Rules
+
+The generator only requires `key` to be a nonblank string; it does not enforce a casing or punctuation style. For readability, UX/Design should use lowercase kebab-case and choose a stable, descriptive key:
+
+- Use the canonical icon name as the key when only one variant is selected, such as `rocket`.
+- Add the style when the application needs multiple variants, such as `heart-regular` or `feather-light`.
+- Add a version suffix only when multiple releases must coexist, such as `rocket-v5` and `rocket-v6`.
+- Do not reuse a key for a different icon identity. If the selected variant changes, review the key and all application references with Engineering.
+- Check keys across every manifest enabled together in a build, including combined Free and Pro selections. A key repeated in separate files is still a duplicate when those files are combined.
+
+These are UX naming conventions; only blank and duplicate keys are rejected by the generator. The application uses the key for lookup, while `name`, `family`, `style`, `version`, and `package` identify the source artwork.
+
+## UX/Design Handoff
+
+For each selection, provide the catalog link, canonical name, family, style, exact approved version, application key, Free/Pro status, and package mapping. UX/Design owns the desired variants and manifest change; Engineering confirms that the exact package and release are available and implements the build integration.
+
+Catalog approval and source availability are separate. If Engineering cannot resolve the requested package, version, or export, do not silently substitute another icon or release. Return to UX/Design and update the approval and manifest together.
+
+After the manifest is ready, continue with [Vite build integration](FontAwesome.md). For Pro selections, review [Pro licensing and setup](LICENSING.md). Non-Vite or pre-typecheck CLI workflows are documented in [the CLI supplement](FontAwesomeCLI.md).