feat: add ObjectDataTable with async data loading, auto-column derivation

Copilot · hotlong · Copilot · commit b4cb2bda96ee · 2026-03-01T10:39:34.000Z
- P0: Create ObjectDataTable component (skeleton/error/empty states, column auto-derivation)
- P0: DashboardRenderer routes table+objectName to object-data-table renderer
- P0: Register object-data-table in ComponentRegistry
- Add 6 new ObjectDataTable tests (188 total passing)
- Update existing table provider tests for new type routing

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/plugin-dashboard/src/DashboardRenderer.tsx b/packages/plugin-dashboard/src/DashboardRenderer.tsx
@@ -192,30 +192,30 @@ export const DashboardRenderer = forwardRef<HTMLDivElement, DashboardRendererPro
                 // Support data at widget level or nested inside options
                 const widgetData = (widget as any).data || options.data;
 
-                // provider: 'object' — pass through object config for async data loading
+                // provider: 'object' — use ObjectDataTable for async data loading
                 if (isObjectProvider(widgetData)) {
                     const { data: _data, ...restOptions } = options;
                     return {
-                        type: 'data-table',
+                        type: 'object-data-table',
                         ...restOptions,
                         objectName: widget.object || widgetData.object,
                         dataProvider: widgetData,
-                        data: [],
-                        searchable: false,
-                        pagination: false,
+                        filter: widgetData.filter || widget.filter,
+                        searchable: widget.searchable ?? false,
+                        pagination: widget.pagination ?? false,
                         className: "border-0"
                     };
                 }
 
                 // No explicit data provider but widget has object binding
                 if (!widgetData && widget.object) {
                     return {
-                        type: 'data-table',
+                        type: 'object-data-table',
                         ...options,
                         objectName: widget.object,
-                        data: [],
-                        searchable: false,
-                        pagination: false,
+                        filter: widget.filter,
+                        searchable: widget.searchable ?? false,
+                        pagination: widget.pagination ?? false,
                         className: "border-0"
                     };
                 }
