argent-grid 0.1.0 → 0.2.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

@@ -125,9 +125,9 @@ api.setGridOption('floatingFilter', true);
 
 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`).
+1.  **Playwright Skill**: Used for running the root-level E2E suite (`npm run test:e2e`) against Storybook stories.
 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.
+3.  **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
 

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');
+});