@@ -5,11 +5,13 @@ This is a dual-purpose repository containing both the **Mantine DataTable** comp
55## Project Architecture
66
77### Dual Repository Structure
8+
89- ** Package code** : ` package/ ` - The actual DataTable component exported to npm
910- ** Documentation site** : ` app/ ` , ` components/ ` - Next.js app with examples and docs
1011- ** Build outputs** : Package builds to ` dist/ ` , docs build for GitHub Pages deployment
1112
1213### Package Development Flow
14+
1315``` bash
1416# Core development commands (use pnpm, not yarn despite legacy docs)
1517pnpm dev # Start Next.js dev server for docs/examples
@@ -20,6 +22,7 @@ pnpm lint # ESLint + TypeScript checks
2022```
2123
2224### Component Architecture Pattern
25+
2326The DataTable follows a ** composition-based architecture** with specialized sub-components:
2427
2528``` typescript
@@ -39,29 +42,36 @@ Each sub-component has its own `.tsx`, `.css`, and sometimes `.module.css` files
3942## Development Conventions
4043
4144### Import Alias Pattern
45+
4246Examples use `import { DataTable } from '__PACKAGE__'` - this resolves to the local package during development. Never import from `mantine-datatable` in examples.
4347
4448### TypeScript Patterns
49+
4550- **Generic constraints**: ` DataTable<T> ` where T extends record type
4651- ** Prop composition ** : Props inherit from base Mantine components (TableProps , etc .)
4752- ** Accessor pattern ** : Use ` idAccessor ` prop for custom ID fields , defaults to ` 'id' `
4853
4954### CSS Architecture
55+
5056- **Layered imports**: ` styles.css ` imports all component styles
5157- ** CSS layers ** : ` @layer mantine, mantine-datatable ` for proper specificity
5258- ** Utility classes ** : Defined in ` utilityClasses.css ` for common patterns
5359- ** CSS variables ** : Dynamic values injected via ` cssVariables.ts `
5460
5561### Hook Patterns
62+
5663Custom hooks follow the pattern ` useDataTable* ` and are located in ` package/hooks/ ` :
64+
5765- ` useDataTableColumns ` - Column management and persistence
5866- ` useRowExpansion ` - Row expansion state
5967- ` useLastSelectionChangeIndex ` - Selection behavior
6068
6169## Documentation Development
6270
6371### Example Structure
72+
6473Each example in ` app/examples/ ` follows this pattern :
74+
6575` ` `
6676feature-name/
6777├── page.tsx # Next.js page with controls
@@ -70,50 +80,59 @@ feature-name/
7080` ` `
7181
7282### Code Block Convention
83+
7384Use the ` CodeBlock ` component for syntax highlighting . Example files should be minimal and focused on demonstrating a single feature clearly .
7485
7586## Data Patterns
7687
7788### Record Structure
89+
7890Examples use consistent data shapes :
91+
7992- ` companies.json ` - Basic company data with id , name , address
80- - ` employees.json ` - Employee data with departments/relationships
93+ - ` employees.json ` - Employee data with departments/relationships
8194- ` async.ts ` - Simulated API calls with delay/error simulation
8295
8396### Selection Patterns
97+
8498- **Gmail-style additive selection**: Shift + click for range selection
8599- ** Trigger modes ** : ` 'checkbox' ` | ` 'row' ` | ` 'cell' `
86100- ** Custom selection logic ** : Use ` isRecordSelectable ` for conditional selection
87101
88102## Build System
89103
90104### Package Build (tsup )
105+
91106- ** ESM ** : ` tsup.esm.ts ` - Modern module format
92- - ** CJS ** : ` tsup.cjs.ts ` - CommonJS compatibility
107+ - ** CJS ** : ` tsup.cjs.ts ` - CommonJS compatibility
93108- ** Types ** : ` tsup.dts.ts ` - TypeScript declarations
94109- ** CSS ** : PostCSS processes styles to ` dist/ `
95110
96111### Documentation Deployment
112+
97113- ** GitHub Pages ** : ` output: 'export' ` in ` next.config.js `
98114- ** Base path ** : ` /mantine-datatable ` when ` GITHUB_PAGES=true `
99115- ** Environment injection ** : Package version , NPM downloads via build-time fetch
100116
101117## Common Patterns
102118
103119### Adding New Features
120+
1041211. Create component in `package/` with `.tsx` and `.css` files
1051222. Add to main `DataTable.tsx` component composition
1061233. Export new types from `package/types/index.ts`
1071244. Create example in `app/examples/new-feature/`
1081255. Update main navigation in `app/config.ts`
109126
110127### Styling New Components
128+
111129- Use CSS custom properties for theming
112130- Follow existing naming: ` .mantine-datatable-component-name `
113131- Import CSS in ` package/styles.css `
114132- Add utility classes to ` utilityClasses.css ` if reusable
115133
116134### TypeScript Integration
135+
117136- Extend base Mantine props where possible
118137- Use composition over inheritance for prop types
119138- Export all public types from ` package/types/index.ts `
@@ -124,4 +143,4 @@ Examples use consistent data shapes:
124143- ** Virtualization ** : Not implemented - DataTable handles reasonable record counts (< 1000s )
125144- **Memoization **: Use ` useMemo ` for expensive column calculations
126145- **CSS -in -JS **: Avoided in favor of CSS modules for better performance
127- - **Bundle size **: Keep dependencies minimal (only Mantine + React )
146+ - **Bundle size **: Keep dependencies minimal (only Mantine + React )
0 commit comments