@lotics/xlsx 0.1.0

package/src/canvas_fill.ts

@@ -0,0 +1,156 @@
+// =============================================================================
+// Canvas Fill Helpers
+// =============================================================================
+//
+// Pattern fills (hatches/stripes) and gradient fills drawn via Canvas 2D API.
+// Patterns are cached by pattern type key for reuse.
+// =============================================================================
+
+import type { GradientData } from "./types";
+
+// =============================================================================
+// Pattern fills
+// =============================================================================
+
+const patternCache = new Map<string, CanvasPattern | null>();
+
+/**
+ * Create a repeating CanvasPattern for a given OOXML pattern type.
+ * Colors are extracted from the CSS string (output of getPatternFillCSS).
+ * Pattern geometry is determined by the OOXML patternType name.
+ */
+export function createPatternFill(
+  ctx: CanvasRenderingContext2D,
+  patternCss: string,
+  patternType?: string,
+): CanvasPattern | null {
+  const cacheKey = `${patternType ?? ""}|${patternCss}`;
+  const cached = patternCache.get(cacheKey);
+  if (cached !== undefined) return cached;
+
+  const size = 8;
+  // Use OffscreenCanvas when available, fall back to a regular canvas element (Safari < 16.4, older WebViews)
+  let tile: HTMLCanvasElement | OffscreenCanvas;
+  if (typeof OffscreenCanvas !== "undefined") {
+    tile = new OffscreenCanvas(size, size);
+  } else {
+    const el = document.createElement("canvas");
+    el.width = size;
+    el.height = size;
+    tile = el;
+  }
+  const tileCtx = tile.getContext("2d") as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+  if (!tileCtx) {
+    patternCache.set(cacheKey, null);
+    return null;
+  }
+
+  const colors = extractPatternColors(patternCss);
+  drawPatternTile(tileCtx, size, patternType ?? "", colors.fg, colors.bg);
+
+  const pattern = ctx.createPattern(tile, "repeat");
+  patternCache.set(cacheKey, pattern);
+  return pattern;
+}
+
+function drawPatternTile(
+  tileCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+  size: number,
+  pt: string,
+  fg: string,
+  bg: string,
+): void {
+  tileCtx.fillStyle = bg;
+  tileCtx.fillRect(0, 0, size, size);
+  tileCtx.strokeStyle = fg;
+  tileCtx.lineWidth = 1;
+
+  if (pt.includes("Vertical") || pt === "lightVertical") {
+    tileCtx.beginPath();
+    tileCtx.moveTo(4, 0);
+    tileCtx.lineTo(4, size);
+    tileCtx.stroke();
+  } else if (pt.includes("Horizontal") || pt === "lightHorizontal") {
+    tileCtx.beginPath();
+    tileCtx.moveTo(0, 4);
+    tileCtx.lineTo(size, 4);
+    tileCtx.stroke();
+  } else if (pt.includes("Grid") || pt === "lightGrid") {
+    tileCtx.beginPath();
+    tileCtx.moveTo(4, 0);
+    tileCtx.lineTo(4, size);
+    tileCtx.moveTo(0, 4);
+    tileCtx.lineTo(size, 4);
+    tileCtx.stroke();
+  } else if (pt.includes("Diagonal") || pt.includes("diagonal")) {
+    tileCtx.beginPath();
+    tileCtx.moveTo(0, 0);
+    tileCtx.lineTo(size, size);
+    tileCtx.stroke();
+  } else if (pt.includes("gray") || pt === "gray125" || pt === "gray0625") {
+    tileCtx.fillStyle = fg;
+    for (let x = 0; x < size; x += 2) {
+      for (let y = 0; y < size; y += 2) {
+        tileCtx.fillRect(x, y, 1, 1);
+      }
+    }
+  } else {
+    tileCtx.beginPath();
+    tileCtx.moveTo(0, 0);
+    tileCtx.lineTo(size, size);
+    tileCtx.stroke();
+  }
+}
+
+function extractPatternColors(css: string): { fg: string; bg: string } {
+  // Try to extract rgb/rgba colors from the CSS string
+  const colorMatches = css.match(/rgba?\([^)]+\)/g);
+  if (colorMatches && colorMatches.length >= 2) {
+    return { fg: colorMatches[0], bg: colorMatches[1] };
+  }
+  if (colorMatches && colorMatches.length === 1) {
+    return { fg: colorMatches[0], bg: "rgb(255, 255, 255)" };
+  }
+  // Try hex colors
+  const hexMatches = css.match(/#[0-9a-fA-F]{6}/g);
+  if (hexMatches && hexMatches.length >= 2) {
+    return { fg: hexMatches[0], bg: hexMatches[1] };
+  }
+  return { fg: "rgb(0, 0, 0)", bg: "rgb(255, 255, 255)" };
+}
+
+// =============================================================================
+// Gradient fills
+// =============================================================================
+
+export function createGradientFill(
+  ctx: CanvasRenderingContext2D,
+  gradientData: GradientData,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): CanvasGradient {
+  let gradient: CanvasGradient;
+
+  if (gradientData.type === "radial") {
+    const cx = x + w / 2;
+    const cy = y + h / 2;
+    const r = Math.max(w, h) / 2;
+    gradient = ctx.createRadialGradient(cx, cy, 0, cx, cy, r);
+  } else {
+    // Linear gradient — convert degree to start/end points
+    const rad = (gradientData.degree * Math.PI) / 180;
+    const dx = Math.cos(rad) * w / 2;
+    const dy = Math.sin(rad) * h / 2;
+    const cx = x + w / 2;
+    const cy = y + h / 2;
+    gradient = ctx.createLinearGradient(cx - dx, cy - dy, cx + dx, cy + dy);
+  }
+
+  for (const stop of gradientData.stops) {
+    gradient.addColorStop(stop.position, stop.color);
+  }
+
+  return gradient;
+}

