@object-ui/plugin-grid 2.0.0 → 3.0.0

package/src/__tests__/performance-benchmark.test.tsx

@@ -0,0 +1,182 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Performance benchmark tests for VirtualGrid.
+ * Part of P2.4 Performance at Scale roadmap.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+import type { VirtualGridColumn, VirtualGridProps } from '../VirtualGrid';
+
+// --- Mock @tanstack/react-virtual ---
+// Cap the visible window to simulate virtualisation (only render a subset)
+const VISIBLE_WINDOW = 50;
+
+vi.mock('@tanstack/react-virtual', () => ({
+  useVirtualizer: (opts: any) => {
+    const count: number = opts.count;
+    const size: number = opts.estimateSize();
+    const visible = Math.min(count, VISIBLE_WINDOW);
+    const items = [];
+    for (let i = 0; i < visible; i++) {
+      items.push({ index: i, key: String(i), start: i * size, size });
+    }
+    return {
+      getVirtualItems: () => items,
+      getTotalSize: () => count * size,
+    };
+  },
+}));
+
+// --- Data generators ---
+function generateRows(count: number) {
+  const rows = [];
+  for (let i = 0; i < count; i++) {
+    rows.push({
+      id: i,
+      name: `User ${i}`,
+      email: `user${i}@example.com`,
+      department: `Dept ${i % 10}`,
+      salary: 50000 + (i * 100),
+    });
+  }
+  return rows;
+}
+
+const benchmarkColumns: VirtualGridColumn[] = [
+  { header: 'ID', accessorKey: 'id' },
+  { header: 'Name', accessorKey: 'name' },
+  { header: 'Email', accessorKey: 'email' },
+  { header: 'Department', accessorKey: 'department' },
+  { header: 'Salary', accessorKey: 'salary', align: 'right' },
+];
+
+type VirtualGridComponent = React.FC<VirtualGridProps>;
+
+let VirtualGrid: VirtualGridComponent;
+
+beforeEach(async () => {
+  cleanup();
+  vi.resetModules();
+  const mod = await import('../VirtualGrid');
+  VirtualGrid = mod.VirtualGrid;
+});
+
+function renderGrid(overrides: Partial<VirtualGridProps> = {}) {
+  const props: VirtualGridProps = {
+    data: [],
+    columns: benchmarkColumns,
+    ...overrides,
+  };
+  return render(<VirtualGrid {...props} />);
+}
+
+// =========================================================================
+// Performance Benchmarks
+// =========================================================================
+
+describe('VirtualGrid: performance benchmarks', () => {
+  it('renders 1,000 rows under 500ms', () => {
+    const data = generateRows(1_000);
+
+    const start = performance.now();
+    const { container } = renderGrid({ data });
+    const elapsed = performance.now() - start;
+
+    expect(container.querySelector('.overflow-auto')).toBeInTheDocument();
+    expect(elapsed).toBeLessThan(500);
+  });
+
+  it('renders 10,000 rows under 2,000ms', () => {
+    const data = generateRows(10_000);
+
+    const start = performance.now();
+    const { container } = renderGrid({ data });
+    const elapsed = performance.now() - start;
+
+    expect(container.querySelector('.overflow-auto')).toBeInTheDocument();
+    expect(elapsed).toBeLessThan(2_000);
+  });
+
+  it('renders 50,000 rows without crashing', () => {
+    const data = generateRows(50_000);
+
+    const start = performance.now();
+    const { container } = renderGrid({ data });
+    const elapsed = performance.now() - start;
+
+    expect(container.querySelector('.overflow-auto')).toBeInTheDocument();
+    // Virtual scrolling should keep render time manageable even at 50K
+    expect(elapsed).toBeLessThan(10_000);
+  });
+
+  it('data generation for 10,000 rows is fast (< 200ms)', () => {
+    const start = performance.now();
+    const data = generateRows(10_000);
+    const elapsed = performance.now() - start;
+
+    expect(data).toHaveLength(10_000);
+    expect(elapsed).toBeLessThan(200);
+  });
+});
+
+// =========================================================================
+// Scaling characteristics
+// =========================================================================
+
+describe('VirtualGrid: scaling characteristics', () => {
+  it('shows correct row count in footer for large dataset', () => {
+    const data = generateRows(1_000);
+    renderGrid({ data });
+
+    // Footer displays total count regardless of virtualised window
+    expect(document.body.textContent).toContain('1000');
+  });
+
+  it('renders with many columns (20+) without degradation', () => {
+    const columns: VirtualGridColumn[] = Array.from({ length: 20 }, (_, i) => ({
+      header: `Col ${i}`,
+      accessorKey: `field${i}`,
+    }));
+    const data = Array.from({ length: 500 }, (_, row) =>
+      Object.fromEntries(columns.map((c) => [c.accessorKey, `R${row}-${c.accessorKey}`])),
+    );
+
+    const start = performance.now();
+    const { container } = renderGrid({ columns, data });
+    const elapsed = performance.now() - start;
+
+    expect(container.querySelector('.overflow-auto')).toBeInTheDocument();
+    expect(elapsed).toBeLessThan(2_000);
+  });
+
+  it('custom cell renderers do not drastically increase render time for 1,000 rows', () => {
+    const columnsWithRenderers: VirtualGridColumn[] = [
+      {
+        header: 'Name',
+        accessorKey: 'name',
+        cell: (value: string) => <strong>{value}</strong>,
+      },
+      {
+        header: 'Email',
+        accessorKey: 'email',
+        cell: (value: string) => <a href={`mailto:${value}`}>{value}</a>,
+      },
+      { header: 'Department', accessorKey: 'department' },
+    ];
+    const data = generateRows(1_000);
+
+    const start = performance.now();
+    renderGrid({ columns: columnsWithRenderers, data });
+    const elapsed = performance.now() - start;
+
+    expect(elapsed).toBeLessThan(1_000);
+  });
+});

