|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a React component library (`@schubergphilis/sbp-frontend-style`) built with TypeScript and styled-components. It provides a complete set of themed, accessible UI components following atomic design principles. The library supports light/dark modes and responsive scaling. |
| 8 | + |
| 9 | +**Published to**: GitHub Package Registry (`npm.pkg.github.com`) |
| 10 | + |
| 11 | +## Commands |
| 12 | + |
| 13 | +### Development |
| 14 | +```bash |
| 15 | +pnpm dev # Start Vite dev server on port 3005 with component showcase |
| 16 | +``` |
| 17 | + |
| 18 | +### Building |
| 19 | +```bash |
| 20 | +pnpm build # Clean dist/ and build library with Rollup (ESM + CJS bundles) |
| 21 | +pnpm clean # Remove dist/ folder |
| 22 | +``` |
| 23 | + |
| 24 | +### Testing |
| 25 | +```bash |
| 26 | +pnpm test # Run all tests with coverage (Jest) |
| 27 | +pnpm test:debug # Run tests in debug mode with watch and detailed output |
| 28 | +pnpm test:focus # Run a specific test file (modify script to target different file) |
| 29 | +pnpm test:clear # Clear Jest cache |
| 30 | +pnpm coverage # Open coverage report in Chrome |
| 31 | +``` |
| 32 | + |
| 33 | +### Code Quality |
| 34 | +```bash |
| 35 | +pnpm lint # ESLint check with TypeScript support |
| 36 | +``` |
| 37 | + |
| 38 | +### Releasing |
| 39 | +```bash |
| 40 | +pnpm release # Create new version with standard-version (CHANGELOG, git tag) |
| 41 | +``` |
| 42 | + |
| 43 | +## Architecture |
| 44 | + |
| 45 | +### Build System |
| 46 | + |
| 47 | +The library uses **two separate entry points**: |
| 48 | +- **Demo/Dev**: `src/index.tsx` → Vite dev server showcasing all components |
| 49 | +- **Library Build**: `src/build.ts` → Rollup bundles for npm distribution |
| 50 | + |
| 51 | +**Pre-build step**: `component-list.js` scans `src/components/` and generates `src/component-list.json` (used by demo app to dynamically list components). This runs automatically before `dev` and `build` commands. |
| 52 | + |
| 53 | +**Two TypeScript configs**: |
| 54 | +- `tsconfig.json`: For development and demo app (Vite, bundler resolution) |
| 55 | +- `tsconfig.build.json`: For Rollup library build |
| 56 | + |
| 57 | +### Atomic Design Structure |
| 58 | + |
| 59 | +Components are organized in three levels: |
| 60 | + |
| 61 | +``` |
| 62 | +src/components/ |
| 63 | +├── atoms/ # Basic building blocks (buttons, inputs, badges, loaders) |
| 64 | +├── molecules/ # Composed components (cards, tables, modals, notifications) |
| 65 | +└── organisms/ # Complex UI patterns (accordion, navigation bars) |
| 66 | +``` |
| 67 | + |
| 68 | +Each level exports through an `index.ts` barrel file. The main export is at `src/components/index.ts`. |
| 69 | + |
| 70 | +### Theming System |
| 71 | + |
| 72 | +**Core files**: |
| 73 | +- `src/styling/ThemeConfig.ts`: Defines `GlobalStyles`, `lightTheme`, `darkTheme`, `largeLightTheme`, `largeDarkTheme` |
| 74 | +- `src/components/CloudStyle.tsx`: Convenience wrapper around styled-components `ThemeProvider` |
| 75 | + |
| 76 | +**Theme tokens** are accessed via `theme.style.*` (colors, spacing, borders) and `theme.fonts.*` (font families). |
| 77 | + |
| 78 | +**CloudStyle component** combines themes based on `isDarkMode` and `isLargeMode` props: |
| 79 | +- Light/Dark mode: Switches color palette |
| 80 | +- Large mode: Changes base `fontSize` from 16px to 24px (all components use `em`/`rem` and scale proportionally) |
| 81 | +- Custom theme overrides: Pass `lightStyle`, `darkStyle`, or `fonts` props |
| 82 | +- **Important**: `darkStyle` inherits overrides from `lightStyle` then applies its own overrides |
| 83 | + |
| 84 | +**Global CSS Reset**: Applied via `GlobalStyles` component (based on Josh Comeau's CSS Reset). |
| 85 | + |
| 86 | +### Path Aliases |
| 87 | + |
| 88 | +TypeScript path resolution is configured with `baseUrl: "./src"`, allowing imports like: |
| 89 | +```typescript |
| 90 | +import { ColumnModel } from 'models/ColumnModel' |
| 91 | +import { FunctionHelpers } from 'helpers/FunctionHelpers' |
| 92 | +import { CloudStyle } from 'components/CloudStyle' |
| 93 | +``` |
| 94 | + |
| 95 | +**Common aliases**: |
| 96 | +- `components/*` → `src/components/*` |
| 97 | +- `datatypes/*` → `src/datatypes/*` |
| 98 | +- `helpers/*` → `src/helpers/*` |
| 99 | +- `models/*` → `src/models/*` |
| 100 | +- `styling/*` → `src/styling/*` |
| 101 | +- `store/*` → `src/store/*` (demo app only) |
| 102 | + |
| 103 | +Both Jest and Vite are configured to resolve these aliases. |
| 104 | + |
| 105 | +### Data Models |
| 106 | + |
| 107 | +`src/models/` contains TypeScript interfaces defining props for complex components: |
| 108 | +- `ColumnModel`: Table column configuration (DynamicTable) |
| 109 | +- `MenuItemModel`: Navigation menu items |
| 110 | +- `SelectOptionModel`: Dropdown options |
| 111 | +- `ComponentOptionModel`: Demo component configuration options |
| 112 | +- `StepsModel`: Step progress indicators |
| 113 | + |
| 114 | +When modifying components that accept structured data, update these models. |
| 115 | + |
| 116 | +### Demo App Architecture |
| 117 | + |
| 118 | +The Vite demo app (`src/App.tsx`) provides an interactive component showcase. It: |
| 119 | +- Uses Redux Toolkit (`src/store/`) for demo settings (dark mode, large mode, etc.) |
| 120 | +- Persists settings to localStorage via middleware |
| 121 | +- Dynamically renders component examples using `component-list.json` |
| 122 | +- Uses `ComponentBox` pattern to create interactive prop controls |
| 123 | + |
| 124 | +**Note**: Consumer applications do **not** need Redux. It's only used for the demo. |
| 125 | + |
| 126 | +## Library Exports |
| 127 | + |
| 128 | +`src/build.ts` exports: |
| 129 | +```typescript |
| 130 | +export * from './components' // All React components |
| 131 | +export * from './datatypes' // Type definitions |
| 132 | +export * from './helpers' // Utility functions |
| 133 | +export * from './models' // Data models/interfaces |
| 134 | +export * from './styling' // Theme config, GlobalStyles |
| 135 | +export * from './types' // Additional types |
| 136 | +``` |
| 137 | + |
| 138 | +**Rollup output**: |
| 139 | +- ESM: `dist/esm/index.mjs.js` |
| 140 | +- CJS: `dist/cjs/index.js` |
| 141 | +- Types: `dist/index.d.ts` |
| 142 | + |
| 143 | +## Key Patterns |
| 144 | + |
| 145 | +### Adding New Components |
| 146 | + |
| 147 | +1. Create component in appropriate atomic level (`atoms/`, `molecules/`, or `organisms/`) |
| 148 | +2. Export from level's `index.ts` barrel file |
| 149 | +3. Component will be auto-detected by `component-list.js` for demo |
| 150 | +4. Use styled-components with theme tokens: `${({ theme }) => theme.style.colorPrimary}` |
| 151 | +5. Follow existing prop patterns (e.g., `isRounded`, `isDisabled`, `variant`) |
| 152 | + |
| 153 | +### Testing |
| 154 | + |
| 155 | +- Test files: `__tests__/**/*.test.ts(x)` or co-located `*.test.ts(x)` |
| 156 | +- Uses Jest with ts-jest (ESM preset) |
| 157 | +- jsdom environment for React components |
| 158 | +- Coverage reports in `./coverage/` |
| 159 | + |
| 160 | +**Common test imports**: |
| 161 | +```typescript |
| 162 | +import '@testing-library/jest-dom' |
| 163 | +import { render, screen } from '@testing-library/react' |
| 164 | +import userEvent from '@testing-library/user-event' |
| 165 | +``` |
| 166 | + |
| 167 | +### Styled Components Best Practices |
| 168 | + |
| 169 | +- Use transient props (`$propName`) for styling props not passed to DOM |
| 170 | +- Access theme via `${({ theme }) => ...}` |
| 171 | +- All colors should reference theme tokens, not hardcoded values |
| 172 | +- Use `em` and `rem` for sizes (supports isLargeMode scaling) |
| 173 | + |
| 174 | +### Version & Release |
| 175 | + |
| 176 | +This project uses `standard-version` for semantic versioning: |
| 177 | +- Automatically generates CHANGELOG from conventional commits |
| 178 | +- Creates git tags |
| 179 | +- Updates version in package.json |
| 180 | +- Commit format: `type(scope): message` (e.g., `feat(button): add loading state`) |
| 181 | + |
| 182 | +## Important Notes |
| 183 | + |
| 184 | +- **Peer dependencies**: React and ReactDOM are peer deps (not bundled). Consumer apps must provide them. |
| 185 | +- **Font files**: Located in `public/fonts/` (TT Interfaces, TT Interphases). Demo app serves these; consumers need to host fonts or provide custom `fonts` prop to CloudStyle. |
| 186 | +- **Icons**: SVG icon components in `src/components/icons/` (not exported in atomic index files, access directly) |
| 187 | +- **Elements**: Helper UI elements in `src/components/elements/` (Elipse, TableOrder, TimestampBar) used internally by molecules/organisms |
| 188 | +- **Module format**: This is an ESM-first package. CJS support provided but ESM is primary target. |
| 189 | + |
| 190 | +## Quality & Honesty |
| 191 | +- **No sycophancy, challenge reasoning.** Be direct — no praise, flattery, or filler. Push back on flawed assumptions or suboptimal approaches (yours and mine). Flag trade-offs honestly. |
0 commit comments