@uxf/icons-generator 11.128.0 → 12.1.0

package/src/providers/fa-pro.d.ts

@@ -1,3 +1,14 @@
 import type { FaProIconName } from "../fa-pro-types";
 import { type IconProvider } from "../types";
+/**
+ * Download whatever the deprecated npm packages cannot answer, in a single
+ * streamed pass. Called by the CLI between loading the config and generating.
+ *
+ * A failure here is deliberately **not** fatal. Rebuilding without Font Awesome
+ * access is a supported mode — the committed `faPro.json` snapshot exists for
+ * exactly that — so an unreachable registry must not turn a project that never
+ * needed the network into a failing build. {@link getIcon} raises it only if an
+ * icon really cannot be resolved from anywhere else.
+ */
+export declare function prefetchFaProIcons(): Promise<void>;
 export declare const faPro: IconProvider<FaProIconName>;

package/src/providers/fa-pro.js

@@ -1,16 +1,32 @@
 "use strict";
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.faPro = void 0;
+exports.prefetchFaProIcons = prefetchFaProIcons;
+/* eslint-disable no-console */
 const fs_1 = require("fs");
+const path_1 = require("path");
+const _faProTarballCache_1 = require("../utils/_faProTarballCache");
 const _generateAdapterFallback_1 = require("../utils/_generateAdapterFallback");
 const _getIconNameForProvider_1 = require("../utils/_getIconNameForProvider");
+const _parseFaSvg_1 = require("../utils/_parseFaSvg");
+const _prefetchRegistry_1 = require("../utils/_prefetchRegistry");
 const KEY = "faPro";
 const LEGACY_PACKAGE = "@fortawesome/fontawesome-pro";
