@pagent-libs/core 0.1.0

package/src/canvas/text-renderer.ts

@@ -0,0 +1,321 @@
+// Text Renderer - Handles text measurement and rendering
+
+import type { CanvasTheme, TextStyle, Rect } from './types';
+
+/**
+ * Cached text metrics for a specific font configuration
+ */
+interface FontMetricsCache {
+  font: string;
+  lineHeight: number;
+  baseline: number;
+}
+
+/**
+ * Handles text measurement and rendering with caching
+ */
+export class TextRenderer {
+  private theme: CanvasTheme;
+  private metricsCache: Map<string, FontMetricsCache> = new Map();
+  private measureCanvas: HTMLCanvasElement;
+  private measureCtx: CanvasRenderingContext2D;
+  
+  constructor(theme: CanvasTheme) {
+    this.theme = theme;
+    
+    // Create offscreen canvas for text measurement
+    this.measureCanvas = document.createElement('canvas');
+    const ctx = this.measureCanvas.getContext('2d');
+    if (!ctx) {
+      throw new Error('Failed to create measurement context');
+    }
+    this.measureCtx = ctx;
+  }
+  
+  /**
+   * Build CSS font string from style
+   */
+  buildFontString(style: Partial<TextStyle>): string {
+    const fontWeight = style.fontWeight ?? 'normal';
+    const fontStyle = style.fontStyle ?? 'normal';
+    const fontSize = style.fontSize ?? this.theme.cellFontSize;
+    const fontFamily = style.fontFamily ?? this.theme.cellFont;
+    
+    return `${fontStyle} ${fontWeight} ${fontSize}px ${fontFamily}`;
+  }
+  
+  /**
+   * Get font metrics (with caching)
+   */
+  getFontMetrics(font: string): FontMetricsCache {
+    const cached = this.metricsCache.get(font);
+    if (cached) {
+      return cached;
+    }
+    
+    // Measure font metrics
+    this.measureCtx.font = font;
+    const metrics = this.measureCtx.measureText('Mg');
+    
+    // Approximate line height as 1.2 * font size
+    const fontSize = parseInt(font.match(/(\d+)px/)?.[1] ?? '11', 10);
+    const lineHeight = fontSize * 1.2;
+    
+    // Use actual metrics if available, otherwise approximate
+    const baseline = metrics.actualBoundingBoxAscent ?? fontSize * 0.8;
+    
+    const fontMetrics: FontMetricsCache = {
+      font,
+      lineHeight,
+      baseline,
+    };
+    
+    this.metricsCache.set(font, fontMetrics);
+    return fontMetrics;
+  }
+  
+  /**
+   * Measure text width
+   */
+  measureText(text: string, style: Partial<TextStyle>): number {
+    const font = this.buildFontString(style);
+    this.measureCtx.font = font;
+    return this.measureCtx.measureText(text).width;
+  }
+  
+  /**
+   * Truncate text to fit within maxWidth, adding ellipsis if needed
+   */
+  truncateText(text: string, maxWidth: number, style: Partial<TextStyle>): string {
+    const font = this.buildFontString(style);
+    this.measureCtx.font = font;
+    
+    const fullWidth = this.measureCtx.measureText(text).width;
+    if (fullWidth <= maxWidth) {
+      return text;
+    }
+    
+    const ellipsis = '…';
+    const ellipsisWidth = this.measureCtx.measureText(ellipsis).width;
+    const availableWidth = maxWidth - ellipsisWidth;
+    
+    if (availableWidth <= 0) {
+      return ellipsis;
+    }
+    
+    // Binary search for the right truncation point
+    let low = 0;
+    let high = text.length;
+    
+    while (low < high) {
+      const mid = Math.ceil((low + high) / 2);
+      const truncated = text.substring(0, mid);
+      const width = this.measureCtx.measureText(truncated).width;
+      
+      if (width <= availableWidth) {
+        low = mid;
+      } else {
+        high = mid - 1;
+      }
+    }
+    
+    return text.substring(0, low) + ellipsis;
+  }
+  
+  /**
+   * Render text within bounds
+   */
+  renderText(
+    ctx: CanvasRenderingContext2D,
+    text: string,
+    bounds: Rect,
+    style: Partial<TextStyle>,
+    padding: number = 4
+  ): void {
+    if (!text) return;
+    
+    const font = this.buildFontString(style);
+    const metrics = this.getFontMetrics(font);
+    
+    ctx.font = font;
+    ctx.fillStyle = style.color ?? this.theme.cellTextColor;
+    
+    // Calculate available width for text
+    const availableWidth = bounds.width - padding * 2;
+    
+    // Truncate if necessary
+    const displayText = this.truncateText(text, availableWidth, style);
+    
+    // Calculate x position based on alignment
+    let x: number;
+    const textAlign = style.textAlign ?? 'left';
+    
+    switch (textAlign) {
+      case 'center':
+        ctx.textAlign = 'center';
+        x = bounds.x + bounds.width / 2;
+        break;
+      case 'right':
+        ctx.textAlign = 'right';
+        x = bounds.x + bounds.width - padding;
+        break;
+      case 'left':
+      default:
+        ctx.textAlign = 'left';
+        x = bounds.x + padding;
+        break;
+    }
+    
+    // Calculate y position based on vertical alignment
+    let y: number;
+    const verticalAlign = style.verticalAlign ?? 'middle';
+    
+    switch (verticalAlign) {
+      case 'top':
+        y = bounds.y + padding + metrics.baseline;
+        break;
+      case 'bottom':
+        y = bounds.y + bounds.height - padding;
+        break;
+      case 'middle':
+      default:
+        y = bounds.y + (bounds.height + metrics.baseline) / 2;
+        break;
+    }
+    
+    // Apply text decoration
+    ctx.fillText(displayText, x, y);
+    
+    // Render text decoration (underline, strikethrough)
+    if (style.textDecoration && style.textDecoration !== 'none') {
+      const textWidth = this.measureCtx.measureText(displayText).width;
+      
+      // Adjust x for decoration based on alignment
+      let decorationX: number;
+      switch (textAlign) {
+        case 'center':
+          decorationX = x - textWidth / 2;
+          break;
+        case 'right':
+          decorationX = x - textWidth;
+          break;
+        default:
+          decorationX = x;
+      }
+      
+      ctx.strokeStyle = style.color ?? this.theme.cellTextColor;
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      
+      if (style.textDecoration === 'underline') {
+        const underlineY = y + 2;
+        ctx.moveTo(decorationX, underlineY);
+        ctx.lineTo(decorationX + textWidth, underlineY);
+      } else if (style.textDecoration === 'line-through') {
+        const strikeY = y - metrics.baseline / 3;
+        ctx.moveTo(decorationX, strikeY);
+        ctx.lineTo(decorationX + textWidth, strikeY);
+      }
+      
+      ctx.stroke();
+    }
+  }
+  
+  /**
+   * Render wrapped text (for cells with text wrapping enabled)
+   */
+  renderWrappedText(
+    ctx: CanvasRenderingContext2D,
+    text: string,
+    bounds: Rect,
+    style: Partial<TextStyle>,
+    padding: number = 4
+  ): void {
+    if (!text) return;
+    
+    const font = this.buildFontString(style);
+    const metrics = this.getFontMetrics(font);
+    
+    ctx.font = font;
+    ctx.fillStyle = style.color ?? this.theme.cellTextColor;
+    
+    const availableWidth = bounds.width - padding * 2;
+    const words = text.split(' ');
+    const lines: string[] = [];
+    let currentLine = '';
+    
+    // Word wrap
+    for (const word of words) {
+      const testLine = currentLine ? `${currentLine} ${word}` : word;
+      const testWidth = this.measureCtx.measureText(testLine).width;
+      
+      if (testWidth <= availableWidth) {
+        currentLine = testLine;
+      } else {
+        if (currentLine) {
+          lines.push(currentLine);
+        }
+        currentLine = word;
+      }
+    }
+    if (currentLine) {
+      lines.push(currentLine);
+    }
+    
+    // Calculate starting y position
+    const totalTextHeight = lines.length * metrics.lineHeight;
+    let startY: number;
+    const verticalAlign = style.verticalAlign ?? 'middle';
+    
+    switch (verticalAlign) {
+      case 'top':
+        startY = bounds.y + padding + metrics.baseline;
+        break;
+      case 'bottom':
+        startY = bounds.y + bounds.height - padding - totalTextHeight + metrics.baseline;
+        break;
+      case 'middle':
+      default:
+        startY = bounds.y + (bounds.height - totalTextHeight) / 2 + metrics.baseline;
+        break;
+    }
+    
+    // Calculate x position based on alignment
+    const textAlign = style.textAlign ?? 'left';
+    let x: number;
+    
+    switch (textAlign) {
+      case 'center':
+        ctx.textAlign = 'center';
+        x = bounds.x + bounds.width / 2;
+        break;
+      case 'right':
+        ctx.textAlign = 'right';
+        x = bounds.x + bounds.width - padding;
+        break;
+      case 'left':
+      default:
+        ctx.textAlign = 'left';
+        x = bounds.x + padding;
+        break;
+    }
+    
+    // Render each line
+    let y = startY;
+    for (const line of lines) {
+      // Only render if within bounds
+      if (y + metrics.lineHeight > bounds.y && y - metrics.baseline < bounds.y + bounds.height) {
+        ctx.fillText(line, x, y);
+      }
+      y += metrics.lineHeight;
+    }
+  }
+  
+  /**
+   * Clear the metrics cache
+   */
+  clearCache(): void {
+    this.metricsCache.clear();
+  }
+}
+

