@fluentui/react-icons-atomic-webpack-loader 0.0.2 → 0.0.4

package/README.md

@@ -3,19 +3,21 @@
 > **⚠️ 0.x** — this package is in early development and follows [zero-based major semver](https://0ver.org/).
 > Breaking changes may occur in minor releases until 1.0.
 
-Webpack loader that transforms barrel imports and re-exports from `@fluentui/react-icons` into atomic deep paths for better tree-shaking and smaller bundles.
+Webpack loader that transforms barrel imports and re-exports from `@fluentui/react-icons` and `@fluentui/react-brand-icons` into atomic deep paths for better tree-shaking and smaller bundles.
 
 ## Before / After
 
 ```js
 // Before — barrel import pulls in the entire icon set
 import { AddFilled, bundleIcon, useIconContext } from '@fluentui/react-icons';
+import { ProjectColor } from '@fluentui/react-brand-icons';
 export { ArrowLeftRegular } from '@fluentui/react-icons';
 
 // After — each reference resolves to a small, isolated module
 import { AddFilled } from '@fluentui/react-icons/svg/add';
 import { bundleIcon } from '@fluentui/react-icons/utils';
 import { useIconContext } from '@fluentui/react-icons/providers';
+import { ProjectColor } from '@fluentui/react-brand-icons/svg/project';
 export { ArrowLeftRegular } from '@fluentui/react-icons/svg/arrow-left';
 ```
 
@@ -23,7 +25,7 @@ export { ArrowLeftRegular } from '@fluentui/react-icons/svg/arrow-left';
 
 Add the loader to your webpack config as an [`enforce: 'pre'`](https://webpack.js.org/configuration/module/#ruleenforce) rule so it runs on the original source before any other loaders:
 
-NOTE: Unlike most loaders, this one should NOT exclude `node_modules`. It needs to process files inside `node_modules` as well to transform barrel imports from `@fluentui/react-icons` in your third-party dependencies. Files that don't reference `@fluentui/react-icons` are skipped via a fast regex pre-check, so there is no meaningful overhead.
+NOTE: Unlike most loaders, this one should NOT exclude `node_modules`. It needs to process files inside `node_modules` as well to transform barrel imports from `@fluentui/react-icons` and `@fluentui/react-brand-icons` in your third-party dependencies. Files that don't reference a supported module are skipped via a fast pre-check, so there is no meaningful overhead.
 
 ```js
 // webpack.config.js
@@ -59,11 +61,41 @@ module.exports = {
 };
 ```
 
+## Supported modules
+
+| Module                        | Variants                     | Notes                         |
+| ----------------------------- | ---------------------------- | ----------------------------- |
+| `@fluentui/react-icons`       | `svg`, `fonts`, `svg-sprite` | Has `/providers` and `/utils` |
+| `@fluentui/react-brand-icons` | `svg`                        | Has `/utils`; no `/providers` |
+
 ## Options
 
-| Option        | Type                                   | Default | Description                                                        |
-| ------------- | -------------------------------------- | ------- | ------------------------------------------------------------------ |
-| `iconVariant` | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `'svg'` | Whether icons resolve to SVG, font-based, or SVG sprite components |
+| Option            | Type                                   | Default     | Description                                                                |
+| ----------------- | -------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `iconVariant`     | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `'svg'`     | Variant icons resolve to. Applied to every supported module.               |
+| `fallbackVariant` | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `undefined` | Variant used for a module that does not support `iconVariant` (see below). |
+
+### Variant resolution & `fallbackVariant`
+
+`iconVariant` is applied to every supported module referenced in a file. Because not every module ships every variant (for example `@fluentui/react-brand-icons` only ships `svg`), the loader resolves the variant per module:
+
+1. If the module supports `iconVariant`, it is used.
+2. Otherwise, if `fallbackVariant` is set and supported by the module, it is used.
+3. Otherwise, if `fallbackVariant` is set but also unsupported, the loader emits a warning and falls back to `svg`.
+4. Otherwise (no `fallbackVariant`), the loader fails with a descriptive error.
+
+Resolution is lazy and per file: only modules actually imported in a given file are checked, so a file that imports only `@fluentui/react-icons` never errors about brand icons.
+
+```js
+// Resolve system icons to fonts, but keep brand icons on svg (their only variant).
+{
+  loader: '@fluentui/react-icons-atomic-webpack-loader',
+  options: {
+    iconVariant: 'fonts',
+    fallbackVariant: 'svg',
+  },
+}
+```
 
 ### Using font icons
 
@@ -105,7 +137,9 @@ This changes icon resolution from `@fluentui/react-icons/svg/*` to `@fluentui/re
 
 ## How it works
 
-The loader uses a Babel transform to rewrite import and re-export declarations that reference `@fluentui/react-icons`. Each named specifier is routed to an atomic subpath based on its name:
+The loader parses each module and rewrites import and re-export declarations that reference a supported module. Each named specifier is routed to an atomic subpath based on its name:
+
+### `@fluentui/react-icons`
 
 | Export type    | Example                                          | Resolved path                                                        |
 | -------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
@@ -113,9 +147,17 @@ The loader uses a Babel transform to rewrite import and re-export declarations t
 | Context / hook | `useIconContext`, `IconDirectionContextProvider` | `@fluentui/react-icons/providers`                                    |
 | Utility        | `bundleIcon`, `createFluentIcon`                 | `@fluentui/react-icons/utils`                                        |
 
-Files that don't reference `@fluentui/react-icons` are passed through untouched (fast regex pre-check).
+### `@fluentui/react-brand-icons`
+
+| Export type    | Example                                   | Resolved path                             |
+| -------------- | ----------------------------------------- | ----------------------------------------- |
+| Icon component | `ProjectColor`, `CalendarTaskbar20Filled` | `@fluentui/react-brand-icons/svg/project` |
+| Utility        | `bundleIcon`, `createFluentIcon`          | `@fluentui/react-brand-icons/utils`       |
+
+Files that don't reference a supported module are passed through untouched (fast pre-check).
 
 ## Requirements
 
 - `webpack` >= 5
 - `@fluentui/react-icons` >= 2 (with atomic subpath exports)
+- `@fluentui/react-brand-icons` (with atomic subpath exports), if used

package/lib/index.d.ts

@@ -1,5 +1,20 @@
+import type { IconVariant } from './modules';
 import type { LoaderContext } from 'webpack';
+export type { IconVariant };
 export interface FluentIconsAtomicImportLoaderOptions {
-    iconVariant?: 'svg' | 'fonts' | 'svg-sprite';
+    /**
+     * The icon variant to resolve atomic imports to. Defaults to `'svg'`.
+     *
+     * Not every module supports every variant (e.g. `@fluentui/react-brand-icons`
+     * only ships `svg`). When a referenced module does not support this variant,
+     * `fallbackVariant` is used instead.
+     */
+    iconVariant?: IconVariant;
+    /**
+     * The variant to use for a referenced module that does not support
+     * `iconVariant`. When omitted and a module cannot honor `iconVariant`, the
+     * loader fails with a descriptive error.
+     */
+    fallbackVariant?: IconVariant;
 }
 export default function fluentIconsAtomicImportLoader(this: LoaderContext<FluentIconsAtomicImportLoaderOptions>, sourceCode: string): void;

package/lib/index.js

@@ -1,18 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const transform_1 = require("./transform");
+const modules_1 = require("./modules");
 function fluentIconsAtomicImportLoader(sourceCode) {
     const { resourcePath } = this;
-    if (!sourceCode.includes('@fluentui/react-icons')) {
+    // Cheap pre-skip only: a false positive here just means we parse the file and
+    // let the module record decide. Diagnostics are driven by actual imports.
+    if (!modules_1.SUPPORTED_MODULE_NAMES.some((name) => sourceCode.includes(name))) {
         return this.callback(null, sourceCode);
     }
-    const { iconVariant = 'svg' } = this.getOptions();
+    const { iconVariant = 'svg', fallbackVariant } = this.getOptions();
+    let code;
+    let map;
+    let diagnostics;
     try {
-        const { code, map } = (0, transform_1.transformSource)(sourceCode, { iconVariant, path: resourcePath });
-        return this.callback(null, code, map);
+        ({ code, map, diagnostics } = (0, transform_1.transformSource)(sourceCode, { iconVariant, fallbackVariant, path: resourcePath }));
     }
-    catch {
-        return this.callback(new Error(`FluentIconsAtomicImportLoader: Failed to transform "${resourcePath}"`));
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return this.callback(new Error(`FluentIconsAtomicImportLoader: Failed to transform "${resourcePath}": ${reason}`));
     }
+    for (const diagnostic of diagnostics) {
+        if (diagnostic.level === 'warning') {
+            this.emitWarning(new Error(`FluentIconsAtomicImportLoader: ${diagnostic.message}`));
+        }
+    }
+    const firstError = diagnostics.find((d) => d.level === 'error');
+    if (firstError) {
+        return this.callback(new Error(`FluentIconsAtomicImportLoader: ${firstError.message}`));
+    }
+    return this.callback(null, code, map);
 }
 exports.default = fluentIconsAtomicImportLoader;

package/lib/modules.d.ts

@@ -0,0 +1,47 @@
+export type IconVariant = 'svg' | 'fonts' | 'svg-sprite';
+/**
+ * The variant used as the ultimate safety net when neither the requested
+ * `iconVariant` nor the configured `fallbackVariant` is supported by a module.
+ * Every module supports `svg`, so it is always a valid resolution target.
+ */
+export declare const DEFAULT_SAFETY_VARIANT: IconVariant;
+/**
+ * Describes how a single supported module's barrel imports are rewritten into
+ * atomic deep paths.
+ */
+export interface ModuleDescriptor {
+    /** The bare module specifier this descriptor applies to. */
+    name: string;
+    /** Icon variants this module ships atomic entry points for. */
+    supportedVariants: IconVariant[];
+    /**
+     * Resolves the atomic subpath for a single named import.
+     *
+     * @param importName - The imported binding name (e.g. `AddFilled`, `bundleIcon`).
+     * @param variant - The already-resolved, supported icon variant for this module.
+     */
+    resolve(importName: string, variant: IconVariant): string;
+}
+export declare const MODULES: ModuleDescriptor[];
+export declare const SUPPORTED_MODULE_NAMES: string[];
+export declare function getModuleDescriptor(moduleName: string): ModuleDescriptor | undefined;
+/**
+ * Outcome of resolving the effective variant for a single module given the
+ * requested `iconVariant` and optional `fallbackVariant`.
+ *
+ * - `variant` is the variant to rewrite with, when resolution succeeds.
+ * - `error` is set when the module cannot be satisfied and no fallback exists.
+ * - `warning` is set when the resolution succeeded only by degrading to the
+ *   safety variant.
+ */
+export interface VariantResolution {
+    variant?: IconVariant;
+    error?: string;
+    warning?: string;
+}
+/**
+ * Resolves the effective icon variant for a module, applying the
+ * `iconVariant` → `fallbackVariant` → safety-variant precedence. This is pure
+ * policy logic; callers decide how to surface `error`/`warning`.
+ */
+export declare function resolveModuleVariant(descriptor: ModuleDescriptor, iconVariant: IconVariant, fallbackVariant: IconVariant | undefined): VariantResolution;

package/lib/modules.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveModuleVariant = exports.getModuleDescriptor = exports.SUPPORTED_MODULE_NAMES = exports.MODULES = exports.DEFAULT_SAFETY_VARIANT = void 0;
+/**
+ * The variant used as the ultimate safety net when neither the requested
+ * `iconVariant` nor the configured `fallbackVariant` is supported by a module.
+ * Every module supports `svg`, so it is always a valid resolution target.
+ */
+exports.DEFAULT_SAFETY_VARIANT = 'svg';
+const ICON_SUFFIX_REGEX = /(\d*)?(Regular|Filled|Light|Color)$/;
+function isIconName(importName) {
+    return ICON_SUFFIX_REGEX.test(importName);
+}
+function toKebabCase(value) {
+    return value.replace(/[a-z\d](?=[A-Z])|[a-zA-Z](?=\d)|[A-Z](?=[A-Z][a-z])/g, '$&-').toLowerCase();
+}
+function iconBaseName(importName) {
+    return toKebabCase(importName.replace(ICON_SUFFIX_REGEX, ''));
+}
+const reactIcons = {
+    name: '@fluentui/react-icons',
+    supportedVariants: ['svg', 'fonts', 'svg-sprite'],
+    resolve(importName, variant) {
+        if (importName === 'useIconContext' || importName === 'IconDirectionContextProvider') {
+            return '@fluentui/react-icons/providers';
+        }
+        if (!isIconName(importName)) {
+            return '@fluentui/react-icons/utils';
+        }
+        return `@fluentui/react-icons/${variant}/${iconBaseName(importName)}`;
+    },
+};
+const reactBrandIcons = {
+    name: '@fluentui/react-brand-icons',
+    supportedVariants: ['svg'],
+    resolve(importName) {
+        if (!isIconName(importName)) {
+            return '@fluentui/react-brand-icons/utils';
+        }
+        return `@fluentui/react-brand-icons/svg/${iconBaseName(importName)}`;
+    },
+};
+exports.MODULES = [reactIcons, reactBrandIcons];
+exports.SUPPORTED_MODULE_NAMES = exports.MODULES.map((m) => m.name);
+function getModuleDescriptor(moduleName) {
+    return exports.MODULES.find((m) => m.name === moduleName);
+}
+exports.getModuleDescriptor = getModuleDescriptor;
+/**
+ * Resolves the effective icon variant for a module, applying the
+ * `iconVariant` → `fallbackVariant` → safety-variant precedence. This is pure
+ * policy logic; callers decide how to surface `error`/`warning`.
+ */
+function resolveModuleVariant(descriptor, iconVariant, fallbackVariant) {
+    if (descriptor.supportedVariants.includes(iconVariant)) {
+        return { variant: iconVariant };
+    }
+    const supported = descriptor.supportedVariants.join(', ');
+    if (fallbackVariant === undefined) {
+        return {
+            error: `"${descriptor.name}" does not support iconVariant "${iconVariant}" ` +
+                `(supported: ${supported}). Provide a "fallbackVariant" option to resolve this.`,
+        };
+    }
+    if (descriptor.supportedVariants.includes(fallbackVariant)) {
+        return { variant: fallbackVariant };
+    }
+    return {
+        variant: exports.DEFAULT_SAFETY_VARIANT,
+        warning: `"${descriptor.name}" supports neither iconVariant "${iconVariant}" nor ` +
+            `fallbackVariant "${fallbackVariant}" (supported: ${supported}). ` +
+            `Falling back to "${exports.DEFAULT_SAFETY_VARIANT}".`,
+    };
+}
+exports.resolveModuleVariant = resolveModuleVariant;

package/lib/transform.d.ts

@@ -1,11 +1,25 @@
 import MagicString from 'magic-string';
+import type { IconVariant } from './modules';
 interface TransformOptions {
-    iconVariant: 'svg' | 'fonts' | 'svg-sprite';
+    /** The requested icon variant. Applied to every supported module. */
+    iconVariant: IconVariant;
+    /** The variant to fall back to when a module does not support `iconVariant`. */
+    fallbackVariant?: IconVariant;
     path: string;
 }
+export interface Diagnostic {
+    level: 'error' | 'warning';
+    message: string;
+}
 export interface TransformResult {
     code: string;
     map: ReturnType<MagicString['generateMap']>;
+    /**
+     * Diagnostics gathered while rewriting. Only modules that are actually
+     * imported/re-exported (as reported by the parsed module record) contribute
+     * diagnostics, so mentions in comments or string literals never trigger one.
+     */
+    diagnostics: Diagnostic[];
 }
 export declare function transformSource(source: string, options: TransformOptions): TransformResult;
 export {};

package/lib/transform.js

@@ -6,22 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformSource = void 0;
 const oxc_parser_1 = require("oxc-parser");
 const magic_string_1 = __importDefault(require("magic-string"));
-const MODULE_NAME = '@fluentui/react-icons';
-const ICON_SUFFIX_REGEX = /(\d*)?(Regular|Filled|Light|Color)$/;
-function getAtomicImportPath(importName, iconVariant) {
-    if (importName === 'useIconContext' || importName === 'IconDirectionContextProvider') {
-        return '@fluentui/react-icons/providers';
-    }
-    const isIcon = importName.match(ICON_SUFFIX_REGEX);
-    if (!isIcon) {
-        return '@fluentui/react-icons/utils';
-    }
-    const withoutSuffix = importName.replace(ICON_SUFFIX_REGEX, '');
-    const kebabCase = withoutSuffix.replace(/[a-z\d](?=[A-Z])|[a-zA-Z](?=\d)|[A-Z](?=[A-Z][a-z])/g, '$&-').toLowerCase();
-    return `@fluentui/react-icons/${iconVariant}/${kebabCase}`;
-}
+const modules_1 = require("./modules");
 function transformSource(source, options) {
-    const { iconVariant, path } = options;
+    const { iconVariant, fallbackVariant, path } = options;
     const result = (0, oxc_parser_1.parseSync)(path, source, {
         sourceType: 'module',
     });
@@ -30,8 +17,36 @@ function transformSource(source, options) {
     }
     const { staticImports, staticExports } = result.module;
     const src = new magic_string_1.default(source);
+    const diagnostics = [];
+    // Resolve (and diagnose) each referenced module at most once.
+    const resolvedVariants = new Map();
+    /**
+     * Returns the variant to rewrite a referenced module with, or `null` when it
+     * could not be resolved (an error diagnostic has been recorded and the module
+     * should be left untouched).
+     */
+    const variantFor = (descriptor) => {
+        if (resolvedVariants.has(descriptor.name)) {
+            return resolvedVariants.get(descriptor.name);
+        }
+        const resolution = (0, modules_1.resolveModuleVariant)(descriptor, iconVariant, fallbackVariant);
+        if (resolution.warning) {
+            diagnostics.push({ level: 'warning', message: resolution.warning });
+        }
+        if (resolution.error) {
+            diagnostics.push({ level: 'error', message: resolution.error });
+        }
+        const variant = resolution.variant ?? null;
+        resolvedVariants.set(descriptor.name, variant);
+        return variant;
+    };
     for (const imp of staticImports) {
-        if (imp.moduleRequest.value !== MODULE_NAME)
+        const moduleName = imp.moduleRequest.value;
+        const descriptor = (0, modules_1.getModuleDescriptor)(moduleName);
+        if (!descriptor)
+            continue;
+        const variant = variantFor(descriptor);
+        if (!variant)
             continue;
         const namedEntries = imp.entries.filter((e) => e.importName.kind === 'Name');
         if (namedEntries.length === 0)
@@ -42,19 +57,19 @@ function transformSource(source, options) {
             const names = otherEntries
                 .map((e) => (e.importName.kind === 'Default' ? e.localName.value : `* as ${e.localName.value}`))
                 .join(', ');
-            lines.push(`import ${names} from '${MODULE_NAME}';`);
+            lines.push(`import ${names} from '${moduleName}';`);
         }
         for (const entry of namedEntries) {
             const importedName = entry.importName.name;
             const localName = entry.localName.value;
-            const newSource = getAtomicImportPath(importedName, iconVariant);
+            const newSource = descriptor.resolve(importedName, variant);
             const spec = importedName === localName ? importedName : `${importedName} as ${localName}`;
             lines.push(`import { ${spec} } from '${newSource}';`);
         }
         src.overwrite(imp.start, imp.end, lines.join('\n'));
     }
     for (const exp of staticExports) {
-        const relevantEntries = exp.entries.filter((e) => e.moduleRequest?.value === MODULE_NAME && e.exportName.kind === 'Name');
+        const relevantEntries = exp.entries.filter((e) => e.moduleRequest && (0, modules_1.getModuleDescriptor)(e.moduleRequest.value) && e.exportName.kind === 'Name');
         if (relevantEntries.length === 0)
             continue;
         // Skip indirect re-exports (`import { X } from '...'; export { X };`): oxc reports these as static
@@ -64,17 +79,25 @@ function transformSource(source, options) {
             continue;
         const lines = [];
         for (const entry of relevantEntries) {
+            const moduleName = entry.moduleRequest.value;
+            const descriptor = (0, modules_1.getModuleDescriptor)(moduleName);
+            const variant = variantFor(descriptor);
+            if (!variant)
+                continue;
             const importedName = entry.importName.name;
             const exportedName = entry.exportName.name;
-            const newSource = getAtomicImportPath(importedName, iconVariant);
+            const newSource = descriptor.resolve(importedName, variant);
             const spec = importedName === exportedName ? importedName : `${importedName} as ${exportedName}`;
             lines.push(`export { ${spec} } from '${newSource}';`);
         }
+        if (lines.length === 0)
+            continue;
         src.overwrite(exp.start, exp.end, lines.join('\n'));
     }
     return {
         code: src.toString(),
         map: src.generateMap({ hires: true }),
+        diagnostics,
     };
 }
 exports.transformSource = transformSource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentui/react-icons-atomic-webpack-loader",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Webpack loader that transforms barrel imports and re-exports from @fluentui/react-icons into atomic deep paths",
   "main": "lib/index.js",
   "scripts": {