argent-grid 0.1.0

package/demo-app/src/app/demo-page/demo-page.component.ts

@@ -0,0 +1,366 @@
+import { Component, OnInit, OnDestroy, AfterViewInit, ViewChild, ChangeDetectorRef } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { ArgentGridModule, ArgentGridComponent } from 'argent-grid';
+import { GridApi, ColDef, IRowNode } from 'argent-grid';
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  role: string;
+  salary: number;
+  salaryTrend: number[];
+  location: string;
+  startDate: string;
+  performance: number;
+}
+
+@Component({
+  selector: 'app-demo-page',
+  standalone: true,
+  imports: [CommonModule, ArgentGridModule],
+  templateUrl: './demo-page.component.html',
+  styleUrls: ['./demo-page.component.css'],
+})
+export class DemoPageComponent implements OnInit, AfterViewInit, OnDestroy {
+  @ViewChild(ArgentGridComponent) gridComponent!: ArgentGridComponent<Employee>;
+
+  rowData: Employee[] = [];
+  renderTime = 0;
+  canvasFrameTime = 0;
+  fps = 0;
+  isLoading = false;
+  rowCount = 100000;
+  isGrouped = false;
+  isFloatingFilterShown = true;
+  isBenchmarking = false;
+  isMasterDetail = false;
+  isPivotMode = false;
+  isSideBarVisible = true;
+  isFiltered = false;
+  benchmarkResults: any = null;
+
+  columnDefs: ColDef<Employee>[] = [
+    { field: 'id', headerName: 'ID', width: 80, sortable: true, filter: 'number' },
+    { field: 'name', headerName: 'Name', width: 200, sortable: true, filter: 'text' },
+    { field: 'department', headerName: 'Department', width: 180, sortable: true, filter: 'text', rowGroup: false },
+    { field: 'role', headerName: 'Role', width: 250, filter: 'text' },
+    {
+      field: 'salary',
+      headerName: 'Salary',
+      width: 120,
+      sortable: true,
+      filter: 'number',
+      valueFormatter: (params: any) => `$${params.value?.toLocaleString()}`,
+    },
+    {
+      field: 'salaryTrend',
+      headerName: 'Salary Trend',
+      width: 150,
+      sparklineOptions: {
+        type: 'area',
+        area: {
+          fill: 'rgba(74, 222, 128, 0.2)',
+          stroke: '#4ade80',
+          strokeWidth: 2
+        }
+      }
+    },
+    { field: 'location', headerName: 'Location', width: 150, filter: 'text' },
+    { field: 'startDate', headerName: 'Start Date', width: 130, filter: 'date' },
+    {
+      field: 'performance',
+      headerName: 'Performance',
+      width: 120,
+      filter: 'number',
+      cellRenderer: (params: any) => {
+        const value = params.value;
+        const color = value >= 80 ? '#22c55e' : value >= 60 ? '#eab308' : '#ef4444';
+        return `<span style="color: ${color}; font-weight: bold; padding: 4px 8px; background: ${color}20; border-radius: 4px;">${value}%</span>`;
+      },
+    },
+  ];
+
+  gridOptions: any = {
+    floatingFilter: true,
+    enableRangeSelection: true,
+    sideBar: true,
+    autoGroupColumnDef: {
+      headerName: 'Organization',
+      width: 250,
+      pinned: 'left'
+    }
+  };
+
+  private gridApi?: GridApi<Employee>;
+  private fpsInterval?: number;
+  private lastFrameTime = 0;
+  private fpsUpdateTimer = 0;
+
+  constructor(
+    private cdr: ChangeDetectorRef
+  ) {}
+
+  ngOnInit(): void {
+    this.loadData(100000);
+    this.startFPSCounter();
+  }
+
+  ngAfterViewInit(): void {
+    // Grid is ready after view init
+  }
+
+  toggleGrouping(): void {
+    this.isGrouped = !this.isGrouped;
+    this.columnDefs = this.columnDefs.map(col => {
+      if (col.field === 'department') {
+        return { ...col, rowGroup: this.isGrouped };
+      }
+      return col;
+    });
+    
+    if (this.gridApi) {
+      this.gridApi.setColumnDefs(this.columnDefs);
+      this.gridApi.onFilterChanged(); // Trigger re-processing
+    }
+
+    this.cdr.detectChanges();
+  }
+
+  toggleFloatingFilter(): void {
+    this.isFloatingFilterShown = !this.isFloatingFilterShown;
+    if (this.gridApi) {
+      this.gridApi.setGridOption('floatingFilter', this.isFloatingFilterShown);
+    }
+    this.cdr.detectChanges();
+  }
+
+  toggleMasterDetail(): void {
+    this.isMasterDetail = !this.isMasterDetail;
+    if (this.gridApi) {
+      this.gridApi.setGridOption('masterDetail', this.isMasterDetail);
+      this.gridApi.setGridOption('isRowMaster', (data: any) => data.id % 2 === 0);
+      this.gridApi.setRowData([...this.rowData]); // Force refresh
+    }
+    this.cdr.detectChanges();
+  }
+
+  togglePivotMode(): void {
+    this.isPivotMode = !this.isPivotMode;
+    if (this.gridApi) {
+      this.columnDefs = this.columnDefs.map(col => {
+        if (col.field === 'location') {
+          return { ...col, pivot: this.isPivotMode };
+        }
+        if (col.field === 'salary') {
+          return { ...col, aggFunc: 'sum' };
+        }
+        return col;
+      });
+      this.gridApi.setColumnDefs(this.columnDefs);
+      this.gridApi.setPivotMode(this.isPivotMode);
+    }
+    this.cdr.detectChanges();
+  }
+
+  toggleSideBar(): void {
+    this.isSideBarVisible = !this.isSideBarVisible;
+    if (this.gridApi) {
+      this.gridApi.setGridOption('sideBar', this.isSideBarVisible);
+    }
+    this.cdr.detectChanges();
+  }
+
+  toggleFilter(): void {
+    this.isFiltered = !this.isFiltered;
+    if (this.gridApi) {
+      if (this.isFiltered) {
+        this.gridApi.setFilterModel({
+          department: { filterType: 'text', type: 'contains', filter: 'Eng' }
+        });
+      } else {
+        this.gridApi.setFilterModel({});
+      }
+    }
+    this.cdr.detectChanges();
+  }
+
+  startFPSCounter(): void {
+    const countFPS = () => {
+      const now = performance.now();
+      let changed = false;
+
+      if (this.lastFrameTime) {
+        const delta = now - this.lastFrameTime;
+        
+        // Update metrics only every 500ms to reduce change detection cycles
+        if (now - this.fpsUpdateTimer > 500) {
+          const newFps = Math.round(1000 / delta);
+          if (newFps !== this.fps) {
+            this.fps = newFps;
+            changed = true;
+          }
+
+          // Update canvas frame time if available
+          if (this.gridComponent) {
+            const newFrameTime = Number(this.gridComponent.getLastFrameTime().toFixed(2));
+            if (newFrameTime !== this.canvasFrameTime) {
+              this.canvasFrameTime = newFrameTime;
+              changed = true;
+            }
+          }
+          
+          this.fpsUpdateTimer = now;
+        }
+      }
+      this.lastFrameTime = now;
+
+      // In zoneless mode, we manually trigger change detection for these async updates
+      if (changed) {
+        this.cdr.detectChanges();
+      }
+
+      this.fpsInterval = requestAnimationFrame(countFPS);
+    };
+    this.fpsInterval = requestAnimationFrame(countFPS);
+  }
+
+  runBenchmark(): void {
+    if (!this.gridApi || !this.gridComponent) return;
+    
+    this.isBenchmarking = true;
+    this.benchmarkResults = null;
+    this.cdr.detectChanges();
+    
+    const results = {
+      initialRender: 0,
+      scrollFrameAverage: 0,
+      selectionUpdateTime: 0,
+      groupingUpdateTime: 0,
+      totalTime: 0
+    };
+
+    const startTime = performance.now();
+
+    // 1. Initial render time (cached from last frame)
+    results.initialRender = this.gridComponent.getLastFrameTime();
+
+    // 2. Selection Update Time
+    const selStart = performance.now();
+    this.gridApi.selectAll();
+    // Wait for render cycle
+    setTimeout(() => {
+      results.selectionUpdateTime = Number((performance.now() - selStart).toFixed(2));
+      this.gridApi?.deselectAll();
+
+      // 3. Grouping Update Time (Toggle grouping twice)
+      const groupStart = performance.now();
+      if (!this.isGrouped) {
+        this.toggleGrouping(); // Turn on
+        setTimeout(() => {
+          this.toggleGrouping(); // Turn off
+          results.groupingUpdateTime = Number((performance.now() - groupStart).toFixed(2));
+          
+          startScrolling();
+        }, 100);
+      } else {
+        this.toggleGrouping(); // Turn off
+        setTimeout(() => {
+          this.toggleGrouping(); // Turn on
+          results.groupingUpdateTime = Number((performance.now() - groupStart).toFixed(2));
+          
+          startScrolling();
+        }, 100);
+      }
+
+      // 4. Scroll performance (programmatic scroll)
+      const startScrolling = () => {
+        const frameTimes: number[] = [];
+        let scrollCount = 0;
+        const totalScrollFrames = 30;
+        const viewport = this.gridComponent.viewportRef.nativeElement;
+
+        const runScroll = () => {
+          if (scrollCount < totalScrollFrames) {
+            viewport.scrollTop += 100;
+            frameTimes.push(this.gridComponent.getLastFrameTime());
+            scrollCount++;
+            requestAnimationFrame(runScroll);
+          } else {
+                      // Finished scroll
+                      results.scrollFrameAverage = Number((frameTimes.reduce((a, b) => a + b, 0) / frameTimes.length).toFixed(2));
+                      results.totalTime = Number((performance.now() - startTime).toFixed(2));
+                      this.benchmarkResults = results;
+                      this.isBenchmarking = false;
+                      
+                      // Scroll back up
+                      viewport.scrollTop = 0;
+                      this.cdr.detectChanges();
+                    }
+                  };        
+        requestAnimationFrame(runScroll);
+      };
+    }, 100);
+  }
+
+  loadData(count: number): void {
+    this.isLoading = true;
+    const startTime = performance.now();
+
+    const departments = ['Engineering', 'Sales', 'Marketing', 'HR', 'Finance', 'Operations', 'Support', 'Product'];
+    const roles = [
+      'Software Engineer', 'Senior Engineer', 'Staff Engineer', 'Principal Engineer',
+      'Engineering Manager', 'Sales Rep', 'Account Executive', 'Marketing Manager',
+      'HR Specialist', 'Financial Analyst', 'Operations Manager', 'Support Specialist',
+      'Product Manager', 'Senior PM', 'Director',
+    ];
+    const locations = ['New York', 'San Francisco', 'London', 'Singapore', 'Tokyo', 'Berlin', 'Remote'];
+
+    const data: Employee[] = [];
+
+    for (let i = 0; i < count; i++) {
+      const dept = departments[Math.floor(Math.random() * departments.length)];
+      const role = roles[Math.floor(Math.random() * roles.length)];
+      const location = locations[Math.floor(Math.random() * locations.length)];
+
+      data.push({
+        id: i + 1,
+        name: `Employee ${i + 1}`,
+        department: dept,
+        role: `${dept} - ${role}`,
+        salary: Math.floor(Math.random() * 150000) + 50000,
+        salaryTrend: Array.from({ length: 10 }, () => Math.floor(Math.random() * 100)),
+        location,
+        startDate: new Date(Date.now() - Math.random() * 5 * 365 * 24 * 60 * 60 * 1000).toISOString().split('T')[0],
+        performance: Math.floor(Math.random() * 40) + 60,
+      });
+    }
+
+    setTimeout(() => {
+      this.rowData = data;
+      const endTime = performance.now();
+      this.renderTime = Math.round(endTime - startTime);
+      this.rowCount = count;
+      this.isLoading = false;
+
+      this.cdr.detectChanges();
+      console.log(`Loaded ${count} rows in ${this.renderTime}ms`);
+    }, 100);
+  }
+
+  onGridReady(api: GridApi<Employee>): void {
+    this.gridApi = api;
+    (window as any).gridApi = api;
+    console.log('Grid ready:', api);
+  }
+
+  onRowClicked(event: { data: Employee; node: IRowNode<Employee> }): void {
+    console.log('Row clicked:', event.data);
+  }
+
+  ngOnDestroy(): void {
+    if (this.fpsInterval) {
+      cancelAnimationFrame(this.fpsInterval);
+    }
+  }
+}

