# Checklist: Adding a New React Component

## In orchard-suite (shared component)

- [ ] Create directory: `packages/suite-components/src/components/<name>/`
- [ ] Create component file: `<name>.tsx`
  - Uppercase `CLASSNAME` constant
  - `classnames` imported as `cx`
  - `testId` prop with default value
  - JSDoc with `@type`, `@status`, `@tags`
  - Props interface with JSDoc on each prop
- [ ] Create styles: `<name>.scss`
- [ ] Create barrel export: `index.ts`
- [ ] Create tests: `__tests__/<name>.spec.tsx`
  - Use `screen` + React Testing Library
  - `testComponent()` helper for standard tests
  - Test className, testId, user interactions
  - Prefer `getByRole` > `getByText` > `getByTestId`
- [ ] Export from package index: `src/index.ts`
- [ ] Add i18n if needed: `i18n/index.ts`
- [ ] Run `pnpm -F @theorchard/suite-components test:unit`
- [ ] Run `pnpm -F @theorchard/suite-components lint`

### For Complex Components

- [ ] Create `types.ts` for shared types
- [ ] Create `components/` folder for sub-components
- [ ] Create `hooks/` folder for component-specific hooks
- [ ] Create `utils/` folder for component-specific utilities

## In frontend-insights (consuming)

- [ ] Update `@theorchard/suite-components` dependency version
- [ ] Import component: `import { ComponentName } from '@theorchard/suite-components'`
- [ ] Use in page component
- [ ] Write page-level tests

## Component Template

```typescript
import type { FC } from 'react';
import React from 'react';
import cx from 'classnames';

const CLASSNAME = 'MyComponent';

export interface MyComponentProps {
    /** Additional CSS classes */
    className?: string;
    /** Test identifier */
    testId?: string;
    /** Component content */
    children?: React.ReactNode;
}

/**
 * Description of what this component does.
 *
 * @type atom
 * @status live
 * @tags category1, category2
 */
export const MyComponent: FC<MyComponentProps> = ({
    className,
    testId = CLASSNAME,
    children,
}) => (
    <div className={cx(CLASSNAME, className)} data-testid={testId}>
        {children}
    </div>
);
```

## Test Template

```typescript
import React from 'react';
import { render, screen } from '@testing-library/react';
import { testComponent } from 'lib/test-utils/common';
import { MyComponent } from '../myComponent';

describe('<MyComponent>', () => {
    const renderComponent = (props = {}) =>
        render(<MyComponent {...props} />);

    testComponent(MyComponent);

    test('renders children', () => {
        renderComponent({ children: 'Hello' });
        expect(screen.getByText('Hello')).toBeVisible();
    });

    test('applies custom className', () => {
        renderComponent({ className: 'custom' });
        expect(screen.getByTestId('MyComponent')).toHaveClass('custom');
    });
});
```