|
| 1 | +# Copilot Instructions for findable-ui |
| 2 | + |
| 3 | +## Repository Purpose |
| 4 | + |
| 5 | +This is a TypeScript library package (`@databiosphere/findable-ui`) that provides reusable UI components and utilities for Data Biosphere applications, particularly the Data Browser. It's designed as an npm package that exports compiled JavaScript from the `lib` directory. |
| 6 | + |
| 7 | +## Key Project Information |
| 8 | + |
| 9 | +- **Language**: TypeScript with strict mode enabled |
| 10 | +- **Node Version**: 20.10.0 (enforced) |
| 11 | +- **UI Framework**: React 18 with Material-UI (MUI) v7 |
| 12 | +- **Build System**: TypeScript compiler (tsc) |
| 13 | +- **Testing**: Jest with React Testing Library |
| 14 | +- **Package Type**: Library package that compiles to `lib/` directory |
| 15 | + |
| 16 | +## Repository Structure |
| 17 | + |
| 18 | +- `/src` - TypeScript source files (compiles to `/lib`) |
| 19 | + - `/components` - React UI components |
| 20 | + - `/hooks` - Custom React hooks |
| 21 | + - `/providers` - React context providers |
| 22 | + - `/utils` - Utility functions |
| 23 | + - `/theme` - MUI theme configuration |
| 24 | + - `/config` - Configuration files |
| 25 | + - `/apis` - API client code |
| 26 | + - `/services` - Business logic services |
| 27 | + - `/types` - TypeScript type definitions |
| 28 | + - `/views` - Page-level components |
| 29 | +- `/tests` - Jest test files (separate from src) |
| 30 | +- `/lib` - Compiled JavaScript output (git-ignored) |
| 31 | +- `/.storybook` - Storybook configuration |
| 32 | + |
| 33 | +## Code Style and Standards |
| 34 | + |
| 35 | +### TypeScript Requirements |
| 36 | + |
| 37 | +- **Strict mode enabled**: All TypeScript strict checks are enforced |
| 38 | +- **Explicit return types required**: All functions must have explicit return type annotations (except in `.styles.ts(x)` files) |
| 39 | +- **No implicit any**: Avoid `any` type; use proper typing (exceptions allowed in test files) |
| 40 | +- **Null safety**: Strict null checks are enforced |
| 41 | + |
| 42 | +### Code Organization |
| 43 | + |
| 44 | +- **Sort keys**: Object keys, destructured keys, interface properties, and string enums must be sorted alphabetically (enforced by ESLint) |
| 45 | +- **Import organization**: Imports are auto-organized with prettier-plugin-organize-imports |
| 46 | +- **File naming**: Use kebab-case for file names (e.g., `my-component.tsx`) |
| 47 | + |
| 48 | +### Documentation Requirements |
| 49 | + |
| 50 | +All code must include JSDoc comments with: |
| 51 | + |
| 52 | +- **Function descriptions**: Required for all functions |
| 53 | +- **Parameter documentation**: `@param` tags with descriptions for all parameters |
| 54 | +- **Return value documentation**: `@returns` tag with description |
| 55 | +- **Hyphen before param descriptions**: Required format |
| 56 | + |
| 57 | +Example: |
| 58 | + |
| 59 | +```typescript |
| 60 | +/** |
| 61 | + * Transforms a route by removing inactivity parameters. |
| 62 | + * @param routes - Array of route strings to transform. |
| 63 | + * @returns The first non-login route without inactivity param, or undefined. |
| 64 | + */ |
| 65 | +function transformRoute(routes: string[]): string | undefined { |
| 66 | + // implementation |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### React Patterns |
| 71 | + |
| 72 | +- **Hooks dependencies**: The `react-hooks/exhaustive-deps` rule is enforced - always include all dependencies in useEffect, useCallback, etc. |
| 73 | +- **Component structure**: Use functional components with hooks |
| 74 | +- **Styling**: Use Emotion styled components (`.styles.ts` or `.styles.tsx` files) |
| 75 | + |
| 76 | +## Build, Test, and Validation Steps |
| 77 | + |
| 78 | +### Before Making Changes |
| 79 | + |
| 80 | +1. Install dependencies: `npm ci` |
| 81 | +2. Run all checks to verify baseline: |
| 82 | + ```bash |
| 83 | + npm run check-format |
| 84 | + npm run lint |
| 85 | + npm run test |
| 86 | + npm run test-compile |
| 87 | + ``` |
| 88 | + |
| 89 | +### During Development |
| 90 | + |
| 91 | +1. **Check formatting**: `npm run check-format` (Prettier) |
| 92 | +2. **Lint code**: `npm run lint` (ESLint with TypeScript, SonarJS, and other plugins) |
| 93 | +3. **Run tests**: `npm run test` (Jest with jsdom environment) |
| 94 | +4. **Type check**: `npm run test-compile` (TypeScript compiler without emit) |
| 95 | +5. **Compile library**: `npx tsc` (when making changes that need to be tested in consuming apps) |
| 96 | + |
| 97 | +### All PRs Must Pass |
| 98 | + |
| 99 | +- Prettier formatting check |
| 100 | +- ESLint with no errors |
| 101 | +- All Jest tests passing |
| 102 | +- TypeScript compilation without errors |
| 103 | + |
| 104 | +## Testing Guidelines |
| 105 | + |
| 106 | +- **Test location**: Tests live in the `/tests` directory (not co-located with source files) |
| 107 | +- **Test framework**: Jest with `@testing-library/react` for component tests |
| 108 | +- **Test naming**: Use `.test.ts` or `.test.tsx` extension |
| 109 | +- **Setup**: Tests use Storybook decorators and parameters (see `tests/setup.ts`) |
| 110 | +- **Mocking**: Global mocks for ResizeObserver, TextEncoder, and TextDecoder are pre-configured |
| 111 | +- **Test structure**: Follow the existing pattern of describe/it blocks with clear descriptions |
| 112 | + |
| 113 | +Example test structure: |
| 114 | + |
| 115 | +```typescript |
| 116 | +describe("ComponentName", () => { |
| 117 | + it("should do something specific", () => { |
| 118 | + // Arrange |
| 119 | + const input = "test"; |
| 120 | + |
| 121 | + // Act |
| 122 | + const result = functionUnderTest(input); |
| 123 | + |
| 124 | + // Assert |
| 125 | + expect(result).toBe("expected"); |
| 126 | + }); |
| 127 | +}); |
| 128 | +``` |
| 129 | + |
| 130 | +## Contribution Workflow |
| 131 | + |
| 132 | +1. **Make minimal changes**: This is a library package - changes impact all consumers |
| 133 | +2. **Maintain backward compatibility**: Breaking changes require major version bumps |
| 134 | +3. **Update documentation**: Keep README and inline docs current |
| 135 | +4. **No breaking test changes**: Don't remove or modify existing tests unless fixing bugs |
| 136 | +5. **Test compilation**: Always run `npm run test-compile` to ensure TypeScript compilation succeeds |
| 137 | + |
| 138 | +## Peer Dependencies |
| 139 | + |
| 140 | +This package has extensive peer dependencies that consuming applications must provide: |
| 141 | + |
| 142 | +- React 18.3+ |
| 143 | +- Material-UI (@mui/material, @mui/icons-material) v7 |
| 144 | +- Next.js 14.2+ and next-auth |
| 145 | +- Emotion (@emotion/react, @emotion/styled) |
| 146 | +- TanStack Table and Virtual (@tanstack/react-table, @tanstack/react-virtual) |
| 147 | +- Various utilities (ky, uuid, yup, etc.) |
| 148 | + |
| 149 | +**Do not add these as direct dependencies** - they must remain as peer dependencies. |
| 150 | + |
| 151 | +## Common Pitfalls to Avoid |
| 152 | + |
| 153 | +1. **Don't import from lib/**: Always import from src/ during development |
| 154 | +2. **Don't add dependencies to dependencies**: New packages should go in peerDependencies or devDependencies |
| 155 | +3. **Don't disable ESLint rules without justification**: The strict rules maintain code quality |
| 156 | +4. **Don't skip JSDoc**: All public functions require documentation |
| 157 | +5. **Don't modify package-lock.json manually**: Use npm commands |
| 158 | +6. **Don't commit lib/ directory**: It's build output and git-ignored |
| 159 | + |
| 160 | +## Special Notes |
| 161 | + |
| 162 | +- **Storybook**: Available for component development (`npm run storybook`) |
| 163 | +- **Husky hooks**: Pre-commit hooks are configured via `.husky` |
| 164 | +- **Release management**: Uses release-please for automated versioning and changelog |
| 165 | +- **Link for local development**: Use `npm link` to test changes in Data Browser locally (see README) |
| 166 | + |
| 167 | +## Development with Data Browser |
| 168 | + |
| 169 | +When developing findable-ui alongside the Data Browser: |
| 170 | + |
| 171 | +1. Clone both repos in the same parent directory |
| 172 | +2. In findable-ui: Run `npm ci`, bump version, run `npx tsc` |
| 173 | +3. In data-browser/explorer: Run `npm link ../../findable-ui` |
| 174 | +4. May need to comment out certain packages in next.config.mjs webpack config |
| 175 | + |
| 176 | +See README.md for complete local development workflow. |
0 commit comments