package/demo-app/src/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>ArgentGrid - Canvas-Based High-Performance Grid Demo</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="Live demo of ArgentGrid - Canvas-based Angular grid with 1M+ rows and 60fps scrolling">
+  <link rel="icon" type="image/x-icon" href="favicon.ico">
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; font-family: 'Inter', sans-serif; background: #0f0f23; }
+  </style>
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>

package/demo-app/src/main.ts

@@ -0,0 +1,6 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { appConfig } from './app/app.config';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, appConfig)
+  .catch((err) => console.error(err));

package/demo-app/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": "./dist/out-tsc",
+    "strict": false,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "sourceMap": true,
+    "declaration": false,
+    "experimentalDecorators": true,
+    "moduleResolution": "bundler",
+    "importHelpers": true,
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022", "dom"],
+    "paths": {}
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.spec.ts"],
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  }
+}

package/ng-package.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "dist",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  },
+  "allowedNonPeerDependencies": ["exceljs"]
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "argent-grid",
+  "version": "0.1.0",
+  "description": "A free, high-performance alternative to AG Grid Enterprise",
+  "author": "hainzhao",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HainanZhao/ArgentGrid.git"
+  },
+  "keywords": [
+    "angular",
+    "grid",
+    "data-grid",
+    "ag-grid",
+    "table",
+    "canvas",
+    "performance"
+  ],
+  "peerDependencies": {
+    "@angular/cdk": "^18.0.0",
+    "@angular/common": "^18.0.0",
+    "@angular/core": "^18.0.0"
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0",
+    "tslib": "^2.6.0"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^18.0.0",
+    "@angular/animations": "^18.0.0",
+    "@angular/cdk": "^18.0.0",
+    "@angular/cli": "^18.0.0",
+    "@angular/common": "^18.0.0",
+    "@angular/compiler": "^18.0.0",
+    "@angular/compiler-cli": "^18.0.0",
+    "@angular/core": "^18.0.0",
+    "@angular/platform-browser": "^18.0.0",
+    "@angular/platform-browser-dynamic": "^18.0.0",
+    "@types/exceljs": "^1.3.2",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "jsdom": "^26.0.0",
+    "ng-packagr": "^18.0.0",
+    "rxjs": "~7.8.0",
+    "typescript": "~5.4.2",
+    "vite": "^6.0.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "build:watch": "ng-packagr -p ng-package.json -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "cd demo-app && npx playwright test",
+    "lint": "eslint src/**/*.ts",
+    "clean": "rm -rf dist"
+  }
+}

