feat: add export button with CSV/JSON support to ObjectGrid (Phase 10 L1)

Copilot · hotlong · Copilot · commit f9d8bc40efd6 · 2026-02-16T09:48:50.000Z
- Add exportOptions property to ObjectGridSchema type definition
- Implement handleExport callback with CSV and JSON format support
- Add export toolbar with Popover dropdown in ObjectGrid component
- Add unit tests verifying export button rendering and format options

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/plugin-grid/src/ObjectGrid.tsx b/packages/plugin-grid/src/ObjectGrid.tsx
@@ -25,15 +25,13 @@ import React, { useEffect, useState, useCallback } from 'react';
 import type { ObjectGridSchema, DataSource, ListColumn, ViewData } from '@object-ui/types';
 import { SchemaRenderer, useDataScope, useNavigationOverlay, useAction } from '@object-ui/react';
 import { getCellRenderer } from '@object-ui/fields';
-import { Button, NavigationOverlay } from '@object-ui/components';
-import { usePullToRefresh } from '@object-ui/mobile';
 import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
+  Button, NavigationOverlay,
+  Popover, PopoverContent, PopoverTrigger,
+  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger,
 } from '@object-ui/components';
-import { Edit, Trash2, MoreVertical, ChevronRight, ChevronDown } from 'lucide-react';
+import { usePullToRefresh } from '@object-ui/mobile';
+import { Edit, Trash2, MoreVertical, ChevronRight, ChevronDown, Download } from 'lucide-react';
 import { useRowColor } from './useRowColor';
 import { useGroupedData } from './useGroupedData';
 
@@ -125,6 +123,7 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
   const [objectSchema, setObjectSchema] = useState<any>(null);
   const [useCardView, setUseCardView] = useState(false);
   const [refreshKey, setRefreshKey] = useState(0);
+  const [showExport, setShowExport] = useState(false);
 
   // Column state persistence (order and widths)
   const columnStorageKey = React.useMemo(() => {
@@ -514,6 +513,47 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     return generatedColumns;
   }, [objectSchema, schemaFields, schemaColumns, dataConfig, hasInlineData, navigation.handleClick, executeAction]);
 
