@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/io/ooxml/chart/resolve-color.ts

@@ -0,0 +1,261 @@
+/**
+ * Resolve a `ColorRef` into a concrete sRGB hex string.
+ *
+ * Implements the second layer of the OOXML chart-color cascade
+ * (docs/plans/lane-5-charts.md § 4 Task 2.2): scheme-color and
+ * themeLinked references are looked up in `ResolvedTheme.colors`, and
+ * OOXML color modifiers (`lumMod`, `lumOff`, `shade`, `tint`, `satMod`,
+ * `hueMod`) are applied in declaration order via HSL color math per
+ * ECMA-376 § 20.1.2.3.x.
+ *
+ * The output is always a valid `#RRGGBB` uppercase hex string. Bad or
+ * missing inputs fall through to a legible default (#808080) rather than
+ * throwing — renderers must never see `undefined` for a color slot.
+ *
+ * Alpha modifiers are intentionally NOT applied to the sRGB output;
+ * callers that want opacity must emit it as a separate channel. This
+ * keeps the return type a pure color and makes the resolver idempotent.
+ */
+
+import type { ColorMod, ColorRef } from "./types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+
+const FALLBACK_COLOR = "#808080";
+const OOXML_UNIT = 100_000; // modifier val is in parts per 100,000
+
+/**
+ * Scheme-alias map. Word often emits aliases that refer to the primary
+ * color slots: `tx1` → `dk1`, `bg1` → `lt1`, `tx2` → `dk2`, `bg2` → `lt2`.
+ * The mapping is standardized by DrawingML.
+ *
+ * `phClr` is deliberately NOT aliased — it's a DrawingML "placeholder"
+ * color (ECMA-376 §20.1.4.1.22) that the caller is expected to substitute
+ * from its own context (e.g. the surrounding shape's accent). When the
+ * caller has no substitution, resolving phClr should fall through to the
+ * fallback color rather than silently pretend it meant accent1. Prior
+ * behavior aliased `phClr` → `accent1`, which silently miscolored every
+ * chart that used a placeholder color in its sidecar colors.xml.
+ */
+const SCHEME_ALIASES: Record<string, string> = {
+  tx1: "dk1",
+  bg1: "lt1",
+  tx2: "dk2",
+  bg2: "lt2",
+};
+
+export function resolveColor(ref: ColorRef, theme: ResolvedTheme): string {
+  const baseHex = baseColor(ref, theme);
+  const rgb = hexToRgb(baseHex);
+  const withMods = applyMods(rgb, "mods" in ref ? ref.mods : undefined);
+  return rgbToHex(withMods);
+}
+
+// ---------------------------------------------------------------------------
+// Base-color lookup (before modifiers)
+// ---------------------------------------------------------------------------
+
+function baseColor(ref: ColorRef, theme: ResolvedTheme): string {
+  switch (ref.kind) {
+    case "srgb":
+      return normalizeHex(ref.value);
+    case "scheme":
+    case "themeLinked": {
+      const slot = SCHEME_ALIASES[ref.value] ?? ref.value;
+      const hex = theme.colors[slot];
+      return hex ? normalizeHex(hex) : FALLBACK_COLOR;
+    }
+    default:
+      return FALLBACK_COLOR;
+  }
+}
+
+/**
+ * Normalize any `#RRGGBB` or `RRGGBB` string to uppercase with a leading
+ * `#`. Returns the fallback color on any malformed input so the output
+ * contract (`/^#[0-9A-F]{6}$/`) is always satisfied.
+ */
+function normalizeHex(raw: string): string {
+  const m = /^#?([0-9A-Fa-f]{6})$/.exec(raw);
+  if (!m) return FALLBACK_COLOR;
+  return `#${m[1]!.toUpperCase()}`;
+}
+
+// ---------------------------------------------------------------------------
+// Modifier pipeline
+// ---------------------------------------------------------------------------
+
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+function applyMods(rgb: Rgb, mods: readonly ColorMod[] | undefined): Rgb {
+  if (!mods || mods.length === 0) return rgb;
+  let current = rgb;
+  for (const mod of mods) {
+    current = applyMod(current, mod);
+  }
+  return current;
+}
+
+function applyMod(rgb: Rgb, mod: ColorMod): Rgb {
+  const frac = mod.value / OOXML_UNIT;
+  switch (mod.kind) {
+    case "lumMod": {
+      // Scale luminance.
+      const hsl = rgbToHsl(rgb);
+      hsl.l = clamp01(hsl.l * frac);
+      return hslToRgb(hsl);
+    }
+    case "lumOff": {
+      // Add to luminance.
+      const hsl = rgbToHsl(rgb);
+      hsl.l = clamp01(hsl.l + frac);
+      return hslToRgb(hsl);
+    }
+    case "satMod": {
+      // Scale saturation.
+      const hsl = rgbToHsl(rgb);
+      hsl.s = clamp01(hsl.s * frac);
+      return hslToRgb(hsl);
+    }
+    case "hueMod": {
+      // Multiplicative scaling of the hue angle — NOT an additive
+      // rotation. ECMA-376 §20.1.2.3.14 and LibreOffice
+      // (oox/source/drawingml/color.cxx `lclModValue`) apply `hueMod` as
+      // `hue' = hue * (val/100000)`, stored in the hue dimension of HSL
+      // and clamped into the valid angle range. We wrap via mod-360 for
+      // numeric resilience when the source value exceeds 100% (a legal
+      // "expand hue" case).
+      const hsl = rgbToHsl(rgb);
+      hsl.h = ((hsl.h * frac) % 360 + 360) % 360;
+      return hslToRgb(hsl);
+    }
+    case "shade": {
+      // Scale channels toward black. Per ECMA-376 § 20.1.2.3.31, shade is
+      // applied in the sRGB color space, not HSL — this is important
+      // because it preserves hue and saturation while darkening.
+      return {
+        r: clamp255(rgb.r * frac),
+        g: clamp255(rgb.g * frac),
+        b: clamp255(rgb.b * frac),
+      };
+    }
+    case "tint": {
+      // Scale channels toward white. Per ECMA-376 § 20.1.2.3.34, tint is
+      // applied in sRGB space: C' = C * frac + 255 * (1 - frac).
+      // Note: this is equivalent to "lighten by (1-frac)".
+      const inv = 1 - frac;
+      return {
+        r: clamp255(rgb.r * frac + 255 * inv),
+        g: clamp255(rgb.g * frac + 255 * inv),
+        b: clamp255(rgb.b * frac + 255 * inv),
+      };
+    }
+    case "alpha":
+      // Opacity — not applied to sRGB output. Callers that need opacity
+      // must query the mods list directly.
+      return rgb;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Color-space conversions
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex: string): Rgb {
+  const n = Number.parseInt(hex.slice(1), 16);
+  return {
+    r: (n >>> 16) & 0xff,
+    g: (n >>> 8) & 0xff,
+    b: n & 0xff,
+  };
+}
+
+function rgbToHex(rgb: Rgb): string {
+  const r = Math.round(clamp255(rgb.r));
+  const g = Math.round(clamp255(rgb.g));
+  const b = Math.round(clamp255(rgb.b));
+  return `#${toHex2(r)}${toHex2(g)}${toHex2(b)}`;
+}
+
+function toHex2(n: number): string {
+  return n.toString(16).padStart(2, "0").toUpperCase();
+}
+
+interface Hsl {
+  /** Hue in degrees [0, 360). */
+  h: number;
+  /** Saturation in [0, 1]. */
+  s: number;
+  /** Luminance in [0, 1]. */
+  l: number;
+}
+
+function rgbToHsl(rgb: Rgb): Hsl {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const delta = max - min;
+    s = l > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+    if (max === r) h = ((g - b) / delta) % 6;
+    else if (max === g) h = (b - r) / delta + 2;
+    else h = (r - g) / delta + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return { h, s, l };
+}
+
+function hslToRgb(hsl: Hsl): Rgb {
+  const { h, s, l } = hsl;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  let r1 = 0;
+  let g1 = 0;
+  let b1 = 0;
+  if (h < 60) {
+    r1 = c;
+    g1 = x;
+  } else if (h < 120) {
+    r1 = x;
+    g1 = c;
+  } else if (h < 180) {
+    g1 = c;
+    b1 = x;
+  } else if (h < 240) {
+    g1 = x;
+    b1 = c;
+  } else if (h < 300) {
+    r1 = x;
+    b1 = c;
+  } else {
+    r1 = c;
+    b1 = x;
+  }
+  return {
+    r: (r1 + m) * 255,
+    g: (g1 + m) * 255,
+    b: (b1 + m) * 255,
+  };
+}
+
+function clamp01(x: number): number {
+  if (x < 0) return 0;
+  if (x > 1) return 1;
+  return x;
+}
+
+function clamp255(x: number): number {
+  if (x < 0) return 0;
+  if (x > 255) return 255;
+  return x;
+}

package/src/io/ooxml/chart/types.ts

@@ -0,0 +1,439 @@
+/**
+ * Chart data-model types (Stage 1).
+ *
+ * Pure type declarations. No runtime code, no imports from runtime modules.
+ * `ChartModel` is a discriminated union (by `kind`) covering every chart
+ * family we parse or intentionally mark as unsupported. Parsed models retain
+ * the source XML in `rawXml` so the export path (which re-emits the
+ * original drawing verbatim) stays byte-identical regardless of renderer
+ * coverage.
+ *
+ * Stage 2 will add the theme/colors/style cascade that turns `ColorRef`
+ * values into concrete sRGB strings. Until then, colors are declared as
+ * references; consumers of Stage 1 models should treat color resolution as
+ * "not yet available."
+ *
+ * See docs/plans/lane-5-charts.md §3 Task 1.1 for the full specification.
+ */
+
+// ---------------------------------------------------------------------------
+// Top-level union
+// ---------------------------------------------------------------------------
+
+export type ChartModel =
+  | BarChartModel
+  | LineChartModel
+  | PieChartModel
+  | AreaChartModel
+  | ScatterChartModel
+  | BubbleChartModel
+  | ComboChartModel
+  | UnsupportedChartModel;
+
+export interface ChartCommon {
+  /** Chart title, if present. */
+  title?: Title;
+  /** Legend configuration; absent if the chart has no legend. */
+  legend?: Legend;
+  /** Whether to plot only visible cells (c:plotVisOnly). */
+  plotVisOnly: boolean;
+  /** How to render blank/null values (c:dispBlanksAs). */
+  dispBlanksAs: "gap" | "zero" | "span";
+  /** Legacy chart style id (c:style val, 1–48), if present. */
+  styleId?: number;
+  /** Theme color scheme slot names available to this chart (accent1..6 etc.). */
+  themeColorScheme?: string[];
+  /**
+   * The raw chart-space XML that produced this model. Preserved so the
+   * export path can re-emit the original drawing without depending on the
+   * renderer's coverage of a given chart family.
+   */
+  rawXml: string;
+}
+
+/**
+ * Category-like axis binding for bar/line/area charts. Date axes are a
+ * legal substitute for a category axis at the XML level (c:dateAx replaces
+ * c:catAx) and we preserve the kind here so the renderer can format
+ * category labels as dates when the source authored them that way.
+ */
+export type CategoryLikeAxis = CategoryAxis | DateAxis;
+
+export interface BarChartModel extends ChartCommon {
+  kind: "bar";
+  /** "bar" = horizontal; "column" = vertical. */
+  direction: "bar" | "column";
+  grouping: "clustered" | "stacked" | "percentStacked" | "standard";
+  /** Gap between categories in percent of bar width (c:gapWidth). */
+  gapWidth: number;
+  /** Overlap within a category in percent, -100..100 (c:overlap). */
+  overlap: number;
+  series: Series[];
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  /** Present when any series/group targeted the secondary axis. */
+  secondaryValueAxis?: ValueAxis;
+}
+
+export interface LineChartModel extends ChartCommon {
+  kind: "line";
+  grouping: "standard" | "stacked" | "percentStacked";
+  /** Global smooth flag; per-series values can override. */
+  smooth: boolean;
+  /** Global marker flag; per-series values can override. */
+  marker: boolean;
+  series: LineSeries[];
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  secondaryValueAxis?: ValueAxis;
+}
+
+export interface PieChartModel extends ChartCommon {
+  kind: "pie";
+  doughnut: boolean;
+  /** Doughnut hole size in percent, typical 10–75 (c:holeSize). */
+  holeSizePercent?: number;
+  /** Clockwise degrees from 12 o'clock, 0–360 (c:firstSliceAngle / 60000). */
+  firstSliceAngle: number;
+  varyColors: boolean;
+  /** Almost always one series; pie-of-pie is length 2 (deferred). */
+  series: PieSeries[];
+  /** Category labels (from the first series' c:cat). */
+  categoryLabels: string[];
+}
+
+export interface AreaChartModel extends ChartCommon {
+  kind: "area";
+  grouping: "standard" | "stacked" | "percentStacked";
+  series: Series[];
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  secondaryValueAxis?: ValueAxis;
+}
+
+export interface ScatterChartModel extends ChartCommon {
+  kind: "scatter";
+  style: "line" | "lineMarker" | "marker" | "smooth" | "smoothMarker";
+  series: ScatterSeries[];
+  /** Scatter uses a numeric x-axis, not a category axis. */
+  xAxis: ValueAxis;
+  yAxis: ValueAxis;
+}
+
+export interface BubbleChartModel extends ChartCommon {
+  kind: "bubble";
+  bubble3D: boolean;
+  series: BubbleSeries[];
+  xAxis: ValueAxis;
+  yAxis: ValueAxis;
+}
+
+export interface ComboChartModel extends ChartCommon {
+  kind: "combo";
+  /**
+   * Each type-group (bar/line/area) contributes its own series list. Axes
+   * may be shared or split into primary/secondary pairs.
+   */
+  groups: Array<BarChartModel | LineChartModel | AreaChartModel>;
+  /** True if any group targeted a secondary value axis. */
+  hasSecondaryAxis: boolean;
+}
+
+export interface UnsupportedChartModel extends ChartCommon {
+  kind: "unsupported";
+  reason: UnsupportedReason;
+  /** Human-readable detail (e.g. "Chart family lineChart not yet implemented"). */
+  detail: string;
+}
+
+/**
+ * Discriminator values for `UnsupportedChartModel.reason`.
+ *
+ * - `not-yet-implemented`: the parser recognises the chart family but a
+ *   subsequent slice is responsible for implementing it (line/pie/area/
+ *   scatter/bubble/combo in this slice).
+ * - `pivot`/`stock`/`surface`/…: families that are intentionally deferred
+ *   indefinitely per the plan's non-goals (rare in legal/finance corpora,
+ *   disproportionate renderer cost).
+ * - `no-plot-area`: the chart XML had no c:plotArea child.
+ * - `parse-error`: unexpected structure or exception during parse.
+ */
+export type UnsupportedReason =
+  | "not-yet-implemented"
+  | "pivot"
+  | "stock"
+  | "surface"
+  | "treemap"
+  | "sunburst"
+  | "histogram"
+  | "waterfall"
+  | "funnel"
+  | "map"
+  | "no-plot-area"
+  | "parse-error";
+
+// ---------------------------------------------------------------------------
+// Series
+// ---------------------------------------------------------------------------
+
+export interface SeriesBase {
+  /** c:idx — render order. */
+  idx: number;
+  /** c:order — data order. */
+  order: number;
+  /** Series display name (c:tx/c:strRef/c:strCache or c:v). */
+  name?: string;
+  /** Explicit fill/stroke overrides from c:spPr. */
+  spPr?: ShapeProperties;
+}
+
+export interface Series extends SeriesBase {
+  /** Category labels; string-form even when c:numRef was used. */
+  categories: string[];
+  /** Numeric values; `null` for blank/missing points (sparse cache). */
+  values: Array<number | null>;
+  dataLabels?: DataLabelsSpec;
+  /** Per-data-point overrides (c:dPt). */
+  dataPoints?: DataPointOverride[];
+}
+
+export interface LineSeries extends Series {
+  /** Per-series smooth override. */
+  smooth?: boolean;
+  marker?: MarkerSpec;
+}
+
+export interface PieSeries extends SeriesBase {
+  values: Array<number | null>;
+  /** Per-series default explosion percent. */
+  explosion?: number;
+  dataPoints?: DataPointOverride[];
+}
+
+export interface ScatterSeries extends SeriesBase {
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  smooth?: boolean;
+  marker?: MarkerSpec;
+}
+
+export interface BubbleSeries extends SeriesBase {
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  sizes: Array<number | null>;
+  bubbleScale?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Axes
+// ---------------------------------------------------------------------------
+
+export type Axis = CategoryAxis | ValueAxis | DateAxis | SeriesAxis;
+
+export interface AxisBase {
+  /** c:axId — unique within the plot area. */
+  id: string;
+  /** c:crossAx — the id of the perpendicular axis this one crosses. */
+  crossAxisId?: string;
+  /** Value at which the perpendicular axis crosses this one (c:crossesAt). */
+  crossesAt?: number | "autoZero" | "max" | "min";
+  /** c:axPos: b = bottom, t = top, l = left, r = right. */
+  position: "b" | "t" | "l" | "r";
+  /**
+   * Whether the axis is visible. Note: c:delete has inverted semantics —
+   * `val="1"` means invisible; we store the normal-sense boolean here.
+   */
+  visible: boolean;
+  title?: Title;
+  majorGridlines?: boolean;
+  minorGridlines?: boolean;
+  majorUnit?: number;
+  minorUnit?: number;
+  /** c:numFmt/@formatCode. */
+  numberFormat?: string;
+}
+
+export interface CategoryAxis extends AxisBase {
+  kind: "category";
+  /** c:auto — whether category width is chosen automatically. */
+  auto: boolean;
+  labelAlign?: "ctr" | "l" | "r";
+  labelOffset?: number;
+  tickMark?: "none" | "in" | "out" | "cross";
+  tickLabelSkip?: number;
+  tickMarkSkip?: number;
+  /** Category labels resolved from the first series' c:cat cache. */
+  categoryLabels: string[];
+}
+
+export interface ValueAxis extends AxisBase {
+  kind: "value";
+  min?: number;
+  max?: number;
+  logBase?: number;
+  /** True when c:scaling/c:orientation val="maxMin". */
+  reverse: boolean;
+  crossBetween?: "between" | "midCat";
+}
+
+export interface DateAxis extends AxisBase {
+  kind: "date";
+  baseTimeUnit?: "days" | "months" | "years";
+  /** Serial date (days since 1899-12-30). */
+  min?: number;
+  max?: number;
+  majorTimeUnit?: "days" | "months" | "years";
+  minorTimeUnit?: "days" | "months" | "years";
+}
+
+export interface SeriesAxis extends AxisBase {
+  kind: "series";
+}
+
+// ---------------------------------------------------------------------------
+// Other chart elements
+// ---------------------------------------------------------------------------
+
+export interface Title {
+  /**
+   * Plain-text rendering of the title. Rich-text formatting is not preserved
+   * at Stage 1; Stage 2/3 may extend this with per-run styling.
+   */
+  text?: string;
+  overlay: boolean;
+  spPr?: ShapeProperties;
+  txPr?: TextProperties;
+}
+
+export interface Legend {
+  position: "b" | "t" | "l" | "r" | "tr";
+  overlay: boolean;
+  spPr?: ShapeProperties;
+  txPr?: TextProperties;
+}
+
+export interface DataLabelsSpec {
+  showVal: boolean;
+  showCatName: boolean;
+  showSerName: boolean;
+  showPercent: boolean;
+  showBubbleSize: boolean;
+  showLegendKey: boolean;
+  position?: "b" | "ctr" | "l" | "r" | "t" | "bestFit" | "inBase" | "inEnd" | "outEnd";
+  separator?: string;
+  numberFormat?: string;
+  txPr?: TextProperties;
+}
+
+export interface MarkerSpec {
+  symbol:
+    | "circle"
+    | "square"
+    | "diamond"
+    | "triangle"
+    | "x"
+    | "star"
+    | "dot"
+    | "dash"
+    | "plus"
+    | "picture"
+    | "none"
+    | "auto";
+  /** Point size 2..72. */
+  size?: number;
+  spPr?: ShapeProperties;
+}
+
+export interface DataPointOverride {
+  /** Index of the data point within the series. */
+  idx: number;
+  spPr?: ShapeProperties;
+  marker?: MarkerSpec;
+  /** Pie only: per-slice explosion percent. */
+  explosion?: number;
+  /** Bar only: render negative values with inverted fill. */
+  invertIfNegative?: boolean;
+  /** Bubble only: 3D bubble flag (rendered as 2D regardless). */
+  bubble3D?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Shape / fill / stroke / color primitives
+// ---------------------------------------------------------------------------
+
+export interface ShapeProperties {
+  fill?: FillSpec;
+  stroke?: StrokeSpec;
+}
+
+export type FillSpec =
+  | { kind: "solid"; color: ColorRef }
+  | { kind: "gradient"; stops: Array<{ pos: number; color: ColorRef }>; angle?: number }
+  | { kind: "none" }
+  | { kind: "auto" };
+
+export interface StrokeSpec {
+  color?: ColorRef;
+  /** Stroke width in EMU (English Metric Units). */
+  widthEmu?: number;
+  dash?: "solid" | "dash" | "dashDot" | "lgDash" | "lgDashDot" | "sysDash" | "sysDashDot";
+  noFill?: boolean;
+}
+
+/**
+ * An unresolved color reference. Stage 2 adds `resolveColor(ref, theme)`
+ * which turns this into a concrete sRGB string via the chart-color cascade
+ * (explicit sRGB → scheme color → theme color scheme).
+ */
+export type ColorRef =
+  | { kind: "srgb"; value: string } // "#RRGGBB"
+  | { kind: "scheme"; value: string; mods?: ColorMod[] }
+  | { kind: "themeLinked"; value: string; mods?: ColorMod[] };
+
+export interface ColorMod {
+  kind: "lumMod" | "lumOff" | "shade" | "tint" | "satMod" | "hueMod" | "alpha";
+  /** Parts per 100,000 (OOXML convention). */
+  value: number;
+}
+
+export interface TextProperties {
+  fontFamily?: string;
+  fontSizePt?: number;
+  bold?: boolean;
+  italic?: boolean;
+  color?: ColorRef;
+}
+
+// ---------------------------------------------------------------------------
+// Exhaustiveness canary (compile-time only)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile-time assertion that `ChartModel["kind"]` equals the expected
+ * literal-union below. If a new variant is added to `ChartModel` without
+ * being listed in `_ExpectedKinds`, `_Equals` resolves to `false` and the
+ * subsequent `true` assignment fails at compile time. The previous
+ * dual-assign-cast pattern did not actually enforce union equality — any
+ * new kind silently passed through.
+ *
+ * Reference: the standard "exact type equality" trick using contravariance
+ * of conditional-type generic functions.
+ */
+type _Equals<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2)
+    ? true
+    : false;
+
+type _ExpectedKinds =
+  | "bar"
+  | "line"
+  | "pie"
+  | "area"
+  | "scatter"
+  | "bubble"
+  | "combo"
+  | "unsupported";
+
+type _ChartKindCheck = _Equals<ChartModel["kind"], _ExpectedKinds>;
+const _kindExhaustive: _ChartKindCheck = true;
+void _kindExhaustive;