@portone/docx-editor 0.2.1 → 0.4.0

package/dist/docx/tableFormatting/editing.js

@@ -1,21 +1,25 @@
 // src/docx/tableFormatting/editing.ts
-import { attrPairs, elementXml } from "../../ooxml/element.js";
+import { elementXml, wAttrValue } from "../../ooxml/element.js";
 import { wName } from "../../ooxml/names.js";
 import { setAttr } from "../../ooxml/precedence.js";
-import { normalizeHex, wAttr } from "../../ooxml/units.js";
-import { childByLocalName } from "../../ooxml/xml.js";
 import {
+  childElement,
+  editChild,
   parseProps,
   parsePropsXml,
   propsChild,
   renderProps,
-  setPropsChild,
-  TC_PR_ORDER,
-  TR_PR_ORDER
-} from "../propsXml.js";
+  setChild,
+  withAttrs
+} from "../../ooxml/props.js";
 import {
-  NO_BORDER_DEFAULTS,
-  NO_CELL_MARGINS,
+  ST_EighthPointMeasure,
+  ST_TwipsMeasure,
+  TWIPS_PER_PT
+} from "../../ooxml/simpleTypes.js";
+import { normalizeHex } from "../../ooxml/units.js";
+import {
+  NO_CELL_DEFAULTS,
   readCellProps,
   readRowFormat
 } from "./reading.js";
@@ -25,18 +29,6 @@ var ALL_CELL_SIDES = [
   "left",
   "right"
 ];
