@docyrus/ui-pro-ai-assistant 0.0.1

package/src/internal/sheets/components/univer-sheets.tsx

@@ -0,0 +1,1104 @@
+// Univer Plugin Mode imports - Core
+import {
+  useCallback, useEffect, useRef, useState, type ChangeEvent
+} from 'react';
+
+import {
+  CommandType,
+  ICommandService,
+  LocaleType,
+  Univer,
+  UniverInstanceType,
+  type ICommand
+} from '@univerjs/core';
+import { defaultTheme } from '@univerjs/design';
+// ==== LOCALE IMPORTS - English (en-US) ====
+import DesignEnUS from '@univerjs/design/locale/en-US';
+// ==== LOCALE IMPORTS - Spanish (es-ES) ====
+import DesignEsES from '@univerjs/design/locale/es-ES';
+// ==== LOCALE IMPORTS - French (fr-FR) ====
+import DesignFrFR from '@univerjs/design/locale/fr-FR';
+import { UniverDocsPlugin } from '@univerjs/docs';
+import { UniverDocsUIPlugin } from '@univerjs/docs-ui';
+import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US';
+import DocsUIEsES from '@univerjs/docs-ui/locale/es-ES';
+import DocsUIFrFR from '@univerjs/docs-ui/locale/fr-FR';
+// Drawing plugins (required for images)
+import { UniverDrawingPlugin } from '@univerjs/drawing';
+import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui';
+import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US';
+import DrawingUIEsES from '@univerjs/drawing-ui/locale/es-ES';
+import DrawingUIFrFR from '@univerjs/drawing-ui/locale/fr-FR';
+import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
+import { UniverRenderEnginePlugin } from '@univerjs/engine-render';
+// Find & Replace plugin
+import FindReplaceEnUS from '@univerjs/find-replace/locale/en-US';
+import FindReplaceEsES from '@univerjs/find-replace/locale/es-ES';
+import FindReplaceFrFR from '@univerjs/find-replace/locale/fr-FR';
+import { UniverSheetsPlugin } from '@univerjs/sheets';
+import SheetsEnUS from '@univerjs/sheets/locale/en-US';
+import SheetsEsES from '@univerjs/sheets/locale/es-ES';
+import SheetsFrFR from '@univerjs/sheets/locale/fr-FR';
+// Conditional Formatting plugins
+import { UniverSheetsConditionalFormattingPlugin } from '@univerjs/sheets-conditional-formatting';
+import { UniverSheetsConditionalFormattingUIPlugin } from '@univerjs/sheets-conditional-formatting-ui';
+import SheetsConditionalFormattingUIEnUS from '@univerjs/sheets-conditional-formatting-ui/locale/en-US';
+import SheetsConditionalFormattingUIEsES from '@univerjs/sheets-conditional-formatting-ui/locale/es-ES';
+import SheetsConditionalFormattingUIFrFR from '@univerjs/sheets-conditional-formatting-ui/locale/fr-FR';
+// Crosshair Highlight plugin
+import { UniverSheetsCrosshairHighlightPlugin } from '@univerjs/sheets-crosshair-highlight';
+import SheetsCrosshairHighlightEnUS from '@univerjs/sheets-crosshair-highlight/locale/en-US';
+import SheetsCrosshairHighlightEsES from '@univerjs/sheets-crosshair-highlight/locale/es-ES';
+import SheetsCrosshairHighlightFrFR from '@univerjs/sheets-crosshair-highlight/locale/fr-FR';
+// Data Validation plugins
+import { UniverSheetsDataValidationPlugin } from '@univerjs/sheets-data-validation';
+import { UniverSheetsDataValidationUIPlugin } from '@univerjs/sheets-data-validation-ui';
+import SheetsDataValidationUIEnUS from '@univerjs/sheets-data-validation-ui/locale/en-US';
+import SheetsDataValidationUIEsES from '@univerjs/sheets-data-validation-ui/locale/es-ES';
+import SheetsDataValidationUIFrFR from '@univerjs/sheets-data-validation-ui/locale/fr-FR';
+import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing';
+import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui';
+import SheetsDrawingUIEnUS from '@univerjs/sheets-drawing-ui/locale/en-US';
+import SheetsDrawingUIEsES from '@univerjs/sheets-drawing-ui/locale/es-ES';
+import SheetsDrawingUIFrFR from '@univerjs/sheets-drawing-ui/locale/fr-FR';
+// Filter plugins
+import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter';
+import { UniverSheetsFilterUIPlugin } from '@univerjs/sheets-filter-ui';
+import SheetsFilterUIEnUS from '@univerjs/sheets-filter-ui/locale/en-US';
+import SheetsFilterUIEsES from '@univerjs/sheets-filter-ui/locale/es-ES';
+import SheetsFilterUIFrFR from '@univerjs/sheets-filter-ui/locale/fr-FR';
+import { UniverSheetsFindReplacePlugin } from '@univerjs/sheets-find-replace';
+import SheetsFindReplaceEnUS from '@univerjs/sheets-find-replace/locale/en-US';
+import SheetsFindReplaceEsES from '@univerjs/sheets-find-replace/locale/es-ES';
+import SheetsFindReplaceFrFR from '@univerjs/sheets-find-replace/locale/fr-FR';
+import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula';
+import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui';
+import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US';
+import SheetsFormulaUIEsES from '@univerjs/sheets-formula-ui/locale/es-ES';
+import SheetsFormulaUIFrFR from '@univerjs/sheets-formula-ui/locale/fr-FR';
+// Hyperlink plugins
+import { UniverSheetsHyperLinkPlugin } from '@univerjs/sheets-hyper-link';
+import { UniverSheetsHyperLinkUIPlugin } from '@univerjs/sheets-hyper-link-ui';
+import SheetsHyperLinkUIEnUS from '@univerjs/sheets-hyper-link-ui/locale/en-US';
+import SheetsHyperLinkUIEsES from '@univerjs/sheets-hyper-link-ui/locale/es-ES';
+import SheetsHyperLinkUIFrFR from '@univerjs/sheets-hyper-link-ui/locale/fr-FR';
+import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt';
+import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui';
+import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US';
+import SheetsNumfmtUIEsES from '@univerjs/sheets-numfmt-ui/locale/es-ES';
+import SheetsNumfmtUIFrFR from '@univerjs/sheets-numfmt-ui/locale/fr-FR';
+// Sort plugins
+import { UniverSheetsSortPlugin } from '@univerjs/sheets-sort';
+import { UniverSheetsSortUIPlugin } from '@univerjs/sheets-sort-ui';
+import SheetsSortUIEnUS from '@univerjs/sheets-sort-ui/locale/en-US';
+import SheetsSortUIEsES from '@univerjs/sheets-sort-ui/locale/es-ES';
+import SheetsSortUIFrFR from '@univerjs/sheets-sort-ui/locale/fr-FR';
+// Thread Comment plugins
+import { UniverSheetsThreadCommentPlugin } from '@univerjs/sheets-thread-comment';
+import { UniverSheetsThreadCommentUIPlugin } from '@univerjs/sheets-thread-comment-ui';
+import SheetsThreadCommentUIEnUS from '@univerjs/sheets-thread-comment-ui/locale/en-US';
+import SheetsThreadCommentUIEsES from '@univerjs/sheets-thread-comment-ui/locale/es-ES';
+import SheetsThreadCommentUIFrFR from '@univerjs/sheets-thread-comment-ui/locale/fr-FR';
+import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui';
+import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US';
+import SheetsUIEsES from '@univerjs/sheets-ui/locale/es-ES';
+import SheetsUIFrFR from '@univerjs/sheets-ui/locale/fr-FR';
+import ThreadCommentUIEnUS from '@univerjs/thread-comment-ui/locale/en-US';
+import ThreadCommentUIEsES from '@univerjs/thread-comment-ui/locale/es-ES';
+import ThreadCommentUIFrFR from '@univerjs/thread-comment-ui/locale/fr-FR';
+import {
+  ComponentManager,
+  IMenuManagerService,
+  MenuItemType,
+  RibbonStartGroup,
+  UniverUIPlugin,
+  type IFontConfig
+} from '@univerjs/ui';
+import UIEnUS from '@univerjs/ui/locale/en-US';
+import UIEsES from '@univerjs/ui/locale/es-ES';
+import UIFrFR from '@univerjs/ui/locale/fr-FR';
+// Watermark plugin
+import { UniverWatermarkPlugin } from '@univerjs/watermark';
+import { FUniver } from '@univerjs/core/facade';
+
+// Facade API imports - Core
+import '@univerjs/sheets/facade';
+import '@univerjs/sheets-ui/facade';
+import '@univerjs/sheets-numfmt/facade';
+
+// Facade API imports - Feature plugins
+import '@univerjs/sheets-data-validation/facade';
+import '@univerjs/sheets-conditional-formatting/facade';
+import '@univerjs/sheets-filter/facade';
+import '@univerjs/sheets-sort/facade';
+import '@univerjs/sheets-hyper-link/facade';
+import '@univerjs/sheets-find-replace/facade';
+import '@univerjs/sheets-thread-comment/facade';
+import '@univerjs/sheets-drawing-ui/facade';
+import '@univerjs/watermark/facade';
+import '@univerjs/sheets-crosshair-highlight/facade';
+// CSS imports - order matters!
+import '@univerjs/design/lib/index.css';
+import '@univerjs/ui/lib/index.css';
+import '@univerjs/docs-ui/lib/index.css';
+import '@univerjs/sheets-ui/lib/index.css';
+import '@univerjs/sheets-formula-ui/lib/index.css';
+import '@univerjs/sheets-numfmt-ui/lib/index.css';
+
+// CSS imports - Feature plugins
+import '@univerjs/drawing-ui/lib/index.css';
+import '@univerjs/sheets-drawing-ui/lib/index.css';
+import '@univerjs/sheets-data-validation-ui/lib/index.css';
+import '@univerjs/sheets-conditional-formatting-ui/lib/index.css';
+import '@univerjs/sheets-filter-ui/lib/index.css';
+import '@univerjs/sheets-sort-ui/lib/index.css';
+import '@univerjs/sheets-hyper-link-ui/lib/index.css';
+import '@univerjs/sheets-thread-comment-ui/lib/index.css';
+import '@univerjs/sheets-crosshair-highlight/lib/index.css';
+
+import { type Locale } from '../i18n/types';
+
+import { type IWorkbookData as XlsxWorkbookData } from '../types';
+
+import { csvToUniver, downloadWorkbook, xlsxToUniver } from '../xlsx';
+
+// Custom font list - only common fonts, excluding Chinese-specific fonts
+const CUSTOM_FONT_LIST: IFontConfig[] = [
+  { value: 'Arial', label: 'fontFamily.arial', category: 'sans-serif' },
+  { value: 'Times New Roman', label: 'fontFamily.times-new-roman', category: 'serif' },
+  { value: 'Tahoma', label: 'fontFamily.tahoma', category: 'sans-serif' },
+  { value: 'Verdana', label: 'fontFamily.verdana', category: 'sans-serif' },
+  { value: 'Georgia', label: 'fontFamily.georgia', category: 'serif' },
+  { value: 'Courier New', label: 'fontFamily.courier-new', category: 'monospace' },
+  { value: 'Trebuchet MS', label: 'fontFamily.trebuchet-ms', category: 'sans-serif' },
+  { value: 'Comic Sans MS', label: 'fontFamily.comic-sans-ms', category: 'handwriting' }
+];
+
+// Deep merge utility for locale objects
+function deepMerge(...objects: unknown[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const obj of objects) {
+    if (obj && typeof obj === 'object') {
+      for (const key of Object.keys(obj)) {
+        const value = (obj as Record<string, unknown>)[key];
+
+        if (
+          typeof value === 'object'
+          && value !== null
+          && !Array.isArray(value)
+          && typeof result[key] === 'object'
+          && result[key] !== null
+          && !Array.isArray(result[key])
+        ) {
+          result[key] = deepMerge(result[key] as Record<string, unknown>, value as Record<string, unknown>);
+        } else {
+          result[key] = value;
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// Additional font family translations for custom fonts not in Univer defaults
+const CUSTOM_FONT_TRANSLATIONS = {
+  fontFamily: {
+    georgia: 'Georgia',
+    'courier-new': 'Courier New',
+    'trebuchet-ms': 'Trebuchet MS',
+    'comic-sans-ms': 'Comic Sans MS'
+  }
+};
+
+// Pre-merged locale data for each supported Univer locale
+const UNIVER_LOCALES = {
+  'en-US': deepMerge(
+    DesignEnUS,
+    UIEnUS,
+    DocsUIEnUS,
+    SheetsEnUS,
+    SheetsUIEnUS,
+    SheetsFormulaUIEnUS,
+    SheetsNumfmtUIEnUS,
+    DrawingUIEnUS,
+    SheetsDrawingUIEnUS,
+    SheetsDataValidationUIEnUS,
+    SheetsConditionalFormattingUIEnUS,
+    SheetsFilterUIEnUS,
+    SheetsSortUIEnUS,
+    SheetsHyperLinkUIEnUS,
+    FindReplaceEnUS,
+    SheetsFindReplaceEnUS,
+    ThreadCommentUIEnUS,
+    SheetsThreadCommentUIEnUS,
+    SheetsCrosshairHighlightEnUS,
+    CUSTOM_FONT_TRANSLATIONS
+  ),
+  'es-ES': deepMerge(
+    DesignEsES,
+    UIEsES,
+    DocsUIEsES,
+    SheetsEsES,
+    SheetsUIEsES,
+    SheetsFormulaUIEsES,
+    SheetsNumfmtUIEsES,
+    DrawingUIEsES,
+    SheetsDrawingUIEsES,
+    SheetsDataValidationUIEsES,
+    SheetsConditionalFormattingUIEsES,
+    SheetsFilterUIEsES,
+    SheetsSortUIEsES,
+    SheetsHyperLinkUIEsES,
+    FindReplaceEsES,
+    SheetsFindReplaceEsES,
+    ThreadCommentUIEsES,
+    SheetsThreadCommentUIEsES,
+    SheetsCrosshairHighlightEsES,
+    CUSTOM_FONT_TRANSLATIONS
+  ),
+  'fr-FR': deepMerge(
+    DesignFrFR,
+    UIFrFR,
+    DocsUIFrFR,
+    SheetsFrFR,
+    SheetsUIFrFR,
+    SheetsFormulaUIFrFR,
+    SheetsNumfmtUIFrFR,
+    DrawingUIFrFR,
+    SheetsDrawingUIFrFR,
+    SheetsDataValidationUIFrFR,
+    SheetsConditionalFormattingUIFrFR,
+    SheetsFilterUIFrFR,
+    SheetsSortUIFrFR,
+    SheetsHyperLinkUIFrFR,
+    FindReplaceFrFR,
+    SheetsFindReplaceFrFR,
+    ThreadCommentUIFrFR,
+    SheetsThreadCommentUIFrFR,
+    SheetsCrosshairHighlightFrFR,
+    CUSTOM_FONT_TRANSLATIONS
+  )
+} as const;
+
+type UniverLocaleCode = keyof typeof UNIVER_LOCALES;
+
+// Map app locale to Univer locale
+function getUniverLocale(appLocale: Locale): {
+  code: UniverLocaleCode;
+  type: LocaleType;
+  data: Record<string, unknown>;
+} {
+  const mapping: Record<Locale, { code: UniverLocaleCode; type: LocaleType }> = {
+    en: { code: 'en-US', type: LocaleType.EN_US },
+    es: { code: 'es-ES', type: LocaleType.ES_ES },
+    fr: { code: 'fr-FR', type: LocaleType.FR_FR },
+    de: { code: 'en-US', type: LocaleType.EN_US }, // Fallback - German not supported by Univer
+    el: { code: 'en-US', type: LocaleType.EN_US }, // Fallback - Greek not supported by Univer
+    it: { code: 'en-US', type: LocaleType.EN_US }, // Fallback - Italian not supported by Univer
+    pt: { code: 'en-US', type: LocaleType.EN_US }, // Fallback - Portuguese not supported by Univer
+    sl: { code: 'en-US', type: LocaleType.EN_US }, // Fallback - Slovenian not supported by Univer
+    tr: { code: 'en-US', type: LocaleType.EN_US } // Fallback - Turkish not supported by Univer
+  };
+  const localeInfo = mapping[appLocale] || mapping.en;
+
+  return {
+    ...localeInfo,
+    data: UNIVER_LOCALES[localeInfo.code]
+  };
+}
+
+/**
+ * Map app locale to numfmt locale for decimal/thousands separator
+ * This affects how numbers are displayed (e.g., 1,234.56 vs 1.234,56)
+ */
+function getNumfmtLocale(appLocale: Locale): string {
+  const mapping: Record<Locale, string> = {
+    en: 'en_US',
+    es: 'es_ES',
+    fr: 'fr_FR',
+    de: 'de_DE',
+    el: 'el_GR',
+    it: 'it_IT',
+    pt: 'pt_PT',
+    sl: 'sl_SI',
+    tr: 'tr_TR'
+  };
+
+  return mapping[appLocale] || 'en_US';
+}
+
+/*
+ * ============================================================================
+ * Import/Export Toolbar Setup
+ * ============================================================================
+ */
+
+// Command IDs
+const IMPORT_XLSX_COMMAND_ID = 'docyrus.sheets.import-xlsx';
+const EXPORT_XLSX_COMMAND_ID = 'docyrus.sheets.export-xlsx';
+const EXPORT_CSV_COMMAND_ID = 'docyrus.sheets.export-csv';
+
+// Import/Export command handlers - will be set by the component
+const importExportHandlers = {
+  import: null as (() => void) | null,
+  exportXlsx: null as (() => void) | null,
+  exportCsv: null as (() => void) | null
+};
+
+// Setup import/export toolbar buttons after Univer is initialized
+function setupImportExportToolbar(univer: Univer): void {
+  const injector = (univer as any).__injector || (univer as any)._injector;
+
+  if (!injector) {
+    console.warn('[UniverSheets] Could not access injector for toolbar setup');
+
+    return;
+  }
+
+  try {
+    const commandService = injector.get(ICommandService);
+    const menuManagerService = injector.get(IMenuManagerService);
+    const componentManager = injector.get(ComponentManager);
+
+    // Register icons
+    componentManager.register('ImportIcon', () => (
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+        <polyline points="17 8 12 3 7 8" />
+        <line x1="12" y1="3" x2="12" y2="15" />
+        <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+      </svg>
+    ));
+
+    componentManager.register('ExportXlsxIcon', () => (
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#217346" strokeWidth="2">
+        <polyline points="7 10 12 15 17 10" />
+        <line x1="12" y1="15" x2="12" y2="3" />
+        <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+      </svg>
+    ));
+
+    componentManager.register('ExportCsvIcon', () => (
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#666" strokeWidth="2">
+        <polyline points="7 10 12 15 17 10" />
+        <line x1="12" y1="15" x2="12" y2="3" />
+        <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+      </svg>
+    ));
+
+    // Register commands
+    const importCommand: ICommand = {
+      id: IMPORT_XLSX_COMMAND_ID,
+      type: CommandType.COMMAND,
+      handler: async () => {
+        importExportHandlers.import?.();
+
+        return true;
+      }
+    };
+
+    const exportXlsxCommand: ICommand = {
+      id: EXPORT_XLSX_COMMAND_ID,
+      type: CommandType.COMMAND,
+      handler: async () => {
+        importExportHandlers.exportXlsx?.();
+
+        return true;
+      }
+    };
+
+    const exportCsvCommand: ICommand = {
+      id: EXPORT_CSV_COMMAND_ID,
+      type: CommandType.COMMAND,
+      handler: async () => {
+        importExportHandlers.exportCsv?.();
+
+        return true;
+      }
+    };
+
+    commandService.registerCommand(importCommand);
+    commandService.registerCommand(exportXlsxCommand);
+    commandService.registerCommand(exportCsvCommand);
+
+    // Add menu items to toolbar ribbon
+    menuManagerService.mergeMenu({
+      [RibbonStartGroup.OTHERS]: {
+        [IMPORT_XLSX_COMMAND_ID]: {
+          order: 0,
+          menuItemFactory: () => ({
+            id: IMPORT_XLSX_COMMAND_ID,
+            title: 'Import',
+            tooltip: 'Import XLSX/CSV',
+            icon: 'ImportIcon',
+            type: MenuItemType.BUTTON
+          })
+        },
+        [EXPORT_XLSX_COMMAND_ID]: {
+          order: 1,
+          menuItemFactory: () => ({
+            id: EXPORT_XLSX_COMMAND_ID,
+            title: 'XLSX',
+            tooltip: 'Export as XLSX',
+            icon: 'ExportXlsxIcon',
+            type: MenuItemType.BUTTON
+          })
+        },
+        [EXPORT_CSV_COMMAND_ID]: {
+          order: 2,
+          menuItemFactory: () => ({
+            id: EXPORT_CSV_COMMAND_ID,
+            title: 'CSV',
+            tooltip: 'Export as CSV',
+            icon: 'ExportCsvIcon',
+            type: MenuItemType.BUTTON
+          })
+        }
+      }
+    });
+
+    console.info('[UniverSheets] Import/Export toolbar buttons registered');
+  } catch (err) {
+    console.warn('[UniverSheets] Failed to setup import/export toolbar:', err);
+  }
+}
+
+// Type definitions
+export interface SheetsPayload {
+  workbookData?: Record<string, unknown>;
+  user?: {
+    tenantId?: string;
+    name?: string;
+  };
+  recordId?: string;
+  versionId?: string;
+}
+
+export interface IApiCallPayload {
+  id?: string;
+  method: string;
+  args?: unknown[];
+}
+
+export interface UniverSheetsProps {
+  /** Initial workbook data to load */
+  initialData?: unknown;
+  /** Locale for UI translations (default: "en") */
+  locale?: Locale;
+  /** Commands to execute after the workbook loads */
+  commands?: IApiCallPayload[];
+  onReady?: () => void;
+  onData?: (data: { workbook: unknown; workbookJson: string }) => void;
+  onLoaded?: (data: { workbookId: string }) => void;
+  onError?: (error: string) => void;
+}
+
+const SAMPLE_WORKBOOK_DATA = {};
+
+type RangeObj = any;
+type SheetObj = any;
+
+const RANGE_ACTIONS: Record<string, (r: RangeObj, a: unknown[]) => void> = {
+  setValue: (r, a) => r.setValue(a[0]),
+  setValues: (r, a) => r.setValues(a[0]),
+  getValue: r => r.getValue(),
+  getValues: r => r.getValues(),
+  setBackgroundColor: (r, a) => r.setBackgroundColor(a[0]),
+  setFontColor: (r, a) => r.setFontColor(a[0]),
+  setFontWeight: (r, a) => r.setFontWeight(a[0]),
+  setFontStyle: (r, a) => r.setFontStyle(a[0]),
+  setFontSize: (r, a) => r.setFontSize(a[0]),
+  setFontFamily: (r, a) => r.setFontFamily(a[0]),
+  setHorizontalAlignment: (r, a) => r.setHorizontalAlignment(a[0]),
+  setVerticalAlignment: (r, a) => r.setVerticalAlignment(a[0]),
+  setNumberFormat: (r, a) => r.setNumberFormat(a[0]),
+  setWrap: (r, a) => r.setWrap(a[0]),
+  setBorder: (r, a) => r.setBorder(a[0], a[1], a[2], a[3], a[4], a[5]),
+  setNote: (r, a) => r.setNote(a[0]),
+  getNote: r => r.getNote(),
+  clearNote: r => r.clearNote(),
+  merge: r => r.merge(),
+  unmerge: r => r.breakApart(),
+  clearFormat: r => r.clearFormat(),
+  clearContent: r => r.clearContent(),
+  clear: r => r.clear(),
+  activate: r => r.activate(),
+  isMerged: r => r.isMerged(),
+  copyTo: (r, a) => r.copyTo(a[0]),
+  sort: (r, a) => r.sort(a[0])
+};
+
+const SHEET_ACTIONS: Record<string, (s: SheetObj, a: unknown[]) => void> = {
+  insertRowsAfter: (s, a) => s.insertRowsAfter(a[0], a[1]),
+  insertRowsBefore: (s, a) => s.insertRowsBefore(a[0], a[1]),
+  deleteRows: (s, a) => s.deleteRows(a[0], a[1]),
+  insertColumnsAfter: (s, a) => s.insertColumnsAfter(a[0], a[1]),
+  insertColumnsBefore: (s, a) => s.insertColumnsBefore(a[0], a[1]),
+  deleteColumns: (s, a) => s.deleteColumns(a[0], a[1]),
+  setRowHeight: (s, a) => s.setRowHeight(a[0], a[1]),
+  setColumnWidth: (s, a) => s.setColumnWidth(a[0], a[1]),
+  setFrozenRows: (s, a) => s.setFrozenRows(a[0]),
+  setFrozenColumns: (s, a) => s.setFrozenColumns(a[0]),
+  setName: (s, a) => s.setName(a[0]),
+  activate: s => s.activate(),
+  hideRows: (s, a) => s.hideRows(a[0], a[1]),
+  showRows: (s, a) => s.showRows(a[0], a[1]),
+  hideColumns: (s, a) => s.hideColumns(a[0], a[1]),
+  showColumns: (s, a) => s.showColumns(a[0], a[1]),
+  zoom: (s, a) => s.zoom(a[0]),
+  getMaxRows: s => s.getMaxRows(),
+  getMaxColumns: s => s.getMaxColumns()
+};
+
+// Instance generation counter to handle React Strict Mode cleanup timing
+let instanceGeneration = 0;
+
+export function UniverSheets({
+  initialData,
+  locale = 'en',
+  commands,
+  onReady,
+  onData,
+  onLoaded,
+  onError: _onError
+}: UniverSheetsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const univerRef = useRef<Univer | null>(null);
+  const univerAPIRef = useRef<FUniver | null>(null);
+  const instanceGenerationRef = useRef<number>(0);
+  const pendingDataRef = useRef<unknown>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const workbookNameRef = useRef<string>('');
+  const [isClient, setIsClient] = useState(false);
+
+  // Store callbacks in refs to avoid effect re-runs when they change
+  const onReadyRef = useRef(onReady);
+  const onDataRef = useRef(onData);
+  const onLoadedRef = useRef(onLoaded);
+  // Store initial data in ref - only used on first load
+  const initialDataRef = useRef(initialData);
+  // Store commands in ref so they're accessible inside the initialization effect
+  const commandsRef = useRef(commands);
+  // True while the initial createUnit is pending its async doc.command-replace-snapshot
+  const isInitializingRef = useRef(false);
+  // Skip first-mount run of the commands effect (init effect already handles it)
+  const isCommandsInitialMountRef = useRef(true);
+
+  // Update refs when callbacks change
+  useEffect(() => {
+    onReadyRef.current = onReady;
+    onDataRef.current = onData;
+    onLoadedRef.current = onLoaded;
+  }, [onReady, onData, onLoaded]);
+
+  /*
+   * Execute an api:call payload directly against the Univer API.
+   * Method format: 'range:A1:setValue' | 'sheet:methodName' | 'undo' | 'redo'
+   */
+  const executeApiCommand = useCallback(async (payload: IApiCallPayload) => {
+    if (!univerAPIRef.current) {
+      console.warn('[Sheets] executeApiCommand called but Univer not ready:', payload.method);
+
+      return;
+    }
+
+    const { method, args = [] } = payload;
+    const parts = method.split(':');
+    const target = parts[0];
+    const action = parts[parts.length - 1];
+
+    try {
+      const workbook = univerAPIRef.current.getActiveWorkbook();
+      const sheet = workbook?.getActiveSheet();
+
+      if (target === 'undo') {
+        await univerAPIRef.current.executeCommand('univer.command.undo');
+      } else if (target === 'redo') {
+        await univerAPIRef.current.executeCommand('univer.command.redo');
+      } else if (target === 'range') {
+        if (!sheet) throw new Error('No active sheet');
+
+        const selector = parts.slice(1, -1).join(':');
+        const range = sheet.getRange(selector);
+        const fn = RANGE_ACTIONS[action];
+
+        if (fn) {
+          fn(range, args);
+        } else {
+          console.warn('[Sheets] Unknown range action:', action);
+        }
+      } else if (target === 'sheet') {
+        if (!sheet) throw new Error('No active sheet');
+
+        const fn = SHEET_ACTIONS[action];
+
+        if (fn) {
+          fn(sheet, args);
+        } else {
+          console.warn('[Sheets] Unknown sheet action:', action);
+        }
+      } else {
+        console.warn('[Sheets] Unknown api:call target:', target);
+      }
+    } catch (err) {
+      console.error('[Sheets] api:call failed:', method, err);
+    }
+  }, []);
+
+  /*
+   * Handle api:call postMessages from parent
+   * Format: { type: 'event', eventName: 'api:call', payload: { id, method, args } }
+   */
+  useEffect(() => {
+    const handleApiCall = (event: MessageEvent) => {
+      if (!event.data || typeof event.data !== 'object') return;
+
+      const { type, eventName, payload } = event.data;
+
+      if (type !== 'event' || eventName !== 'api:call' || !payload?.method) return;
+
+      void executeApiCommand(payload as IApiCallPayload);
+    };
+
+    window.addEventListener('message', handleApiCall);
+
+    return () => window.removeEventListener('message', handleApiCall);
+  }, [executeApiCommand]);
+
+  // Execute new commands whenever the commands prop changes after initial mount
+  useEffect(() => {
+    commandsRef.current = commands;
+
+    if (isCommandsInitialMountRef.current) {
+      isCommandsInitialMountRef.current = false;
+
+      return;
+    }
+
+    if (!commands?.length || !univerAPIRef.current) return;
+
+    for (const cmd of commands) {
+      void executeApiCommand(cmd);
+    }
+  }, [commands, executeApiCommand]);
+
+  // Handle file import
+  const handleImport = () => {
+    fileInputRef.current?.click();
+  };
+
+  const handleFileChange = async (e: ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+
+    if (!file) return;
+
+    try {
+      const arrayBuffer = await file.arrayBuffer();
+      const bytes = new Uint8Array(arrayBuffer);
+      const filename = file.name.toLowerCase();
+      const isCSV = filename.endsWith('.csv');
+
+      let workbookData: XlsxWorkbookData;
+
+      const workbookName = file.name.replace(/\.[^.]+$/, '');
+
+      if (isCSV) {
+        const text = new TextDecoder().decode(bytes);
+
+        workbookData = csvToUniver(text, {
+          workbookName,
+          firstRowIsHeader: true
+        });
+      } else {
+        workbookData = xlsxToUniver(arrayBuffer, {
+          workbookName
+        });
+      }
+
+      // Track the workbook name for export
+      workbookNameRef.current = workbookName;
+
+      if (univerRef.current) {
+        univerRef.current.createUnit(UniverInstanceType.UNIVER_SHEET, workbookData as any);
+      }
+    } catch (err) {
+      console.error('Import error:', err);
+    }
+
+    e.target.value = '';
+  };
+
+  // Get workbook name for export (fallback to ref, sheet name, ID, or timestamp)
+  const getExportFileName = useCallback((workbookData: XlsxWorkbookData): string => {
+    // Use workbook name from data if available and not empty
+    if (workbookData.name && workbookData.name.trim()) {
+      return workbookData.name.trim();
+    }
+
+    // Fallback to tracked workbook name (from import or initial load)
+    if (workbookNameRef.current && workbookNameRef.current.trim()) {
+      return workbookNameRef.current.trim();
+    }
+
+    // Fallback to first sheet name
+    if (workbookData.sheets) {
+      const sheetOrder = workbookData.sheetOrder || Object.keys(workbookData.sheets);
+      const firstSheetId = sheetOrder[0];
+
+      if (firstSheetId && workbookData.sheets[firstSheetId]?.name) {
+        const sheetName = workbookData.sheets[firstSheetId].name.trim();
+
+        if (sheetName) {
+          return sheetName;
+        }
+      }
+    }
+
+    // Fallback to workbook ID
+    if (workbookData.id) {
+      return `Spreadsheet_${workbookData.id}`;
+    }
+
+    // Last resort: timestamp
+    return `Spreadsheet_${new Date().toISOString().slice(0, 10)}`;
+  }, []);
+
+  // Handle file export using SheetJS
+  const handleExportXlsx = useCallback(() => {
+    try {
+      const workbook = univerAPIRef.current?.getActiveWorkbook();
+
+      if (!workbook) return;
+
+      const workbookData = workbook.save() as unknown as XlsxWorkbookData;
+      const name = getExportFileName(workbookData);
+
+      downloadWorkbook(workbookData, name, 'xlsx');
+    } catch (err) {
+      console.error('XLSX Export error:', err);
+    }
+  }, [getExportFileName]);
+
+  // Handle CSV export (uses SheetJS - simpler format)
+  const handleExportCsv = useCallback(() => {
+    try {
+      const workbook = univerAPIRef.current?.getActiveWorkbook();
+
+      if (!workbook) return;
+
+      const workbookData = workbook.save() as unknown as XlsxWorkbookData;
+      const name = getExportFileName(workbookData);
+
+      downloadWorkbook(workbookData, name, 'csv');
+    } catch (err) {
+      console.error('CSV Export error:', err);
+    }
+  }, [getExportFileName]);
+
+  // Client-side only check
+  useEffect(() => {
+    setIsClient(true);
+  }, []);
+
+  // Initialize Univer
+  useEffect(() => {
+    if (!isClient || !containerRef.current) return;
+
+    // Get locale data synchronously
+    const univerLocale = getUniverLocale(locale);
+
+    // Increment generation and capture for this effect instance
+    instanceGeneration++;
+    const currentGeneration = instanceGeneration;
+
+    instanceGenerationRef.current = currentGeneration;
+
+    // Always dispose existing instance first (handles React Strict Mode)
+    if (univerRef.current) {
+      univerRef.current.dispose();
+      univerRef.current = null;
+      univerAPIRef.current = null;
+    }
+
+    const container = containerRef.current;
+    const rect = container.getBoundingClientRect();
+
+    // If container has no dimensions, wait for next frame
+    if (rect.width === 0 || rect.height === 0) {
+      const timerId = setTimeout(() => {
+        // Force re-render by updating isClient (already true, but React will re-run effect)
+        setIsClient(true);
+      }, 50);
+
+      return () => clearTimeout(timerId);
+    }
+
+    const univer = new Univer({
+      theme: defaultTheme,
+      locale: univerLocale.type,
+      locales: {
+        [univerLocale.type]: univerLocale.data
+      } as any
+    });
+
+    // Register core plugins in order
+    univer.registerPlugin(UniverRenderEnginePlugin as any);
+    univer.registerPlugin(UniverFormulaEnginePlugin as any);
+    univer.registerPlugin(UniverUIPlugin as any, {
+      container: containerRef.current,
+      customFontFamily: {
+        override: true,
+        list: CUSTOM_FONT_LIST
+      }
+    });
+
+    univer.registerPlugin(UniverDocsPlugin as any);
+    univer.registerPlugin(UniverDocsUIPlugin as any);
+
+    univer.registerPlugin(UniverSheetsPlugin as any);
+    univer.registerPlugin(UniverSheetsUIPlugin as any);
+    univer.registerPlugin(UniverSheetsFormulaPlugin as any);
+    univer.registerPlugin(UniverSheetsFormulaUIPlugin as any);
+    univer.registerPlugin(UniverSheetsNumfmtPlugin as any);
+    univer.registerPlugin(UniverSheetsNumfmtUIPlugin as any);
+
+    // Register Drawing plugins
+    univer.registerPlugin(UniverDrawingPlugin as any);
+    univer.registerPlugin(UniverDrawingUIPlugin as any);
+    univer.registerPlugin(UniverSheetsDrawingPlugin as any);
+    univer.registerPlugin(UniverSheetsDrawingUIPlugin as any);
+
+    // Register feature plugins
+    univer.registerPlugin(UniverSheetsDataValidationPlugin as any);
+    univer.registerPlugin(UniverSheetsDataValidationUIPlugin as any);
+    univer.registerPlugin(UniverSheetsConditionalFormattingPlugin as any);
+    univer.registerPlugin(UniverSheetsConditionalFormattingUIPlugin as any);
+    univer.registerPlugin(UniverSheetsFilterPlugin as any);
+    univer.registerPlugin(UniverSheetsFilterUIPlugin as any);
+    univer.registerPlugin(UniverSheetsSortPlugin as any);
+    univer.registerPlugin(UniverSheetsSortUIPlugin as any);
+    univer.registerPlugin(UniverSheetsHyperLinkPlugin as any);
+    univer.registerPlugin(UniverSheetsHyperLinkUIPlugin as any);
+    univer.registerPlugin(UniverSheetsFindReplacePlugin as any);
+    univer.registerPlugin(UniverSheetsThreadCommentPlugin as any);
+    univer.registerPlugin(UniverSheetsThreadCommentUIPlugin as any);
+    univer.registerPlugin(UniverWatermarkPlugin as any);
+    univer.registerPlugin(UniverSheetsCrosshairHighlightPlugin as any);
+
+    univerRef.current = univer;
+    univerAPIRef.current = FUniver.newAPI(univer);
+
+    // Listen for workbook changes
+    let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+    const univerAPI = univerAPIRef.current;
+
+    univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {
+      /*
+       * Only react to user-level commands (CommandType.COMMAND = 0).
+       * System plugins such as SHEET_FILTER_PLUGIN fire CommandType.MUTATION (2)
+       * directly without a command wrapper, which must not trigger a save.
+       * All user actions (typing, paste, API calls via FUniver) go through
+       * CommandType.COMMAND first, so this is the correct layer to listen on.
+       */
+      if (event.type !== CommandType.COMMAND) return;
+
+      const cmd = event.id || '';
+
+      /*
+       * Skip the async snapshot-replace fired by createUnit during initialization.
+       * Once it fires, clear the flag so subsequent calls (e.g. file import) are saved.
+       */
+      if (cmd === 'doc.command-replace-snapshot') {
+        isInitializingRef.current = false;
+
+        return;
+      }
+
+      // Skip UI-only commands that don't change workbook data
+      const isUICommand
+        = cmd.includes('select')
+          || cmd.includes('scroll')
+          || cmd.includes('focus')
+          || cmd.includes('hover')
+          || cmd.includes('click')
+          || cmd.includes('cursor')
+          || cmd.includes('highlight')
+          || cmd.includes('zoom')
+          || cmd.includes('view')
+          || cmd.includes('activate')
+          || cmd.includes('editor')
+          || cmd.includes('operation');
+
+      if (isUICommand) return;
+
+      const isMutation
+        = cmd.includes('set-range-values')
+          || cmd.includes('set-cell')
+          || cmd.includes('insert-row')
+          || cmd.includes('insert-col')
+          || cmd.includes('delete-row')
+          || cmd.includes('delete-col')
+          || cmd.includes('remove-row')
+          || cmd.includes('remove-col')
+          || cmd.includes('move-row')
+          || cmd.includes('move-col')
+          || cmd.includes('add-merge')
+          || cmd.includes('remove-merge')
+          || cmd.includes('clear-selection')
+          || cmd.includes('set-worksheet-name')
+          || cmd.includes('paste')
+          || cmd.includes('cut')
+          || cmd.includes('set-style')
+          || cmd.includes('set-format')
+          || cmd.includes('undo')
+          || cmd.includes('redo');
+
+      if (!isMutation) return;
+
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        const workbook = univerAPIRef.current?.getActiveWorkbook();
+
+        if (!workbook) return;
+
+        const snapshot = workbook.save();
+
+        onDataRef.current?.({
+          workbook: snapshot,
+          workbookJson: JSON.stringify(snapshot)
+        });
+      }, 300);
+    });
+
+    onReadyRef.current?.();
+
+    // Set up toolbar command handlers
+    importExportHandlers.import = handleImport;
+    importExportHandlers.exportXlsx = handleExportXlsx;
+    importExportHandlers.exportCsv = handleExportCsv;
+
+    // Setup import/export toolbar buttons
+    setupImportExportToolbar(univer);
+
+    // Use initialData prop or pendingDataRef or empty workbook
+    const workbookData = initialDataRef.current || pendingDataRef.current;
+
+    if (workbookData) {
+      console.info('[UniverSheets] Loading workbook data:', workbookData);
+
+      // Track workbook name from loaded data
+      const loadedName = (workbookData as any).name;
+
+      if (loadedName && loadedName.trim()) {
+        workbookNameRef.current = loadedName.trim();
+      }
+
+      isInitializingRef.current = true;
+      univer.createUnit(UniverInstanceType.UNIVER_SHEET, workbookData as any);
+      onLoadedRef.current?.({ workbookId: (workbookData as any).id });
+      pendingDataRef.current = null;
+    } else {
+      console.info('[UniverSheets] Creating empty workbook');
+      univer.createUnit(UniverInstanceType.UNIVER_SHEET, SAMPLE_WORKBOOK_DATA);
+    }
+
+    // Execute initial commands after the workbook is fully initialized
+    const pendingCommands = commandsRef.current;
+
+    if (pendingCommands && pendingCommands.length > 0) {
+      for (const cmd of pendingCommands) {
+        void executeApiCommand(cmd);
+      }
+    }
+
+    // Set numfmt locale for decimal/thousands separator based on app locale
+    const numfmtLocale = getNumfmtLocale(locale);
+    const activeWorkbook = univerAPIRef.current?.getActiveWorkbook();
+
+    if (activeWorkbook) {
+      try {
+        (activeWorkbook as any).setNumfmtLocal(numfmtLocale);
+        console.info('[UniverSheets] Set numfmt locale to:', numfmtLocale);
+      } catch (e) {
+        console.warn('[UniverSheets] Failed to set numfmt locale:', e);
+      }
+    }
+
+    return () => {
+      /*
+       * Only dispose if this cleanup is for the current generation
+       * This prevents React Strict Mode's first cleanup from disposing
+       * the instance created by the second render
+       */
+      if (instanceGenerationRef.current === currentGeneration) {
+        console.info('[UniverSheets] Cleanup - disposing generation:', currentGeneration);
+
+        // Defer dispose to next tick to avoid React concurrent rendering conflicts
+        queueMicrotask(() => {
+          try {
+            univer.dispose();
+          } catch (e) {
+            /*
+             * Ignore errors during dispose - can happen when navigating away
+             * while Univer's internal callbacks are still running
+             */
+            console.warn('[UniverSheets] Error during dispose (safe to ignore):', e);
+          }
+        });
+
+        univerRef.current = null;
+        univerAPIRef.current = null;
+      } else {
+        console.info(
+          '[UniverSheets] Cleanup - skipping stale generation:',
+          currentGeneration,
+          'current:',
+          instanceGenerationRef.current
+        );
+      }
+    };
+  }, [
+    isClient,
+    locale,
+    handleExportXlsx,
+    handleExportCsv,
+    executeApiCommand
+  ]);
+
+  if (!isClient) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: '#f5f5f5'
+        }}>
+        <span>Loading...</span>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ position: 'absolute', inset: 0 }}>
+      {/* Hidden file input for import - triggered by toolbar button */}
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept=".xlsx,.xls,.csv"
+        onChange={handleFileChange}
+        style={{ display: 'none' }} />
+
+      <div
+        ref={containerRef}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          overflow: 'hidden'
+        }} />
+    </div>
+  );
+}