@portone/docx-editor 0.2.1 → 0.3.0

package/dist/docx/formatting/direct.js

@@ -1,56 +1,27 @@
 // src/docx/formatting/direct.ts
 import {
-  isHighlightName,
-  isUnderlineKind
+  RUN_FORMAT_KEYS
 } from "../../model/format.js";
-import { overridingAttrs } from "../../ooxml/precedence.js";
+import {
+  ST_DecimalNumber,
+  ST_SignedTwipsMeasure,
+  ST_TwipsMeasure,
+  TWIPS_PER_PT
+} from "../../ooxml/simpleTypes.js";
 import { readTabStopDirectives } from "../../ooxml/tabStops.js";
 import {
   ALIGN_BY_JC,
   borderSide,
   childValue,
-  halfPointsToPt,
   isOn,
   round,
   shadingOf,
-  toHexColor,
-  toNumber,
   twipsToPt,
   wAttr
 } from "../../ooxml/units.js";
 import { childByLocalName } from "../../ooxml/xml.js";
-import { NO_THEME_FONTS, themeFontName } from "../theme.js";
-var VERTICAL_ALIGN_BY_VAL = {
-  superscript: "superscript",
-  subscript: "subscript"
-};
-function fontNamesOf(cssNames) {
-  if (!cssNames) return [];
-  return cssNames.split(",").map((name) => name.trim().replace(/^"|"$/g, "")).filter((name) => name.length > 0);
-}
-var FONT_SLOTS = ["ascii", "eastAsia", "hAnsi", "cs"];
-function slotFontName(rFonts, slot, themeFonts) {
-  const written = wAttr(rFonts, slot);
-  if (written !== null) return written;
-  for (const attr of overridingAttrs("rFonts", slot)) {
-    const resolved = themeFontName(themeFonts, wAttr(rFonts, attr));
-    if (resolved !== null) return resolved;
-  }
-  return null;
-}
-function fontFamilyOf(rFonts, themeFonts) {
-  const names = FONT_SLOTS.map((slot) => slotFontName(rFonts, slot, themeFonts)).filter((name) => name !== null).filter((name) => name.length > 0 && !/["';\\]/.test(name));
-  const unique = Array.from(new Set(names));
-  return unique.length > 0 ? unique.map((name) => `"${name}"`).join(",") : null;
-}
-function langOf(rPr) {
-  const lang = childByLocalName(rPr, "lang");
-  if (!lang) return null;
-  const eastAsia = wAttr(lang, "eastAsia");
-  if (eastAsia !== null && eastAsia.length > 0) return eastAsia;
-  const value = wAttr(lang, "val");
-  return value !== null && value.length > 0 ? value : null;
-}
+import { NO_THEME_FONTS } from "../theme.js";
+import { RUN_PROPERTIES } from "./runProperties.js";
 function drawnBorder(pBdr, side) {
   const css = borderSide(pBdr, side);
   return css === "none" ? null : css;
@@ -73,33 +44,39 @@ function readIndent(pPr) {
   const ind = childByLocalName(pPr, "ind");
   if (!ind) return {};
   const format = {};
-  const start = twipsToPt(wAttr(ind, "start") ?? wAttr(ind, "left"));
+  const start = twipsToPt(
+    ST_SignedTwipsMeasure.parse(wAttr(ind, "start") ?? wAttr(ind, "left"))
+  );
   if (start !== null) format.indentStartPt = start;
-  const end = twipsToPt(wAttr(ind, "end") ?? wAttr(ind, "right"));
+  const end = twipsToPt(
+    ST_SignedTwipsMeasure.parse(wAttr(ind, "end") ?? wAttr(ind, "right"))
+  );
   if (end !== null) format.indentEndPt = end;
-  const hanging = twipsToPt(wAttr(ind, "hanging"));
-  const firstLine = twipsToPt(wAttr(ind, "firstLine"));
+  const hanging = twipsToPt(ST_TwipsMeasure.parse(wAttr(ind, "hanging")));
+  const firstLine = twipsToPt(ST_TwipsMeasure.parse(wAttr(ind, "firstLine")));
   if (hanging !== null) format.textIndentPt = -hanging;
   else if (firstLine !== null) format.textIndentPt = firstLine;
   return format;
 }
+var LINE_UNITS_PER_LINE = 240;
 function readLineSpacing(pPr) {
   const spacing = childByLocalName(pPr, "spacing");
   if (!spacing) return null;
-  const line = toNumber(wAttr(spacing, "line"));
+  const line = ST_SignedTwipsMeasure.parse(wAttr(spacing, "line"));
   if (line === null) return null;
   const rule = wAttr(spacing, "lineRule");
-  if (rule === "exact") return { rule: "exact", pt: round(line / 20) };
-  if (rule === "atLeast") return { rule: "atLeast", pt: round(line / 20) };
-  return { rule: "auto", lines: round(line / 240) };
+  const pt = round(line / TWIPS_PER_PT);
+  if (rule === "exact") return { rule: "exact", pt };
+  if (rule === "atLeast") return { rule: "atLeast", pt };
+  return { rule: "auto", lines: round(line / LINE_UNITS_PER_LINE) };
 }
 function readSpacing(pPr) {
   const spacing = childByLocalName(pPr, "spacing");
   if (!spacing) return {};
   const format = {};
-  const before = twipsToPt(wAttr(spacing, "before"));
+  const before = twipsToPt(ST_TwipsMeasure.parse(wAttr(spacing, "before")));
   if (before !== null) format.spaceBeforePt = before;
-  const after = twipsToPt(wAttr(spacing, "after"));
+  const after = twipsToPt(ST_TwipsMeasure.parse(wAttr(spacing, "after")));
   if (after !== null) format.spaceAfterPt = after;
   const lineSpacing = readLineSpacing(pPr);
   if (lineSpacing) format.lineSpacing = lineSpacing;
@@ -108,13 +85,13 @@ function readSpacing(pPr) {
 function readNumbering(pPr) {
   const numPr = childByLocalName(pPr, "numPr");
   if (!numPr) return {};
-  const numId = toNumber(childValue(numPr, "numId"));
+  const numId = ST_DecimalNumber.parse(childValue(numPr, "numId"));
   if (numId === 0) return { numbering: null };
   if (numId === null || numId < 0) return {};
   return {
     numbering: {
-      numId: Math.trunc(numId),
-      ilvl: Math.trunc(toNumber(childValue(numPr, "ilvl")) ?? 0)
+      numId,
+      ilvl: ST_DecimalNumber.parse(childValue(numPr, "ilvl")) ?? 0
     }
   };
 }
@@ -134,34 +111,23 @@ function readParagraphFormat(pPr) {
     format.direction = isOn(pPr, "bidi") ? "rtl" : "ltr";
   }
   if (isOn(pPr, "pageBreakBefore")) format.pageBreakBefore = true;
+  if (childByLocalName(pPr, "keepNext")) {
+    format.keepNext = isOn(pPr, "keepNext");
+  }
   const background = shadingOf(pPr);
   if (background) format.background = background;
   return format;
 }
+function readRunProperty(format, key, rPr, themeFonts) {
+  const value = RUN_PROPERTIES[key].read(rPr, themeFonts);
+  if (value !== void 0) format[key] = value;
+}
 function readRunFormat(rPr, themeFonts = NO_THEME_FONTS) {
   if (!rPr) return null;
   const format = {};
-  if (isOn(rPr, "b")) format.bold = true;
-  if (isOn(rPr, "i")) format.italic = true;
-  if (isOn(rPr, "strike")) format.strike = true;
-  if (isOn(rPr, "smallCaps")) format.smallCaps = true;
-  const underline = childValue(rPr, "u");
-  if (isUnderlineKind(underline)) format.underline = underline;
-  const fontSizePt = halfPointsToPt(childValue(rPr, "sz"));
-  if (fontSizePt !== null) format.fontSizePt = fontSizePt;
-  const rFonts = childByLocalName(rPr, "rFonts");
-  const fontFamily = rFonts ? fontFamilyOf(rFonts, themeFonts) : null;
-  if (fontFamily) format.fontFamily = fontFamily;
-  const color = toHexColor(childValue(rPr, "color"));
-  if (color) format.color = color;
-  const highlight = childValue(rPr, "highlight");
-  if (isHighlightName(highlight)) format.highlight = highlight;
-  const background = shadingOf(rPr);
-  if (background) format.background = background;
-  const verticalAlign = VERTICAL_ALIGN_BY_VAL[childValue(rPr, "vertAlign") ?? ""];
-  if (verticalAlign) format.verticalAlign = verticalAlign;
-  const lang = langOf(rPr);
-  if (lang) format.lang = lang;
+  for (const key of RUN_FORMAT_KEYS) {
+    readRunProperty(format, key, rPr, themeFonts);
+  }
   return format;
 }
 var NO_DOCUMENT_DEFAULTS = {
@@ -177,22 +143,30 @@ function defaultProperties(styles, slot, name) {
 function readDefaultParagraphFormat(styles) {
   return readParagraphFormat(defaultProperties(styles, "pPrDefault", "pPr")) ?? {};
 }
+function readRunDefaults(styles, themeFonts = NO_THEME_FONTS) {
+  return readRunFormat(defaultProperties(styles, "rPrDefault", "rPr"), themeFonts) ?? {};
+}
+function runStyleIdOf(rPr) {
+  const id = rPr ? childValue(rPr, "rStyle") : null;
+  return id !== null && id.length > 0 ? id : null;
+}
 function readDocumentDefaults(styles, themeFonts = NO_THEME_FONTS) {
-  const rPr = defaultProperties(styles, "rPrDefault", "rPr");
+  const run = readRunDefaults(styles, themeFonts);
   const pPr = defaultProperties(styles, "pPrDefault", "pPr");
-  const rFonts = rPr ? childByLocalName(rPr, "rFonts") : null;
   return {
-    fontSizePt: rPr ? halfPointsToPt(childValue(rPr, "sz")) : null,
-    fontFamily: rFonts ? fontFamilyOf(rFonts, themeFonts) : null,
+    fontSizePt: run.fontSizePt ?? null,
+    fontFamily: run.fontFamily ?? null,
     lineSpacing: pPr ? readLineSpacing(pPr) : null
   };
 }
 export {
+  LINE_UNITS_PER_LINE,
   NO_DOCUMENT_DEFAULTS,
-  fontNamesOf,
   readDefaultParagraphFormat,
   readDocumentDefaults,
   readLineSpacing,
   readParagraphFormat,
-  readRunFormat
+  readRunDefaults,
+  readRunFormat,
+  runStyleIdOf
 };

package/dist/docx/formatting/resolve.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolves the §17.7.2 hierarchy for one paragraph and for the runs inside it.
+ *
+ * The layers are put in order here and nowhere else, so a paragraph's display values are the
+ * same whichever path asked for them: opening the document, an edit, a paste, or a paragraph an
+ * edit built from nothing.
+ */
+import { type ParagraphFormat, type RunFormat } from "../../model/format";
+import type { TabStop } from "../../model/tabStops";
+import type { TableStyleOverrideType } from "../tableFormatting";
+import type { FormattingContext } from "./context";
+/** Where a paragraph sits when it is inside a table cell. null for body text */
+export interface ParagraphPlacement {
+    tableStyleId: string | null;
+    /**
+     * The conditional formats the cell takes, lowest first. Not read yet: a table style
+     * contributes the values it lays down for the whole table alone
+     */
+    conditions: readonly TableStyleOverrideType[];
+}
+/**
+ * The layer of the hierarchy a tab stop came from. Removing an inherited stop means writing a
+ * `clear` over it, while a direct one is deleted from the paragraph's own list, which is what a
+ * ruler needs to tell apart. The document defaults and a table style count as `style`, since a
+ * stop from either is taken away the same way
+ */
+export type TabStopLayer = "numbering" | "style" | "direct" | "implicit";
+export interface LayeredTabStop extends TabStop {
+    layer: TabStopLayer;
+}
+export interface ResolvedParagraph {
+    /** `format` in `schema`: docDefaults < table style < numbering level < paragraph style < direct */
+    format: ParagraphFormat | null;
+    /** `styleRun` in `schema`: run defaults < table style rPr < paragraph style rPr. Default font and size stay in CSS variables */
+    styleRun: RunFormat | null;
+    /** Everything below a run's own formatting, docDefaults included. What a removed run property falls back to */
+    inheritedRun: RunFormat;
+    /** The stops `format.tabStops` holds, each with the layer that laid it down */
+    tabStops: readonly LayeredTabStop[];
+}
+export declare function resolveParagraph(pPr: string | null, context: FormattingContext, placement?: ParagraphPlacement | null): ResolvedParagraph;
+/** `format` on a run mark: paragraph.styleRun < character style < the run's own rPr */
+export declare function resolveRun(rPr: string | null, paragraph: ResolvedParagraph, context: FormattingContext): RunFormat | null;
+/** paragraph.inheritedRun < character style. What a run property taken out of the rPr falls back to */
+export declare function inheritedRunFormat(rPr: string | null, paragraph: ResolvedParagraph, context: FormattingContext): RunFormat;

package/dist/docx/formatting/resolve.js

@@ -0,0 +1,140 @@
+// src/docx/formatting/resolve.ts
+import {
+  toParagraphFormat
+} from "../../model/format.js";
+import {
+  levelIndentPt
+} from "../../numbering/parseNumbering.js";
+import { parsePropsXml } from "../../ooxml/props.js";
+import { readParagraphFormat, readRunFormat, runStyleIdOf } from "./direct.js";
+import {
+  layerRunFormat,
+  paragraphStyleFormat
+} from "./styles.js";
+function directLayer(pPr) {
+  return pPr === null ? {} : readParagraphFormat(parsePropsXml(pPr)) ?? {};
+}
+function tableStyleOf(placement, context) {
+  const id = placement?.tableStyleId ?? null;
+  return id === null ? void 0 : context.styles.get(id);
+}
+function numberingLevelOf(layers, context) {
+  const ref = layers.reduce(
+    (found, layer) => layer.numbering === void 0 ? found : layer.numbering,
+    void 0
+  );
+  if (!ref) return void 0;
+  return context.numbering.lists.get(ref.numId)?.levels.get(ref.ilvl);
+}
+function numberingLayer(level) {
+  return level?.tabStops ? { tabStops: level.tabStops } : {};
+}
+function layerValues(base, over) {
+  const { tabStops: _stops, ...values } = over;
+  return { ...base, ...values };
+}
+function byPosition(left, right) {
+  return left.positionPt - right.positionPt;
+}
+function explicitStops(layers) {
+  const spoken = /* @__PURE__ */ new Map();
+  for (const { values, stops } of layers) {
+    for (const stop of values.tabStops ?? []) {
+      spoken.set(stop.positionPt, { stop, layer: stops });
+    }
+  }
+  return [...spoken.values()].flatMap(
+    ({ stop, layer }) => stop.align === "clear" ? [] : [{ ...stop, layer }]
+  ).sort(byPosition);
+}
+function hangingStopPt(values, level) {
+  const leading = values.indentStartPt ?? values.indentLeftPt ?? level.startPt;
+  const textIndent = values.textIndentPt ?? level.textIndentPt;
+  return leading !== null && textIndent !== null && textIndent < 0 ? leading : null;
+}
+function withImplicitStop(stops, positionPt) {
+  if (positionPt === null) return stops;
+  if (stops.some((stop) => stop.positionPt === positionPt)) return stops;
+  const implicit = {
+    positionPt,
+    align: "start",
+    layer: "implicit"
+  };
+  return [...stops, implicit].sort(byPosition);
+}
+function orNull(values) {
+  return Object.keys(values).length === 0 ? null : values;
+}
+function resolveParagraph(pPr, context, placement = null) {
+  const tableStyle = tableStyleOf(placement, context);
+  const style = paragraphStyleFormat(
+    pPr,
+    context.styles,
+    context.defaultParagraphStyleId
+  );
+  const direct = directLayer(pPr);
+  const explicit = [
+    { values: context.paragraphDefaults, stops: "style" },
+    { values: tableStyle?.paragraph ?? {}, stops: "style" },
+    { values: style?.paragraph ?? {}, stops: "style" },
+    { values: direct, stops: "direct" }
+  ];
+  const level = numberingLevelOf(
+    explicit.map((layer) => layer.values),
+    context
+  );
+  const layers = [
+    ...explicit.slice(0, 2),
+    { values: numberingLayer(level), stops: "numbering" },
+    ...explicit.slice(2)
+  ];
+  const values = layers.reduce(
+    (base, layer) => layerValues(base, layer.values),
+    {}
+  );
+  const stops = explicitStops(layers);
+  const tabStops = context.compat.noTabHangInd ? stops : withImplicitStop(
+    stops,
+    hangingStopPt(values, levelIndentPt(level?.indent ?? null))
+  );
+  const format = toParagraphFormat(values) ?? {};
+  if (tabStops.length > 0) {
+    format.tabStops = tabStops.map(({ layer: _layer, ...stop }) => stop);
+  }
+  const {
+    fontSizePt: _size,
+    fontFamily: _font,
+    ...displayDefaults
+  } = context.runDefaults;
+  const styleRun = {
+    ...displayDefaults,
+    ...tableStyle?.run,
+    ...style?.run
+  };
+  return {
+    format: orNull(format),
+    styleRun: orNull(styleRun),
+    inheritedRun: { ...context.runDefaults, ...styleRun },
+    tabStops
+  };
+}
+function characterStyleRun(rPr, context) {
+  const id = runStyleIdOf(rPr);
+  return id === null ? {} : context.styles.get(id)?.run ?? {};
+}
+function resolveRun(rPr, paragraph, context) {
+  const el = rPr === null ? null : parsePropsXml(rPr);
+  return layerRunFormat(
+    { ...paragraph.styleRun, ...characterStyleRun(el, context) },
+    readRunFormat(el, context.themeFonts)
+  );
+}
+function inheritedRunFormat(rPr, paragraph, context) {
+  const el = rPr === null ? null : parsePropsXml(rPr);
+  return { ...paragraph.inheritedRun, ...characterStyleRun(el, context) };
+}
+export {
+  inheritedRunFormat,
+  resolveParagraph,
+  resolveRun
+};

package/dist/docx/formatting/runProperties.d.ts

@@ -0,0 +1,93 @@
+/**
+ * One row per run property: what it reads out of an rPr, what it writes into one, and whether
+ * text already carries a value.
+ *
+ * Reading, writing and comparing used to be three hand-kept copies of the same vocabulary, so a
+ * property could be read under one name and written under another. Here each is one row, and the
+ * readers and writers below walk the table, so anything else that has to speak for a run
+ * property - a tracked change's `w:rPrChange` snapshot, a style's `w:rPr` - asks the same row.
+ *
+ * The values read are for display only. What goes back into the document is the rPr string, and
+ * a write is a list of children swapped into it (`ooxml/props`), never a tree serialized again.
+ */
+import { type RunFormat } from "../../model/format";
+import { type Props } from "../../ooxml/props";
+import { type ThemeFonts } from "../theme";
+/** What text one child of the rPr is to be changed to. A null xml removes that child */
+export type ChildEdit = readonly [name: string, xml: string | null];
+/** What an edit is written against: the rPr as it stands, and everything the layers below the run lay down */
+export interface RunEditContext {
+    rPr: Props;
+    inherited: RunFormat;
+}
+type Read<K extends keyof RunFormat> = NonNullable<RunFormat[K]>;
+/**
+ * The value an edit sets. An off - `false`, an underline of `none` - is not one: it is spelled
+ * as null, the withdrawal, and pinned into the rPr only where the layers below would otherwise
+ * show through.
+ */
+export type RunSetting<K extends keyof RunFormat> = Exclude<Read<K>, false | "none">;
+/** A run property as it is read and compared. `R` is the value read, `S` the value an edit sets */
+export interface RunProperty<R, S> {
+    /**
+     * The rPr children the property owns, in the order CT_RPr lays them down. A `w:rPrChange`
+     * snapshot of the property is exactly these
+     */
+    readonly children: readonly string[];
+    read(rPr: Element, themeFonts: ThemeFonts): R | undefined;
+    /** Whether the display values switch or paint the property on, which is what a withdrawal has to undo */
+    isOn(format: RunFormat): boolean;
+    /** Whether the display values already carry the value, so that writing it would change nothing */
+    matches(format: RunFormat, value: S): boolean;
+}
+/** A run property an edit may write as well */
+export interface EditableRunProperty<R, S> extends RunProperty<R, S> {
+    /** The children that make the run say the value. null for a value the document cannot record */
+    write(value: S, context: RunEditContext): ChildEdit[] | null;
+    /** The children that take the run's own say away, pinned off where the layers below would otherwise show through */
+    off(context: RunEditContext): ChildEdit[];
+}
+/** The properties read for display alone. Nothing writes them, so no edit names them */
+declare const DISPLAY_ONLY_RUN_KEYS: readonly ["lang"];
+type DisplayOnlyRunKey = (typeof DISPLAY_ONLY_RUN_KEYS)[number];
+export type EditableRunKey = Exclude<keyof RunFormat, DisplayOnlyRunKey>;
+/**
+ * A job that changes one run property. A null value withdraws the run's own setting: the layers
+ * below stand again, except where they would switch or paint the property on, in which case the
+ * off is pinned into the run.
+ */
+export type RunEdit<K extends EditableRunKey = EditableRunKey> = {
+    [P in K]: {
+        key: P;
+        value: RunSetting<P> | null;
+    };
+}[K];
+/** The settings an rPr built from nothing records */
+export type RunSettings = {
+    [K in EditableRunKey]?: RunSetting<K>;
+};
+/** The editable properties, in the order they are read */
+export declare const EDITABLE_RUN_KEYS: readonly EditableRunKey[];
+/**
+ * The font names held in a display value.
+ * Splits the CSS name list `fontFamilyOf` produced back into individual names.
+ */
+export declare function fontNamesOf(cssNames: string | undefined | null): string[];
+export declare const RUN_PROPERTIES: {
+    [K in keyof Required<RunFormat>]: RunProperty<Read<K>, RunSetting<K>>;
+};
+/** Which children of the rPr one job changes and how. null for a value whose meaning cannot be made out */
+export declare function runChildEdits<K extends EditableRunKey>(edit: RunEdit<K>, context: RunEditContext): ChildEdit[] | null;
+/** Whether this text is already in the state the job wants. If it already is, we leave it untouched */
+export declare function matchesRunEdit<K extends EditableRunKey>(format: RunFormat | null, edit: RunEdit<K>): boolean;
+/** The rPr with these children swapped in */
+export declare function withChildEdits(rPr: Props, edits: readonly ChildEdit[]): Props;
+/** Turning formatting on for a run with no formatting creates a minimal rPr from scratch */
+export declare const EMPTY_RUN_PROPS: Props;
+/**
+ * A whole rPr recording these settings, built from nothing, and null where they record nothing.
+ * A setting the document cannot record is left out, the way an edit refusing it leaves the run
+ * as it was.
+ */
+export declare function rPrOf(settings: RunSettings): string | null;
+export {};