@lotics/xlsx 0.1.0

package/src/ooxml_sheet.ts

@@ -0,0 +1,1271 @@
+import { XMLParser } from "fast-xml-parser";
+import type {
+  ParsedSheet,
+  ParsedRow,
+  ParsedCell,
+  ParsedColumn,
+  ParsedImage,
+  FreezePane,
+  MergedCellRange,
+  PageSetup,
+  HeaderFooter,
+} from "./types";
+import type { StyleResolver } from "./ooxml_styles";
+import type { SharedStringEntry } from "./ooxml_workbook";
+import type { ThemeData } from "./ooxml_color";
+import { parseColorElement, resolveColor, prefixHex } from "./ooxml_color";
+import { decodeXmlEntities } from "./xml_entities";
+import { formatCellValue, buildCellContent } from "./ooxml_cell_format";
+import { colLettersToNum } from "./excel_utils";
+import type {
+  ParsedConditionalFormat,
+  ParsedCfRule,
+  ParsedStyleRule,
+  CfThreshold,
+} from "./excel_cf_types";
+import type {
+  ParsedDataValidation,
+  ParsedSparklineGroup,
+  ParsedSparkline,
+  AutoFilterRange,
+  AutoFilterColumn,
+} from "./ooxml_chart_types";
+import { decodeUtf8 } from "./ooxml_zip";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const MAX_ROWS_PER_SHEET = 10_000;
+const MAX_IMAGES = 50;
+
+// fast-xml-parser returns a string for `<el>foo</el>` but an object
+// `{ "#text": "foo", "@_xml:space": "preserve", ... }` when the element
+// carries any attribute. Excel emits `xml:space="preserve"` whenever cell
+// or formula text contains leading/trailing whitespace or newlines, so
+// every site that reads element text must normalize both shapes.
+function extractElementText(node: unknown): string | undefined {
+  if (node === undefined || node === null) return undefined;
+  if (typeof node === "object") {
+    const text = (node as Record<string, unknown>)["#text"];
+    return text !== undefined ? String(text) : "";
+  }
+  return String(node);
+}
+
+// =============================================================================
+// XML parser
+// =============================================================================
+
+const xmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  processEntities: false,
+  isArray: (tagName) =>
+    tagName === "row" ||
+    tagName === "c" ||
+    tagName === "col" ||
+    tagName === "mergeCell" ||
+    tagName === "conditionalFormatting" ||
+    tagName === "cfRule" ||
+    tagName === "cfvo" ||
+    tagName === "color" ||
+    tagName === "hyperlink" ||
+    tagName === "Relationship" ||
+    tagName === "sheetView" ||
+    tagName === "xdr:twoCellAnchor" ||
+    tagName === "xdr:oneCellAnchor" ||
+    tagName === "dataValidation" ||
+    tagName === "filterColumn" ||
+    tagName === "filter" ||
+    tagName === "brk" ||
+    tagName === "ext",
+  // Preserve whitespace in cell values
+  trimValues: false,
+});
+
+const relsParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  processEntities: false,
+  isArray: (tagName) => tagName === "Relationship",
+});
+
+const drawingParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  processEntities: false,
+  isArray: (tagName) =>
+    tagName === "xdr:twoCellAnchor" ||
+    tagName === "xdr:oneCellAnchor" ||
+    tagName === "Relationship",
+});
+
+// =============================================================================
+// Main sheet parsing
+// =============================================================================
+
+export function parseSheet(
+  sheetXml: string,
+  sheetRelsXml: string | undefined,
+  styles: StyleResolver,
+  sharedStrings: SharedStringEntry[],
+  theme: ThemeData,
+  indexedColors: string[],
+  zipEntries: Record<string, Uint8Array>,
+  date1904: boolean,
+): ParsedSheet {
+  const doc = xmlParser.parse(sheetXml);
+  const worksheet = doc?.["worksheet"];
+  if (!worksheet) return emptySheet("Sheet");
+
+  // Parse relationships for this sheet (hyperlinks, comments, drawings)
+  const rels = sheetRelsXml ? parseSheetRels(sheetRelsXml) : new Map<string, { target: string; type: string }>();
+
+  // Sheet format defaults
+  const sheetFormatPr = worksheet["sheetFormatPr"] as Record<string, string> | undefined;
+  const defaultRowHeight = sheetFormatPr?.["@_defaultRowHeight"]
+    ? parseFloat(sheetFormatPr["@_defaultRowHeight"])
+    : 15;
+  const defaultColWidth = sheetFormatPr?.["@_defaultColWidth"]
+    ? parseFloat(sheetFormatPr["@_defaultColWidth"])
+    : 8;
+
+  // Sheet views (freeze panes, grid lines)
+  const { freezePane, showGridLines } = parseSheetViews(worksheet);
+
+  // Column definitions
+  const { columns: parsedCols, colHidden, colOutlineLevels } = parseCols(worksheet, defaultColWidth);
+
+  // Hyperlinks map (cell ref → URL)
+  const hyperlinkMap = parseHyperlinks(worksheet, rels);
+
+  // Parse sheet data (rows + cells)
+  const {
+    rows,
+    totalRowCount,
+    truncated,
+    maxCol,
+    maxContentWidth,
+    rowOutlineLevels,
+  } = parseSheetData(worksheet, styles, sharedStrings, hyperlinkMap, defaultRowHeight, date1904);
+
+  // Build final columns from parsed col defs and data bounds
+  const colCount = Math.max(parsedCols.length > 0 ? parsedCols[parsedCols.length - 1].max : 0, maxCol);
+  const columns = buildColumns(parsedCols, colHidden, maxContentWidth, colCount, defaultColWidth);
+
+  // Merged cells
+  const mergedCells = parseMergedCells(worksheet);
+
+  // Conditional formatting
+  const conditionalFormats = parseConditionalFormats(worksheet, theme, indexedColors);
+
+  // Images
+  const images = parseImages(rels, zipEntries);
+
+  // Data validations
+  const dataValidations = parseDataValidations(worksheet);
+
+  // Sparklines (from sheet extension list)
+  const sparklineGroups = parseSparklineGroups(worksheet);
+
+  // Auto-filter
+  const autoFilter = parseAutoFilter(worksheet);
+
+  const result: ParsedSheet = {
+    name: "",
+    columns,
+    rows,
+    mergedCells,
+    totalRowCount,
+    truncated,
+    defaultRowHeight,
+    defaultColWidth,
+    showGridLines,
+    freezePane,
+    conditionalFormats,
+    images,
+    rowOutlineLevels,
+    colOutlineLevels,
+  };
+  if (dataValidations.length > 0) result.dataValidations = dataValidations;
+  if (sparklineGroups.length > 0) result.sparklineGroups = sparklineGroups;
+  if (autoFilter) result.autoFilter = autoFilter;
+
+  // Page breaks
+  const { rowPageBreaks, colPageBreaks } = parsePageBreaks(worksheet);
+  if (rowPageBreaks.length > 0) result.rowPageBreaks = rowPageBreaks;
+  if (colPageBreaks.length > 0) result.colPageBreaks = colPageBreaks;
+
+  // Page setup + margins (only emitted when diverging from defaults)
+  const pageSetup = parsePageSetupElement(worksheet);
+  if (pageSetup) result.pageSetup = pageSetup;
+
+  // Header/footer
+  const headerFooter = parseHeaderFooterElement(worksheet);
+  if (headerFooter) result.headerFooter = headerFooter;
+
+  return result;
+}
+
+function parsePageSetupElement(worksheet: Record<string, unknown>): PageSetup | undefined {
+  const ps = worksheet["pageSetup"] as Record<string, string> | undefined;
+  const pm = worksheet["pageMargins"] as Record<string, string> | undefined;
+
+  const out: PageSetup = {};
+  if (ps) {
+    const orient = ps["@_orientation"];
+    if (orient === "portrait" || orient === "landscape") out.orientation = orient;
+    if (ps["@_paperSize"]) out.paperSize = parseInt(ps["@_paperSize"], 10);
+    if (ps["@_fitToWidth"] !== undefined) out.fitToWidth = parseInt(ps["@_fitToWidth"], 10);
+    if (ps["@_fitToHeight"] !== undefined) out.fitToHeight = parseInt(ps["@_fitToHeight"], 10);
+    if (ps["@_scale"]) out.scale = parseInt(ps["@_scale"], 10);
+  }
+  if (pm) {
+    const margins: NonNullable<PageSetup["margins"]> = {};
+    const fields: Array<["left" | "right" | "top" | "bottom" | "header" | "footer", number]> = [
+      ["left", 0.7],
+      ["right", 0.7],
+      ["top", 0.75],
+      ["bottom", 0.75],
+      ["header", 0.3],
+      ["footer", 0.3],
+    ];
+    let anyNonDefault = false;
+    for (const [key, def] of fields) {
+      const raw = pm[`@_${key}`];
+      if (raw === undefined) continue;
+      const val = parseFloat(raw);
+      if (!Number.isNaN(val) && Math.abs(val - def) > 1e-6) {
+        margins[key] = val;
+        anyNonDefault = true;
+      }
+    }
+    if (anyNonDefault) out.margins = margins;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function parseHeaderFooterElement(worksheet: Record<string, unknown>): HeaderFooter | undefined {
+  const hf = worksheet["headerFooter"] as Record<string, unknown> | undefined;
+  if (!hf) return undefined;
+  const out: HeaderFooter = {};
+  const readText = (key: string): string | undefined => {
+    const val = hf[key];
+    let raw: string | undefined;
+    if (typeof val === "string") raw = val;
+    else if (val && typeof val === "object" && "#text" in val && typeof (val as { "#text": unknown })["#text"] === "string") {
+      raw = (val as { "#text": string })["#text"];
+    }
+    return raw !== undefined ? decodeXmlEntities(raw) : undefined;
+  };
+  const oh = readText("oddHeader");
+  const of = readText("oddFooter");
+  const eh = readText("evenHeader");
+  const ef = readText("evenFooter");
+  const fh = readText("firstHeader");
+  const ff = readText("firstFooter");
+  if (oh !== undefined) out.oddHeader = oh;
+  if (of !== undefined) out.oddFooter = of;
+  if (eh !== undefined) out.evenHeader = eh;
+  if (ef !== undefined) out.evenFooter = ef;
+  if (fh !== undefined) out.firstHeader = fh;
+  if (ff !== undefined) out.firstFooter = ff;
+  if (hf["@_differentOddEven"] === "1") out.differentOddEven = true;
+  if (hf["@_differentFirst"] === "1") out.differentFirst = true;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+// =============================================================================
+// Sheet relationships
+// =============================================================================
+
+function parseSheetRels(relsXml: string): Map<string, { target: string; type: string }> {
+  const doc = relsParser.parse(relsXml);
+  const relationships = doc?.["Relationships"];
+  if (!relationships) return new Map();
+
+  const relArr = relationships["Relationship"] as Array<Record<string, string>> | undefined;
+  if (!relArr) return new Map();
+
+  const map = new Map<string, { target: string; type: string }>();
+  for (const rel of relArr) {
+    const id = rel["@_Id"];
+    const target = rel["@_Target"];
+    const type = rel["@_Type"] ?? "";
+    if (id && target) {
+      map.set(id, { target, type });
+    }
+  }
+  return map;
+}
+
+// =============================================================================
+// Sheet views
+// =============================================================================
+
+function parseSheetViews(worksheet: Record<string, unknown>): {
+  freezePane?: FreezePane;
+  showGridLines: boolean;
+} {
+  const views = worksheet["sheetViews"] as Record<string, unknown> | undefined;
+  if (!views) return { showGridLines: true };
+
+  const viewArr = views["sheetView"];
+  const firstView = Array.isArray(viewArr) ? viewArr[0] : viewArr;
+  if (!firstView || typeof firstView !== "object") return { showGridLines: true };
+
+  const view = firstView as Record<string, unknown>;
+  const showGridLines = view["@_showGridLines"] !== "0";
+
+  let freezePane: FreezePane | undefined;
+  const pane = view["pane"] as Record<string, string> | undefined;
+  if (pane?.["@_state"] === "frozen") {
+    const frozenCols = parseInt(pane["@_xSplit"] ?? "0", 10);
+    const frozenRows = parseInt(pane["@_ySplit"] ?? "0", 10);
+    if (frozenRows > 0 || frozenCols > 0) {
+      freezePane = { frozenRows, frozenCols };
+    }
+  }
+
+  return { freezePane, showGridLines };
+}
+
+// =============================================================================
+// Columns
+// =============================================================================
+
+interface ColDef {
+  min: number;
+  max: number;
+  width: number;
+  hidden: boolean;
+  outlineLevel: number;
+}
+
+function parseCols(
+  worksheet: Record<string, unknown>,
+  defaultColWidth: number,
+): {
+  columns: ColDef[];
+  colHidden: Set<number>;
+  colOutlineLevels: Map<number, number>;
+} {
+  const colsEl = worksheet["cols"] as Record<string, unknown> | undefined;
+  const colHidden = new Set<number>();
+  const colOutlineLevels = new Map<number, number>();
+
+  if (!colsEl) return { columns: [], colHidden, colOutlineLevels };
+
+  const colArr = colsEl["col"] as Array<Record<string, string>> | undefined;
+  if (!colArr) return { columns: [], colHidden, colOutlineLevels };
+
+  const columns: ColDef[] = [];
+  for (const col of colArr) {
+    const min = parseInt(col["@_min"] ?? "1", 10);
+    const max = parseInt(col["@_max"] ?? "1", 10);
+    const width = col["@_width"] ? parseFloat(col["@_width"]) : defaultColWidth;
+    const hidden = col["@_hidden"] === "1" || col["@_hidden"] === "true";
+    const outlineLevel = parseInt(col["@_outlineLevel"] ?? "0", 10);
+
+    columns.push({ min, max, width, hidden, outlineLevel });
+
+    // Expand into individual column entries
+    for (let c = min; c <= max; c++) {
+      if (hidden) colHidden.add(c);
+      if (outlineLevel > 0) colOutlineLevels.set(c, outlineLevel);
+    }
+  }
+
+  return { columns, colHidden, colOutlineLevels };
+}
+
+function buildColumns(
+  colDefs: ColDef[],
+  colHidden: Set<number>,
+  maxContentWidth: Map<number, number>,
+  colCount: number,
+  _defaultColWidth: number,
+): ParsedColumn[] {
+  // Build a map of column index → explicit width from col definitions
+  const explicitWidth = new Map<number, number>();
+  for (const def of colDefs) {
+    for (let c = def.min; c <= def.max; c++) {
+      explicitWidth.set(c, def.width);
+    }
+  }
+
+  const columns: ParsedColumn[] = [];
+  for (let c = 1; c <= colCount; c++) {
+    const excelWidth = explicitWidth.get(c);
+    const contentChars = maxContentWidth.get(c) ?? 0;
+    const hidden = colHidden.has(c);
+
+    let width: number;
+    if (excelWidth && excelWidth > 8) {
+      width = excelWidth;
+    } else {
+      width = Math.max(8, Math.min(contentChars + 2, 40));
+    }
+
+    columns.push({ index: c, width, hidden });
+  }
+
+  return columns;
+}
+
+// =============================================================================
+// Sheet data (rows + cells)
+// =============================================================================
+
+function parseSheetData(
+  worksheet: Record<string, unknown>,
+  styles: StyleResolver,
+  sharedStrings: SharedStringEntry[],
+  hyperlinkMap: Map<string, string>,
+  defaultRowHeight: number,
+  date1904: boolean,
+): {
+  rows: ParsedRow[];
+  totalRowCount: number;
+  truncated: boolean;
+  maxCol: number;
+  maxContentWidth: Map<number, number>;
+  rowOutlineLevels: Map<number, number>;
+} {
+  const sheetData = worksheet["sheetData"] as Record<string, unknown> | undefined;
+  if (!sheetData) {
+    return {
+      rows: [],
+      totalRowCount: 0,
+      truncated: false,
+      maxCol: 0,
+      maxContentWidth: new Map(),
+      rowOutlineLevels: new Map(),
+    };
+  }
+
+  const rowArr = sheetData["row"] as Array<Record<string, unknown>> | undefined;
+  if (!rowArr) {
+    return {
+      rows: [],
+      totalRowCount: 0,
+      truncated: false,
+      maxCol: 0,
+      maxContentWidth: new Map(),
+      rowOutlineLevels: new Map(),
+    };
+  }
+
+  const totalRowCount = rowArr.length > 0
+    ? parseInt((rowArr[rowArr.length - 1]["@_r"] as string) ?? String(rowArr.length), 10)
+    : 0;
+
+  const rows: ParsedRow[] = [];
+  let maxCol = 0;
+  const maxContentWidth = new Map<number, number>();
+  const rowOutlineLevels = new Map<number, number>();
+  let rowCount = 0;
+
+  for (const rowEl of rowArr) {
+    const rowIndex = parseInt((rowEl["@_r"] as string) ?? "0", 10);
+    if (rowIndex === 0) continue;
+
+    // Track outline levels even if we skip the row
+    const outlineLevel = parseInt((rowEl["@_outlineLevel"] as string) ?? "0", 10);
+    if (outlineLevel > 0) {
+      rowOutlineLevels.set(rowIndex, outlineLevel);
+    }
+
+    // Skip hidden rows
+    if (rowEl["@_hidden"] === "1" || rowEl["@_hidden"] === "true") continue;
+
+    // Truncation check
+    rowCount++;
+    if (rowCount > MAX_ROWS_PER_SHEET) continue;
+
+    const height = rowEl["@_ht"]
+      ? parseFloat(rowEl["@_ht"] as string)
+      : defaultRowHeight;
+
+    const cellArr = rowEl["c"] as Array<Record<string, unknown>> | undefined;
+    const cells: ParsedCell[] = [];
+
+    if (cellArr) {
+      for (const cellEl of cellArr) {
+        const parsed = parseCell(cellEl, styles, sharedStrings, hyperlinkMap, date1904);
+        if (parsed) {
+          cells.push(parsed);
+          if (parsed.column > maxCol) maxCol = parsed.column;
+
+          // Track content width (sample first 200 rows)
+          if (rowCount <= 200) {
+            const currentMax = maxContentWidth.get(parsed.column) ?? 0;
+            if (parsed.value.length > currentMax) {
+              maxContentWidth.set(parsed.column, parsed.value.length);
+            }
+          }
+        }
+      }
+    }
+
+    rows.push({
+      index: rowIndex,
+      height,
+      cells,
+      hidden: false,
+    });
+  }
+
+  return {
+    rows,
+    totalRowCount,
+    truncated: rowCount > MAX_ROWS_PER_SHEET,
+    maxCol,
+    maxContentWidth,
+    rowOutlineLevels,
+  };
+}
+
+// =============================================================================
+// Cell parsing
+// =============================================================================
+
+/** Parse cell reference like "A1" into { col: 1, ref: "A1" } */
+function parseCellRef(ref: string): { col: number; row: number } | undefined {
+  const match = ref.match(/^([A-Z]+)(\d+)$/);
+  if (!match) return undefined;
+  return { col: colLettersToNum(match[1]), row: parseInt(match[2], 10) };
+}
+
+function parseCell(
+  cellEl: Record<string, unknown>,
+  styles: StyleResolver,
+  sharedStrings: SharedStringEntry[],
+  hyperlinkMap: Map<string, string>,
+  date1904: boolean,
+): ParsedCell | undefined {
+  const ref = cellEl["@_r"] as string | undefined;
+  if (!ref) return undefined;
+
+  const cellRef = parseCellRef(ref);
+  if (!cellRef) return undefined;
+
+  const type = (cellEl["@_t"] as string) ?? "";
+  const styleIndex = parseInt((cellEl["@_s"] as string) ?? "0", 10);
+
+  // Raw value
+  const rawValue = extractElementText(cellEl["v"]);
+
+  // Inline string: <c t="inlineStr"><is><t>text</t></is></c>
+  let inlineStr: string | undefined;
+  if (type === "inlineStr") {
+    const is = cellEl["is"] as Record<string, unknown> | undefined;
+    if (is) {
+      const raw = extractElementText(is["t"]);
+      inlineStr = raw !== undefined ? decodeXmlEntities(raw) : undefined;
+    }
+  }
+
+  // Resolve shared string
+  const ssIndex = type === "s" && rawValue !== undefined ? parseInt(rawValue, 10) : -1;
+  const sharedString = ssIndex >= 0 && ssIndex < sharedStrings.length ? sharedStrings[ssIndex] : undefined;
+
+  // Number format
+  const numFmt = styles.getNumFmt(styleIndex);
+
+  // Format display value
+  const effectiveValue = type === "inlineStr" ? (inlineStr ?? "") : rawValue;
+  const displayValue = formatCellValue(effectiveValue, type, numFmt, sharedString, date1904);
+
+  // Build content
+  const hyperlink = hyperlinkMap.get(ref);
+  const content = buildCellContent(displayValue, sharedString, hyperlink);
+
+  // Style
+  const style = styles.resolveStyle(styleIndex);
+
+  // Formula (detect array formulas)
+  const fEl = cellEl["f"];
+  let formula: string | undefined;
+  let isArrayFormula = false;
+  let arrayRange: string | undefined;
+  if (fEl !== undefined && fEl !== null) {
+    if (typeof fEl === "object") {
+      const fObj = fEl as Record<string, string>;
+      formula = fObj["#text"];
+      if (fObj["@_t"] === "array") {
+        isArrayFormula = true;
+        arrayRange = fObj["@_ref"];
+        // Strip {} braces from array formula text
+        if (formula?.startsWith("{") && formula.endsWith("}")) {
+          formula = formula.slice(1, -1);
+        }
+      }
+    } else {
+      formula = String(fEl);
+    }
+    if (formula !== undefined) formula = decodeXmlEntities(formula);
+  }
+
+  // Compute typed value for lossless round-trip export
+  let typedValue: string | number | boolean | null;
+  let cellRawValue: number | undefined;
+  if (type === "s") {
+    typedValue = sharedString?.text ?? "";
+  } else if (type === "b") {
+    typedValue = rawValue === "1";
+  } else if (type === "e") {
+    typedValue = rawValue ?? null;
+  } else if (type === "str" || type === "inlineStr") {
+    typedValue = effectiveValue ?? "";
+  } else if (rawValue !== undefined) {
+    const num = parseFloat(rawValue);
+    if (!isNaN(num)) {
+      typedValue = num;
+      cellRawValue = num;
+    } else {
+      typedValue = rawValue;
+    }
+  } else {
+    typedValue = null;
+  }
+
+  const cell: ParsedCell = { column: cellRef.col, value: displayValue, content, style };
+  cell.typedValue = typedValue;
+  cell.rawValue = cellRawValue;
+  cell.originalXfIndex = styleIndex;
+  if (numFmt !== "General") cell.numFmtCode = numFmt;
+  if (type === "e" && rawValue) cell.error = rawValue;
+  if (formula) cell.formula = formula;
+  if (isArrayFormula) cell.isArrayFormula = true;
+  if (arrayRange) cell.arrayRange = arrayRange;
+
+  return cell;
+}
+
+// =============================================================================
+// Merged cells
+// =============================================================================
+
+function parseMergedCells(worksheet: Record<string, unknown>): MergedCellRange[] {
+  const mcEl = worksheet["mergeCells"] as Record<string, unknown> | undefined;
+  if (!mcEl) return [];
+
+  const mcArr = mcEl["mergeCell"] as Array<Record<string, string>> | undefined;
+  if (!mcArr) return [];
+
+  const ranges: MergedCellRange[] = [];
+  for (const mc of mcArr) {
+    const ref = mc["@_ref"];
+    if (!ref) continue;
+
+    const match = ref.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/);
+    if (!match) continue;
+
+    ranges.push({
+      startCol: colLettersToNum(match[1]),
+      startRow: parseInt(match[2], 10),
+      endCol: colLettersToNum(match[3]),
+      endRow: parseInt(match[4], 10),
+    });
+  }
+
+  return ranges;
+}
+
+// =============================================================================
+// Hyperlinks
+// =============================================================================
+
+function parseHyperlinks(
+  worksheet: Record<string, unknown>,
+  rels: Map<string, { target: string; type: string }>,
+): Map<string, string> {
+  const map = new Map<string, string>();
+  const hlEl = worksheet["hyperlinks"] as Record<string, unknown> | undefined;
+  if (!hlEl) return map;
+
+  const hlArr = hlEl["hyperlink"] as Array<Record<string, string>> | undefined;
+  if (!hlArr) return map;
+
+  for (const hl of hlArr) {
+    const ref = hl["@_ref"];
+    if (!ref) continue;
+
+    // External hyperlink via relationship
+    const rId = hl["@_r:id"];
+    if (rId) {
+      const rel = rels.get(rId);
+      if (rel) {
+        map.set(ref, rel.target);
+        continue;
+      }
+    }
+
+    // Internal location
+    const location = hl["@_location"];
+    if (location) {
+      map.set(ref, `#${location}`);
+    }
+  }
+
+  return map;
+}
+
+// =============================================================================
+// Images
+// =============================================================================
+
+function parseImages(
+  rels: Map<string, { target: string; type: string }>,
+  zipEntries: Record<string, Uint8Array>,
+): ParsedImage[] {
+  const images: ParsedImage[] = [];
+
+  // Find drawing relationship
+  for (const [, rel] of rels) {
+    if (!rel.type.includes("drawing") || rel.type.includes("drawingML")) continue;
+
+    const drawingPath = resolveRelPath(rel.target);
+    const drawingEntry = findZipEntry(zipEntries, drawingPath);
+    if (!drawingEntry) continue;
+
+    const drawingXml = decodeUtf8(drawingEntry);
+    const doc = drawingParser.parse(drawingXml);
+    const wsDr = doc?.["xdr:wsDr"];
+    if (!wsDr) continue;
+
+    // Parse drawing relationships
+    const drawingRelsPath = drawingPath.replace(/([^/]+)$/, "_rels/$1.rels");
+    const drawingRelsEntry = findZipEntry(zipEntries, drawingRelsPath);
+    const drawingRels = drawingRelsEntry
+      ? parseDrawingRels(decodeUtf8(drawingRelsEntry))
+      : new Map<string, string>();
+
+    // Two-cell anchors
+    const anchors = wsDr["xdr:twoCellAnchor"] as Array<Record<string, unknown>> | undefined;
+    if (anchors) {
+      for (const anchor of anchors) {
+        if (images.length >= MAX_IMAGES) break;
+        const image = extractImageFromAnchor(anchor, drawingRels, zipEntries, drawingPath);
+        if (image) images.push(image);
+      }
+    }
+  }
+
+  return images;
+}
+
+function parseDrawingRels(relsXml: string): Map<string, string> {
+  const doc = relsParser.parse(relsXml);
+  const relationships = doc?.["Relationships"];
+  if (!relationships) return new Map();
+
+  const relArr = relationships["Relationship"] as Array<Record<string, string>> | undefined;
+  if (!relArr) return new Map();
+
+  const map = new Map<string, string>();
+  for (const rel of relArr) {
+    const id = rel["@_Id"];
+    const target = rel["@_Target"];
+    if (id && target) {
+      map.set(id, target);
+    }
+  }
+  return map;
+}
+
+function extractImageFromAnchor(
+  anchor: Record<string, unknown>,
+  drawingRels: Map<string, string>,
+  zipEntries: Record<string, Uint8Array>,
+  drawingPath: string,
+): ParsedImage | undefined {
+  // Get position
+  const from = anchor["xdr:from"] as Record<string, string> | undefined;
+  const to = anchor["xdr:to"] as Record<string, string> | undefined;
+  if (!from || !to) return undefined;
+
+  const tl = {
+    row: parseInt(from["xdr:row"] ?? "0", 10),
+    col: parseInt(from["xdr:col"] ?? "0", 10),
+  };
+  const br = {
+    row: parseInt(to["xdr:row"] ?? "0", 10) + 1,
+    col: parseInt(to["xdr:col"] ?? "0", 10) + 1,
+  };
+
+  // Find the image reference
+  const pic = anchor["xdr:pic"] as Record<string, unknown> | undefined;
+  if (!pic) return undefined;
+
+  const blipFill = pic["xdr:blipFill"] as Record<string, unknown> | undefined;
+  if (!blipFill) return undefined;
+
+  const blip = blipFill["a:blip"] as Record<string, string> | undefined;
+  if (!blip) return undefined;
+
+  const embedId = blip["@_r:embed"];
+  if (!embedId) return undefined;
+
+  const imageRelTarget = drawingRels.get(embedId);
+  if (!imageRelTarget) return undefined;
+
+  // Resolve image path relative to drawing
+  const drawingDir = drawingPath.substring(0, drawingPath.lastIndexOf("/") + 1);
+  const imagePath = resolveRelativePath(drawingDir, imageRelTarget);
+  const imageEntry = findZipEntry(zipEntries, imagePath);
+  if (!imageEntry) return undefined;
+
+  // Build data URL
+  const ext = imagePath.split(".").pop()?.toLowerCase() ?? "png";
+  const mimeType = ext === "jpeg" || ext === "jpg" ? "image/jpeg" : ext === "gif" ? "image/gif" : "image/png";
+  const base64 = uint8ToBase64(imageEntry);
+  const dataUrl = `data:${mimeType};base64,${base64}`;
+
+  return { dataUrl, tl, br };
+}
+
+// =============================================================================
+// Conditional formatting
+// =============================================================================
+
+function parseConditionalFormats(
+  worksheet: Record<string, unknown>,
+  theme: ThemeData,
+  indexedColors: string[],
+): ParsedConditionalFormat[] {
+  const cfArr = worksheet["conditionalFormatting"] as Array<Record<string, unknown>> | undefined;
+  if (!cfArr) return [];
+
+  const result: ParsedConditionalFormat[] = [];
+
+  for (const cf of cfArr) {
+    const ref = cf["@_sqref"] as string;
+    if (!ref) continue;
+
+    const ruleArr = cf["cfRule"] as Array<Record<string, unknown>> | undefined;
+    if (!ruleArr) continue;
+
+    const rules: ParsedCfRule[] = [];
+    for (const ruleEl of ruleArr) {
+      const parsed = parseCfRule(ruleEl, theme, indexedColors);
+      if (parsed) rules.push(parsed);
+    }
+
+    if (rules.length > 0) {
+      result.push({ ref, rules });
+    }
+  }
+
+  return result;
+}
+
+function parseCfRule(
+  el: Record<string, unknown>,
+  theme: ThemeData,
+  indexedColors: string[],
+): ParsedCfRule | undefined {
+  const type = el["@_type"] as string;
+  const priority = parseInt((el["@_priority"] as string) ?? "1", 10);
+  const stopIfTrue = (el["@_stopIfTrue"] as string) === "1";
+
+  switch (type) {
+    case "colorScale": {
+      const colorScale = el["colorScale"] as Record<string, unknown> | undefined;
+      if (!colorScale) return undefined;
+      const colorArr = colorScale["color"] as Array<Record<string, string>> | undefined;
+      if (!colorArr || colorArr.length < 2) return undefined;
+
+      const colors = colorArr.map((c) => {
+        const ooxmlColor = parseColorElement(c);
+        const hex = resolveColor(ooxmlColor, theme, indexedColors, "fill");
+        return hex ? prefixHex(hex) : "#000000";
+      });
+
+      return { ruleType: "colorScale", priority, stopIfTrue, colors };
+    }
+
+    case "dataBar": {
+      const dataBar = el["dataBar"] as Record<string, unknown> | undefined;
+      let color = "#638EC6";
+      if (dataBar) {
+        const colorArr = dataBar["color"] as Array<Record<string, string>> | undefined;
+        const colorEl = colorArr?.[0];
+        if (colorEl) {
+          const ooxmlColor = parseColorElement(colorEl);
+          const hex = resolveColor(ooxmlColor, theme, indexedColors, "fill");
+          if (hex) color = prefixHex(hex);
+        }
+      }
+
+      return {
+        ruleType: "dataBar",
+        priority,
+        stopIfTrue,
+        color,
+        minLength: parseInt((dataBar?.["@_minLength"] as string) ?? "10", 10),
+        maxLength: parseInt((dataBar?.["@_maxLength"] as string) ?? "90", 10),
+        showValue: (dataBar?.["@_showValue"] as string) !== "0",
+      };
+    }
+
+    case "iconSet": {
+      const iconSet = el["iconSet"] as Record<string, unknown> | undefined;
+      const cfvoArr = iconSet?.["cfvo"] as Array<Record<string, string>> | undefined;
+
+      return {
+        ruleType: "iconSet",
+        priority,
+        stopIfTrue,
+        iconSet: (iconSet?.["@_iconSet"] as string) ?? "3TrafficLights1",
+        thresholds: (cfvoArr ?? []).map((cfvo): CfThreshold => ({
+          type: cfvo["@_type"] as CfThreshold["type"],
+          value: cfvo["@_val"] !== undefined ? parseFloat(cfvo["@_val"]) : undefined,
+        })),
+        showValue: (iconSet?.["@_showValue"] as string) !== "0",
+        reverse: (iconSet?.["@_reverse"] as string) === "1",
+      };
+    }
+
+    case "cellIs":
+    case "containsText":
+    case "top10":
+    case "aboveAverage":
+    case "timePeriod":
+    case "expression": {
+      return parseStyleCfRule(el, type, priority, stopIfTrue, theme, indexedColors);
+    }
+
+    default:
+      return undefined;
+  }
+}
+
+function parseStyleCfRule(
+  el: Record<string, unknown>,
+  type: "cellIs" | "containsText" | "top10" | "aboveAverage" | "timePeriod" | "expression",
+  priority: number,
+  stopIfTrue: boolean,
+  _theme: ThemeData,
+  _indexedColors: string[],
+): ParsedStyleRule {
+  const rule: ParsedStyleRule = { ruleType: "style", priority, stopIfTrue, type };
+
+  if (type === "cellIs") {
+    rule.operator = el["@_operator"] as string | undefined;
+    const formula = el["formula"];
+    if (formula !== undefined) {
+      const arr = Array.isArray(formula) ? formula : [formula];
+      rule.formulae = arr
+        .map(extractElementText)
+        .filter((s): s is string => s !== undefined);
+    }
+  } else if (type === "containsText") {
+    rule.operator = el["@_operator"] as string | undefined;
+    rule.text = el["@_text"] as string | undefined;
+  } else if (type === "top10") {
+    rule.rank = el["@_rank"] !== undefined ? parseInt(el["@_rank"] as string, 10) : undefined;
+    rule.percent = el["@_percent"] === "1";
+    rule.bottom = el["@_bottom"] === "1";
+  } else if (type === "aboveAverage") {
+    rule.aboveAverage = el["@_aboveAverage"] !== "0";
+  } else if (type === "timePeriod") {
+    rule.timePeriod = el["@_timePeriod"] as string | undefined;
+  } else if (type === "expression") {
+    const formula = el["formula"];
+    if (formula !== undefined) {
+      const arr = Array.isArray(formula) ? formula : [formula];
+      rule.formulae = arr
+        .map(extractElementText)
+        .filter((s): s is string => s !== undefined);
+    }
+  }
+
+  return rule;
+}
+
+// =============================================================================
+// Data validations
+// =============================================================================
+
+function parseDataValidations(worksheet: Record<string, unknown>): ParsedDataValidation[] {
+  const dvEl = worksheet["dataValidations"] as Record<string, unknown> | undefined;
+  if (!dvEl) return [];
+
+  const dvArr = dvEl["dataValidation"] as Array<Record<string, string>> | undefined;
+  if (!dvArr) return [];
+
+  const result: ParsedDataValidation[] = [];
+  for (const dv of dvArr) {
+    const ref = dv["@_sqref"];
+    if (!ref) continue;
+
+    const typeStr = dv["@_type"] ?? "none";
+    const type = (["list", "whole", "decimal", "date", "time", "textLength", "custom", "none"].includes(typeStr)
+      ? typeStr
+      : "none") as ParsedDataValidation["type"];
+
+    const operatorStr = dv["@_operator"];
+    const validOperators = ["between", "notBetween", "equal", "notEqual", "greaterThan", "lessThan", "greaterThanOrEqual", "lessThanOrEqual"];
+    const operator = operatorStr && validOperators.includes(operatorStr)
+      ? operatorStr as ParsedDataValidation["operator"]
+      : undefined;
+
+    const formula1Text = extractElementText(dv["formula1"]);
+    const formula1 = formula1Text !== undefined ? decodeXmlEntities(formula1Text) : undefined;
+    const formula2Text = extractElementText(dv["formula2"]);
+    const formula2 = formula2Text !== undefined ? decodeXmlEntities(formula2Text) : undefined;
+    const decodeAttr = (v: string | undefined) => v !== undefined ? decodeXmlEntities(v) : undefined;
+
+    result.push({
+      ref,
+      type,
+      operator,
+      formula1,
+      formula2,
+      showDropdown: dv["@_showDropDown"] !== "1",
+      errorStyle: dv["@_errorStyle"] as ParsedDataValidation["errorStyle"],
+      errorTitle: decodeAttr(dv["@_errorTitle"]),
+      errorMessage: decodeAttr(dv["@_error"]),
+      promptTitle: decodeAttr(dv["@_promptTitle"]),
+      promptMessage: decodeAttr(dv["@_prompt"]),
+    });
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Sparklines (sheet extension list)
+// =============================================================================
+
+function parseSparklineGroups(worksheet: Record<string, unknown>): ParsedSparklineGroup[] {
+  const extLst = worksheet["extLst"] as Record<string, unknown> | undefined;
+  if (!extLst) return [];
+
+  const extArr = extLst["ext"] as Array<Record<string, unknown>> | undefined;
+  if (!extArr) return [];
+
+  const result: ParsedSparklineGroup[] = [];
+
+  for (const ext of extArr) {
+    // Look for sparklineGroups in any x14 namespace variant
+    const sparkGroups = ext["x14:sparklineGroups"]
+      ?? ext["sparklineGroups"] as Record<string, unknown> | undefined;
+    if (!sparkGroups || typeof sparkGroups !== "object") continue;
+
+    const groupArr = ensureSparkArray(
+      (sparkGroups as Record<string, unknown>)["x14:sparklineGroup"]
+      ?? (sparkGroups as Record<string, unknown>)["sparklineGroup"],
+    );
+
+    for (const group of groupArr) {
+      if (!group || typeof group !== "object") continue;
+      const g = group as Record<string, unknown>;
+      const typeAttr = (g["@_type"] as string) ?? "line";
+      const type = (["line", "column", "stacked"].includes(typeAttr) ? typeAttr : "line") as ParsedSparklineGroup["type"];
+      const color = extractSparklineColor(g);
+
+      const sparklineContainer = g["x14:sparklines"] ?? g["sparklines"];
+      if (!sparklineContainer || typeof sparklineContainer !== "object") continue;
+
+      const sparkArr = ensureSparkArray(
+        (sparklineContainer as Record<string, unknown>)["x14:sparkline"]
+        ?? (sparklineContainer as Record<string, unknown>)["sparkline"],
+      );
+
+      const sparklines: ParsedSparkline[] = [];
+      for (const sp of sparkArr) {
+        if (!sp || typeof sp !== "object") continue;
+        const s = sp as Record<string, unknown>;
+        const dataRangeEl = s["xm:f"] ?? s["f"];
+        const locationEl = s["xm:sqref"] ?? s["sqref"];
+        const dataRange = extractElementText(dataRangeEl) ?? "";
+        const locationRef = extractElementText(locationEl) ?? "";
+        if (dataRange && locationRef) {
+          sparklines.push({ dataRange, locationRef });
+        }
+      }
+
+      if (sparklines.length > 0) {
+        result.push({ type, sparklines, color });
+      }
+    }
+  }
+
+  return result;
+}
+
+function extractSparklineColor(group: Record<string, unknown>): string | undefined {
+  const colorEl = group["x14:colorSeries"] ?? group["colorSeries"];
+  if (!colorEl || typeof colorEl !== "object") return undefined;
+  const rgb = (colorEl as Record<string, string>)["@_rgb"];
+  if (!rgb) return undefined;
+  // AARRGGBB → #RRGGBB
+  return `#${rgb.length === 8 ? rgb.slice(2) : rgb}`;
+}
+
+function ensureSparkArray(val: unknown): unknown[] {
+  if (val === undefined || val === null) return [];
+  return Array.isArray(val) ? val : [val];
+}
+
+// =============================================================================
+// Page breaks
+// =============================================================================
+
+function parsePageBreaks(worksheet: Record<string, unknown>): { rowPageBreaks: number[]; colPageBreaks: number[] } {
+  const rowPageBreaks: number[] = [];
+  const colPageBreaks: number[] = [];
+
+  const rowBreaksEl = worksheet["rowBreaks"] as Record<string, unknown> | undefined;
+  if (rowBreaksEl) {
+    const brkArr = ensureBreakArray(rowBreaksEl["brk"]);
+    for (const brk of brkArr) {
+      if (!brk || typeof brk !== "object") continue;
+      const id = (brk as Record<string, string>)["@_id"];
+      if (id) rowPageBreaks.push(parseInt(id, 10));
+    }
+  }
+
+  const colBreaksEl = worksheet["colBreaks"] as Record<string, unknown> | undefined;
+  if (colBreaksEl) {
+    const brkArr = ensureBreakArray(colBreaksEl["brk"]);
+    for (const brk of brkArr) {
+      if (!brk || typeof brk !== "object") continue;
+      const id = (brk as Record<string, string>)["@_id"];
+      if (id) colPageBreaks.push(parseInt(id, 10));
+    }
+  }
+
+  return { rowPageBreaks: rowPageBreaks.sort((a, b) => a - b), colPageBreaks: colPageBreaks.sort((a, b) => a - b) };
+}
+
+function ensureBreakArray(val: unknown): unknown[] {
+  if (val === undefined || val === null) return [];
+  return Array.isArray(val) ? val : [val];
+}
+
+// =============================================================================
+// Auto-filter
+// =============================================================================
+
+function parseAutoFilter(worksheet: Record<string, unknown>): AutoFilterRange | undefined {
+  const afEl = worksheet["autoFilter"] as Record<string, unknown> | undefined;
+  if (!afEl) return undefined;
+
+  const ref = afEl["@_ref"] as string | undefined;
+  if (!ref) return undefined;
+
+  const columns: AutoFilterColumn[] = [];
+  const fcArr = afEl["filterColumn"] as Array<Record<string, unknown>> | undefined;
+  if (fcArr) {
+    for (const fc of fcArr) {
+      const colIndex = parseInt((fc["@_colId"] as string) ?? "0", 10);
+      const filterValues: string[] = [];
+
+      const filtersEl = fc["filters"] as Record<string, unknown> | undefined;
+      if (filtersEl) {
+        const filterArr = filtersEl["filter"] as Array<Record<string, string>> | undefined;
+        if (filterArr) {
+          for (const f of filterArr) {
+            const val = f["@_val"];
+            if (val !== undefined) filterValues.push(decodeXmlEntities(val));
+          }
+        }
+      }
+
+      const customFilterEl = fc["customFilters"] as Record<string, unknown> | undefined;
+      let customFilter: AutoFilterColumn["customFilter"];
+      if (customFilterEl) {
+        const cf = customFilterEl["customFilter"] as Record<string, string> | undefined;
+        if (cf) {
+          customFilter = {
+            operator: cf["@_operator"] ?? "equal",
+            value: decodeXmlEntities(cf["@_val"] ?? ""),
+          };
+        }
+      }
+
+      columns.push({
+        colIndex,
+        filterValues: filterValues.length > 0 ? filterValues : undefined,
+        customFilter,
+      });
+    }
+  }
+
+  return { ref, columns };
+}
+
+// =============================================================================
+// Utility helpers
+// =============================================================================
+
+function resolveRelPath(target: string): string {
+  // Targets in rels are relative to the sheet's directory
+  // e.g., "../comments1.xml" from xl/worksheets/ → xl/comments1.xml
+  if (target.startsWith("/")) return target.slice(1);
+  return `xl/${target.replace(/^\.\.\//, "")}`;
+}
+
+function resolveRelativePath(basePath: string, relativePath: string): string {
+  if (relativePath.startsWith("/")) return relativePath.slice(1);
+
+  const parts = basePath.split("/").filter(Boolean);
+  const relParts = relativePath.split("/");
+
+  // Remove the file name from base path (keep directory)
+  // basePath already ends with / so this is fine
+
+  const resolved = [...parts];
+  for (const part of relParts) {
+    if (part === "..") {
+      resolved.pop();
+    } else if (part !== ".") {
+      resolved.push(part);
+    }
+  }
+
+  return resolved.join("/");
+}
+
+function findZipEntry(zipEntries: Record<string, Uint8Array>, path: string): Uint8Array | undefined {
+  // Try exact path
+  if (zipEntries[path]) return zipEntries[path];
+  // Try with leading xl/ prefix variations
+  if (zipEntries[`xl/${path}`]) return zipEntries[`xl/${path}`];
+  // Try without leading slash
+  const noSlash = path.replace(/^\//, "");
+  if (zipEntries[noSlash]) return zipEntries[noSlash];
+  return undefined;
+}
+
+function uint8ToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+export function emptySheet(name: string): ParsedSheet {
+  return {
+    name,
+    columns: [],
+    rows: [],
+    mergedCells: [],
+    totalRowCount: 0,
+    truncated: false,
+    defaultRowHeight: 15,
+    defaultColWidth: 10,
+    showGridLines: true,
+    conditionalFormats: [],
+    images: [],
+    rowOutlineLevels: new Map(),
+    colOutlineLevels: new Map(),
+  };
+}
+