argent-grid 0.1.0 → 0.3.0

package/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dirty]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build library
+        run: npm run build
+
+      - name: Build Storybook
+        run: npm run build-storybook
+
+      - name: Run unit tests with coverage
+        run: npm run test:coverage
+
+      - name: Run E2E tests
+        run: |
+          npx playwright install chromium --with-deps
+          npm run test:e2e
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/coverage-final.json
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  code-quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Lint
+        run: npm run lint

package/.github/workflows/pages.yml

@@ -7,12 +7,12 @@ on:
 
     paths:
       - 'src/**'
-      - 'demo-app/**'
       - '.github/workflows/pages.yml'
       - 'package.json'
       - 'package-lock.json'
       - 'ng-package.json'
       - 'tsconfig.json'
+      - 'tsconfig.storybook.json'
   workflow_dispatch:
 
 permissions:
@@ -39,21 +39,15 @@ jobs:
         with:
           node-version: '20'
           cache: 'npm'
-          cache-dependency-path: './package-lock.json'
 
       - name: Install root dependencies
-        run: npm ci
+        run: npm ci --legacy-peer-deps
 
       - 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: Build Storybook
+        run: npm run build-storybook
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
@@ -61,8 +55,8 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: './demo-app/dist/argent-grid-demo/browser'
+          path: './storybook-static'
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

package/.storybook/main.ts

@@ -0,0 +1,20 @@
+import type { StorybookConfig } from '@storybook/angular';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-actions',
+    '@storybook/addon-controls',
+    '@chromatic-com/storybook',
+  ],
+  framework: {
+    name: '@storybook/angular',
+    options: {},
+  },
+  docs: {
+    autodocs: false,
+  },
+};
+
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,18 @@
+import type { Preview } from '@storybook/angular';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    layout: 'fullscreen',
+    docs: {
+      disable: true,
+    },
+  },
+};
+
+export default preview;

package/.storybook/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": "../dist-storybook",
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "lib": ["ES2022", "dom"],
+    "strict": false,
+    "noImplicitAny": false,
+    "noImplicitReturns": false,
+    "noFallthroughCasesInSwitch": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "useDefineForClassFields": false,
+    "importHelpers": true,
+    "paths": {}
+  },
+  "include": ["../src/**/*.ts", "*.ts"],
+  "exclude": ["../node_modules", "../dist", "../dist-storybook", "../src/**/*.spec.ts"]
+}

package/AGENTS.md

@@ -30,7 +30,7 @@
 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)
+5. **TDD approach** - Tests written before implementation (400+ passing tests)
 
 ## Project Structure
 
@@ -62,7 +62,7 @@ ArgentGrid/
 
 ## Implementation Status
 
-### ✅ Phase I, II, III & IV - COMPLETE! 🚀
+### ✅ Phase I - VI - COMPLETE! 🚀
 
 | Feature | Status | Notes |
 |---------|--------|-------|
@@ -71,26 +71,25 @@ ArgentGrid/
 | 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 |
+| Filtering | ✅ | Text, number, date, boolean, **Set Filter** |
 | Floating Filters | ✅ | Quick headers filters with clear button |
-| Row Grouping | ✅ | Hierarchical, Auto Group column support |
+| Row Grouping | ✅ | Hierarchical, Auto Group column, `groupDefaultExpanded` |
 | 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 |
+| Selection | ✅ | Checkbox, multi-select, header checkbox, **Range Selection** |
 | Menus | ✅ | Header menus (ellipsis) and Context menus (right-click) |
-| Guard Rail Tests | ✅ | 7+ passing Playwright E2E scenarios |
+| Sparklines | ✅ | Line, Bar, Area charts in cells |
+| Guard Rail Tests | ✅ | 10+ passing Playwright E2E scenarios |
 
-### ⏳ Phase V (Future)
+### ⏳ Phase VII (Next)
 
 | 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 |
+| Tooltips | High | High-performance tooltips for cells/headers |
+| Server-Side Row Model | Medium | SSRM for millions of rows |
+| Infinite Row Model | Medium | Lazy loading data |
+| Keyboard Navigation | Low | Advanced cell-to-cell navigation |
 
 ## Technical Details
 
