@lotics/xlsx 0.1.0

package/src/ooxml_color.ts

@@ -0,0 +1,339 @@
+import { XMLParser } from "fast-xml-parser";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ThemeData {
+  colors: string[];   // 12 entries: lt1, dk1, lt2, dk2, accent1-6, hlink, folHlink
+  majorFont: string;
+  minorFont: string;
+}
+
+export interface OoxmlColor {
+  rgb?: string;
+  theme?: number;
+  indexed?: number;
+  tint?: number;
+  auto?: boolean;
+}
+
+// =============================================================================
+// Default indexed color palette (64 colors, indices 0-63)
+// =============================================================================
+
+export const DEFAULT_INDEXED_COLORS: string[] = [
+  "000000", "FFFFFF", "FF0000", "00FF00", "0000FF", "FFFF00", "FF00FF", "00FFFF", // 0-7
+  "000000", "FFFFFF", "FF0000", "00FF00", "0000FF", "FFFF00", "FF00FF", "00FFFF", // 8-15
+  "800000", "008000", "000080", "808000", "800080", "008080", "C0C0C0", "808080", // 16-23
+  "9999FF", "993366", "FFFFCC", "CCFFFF", "660066", "FF8080", "0066CC", "CCCCFF", // 24-31
+  "000080", "FF00FF", "FFFF00", "00FFFF", "800080", "800000", "008080", "0000FF", // 32-39
+  "00CCFF", "CCFFFF", "CCFFCC", "FFFF99", "99CCFF", "FF99CC", "CC99FF", "FFCC99", // 40-47
+  "3366FF", "33CCCC", "99CC00", "FFCC00", "FF9900", "FF6600", "666699", "969696", // 48-55
+  "003366", "339966", "003300", "333300", "993300", "993366", "333399", "333333", // 56-63
+];
+
+// =============================================================================
+// Theme parsing
+// =============================================================================
+
+const xmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  processEntities: false,
+  isArray: (tagName) => tagName === "a:srgbClr" || tagName === "a:sysClr",
+});
+
+export function parseTheme(themeXml: string): ThemeData {
+  const doc = xmlParser.parse(themeXml);
+  const themeElements = doc?.["a:theme"]?.["a:themeElements"];
+  if (!themeElements) {
+    return { colors: defaultThemeColors(), majorFont: "Calibri", minorFont: "Calibri" };
+  }
+
+  // Color scheme
+  const clrScheme = themeElements["a:clrScheme"];
+  const colors = parseColorScheme(clrScheme);
+
+  // Font scheme
+  const fontScheme = themeElements["a:fontScheme"];
+  const majorFont = extractFontName(fontScheme?.["a:majorFont"]) ?? "Calibri";
+  const minorFont = extractFontName(fontScheme?.["a:minorFont"]) ?? "Calibri";
+
+  return { colors, majorFont, minorFont };
+}
+
+/** XML color scheme order: dk1, lt1, dk2, lt2, accent1-6, hlink, folHlink */
+const COLOR_SCHEME_KEYS = [
+  "a:dk1", "a:lt1", "a:dk2", "a:lt2",
+  "a:accent1", "a:accent2", "a:accent3", "a:accent4", "a:accent5", "a:accent6",
+  "a:hlink", "a:folHlink",
+];
+
+function parseColorScheme(clrScheme: Record<string, unknown> | undefined): string[] {
+  if (!clrScheme) return defaultThemeColors();
+
+  const colors: string[] = [];
+  for (const key of COLOR_SCHEME_KEYS) {
+    const el = clrScheme[key] as Record<string, unknown> | undefined;
+    colors.push(extractSchemeColor(el));
+  }
+
+  // Reorder: XML is [dk1, lt1, dk2, lt2, ...] but theme index mapping needs
+  // [lt1, dk1, lt2, dk2, ...] — swap 0↔1 and 2↔3
+  const reordered = [...colors];
+  reordered[0] = colors[1]; // lt1
+  reordered[1] = colors[0]; // dk1
+  reordered[2] = colors[3]; // lt2
+  reordered[3] = colors[2]; // dk2
+  return reordered;
+}
+
+function extractSchemeColor(el: Record<string, unknown> | undefined): string {
+  if (!el) return "000000";
+
+  // srgbClr has @_val attribute directly
+  const srgb = el["a:srgbClr"];
+  if (srgb) {
+    const val = Array.isArray(srgb) ? srgb[0] : srgb;
+    const hex = typeof val === "object" && val !== null ? (val as Record<string, string>)["@_val"] : undefined;
+    if (hex) return hex;
+  }
+
+  // sysClr has @_lastClr attribute
+  const sys = el["a:sysClr"];
+  if (sys) {
+    const val = Array.isArray(sys) ? sys[0] : sys;
+    const lastClr = typeof val === "object" && val !== null ? (val as Record<string, string>)["@_lastClr"] : undefined;
+    if (lastClr) return lastClr;
+  }
+
+  return "000000";
+}
+
+function extractFontName(fontEl: Record<string, unknown> | undefined): string | undefined {
+  if (!fontEl) return undefined;
+  const latin = fontEl["a:latin"] as Record<string, string> | undefined;
+  return latin?.["@_typeface"];
+}
+
+export function defaultThemeColors(): string[] {
+  return [
+    "FFFFFF", "000000", "E7E6E6", "44546A",
+    "4472C4", "ED7D31", "A5A5A5", "FFC000",
+    "5B9BD5", "70AD47", "0563C1", "954F72",
+  ];
+}
+
+// =============================================================================
+// Color resolution
+// =============================================================================
+
+/** Parse a color element's attributes into an OoxmlColor. */
+export function parseColorElement(attrs: Record<string, string>): OoxmlColor {
+  const color: OoxmlColor = {};
+  if (attrs["@_rgb"] !== undefined) color.rgb = attrs["@_rgb"];
+  if (attrs["@_theme"] !== undefined) color.theme = parseInt(attrs["@_theme"], 10);
+  if (attrs["@_indexed"] !== undefined) color.indexed = parseInt(attrs["@_indexed"], 10);
+  if (attrs["@_tint"] !== undefined) color.tint = parseFloat(attrs["@_tint"]);
+  if (attrs["@_auto"] !== undefined) color.auto = attrs["@_auto"] === "1" || attrs["@_auto"] === "true";
+  return color;
+}
+
+/**
+ * Resolve an OOXML color to a CSS hex string (6-char, no #).
+ * Returns undefined if the color is auto/unresolvable.
+ */
+export function resolveColor(
+  color: OoxmlColor | undefined,
+  theme: ThemeData,
+  indexedColors: string[],
+  context: "font" | "fill" | "border",
+): string | undefined {
+  if (!color) return undefined;
+
+  // Auto color: black for font, undefined for fill/border
+  if (color.auto) {
+    return context === "font" ? "000000" : undefined;
+  }
+
+  let hex: string | undefined;
+
+  if (color.rgb !== undefined) {
+    // RGB can be AARRGGBB (8 chars) or RRGGBB (6 chars)
+    hex = color.rgb.length === 8 ? color.rgb.slice(2) : color.rgb;
+  } else if (color.theme !== undefined) {
+    const idx = color.theme;
+    if (idx >= 0 && idx < theme.colors.length) {
+      hex = theme.colors[idx];
+    }
+  } else if (color.indexed !== undefined) {
+    const idx = color.indexed;
+    if (idx >= 0 && idx < indexedColors.length) {
+      hex = indexedColors[idx];
+    }
+  }
+
+  if (!hex) return undefined;
+
+  // Apply tint
+  if (color.tint !== undefined && color.tint !== 0) {
+    hex = applyTint(hex, color.tint);
+  }
+
+  return hex;
+}
+
+// =============================================================================
+// Canonical color format
+// =============================================================================
+//
+// Internal canonical color format throughout @lotics/xlsx is `#RRGGBB`
+// (uppercase, hash-prefixed). Every consumer reads/writes that format.
+// Inputs from outside the package (parser, tools, frontend pickers) flow
+// through `normalizeColor()` at ingress; OOXML writers convert via
+// `hexToArgb()` (8-char ARGB) or `hexToOoxmlRgb()` (6-char RGB for chart XML)
+// at egress.
+
+/** Prefix a 6-char internal hex (`RRGGBB`) with `#`. */
+export function prefixHex(hex6: string): string {
+  if (hex6.length !== 6) return "#000000";
+  return `#${hex6.toUpperCase()}`;
+}
+
+/**
+ * Coerce a color string in any supported input format to canonical `#RRGGBB`.
+ * Accepts `#RRGGBB`, `RRGGBB`, `#RGB`, `rgb(r, g, b)`, `rgba(r, g, b, a)`.
+ * Returns undefined for empty or unparseable input.
+ */
+export function normalizeColor(input: string | undefined): string | undefined {
+  if (input === undefined) return undefined;
+  const s = input.trim();
+  if (s === "") return undefined;
+
+  // rgb()/rgba()
+  const rgbMatch = s.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgbMatch) {
+    return `#${toHex2(parseInt(rgbMatch[1], 10))}${toHex2(parseInt(rgbMatch[2], 10))}${toHex2(parseInt(rgbMatch[3], 10))}`;
+  }
+
+  // #RRGGBB
+  const hex6Match = s.match(/^#([0-9a-fA-F]{6})$/);
+  if (hex6Match) return `#${hex6Match[1].toUpperCase()}`;
+
+  // RRGGBB (no hash)
+  const bareHex6Match = s.match(/^([0-9a-fA-F]{6})$/);
+  if (bareHex6Match) return `#${bareHex6Match[1].toUpperCase()}`;
+
+  // #RGB shorthand
+  const hex3Match = s.match(/^#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])$/);
+  if (hex3Match) {
+    const r = hex3Match[1];
+    const g = hex3Match[2];
+    const b = hex3Match[3];
+    return `#${(r + r + g + g + b + b).toUpperCase()}`;
+  }
+
+  return undefined;
+}
+
+/**
+ * Convert a normalized `#RRGGBB` color to OOXML 8-char ARGB (`FFRRGGBB`).
+ * Accepts unnormalized input as a courtesy — runs `normalizeColor` first.
+ */
+export function hexToArgb(input: string | undefined): string {
+  const norm = normalizeColor(input);
+  if (!norm) return "FF000000";
+  return `FF${norm.slice(1)}`;
+}
+
+/**
+ * Convert a normalized `#RRGGBB` color to OOXML 6-char hex (`RRGGBB`),
+ * used by drawing/chart XML where `<a:srgbClr val="…"/>` requires no alpha.
+ */
+export function hexToOoxmlRgb(input: string | undefined): string {
+  const norm = normalizeColor(input);
+  if (!norm) return "000000";
+  return norm.slice(1);
+}
+
+// =============================================================================
+// Tint algorithm
+// =============================================================================
+
+/** Apply Excel tint to a 6-char hex color. Returns 6-char hex. */
+export function applyTint(hex: string, tint: number): string {
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+
+  const { h, s, l } = rgbToHsl(r, g, b);
+
+  let newL: number;
+  if (tint < 0) {
+    newL = l * (1 + tint);
+  } else {
+    newL = l + (1 - l) * tint;
+  }
+  newL = Math.max(0, Math.min(1, newL));
+
+  const { r: nr, g: ng, b: nb } = hslToRgb(h, s, newL);
+  return toHex2(nr) + toHex2(ng) + toHex2(nb);
+}
+
+function toHex2(n: number): string {
+  const clamped = Math.max(0, Math.min(255, Math.round(n)));
+  return clamped.toString(16).padStart(2, "0").toUpperCase();
+}
+
+function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } {
+  const rf = r / 255;
+  const gf = g / 255;
+  const bf = b / 255;
+
+  const max = Math.max(rf, gf, bf);
+  const min = Math.min(rf, gf, bf);
+  const l = (max + min) / 2;
+
+  if (max === min) return { h: 0, s: 0, l };
+
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+  let h: number;
+  if (max === rf) {
+    h = ((gf - bf) / d + (gf < bf ? 6 : 0)) / 6;
+  } else if (max === gf) {
+    h = ((bf - rf) / d + 2) / 6;
+  } else {
+    h = ((rf - gf) / d + 4) / 6;
+  }
+
+  return { h, s, l };
+}
+
+function hslToRgb(h: number, s: number, l: number): { r: number; g: number; b: number } {
+  if (s === 0) {
+    const v = Math.round(l * 255);
+    return { r: v, g: v, b: v };
+  }
+
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+
+  return {
+    r: Math.round(hueToRgb(p, q, h + 1 / 3) * 255),
+    g: Math.round(hueToRgb(p, q, h) * 255),
+    b: Math.round(hueToRgb(p, q, h - 1 / 3) * 255),
+  };
+}
+
+function hueToRgb(p: number, q: number, t: number): number {
+  let tt = t;
+  if (tt < 0) tt += 1;
+  if (tt > 1) tt -= 1;
+  if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+  if (tt < 1 / 2) return q;
+  if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+  return p;
+}

