@lotics/xlsx 0.1.0

package/src/excel_parser.ts

@@ -0,0 +1,393 @@
+import { XMLParser } from "fast-xml-parser";
+import { unzipXlsx, decodeUtf8 } from "./ooxml_zip";
+import { parseTheme, defaultThemeColors } from "./ooxml_color";
+import type { ThemeData } from "./ooxml_color";
+import { parseStyles, emptyStyleResolver } from "./ooxml_styles";
+import { parseWorkbook, parseWorkbookRels, parseSharedStrings } from "./ooxml_workbook";
+import { parseSheet, emptySheet } from "./ooxml_sheet";
+import { parseChartXml } from "./ooxml_chart";
+import { parseDrawingXml } from "./ooxml_drawing";
+import type { DrawingRelation } from "./ooxml_drawing";
+import { parseTableXml, extractTableRIds } from "./ooxml_table";
+import {
+  parsePivotCacheDefinitionXml,
+  parsePivotTableXml,
+  extractPivotTableRIds,
+  extractWorkbookPivotCaches,
+} from "./ooxml_pivot";
+import { parseVmlDrawing } from "./ooxml_shape";
+import type { ParsedSpreadsheet, ParsedSheet, PrintTitles } from "./types";
+import type { ParsedChart } from "./ooxml_chart_types";
+import type { ParsedPivotCache, ParsedPivotTable } from "./ooxml_pivot_types";
+import { colLettersToNum } from "./excel_utils";
+
+// Re-export all public types from the canonical source
+export type {
+  ParsedSpreadsheet,
+  ParsedSheet,
+  ParsedImage,
+  FreezePane,
+  ParsedColumn,
+  ParsedRow,
+  CellContent,
+  RichTextPart,
+  RichTextFont,
+  ParsedCell,
+  CellStyle,
+  BorderStyle,
+  MergedCellRange,
+} from "./types";
+export { PasswordProtectedError } from "./types";
+
+export type {
+  ParsedConditionalFormat,
+  ParsedCfRule,
+  ParsedColorScaleRule,
+  ParsedDataBarRule,
+  ParsedIconSetRule,
+  ParsedStyleRule,
+  CfThreshold,
+  ParsedCfStyle,
+} from "./excel_cf_types";
+
+// =============================================================================
+// Parsing
+// =============================================================================
+
+export async function parseExcelFile(
+  url: string,
+  signal?: AbortSignal,
+): Promise<ParsedSpreadsheet> {
+  const response = await fetch(url, { signal });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch file: ${response.status} ${response.statusText}`);
+  }
+  return parseExcelBuffer(await response.arrayBuffer());
+}
+
+/**
+ * Parse an in-memory .xlsx buffer into a ParsedSpreadsheet.
+ * Use this when you already have the bytes (e.g. from File.arrayBuffer()).
+ */
+export function parseExcelBuffer(arrayBuffer: ArrayBuffer): ParsedSpreadsheet {
+  const zip = unzipXlsx(arrayBuffer);
+  return parseExcelFromZip(zip);
+}
+
+/**
+ * Parse from already-unzipped entries. Use this when you need both the
+ * ParsedSpreadsheet and the raw ZIP entries (e.g. for delta export).
+ */
+export function parseExcelFromZip(zip: Record<string, Uint8Array>): ParsedSpreadsheet {
+  // Parse theme
+  const themeEntry = findEntry(zip, "xl/theme/theme1.xml");
+  const theme: ThemeData = themeEntry
+    ? parseTheme(decodeUtf8(themeEntry))
+    : { colors: defaultThemeColors(), majorFont: "Calibri", minorFont: "Calibri" };
+
+  // Parse styles
+  const stylesEntry = findEntry(zip, "xl/styles.xml");
+  const styles = stylesEntry
+    ? parseStyles(decodeUtf8(stylesEntry), theme)
+    : emptyStyleResolver();
+
+  // Parse workbook
+  const wbEntry = findEntry(zip, "xl/workbook.xml");
+  if (!wbEntry) {
+    return { sheets: [emptySheet("Sheet1")], activeSheetIndex: 0 };
+  }
+  const workbookInfo = parseWorkbook(decodeUtf8(wbEntry));
+
+  // Parse workbook relationships
+  const wbRelsEntry = findEntry(zip, "xl/_rels/workbook.xml.rels");
+  const wbRels = wbRelsEntry ? parseWorkbookRels(decodeUtf8(wbRelsEntry)) : new Map<string, string>();
+
+  // Parse shared strings
+  const ssEntry = findEntry(zip, "xl/sharedStrings.xml");
+  const sharedStrings = ssEntry
+    ? parseSharedStrings(decodeUtf8(ssEntry), theme, styles.indexedColors)
+    : [];
+
+  // Generic XML parser for chart/drawing/table/comment files
+  const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    processEntities: false,
+    isArray: (tagName) =>
+      tagName === "Relationship" ||
+      tagName === "xdr:twoCellAnchor" ||
+      tagName === "xdr:oneCellAnchor" ||
+      tagName === "tableColumn" ||
+      tagName === "pivotField" ||
+      tagName === "cacheField" ||
+      tagName === "field" ||
+      tagName === "pageField" ||
+      tagName === "dataField" ||
+      tagName === "pivotCache",
+  });
+  const parseXmlDoc = (xml: string) => xmlParser.parse(xml) as Record<string, unknown>;
+
+  // -------------------------------------------------------------------------
+  // Pivot caches (workbook scope)
+  // -------------------------------------------------------------------------
+  // workbook.xml lists each pivotCache by cacheId + r:id; the rId resolves
+  // through the workbook rels to a pivotCacheDefinition path. Multiple pivot
+  // tables on different sheets may share a cache, so we parse caches once
+  // here and reference them from per-sheet pivot tables below.
+  const pivotCaches = new Map<number, ParsedPivotCache>();
+  if (wbEntry) {
+    const wbDoc = parseXmlDoc(decodeUtf8(wbEntry));
+    const wbCacheMap = extractWorkbookPivotCaches(wbDoc);
+    for (const [cacheId, rId] of wbCacheMap) {
+      const cacheTarget = wbRels.get(rId);
+      if (!cacheTarget) continue;
+      const cachePath = cacheTarget.startsWith("/")
+        ? cacheTarget.slice(1)
+        : `xl/${cacheTarget}`;
+      const cacheEntry = findEntry(zip, cachePath);
+      if (!cacheEntry) continue;
+      try {
+        pivotCaches.set(
+          cacheId,
+          parsePivotCacheDefinitionXml(decodeUtf8(cacheEntry), cacheId, parseXmlDoc),
+        );
+      } catch {
+        // Defensive: malformed cache shouldn't break workbook load. Pivot
+        // tables referencing this cache will simply render as empty.
+      }
+    }
+  }
+
+  // Parse every sheet. Hidden/veryHidden sheets are parsed too but tagged via
+  // `hidden` so renderers can skip them while data consumers can read them.
+  const sheets: ParsedSheet[] = [];
+  let activeSheetIndex = 0;
+
+  let visibleIndex = 0;
+  for (let i = 0; i < workbookInfo.sheets.length; i++) {
+    const sheetInfo = workbookInfo.sheets[i];
+    const isHidden = sheetInfo.state === "hidden" || sheetInfo.state === "veryHidden";
+
+    const relTarget = wbRels.get(sheetInfo.rId);
+    if (!relTarget) continue;
+
+    const sheetPath = relTarget.startsWith("/")
+      ? relTarget.slice(1)
+      : `xl/${relTarget}`;
+    const sheetEntry = findEntry(zip, sheetPath);
+    if (!sheetEntry) continue;
+
+    const sheetRelsPath = sheetPath.replace(/([^/]+)$/, "_rels/$1.rels");
+    const sheetRelsEntry = findEntry(zip, sheetRelsPath);
+    const sheetRelsXml = sheetRelsEntry ? decodeUtf8(sheetRelsEntry) : undefined;
+
+    const parsed = parseSheet(
+      decodeUtf8(sheetEntry),
+      sheetRelsXml,
+      styles,
+      sharedStrings,
+      theme,
+      styles.indexedColors,
+      zip,
+      workbookInfo.date1904,
+    );
+    parsed.name = sheetInfo.name;
+    if (isHidden) parsed.hidden = true;
+
+    const printTitlesRaw = workbookInfo.printTitlesBySheet.get(i);
+    if (printTitlesRaw) {
+      const pt = parsePrintTitlesRef(printTitlesRaw);
+      if (pt) parsed.printTitles = pt;
+    }
+
+    // Extract charts, tables, drawings, and threaded comments from sheet rels
+    if (sheetRelsXml) {
+      const sheetDir = sheetPath.substring(0, sheetPath.lastIndexOf("/") + 1);
+      const relsDoc = parseXmlDoc(sheetRelsXml);
+      const relsRoot = (relsDoc["Relationships"] ?? relsDoc) as Record<string, unknown>;
+      const relArr = (Array.isArray(relsRoot["Relationship"])
+        ? relsRoot["Relationship"]
+        : relsRoot["Relationship"] ? [relsRoot["Relationship"]] : []) as Array<Record<string, string>>;
+
+      const relMap = new Map<string, { type: string; target: string }>();
+      for (const rel of relArr) {
+        const id = rel["@_Id"];
+        const target = rel["@_Target"];
+        const type = rel["@_Type"] ?? "";
+        if (id && target) relMap.set(id, { type, target });
+      }
+
+      // --- Drawings (contains charts and additional images) ---
+      const charts: ParsedChart[] = [];
+      const drawingRelations: DrawingRelation[] = [];
+      for (const [, rel] of relMap) {
+        if (!rel.type.includes("/drawing") || rel.type.includes("drawingML")) continue;
+        const drawingPath = resolveRelTarget(rel.target, sheetDir);
+        const drawingEntry = findEntry(zip, drawingPath);
+        if (!drawingEntry) continue;
+
+        const drawingXml = decodeUtf8(drawingEntry);
+        const relations = parseDrawingXml(drawingXml, parseXmlDoc);
+        drawingRelations.push(...relations);
+
+        // Parse drawing rels (for chart and image targets)
+        const drawingRelsPath = drawingPath.replace(/([^/]+)$/, "_rels/$1.rels");
+        const drawingRelsEntry = findEntry(zip, drawingRelsPath);
+        const drawingRels = new Map<string, string>();
+        if (drawingRelsEntry) {
+          const drawingRelsDoc = parseXmlDoc(decodeUtf8(drawingRelsEntry));
+          const dr = (drawingRelsDoc["Relationships"] ?? drawingRelsDoc) as Record<string, unknown>;
+          const drArr = (Array.isArray(dr["Relationship"])
+            ? dr["Relationship"]
+            : dr["Relationship"] ? [dr["Relationship"]] : []) as Array<Record<string, string>>;
+          for (const r of drArr) {
+            if (r["@_Id"] && r["@_Target"]) drawingRels.set(r["@_Id"], r["@_Target"]);
+          }
+        }
+
+        const drawingDir = drawingPath.substring(0, drawingPath.lastIndexOf("/") + 1);
+
+        // Load charts referenced by drawing anchors
+        for (const dr of relations) {
+          if (dr.type !== "chart" || !dr.rId) continue;
+          const chartTarget = drawingRels.get(dr.rId);
+          if (!chartTarget) continue;
+          const chartPath = resolveRelTarget(chartTarget, drawingDir);
+          const chartEntry = findEntry(zip, chartPath);
+          if (!chartEntry) continue;
+          const chartData = parseChartXml(decodeUtf8(chartEntry), parseXmlDoc);
+          charts.push({ ...chartData, anchor: dr.anchor });
+        }
+      }
+
+      if (charts.length > 0) parsed.charts = charts;
+
+      // Collect shape/textbox/connector drawings
+      const drawings = drawingRelations
+        .filter((dr) => dr.type === "shape" && dr.drawing)
+        .map((dr) => dr.drawing!);
+      if (drawings.length > 0) parsed.drawings = drawings;
+
+      // --- VML drawings (legacy form controls) ---
+      for (const [, rel] of relMap) {
+        if (!rel.type.includes("vmlDrawing")) continue;
+        const vmlPath = resolveRelTarget(rel.target, sheetDir);
+        const vmlEntry = findEntry(zip, vmlPath);
+        if (!vmlEntry) continue;
+        const vmlDrawings = parseVmlDrawing(decodeUtf8(vmlEntry), parseXmlDoc);
+        if (vmlDrawings.length > 0) {
+          if (!parsed.drawings) parsed.drawings = [];
+          parsed.drawings.push(...vmlDrawings);
+        }
+      }
+
+      // --- Tables ---
+      const tableRIds = extractTableRIds(relsDoc);
+      const tables = [];
+      for (const [, target] of tableRIds) {
+        const tablePath = resolveRelTarget(target, sheetDir);
+        const tableEntry = findEntry(zip, tablePath);
+        if (!tableEntry) continue;
+        tables.push(parseTableXml(decodeUtf8(tableEntry), parseXmlDoc));
+      }
+      if (tables.length > 0) parsed.tables = tables;
+
+      // --- Pivot tables ---
+      const pivotRIds = extractPivotTableRIds(relsDoc);
+      const pivotTables: ParsedPivotTable[] = [];
+      for (const [, target] of pivotRIds) {
+        const pivotPath = resolveRelTarget(target, sheetDir);
+        const pivotEntry = findEntry(zip, pivotPath);
+        if (!pivotEntry) continue;
+        try {
+          pivotTables.push(
+            parsePivotTableXml(decodeUtf8(pivotEntry), parseXmlDoc),
+          );
+        } catch {
+          // Defensive: skip malformed pivots rather than failing the whole load.
+        }
+      }
+      if (pivotTables.length > 0) parsed.pivotTables = pivotTables;
+    }
+
+    sheets.push(parsed);
+
+    if (i === workbookInfo.activeSheetIndex) {
+      activeSheetIndex = visibleIndex;
+    }
+    visibleIndex++;
+  }
+
+  if (sheets.length === 0) {
+    return { sheets: [emptySheet("Sheet1")], activeSheetIndex: 0 };
+  }
+
+  if (activeSheetIndex >= sheets.length) activeSheetIndex = 0;
+
+  const result: ParsedSpreadsheet = { sheets, activeSheetIndex };
+  if (workbookInfo.namedRanges.size > 0) {
+    result.namedRanges = workbookInfo.namedRanges;
+  }
+  if (workbookInfo.fullCalcOnLoad) {
+    result.fullCalcOnLoad = true;
+  }
+  if (pivotCaches.size > 0) {
+    result.pivotCaches = pivotCaches;
+  }
+  return result;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function findEntry(zip: Record<string, Uint8Array>, path: string): Uint8Array | undefined {
+  if (zip[path]) return zip[path];
+  const lower = path.toLowerCase();
+  for (const key of Object.keys(zip)) {
+    if (key.toLowerCase() === lower) return zip[key];
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a relationship target path relative to a base directory.
+ * Handles absolute paths (leading /), relative paths with ../, and plain relative paths.
+ */
+function resolveRelTarget(target: string, baseDir: string): string {
+  if (target.startsWith("/")) return target.slice(1);
+  const baseParts = baseDir.split("/").filter(Boolean);
+  const targetParts = target.split("/");
+  const resolved = [...baseParts];
+  for (const part of targetParts) {
+    if (part === "..") {
+      resolved.pop();
+    } else if (part !== ".") {
+      resolved.push(part);
+    }
+  }
+  return resolved.join("/");
+}
+
+/**
+ * Parse a `_xlnm.Print_Titles` raw reference string into repeat row/col ranges.
+ * Example: `"Sheet1!$A:$B,Sheet1!$1:$2"` → `{ repeatRows: [1, 2], repeatCols: [1, 2] }`.
+ */
+function parsePrintTitlesRef(raw: string): PrintTitles | undefined {
+  const result: PrintTitles = {};
+  for (const segment of raw.split(",")) {
+    const afterBang = segment.includes("!") ? segment.split("!")[1] : segment;
+    if (!afterBang) continue;
+    const rowMatch = afterBang.match(/^\$(\d+):\$(\d+)$/);
+    if (rowMatch) {
+      result.repeatRows = [parseInt(rowMatch[1], 10), parseInt(rowMatch[2], 10)];
+      continue;
+    }
+    const colMatch = afterBang.match(/^\$([A-Z]+):\$([A-Z]+)$/i);
+    if (colMatch) {
+      result.repeatCols = [colLettersToNum(colMatch[1]), colLettersToNum(colMatch[2])];
+    }
+  }
+  return result.repeatRows || result.repeatCols ? result : undefined;
+}
+

package/src/excel_pattern_fills.ts

@@ -0,0 +1,64 @@
+/**
+ * Maps ExcelJS FillPattern types to CSS background-image strings.
+ * Uses repeating-linear-gradient for stripe/grid patterns
+ * and inline SVG data URIs for dot patterns.
+ */
+
+type PatternGenerator = (fg: string, bg: string) => string;
+
+const PATTERNS: Record<string, PatternGenerator> = {
+  darkVertical: (fg, bg) =>
+    `repeating-linear-gradient(90deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 4px)`,
+  darkHorizontal: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 4px)`,
+  darkDown: (fg, bg) =>
+    `repeating-linear-gradient(45deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 5px)`,
+  darkUp: (fg, bg) =>
+    `repeating-linear-gradient(-45deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 5px)`,
+  darkGrid: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, transparent 1px, transparent 4px), ` +
+    `repeating-linear-gradient(90deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 4px)`,
+  darkTrellis: (fg, bg) =>
+    `repeating-linear-gradient(45deg, ${fg} 0px, ${fg} 1px, transparent 1px, transparent 5px), ` +
+    `repeating-linear-gradient(-45deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 5px)`,
+
+  lightVertical: (fg, bg) =>
+    `repeating-linear-gradient(90deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+  lightHorizontal: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+  lightDown: (fg, bg) =>
+    `repeating-linear-gradient(45deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+  lightUp: (fg, bg) =>
+    `repeating-linear-gradient(-45deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+  lightGrid: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, transparent 1px, transparent 8px), ` +
+    `repeating-linear-gradient(90deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+  lightTrellis: (fg, bg) =>
+    `repeating-linear-gradient(45deg, ${fg} 0px, ${fg} 1px, transparent 1px, transparent 8px), ` +
+    `repeating-linear-gradient(-45deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+
+  mediumGray: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 3px)`,
+  darkGray: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 2px, ${bg} 2px, ${bg} 3px)`,
+  lightGray: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 5px)`,
+
+  // gray125 = 12.5% gray (every 8th pixel filled)
+  gray125: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 8px)`,
+
+  // gray0625 = 6.25% gray (every 16th pixel filled)
+  gray0625: (fg, bg) =>
+    `repeating-linear-gradient(0deg, ${fg} 0px, ${fg} 1px, ${bg} 1px, ${bg} 16px)`,
+};
+
+export function getPatternFillCSS(
+  pattern: string,
+  fgColor: string,
+  bgColor: string,
+): string | undefined {
+  const generator = PATTERNS[pattern];
+  if (!generator) return undefined;
+  return generator(fgColor, bgColor);
+}

package/src/excel_table_styles.ts

@@ -0,0 +1,160 @@
+// =============================================================================
+// Excel Table Styles
+// =============================================================================
+//
+// Built-in table style definitions for structured tables.
+// Excel has ~80 built-in styles (TableStyleLight1-21, TableStyleMedium1-28,
+// TableStyleDark1-11). Each style defines colors for header, total,
+// first/last column, and banded row/column stripes.
+// =============================================================================
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TableStyleDef {
+  /** Style name (e.g., "TableStyleMedium2"). */
+  name: string;
+  /** Header row background. */
+  headerBg: string;
+  /** Header row text color. */
+  headerFg: string;
+  /** Total row background. */
+  totalBg: string;
+  /** Total row text color. */
+  totalFg: string;
+  /** Odd row stripe background. */
+  stripe1Bg: string;
+  /** Even row stripe background (empty = transparent). */
+  stripe2Bg: string;
+  /** First column highlight. */
+  firstColBg?: string;
+  /** Last column highlight. */
+  lastColBg?: string;
+}
+
+// =============================================================================
+// Built-in styles
+// =============================================================================
+
+const LIGHT_STYLES: TableStyleDef[] = buildStyleSet("TableStyleLight", [
+  { header: "#000000", headerFg: "#FFFFFF", s1: "#D9E2F3", s2: "" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#D6E4F0", s2: "" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#FCE4D6", s2: "" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#EDEDED", s2: "" },
+  { header: "#FFC000", headerFg: "#FFFFFF", s1: "#FFF2CC", s2: "" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#DDEBF7", s2: "" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#E2EFDA", s2: "" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#D6E4F0", s2: "#EDF2F9" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#FCE4D6", s2: "#FDF0E8" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#EDEDED", s2: "#F6F6F6" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#FFF2CC", s2: "#FFF8E6" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#DDEBF7", s2: "#EDF4FB" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#E2EFDA", s2: "#F0F7EC" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#B4C6E7", s2: "#D6E4F0" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#F8CBAD", s2: "#FCE4D6" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#DBDBDB", s2: "#EDEDED" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#FFE699", s2: "#FFF2CC" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#BDD7EE", s2: "#DDEBF7" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#C6E0B4", s2: "#E2EFDA" },
+  { header: "#000000", headerFg: "#FFFFFF", s1: "#F2F2F2", s2: "" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#D6E4F0", s2: "" },
+]);
+
+const MEDIUM_STYLES: TableStyleDef[] = buildStyleSet("TableStyleMedium", [
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#D6E4F0", s2: "" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#FCE4D6", s2: "" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#EDEDED", s2: "" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#FFF2CC", s2: "" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#DDEBF7", s2: "" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#E2EFDA", s2: "" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#D6E4F0", s2: "#EDF2F9" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#FCE4D6", s2: "#FDF0E8" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#EDEDED", s2: "#F6F6F6" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#FFF2CC", s2: "#FFF8E6" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#DDEBF7", s2: "#EDF4FB" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#E2EFDA", s2: "#F0F7EC" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#B4C6E7", s2: "#D6E4F0" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#F8CBAD", s2: "#FCE4D6" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#DBDBDB", s2: "#EDEDED" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#FFE699", s2: "#FFF2CC" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#BDD7EE", s2: "#DDEBF7" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#C6E0B4", s2: "#E2EFDA" },
+  { header: "#000000", headerFg: "#FFFFFF", s1: "#D9D9D9", s2: "#F2F2F2" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#8FAADC", s2: "#B4C6E7" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#F4B183", s2: "#F8CBAD" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#C9C9C9", s2: "#DBDBDB" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#FFD966", s2: "#FFE699" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#9DC3E6", s2: "#BDD7EE" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#A9D18E", s2: "#C6E0B4" },
+  { header: "#264478", headerFg: "#FFFFFF", s1: "#D6DCE4", s2: "#E9ECF1" },
+  { header: "#9B57A0", headerFg: "#FFFFFF", s1: "#E8D5EA", s2: "#F3EAF4" },
+  { header: "#636363", headerFg: "#FFFFFF", s1: "#E0E0E0", s2: "#F0F0F0" },
+]);
+
+const DARK_STYLES: TableStyleDef[] = buildStyleSet("TableStyleDark", [
+  { header: "#000000", headerFg: "#FFFFFF", s1: "#737373", s2: "#595959" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#44546A", s2: "#2F3B52" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#C55A11", s2: "#843C0C" },
+  { header: "#A5A5A5", headerFg: "#FFFFFF", s1: "#7F7F7F", s2: "#595959" },
+  { header: "#FFC000", headerFg: "#000000", s1: "#BF8F00", s2: "#806000" },
+  { header: "#5B9BD5", headerFg: "#FFFFFF", s1: "#2E75B6", s2: "#1F4E79" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#548235", s2: "#375623" },
+  { header: "#000000", headerFg: "#FFFFFF", s1: "#404040", s2: "#262626" },
+  { header: "#4472C4", headerFg: "#FFFFFF", s1: "#305496", s2: "#203764" },
+  { header: "#ED7D31", headerFg: "#FFFFFF", s1: "#BF8F00", s2: "#806000" },
+  { header: "#70AD47", headerFg: "#FFFFFF", s1: "#375623", s2: "#1D3311" },
+]);
+
+// =============================================================================
+// Style lookup
+// =============================================================================
+
+const ALL_STYLES = new Map<string, TableStyleDef>();
+
+function initStyles(): void {
+  if (ALL_STYLES.size > 0) return;
+  for (const s of [...LIGHT_STYLES, ...MEDIUM_STYLES, ...DARK_STYLES]) {
+    ALL_STYLES.set(s.name, s);
+  }
+}
+
+/**
+ * Get a table style definition by name.
+ * Returns a default light style if not found.
+ */
+export function getTableStyle(name: string): TableStyleDef {
+  initStyles();
+  return ALL_STYLES.get(name) ?? LIGHT_STYLES[0];
+}
+
+/**
+ * Get all available table style names.
+ */
+export function getTableStyleNames(): string[] {
+  initStyles();
+  return Array.from(ALL_STYLES.keys());
+}
+
+// =============================================================================
+// Builder
+// =============================================================================
+
+interface StyleInput {
+  header: string;
+  headerFg: string;
+  s1: string;
+  s2: string;
+}
+
+function buildStyleSet(prefix: string, inputs: StyleInput[]): TableStyleDef[] {
+  return inputs.map((input, i) => ({
+    name: `${prefix}${i + 1}`,
+    headerBg: input.header,
+    headerFg: input.headerFg,
+    totalBg: input.header,
+    totalFg: input.headerFg,
+    stripe1Bg: input.s1,
+    stripe2Bg: input.s2,
+  }));
+}