@@ -121,13 +120,45 @@ api.setFilterModel({
 api.setGridOption('floatingFilter', true);
 ```
 
+### Canvas Renderer Architecture & Invariants
+
+**CRITICAL — read before touching `canvas-renderer.ts` or `argent-grid.component.ts`:**
+
+#### Render Pipeline
+
+| Method | Behaviour | When to Use |
+|--------|-----------|-------------|
+| `renderFrame()` | Synchronous immediate paint. Bypasses damage gate. | Forced repaints only (tests, initial mount). |
+| `render()` | Calls `markAllDirty()` + `scheduleRender()`. | All event-driven repaints (`gridStateChanged$`, etc.). |
+| `scheduleRender()` | Queues one `requestAnimationFrame`. No-op if `!hasDamage()`. Uses `nextRenderPending` coalescing so concurrent calls queue at most one follow-up frame. | Called internally by `render()`. |
+
+#### Damage Gate
+
+`scheduleRender()` checks `damageTracker.hasDamage()` **before queuing any rAF**. `doRender()` also checks it as a secondary guard. If nothing is dirty, no frame is ever painted. Always call `markAllDirty()` (or `invalidateRow()`) before `scheduleRender()` if you want a repaint.
+
+#### applyTransaction Throttling — Client Responsibility
+
+The renderer does **not** throttle `applyTransaction`. High-frequency callers (e.g., streaming stories) must throttle upstream using RxJS (`throttleTime`, `bufferTime`, etc.). Do **not** re-introduce `renderThrottleMs` or any setTimeout delay inside the renderer.
+
+#### ResizeObserver Feedback Loop — NEVER set `canvas.style.width/height` in JS
+
+The canvas sits `position: sticky` inside an `overflow: auto` viewport div. If you assign `canvas.style.width` or `canvas.style.height` in JS, it changes the layout size of the canvas, which changes the scrollable content size of the viewport, which re-fires the ResizeObserver — **infinitely**. This produces a blank, ever-growing canvas.
+
+**Rule:** CSS owns the canvas layout size (`width: 100%; height: 100%; display: block` on `.argent-grid-canvas`). JS (`updateCanvasSize`) only sets the pixel buffer — `canvas.width` and `canvas.height` — for device pixel ratio scaling. Never touch `canvas.style.*` dimensions.
+
+#### blitState / setLastCanvas
+
+The `blitState.setLastCanvas()` call was removed from `doRender()`. Copying the entire canvas to an offscreen buffer every frame caused ~7 ms GC spikes at 60 fps. The blit/diff feature is not used by any current code path. Do not re-add `setLastCanvas()` inside the render loop.
+
 ### Agent Tooling & Verification
 
-Agents working on this repository should utilize the following tools for high-quality contributions:
+Agents working on this repository MUST follow these verification steps to ensure stability and code quality:
 
-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.
+1.  **Mandatory Tests**: Run `npm run test` (Vitest) to verify core logic and `npm run test:e2e` (Playwright) for visual/interactive verification.
+2.  **Linting**: Run `npm run lint:fix` before concluding a task to ensure consistent code style and fix automated issues.
+3.  **Finalization**: Before completing a significant feature or fix, run `npm run build-storybook`. **Note:** This command is slow; only execute it once everything is finalized to ensure the full production build of stories succeeds.
+4.  **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.
+5.  **TS Strict Mode**: The library is verified against a strict TypeScript configuration. Ensure all property accesses (especially dynamic ones in tests) are type-safe.
 
 ## Known Issues / TODOs
 
@@ -139,21 +170,33 @@ Agents working on this repository should utilize the following tools for high-qu
 
 4. **Range Selection** - Visual selection box on canvas is not yet implemented.
 
-## Next Steps (Phase V - Advanced Analysis)
+## Next Steps (Phase VII - Enterprise Row Models & Polish)
+
+1. **Tooltips**
+   - Hover detection on Canvas coordinates
+   - Support for `tooltipField` and `tooltipValueGetter`
+   - Custom tooltip components (DOM-based overlay)
 
-1. **Excel-like Range Selection**
-   - Drag-to-select multiple cells
-   - Visual selection overlay on Canvas
-   - Copy-paste range support
+2. **Enterprise Row Models**
+   - SSRM and Infinite Row Model support
 
-2. **Full-featured Excel Export**
-   - Use `exceljs` for native `.xlsx` files with styles/colors.
+## Recent Changes (Phase VII Highlights)
 
-3. **Column Virtualization**
-   - Only render visible columns in CanvasRenderer.renderColGroup.
+- **canvas-renderer** fix: eliminate ResizeObserver feedback loop — CSS now owns canvas layout size; JS only sets pixel buffer (`canvas.width/height`)
+- **canvas-renderer** fix: add damage gate in `scheduleRender()` — no rAF queued when nothing dirty, eliminating 60 fps idle CPU waste
+- **canvas-renderer** fix: add `nextRenderPending` coalescing flag — prevents dropped renders when `scheduleRender()` is called while a frame is already in-flight
+- **canvas-renderer** fix: remove `setLastCanvas()` from `doRender()` — was causing ~7 ms GC spike per frame
+- **canvas-renderer** refactor: remove `renderThrottleMs` / `setRenderThrottle()` entirely — clients throttle `applyTransaction` upstream via RxJS
+- **argent-grid.component** fix: remove redundant `renderFrame()` call from ResizeObserver callback (now handled by `setViewportDimensions` internally)
+- **streaming-wrapper** refactor: remove `renderThrottleMs` input binding
 
-## Recent Changes (Phase IV Highlights)
+## Recent Changes (Phase VI Highlights)
 
+- **9e2f1a3** fix: resolve infinite flickering in Storybook via `setGridOption` change check
+- **a4d2b1c** feat: implement `groupDefaultExpanded` support in GridService
+- **f3e4d5b** fix: align header menus correctly relative to grid container
+- **c2b1a0d** fix: resolve Auto Group column persistence bug when removing grouping
+- **d1e2f3a** fix: allow manual group collapse when `groupDefaultExpanded` is set
 - **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

package/README.md

@@ -141,71 +141,88 @@ npm run test:coverage # With coverage
 npm run lint
 ```
 
-## 🎨 Demo App Development
+## 🎨 Storybook 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.
+ArgentGrid uses **Storybook** for component development, documentation, and visual testing. Each feature (Sorting, Grouping, Theming, etc.) is documented as an isolated story.
 
-**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 Storybook
 
-### Run Demo App
+```bash
+# Start Storybook dev server
+npm run storybook
+```
+
+Open [http://localhost:6006](http://localhost:6006) to view the stories and interact with the grid.
+
+### Build Storybook
 
 ```bash
-cd demo-app
-npm install
-npm start
+# Build static Storybook site
+npm run build-storybook
 ```
 
-Open [http://localhost:4200](http://localhost:4200) to view the demo.
+Output will be in the `./storybook-static` directory.
 
 ### 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/`).
+ArgentGrid uses Playwright for end-to-end testing against the Storybook stories. These tests verify visual rendering, interactivity (dragging, resizing), and complex logic (filtering, grouping).
 
 **Run Tests:**
 ```bash
-cd demo-app
-npx playwright test
+# Run all E2E tests
+npm run test:e2e
 ```
 
 This will execute the **Feature Guard Rails** suite which verifies:
 - Row Grouping & Expansion
 - Floating Filters
-- Cell Editing (Enter/Escape/Tab)
+- Cell Editing
 - Column Pinning & Scroll Sync
 - Column Re-ordering (Drag & Drop)
 
+### Visual Regression Testing
+
+Since ArgentGrid renders its core data area using HTML5 Canvas, we use **Visual Regression Testing** to ensure consistent rendering and catch pixel-level regressions.
+
+**Run Visual Tests:**
+```bash
+npx playwright test e2e/visual.spec.ts
+```
+
+**Updating Snapshots:**
+If you have made intentional UI changes (e.g., changed selection colors, refined border logic, or adjusted header padding) and the visual tests fail, you must update the baseline snapshots:
+
+```bash
+npx playwright test e2e/visual.spec.ts --update-snapshots
+```
+
+*Note: Ensure your local environment is clean and Storybook is correctly built before updating snapshots. Baseline snapshots are committed to the repository to serve as the source of truth for CI.*
+
 ### Performance Benchmarking
 
-ArgentGrid includes a built-in benchmarking suite to measure rendering efficiency, scroll performance, and memory overhead.
+ArgentGrid includes a benchmarking suite to measure rendering efficiency and scroll performance under heavy load (100,000+ rows).
 
 **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.
+1. Start Storybook: `npm run storybook`
+2. Open [http://localhost:6006](http://localhost:6006)
+3. Navigate to **ArgentGrid / Benchmark**
+4. View real-time **ms frame** metrics and a detailed report.
 
 **Option 2: Automated (CLI)**
-To run the automated performance test and see results in your terminal:
+To run the automated performance test:
 ```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+ | ✅ |
+-------------------------------------------
+🚀 ArgentGrid Performance Benchmark Results
+-------------------------------------------
+Initial Render      : 2.60ms
+Avg Scroll Frame    : 1.55ms
+Selection All       : 103.70ms
+Grouping Toggle     : 147.10ms
+Total Test Time     : 495.60ms
+-------------------------------------------
 
 ## License
 

package/angular.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "argent-grid": {
+      "projectType": "library",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "lib",
+      "architect": {
+        "build": {
+          "builder": "ng-packagr:build",
+          "options": {
+            "project": "ng-package.json"
+          },
+          "configurations": {
+            "production": {
+              "tsConfig": "tsconfig.lib.json"
+            },
+            "development": {
+              "tsConfig": "tsconfig.lib.json"
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "tsConfig": "tsconfig.spec.json",
+            "karmaConfig": "karma.conf.js"
+          }
+        }
+      }
+    },
+    "argent-grid-storybook": {
+      "projectType": "library",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "lib",
+      "architect": {
+        "storybook": {
+          "builder": "@storybook/angular:start-storybook",
+          "options": {
+            "configDir": ".storybook",
+            "tsConfig": ".storybook/tsconfig.json",
+            "compodoc": false,
+            "port": 6006
+          }
+        },
+        "build-storybook": {
+          "builder": "@storybook/angular:build-storybook",
+          "options": {
+            "configDir": ".storybook",
+            "tsConfig": ".storybook/tsconfig.json",
+            "compodoc": false,
+            "outputDir": "storybook-static"
+          }
+        }
+      }
+    }
+  },
+  "cli": {
+    "analytics": false
+  }
+}

package/biome.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "noExcessiveCognitiveComplexity": "off",
+        "noBannedTypes": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "off",
+        "useIterableCallbackReturn": "off",
+        "useAdjacentOverloadSignatures": "off"
+      },
+      "style": {
+        "useImportType": "off",
+        "noNonNullAssertion": "off",
+        "noParameterProperties": "off"
+      },
+      "correctness": {
+        "noUnusedFunctionParameters": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "es5"
+    },
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": true
+    }
+  },
+  "html": {
+    "parser": {
+      "interpolation": true
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.html"],
+      "linter": { "enabled": false },
+      "formatter": { "enabled": false }
+    }
+  ],
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/demo-app/e2e/selection-screenshot.spec.ts

@@ -0,0 +1,20 @@
+import { test, expect } from '@playwright/test';
+
+test('Take selection mode screenshot', async ({ page }) => {
+  // Start demo app
+  await page.goto('http://localhost:4200');
+  
+  // Wait for grid to load
+  await page.waitForSelector('argent-grid', { timeout: 30000 });
+  
+  // Enable selection mode (click the selection toggle if available)
+  // Or navigate to a story with selection enabled
+  
+  // Take screenshot
+  await page.screenshot({ 
+    path: 'e2e/screenshots/selection-mode.png',
+    fullPage: true 
+  });
+  
+  console.log('Screenshot saved to e2e/screenshots/selection-mode.png');
+});