package/src/__tests__/view-states.test.tsx

@@ -0,0 +1,203 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * P3.3 Plugin View Robustness - Grid View States
+ *
+ * Tests empty, loading, error states for VirtualGrid component,
+ * and edge cases like single-row data, many columns, and missing fields.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+import type { VirtualGridColumn, VirtualGridProps } from '../VirtualGrid';
+
+// Mock @tanstack/react-virtual
+vi.mock('@tanstack/react-virtual', () => ({
+  useVirtualizer: (opts: any) => {
+    const count: number = opts.count;
+    const size: number = opts.estimateSize();
+    const items = [];
+    for (let i = 0; i < count; i++) {
+      items.push({ index: i, key: String(i), start: i * size, size });
+    }
+    return {
+      getVirtualItems: () => items,
+      getTotalSize: () => count * size,
+    };
+  },
+}));
+
+const defaultColumns: VirtualGridColumn[] = [
+  { header: 'Name', accessorKey: 'name' },
+  { header: 'Email', accessorKey: 'email' },
+  { header: 'Status', accessorKey: 'status' },
+];
+
+type VirtualGridComponent = React.FC<VirtualGridProps>;
+let VirtualGrid: VirtualGridComponent;
+
+beforeEach(async () => {
+  cleanup();
+  vi.resetModules();
+  const mod = await import('../VirtualGrid');
+  VirtualGrid = mod.VirtualGrid;
+});
+
+function renderGrid(overrides: Partial<VirtualGridProps> = {}) {
+  return render(
+    <VirtualGrid
+      data={[]}
+      columns={defaultColumns}
+      {...overrides}
+    />
+  );
+}
+
+describe('P3.3 Grid View States', () => {
+  // ---------------------------------------------------------------
+  // Empty state
+  // ---------------------------------------------------------------
+  describe('empty state', () => {
+    it('renders column headers with empty data', () => {
+      renderGrid({ data: [] });
+      expect(screen.getByText('Name')).toBeInTheDocument();
+      expect(screen.getByText('Email')).toBeInTheDocument();
+      expect(screen.getByText('Status')).toBeInTheDocument();
+    });
+
+    it('shows 0 rows in footer for empty data', () => {
+      renderGrid({ data: [] });
+      expect(screen.getByText(/Showing 0 of 0 rows/)).toBeInTheDocument();
+    });
+
+    it('does not render any data cells for empty data', () => {
+      renderGrid({ data: [] });
+      expect(screen.queryByText('Alice')).not.toBeInTheDocument();
+    });
+
+    it('renders with empty columns array', () => {
+      const { container } = renderGrid({ data: [], columns: [] });
+      expect(container.firstElementChild).toBeInTheDocument();
+    });
+  });
+
+  // ---------------------------------------------------------------
+  // Normal data rendering
+  // ---------------------------------------------------------------
+  describe('normal data rendering', () => {
+    const sampleData = [
+      { name: 'Alice', email: 'alice@test.com', status: 'active' },
+      { name: 'Bob', email: 'bob@test.com', status: 'inactive' },
+    ];
+
+    it('renders all rows', () => {
+      renderGrid({ data: sampleData });
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+      expect(screen.getByText('Bob')).toBeInTheDocument();
+    });
+
+    it('shows correct row count', () => {
+      renderGrid({ data: sampleData });
+      expect(screen.getByText(/Showing 2 of 2 rows/)).toBeInTheDocument();
+    });
+
+    it('renders all column values', () => {
+      renderGrid({ data: sampleData });
+      expect(screen.getByText('alice@test.com')).toBeInTheDocument();
+      expect(screen.getByText('active')).toBeInTheDocument();
+    });
+  });
+
+  // ---------------------------------------------------------------
+  // Edge cases
+  // ---------------------------------------------------------------
+  describe('edge cases', () => {
+    it('renders single row', () => {
+      renderGrid({ data: [{ name: 'Solo', email: 'solo@test.com', status: 'ok' }] });
+      expect(screen.getByText('Solo')).toBeInTheDocument();
+      expect(screen.getByText(/Showing 1 of 1 rows/)).toBeInTheDocument();
+    });
+
+    it('handles row with missing fields gracefully', () => {
+      renderGrid({
+        data: [{ name: 'Partial' }],
+      });
+      expect(screen.getByText('Partial')).toBeInTheDocument();
+      // Missing email and status should not crash
+    });
+
+    it('handles many columns', () => {
+      const cols: VirtualGridColumn[] = Array.from({ length: 20 }, (_, i) => ({
+        header: `Col${i}`,
+        accessorKey: `field${i}`,
+      }));
+      const data = [Object.fromEntries(cols.map((c, i) => [c.accessorKey, `val${i}`]))];
+
+      renderGrid({ columns: cols, data });
+      expect(screen.getByText('Col0')).toBeInTheDocument();
+      expect(screen.getByText('Col19')).toBeInTheDocument();
+      expect(screen.getByText('val0')).toBeInTheDocument();
+      expect(screen.getByText('val19')).toBeInTheDocument();
+    });
+
+    it('handles data with null/undefined field values', () => {
+      renderGrid({
+        data: [{ name: null, email: undefined, status: 'ok' }],
+      });
+      expect(screen.getByText('ok')).toBeInTheDocument();
+    });
+
+    it('handles data with numeric values', () => {
+      const cols: VirtualGridColumn[] = [
+        { header: 'ID', accessorKey: 'id' },
+        { header: 'Score', accessorKey: 'score' },
+      ];
+      renderGrid({
+        columns: cols,
+        data: [{ id: 1, score: 99.5 }],
+      });
+      expect(screen.getByText('1')).toBeInTheDocument();
+      expect(screen.getByText('99.5')).toBeInTheDocument();
+    });
+
+    it('handles data with boolean values', () => {
+      const cols: VirtualGridColumn[] = [
+        { header: 'Name', accessorKey: 'name' },
+        { header: 'Active', accessorKey: 'active' },
+      ];
+      renderGrid({
+        columns: cols,
+        data: [{ name: 'Test', active: true }],
+      });
+      expect(screen.getByText('Test')).toBeInTheDocument();
+    });
+  });
+
+  // ---------------------------------------------------------------
+  // Custom className support
+  // ---------------------------------------------------------------
+  describe('className support in states', () => {
+    it('applies className to empty grid', () => {
+      const { container } = renderGrid({ data: [], className: 'my-grid' });
+      const root = container.firstElementChild as HTMLElement;
+      expect(root).toHaveClass('my-grid');
+    });
+
+    it('applies className to populated grid', () => {
+      const { container } = renderGrid({
+        data: [{ name: 'A', email: 'a@t.com', status: 'ok' }],
+        className: 'styled-grid',
+      });
+      const root = container.firstElementChild as HTMLElement;
+      expect(root).toHaveClass('styled-grid');
+    });
+  });
+});