package/src/ooxml_drawing.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { XMLParser } from "fast-xml-parser";
+import { parseDrawingXml } from "./ooxml_drawing";
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  isArray: (tagName) =>
+    tagName === "xdr:twoCellAnchor" || tagName === "xdr:oneCellAnchor",
+});
+const parseXml = (xml: string) => parser.parse(xml) as Record<string, unknown>;
+
+const CHART_DRAWING_XML = `<?xml version="1.0"?>
+<xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:c="http://schemas.openxmlformats.org/drawingml/2006/chart">
+  <xdr:twoCellAnchor>
+    <xdr:from><xdr:col>1</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>2</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from>
+    <xdr:to><xdr:col>5</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>10</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:to>
+    <xdr:graphicFrame>
+      <a:graphic><a:graphicData><c:chart r:id="rId1"/></a:graphicData></a:graphic>
+    </xdr:graphicFrame>
+  </xdr:twoCellAnchor>
+</xdr:wsDr>`;
+
+const SHAPE_DRAWING_XML = `<?xml version="1.0"?>
+<xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
+  <xdr:twoCellAnchor>
+    <xdr:from><xdr:col>0</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>0</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from>
+    <xdr:to><xdr:col>3</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>4</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:to>
+    <xdr:sp>
+      <xdr:spPr>
+        <a:prstGeom prst="rect"/>
+        <a:solidFill><a:srgbClr val="FF0000"/></a:solidFill>
+      </xdr:spPr>
+      <xdr:txBody><a:p><a:r><a:t>Hello</a:t></a:r></a:p></xdr:txBody>
+    </xdr:sp>
+  </xdr:twoCellAnchor>
+</xdr:wsDr>`;
+
+const CONNECTOR_DRAWING_XML = `<?xml version="1.0"?>
+<xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
+  <xdr:twoCellAnchor>
+    <xdr:from><xdr:col>1</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>1</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from>
+    <xdr:to><xdr:col>4</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>4</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:to>
+    <xdr:cxnSp>
+      <xdr:spPr>
+        <a:ln><a:solidFill><a:srgbClr val="0000FF"/></a:solidFill></a:ln>
+      </xdr:spPr>
+    </xdr:cxnSp>
+  </xdr:twoCellAnchor>
+</xdr:wsDr>`;
+
+describe("parseDrawingXml", () => {
+  it("parses two-cell anchor coordinates", () => {
+    const results = parseDrawingXml(CHART_DRAWING_XML, parseXml);
+    expect(results).toHaveLength(1);
+    const anchor = results[0].anchor;
+    expect(anchor.from).toEqual({ row: 2, col: 1, rowOffset: 0, colOffset: 0 });
+    expect(anchor.to).toEqual({ row: 10, col: 5, rowOffset: 0, colOffset: 0 });
+  });
+
+  it("identifies chart graphic frame and extracts rId", () => {
+    const results = parseDrawingXml(CHART_DRAWING_XML, parseXml);
+    expect(results[0].type).toBe("chart");
+    expect(results[0].rId).toBe("rId1");
+  });
+
+  it("parses shape with text and fill", () => {
+    const results = parseDrawingXml(SHAPE_DRAWING_XML, parseXml);
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe("shape");
+    expect(results[0].drawing).toBeDefined();
+    expect(results[0].drawing!.type).toBe("textbox");
+    expect(results[0].drawing!.text).toBe("Hello");
+    expect(results[0].drawing!.fillColor).toBe("#FF0000");
+    expect(results[0].drawing!.geometry).toBe("rect");
+  });
+
+  it("parses connector with outline color", () => {
+    const results = parseDrawingXml(CONNECTOR_DRAWING_XML, parseXml);
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe("shape");
+    expect(results[0].drawing).toBeDefined();
+    expect(results[0].drawing!.type).toBe("connector");
+    expect(results[0].drawing!.geometry).toBe("line");
+    expect(results[0].drawing!.outlineColor).toBe("#0000FF");
+  });
+});