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

package/README.md

@@ -63,17 +63,21 @@ 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` |
+| Module                        | Variants                     | Headless       | Notes                         |
+| ----------------------------- | ---------------------------- | -------------- | ----------------------------- |
+| `@fluentui/react-icons`       | `svg`, `fonts`, `svg-sprite` | `svg`, `fonts` | Has `/providers` and `/utils` |
+| `@fluentui/react-brand-icons` | `svg`                        | `svg`          | Has `/utils`; no `/providers` |
+
+> **Color icons are SVG-only.** Color variants (`*Color`) rely on gradients that cannot be represented in an icon font, so they ship only in the `svg` and `svg-sprite` builds — never `fonts`. The loader reroutes color imports off font variants automatically (see [Color icons](#color-icons) below).
 
 ## Options
 
-| 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). |
+| 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).              |
+| `headless`            | `boolean`                              | `false`     | Resolve to the headless (Griffel-free) build where the module ships one.                |
+| `allowDynamicImports` | `boolean`                              | `false`     | Atomize a narrow, statically-provable subset of dynamic `import()` barrels (see below). |
 
 ### Variant resolution & `fallbackVariant`
 
@@ -97,6 +101,26 @@ Resolution is lazy and per file: only modules actually imported in a given file
 }
 ```
 
