js-style-kit 0.6.1 → 0.7.0

package/src/eslint/react-refresh/config.ts

@@ -0,0 +1,28 @@
+import reactRefresh from "eslint-plugin-react-refresh";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+
+import { configNames } from "../constants.js";
+import { reactRefreshRules } from "./rules.js";
+
+/**
+ * Generates ESLint configuration for React Refresh.
+ *
+ * This plugin validates that components can safely be updated with Fast Refresh.
+ * It enforces that components are structured in a way that integrations like
+ * react-refresh expect.
+ *
+ * @param customRules - Optional object containing custom rules to override or add to the React Refresh configuration.
+ * @returns An ESLint configuration object for React Refresh.
+ */
+export const reactRefreshEslintConfig = (
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => {
+  return {
+    name: configNames.reactRefresh,
+    plugins: {
+      "react-refresh": reactRefresh,
+    },
+    rules: customRules ?? reactRefreshRules,
+  };
+};

package/src/eslint/react-refresh/rules.ts

@@ -0,0 +1,48 @@
+import type { EslintRuleConfig } from "../types.js";
+
+export type ReactRefreshRules = Record<string, EslintRuleConfig> & {
+  "react-refresh/only-export-components"?: EslintRuleConfig<{
+    /**
+     * Don't warn when a constant (string, number, boolean, templateLiteral)
+     * is exported aside one or more components.
+     */
+    allowConstantExport?: boolean;
+    /**
+     * If you use a framework that handles HMR of some specific exports,
+     * you can use this option to avoid warning for them.
+     */
+    allowExportNames?: string[];
+    /**
+     * If you're using JSX inside .js files, you can enable this option.
+     * To reduce false positives, only files importing 'react' are checked.
+     */
+    checkJS?: boolean;
+    /**
+     * If you're exporting a component wrapped in a custom HOC,
+     * you can use this option to avoid false positives.
+     */
+    customHOCs?: string[];
+  }>;
+};
+
+/**
+ * Generates ESLint rules configuration for React Refresh.
+ *
+ * This plugin validates that components can safely be updated with Fast Refresh.
+ *
+ * @returns Configuration object containing ESLint rules for React Refresh
+ */
+export const reactRefreshRules: ReactRefreshRules = {
+  /**
+   * Validate that your components can safely be updated with Fast Refresh.
+   *
+   * This rule enforces that components are structured in a way that integrations
+   * like react-refresh expect.
+   *
+   * 🚫 Not fixable - https://github.com/ArnaudBarre/eslint-plugin-react-refresh
+   */
+  "react-refresh/only-export-components": [
+    "warn",
+    { allowConstantExport: true },
+  ],
+};

package/src/eslint/storybook/README.md

@@ -0,0 +1,424 @@
+# Storybook Configuration
+
+ESLint rules for Storybook stories and configuration files.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+Storybook configuration is **disabled by default** and provides:
+
+- Story file best practices
+- CSF (Component Story Format) validation
+- Story naming and structure rules
+- Testing library integration
+- Storybook addon validation
+
+## Quick Start
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  storybook: true, // Enable Storybook rules
+});
+```
+
+## File Scope
+
+Storybook rules apply to:
+
+- **Story files**: `**/*.stories.{ts,tsx,js,jsx,mjs,cjs}` and `**/*.story.{ts,tsx,js,jsx,mjs,cjs}`
+- **Config files**: `.storybook/main.{js,cjs,mjs,ts}`
+
+## Key Features
+
+### CSF (Component Story Format)
+
+Ensures proper CSF structure:
+
+```tsx
+// ✅ Good - proper CSF format
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./Button";
+
+const meta = {
+  title: "Components/Button",
+  component: Button,
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: {
+    label: "Click me",
+    variant: "primary",
+  },
+};
+
+// ❌ Bad - missing default export
+export const Primary: Story = {
+  /* ... */
+};
+
+// ❌ Bad - missing component in meta
+export default {
+  title: "Components/Button",
+};
+```
+
+**Rules:**
+
+- `storybook/default-exports` - Requires default export with meta
+- `storybook/csf-component` - Ensures `component` is defined in meta
+
+### Story Naming
+
+Enforces consistent story naming:
+
+```tsx
+// ✅ Good - PascalCase story names
+export const Primary: Story = {
+  /* ... */
+};
+export const Secondary: Story = {
+  /* ... */
+};
+export const WithIcon: Story = {
+  /* ... */
+};
+
+// ❌ Bad - incorrect casing
+export const primary: Story = {
+  /* ... */
+};
+export const with_icon: Story = {
+  /* ... */
+};
+
+// ❌ Bad - redundant story name
+export const ButtonPrimary: Story = {
+  name: "Primary", // Redundant - matches export name
+};
+```
+
+**Rules:**
+
+- `storybook/prefer-pascal-case` - PascalCase for story names
+- `storybook/no-redundant-story-name` - No redundant `name` property
+
+### Story Structure
+
+Ensures clean story organization:
+
+```tsx
+// ✅ Good - meta properties as properties
+const meta = {
+  title: "Components/Button",
+  component: Button,
+  tags: ["autodocs"],
+} satisfies Meta<typeof Button>;
+
+// ✅ Good - hierarchy separator
+const meta = {
+  title: "Design System/Components/Button", // Uses /
+} satisfies Meta<typeof Button>;
+
+// ❌ Bad - hierarchy with pipe
+const meta = {
+  title: "Design System | Components | Button", // Don't use |
+} satisfies Meta<typeof Button>;
+```
+
+**Rules:**
+
+- `storybook/meta-inline-properties` - Inline meta properties (no spread)
+- `storybook/hierarchy-separator` - Use `/` for hierarchy, not `|`
+- `storybook/story-exports` - All exports must be stories (except default)
+
+### Testing Integration
+
+When writing play functions for interaction tests:
+
+```tsx
+// ✅ Good - proper test setup
+export const Login: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await userEvent.type(canvas.getByRole("textbox"), "user@example.com");
+    await userEvent.click(canvas.getByRole("button"));
+
+    await expect(canvas.getByText("Welcome")).toBeInTheDocument();
+  },
+};
+
+// ❌ Bad - missing context parameter
+export const Login: Story = {
+  play: async () => {
+    // Missing context - can't access canvas
+    await userEvent.click(/* ??? */);
+  },
+};
+
+// ❌ Bad - not awaiting interactions
+export const Login: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    userEvent.click(canvas.getByRole("button")); // Missing await
+  },
+};
+
+// ❌ Bad - using regular testing-library
+import { screen } from "@testing-library/react"; // Don't import from here
+
+export const Login: Story = {
+  play: async () => {
+    screen.getByRole("button"); // Use canvas from context instead
+  },
+};
+```
+
+**Rules:**
+
+- `storybook/context-in-play-function` - Requires context parameter in play functions
+- `storybook/await-interactions` - Ensures interactions are awaited
+- `storybook/use-storybook-expect` - Use `@storybook/test` expect
+- `storybook/use-storybook-testing-library` - Use `@storybook/test` for queries
+
+### Disabled Rules in Stories
+
+Certain rules are automatically disabled in story files:
+
+```tsx
+// ✅ OK in story files - anonymous default export
+export default {
+  title: "Components/Button",
+  component: Button,
+};
+
+// ✅ OK in story files - rules of hooks don't apply
+export const WithHook: Story = {
+  render: () => {
+    const [count, setCount] = useState(0); // OK in render function
+    return <Button onClick={() => setCount(count + 1)}>{count}</Button>;
+  },
+};
+```
+
+**Auto-disabled:**
+
+- `import/no-anonymous-default-export` - Story meta needs anonymous default
+- `react-hooks/rules-of-hooks` - Hooks in render functions are OK
+
+### Storybook Configuration
+
+Additional rules for `.storybook/main.js` configuration:
+
+```js
+// .storybook/main.ts
+const config = {
+  stories: ["../src/**/*.stories.@(ts|tsx)"],
+  addons: ["@storybook/addon-essentials", "@storybook/addon-interactions"],
+};
+
+export default config;
+```
+
+**Rules:**
+
+- `storybook/no-uninstalled-addons` - Ensures addons are installed in `package.json`
+
+## Examples
+
+### Basic Component Story
+
+```tsx
+// Button.stories.tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./Button";
+
+const meta = {
+  title: "UI/Button",
+  component: Button,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["primary", "secondary", "outline"],
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: {
+    children: "Button",
+    variant: "primary",
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: "Button",
+    variant: "secondary",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    children: "Button",
+    disabled: true,
+  },
+};
+```
+
+### Story with Interactions
+
+```tsx
+// LoginForm.stories.tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, userEvent, within } from "@storybook/test";
+import { LoginForm } from "./LoginForm";
+
+const meta = {
+  title: "Forms/LoginForm",
+  component: LoginForm,
+} satisfies Meta<typeof LoginForm>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const FilledForm: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await userEvent.type(canvas.getByLabelText("Email"), "user@example.com");
+    await userEvent.type(canvas.getByLabelText("Password"), "password123");
+  },
+};
+
+export const SubmitSuccess: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await userEvent.type(canvas.getByLabelText("Email"), "user@example.com");
+    await userEvent.type(canvas.getByLabelText("Password"), "password123");
+    await userEvent.click(canvas.getByRole("button", { name: /submit/i }));
+
+    await expect(canvas.getByText("Success!")).toBeInTheDocument();
+  },
+};
+```
+
+### Multiple Components
+
+```tsx
+// Card.stories.tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "./Card";
+import { CardHeader } from "./CardHeader";
+import { CardBody } from "./CardBody";
+
+const meta = {
+  title: "Components/Card",
+  component: Card,
+} satisfies Meta<typeof Card>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Basic: Story = {
+  render: () => (
+    <Card>
+      <CardHeader>Title</CardHeader>
+      <CardBody>Content goes here</CardBody>
+    </Card>
+  ),
+};
+```
+
+## Customization
+
+### Disable Specific Rules
+
+```js
+export default eslintConfig({
+  storybook: true,
+  rules: {
+    // Allow non-PascalCase story names
+    "storybook/prefer-pascal-case": "off",
+
+    // Allow redundant story names
+    "storybook/no-redundant-story-name": "off",
+  },
+});
+```
+
+### Custom Story Patterns
+
+```js
+export default eslintConfig({
+  storybook: true,
+  overrides: [
+    {
+      // Apply to custom story file pattern
+      files: ["**/*.stories.mdx"],
+      rules: {
+        // Custom rules for MDX stories
+      },
+    },
+  ],
+});
+```
+
+## Common Patterns
+
+### Storybook + React + TypeScript
+
+```js
+export default eslintConfig({
+  typescript: true,
+  react: true,
+  storybook: true,
+});
+```
+
+### Storybook with Testing
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, userEvent, within } from "@storybook/test";
+
+// Story with comprehensive testing
+export const InteractiveTest: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Test user interactions
+    await userEvent.click(canvas.getByRole("button"));
+
+    // Verify results
+    await expect(canvas.getByText("Clicked")).toBeInTheDocument();
+  },
+};
+```
+
+## Related Configurations
+
+- [React](../react/README.md) - React configuration
+- [TypeScript](../typescript/README.md) - TypeScript configuration
+- [Testing](../testing/README.md) - Test configuration
+
+## Learn More
+
+- [eslint-plugin-storybook](https://github.com/storybookjs/eslint-plugin-storybook)
+- [Storybook](https://storybook.js.org/)
+- [Component Story Format (CSF)](https://storybook.js.org/docs/react/api/csf)
+- [Storybook Interactions](https://storybook.js.org/docs/react/writing-tests/interaction-testing)
+- [Main README](../../../README.md)

package/src/eslint/storybook/config.ts

@@ -0,0 +1,57 @@
+import type { ESLint } from "eslint";
+
+import storybookPlugin from "eslint-plugin-storybook";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+
+import { configNames } from "../constants.js";
+
+/**
+ * ESLint configuration for Storybook.
+ * Contains rules for best practices when working with Storybook.
+ *
+ * @param customRules - Optional custom rules to merge into the Storybook config.
+ * @returns Storybook ESLint config array.
+ */
+export const storybookConfig = (
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject[] => [
+  {
+    files: [
+      "**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)",
+      "**/*.story.@(ts|tsx|js|jsx|mjs|cjs)",
+    ],
+    name: configNames.storybook,
+    plugins: {
+      storybook: storybookPlugin as unknown as ESLint.Plugin,
+    },
+    rules: {
+      // Default Storybook rules
+      "import-x/no-anonymous-default-export": "off",
+      "react-hooks/rules-of-hooks": "off",
+      "storybook/await-interactions": "warn",
+      "storybook/context-in-play-function": "warn",
+      "storybook/csf-component": "warn",
+      "storybook/default-exports": "warn",
+      "storybook/hierarchy-separator": "warn",
+      "storybook/meta-inline-properties": "warn",
+      "storybook/no-redundant-story-name": "warn",
+      "storybook/prefer-pascal-case": "warn",
+      "storybook/story-exports": "warn",
+      "storybook/use-storybook-expect": "warn",
+      "storybook/use-storybook-testing-library": "warn",
+      // Merge custom rules
+      ...(customRules ?? {}),
+    },
+  },
+  {
+    files: [".storybook/main.@(js|cjs|mjs|ts)"],
+    name: configNames.storybookConfig,
+    plugins: {
+      storybook: storybookPlugin as unknown as ESLint.Plugin,
+    },
+    rules: {
+      "storybook/no-uninstalled-addons": "warn",
+    },
+  },
+];