argent-grid 0.1.0

package/.github/workflows/pages.yml

@@ -0,0 +1,68 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+    paths:
+      - 'src/**'
+      - 'demo-app/**'
+      - '.github/workflows/pages.yml'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'ng-package.json'
+      - 'tsconfig.json'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: './package-lock.json'
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Build ArgentGrid library
+        run: npm run build
+
+      - name: Install demo app dependencies
+        working-directory: ./demo-app
+        run: npm install
+
+      - name: Build demo app
+        working-directory: ./demo-app
+        run: npm run build:gh-pages
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './demo-app/dist/argent-grid-demo/browser'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/AGENTS.md

@@ -0,0 +1,179 @@
+# ArgentGrid - Agent Context File
+
+> **Purpose:** This file preserves critical project context for AI agents across sessions. Read this first when starting work.
+
+## Project Overview
+
+**ArgentGrid** is a free, high-performance alternative to AG Grid Enterprise built with Angular 18+. It uses canvas rendering for the data viewport to achieve 60fps performance with 100,000+ rows.
+
+**Repository:** https://github.com/HainanZhao/ArgentGrid
+
+**License:** MIT
+
+## Core Architecture
+
+### Hybrid Rendering Approach
+```
+┌─────────────────────────────────────┐
+│  Header Layer (DOM-based)           │  ← Accessibility, CSS styling
+├─────────────────────────────────────┤
+│  Canvas Layer (Data Viewport)       │  ← High-performance rendering
+│  - Virtual scrolling                │
+│  - Only renders visible rows        │
+│  - 100k+ rows at 60fps              │
+└─────────────────────────────────────┘
+```
+
+### Key Design Decisions
+
+1. **Canvas for data viewport** - DOM-based grids struggle with 10k+ rows; canvas handles 100k+
+2. **DOM headers** - Keep headers as DOM elements for accessibility and CSS styling
+3. **AG Grid API compatibility** - 1:1 TypeScript definitions so users can switch by changing imports
+4. **Headless logic layer** - GridService handles all data operations independently of rendering
+5. **TDD approach** - Tests written before implementation (209 passing tests)
+
+## Project Structure
+
+```
+ArgentGrid/
+├── src/
+│   ├── lib/
+│   │   ├── types/
+│   │   │   └── ag-grid-types.ts       # AG Grid compatible TypeScript definitions
+│   │   ├── components/
+│   │   │   ├── argent-grid.component.ts
+│   │   │   └── argent-grid.component.spec.ts
+│   │   ├── services/
+│   │   │   ├── grid.service.ts        # Headless logic layer
+│   │   │   └── grid.service.spec.ts
+│   │   ├── rendering/
+│   │   │   └── canvas-renderer.ts     # Canvas painting engine
+│   │   ├── directives/
+│   │   │   └── ag-grid-compatibility.directive.ts
+│   │   └── argent-grid.module.ts
+│   └── public-api.ts                   # Public API exports
+├── package.json                        # Angular 18, TypeScript 5.4
+├── ng-package.json                     # ng-packagr config
+├── tsconfig.json                       # TypeScript config
+├── vitest.config.ts                    # Vitest test config
+├── setup-vitest.ts                     # Vitest zoneless setup
+└── README.md
+```
+
+## Implementation Status
+
+### ✅ Phase I, II, III & IV - COMPLETE! 🚀
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| AG Grid TypeScript definitions | ✅ | Full GridOptions, ColDef, GridApi |
+| Angular 18 library setup | ✅ | ng-packagr build |
+| Canvas renderer | ✅ | Virtual scrolling, row buffering, pinning support |
+| GridService (headless logic) | ✅ | $O(1)$ row lookups, reactive state |
+| Sorting | ✅ | Client-side, multi-column, menu-driven |
+| Filtering | ✅ | Text, number, date, boolean |
+| Floating Filters | ✅ | Quick headers filters with clear button |
+| Row Grouping | ✅ | Hierarchical, Auto Group column support |
+| Cell Editing | ✅ | Enter/Escape/Tab navigation, group prevention |
+| Column Pinning | ✅ | Left/right sticky columns (Canvas + Header sync) |
+| Column Re-ordering | ✅ | Drag & Drop via Angular CDK |
+| Selection | ✅ | Checkbox, multi-select, header checkbox |
+| Menus | ✅ | Header menus (ellipsis) and Context menus (right-click) |
+| Guard Rail Tests | ✅ | 7+ passing Playwright E2E scenarios |
+
+### ⏳ Phase V (Future)
+
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Excel-like Range Selection | High | Drag-to-select rectangular ranges |
+| Column Virtualization | Medium | Horizontal scrolling for 50+ columns |
+| Pivot Tables | Low | Complex but powerful |
+| Tree Data | Low | Parent/child relationships |
+| Master/Detail | Low | Nested grids |
+| Integrated Sparklines | Low | Mini-charts in cells |
+
+## Technical Details
+
+### Key Interfaces
+
+```typescript
+// Main component
+<argent-grid
+  [columnDefs]="columnDefs"
+  [rowData]="rowData"
+  [gridOptions]="gridOptions"
+  (gridReady)="onGridReady($event)"
+  (rowClicked)="onRowClicked($event)">
+</argent-grid>
+```
+
+### GridService API & Reactivity
+
+The grid uses a reactive state model. programmtic changes to filters, sorts, or options via the API are emitted through `gridStateChanged$`, ensuring the Canvas and DOM layers stay synchronized.
+
+```typescript
+// Programmatic filter
+api.setFilterModel({
+  department: { filterType: 'text', type: 'contains', filter: 'Eng' }
+});
+
+// Programmatic option toggle
+api.setGridOption('floatingFilter', true);
+```
+
+### Agent Tooling & Verification
+
+Agents working on this repository should utilize the following tools for high-quality contributions:
+
+1.  **Playwright Skill**: Used for running the `demo-app` E2E suite (`npm run test:e2e`).
+2.  **Computer Use (Browser Automation)**: Highly recommended for visual verification of Canvas rendering. Always verify menu positioning, scrolling alignment, and interactive states (like editing) in a live browser before concluding a task.
+3.  **TS Strict Mode**: The library is verified against the `demo-app`'s strict TypeScript configuration. Ensure all property accesses (especially dynamic ones in tests) are type-safe.
+
+## Known Issues / TODOs
+
+1. **Row grouping tests** - Skipped in Vitest due to service instance sharing. Playwright E2E tests now cover this logic in a real browser.
+
+2. **Column virtualization** - Currently renders all columns; should virtualize horizontal scrolling for wide grids.
+
+3. **Context Menu Customization** - Currently only supports fixed default items (Copy, Export, Reset).
+
+4. **Range Selection** - Visual selection box on canvas is not yet implemented.
+
+## Next Steps (Phase V - Advanced Analysis)
+
+1. **Excel-like Range Selection**
+   - Drag-to-select multiple cells
+   - Visual selection overlay on Canvas
+   - Copy-paste range support
+
+2. **Full-featured Excel Export**
+   - Use `exceljs` for native `.xlsx` files with styles/colors.
+
+3. **Column Virtualization**
+   - Only render visible columns in CanvasRenderer.renderColGroup.
+
+## Recent Changes (Phase IV Highlights)
+
+- **be1273d** fix: resolve editor update issues and Escape key handling
+- **b44ebbd** fix: synchronize floating filter inputs with GridApi
+- **90cca11** feat: implement Auto Group column and AG Grid-compatible grouping
+- **9c7b162** feat: implement column re-ordering via Drag & Drop
+- **72cddb8** feat: implement Header Menus (Sort, Hide, Pin)
+- **ce0139e** feat: implement Context Menus on Canvas
+- **6b540aa** test: add comprehensive Playwright guard rail suite
+
+
+## Important Notes
+
+- **DO NOT use Web Workers** - Deprioritized. Current virtual scrolling handles 100k rows efficiently without the complexity.
+
+- **Keep AG Grid API compatibility** - This is the main differentiator. Users should be able to switch by changing imports.
+
+- **Test-first approach** - Continue writing tests before implementation for new features.
+
+- **Angular 18+** - Do not downgrade. The library targets Angular 18+.
+
+## Contact / Repository
+
+- **GitHub:** https://github.com/HainanZhao/ArgentGrid
+- **Issues:** https://github.com/HainanZhao/ArgentGrid/issues