package/src/index.tsx

@@ -13,8 +13,13 @@ import { ObjectGrid } from './ObjectGrid';
 import { VirtualGrid } from './VirtualGrid';
 
 export { ObjectGrid, VirtualGrid };
+export { InlineEditing } from './InlineEditing';
+export { useRowColor } from './useRowColor';
+export { useGroupedData } from './useGroupedData';
 export type { ObjectGridProps } from './ObjectGrid';
 export type { VirtualGridProps, VirtualGridColumn } from './VirtualGrid';
+export type { InlineEditingProps } from './InlineEditing';
+export type { GroupEntry, UseGroupedDataResult } from './useGroupedData';
 
 // Register object-grid component
 export const ObjectGridRenderer: React.FC<{ schema: any; [key: string]: any }> = ({ schema, ...props }) => {

package/src/useGroupedData.ts

@@ -0,0 +1,122 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { useState, useMemo, useCallback } from 'react';
+import type { GroupingConfig } from '@object-ui/types';
+
+export interface GroupEntry {
+  /** Composite key identifying this group (field values joined by ' / ') */
+  key: string;
+  /** Display label for the group header */
+  label: string;
+  /** Rows belonging to this group */
+  rows: any[];
+  /** Whether the group section is collapsed */
+  collapsed: boolean;
+}
+
+export interface UseGroupedDataResult {
+  /** Grouped entries (empty when grouping is not configured) */
+  groups: GroupEntry[];
+  /** Whether grouping is active */
+  isGrouped: boolean;
+  /** Toggle the collapsed state of a group by its key */
+  toggleGroup: (key: string) => void;
+}
+
+/**
+ * Build a composite group key from a row based on the grouping fields.
+ */
+function buildGroupKey(row: Record<string, any>, fields: GroupingConfig['fields']): string {
+  return fields.map((f) => String(row[f.field] ?? '')).join(' / ');
+}
+
+/**
+ * Build a human-readable label from a row based on the grouping fields.
+ */
+function buildGroupLabel(row: Record<string, any>, fields: GroupingConfig['fields']): string {
+  return fields
+    .map((f) => {
+      const val = row[f.field];
+      return val !== undefined && val !== null && val !== '' ? String(val) : '(empty)';
+    })
+    .join(' / ');
+}
+
+/**
+ * Compare function that respects per-field sort order.
+ */
+function compareGroups(a: string, b: string, order: 'asc' | 'desc'): number {
+  const cmp = a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+  return order === 'desc' ? -cmp : cmp;
+}
+
+/**
+ * Hook that groups a flat data array by the fields specified in GroupingConfig.
+ *
+ * Supports multi-level grouping, per-field sort order, and per-field default
+ * collapsed state.  Collapse state is managed internally so the consumer only
+ * needs to wire `toggleGroup` to the UI.
+ *
+ * @param config  - GroupingConfig from the grid schema (optional)
+ * @param data    - flat data rows
+ */
+export function useGroupedData(
+  config: GroupingConfig | undefined,
+  data: any[],
+): UseGroupedDataResult {
+  const fields = config?.fields;
+  const isGrouped = !!(fields && fields.length > 0);
+
+  // Track which group keys have been explicitly toggled by the user.
+  const [toggledKeys, setToggledKeys] = useState<Record<string, boolean>>({});
+
+  // Determine whether a field set defaults to collapsed.
+  const fieldsDefaultCollapsed = useMemo(() => {
+    if (!fields) return false;
+    // If any grouping field has collapsed: true, default all groups to collapsed.
+    return fields.some((f) => f.collapsed);
+  }, [fields]);
+
+  const groups: GroupEntry[] = useMemo(() => {
+    if (!isGrouped || !fields) return [];
+
+    // Group rows by composite key
+    const map = new Map<string, { label: string; rows: any[] }>();
+    const keyOrder: string[] = [];
+
+    for (const row of data) {
+      const key = buildGroupKey(row, fields);
+      if (!map.has(key)) {
+        map.set(key, { label: buildGroupLabel(row, fields), rows: [] });
+        keyOrder.push(key);
+      }
+      map.get(key)!.rows.push(row);
+    }
+
+    // Sort groups using the first grouping field's order
+    const primaryOrder = fields[0]?.order ?? 'asc';
+    keyOrder.sort((a, b) => compareGroups(a, b, primaryOrder));
+
+    return keyOrder.map((key) => {
+      const entry = map.get(key)!;
+      const collapsed =
+        key in toggledKeys ? toggledKeys[key] : fieldsDefaultCollapsed;
+      return { key, label: entry.label, rows: entry.rows, collapsed };
+    });
+  }, [data, fields, isGrouped, toggledKeys, fieldsDefaultCollapsed]);
+
+  const toggleGroup = useCallback((key: string) => {
+    setToggledKeys((prev) => ({
+      ...prev,
+      [key]: prev[key] !== undefined ? !prev[key] : !fieldsDefaultCollapsed,
+    }));
+  }, [fieldsDefaultCollapsed]);
+
+  return { groups, isGrouped, toggleGroup };
+}

package/src/useRowColor.ts

@@ -0,0 +1,74 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { useCallback } from 'react';
+import type { RowColorConfig } from '@object-ui/types';
+
+/**
+ * CSS color to Tailwind-compatible background class mapping.
+ * For colors not in this map, a CSS custom property approach is used.
+ */
+const COLOR_TO_CLASS: Record<string, string> = {
+  red: 'bg-red-100',
+  green: 'bg-green-100',
+  blue: 'bg-blue-100',
+  yellow: 'bg-yellow-100',
+  orange: 'bg-orange-100',
+  purple: 'bg-purple-100',
+  pink: 'bg-pink-100',
+  gray: 'bg-gray-100',
+  grey: 'bg-gray-100',
+  indigo: 'bg-indigo-100',
+  teal: 'bg-teal-100',
+  cyan: 'bg-cyan-100',
+  amber: 'bg-amber-100',
+  lime: 'bg-lime-100',
+  emerald: 'bg-emerald-100',
+  rose: 'bg-rose-100',
+  sky: 'bg-sky-100',
+  violet: 'bg-violet-100',
+  fuchsia: 'bg-fuchsia-100',
+  slate: 'bg-slate-100',
+  zinc: 'bg-zinc-100',
+  stone: 'bg-stone-100',
+  neutral: 'bg-neutral-100',
+};
+
+/**
+ * Maps a CSS color string to a Tailwind background class.
+ * Falls back to undefined for unrecognised values (dynamic CSS colors
+ * that cannot be represented as static Tailwind classes).
+ */
+function colorToClass(color: string): string | undefined {
+  // Direct Tailwind class (e.g. "bg-red-200")
+  if (color.startsWith('bg-')) return color;
+
+  const lower = color.toLowerCase().trim();
+  return COLOR_TO_CLASS[lower];
+}
+
+/**
+ * Hook that returns a row-className resolver based on RowColorConfig.
+ *
+ * @param config  - RowColorConfig from the grid schema (optional)
+ * @returns a function `(row) => className | undefined`
+ */
+export function useRowColor(config: RowColorConfig | undefined) {
+  return useCallback(
+    (row: Record<string, any>): string | undefined => {
+      if (!config?.field || !config.colors) return undefined;
+
+      const value = String(row[config.field] ?? '');
+      const color = config.colors[value];
+      if (!color) return undefined;
+
+      return colorToClass(color);
+    },
+    [config?.field, config?.colors],
+  );
+}