@pagent-libs/core 0.1.0

package/src/event-emitter.ts

@@ -0,0 +1,73 @@
+// Event emitter for workbook events
+
+import type { EventData, EventHandler, EventType } from './types';
+
+export class EventEmitter {
+  private handlers: Map<EventType, Set<EventHandler>> = new Map();
+  private batchQueue: EventData[] = [];
+  private isBatching = false;
+
+  on(event: EventType, handler: EventHandler): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+
+    // Return unsubscribe function
+    return () => {
+      this.handlers.get(event)?.delete(handler);
+    };
+  }
+
+  off(event: EventType, handler: EventHandler): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+
+  emit(event: EventType, payload: unknown): void {
+    const data: EventData = { type: event, payload };
+
+    if (this.isBatching) {
+      this.batchQueue.push(data);
+      return;
+    }
+
+    this.dispatch(data);
+  }
+
+  private dispatch(data: EventData): void {
+    const handlers = this.handlers.get(data.type);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error('Error in event handler:', error);
+        }
+      }
+    }
+  }
+
+  batch(operations: () => void): void {
+    this.isBatching = true;
+    this.batchQueue = [];
+
+    try {
+      operations();
+    } finally {
+      this.isBatching = false;
+      const events = [...this.batchQueue];
+      this.batchQueue = [];
+
+      // Dispatch all batched events
+      for (const event of events) {
+        this.dispatch(event);
+      }
+    }
+  }
+
+  clear(): void {
+    this.handlers.clear();
+    this.batchQueue = [];
+  }
+}
+

package/src/export/csv.ts

