argent-grid 0.2.0 → 0.3.0

package/src/stories/Streaming.stories.ts

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/angular';
+import { moduleMetadata } from '@storybook/angular';
+import { StreamingWrapperComponent } from './streaming-wrapper.component';
+
+const meta: Meta<StreamingWrapperComponent> = {
+  title: 'Features/Streaming',
+  component: StreamingWrapperComponent,
+  decorators: [
+    moduleMetadata({
+      imports: [StreamingWrapperComponent],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<StreamingWrapperComponent>;
+
+export const LiveStockFeed: Story = {
+  args: {
+    updateFrequency: 100,
+    batchSize: 5,
+  },
+  render: (args) => ({
+    props: args,
+    template: `<app-streaming-wrapper [updateFrequency]="updateFrequency" [batchSize]="batchSize" />`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Simulates a live stock market feed. Updates are buffered and applied via applyTransaction at most twice per second (500ms throttle) for efficient rendering. Demonstrates high-performance row updates with the canvas engine.',
+      },
+    },
+  },
+};
+
+export const HighFrequencyStream: Story = {
+  args: {
+    updateFrequency: 50,
+    batchSize: 10,
+  },
+  render: (args) => ({
+    props: args,
+    template: `<app-streaming-wrapper [updateFrequency]="updateFrequency" [batchSize]="batchSize" />`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Stresses the grid with 20 updates per second (10 rows each), totaling 200 row updates per second. All updates are buffered and applied in batched transactions every 500ms. Shows the efficiency of the transaction API and canvas renderer.',
+      },
+    },
+  },
+};

package/src/stories/Theming.stories.ts

@@ -3,6 +3,14 @@ import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
 import type { Meta, StoryObj } from '@storybook/angular';
 import { moduleMetadata } from '@storybook/angular';
 import { ArgentGridComponent, ArgentGridModule, colorSchemeDark, themeQuartz } from '../public-api';
+import {
+  departmentValueFormatter,
+  locationValueFormatter,
+  roleValueFormatter,
+  STORY_DEPARTMENTS,
+  STORY_LOCATIONS,
+  STORY_ROLES,
+} from './story-utils';
 
 interface Employee {
   id: number;
@@ -30,9 +38,9 @@ export default meta;
 type Story = StoryObj<ArgentGridComponent<Employee>>;
 
 function generateStaticData(count: number): Employee[] {
-  const departments = ['Engineering', 'Sales', 'Marketing', 'HR', 'Finance'];
-  const roles = ['Engineer', 'Manager', 'Director', 'VP', 'Intern'];
-  const locations = ['New York', 'San Francisco', 'London', 'Singapore', 'Remote'];
+  const departments = STORY_DEPARTMENTS;
+  const roles = STORY_ROLES;
+  const locations = STORY_LOCATIONS;
 
   return Array.from({ length: count }, (_, i) => ({
     id: i + 1,
@@ -47,17 +55,22 @@ function generateStaticData(count: number): Employee[] {
 const columnDefs = [
   { field: 'id', headerName: 'ID', width: 80 },
   { field: 'name', headerName: 'Name', width: 200 },
-  { field: 'department', headerName: 'Department', width: 180 },
-  { field: 'role', headerName: 'Role', width: 250 },
+  {
+    field: 'department',
+    headerName: 'Department',
+    width: 180,
+    valueFormatter: departmentValueFormatter,
+  },
+  { field: 'role', headerName: 'Role', width: 250, valueFormatter: roleValueFormatter },
   { field: 'salary', headerName: 'Salary', width: 120 },
-  { field: 'location', headerName: 'Location', width: 150 },
+  { field: 'location', headerName: 'Location', width: 150, valueFormatter: locationValueFormatter },
 ];
 
 export const LightMode: Story = {
   args: {
     columnDefs,
     rowData: generateStaticData(50),
-    height: '400px',
+    height: 'calc(100vh - 60px)',
     width: '100%',
     theme: themeQuartz,
   },
@@ -74,7 +87,7 @@ export const DarkMode: Story = {
   args: {
     columnDefs,
     rowData: generateStaticData(50),
-    height: '400px',
+    height: 'calc(100vh - 60px)',
     width: '100%',
     theme: themeQuartz.withPart(colorSchemeDark),
   },
@@ -91,7 +104,7 @@ export const CompactMode: Story = {
   args: {
     columnDefs,
     rowData: generateStaticData(50),
-    height: '400px',
+    height: 'calc(100vh - 60px)',
     width: '100%',
     theme: themeQuartz.withParams({ rowHeight: 32, fontSize: 12, spacing: 4 }),
   },
@@ -108,7 +121,7 @@ export const CompactDarkMode: Story = {
   args: {
     columnDefs,
     rowData: generateStaticData(50),
-    height: '400px',
+    height: 'calc(100vh - 60px)',
     width: '100%',
     theme: themeQuartz
       .withParams({ rowHeight: 32, fontSize: 12, spacing: 4 })

package/src/stories/Tooltips.stories.ts

@@ -0,0 +1,381 @@
+import { BrowserModule } from '@angular/platform-browser';
+import type { Meta, StoryObj } from '@storybook/angular';
+import { moduleMetadata } from '@storybook/angular';
+import { ArgentGridComponent, ArgentGridModule, themeQuartz } from '../public-api';
+import {
+  departmentValueFormatter,
+  locationValueFormatter,
+  roleValueFormatter,
+  STORY_DEPARTMENTS,
+  STORY_LOCATIONS,
+  STORY_ROLES,
+} from './story-utils';
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  role: string;
+  salary: number;
+  location: string;
+  email: string;
+  phone: string;
+  startDate: string;
+  performance: number;
+  skills: string;
+  bio: string;
+  manager: string;
+  projects: number;
+  vacationDays: number;
+}
+
+const meta: Meta<ArgentGridComponent<Employee>> = {
+  title: 'Features/Tooltips',
+  component: ArgentGridComponent,
+  decorators: [
+    moduleMetadata({
+      imports: [ArgentGridModule, BrowserModule],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Cell Tooltips** — AG Grid-compatible `tooltipField` and `tooltipValueGetter` APIs. ' +
+          'Hover over a cell for 500ms to reveal the tooltip overlay.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<ArgentGridComponent<Employee>>;
+
+const departments = STORY_DEPARTMENTS;
+const roles = STORY_ROLES;
+const locations = STORY_LOCATIONS;
+const skills: Record<string, string> = {
+  Engineering: 'TypeScript, Angular, RxJS, Canvas API, WebGL',
+  Sales: 'CRM, Negotiation, Salesforce, Pipeline Management',
+  Marketing: 'SEO, Content Strategy, Google Analytics, A/B Testing',
+  HR: 'Recruiting, HRIS, Onboarding, Conflict Resolution',
+  Finance: 'Excel, SQL, Financial Modeling, SAP',
+  Design: 'Figma, Sketch, CSS, User Research, Prototyping',
+};
+const managers: Record<string, string> = {
+  Engineering: 'Alice Chen',
+  Sales: 'Bob Martinez',
+  Marketing: 'Carol White',
+  HR: 'David Park',
+  Finance: 'Eve Johnson',
+  Design: 'Frank Lee',
+};
+
+function generateData(count: number): Employee[] {
+  return Array.from({ length: count }, (_, i) => {
+    const dept = departments[i % departments.length];
+    const role = roles[i % roles.length];
+    const location = locations[i % locations.length];
+    return {
+      id: i + 1,
+      name: `Employee ${i + 1}`,
+      department: dept,
+      role,
+      salary: 50000 + (i % 10) * 8000 + departments.indexOf(dept) * 5000,
+      location,
+      email: `employee${i + 1}@company.com`,
+      phone: `+1-555-${String(1000 + i).slice(1)}-${String(5000 + i).slice(1)}`,
+      startDate: `202${i % 5}-${String((i % 12) + 1).padStart(2, '0')}-${String((i % 28) + 1).padStart(2, '0')}`,
+      performance: 60 + (i % 41),
+      skills: skills[dept],
+      bio: `${role} in ${dept} based in ${location}. ${i % 2 === 0 ? 'Team lead for Q4 initiative.' : 'Contributing to cross-functional projects.'}`,
+      manager: managers[dept],
+      projects: 1 + (i % 8),
+      vacationDays: 10 + (i % 16),
+    };
+  });
+}
+
+const sampleData = generateData(50);
+
+// ─── Story 1: tooltipField ────────────────────────────────────────────────────
+
+export const TooltipField: Story = {
+  args: {
+    columnDefs: [
+      { field: 'id', headerName: 'ID', width: 70 },
+      {
+        field: 'name',
+        headerName: 'Name',
+        width: 180,
+        tooltipField: 'bio',
+      },
+      {
+        field: 'department',
+        headerName: 'Department',
+        width: 160,
+        tooltipField: 'skills',
+        valueFormatter: departmentValueFormatter,
+      },
+      {
+        field: 'role',
+        headerName: 'Role',
+        width: 140,
+        tooltipField: 'manager',
+        valueFormatter: roleValueFormatter,
+      },
+      {
+        field: 'salary',
+        headerName: 'Salary',
+        width: 110,
+        tooltipField: 'salary',
+      },
+      {
+        field: 'location',
+        headerName: 'Location',
+        width: 150,
+        tooltipField: 'email',
+        valueFormatter: locationValueFormatter,
+      },
+    ],
+    rowData: sampleData,
+    height: 'calc(100vh - 60px)',
+    width: '100%',
+    theme: themeQuartz,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '**`tooltipField`** — the simplest tooltip API. Specify any field name and ' +
+          'its value will appear as the tooltip when hovering over cells in that column. ' +
+          'Hover over **Name** to see the employee bio, **Department** to see their skill set, ' +
+          "or **Role** to see their manager's name.",
+      },
+    },
+  },
+};
+
+// ─── Story 2: tooltipValueGetter ─────────────────────────────────────────────
+
+export const TooltipValueGetter: Story = {
+  args: {
+    columnDefs: [
+      { field: 'id', headerName: 'ID', width: 70 },
+      {
+        field: 'name',
+        headerName: 'Name',
+        width: 180,
+        tooltipValueGetter: ({ data }: { data: Employee }) =>
+          [
+            `👤 ${data.name}`,
+            `📧 ${data.email}`,
+            `📞 ${data.phone}`,
+            `🏢 Reports to: ${data.manager}`,
+          ].join('\n'),
+      },
+      {
+        field: 'department',
+        headerName: 'Department',
+        width: 160,
+        tooltipValueGetter: ({ data }: { data: Employee }) =>
+          `🏷 Department: ${data.department}\n🔧 Skills: ${data.skills}`,
+        valueFormatter: departmentValueFormatter,
+      },
+      {
+        field: 'salary',
+        headerName: 'Salary',
+        width: 110,
+        tooltipValueGetter: ({ value, data }: { value: number; data: Employee }) => {
+          const annual = value;
+          const monthly = Math.round(annual / 12).toLocaleString();
+          const daily = Math.round(annual / 260).toLocaleString();
+          return `💰 Annual:  $${annual.toLocaleString()}\n📆 Monthly: $${monthly}\n📅 Daily:   $${daily}`;
+        },
+      },
+      {
+        field: 'performance',
+        headerName: 'Performance',
+        width: 130,
+        tooltipValueGetter: ({ value, data }: { value: number; data: Employee }) => {
+          const stars = '★'.repeat(Math.round(value / 20)) + '☆'.repeat(5 - Math.round(value / 20));
+          const label =
+            value >= 90
+              ? 'Exceptional'
+              : value >= 75
+                ? 'Strong'
+                : value >= 60
+                  ? 'Meets Expectations'
+                  : 'Needs Improvement';
+          return `${stars}\n${value}/100 — ${label}\nProjects active: ${data.projects}`;
+        },
+      },
+      {
+        field: 'startDate',
+        headerName: 'Start Date',
+        width: 130,
+        tooltipValueGetter: ({ value, data }: { value: string; data: Employee }) => {
+          const start = new Date(value);
+          const now = new Date();
+          const months =
+            (now.getFullYear() - start.getFullYear()) * 12 + (now.getMonth() - start.getMonth());
+          const years = Math.floor(months / 12);
+          const rem = months % 12;
+          const tenure = years > 0 ? `${years}y ${rem}m` : `${rem} months`;
+          return `📅 Joined: ${value}\n⏱  Tenure: ${tenure}\n🏖  Vacation days: ${data.vacationDays}`;
+        },
+      },
+    ],
+    rowData: sampleData,
+    height: 'calc(100vh - 60px)',
+    width: '100%',
+    theme: themeQuartz,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '**`tooltipValueGetter`** — full control over tooltip content via a function. ' +
+          'Receives `{ value, data, node, column }` and returns a string (newlines supported). ' +
+          'Hover over **Name** for contact details, **Salary** for a pay breakdown, ' +
+          '**Performance** for a star-rating, or **Start Date** for tenure info.',
+      },
+    },
+  },
+};
+
+// ─── Story 3: Mixed (both APIs together) ─────────────────────────────────────
+
+export const MixedTooltips: Story = {
+  args: {
+    columnDefs: [
+      { field: 'id', headerName: 'ID', width: 70 },
+      {
+        field: 'name',
+        headerName: 'Name',
+        width: 180,
+        // tooltipValueGetter takes priority over tooltipField
+        tooltipField: 'bio',
+        tooltipValueGetter: ({ data }: { data: Employee }) =>
+          `👤 ${data.name}\n📧 ${data.email}\n📞 ${data.phone}`,
+      },
+      {
+        field: 'department',
+        headerName: 'Department',
+        width: 160,
+        // plain tooltipField
+        tooltipField: 'skills',
+        valueFormatter: departmentValueFormatter,
+      },
+      {
+        field: 'salary',
+        headerName: 'Salary',
+        width: 110,
+        tooltipValueGetter: ({ value }: { value: number }) =>
+          `Monthly: $${Math.round(value / 12).toLocaleString()}`,
+      },
+      {
+        field: 'performance',
+        headerName: 'Performance',
+        width: 130,
+        // no tooltip — hovering shows nothing
+      },
+      {
+        field: 'location',
+        headerName: 'Location',
+        width: 150,
+        tooltipField: 'email',
+        valueFormatter: locationValueFormatter,
+      },
+      {
+        field: 'startDate',
+        headerName: 'Start Date',
+        width: 130,
+        tooltipField: 'manager',
+      },
+    ],
+    rowData: sampleData,
+    height: 'calc(100vh - 60px)',
+    width: '100%',
+    theme: themeQuartz,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '**Mixed usage** — some columns use `tooltipField`, some use `tooltipValueGetter`, ' +
+          'and some have no tooltip at all. When both are set on the same column, ' +
+          '`tooltipValueGetter` takes priority (see **Name** column). ' +
+          '**Performance** intentionally has no tooltip.',
+      },
+    },
+  },
+};
+
+// ─── Story 4: Long / multi-line content ──────────────────────────────────────
+
+export const LongTooltips: Story = {
+  args: {
+    columnDefs: [
+      { field: 'id', headerName: 'ID', width: 70 },
+      {
+        field: 'name',
+        headerName: 'Name',
+        width: 180,
+        tooltipValueGetter: ({ data }: { data: Employee }) =>
+          [
+            `Employee Profile`,
+            `─────────────────────`,
+            `Name:       ${data.name}`,
+            `Role:       ${data.role}`,
+            `Dept:       ${data.department}`,
+            `Location:   ${data.location}`,
+            `Manager:    ${data.manager}`,
+            `Email:      ${data.email}`,
+            `Phone:      ${data.phone}`,
+            `Start Date: ${data.startDate}`,
+            `Projects:   ${data.projects}`,
+            `Salary:     $${data.salary.toLocaleString()}`,
+            `Performance:${data.performance}/100`,
+            `─────────────────────`,
+            data.bio,
+          ].join('\n'),
+      },
+      {
+        field: 'department',
+        headerName: 'Department',
+        width: 160,
+        tooltipValueGetter: ({ data }: { data: Employee }) =>
+          `Skills required for ${data.department}:\n\n${data.skills
+            .split(', ')
+            .map((s) => `  • ${s}`)
+            .join('\n')}`,
+        valueFormatter: departmentValueFormatter,
+      },
+      { field: 'role', headerName: 'Role', width: 140, valueFormatter: roleValueFormatter },
+      { field: 'salary', headerName: 'Salary', width: 110 },
+      { field: 'performance', headerName: 'Perf', width: 80 },
+      {
+        field: 'location',
+        headerName: 'Location',
+        width: 150,
+        valueFormatter: locationValueFormatter,
+      },
+    ],
+    rowData: sampleData,
+    height: 'calc(100vh - 60px)',
+    width: '100%',
+    theme: themeQuartz,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '**Multi-line / long tooltips** — hover over **Name** for a full employee profile card, ' +
+          'or **Department** for a bulleted skills list. The tooltip supports `\\n` newlines and ' +
+          'is capped at `max-width: 300px` with `white-space: pre-wrap`.',
+      },
+    },
+  },
+};

package/src/stories/benchmark-wrapper.component.ts

@@ -1,6 +1,14 @@
 import { CommonModule } from '@angular/common';
 import { AfterViewInit, Component, Input, OnDestroy, ViewChild } from '@angular/core';
 import { ArgentGridComponent, ArgentGridModule, ColDef, GridApi, themeQuartz } from '../public-api';
+import {
+  departmentValueFormatter,
+  locationValueFormatter,
+  roleValueFormatter,
+  STORY_DEPARTMENTS,
+  STORY_LOCATIONS,
+  STORY_ROLES,
+} from './story-utils';
 
 interface Employee {
   id: number;
@@ -25,24 +33,35 @@ interface Employee {
         <span class="row-count">{{ rowCount | number }} rows</span>
       </div>
 
+      <div class="benchmark-info">
+        <strong>What does this benchmark measure?</strong>
+        <ul>
+          <li><b>Initial Render</b> — time to paint the first visible frame of the grid</li>
+          <li><b>Selection Update</b> — time to select and deselect all {{ rowCount | number }} rows</li>
+          <li><b>Grouping Toggle</b> — time to enable then revert row grouping on the Department column</li>
+          <li><b>Avg Scroll Frame</b> — average canvas render time across 30 scroll frames (100 px each)</li>
+          <li><b>Total</b> — total wall-clock time for the entire benchmark run</li>
+        </ul>
+      </div>
+
       <div class="results" *ngIf="results">
-        <div class="result-item">
+        <div class="result-item" title="Time to paint the first visible frame of the grid">
           <span class="label">Initial Render:</span>
           <span class="value">{{ results.initialRender }}ms</span>
         </div>
-        <div class="result-item">
+        <div class="result-item" title="Time to select and deselect all rows">
           <span class="label">Selection Update:</span>
           <span class="value">{{ results.selectionUpdateTime }}ms</span>
         </div>
-        <div class="result-item">
+        <div class="result-item" title="Time to toggle row grouping on the Department column">
           <span class="label">Grouping Toggle:</span>
           <span class="value">{{ results.groupingUpdateTime }}ms</span>
         </div>
-        <div class="result-item">
+        <div class="result-item" title="Average canvas render time per scroll frame (30 frames, 100px each)">
           <span class="label">Avg Scroll Frame:</span>
           <span class="value">{{ results.scrollFrameAverage }}ms</span>
         </div>
-        <div class="result-item total">
+        <div class="result-item total" title="Total wall-clock time for the full benchmark run">
           <span class="label">Total:</span>
           <span class="value">{{ results.totalTime }}ms</span>
         </div>
@@ -118,25 +137,62 @@ interface Employee {
     .result-item.total .value {
       color: #059669;
     }
+    .benchmark-info {
+      padding: 10px 14px;
+      background: #eff6ff;
+      border: 1px solid #bfdbfe;
+      border-radius: 4px;
+      font-size: 13px;
+      color: #1e40af;
+    }
+    .benchmark-info strong {
+      display: block;
+      margin-bottom: 6px;
+    }
+    .benchmark-info ul {
+      margin: 0;
+      padding-left: 18px;
+    }
+    .benchmark-info li {
+      margin-bottom: 3px;
+    }
   `,
   ],
 })
 export class BenchmarkWrapperComponent implements AfterViewInit, OnDestroy {
   @ViewChild('grid') gridComponent!: ArgentGridComponent;
 
-  @Input() rowCount = 10000;
+  @Input() rowCount = 100000;
 
   columnDefs: ColDef<Employee>[] = [
     { field: 'id', headerName: 'ID', width: 80, sortable: true },
     { field: 'name', headerName: 'Name', width: 200, sortable: true },
-    { field: 'department', headerName: 'Department', width: 180, sortable: true },
-    { field: 'role', headerName: 'Role', width: 250, filter: true },
+    {
+      field: 'department',
+      headerName: 'Department',
+      width: 180,
+      sortable: true,
+      valueFormatter: departmentValueFormatter,
+    },
+    {
+      field: 'role',
+      headerName: 'Role',
+      width: 250,
+      filter: true,
+      valueFormatter: roleValueFormatter,
+    },
     { field: 'salary', headerName: 'Salary', width: 120, sortable: true, filter: 'number' },
-    { field: 'location', headerName: 'Location', width: 150, filter: true },
+    {
+      field: 'location',
+      headerName: 'Location',
+      width: 150,
+      filter: true,
+      valueFormatter: locationValueFormatter,
+    },
   ];
 
   rowData: Employee[] = [];
-  height = '500px';
+  height = 'calc(100vh - 60px)';
   width = '100%';
   theme = themeQuartz;
 
@@ -167,25 +223,9 @@ export class BenchmarkWrapperComponent implements AfterViewInit, OnDestroy {
   }
 
   generateData(count: number): Employee[] {
-    const departments = [
-      'Engineering',
-      'Sales',
-      'Marketing',
-      'HR',
-      'Finance',
-      'Operations',
-      'Support',
-    ];
-    const roles = ['Software Engineer', 'Manager', 'Director', 'VP', 'Intern', 'Analyst', 'Lead'];
-    const locations = [
-      'New York',
-      'San Francisco',
-      'London',
-      'Singapore',
-      'Remote',
-      'Berlin',
-      'Tokyo',
-    ];
+    const departments = STORY_DEPARTMENTS;
+    const roles = STORY_ROLES;
+    const locations = STORY_LOCATIONS;
 
     return Array.from({ length: count }, (_, i) => ({
       id: i + 1,