@papernote/ui 1.0.0 → 1.2.0

package/src/components/Spreadsheet.stories.tsx

@@ -0,0 +1,362 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Spreadsheet, SpreadsheetReport } from './Spreadsheet';
+import type { SpreadsheetCell, Matrix } from './Spreadsheet';
+import { useState } from 'react';
+import Button from './Button';
+import { Calculator } from 'lucide-react';
+
+const meta: Meta<typeof Spreadsheet> = {
+  title: 'Components/Spreadsheet',
+  component: Spreadsheet,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Interactive spreadsheet component with Excel formula support (280+ formulas via Fast Formula Parser), import/export functionality, and save capabilities. Perfect for report designers and data editing interfaces.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Spreadsheet>;
+
+/**
+ * Basic spreadsheet with default settings
+ */
+export const Basic: Story = {
+  args: {
+    rows: 10,
+    columns: 5,
+  },
+};
+
+/**
+ * Spreadsheet with toolbar showing import/export/save actions
+ */
+export const WithToolbar: Story = {
+  args: {
+    rows: 15,
+    columns: 8,
+    showToolbar: true,
+    enableImport: true,
+    enableExport: true,
+    enableSave: true,
+    title: 'Data Editor',
+    exportFileName: 'my-data.xlsx',
+  },
+  render: (args) => {
+    const [data, setData] = useState<Matrix<SpreadsheetCell>>();
+
+    return (
+      <Spreadsheet
+        {...args}
+        data={data}
+        onChange={setData}
+        onSave={async (data) => {
+          console.log('Saving data:', data);
+          // Simulate API call
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+        }}
+      />
+    );
+  },
+};
+
+/**
+ * Spreadsheet wrapped in Card component for better presentation
+ */
+export const InCard: Story = {
+  args: {
+    rows: 12,
+    columns: 6,
+    showToolbar: true,
+    enableImport: true,
+    enableExport: true,
+    enableSave: true,
+    title: 'Financial Report',
+    wrapInCard: true,
+  },
+  render: (args) => {
+    const [data, setData] = useState<Matrix<SpreadsheetCell>>();
+
+    return (
+      <Spreadsheet
+        {...args}
+        data={data}
+        onChange={setData}
+        onSave={async (data) => {
+          console.log('Saving:', data);
+          await new Promise((resolve) => setTimeout(resolve, 800));
+        }}
+      />
+    );
+  },
+};
+
+/**
+ * Pre-populated spreadsheet with formula examples
+ */
+export const WithFormulas: Story = {
+  render: () => {
+    const initialData: Matrix<SpreadsheetCell> = [
+      [
+        { value: 'Product', readOnly: true, className: 'font-bold' },
+        { value: 'Q1', readOnly: true, className: 'font-bold' },
+        { value: 'Q2', readOnly: true, className: 'font-bold' },
+        { value: 'Q3', readOnly: true, className: 'font-bold' },
+        { value: 'Q4', readOnly: true, className: 'font-bold' },
+        { value: 'Total', readOnly: true, className: 'font-bold' },
+      ],
+      [
+        { value: 'Widget A' },
+        { value: 15000 },
+        { value: 18000 },
+        { value: 22000 },
+        { value: 19000 },
+        { formula: '=SUM(B2:E2)' },
+      ],
+      [
+        { value: 'Widget B' },
+        { value: 12000 },
+        { value: 13500 },
+        { value: 14200 },
+        { value: 15800 },
+        { formula: '=SUM(B3:E3)' },
+      ],
+      [
+        { value: 'Widget C' },
+        { value: 8500 },
+        { value: 9200 },
+        { value: 11000 },
+        { value: 12300 },
+        { formula: '=SUM(B4:E4)' },
+      ],
+      [],
+      [
+        { value: 'Quarterly Total', readOnly: true, className: 'font-bold' },
+        { formula: '=SUM(B2:B4)' },
+        { formula: '=SUM(C2:C4)' },
+        { formula: '=SUM(D2:D4)' },
+        { formula: '=SUM(E2:E4)' },
+        { formula: '=SUM(F2:F4)' },
+      ],
+      [
+        { value: 'Average per Product', readOnly: true, className: 'font-bold' },
+        { formula: '=AVERAGE(B2:B4)' },
+        { formula: '=AVERAGE(C2:C4)' },
+        { formula: '=AVERAGE(D2:D4)' },
+        { formula: '=AVERAGE(E2:E4)' },
+        { formula: '=AVERAGE(F2:F4)' },
+      ],
+    ];
+
+    const [data, setData] = useState<Matrix<SpreadsheetCell>>(initialData);
+
+    return (
+      <div className="p-4">
+        <h3 className="text-lg font-semibold mb-4">Sales Report with Formulas</h3>
+        <p className="text-sm text-ink-600 mb-4">
+          This example demonstrates SUM and AVERAGE formulas. Try editing the values in Q1-Q4 columns
+          and watch the totals update automatically!
+        </p>
+        <Spreadsheet
+          data={data}
+          onChange={setData}
+          showToolbar
+          enableExport
+          enableSave
+          title="Quarterly Sales Report"
+          wrapInCard
+          exportFileName="sales-report.xlsx"
+          onSave={async (data) => {
+            console.log('Saving report:', data);
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+          }}
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Read-only spreadsheet for viewing reports
+ */
+export const ReadOnly: Story = {
+  render: () => {
+    const reportData: Matrix<SpreadsheetCell> = [
+      [
+        { value: 'Metric', readOnly: true },
+        { value: 'Value', readOnly: true },
+        { value: 'Target', readOnly: true },
+        { value: 'Status', readOnly: true },
+      ],
+      [{ value: 'Revenue' }, { value: 125000 }, { value: 120000 }, { value: '✓ Met' }],
+      [{ value: 'Expenses' }, { value: 85000 }, { value: 90000 }, { value: '✓ Under' }],
+      [{ value: 'Profit' }, { formula: '=B2-B3' }, { formula: '=C2-C3' }, { value: '✓ Above' }],
+      [{ value: 'Margin %' }, { formula: '=B4/B2*100' }, { formula: '=C4/C2*100' }, { value: '' }],
+    ];
+
+    return (
+      <Spreadsheet
+        data={reportData}
+        readOnly
+        title="Financial Summary (Read-Only)"
+        showToolbar
+        enableExport
+        wrapInCard
+        exportFileName="financial-summary.xlsx"
+      />
+    );
+  },
+};
+
+/**
+ * SpreadsheetReport component - pre-configured for report designer use
+ */
+export const ReportDesigner: Story = {
+  render: () => {
+    const [reportData, setReportData] = useState<Matrix<SpreadsheetCell>>([
+      [
+        { value: 'Month', readOnly: true },
+        { value: 'Sales', readOnly: true },
+        { value: 'Costs', readOnly: true },
+        { value: 'Profit', readOnly: true },
+      ],
+      [{ value: 'January' }, { value: 50000 }, { value: 30000 }, { formula: '=B2-C2' }],
+      [{ value: 'February' }, { value: 55000 }, { value: 32000 }, { formula: '=B3-C3' }],
+      [{ value: 'March' }, { value: 62000 }, { value: 35000 }, { formula: '=B4-C4' }],
+      [],
+      [
+        { value: 'Total', readOnly: true },
+        { formula: '=SUM(B2:B4)' },
+        { formula: '=SUM(C2:C4)' },
+        { formula: '=SUM(D2:D4)' },
+      ],
+    ]);
+
+    return (
+      <div className="max-w-6xl mx-auto p-6">
+        <h2 className="text-2xl font-bold mb-4">Report Designer</h2>
+        <p className="text-ink-600 mb-6">
+          The SpreadsheetReport component comes pre-configured with toolbar, import/export, and save
+          functionality. Perfect for building interactive reports!
+        </p>
+
+        <SpreadsheetReport
+          data={reportData}
+          onChange={setReportData}
+          title="Monthly Financial Report"
+          exportFileName="monthly-report.xlsx"
+          onSave={async (data) => {
+            console.log('Saving report:', data);
+            await new Promise((resolve) => setTimeout(resolve, 1200));
+          }}
+        />
+
+        <div className="mt-6 p-4 bg-paper-50 border border-stone-200 rounded-lg">
+          <h3 className="font-semibold mb-2">Formula Support</h3>
+          <p className="text-sm text-ink-600 mb-2">
+            Fast Formula Parser provides 280+ Excel formulas including:
+          </p>
+          <ul className="text-sm text-ink-600 list-disc list-inside space-y-1">
+            <li>Math: SUM, AVERAGE, ROUND, ABS, POWER, SQRT</li>
+            <li>Logical: IF, AND, OR, NOT, IFERROR</li>
+            <li>Lookup: VLOOKUP, HLOOKUP, INDEX</li>
+            <li>Text: CONCATENATE, LEFT, RIGHT, TRIM, UPPER, LOWER</li>
+            <li>Date/Time: DATE, TODAY, YEAR, MONTH, DAY</li>
+            <li>Statistical: COUNT, COUNTIF, MAX, MIN, STDEV</li>
+          </ul>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Spreadsheet with custom actions in toolbar
+ */
+export const WithCustomActions: Story = {
+  render: () => {
+    const [data, setData] = useState<Matrix<SpreadsheetCell>>();
+
+    return (
+      <Spreadsheet
+        data={data}
+        onChange={setData}
+        rows={10}
+        columns={6}
+        showToolbar
+        enableImport
+        enableExport
+        title="Custom Actions Demo"
+        actions={
+          <>
+            <Button
+              variant="ghost"
+              size="sm"
+              icon={<Calculator className="h-4 w-4" />}
+              onClick={() => console.log('Calculate clicked')}
+            >
+              Calculate
+            </Button>
+            <Button
+              variant="secondary"
+              size="sm"
+              onClick={() => console.log('Clear clicked')}
+            >
+              Clear
+            </Button>
+          </>
+        }
+        wrapInCard
+      />
+    );
+  },
+};
+
+/**
+ * Compact spreadsheet for smaller spaces
+ */
+export const Compact: Story = {
+  args: {
+    rows: 8,
+    columns: 4,
+    showToolbar: false,
+    className: 'text-sm',
+  },
+};
+
+/**
+ * Large spreadsheet for complex data entry
+ */
+export const Large: Story = {
+  args: {
+    rows: 50,
+    columns: 20,
+    showToolbar: true,
+    enableImport: true,
+    enableExport: true,
+    enableSave: true,
+    title: 'Large Dataset Editor',
+    wrapInCard: true,
+  },
+  render: (args) => {
+    const [data, setData] = useState<Matrix<SpreadsheetCell>>();
+
+    return (
+      <div style={{ height: '600px' }}>
+        <Spreadsheet
+          {...args}
+          data={data}
+          onChange={setData}
+          onSave={async (data) => {
+            console.log('Saving large dataset');
+            await new Promise((resolve) => setTimeout(resolve, 1500));
+          }}
+        />
+      </div>
+    );
+  },
+};

package/src/components/Spreadsheet.tsx

@@ -0,0 +1,351 @@
+import React, { useState, useCallback } from 'react';
+import BaseSpreadsheet, { CellBase, Matrix } from 'react-spreadsheet';
+import { read, utils, writeFile, WorkBook } from 'xlsx';
+import Button from './Button';
+import Card, { CardHeader, CardTitle, CardContent } from './Card';
+import Stack from './Stack';
+import { Download, Upload, Save } from 'lucide-react';
+import { addSuccessMessage, addErrorMessage } from './StatusBar';
+import './Spreadsheet.css';
+
+// Re-export types for external use
+export type { CellBase, Matrix } from 'react-spreadsheet';
+
+/**
+ * Enhanced cell type with formula support
+ */
+export interface SpreadsheetCell extends CellBase {
+  value: string | number | boolean;
+  formula?: string;
+  readOnly?: boolean;
+  className?: string;
+}
+
+/**
+ * Spreadsheet component props
+ */
+export interface SpreadsheetProps {
+  /** Initial data matrix */
+  data?: Matrix<SpreadsheetCell>;
+  /** Callback when data changes */
+  onChange?: (data: Matrix<SpreadsheetCell>) => void;
+  /** Number of rows to display */
+  rows?: number;
+  /** Number of columns to display */
+  columns?: number;
+  /** Column labels (A, B, C... if not provided) */
+  columnLabels?: string[];
+  /** Row labels (1, 2, 3... if not provided) */
+  rowLabels?: string[];
+  /** Show toolbar with actions */
+  showToolbar?: boolean;
+  /** Enable Excel import */
+  enableImport?: boolean;
+  /** Enable Excel export */
+  enableExport?: boolean;
+  /** Enable save button */
+  enableSave?: boolean;
+  /** Save handler */
+  onSave?: (data: Matrix<SpreadsheetCell>) => Promise<void> | void;
+  /** Title to display in toolbar */
+  title?: string;
+  /** Additional toolbar actions */
+  actions?: React.ReactNode;
+  /** Wrap in Card component */
+  wrapInCard?: boolean;
+  /** Custom className for the spreadsheet container */
+  className?: string;
+  /** Make entire spreadsheet read-only */
+  readOnly?: boolean;
+  /** Default export filename */
+  exportFileName?: string;
+}
+
+/**
+ * Spreadsheet - Interactive spreadsheet component with formula support
+ *
+ * A full-featured spreadsheet component for report designers and data editing.
+ * Built on react-spreadsheet with Fast Formula Parser (280+ Excel formulas).
+ *
+ * **Features:**
+ * - Excel-like formula support (SUM, AVERAGE, VLOOKUP, IF, etc.)
+ * - Excel import/export with SheetJS
+ * - Save/load functionality
+ * - Keyboard navigation
+ * - Copy/paste support
+ * - Customizable styling to match notebook-ui aesthetic
+ *
+ * @example
+ * ```tsx
+ * // Basic spreadsheet
+ * <Spreadsheet
+ *   rows={10}
+ *   columns={5}
+ *   showToolbar
+ * />
+ *
+ * // Report designer with formulas
+ * const [reportData, setReportData] = useState<Matrix<SpreadsheetCell>>([
+ *   [{ value: 'Q1' }, { value: 100 }],
+ *   [{ value: 'Q2' }, { value: 200 }],
+ *   [{ value: 'Total' }, { formula: '=SUM(B1:B2)' }],
+ * ]);
+ *
+ * <Spreadsheet
+ *   data={reportData}
+ *   onChange={setReportData}
+ *   title="Sales Report"
+ *   showToolbar
+ *   enableImport
+ *   enableExport
+ *   enableSave
+ *   onSave={async (data) => {
+ *     await saveReport(data);
+ *   }}
+ * />
+ *
+ * // With custom actions
+ * <Spreadsheet
+ *   data={data}
+ *   onChange={setData}
+ *   showToolbar
+ *   actions={
+ *     <Button onClick={handleCustomAction}>Custom Action</Button>
+ *   }
+ * />
+ * ```
+ */
+export const Spreadsheet: React.FC<SpreadsheetProps> = ({
+  data: initialData,
+  onChange,
+  rows = 20,
+  columns = 10,
+  columnLabels,
+  rowLabels,
+  showToolbar = false,
+  enableImport = false,
+  enableExport = false,
+  enableSave = false,
+  onSave,
+  title,
+  actions,
+  wrapInCard = false,
+  className = '',
+  readOnly = false,
+  exportFileName = 'spreadsheet.xlsx',
+}) => {
+  // Initialize data if not provided
+  const [data, setData] = useState<Matrix<SpreadsheetCell>>(() => {
+    if (initialData) return initialData;
+    return Array(rows)
+      .fill(null)
+      .map(() => Array(columns).fill(null).map(() => ({ value: '' })));
+  });
+
+  const [isSaving, setIsSaving] = useState(false);
+
+  // Handle data changes
+  const handleChange = useCallback(
+    (newData: Matrix<SpreadsheetCell>) => {
+      setData(newData);
+      onChange?.(newData);
+    },
+    [onChange]
+  );
+
+  // Handle Excel import
+  const handleImport = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const file = event.target.files?.[0];
+      if (!file) return;
+
+      const reader = new FileReader();
+      reader.onload = (e) => {
+        try {
+          const workbook: WorkBook = read(e.target?.result, { type: 'binary' });
+          const sheetName = workbook.SheetNames[0];
+          const worksheet = workbook.Sheets[sheetName];
+
+          // Convert to array of arrays
+          const jsonData: any[][] = utils.sheet_to_json(worksheet, { header: 1 });
+
+          // Convert to spreadsheet format
+          const spreadsheetData: Matrix<SpreadsheetCell> = jsonData.map(row =>
+            row.map(cell => ({
+              value: cell,
+            }))
+          );
+
+          handleChange(spreadsheetData);
+          addSuccessMessage('Excel file imported successfully');
+        } catch (error) {
+          console.error('Error importing Excel file:', error);
+          addErrorMessage('Failed to import Excel file');
+        }
+      };
+      reader.readAsBinaryString(file);
+
+      // Reset input
+      event.target.value = '';
+    },
+    [handleChange]
+  );
+
+  // Handle Excel export
+  const handleExport = useCallback(() => {
+    try {
+      // Convert spreadsheet data to worksheet format
+      const worksheetData = data.map(row =>
+        row.map(cell => {
+          // If cell has a formula, export the calculated value
+          if (cell?.formula) {
+            return cell.value ?? cell.formula;
+          }
+          return cell?.value ?? '';
+        })
+      );
+
+      const worksheet = utils.aoa_to_sheet(worksheetData);
+      const workbook = utils.book_new();
+      utils.book_append_sheet(workbook, worksheet, 'Sheet1');
+
+      writeFile(workbook, exportFileName);
+      addSuccessMessage('Excel file exported successfully');
+    } catch (error) {
+      console.error('Error exporting Excel file:', error);
+      addErrorMessage('Failed to export Excel file');
+    }
+  }, [data, exportFileName]);
+
+  // Handle save
+  const handleSave = useCallback(async () => {
+    if (!onSave) return;
+
+    setIsSaving(true);
+    try {
+      await onSave(data);
+      addSuccessMessage('Spreadsheet saved successfully');
+    } catch (error) {
+      console.error('Error saving spreadsheet:', error);
+      addErrorMessage('Failed to save spreadsheet');
+    } finally {
+      setIsSaving(false);
+    }
+  }, [onSave, data]);
+
+  // Build toolbar
+  const toolbar = showToolbar && (
+    <Stack direction="horizontal" spacing="md" align="center" className="mb-4">
+      {title && <div className="text-lg font-medium text-ink-900 flex-1">{title}</div>}
+
+      {enableImport && (
+        <label>
+          <input
+            type="file"
+            accept=".xlsx,.xls,.csv"
+            onChange={handleImport}
+            className="hidden"
+          />
+          <Button variant="ghost" size="sm" icon={<Upload className="h-4 w-4" />}>
+            Import
+          </Button>
+        </label>
+      )}
+
+      {enableExport && (
+        <Button
+          variant="ghost"
+          size="sm"
+          icon={<Download className="h-4 w-4" />}
+          onClick={handleExport}
+        >
+          Export
+        </Button>
+      )}
+
+      {enableSave && onSave && (
+        <Button
+          variant="primary"
+          size="sm"
+          icon={<Save className="h-4 w-4" />}
+          onClick={handleSave}
+          loading={isSaving}
+        >
+          Save
+        </Button>
+      )}
+
+      {actions}
+    </Stack>
+  );
+
+  // Spreadsheet component
+  const spreadsheet = (
+    <div className={`spreadsheet-container ${className}`}>
+      <BaseSpreadsheet
+        data={data}
+        onChange={readOnly ? undefined : handleChange}
+        columnLabels={columnLabels}
+        rowLabels={rowLabels}
+        className="notebook-spreadsheet"
+      />
+    </div>
+  );
+
+  // Wrap in card if requested
+  if (wrapInCard) {
+    return (
+      <Card>
+        {(showToolbar || title) && (
+          <CardHeader>
+            {title && !showToolbar && <CardTitle>{title}</CardTitle>}
+            {toolbar}
+          </CardHeader>
+        )}
+        <CardContent>{spreadsheet}</CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <>
+      {toolbar}
+      {spreadsheet}
+    </>
+  );
+};
+
+/**
+ * SpreadsheetReport - Pre-configured spreadsheet for report designer
+ *
+ * A ready-to-use spreadsheet component specifically designed for building
+ * and editing reports with formulas, import/export, and save functionality.
+ *
+ * @example
+ * ```tsx
+ * const [reportData, setReportData] = useState<Matrix<SpreadsheetCell>>();
+ *
+ * <SpreadsheetReport
+ *   data={reportData}
+ *   onChange={setReportData}
+ *   title="Monthly Sales Report"
+ *   onSave={async (data) => {
+ *     await api.saveReport(reportId, data);
+ *   }}
+ * />
+ * ```
+ */
+export const SpreadsheetReport: React.FC<
+  Omit<SpreadsheetProps, 'showToolbar' | 'enableImport' | 'enableExport' | 'enableSave' | 'wrapInCard'>
+> = (props) => {
+  return (
+    <Spreadsheet
+      {...props}
+      showToolbar
+      enableImport
+      enableExport
+      enableSave
+      wrapInCard
+    />
+  );
+};