docs(plan): add feature complete implementation plan
This commit is contained in:
Hein
702
src/Griddy/plan.md
Normal file
702
src/Griddy/plan.md
Normal file
@@ -0,0 +1,702 @@
|
|||||||
|
# Griddy - Feature Complete Implementation Plan
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
Griddy is a native TypeScript HTML table/grid component designed as a lightweight, extensible alternative to both Glide Data Editor and Mantine React Table. It will provide a zero-dependency core with optional plugin architecture, built on TanStack React Virtual for efficient virtualization.
|
||||||
|
|
||||||
|
## Architecture & Core Design Principles
|
||||||
|
|
||||||
|
### 1. Core Philosophy
|
||||||
|
- **Independent**: Minimal peer dependencies (React, React DOM only at minimum)
|
||||||
|
- **Lightweight**: Pure HTML table rendering with CSS styling
|
||||||
|
- **Virtual-First**: Virtualization from the ground up using TanStack React Virtual
|
||||||
|
- **Plugin-Based**: All advanced features as pluggable modules
|
||||||
|
- **State Agnostic**: Works with any state management solution or local state
|
||||||
|
- **Callback-Driven**: Similar to Glide Data Editor's read-only data principle
|
||||||
|
|
||||||
|
### 1.5. Lessons from Gridler
|
||||||
|
Gridly (existing implementation) provides valuable patterns:
|
||||||
|
- **Zustand Store Pattern**: Central state management using `createSyncStore` for reactive updates
|
||||||
|
- **Data Adapter Pattern**: Wrapper components that interface with store (LocalDataAdaptor, FormAdaptor, APIAdaptor)
|
||||||
|
- **Event System**: Uses CustomEvent for inter-component communication
|
||||||
|
- **Provider/Context Pattern**: Wraps grid in Provider for configuration and state sharing
|
||||||
|
- **Column Definition System**: Type-safe, extensible column definitions with custom rendering
|
||||||
|
- **Ref-based API**: Forward refs for imperative commands (refresh, reload, scrollTo, selectRow)
|
||||||
|
- **Persistence**: Automatic localStorage persistence for column order and sizing
|
||||||
|
|
||||||
|
**Griddy will adopt these proven patterns while building on TanStack React Virtual instead of Glide Data Grid**
|
||||||
|
|
||||||
|
### 2. Component Structure
|
||||||
|
|
||||||
|
Following Gridler's proven architecture, with improvements:
|
||||||
|
|
||||||
|
```
|
||||||
|
Griddy/
|
||||||
|
├── core/
|
||||||
|
│ ├── Griddy.tsx (main component, similar to Gridler.tsx)
|
||||||
|
│ ├── GriddyStore.ts (zustand store, similar to Gridler's createSyncStore)
|
||||||
|
│ ├── GriddyProvider.tsx (context provider for configuration)
|
||||||
|
│ └── types.ts (core type definitions)
|
||||||
|
├── virtualization/
|
||||||
|
│ ├── VirtualBody.tsx (uses TanStack React Virtual)
|
||||||
|
│ ├── VirtualHeader.tsx
|
||||||
|
│ └── hooks/useVirtualize.ts
|
||||||
|
├── features/
|
||||||
|
│ ├── filtering/ (column filtering)
|
||||||
|
│ ├── sorting/ (multi-column sorting)
|
||||||
|
│ ├── grouping/ (header grouping & data grouping)
|
||||||
|
│ ├── search/ (global & column-specific search)
|
||||||
|
│ ├── selection/ (row/column/range selection)
|
||||||
|
│ ├── editing/ (in-place cell editors)
|
||||||
|
│ ├── pagination/ (cursor & offset-based)
|
||||||
|
│ ├── resizing/ (column width resizing)
|
||||||
|
│ ├── pinning/ (freeze columns/rows)
|
||||||
|
│ └── export/ (CSV/data export)
|
||||||
|
├── editors/
|
||||||
|
│ ├── TextEditor.tsx
|
||||||
|
│ ├── NumericEditor.tsx
|
||||||
|
│ ├── DateEditor.tsx
|
||||||
|
│ ├── SelectEditor.tsx
|
||||||
|
│ └── CustomEditor.tsx (extensibility point)
|
||||||
|
├── renderers/
|
||||||
|
│ ├── defaultRenderers.ts
|
||||||
|
│ ├── CustomRenderer.tsx (extensibility point)
|
||||||
|
│ └── formatters.ts (value formatting)
|
||||||
|
├── hooks/
|
||||||
|
│ ├── useGriddy.ts (main hook)
|
||||||
|
│ ├── useFiltering.ts
|
||||||
|
│ ├── useSorting.ts
|
||||||
|
│ ├── useSearch.ts
|
||||||
|
│ ├── useSelection.ts
|
||||||
|
│ ├── usePagination.ts
|
||||||
|
│ ├── useEditing.ts
|
||||||
|
│ └── useVirtualization.ts
|
||||||
|
├── adapters/
|
||||||
|
│ ├── LocalDataAdapter.ts
|
||||||
|
│ ├── RemoteServerAdapter.ts
|
||||||
|
│ ├── GraphQLAdapter.ts (optional)
|
||||||
|
│ └── RESTAdapter.ts (optional)
|
||||||
|
├── styles/
|
||||||
|
│ ├── griddy.module.css
|
||||||
|
│ └── themes.ts (theme system)
|
||||||
|
└── index.ts (exports)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Feature Specifications
|
||||||
|
|
||||||
|
### Core Features
|
||||||
|
|
||||||
|
#### 1. Data Handling
|
||||||
|
- **Local Data**: Direct array-based data binding
|
||||||
|
- **Remote Server Data**: Async data fetching with loading states
|
||||||
|
- **Cursor-Based Paging**: Server-side paging with cursor tokens (for performance)
|
||||||
|
- **Offset-Based Paging**: Traditional offset/limit paging
|
||||||
|
- **Lazy Loading**: Data loaded as user scrolls (virtual scrolling integration)
|
||||||
|
- **Data Adapters**: Pluggable adapters for different data sources
|
||||||
|
|
||||||
|
API:
|
||||||
|
```typescript
|
||||||
|
interface GriddyDataSource {
|
||||||
|
data: T[]
|
||||||
|
total?: number
|
||||||
|
pageInfo?: { hasNextPage: boolean, cursor?: string }
|
||||||
|
isLoading?: boolean
|
||||||
|
error?: Error
|
||||||
|
}
|
||||||
|
|
||||||
|
interface GriddyProps<T> {
|
||||||
|
data: T[]
|
||||||
|
columns: Column<T>[]
|
||||||
|
onDataChange?: (data: T[]) => void
|
||||||
|
dataAdapter?: DataAdapter<T>
|
||||||
|
// ... other props
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. Virtualization
|
||||||
|
- **Row Virtualization**: Only render visible rows using TanStack React Virtual
|
||||||
|
- **Column Virtualization**: Optionally virtualize columns for wide tables
|
||||||
|
- **Scrolling Performance**: Smooth scrolling with overscan optimization
|
||||||
|
- **Height Calculation**: Fixed height container with auto-height option
|
||||||
|
- **Sticky Headers**: Virtual header stays fixed while scrolling
|
||||||
|
|
||||||
|
Implementation:
|
||||||
|
- Use `@tanstack/react-virtual` for row/column virtualization
|
||||||
|
- Configurable overscan count for smooth scrolling
|
||||||
|
- Support both fixed and variable row heights
|
||||||
|
|
||||||
|
#### 3. Column Management
|
||||||
|
- **Column Definition**: Type-safe column definitions with accessors
|
||||||
|
- **Header Grouping**: Multi-level header groups (similar to Glide)
|
||||||
|
- **Column Pinning**: Freeze left/right columns
|
||||||
|
- **Column Resizing**: Drag-to-resize with min/max constraints
|
||||||
|
- **Column Hiding**: Show/hide columns dynamically
|
||||||
|
- **Column Reordering**: Drag-and-drop column reordering
|
||||||
|
- **Header Customization**: Custom header renderers
|
||||||
|
|
||||||
|
API:
|
||||||
|
```typescript
|
||||||
|
interface Column<T> {
|
||||||
|
id: string
|
||||||
|
header: string | ReactNode
|
||||||
|
accessor: keyof T | ((row: T) => any)
|
||||||
|
width?: number
|
||||||
|
minWidth?: number
|
||||||
|
maxWidth?: number
|
||||||
|
pinned?: 'left' | 'right'
|
||||||
|
sortable?: boolean
|
||||||
|
filterable?: boolean
|
||||||
|
searchable?: boolean
|
||||||
|
editable?: boolean
|
||||||
|
editor?: EditorComponent<T>
|
||||||
|
renderer?: RendererComponent<T>
|
||||||
|
headerGroup?: string
|
||||||
|
hidden?: boolean
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. Filtering
|
||||||
|
- **Column Filtering**: Per-column filter UI (text, number, date, select)
|
||||||
|
- **Filter Modes**: Exact match, contains, starts with, ends with, between (for numbers/dates)
|
||||||
|
- **Multi-Filter**: Multiple filters per column with AND/OR logic
|
||||||
|
- **Filter Persistence**: Save/restore filter state
|
||||||
|
- **Custom Filters**: User-provided filter functions
|
||||||
|
|
||||||
|
Implementation:
|
||||||
|
- Filter dropdown in column header
|
||||||
|
- Configuration for filter types per column
|
||||||
|
- Debounced filtering for performance
|
||||||
|
|
||||||
|
#### 5. Search
|
||||||
|
- **Global Search**: Search across all searchable columns
|
||||||
|
- **Column Search**: Search within specific columns
|
||||||
|
- **Search Highlighting**: Highlight matching text
|
||||||
|
- **Search Navigation**: Navigate through search results
|
||||||
|
- **Fuzzy Search**: Optional fuzzy search capability
|
||||||
|
|
||||||
|
API:
|
||||||
|
```typescript
|
||||||
|
interface SearchConfig {
|
||||||
|
enabled: boolean
|
||||||
|
debounceMs?: number
|
||||||
|
fuzzy?: boolean
|
||||||
|
highlightMatches?: boolean
|
||||||
|
caseSensitive?: boolean
|
||||||
|
columnsToSearch?: string[] // column IDs
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 6. Sorting
|
||||||
|
- **Single Column Sort**: Sort by one column (default)
|
||||||
|
- **Multi-Column Sort**: Sort by multiple columns with priority
|
||||||
|
- **Sort Direction**: Ascending/descending/unsorted
|
||||||
|
- **Custom Sort Functions**: User-provided sort comparators
|
||||||
|
- **Sort Persistence**: Save/restore sort state
|
||||||
|
- **Server-Side Sort**: Offload sorting to server
|
||||||
|
|
||||||
|
Implementation:
|
||||||
|
- Click header to sort (first click = asc, second = desc, third = unsorted)
|
||||||
|
- Shift+Click for multi-column sort
|
||||||
|
- Visual indicators in header (arrows/icons)
|
||||||
|
|
||||||
|
#### 7. Row/Column Selection
|
||||||
|
- **Row Selection**: Single or multi-select with checkboxes
|
||||||
|
- **Column Selection**: Select entire columns
|
||||||
|
- **Range Selection**: Rectangular range selection (like Glide)
|
||||||
|
- **Selection Callbacks**: On selection change events
|
||||||
|
- **Selection Persistence**: Maintain selection across pagination
|
||||||
|
- **Selection Styling**: Highlight selected rows/columns
|
||||||
|
|
||||||
|
API:
|
||||||
|
```typescript
|
||||||
|
interface SelectionConfig {
|
||||||
|
mode: 'none' | 'row' | 'column' | 'range'
|
||||||
|
multiSelect?: boolean
|
||||||
|
selectOnClick?: boolean
|
||||||
|
deselectOnClick?: boolean
|
||||||
|
onSelectionChange?: (selection: Selection) => void
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 8. Grouping
|
||||||
|
- **Header Grouping**: Multi-level column groups (visual grouping only, no data aggregation initially)
|
||||||
|
- **Data Grouping**: Group rows by column value with collapsible groups
|
||||||
|
- **Aggregation**: Show aggregate values (count, sum, avg, etc.) in group headers
|
||||||
|
- **Group Actions**: Expand/collapse groups, delete groups
|
||||||
|
|
||||||
|
#### 9. In-Place Editing
|
||||||
|
- **Text Editor**: Simple text input with validation
|
||||||
|
- **Numeric Editor**: Number input with constraints
|
||||||
|
- **Date Editor**: Date picker or input
|
||||||
|
- **Select Editor**: Dropdown with predefined options
|
||||||
|
- **Custom Editors**: User-provided editor components
|
||||||
|
- **Validation**: Per-cell or per-row validation
|
||||||
|
- **Undo/Redo**: Optional undo/redo support
|
||||||
|
- **Batch Edits**: Edit multiple cells and submit together
|
||||||
|
|
||||||
|
API:
|
||||||
|
```typescript
|
||||||
|
interface EditorProps<T> {
|
||||||
|
value: any
|
||||||
|
column: Column<T>
|
||||||
|
row: T
|
||||||
|
onCommit: (newValue: any) => void
|
||||||
|
onCancel: () => void
|
||||||
|
onBlur?: () => void
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Column<T> {
|
||||||
|
editor?: EditorComponent<T>
|
||||||
|
editable?: boolean | ((row: T) => boolean)
|
||||||
|
onEditCommit?: (newValue: any, row: T) => Promise<void>
|
||||||
|
validation?: (value: any) => string | null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 10. Pagination
|
||||||
|
- **Offset Pagination**: Page/limit based (e.g., page 1-10, 20 items per page)
|
||||||
|
- **Cursor Pagination**: Cursor-based (for infinite scroll or server-side)
|
||||||
|
- **Page Navigation**: Next/prev buttons, page input, jump to page
|
||||||
|
- **Items Per Page**: Configurable items per page with preset options
|
||||||
|
- **Total Count**: Display total items and current range
|
||||||
|
|
||||||
|
API:
|
||||||
|
```typescript
|
||||||
|
interface PaginationConfig {
|
||||||
|
enabled: boolean
|
||||||
|
type: 'offset' | 'cursor'
|
||||||
|
pageSize: number
|
||||||
|
pageSizeOptions?: number[]
|
||||||
|
onPageChange?: (page: number) => void
|
||||||
|
onPageSizeChange?: (pageSize: number) => void
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 11. Extensibility
|
||||||
|
|
||||||
|
**Custom Cell Renderers**:
|
||||||
|
```typescript
|
||||||
|
interface RendererProps<T> {
|
||||||
|
value: any
|
||||||
|
row: T
|
||||||
|
column: Column<T>
|
||||||
|
rowIndex: number
|
||||||
|
columnIndex: number
|
||||||
|
isEditing?: boolean
|
||||||
|
}
|
||||||
|
|
||||||
|
type CellRenderer<T> = (props: RendererProps<T>) => ReactNode
|
||||||
|
```
|
||||||
|
|
||||||
|
**Custom Features via Hooks**:
|
||||||
|
- Users can wrap Griddy with custom hooks to add features
|
||||||
|
- Plugin architecture through context and callbacks
|
||||||
|
|
||||||
|
**Custom Editors**:
|
||||||
|
- Any component can be an editor if it implements EditorProps interface
|
||||||
|
|
||||||
|
**Custom Data Adapters**:
|
||||||
|
```typescript
|
||||||
|
interface DataAdapter<T> {
|
||||||
|
fetch: (config: FetchConfig) => Promise<GriddyDataSource<T>>
|
||||||
|
save: (row: T) => Promise<void>
|
||||||
|
delete: (row: T) => Promise<void>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architectural Patterns from Gridler to Adopt
|
||||||
|
|
||||||
|
### 1. Zustand Store Pattern
|
||||||
|
Gridler's `GridlerStore.tsx` demonstrates effective state management:
|
||||||
|
```typescript
|
||||||
|
// Griddy will follow similar pattern
|
||||||
|
const { Provider, useGriddyStore } = createSyncStore<GriddyState, GriddyProps>(
|
||||||
|
(set, get) => ({
|
||||||
|
// State mutations and getters
|
||||||
|
// Immer integration for immutable updates
|
||||||
|
// Custom methods for grid operations
|
||||||
|
})
|
||||||
|
)
|
||||||
|
```
|
||||||
|
**Benefits**: Reactive updates, easy testing, dev tools support, persistence support
|
||||||
|
|
||||||
|
### 2. Data Adapter Pattern
|
||||||
|
Gridler's adapters (LocalDataAdaptor, FormAdaptor, APIAdaptor) show clean separation:
|
||||||
|
- Adapters are wrapper components that consume store and trigger data operations
|
||||||
|
- They handle filtering, sorting, searching via store mutations
|
||||||
|
- Support both local and remote data without core changes
|
||||||
|
- Each adapter implements `useAPIQuery` pattern for pagination
|
||||||
|
|
||||||
|
**Griddy will adopt this for extensibility**:
|
||||||
|
```typescript
|
||||||
|
// Location: src/Griddy/adapters/
|
||||||
|
// - LocalDataAdapter.tsx (array data)
|
||||||
|
// - RemoteServerAdapter.tsx (API with cursor/offset paging)
|
||||||
|
// - CustomAdapter pattern for user extensions
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Event System
|
||||||
|
Gridler uses `CustomEvent` for loose coupling between components:
|
||||||
|
```typescript
|
||||||
|
state._events.dispatchEvent(new CustomEvent('loadPage', { detail }))
|
||||||
|
state._events.addEventListener('reload', handler)
|
||||||
|
```
|
||||||
|
**Griddy benefit**: Allows features to trigger actions without tight coupling
|
||||||
|
|
||||||
|
### 4. Column Definition System
|
||||||
|
Gridler's `GridlerColumn` interface shows best practices:
|
||||||
|
- Optional `Cell` renderer for custom cell display
|
||||||
|
- `disableSort`, `disableFilter`, `disableMove`, `disableResize` flags
|
||||||
|
- Custom menu items via `getMenuItems`
|
||||||
|
- Tooltip support (string or function)
|
||||||
|
- Nested field access via dot notation
|
||||||
|
|
||||||
|
**Griddy will enhance this**:
|
||||||
|
```typescript
|
||||||
|
interface Column<T> {
|
||||||
|
id: string
|
||||||
|
header: string
|
||||||
|
accessor: keyof T | ((row: T) => any)
|
||||||
|
renderer?: (props: RendererProps<T>) => ReactNode
|
||||||
|
editor?: EditorComponent<T>
|
||||||
|
sortable?: boolean
|
||||||
|
filterable?: boolean
|
||||||
|
resizable?: boolean
|
||||||
|
pinned?: 'left' | 'right'
|
||||||
|
// ... more options
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Ref-Based Imperative API
|
||||||
|
Gridler's `GridlerRef` provides necessary imperative operations:
|
||||||
|
```typescript
|
||||||
|
interface GridlerRef {
|
||||||
|
getState: () => GridlerState
|
||||||
|
refresh: () => Promise<void>
|
||||||
|
scrollToRow: (key: string | number) => Promise<void>
|
||||||
|
selectRow: (key: string | number) => Promise<void>
|
||||||
|
reloadRow: (key: string | number) => Promise<void>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
**Griddy will provide similar imperative API for parent control**
|
||||||
|
|
||||||
|
### 6. Persistence Layer
|
||||||
|
Gridler uses localStorage for column state:
|
||||||
|
```typescript
|
||||||
|
persist={{
|
||||||
|
name: `Gridler_${props.uniqueid}`,
|
||||||
|
partialize: (s) => ({ colOrder: s.colOrder, colSize: s.colSize }),
|
||||||
|
version: 1,
|
||||||
|
}}
|
||||||
|
```
|
||||||
|
**Griddy will support this optional persistence**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Phases
|
||||||
|
|
||||||
|
### Phase 1: Core Foundation (Weeks 1-2)
|
||||||
|
- [ ] Set up Griddy package structure
|
||||||
|
- [ ] Create core types and interfaces
|
||||||
|
- [ ] Implement basic Griddy component with:
|
||||||
|
- Simple table rendering (HTML `<table>`)
|
||||||
|
- Column definition system
|
||||||
|
- Basic props interface
|
||||||
|
- Initial Zustand store (optional, minimal state)
|
||||||
|
- [ ] Implement LocalDataAdapter
|
||||||
|
- [ ] Add Storybook stories for basic table
|
||||||
|
|
||||||
|
**Deliverable**: Functional table rendering local data with column definitions
|
||||||
|
|
||||||
|
### Phase 2: Virtualization & Performance (Weeks 2-3)
|
||||||
|
- [ ] Integrate TanStack React Virtual
|
||||||
|
- [ ] Implement row virtualization
|
||||||
|
- [ ] Implement sticky header with virtual scroll
|
||||||
|
- [ ] Add column resizing
|
||||||
|
- [ ] Performance optimization (memo, useMemo)
|
||||||
|
- [ ] Test with large datasets (10k+ rows)
|
||||||
|
|
||||||
|
**Deliverable**: High-performance virtualized table
|
||||||
|
|
||||||
|
### Phase 3: Data Handling (Weeks 3-4)
|
||||||
|
- [ ] Implement RemoteServerAdapter
|
||||||
|
- [ ] Add cursor-based pagination
|
||||||
|
- [ ] Add offset-based pagination
|
||||||
|
- [ ] Implement loading states
|
||||||
|
- [ ] Error handling and display
|
||||||
|
- [ ] Infinite scroll pattern
|
||||||
|
|
||||||
|
**Deliverable**: Full data source flexibility (local, remote, paginated)
|
||||||
|
|
||||||
|
### Phase 4: Selection & Interaction (Week 4)
|
||||||
|
- [ ] Row selection (checkbox + keyboard)
|
||||||
|
- [ ] Column selection
|
||||||
|
- [ ] Range selection
|
||||||
|
- [ ] Selection persistence
|
||||||
|
- [ ] Keyboard navigation (arrows, shift+click, etc.)
|
||||||
|
|
||||||
|
**Deliverable**: Full selection capabilities
|
||||||
|
|
||||||
|
### Phase 5: Filtering, Sorting, Search (Week 5)
|
||||||
|
- [ ] Sorting (single & multi-column)
|
||||||
|
- [ ] Column filtering UI and logic
|
||||||
|
- [ ] Global search
|
||||||
|
- [ ] Search highlighting
|
||||||
|
- [ ] Filter/sort state persistence
|
||||||
|
|
||||||
|
**Deliverable**: Data manipulation features
|
||||||
|
|
||||||
|
### Phase 6: In-Place Editing (Week 5-6)
|
||||||
|
- [ ] Text, Numeric, Date editors
|
||||||
|
- [ ] Select editor
|
||||||
|
- [ ] Validation system
|
||||||
|
- [ ] Edit callbacks (onEditCommit, onEditCancel)
|
||||||
|
- [ ] Undo/redo (optional)
|
||||||
|
- [ ] Trailing row for new records (optional)
|
||||||
|
|
||||||
|
**Deliverable**: Full editing capabilities
|
||||||
|
|
||||||
|
### Phase 7: Advanced Features (Week 6-7)
|
||||||
|
- [ ] Grouping (header groups)
|
||||||
|
- [ ] Data grouping with aggregation
|
||||||
|
- [ ] Column pinning/freezing
|
||||||
|
- [ ] Column reordering
|
||||||
|
- [ ] Column hiding/showing
|
||||||
|
- [ ] Export to CSV
|
||||||
|
|
||||||
|
**Deliverable**: Advanced features
|
||||||
|
|
||||||
|
### Phase 8: Polish & Documentation (Week 7-8)
|
||||||
|
- [ ] Comprehensive Storybook stories
|
||||||
|
- [ ] API documentation
|
||||||
|
- [ ] TypeScript definitions and examples
|
||||||
|
- [ ] Integration examples
|
||||||
|
- [ ] Performance benchmarks
|
||||||
|
- [ ] Accessibility improvements (ARIA, keyboard nav)
|
||||||
|
- [ ] Theme system documentation
|
||||||
|
|
||||||
|
**Deliverable**: Production-ready component
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Comparison with Competitors
|
||||||
|
|
||||||
|
### vs. Glide Data Editor
|
||||||
|
**Advantages**:
|
||||||
|
- No proprietary license needed
|
||||||
|
- Simpler API, less callback hell
|
||||||
|
- Smaller bundle size
|
||||||
|
- Framework agnostic (could be ported to Vue, Svelte, etc.)
|
||||||
|
- More transparent development
|
||||||
|
|
||||||
|
**Disadvantages**:
|
||||||
|
- Less mature (initially)
|
||||||
|
- Fewer enterprise features
|
||||||
|
- No rich text editing (not planned for MVP)
|
||||||
|
|
||||||
|
### vs. Mantine React Table
|
||||||
|
**Advantages**:
|
||||||
|
- Lighter weight
|
||||||
|
- Pure virtual rendering (no DOM overhead)
|
||||||
|
- More flexible CSS styling (pure HTML table)
|
||||||
|
- Better performance with large datasets
|
||||||
|
- Simpler core API
|
||||||
|
|
||||||
|
**Disadvantages**:
|
||||||
|
- No built-in Modal editing (only in-line)
|
||||||
|
- No tree/hierarchical data (initially)
|
||||||
|
- Requires Mantine knowledge (eventually provide integrations)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
- **React**: 19.x (peer dependency)
|
||||||
|
- **TypeScript**: 5.9+
|
||||||
|
- **Virtualization**: @tanstack/react-virtual 3.13+
|
||||||
|
- **State Management**: Zustand (optional, for advanced features)
|
||||||
|
- **Styling**: CSS Modules + Mantine theming integration (optional)
|
||||||
|
- **Testing**: Vitest, React Testing Library
|
||||||
|
- **Build**: Vite with TypeScript declaration generation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
**Peer Dependencies**:
|
||||||
|
- react >= 19.0.0
|
||||||
|
- react-dom >= 19.0.0
|
||||||
|
- @tanstack/react-virtual >= 3.13.0
|
||||||
|
|
||||||
|
**Optional Peer Dependencies**:
|
||||||
|
- @mantine/core (for integrated theming)
|
||||||
|
- @tanstack/react-query (for server-side data)
|
||||||
|
|
||||||
|
**Dev Dependencies**:
|
||||||
|
- Same as Oranguru project (Vitest, Storybook, etc.)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
|
||||||
|
1. **Unit Tests**:
|
||||||
|
- Editor components
|
||||||
|
- Filter/Sort logic
|
||||||
|
- Data adapter functions
|
||||||
|
- Hook logic
|
||||||
|
|
||||||
|
2. **Integration Tests**:
|
||||||
|
- Column definition system
|
||||||
|
- Data flow end-to-end
|
||||||
|
- Selection with filtering
|
||||||
|
- Editing with validation
|
||||||
|
|
||||||
|
3. **Performance Tests**:
|
||||||
|
- Rendering 10k+ rows
|
||||||
|
- Filtering/sorting on large datasets
|
||||||
|
- Memory usage monitoring
|
||||||
|
|
||||||
|
4. **Accessibility Tests**:
|
||||||
|
- Keyboard navigation
|
||||||
|
- ARIA labels and roles
|
||||||
|
- Screen reader compatibility
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Browser Support
|
||||||
|
|
||||||
|
- Chrome/Edge: Latest 2 versions
|
||||||
|
- Firefox: Latest 2 versions
|
||||||
|
- Safari: Latest 2 versions
|
||||||
|
- No IE11 support (modern React requirement)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
1. ✅ Table renders 10k+ rows smoothly (60fps)
|
||||||
|
2. ✅ Filtering/sorting on 10k rows completes in <500ms
|
||||||
|
3. ✅ TypeScript types cover 95%+ of code
|
||||||
|
4. ✅ Bundle size < 50KB (gzipped, excluding Mantine)
|
||||||
|
5. ✅ Full keyboard accessibility (WCAG AA)
|
||||||
|
6. ✅ 100+ Storybook stories covering all features
|
||||||
|
7. ✅ Zero external styling dependencies (works with any CSS)
|
||||||
|
8. ✅ All features tested with >80% coverage
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known Limitations (Phase 1)
|
||||||
|
|
||||||
|
- Tree/hierarchical data: Planned for Phase 2
|
||||||
|
- Drag-and-drop column reordering: Phase 2
|
||||||
|
- Copy/paste: Phase 2
|
||||||
|
- Rich text/HTML content: Not planned
|
||||||
|
- Master-detail/expandable rows: Phase 2
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Structure (Detailed)
|
||||||
|
|
||||||
|
```
|
||||||
|
src/Griddy/
|
||||||
|
├── core/
|
||||||
|
│ ├── Griddy.tsx # Main component
|
||||||
|
│ ├── GriddyContext.ts # React context
|
||||||
|
│ ├── GriddyStore.ts # Zustand store (optional)
|
||||||
|
│ ├── types.ts # Core types
|
||||||
|
│ ├── defaults.ts # Default config
|
||||||
|
│ └── constants.ts # Constants
|
||||||
|
├── virtualization/
|
||||||
|
│ ├── VirtualBody.tsx # Virtual row rendering
|
||||||
|
│ ├── VirtualHeader.tsx # Virtual column header
|
||||||
|
│ ├── hooks/
|
||||||
|
│ │ ├── useVirtualize.ts # Virtualization logic
|
||||||
|
│ │ └── useVirtualizeColumns.ts
|
||||||
|
│ └── utils/
|
||||||
|
│ └── sizing.ts # Size calculations
|
||||||
|
├── features/
|
||||||
|
│ ├── filtering/
|
||||||
|
│ │ ├── FilterControl.tsx
|
||||||
|
│ │ ├── useFiltering.ts
|
||||||
|
│ │ ├── types.ts
|
||||||
|
│ │ └── operators.ts
|
||||||
|
│ ├── sorting/
|
||||||
|
│ │ ├── SortIndicator.tsx
|
||||||
|
│ │ ├── useSorting.ts
|
||||||
|
│ │ └── types.ts
|
||||||
|
│ ├── search/
|
||||||
|
│ │ ├── SearchBox.tsx
|
||||||
|
│ │ ├── useSearch.ts
|
||||||
|
│ │ └── types.ts
|
||||||
|
│ ├── selection/
|
||||||
|
│ │ ├── SelectionCheckbox.tsx
|
||||||
|
│ │ ├── useSelection.ts
|
||||||
|
│ │ ├── types.ts
|
||||||
|
│ │ └── keyboard.ts
|
||||||
|
│ ├── grouping/
|
||||||
|
│ │ ├── HeaderGroup.tsx
|
||||||
|
│ │ ├── DataGrouping.tsx
|
||||||
|
│ │ ├── useGrouping.ts
|
||||||
|
│ │ └── types.ts
|
||||||
|
│ ├── editing/
|
||||||
|
│ │ ├── EditableCell.tsx
|
||||||
|
│ │ ├── useEditing.ts
|
||||||
|
│ │ ├── validation.ts
|
||||||
|
│ │ └── types.ts
|
||||||
|
│ ├── pagination/
|
||||||
|
│ │ ├── PaginationControl.tsx
|
||||||
|
│ │ ├── usePagination.ts
|
||||||
|
│ │ └── types.ts
|
||||||
|
│ ├── pinning/
|
||||||
|
│ │ ├── usePinning.ts
|
||||||
|
│ │ └── types.ts
|
||||||
|
│ └── resizing/
|
||||||
|
│ ├── useColumnResizing.ts
|
||||||
|
│ └── types.ts
|
||||||
|
├── editors/
|
||||||
|
│ ├── TextEditor.tsx
|
||||||
|
│ ├── NumericEditor.tsx
|
||||||
|
│ ├── DateEditor.tsx
|
||||||
|
│ ├── SelectEditor.tsx
|
||||||
|
│ ├── CheckboxEditor.tsx
|
||||||
|
│ └── index.ts
|
||||||
|
├── renderers/
|
||||||
|
│ ├── defaultRenderers.tsx
|
||||||
|
│ ├── formatters.ts
|
||||||
|
│ └── types.ts
|
||||||
|
├── adapters/
|
||||||
|
│ ├── LocalDataAdapter.ts
|
||||||
|
│ ├── RemoteServerAdapter.ts
|
||||||
|
│ ├── base.ts
|
||||||
|
│ └── types.ts
|
||||||
|
├── hooks/
|
||||||
|
│ ├── useGriddy.ts # Main hook composing all features
|
||||||
|
│ ├── useMergedRefs.ts
|
||||||
|
│ ├── useAsync.ts
|
||||||
|
│ └── index.ts
|
||||||
|
├── styles/
|
||||||
|
│ ├── griddy.module.css
|
||||||
|
│ ├── themes.ts
|
||||||
|
│ ├── variables.css
|
||||||
|
│ └── reset.css
|
||||||
|
├── utils/
|
||||||
|
│ ├── merge.ts
|
||||||
|
│ ├── classNames.ts
|
||||||
|
│ ├── keyboard.ts
|
||||||
|
│ ├── accessibility.ts
|
||||||
|
│ └── index.ts
|
||||||
|
├── index.ts # Main export
|
||||||
|
├── Griddy.test.tsx
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. Review and approve this plan
|
||||||
|
2. Create project directory structure
|
||||||
|
3. Set up initial TypeScript types and interfaces
|
||||||
|
4. Begin Phase 1 implementation
|
||||||
|
5. Create Storybook stories alongside implementation
|
||||||
Reference in New Issue
Block a user