-var TC_BORDERS_ORDER = [
-  "top",
-  "start",
-  "left",
-  "bottom",
-  "end",
-  "right",
-  "insideH",
-  "insideV",
-  "tl2br",
-  "tr2bl"
-];
 var SIDE_NAMES = {
   top: ["top"],
   bottom: ["bottom"],
@@ -46,22 +38,24 @@ var SIDE_NAMES = {
 var PRESET_BORDER_EIGHTHS = 4;
 var EMPTY_TC_PR = { tag: "w:tcPr", attrs: null, children: [] };
 function drawsLine(side) {
-  if (!side) return false;
-  const val = wAttr(side, "val");
+  if (side.tag === null) return false;
+  const val = wAttrValue(side.attrs, "val");
   return val !== null && val !== "nil" && val !== "none";
 }
 function sideAttrs(name, current, edit, fallback = null) {
   if (edit.kind === "color") {
     if (!drawsLine(current)) {
-      if (current || !fallback || fallback === "none") return null;
+      if (current.tag !== null || fallback === null || fallback.val === "none") {
+        return null;
+      }
       return inheritedBorderAttrs(fallback, edit.hex);
     }
-    return setAttr(attrPairs(current), name, "color", edit.hex ?? "auto");
+    return setAttr(current.attrs, name, "color", edit.hex ?? "auto");
   }
   if (edit.line === "none") {
-    return current ? setAttr(attrPairs(current), name, "val", "none") : [[wName("val"), "none"]];
+    return current.tag !== null ? setAttr(current.attrs, name, "val", "none") : [[wName("val"), "none"]];
   }
-  if (!current) {
+  if (current.tag === null) {
     return [
       [wName("val"), "single"],
       [wName("sz"), `${PRESET_BORDER_EIGHTHS}`],
@@ -70,217 +64,191 @@ function sideAttrs(name, current, edit, fallback = null) {
     ];
   }
   return setAttr(
-    setAttr(attrPairs(current), name, "val", "single"),
+    setAttr(current.attrs, name, "val", "single"),
     name,
     "sz",
     `${PRESET_BORDER_EIGHTHS}`
   );
 }
-var BORDER_VAL_BY_CSS_STYLE = {
-  solid: "single",
-  double: "double",
-  dashed: "dashed",
-  dotted: "dotted"
-};
-function inheritedBorderAttrs(border, hex) {
-  const matched = border.match(
-    /^(\d+(?:\.\d+)?)pt (solid|double|dashed|dotted) (#[0-9a-f]{6})$/i
-  );
-  if (!matched) return null;
-  const [, widthText, style, currentColor] = matched;
-  if (hex !== null && normalizeHex(currentColor) === hex) return null;
-  const eighths = Math.round(Number.parseFloat(widthText) * 8);
-  if (!Number.isSafeInteger(eighths) || eighths <= 0) return null;
+function inheritedBorderAttrs(line, hex) {
+  const current = line.color.kind === "rgb" ? normalizeHex(line.color.hex) : null;
+  if (hex !== null && current === hex) return null;
+  const thickness = ST_EighthPointMeasure.format(line.eighths);
+  if (thickness === null) return null;
   return [
-    [wName("val"), BORDER_VAL_BY_CSS_STYLE[style.toLowerCase()]],
-    [wName("sz"), `${eighths}`],
+    [wName("val"), line.val],
+    [wName("sz"), thickness],
     [wName("space"), "0"],
     [wName("color"), hex ?? "auto"]
   ];
 }
 function sideNames(borders, side) {
   const [primary, alternate] = SIDE_NAMES[side];
-  const usesAlternate = alternate !== void 0 && borders !== null && childByLocalName(borders, primary) === null && childByLocalName(borders, alternate) !== null;
+  const usesAlternate = alternate !== void 0 && propsChild(borders.children, primary) === void 0 && propsChild(borders.children, alternate) !== void 0;
   if (usesAlternate) return { write: alternate, drop: null };
   return { write: primary, drop: alternate ?? null };
 }
-function editedBorders(current, edit, defaults = NO_BORDER_DEFAULTS) {
-  const props = current === null ? { tag: "w:tcBorders", attrs: null, children: [] } : parseProps(current);
-  const borders = current === null ? null : parsePropsXml(current);
-  if (!props || current !== null && !borders) return null;
+function leafElement(tag, attrs) {
+  return withAttrs({ tag, attrs: null, children: [] }, attrs);
+}
+function containerOf(props, name) {
+  const current = propsChild(props.children, name)?.xml;
+  if (current === void 0) {
+    return { tag: wName(name), attrs: null, children: [] };
+  }
+  return parseProps(current);
+}
+function editedBorders(props, edit, defaults) {
+  const borders = containerOf(props, "tcBorders");
+  if (!borders) return null;
   const sides = edit.kind === "line" ? edit.sides : ALL_CELL_SIDES;
-  const edited = sides.reduce((kept, side) => {
+  return sides.reduce((kept, side) => {
+    if (kept === null) return null;
     const { write, drop } = sideNames(borders, side);
-    const currentSide = borders ? childByLocalName(borders, write) : null;
+    const currentSide = childElement(borders, write);
+    if (!currentSide) return null;
     const attrs = sideAttrs(write, currentSide, edit, defaults[side]);
     if (!attrs) return kept;
-    const tag = currentSide?.nodeName ?? wName(write);
-    const written = setPropsChild(
+    const written = editChild(
       kept,
-      write,
-      elementXml(tag, attrs),
-      TC_BORDERS_ORDER
+      ["tcBorders", write],
+      () => leafElement(currentSide.tag ?? wName(write), attrs)
     );
-    return drop === null ? written : setPropsChild(written, drop, null, TC_BORDERS_ORDER);
+    if (written === null || drop === null) return written;
+    return editChild(written, ["tcBorders", drop], () => null);
   }, props);
-  const xml = renderProps(edited);
-  return { xml: xml === "" ? null : xml };
 }
 function hasPattern(shd) {
-  const val = shd ? wAttr(shd, "val") : null;
+  const val = wAttrValue(shd.attrs, "val");
   return val !== null && val !== "clear" && val !== "nil";
 }
 function editedShading(current, fill) {
-  const tag = current?.nodeName ?? wName("shd");
+  const tag = current.tag ?? wName("shd");
   if (fill === null) {
     if (!hasPattern(current)) return null;
-    return elementXml(tag, setAttr(attrPairs(current), "shd", "fill", "auto"));
+    return elementXml(tag, setAttr(current.attrs, "shd", "fill", "auto"));
   }
-  if (!current) {
+  if (current.tag === null) {
     return elementXml(tag, [
       [wName("val"), "clear"],
       [wName("color"), "auto"],
       [wName("fill"), fill]
     ]);
   }
-  const painting = hasPattern(current) ? attrPairs(current) : setAttr(attrPairs(current), "shd", "val", "clear");
+  const painting = hasPattern(current) ? current.attrs : setAttr(current.attrs, "shd", "val", "clear");
   return elementXml(tag, setAttr(painting, "shd", "fill", fill));
 }
-function bordersChange(props, edit, defaults) {
-  const current = propsChild(props.children, "tcBorders")?.xml ?? null;
-  const edited = editedBorders(current, edit, defaults);
-  return edited === null ? null : { name: "tcBorders", xml: edited.xml };
-}
-var TC_MAR_ORDER = [
-  "top",
-  "start",
-  "left",
-  "bottom",
-  "end",
-  "right"
-];
 var MARGIN_SIDE_NAMES = {
   top: ["top"],
   right: ["end", "right"],
   bottom: ["bottom"],
   left: ["start", "left"]
 };
-function paddingChange(props, values) {
-  const current = propsChild(props.children, "tcMar")?.xml ?? null;
-  const margins = current === null ? null : parsePropsXml(current);
-  const parsed = current === null ? { tag: "w:tcMar", attrs: null, children: [] } : parseProps(current);
-  if (!parsed || current !== null && !margins) return null;
-  let edited = parsed;
+function editedPadding(props, values) {
+  const margins = containerOf(props, "tcMar");
+  if (!margins) return null;
+  let edited = props;
   let wrote = false;
   for (const side of ALL_CELL_SIDES) {
     const points = values[side];
     if (points === void 0) continue;
-    const twips = Math.round(points * 20);
-    if (!Number.isFinite(points) || points < 0 || !Number.isSafeInteger(twips)) {
-      return null;
-    }
-    const existing = margins ? MARGIN_SIDE_NAMES[side].map((name2) => childByLocalName(margins, name2)).find((element) => element !== null) ?? null : null;
-    const name = existing?.localName ?? side;
+    if (points < 0) return null;
+    const twips = ST_TwipsMeasure.format(Math.round(points * TWIPS_PER_PT));
+    if (twips === null) return null;
+    const name = MARGIN_SIDE_NAMES[side].find(
+      (spelling) => propsChild(margins.children, spelling) !== void 0
+    ) ?? side;
+    const existing = childElement(margins, name);
+    if (existing === null || edited === null) return null;
     const attrs = setAttr(
-      setAttr(attrPairs(existing), name, "w", `${twips}`),
+      setAttr(existing.attrs, name, "w", twips),
       name,
       "type",
       "dxa"
     );
-    edited = setPropsChild(
+    edited = editChild(
       edited,
-      name,
-      elementXml(existing?.nodeName ?? wName(side), attrs),
-      TC_MAR_ORDER
+      ["tcMar", name],
+      () => leafElement(existing.tag ?? wName(side), attrs)
     );
     wrote = true;
   }
-  if (!wrote) return null;
-  return { name: "tcMar", xml: renderProps(edited) };
+  return wrote ? edited : null;
 }
-function childChange(edit, props, defaults) {
+function editedProps(edit, props, defaults) {
   switch (edit.kind) {
     case "background": {
       const fill = edit.hex === null ? null : normalizeHex(edit.hex);
       if (edit.hex !== null && fill === null) return null;
-      const current = propsChild(props.children, "shd")?.xml ?? null;
-      const shd = current === null ? null : parsePropsXml(current);
-      if (current !== null && !shd) return null;
-      return { name: "shd", xml: editedShading(shd, fill) };
+      const shd = childElement(props, "shd");
+      if (!shd) return null;
+      return setChild(props, "shd", editedShading(shd, fill));
     }
     case "borders":
-      return bordersChange(
+      return editedBorders(
         props,
-        {
-          kind: "line",
-          line: edit.line,
-          sides: edit.sides
-        },
+        { kind: "line", line: edit.line, sides: edit.sides },
         defaults
       );
     case "borderColor": {
       const hex = edit.hex === null ? null : normalizeHex(edit.hex);
       if (edit.hex !== null && hex === null) return null;
-      return bordersChange(props, { kind: "color", hex }, defaults);
+      return editedBorders(props, { kind: "color", hex }, defaults);
     }
     case "verticalAlign": {
-      const current = propsChild(props.children, "vAlign")?.xml ?? null;
-      const element = current === null ? null : parsePropsXml(current);
-      if (current !== null && !element) return null;
-      return {
-        name: "vAlign",
-        xml: elementXml(
-          element?.nodeName ?? wName("vAlign"),
-          setAttr(attrPairs(element), "vAlign", "val", edit.align)
+      const current = childElement(props, "vAlign");
+      if (!current) return null;
+      return setChild(
+        props,
+        "vAlign",
+        elementXml(
+          current.tag ?? wName("vAlign"),
+          setAttr(current.attrs, "vAlign", "val", edit.align)
         )
-      };
+      );
     }
     case "padding":
-      return paddingChange(props, edit.values);
+      return editedPadding(props, edit.values);
   }
 }
-function editCellProps(tcPr, edit, defaults = NO_BORDER_DEFAULTS, margins = NO_CELL_MARGINS) {
+function editCellProps(tcPr, edit, defaults = NO_CELL_DEFAULTS) {
   const props = tcPr === null ? EMPTY_TC_PR : parseProps(tcPr);
   if (!props) return null;
-  const change = childChange(edit, props, defaults);
-  if (!change) return null;
-  const rendered = renderProps(
-    setPropsChild(props, change.name, change.xml, TC_PR_ORDER)
-  );
+  const edited = editedProps(edit, props, defaults.borders);
+  if (!edited) return null;
+  const rendered = renderProps(edited);
   const next = rendered === "" ? null : rendered;
   if (next === tcPr) return null;
-  return { tcPr: next, format: readCellProps(next, defaults, margins) };
+  return { tcPr: next, format: readCellProps(next, defaults) };
 }
 function drawsOwnCellBorder(tcPr) {
-  const el = tcPr === null ? null : parsePropsXml(tcPr);
-  const borders = el ? childByLocalName(el, "tcBorders") : null;
+  const props = tcPr === null ? null : parseProps(tcPr);
+  const borders = props && containerOf(props, "tcBorders");
   if (!borders) return false;
   return ALL_CELL_SIDES.some(
-    (side) => SIDE_NAMES[side].some((name) => drawsLine(childByLocalName(borders, name)))
+    (side) => SIDE_NAMES[side].some((name) => {
+      const element = childElement(borders, name);
+      return element !== null && drawsLine(element);
+    })
   );
 }
 function editRowHeight(trPr, heightPt) {
-  const twips = Math.round(heightPt * 20);
-  if (!Number.isFinite(heightPt) || heightPt <= 0 || !Number.isSafeInteger(twips)) {
-    return null;
-  }
-  const props = trPr === null ? { tag: "w:trPr", attrs: null, children: [] } : parseProps(trPr);
+  const twips = heightPt > 0 ? ST_TwipsMeasure.format(Math.round(heightPt * TWIPS_PER_PT)) : null;
+  if (twips === null) return null;
+  const props = trPr === null ? { tag: wName("trPr"), attrs: null, children: [] } : parseProps(trPr);
   if (!props) return null;
-  const current = propsChild(props.children, "trHeight")?.xml ?? null;
-  const element = current === null ? null : parsePropsXml(current);
-  if (current !== null && !element) return null;
-  const writtenRule = element ? wAttr(element, "hRule") : null;
-  const attrs = setAttr(attrPairs(element), "trHeight", "val", `${twips}`);
+  const current = childElement(props, "trHeight");
+  if (!current) return null;
+  const writtenRule = wAttrValue(current.attrs, "hRule");
+  const attrs = setAttr(current.attrs, "trHeight", "val", twips);
   const nextAttrs = setAttr(
     attrs,
     "trHeight",
     "hRule",
     writtenRule === "exact" ? "exact" : "atLeast"
   );
-  const child = elementXml(element?.nodeName ?? wName("trHeight"), nextAttrs);
-  const rendered = renderProps(
-    setPropsChild(props, "trHeight", child, TR_PR_ORDER)
-  );
+  const child = elementXml(current.tag ?? wName("trHeight"), nextAttrs);
+  const rendered = renderProps(setChild(props, "trHeight", child));
   if (rendered === trPr) return null;
   const parsed = parsePropsXml(rendered);
   const format = parsed ? readRowFormat(parsed) : null;

package/dist/docx/tableFormatting/reading.d.ts

@@ -2,15 +2,20 @@
  * Reads table formatting for display. Table borders and margins are folded into cell values so CSS
  * collapsed-border resolution matches OOXML inheritance without changing exported XML.
  */
-import type { CellFormat, CellMargins, InsideBorders, RowFormat, TableFormat, TableWidth } from "../../model/format";
-export type { CellMargins, InsideBorders } from "../../model/format";
+import { type BandSizes, type CellFormat, type CellMargins, type CellStyleFormat, type CellVerticalAlign, type InsideBorders, type RowFormat, type RunFormat, type TableFormat, type TableStyleConditions, type TableStyleOverrideType, type TableWidth } from "../../model/format";
+import { type BorderLine } from "../../ooxml/units";
+import type { ParagraphPlacement } from "../formatting/resolve";
+import type { ParagraphFormatLayer } from "../formatting/tabStops";
+export type { BandSizes, CellMargins, CellStyleFormat, InsideBorders, TableStyleConditions, TableStyleOverrideType, } from "../../model/format";
 /**
  * The width written down by `<w:tblW>` or `<w:tcW>`.
  * If we cannot make out what it means it is null, and such a width goes back out unchanged on export.
  *
- * `auto` and `nil` leave the width to the layout, so whatever number stands beside them says nothing.
+ * `auto` and `nil` leave the width to the layout unless the value carries an explicit percentage.
  * A percentage may be written in fiftieths of a percent, as in `w:w="2500"`, or as `w:w="50%"`.
  * Both have to be gathered into the same unit, or the table collapses into a thin strip on screen.
+ * Word lets an explicit `%` override `w:type` (MS-OI29500 §2.1.185(b)); see
+ * spec/notes/simpleTypes.md. A universal measure under `pct` remains unreadable here.
  */
 export declare function readTableWidth(parent: Element | null, name: "tblW" | "tcW"): TableWidth | null;
 /** The sequence of column widths (dxa) set by `<w:tblGrid>`. Revision markup (tblGridChange) is skipped */
@@ -32,15 +37,20 @@ export declare function readCellMarginsOf(parent: Element | null, name: "tblCell
  * their cell padding from.
  */
 export declare function layerCellMargins(style: CellMargins, direct: CellMargins): CellMargins;
-/** The lines a cell falls back on, one per side, already resolved for its spot in the grid */
+/**
+ * The lines a cell falls back on, one per side, already resolved for its spot in the grid.
+ *
+ * They are held as the markup records them rather than as CSS, because a cell that takes one of
+ * them over as a border of its own writes it back into `w:tcBorders`.
+ */
 export interface CellBorderDefaults {
-    top: string | null;
-    bottom: string | null;
-    left: string | null;
-    right: string | null;
+    top: BorderLine | null;
+    bottom: BorderLine | null;
+    left: BorderLine | null;
+    right: BorderLine | null;
 }
 export declare const NO_BORDER_DEFAULTS: CellBorderDefaults;
-/** Which sides of a cell lie on the edge of the table's grid */
+/** Which sides of a cell lie on the edge of a part of the table */
 export interface GridEdges {
     top: boolean;
     bottom: boolean;
@@ -59,19 +69,48 @@ export interface GridSize {
     cols: number;
 }
 /**
- * Which sides of the block a cell covers lie on the edge of the grid, merges included.
- * Everything that works out a cell's lines asks this first, whether the cell is being imported,
- * created fresh, or looked up again in a table on screen.
+ * Everything one cell falls back on for what it did not write down itself, worked out from where
+ * it sits in the grid by `cellDefaultsFor`. Everything that reads or edits a cell takes one of
+ * these, so the lines a cell draws and the lines an edit measures against are always the same.
  */
-export declare function gridEdgesOf(rect: GridRect, grid: GridSize): GridEdges;
+export interface CellDefaults {
+    borders: CellBorderDefaults;
+    margins: CellMargins;
+    background: string | null;
+    verticalAlign: CellVerticalAlign | null;
+    /** What the paragraphs inside the cell resolve their formatting against */
+    placement: ParagraphPlacement;
+}
+export declare const NO_CELL_DEFAULTS: CellDefaults;
+export declare const NO_BAND_SIZES: BandSizes;
+/** How many rows and columns one band of a table style is made of, read from the style's `w:tblPr` */
+export declare function readBandSizes(tblPr: Element | null): BandSizes;
+export declare function layerBandSizes(style: BandSizes, over: BandSizes): BandSizes;
+export declare const NO_CELL_STYLE_FORMAT: CellStyleFormat;
+export declare const NO_TABLE_STYLE_CONDITIONS: TableStyleConditions;
+/**
+ * The formatting one conditional format of a table style lays down (`w:tblStylePr`).
+ * Its `w:tblPr` speaks for the region as a whole and its `w:tcPr` for the cells in it, so the
+ * cell values are read with the table values underneath them.
+ */
+export interface ConditionalTableFormat {
+    paragraph: ParagraphFormatLayer;
+    run: RunFormat;
+    table: TableFormat;
+    cell: CellStyleFormat;
+}
 /**
- * The lines the four sides of one cell fall back on.
+ * What a conditional format lays down for the cells of its region.
  *
- * A side on the edge of the grid falls on the table's outer border, and one facing another cell on
- * the table's inside line. An outer side the document wrote as `none` is passed through as it is:
- * the table switched that line off, and nothing is to bring it back.
+ * The `w:tcPr` of a conditional format writes the lines of the region rather than of every cell in
+ * it: `insideH` and `insideV` are the lines between the cells it covers, which is how the header
+ * row of a style with `insideV` set to `nil` is drawn as one unbroken band.
  */
-export declare function cellBorderDefaults(edges: GridEdges, outer: TableFormat | null, inside: InsideBorders): CellBorderDefaults;
+export declare function readCellStyleFormat(tcPr: Element | null, tblPr: Element | null): CellStyleFormat;
+/** Lays one conditional format over the one a style further up the `basedOn` chain wrote for the same part */
+export declare function layerCellStyleFormat(base: CellStyleFormat, over: CellStyleFormat): CellStyleFormat;
+/** The conditions a table style lays down for its cells alone, which is what a table carries for its cells to draw */
+export declare function cellConditionsOf(conditions: Readonly<Partial<Record<TableStyleOverrideType, ConditionalTableFormat>>>): TableStyleConditions;
 /** The name of the table style `w:tblStyle` points at. null if it points at none */
 export declare function tblStyleIdOf(tblPr: Element | null): string | null;
 export declare function readTableFormat(tblPr: Element | null): TableFormat | null;
@@ -79,11 +118,12 @@ export declare function readRowFormat(trPr: Element | null): RowFormat | null;
 /**
  * Cell formatting.
  * A side for which the cell has not written down its own border uses the line that side falls on,
- * which is the table's outer border or its inside line depending on where the cell sits.
- * The padding works the same way: what the cell wrote down wins, and the table's cell margins lie
- * underneath it. null if there is nothing at all to draw.
+ * which is the table's outer border, its inside line, or the line a conditional format of its
+ * style draws there, depending on where the cell sits.
+ * The fill, the vertical alignment and the padding work the same way: what the cell wrote down
+ * wins, and what it falls back on lies underneath. null if there is nothing at all to draw.
  */
-export declare function readCellFormat(tcPr: Element | null, defaults: CellBorderDefaults, margins?: CellMargins): CellFormat | null;
+export declare function readCellFormat(tcPr: Element | null, defaults?: CellDefaults): CellFormat | null;
 /** The inside lines the table lays down, read from the table's own formatting XML */
 export declare function insideBordersOf(tblPr: string | null): InsideBorders;
 /** The cell margins the table lays down, read from the table's own formatting XML */
@@ -92,5 +132,5 @@ export declare function cellMarginsOf(tblPr: string | null): CellMargins;
  * Reads a cell formatting fragment we operated on back into display values, along the same path
  * the import takes. The same fragment always yields the same display values.
  */
-export declare function readCellProps(tcPr: string | null, defaults: CellBorderDefaults, margins?: CellMargins): CellFormat | null;
+export declare function readCellProps(tcPr: string | null, defaults?: CellDefaults): CellFormat | null;
 /** The formatting a cell holds. The original XML and the display values read out of it form a pair */