@fluentui/eslint-plugin-react-icons 0.0.1

package/README.md

@@ -0,0 +1,83 @@
+# @fluentui/eslint-plugin-react-icons
+
+ESLint plugin for [`@fluentui/react-icons`](https://github.com/microsoft/fluentui-system-icons/tree/main/packages/react-icons).
+
+## Overview
+
+This ESLint plugin enforces best practices and coding standards when consuming
+Fluent UI System and Brand Icons. It helps developers:
+
+- Maintain consistency across `@fluentui/react-icons` usage
+- Catch common mistakes and anti-patterns early
+
+## Installation
+
+```bash
+# npm
+npm install --save-dev @fluentui/eslint-plugin-react-icons
+
+# yarn
+yarn add --dev @fluentui/eslint-plugin-react-icons
+
+# pnpm
+pnpm add --save-dev @fluentui/eslint-plugin-react-icons
+```
+
+## Usage
+
+### Flat Config (ESLint 9+, recommended)
+
+Add the plugin to your `eslint.config.js`:
+
+```js
+const fluentuiReactIcons = require('@fluentui/eslint-plugin-react-icons');
+
+module.exports = [
+  fluentuiReactIcons.configs.recommended,
+  // Your other configs...
+];
+```
+
+Or configure individual rules manually:
+
+```js
+const fluentuiReactIcons = require('@fluentui/eslint-plugin-react-icons');
+
+module.exports = [
+  {
+    plugins: {
+      '@fluentui/react-icons': fluentuiReactIcons,
+    },
+    rules: {
+      '@fluentui/react-icons/prefer-resizable': 'warn',
+    },
+  },
+];
+```
+
+### Legacy Config (ESLint 8 and below)
+
+Add the plugin to your `.eslintrc.js`:
+
+```js
+module.exports = {
+  plugins: ['@fluentui/react-icons'],
+  extends: ['plugin:@fluentui/react-icons/recommended-legacy'],
+};
+```
+
+## Available Rules
+
+💼 Configurations enabled in.\
+🔧 Whether the rule has an auto-fixer and/or has suggestions.
+
+| Name                                                 | Description                                                       | 💼  | 🔧  |
+| ---------------------------------------------------- | ----------------------------------------------------------------- | --- | --- |
+| [prefer-resizable](./docs/rules/prefer-resizable.md) | Prefer resizable Fluent icons over fixed-size ("sized") variants. | ✅  | 💡  |
+
+💼 ✅ = enabled in the `recommended` config (as `warn`).\
+🔧 = fixable , 💡 = has suggestions.
+
+## License
+
+This project is licensed under the MIT License.

package/docs/rules/prefer-resizable.md

@@ -0,0 +1,80 @@
+# prefer-resizable
+
+Prefer resizable Fluent icons over fixed-size ("sized") variants.
+
+## Rule Details
+
+`@fluentui/react-icons` (and `@fluentui/react-brand-icons`) ship each icon in two
+shapes:
+
+- **Resizable** — e.g. `SendRegular`, `AccessTimeFilled`. Rendered at `1em`, so
+  they scale to any size via `fontSize` / CSS and let a bundler ship a single glyph
+  that can be reused at multiple sizes.
+- **Sized** — e.g. `Send24Regular`, `AccessTime24Filled`. Locked to a design pixel
+  size; each size is a separate export and its hardcoded geometry ignores
+  `fontSize`.
+
+This rule flags imports (and namespace usages) of sized icons and offers a
+suggestion to switch to the resizable equivalent.
+
+## How sized icons are detected
+
+Detection is data-driven, generated from `@fluentui/react-icons` `metadata.json`:
+
+- A name is "sized" when it ends with a real two-digit Fluent size
+  (`10, 12, 16, 20, 24, 28, 32, 48`) immediately before its variant suffix
+  (`Filled` / `Regular` / `Color` / `Light`).
+- Names whose trailing digits are part of a product name rather than a size
+  (e.g. `Battery10Regular`, `Fps120Regular`, `Timer10Filled`) are excluded via a
+  generated collision denylist, so they are never mis-flagged.
+
+The generated data is verified to classify every icon exactly as `metadata.json` does;
+regenerate it with `yarn generate:data` when the icon set changes.
+
+## Examples
+
+### ❌ Incorrect
+
+```tsx
+import { Send24Regular } from '@fluentui/react-icons';
+import { Send24Filled } from '@fluentui/react-brand-icons';
+import * as Icons from '@fluentui/react-icons';
+
+const a = <Send24Regular />;
+const b = <Icons.Send24Regular />;
+```
+
+### ✅ Correct
+
+```tsx
+import { SendRegular } from '@fluentui/react-icons';
+import * as Icons from '@fluentui/react-icons';
+
+const a = <SendRegular fontSize={24} />;
+const b = <Icons.SendRegular />;
+
+// Product names that merely end in a size-shaped number are fine:
+import { Battery10Regular, Fps120Regular } from '@fluentui/react-icons';
+```
+
+## Options
+
+```jsonc
+{
+  "@fluentui/react-icons/prefer-resizable": [
+    "warn",
+    {
+      // Module sources treated as Fluent icon packages (matched exactly or as a
+      // subpath prefix, e.g. "@fluentui/react-icons/fonts/send").
+      "sources": ["@fluentui/react-icons", "@fluentui/react-brand-icons"],
+    },
+  ],
+}
+```
+
+## When Not To Use It
+
+If you intentionally rely on a specific pixel size's optical tuning and do not want
+to migrate those usages, disable the rule (or the specific lines). Note that
+resizable icons are the 20px artwork made scalable, so swapping a sized icon may
+change its optical rendering.

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+export declare const meta: {
+    name: string;
+    version: string;
+};
+export declare const rules: {
+    "prefer-resizable": TSESLint.RuleModule<import("./rules/prefer-resizable").MessageIds, import("./rules/prefer-resizable").Options, TSESLint.RuleListener>;
+};
+export declare const configs: Record<string, TSESLint.FlatConfig.Config | TSESLint.ClassicConfig.Config>;

package/lib/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.rules = exports.meta = void 0;
+const node_module_1 = require("node:module");
+const prefer_resizable_1 = require("./rules/prefer-resizable");
+// Read name/version from package.json. A runtime `require` (relative to the built
+// `lib/` output) is used instead of a static `import ... from '../package.json'`
+// because the latter is outside tsc's `rootDir` and would break the flat `lib/`
+// output layout.
+const { name, version } = (0, node_module_1.createRequire)(__filename)('../package.json');
+exports.meta = {
+    name,
+    version,
+};
+exports.rules = {
+    [prefer_resizable_1.RULE_NAME]: prefer_resizable_1.rule,
+};
+const plugin = { meta: exports.meta, rules: exports.rules };
+exports.configs = {
+    // Flat config (ESLint 9+, recommended).
+    recommended: {
+        name: '@fluentui/react-icons/recommended',
+        plugins: {
+            '@fluentui/react-icons': plugin,
+        },
+        rules: {
+            [`@fluentui/react-icons/${prefer_resizable_1.RULE_NAME}`]: 'warn',
+        },
+    },
+    // Legacy config (ESLint 8 and below).
+    'recommended-legacy': {
+        plugins: ['@fluentui/react-icons'],
+        rules: {
+            [`@fluentui/react-icons/${prefer_resizable_1.RULE_NAME}`]: 'warn',
+        },
+    },
+};

package/lib/rules/prefer-resizable/icon-sizes.generated.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pixel sizes used by "sized" Fluent icon variants (e.g. `AccessTime24Filled`).
+ * All Fluent icon sizes are two digits; a sized export name embeds one of these
+ * immediately before its variant suffix.
+ */
+export declare const SIZED_ICON_SIZES: readonly number[];
+/**
+ * "resizable" icon names that syntactically look "sized" because a product name
+ * ends in a two-digit number matching a real size (e.g. `Battery10Regular`, where
+ * "10" is a battery level, not a size). These must NOT be flagged as sized.
+ */
+export declare const RESIZABLE_COLLISIONS: readonly string[];

package/lib/rules/prefer-resizable/icon-sizes.generated.js

@@ -0,0 +1,34 @@
+"use strict";
+// AUTO-GENERATED by scripts/generate-icon-sizes.mjs — do not edit by hand.
+// Regenerate with: npm run generate:data (inside packages/eslint-plugin-react-icons).
+//
+// Source of truth: @fluentui/react-icons metadata.json (icon "type" field).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESIZABLE_COLLISIONS = exports.SIZED_ICON_SIZES = void 0;
+/**
+ * Pixel sizes used by "sized" Fluent icon variants (e.g. `AccessTime24Filled`).
+ * All Fluent icon sizes are two digits; a sized export name embeds one of these
+ * immediately before its variant suffix.
+ */
+exports.SIZED_ICON_SIZES = [10, 12, 16, 20, 24, 28, 32, 48];
+/**
+ * "resizable" icon names that syntactically look "sized" because a product name
+ * ends in a two-digit number matching a real size (e.g. `Battery10Regular`, where
+ * "10" is a battery level, not a size). These must NOT be flagged as sized.
+ */
+exports.RESIZABLE_COLLISIONS = [
+    'Battery10Filled',
+    'Battery10Regular',
+    'BatteryCharge10Filled',
+    'BatteryCharge10Regular',
+    'Fps120Filled',
+    'Fps120Regular',
+    'Fps124Filled',
+    'Fps124Regular',
+    'SkipBack10Filled',
+    'SkipBack10Regular',
+    'SkipForward10Filled',
+    'SkipForward10Regular',
+    'Timer10Filled',
+    'Timer10Regular',
+];

package/lib/rules/prefer-resizable/index.d.ts

@@ -0,0 +1,7 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const RULE_NAME = "prefer-resizable";
+export type MessageIds = 'preferResizable' | 'useResizable';
+export type Options = [{
+    sources?: string[];
+}];
+export declare const rule: ESLintUtils.RuleModule<MessageIds, Options, ESLintUtils.RuleListener>;

package/lib/rules/prefer-resizable/index.js

@@ -0,0 +1,126 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rule = exports.RULE_NAME = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const sized_icons_1 = require("./sized-icons");
+exports.RULE_NAME = 'prefer-resizable';
+const createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/microsoft/fluentui-system-icons/blob/main/packages/eslint-plugin-react-icons/docs/rules/${name}.md`);
+const DEFAULT_SOURCES = ['@fluentui/react-icons', '@fluentui/react-brand-icons'];
+exports.rule = createRule({
+    name: exports.RULE_NAME,
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer resizable Fluent icons over fixed-size ("sized") variants. Resizable icons scale to any size and reduce bundle size.',
+        },
+        hasSuggestions: true,
+        messages: {
+            preferResizable: 'Prefer the resizable "{{resizable}}" icon over the fixed-size "{{sized}}" icon. Resizable icons scale to any size (via the `fontSize`/CSS) and reduce bundle size.',
+            useResizable: 'Replace "{{sized}}" with "{{resizable}}".',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    sources: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Module sources treated as Fluent icon packages.',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ sources: DEFAULT_SOURCES }],
+    create(context, [options]) {
+        const sources = options.sources ?? DEFAULT_SOURCES;
+        const { sourceCode } = context;
+        /** Local identifiers bound to `import * as X` from an icon source. */
+        const namespaceLocals = new Set();
+        function isIconSource(value) {
+            return sources.some((source) => value === source || value.startsWith(`${source}/`));
+        }
+        function reportNamed(specifier) {
+            const importedName = specifier.imported.name;
+            const resizable = (0, sized_icons_1.getResizableIconName)(importedName);
+            if (resizable === null) {
+                return;
+            }
+            const isAliased = specifier.local.range[0] !== specifier.imported.range[0];
+            const fix = (fixer) => {
+                if (isAliased) {
+                    // `import { Send24Regular as Foo }` -> only rename the imported name.
+                    return [fixer.replaceText(specifier.imported, resizable)];
+                }
+                // `import { Send24Regular }` -> rename the binding and every usage.
+                const [variable] = sourceCode.getDeclaredVariables(specifier);
+                const fixes = [fixer.replaceText(specifier.local, resizable)];
+                for (const reference of variable?.references ?? []) {
+                    fixes.push(fixer.replaceText(reference.identifier, resizable));
+                }
+                return fixes;
+            };
+            context.report({
+                node: specifier.imported,
+                messageId: 'preferResizable',
+                data: { sized: importedName, resizable },
+                suggest: [
+                    {
+                        messageId: 'useResizable',
+                        data: { sized: importedName, resizable },
+                        fix,
+                    },
+                ],
+            });
+        }
+        function reportNamespaceMember(property) {
+            const resizable = (0, sized_icons_1.getResizableIconName)(property.name);
+            if (resizable === null) {
+                return;
+            }
+            const fix = (fixer) => fixer.replaceText(property, resizable);
+            context.report({
+                node: property,
+                messageId: 'preferResizable',
+                data: { sized: property.name, resizable },
+                suggest: [
+                    {
+                        messageId: 'useResizable',
+                        data: { sized: property.name, resizable },
+                        fix,
+                    },
+                ],
+            });
+        }
+        return {
+            ImportDeclaration(node) {
+                if (!isIconSource(node.source.value)) {
+                    return;
+                }
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === 'ImportSpecifier') {
+                        reportNamed(specifier);
+                    }
+                    else if (specifier.type === 'ImportNamespaceSpecifier') {
+                        namespaceLocals.add(specifier.local.name);
+                    }
+                }
+            },
+            'JSXMemberExpression[object.type="JSXIdentifier"]'(node) {
+                const object = node.object;
+                if (namespaceLocals.has(object.name)) {
+                    reportNamespaceMember(node.property);
+                }
+            },
+            'MemberExpression[object.type="Identifier"][property.type="Identifier"][computed=false]'(node) {
+                const object = node.object;
+                if (namespaceLocals.has(object.name)) {
+                    reportNamespaceMember(node.property);
+                }
+            },
+        };
+    },
+});

package/lib/rules/prefer-resizable/sized-icons.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Matches a "sized" Fluent icon export name: a two-digit pixel size immediately
+ * before the variant suffix, e.g. `AccessTime24Filled`. Sizes are sorted
+ * descending so any multi-digit size (should one ever be added) is matched first.
+ */
+export declare const SIZED_ICON_RE: RegExp;
+/**
+ * Whether an icon export name refers to a fixed-size ("sized") icon variant
+ * (e.g. `Send24Regular`) rather than a resizable one (e.g. `SendRegular`).
+ *
+ * Names that look sized but are actually resizable (a product name ending in a
+ * size-shaped number, e.g. `Battery10Regular`) are excluded via the generated
+ * collision denylist.
+ */
+export declare function isSizedIconName(name: string): boolean;
+/**
+ * The resizable equivalent of a sized icon name (the size token stripped), or
+ * `null` when the name is not a sized icon. E.g. `Send24Regular` -> `SendRegular`,
+ * `PresenceDnd10Filled` -> `PresenceDndFilled`.
+ */
+export declare function getResizableIconName(name: string): string | null;

package/lib/rules/prefer-resizable/sized-icons.js

@@ -0,0 +1,38 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getResizableIconName = exports.isSizedIconName = exports.SIZED_ICON_RE = void 0;
+const icon_sizes_generated_1 = require("./icon-sizes.generated");
+const VARIANT_SUFFIX = 'Filled|Regular|Color|Light';
+/**
+ * Matches a "sized" Fluent icon export name: a two-digit pixel size immediately
+ * before the variant suffix, e.g. `AccessTime24Filled`. Sizes are sorted
+ * descending so any multi-digit size (should one ever be added) is matched first.
+ */
+exports.SIZED_ICON_RE = new RegExp(`(${[...icon_sizes_generated_1.SIZED_ICON_SIZES].sort((a, b) => b - a).join('|')})(${VARIANT_SUFFIX})$`);
+const collisions = new Set(icon_sizes_generated_1.RESIZABLE_COLLISIONS);
+/**
+ * Whether an icon export name refers to a fixed-size ("sized") icon variant
+ * (e.g. `Send24Regular`) rather than a resizable one (e.g. `SendRegular`).
+ *
+ * Names that look sized but are actually resizable (a product name ending in a
+ * size-shaped number, e.g. `Battery10Regular`) are excluded via the generated
+ * collision denylist.
+ */
+function isSizedIconName(name) {
+    return exports.SIZED_ICON_RE.test(name) && !collisions.has(name);
+}
+exports.isSizedIconName = isSizedIconName;
+/**
+ * The resizable equivalent of a sized icon name (the size token stripped), or
+ * `null` when the name is not a sized icon. E.g. `Send24Regular` -> `SendRegular`,
+ * `PresenceDnd10Filled` -> `PresenceDndFilled`.
+ */
+function getResizableIconName(name) {
+    if (!isSizedIconName(name)) {
+        return null;
+    }
+    return name.replace(exports.SIZED_ICON_RE, '$2');
+}
+exports.getResizableIconName = getResizableIconName;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@fluentui/eslint-plugin-react-icons",
+  "version": "0.0.1",
+  "description": "ESLint plugin for @fluentui/react-icons and @fluentui/react-brand-icons",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "git clean -fXd lib/",
+    "generate:data": "node scripts/generate-icon-sizes.mjs --metadata ../react-icons/metadata.json --out src/rules/prefer-resizable/icon-sizes.generated.ts",
+    "build": "yarn clean && yarn generate:data && yarn run -T tsc -p tsconfig.lib.json",
+    "lint": "yarn run -T eslint src package.json",
+    "test": "yarn run -T vitest run",
+    "type-check": "yarn run -T tsc -p tsconfig.json",
+    "type-check:infra": "yarn run -T tsc -p tsconfig.utils.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/fluentui-system-icons.git",
+    "directory": "packages/eslint-plugin-react-icons"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/microsoft/fluentui-system-icons/issues"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "7.18.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "files": [
+    "lib/*",
+    "docs"
+  ]
+}