package/README.md

@@ -0,0 +1,222 @@
+# ArgentGrid
+
+A **free, high-performance** alternative to AG Grid Enterprise built with Angular and Canvas rendering.
+
+## 🌐 Live Demo
+
+Check out the interactive demo: **[https://hainanzhao.github.io/ArgentGrid/](https://hainanzhao.github.io/ArgentGrid/)**
+
+The demo showcases:
+- Canvas-based rendering with 100,000+ rows
+- Virtual scrolling
+- Sorting, filtering, and selection
+- Cell editing
+- Column and row pinning
+- Excel/CSV export
+
+## Features
+
+- 🚀 **High Performance**: Canvas-based rendering for 100,000+ rows at 60fps
+- 🎯 **AG Grid Compatible**: Drop-in replacement with 1:1 API compatibility
+- 📦 **Angular Native**: Built with Angular 18+ using modern best practices
+- 🧪 **TDD Developed**: Comprehensive test coverage with Vitest
+- 🎨 **Hybrid Architecture**: Canvas viewport + DOM headers for accessibility
+
+## ⚖️ Feature Parity
+
+For a detailed comparison with AG Grid and our development roadmap, see:
+**[plan](./plan.md)**
+
+## Installation
+
+```bash
+npm install argent-grid
+```
+
+## Requirements
+
+- Angular 18+
+- TypeScript 5.4+
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { ColDef } from 'argent-grid';
+
+interface RowData {
+  id: number;
+  name: string;
+  age: number;
+}
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <argent-grid
+      [columnDefs]="columnDefs"
+      [rowData]="rowData"
+      [rowHeight]="32"
+      height="600px">
+    </argent-grid>
+  `
+})
+export class AppComponent {
+  columnDefs: ColDef<RowData>[] = [
+    { colId: 'id', field: 'id', headerName: 'ID', width: 100 },
+    { colId: 'name', field: 'name', headerName: 'Name', width: 150 },
+    { colId: 'age', field: 'age', headerName: 'Age', width: 80, sortable: true }
+  ];
+
+  rowData: RowData[] = [
+    { id: 1, name: 'John Doe', age: 30 },
+    { id: 2, name: 'Jane Smith', age: 25 }
+  ];
+}
+```
+
+### Module Import
+
+```typescript
+import { NgModule } from '@angular/core';
+import { ArgentGridModule } from 'argent-grid';
+
+@NgModule({
+  imports: [
+    ArgentGridModule
+  ]
+})
+export class AppModule {}
+```
+
+## Architecture
+
+### Hybrid Rendering Approach
+
+```
+┌─────────────────────────────────────┐
+│  Header Layer (DOM-based)           │  ← Accessibility, Styling
+├─────────────────────────────────────┤
+│  Canvas Layer (Data Viewport)       │  ← High-performance rendering
+│  - 100,000+ rows                    │
+│  - 60fps scrolling                  │
+│  - Virtual scrolling                │
+└─────────────────────────────────────┘
+```
+
+### Core Components
+
+- **ArgentGridComponent**: Main grid component
+- **CanvasRenderer**: High-performance canvas painting engine
+- **GridService**: Headless logic layer for data management
+- **AgGridCompatibilityDirective**: AG Grid API compatibility layer
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test           # Run tests
+npm run test:watch # Watch mode
+npm run test:coverage # With coverage
+```
+
+### Lint
+
+```bash
+npm run lint
+```
+
+## 🎨 Demo App Development
+
+The repository includes a standalone Angular application for visual testing and performance benchmarking. It is configured to import `argent-grid` directly from the `src/` folder using TypeScript path mapping.
+
+**Why this is better:**
+- **No Build Step:** You don't need to run `npm run build` in the root every time you change the library.
+- **HMR / Live Reload:** Changes in `src/` are detected by the Angular dev-server, triggering an immediate browser refresh.
+- **Easier Debugging:** Sourcemaps point directly to your original library source code.
+
+### Run Demo App
+
+```bash
+cd demo-app
+npm install
+npm start
+```
+
+Open [http://localhost:4200](http://localhost:4200) to view the demo.
+
+### E2E Testing (Playwright)
+
+argent-grid uses Playwright for end-to-end testing of visual and interactive features (like Canvas rendering, dragging, and menu interactions).
+
+**Prerequisites:**
+The demo app must be running (`npm start` inside `demo-app/`).
+
+**Run Tests:**
+```bash
+cd demo-app
+npx playwright test
+```
+
+This will execute the **Feature Guard Rails** suite which verifies:
+- Row Grouping & Expansion
+- Floating Filters
+- Cell Editing (Enter/Escape/Tab)
+- Column Pinning & Scroll Sync
+- Column Re-ordering (Drag & Drop)
+
+### Performance Benchmarking
+
+ArgentGrid includes a built-in benchmarking suite to measure rendering efficiency, scroll performance, and memory overhead.
+
+**Option 1: Interactive (UI)**
+1. Start the demo app: `cd demo-app && npm start`
+2. Open [http://localhost:4200](http://localhost:4200)
+3. Click the **🚀 Benchmark** button in the header.
+4. View real-time **ms frame** metrics and a detailed report covering initial render, scrolling, and selection updates.
+
+**Option 2: Automated (CLI)**
+To run the automated performance test and see results in your terminal:
+```bash
+cd demo-app
+npx playwright test e2e/benchmark.spec.ts --reporter=list
+```
+
+## Performance Targets
+
+| Metric | Baseline | Target | Status |
+| :--- | :--- | :--- | :--- |
+| **Initial Render (100k rows)** | ~45ms | < 30ms | 🚀 (Optimizing) |
+| **Scroll Frame Time (avg)** | ~3.8ms | < 4ms | ✅ |
+| **Selection Update (All)** | ~12ms | < 20ms | ✅ (Damage Tracking) |
+| **Memory per 100k rows** | ~45MB | < 30MB | 🚀 (Optimizing) |
+| **Max Rows (60fps)** | 1,000,000+ | 1,000,000+ | ✅ |
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## Acknowledgments
+
+- [AG Grid](https://www.ag-grid.com/) for the API inspiration
+- [Glide Data Grid](https://github.com/hyperledger-labs/glide-data-grid) for canvas rendering approach
+- [TanStack Table](https://tanstack.com/table) for headless architecture concept

package/demo-app/README.md

@@ -0,0 +1,70 @@
+# ArgentGrid Demo App
+
+Live demo showcasing the canvas-based high-performance Angular grid.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev server
+npm start
+
+# Build for production
+npm run build
+
+# Build for GitHub Pages
+npm run build:gh-pages
+```
+
+## E2E Testing (Playwright)
+
+End-to-end tests are located in the `e2e/` folder. They verify critical visual and interactive features that cannot be easily tested with unit tests (like Canvas rendering and Drag & Drop).
+
+**Prerequisites:**
+Ensure the dev server is running (`npm start`).
+
+**Run All Tests:**
+```bash
+npx playwright test
+```
+
+**Run with UI:**
+```bash
+npx playwright test --ui
+```
+
+**Key Scenarios Covered:**
+- Row Grouping & Hierarchical Expansion
+- Floating Filters & Quick Clear
+- Inline Cell Editing (Enter/Escape/Tab)
+- Column Pinning (Sticky Columns)
+- Column Re-ordering via Drag & Drop
+
+## Demo Features
+
+- **100K rows** - Standard load test
+- **500K rows** - Heavy load test  
+- **1M rows** - Extreme stress test
+- **Real-time FPS** - Monitor rendering performance
+- **Canvas rendering** - Zero DOM overhead
+
+## Live Demo
+
+https://hainanzhao.github.io/ArgentGrid/
+
+## Tech Stack
+
+- Angular 18
+- Canvas 2D API
+- RequestAnimationFrame for 60fps
+- Zero dependencies beyond Angular
+
+## Performance Targets
+
+| Rows | Load Time | FPS | Memory |
+|------|-----------|-----|--------|
+| 100K | < 500ms | 60 | ~50MB |
+| 500K | < 2s | 60 | ~150MB |
+| 1M | < 5s | 55-60 | ~300MB |

package/demo-app/angular.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "argent-grid-demo": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": "dist/argent-grid-demo",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": [],
+            "tsConfig": "tsconfig.json",
+            "preserveSymlinks": true,
+            "sourceMap": true,
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "public"
+              }
+            ],
+            "styles": [],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "2MB"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "10kB",
+                  "maximumError": "20kB"
+                }
+              ],
+              "outputHashing": "all",
+              "sourceMap": true
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "argent-grid-demo:build:production"
+            },
+            "development": {
+              "buildTarget": "argent-grid-demo:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n"
+        }
+      }
+    }
+  },
+  "cli": {
+    "analytics": false
+  }
+}

