@lotics/docx 0.1.0

package/src/model/style_resolution.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect } from "vitest";
+import { parseXml, getTagName, getChildren } from "@lotics/ooxml/xml";
+import {
+  EMPTY_PARAGRAPH_PROPERTIES,
+  EMPTY_RUN_PROPERTIES,
+  extractParagraphProperties,
+  extractRunProperties,
+} from "./properties";
+import { parseStyleTable } from "../parse/styles";
+import {
+  resolveParagraphProperties,
+  resolveRunProperties,
+} from "./style_resolution";
+import type { StyleTable } from "./style_table";
+
+function partsFromStylesXml(xml: string): Map<string, Uint8Array> {
+  return new Map([
+    ["word/styles.xml", new TextEncoder().encode(xml)],
+  ]);
+}
+
+const STYLES_XML = `<?xml version="1.0"?>
+<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:docDefaults>
+    <w:rPrDefault>
+      <w:rPr>
+        <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
+        <w:sz w:val="22"/>
+      </w:rPr>
+    </w:rPrDefault>
+    <w:pPrDefault>
+      <w:pPr>
+        <w:spacing w:after="160" w:line="259" w:lineRule="auto"/>
+      </w:pPr>
+    </w:pPrDefault>
+  </w:docDefaults>
+  <w:style w:type="paragraph" w:styleId="Normal" w:default="1">
+    <w:name w:val="Normal"/>
+  </w:style>
+  <w:style w:type="paragraph" w:styleId="Heading1">
+    <w:name w:val="heading 1"/>
+    <w:basedOn w:val="Normal"/>
+    <w:pPr>
+      <w:keepNext/>
+      <w:spacing w:before="240" w:after="0"/>
+      <w:outlineLvl w:val="0"/>
+    </w:pPr>
+    <w:rPr>
+      <w:b/>
+      <w:sz w:val="32"/>
+    </w:rPr>
+  </w:style>
+  <w:style w:type="paragraph" w:styleId="Heading2">
+    <w:name w:val="heading 2"/>
+    <w:basedOn w:val="Heading1"/>
+    <w:pPr>
+      <w:outlineLvl w:val="1"/>
+    </w:pPr>
+    <w:rPr>
+      <w:sz w:val="26"/>
+    </w:rPr>
+  </w:style>
+  <w:style w:type="character" w:styleId="Emphasis">
+    <w:name w:val="Emphasis"/>
+    <w:rPr>
+      <w:i/>
+    </w:rPr>
+  </w:style>
+</w:styles>`;
+
+function loadTable(): StyleTable {
+  return parseStyleTable(partsFromStylesXml(STYLES_XML));
+}
+
+describe("parseStyleTable", () => {
+  it("extracts doc defaults", () => {
+    const table = loadTable();
+    expect(table.runDefaults.fontAscii).toBe("Calibri");
+    expect(table.runDefaults.size).toBe(22);
+    expect(table.paragraphDefaults.spacing).toEqual({
+      before: null,
+      after: 160,
+      line: 259,
+      lineRule: "auto",
+    });
+  });
+
+  it("extracts styles with type, basedOn, link, pPr, rPr", () => {
+    const table = loadTable();
+    expect(table.styles.size).toBe(4);
+    const heading1 = table.styles.get("Heading1")!;
+    expect(heading1.type).toBe("paragraph");
+    expect(heading1.basedOn).toBe("Normal");
+    expect(heading1.runProperties?.bold).toBe(true);
+    expect(heading1.runProperties?.size).toBe(32);
+    expect(heading1.paragraphProperties?.keepNext).toBe(true);
+    expect(heading1.paragraphProperties?.outlineLevel).toBe(0);
+
+    const emphasis = table.styles.get("Emphasis")!;
+    expect(emphasis.type).toBe("character");
+    expect(emphasis.runProperties?.italic).toBe(true);
+  });
+
+  it("identifies the default paragraph style", () => {
+    const table = loadTable();
+    expect(table.defaultParagraphStyleId).toBe("Normal");
+  });
+});
+
+describe("resolveParagraphProperties", () => {
+  it("applies defaults when no style or direct properties", () => {
+    const table = loadTable();
+    const resolved = resolveParagraphProperties(table, {
+      ...EMPTY_PARAGRAPH_PROPERTIES,
+    });
+    expect(resolved.spacing?.after).toBe(160);
+    expect(resolved.spacing?.line).toBe(259);
+  });
+
+  it("walks the basedOn chain and overrides", () => {
+    const table = loadTable();
+    const resolved = resolveParagraphProperties(table, {
+      ...EMPTY_PARAGRAPH_PROPERTIES,
+      styleId: "Heading2",
+    });
+    expect(resolved.spacing?.before).toBe(240);
+    expect(resolved.spacing?.after).toBe(0);
+    expect(resolved.outlineLevel).toBe(1);
+    expect(resolved.keepNext).toBe(true);
+    expect(resolved.styleId).toBe("Heading2");
+  });
+
+  it("direct properties override style chain", () => {
+    const table = loadTable();
+    const resolved = resolveParagraphProperties(table, {
+      ...EMPTY_PARAGRAPH_PROPERTIES,
+      styleId: "Heading1",
+      alignment: "center",
+    });
+    expect(resolved.alignment).toBe("center");
+    expect(resolved.outlineLevel).toBe(0);
+  });
+});
+
+describe("resolveRunProperties", () => {
+  it("applies run defaults", () => {
+    const table = loadTable();
+    const resolved = resolveRunProperties(table, null, {
+      ...EMPTY_RUN_PROPERTIES,
+    });
+    expect(resolved.fontAscii).toBe("Calibri");
+    expect(resolved.size).toBe(22);
+  });
+
+  it("inherits from paragraph style's run properties", () => {
+    const table = loadTable();
+    const resolved = resolveRunProperties(table, "Heading1", {
+      ...EMPTY_RUN_PROPERTIES,
+    });
+    expect(resolved.bold).toBe(true);
+    expect(resolved.size).toBe(32);
+    expect(resolved.fontAscii).toBe("Calibri");
+  });
+
+  it("character style overrides paragraph style", () => {
+    const table = loadTable();
+    const resolved = resolveRunProperties(table, "Heading1", {
+      ...EMPTY_RUN_PROPERTIES,
+      styleId: "Emphasis",
+    });
+    expect(resolved.bold).toBe(true);
+    expect(resolved.italic).toBe(true);
+    expect(resolved.size).toBe(32);
+  });
+
+  it("direct properties override everything", () => {
+    const table = loadTable();
+    const resolved = resolveRunProperties(table, "Heading1", {
+      ...EMPTY_RUN_PROPERTIES,
+      bold: false,
+      size: 18,
+    });
+    expect(resolved.bold).toBe(false);
+    expect(resolved.size).toBe(18);
+  });
+});
+
+describe("extract* property helpers", () => {
+  it("treats <w:b/> as toggle on, <w:b w:val=\"0\"/> as off", () => {
+    const xmlOn = parseXml(`<w:rPr xmlns:w="x"><w:b/></w:rPr>`)[0];
+    const xmlOff = parseXml(
+      `<w:rPr xmlns:w="x"><w:b w:val="0"/></w:rPr>`,
+    )[0];
+    expect(getTagName(xmlOn)).toBe("w:rPr");
+    expect(extractRunProperties(getChildren(xmlOn)).bold).toBe(true);
+    expect(extractRunProperties(getChildren(xmlOff)).bold).toBe(false);
+  });
+
+  it("parses indent attributes including start/end aliases", () => {
+    const el = parseXml(
+      `<w:pPr xmlns:w="x"><w:ind w:start="720" w:firstLine="360"/></w:pPr>`,
+    )[0];
+    const props = extractParagraphProperties(getChildren(el));
+    expect(props.indent).toEqual({
+      left: 720,
+      right: null,
+      firstLine: 360,
+      hanging: null,
+    });
+  });
+
+  it("parses numPr (numId + ilvl)", () => {
+    const el = parseXml(
+      `<w:pPr xmlns:w="x"><w:numPr><w:ilvl w:val="2"/><w:numId w:val="3"/></w:numPr></w:pPr>`,
+    )[0];
+    const props = extractParagraphProperties(getChildren(el));
+    expect(props.numbering).toEqual({ numId: 3, ilvl: 2 });
+  });
+});