@@ -0,0 +1,101 @@
+import type { Sheet } from '../types';
+import type { WorkbookImpl } from '../workbook';
+
+export function exportToCSV(workbook: WorkbookImpl, sheetId?: string): string {
+  const sheet = workbook.getSheet(sheetId);
+  const rows: string[][] = [];
+
+  // Find the maximum row and column with data
+  let maxRow = 0;
+  let maxCol = 0;
+
+  for (const [key] of sheet.cells) {
+    const [row, col] = key.split(':').map(Number);
+    maxRow = Math.max(maxRow, row);
+    maxCol = Math.max(maxCol, col);
+  }
+
+  // Generate CSV rows
+  for (let row = 0; row <= maxRow; row++) {
+    const csvRow: string[] = [];
+    for (let col = 0; col <= maxCol; col++) {
+      const cell = sheet.getCell(row, col);
+      let value = '';
+
+      if (cell) {
+        if (cell.formula) {
+          // For formulas, export the formula itself (or could export calculated value)
+          value = cell.formula;
+        } else {
+          value = cell.value?.toString() || '';
+        }
+      }
+
+      // Escape CSV value
+      if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+        value = `"${value.replace(/"/g, '""')}"`;
+      }
+
+      csvRow.push(value);
+    }
+    rows.push(csvRow);
+  }
+
+  return rows.map((row) => row.join(',')).join('\n');
+}
+
+export function importFromCSV(csv: string, sheet: Sheet): void {
+  const lines = csv.split('\n');
+  let row = 0;
+
+  for (const line of lines) {
+    if (!line.trim()) {
+      row++;
+      continue;
+    }
+
+    // Simple CSV parsing (doesn't handle all edge cases)
+    const values = parseCSVLine(line);
+    values.forEach((value, col) => {
+      if (value.trim()) {
+        sheet.setCellValue(row, col, value);
+      }
+    });
+
+    row++;
+  }
+}
+
+function parseCSVLine(line: string): string[] {
+  const values: string[] = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    const nextChar = line[i + 1];
+
+    if (char === '"') {
+      if (inQuotes && nextChar === '"') {
+        // Escaped quote
+        current += '"';
+        i++; // Skip next quote
+      } else {
+        // Toggle quote state
+        inQuotes = !inQuotes;
+      }
+    } else if (char === ',' && !inQuotes) {
+      // End of value
+      values.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  // Add last value
+  values.push(current);
+
+  return values;
+}
+

package/src/export/index.ts

@@ -0,0 +1,4 @@
+// Export functionality
+
+export * from './csv';
+

package/src/features/filter.ts

@@ -0,0 +1,231 @@
+// Filter functionality for spreadsheet sheets
+
+import type { ColumnFilter, FilterCriteria, Sheet } from '../types';
+import { getCellKey } from '../utils/cell-key';
+
+/**
+ * Manages filtering operations for a spreadsheet sheet
+ */
+export class FilterManager {
+  /**
+   * Apply filters to get visible row indices
+   * @param sheet The sheet to filter
+   * @param filters Map of column filters
+   * @param dataRange Optional range to filter, defaults to data rows (starting from row 1, assuming row 0 is header)
+   * @returns Set of visible row indices
+   */
+  static getFilteredRows(
+    sheet: Sheet,
+    filters: Map<number, ColumnFilter>,
+    dataRange?: { startRow: number; endRow: number }
+  ): Set<number> {
+    if (filters.size === 0) {
+      // No filters, all rows visible (including header row 0)
+      const visibleRows = new Set<number>();
+      const startRow = dataRange?.startRow ?? 0;
+      const endRow = dataRange?.endRow ?? sheet.rowCount - 1;
+      for (let row = startRow; row <= endRow; row++) {
+        visibleRows.add(row);
+      }
+      return visibleRows;
+    }
+
+    // Determine data range to filter (default to row 1+, assuming row 0 is header)
+    const startRow = dataRange?.startRow ?? Math.max(1, this.detectDataStartRow(sheet));
+    const endRow = dataRange?.endRow ?? this.detectDataEndRow(sheet);
+
+    const visibleRows = new Set<number>();
+
+    // Always include the header row (row 0) if we're starting from row 0 or earlier
+    if (dataRange?.startRow === undefined || dataRange.startRow <= 0) {
+      visibleRows.add(0);
+    }
+
+    // Check each data row against all filters
+    for (let row = startRow; row <= endRow; row++) {
+      let isVisible = true;
+
+      for (const [, filter] of filters) {
+        const cell = sheet.cells.get(getCellKey(row, filter.column));
+        const cellValue = cell?.value ?? null;
+
+        if (!this.matchesFilter(cellValue, filter.criteria)) {
+          isVisible = false;
+          break;
+        }
+      }
+
+      if (isVisible) {
+        visibleRows.add(row);
+      }
+    }
+
+    return visibleRows;
+  }
+
+  /**
+   * Check if a cell value matches a filter criteria
+   * @param cellValue The cell value to check
+   * @param criteria The filter criteria
+   * @returns true if the value matches the filter
+   */
+  private static matchesFilter(cellValue: unknown, criteria: FilterCriteria): boolean {
+    // Handle null/undefined values
+    if (cellValue === null || cellValue === undefined) {
+      // Null values only match if criteria allows empty values
+      return criteria.type === 'equals' && criteria.value === '';
+    }
+
+    // Convert cell value to string for text operations
+    const strValue = String(cellValue) as string;
+
+    switch (criteria.type) {
+      case 'equals':
+        return strValue === String(criteria.value);
+
+      case 'notEquals':
+        return strValue !== String(criteria.value);
+
+      case 'contains':
+        return strValue.toLowerCase().includes(criteria.value.toLowerCase());
+
+      case 'notContains':
+        return !strValue.toLowerCase().includes(criteria.value.toLowerCase());
+
+      case 'startsWith':
+        return strValue.toLowerCase().startsWith(criteria.value.toLowerCase());
+
+      case 'endsWith':
+        return strValue.toLowerCase().endsWith(criteria.value.toLowerCase());
+
+      case 'greaterThan': {
+        const numValue = Number(cellValue);
+        return !isNaN(numValue) && numValue > criteria.value;
+      }
+
+      case 'lessThan': {
+        const numValue = Number(cellValue);
+        return !isNaN(numValue) && numValue < criteria.value;
+      }
+
+      case 'greaterThanOrEqual': {
+        const numValue = Number(cellValue);
+        return !isNaN(numValue) && numValue >= criteria.value;
+      }
+
+      case 'lessThanOrEqual': {
+        const numValue = Number(cellValue);
+        return !isNaN(numValue) && numValue <= criteria.value;
+      }
+
+      case 'between': {
+        const numValue = Number(cellValue);
+        return !isNaN(numValue) && numValue >= criteria.min && numValue <= criteria.max;
+      }
+
+      case 'custom':
+        return criteria.values.has(cellValue as string | number);
+
+      default:
+        return true; // Unknown criteria type, show the row
+    }
+  }
+
+  /**
+   * Get unique values in a column for filter dropdowns
+   * @param sheet The sheet to analyze
+   * @param column Column index
+   * @param dataRange Optional range to analyze, defaults to data rows (starting from row 1, assuming row 0 is header)
+   * @returns Set of unique values in the column
+   */
+  static getUniqueColumnValues(
+    sheet: Sheet,
+    column: number,
+    dataRange?: { startRow: number; endRow: number }
+  ): Set<string | number> {
+    const uniqueValues = new Set<string | number>();
+
+    // Default to data rows only (skip header row 0), unless explicitly specified
+    const startRow = dataRange?.startRow ?? Math.max(1, this.detectDataStartRow(sheet));
+    const endRow = dataRange?.endRow ?? this.detectDataEndRow(sheet);
+
+    for (let row = startRow; row <= endRow; row++) {
+      const cell = sheet.cells.get(getCellKey(row, column));
+      if (cell?.value !== null && cell?.value !== undefined) {
+        uniqueValues.add(cell.value as string | number);
+      }
+    }
+
+    return uniqueValues;
+  }
+
+  /**
+   * Detect the first row that contains data (skip empty rows at the top)
+   */
+  private static detectDataStartRow(sheet: Sheet): number {
+    // Start from row 0, find first non-empty row
+    for (let row = 0; row < sheet.rowCount; row++) {
+      for (let col = 0; col < sheet.colCount; col++) {
+        const cell = sheet.cells.get(getCellKey(row, col));
+        if (cell && (cell.value !== null || cell.formula)) {
+          return row;
+        }
+      }
+    }
+    return 0;
+  }
+
+  /**
+   * Detect the last row that contains data (skip empty rows at the bottom)
+   */
+  private static detectDataEndRow(sheet: Sheet): number {
+    // Start from the bottom, find last non-empty row
+    for (let row = sheet.rowCount - 1; row >= 0; row--) {
+      for (let col = 0; col < sheet.colCount; col++) {
+        const cell = sheet.cells.get(getCellKey(row, col));
+        if (cell && (cell.value !== null || cell.formula)) {
+          return row;
+        }
+      }
+    }
+    return Math.max(0, sheet.rowCount - 1);
+  }
+
+  /**
+   * Check if a column has an active filter
+   * @param column Column index
+   * @param filters Current filters map
+   * @returns true if column has a filter
+   */
+  static hasFilter(column: number, filters: Map<number, ColumnFilter>): boolean {
+    return filters.has(column);
+  }
+
+  /**
+   * Get filter type based on column data
+   * @param sheet The sheet to analyze
+   * @param column Column index
+   * @returns 'text', 'number', or 'date' based on data analysis
+   */
+  static detectColumnType(sheet: Sheet, column: number): 'text' | 'number' | 'date' {
+    const uniqueValues = this.getUniqueColumnValues(sheet, column);
+    let hasNumbers = false;
+    let hasDates = false;
+
+    for (const value of uniqueValues) {
+      if (typeof value === 'number') {
+        hasNumbers = true;
+      } else if (typeof value === 'string') {
+        // Check if string looks like a date
+        const date = new Date(value);
+        if (!isNaN(date.getTime()) && value.match(/\d{1,2}[-/]\d{1,2}[-/]\d{4}|\d{4}[-/]\d{1,2}[-/]\d{1,2}/)) {
+          hasDates = true;
+        }
+      }
+    }
+
+    if (hasDates) return 'date';
+    if (hasNumbers) return 'number';
+    return 'text';
+  }
+}

package/src/features/freeze.ts

@@ -0,0 +1,271 @@
+// Freeze Panes Utilities
+// Handles calculation and management of frozen rows/columns
+
+/**
+ * Configuration for freeze panes
+ */
+export interface FreezeConfig {
+  frozenRows: number;
+  frozenCols: number;
+}
+
+/**
+ * Cached dimensions for frozen areas
+ */
+export interface FreezeDimensions {
+  /** Total width of all frozen columns */
+  frozenWidth: number;
+  /** Total height of all frozen rows */
+  frozenHeight: number;
+}
+
+/**
+ * The 4 regions created by freeze panes
+ */
+export type FreezeRegion = 
+  | 'top-left'    // Frozen rows AND cols - never scrolls
+  | 'top'         // Frozen rows only - scrolls horizontally
+  | 'left'        // Frozen cols only - scrolls vertically
+  | 'main';       // Regular scrollable area
+
+/**
+ * Calculate the total dimensions of frozen areas
+ */
+export function calculateFreezeDimensions(
+  frozenRows: number,
+  frozenCols: number,
+  rowHeights: Map<number, number>,
+  colWidths: Map<number, number>,
+  defaultRowHeight: number,
+  defaultColWidth: number,
+  hiddenRows?: Set<number>,
+  hiddenCols?: Set<number>
+): FreezeDimensions {
+  const hidRows = hiddenRows ?? new Set<number>();
+  const hidCols = hiddenCols ?? new Set<number>();
+  
+  // Calculate frozen width (sum of frozen column widths, excluding hidden)
+  let frozenWidth = 0;
+  for (let c = 0; c < frozenCols; c++) {
+    if (!hidCols.has(c)) {
+      frozenWidth += colWidths.get(c) ?? defaultColWidth;
+    }
+  }
+  
+  // Calculate frozen height (sum of frozen row heights, excluding hidden)
+  let frozenHeight = 0;
+  for (let r = 0; r < frozenRows; r++) {
+    if (!hidRows.has(r)) {
+      frozenHeight += rowHeights.get(r) ?? defaultRowHeight;
+    }
+  }
+  
+  return { frozenWidth, frozenHeight };
+}
+
+/**
+ * Determine which freeze region a canvas point falls into
+ * 
+ * @param x - Canvas x coordinate (relative to canvas origin, after headers)
+ * @param y - Canvas y coordinate (relative to canvas origin, after headers)
+ * @param frozenWidth - Total width of frozen columns
+ * @param frozenHeight - Total height of frozen rows
+ * @param headerWidth - Width of row headers
+ * @param headerHeight - Height of column headers
+ */
+export function getRegionAtPoint(
+  x: number,
+  y: number,
+  frozenWidth: number,
+  frozenHeight: number,
+  headerWidth: number,
+  headerHeight: number
+): FreezeRegion {
+  const inFrozenCols = x <= headerWidth + frozenWidth;
+  const inFrozenRows = y <= headerHeight + frozenHeight;
+  
+  if (inFrozenRows && inFrozenCols) {
+    return 'top-left';
+  } else if (inFrozenRows) {
+    return 'top';
+  } else if (inFrozenCols) {
+    return 'left';
+  } else {
+    return 'main';
+  }
+}
+
+/**
+ * Get the effective scroll offset for a given region
+ */
+export function getScrollForRegion(
+  region: FreezeRegion,
+  scrollTop: number,
+  scrollLeft: number
+): { effectiveScrollTop: number; effectiveScrollLeft: number } {
+  switch (region) {
+    case 'top-left':
+      // Never scrolls
+      return { effectiveScrollTop: 0, effectiveScrollLeft: 0 };
+    case 'top':
+      // Only scrolls horizontally
+      return { effectiveScrollTop: 0, effectiveScrollLeft: scrollLeft };
+    case 'left':
+      // Only scrolls vertically
+      return { effectiveScrollTop: scrollTop, effectiveScrollLeft: 0 };
+    case 'main':
+      // Scrolls both ways
+      return { effectiveScrollTop: scrollTop, effectiveScrollLeft: scrollLeft };
+  }
+}
+
+/**
+ * Convert a canvas point to grid coordinates, accounting for freeze regions
+ * 
+ * @param canvasX - X position on canvas (including headers)
+ * @param canvasY - Y position on canvas (including headers)
+ * @param scrollTop - Current vertical scroll position
+ * @param scrollLeft - Current horizontal scroll position
+ * @param frozenWidth - Total width of frozen columns
+ * @param frozenHeight - Total height of frozen rows
+ * @param headerWidth - Width of row headers
+ * @param headerHeight - Height of column headers
+ */
+export function canvasToGridCoordinates(
+  canvasX: number,
+  canvasY: number,
+  scrollTop: number,
+  scrollLeft: number,
+  frozenWidth: number,
+  frozenHeight: number,
+  headerWidth: number,
+  headerHeight: number
+): { gridX: number; gridY: number } {
+  const region = getRegionAtPoint(
+    canvasX, canvasY,
+    frozenWidth, frozenHeight,
+    headerWidth, headerHeight
+  );
+  
+  const { effectiveScrollTop, effectiveScrollLeft } = getScrollForRegion(
+    region, scrollTop, scrollLeft
+  );
+  
+  // Convert to grid coordinates based on region
+  let gridX: number;
+  let gridY: number;
+  
+  if (region === 'top-left' || region === 'left') {
+    // In frozen columns - no horizontal scroll adjustment
+    gridX = canvasX - headerWidth;
+  } else {
+    // In scrollable columns - apply scroll offset
+    gridX = canvasX - headerWidth + effectiveScrollLeft;
+  }
+  
+  if (region === 'top-left' || region === 'top') {
+    // In frozen rows - no vertical scroll adjustment
+    gridY = canvasY - headerHeight;
+  } else {
+    // In scrollable rows - apply scroll offset
+    gridY = canvasY - headerHeight + effectiveScrollTop;
+  }
+  
+  return { gridX, gridY };
+}
+
+/**
+ * Calculate clipping rectangle for a freeze region
+ * 
+ * @returns Clip rect in canvas coordinates { x, y, width, height }
+ */
+export function getClipRectForRegion(
+  region: FreezeRegion,
+  canvasWidth: number,
+  canvasHeight: number,
+  frozenWidth: number,
+  frozenHeight: number,
+  headerWidth: number,
+  headerHeight: number
+): { x: number; y: number; width: number; height: number } {
+  switch (region) {
+    case 'top-left':
+      return {
+        x: headerWidth,
+        y: headerHeight,
+        width: frozenWidth,
+        height: frozenHeight,
+      };
+    case 'top':
+      return {
+        x: headerWidth + frozenWidth,
+        y: headerHeight,
+        width: canvasWidth - headerWidth - frozenWidth,
+        height: frozenHeight,
+      };
+    case 'left':
+      return {
+        x: headerWidth,
+        y: headerHeight + frozenHeight,
+        width: frozenWidth,
+        height: canvasHeight - headerHeight - frozenHeight,
+      };
+    case 'main':
+      return {
+        x: headerWidth + frozenWidth,
+        y: headerHeight + frozenHeight,
+        width: canvasWidth - headerWidth - frozenWidth,
+        height: canvasHeight - headerHeight - frozenHeight,
+      };
+  }
+}
+
+/**
+ * Check if a row is in the frozen area
+ */
+export function isRowFrozen(row: number, frozenRows: number): boolean {
+  return row < frozenRows;
+}
+
+/**
+ * Check if a column is in the frozen area
+ */
+export function isColFrozen(col: number, frozenCols: number): boolean {
+  return col < frozenCols;
+}
+
+/**
+ * Check if a cell is fully in the frozen area (both row and col frozen)
+ */
+export function isCellFullyFrozen(
+  row: number,
+  col: number,
+  frozenRows: number,
+  frozenCols: number
+): boolean {
+  return isRowFrozen(row, frozenRows) && isColFrozen(col, frozenCols);
+}
+
+/**
+ * Get the region a cell belongs to based on its row/col indices
+ */
+export function getCellRegion(
+  row: number,
+  col: number,
+  frozenRows: number,
+  frozenCols: number
+): FreezeRegion {
+  const rowFrozen = isRowFrozen(row, frozenRows);
+  const colFrozen = isColFrozen(col, frozenCols);
+  
+  if (rowFrozen && colFrozen) {
+    return 'top-left';
+  } else if (rowFrozen) {
+    return 'top';
+  } else if (colFrozen) {
+    return 'left';
+  } else {
+    return 'main';
+  }
+}
+

package/src/features/index.ts

@@ -0,0 +1,5 @@
+// Features module - Advanced spreadsheet features
+export * from './freeze';
+export * from './sort';
+export * from './filter';
+