|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +CoreUI for React is a comprehensive React.js components library built on top of Bootstrap 5 and TypeScript. It's organized as a monorepo using Lerna with multiple packages including the main React component library, icons, charts, and documentation. |
| 8 | + |
| 9 | +## Repository Structure |
| 10 | + |
| 11 | +This is a **Lerna monorepo** with the following key packages: |
| 12 | +- `packages/coreui-react/` - Main React components library (TypeScript) |
| 13 | +- `packages/coreui-icons-react/` - Icon components for React |
| 14 | +- `packages/coreui-react-chartjs/` - Chart.js integration for React |
| 15 | +- `packages/docs/` - Gatsby-based documentation site |
| 16 | + |
| 17 | +## Development Commands |
| 18 | + |
| 19 | +### Root Level Commands |
| 20 | +- `npm run lint` - Lint all packages |
| 21 | +- `npm run test` - Run tests for all packages |
| 22 | +- `npm run test:update` - Update snapshots for all packages |
| 23 | + |
| 24 | +### Package-Specific Commands (using Lerna) |
| 25 | +- `npm run lib:build` - Build main React library |
| 26 | +- `npm run lib:test` - Test main React library only |
| 27 | +- `npm run lib:test:update` - Update main library test snapshots |
| 28 | +- `npm run icons:build` - Build icons package |
| 29 | +- `npm run charts:build` - Build charts package |
| 30 | +- `npm run docs:dev` - Start documentation dev server |
| 31 | +- `npm run docs:build` - Build documentation |
| 32 | + |
| 33 | +### Working with Individual Packages |
| 34 | +Navigate to specific packages to run commands directly: |
| 35 | +```bash |
| 36 | +cd packages/coreui-react |
| 37 | +npm test -- src/components/focus-trap/__tests__/CFocusTrap.spec.tsx # Run specific test |
| 38 | +npm run build # Build this package only |
| 39 | +``` |
| 40 | + |
| 41 | +### Running Single Tests |
| 42 | +To run a specific test file: |
| 43 | +```bash |
| 44 | +cd packages/coreui-react |
| 45 | +npm test -- path/to/test.spec.tsx |
| 46 | +``` |
| 47 | + |
| 48 | +## Architecture |
| 49 | + |
| 50 | +### Component Organization |
| 51 | +Each component follows a consistent structure: |
| 52 | +``` |
| 53 | +components/[component-name]/ |
| 54 | +├── C[ComponentName].tsx # Main component |
| 55 | +├── C[ComponentName]Part.tsx # Sub-components |
| 56 | +├── index.ts # Exports |
| 57 | +├── types.ts # TypeScript types (if complex) |
| 58 | +├── utils.ts # Utility functions (if any) |
| 59 | +├── const.ts # Constants (if any) |
| 60 | +└── __tests__/ # Tests and snapshots |
| 61 | + ├── C[ComponentName].spec.tsx |
| 62 | + └── __snapshots__/ |
| 63 | +``` |
| 64 | + |
| 65 | +### Component Development Patterns |
| 66 | + |
| 67 | +**Props Interface**: All components have well-documented TypeScript interfaces with JSDoc comments focusing on accessibility and SEO benefits. |
| 68 | + |
| 69 | +**Ref Forwarding**: Components forward refs properly to DOM elements for accessibility and integration. |
| 70 | + |
| 71 | +**Testing**: Uses React Testing Library with Jest, focusing on behavior over implementation details. Each component has snapshot tests and behavioral tests. |
| 72 | + |
| 73 | +**Styling**: Components use Bootstrap 5 classes and are compatible with `@coreui/coreui` CSS library. |
| 74 | + |
| 75 | +### Key Development Principles |
| 76 | + |
| 77 | +**TypeScript First**: All components are written in TypeScript with proper type definitions. |
| 78 | + |
| 79 | +**Accessibility Focus**: Components implement WCAG 2.1 standards and include proper ARIA attributes. |
| 80 | + |
| 81 | +**Bootstrap Compatible**: Components extend Bootstrap 5 functionality while maintaining compatibility. |
| 82 | + |
| 83 | +**No Extra DOM**: Many components avoid adding wrapper elements, using ref merging instead (see `focus-trap` component). |
| 84 | + |
| 85 | +**Utility Separation**: Complex components separate utilities into dedicated files (`utils.ts`, `const.ts`). |
| 86 | + |
| 87 | +## Testing |
| 88 | + |
| 89 | +### Test Structure |
| 90 | +- Snapshot tests for UI consistency |
| 91 | +- Behavioral tests for user interactions |
| 92 | +- Accessibility tests for focus management |
| 93 | +- Props validation tests |
| 94 | + |
| 95 | +### Test Environment |
| 96 | +- Jest with JSDOM environment |
| 97 | +- React Testing Library for component testing |
| 98 | +- `@testing-library/jest-dom` for DOM assertions |
| 99 | + |
| 100 | +### Running Tests |
| 101 | +Tests are run at the package level. Some complex focus management tests may not work perfectly in JSDOM but will work in real browsers. |
| 102 | + |
| 103 | +## Build System |
| 104 | + |
| 105 | +### Rollup Configuration |
| 106 | +Each package uses Rollup for building: |
| 107 | +- ESM and CommonJS outputs |
| 108 | +- TypeScript compilation |
| 109 | +- Separate bundles for different environments |
| 110 | + |
| 111 | +### Package Dependencies |
| 112 | +- `@coreui/coreui` - Core CSS library |
| 113 | +- `@popperjs/core` - For positioning (tooltips, dropdowns) |
| 114 | +- `prop-types` - Runtime type checking |
| 115 | +- React 17+ peer dependency |
| 116 | + |
| 117 | +## Component Development |
| 118 | + |
| 119 | +### Creating New Components |
| 120 | +1. Follow the directory structure pattern |
| 121 | +2. Use TypeScript interfaces with comprehensive JSDoc |
| 122 | +3. Implement proper ref forwarding |
| 123 | +4. Add comprehensive tests (snapshot + behavioral) |
| 124 | +5. Export from package index files |
| 125 | +6. Consider accessibility from the start |
| 126 | + |
| 127 | +### Refactoring Components |
| 128 | +When refactoring complex components: |
| 129 | +1. Separate utilities into `utils.ts` and constants into `const.ts` |
| 130 | +2. Maintain backward compatibility with existing props |
| 131 | +3. Update tests to match new structure |
| 132 | +4. Keep the same export interface |
| 133 | + |
| 134 | +### Focus Management |
| 135 | +For components requiring focus management (modals, dropdowns), use the patterns established in the `focus-trap` component, which implements proper Tab/Shift+Tab cycling and external focus redirection. |
0 commit comments