feat: react component template and create-component script (#139)

georgewrmarshall · brianacnguyen · web-flow · commit 05f9df94d8ae · 2024-12-02T16:50:05.000-08:00
## **Description** This PR implements a reusable react component template system with an accompanying CLI tool for the MetaMask Design System. It addresses two main improvements: 1. Creates a standardized react component template structure 2. Adds the create-component script 3. Adds comprehensive documentation for the component creation process Key changes: - Established a consistent react component template with required files (index.ts, ComponentName.tsx, etc.) - Implemented CLI tool to automate component creation with proper naming - Created detailed documentation in `docs/create-component.md` ## **Related issues** Fixes: #13 #36 ## **Manual testing steps** 1. Read the documentation at `docs/create-component.md` for full usage details 2. Run the example command: ```bash yarn create-component:react --name TestComponent --description "Test component" ``` 3. Verify that the following files are created as documented: ``` testcomponent/ ├── TestComponent.constants.ts ├── TestComponent.stories.tsx ├── TestComponent.test.tsx ├── TestComponent.tsx ├── TestComponent.types.ts ├── README.mdx └── index.ts ``` 4. Verify all template content is properly updated with the new component name 5. Verify the component is created in the correct location under `packages/design-system-react/src/components` ## **Documentation Updates** Added new documentation that covers: - Script usage and required arguments - Generated file structure and descriptions - Best practices for component creation - Example usage with real-world cases - File-by-file explanation of the template structure See `docs/create-component.md` for the complete documentation. ## **Screenshots/Recordings** ### **Before** Error when running create-component script: ``` Error: ENOENT: no such file or directory, scandir '.../templates/ComponentName' ``` ### **After** 1. Provides clear documentation for usage. 2. Initially fails to create `Button` because it already exists 3. Successfully creates `Icon` with standardized structure https://github.com/user-attachments/assets/02fa403b-6c2a-4ad9-866d-76ed13426b42 ## **Pre-merge author checklist** - [x] I've followed MetaMask Contributor Docs - [x] I've completed the PR template - [x] I've included error handling and validation - [x] I've documented the code changes and component structure - [x] I've ensured the template follows the specified structure from issue #13 - [x] I've added comprehensive documentation in `docs/create-component.md` --------- Co-authored-by: Brian August Nguyen <brianacnguyen@gmail.com>
diff --git a/docs/create-component.md b/docs/create-component.md
@@ -0,0 +1,72 @@
+# Create Component Script
+
+The create-component script is a utility for generating new React components(React Native coming soon!) in the MetaMask Design System with consistent structure and boilerplate code.
+
+## Usage
+
+From the root directory, run:
+
+```bash
+yarn create-component:react --name ComponentName --description "Brief description of the component"
+```
+
+### Required Arguments
+
+- `--name`: The name of the component in PascalCase (e.g., Button, TextField, Modal)
+- `--description`: A brief description of the component's purpose in quotes
+
+### Example
+
+```bash
+yarn create-component:react --name Button --description "A reusable button component that supports different variants and sizes"
+```
+
+## Generated Files
+
+The script will create a new directory under `packages/design-system-react/src/components` with the following structure:
+
+```
+button/
+├── Button.constants.ts
+├── Button.stories.tsx
+├── Button.test.tsx
+├── Button.tsx
+├── Button.types.ts
+├── README.mdx
+└── index.ts
+```
+
+### File Descriptions
+
+- `ComponentName.constants.ts`: Constants and classname mappings
+- `ComponentName.stories.tsx`: Storybook stories for component documentation
+- `ComponentName.test.tsx`: Jest test suite
+- `ComponentName.tsx`: Main component implementation
+- `ComponentName.types.ts`: TypeScript interfaces and types
+- `README.mdx`: Component documentation and usage examples
+- `index.ts`: Exports for the component
+
+The script will also automatically:
+
+1. Create the component directory with all necessary files
+2. Update `src/components/index.ts` to export the new component
+3. Add proper TypeScript types and basic tests
+4. Set up Storybook documentation
+
+## Best Practices
+
+1. Use PascalCase for the component name
+2. Provide a clear, concise description
+3. After generating the component:
+   - Add proper styling using Tailwind classes
+   - Implement comprehensive tests
+   - Add meaningful Storybook stories
+   - Update the README.mdx with usage examples
+
+## Example Component Creation
+
+```bash
+yarn create-component:react --name Button --description "A reusable button component that supports different variants and sizes"
+```
+
+This will create a new TextField component with all the necessary files and boilerplate code.
diff --git a/package.json b/package.json
@@ -18,6 +18,7 @@
     "build:types": "tsc --build tsconfig.build.json --verbose",
     "changelog:update": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:update",
     "changelog:validate": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:validate",
+    "create-component:react": "yarn workspace @metamask/design-system-react create-component",
     "create-package": "ts-node scripts/create-package",
     "lint": "yarn lint:eslint && yarn lint:misc --check && yarn constraints && yarn lint:dependencies",
     "lint:dependencies": "depcheck && yarn dedupe --check",
diff --git a/packages/design-system-react/jest.config.js b/packages/design-system-react/jest.config.js
@@ -15,7 +15,14 @@ module.exports = merge(baseConfig, {
   displayName,
 
   // Add coverage ignore patterns
-  coveragePathIgnorePatterns: ['index.ts', '.d.ts'],
+  coveragePathIgnorePatterns: [
+    'index.ts',
+    '.d.ts',
+    'scripts/create-component/ComponentName/',
+  ],
+
+  // Add test match ignore patterns
+  testPathIgnorePatterns: ['scripts/create-component/ComponentName/'],
 
   // An object that configures minimum threshold enforcement for coverage results
   coverageThreshold: {
diff --git a/packages/design-system-react/package.json b/packages/design-system-react/package.json
@@ -38,6 +38,7 @@
     "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/design-system-react",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/design-system-react",
+    "create-component": "ts-node scripts/create-component",
     "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
@@ -58,12 +59,14 @@
     "@testing-library/react": "^16.0.1",
     "@ts-bridge/cli": "^0.5.1",
     "@types/jest": "^27.4.1",
+    "@types/node": "^16.18.54",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "deepmerge": "^4.2.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.1",
     "typescript": "~5.2.2"
   },
   "peerDependencies": {
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.constants.ts b/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.constants.ts
@@ -0,0 +1,2 @@
+// Remove this file if it's not needed
+export const COMPONENT_NAME_CLASSMAP = {};
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.stories.tsx b/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.stories.tsx
@@ -0,0 +1,25 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ComponentName } from './ComponentName';
+import README from './README.mdx';
+
+const meta: Meta<typeof ComponentName> = {
+  title: 'Components/ComponentName',
+  component: ComponentName,
+  parameters: {
+    docs: {
+      page: README,
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ComponentName>;
+
+export const Default: Story = {
+  args: {
+    children: 'Default ComponentName',
+  },
+};
+
+// You can add more stories as needed
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.test.tsx b/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.test.tsx
@@ -0,0 +1,21 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { ComponentName } from './ComponentName';
+import '@testing-library/jest-dom';
+
+describe('ComponentName Component', () => {
+  it('renders children correctly', () => {
+    render(<ComponentName>Hello, World!</ComponentName>);
+    expect(screen.getByText('Hello, World!')).toBeInTheDocument();
+  });
+
+  it('applies the correct classes', () => {
+    render(
+      <ComponentName className="custom-class">Styled Content</ComponentName>,
+    );
+    expect(screen.getByText('Styled Content')).toHaveClass('custom-class');
+    // Add more class-related tests as needed
+  });
+
+  // Add more tests as needed
+});
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.tsx b/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.tsx
@@ -0,0 +1,12 @@
+import React from 'react';
+import { twMerge } from '../../utils/tw-merge';
+import { ComponentNameProps } from './ComponentName.types';
+
+export const ComponentName: React.FC<ComponentNameProps> = ({
+  children,
+  className,
+}) => {
+  const mergedClassName = twMerge('your-default-classes', className);
+
+  return <div className={mergedClassName}>{children}</div>;
+};
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.types.ts b/packages/design-system-react/scripts/create-component/ComponentName/ComponentName.types.ts
@@ -0,0 +1,10 @@
+export type ComponentNameProps = {
+  /**
+   * The content to be rendered within the ComponentName.
+   */
+  children: React.ReactNode;
+  /**
+   * Additional CSS classes to be applied to the ComponentName component.
+   */
+  className?: string;
+};
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/README.mdx b/packages/design-system-react/scripts/create-component/ComponentName/README.mdx
@@ -0,0 +1,27 @@
+import { Controls, Canvas } from '@storybook/blocks';
+
+import * as ComponentNameStories from './ComponentName.stories';
+
+# ComponentName
+
+ComponentName is used to render standardized elements within an interface.
+
+<Canvas of={ComponentNameStories.Default} />
+
+## Props
+
+### Children
+
+The content of the `ComponentName` component.
+
+### Class Name
+
+Adds an additional class to the `ComponentName` component.
+
+### Component API
+
+<Controls of={ComponentNameStories.Default} />
+
+### References
+
+[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)
diff --git a/packages/design-system-react/scripts/create-component/ComponentName/index.ts b/packages/design-system-react/scripts/create-component/ComponentName/index.ts
@@ -0,0 +1,2 @@
+export { ComponentName } from './ComponentName';
+export type { ComponentNameProps } from './ComponentName.types';
diff --git a/packages/design-system-react/scripts/create-component/create-component.test.ts b/packages/design-system-react/scripts/create-component/create-component.test.ts
@@ -0,0 +1,154 @@
+import { promises as fs } from 'fs';
+
+import { createComponent, parseArgs } from './create-component';
+
+// Mock the fs promises module
+jest.mock('fs', () => ({
+  promises: {
+    access: jest.fn(),
+    mkdir: jest.fn(),
+    readdir: jest.fn(),
+    readFile: jest.fn(),
+    writeFile: jest.fn(),
+    appendFile: jest.fn(),
+  },
+}));
+
+describe('create-component', () => {
+  beforeEach(() => {
+    // Clear all mocks
+    jest.clearAllMocks();
+
+    // Mock successful file reading
+    (fs.readdir as jest.Mock).mockResolvedValue([
+      'ComponentName.tsx',
+      'ComponentName.types.ts',
+      'ComponentName.test.tsx',
+      'ComponentName.stories.tsx',
+      'ComponentName.constants.ts',
+      'README.mdx',
+    ]);
+
+    (fs.readFile as jest.Mock).mockResolvedValue(
+      'ComponentName template content',
+    );
+  });
+
+  describe('parseArgs', () => {
+    it('should parse valid arguments correctly', () => {
+      const args = [
+        '--name',
+        'Button',
+        '--description',
+        'A reusable button component',
+      ];
+      const result = parseArgs(args);
+      expect(result).toStrictEqual({
+        name: 'Button',
+        description: 'A reusable button component',
+      });
+    });
+
+    it('should throw error if name argument is missing', () => {
+      const args = ['--description', 'A reusable button component'];
+      expect(() => parseArgs(args)).toThrow(/Usage: yarn create-component/u);
+    });
+
+    it('should throw error if description argument is missing', () => {
+      const args = ['--name', 'Button'];
+      expect(() => parseArgs(args)).toThrow(/Usage: yarn create-component/u);
+    });
+  });
+
+  describe('createComponent', () => {
+    it('should create a new component successfully', async () => {
+      // Mock fs.access to throw ENOENT (simulating directory doesn't exist)
+      (fs.access as jest.Mock).mockRejectedValue({
+        code: 'ENOENT',
+      });
+
+      await createComponent({
+        name: 'Button',
+        description: 'A reusable button component',
+      });
+
+      // Verify directory was created
+      expect(fs.mkdir).toHaveBeenCalledWith(
+        expect.stringContaining('/src/components/button'),
+        { recursive: true },
+      );
+
+      // Verify files were written
+      expect(fs.writeFile).toHaveBeenCalledTimes(6); // One for each template file
+
+      // Verify index.ts was updated with correct exports
+      const appendFileCalls = (fs.appendFile as jest.Mock).mock.calls;
+      expect(appendFileCalls).toHaveLength(1);
+      expect(appendFileCalls[0][0]).toMatch(/\/src\/components\/index\.ts$/u);
+      expect(appendFileCalls[0][1]).toContain(
+        "export { Button } from './button'",
+      );
+      expect(appendFileCalls[0][1]).toContain(
+        "export type { ButtonProps } from './button'",
+      );
+    });
+
+    it('should throw error if component already exists', async () => {
+      // Mock fs.access to succeed (simulating directory exists)
+      (fs.access as jest.Mock).mockResolvedValue(undefined);
+
+      await expect(
+        createComponent({
+          name: 'Button',
+          description: 'A reusable button component',
+        }),
+      ).rejects.toThrow('Component "Button" already exists.');
+    });
+
+    it('should replace all placeholder instances in template files', async () => {
+      // Mock fs.access to throw ENOENT
+      (fs.access as jest.Mock).mockRejectedValue({
+        code: 'ENOENT',
+      });
+
+      // Mock template file content with placeholders
+      (fs.readFile as jest.Mock).mockResolvedValue(
+        'export const ComponentName: React.FC<ComponentNameProps> = () => {};',
+      );
+
+      await createComponent({
+        name: 'Button',
+        description: 'A reusable button component',
+      });
+
+      // Verify placeholder replacements in all written files
+      const writeFileCalls = (fs.writeFile as jest.Mock).mock.calls;
+      const replacedContent =
+        'export const Button: React.FC<ButtonProps> = () => {};';
+
+      // Check that at least one file contains our expected content
+      const hasCorrectContent = writeFileCalls.some(
+        (call: [string, string, ...unknown[]]) => call[1] === replacedContent,
+      );
+      expect(hasCorrectContent).toBe(true);
+    });
+
+    it('should convert component folder name to lowercase', async () => {
+      // Mock fs.access to throw ENOENT
+      (fs.access as jest.Mock).mockRejectedValue({
+        code: 'ENOENT',
+      });
+
+      await createComponent({
+        name: 'MyButton',
+        description: 'A reusable button component',
+      });
+
+      // Verify directory was created with lowercase name
+      expect(fs.mkdir).toHaveBeenCalledWith(
+        expect.stringContaining('/src/components/mybutton'),
+        { recursive: true },
+      );
+    });
+  });
+});
diff --git a/packages/design-system-react/scripts/create-component/create-component.ts b/packages/design-system-react/scripts/create-component/create-component.ts
diff --git a/packages/design-system-react/scripts/create-component/index.ts b/packages/design-system-react/scripts/create-component/index.ts
diff --git a/packages/design-system-react/tsconfig.json b/packages/design-system-react/tsconfig.json
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+// Remove this file if it's not needed`
	`2`	`+export const COMPONENT_NAME_CLASSMAP = {};`