@portone/docx-editor 0.1.0

package/dist/docx/pageGeometry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The paper a document is written on: its size and its margins.
+ *
+ * A document says so in the `w:sectPr` at the end of its body. The values are read for the screen
+ * only: the `w:sectPr` itself rides out with the rest of the preserved tail, so what a document
+ * declares is never rewritten from these numbers.
+ *
+ * Everything here is in twips (1/1440 inch), the unit `w:pgSz` and `w:pgMar` are written in.
+ * The one derived value the rest of the editor asks for in two units is the body width, which
+ * a table writes down in twips and the sheet draws in pixels, so `bodyWidth` hands out both
+ * views of the one number rather than letting each caller convert for itself.
+ */
+/** The paper and the margins a section lays down, in twips */
+export interface PageGeometry {
+    /** The paper width. §17.6.13 `w:pgSz/@w:w` */
+    widthTwips: number;
+    /** The paper height. §17.6.13 `w:pgSz/@w:h` */
+    heightTwips: number;
+    marginLeftTwips: number;
+    marginRightTwips: number;
+    marginTopTwips: number;
+    marginBottomTwips: number;
+}
+export declare function twipsToPx(twips: number): number;
+/**
+ * The paper a document that says nothing is drawn on: A4 portrait with the margins this
+ * editor has always used.
+ *
+ * A document with no `w:sectPr`, or one whose `w:pgSz` cannot be read, is drawn on this, which
+ * is what every document was drawn on before the geometry was read at all.
+ */
+export declare const A4_PORTRAIT: PageGeometry;
+/**
+ * The geometry a `w:sectPr` element lays down, with anything it leaves unsaid taken from A4.
+ *
+ * `w:orient` is not applied on top of the size: Word writes the width and the height already
+ * swapped for a landscape section, so honouring both would turn the paper back upright.
+ */
+export declare function readPageGeometry(sectPr: Element | null): PageGeometry;
+/** The width one line of body text occupies: the paper less the side margins */
+export declare function bodyWidthTwips(geometry: PageGeometry): number;
+/** The height the body occupies on one page: the paper less the top and bottom margins */
+export declare function bodyHeightTwips(geometry: PageGeometry): number;
+/**
+ * The width of one line of body text, in both units the editor fits things to.
+ *
+ * A table writes its width down in twips (`w:tblW`, `w:tcW`) and the sheet draws an image in
+ * pixels, so the width a new table is divided into, the width a column drag stops at and the
+ * width an oversized image is shrunk to are all one number in two views.
+ */
+export interface BodyWidth {
+    /** dxa, the unit a table width is written in */
+    twips: number;
+    /** CSS pixels, the unit the sheet is drawn in */
+    px: number;
+}
+export declare function bodyWidth(geometry: PageGeometry): BodyWidth;
+/**
+ * The body width of the paper a document that names none is drawn on.
+ *
+ * It is what a caller with no document to ask still gets: 11906 - 1247 * 2 = 9412 dxa.
+ */
+export declare const A4_BODY_WIDTH: BodyWidth;
+/**
+ * The geometry of the first section of an already parsed body.
+ *
+ * A document may hold a `w:sectPr` per section, each with a paper of its own. The screen draws
+ * one paper for the whole document, so the first section decides it; the rest ride out
+ * untouched in their preserved blocks and are drawn on the first section's paper.
+ * `site/content/docs/features.mdx` records that limit.
+ *
+ * The reading is deliberately forgiving: this runs against a document already opened, and a
+ * `w:sectPr` we cannot read is a reason to draw A4, never a reason to refuse the file.
+ */
+export declare function readBodyGeometry(body: Element): PageGeometry;

package/dist/docx/pageGeometry.js