+### Color icons
+
+Color variants (`*Color`, e.g. `AddCircleColor`) are **SVG-only** — their gradients cannot be represented in an icon font, so the `fonts` build ships no color glyphs. When a color icon is imported under a color-less variant (`iconVariant: 'fonts'`), the loader reroutes just that import to a color-capable variant, following the same precedence as above (constrained to `svg` / `svg-sprite`), and emits a warning:
+
+1. If `iconVariant` is already color-capable (`svg` / `svg-sprite`), the color import is left on it — no reroute, no warning.
+2. Otherwise, if `fallbackVariant` is set and color-capable, it is used (e.g. `svg-sprite`).
+3. Otherwise the loader falls back to `svg`.
+
+Rerouting is per specifier, so color and non-color icons in the same statement resolve independently:
+
+```js
+// iconVariant: 'fonts'
+import { AddFilled, AddCircleColor } from '@fluentui/react-icons';
+// →
+import { AddFilled } from '@fluentui/react-icons/fonts/add';
+import { AddCircleColor } from '@fluentui/react-icons/svg/add-circle';
+```
+
+> Color icons are deprecated. See the [user guidance](https://microsoft.github.io/fluentui-system-icons/?path=/docs/icons-user-guidance--docs#color-variants-deprecated).
+
 ### Using font icons
 
 ```js
@@ -116,6 +140,40 @@ Resolution is lazy and per file: only modules actually imported in a given file
 
 This changes icon resolution from `@fluentui/react-icons/svg/*` to `@fluentui/react-icons/fonts/*`. Non-icon exports (`utils`, `providers`) are unaffected.
 
+> Color icons have no font build and are rerouted to `svg` (or `svg-sprite`) automatically — see [Color icons](#color-icons).
+
+### Using the headless API
+
+```js
+{
+  loader: '@fluentui/react-icons-atomic-webpack-loader',
+  options: {
+    iconVariant: 'fonts',
+    headless: true,
+  },
+}
+```
+
+With the example above:
+
+| Import              | Resolves to                                |
+| ------------------- | ------------------------------------------ |
+| `AddFilled`         | `@fluentui/react-icons/headless/fonts/add` |
+| `bundleIcon` (util) | `@fluentui/react-icons/headless/utils`     |
+| `useIconContext`    | `@fluentui/react-icons/providers` (shared) |
+
+Notes:
+
+- **Best-effort per module:** a module without a headless build for the resolved variant degrades to its standard (Griffel) implementation with a warning rather than failing the build. This applies to headless `svg-sprite` (not generated yet).
+- **Version requirement:** headless `@fluentui/react-brand-icons` requires `>= 2.0.206`. The loader rewrites imports statically and does not check the installed version, so an older brand-icons will fail to resolve the `/headless/*` entries at build time.
+- **Context is shared:** `useIconContext` / `IconDirectionContextProvider` always resolve to `@fluentui/react-icons/providers` — it is framework-agnostic and reused by both APIs.
+- **CSS is your responsibility:** the loader only rewrites component/utility imports. You must still import the headless CSS in your app entry point:
+  ```js
+  import '@fluentui/react-icons/headless/styles.css';
+  // and, for font icons:
+  import '@fluentui/react-icons/headless/fonts/styles.css';
+  ```
+
 ### Using SVG sprite icons
 
 ```js
@@ -139,6 +197,40 @@ This changes icon resolution from `@fluentui/react-icons/svg/*` to `@fluentui/re
 
 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:
 
+### Resolution flow
+
+Each named specifier is resolved independently, so color and non-color icons — even within the same statement — can land on different variants.
+
+```mermaid
+flowchart TD
+    A["Named specifier from a supported module"] --> B{"Icon name? ends in Regular / Filled / Light / Color"}
+    B -->|"context / hook"| P["/providers"]
+    B -->|"utility"| U["/utils"]
+    B -->|"yes"| V{"Module supports iconVariant?"}
+
+    V -->|"yes"| R["variant = iconVariant"]
+    V -->|"no"| F{"fallbackVariant set?"}
+    F -->|"no"| ERR["Error: import left untouched, set fallbackVariant"]
+    F -->|"yes, supported"| R2["variant = fallbackVariant"]
+    F -->|"yes, unsupported"| RS["variant = svg (warning)"]
+
+    R --> C{"Color icon?"}
+    R2 --> C
+    RS --> C
+
+    C -->|"no"| H{"headless requested and available for variant?"}
+    C -->|"yes, already color-capable: svg / svg-sprite"| H
+    C -->|"yes, color-less variant: fonts"| CC["reroute to first color-capable of iconVariant, fallbackVariant, svg (warning)"]
+    CC --> H
+
+    H -->|"yes"| HP["prefix with /headless"]
+    H -->|"no / not available (warning)"| STD["standard build"]
+    HP --> OUT["resolved atomic path"]
+    STD --> OUT
+```
+
+> Steps marked "(warning)" emit a build warning — a best-effort degrade rather than a hard failure.
+
 ### `@fluentui/react-icons`
 
 | Export type    | Example                                          | Resolved path                                                        |
@@ -156,8 +248,89 @@ The loader parses each module and rewrites import and re-export declarations tha
 
 Files that don't reference a supported module are passed through untouched (fast pre-check).
 
+## Limitations
+
+### Dynamic imports are not atomized
+
+The loader only rewrites **static** `import` / `export … from` declarations. A dynamic `import()` of a barrel cannot be atomized, because the returned module-namespace object is a runtime value whose usage the loader cannot statically prove:
+
+```js
+// ⚠️ Not rewritten — the ENTIRE icon set is pulled into the async chunk.
+const { AddFilled } = await import('@fluentui/react-icons');
+React.lazy(() => import('@fluentui/react-icons'));
+```
+
+When it detects a dynamic import of a supported barrel, the loader emits a warning. Import the atomic path directly instead — then you lazy-load only the icons you use:
+
+```js
+// ✅ Only this icon lands in the async chunk.
+const { AddFilled } = await import('@fluentui/react-icons/svg/add');
+```
+
+Alternatively, move the icons behind a local module that statically imports them; the loader atomizes that module, and only your lazy chunk pays for what it uses.
+
+> The same applies to full-barrel subpaths (`@fluentui/react-icons/svg`, `@fluentui/react-icons/fonts`) — dynamically importing those also bundles the whole set. Always target a per-icon atomic path.
+
+### Opt-in: `allowDynamicImports`
+
+> **Prefer a dedicated module of static imports.** The most robust pattern is a
+> small module that statically imports the icons you need and is itself lazy-loaded
+> (`const { AddFilled } = await import('./lazy-icons')`). Static imports are
+> atomized unconditionally, tree-shake predictably, and avoid every gotcha below.
+> Reach for `allowDynamicImports` only when refactoring to that pattern isn't
+> practical.
+
+With `allowDynamicImports: true`, the loader additionally rewrites a **narrow,
+statically-provable** subset of dynamic barrel imports into atomic ones. Only two
+call-site shapes qualify — where the imported names are literals at the `import()`:
+
+```js
+// await + object destructure
+const { AddFilled } = await import('@fluentui/react-icons');
+// → const { AddFilled } = await import('@fluentui/react-icons/svg/add');
+
+// .then + object-pattern callback param
+import('@fluentui/react-icons').then(({ AddFilled }) => …);
+// → import('@fluentui/react-icons/svg/add').then(({ AddFilled }) => …);
+```
+
+Names from the **same** atom are grouped into one import; names from **different**
+atoms become a positional `Promise.all([...])`:
+
+```js
+const { AddFilled, ArrowLeftRegular } = await import('@fluentui/react-icons');
+// →
+const [{ AddFilled }, { ArrowLeftRegular }] = await Promise.all([
+  import('@fluentui/react-icons/svg/add'),
+  import('@fluentui/react-icons/svg/arrow-left'),
+]);
+```
+
+It honors `iconVariant` / `fallbackVariant` / `headless` and per-name color
+rerouting exactly like static imports.
+
+#### Gotchas — what is **not** rewritten (left untouched, still warns)
+
+- **Namespace binding**: `const ns = await import('@fluentui/react-icons')` — `ns`
+  is a runtime object; usage isn't statically known, so the whole set ships.
+- **`.then(m => m.AddFilled)`**: namespace parameter + member access — not a
+  destructure, so the names aren't visible at the call site.
+- **Rest / computed / default / nested patterns**: `{ AddFilled, ...rest }`,
+  `{ [name]: icon }`, `{ AddFilled = fallback }`, `{ Add: { … } }`.
+- **Non-literal specifiers**: `import(pkg)`, template interpolation, or a promise
+  stored in a variable and `.then`-ed elsewhere.
+
+For any of these the loader leaves your code as-is and emits the standard
+"cannot be atomized" warning — the safe default.
+
+> ⚠️ The `Promise.all` rewrite changes the emitted runtime structure (parallel
+> chunk loading, positional destructuring). It's semantically equivalent for the
+> supported shapes, but if you depend on the exact expression shape, prefer the
+> dedicated-module pattern above.
+
 ## Requirements
 
 - `webpack` >= 5
 - `@fluentui/react-icons` >= 2 (with atomic subpath exports)
 - `@fluentui/react-brand-icons` (with atomic subpath exports), if used
+  - `>= 2.0.206` when using `headless: true` — earlier versions do not ship the `/headless/svg/*` and `/headless/utils` entries, so the loader's rewritten imports will fail to resolve.

package/lib/index.d.ts

@@ -8,13 +8,54 @@ export interface FluentIconsAtomicImportLoaderOptions {
      * 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.
+     *
+     * Color icons are an exception: they are SVG-only (gradients cannot live in an
+     * icon font), so a `*Color` import under `iconVariant: 'fonts'` is rerouted to
+     * a color-capable variant (`svg` / `svg-sprite`) following the same
+     * `iconVariant → fallbackVariant → svg` precedence, with a warning.
      */
     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.
+     *
+     * Also used as the preferred target when rerouting SVG-only color icons off a
+     * color-less `iconVariant` (e.g. `fonts`), provided the fallback itself is
+     * color-capable; otherwise the loader degrades to `svg`.
      */
     fallbackVariant?: IconVariant;
+    /**
+     * Resolve atomic imports to the **headless** (Griffel-free) build where the
+     * referenced module ships one. Defaults to `false`.
+     *
+     * Headless is best-effort per module: a module without a headless build for
+     * the resolved variant (e.g. headless `svg-sprite` which isn't generated yet)
+     * degrades to its standard implementation with a warning instead of failing
+     * the build.
+     *
+     * NOTE: the loader only rewrites component/utility imports — you must still
+     * import the headless CSS (`@fluentui/react-icons/headless/styles.css`, plus
+     * `headless/fonts/styles.css` for font icons) in your app entry point.
+     */
+    headless?: boolean;
+    /**
+     * Rewrite a **narrow, statically-provable** subset of dynamic `import()` barrel
+     * calls into atomic dynamic imports. Defaults to `false`.
+     *
+     * Only two shapes are rewritten, where the imported names are known literals at
+     * the call site:
+     * - `const { AddFilled } = await import('@fluentui/react-icons')`
+     * - `import('@fluentui/react-icons').then(({ AddFilled }) => …)`
+     *
+     * Names from the same atom are grouped into one import; names from different
+     * atoms become a positional `Promise.all([...])`. Anything else (namespace
+     * binding `const ns = await import(…)`, `.then(m => m.X)`, rest/computed/default
+     * patterns, non-literal specifiers) is left untouched and still warns.
+     *
+     * Prefer a dedicated module of **static** atomic imports that you lazy-load
+     * (`import('./icons')`) over relying on this; see the README for the gotchas.
+     */
+    allowDynamicImports?: boolean;
 }
 export default function fluentIconsAtomicImportLoader(this: LoaderContext<FluentIconsAtomicImportLoaderOptions>, sourceCode: string): void;

