@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/src/runtime/theme-color-resolver.ts

@@ -1,44 +1,112 @@
 /**
- * Resolve a (`<w:color>`-shaped) theme-color reference to a concrete hex
- * string, applying the `w:themeTint` / `w:themeShade` HSL-luminance
- * modulation per ECMA-376 §17.18.85 / §17.18.83.
+ * Unified runtime color resolver for every OOXML theme reference.
  *
- * Usage:
- *   - The IO layer (`parse-run-formatting.ts`) captures
- *     `colorThemeSlot` / `colorThemeTint` / `colorThemeShade` on
- *     `CanonicalRunFormatting` as raw strings (preserved for
- *     byte-stable round-trip).
- *   - The render/cascade layer calls `resolveThemeColorHex(rPr, theme)`
- *     to collapse the reference to the actual hex colour the browser
- *     should paint. The original fields stay intact so export still
- *     round-trips the theme reference (not the computed hex).
+ * Covers:
+ *   - `<w:color>` §17.18.85/§17.18.83 byte-form `w:themeTint`/`w:themeShade`
+ *     (HSL luminance modulation).
+ *   - `<a:schemeClr>` §20.1.2.3.x DrawingML modifier chain
+ *     `lumMod → lumOff → satMod → hueMod → tint → shade` (per-100,000 units).
+ *   - `<w:clrSchemeMapping>` §17.15.1.17 style-slot → scheme-slot remap
+ *     (including the implicit identity default when settings.xml omits it).
+ *   - `<w:color w:val="auto"/>` → the `t1` style slot via the clrMap.
  *
- * Lane 3 L2.c. Mirrors LibreOffice's `Color::ApplyTintOrShade` at
- * `vendor/libreoffice/include/tools/color.hxx:200-240` (shape only; no
- * code copied — our implementation is pure TypeScript against the
- * ECMA-376 formulae).
+ * Cascade layer entry points:
+ *   - `ThemeColorResolver` class — build once per `CanonicalTheme` snapshot,
+ *     key the cache on `(themeHash, clrMapHash)` per CLAUDE.md §3.
+ *   - `concretizeThemeColors(cascade, resolver)` — run-formatting post-pass.
  *
- * **Scope boundary:** this resolver handles the standard tint/shade
- * pair. Theme-color-mapping (clrSchemeMapping — how "accent1" maps to a
- * different `<w:clrScheme>` slot in older Word versions) is NOT applied
- * here — `resolveThemeColor` from `src/io/ooxml/parse-theme.ts` is the
- * authoritative slot→hex lookup and future work will layer scheme
- * mapping into it.
+ * LibreOffice parity: port of `vendor/libreoffice/oox/source/drawingml/color.cxx`
+ * (shape only; no code copied). Modifier order + HSL/sRGB color-space split
+ * match LO; modifiers are applied in declaration order — do NOT sort.
+ *
+ * The original `colorThemeSlot` / `Tint` / `Shade` fields are preserved on
+ * returned cascades so the export path can re-emit the original theme
+ * reference byte-for-byte.
  */
 
-import type { CanonicalRunFormatting, ResolvedTheme } from "../model/canonical-document.ts";
+import type { CanonicalRunFormatting, CanonicalTheme, ClrSchemeMappingSlot, ResolvedTheme } from "../model/canonical-document.ts";
 import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
 