diff --git a/packages/plugin-dashboard/src/ObjectDataTable.tsx b/packages/plugin-dashboard/src/ObjectDataTable.tsx
@@ -0,0 +1,189 @@
+/**
+ * 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 React, { useState, useEffect, useContext, useMemo } from 'react';
+import { useDataScope, SchemaRendererContext, SchemaRenderer } from '@object-ui/react';
+import { extractRecords } from '@object-ui/core';
+import { Skeleton, cn } from '@object-ui/components';
+
+export interface ObjectDataTableProps {
+  schema: {
+    type: string;
+    objectName?: string;
+    dataProvider?: { provider: string; object?: string };
+    bind?: string;
+    filter?: any;
+    data?: any[];
+    columns?: any[];
+    searchable?: boolean;
+    pagination?: boolean;
+    className?: string;
+    [key: string]: any;
+  };
+  dataSource?: any;
+  className?: string;
+}
+
+/**
+ * ObjectDataTable — Async-aware wrapper for data-table.
+ *
+ * When `objectName` is provided and a `dataSource` is available via context
+ * or props, fetches records automatically and passes them to the registered
+ * `data-table` component via SchemaRenderer.
+ *
+ * Also auto-derives columns from fetched data keys when no explicit columns
+ * are configured.
+ *
+ * Lifecycle states:
+ * - **Loading** → skeleton placeholder
+ * - **Error** → error message
+ * - **Empty** → friendly "No data available" message
+ * - **Data** → data-table with fetched rows
+ */
+export const ObjectDataTable: React.FC<ObjectDataTableProps> = ({ schema, dataSource: propDataSource, className }) => {
+  const context = useContext(SchemaRendererContext);
+  const dataSource = propDataSource || context?.dataSource;
+  const boundData = useDataScope(schema.bind);
+
+  const [fetchedData, setFetchedData] = useState<any[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    const fetchData = async () => {
+      if (!dataSource || !schema.objectName) return;
+      if (isMounted) {
+        setLoading(true);
+        setError(null);
+      }
+      try {
+        let data: any[];
+
+        if (typeof dataSource.find === 'function') {
+          const results = await dataSource.find(schema.objectName, {
+            $filter: schema.filter,
+          });
+          data = extractRecords(results);
+        } else {
+          return;
+        }
+
+        if (isMounted) {
+          setFetchedData(data);
+        }
+      } catch (e) {
+        console.error('[ObjectDataTable] Fetch error:', e);
+        if (isMounted) {
+          setError(e instanceof Error ? e.message : 'Failed to load data');
+        }
+      } finally {
+        if (isMounted) setLoading(false);
+      }
+    };
+
+    if (schema.objectName && !boundData && (!schema.data || schema.data.length === 0)) {
+      fetchData();
+    }
+
+    return () => { isMounted = false; };
+  }, [schema.objectName, dataSource, boundData, schema.data, schema.filter]);
+
+  // Resolve data: bound data > static schema data > fetched data
+  const rawData = boundData || schema.data || fetchedData;
+  const finalData = Array.isArray(rawData) ? rawData : [];
+
+  // Auto-derive columns from data keys when none are provided
+  const derivedColumns = useMemo(() => {
+    if (schema.columns && schema.columns.length > 0) return schema.columns;
+    if (finalData.length === 0) return [];
+    const keys = Object.keys(finalData[0]).filter(k => !k.startsWith('_'));
+    return keys.map(k => ({
+      header: k.charAt(0).toUpperCase() + k.slice(1).replace(/([A-Z])/g, ' $1'),
+      accessorKey: k,
+    }));
+  }, [schema.columns, finalData]);
+
+  // Loading skeleton
+  if (loading && finalData.length === 0) {
+    return (
+      <div className={cn('overflow-auto', className)} data-testid="table-loading">
+        <div className="space-y-2 p-2">
+          <div className="flex gap-2">
+            <Skeleton className="h-6 w-1/4" />
+            <Skeleton className="h-6 w-1/4" />
+            <Skeleton className="h-6 w-1/4" />
+            <Skeleton className="h-6 w-1/4" />
+          </div>
+          {[1, 2, 3, 4].map((i) => (
+            <div key={i} className="flex gap-2">
+              <Skeleton className="h-5 w-1/4" />
+              <Skeleton className="h-5 w-1/4" />
+              <Skeleton className="h-5 w-1/4" />
+              <Skeleton className="h-5 w-1/4" />
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  // Error state
+  if (error) {
+    return (
+      <div className={cn('overflow-auto', className)} data-testid="table-error">
+        <div className="flex flex-col items-center justify-center py-8 text-destructive" data-testid="table-error-message">
+          <svg xmlns="http://www.w3.org/2000/svg" className="h-8 w-8 mb-2 opacity-60" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+            <circle cx="12" cy="12" r="10" />
+            <line x1="12" y1="8" x2="12" y2="12" />
+            <line x1="12" y1="16" x2="12.01" y2="16" />
+          </svg>
+          <p className="text-xs">{error}</p>
+        </div>
+      </div>
+    );
+  }
+
+  // No data source available but objectName configured
+  if (!dataSource && schema.objectName && finalData.length === 0) {
+    return (
+      <div className={cn('overflow-auto', className)}>
+        <div className="flex flex-col items-center justify-center py-8 text-muted-foreground">
+          <p className="text-xs">No data source available for &ldquo;{schema.objectName}&rdquo;</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Empty state
+  if (finalData.length === 0) {
+    return (
+      <div className={cn('overflow-auto', className)} data-testid="table-empty-state">
+        <div className="flex flex-col items-center justify-center py-8 text-muted-foreground">
+          <svg xmlns="http://www.w3.org/2000/svg" className="h-8 w-8 mb-2 opacity-40" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+            <rect x="3" y="3" width="18" height="18" rx="2" ry="2" />
+            <line x1="3" y1="9" x2="21" y2="9" />
+            <line x1="9" y1="21" x2="9" y2="9" />
+          </svg>
+          <p className="text-xs">No data available</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Delegate to data-table via SchemaRenderer
+  const tableSchema = {
+    ...schema,
+    type: 'data-table',
+    data: finalData,
+    columns: derivedColumns,
+  };
+
+  return <SchemaRenderer schema={tableSchema} className={className} />;
+};
diff --git a/packages/plugin-dashboard/src/__tests__/DashboardRenderer.widgetData.test.tsx b/packages/plugin-dashboard/src/__tests__/DashboardRenderer.widgetData.test.tsx
@@ -398,18 +398,15 @@ describe('DashboardRenderer widget data extraction', () => {
 
     const { container } = render(<DashboardRenderer schema={schema} />);
     const schemas = getRenderedSchemas(container);
-    const tableSchema = schemas.find(s => s.type === 'data-table');
+    // DashboardRenderer now routes object-bound tables to 'object-data-table'
+    const tableSchema = schemas.find(s => s.type === 'object-data-table');
 
-    // data-table is a registered component so it may render directly.
-    // If not registered, the schema will appear in the error <pre>.
-    // In either case, the schema must contain objectName instead of empty data.
     if (tableSchema) {
       expect(tableSchema.objectName).toBe('opportunity');
       expect(tableSchema.dataProvider).toEqual({
         provider: 'object',
         object: 'opportunity',
       });
-      expect(tableSchema.data).toBeUndefined();
     }
   });
 
@@ -955,9 +952,9 @@ describe('DashboardRenderer widget data extraction', () => {
 
     const { container } = render(<DashboardRenderer schema={schema} />);
     const schemas = getRenderedSchemas(container);
-    const tableSchema = schemas.find(s => s.type === 'data-table');
+    // DashboardRenderer now routes table+objectName to 'object-data-table'
+    const tableSchema = schemas.find(s => s.type === 'object-data-table');
 
-    // data-table is registered, may render directly — check if schema was produced
     if (tableSchema) {
       expect(tableSchema.objectName).toBe('contact');
     }
diff --git a/packages/plugin-dashboard/src/__tests__/ObjectDataTable.test.tsx b/packages/plugin-dashboard/src/__tests__/ObjectDataTable.test.tsx
@@ -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 { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import React from 'react';
+import { ObjectDataTable } from '../ObjectDataTable';
+import { SchemaRendererProvider } from '@object-ui/react';
+
+describe('ObjectDataTable', () => {
+  const baseSchema = {
+    type: 'object-data-table',
+    objectName: 'contacts',
+  };
+
+  it('should show loading skeleton when fetching data', async () => {
+    const dataSource = {
+      find: vi.fn(() => new Promise(() => {})), // Never resolves
+    };
+
+    const { container } = render(
+      <SchemaRendererProvider dataSource={dataSource}>
+        <ObjectDataTable schema={baseSchema} />
+      </SchemaRendererProvider>,
+    );
+
+    await waitFor(() => {
+      const loadingEl = container.querySelector('[data-testid="table-loading"]');
+      expect(loadingEl).toBeDefined();
+    });
+  });
+
+  it('should show error state on fetch failure', async () => {
+    const dataSource = {
+      find: vi.fn().mockRejectedValue(new Error('Connection refused')),
+    };
+
+    const { container } = render(
+      <SchemaRendererProvider dataSource={dataSource}>
+        <ObjectDataTable schema={baseSchema} />
+      </SchemaRendererProvider>,
+    );
+
+    await waitFor(() => {
+      const errorEl = container.querySelector('[data-testid="table-error"]');
+      expect(errorEl).toBeDefined();
+    });
+
+    expect(screen.getByText('Connection refused')).toBeDefined();
+  });
+
+  it('should show empty state when no data returned', async () => {
+    const dataSource = {
+      find: vi.fn().mockResolvedValue({ records: [] }),
+    };
+
+    const { container } = render(
+      <SchemaRendererProvider dataSource={dataSource}>
+        <ObjectDataTable schema={baseSchema} />
+      </SchemaRendererProvider>,
+    );
+
+    await waitFor(() => {
+      const emptyState = container.querySelector('[data-testid="table-empty-state"]');
+      expect(emptyState).toBeDefined();
+    });
+  });
+
+  it('should show no-data-source message when objectName is set but no dataSource', () => {
+    render(<ObjectDataTable schema={baseSchema} />);
+    expect(screen.getByText(/No data source available/)).toBeDefined();
+  });
+
+  it('should auto-derive columns from fetched data keys', async () => {
+    const dataSource = {
+      find: vi.fn().mockResolvedValue({
+        records: [
+          { firstName: 'Alice', lastName: 'Smith', email: 'alice@test.com' },
+          { firstName: 'Bob', lastName: 'Jones', email: 'bob@test.com' },
+        ],
+      }),
+    };
+
+    const schema = { ...baseSchema, objectName: 'contacts' };
+
+    const { container } = render(
+      <SchemaRendererProvider dataSource={dataSource}>
+        <ObjectDataTable schema={schema} />
+      </SchemaRendererProvider>,
+    );
+
+    // Wait for data to be fetched and rendered
+    await waitFor(() => {
+      // data-table renders via SchemaRenderer, so look for content
+      expect(container.textContent).toBeDefined();
+    });
+
+    expect(dataSource.find).toHaveBeenCalledWith('contacts', { $filter: undefined });
+  });
+
+  it('should prefer static data over fetched data', () => {
+    const dataSource = { find: vi.fn() };
+
+    const schema = {
+      ...baseSchema,
+      data: [{ name: 'Static Row', value: 42 }],
+    };
+
+    render(
+      <SchemaRendererProvider dataSource={dataSource}>
+        <ObjectDataTable schema={schema} />
+      </SchemaRendererProvider>,
+    );
+
+    expect(dataSource.find).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/plugin-dashboard/src/index.tsx b/packages/plugin-dashboard/src/index.tsx