package/src/canvas_images.ts

@@ -0,0 +1,99 @@
+// =============================================================================
+// Canvas Image Compositing
+// =============================================================================
+//
+// Draws embedded images on the canvas at their anchor positions.
+// Images use two-cell anchors (from/to) with optional EMU sub-cell offsets.
+// =============================================================================
+
+import type { LayoutEngine } from "./canvas_layout";
+import type { ParsedImage } from "./types";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** EMU per inch — Excel Measurement Unit. */
+const EMU_PER_INCH = 914400;
+/** Pixels per inch (screen DPI). */
+const PPI = 96;
+/** EMU per pixel. */
+const EMU_PER_PX = EMU_PER_INCH / PPI;
+
+// =============================================================================
+// Image drawing
+// =============================================================================
+
+/** Cache for loaded image elements. */
+const imageCache = new Map<string, HTMLImageElement>();
+
+/**
+ * Draw all images for the visible area.
+ */
+export function drawImages(
+  ctx: CanvasRenderingContext2D,
+  images: ParsedImage[],
+  layout: LayoutEngine,
+  scrollX: number,
+  scrollY: number,
+  viewWidth: number,
+  viewHeight: number,
+): void {
+  for (const img of images) {
+    drawImage(ctx, img, layout, scrollX, scrollY, viewWidth, viewHeight);
+  }
+}
+
+function drawImage(
+  ctx: CanvasRenderingContext2D,
+  img: ParsedImage,
+  layout: LayoutEngine,
+  scrollX: number,
+  scrollY: number,
+  viewWidth: number,
+  viewHeight: number,
+): void {
+  // Compute pixel bounds from anchor
+  const x1 = layout.colX[img.tl.col] ?? 0;
+  const y1 = layout.rowY[img.tl.row] ?? 0;
+  const x2 = (layout.colX[img.br.col] ?? 0) + (layout.colW[img.br.col] ?? 0);
+  const y2 = (layout.rowY[img.br.row] ?? 0) + (layout.rowH[img.br.row] ?? 0);
+
+  // Apply scroll
+  const drawX = x1 - scrollX;
+  const drawY = y1 - scrollY;
+  const drawW = x2 - x1;
+  const drawH = y2 - y1;
+
+  // Skip if outside viewport
+  if (drawX + drawW < 0 || drawY + drawH < 0 || drawX > viewWidth || drawY > viewHeight) {
+    return;
+  }
+
+  // Load or retrieve cached image
+  let imgEl = imageCache.get(img.dataUrl);
+  if (!imgEl) {
+    imgEl = new Image();
+    imgEl.src = img.dataUrl;
+    imageCache.set(img.dataUrl, imgEl);
+  }
+
+  if (imgEl.complete && imgEl.naturalWidth > 0) {
+    ctx.drawImage(imgEl, drawX, drawY, drawW, drawH);
+  }
+  // If not loaded yet, it will appear on the next redraw
+}
+
+/**
+ * Convert EMU offset to pixels.
+ */
+export function emuToPixels(emu: number): number {
+  return emu / EMU_PER_PX;
+}
+
+/**
+ * Clear the image cache (call on workbook change).
+ */
+export function clearImageCache(): void {
+  imageCache.clear();
+}