package/src/canvas/types.ts

@@ -0,0 +1,289 @@
+// Canvas rendering types for pagent-sheets
+
+import type { Cell, CellStyle, CellFormat, Selection, ColumnFilter } from '../types';
+
+/**
+ * Rectangle bounds
+ */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Point coordinates
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Cell position in the grid
+ */
+export interface CellPosition {
+  row: number;
+  col: number;
+}
+
+/**
+ * Viewport state - what's currently visible
+ */
+export interface Viewport {
+  scrollTop: number;
+  scrollLeft: number;
+  width: number;
+  height: number;
+  startRow: number;
+  endRow: number;
+  startCol: number;
+  endCol: number;
+}
+
+/**
+ * Text style for rendering
+ */
+export interface TextStyle {
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: 'normal' | 'bold';
+  fontStyle: 'normal' | 'italic';
+  color: string;
+  textAlign: 'left' | 'center' | 'right';
+  verticalAlign: 'top' | 'middle' | 'bottom';
+  textDecoration?: 'none' | 'underline' | 'line-through';
+}
+
+/**
+ * Border style for a single edge
+ */
+export interface BorderStyle {
+  width: number;
+  color: string;
+  style: 'solid' | 'dashed' | 'dotted';
+}
+
+/**
+ * Complete border configuration for a cell
+ */
+export interface CellBorders {
+  top?: BorderStyle;
+  right?: BorderStyle;
+  bottom?: BorderStyle;
+  left?: BorderStyle;
+}
+
+/**
+ * Header hit test result
+ */
+export interface HeaderHit {
+  type: 'row' | 'column';
+  index: number;
+  isResize: boolean;
+}
+
+/**
+ * Resize handle hit test result
+ */
+export interface ResizeHandle {
+  type: 'row' | 'column';
+  index: number;
+}
+
+/**
+ * Theme colors for the canvas
+ */
+export interface CanvasTheme {
+  // Grid
+  gridLineColor: string;
+  gridLineWidth: number;
+  
+  // Headers
+  headerBackgroundColor: string;
+  headerTextColor: string;
+  headerBorderColor: string;
+  headerFont: string;
+  headerFontSize: number;
+  
+  // Cells
+  cellBackgroundColor: string;
+  cellTextColor: string;
+  cellFont: string;
+  cellFontSize: number;
+  
+  // Selection
+  selectionBorderColor: string;
+  selectionBorderWidth: number;
+  selectionFillColor: string;
+  activeCellBorderColor: string;
+  activeCellBorderWidth: number;
+  
+  // Fill handle
+  fillHandleColor: string;
+  fillHandleSize: number;
+  
+  // Formula reference highlighting colors (border, fill pairs)
+  formulaReferenceColors: Array<{ border: string; fill: string }>;
+  
+  // Freeze panes
+  freezeDividerColor: string;
+  freezeDividerWidth: number;
+  freezeShadowColor: string;
+}
+
+/**
+ * Default theme
+ */
+export const DEFAULT_THEME: CanvasTheme = {
+  // Grid
+  gridLineColor: '#e2e2e2',
+  gridLineWidth: 1,
+  
+  // Headers
+  headerBackgroundColor: '#f8f9fa',
+  headerTextColor: '#5f6368',
+  headerBorderColor: '#e8eaed',
+  headerFont: 'Arial',
+  headerFontSize: 11,
+  
+  // Cells
+  cellBackgroundColor: '#ffffff',
+  cellTextColor: '#000000',
+  cellFont: 'Arial',
+  cellFontSize: 11,
+  
+  // Selection
+  selectionBorderColor: '#1a73e8',
+  selectionBorderWidth: 2,
+  selectionFillColor: 'rgba(26, 115, 232, 0.1)',
+  activeCellBorderColor: '#1a73e8',
+  activeCellBorderWidth: 2,
+  
+  // Fill handle
+  fillHandleColor: '#1a73e8',
+  fillHandleSize: 6,
+  
+  // Formula reference highlighting colors (like Google Sheets)
+  formulaReferenceColors: [
+    { border: '#4285F4', fill: 'rgba(66, 133, 244, 0.15)' },  // Blue
+    { border: '#EA4335', fill: 'rgba(234, 67, 53, 0.15)' },   // Red
+    { border: '#FBBC04', fill: 'rgba(251, 188, 4, 0.15)' },   // Yellow
+    { border: '#34A853', fill: 'rgba(52, 168, 83, 0.15)' },   // Green
+    { border: '#9C27B0', fill: 'rgba(156, 39, 176, 0.15)' },  // Purple
+    { border: '#FF9800', fill: 'rgba(255, 152, 0, 0.15)' },   // Orange
+    { border: '#00BCD4', fill: 'rgba(0, 188, 212, 0.15)' },   // Cyan
+    { border: '#E91E63', fill: 'rgba(233, 30, 99, 0.15)' },   // Pink
+  ],
+  
+  // Freeze panes
+  freezeDividerColor: '#c0c0c0',
+  freezeDividerWidth: 2,
+  freezeShadowColor: 'rgba(0, 0, 0, 0.08)',
+};
+
+/**
+ * Configuration for the canvas renderer
+ */
+export interface CanvasRendererConfig {
+  canvas: HTMLCanvasElement;
+  devicePixelRatio?: number;
+  defaultRowHeight: number;
+  defaultColWidth: number;
+  headerHeight: number;
+  headerWidth: number;
+  theme?: Partial<CanvasTheme>;
+}
+
+/**
+ * Formula range for highlighting cell references in formulas
+ */
+export interface FormulaRangeHighlight {
+  startRow: number;
+  startCol: number;
+  endRow: number;
+  endCol: number;
+  colorIndex: number; // Index for color selection
+}
+
+/**
+ * State required for rendering
+ */
+export interface RenderState {
+  cells: Map<string, Cell>;
+  styles: Map<string, CellStyle>;
+  formats: Map<string, CellFormat>;
+  selection: Selection | null;
+  activeCell: CellPosition | null;
+  editingCell: CellPosition | null;
+  rowHeights: Map<number, number>;
+  colWidths: Map<number, number>;
+  rowCount: number;
+  colCount: number;
+  /** Formula ranges to highlight (cell references in formulas) */
+  formulaRanges?: FormulaRangeHighlight[];
+  /** Hidden rows (Set of row indices) */
+  hiddenRows?: Set<number>;
+  /** Hidden columns (Set of column indices) */
+  hiddenCols?: Set<number>;
+  /** Number of frozen rows (rows that stay visible when scrolling vertically) */
+  frozenRows?: number;
+  /** Number of frozen columns (columns that stay visible when scrolling horizontally) */
+  frozenCols?: number;
+  /** Active filters (column -> filter) */
+  filters?: Map<number, ColumnFilter>;
+  /** Filtered rows (rows that should be visible after filtering) */
+  filteredRows?: Set<number>;
+}
+
+/**
+ * Region that needs to be redrawn
+ */
+export interface DirtyRegion {
+  type: 'all' | 'cells' | 'headers' | 'selection';
+  bounds?: Rect;
+}
+
+/**
+ * Cursor types for different interactions
+ */
+export type CursorType = 
+  | 'default'
+  | 'pointer'
+  | 'cell'
+  | 'col-resize'
+  | 'row-resize'
+  | 'crosshair'
+  | 'grab'
+  | 'grabbing';
+
+/**
+ * Mouse event data with grid coordinates
+ */
+export interface CanvasMouseEvent {
+  // Screen coordinates relative to canvas
+  x: number;
+  y: number;
+  // Grid coordinates (if over a cell)
+  cell: CellPosition | null;
+  // Header info (if over a header)
+  header: HeaderHit | null;
+  // Resize handle (if near one)
+  resizeHandle: ResizeHandle | null;
+  // Fill handle
+  isFillHandle: boolean;
+  // Original event
+  originalEvent: MouseEvent;
+}
+
+/**
+ * Scroll event data
+ */
+export interface CanvasScrollEvent {
+  scrollTop: number;
+  scrollLeft: number;
+  deltaX: number;
+  deltaY: number;
+}
+