@@ -0,0 +1,88 @@
+// src/docx/pageGeometry.ts
+import { toNumber, wAttr } from "../ooxml/units.js";
+import { childByLocalName } from "../ooxml/xml.js";
+var TWIPS_PER_CM = 1440 / 2.54;
+var PX_PER_TWIP = 96 / 1440;
+function cm(value) {
+  return Math.round(value * TWIPS_PER_CM);
+}
+function twipsToPx(twips) {
+  return twips * PX_PER_TWIP;
+}
+var A4_PORTRAIT = {
+  widthTwips: cm(21),
+  heightTwips: cm(29.7),
+  marginLeftTwips: cm(2.2),
+  marginRightTwips: cm(2.2),
+  marginTopTwips: cm(2),
+  marginBottomTwips: cm(2)
+};
+var MIN_PAGE_TWIPS = cm(1);
+var MAX_PAGE_TWIPS = cm(600);
+function readSize(value) {
+  if (value === null) return null;
+  if (!Number.isFinite(value)) return null;
+  if (value < MIN_PAGE_TWIPS || value > MAX_PAGE_TWIPS) return null;
+  return Math.round(value);
+}
+function readMargin(value, fallback) {
+  if (value === null || !Number.isFinite(value)) return fallback;
+  if (value < 0) return 0;
+  return Math.min(Math.round(value), MAX_PAGE_TWIPS);
+}
+function readPageGeometry(sectPr) {
+  if (!sectPr) return A4_PORTRAIT;
+  const pgSz = childByLocalName(sectPr, "pgSz");
+  const pgMar = childByLocalName(sectPr, "pgMar");
+  const width = pgSz ? readSize(toNumber(wAttr(pgSz, "w"))) : null;
+  const height = pgSz ? readSize(toNumber(wAttr(pgSz, "h"))) : null;
+  const readable = width !== null && height !== null;
+  const marginLeft = pgMar ? toNumber(wAttr(pgMar, "left")) : null;
+  const marginRight = pgMar ? toNumber(wAttr(pgMar, "right")) : null;
+  const marginTop = pgMar ? toNumber(wAttr(pgMar, "top")) : null;
+  const marginBottom = pgMar ? toNumber(wAttr(pgMar, "bottom")) : null;
+  const geometry = {
+    widthTwips: readable ? width : A4_PORTRAIT.widthTwips,
+    heightTwips: readable ? height : A4_PORTRAIT.heightTwips,
+    marginLeftTwips: readMargin(marginLeft, A4_PORTRAIT.marginLeftTwips),
+    marginRightTwips: readMargin(marginRight, A4_PORTRAIT.marginRightTwips),
+    marginTopTwips: readMargin(marginTop, A4_PORTRAIT.marginTopTwips),
+    marginBottomTwips: readMargin(marginBottom, A4_PORTRAIT.marginBottomTwips)
+  };
+  return hasBody(geometry) ? geometry : A4_PORTRAIT;
+}
+function hasBody(geometry) {
+  return bodyWidthTwips(geometry) > 0 && bodyHeightTwips(geometry) > 0;
+}
+function bodyWidthTwips(geometry) {
+  return geometry.widthTwips - geometry.marginLeftTwips - geometry.marginRightTwips;
+}
+function bodyHeightTwips(geometry) {
+  return geometry.heightTwips - geometry.marginTopTwips - geometry.marginBottomTwips;
+}
+function bodyWidth(geometry) {
+  const twips = bodyWidthTwips(geometry);
+  return { twips, px: twipsToPx(twips) };
+}
+var A4_BODY_WIDTH = bodyWidth(A4_PORTRAIT);
+function readBodyGeometry(body) {
+  return readPageGeometry(firstSectPrIn(body));
+}
+function firstSectPrIn(root) {
+  const found = root.getElementsByTagName("w:sectPr").item(0);
+  if (found) return found;
+  for (const el of root.getElementsByTagName("*")) {
+    if (el.localName === "sectPr") return el;
+  }
+  return null;
+}
+export {
+  A4_BODY_WIDTH,
+  A4_PORTRAIT,
+  bodyHeightTwips,
+  bodyWidth,
+  bodyWidthTwips,
+  readBodyGeometry,
+  readPageGeometry,
+  twipsToPx
+};

