@docyrus/ui-pro-ai-assistant 0.0.1

package/src/internal/sheets/xlsx.ts

@@ -0,0 +1,1169 @@
+/**
+ * Browser-compatible XLSX ↔ Univer Converter
+ *
+ * Uses SheetJS (xlsx) for browser-side Excel file processing.
+ * Works in both browser and Cloudflare Workers (no Node.js dependencies).
+ */
+
+import { type CellObject } from 'xlsx';
+
+import * as XLSX from 'xlsx';
+
+import {
+  type AIWorkbookOutput,
+  type IBorderData,
+  type ICellData,
+  type ICellDataMatrix,
+  type IColumnData,
+  type IMergeRange,
+  type IRowData,
+  type IStyleData,
+  type IWorkbookData,
+  type IWorksheetData
+} from './types';
+
+/*
+ * ============================================================================
+ * Utility Functions
+ * ============================================================================
+ */
+
+function generateId(): string {
+  return Math.random().toString(36).substring(2, 15);
+}
+
+function colIndexToLetter(colIndex: number): string {
+  let result = '';
+  let index = colIndex + 1;
+
+  while (index > 0) {
+    const remainder = (index - 1) % 26;
+
+    result = String.fromCharCode(65 + remainder) + result;
+    index = Math.floor((index - 1) / 26);
+  }
+
+  return result;
+}
+
+function letterToColIndex(letter: string): number {
+  let col = 0;
+
+  for (let i = 0; i < letter.length; i++) {
+    col = col * 26 + (letter.charCodeAt(i) - 64);
+  }
+
+  return col - 1;
+}
+
+function cellRefToRowCol(ref: string): { row: number; col: number } {
+  const match = ref.match(/^([A-Z]+)(\d+)$/);
+
+  if (!match) return { row: 0, col: 0 };
+
+  return {
+    row: parseInt(match[2], 10) - 1,
+    col: letterToColIndex(match[1])
+  };
+}
+
+function rangeToMerge(range: string): IMergeRange | null {
+  const [start, end] = range.split(':');
+
+  if (!start) return null;
+
+  const startPos = cellRefToRowCol(start);
+  const endPos = end ? cellRefToRowCol(end) : startPos;
+
+  return {
+    startRow: startPos.row,
+    startColumn: startPos.col,
+    endRow: endPos.row,
+    endColumn: endPos.col
+  };
+}
+
+// SheetJS color type
+interface XLSXColor {
+  rgb?: string;
+  theme?: number;
+  tint?: number;
+}
+
+// SheetJS style to hex color
+function styleColorToHex(color: XLSXColor | undefined): string | undefined {
+  if (!color) return undefined;
+
+  if (color.rgb) {
+    // RGB format: RRGGBB
+    return `#${color.rgb}`;
+  }
+  if (color.theme !== undefined) {
+    // Theme colors - return a default, actual theme resolution needs workbook context
+    const themeColors = [
+      '#000000',
+      '#FFFFFF',
+      '#1F4E79',
+      '#2E75B6',
+      '#5B9BD5',
+      '#ED7D31',
+      '#70AD47',
+      '#FFC000'
+    ];
+
+    return themeColors[color.theme] || '#000000';
+  }
+
+  return undefined;
+}
+
+function convertBorderStyle(style: string | undefined): number {
+  const styleMap: Record<string, number> = {
+    thin: 1,
+    medium: 2,
+    thick: 3,
+    dotted: 4,
+    dashed: 5,
+    double: 6,
+    hair: 7,
+    mediumDashed: 8,
+    dashDot: 9,
+    mediumDashDot: 10,
+    dashDotDot: 11,
+    mediumDashDotDot: 12,
+    slantDashDot: 13
+  };
+
+  return styleMap[style || 'thin'] || 1;
+}
+
+function convertHAlign(align: string | undefined): 1 | 2 | 3 | undefined {
+  const map: Record<string, 1 | 2 | 3> = { left: 1, center: 2, right: 3 };
+
+  return align ? map[align] : undefined;
+}
+
+function convertVAlign(align: string | undefined): 1 | 2 | 3 | undefined {
+  const map: Record<string, 1 | 2 | 3> = { top: 1, center: 2, bottom: 3 };
+
+  return align ? map[align] : undefined;
+}
+
+/*
+ * ============================================================================
+ * XLSX → Univer Converter
+ * ============================================================================
+ */
+
+export interface XlsxToUniverOptions {
+  workbookId?: string;
+  workbookName?: string;
+}
+
+export function xlsxToUniver(data: ArrayBuffer | Uint8Array, options: XlsxToUniverOptions = {}): IWorkbookData {
+  const workbook = XLSX.read(data, {
+    type: 'array',
+    cellStyles: true,
+    cellFormula: true,
+    cellDates: true,
+    cellNF: true
+  });
+
+  const workbookId = options.workbookId || generateId();
+  const workbookName = options.workbookName || workbook.Props?.Title || 'Workbook';
+
+  const sheetOrder: string[] = [];
+  const sheets: Record<string, IWorksheetData> = {};
+  const styles: Record<string, IStyleData> = {};
+  const styleCache = new Map<string, string>();
+
+  for (const sheetName of workbook.SheetNames) {
+    const ws = workbook.Sheets[sheetName];
+
+    if (!ws) continue;
+
+    const sheetId = generateId();
+
+    sheetOrder.push(sheetId);
+
+    // Get sheet range
+    const range = ws['!ref'] ? XLSX.utils.decode_range(ws['!ref']) : { s: { r: 0, c: 0 }, e: { r: 999, c: 25 } };
+    const rowCount = Math.max(range.e.r + 1, 1000);
+    const columnCount = Math.max(range.e.c + 1, 26);
+
+    const cellData: ICellDataMatrix = {};
+    const rowData: Record<number, IRowData> = {};
+    const columnData: Record<number, IColumnData> = {};
+    const mergeData: IMergeRange[] = [];
+
+    // Process cells
+    for (let { r } = range.s; r <= range.e.r; r++) {
+      for (let { c } = range.s; c <= range.e.c; c++) {
+        const cellAddress = XLSX.utils.encode_cell({ r, c });
+        const cell = ws[cellAddress] as CellObject | undefined;
+
+        if (!cell) continue;
+
+        if (!cellData[r]) {
+          cellData[r] = {};
+        }
+
+        const cellObj: ICellData = {};
+
+        // Value and type
+        if (cell.f) {
+          // Formula
+          cellObj.f = cell.f;
+          if (cell.v !== undefined) {
+            cellObj.v = cell.v as string | number | boolean;
+          }
+        } else if (cell.v !== undefined) {
+          cellObj.v = cell.v as string | number | boolean;
+        }
+
+        // Cell type
+        switch (cell.t) {
+          case 's':
+            cellObj.t = 1;
+            break; // STRING
+
+          case 'n':
+            cellObj.t = 2;
+            break; // NUMBER
+
+          case 'b':
+            cellObj.t = 3;
+            break; // BOOLEAN
+
+          case 'd':
+            cellObj.t = 2;
+            break; // DATE (stored as number)
+
+          default:
+            cellObj.t = 1;
+        }
+
+        // Style
+        if (cell.s) {
+          const style: IStyleData = {};
+          let hasStyle = false;
+
+          // Font
+          if (cell.s.font) {
+            const { font } = cell.s;
+
+            if (font.name) {
+              style.ff = font.name;
+              hasStyle = true;
+            }
+            if (font.sz) {
+              style.fs = font.sz;
+              hasStyle = true;
+            }
+            if (font.bold) {
+              style.bl = 1;
+              hasStyle = true;
+            }
+            if (font.italic) {
+              style.it = 1;
+              hasStyle = true;
+            }
+            if (font.underline) {
+              style.ul = { s: 1 };
+              hasStyle = true;
+            }
+            if (font.strike) {
+              style.st = { s: 1 };
+              hasStyle = true;
+            }
+            if (font.color) {
+              const rgb = styleColorToHex(font.color);
+
+              if (rgb) {
+                style.cl = { rgb };
+                hasStyle = true;
+              }
+            }
+          }
+
+          // Fill
+          if (cell.s.fill?.fgColor) {
+            const rgb = styleColorToHex(cell.s.fill.fgColor);
+
+            if (rgb) {
+              style.bg = { rgb };
+              hasStyle = true;
+            }
+          }
+
+          // Alignment
+          if (cell.s.alignment) {
+            const align = cell.s.alignment;
+            const ht = convertHAlign(align.horizontal);
+            const vt = convertVAlign(align.vertical);
+
+            if (ht) {
+              style.ht = ht;
+              hasStyle = true;
+            }
+            if (vt) {
+              style.vt = vt;
+              hasStyle = true;
+            }
+            if (align.wrapText) {
+              style.tb = 2;
+              hasStyle = true;
+            }
+            if (align.textRotation) {
+              style.tr = { a: align.textRotation };
+              hasStyle = true;
+            }
+          }
+
+          // Border
+          if (cell.s.border) {
+            const bd: IBorderData = {};
+            let hasBorder = false;
+
+            for (const side of [
+              'top',
+              'bottom',
+              'left',
+              'right'
+            ] as const) {
+              const b = cell.s.border[side];
+
+              if (b?.style) {
+                const key = side === 'top' ? 't' : side === 'bottom' ? 'b' : side === 'left' ? 'l' : 'r';
+
+                bd[key] = {
+                  s: convertBorderStyle(b.style),
+                  cl: { rgb: styleColorToHex(b.color) || '#000000' }
+                };
+                hasBorder = true;
+              }
+            }
+
+            if (hasBorder) {
+              style.bd = bd;
+              hasStyle = true;
+            }
+          }
+
+          // Number format
+          if (cell.z && cell.z !== 'General') {
+            style.n = { pattern: String(cell.z) };
+            hasStyle = true;
+          }
+
+          if (hasStyle) {
+            const styleJson = JSON.stringify(style);
+            let styleId = styleCache.get(styleJson);
+
+            if (!styleId) {
+              styleId = generateId();
+              styleCache.set(styleJson, styleId);
+              styles[styleId] = style;
+            }
+            cellObj.s = styleId;
+          }
+        }
+
+        // Hyperlink
+        if (cell.l) {
+          cellObj.custom = { hyperlink: cell.l.Target };
+        }
+
+        if (Object.keys(cellObj).length > 0) {
+          cellData[r][c] = cellObj;
+        }
+      }
+    }
+
+    // Row heights
+    if (ws['!rows']) {
+      ws['!rows'].forEach((row, idx) => {
+        if (row) {
+          const rd: IRowData = {};
+
+          if (row.hpt) rd.h = row.hpt;
+          if (row.hidden) rd.hd = 1;
+          if (Object.keys(rd).length > 0) {
+            rowData[idx] = rd;
+          }
+        }
+      });
+    }
+
+    // Column widths
+    if (ws['!cols']) {
+      ws['!cols'].forEach((col, idx) => {
+        if (col) {
+          const cd: IColumnData = {};
+
+          if (col.wpx) cd.w = col.wpx;
+          else if (col.wch) cd.w = col.wch * 7; // Approximate pixels
+          if (col.hidden) cd.hd = 1;
+          if (Object.keys(cd).length > 0) {
+            columnData[idx] = cd;
+          }
+        }
+      });
+    }
+
+    // Merged cells
+    if (ws['!merges']) {
+      for (const merge of ws['!merges']) {
+        mergeData.push({
+          startRow: merge.s.r,
+          startColumn: merge.s.c,
+          endRow: merge.e.r,
+          endColumn: merge.e.c
+        });
+      }
+    }
+
+    // Build sheet
+    const sheetData: IWorksheetData = {
+      id: sheetId,
+      name: sheetName,
+      rowCount,
+      columnCount,
+      defaultColumnWidth: 88,
+      defaultRowHeight: 24,
+      cellData
+    };
+
+    if (Object.keys(rowData).length > 0) sheetData.rowData = rowData;
+    if (Object.keys(columnData).length > 0) sheetData.columnData = columnData;
+    if (mergeData.length > 0) sheetData.mergeData = mergeData;
+
+    // Freeze panes
+    if (ws['!freeze']) {
+      const freeze = ws['!freeze'];
+
+      sheetData.freeze = {
+        xSplit: freeze.xSplit || 0,
+        ySplit: freeze.ySplit || 0,
+        startRow: freeze.ySplit || 0,
+        startColumn: freeze.xSplit || 0
+      };
+    }
+
+    // Auto filter
+    if (ws['!autofilter']) {
+      const filterRef = ws['!autofilter'].ref;
+      const filterRange = rangeToMerge(filterRef);
+
+      if (filterRange) {
+        sheetData.autoFilter = { ref: filterRange };
+      }
+    }
+
+    // Data validations (if available)
+    if ((ws as any)['!dataValidations']) {
+      const dvs = (ws as any)['!dataValidations'] as any[];
+
+      sheetData.dataValidations = dvs.map(dv => ({
+        uid: generateId(),
+        type: dv.type === 'list' ? 'list' : 'custom',
+        ranges: dv.sqref ? (dv.sqref.split(' ').map(rangeToMerge).filter(Boolean) as IMergeRange[]) : [],
+        formula1: dv.formula1,
+        formula2: dv.formula2,
+        allowBlank: dv.allowBlank,
+        showErrorMessage: dv.showErrorMessage,
+        showInputMessage: dv.showInputMessage,
+        promptTitle: dv.promptTitle,
+        prompt: dv.prompt,
+        errorTitle: dv.errorTitle,
+        error: dv.error
+      }));
+    }
+
+    sheets[sheetId] = sheetData;
+  }
+
+  return {
+    id: workbookId,
+    name: workbookName,
+    locale: 'EN_US',
+    sheetOrder,
+    sheets,
+    styles: Object.keys(styles).length > 0 ? styles : undefined
+  };
+}
+
+/*
+ * ============================================================================
+ * Univer → XLSX Converter
+ * ============================================================================
+ */
+
+export function univerToXlsx(data: IWorkbookData): ArrayBuffer {
+  const workbook = XLSX.utils.book_new();
+
+  // Set workbook properties
+  workbook.Props = {
+    Title: data.name,
+    CreatedDate: new Date()
+  };
+
+  for (const sheetId of data.sheetOrder) {
+    const sheetData = data.sheets[sheetId];
+
+    if (!sheetData) continue;
+
+    // Build AOA (Array of Arrays) for better compatibility
+    const aoa: (string | number | boolean | null | undefined)[][] = [];
+
+    // Find actual data bounds
+    let maxRow = 0;
+    let maxCol = 0;
+
+    if (sheetData.cellData) {
+      for (const rowStr of Object.keys(sheetData.cellData)) {
+        const r = parseInt(rowStr, 10);
+
+        maxRow = Math.max(maxRow, r);
+        const rowCells = sheetData.cellData[r];
+
+        for (const colStr of Object.keys(rowCells)) {
+          const c = parseInt(colStr, 10);
+
+          maxCol = Math.max(maxCol, c);
+        }
+      }
+    }
+
+    // Initialize AOA with proper dimensions
+    for (let r = 0; r <= maxRow; r++) {
+      aoa[r] = new Array(maxCol + 1).fill(null);
+    }
+
+    // Fill AOA with values
+    if (sheetData.cellData) {
+      for (const rowStr of Object.keys(sheetData.cellData)) {
+        const r = parseInt(rowStr, 10);
+        const rowCells = sheetData.cellData[r];
+
+        for (const colStr of Object.keys(rowCells)) {
+          const c = parseInt(colStr, 10);
+          const cellData = rowCells[c];
+
+          // Get value (prefer calculated value over formula for simple export)
+          if (cellData.v !== undefined && cellData.v !== null) {
+            aoa[r][c] = cellData.v;
+          } else if (cellData.f) {
+            // For formulas without cached value, store the formula result placeholder
+            aoa[r][c] = null;
+          }
+        }
+      }
+    }
+
+    // Create worksheet from AOA
+    const ws = XLSX.utils.aoa_to_sheet(aoa);
+
+    // Now add formulas and number formats to cells
+    if (sheetData.cellData) {
+      for (const rowStr of Object.keys(sheetData.cellData)) {
+        const r = parseInt(rowStr, 10);
+        const rowCells = sheetData.cellData[r];
+
+        for (const colStr of Object.keys(rowCells)) {
+          const c = parseInt(colStr, 10);
+          const cellData = rowCells[c];
+          const cellAddress = XLSX.utils.encode_cell({ r, c });
+
+          // Ensure cell exists
+          if (!ws[cellAddress]) {
+            ws[cellAddress] = { t: 's', v: '' };
+          }
+
+          const cell = ws[cellAddress] as CellObject;
+
+          // Add formula
+          if (cellData.f) {
+            cell.f = cellData.f;
+          }
+
+          // Add number format from style
+          const styleData
+            = typeof cellData.s === 'string' ? data.styles?.[cellData.s] : (cellData.s as IStyleData | undefined);
+
+          if (styleData?.n?.pattern) {
+            // Convert Univer pattern to Excel format if needed
+            cell.z = convertNumberFormatPattern(styleData.n.pattern);
+          }
+
+          // Add hyperlink
+          if (cellData.custom?.hyperlink) {
+            cell.l = { Target: cellData.custom.hyperlink as string };
+          }
+        }
+      }
+    }
+
+    // Row heights
+    if (sheetData.rowData) {
+      ws['!rows'] = [];
+      for (const rowStr of Object.keys(sheetData.rowData)) {
+        const r = parseInt(rowStr, 10);
+        const rd = sheetData.rowData[r];
+
+        if (rd.h || rd.hd) {
+          ws['!rows'][r] = {};
+          if (rd.h) ws['!rows'][r].hpt = rd.h;
+          if (rd.hd === 1) ws['!rows'][r].hidden = true;
+        }
+      }
+    }
+
+    // Column widths
+    if (sheetData.columnData) {
+      ws['!cols'] = [];
+      for (const colStr of Object.keys(sheetData.columnData)) {
+        const c = parseInt(colStr, 10);
+        const cd = sheetData.columnData[c];
+
+        if (cd.w || cd.hd) {
+          ws['!cols'][c] = {};
+          if (cd.w) ws['!cols'][c].wpx = cd.w;
+          if (cd.hd === 1) ws['!cols'][c].hidden = true;
+        }
+      }
+    }
+
+    // Merged cells
+    if (sheetData.mergeData && sheetData.mergeData.length > 0) {
+      ws['!merges'] = sheetData.mergeData.map(m => ({
+        s: { r: m.startRow, c: m.startColumn },
+        e: { r: m.endRow, c: m.endColumn }
+      }));
+    }
+
+    // Auto filter
+    if (sheetData.autoFilter) {
+      const { ref } = sheetData.autoFilter;
+
+      ws['!autofilter'] = {
+        ref: `${colIndexToLetter(ref.startColumn)}${ref.startRow + 1}:${colIndexToLetter(ref.endColumn)}${ref.endRow + 1}`
+      };
+    }
+
+    XLSX.utils.book_append_sheet(workbook, ws, sheetData.name);
+  }
+
+  // Generate buffer - Note: cellStyles requires SheetJS Pro, so we don't use it
+  const buffer = XLSX.write(workbook, {
+    type: 'array',
+    bookType: 'xlsx',
+    compression: true
+  });
+
+  return buffer;
+}
+
+/**
+ * Convert Univer number format pattern to Excel-compatible format
+ */
+function convertNumberFormatPattern(pattern: string): string {
+  /*
+   * Most patterns should work directly, but some need conversion
+   * Remove any locale-specific prefixes like [$-804]
+   */
+  let result = pattern;
+
+  // Remove Chinese locale prefix if present
+  result = result.replace(/\[\$-[0-9A-Fa-f]+\]/g, '');
+
+  // Convert common Univer patterns to Excel patterns
+  const patternMap: Record<string, string> = {
+    // Date patterns - ensure Excel compatibility
+    'yyyy/m/d': 'yyyy/m/d',
+    'yyyy-mm-dd': 'yyyy-mm-dd',
+    'dd/mm/yyyy': 'dd/mm/yyyy',
+    'dd.mm.yyyy': 'dd.mm.yyyy',
+    'm/d/yyyy': 'm/d/yyyy',
+    // Time patterns
+    'h:mm:ss': 'h:mm:ss',
+    'hh:mm:ss': 'hh:mm:ss',
+    'h:mm': 'h:mm',
+    'hh:mm': 'hh:mm',
+    // Percentage
+    '0%': '0%',
+    '0.00%': '0.00%'
+  };
+
+  return patternMap[result.toLowerCase()] || result;
+}
+
+/*
+ * ============================================================================
+ * CSV Converters
+ * ============================================================================
+ */
+
+export function csvToUniver(
+  csvContent: string,
+  options: {
+    delimiter?: string;
+    sheetName?: string;
+    workbookName?: string;
+    firstRowIsHeader?: boolean;
+  } = {}
+): IWorkbookData {
+  const {
+    delimiter = ',', sheetName = 'Sheet1', workbookName = 'CSV Import', firstRowIsHeader = false
+  } = options;
+
+  const workbook = XLSX.read(csvContent, {
+    type: 'string',
+    FS: delimiter
+  });
+
+  // Convert using xlsx parser, then transform
+  const ws = workbook.Sheets[workbook.SheetNames[0]];
+
+  if (!ws) {
+    return {
+      id: generateId(),
+      name: workbookName,
+      locale: 'EN_US',
+      sheetOrder: [generateId()],
+      sheets: {
+        [generateId()]: {
+          id: generateId(),
+          name: sheetName,
+          rowCount: 1000,
+          columnCount: 26,
+          cellData: {}
+        }
+      }
+    };
+  }
+
+  // Use xlsxToUniver with proper array buffer
+  const buffer = XLSX.write(workbook, { type: 'array', bookType: 'xlsx' });
+  const result = xlsxToUniver(buffer, { workbookName });
+
+  // Apply header styling if needed
+  if (firstRowIsHeader && result.sheetOrder[0]) {
+    const sheet = result.sheets[result.sheetOrder[0]];
+
+    if (sheet.cellData[0]) {
+      const headerStyle: IStyleData = {
+        bl: 1,
+        bg: { rgb: '#F3F4F6' }
+      };
+      const styleId = generateId();
+
+      if (!result.styles) result.styles = {};
+      result.styles[styleId] = headerStyle;
+
+      for (const colKey of Object.keys(sheet.cellData[0])) {
+        const cell = sheet.cellData[0][parseInt(colKey, 10)];
+
+        if (cell) {
+          cell.s = styleId;
+        }
+      }
+
+      // Add freeze
+      sheet.freeze = {
+        xSplit: 0,
+        ySplit: 1,
+        startRow: 1,
+        startColumn: 0
+      };
+    }
+  }
+
+  return result;
+}
+
+export function univerToCsv(data: IWorkbookData, sheetId?: string): string {
+  const targetSheetId = sheetId || data.sheetOrder[0];
+  const sheetData = data.sheets[targetSheetId];
+
+  if (!sheetData?.cellData) {
+    return '';
+  }
+
+  const rows: string[][] = [];
+
+  // Find bounds
+  let maxRow = 0;
+  let maxCol = 0;
+
+  for (const rowStr of Object.keys(sheetData.cellData)) {
+    const r = parseInt(rowStr, 10);
+
+    maxRow = Math.max(maxRow, r);
+    for (const colStr of Object.keys(sheetData.cellData[r])) {
+      maxCol = Math.max(maxCol, parseInt(colStr, 10));
+    }
+  }
+
+  for (let r = 0; r <= maxRow; r++) {
+    const row: string[] = [];
+
+    for (let c = 0; c <= maxCol; c++) {
+      const cell = sheetData.cellData[r]?.[c];
+      let value = '';
+
+      if (cell) {
+        if (cell.p?.body?.dataStream) {
+          value = cell.p.body.dataStream.replace(/\r\n$/, '');
+        } else if (cell.v !== undefined) {
+          value = String(cell.v);
+        }
+      }
+
+      // Escape for CSV
+      if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+        value = `"${value.replace(/"/g, '""')}"`;
+      }
+
+      row.push(value);
+    }
+    rows.push(row);
+  }
+
+  return rows.map(r => r.join(',')).join('\n');
+}
+
+/*
+ * ============================================================================
+ * File Helper Functions (Browser)
+ * ============================================================================
+ */
+
+export async function fileToUniver(file: File): Promise<IWorkbookData> {
+  const buffer = await file.arrayBuffer();
+  const ext = file.name.split('.').pop()?.toLowerCase();
+
+  if (ext === 'csv') {
+    const text = new TextDecoder().decode(buffer);
+
+    return csvToUniver(text, {
+      workbookName: file.name.replace(/\.[^.]+$/, '')
+    });
+  }
+
+  return xlsxToUniver(buffer, {
+    workbookName: file.name.replace(/\.[^.]+$/, '')
+  });
+}
+
+export function univerToBlob(data: IWorkbookData, format: 'xlsx' | 'csv' = 'xlsx'): Blob {
+  if (format === 'csv') {
+    const csv = univerToCsv(data);
+
+    return new Blob([csv], { type: 'text/csv;charset=utf-8;' });
+  }
+
+  const buffer = univerToXlsx(data);
+
+  return new Blob([buffer], {
+    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+  });
+}
+
+export function downloadWorkbook(data: IWorkbookData, filename: string, format: 'xlsx' | 'csv' = 'xlsx'): void {
+  const blob = univerToBlob(data, format);
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+
+  link.href = url;
+  link.download = filename.endsWith(`.${format}`) ? filename : `${filename}.${format}`;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}
+
+/*
+ * ============================================================================
+ * AI Output → Univer Native Format Converter
+ * ============================================================================
+ */
+
+/**
+ * Convert AI output (array-based format) to Univer native format (sparse matrix)
+ *
+ * @param aiOutput - The AI-generated workbook data in array-based format
+ * @returns Univer-compatible IWorkbookData in sparse matrix format
+ */
+export function aiOutputToUniver(aiOutput: AIWorkbookOutput): IWorkbookData {
+  // Support both 'workbook' (new) and 'workbookData' (legacy) keys
+  const workbookData = aiOutput.workbook || aiOutput.workbookData;
+
+  if (!workbookData) {
+    throw new Error('Missing workbook data in AI output');
+  }
+
+  // Validate sheets array exists and is not empty
+  if (!workbookData.sheets || !Array.isArray(workbookData.sheets) || workbookData.sheets.length === 0) {
+    console.warn('[aiOutputToUniver] Missing or empty sheets array, creating default sheet');
+
+    // Create a minimal valid workbook with empty sheet
+    return {
+      id: workbookData.id || 'workbook-1',
+      name: workbookData.name || 'Untitled Workbook',
+      sheetOrder: ['sheet-1'],
+      sheets: {
+        'sheet-1': {
+          id: 'sheet-1',
+          name: 'Sheet1',
+          rowCount: 100,
+          columnCount: 20,
+          cellData: {}
+        }
+      }
+    };
+  }
+
+  // Convert sheets array to object map
+  const sheets: Record<string, IWorksheetData> = {};
+
+  for (const sheetEntry of workbookData.sheets) {
+    // Skip null/undefined entries (malformed AI output)
+    if (!sheetEntry || !sheetEntry.sheet) {
+      console.warn('[aiOutputToUniver] Skipping invalid sheet entry:', sheetEntry);
+      continue;
+    }
+    const aiSheet = sheetEntry.sheet;
+
+    // Convert 2D array cellData to sparse matrix
+    const cellData: ICellDataMatrix = {};
+
+    if (aiSheet.cellData) {
+      for (let rowIndex = 0; rowIndex < aiSheet.cellData.length; rowIndex++) {
+        const row = aiSheet.cellData[rowIndex];
+
+        if (!row) continue;
+
+        for (let colIndex = 0; colIndex < row.length; colIndex++) {
+          const cell = row[colIndex];
+
+          if (!cell) continue;
+
+          // Initialize row if needed
+          if (!cellData[rowIndex]) {
+            cellData[rowIndex] = {};
+          }
+
+          // Copy cell data, removing null values
+          const cleanCell: ICellData = {};
+
+          if (cell.v !== undefined && cell.v !== null) cleanCell.v = cell.v;
+          if (cell.t !== undefined && cell.t !== null) cleanCell.t = cell.t;
+          if (cell.f !== undefined && cell.f !== null) cleanCell.f = cell.f;
+          if (cell.s !== undefined && cell.s !== null) cleanCell.s = cell.s;
+
+          if (Object.keys(cleanCell).length > 0) {
+            cellData[rowIndex][colIndex] = cleanCell;
+          }
+        }
+      }
+    }
+
+    // Convert rowData array to object map
+    let rowData: Record<number, IRowData> | undefined;
+
+    if (aiSheet.rowData && aiSheet.rowData.length > 0) {
+      rowData = {};
+      for (const rd of aiSheet.rowData) {
+        const rowEntry: IRowData = {};
+
+        if (rd.h !== undefined && rd.h !== null) rowEntry.h = rd.h;
+        if (rd.hd !== undefined && rd.hd !== null) rowEntry.hd = rd.hd;
+        if (Object.keys(rowEntry).length > 0) {
+          rowData[rd.row] = rowEntry;
+        }
+      }
+    }
+
+    // Convert columnData array to object map
+    let columnData: Record<number, IColumnData> | undefined;
+
+    if (aiSheet.columnData && aiSheet.columnData.length > 0) {
+      columnData = {};
+      for (const cd of aiSheet.columnData) {
+        const colEntry: IColumnData = {};
+
+        if (cd.w !== undefined && cd.w !== null) colEntry.w = cd.w;
+        if (cd.hd !== undefined && cd.hd !== null) colEntry.hd = cd.hd;
+        if (Object.keys(colEntry).length > 0) {
+          columnData[cd.col] = colEntry;
+        }
+      }
+    }
+
+    // Build sheet data
+    const sheetData: IWorksheetData = {
+      id: aiSheet.id,
+      name: aiSheet.name,
+      rowCount: aiSheet.rowCount,
+      columnCount: aiSheet.columnCount,
+      cellData
+    };
+
+    // Optional properties
+    if (aiSheet.tabColor) sheetData.tabColor = aiSheet.tabColor;
+    if (aiSheet.hidden !== undefined && aiSheet.hidden !== null) sheetData.hidden = aiSheet.hidden;
+    if (aiSheet.defaultColumnWidth !== undefined && aiSheet.defaultColumnWidth !== null) {
+      sheetData.defaultColumnWidth = aiSheet.defaultColumnWidth;
+    }
+    if (aiSheet.defaultRowHeight !== undefined && aiSheet.defaultRowHeight !== null) {
+      sheetData.defaultRowHeight = aiSheet.defaultRowHeight;
+    }
+    if (aiSheet.showGridlines !== undefined && aiSheet.showGridlines !== null) {
+      sheetData.showGridlines = aiSheet.showGridlines;
+    }
+    if (aiSheet.freeze) sheetData.freeze = aiSheet.freeze;
+    if (rowData && Object.keys(rowData).length > 0) sheetData.rowData = rowData;
+    if (columnData && Object.keys(columnData).length > 0) sheetData.columnData = columnData;
+    if (aiSheet.mergeData && aiSheet.mergeData.length > 0) sheetData.mergeData = aiSheet.mergeData;
+    if (aiSheet.dataValidations && aiSheet.dataValidations.length > 0) {
+      sheetData.dataValidations = aiSheet.dataValidations;
+    }
+    if (aiSheet.conditionalFormattingRules && aiSheet.conditionalFormattingRules.length > 0) {
+      sheetData.conditionalFormattingRules = aiSheet.conditionalFormattingRules;
+    }
+    if (aiSheet.autoFilter) sheetData.autoFilter = aiSheet.autoFilter;
+
+    sheets[sheetEntry.id] = sheetData;
+  }
+
+  // Ensure we have at least one valid sheet after filtering
+  if (Object.keys(sheets).length === 0) {
+    console.warn('[aiOutputToUniver] No valid sheets after filtering, creating default sheet');
+    sheets['sheet-1'] = {
+      id: 'sheet-1',
+      name: 'Sheet1',
+      rowCount: 100,
+      columnCount: 20,
+      cellData: {}
+    };
+    // Fix sheetOrder if empty
+    if (!workbookData.sheetOrder || workbookData.sheetOrder.length === 0) {
+      workbookData.sheetOrder = ['sheet-1'];
+    }
+  }
+
+  // Convert styles array to object map (filter out null entries from malformed AI output)
+  let styles: Record<string, IStyleData> | undefined;
+
+  if (workbookData.styles && Array.isArray(workbookData.styles) && workbookData.styles.length > 0) {
+    styles = {};
+    for (const styleEntry of workbookData.styles) {
+      // Skip null/undefined entries (malformed AI output often has [null, null, ...])
+      if (!styleEntry || !styleEntry.id || !styleEntry.style) {
+        continue;
+      }
+      styles[styleEntry.id] = styleEntry.style;
+    }
+    // If all entries were null, set styles to undefined
+    if (Object.keys(styles).length === 0) {
+      styles = undefined;
+    }
+  }
+
+  // Ensure sheetOrder is valid and contains actual sheet IDs
+  const validSheetIds = Object.keys(sheets);
+  let { sheetOrder } = workbookData;
+
+  if (!sheetOrder || !Array.isArray(sheetOrder) || sheetOrder.length === 0) {
+    sheetOrder = validSheetIds;
+  } else {
+    // Filter sheetOrder to only include valid sheet IDs
+    sheetOrder = sheetOrder.filter(id => validSheetIds.includes(id));
+    if (sheetOrder.length === 0) {
+      sheetOrder = validSheetIds;
+    }
+  }
+
+  // Build workbook
+  const workbook: IWorkbookData = {
+    id: workbookData.id || 'workbook-1',
+    name: workbookData.name || 'Untitled Workbook',
+    sheetOrder,
+    sheets
+  };
+
+  if (workbookData.locale) workbook.locale = workbookData.locale;
+  if (styles && Object.keys(styles).length > 0) workbook.styles = styles;
+
+  return workbook;
+}
+
+/**
+ * Validate AI output structure before conversion
+ *
+ * @param data - Raw parsed JSON from AI
+ * @returns Validation result with errors if any
+ */
+export function validateAIOutput(data: unknown): {
+  valid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (!data || typeof data !== 'object') {
+    errors.push('Response must be an object');
+
+    return { valid: false, errors };
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  // Check required top-level fields
+  if (typeof obj.title !== 'string') errors.push('Missing or invalid "title"');
+  if (typeof obj.description !== 'string') errors.push('Missing or invalid "description"');
+
+  // Support both 'workbook' (new) and 'workbookData' (legacy) keys
+  const workbookObj = obj.workbook || obj.workbookData;
+
+  if (!workbookObj || typeof workbookObj !== 'object') {
+    errors.push('Missing or invalid "workbook" (or "workbookData")');
+
+    return { valid: false, errors };
+  }
+
+  const wb = workbookObj as Record<string, unknown>;
+
+  // Check workbook fields
+  if (typeof wb.id !== 'string') errors.push('workbook.id must be a string');
+  if (typeof wb.name !== 'string') errors.push('workbook.name must be a string');
+  if (!Array.isArray(wb.sheetOrder)) errors.push('workbook.sheetOrder must be an array');
+  if (!Array.isArray(wb.sheets)) errors.push('workbook.sheets must be an array');
+
+  // Check sheets
+  if (Array.isArray(wb.sheets)) {
+    for (let i = 0; i < wb.sheets.length; i++) {
+      const entry = wb.sheets[i] as Record<string, unknown>;
+
+      if (!entry || typeof entry !== 'object') {
+        errors.push(`sheets[${i}] must be an object`);
+        continue;
+      }
+      if (typeof entry.id !== 'string') errors.push(`sheets[${i}].id must be a string`);
+      if (!entry.sheet || typeof entry.sheet !== 'object') {
+        errors.push(`sheets[${i}].sheet must be an object`);
+        continue;
+      }
+
+      const sheet = entry.sheet as Record<string, unknown>;
+
+      if (typeof sheet.id !== 'string') errors.push(`sheets[${i}].sheet.id must be a string`);
+      if (typeof sheet.name !== 'string') errors.push(`sheets[${i}].sheet.name must be a string`);
+      if (typeof sheet.rowCount !== 'number') errors.push(`sheets[${i}].sheet.rowCount must be a number`);
+      if (typeof sheet.columnCount !== 'number') errors.push(`sheets[${i}].sheet.columnCount must be a number`);
+      if (!Array.isArray(sheet.cellData)) errors.push(`sheets[${i}].sheet.cellData must be a 2D array`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}