package/src/collaboration/firebase-provider.ts

@@ -0,0 +1,48 @@
+// Firebase collaboration provider
+// disabling eslint for this file because it is a placeholder for the actual implementation. remove when implemented.
+/* eslint-disable */
+// @ts-nocheck
+import type { CollaborationProvider, Presence } from './types';
+
+export class FirebaseCollaborationProvider implements CollaborationProvider {
+  private db: any; // Firebase Realtime Database or Firestore
+  private handlers: Map<string, Set<(data: unknown) => void>> = new Map();
+  private presences: Map<string, Presence> = new Map();
+
+  constructor() {
+    // Initialize Firebase
+    // this.db = initializeFirebase(firebaseConfig);
+  }
+
+  async connect(workbookId: string): Promise<void> {
+    // Connect to Firebase Realtime Database or Firestore
+    // Set up listeners for changes, presence, etc.
+  }
+
+  disconnect(): void {
+    // Clean up Firebase listeners
+    this.handlers.clear();
+    this.presences.clear();
+  }
+
+  on(event: 'change' | 'presence' | 'cursor', handler: (data: unknown) => void): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+
+    return () => {
+      this.handlers.get(event)?.delete(handler);
+    };
+  }
+
+  emit(event: 'change' | 'presence' | 'cursor', data: unknown): void {
+    // Send data to Firebase
+    // Firebase will broadcast to other clients
+  }
+
+  getPresences(): Presence[] {
+    return Array.from(this.presences.values());
+  }
+}
+

package/src/collaboration/index.ts

@@ -0,0 +1,5 @@
+// Collaboration package exports
+
+export * from './types';
+export * from './firebase-provider';
+

package/src/collaboration/types.ts

@@ -0,0 +1,38 @@
+// Collaboration types
+
+export interface Presence {
+  userId: string;
+  username: string;
+  color: string;
+  selection?: {
+    row: number;
+    col: number;
+  };
+  cursor?: {
+    row: number;
+    col: number;
+  };
+}
+
+export interface CollaborationOperation {
+  type: 'cellChange' | 'selectionChange' | 'sheetChange';
+  sheetId: string;
+  row?: number;
+  col?: number;
+  value?: unknown;
+  selection?: {
+    row: number;
+    col: number;
+  };
+  timestamp: number;
+  userId: string;
+}
+
+export interface CollaborationProvider {
+  connect(workbookId: string): Promise<void>;
+  disconnect(): void;
+  on(event: 'change' | 'presence' | 'cursor', handler: (data: unknown) => void): () => void;
+  emit(event: 'change' | 'presence' | 'cursor', data: unknown): void;
+  getPresences(): Presence[];
+}
+