package/dist/docx/paraProps.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Swaps out only the style name, the list slot, the indents, the spacing, and the alignment in a
+ * paragraph formatting fragment (`<w:pPr>`).
+ *
+ * When one paragraph is changed, the formatting we do not touch, such as tab stops and borders,
+ * must stay as the original text wrote it. So we never rebuild the fragment; we change it one child
+ * at a time, and within a child one attribute at a time.
+ * The fragment we operated on is read back with the parser used when opening the document to build
+ * the display values, and the style the paragraph points at is layered in the same order as it was
+ * then. That way a changed paragraph's display values are the same as they would be after saving
+ * and reopening.
+ */
+import type { LineSpacing, NumberingRef, ParagraphAlign, ParagraphFormat, RunFormat } from "../model/format";
+import type { LevelIndent } from "../numbering/parseNumbering";
+import { type StyleTable } from "./formatting";
+/** What to do with the indents */
+export type IndentChange = 
+/** Leaves the indents the paragraph wrote down as they are */
+{
+    kind: "keep";
+}
+/** Changes them to the indents the list level lays down */
+ | {
+    kind: "level";
+    indent: LevelIndent;
+}
+/** Removes only the hanging indent the marker used to sit in (when leaving a list) */
+ | {
+    kind: "clearHanging";
+};
+export interface ListChange {
+    /** The list slot this paragraph will belong to. null takes it out of the list */
+    numbering: NumberingRef | null;
+    indent: IndentChange;
+}
+/** The paragraph formatting we operated on, and the display values read back out of it */
+export interface ParagraphProps {
+    pPr: string | null;
+    format: ParagraphFormat | null;
+    /** The character formatting the style the paragraph now wears lays down (`styleRun` in `schema`) */
+    styleRun: RunFormat | null;
+}
+/**
+ * Reads the fragment we operated on back along the same path used when opening the document.
+ *
+ * The values of the style the paragraph wears are laid down underneath (the same order as import),
+ * which for a paragraph pointing at no style of its own is the document's default paragraph style.
+ */
+export declare function readParagraphProps(pPr: string | null, styles?: StyleTable, defaultStyleId?: string | null): ParagraphFormat | null;
+export declare function withListNumbering(pPr: string | null, change: ListChange, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+/**
+ * The result of moving the paragraph's own left indent to `leftTwips`.
+ * Everything else the indent recorded - the hanging or first-line indent, the right indent -
+ * stays as it was.
+ */
+export declare function withLeftIndent(pPr: string | null, leftTwips: number, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+/**
+ * The result of changing the line spacing. The space above and below the paragraph is left as it was.
+ * `auto` states the multiple in 240ths of a line; the other rules pin the height down in twips.
+ */
+export declare function withLineSpacing(pPr: string | null, spacing: LineSpacing, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+/**
+ * The result of pointing the paragraph at a named style.
+ * A null id takes the pStyle away, which is how the default style is worn.
+ *
+ * Nothing else in the fragment moves: as in Word, a style is applied by naming it and not by
+ * copying its values into the paragraph, so the direct formatting written here keeps beating it.
+ */
+export declare function withParagraphStyle(pPr: string | null, styleId: string | null, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;
+/**
+ * The result of changing the paragraph alignment.
+ * One alignment is always on, so we provide no way to withdraw the setting (the same as Word).
+ */
+export declare function withParagraphAlign(pPr: string | null, align: ParagraphAlign, styles?: StyleTable, defaultStyleId?: string | null): ParagraphProps | null;

package/dist/docx/paraProps.js

@@ -0,0 +1,167 @@
+// src/docx/paraProps.ts
+import { childByLocalName, escapeXml, localPart } from "../ooxml/xml.js";
+import {
+  layerParagraphFormat,
+  layerRunFormat,
+  NO_STYLES,
+  paragraphStyleFormat,
+  readParagraphFormat
+} from "./formatting.js";
+import {
+  P_PR_ORDER,
+  parseProps,
+  parsePropsXml,
+  renderProps,
+  setPropsChild
+} from "./propsXml.js";
+var LEFT_IND_ATTRS = ["left", "start", "leftChars", "startChars"];
+var LEFT_TWIPS_IND_ATTRS = ["left", "start"];
+var HANGING_IND_ATTRS = ["hanging", "hangingChars"];
+var FIRST_LINE_IND_ATTRS = [
+  ...HANGING_IND_ATTRS,
+  "firstLine",
+  "firstLineChars"
+];
+function readParagraphProps(pPr, styles = NO_STYLES, defaultStyleId = null) {
+  const direct = pPr === null ? null : readParagraphFormat(parsePropsXml(pPr));
+  const style = paragraphStyleFormat(pPr, styles, defaultStyleId);
+  return layerParagraphFormat(style?.paragraph ?? {}, direct);
+}
+function readParagraphStyleRun(pPr, styles = NO_STYLES, defaultStyleId = null) {
+  const style = paragraphStyleFormat(pPr, styles, defaultStyleId);
+  return layerRunFormat(style?.run ?? {}, null);
+}
+function numPrXml(ref) {
+  if (!ref) return null;
+  return `<w:numPr><w:ilvl w:val="${ref.ilvl}"/><w:numId w:val="${ref.numId}"/></w:numPr>`;
+}
+function keptIndAttrs(ind, dropped) {
+  if (!ind) return [];
+  return Array.from(ind.attributes).filter((attr) => !dropped.includes(localPart(attr.name))).map((attr) => [attr.name, attr.value]);
+}
+function levelIndAttrs(indent) {
+  const attrs = [];
+  if (indent.startTwips !== null)
+    attrs.push(["w:left", `${indent.startTwips}`]);
+  if (indent.hangingTwips !== null) {
+    attrs.push(["w:hanging", `${indent.hangingTwips}`]);
+  } else if (indent.firstLineTwips !== null) {
+    attrs.push(["w:firstLine", `${indent.firstLineTwips}`]);
+  }
+  return attrs;
+}
+function attrsXml(tag, attrs) {
+  if (attrs.length === 0) return null;
+  const text = attrs.map(([name, value]) => `${name}="${escapeXml(value)}"`).join(" ");
+  return `<${tag} ${text}/>`;
+}
+function indXml(attrs) {
+  return attrsXml("w:ind", attrs);
+}
+function nextIndXml(ind, change) {
+  if (change.kind === "keep") return void 0;
+  if (change.kind === "clearHanging") {
+    return indXml(keptIndAttrs(ind, HANGING_IND_ATTRS));
+  }
+  const dropped = [...LEFT_IND_ATTRS, ...FIRST_LINE_IND_ATTRS];
+  return indXml([
+    ...levelIndAttrs(change.indent),
+    ...keptIndAttrs(ind, dropped)
+  ]);
+}
+function leftIndAttrs(ind, leftTwips) {
+  const original = ind ? Array.from(ind.attributes) : [];
+  const slot = original.find(
+    (attr) => LEFT_TWIPS_IND_ATTRS.includes(localPart(attr.name))
+  )?.name;
+  const moved = original.flatMap((attr) => {
+    if (!LEFT_IND_ATTRS.includes(localPart(attr.name))) {
+      return [[attr.name, attr.value]];
+    }
+    return attr.name === slot && leftTwips > 0 ? [[attr.name, `${leftTwips}`]] : [];
+  });
+  return slot === void 0 && leftTwips > 0 ? [["w:left", `${leftTwips}`], ...moved] : moved;
+}
+var EMPTY_P_PR = { tag: "w:pPr", attrs: null, children: [] };
+function editParagraphProps(pPr, styles, defaultStyleId, plan) {
+  const props = pPr === null ? EMPTY_P_PR : parseProps(pPr);
+  const element = pPr === null ? null : parsePropsXml(pPr);
+  if (!props || pPr !== null && !element) return null;
+  const children = plan(element).reduce(
+    (kept, [name, xml]) => setPropsChild(kept, name, xml, P_PR_ORDER),
+    props.children
+  );
+  const rendered = renderProps({ ...props, children });
+  const next = rendered === "" ? null : rendered;
+  return {
+    pPr: next,
+    format: readParagraphProps(next, styles, defaultStyleId),
+    styleRun: readParagraphStyleRun(next, styles, defaultStyleId)
+  };
+}
+function withListNumbering(pPr, change, styles = NO_STYLES, defaultStyleId = null) {
+  return editParagraphProps(pPr, styles, defaultStyleId, (element) => {
+    const ind = nextIndXml(
+      element ? childByLocalName(element, "ind") : null,
+      change.indent
+    );
+    const numPr = ["numPr", numPrXml(change.numbering)];
+    return ind === void 0 ? [numPr] : [numPr, ["ind", ind]];
+  });
+}
+function withLeftIndent(pPr, leftTwips, styles = NO_STYLES, defaultStyleId = null) {
+  return editParagraphProps(pPr, styles, defaultStyleId, (element) => {
+    const ind = element ? childByLocalName(element, "ind") : null;
+    return [["ind", indXml(leftIndAttrs(ind, leftTwips))]];
+  });
+}
+function spacingAttrs(spacing, edits) {
+  const original = spacing ? Array.from(spacing.attributes) : [];
+  const editOf = (name) => edits.find(([edited]) => edited === localPart(name));
+  const changed = original.map((attr) => [
+    attr.name,
+    editOf(attr.name)?.[1] ?? attr.value
+  ]);
+  const added = edits.filter(
+    ([name]) => !original.some((attr) => localPart(attr.name) === name)
+  );
+  return [
+    ...changed,
+    ...added.map(([name, value]) => [`w:${name}`, value])
+  ];
+}
+function withLineSpacing(pPr, spacing, styles = NO_STYLES, defaultStyleId = null) {
+  const line = spacing.rule === "auto" ? Math.round(spacing.lines * 240) : Math.round(spacing.pt * 20);
+  return editParagraphProps(pPr, styles, defaultStyleId, (element) => {
+    const current = element ? childByLocalName(element, "spacing") : null;
+    const attrs = spacingAttrs(current, [
+      ["line", `${line}`],
+      ["lineRule", spacing.rule]
+    ]);
+    return [["spacing", attrsXml("w:spacing", attrs)]];
+  });
+}
+function withParagraphStyle(pPr, styleId, styles = NO_STYLES, defaultStyleId = null) {
+  const pStyle = styleId === null ? null : `<w:pStyle w:val="${escapeXml(styleId)}"/>`;
+  return editParagraphProps(pPr, styles, defaultStyleId, () => [
+    ["pStyle", pStyle]
+  ]);
+}
+var JC_BY_ALIGN = {
+  left: "left",
+  center: "center",
+  right: "right",
+  justify: "both"
+};
+function withParagraphAlign(pPr, align, styles = NO_STYLES, defaultStyleId = null) {
+  const jc = `<w:jc w:val="${JC_BY_ALIGN[align]}"/>`;
+  return editParagraphProps(pPr, styles, defaultStyleId, () => [["jc", jc]]);
+}
+export {
+  readParagraphProps,
+  withLeftIndent,
+  withLineSpacing,
+  withListNumbering,
+  withParagraphAlign,
+  withParagraphStyle
+};

package/dist/docx/propsXml.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Handles the XML fragments that carry formatting, such as `<w:rPr>`, `<w:pPr>`, and `<w:tcPr>`.
+ *
+ * A fragment is never rebuilt: only the one child a job names is sliced out and swapped, so the
+ * rest (borders, shading, margins) stays as the original text wrote it. OOXML lays down the order
+ * of the children, so the spot to insert a child that was not there is found by that same order.
+ */
+export interface PropsChild {
+    /** The name with its namespace prefix stripped off (e.g. `gridSpan`) */
+    name: string;
+    /** This child's original XML fragment exactly as it was */
+    xml: string;
+}
+export interface Props {
+    /** The opening tag name exactly as written (e.g. `w:tcPr`) */
+    tag: string;
+    attrs: string | null;
+    children: PropsChild[];
+}
+/** The order the children are laid out in under `w:rPr` (CT_RPr) */
+export declare const RUN_PR_ORDER: readonly string[];
+/** The order the children are laid out in under `w:pPr` (CT_PPr) */
+export declare const P_PR_ORDER: readonly string[];
+/** The order the children are laid out in under `w:tcPr` (CT_TcPr) */
+export declare const TC_PR_ORDER: readonly string[];
+/** The conventional order of children under `w:trPr` (CT_TrPr). */
+export declare const TR_PR_ORDER: readonly string[];
+/** The order the children are laid out in under `w:tblPr` (CT_TblPr) */
+export declare const TBL_PR_ORDER: readonly string[];
+/**
+ * Splits a formatting fragment into its opening tag and its list of children.
+ * null if its shape cannot be made out (in which case leaving the original untouched is the safe move).
+ */
+export declare function parseProps(xml: string): Props | null;
+/** With no children at all, the formatting fragment itself is not written */
+export declare function renderProps(props: Props): string;
+/**
+ * Replaces a single child with new XML.
+ * A null `xml` removes that child. A child that was not there goes into the spot the order calls for.
+ */
+export declare function setPropsChild(children: PropsChild[], name: string, xml: string | null, order: readonly string[]): PropsChild[];
+export declare function propsChild(children: PropsChild[], name: string): PropsChild | undefined;
+/**
+ * Reads a single formatting fragment into an element.
+ *
+ * A fragment carries no namespace declarations, so they are put back on as it is wrapped.
+ * null if its shape cannot be made out, in which case the caller leaves the display values alone.
+ */
+export declare function parsePropsXml(xml: string): Element | null;