js-style-kit 0.6.1 → 0.7.0

package/src/eslint/react/README.md

@@ -0,0 +1,416 @@
+# React Configuration
+
+Comprehensive React support with ESLint rules for React, hooks, compiler, and framework-specific configurations for Next.js, Vite, Remix, and React Router.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+React support is **disabled by default** and provides:
+
+- React and JSX best practices
+- React Hooks validation
+- React Compiler support (enabled by default)
+- Framework-specific configurations
+- TypeScript integration
+
+## Quick Start
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  react: true, // Enable with defaults
+});
+```
+
+## Configuration Options
+
+### Basic Enable
+
+```js
+react: true; // React + hooks + compiler rules
+```
+
+### Framework-Specific
+
+```js
+react: {
+  framework: "next",        // "next" | "vite" | "remix" | "react-router" | "none"
+  reactCompiler: true,      // React 19 compiler (default: true)
+  reactRefresh: false,      // Fast Refresh validation (framework-dependent)
+}
+```
+
+## Framework Configurations
+
+### Next.js
+
+```js
+export default eslintConfig({
+  react: { framework: "next" },
+});
+```
+
+**Includes:**
+
+- ✅ Next.js-specific ESLint rules
+- ✅ Ignores `.next` directory
+- ✅ React Refresh disabled (Next.js handles it)
+
+### Vite
+
+```js
+export default eslintConfig({
+  react: { framework: "vite" },
+});
+```
+
+**Includes:**
+
+- ✅ React Refresh validation enabled
+- ✅ No Next.js-specific rules
+
+### Remix
+
+```js
+export default eslintConfig({
+  react: { framework: "remix" },
+});
+```
+
+**Includes:**
+
+- ✅ React Refresh disabled (Remix handles it)
+- ✅ No Next.js-specific rules
+
+### React Router
+
+```js
+export default eslintConfig({
+  react: { framework: "react-router" },
+});
+```
+
+**Includes:**
+
+- ✅ React Refresh disabled (Router handles it)
+- ✅ No Next.js-specific rules
+
+### Override Defaults
+
+```js
+react: {
+  framework: "next",
+  reactRefresh: true,  // Force enable even with Next.js
+}
+```
+
+## React Compiler
+
+[React Compiler](https://react.dev/learn/react-compiler) optimizes React components automatically. `eslint-plugin-react-hooks` provides several rules to ensure your code is compatible with the compiler. They are new, and they may conflict with some rules from `eslint-plugin-react`. If it does, open an issue to let me know!
+
+**Enabled by default** when React is enabled.
+
+### What It Checks
+
+- Proper Hook usage
+- Component purity requirements
+- Dependencies tracking
+
+### Disable Compiler Rules
+
+```js
+export default eslintConfig({
+  react: {
+    framework: "none", // could be anything
+    reactCompiler: false,
+  },
+});
+```
+
+## React Fast Refresh
+
+[React Fast Refresh](https://www.npmjs.com/package/react-refresh) provides instant component updates without losing state. The validation ensures your components work with Fast Refresh.
+
+### When to Enable
+
+- ✅ **Enable** for Vite SPAs
+- ❌ **Disable** for Next.js (handles its own)
+- ❌ **Disable** for Remix (handles its own)
+- ❌ **Disable** for React Router (handles its own)
+
+### Manual Control
+
+```js
+react: {
+  framework: "vite",
+  reactRefresh: true,  // Explicitly enable
+}
+```
+
+### What It Validates
+
+- ✅ Components properly exported
+- ✅ No anonymous components
+- ✅ No nested component definitions
+- ✅ Export patterns compatible with Fast Refresh
+- ✅ Allows constant exports with components (Vite-compatible)
+
+## Function Styles for Components
+
+Control how React components are written:
+
+```js
+export default eslintConfig({
+  react: true,
+  functionStyle: "arrow", // Default
+});
+```
+
+### Arrow Functions (default)
+
+```jsx
+// ✅ Good
+const MyComponent = ({ name }) => {
+  return <div>Hello {name}</div>;
+};
+
+export default () => <div>App</div>;
+```
+
+### Function Declarations
+
+```jsx
+// ✅ Good
+function MyComponent({ name }) {
+  return <div>Hello {name}</div>;
+}
+
+export default function App() {
+  return <div>App</div>;
+}
+```
+
+### Function Expressions
+
+```jsx
+// ✅ Good
+const MyComponent = function ({ name }) {
+  return <div>Hello {name}</div>;
+};
+
+export default function () {
+  return <div>App</div>;
+}
+```
+
+### Disabled (Any Style)
+
+```jsx
+functionStyle: "off"; // Use any style you prefer
+```
+
+## Key Rules
+
+### React Hooks
+
+- **`react-hooks/rules-of-hooks`** - Enforces Rules of Hooks
+- **`react-hooks/exhaustive-deps`** - Validates dependency arrays
+
+```jsx
+// ✅ Good - hooks at top level
+const MyComponent = () => {
+  const [count, setCount] = useState(0);
+  useEffect(() => {
+    /* ... */
+  }, [count]); // All deps listed
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+};
+
+// ❌ Bad - hooks in conditional
+const MyComponent = () => {
+  if (condition) {
+    const [count, setCount] = useState(0); // ❌ Conditional hook
+  }
+};
+```
+
+### JSX Best Practices
+
+- **`react/jsx-boolean-value`** - Enforce boolean prop syntax
+- **`react/jsx-curly-brace-presence`** - Avoid unnecessary JSX braces
+- **`react/jsx-fragments`** - Prefer `<>` over `<React.Fragment>`
+- **`react/jsx-key`** - Require `key` prop in lists
+- **`react/jsx-no-target-blank`** - Prevent unsafe `target="_blank"`
+- **`react/self-closing-comp`** - Require self-closing tags when appropriate
+
+```jsx
+// ✅ Good
+<>
+  <MyComponent enabled />
+  {items.map(item => <Item key={item.id} {...item} />)}
+  <Link href="/docs" target="_blank" rel="noopener noreferrer">Docs</Link>
+  <EmptyComponent />
+</>
+
+// ❌ Bad
+<React.Fragment>
+  <MyComponent enabled={true} />
+  {items.map(item => <Item {...item} />)} {/* Missing key */}
+  <Link href="/docs" target="_blank">Docs</Link> {/* Unsafe */}
+  <EmptyComponent></EmptyComponent>
+</React.Fragment>
+```
+
+### Component Best Practices
+
+- **`react/no-array-index-key`** - Avoid array index as key
+- **`react/no-children-prop`** - Use children as JSX, not prop
+- **`react/no-danger`** - Warn on `dangerouslySetInnerHTML`
+- **`react/no-unstable-nested-components`** - No component definitions in render
+- **`react/void-dom-elements-no-children`** - No children on void elements
+
+```jsx
+// ✅ Good
+const Parent = () => {
+  return items.map((item) => <Item key={item.id}>{item.name}</Item>);
+};
+
+// ❌ Bad
+const Parent = () => {
+  // ❌ Component defined inside render
+  const Child = () => <div>Bad</div>;
+
+  return (
+    <>
+      {items.map((item, i) => (
+        <Item key={i}>{item.name}</Item>
+      ))}{" "}
+      {/* ❌ Index as key */}
+      <img>child content</img> {/* ❌ Void element with children */}
+    </>
+  );
+};
+```
+
+### State Management
+
+- **`react/no-direct-mutation-state`** - No direct state mutation
+- **`react/no-unused-state`** - Detect unused state
+- **`react/prefer-stateless-function`** - Prefer functions over classes when possible
+
+### TypeScript Integration
+
+When both React and TypeScript are enabled:
+
+```js
+export default eslintConfig({
+  react: true,
+  typescript: true, // Enabled by default
+});
+```
+
+**Additional rules:**
+
+- `react/prop-types` disabled (TypeScript handles it)
+- Type-safe prop definitions
+- JSX type checking
+
+[→ See TypeScript Configuration](../typescript/README.md)
+
+## Next.js-Specific Rules
+
+When `framework: "next"` is set, additional Next.js rules are included:
+
+- Google Font optimization
+- No `<img>` element (use `next/image`)
+- No `<head>` element (use `next/head`)
+- No HTML link for pages
+- Script optimization
+- And more...
+
+[→ Learn more about Next.js plugin](../nextjs/README.md)
+
+## Common Patterns
+
+### Next.js + TypeScript
+
+```js
+export default eslintConfig({
+  typescript: "./tsconfig.json",
+  react: {
+    framework: "next",
+    reactCompiler: true,
+  },
+});
+```
+
+### Vite + TypeScript
+
+```js
+export default eslintConfig({
+  typescript: true,
+  react: {
+    framework: "vite",
+    reactRefresh: true,
+  },
+});
+```
+
+### Library Development
+
+```js
+export default eslintConfig({
+  typescript: true,
+  react: true,
+  jsdoc: { requireJsdoc: true },
+  functionStyle: "arrow",
+});
+```
+
+## Customization
+
+Override specific React rules:
+
+```js
+export default eslintConfig({
+  react: true,
+  rules: {
+    // Allow array index as key in some cases
+    "react/no-array-index-key": "off",
+
+    // Disable compiler rules
+    "react-hooks/react-compiler": "off",
+
+    // Stricter hook dependencies
+    "react-hooks/exhaustive-deps": "error",
+  },
+});
+```
+
+## Troubleshooting
+
+### React version detection fails
+
+Ensure React is installed in your project. The config auto-detects the version.
+
+### Fast Refresh not working
+
+1. Check that `reactRefresh: true` is set for Vite
+2. Ensure components follow Fast Refresh patterns
+3. Review warnings from `eslint-plugin-react-refresh`
+
+## Related Configurations
+
+- [TypeScript](../typescript/README.md) - TypeScript configuration
+- [Next.js Plugin](../nextjs/README.md) - Next.js-specific rules
+- [Testing](../testing/README.md) - Test React components
+
+## Learn More
+
+- [React ESLint Plugin](https://github.com/jsx-eslint/eslint-plugin-react)
+- [React Hooks ESLint Plugin](https://www.npmjs.com/package/eslint-plugin-react-hooks)
+- [React Refresh Plugin](https://github.com/ArnaudBarre/eslint-plugin-react-refresh)
+- [React Compiler](https://react.dev/learn/react-compiler)
+- [Main README](../../../README.md)

package/src/eslint/react/config.ts

@@ -0,0 +1,65 @@
+import react from "eslint-plugin-react";
+import pluginReactHooks from "eslint-plugin-react-hooks";
+import globals from "globals";
+
+import type {
+  EslintConfigObject,
+  EslintRuleConfig,
+  FunctionStyle,
+} from "../types.js";
+
+import { configNames } from "../constants.js";
+import { reactRules } from "./rules.js";
+
+/**
+ * Generates ESLint configuration for React.
+ *
+ * @param options - Configuration options
+ * @param options.functionStyle - Controls how functions (components) should be written. Can be:
+ *   - "off": Disables function style enforcement
+ *   - "arrow": Enforces arrow function expressions
+ *   - "declaration": Enforces function declarations
+ *   - "expression": Enforces function expressions
+ * @param options.reactCompiler - Whether to use the React compiler rules from `eslint-plugin-react-hooks`
+ * @param options.typescript - Whether TypeScript is being used in the project. When true, some rules are adjusted to be more TypeScript-friendly
+ * @param options.customRules - Optional object containing custom rules to override or add to the React configuration
+ * @returns An ESLint configuration object for React.
+ */
+export const reactEslintConfig = ({
+  customRules,
+  functionStyle,
+  reactCompiler,
+  typescript,
+}: {
+  customRules?: Record<string, EslintRuleConfig>;
+  functionStyle: "off" | FunctionStyle;
+  reactCompiler: boolean;
+  typescript: boolean;
+}): EslintConfigObject => {
+  return {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+    },
+    name: configNames.react,
+    plugins: {
+      react,
+      "react-hooks": pluginReactHooks,
+    },
+    rules: {
+      ...reactRules({ functionStyle, reactCompiler, typescript }),
+      ...(customRules ?? {}),
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+  };
+};

package/src/eslint/react/rules.ts

@@ -0,0 +1,188 @@
+import type { FunctionStyle } from "../types.js";
+import type { ReactFunctionDefinitions, ReactRules } from "./types.js";
+
+/**
+ * Generates ESLint rules configuration for React and React Hooks.
+ * Includes settings for function component style enforcement and TypeScript-specific rules.
+ *
+ * @param options - Configuration options
+ * @param options.functionStyle - The preferred style for React function components: 'arrow' for arrow functions, 'declaration' for function declarations, 'expression' for function expressions, or 'off' to disable style enforcement
+ * @param options.reactCompiler - Whether to use the React compiler rules from `eslint-plugin-react-hooks`
+ * @param options.typescript - Whether TypeScript-specific React rules should be enabled
+ * @returns Configuration object containing ESLint rules for React and React Hooks
+ */
+export const reactRules = ({
+  functionStyle,
+  reactCompiler,
+  typescript,
+}: {
+  functionStyle: "off" | FunctionStyle;
+  reactCompiler: boolean;
+  typescript: boolean;
+}): ReactRules => {
+  const functionStyleMap: Record<FunctionStyle, ReactFunctionDefinitions> = {
+    arrow: "arrow-function",
+    declaration: "function-declaration",
+    expression: "function-expression",
+  };
+
+  // TODO: split out new rules into a `react-compiler` option
+
+  return {
+    /**
+     * Disabled in favor of TypeScript for type checking
+     */
+    ...(typescript ? {} : { "react/prop-types": "warn" }),
+    /**
+     * Core React Hooks rules
+     */
+    "react-hooks/exhaustive-deps": "warn",
+    "react-hooks/rules-of-hooks": "warn",
+    /**
+     * React compiler rules
+     */
+    ...(reactCompiler ?
+      {
+        /**
+         * Does not seem to be working, and overlaps with static-components
+         */
+        // "react-hooks/component-hook-factories": "warn",
+
+        /**
+         * seems unecessary unless you're rolling your own React setup, users can always enable
+         */
+        // "react-hooks/config": "warn",
+
+        "react-hooks/error-boundaries": "warn",
+        "react-hooks/globals": "warn",
+        "react-hooks/immutability": "warn",
+        "react-hooks/incompatible-library": "warn",
+        "react-hooks/preserve-manual-memoization": "warn",
+        "react-hooks/purity": "warn",
+        "react-hooks/refs": "warn",
+        "react-hooks/set-state-in-effect": "warn",
+        "react-hooks/set-state-in-render": "warn",
+
+        /**
+         * overlaps with react/no-unstable-nested-components
+         */
+        // "react-hooks/static-components": "warn",
+
+        "react-hooks/unsupported-syntax": "warn",
+        "react-hooks/use-memo": "warn",
+      }
+    : {}),
+    /**
+     * Require an explicit type when using button elements.
+     *
+     * 🚫 Not fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/button-has-type.md
+     */
+    "react/button-has-type": "warn",
+    "react/destructuring-assignment": ["warn", "always"],
+    "react/display-name": "warn",
+    /**
+     * Require consistent function type for function components.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/HEAD/docs/rules/function-component-definition.md
+     */
+    "react/function-component-definition":
+      functionStyle === "off" ? "off" : (
+        [
+          "warn",
+          {
+            namedComponents: functionStyleMap[functionStyle],
+            unnamedComponents:
+              functionStyle === "arrow" ? "arrow-function" : (
+                "function-expression"
+              ),
+          },
+        ]
+      ),
+    /**
+     * Require consistent boolean attributes notation in JSX.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-boolean-value.md
+     */
+    "react/jsx-boolean-value": "warn",
+    /**
+     * Disallow unnecessary curly braces in JSX props and children.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-curly-brace-presence.md
+     */
+    "react/jsx-curly-brace-presence": "warn",
+    /**
+     * Require using shorthand form for React fragments, unless required.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-fragments.md
+     */
+    "react/jsx-fragments": "warn",
+    "react/jsx-key": "warn",
+    "react/jsx-no-comment-textnodes": "warn",
+    "react/jsx-no-duplicate-props": "warn",
+    /**
+     * Prevent problematic leaked values from being rendered.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md
+     */
+    "react/jsx-no-leaked-render": "warn",
+    /**
+     * Prevents usage of unsafe `target='_blank'`.
+     *
+     * This rule is a part of `react/recommended`, but we've modified it to
+     * allow referrer.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-target-blank.md
+     */
+    "react/jsx-no-target-blank": [
+      "warn",
+      {
+        allowReferrer: true,
+      },
+    ],
+    "react/jsx-no-undef": "warn",
+    /**
+     * Disallow empty React fragments.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-useless-fragment.md
+     */
+    "react/jsx-no-useless-fragment": ["warn", { allowExpressions: true }],
+    /**
+     * Require the use of PascalCase for user-defined JSX components.
+     *
+     * 🚫 Not fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md
+     */
+    "react/jsx-pascal-case": "warn",
+    "react/jsx-uses-react": "warn",
+    "react/jsx-uses-vars": "warn",
+    /**
+     * Disallow usage of Array index in keys.
+     *
+     * � Not fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/no-array-index-key.md
+     */
+    "react/no-array-index-key": "warn",
+    "react/no-children-prop": "warn",
+    "react/no-danger-with-children": "warn",
+    "react/no-deprecated": "warn",
+    "react/no-direct-mutation-state": "warn",
+    "react/no-find-dom-node": "warn",
+    "react/no-is-mounted": "warn",
+    "react/no-render-return-value": "warn",
+    "react/no-string-refs": "warn",
+    "react/no-unescaped-entities": "warn",
+    "react/no-unknown-property": "warn",
+    "react/no-unsafe": "warn",
+    /**
+     * Disallow creating unstable components inside components.
+     *
+     * 🚫 Not fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/no-unstable-nested-components.md
+     */
+    "react/no-unstable-nested-components": "warn",
+    "react/require-render-return": "warn",
+    /**
+     * Disallow closing tags for components without children.
+     *
+     * 🔧 Fixable - https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/self-closing-comp.md
+     */
+    "react/self-closing-comp": "warn",
+  };
+};

package/src/eslint/react/types.ts

@@ -0,0 +1,26 @@
+import type { EslintRuleConfig } from "../types.js";
+
+export type ReactFunctionDefinitions =
+  | "arrow-function"
+  | "function-declaration"
+  | "function-expression";
+
+export type ReactRules = Record<
+  `${"react" | "react-hooks"}/${string}`,
+  EslintRuleConfig
+> & {
+  "react/destructuring-assignment"?: EslintRuleConfig<
+    "always" | "never",
+    {
+      destructureInSignature?: "always" | "ignore";
+      ignoreClassFields?: boolean;
+    }
+  >;
+  "react/function-component-definition"?: EslintRuleConfig<{
+    namedComponents?: ReactFunctionDefinitions | ReactFunctionDefinitions[];
+    unnamedComponents?:
+      | "arrow-function"
+      | "function-expression"
+      | ("arrow-function" | "function-expression")[];
+  }>;
+};