package/src/canvas_layout.test.ts

@@ -0,0 +1,159 @@
+import {
+  LayoutEngine,
+  ROW_HEADER_WIDTH,
+  COL_HEADER_HEIGHT,
+  MIN_COL_WIDTH_PX,
+} from "./canvas_layout";
+
+function makeLayout(overrides?: {
+  colCount?: number;
+  rowCount?: number;
+  colWidths?: Map<number, number>;
+  rowHeights?: Map<number, number>;
+  hiddenCols?: Set<number>;
+  hiddenRows?: Set<number>;
+  freeze?: { row: number; col: number };
+}): LayoutEngine {
+  return new LayoutEngine({
+    colCount: overrides?.colCount ?? 10,
+    rowCount: overrides?.rowCount ?? 20,
+    colWidths: overrides?.colWidths ?? new Map(),
+    rowHeights: overrides?.rowHeights ?? new Map(),
+    defaultColWidth: 8,
+    defaultRowHeight: 15, // 15pt → 20px after pt-to-px conversion
+    hiddenCols: overrides?.hiddenCols ?? new Set(),
+    hiddenRows: overrides?.hiddenRows ?? new Set(),
+    freeze: overrides?.freeze,
+  });
+}
+
+describe("LayoutEngine", () => {
+  test("computes column positions", () => {
+    const layout = makeLayout({ colCount: 3 });
+    expect(layout.colX[0]).toBe(ROW_HEADER_WIDTH);
+    // Default col width = 8 * CHAR_WIDTH_PX = 64
+    expect(layout.colX[1]).toBe(ROW_HEADER_WIDTH);
+    expect(layout.colX[2]).toBe(ROW_HEADER_WIDTH + 64);
+    expect(layout.colX[3]).toBe(ROW_HEADER_WIDTH + 128);
+    expect(layout.colW[1]).toBe(64);
+  });
+
+  test("computes row positions", () => {
+    const layout = makeLayout({ rowCount: 3 });
+    expect(layout.rowY[0]).toBe(COL_HEADER_HEIGHT);
+    expect(layout.rowY[1]).toBe(COL_HEADER_HEIGHT);
+    expect(layout.rowY[2]).toBe(COL_HEADER_HEIGHT + 20);
+    expect(layout.rowH[1]).toBe(20);
+  });
+
+  test("respects custom column widths", () => {
+    const layout = makeLayout({
+      colCount: 3,
+      colWidths: new Map([[2, 20]]),
+    });
+    expect(layout.colW[1]).toBe(64); // default
+    expect(layout.colW[2]).toBe(160); // 20 * 8
+    expect(layout.colW[3]).toBe(64); // default
+  });
+
+  test("respects custom row heights", () => {
+    const layout = makeLayout({
+      rowCount: 3,
+      rowHeights: new Map([[2, 30]]), // 30pt → 40px
+    });
+    expect(layout.rowH[1]).toBe(20); // default: 15pt → 20px
+    expect(layout.rowH[2]).toBe(40); // 30pt → 40px
+    expect(layout.rowH[3]).toBe(20); // default
+  });
+
+  test("hidden columns have zero width", () => {
+    const layout = makeLayout({
+      colCount: 3,
+      hiddenCols: new Set([2]),
+    });
+    expect(layout.colW[2]).toBe(0);
+    expect(layout.colX[3]).toBe(layout.colX[2]); // same position
+  });
+
+  test("hidden rows have zero height", () => {
+    const layout = makeLayout({
+      rowCount: 3,
+      hiddenRows: new Set([2]),
+    });
+    expect(layout.rowH[2]).toBe(0);
+    expect(layout.rowY[3]).toBe(layout.rowY[2]);
+  });
+
+  test("totalWidth includes all columns + row header", () => {
+    const layout = makeLayout({ colCount: 5 });
+    expect(layout.totalWidth).toBe(ROW_HEADER_WIDTH + 5 * 64);
+  });
+
+  test("totalHeight includes all rows + col header", () => {
+    const layout = makeLayout({ rowCount: 5 });
+    expect(layout.totalHeight).toBe(COL_HEADER_HEIGHT + 5 * 20);
+  });
+
+  test("frozen dimensions", () => {
+    const layout = makeLayout({
+      colCount: 5,
+      rowCount: 10,
+      freeze: { row: 2, col: 1 },
+    });
+    expect(layout.frozenHeight).toBe(40); // 2 rows * 20px
+    expect(layout.frozenWidth).toBe(64); // 1 col * 64px
+  });
+
+  test("getVisibleRange returns correct range", () => {
+    const layout = makeLayout({ colCount: 100, rowCount: 1000 });
+    const range = layout.getVisibleRange(0, 0, 800, 600);
+    expect(range.startRow).toBeGreaterThanOrEqual(1);
+    expect(range.endRow).toBeLessThanOrEqual(1000);
+    expect(range.startCol).toBeGreaterThanOrEqual(1);
+    expect(range.endCol).toBeLessThanOrEqual(100);
+  });
+
+  test("getVisibleRange with scroll offset", () => {
+    const layout = makeLayout({ colCount: 100, rowCount: 1000 });
+    const range = layout.getVisibleRange(640, 2000, 800, 600);
+    // With scroll, visible rows/cols should shift
+    expect(range.startRow).toBeGreaterThan(1);
+    expect(range.startCol).toBeGreaterThan(1);
+  });
+
+  test("hitTest identifies cell region", () => {
+    const layout = makeLayout({ colCount: 5, rowCount: 10 });
+    const hit = layout.hitTest(ROW_HEADER_WIDTH + 10, COL_HEADER_HEIGHT + 10, 0, 0);
+    expect(hit?.region).toBe("cell");
+    expect(hit?.row).toBe(1);
+    expect(hit?.col).toBe(1);
+  });
+
+  test("hitTest identifies corner", () => {
+    const layout = makeLayout();
+    const hit = layout.hitTest(5, 5, 0, 0);
+    expect(hit?.region).toBe("corner");
+  });
+
+  test("hitTest identifies column header", () => {
+    const layout = makeLayout();
+    const hit = layout.hitTest(ROW_HEADER_WIDTH + 10, 5, 0, 0);
+    expect(hit?.region).toBe("col-header");
+    expect(hit?.col).toBe(1);
+  });
+
+  test("hitTest identifies row header", () => {
+    const layout = makeLayout();
+    const hit = layout.hitTest(5, COL_HEADER_HEIGHT + 10, 0, 0);
+    expect(hit?.region).toBe("row-header");
+    expect(hit?.row).toBe(1);
+  });
+
+  test("minimum column width enforced", () => {
+    const layout = makeLayout({
+      colCount: 1,
+      colWidths: new Map([[1, 1]]), // 1 char = 8px, less than MIN_COL_WIDTH_PX
+    });
+    expect(layout.colW[1]).toBe(MIN_COL_WIDTH_PX);
+  });
+});