+/**
+ * DrawingML color modifier (ECMA-376 §20.1.2.3.x).
+ * Values are in per-100,000 units (e.g. 65_000 = 65%).
+ * Apply in declaration order — do NOT sort or reorder.
+ *
+ * Distinct from w:themeTint / w:themeShade (ECMA-376 §17) which use
+ * hex-byte 0x00–0xFF encoding.
+ */
+export interface DrawingMlColorMod {
+  kind: "lumMod" | "lumOff" | "satMod" | "hueMod" | "shade" | "tint" | "alpha";
+  value: number;
+}
+
+const DML_UNIT = 100_000;
+
+/**
+ * Unified runtime theme color resolver.
+ * Construct once per CanonicalTheme (keyed on themeHash + clrMapHash).
+ * All resolution methods apply clrMap remapping before any slot lookup.
+ */
+export class ThemeColorResolver {
+  private readonly theme: CanonicalTheme;
+
+  constructor(theme: CanonicalTheme) {
+    this.theme = theme;
+  }
+
+  /** Look up a scheme slot with clrMap remapping applied. Returns #RRGGBB or undefined. */
+  resolveSchemeSlot(slot: string): string | undefined {
+    const mapped = this.theme.clrMap[slot as ClrSchemeMappingSlot] ?? slot;
+    const hex = this.theme.clrScheme.colors[mapped];
+    return hex ?? undefined;
+  }
+
+  /** Resolve w:color val="auto" → "text 1" style slot (t1) via clrMap. */
+  resolveAuto(): string | undefined {
+    // "auto" = windowText = "text 1" style slot (t1).
+    // Pass "t1" so clrMap remapping is honoured (e.g. <w:clrSchemeMapping w:t1="dk2"/>).
+    return this.resolveSchemeSlot("t1");
+  }
+
+  /**
+   * Resolve a w:themeColor + w:themeTint/w:themeShade (§17 byte form, 0x00–0xFF).
+   * Delegates to the existing applyThemeTintShade for the HSL transform.
+   */
+  resolveWordThemeColor(
+    colorThemeSlot: string,
+    colorThemeTint: string | undefined,
+    colorThemeShade: string | undefined,
+  ): string | undefined {
+    const baseHex = this.resolveSchemeSlot(colorThemeSlot);
+    if (!baseHex) return undefined;
+    return applyThemeTintShade(baseHex, colorThemeTint, colorThemeShade);
+  }
+
+  /**
+   * Resolve an a:schemeClr reference with DrawingML modifiers (§20).
+   * Modifiers are applied in declaration order. Alpha mods are ignored.
+   * Returns undefined when the slot is absent.
+   */
+  resolveWithModifiers(
+    slot: string,
+    mods: readonly DrawingMlColorMod[],
+  ): string | undefined {
+    const baseHex = this.resolveSchemeSlot(slot);
+    if (!baseHex) return undefined;
+    if (mods.length === 0) return baseHex;
+    return applyDmlMods(baseHex.startsWith("#") ? baseHex : `#${baseHex}`, mods);
+  }
+}
+
 /**
  * Collapse `<w:color>`-style theme-slot + tint + shade references into a
- * single resolved hex colour. Returns:
- *   - the raw `colorHex` as-is when it's a direct hex (the theme fields
- *     are ignored because direct colour wins per ECMA-376 cascade).
- *   - `"auto"` when the source declared `w:color w:val="auto"` (sentinel
- *     kept verbatim per our long-standing A.9 round-trip rule).
- *   - the theme slot's hex — tint/shade applied — when the source
- *     declared `w:themeColor="accent1"` etc. and the theme is available.
- *   - `undefined` otherwise (no colour declared, or theme slot absent).
+ * single resolved hex colour. §17-only byte-form path; does NOT apply
+ * `w:clrSchemeMapping` remap.
+ *
+ * @deprecated Use `ThemeColorResolver.resolveWordThemeColor` instead —
+ * it honours clrSchemeMapping. This free function is retained only for
+ * its targeted unit tests (`test/io/theme-color-tint-shade.test.ts`) and
+ * will be removed once those migrate to the class.
  */
 export function resolveThemeColorHex(
   rPr: Pick<
@@ -81,23 +149,22 @@ export function resolveThemeColorHex(
  */
 export function concretizeThemeColors(
   cascade: CanonicalRunFormatting,
-  theme: ResolvedTheme | undefined,
+  resolver: ThemeColorResolver | undefined,
 ): CanonicalRunFormatting {
   if (!cascade.colorThemeSlot) return cascade;
   if (cascade.colorHex && cascade.colorHex !== "auto") return cascade;
-  // When colorHex is "auto" we intentionally bypass it during theme
-  // resolution: Word's cascade treats `<w:color w:val="auto"
-  // w:themeColor="accent1"/>` as "paint with the theme slot; auto is
-  // the fallback if theme is missing." Pass a stripped input to the
-  // resolver so `colorHex === "auto"` doesn't short-circuit.
-  const resolved = resolveThemeColorHex(
-    {
-      colorThemeSlot: cascade.colorThemeSlot,
-      colorThemeTint: cascade.colorThemeTint,
-      colorThemeShade: cascade.colorThemeShade,
-    },
-    theme,
+  if (!resolver) return cascade;
+
+  // `colorHex === "auto"` with a themeColor slot means "paint via the theme
+  // slot; auto is only the fallback when theme is missing" — so we always
+  // resolve via the slot here. clrSchemeMapping remap is applied inside
+  // `resolver.resolveWordThemeColor`.
+  const resolved = resolver.resolveWordThemeColor(
+    cascade.colorThemeSlot,
+    cascade.colorThemeTint,
+    cascade.colorThemeShade,
   );
+
   if (!resolved || resolved === "auto") return cascade;
   if (resolved === cascade.colorHex) return cascade;
   return { ...cascade, colorHex: resolved };
@@ -174,6 +241,84 @@ function formatHexColor(rgb: { r: number; g: number; b: number }): string {
   return `${to2(rgb.r)}${to2(rgb.g)}${to2(rgb.b)}`;
 }
 
+// ---------------------------------------------------------------------------
+// DrawingML modifier pipeline (§20 forms — per-100,000 units)
+// ---------------------------------------------------------------------------
+
+function applyDmlMods(
+  hex: string,
+  mods: readonly DrawingMlColorMod[],
+): string {
+  let rgb = parseHexToRgbDml(hex);
+  for (const mod of mods) {
+    const frac = mod.value / DML_UNIT;
+    switch (mod.kind) {
+      case "lumMod": {
+        const hsl = rgbToHsl(rgb);
+        rgb = hslToRgb({ ...hsl, l: clamp01(hsl.l * frac) });
+        break;
+      }
+      case "lumOff": {
+        const hsl = rgbToHsl(rgb);
+        rgb = hslToRgb({ ...hsl, l: clamp01(hsl.l + frac) });
+        break;
+      }
+      case "satMod": {
+        const hsl = rgbToHsl(rgb);
+        rgb = hslToRgb({ ...hsl, s: clamp01(hsl.s * frac) });
+        break;
+      }
+      case "hueMod": {
+        const hsl = rgbToHsl(rgb);
+        // Multiplicative scale per LO color.cxx, not additive rotation
+        rgb = hslToRgb({ ...hsl, h: ((hsl.h * frac) % 360 + 360) % 360 });
+        break;
+      }
+      case "shade": {
+        // §20.1.2.3.31: sRGB space (NOT HSL) — multiply channels toward black
+        rgb = {
+          r: clamp255(rgb.r * frac),
+          g: clamp255(rgb.g * frac),
+          b: clamp255(rgb.b * frac),
+        };
+        break;
+      }
+      case "tint": {
+        // §20.1.2.3.34: sRGB space — C' = C * frac + 255 * (1 - frac)
+        const inv = 1 - frac;
+        rgb = {
+          r: clamp255(rgb.r * frac + 255 * inv),
+          g: clamp255(rgb.g * frac + 255 * inv),
+          b: clamp255(rgb.b * frac + 255 * inv),
+        };
+        break;
+      }
+      case "alpha":
+        break; // opacity not reflected in sRGB output
+    }
+  }
+  return formatDmlHex(rgb);
+}
+
+function parseHexToRgbDml(hex: string): { r: number; g: number; b: number } {
+  const n = Number.parseInt(hex.slice(1), 16);
+  return { r: (n >>> 16) & 0xff, g: (n >>> 8) & 0xff, b: n & 0xff };
+}
+
+function formatDmlHex(rgb: { r: number; g: number; b: number }): string {
+  const h2 = (n: number): string =>
+    Math.round(clamp255(n)).toString(16).padStart(2, "0").toUpperCase();
+  return `#${h2(rgb.r)}${h2(rgb.g)}${h2(rgb.b)}`;
+}
+
+function clamp01(x: number): number {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+
+function clamp255(x: number): number {
+  return x < 0 ? 0 : x > 255 ? 255 : x;
+}
+
 function rgbToHsl(rgb: { r: number; g: number; b: number }): {
   h: number;
   s: number;

package/src/runtime/units.ts

@@ -0,0 +1,46 @@
+/**
+ * OOXML unit conversions used across the runtime + UI.
+ *
+ * Hoisted from per-file constants to deduplicate the magic numbers that
+ * appear in `pm-schema.ts`, `chart-model-store.ts`, `float-wrap-resolver.ts`,
+ * `shape-renderer.ts`, and several other call sites.  Renaming an alias
+ * here propagates everywhere; renaming a literal would not.
+ *
+ * Conventions:
+ *   - All EMU helpers assume 96 dpi (the default OOXML rendering DPI).
+ *   - Twip helpers assume 1440 twips per inch (OOXML standard).
+ *   - Rotation values use OOXML's 60 000ths of a degree (`a:xfrm a:rot`).
+ *   - Picture crop (`a:srcRect`) values use 1/1000 of a percent per edge.
+ */
+
+/** EMU (English Metric Units) per CSS pixel at 96 dpi. */
+export const EMU_PER_PX = 9525;
+
+/** OOXML rotation units per degree (`a:xfrm a:rot` = 60 000ths°). */
+export const ROTATION_UNITS_PER_DEGREE = 60000;
+
+/** OOXML picture-crop units per percent (`a:srcRect` uses 1/1000 of a percent). */
+export const SRCRECT_UNITS_PER_PERCENT = 1000;
+
+/** Twips per CSS pixel at 96 dpi (1440 twips/inch ÷ 96 px/inch = 15). */
+export const TWIPS_PER_PX = 15;
+
+/** Convert EMU → CSS pixels at 96 dpi. */
+export function emuToPx(emu: number): number {
+  return emu / EMU_PER_PX;
+}
+
+/** Convert OOXML rotation units → CSS degrees. */
+export function rotationToDeg(units: number): number {
+  return units / ROTATION_UNITS_PER_DEGREE;
+}
+
+/** Convert an `a:srcRect` edge value → CSS percent. */
+export function srcRectToPercent(units: number): number {
+  return units / SRCRECT_UNITS_PER_PERCENT;
+}
+
+/** Convert twips → CSS pixels at 96 dpi. */
+export function twipsToPx(twips: number): number {
+  return twips / TWIPS_PER_PX;
+}

package/src/runtime/view-state.ts

@@ -403,6 +403,14 @@ function deriveActiveObjectFrame(
     };
   }
 
+  if (segment.kind === "shape") {
+    return {
+      kind: "shape",
+      anchorPos: segment.from,
+      display: segment.anchor?.display === "floating" ? "floating" : "inline",
+    };
+  }
+
   const objectKind = inferOpaqueObjectKind(segment);
   if (!objectKind) {
     return null;
@@ -491,7 +499,7 @@ function normalizeZoomLevel(
 function findObjectSegmentAtPosition(
   segments: readonly SurfaceInlineSegment[],
   position: number,
-): Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" }> | null {
+): Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" | "shape" }> | null {
   for (const segment of segments) {
     if (!isObjectLikeSegment(segment)) {
       continue;
@@ -505,10 +513,13 @@ function findObjectSegmentAtPosition(
 
 function isObjectLikeSegment(
   segment: SurfaceInlineSegment,
-): segment is Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" }> {
+): segment is Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" | "shape" }> {
   if (segment.kind === "image") {
     return true;
   }
+  if (segment.kind === "shape") {
+    return true;
+  }
   if (segment.kind !== "opaque_inline") {
     return false;
   }