package/demo-app/e2e/benchmark.spec.ts

@@ -0,0 +1,53 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('ArgentGrid Performance Benchmark', () => {
+  test('should run the benchmark and report results', async ({ page }) => {
+    // Navigate to the demo page
+    await page.goto('/', { waitUntil: 'networkidle' });
+
+    // Wait for the grid to be ready
+    await page.waitForSelector('argent-grid', { timeout: 10000 });
+
+    // Click the Benchmark button
+    console.log('Starting benchmark...');
+    await page.click('.btn-benchmark');
+
+    // Wait for benchmark to complete (isBenchmarking becomes false)
+    // The benchmark-results section appears when finished
+    await page.waitForSelector('.benchmark-results', { timeout: 30000 });
+
+    // Extract results
+    const results = await page.evaluate(() => {
+      const items = document.querySelectorAll('.result-item');
+      const data: Record<string, string> = {};
+      items.forEach(item => {
+        const label = item.querySelector('label')?.textContent?.replace(':', '') || 'unknown';
+        const value = item.querySelector('span')?.textContent || '0';
+        data[label] = value;
+      });
+      return data;
+    });
+
+    console.log('-------------------------------------------');
+    console.log('🚀 ArgentGrid Performance Benchmark Results');
+    console.log('-------------------------------------------');
+    Object.entries(results).forEach(([label, value]) => {
+      console.log(`${label.padEnd(20)}: ${value}`);
+    });
+    console.log('-------------------------------------------');
+
+    // Optional assertions based on targets
+    const initialRender = parseFloat(results['Initial Render']);
+    const scrollFrame = parseFloat(results['Avg Scroll Frame']);
+    
+    console.log(`Checking against targets...`);
+    console.log(`Initial Render: ${initialRender}ms (Target: < 30ms)`);
+    console.log(`Avg Scroll Frame: ${scrollFrame}ms (Target: < 4ms)`);
+
+    // We don't fail the test if targets aren't met yet, but we report it
+    if (initialRender > 30) console.warn('⚠️ Initial render is slower than target (30ms)');
+    if (scrollFrame > 4) console.warn('⚠️ Scroll frame time is slower than target (4ms)');
+
+    expect(results['Total Test Time']).toBeDefined();
+  });
+});