package/src/model/style_resolution.ts

@@ -0,0 +1,113 @@
+import {
+  EMPTY_PARAGRAPH_PROPERTIES,
+  EMPTY_RUN_PROPERTIES,
+  type ParagraphProperties,
+  type RunProperties,
+} from "./properties";
+import type { Style, StyleTable } from "./style_table";
+
+function mergeParagraph(
+  base: ParagraphProperties,
+  overlay: ParagraphProperties,
+): ParagraphProperties {
+  return {
+    styleId: overlay.styleId ?? base.styleId,
+    alignment: overlay.alignment ?? base.alignment,
+    indent: overlay.indent ?? base.indent,
+    spacing: overlay.spacing ?? base.spacing,
+    numbering: overlay.numbering ?? base.numbering,
+    pageBreakBefore: overlay.pageBreakBefore ?? base.pageBreakBefore,
+    keepLines: overlay.keepLines ?? base.keepLines,
+    keepNext: overlay.keepNext ?? base.keepNext,
+    widowControl: overlay.widowControl ?? base.widowControl,
+    outlineLevel: overlay.outlineLevel ?? base.outlineLevel,
+  };
+}
+
+function mergeRun(base: RunProperties, overlay: RunProperties): RunProperties {
+  return {
+    styleId: overlay.styleId ?? base.styleId,
+    bold: overlay.bold ?? base.bold,
+    italic: overlay.italic ?? base.italic,
+    underline: overlay.underline ?? base.underline,
+    strike: overlay.strike ?? base.strike,
+    doubleStrike: overlay.doubleStrike ?? base.doubleStrike,
+    caps: overlay.caps ?? base.caps,
+    smallCaps: overlay.smallCaps ?? base.smallCaps,
+    color: overlay.color ?? base.color,
+    themeColor: overlay.themeColor ?? base.themeColor,
+    themeTint: overlay.themeTint ?? base.themeTint,
+    themeShade: overlay.themeShade ?? base.themeShade,
+    highlight: overlay.highlight ?? base.highlight,
+    size: overlay.size ?? base.size,
+    fontAscii: overlay.fontAscii ?? base.fontAscii,
+    fontHAnsi: overlay.fontHAnsi ?? base.fontHAnsi,
+    fontEastAsia: overlay.fontEastAsia ?? base.fontEastAsia,
+    fontComplexScript: overlay.fontComplexScript ?? base.fontComplexScript,
+    vertAlign: overlay.vertAlign ?? base.vertAlign,
+  };
+}
+
+function styleChain(table: StyleTable, styleId: string | null): Style[] {
+  if (!styleId) return [];
+  const chain: Style[] = [];
+  const visited = new Set<string>();
+  let current: string | null = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const style = table.styles.get(current);
+    if (!style) break;
+    chain.unshift(style);
+    current = style.basedOn;
+  }
+  return chain;
+}
+
+export function resolveParagraphProperties(
+  table: StyleTable,
+  direct: ParagraphProperties,
+): ParagraphProperties {
+  let result = { ...table.paragraphDefaults };
+
+  const referencedStyleId = direct.styleId ?? table.defaultParagraphStyleId;
+  for (const style of styleChain(table, referencedStyleId)) {
+    if (style.paragraphProperties) {
+      result = mergeParagraph(result, style.paragraphProperties);
+    }
+  }
+
+  result = mergeParagraph(result, direct);
+  return result;
+}
+
+export function resolveRunProperties(
+  table: StyleTable,
+  paragraphStyleId: string | null,
+  directRun: RunProperties,
+): RunProperties {
+  let result = { ...table.runDefaults };
+
+  for (const style of styleChain(table, paragraphStyleId)) {
+    if (style.runProperties) {
+      result = mergeRun(result, style.runProperties);
+    }
+  }
+
+  const characterStyleId = directRun.styleId;
+  for (const style of styleChain(table, characterStyleId)) {
+    if (style.runProperties) {
+      result = mergeRun(result, style.runProperties);
+    }
+  }
+
+  result = mergeRun(result, directRun);
+  return result;
+}
+
+export function emptyResolvedParagraphProperties(): ParagraphProperties {
+  return { ...EMPTY_PARAGRAPH_PROPERTIES };
+}
+
+export function emptyResolvedRunProperties(): RunProperties {
+  return { ...EMPTY_RUN_PROPERTIES };
+}