-// FA's npm naming is inconsistent: the legacy duotone solid keeps the `pro-`
-// prefix (`@fortawesome/pro-duotone-svg-icons`) while the v7 duotone-light /
-// duotone-regular / duotone-thin variants are published without it.
-const NAMESPACE_TO_PACKAGE = {
+/**
+ * Per-style npm packages, kept only so projects that still have them installed
+ * keep building. The styles Font Awesome 7 added on top of classic/sharp/duotone
+ * are not published this way, and installing them costs ~43 MB of `node_modules`
+ * per style.
+ *
+ * FA's npm naming is inconsistent: the legacy duotone solid keeps the `pro-`
+ * prefix (`@fortawesome/pro-duotone-svg-icons`) while the v7 duotone-light /
+ * duotone-regular / duotone-thin variants are published without it.
+ *
+ * @deprecated Icons stream from the kit package instead; uninstall the
+ * `@fortawesome/*-svg-icons` packages. Removed in the next major — see
+ * `docs/migration/fa-pro-kit-stream.md`.
+ */
+const DEPRECATED_NAMESPACE_TO_PACKAGE = {
     brands: "@fortawesome/free-brands-svg-icons",
     duotone: "@fortawesome/pro-duotone-svg-icons",
     "duotone-light": "@fortawesome/duotone-light-svg-icons",
@@ -29,18 +45,25 @@ const NAMESPACE_TO_PACKAGE = {
     solid: "@fortawesome/pro-solid-svg-icons",
     thin: "@fortawesome/pro-thin-svg-icons",
 };
-const NODE_MODULES_PATH = (_a = process.env.NODE_MODULES_PATH) !== null && _a !== void 0 ? _a : "./node_modules";
+// Where the deprecated per-style lookup resolves from. Without it a bare
+// `require` walks up from this file, which in a monorepo checkout reaches the
+// root `node_modules`; pointing it at an empty directory is how a test drives
+// the streamed path regardless of what happens to be installed.
+const NODE_MODULES_PATH_OVERRIDE = process.env.NODE_MODULES_PATH;
+const NODE_MODULES_PATH = NODE_MODULES_PATH_OVERRIDE !== null && NODE_MODULES_PATH_OVERRIDE !== void 0 ? NODE_MODULES_PATH_OVERRIDE : "./node_modules";
 if ((0, fs_1.existsSync)(`${NODE_MODULES_PATH}/${LEGACY_PACKAGE}`)) {
-    throw new Error(`Package "${LEGACY_PACKAGE}" is installed but no longer used. The faPro adapter reads from per-style packages instead. Run \`yarn remove ${LEGACY_PACKAGE}\`.`);
+    throw new Error(`Package "${LEGACY_PACKAGE}" is installed but no longer used — the faPro adapter streams icons straight from ${(0, _faProTarballCache_1._getFaProPackage)()} instead. Run \`yarn remove ${LEGACY_PACKAGE}\`.`);
 }
 const kebabToPascal = (name) => name
     .split("-")
     .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
     .join("");
 const tryRequire = (pkg) => {
+    // `resolve` already anchors a relative override on the working directory.
+    const specifier = NODE_MODULES_PATH_OVERRIDE ? (0, path_1.resolve)(NODE_MODULES_PATH_OVERRIDE, pkg) : pkg;
     try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        return require(pkg);
+        return require(specifier);
     }
     catch {
         return null;
@@ -49,31 +72,62 @@ const tryRequire = (pkg) => {
 const wrapPath = (pathData) => Array.isArray(pathData)
     ? pathData.map((d) => `<path fill="currentColor" d="${d}"/>`).join("")
     : `<path fill="currentColor" d="${pathData}"/>`;
-const resolvePackage = (namespace, iconName) => {
-    const pkg = NAMESPACE_TO_PACKAGE[namespace];
+/* ------------------------------------------------- deprecated npm packages */
+const warnedPackages = new Set();
+function warnDeprecatedPackage(pkg) {
+    if (warnedPackages.has(pkg)) {
+        return;
+    }
+    warnedPackages.add(pkg);
+    console.warn(`[@uxf/icons-generator] Reading icons from "${pkg}" in node_modules. This is deprecated and will be removed in a future major — icons now stream from the Font Awesome kit at generation time. Uninstall the "@fortawesome/*-svg-icons" packages; see docs/migration/fa-pro-kit-stream.md.`);
+}
+/**
+ * Resolve from a per-style package, if the project still has one installed.
+ *
+ * @deprecated Superseded by {@link loadIconFromTarball}. Kept so that upgrading
+ * cannot break a project that still installs the `@fortawesome/*-svg-icons`
+ * packages; delete together with {@link DEPRECATED_NAMESPACE_TO_PACKAGE}.
+ */
+function loadIconFromPackage(iconName) {
+    const [namespace, ...rest] = iconName.split(".");
+    const name = rest.join(".");
+    const pkg = DEPRECATED_NAMESPACE_TO_PACKAGE[namespace];
     if (!pkg) {
-        const supported = Object.keys(NAMESPACE_TO_PACKAGE).join(", ");
-        throw new Error(`Unsupported FA namespace "${namespace}" for icon "${iconName}". Supported namespaces: ${supported}.`);
+        return null;
     }
-    return pkg;
-};
-const loadIconFromPackage = (iconName) => {
-    const [namespace, name] = iconName.split(".");
-    const pkg = resolvePackage(namespace, iconName);
     const pkgExports = tryRequire(pkg);
     if (!pkgExports) {
         return null;
     }
-    const exportKey = `fa${kebabToPascal(name)}`;
-    const def = pkgExports[exportKey];
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const def = pkgExports[`fa${kebabToPascal(name)}`];
     if (!def || !Array.isArray(def.icon)) {
-        throw new Error(`Icon "${iconName}" not found in "${pkg}" (looked up export "${exportKey}").`);
+        // The package is installed but does not carry this icon — let the
+        // tarball answer instead of failing the whole run.
+        return null;
     }
+    warnDeprecatedPackage(pkg);
     const [width, height, , , pathData] = def.icon;
     return { width: Number(width), height: Number(height), path: wrapPath(pathData) };
-};
-const readFromFallback = (iconName, config) => {
+}
+/* --------------------------------------------------------- streamed source */
+function loadIconFromTarball(iconName) {
+    const svgContent = (0, _faProTarballCache_1._readFaProSvg)(iconName);
+    if (!svgContent) {
+        return null;
+    }
+    try {
+        const { height, pathData, width } = (0, _parseFaSvg_1._parseFaSvg)(svgContent);
+        return { width, height, path: wrapPath(pathData) };
+    }
+    catch (error) {
+        // One unreadable SVG must not take the whole run down: name it, and let
+        // the committed snapshot answer for it the way a missing icon is handled.
+        console.warn(`[@uxf/icons-generator] Could not read "${iconName}" from ${(0, _faProTarballCache_1._getFaProPackage)()}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/* --------------------------------------------------------- committed cache */
+function readFromFallback(iconName, config) {
     const fallbackPath = config.fallbackFilesDirectory + KEY + ".json";
     let fileContent;
     try {
@@ -91,27 +145,67 @@ const readFromFallback = (iconName, config) => {
         height: Number(icon.height),
         path: decodeURIComponent(icon.path),
     };
+}
+/* ------------------------------------------------------------------ prefetch */
+/**
+ * Icon names collected while `icons.config.js` is being evaluated. The provider
+ * API is synchronous, so everything the tarball has to answer is resolved up
+ * front by {@link prefetchFaProIcons} before the generator runs.
+ */
+const requestedIcons = new Set();
+/**
+ * Reason the streamed source could not be read, if it could not. Reported only
+ * once an icon turns out to need it, so it does not drown out a plain typo.
+ */
+let prefetchError = null;
+/**
+ * Download whatever the deprecated npm packages cannot answer, in a single
+ * streamed pass. Called by the CLI between loading the config and generating.
+ *
+ * A failure here is deliberately **not** fatal. Rebuilding without Font Awesome
+ * access is a supported mode — the committed `faPro.json` snapshot exists for
+ * exactly that — so an unreachable registry must not turn a project that never
+ * needed the network into a failing build. {@link getIcon} raises it only if an
+ * icon really cannot be resolved from anywhere else.
+ */
+async function prefetchFaProIcons() {
+    const needed = [...requestedIcons].filter((iconName) => loadIconFromPackage(iconName) === null);
+    if (needed.length === 0) {
+        return;
+    }
+    try {
+        await (0, _faProTarballCache_1._prefetchFaProIcons)(needed);
+    }
+    catch (error) {
+        prefetchError = error instanceof Error ? error : new Error(String(error));
+        console.warn(`[@uxf/icons-generator] Could not read ${(0, _faProTarballCache_1._getFaProPackage)()}, falling back to the committed ${KEY}.json snapshot. Icons already generated will keep working; adding a new one will not.\n${prefetchError.message}`);
+    }
+}
+/* ---------------------------------------------------------------- provider */
+function getIcon(iconName, config) {
+    var _a;
+    const resolved = (_a = loadIconFromPackage(iconName)) !== null && _a !== void 0 ? _a : loadIconFromTarball(iconName);
+    if (resolved) {
+        (0, _generateAdapterFallback_1._generateAdapterFallback)(KEY, iconName, resolved, config);
+        return resolved;
+    }
+    const fromSnapshot = readFromFallback(iconName, config);
+    if (fromSnapshot) {
+        return fromSnapshot;
+    }
+    throw new Error(`Can't resolve icon "${iconName}". It was not found in ${(0, _faProTarballCache_1._getFaProPackage)()}, in any installed "@fortawesome/*-svg-icons" package, or in the committed ${KEY}.json fallback. Check the namespace and the icon name.` +
+        (prefetchError ? `\n\nThe package could not be read:\n${prefetchError.message}` : ""));
+}
+const icon = (iconName) => {
+    requestedIcons.add(iconName);
+    return (config) => getIcon(iconName, config);
 };
-const getIcon = (iconName, config) => {
-    const iconDefinition = loadIconFromPackage(iconName);
-    if (iconDefinition) {
-        (0, _generateAdapterFallback_1._generateAdapterFallback)(KEY, iconName, iconDefinition, config);
-        return iconDefinition;
-    }
-    const fallbackIcon = readFromFallback(iconName, config);
-    if (fallbackIcon) {
-        return fallbackIcon;
-    }
-    const [namespace] = iconName.split(".");
-    const pkg = resolvePackage(namespace, iconName);
-    throw new Error(`Can't resolve icon "${iconName}": package "${pkg}" is not installed. Run \`yarn add -D ${pkg}\` to enable "${namespace}" icons.`);
-};
-const icon = (iconName) => (config) => getIcon(iconName, config);
 exports.faPro = {
-    icon(iconName) {
-        return (config) => getIcon(iconName, config);
-    },
     adapter(icons) {
         return Object.fromEntries(icons.map((iconName) => [(0, _getIconNameForProvider_1._getIconNameForProvider)(KEY, iconName), icon(iconName)]));
     },
+    icon,
 };
+// Loading this module is itself the signal that the project uses the adapter,
+// so the CLI never has to know which providers exist.
+(0, _prefetchRegistry_1._registerPrefetch)(prefetchFaProIcons);

package/src/scripts/cli.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const process_1 = require("process");
 const yargs_1 = __importDefault(require("yargs"));
 const _getConfig_1 = require("../utils/_getConfig");
+const _prefetchRegistry_1 = require("../utils/_prefetchRegistry");
 const index_1 = __importDefault(require("./index"));
 exports.default = async () => {
     const cli = (0, yargs_1.default)()
@@ -18,5 +19,10 @@ exports.default = async () => {
     if (help) {
         return 0;
     }
-    (0, index_1.default)((0, _getConfig_1._getConfig)(configFile));
+    // Loading the config is what pulls in the providers it uses and registers
+    // every icon they are asked for; the prefetch then resolves them all in one
+    // pass, because the provider API itself is synchronous.
+    const config = (0, _getConfig_1._getConfig)(configFile);
+    await (0, _prefetchRegistry_1._runPrefetch)();
+    (0, index_1.default)(config);
 };

package/src/utils/_faProTarballCache.d.ts

@@ -0,0 +1,48 @@
+export interface FaProSource {
+    package: string;
+    version: string;
+}
+export interface FaProIndex extends FaProSource {
+    /** namespace → sorted icon names. */
+    icons: Partial<Record<string, string[]>>;
+    schema: number;
+}
+export declare function _getFaProPackage(): string;
+/** The version `src/fa-pro-types.ts` is expected to have been generated from. */
+export declare function _getFaProDefaultVersion(): string;
+/**
+ * Resolve the package version to read icons from: {@link DEFAULT_VERSION}
+ * unless `UXF_FA_PRO_VERSION` overrides it, and only the literal `latest`
+ * consults the registry's mutable dist-tag.
+ *
+ * The promise is memoised so concurrent callers share one round trip, but a
+ * rejection is not: a transient network failure must not be sticky for the rest
+ * of the process, because the prefetch swallows it and later callers retry.
+ */
+export declare function _resolveFaProSource(): Promise<FaProSource>;
+interface EntryLocation {
+    iconName: string;
+    namespace: string;
+}
+/**
+ * Derive the namespace an archive entry belongs to, or `null` for entries that
+ * are not per-icon SVGs (webfonts, sprites, the `svgs-full` duplicates, …).
+ *
+ * The namespace is the style directory verbatim, so `svgs/sharp-regular/x.svg`
+ * is `sharp-regular.x` — the same string the per-style npm packages produced.
+ */
+export declare function _locateEntry(name: string): EntryLocation | null;
+/**
+ * Make sure every requested `"<namespace>.<icon-name>"` is available to
+ * {@link _readFaProSvg}, downloading the package tarball at most once.
+ *
+ * Icons already in the on-disk cache cost nothing but a file read, and since
+ * the version is pinned rather than resolved from a dist-tag, such a run makes
+ * no request at all.
+ */
+export declare function _prefetchFaProIcons(names: Iterable<string>): Promise<void>;
+/** Read a prefetched icon. Returns `null` when the icon is not in the package. */
+export declare function _readFaProSvg(qualifiedName: string): string | null;
+/** Namespaces the resolved package provides, with their icon names. */
+export declare function _getFaProIndex(): Promise<FaProIndex>;
+export {};