package/lib/index.js

@@ -9,12 +9,18 @@ function fluentIconsAtomicImportLoader(sourceCode) {
     if (!modules_1.SUPPORTED_MODULE_NAMES.some((name) => sourceCode.includes(name))) {
         return this.callback(null, sourceCode);
     }
-    const { iconVariant = 'svg', fallbackVariant } = this.getOptions();
+    const { iconVariant = 'svg', fallbackVariant, headless = false, allowDynamicImports = false } = this.getOptions();
     let code;
     let map;
     let diagnostics;
     try {
-        ({ code, map, diagnostics } = (0, transform_1.transformSource)(sourceCode, { iconVariant, fallbackVariant, path: resourcePath }));
+        ({ code, map, diagnostics } = (0, transform_1.transformSource)(sourceCode, {
+            iconVariant,
+            fallbackVariant,
+            headless,
+            allowDynamicImports,
+            path: resourcePath,
+        }));
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);

package/lib/modules.d.ts

@@ -5,6 +5,14 @@ export type IconVariant = 'svg' | 'fonts' | 'svg-sprite';
  * Every module supports `svg`, so it is always a valid resolution target.
  */
 export declare const DEFAULT_SAFETY_VARIANT: IconVariant;
+/**
+ * Whether an import name is a *color* icon variant, i.e. its style suffix is
+ * `Color` (e.g. `AddCircleColor`, `AddCircle20Color`). Every icon export carries
+ * exactly one trailing style suffix, so a `Color` suffix unambiguously marks a
+ * color variant — icons whose base name merely contains the word "Color" (e.g.
+ * `TextColorRegular`) end in a different style suffix.
+ */
+export declare function isColorIconName(importName: string): boolean;
 /**
  * Describes how a single supported module's barrel imports are rewritten into
  * atomic deep paths.
@@ -14,13 +22,27 @@ export interface ModuleDescriptor {
     name: string;
     /** Icon variants this module ships atomic entry points for. */
     supportedVariants: IconVariant[];
+    /**
+     * Icon variants for which this module ships a *headless* (Griffel-free) build.
+     * Empty when the module has no headless build at all.
+     */
+    headlessVariants: IconVariant[];
+    /**
+     * Icon variants for which this module ships *color* icon atoms.
+     *
+     * Color icons are SVG-only by nature — their gradients cannot be represented
+     * in an icon font — so the font builds contain no color glyphs. Empty when the
+     * module has no color icons at all.
+     */
+    colorVariants: 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.
+     * @param headless - Whether to resolve to the headless (Griffel-free) build.
      */
-    resolve(importName: string, variant: IconVariant): string;
+    resolve(importName: string, variant: IconVariant, headless: boolean): string;
 }
 export declare const MODULES: ModuleDescriptor[];
 export declare const SUPPORTED_MODULE_NAMES: string[];