package/src/model/style_table.ts

@@ -0,0 +1,22 @@
+import type { ParagraphProperties, RunProperties } from "./properties";
+
+export type StyleType = "paragraph" | "character" | "table" | "numbering";
+
+export type Style = {
+  id: string;
+  name: string | null;
+  type: StyleType;
+  basedOn: string | null;
+  linkedStyleId: string | null;
+  paragraphProperties: ParagraphProperties | null;
+  runProperties: RunProperties | null;
+  isDefault: boolean;
+};
+
+export type StyleTable = {
+  paragraphDefaults: ParagraphProperties;
+  runDefaults: RunProperties;
+  styles: ReadonlyMap<string, Style>;
+  defaultParagraphStyleId: string | null;
+  defaultCharacterStyleId: string | null;
+};

package/src/model/theme.ts

@@ -0,0 +1,156 @@
+export type ThemeColorName =
+  | "dk1"
+  | "lt1"
+  | "dk2"
+  | "lt2"
+  | "accent1"
+  | "accent2"
+  | "accent3"
+  | "accent4"
+  | "accent5"
+  | "accent6"
+  | "hlink"
+  | "folHlink";
+
+export type ThemeFontVariants = {
+  latin: string | null;
+  eastAsia: string | null;
+  complexScript: string | null;
+};
+
+export type ThemeTable = {
+  colors: ReadonlyMap<ThemeColorName, string>;
+  majorFonts: ThemeFontVariants;
+  minorFonts: ThemeFontVariants;
+};
+
+export const EMPTY_THEME_TABLE: ThemeTable = {
+  colors: new Map(),
+  majorFonts: { latin: null, eastAsia: null, complexScript: null },
+  minorFonts: { latin: null, eastAsia: null, complexScript: null },
+};
+
+const W_TO_THEME: Record<string, ThemeColorName> = {
+  text1: "dk1",
+  background1: "lt1",
+  text2: "dk2",
+  background2: "lt2",
+  accent1: "accent1",
+  accent2: "accent2",
+  accent3: "accent3",
+  accent4: "accent4",
+  accent5: "accent5",
+  accent6: "accent6",
+  hyperlink: "hlink",
+  followedHyperlink: "folHlink",
+  dark1: "dk1",
+  dark2: "dk2",
+  light1: "lt1",
+  light2: "lt2",
+};
+
+export function wThemeColorToScheme(name: string): ThemeColorName | null {
+  return W_TO_THEME[name] ?? null;
+}
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  const cleaned = hex.replace(/^#/, "");
+  if (cleaned.length !== 6) return null;
+  const r = Number.parseInt(cleaned.slice(0, 2), 16);
+  const g = Number.parseInt(cleaned.slice(2, 4), 16);
+  const b = Number.parseInt(cleaned.slice(4, 6), 16);
+  if (![r, g, b].every((v) => Number.isFinite(v))) return null;
+  return { r, g, b };
+}
+
+function rgbToHsl(r: number, g: number, b: number): { h: number; s: number; l: number } {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case rn:
+        h = (gn - bn) / d + (gn < bn ? 6 : 0);
+        break;
+      case gn:
+        h = (bn - rn) / d + 2;
+        break;
+      default:
+        h = (rn - gn) / d + 4;
+    }
+    h /= 6;
+  }
+  return { h, s, l };
+}
+
+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;
+}
+
+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 rgbToHex(rgb: { r: number; g: number; b: number }): string {
+  const to2 = (v: number) =>
+    Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0").toUpperCase();
+  return `${to2(rgb.r)}${to2(rgb.g)}${to2(rgb.b)}`;
+}
+
+function applyLumMod(
+  hex: string,
+  tint: number | null,
+  shade: number | null,
+): string {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return hex;
+  const hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
+  let newL = hsl.l;
+  if (tint !== null && tint > 0) {
+    const t = tint / 255;
+    newL = hsl.l * (1 - t) + t;
+  } else if (shade !== null && shade > 0) {
+    const s = shade / 255;
+    newL = hsl.l * s;
+  }
+  newL = Math.max(0, Math.min(1, newL));
+  return rgbToHex(hslToRgb(hsl.h, hsl.s, newL));
+}
+
+export function resolveThemeColor(
+  theme: ThemeTable,
+  themeColorName: string,
+  themeTint: string | null,
+  themeShade: string | null,
+): string | null {
+  const scheme = wThemeColorToScheme(themeColorName);
+  if (!scheme) return null;
+  const base = theme.colors.get(scheme);
+  if (!base) return null;
+  const tintNum = themeTint ? Number.parseInt(themeTint, 16) : null;
+  const shadeNum = themeShade ? Number.parseInt(themeShade, 16) : null;
+  return applyLumMod(base, tintNum, shadeNum);
+}

