gp-grid-core 0.1.1 → 0.1.4

package/README.md

@@ -1,362 +1,423 @@
-# gp-grid-core
-
-A framework-agnostic TypeScript library for building high-performance data grids with virtual scrolling, supporting 150,000+ rows with ease.
-
-## Philosophy
-
-**gp-grid-core** is built on three core principles:
-
-### 1. Slot-Based Virtual Scrolling
-
-Instead of rendering all rows, the grid maintains a pool of reusable "slots" (DOM containers) that are recycled as users scroll. This approach:
-
-- Renders only visible rows plus a small overscan buffer
-- Recycles DOM elements instead of creating/destroying them
-- Maintains consistent performance regardless of dataset size
-
-### 2. Instruction-Based Architecture
-
-The core emits declarative **instructions** (commands) that describe what the UI should do, rather than manipulating the DOM directly. This pattern:
-
-- Keeps the core framework-agnostic (works with React, Vue, Svelte, vanilla JS)
-- Enables batched updates for optimal rendering performance
-- Provides a clean separation between logic and presentation
-
-### 3. DataSource Abstraction
-
-Data fetching is abstracted through a `DataSource` interface, supporting both:
-
-- **Client-side**: All data loaded in memory, with local sorting/filtering
-- **Server-side**: Data fetched on-demand from an API with server-side operations
-
-## Installation
-
-npm/pnpm/yarn
-
-```bash
-pnpm add gp-grid-core
-```
-
-## Architecture Overview
-
-### GridCore
-
-The main orchestrator class that manages:
-
-- Viewport tracking and scroll synchronization
-- Slot pool lifecycle (create, assign, move, destroy)
-- Data fetching and caching
-- Sort and filter state
-
-```typescript
-import { GridCore, createClientDataSource } from "gp-grid-core";
-
-const dataSource = createClientDataSource(myData);
-
-const grid = new GridCore({
-  columns: [
-    { field: "name", cellDataType: "text", width: 150 },
-    { field: "age", cellDataType: "number", width: 80 },
-  ],
-  dataSource,
-  rowHeight: 36,
-  headerHeight: 40,
-  overscan: 3,
-});
-
-// Subscribe to instructions
-grid.onBatchInstruction((instructions) => {
-  // Handle UI updates based on instructions
-  instructions.forEach((instruction) => {
-    switch (instruction.type) {
-      case "CREATE_SLOT":
-        // Create a new row container
-        break;
-      case "ASSIGN_SLOT":
-        // Assign row data to a slot
-        break;
-      case "MOVE_SLOT":
-        // Position slot via translateY
-        break;
-      // ... handle other instructions
-    }
-  });
-});
-
-// Initialize and start
-await grid.initialize();
-```
-
-### Managers
-
-GridCore includes specialized managers for complex behaviors:
-
-- **SelectionManager**: Handles cell selection, range selection, keyboard navigation
-- **FillManager**: Implements Excel-like fill handle drag operations
-
-### Instruction Types
-
-The core emits these instruction types:
-
-| Instruction | Description |
-|-------------|-------------|
-| `CREATE_SLOT` | Create a new slot in the DOM pool |
-| `DESTROY_SLOT` | Remove a slot from the pool |
-| `ASSIGN_SLOT` | Assign row data to a slot |
-| `MOVE_SLOT` | Update slot position (translateY) |
-| `SET_ACTIVE_CELL` | Update active cell highlight |
-| `SET_SELECTION_RANGE` | Update selection range |
-| `START_EDIT` / `STOP_EDIT` | Toggle edit mode |
-| `COMMIT_EDIT` | Commit edited value |
-| `UPDATE_HEADER` | Update header with sort state |
-| `DATA_LOADING` / `DATA_LOADED` / `DATA_ERROR` | Data fetch lifecycle |
-
-## Data Sources
-
-### Client-Side Data Source
-
-For datasets that can be loaded entirely in memory. Sorting and filtering are performed client-side.
-
-```typescript
-import { createClientDataSource } from "gp-grid-core";
-
-interface Person {
-  id: number;
-  name: string;
-  age: number;
-  email: string;
-}
-
-const data: Person[] = [
-  { id: 1, name: "Alice", age: 30, email: "alice@example.com" },
-  { id: 2, name: "Bob", age: 25, email: "bob@example.com" },
-  // ... more rows
-];
-
-const dataSource = createClientDataSource(data);
-```
-
-**With custom field accessor** (for nested properties):
-
-```typescript
-const dataSource = createClientDataSource(data, {
-  getFieldValue: (row, field) => {
-    // Custom logic for accessing nested fields
-    if (field === "address.city") {
-      return row.address?.city;
-    }
-    return row[field];
-  },
-});
-```
-
-### Server-Side Data Source
-
-For large datasets that require server-side pagination, sorting, and filtering.
-
-```typescript
-import { createServerDataSource, DataSourceRequest, DataSourceResponse } from "gp-grid-core";
-
-interface Person {
-  id: number;
-  name: string;
-  age: number;
-}
-
-const dataSource = createServerDataSource<Person>(async (request: DataSourceRequest) => {
-  // Build query parameters from request
-  const params = new URLSearchParams({
-    page: String(request.pagination.pageIndex),
-    pageSize: String(request.pagination.pageSize),
-  });
-
-  // Add sort parameters
-  if (request.sort && request.sort.length > 0) {
-    params.set("sortBy", request.sort.map(s => `${s.colId}:${s.direction}`).join(","));
-  }
-
-  // Add filter parameters
-  if (request.filter) {
-    Object.entries(request.filter).forEach(([field, value]) => {
-      params.set(`filter_${field}`, value);
-    });
-  }
-
-  // Fetch from your API
-  const response = await fetch(`/api/people?${params}`);
-  const data = await response.json();
-
-  return {
-    rows: data.items,
-    totalRows: data.totalCount,
-  };
-});
-```
-
-### DataSource Interface
-
-Both data source types implement this interface:
-
-```typescript
-interface DataSource<TData = Row> {
-  fetch(request: DataSourceRequest): Promise<DataSourceResponse<TData>>;
-}
-
-interface DataSourceRequest {
-  pagination: {
-    pageIndex: number;
-    pageSize: number;
-  };
-  sort?: SortModel[];
-  filter?: FilterModel;
-}
-
-interface DataSourceResponse<TData> {
-  rows: TData[];
-  totalRows: number;
-}
-```
-
-## Types Reference
-
-### ColumnDefinition
-
-```typescript
-interface ColumnDefinition {
-  field: string;                    // Property path in row data
-  colId?: string;                   // Unique column ID (defaults to field)
-  cellDataType: CellDataType;       // "text" | "number" | "boolean" | "date" | "object"
-  width: number;                    // Column width in pixels
-  headerName?: string;              // Display name (defaults to field)
-  editable?: boolean;               // Enable cell editing
-  cellRenderer?: string;            // Custom renderer key
-  editRenderer?: string;            // Custom edit renderer key
-  headerRenderer?: string;          // Custom header renderer key
-}
-```
-
-### Renderer Params
-
-When building framework adapters, these params are passed to custom renderers:
-
-```typescript
-interface CellRendererParams {
-  value: CellValue;
-  rowData: Row;
-  column: ColumnDefinition;
-  rowIndex: number;
-  colIndex: number;
-  isActive: boolean;
-  isSelected: boolean;
-  isEditing: boolean;
-}
-
-interface EditRendererParams extends CellRendererParams {
-  initialValue: CellValue;
-  onValueChange: (newValue: CellValue) => void;
-  onCommit: () => void;
-  onCancel: () => void;
-}
-
-interface HeaderRendererParams {
-  column: ColumnDefinition;
-  colIndex: number;
-  sortDirection?: SortDirection;
-  sortIndex?: number;
-  onSort: (direction: SortDirection | null, addToExisting: boolean) => void;
-}
-```
-
-## Creating a Framework Adapter
-
-To integrate gp-grid-core with any UI framework:
-
-1. **Subscribe to instructions** using `onBatchInstruction()`
-2. **Maintain UI state** by processing instructions
-3. **Render slots** based on the slot pool state
-4. **Forward user interactions** back to GridCore
-
-### Example: Minimal Adapter Pattern
-
-```typescript
-import { GridCore, GridInstruction } from "gp-grid-core";
-
-class MyGridAdapter {
-  private core: GridCore;
-  private slots: Map<string, SlotUIElement> = new Map();
-
-  constructor(options: GridCoreOptions) {
-    this.core = new GridCore(options);
-    
-    // Process instructions to update UI
-    this.core.onBatchInstruction((instructions) => {
-      this.processInstructions(instructions);
-      this.render();
-    });
-  }
-
-  private processInstructions(instructions: GridInstruction[]) {
-    for (const instr of instructions) {
-      switch (instr.type) {
-        case "CREATE_SLOT":
-          this.slots.set(instr.slotId, this.createSlotElement());
-          break;
-        case "DESTROY_SLOT":
-          this.slots.delete(instr.slotId);
-          break;
-        case "ASSIGN_SLOT":
-          const slot = this.slots.get(instr.slotId);
-          if (slot) {
-            slot.rowIndex = instr.rowIndex;
-            slot.rowData = instr.rowData;
-          }
-          break;
-        case "MOVE_SLOT":
-          const moveSlot = this.slots.get(instr.slotId);
-          if (moveSlot) {
-            moveSlot.translateY = instr.translateY;
-          }
-          break;
-      }
-    }
-  }
-
-  // Handle scroll events
-  onScroll(scrollTop: number, scrollLeft: number, width: number, height: number) {
-    this.core.setViewport(scrollTop, scrollLeft, width, height);
-  }
-
-  // Handle cell click
-  onCellClick(row: number, col: number, modifiers: { shift: boolean; ctrl: boolean }) {
-    this.core.selection.startSelection({ row, col }, modifiers);
-  }
-
-  async initialize() {
-    await this.core.initialize();
-  }
-}
-```
-
-## API Reference
-
-### GridCore Methods
-
-| Method | Description |
-|--------|-------------|
-| `initialize()` | Initialize grid and load initial data |
-| `setViewport(scrollTop, scrollLeft, width, height)` | Update viewport on scroll/resize |
-| `setSort(colId, direction, addToExisting)` | Set column sort |
-| `setFilter(colId, value)` | Set column filter |
-| `startEdit(row, col)` | Start editing a cell |
-| `commitEdit()` | Commit current edit |
-| `cancelEdit()` | Cancel current edit |
-| `refresh()` | Refetch data from source |
-| `getRowCount()` | Get total row count |
-| `getRowData(rowIndex)` | Get data for a specific row |
-
-### GridCore Properties
-
-| Property | Description |
-|----------|-------------|
-| `selection` | SelectionManager instance |
-| `fill` | FillManager instance |
+# gp-grid-core 🏁 🏎️
+
+A framework-agnostic TypeScript library for building high-performance data grids with high (millions) number of rows with ease.
+
+## Table of Contents
+
+- [Philosophy](#philosophy)
+- [Installation](#installation)
+- [Architecture Overview](#architecture-overview)
+- [Data Sources](#data-sources)
+- [Types Reference](#types-reference)
+- [Creating a Framework Adapter](#creating-a-framework-adapter)
+- [API Reference](#api-reference)
+- [Donations](#donations)
+
+## Available implementations
+
+- [**gp-grid-react**](https://www.npmjs.com/package/gp-grid-react) | Official
+
+## Philosophy
+
+**gp-grid-core** is built on three core principles:
+
+### 1. Slot-Based Virtual Scrolling
+
+Instead of rendering all rows, the grid maintains a pool of reusable "slots" (DOM containers) that are recycled as users scroll. This approach:
+
+- Renders only visible rows plus a small overscan buffer
+- Recycles DOM elements instead of creating/destroying them
+- Maintains consistent performance regardless of dataset size
+
+### 2. Instruction-Based Architecture
+
+The core emits declarative **instructions** (commands) that describe what the UI should do, rather than manipulating the DOM directly. This pattern:
+
+- Keeps the core framework-agnostic (works with React, Vue, Svelte, vanilla JS)
+- Enables batched updates for optimal rendering performance
+- Provides a clean separation between logic and presentation
+
+### 3. DataSource Abstraction
+
+Data fetching is abstracted through a `DataSource` interface, supporting both:
+
+- **Client-side**: All data loaded in memory, with local sorting/filtering
+- **Server-side**: Data fetched on-demand from an API with server-side operations
+
+## Installation
+
+npm/pnpm/yarn
+
+```bash
+pnpm add gp-grid-core
+```
+
+## Architecture Overview
+
+### GridCore
+
+The main orchestrator class that manages:
+
+- Viewport tracking and scroll synchronization
+- Slot pool lifecycle (create, assign, move, destroy)
+- Data fetching and caching
+- Sort and filter state
+
+```typescript
+import { GridCore, createClientDataSource } from "gp-grid-core";
+
+const dataSource = createClientDataSource(myData);
+
+const grid = new GridCore({
+  columns: [
+    { field: "name", cellDataType: "text", width: 150 },
+    { field: "age", cellDataType: "number", width: 80 },
+  ],
+  dataSource,
+  rowHeight: 36,
+  headerHeight: 40,
+  overscan: 3,
+});
+
+// Subscribe to instructions
+grid.onBatchInstruction((instructions) => {
+  // Handle UI updates based on instructions
+  instructions.forEach((instruction) => {
+    switch (instruction.type) {
+      case "CREATE_SLOT":
+        // Create a new row container
+        break;
+      case "ASSIGN_SLOT":
+        // Assign row data to a slot
+        break;
+      case "MOVE_SLOT":
+        // Position slot via translateY
+        break;
+      // ... handle other instructions
+    }
+  });
+});
+
+// Initialize and start
+await grid.initialize();
+```
+
+### Managers
+
+GridCore includes specialized managers for complex behaviors:
+
+- **SelectionManager**: Handles cell selection, range selection, keyboard navigation
+- **FillManager**: Implements Excel-like fill handle drag operations
+
+### Instruction Types
+
+The core emits these instruction types:
+
+| Instruction                                   | Description                       |
+| --------------------------------------------- | --------------------------------- |
+| `CREATE_SLOT`                                 | Create a new slot in the DOM pool |
+| `DESTROY_SLOT`                                | Remove a slot from the pool       |
+| `ASSIGN_SLOT`                                 | Assign row data to a slot         |
+| `MOVE_SLOT`                                   | Update slot position (translateY) |
+| `SET_ACTIVE_CELL`                             | Update active cell highlight      |
+| `SET_SELECTION_RANGE`                         | Update selection range            |
+| `START_EDIT` / `STOP_EDIT`                    | Toggle edit mode                  |
+| `COMMIT_EDIT`                                 | Commit edited value               |
+| `UPDATE_HEADER`                               | Update header with sort state     |
+| `DATA_LOADING` / `DATA_LOADED` / `DATA_ERROR` | Data fetch lifecycle              |
+
+## Data Sources
+
+### Client-Side Data Source
+
+For datasets that can be loaded entirely in memory. Sorting and filtering are performed client-side.
+
+```typescript
+import { createClientDataSource } from "gp-grid-core";
+
+interface Person {
+  id: number;
+  name: string;
+  age: number;
+  email: string;
+}
+
+const data: Person[] = [
+  { id: 1, name: "Alice", age: 30, email: "alice@example.com" },
+  { id: 2, name: "Bob", age: 25, email: "bob@example.com" },
+  // ... more rows
+];
+
+const dataSource = createClientDataSource(data);
+```
+
+**With custom field accessor** (for nested properties):
+
+```typescript
+const dataSource = createClientDataSource(data, {
+  getFieldValue: (row, field) => {
+    // Custom logic for accessing nested fields
+    if (field === "address.city") {
+      return row.address?.city;
+    }
+    return row[field];
+  },
+});
+```
+
+### Server-Side Data Source
+
+For large datasets that require server-side pagination, sorting, and filtering.
+
+```typescript
+import {
+  createServerDataSource,
+  DataSourceRequest,
+  DataSourceResponse,
+} from "gp-grid-core";
+
+interface Person {
+  id: number;
+  name: string;
+  age: number;
+}
+
+const dataSource = createServerDataSource<Person>(
+  async (request: DataSourceRequest) => {
+    // Build query parameters from request
+    const params = new URLSearchParams({
+      page: String(request.pagination.pageIndex),
+      pageSize: String(request.pagination.pageSize),
+    });
+
+    // Add sort parameters
+    if (request.sort && request.sort.length > 0) {
+      params.set(
+        "sortBy",
+        request.sort.map((s) => `${s.colId}:${s.direction}`).join(","),
+      );
+    }
+
+    // Add filter parameters
+    if (request.filter) {
+      Object.entries(request.filter).forEach(([field, value]) => {
+        params.set(`filter_${field}`, value);
+      });
+    }
+
+    // Fetch from your API
+    const response = await fetch(`/api/people?${params}`);
+    const data = await response.json();
+
+    return {
+      rows: data.items,
+      totalRows: data.totalCount,
+    };
+  },
+);
+```
+
+### DataSource Interface
+
+Both data source types implement this interface:
+
+```typescript
+interface DataSource<TData = Row> {
+  fetch(request: DataSourceRequest): Promise<DataSourceResponse<TData>>;
+}
+
+interface DataSourceRequest {
+  pagination: {
+    pageIndex: number;
+    pageSize: number;
+  };
+  sort?: SortModel[];
+  filter?: FilterModel;
+}
+
+interface DataSourceResponse<TData> {
+  rows: TData[];
+  totalRows: number;
+}
+```
+
+## Types Reference
+
+### ColumnDefinition
+
+```typescript
+interface ColumnDefinition {
+  field: string; // Property path in row data
+  colId?: string; // Unique column ID (defaults to field)
+  cellDataType: CellDataType; // "text" | "number" | "boolean" | "date" | "object"
+  width: number; // Column width in pixels
+  headerName?: string; // Display name (defaults to field)
+  editable?: boolean; // Enable cell editing
+  cellRenderer?: string; // Custom renderer key
+  editRenderer?: string; // Custom edit renderer key
+  headerRenderer?: string; // Custom header renderer key
+}
+```
+
+### Renderer Params
+
+When building framework adapters, these params are passed to custom renderers:
+
+```typescript
+interface CellRendererParams {
+  value: CellValue;
+  rowData: Row;
+  column: ColumnDefinition;
+  rowIndex: number;
+  colIndex: number;
+  isActive: boolean;
+  isSelected: boolean;
+  isEditing: boolean;
+}
+
+interface EditRendererParams extends CellRendererParams {
+  initialValue: CellValue;
+  onValueChange: (newValue: CellValue) => void;
+  onCommit: () => void;
+  onCancel: () => void;
+}
+
+interface HeaderRendererParams {
+  column: ColumnDefinition;
+  colIndex: number;
+  sortDirection?: SortDirection;
+  sortIndex?: number;
+  onSort: (direction: SortDirection | null, addToExisting: boolean) => void;
+}
+```
+
+## Creating a Framework Adapter
+
+To integrate gp-grid-core with any UI framework:
+
+1. **Subscribe to instructions** using `onBatchInstruction()`
+2. **Maintain UI state** by processing instructions
+3. **Render slots** based on the slot pool state
+4. **Forward user interactions** back to GridCore
+
+### Example: Minimal Adapter Pattern
+
+```typescript
+import { GridCore, GridInstruction } from "gp-grid-core";
+
+class MyGridAdapter {
+  private core: GridCore;
+  private slots: Map<string, SlotUIElement> = new Map();
+
+  constructor(options: GridCoreOptions) {
+    this.core = new GridCore(options);
+
+    // Process instructions to update UI
+    this.core.onBatchInstruction((instructions) => {
+      this.processInstructions(instructions);
+      this.render();
+    });
+  }
+
+  private processInstructions(instructions: GridInstruction[]) {
+    for (const instr of instructions) {
+      switch (instr.type) {
+        case "CREATE_SLOT":
+          this.slots.set(instr.slotId, this.createSlotElement());
+          break;
+        case "DESTROY_SLOT":
+          this.slots.delete(instr.slotId);
+          break;
+        case "ASSIGN_SLOT":
+          const slot = this.slots.get(instr.slotId);
+          if (slot) {
+            slot.rowIndex = instr.rowIndex;
+            slot.rowData = instr.rowData;
+          }
+          break;
+        case "MOVE_SLOT":
+          const moveSlot = this.slots.get(instr.slotId);
+          if (moveSlot) {
+            moveSlot.translateY = instr.translateY;
+          }
+          break;
+      }
+    }
+  }
+
+  // Handle scroll events
+  onScroll(
+    scrollTop: number,
+    scrollLeft: number,
+    width: number,
+    height: number,
+  ) {
+    this.core.setViewport(scrollTop, scrollLeft, width, height);
+  }
+
+  // Handle cell click
+  onCellClick(
+    row: number,
+    col: number,
+    modifiers: { shift: boolean; ctrl: boolean },
+  ) {
+    this.core.selection.startSelection({ row, col }, modifiers);
+  }
+
+  async initialize() {
+    await this.core.initialize();
+  }
+}
+```
+
+## API Reference
+
+### GridCore Methods
+
+| Method                                              | Description                           |
+| --------------------------------------------------- | ------------------------------------- |
+| `initialize()`                                      | Initialize grid and load initial data |
+| `setViewport(scrollTop, scrollLeft, width, height)` | Update viewport on scroll/resize      |
+| `setSort(colId, direction, addToExisting)`          | Set column sort                       |
+| `setFilter(colId, value)`                           | Set column filter                     |
+| `startEdit(row, col)`                               | Start editing a cell                  |
+| `commitEdit()`                                      | Commit current edit                   |
+| `cancelEdit()`                                      | Cancel current edit                   |
+| `refresh()`                                         | Refetch data from source              |
+| `getRowCount()`                                     | Get total row count                   |
+| `getRowData(rowIndex)`                              | Get data for a specific row           |
+
+### GridCore Properties
+
+| Property    | Description               |
+| ----------- | ------------------------- |
+| `selection` | SelectionManager instance |
+| `fill`      | FillManager instance      |
+
+## Donations
+
+Keeping this library requires effort and passion, I'm a full time engineer employed on other project and I'm trying my best to keep this work free! For all the features. 
+
+If you think this project helped you achieve your goals, it's hopefully worth a beer! 🍻
+
+<div align="center">
+
+### Paypal
+
+[![Paypal QR Code](../../public/images/donazione_paypal.png "Paypal QR Code donation")](https://www.paypal.com/donate/?hosted_button_id=XCNMG6BR4ZMLY)
+
+[https://www.paypal.com/donate/?hosted_button_id=XCNMG6BR4ZMLY](https://www.paypal.com/donate/?hosted_button_id=XCNMG6BR4ZMLY)
+
+### Bitcoin
+
+[![Bitcoin QR Donation](../../public/images/bc1qcukwmzver59eyqq442xyzscmxavqjt568kkc9m.png "Bitcoin QR Donation")](bitcoin:bc1qcukwmzver59eyqq442xyzscmxavqjt568kkc9m)
+
+bitcoin:bc1qcukwmzver59eyqq442xyzscmxavqjt568kkc9m
+
+### Lightning Network
+
+[![Lightning Network QR Donation](../../public/images/lightning.png "Lightning Network QR Donation")](lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhx6rpvanhjetdvfjhyvf4xs0xu5p7)
+
+lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhx6rpvanhjetdvfjhyvf4xs0xu5p7
+
+</div>