+  const handleExport = useCallback((format: 'csv' | 'xlsx' | 'json' | 'pdf') => {
+    const exportConfig = schema.exportOptions;
+    const maxRecords = exportConfig?.maxRecords || 0;
+    const includeHeaders = exportConfig?.includeHeaders !== false;
+    const prefix = exportConfig?.fileNamePrefix || schema.objectName || 'export';
+    const exportData = maxRecords > 0 ? data.slice(0, maxRecords) : data;
+
+    if (format === 'csv') {
+      const cols = generateColumns().filter((c: any) => c.accessorKey !== '_actions');
+      const fields = cols.map((c: any) => c.accessorKey);
+      const headers = cols.map((c: any) => c.header);
+      const rows: string[] = [];
+      if (includeHeaders) {
+        rows.push(headers.join(','));
+      }
+      exportData.forEach(record => {
+        rows.push(fields.map((f: string) => {
+          const val = record[f];
+          const str = val == null ? '' : String(val);
+          return str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r') ? `"${str.replace(/"/g, '""')}"` : str;
+        }).join(','));
+      });
+      const blob = new Blob([rows.join('\n')], { type: 'text/csv;charset=utf-8;' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `${prefix}.csv`;
+      a.click();
+      URL.revokeObjectURL(url);
+    } else if (format === 'json') {
+      const blob = new Blob([JSON.stringify(exportData, null, 2)], { type: 'application/json' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `${prefix}.json`;
+      a.click();
+      URL.revokeObjectURL(url);
+    }
+    setShowExport(false);
+  }, [data, schema.exportOptions, schema.objectName, generateColumns]);
+
   if (error) {
     return (
       <div className="p-3 sm:p-4 border border-red-300 bg-red-50 rounded-md">
@@ -713,6 +753,40 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
     );
   }
 
+  // Export toolbar (shown when exportOptions is configured)
+  const exportToolbar = schema.exportOptions ? (
+    <div className="flex items-center justify-end px-2 py-1">
+      <Popover open={showExport} onOpenChange={setShowExport}>
+        <PopoverTrigger asChild>
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-7 px-2 text-muted-foreground hover:text-primary text-xs"
+          >
+            <Download className="h-3.5 w-3.5 mr-1.5" />
+            <span className="hidden sm:inline">Export</span>
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent align="end" className="w-48 p-2">
+          <div className="space-y-1">
+            {(schema.exportOptions.formats || ['csv', 'json']).map(format => (
+              <Button
+                key={format}
+                variant="ghost"
+                size="sm"
+                className="w-full justify-start h-8 text-xs"
+                onClick={() => handleExport(format)}
+              >
+                <Download className="h-3.5 w-3.5 mr-2" />
+                Export as {format.toUpperCase()}
+              </Button>
+            ))}
+          </div>
+        </PopoverContent>
+      </Popover>
+    </div>
+  ) : null;
+
   // Render grid content: grouped (multiple tables with headers) or flat (single table)
   const gridContent = isGrouped ? (
     <div className="space-y-2">
@@ -745,7 +819,7 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
       <NavigationOverlay
         {...navigation}
         title={detailTitle}
-        mainContent={gridContent}
+        mainContent={<>{exportToolbar}{gridContent}</>}
       >
         {(record) => (
           <div className="space-y-3">
@@ -773,6 +847,7 @@ export const ObjectGrid: React.FC<ObjectGridProps> = ({
           {isRefreshing ? 'Refreshing…' : 'Pull to refresh'}
         </div>
       )}
+      {exportToolbar}
       {gridContent}
       {navigation.isOverlay && (
         <NavigationOverlay
diff --git a/packages/plugin-grid/src/__tests__/grid-export.test.tsx b/packages/plugin-grid/src/__tests__/grid-export.test.tsx
@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+
+/**
+ * Phase 10 - Grid Export Tests
+ *
+ * Tests the CSV/JSON export functionality on ObjectGrid component.
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+import { ObjectGrid } from '../ObjectGrid';
+import { registerAllFields } from '@object-ui/fields';
+
+registerAllFields();
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+const sampleData = [
+  { _id: '1', name: 'Alice', email: 'alice@example.com', status: 'Active' },
+  { _id: '2', name: 'Bob', email: 'bob@example.com', status: 'Inactive' },
+  { _id: '3', name: 'Charlie', email: 'charlie@example.com', status: 'Active' },
+];
+
+describe('Phase 10 - Grid Export', () => {
+  it('does not render export button when exportOptions is not configured', () => {
+    render(
+      <ObjectGrid
+        schema={{
+          type: 'object-grid',
+          objectName: 'contacts',
+          data: sampleData,
+          columns: ['name', 'email', 'status'],
+        }}
+      />
+    );
+
+    expect(screen.queryByText('Export')).not.toBeInTheDocument();
+  });
+
+  it('renders export button when exportOptions is configured', async () => {
+    render(
+      <ObjectGrid
+        schema={{
+          type: 'object-grid',
+          objectName: 'contacts',
+          data: sampleData,
+          columns: ['name', 'email', 'status'],
+          exportOptions: {
+            formats: ['csv', 'json'],
+          },
+        }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Export')).toBeInTheDocument();
+    });
+  });
+
+  it('shows format options when export button is clicked', async () => {
+    render(
+      <ObjectGrid
+        schema={{
+          type: 'object-grid',
+          objectName: 'contacts',
+          data: sampleData,
+          columns: ['name', 'email', 'status'],
+          exportOptions: {
+            formats: ['csv', 'json'],
+          },
+        }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Export')).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByText('Export'));
+
+    await waitFor(() => {
+      expect(screen.getByText('Export as CSV')).toBeInTheDocument();
+      expect(screen.getByText('Export as JSON')).toBeInTheDocument();
+    });
+  });
+
+  it('defaults to csv and json formats when formats not specified', async () => {
+    render(
+      <ObjectGrid
+        schema={{
+          type: 'object-grid',
+          objectName: 'contacts',
+          data: sampleData,
+          columns: ['name', 'email', 'status'],
+          exportOptions: {},
+        }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Export')).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByText('Export'));
+
+    await waitFor(() => {
+      expect(screen.getByText('Export as CSV')).toBeInTheDocument();
+      expect(screen.getByText('Export as JSON')).toBeInTheDocument();
+    });
+  });
+});
diff --git a/packages/types/src/objectql.ts b/packages/types/src/objectql.ts
@@ -415,6 +415,22 @@ export interface ObjectGridSchema extends BaseSchema {
    */
   frozenColumns?: number;
 
+  /**
+   * Export options configuration for exporting grid data.
+   * Supports csv, xlsx, json, and pdf formats.
+   * Aligned with @objectstack/spec ListViewSchema.exportOptions.
+   */
+  exportOptions?: {
+    /** Formats available for export */
+    formats?: Array<'csv' | 'xlsx' | 'json' | 'pdf'>;
+    /** Maximum number of records to export (0 = unlimited) */
+    maxRecords?: number;
+    /** Include column headers in export */
+    includeHeaders?: boolean;
+    /** Custom file name prefix */
+    fileNamePrefix?: string;
+  };
+
   /**
    * Navigation configuration for row click behavior.
    * Controls how record detail is displayed when a row is clicked.