package/src/model/types.ts

@@ -0,0 +1,55 @@
+import type { XmlElement } from "@lotics/ooxml/xml";
+
+export type DocxDocument = {
+  readonly parts: ReadonlyMap<string, Uint8Array>;
+  readonly documentAttrs: Readonly<Record<string, string>>;
+  readonly body: Body;
+};
+
+export type Body = {
+  readonly children: readonly Block[];
+};
+
+export type Block = Paragraph | OpaqueBlock | BodySectPr;
+
+export type Paragraph = {
+  readonly kind: "paragraph";
+  readonly properties: readonly XmlElement[] | null;
+  readonly content: readonly Inline[];
+};
+
+export type Inline = Run | OpaqueInline;
+
+export type Run = {
+  readonly kind: "run";
+  readonly properties: readonly XmlElement[] | null;
+  readonly content: readonly RunChild[];
+};
+
+export type RunChild = TextNode | OpaqueRunChild;
+
+export type TextNode = {
+  readonly kind: "text";
+  readonly value: string;
+  readonly preserveSpace: boolean;
+};
+
+export type OpaqueBlock = {
+  readonly kind: "opaque_block";
+  readonly xml: XmlElement;
+};
+
+export type OpaqueInline = {
+  readonly kind: "opaque_inline";
+  readonly xml: XmlElement;
+};
+
+export type OpaqueRunChild = {
+  readonly kind: "opaque_run_child";
+  readonly xml: XmlElement;
+};
+
+export type BodySectPr = {
+  readonly kind: "body_sect_pr";
+  readonly xml: XmlElement;
+};