package/plan.md

@@ -0,0 +1,131 @@
+# ArgentGrid Project Plan
+
+> **Goal:** Build a free, high-performance alternative to AG Grid Enterprise using Canvas rendering and a headless logic layer.
+
+## ⚖️ AG Grid Comparison Matrix
+
+| Feature Category | AG Grid Community | AG Grid Enterprise | **ArgentGrid (Current)** |
+| :--- | :--- | :--- | :--- |
+| **Rendering Engine** | DOM-based | DOM-based | **Canvas-based (GPU Opt)** |
+| **Data Volume Limit** | ~100k rows | Millions (SSRM) | **1M+ rows (Client-side)** |
+| **Row Models** | Client-side only | Client, **SSRM, Infinite** | **Client-side only** |
+| **Custom Components** | Header, Cell, Filter | Header, Cell, Filter | **Hardcoded / String-based** |
+| **Sorting & Filtering**| Yes (Basic) | Yes (Advanced) | **Yes (Client-side)** |
+| **Filter Types** | Text, Num, Date | + **Set Filter**, Multi | **Text, Num, Date, Boolean** |
+| **Row Grouping** | No | Yes | **Yes (Hierarchical)** |
+| **Aggregation** | No | Yes | **Yes (Sum/Avg/Min/Max/Cnt)** |
+| **Pivoting** | No | Yes | **Yes (Basic)** |
+| **Master/Detail** | No | Yes | **Yes (Basic)** |
+| **Tree Data** | Basic | Advanced | **Planned (Phase IV)** |
+| **Selection** | Row only | Row + **Range** | **Row + Range (Basic)** |
+| **Excel Export** | No (CSV only) | True .xlsx | **True .xlsx & CSV** |
+| **Context Menu** | No | Yes | **Yes (Basic)** |
+| **Header Menus** | Basic | Advanced | **Yes (Sort, Hide, Pin)** |
+| **Side Bar** | No | Yes | **Yes (Columns, Filters)** |
+| **Keyboard Nav** | Yes (Cell-level) | Yes (Advanced) | **Basic (Editing only)** |
+| **State Persistence** | No | Yes | **No** |
+| **Integrated Charts** | No | Yes | **Planned (Phase IV)** |
+| **Sparklines** | No | Yes | **Yes (Area, Line, Bar)** |
+| **Accessibility (ARIA)**| Yes | Yes | **Partial (Headers only)** |
+
+
+## 🚀 Status: Phase V Complete - Transitioning to Enterprise Maturity
+
+ArgentGrid has met its initial implementation goals. We are now entering a maturity phase to bridge the final gaps with AG Grid Enterprise, including Server-Side Row Models and deep Angular component integration.
+
+---
+
+## 🗺️ Roadmap
+
+### Phase I: API Extraction & Architecture ✅
+- [x] Map AG Grid `GridOptions`, `ColDef`, and `GridApi` interfaces.
+- [x] Bootstrap Angular library project.
+- [x] Hybrid Architecture: DOM Headers + Canvas Viewport.
+- [x] Virtual Scrolling engine (60fps at 1M rows).
+
+### Phase II: Core Grid Logic ✅
+- [x] Client-side Sorting.
+- [x] Advanced Filtering (Text, Number, Date, Boolean).
+- [x] Cell Editing (Inline with valueParser/valueSetter).
+- [x] Selection (Single/Multi with Checkbox support).
+- [x] Column & Row Pinning (Left/Right, Top/Bottom).
+
+### Phase III: Enterprise Features ✅
+- [x] **Row Grouping**: Hierarchical data with expand/collapse.
+- [x] **Aggregation**: sum, avg, min, max, count, and custom functions.
+- [x] **Export**: CSV and HTML-based Excel export.
+
+### Phase IV: UI Interactivity & UX ✅
+- [x] **Column Re-ordering (Drag & Drop)**:
+    - [x] Implement drag handle in DOM headers.
+    - [x] Sidebar column re-ordering via tool panel.
+    - [x] Update `columnDefs` and `GridApi` on drop.
+    - [x] Animate column movement on Canvas.
+- [x] **Column Resizing**:
+    - [x] Add resize handles to DOM header cells.
+    - [x] Implement drag-to-resize logic.
+    - [x] Update `columnDefs` and `GridApi` on resize completion.
+- [x] **Header Menus**:
+    - [x] Add "hamburger" or "ellipsis" menu to column headers.
+    - [x] Support Sort, Filter, and "Hide Column" actions from menu.
+    - [x] Integrate with existing `GridApi`.
+- [ ] **Context Menus**:
+    - [x] Right-click cell interaction.
+    - [x] Default actions: Copy, Export, Reset Columns.
+    - [ ] Support for user-defined custom context menu items.
+- [x] **Excel-like Range Selection**:
+    - [x] Drag-to-select rectangular ranges of cells.
+    - [x] Visual selection box rendered on Canvas.
+    - [x] "Copy with Headers" support.
+
+### Phase V: Advanced Data Analysis ✅
+- [x] **Pivoting**: Excel-style pivot tables (cross-tabulation).
+- [x] **Tool Panels & Sidebars**: Dedicated UI for column management and global filtering.
+- [x] **Master/Detail**: Expandable rows to reveal nested grids or custom templates.
+- [x] **True Excel Export**: Implementation using `exceljs` for native `.xlsx` files with styles.
+- [x] **Integrated Sparklines**: Mini-charts rendered directly in cells using the Canvas engine.
+
+### Phase VI: UX Polish & Extensibility 🚧
+- [ ] **Custom Angular Components**: Support for using real Angular components as cell renderers/editors inside the Canvas.
+- [x] **Context Menu API**: Full implementation of `getContextMenuItems` to allow dynamic, user-defined menu actions.
+- [ ] **Advanced Keyboard Navigation**: Full cell-to-cell navigation (Arrows, Tab, Page Up/Down) matching AG Grid behavior.
+- [ ] **State Persistence**: Save/Restore user grid state (order, width, filters) to LocalStorage.
+- [ ] **Advanced Filtering**: Set Filter (Excel-style checkboxes) and Multi-Filter support.
+
+### Phase VII: Enterprise Row Models
+- [ ] **Server-Side Row Model (SSRM)**: Loading and aggregating millions of rows on the server.
+- [ ] **Infinite Row Model**: Standard infinite scrolling for large flat datasets.
+- [ ] **Tree Data**: Advanced hierarchical structures with path-based navigation.
+
+### Phase VIII: Final Polish
+- [ ] **Advanced Accessibility**: Full ARIA compliance and screen reader optimization for the Canvas viewport.
+- [ ] **Touch & Mobile Support**: Optimized interactions for mobile devices.
+- [ ] **Web Workers**: Move data processing to background threads for even better responsiveness.
+
+## 🎉 Project Milestone: CORE PHASES COMPLETE!
+
+ArgentGrid has reached its initial goal of providing a high-performance, Enterprise-compatible Angular data grid.
+
+### Future Considerations
+- [ ] **Web Workers**: Move data processing to background threads for even better responsiveness.
+- [ ] **Touch & Mobile Support**: Optimized interactions for mobile devices.
+- [ ] **Integrated Charts**: User-creatable charts directly from range selections.
+- [ ] **Tree Data**: Advanced hierarchical structures with path-based navigation.
+
+
+---
+
+## 🛠️ Implementation Strategy
+
+1. **Hybrid Rendering Strategy**:
+   - Keep headers as DOM elements for easy Drag-and-Drop implementation (using Angular CDK) and native browser menus.
+   - Maintain the data viewport on Canvas for infinite performance.
+   - Synchronize horizontal scroll between DOM header and Canvas viewport.
+
+2. **State Management**:
+   - Use a centralized `GridService` to maintain the source of truth.
+   - Trigger partial Canvas repaints on state changes to maximize performance.
+
+3. **Test-Driven Development (TDD)**:
+   - Every new UI feature must have a corresponding Playwright E2E test in the `demo-app`.
+       - Logic changes must be verified by Vitest unit tests in `src/lib/services/grid.service.spec.ts`.

package/setup-vitest.ts

@@ -0,0 +1,18 @@
+import { vi } from 'vitest';
+import { TestBed } from '@angular/core/testing';
+import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
+import { provideExperimentalZonelessChangeDetection } from '@angular/core';
+
+// Initialize Angular test environment
+TestBed.initTestEnvironment(
+  BrowserDynamicTestingModule,
+  platformBrowserDynamicTesting(),
+  {
+    provide: [
+      provideExperimentalZonelessChangeDetection()
+    ]
+  }
+);
+
+// Setup fake timers
+vi.useFakeTimers();

package/src/lib/argent-grid.module.ts

@@ -0,0 +1,21 @@
+import { NgModule } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { DragDropModule } from '@angular/cdk/drag-drop';
+import { ArgentGridComponent } from './components/argent-grid.component';
+import { AgGridCompatibilityDirective } from './directives/ag-grid-compatibility.directive';
+
+@NgModule({
+  declarations: [
+    ArgentGridComponent,
+    AgGridCompatibilityDirective
+  ],
+  imports: [
+    CommonModule,
+    DragDropModule
+  ],
+  exports: [
+    ArgentGridComponent,
+    AgGridCompatibilityDirective
+  ]
+})
+export class ArgentGridModule {}