package/src/canvas_layout.ts

@@ -0,0 +1,239 @@
+// =============================================================================
+// Canvas Layout Engine
+// =============================================================================
+//
+// Pure math for spreadsheet layout calculations:
+// - Column X positions and widths in pixels
+// - Row Y positions and heights in pixels
+// - Visible range computation for virtual scrolling
+// - Hit-testing: pixel → cell reference
+// =============================================================================
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+export const ROW_HEADER_WIDTH = 50;
+export const COL_HEADER_HEIGHT = 24;
+export const DEFAULT_COL_WIDTH_PX = 64;
+export const MIN_COL_WIDTH_PX = 20;
+export const DEFAULT_ROW_HEIGHT_PX = 21;
+export const CHAR_WIDTH_PX = 8;
+/** Excel stores row heights in points (1pt = 1/72 inch). At 96 DPI, 1pt = 96/72 = 1.333px. */
+export const PT_TO_PX = 96 / 72;
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface LayoutConfig {
+  /** Total number of columns. */
+  colCount: number;
+  /** Total number of rows. */
+  rowCount: number;
+  /** Column widths in character units (sparse — only non-default). */
+  colWidths: Map<number, number>;
+  /** Row heights in points (sparse — only non-default). */
+  rowHeights: Map<number, number>;
+  /** Default column width in character units. */
+  defaultColWidth: number;
+  /** Default row height in points. */
+  defaultRowHeight: number;
+  /** Hidden columns. */
+  hiddenCols: Set<number>;
+  /** Hidden rows. */
+  hiddenRows: Set<number>;
+  /** Frozen pane: { row, col } — rows/cols before this are frozen. */
+  freeze?: { row: number; col: number };
+}
+
+export interface VisibleRange {
+  startRow: number;
+  endRow: number;
+  startCol: number;
+  endCol: number;
+}
+
+export interface HitResult {
+  row: number;
+  col: number;
+  region: "cell" | "row-header" | "col-header" | "corner";
+}
+
+// =============================================================================
+// LayoutEngine
+// =============================================================================
+
+export class LayoutEngine {
+  /** Cumulative X positions: colX[i] = left edge of column i (1-based). colX[0] = ROW_HEADER_WIDTH. */
+  readonly colX: Float64Array;
+  /** Width of each column in pixels: colW[i] for column i (1-based). */
+  readonly colW: Float64Array;
+  /** Cumulative Y positions: rowY[i] = top edge of row i (1-based). rowY[0] = COL_HEADER_HEIGHT. */
+  readonly rowY: Float64Array;
+  /** Height of each row in pixels: rowH[i] for row i (1-based). */
+  readonly rowH: Float64Array;
+
+  /** Total content width (all columns + row header). */
+  readonly totalWidth: number;
+  /** Total content height (all rows + col header). */
+  readonly totalHeight: number;
+  /** Frozen area width in pixels (excludes row header). */
+  readonly frozenWidth: number;
+  /** Frozen area height in pixels (excludes col header). */
+  readonly frozenHeight: number;
+
+  /** Frozen pane configuration (row/col indices). */
+  readonly freeze: { row: number; col: number };
+
+  private config: LayoutConfig;
+
+  constructor(config: LayoutConfig) {
+    this.config = config;
+    this.freeze = { row: config.freeze?.row ?? 0, col: config.freeze?.col ?? 0 };
+    const { colCount, rowCount } = config;
+
+    // Build column positions
+    this.colW = new Float64Array(colCount + 1);
+    this.colX = new Float64Array(colCount + 1);
+    this.colX[0] = ROW_HEADER_WIDTH;
+    let x = ROW_HEADER_WIDTH;
+    for (let c = 1; c <= colCount; c++) {
+      const w = config.hiddenCols.has(c)
+        ? 0
+        : Math.max(
+            (config.colWidths.get(c) ?? config.defaultColWidth) * CHAR_WIDTH_PX,
+            MIN_COL_WIDTH_PX,
+          );
+      this.colW[c] = w;
+      this.colX[c] = x;
+      x += w;
+    }
+    this.totalWidth = x;
+
+    // Build row positions
+    this.rowH = new Float64Array(rowCount + 1);
+    this.rowY = new Float64Array(rowCount + 1);
+    this.rowY[0] = COL_HEADER_HEIGHT;
+    let y = COL_HEADER_HEIGHT;
+    for (let r = 1; r <= rowCount; r++) {
+      const rawH = config.hiddenRows.has(r)
+        ? 0
+        : config.rowHeights.get(r) ?? config.defaultRowHeight;
+      const h = rawH > 0 ? Math.round(rawH * PT_TO_PX) : 0;
+      this.rowH[r] = h;
+      this.rowY[r] = y;
+      y += h;
+    }
+    this.totalHeight = y;
+
+    // Frozen dimensions — sum heights/widths of frozen rows/cols
+    const freezeRow = config.freeze?.row ?? 0;
+    const freezeCol = config.freeze?.col ?? 0;
+    let fh = 0;
+    for (let r = 1; r <= Math.min(freezeRow, rowCount); r++) fh += this.rowH[r];
+    this.frozenHeight = fh;
+    let fw = 0;
+    for (let c = 1; c <= Math.min(freezeCol, colCount); c++) fw += this.colW[c];
+    this.frozenWidth = fw;
+  }
+
+  /** Get the visible row/col range for the given scroll position and viewport size. */
+  getVisibleRange(
+    scrollX: number,
+    scrollY: number,
+    viewWidth: number,
+    viewHeight: number,
+  ): VisibleRange {
+    const freezeRow = this.config.freeze?.row ?? 0;
+    const freezeCol = this.config.freeze?.col ?? 0;
+
+    // Adjust for frozen area — scrollable content starts after frozen rows/cols
+    const contentStartY = COL_HEADER_HEIGHT + this.frozenHeight;
+    const contentStartX = ROW_HEADER_WIDTH + this.frozenWidth;
+
+    const startRow = Math.max(
+      freezeRow + 1,
+      this.findRow(scrollY + contentStartY),
+    );
+    const endRow = Math.min(
+      this.config.rowCount,
+      this.findRow(scrollY + viewHeight) + 1,
+    );
+    const startCol = Math.max(
+      freezeCol + 1,
+      this.findCol(scrollX + contentStartX),
+    );
+    const endCol = Math.min(
+      this.config.colCount,
+      this.findCol(scrollX + viewWidth) + 1,
+    );
+
+    return { startRow, endRow, startCol, endCol };
+  }
+
+  /** Convert a pixel position to a cell reference. */
+  hitTest(
+    px: number,
+    py: number,
+    scrollX: number,
+    scrollY: number,
+  ): HitResult | undefined {
+    // Corner
+    if (px < ROW_HEADER_WIDTH && py < COL_HEADER_HEIGHT) {
+      return { row: 0, col: 0, region: "corner" };
+    }
+
+    // Column header
+    if (py < COL_HEADER_HEIGHT) {
+      const col = px < ROW_HEADER_WIDTH + this.frozenWidth
+        ? this.findCol(px)
+        : this.findCol(px + scrollX);
+      return { row: 0, col, region: "col-header" };
+    }
+
+    // Row header
+    if (px < ROW_HEADER_WIDTH) {
+      const row = py < COL_HEADER_HEIGHT + this.frozenHeight
+        ? this.findRow(py)
+        : this.findRow(py + scrollY);
+      return { row, col: 0, region: "row-header" };
+    }
+
+    // Cell area
+    const col = px < ROW_HEADER_WIDTH + this.frozenWidth
+      ? this.findCol(px)
+      : this.findCol(px + scrollX);
+    const row = py < COL_HEADER_HEIGHT + this.frozenHeight
+      ? this.findRow(py)
+      : this.findRow(py + scrollY);
+
+    if (row < 1 || col < 1) return undefined;
+    return { row, col, region: "cell" };
+  }
+
+  /** Binary search for the row at pixel position y. */
+  private findRow(y: number): number {
+    let lo = 1;
+    let hi = this.config.rowCount;
+    while (lo <= hi) {
+      const mid = (lo + hi) >>> 1;
+      if (this.rowY[mid] <= y) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return Math.max(1, hi);
+  }
+
+  /** Binary search for the column at pixel position x. */
+  private findCol(x: number): number {
+    let lo = 1;
+    let hi = this.config.colCount;
+    while (lo <= hi) {
+      const mid = (lo + hi) >>> 1;
+      if (this.colX[mid] <= x) lo = mid + 1;
+      else hi = mid - 1;
+    }
+    return Math.max(1, hi);
+  }
+}
+