@@ -45,3 +67,32 @@ export interface VariantResolution {
  * policy logic; callers decide how to surface `error`/`warning`.
  */
 export declare function resolveModuleVariant(descriptor: ModuleDescriptor, iconVariant: IconVariant, fallbackVariant: IconVariant | undefined): VariantResolution;
+/**
+ * Refines an already module-resolved `variant` for a single *color* icon import.
+ *
+ * Color icons are SVG-only (gradients cannot live in an icon font), so the font
+ * builds ship no color glyphs. When the module-resolved `variant` has no color
+ * atoms, the color import is rerouted using the same
+ * `iconVariant → fallbackVariant → svg` precedence as {@link resolveModuleVariant},
+ * constrained to variants that are both supported *and* color-capable. `svg` is
+ * always both, so a resolution always exists.
+ *
+ * Callers must only invoke this for color imports (see {@link isColorIconName})
+ * and only after module resolution has succeeded.
+ */
+export declare function resolveColorVariant(descriptor: ModuleDescriptor, variant: IconVariant, iconVariant: IconVariant, fallbackVariant: IconVariant | undefined): {
+    variant: IconVariant;
+    warning?: string;
+};
+/**
+ * Resolves whether to use a module's headless build, given the requested
+ * `headless` flag and the already-resolved `variant`.
+ *
+ * Headless is best-effort: when a module has no headless build for the resolved
+ * variant, the loader degrades to the standard (Griffel) implementation and
+ * records a warning rather than failing the build.
+ */
+export declare function resolveModuleHeadless(descriptor: ModuleDescriptor, variant: IconVariant, headless: boolean): {
+    headless: boolean;
+    warning?: string;
+};

package/lib/modules.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveModuleVariant = exports.getModuleDescriptor = exports.SUPPORTED_MODULE_NAMES = exports.MODULES = exports.DEFAULT_SAFETY_VARIANT = void 0;
+exports.resolveModuleHeadless = exports.resolveColorVariant = exports.resolveModuleVariant = exports.getModuleDescriptor = exports.SUPPORTED_MODULE_NAMES = exports.MODULES = exports.isColorIconName = 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.
@@ -11,6 +11,17 @@ const ICON_SUFFIX_REGEX = /(\d*)?(Regular|Filled|Light|Color)$/;
 function isIconName(importName) {
     return ICON_SUFFIX_REGEX.test(importName);
 }
+/**
+ * Whether an import name is a *color* icon variant, i.e. its style suffix is
+ * `Color` (e.g. `AddCircleColor`, `AddCircle20Color`). Every icon export carries
+ * exactly one trailing style suffix, so a `Color` suffix unambiguously marks a
+ * color variant — icons whose base name merely contains the word "Color" (e.g.
+ * `TextColorRegular`) end in a different style suffix.
+ */
+function isColorIconName(importName) {
+    return ICON_SUFFIX_REGEX.exec(importName)?.[2] === 'Color';
+}
+exports.isColorIconName = isColorIconName;
 function toKebabCase(value) {
     return value.replace(/[a-z\d](?=[A-Z])|[a-zA-Z](?=\d)|[A-Z](?=[A-Z][a-z])/g, '$&-').toLowerCase();
 }
@@ -20,24 +31,35 @@ function iconBaseName(importName) {
 const reactIcons = {
     name: '@fluentui/react-icons',
     supportedVariants: ['svg', 'fonts', 'svg-sprite'],
-    resolve(importName, variant) {
+    // Headless ships svg + fonts today; headless svg-sprite is not generated yet.
+    headlessVariants: ['svg', 'fonts'],
+    // Color icons ship in svg + svg-sprite; the font build has no color glyphs.
+    colorVariants: ['svg', 'svg-sprite'],
+    resolve(importName, variant, headless) {
         if (importName === 'useIconContext' || importName === 'IconDirectionContextProvider') {
+            // Context is framework-agnostic and shared by both APIs.
             return '@fluentui/react-icons/providers';
         }
+        const pkg = headless ? '@fluentui/react-icons/headless' : '@fluentui/react-icons';
         if (!isIconName(importName)) {
-            return '@fluentui/react-icons/utils';
+            return `${pkg}/utils`;
         }
-        return `@fluentui/react-icons/${variant}/${iconBaseName(importName)}`;
+        return `${pkg}/${variant}/${iconBaseName(importName)}`;
     },
 };
 const reactBrandIcons = {
     name: '@fluentui/react-brand-icons',
     supportedVariants: ['svg'],
-    resolve(importName) {
+    // Brand icons ship a headless (Griffel-free) svg build.
+    headlessVariants: ['svg'],
+    // Brand icons ship a single svg build, which already includes color icons.
+    colorVariants: ['svg'],
+    resolve(importName, _variant, headless) {
+        const pkg = headless ? '@fluentui/react-brand-icons/headless' : '@fluentui/react-brand-icons';
         if (!isIconName(importName)) {
-            return '@fluentui/react-brand-icons/utils';
+            return `${pkg}/utils`;
         }
-        return `@fluentui/react-brand-icons/svg/${iconBaseName(importName)}`;
+        return `${pkg}/svg/${iconBaseName(importName)}`;
     },
 };
 exports.MODULES = [reactIcons, reactBrandIcons];
@@ -73,3 +95,59 @@ function resolveModuleVariant(descriptor, iconVariant, fallbackVariant) {
     };
 }
 exports.resolveModuleVariant = resolveModuleVariant;
+/**
+ * Refines an already module-resolved `variant` for a single *color* icon import.
+ *
+ * Color icons are SVG-only (gradients cannot live in an icon font), so the font
+ * builds ship no color glyphs. When the module-resolved `variant` has no color
+ * atoms, the color import is rerouted using the same
+ * `iconVariant → fallbackVariant → svg` precedence as {@link resolveModuleVariant},
+ * constrained to variants that are both supported *and* color-capable. `svg` is
+ * always both, so a resolution always exists.
+ *
+ * Callers must only invoke this for color imports (see {@link isColorIconName})
+ * and only after module resolution has succeeded.
+ */
+function resolveColorVariant(descriptor, variant, iconVariant, fallbackVariant) {
+    // Already color-capable — nothing to reroute (e.g. svg, svg-sprite).
+    if (descriptor.colorVariants.includes(variant)) {
+        return { variant };
+    }
+    const candidates = [iconVariant, fallbackVariant, exports.DEFAULT_SAFETY_VARIANT].filter((candidate) => candidate !== undefined);
+    const colorVariant = candidates.find((candidate) => descriptor.supportedVariants.includes(candidate) && descriptor.colorVariants.includes(candidate)) ?? exports.DEFAULT_SAFETY_VARIANT;
+    return {
+        variant: colorVariant,
+        warning: `"${descriptor.name}" has no color icons for variant "${variant}" ` +
+            `(color icons are SVG-only). Resolving Color imports to "${colorVariant}".`,
+    };
+}
+exports.resolveColorVariant = resolveColorVariant;
+/**
+ * Resolves whether to use a module's headless build, given the requested
+ * `headless` flag and the already-resolved `variant`.
+ *
+ * Headless is best-effort: when a module has no headless build for the resolved
+ * variant, the loader degrades to the standard (Griffel) implementation and
+ * records a warning rather than failing the build.
+ */
+function resolveModuleHeadless(descriptor, variant, headless) {
+    if (!headless) {
+        return { headless: false };
+    }
+    if (descriptor.headlessVariants.includes(variant)) {
+        return { headless: true };
+    }
+    if (descriptor.headlessVariants.length === 0) {
+        return {
+            headless: false,
+            warning: `"${descriptor.name}" has no headless build; using its standard (Griffel) ` + `implementation for this import.`,
+        };
+    }
+    return {
+        headless: false,
+        warning: `"${descriptor.name}" has no headless build for variant "${variant}" ` +
+            `(headless supports: ${descriptor.headlessVariants.join(', ')}); using its standard ` +
+            `(Griffel) implementation for this import.`,
+    };
+}
+exports.resolveModuleHeadless = resolveModuleHeadless;

package/lib/transform.d.ts

@@ -5,6 +5,14 @@ interface TransformOptions {
     iconVariant: IconVariant;
     /** The variant to fall back to when a module does not support `iconVariant`. */
     fallbackVariant?: IconVariant;
+    /** Resolve to the headless (Griffel-free) build where the module supports it. */
+    headless?: boolean;
+    /**
+     * Rewrite a narrow, statically-provable subset of dynamic `import()` barrel
+     * calls into atomic dynamic imports (see {@link rewriteDynamicImports}).
+     * Defaults to `false`. Un-rewritable dynamic barrel imports still warn.
+     */
+    allowDynamicImports?: boolean;
     path: string;
 }
 export interface Diagnostic {

package/lib/transform.js

@@ -8,49 +8,90 @@ const oxc_parser_1 = require("oxc-parser");
 const magic_string_1 = __importDefault(require("magic-string"));
 const modules_1 = require("./modules");
 function transformSource(source, options) {
-    const { iconVariant, fallbackVariant, path } = options;
+    const { iconVariant, fallbackVariant, headless = false, allowDynamicImports = false, path } = options;
     const result = (0, oxc_parser_1.parseSync)(path, source, {
         sourceType: 'module',
     });
     if (result.errors.length > 0) {
         throw new Error(result.errors[0].message);
     }
-    const { staticImports, staticExports } = result.module;
+    const { staticImports, staticExports, dynamicImports } = 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();
+    // Dedupe diagnostics by message so a module's variant / color / headless
+    // concern surfaces at most once, even though resolution now runs per
+    // (module, color-ness) rather than per module.
+    const seenDiagnostics = new Set();
+    const pushDiagnostic = (diagnostic) => {
+        const key = `${diagnostic.level}:${diagnostic.message}`;
+        if (seenDiagnostics.has(key))
+            return;
+        seenDiagnostics.add(key);
+        diagnostics.push(diagnostic);
+    };
+    // Resolve each referenced module at most once per color-ness: color icons may
+    // route to a different variant than their non-color siblings, so the cache key
+    // is `${name}:${isColor}`. Resolution stays O(#modules × 2) regardless of how
+    // many icons a file imports.
+    const resolvedTargets = 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).
+     * Returns the target (variant + headless) to rewrite a single referenced
+     * import with, or `null` when the module could not be resolved (an error
+     * diagnostic has been recorded and the import should be left untouched).
      */
-    const variantFor = (descriptor) => {
-        if (resolvedVariants.has(descriptor.name)) {
-            return resolvedVariants.get(descriptor.name);
+    const targetFor = (descriptor, isColor) => {
+        const cacheKey = `${descriptor.name}:${isColor}`;
+        if (resolvedTargets.has(cacheKey)) {
+            return resolvedTargets.get(cacheKey);
         }
         const resolution = (0, modules_1.resolveModuleVariant)(descriptor, iconVariant, fallbackVariant);
         if (resolution.warning) {
-            diagnostics.push({ level: 'warning', message: resolution.warning });
+            pushDiagnostic({ level: 'warning', message: resolution.warning });
         }
         if (resolution.error) {
-            diagnostics.push({ level: 'error', message: resolution.error });
+            pushDiagnostic({ level: 'error', message: resolution.error });
+        }
+        if (!resolution.variant) {
+            resolvedTargets.set(cacheKey, null);
+            return null;
+        }
+        let variant = resolution.variant;
+        // Color icons are SVG-only; reroute them off any color-less variant (fonts)
+        // to a color-capable one, honoring the fallback precedence.
+        if (isColor) {
+            const colorResolution = (0, modules_1.resolveColorVariant)(descriptor, variant, iconVariant, fallbackVariant);
+            if (colorResolution.warning) {
+                pushDiagnostic({ level: 'warning', message: colorResolution.warning });
+            }
+            variant = colorResolution.variant;
+        }
+        const headlessResolution = (0, modules_1.resolveModuleHeadless)(descriptor, variant, headless);
+        if (headlessResolution.warning) {
+            pushDiagnostic({ level: 'warning', message: headlessResolution.warning });
         }
-        const variant = resolution.variant ?? null;
-        resolvedVariants.set(descriptor.name, variant);
-        return variant;
+        const target = { variant, headless: headlessResolution.headless };
+        resolvedTargets.set(cacheKey, target);
+        return target;
     };
     for (const imp of staticImports) {
         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)
             continue;
+        // Resolve each named specifier independently — color icons may route to a
+        // different variant than their non-color siblings in the same statement.
+        const resolvedEntries = namedEntries.map((entry) => ({
+            entry,
+            importedName: entry.importName.name,
+            target: targetFor(descriptor, (0, modules_1.isColorIconName)(entry.importName.name)),
+        }));
+        // A module-level resolution error is independent of color-ness, so if any
+        // specifier is unresolved they all are — leave the whole statement untouched.
+        if (resolvedEntries.some(({ target }) => !target))
+            continue;
         const otherEntries = imp.entries.filter((e) => e.importName.kind !== 'Name');
         const lines = [];
         if (otherEntries.length > 0) {
@@ -59,10 +100,9 @@ function transformSource(source, options) {
                 .join(', ');
             lines.push(`import ${names} from '${moduleName}';`);
         }
-        for (const entry of namedEntries) {
-            const importedName = entry.importName.name;
+        for (const { entry, importedName, target } of resolvedEntries) {
             const localName = entry.localName.value;
-            const newSource = descriptor.resolve(importedName, variant);
+            const newSource = descriptor.resolve(importedName, target.variant, target.headless);
             const spec = importedName === localName ? importedName : `${importedName} as ${localName}`;
             lines.push(`import { ${spec} } from '${newSource}';`);
         }
@@ -81,12 +121,12 @@ function transformSource(source, options) {
         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 target = targetFor(descriptor, (0, modules_1.isColorIconName)(importedName));
+            if (!target)
+                continue;
             const exportedName = entry.exportName.name;
-            const newSource = descriptor.resolve(importedName, variant);
+            const newSource = descriptor.resolve(importedName, target.variant, target.headless);
             const spec = importedName === exportedName ? importedName : `${importedName} as ${exportedName}`;
             lines.push(`export { ${spec} } from '${newSource}';`);
         }
@@ -94,6 +134,169 @@ function transformSource(source, options) {
             continue;
         src.overwrite(exp.start, exp.end, lines.join('\n'));
     }
+    // Source-literal start offsets of dynamic imports that were atomized below.
+    // Used to suppress the "cannot be atomized" warning for imports we rewrote.
+    const rewrittenImportStarts = new Set();
+    if (allowDynamicImports) {
+        /**
+         * Resolves one destructured binding name to the atomic subpath it should be
+         * imported from, honoring the active `iconVariant` / `headless` / color rules
+         * (same policy as static imports). Returns `null` when the owning module can't
+         * be resolved — `targetFor` has already recorded an error diagnostic — which
+         * signals the caller to bail and leave the dynamic import untouched.
+         *
+         * @example
+         * // iconVariant: 'svg'
+         * resolveNameSource(reactIcons, 'AddFilled')   // → '@fluentui/react-icons/svg/add'
+         * resolveNameSource(reactIcons, 'bundleIcon')  // → '@fluentui/react-icons/utils'
+         * // iconVariant: 'fonts'
+         * resolveNameSource(reactIcons, 'AddFilled')   // → '@fluentui/react-icons/fonts/add'
+         */
+        const resolveNameSource = (descriptor, importedName) => {
+            const target = targetFor(descriptor, (0, modules_1.isColorIconName)(importedName));
+            if (!target)
+                return null;
+            return descriptor.resolve(importedName, target.variant, target.headless);
+        };
+        /**
+         * Groups the properties of a destructuring object pattern by the atomic module
+         * each imported name resolves to, preserving first-seen order. Each group's
+         * `specs` are the emit-ready specifier strings (`'AddFilled'`, or
+         * `'ArrowLeftRegular: arrow'` for a rename).
+         *
+         * Returns `null` (bail — leave the dynamic import untouched) when any property
+         * isn't a plain, statically-known `name → binding` pair: rest elements,
+         * computed/string keys, default values, or nested patterns.
+         *
+         * @example
+         * // `{ AddFilled, AddRegular }`  — both live in the `add` atom
+         * // → [{ source: '@fluentui/react-icons/svg/add', specs: ['AddFilled', 'AddRegular'] }]
+         *
+         * @example
+         * // `{ AddFilled, ArrowLeftRegular: arrow }`  — different atoms, one renamed
+         * // → [
+         * //     { source: '@fluentui/react-icons/svg/add',        specs: ['AddFilled'] },
+         * //     { source: '@fluentui/react-icons/svg/arrow-left', specs: ['ArrowLeftRegular: arrow'] },
+         * //   ]
+         *
+         * @example
+         * // `{ AddFilled, ...rest }`  → null   (rest element → bail)
+         */
+        const buildGroups = (objectPattern, descriptor) => {
+            const bySource = new Map();
+            const order = [];
+            for (const prop of objectPattern.properties) {
+                if (prop.type !== 'Property' || prop.computed || prop.kind !== 'init')
+                    return null;
+                if (prop.key.type !== 'Identifier' || prop.value.type !== 'Identifier')
+                    return null;
+                const importedName = prop.key.name;
+                const localName = prop.value.name;
+                const resolvedSource = resolveNameSource(descriptor, importedName);
+                if (resolvedSource === null)
+                    return null;
+                const spec = importedName === localName ? importedName : `${importedName}: ${localName}`;
+                if (!bySource.has(resolvedSource)) {
+                    bySource.set(resolvedSource, []);
+                    order.push(resolvedSource);
+                }
+                bySource.get(resolvedSource).push(spec);
+            }
+            if (order.length === 0)
+                return null;
+            return order.map((groupSource) => ({ source: groupSource, specs: bySource.get(groupSource) }));
+        };
+        const importCallText = (groups) => groups.length === 1
+            ? `import('${groups[0].source}')`
+            : `Promise.all([${groups.map((g) => `import('${g.source}')`).join(', ')}])`;
+        const patternText = (groups) => groups.length === 1
+            ? `{ ${groups[0].specs.join(', ')} }`
+            : `[${groups.map((g) => `{ ${g.specs.join(', ')} }`).join(', ')}]`;
+        const visitor = new oxc_parser_1.Visitor({
+            // `const { A, B } = await import('barrel')`
+            VariableDeclarator(node) {
+                if (node.id.type !== 'ObjectPattern' ||
+                    node.init?.type !== 'AwaitExpression' ||
+                    node.init.argument.type !== 'ImportExpression') {
+                    return;
+                }
+                const importExpr = node.init.argument;
+                if (importExpr.source.type !== 'Literal' || typeof importExpr.source.value !== 'string')
+                    return;
+                const descriptor = (0, modules_1.getModuleDescriptor)(importExpr.source.value);
+                if (!descriptor)
+                    return;
+                const groups = buildGroups(node.id, descriptor);
+                if (!groups)
+                    return;
+                src.overwrite(node.start, node.end, `${patternText(groups)} = await ${importCallText(groups)}`);
+                rewrittenImportStarts.add(importExpr.source.start);
+            },
+            // `import('barrel').then(({ A, B }) => …)`
+            CallExpression(node) {
+                if (node.callee.type !== 'MemberExpression' ||
+                    node.callee.computed ||
+                    node.callee.property.type !== 'Identifier' ||
+                    node.callee.property.name !== 'then' ||
+                    node.callee.object.type !== 'ImportExpression') {
+                    return;
+                }
+                const importExpr = node.callee.object;
+                if (importExpr.source.type !== 'Literal' || typeof importExpr.source.value !== 'string')
+                    return;
+                const descriptor = (0, modules_1.getModuleDescriptor)(importExpr.source.value);
+                if (!descriptor)
+                    return;
+                const callback = node.arguments[0];
+                if (!callback || (callback.type !== 'ArrowFunctionExpression' && callback.type !== 'FunctionExpression')) {
+                    return;
+                }
+                const param = callback.params[0];
+                if (param?.type !== 'ObjectPattern')
+                    return;
+                const groups = buildGroups(param, descriptor);
+                if (!groups)
+                    return;
+                src.overwrite(importExpr.start, importExpr.end, importCallText(groups));
+                // Multiple atoms resolve to an array, so the callback must destructure by
+                // position instead of by name.
+                if (groups.length > 1) {
+                    src.overwrite(param.start, param.end, patternText(groups));
+                }
+                rewrittenImportStarts.add(importExpr.source.start);
+            },
+        });
+        visitor.visit(result.program);
+    }
+    // Dynamic imports of a barrel (`import('@fluentui/react-icons')`) cannot be
+    // atomized: the returned namespace object is a runtime value whose usage is
+    // not statically known, so the whole icon set ends up in the async chunk. We
+    // can't rewrite it safely, but we can warn and point at the atomic escape
+    // hatch (`import('@fluentui/react-icons/svg/add')`). Atomic and subpath
+    // requests don't match a barrel descriptor, so they never warn.
+    for (const dyn of dynamicImports) {
+        const request = dyn.moduleRequest;
+        if (!request)
+            continue;
+        // Skip imports we already atomized above (their usage was statically provable).
+        if (rewrittenImportStarts.has(request.start))
+            continue;
+        // Unlike static imports, oxc doesn't resolve a dynamic import's argument to a
+        // specifier value — it's an arbitrary expression. Match the raw span against
+        // each supported module's quoted spellings; this naturally ignores variables,
+        // interpolated templates, and subpath/atomic requests (module names never
+        // contain quotes).
+        const raw = source.slice(request.start, request.end);
+        const moduleName = modules_1.SUPPORTED_MODULE_NAMES.find((name) => raw === `'${name}'` || raw === `"${name}"` || raw === `\`${name}\``);
+        if (!moduleName)
+            continue;
+        pushDiagnostic({
+            level: 'warning',
+            message: `dynamic import of the "${moduleName}" barrel cannot be atomized, so the entire icon ` +
+                `set will be bundled into the async chunk. Import an atomic path directly instead, ` +
+                `e.g. import('${moduleName}/svg/add').`,
+        });
+    }
     return {
         code: src.toString(),
         map: src.generateMap({ hires: true }),

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@fluentui/react-icons-atomic-webpack-loader",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Webpack loader that transforms barrel imports and re-exports from @fluentui/react-icons into atomic deep paths",
   "main": "lib/index.js",
   "scripts": {
-    "build": "tsc -p .",
-    "test": "vitest run && webpack -c test/webpack.config.js"
+    "build": "yarn run -T tsc -p .",
+    "lint": "yarn run -T eslint package.json",
+    "test": "yarn run -T vitest run && yarn run -T webpack -c test/webpack.config.js"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -24,11 +25,7 @@
     "oxc-parser": "^0.125.0"
   },
   "devDependencies": {
-    "@fluentui/react-icons": "*",
-    "ts-loader": "^9.5.0",
-    "typescript": "5.0.4",
-    "webpack": "^5.72.0",
-    "@types/node": "22"
+    "@fluentui/react-icons": "*"
   },
   "peerDependencies": {
     "webpack": ">=5.0.0"