web-doc 0.6.2 → 0.8.0

package/dist/edit/docx/types.d.ts

@@ -0,0 +1,206 @@
+import type { ApplyOptions, BinaryData, EditColor, EditElement, EditReceipt, EditSessionBase, ReadOptions, ReadResult, SavedDocument, SaveOptions, TextRange } from "../types.js";
+export type DocxElementKind = "paragraph" | "table" | "image" | "other";
+export type DocxTextAlign = "left" | "center" | "right" | "justify";
+/** Word's sixteen highlight colours (`w:highlight/@w:val`). */
+export type DocxHighlight = "yellow" | "green" | "cyan" | "magenta" | "blue" | "red" | "darkBlue" | "darkCyan" | "darkGreen" | "darkMagenta" | "darkRed" | "darkYellow" | "darkGray" | "lightGray" | "black" | "white";
+/** The style of a paragraph's first run with text, resolved through the style chain and the theme. */
+export interface DocxTextStyle {
+    /** Theme fonts resolved ("minorHAnsi" becomes the minor Latin face). */
+    readonly fontFamily: string;
+    /** Points. */
+    readonly fontSize: number;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+    /** `#RRGGBB`, `{ theme }` for a theme colour, "auto" for Word's automatic colour. */
+    readonly color: EditColor;
+    readonly highlight?: DocxHighlight;
+}
+export interface DocxParagraphSpacing {
+    /** Points before the paragraph; absent when inherited. */
+    readonly before?: number;
+    /** Points after the paragraph; absent when inherited. */
+    readonly after?: number;
+    /**
+     * Line spacing: points for `exact` and `atLeast`, a multiple of single
+     * spacing (1 = single, 1.5, 2) for `auto`; absent when inherited.
+     */
+    readonly line?: number;
+    readonly lineRule?: "auto" | "exact" | "atLeast";
+}
+export interface DocxParagraphStyle {
+    /** `w:pStyle`, when the paragraph names a style. */
+    readonly styleId?: string;
+    readonly align: DocxTextAlign;
+    readonly spacing: DocxParagraphSpacing;
+    /** `w:numPr`: the paragraph belongs to a list. */
+    readonly numbering?: {
+        readonly numId: number;
+        readonly level: number;
+    };
+}
+/** Why a paragraph's text cannot be edited in place. */
+export type DocxReadOnlyReason = "tracked-changes" | "section-break" | "unsupported-content";
+/**
+ * An element of the body story. Geometry comes from the renderer: `bounds`
+ * and `fragments` are the unions of the element's text runs per page, so
+ * an element whose pages the viewer has not laid out yet, or which draws
+ * no run (an empty paragraph), has `pageIndex` −1, empty `bounds` and an
+ * empty `fragments` list until a query names its page.
+ */
+export interface DocxElement extends EditElement {
+    readonly kind: DocxElementKind;
+    /** Present for a paragraph: resolved style of its first run with text. */
+    readonly textStyle?: DocxTextStyle;
+    /** Present for a paragraph. */
+    readonly paragraphStyle?: DocxParagraphStyle;
+    /** Present for a table: cell text by row. */
+    readonly table?: {
+        readonly rows: readonly (readonly string[])[];
+    };
+    /** Present for a paragraph whose text cannot be edited in place. */
+    readonly readOnlyReason?: DocxReadOnlyReason;
+    /** Present for an inline picture: its declared extent in page space (CSS pixels). */
+    readonly imageSize?: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+export interface DocxTextStyleChange {
+    /** `w:rFonts` ascii and hAnsi faces. */
+    readonly fontFamily?: string;
+    /** 1–400 points. */
+    readonly fontSize?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    /** `w:u` single or none. */
+    readonly underline?: boolean;
+    /** `#RRGGBB` writes `w:color`; `{ theme }` writes the theme colour and its resolved value. */
+    readonly color?: EditColor;
+    /** `w:highlight`; "none" removes it. */
+    readonly highlight?: DocxHighlight | "none";
+}
+export interface DocxParagraphStyleChange {
+    readonly align?: DocxTextAlign;
+    /** Points; a field absent keeps its bytes. */
+    readonly spacing?: {
+        readonly before?: number;
+        readonly after?: number;
+        /** A multiple of single spacing, written with `w:lineRule="auto"`. */
+        readonly line?: number;
+    };
+}
+export interface DocxReplaceTextOperation {
+    readonly op: "replaceText";
+    /** A `paragraph` element. */
+    readonly target: string;
+    readonly text: string;
+    /** Both ends on the target; absent, the whole text; collapsed, an insertion. */
+    readonly range?: TextRange;
+}
+export interface DocxSetTextStyleOperation {
+    readonly op: "setTextStyle";
+    readonly target: string;
+    readonly range?: TextRange;
+    readonly style: DocxTextStyleChange;
+}
+export interface DocxSetParagraphStyleOperation {
+    readonly op: "setParagraphStyle";
+    readonly target: string;
+    readonly style: DocxParagraphStyleChange;
+}
+export interface DocxInsertParagraphOperation {
+    readonly op: "insertParagraph";
+    /** Exactly one of `before` and `after`: a paragraph or table id. */
+    readonly before?: string;
+    readonly after?: string;
+    readonly text: string;
+    readonly style?: DocxTextStyleChange;
+}
+export interface DocxDeleteElementOperation {
+    readonly op: "deleteElement";
+    /** A paragraph, a table or an inline picture. */
+    readonly target: string;
+}
+export interface DocxMoveElementOperation {
+    readonly op: "moveElement";
+    /** A paragraph or a table. */
+    readonly target: string;
+    /** Exactly one of `before` and `after`: a paragraph or table id of the same container. */
+    readonly before?: string;
+    readonly after?: string;
+}
+export interface DocxInsertTableOperation {
+    readonly op: "insertTable";
+    readonly before?: string;
+    readonly after?: string;
+    /** Cell text by row; every row has the same number of cells. 1–100 rows, 1–20 columns. */
+    readonly rows: readonly (readonly string[])[];
+    /** Relative column weights, one per column; equal when omitted. */
+    readonly columnWidths?: readonly number[];
+}
+export interface DocxSetTableCellOperation {
+    readonly op: "setTableCell";
+    /** A `table` element. */
+    readonly target: string;
+    readonly row: number;
+    readonly column: number;
+    /** The cell's new text; empty clears the cell. */
+    readonly text: string;
+}
+export interface DocxInsertImageOperation {
+    readonly op: "insertImage";
+    readonly before?: string;
+    readonly after?: string;
+    /** PNG or JPEG bytes; base64 over pure-JSON transports. */
+    readonly data: BinaryData;
+    readonly mimeType: "image/png" | "image/jpeg";
+    /** Points. */
+    readonly size: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** The DOCX operation union; operations are added as they ship. */
+export type DocxOperation = DocxReplaceTextOperation | DocxSetTextStyleOperation | DocxSetParagraphStyleOperation | DocxInsertParagraphOperation | DocxDeleteElementOperation | DocxMoveElementOperation | DocxInsertTableOperation | DocxSetTableCellOperation | DocxInsertImageOperation;
+/** DOCX saves have no fields of their own. */
+export type DocxSaveOptions = SaveOptions;
+/** One revision of a paragraph, as `getRevisions()` lists them in document order. */
+export interface DocxRevision {
+    readonly kind: "ins" | "del" | "moveFrom" | "moveTo" | "rPrChange" | "pPrChange";
+    /** The `w:id`; -1 when the file leaves it out. */
+    readonly id: number;
+    readonly author?: string;
+    /** ISO 8601, as the file writes it. */
+    readonly date?: string;
+    /** Runs of the paragraph, its paragraph mark, or the paragraph's properties. */
+    readonly scope: "runs" | "mark" | "paragraph";
+    /** The inserted, deleted or restyled text; "\n" for a paragraph mark; absent for a property change. */
+    readonly text?: string;
+}
+/** An operation's fields without its `op`, as the typed methods take them. */
+export type DocxFields<T extends DocxOperation> = T extends unknown ? Omit<T, "op"> : never;
+export interface DocxEditSession extends EditSessionBase<DocxOperation, DocxElement> {
+    readonly format: "docx";
+    save(options?: DocxSaveOptions): Promise<SavedDocument>;
+    /** The tracked changes a paragraph holds, in document order; empty for other elements. */
+    getRevisions(elementId: string, options?: ReadOptions): Promise<ReadResult<DocxRevision>>;
+    /** Replaces the whole text of a paragraph, or the part a range covers. */
+    replaceText(fields: DocxFields<DocxReplaceTextOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Changes run properties; unspecified ones keep their bytes. */
+    setTextStyle(fields: DocxFields<DocxSetTextStyleOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Changes alignment and spacing of a paragraph. */
+    setParagraphStyle(fields: DocxFields<DocxSetParagraphStyleOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Adds a paragraph next to another element; its id is in `createdIds`. */
+    insertParagraph(fields: DocxFields<DocxInsertParagraphOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Removes a paragraph, a table or an inline picture. */
+    deleteElement(fields: DocxFields<DocxDeleteElementOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Moves a paragraph or a table next to another element of the same container. */
+    moveElement(fields: DocxFields<DocxMoveElementOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Adds a table with the given cell text. */
+    insertTable(fields: DocxFields<DocxInsertTableOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Changes one cell's text. */
+    setTableCell(fields: DocxFields<DocxSetTableCellOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Adds a paragraph holding an inline PNG or JPEG. */
+    insertImage(fields: DocxFields<DocxInsertImageOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+}

package/dist/edit/docx/types.js

@@ -0,0 +1 @@
+export {};

package/dist/edit/docx/write.d.ts

@@ -0,0 +1,64 @@
+import { type XmlPatch } from "../ooxml/patch.js";
+import { type XmlElement, type XmlPart } from "../ooxml/xml.js";
+import type { EditColor } from "../types.js";
+import { type DocxStyles } from "./style.js";
+import type { DocxParagraphStyleChange, DocxTextStyleChange } from "./types.js";
+/** Children of `w:rPr` in schema order (CT_RPr). */
+export declare const RPR_ORDER: string[];
+/** Children of `w:pPr` in schema order (CT_PPr). */
+export declare const PPR_ORDER: string[];
+/** Why a text cannot be written, or undefined when it can. */
+export declare function textProblem(text: string): string | undefined;
+/** Why a value cannot be written as an attribute: text problems plus the breaks text may hold. */
+export declare function attributeProblem(value: string): string | undefined;
+export declare function colorProblem(color: unknown): string | undefined;
+/** Text as the engine stores it: Windows and classic Mac line ends become "\n". */
+export declare function normalizeText(text: string): string;
+export declare function sliceOf(part: XmlPart, node: XmlElement | undefined): string;
+export declare function escapeAttributeValue(value: string): string;
+/** The content elements of a run for `text`: `w:t`, `w:tab`, `w:br`. */
+export declare function runContentXml(text: string): string;
+/** A run with `rPr` bytes (or "") and the given content; nothing for empty content. */
+export declare function runXml(rPr: string, content: string): string;
+/**
+ * Properties with changes merged in schema order: every child of `source`
+ * keeps its bytes unless `set` names its local name, in which case the
+ * replacement (or nothing, for `null`) takes its place; new children go
+ * where the schema puts them. Returns "" for no properties at all.
+ */
+export declare function mergedProperties(part: XmlPart, source: XmlElement | undefined, tag: "w:rPr" | "w:pPr", order: readonly string[], set: ReadonlyMap<string, string | null>): string;
+/**
+ * `w:rPr` bytes with a text style change applied. With `revision` (the
+ * attributes of a tracked change) the previous properties are kept in a
+ * `w:rPrChange`, so Word shows the change as a suggestion.
+ */
+export declare function changedRunProperties(part: XmlPart, rPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles, revision?: string): string;
+/** `w:color` for a colour: RGB, automatic, or a theme name with the theme's value. */
+export declare function colorXml(color: EditColor, styles: DocxStyles): string;
+/** The children of a properties element as bytes, the named ones left out. */
+export declare function innerPropertiesXml(part: XmlPart, properties: XmlElement | undefined, without: readonly string[]): string;
+/**
+ * `w:pPr` bytes with alignment and spacing changed, other children kept.
+ * With `revision` the previous paragraph properties are kept in a
+ * `w:pPrChange`.
+ */
+export declare function changedParagraphProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxParagraphStyleChange, revision?: string): string;
+export declare function alignValue(align: NonNullable<DocxParagraphStyleChange["align"]>): string;
+/** `w:pPr` bytes with the paragraph mark's `w:rPr` changed (created when absent). */
+export declare function paragraphMarkProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles, revision?: string): string;
+/** `w:pPr` bytes without the section properties, for a paragraph copied next to one that ends a section. */
+export declare function paragraphPropertiesWithoutSection(part: XmlPart, pPr: XmlElement | undefined): string;
+/**
+ * The start tag of a `w:p` with its id written: the paragraph's own
+ * attributes, `w14:paraId` and `w14:textId` replaced.
+ */
+export declare function paragraphStartTag(source: XmlElement | undefined, id: string): string;
+/** A whole paragraph from its start tag, property bytes and content. */
+export declare function paragraphXml(source: XmlElement | undefined, id: string, pPr: string, content: string): string;
+/**
+ * Patches that declare the `w14` namespace on the document root and list
+ * it as ignorable, when the root does not yet; nothing when it does.
+ */
+export declare function namespacePatches(part: XmlPart): XmlPatch[];
+/** Whether the paragraph already carries a `w14:paraId`. */
+export declare function isAuthored(part: XmlPart, paragraph: XmlElement): boolean;

package/dist/edit/docx/write.js

@@ -0,0 +1,375 @@
+import { patches } from "../ooxml/patch.js";
+import { escapeText } from "../ooxml/xml.js";
+import { W14_NS, W_NS } from "./ids.js";
+import { isThemeColorName } from "./style.js";
+import { LINE_BREAK, PAGE_BREAK, TAB } from "./text.js";
+/*
+ * Writing WordprocessingML: runs re-serialized from text and their
+ * properties, run and paragraph properties changed in schema order with
+ * every other child kept as its bytes, paragraph start tags carrying their
+ * `w14:paraId`, and the namespace declarations that attribute needs.
+ */
+const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+/** Children of `w:rPr` in schema order (CT_RPr). */
+export const RPR_ORDER = [
+    "rStyle",
+    "rFonts",
+    "b",
+    "bCs",
+    "i",
+    "iCs",
+    "caps",
+    "smallCaps",
+    "strike",
+    "dstrike",
+    "outline",
+    "shadow",
+    "emboss",
+    "imprint",
+    "noProof",
+    "snapToGrid",
+    "vanish",
+    "webHidden",
+    "color",
+    "spacing",
+    "w",
+    "kern",
+    "position",
+    "sz",
+    "szCs",
+    "highlight",
+    "u",
+    "effect",
+    "bdr",
+    "shd",
+    "fitText",
+    "vertAlign",
+    "rtl",
+    "cs",
+    "em",
+    "lang",
+    "eastAsianLayout",
+    "specVanish",
+    "oMath",
+    "rPrChange",
+];
+/** Children of `w:pPr` in schema order (CT_PPr). */
+export const PPR_ORDER = [
+    "pStyle",
+    "keepNext",
+    "keepLines",
+    "pageBreakBefore",
+    "framePr",
+    "widowControl",
+    "numPr",
+    "suppressLineNumbers",
+    "pBdr",
+    "shd",
+    "tabs",
+    "suppressAutoHyphens",
+    "kinsoku",
+    "wordWrap",
+    "overflowPunct",
+    "topLinePunct",
+    "autoSpaceDE",
+    "autoSpaceDN",
+    "bidi",
+    "adjustRightInd",
+    "snapToGrid",
+    "spacing",
+    "ind",
+    "contextualSpacing",
+    "mirrorIndents",
+    "suppressOverlap",
+    "jc",
+    "textDirection",
+    "textAlignment",
+    "textboxTightWrap",
+    "outlineLvl",
+    "divId",
+    "cnfStyle",
+    "rPr",
+    "sectPr",
+    "pPrChange",
+];
+const FORBIDDEN = /[\u0000-\u0008\u000e-\u001f￾￿]/;
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+/** Why a text cannot be written, or undefined when it can. */
+export function textProblem(text) {
+    if (FORBIDDEN.test(text))
+        return "control characters XML cannot carry";
+    if (LONE_SURROGATE.test(text))
+        return "a lone surrogate";
+    return undefined;
+}
+/** Why a value cannot be written as an attribute: text problems plus the breaks text may hold. */
+export function attributeProblem(value) {
+    if (/[\u000b\u000c]/.test(value))
+        return "line or page breaks an attribute cannot carry";
+    return textProblem(value);
+}
+export function colorProblem(color) {
+    if (typeof color === "string")
+        return color === "auto" || /^#[0-9A-Fa-f]{6}$/.test(color)
+            ? undefined
+            : "not #RRGGBB or auto";
+    if (!color || typeof color !== "object")
+        return "not a colour";
+    const { theme } = color;
+    return typeof theme === "string" && isThemeColorName(theme)
+        ? undefined
+        : "not a theme colour name";
+}
+/** Text as the engine stores it: Windows and classic Mac line ends become "\n". */
+export function normalizeText(text) {
+    return text.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+}
+export function sliceOf(part, node) {
+    return node ? part.text.slice(node.start, node.end) : "";
+}
+export function escapeAttributeValue(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("\t", "&#9;")
+        .replaceAll("\n", "&#10;")
+        .replaceAll("\r", "&#13;");
+}
+/** The content elements of a run for `text`: `w:t`, `w:tab`, `w:br`. */
+export function runContentXml(text) {
+    let out = "";
+    let pending = "";
+    const flush = () => {
+        if (pending.length === 0)
+            return;
+        const preserve = /^\s|\s$/.test(pending) ? ' xml:space="preserve"' : "";
+        out += `<w:t${preserve}>${escapeText(pending)}</w:t>`;
+        pending = "";
+    };
+    for (const char of text) {
+        if (char === TAB) {
+            flush();
+            out += "<w:tab/>";
+        }
+        else if (char === LINE_BREAK) {
+            flush();
+            out += "<w:br/>";
+        }
+        else if (char === PAGE_BREAK) {
+            flush();
+            out += '<w:br w:type="page"/>';
+        }
+        else
+            pending += char;
+    }
+    flush();
+    return out;
+}
+/** A run with `rPr` bytes (or "") and the given content; nothing for empty content. */
+export function runXml(rPr, content) {
+    return content.length === 0 ? "" : `<w:r>${rPr}${content}</w:r>`;
+}
+/**
+ * Properties with changes merged in schema order: every child of `source`
+ * keeps its bytes unless `set` names its local name, in which case the
+ * replacement (or nothing, for `null`) takes its place; new children go
+ * where the schema puts them. Returns "" for no properties at all.
+ */
+export function mergedProperties(part, source, tag, order, set) {
+    const children = source
+        ? source.children.map((child) => ({
+            local: child.local,
+            xml: sliceOf(part, child),
+        }))
+        : [];
+    for (const [local, xml] of set) {
+        const index = children.findIndex((child) => child.local === local);
+        for (let at = children.length - 1; at >= 0; at -= 1)
+            if (children[at].local === local)
+                children.splice(at, 1);
+        if (xml === null)
+            continue;
+        let at = index;
+        if (at < 0) {
+            // Before the first child the schema places later; a child the
+            // schema list does not name (an extension) counts as later too.
+            const rank = order.indexOf(local);
+            at = children.findIndex((child) => {
+                const other = order.indexOf(child.local);
+                return other < 0 || other > rank;
+            });
+            if (at < 0)
+                at = children.length;
+        }
+        children.splice(at, 0, { local, xml });
+    }
+    const attributes = source
+        ? source.attributes.map((a) => ` ${a.name}="${a.rawValue}"`).join("")
+        : "";
+    const content = children.map((child) => child.xml).join("");
+    if (!content)
+        return source ? `<${tag}${attributes}/>` : "";
+    return `<${tag}${attributes}>${content}</${tag}>`;
+}
+function toggleXml(local, on) {
+    return on ? `<w:${local}/>` : `<w:${local} w:val="0"/>`;
+}
+/**
+ * `w:rPr` bytes with a text style change applied. With `revision` (the
+ * attributes of a tracked change) the previous properties are kept in a
+ * `w:rPrChange`, so Word shows the change as a suggestion.
+ */
+export function changedRunProperties(part, rPr, change, styles, revision) {
+    const set = new Map();
+    if (revision !== undefined)
+        set.set("rPrChange", `<w:rPrChange${revision}>${wrapped("w:rPr", innerPropertiesXml(part, rPr, ["rPrChange"]))}</w:rPrChange>`);
+    if (change.bold !== undefined) {
+        set.set("b", toggleXml("b", change.bold));
+        set.set("bCs", toggleXml("bCs", change.bold));
+    }
+    if (change.italic !== undefined) {
+        set.set("i", toggleXml("i", change.italic));
+        set.set("iCs", toggleXml("iCs", change.italic));
+    }
+    if (change.underline !== undefined)
+        set.set("u", `<w:u w:val="${change.underline ? "single" : "none"}"/>`);
+    if (change.fontSize !== undefined) {
+        const half = String(Math.round(change.fontSize * 2));
+        set.set("sz", `<w:sz w:val="${half}"/>`);
+        set.set("szCs", `<w:szCs w:val="${half}"/>`);
+    }
+    if (change.color !== undefined)
+        set.set("color", colorXml(change.color, styles));
+    if (change.highlight !== undefined)
+        set.set("highlight", change.highlight === "none"
+            ? null
+            : `<w:highlight w:val="${change.highlight}"/>`);
+    if (change.fontFamily !== undefined)
+        set.set("rFonts", fontsXml(part, rPr, change.fontFamily));
+    return mergedProperties(part, rPr, "w:rPr", RPR_ORDER, set);
+}
+/** `w:color` for a colour: RGB, automatic, or a theme name with the theme's value. */
+export function colorXml(color, styles) {
+    if (typeof color === "string") {
+        if (color === "auto")
+            return '<w:color w:val="auto"/>';
+        return `<w:color w:val="${color.slice(1).toUpperCase()}"/>`;
+    }
+    const value = styles.themeColor(color.theme) ?? "auto";
+    return `<w:color w:val="${value}" w:themeColor="${escapeAttributeValue(color.theme)}"/>`;
+}
+/** `w:rFonts` with the ASCII and high-ANSI faces set and their theme overrides dropped. */
+function fontsXml(part, rPr, family) {
+    const existing = rPr?.children.find((child) => child.local === "rFonts" && child.namespace === W_NS);
+    const kept = (existing?.attributes ?? []).filter((attribute) => !["w:ascii", "w:hAnsi", "w:asciiTheme", "w:hAnsiTheme"].includes(attribute.name));
+    const face = escapeAttributeValue(family);
+    const rest = kept.map((a) => ` ${a.name}="${a.rawValue}"`).join("");
+    return `<w:rFonts w:ascii="${face}" w:hAnsi="${face}"${rest}/>`;
+}
+/** `inner` inside `tag`, self-closing when empty. */
+function wrapped(tag, inner) {
+    return inner.length === 0 ? `<${tag}/>` : `<${tag}>${inner}</${tag}>`;
+}
+/** The children of a properties element as bytes, the named ones left out. */
+export function innerPropertiesXml(part, properties, without) {
+    return (properties?.children ?? [])
+        .filter((child) => !without.includes(child.local))
+        .map((child) => sliceOf(part, child))
+        .join("");
+}
+/**
+ * `w:pPr` bytes with alignment and spacing changed, other children kept.
+ * With `revision` the previous paragraph properties are kept in a
+ * `w:pPrChange`.
+ */
+export function changedParagraphProperties(part, pPr, change, revision) {
+    const set = new Map();
+    if (revision !== undefined)
+        set.set("pPrChange", `<w:pPrChange${revision}>${wrapped("w:pPr", innerPropertiesXml(part, pPr, ["rPr", "sectPr", "pPrChange"]))}</w:pPrChange>`);
+    if (change.align !== undefined)
+        set.set("jc", `<w:jc w:val="${alignValue(change.align)}"/>`);
+    if (change.spacing !== undefined) {
+        const existing = pPr?.children.find((child) => child.local === "spacing" && child.namespace === W_NS);
+        const attributes = new Map();
+        for (const attribute of existing?.attributes ?? [])
+            attributes.set(attribute.name, attribute.rawValue);
+        // Word prefers the line-based and automatic forms over w:before and
+        // w:after, so a set value drops them.
+        if (change.spacing.before !== undefined) {
+            attributes.set("w:before", String(Math.round(change.spacing.before * 20)));
+            attributes.delete("w:beforeLines");
+            attributes.delete("w:beforeAutospacing");
+        }
+        if (change.spacing.after !== undefined) {
+            attributes.set("w:after", String(Math.round(change.spacing.after * 20)));
+            attributes.delete("w:afterLines");
+            attributes.delete("w:afterAutospacing");
+        }
+        if (change.spacing.line !== undefined) {
+            attributes.set("w:line", String(Math.round(change.spacing.line * 240)));
+            attributes.set("w:lineRule", "auto");
+        }
+        set.set("spacing", `<w:spacing${[...attributes].map(([name, raw]) => ` ${name}="${raw}"`).join("")}/>`);
+    }
+    return mergedProperties(part, pPr, "w:pPr", PPR_ORDER, set);
+}
+export function alignValue(align) {
+    switch (align) {
+        case "center":
+            return "center";
+        case "right":
+            return "right";
+        case "justify":
+            return "both";
+        default:
+            return "left";
+    }
+}
+/** `w:pPr` bytes with the paragraph mark's `w:rPr` changed (created when absent). */
+export function paragraphMarkProperties(part, pPr, change, styles, revision) {
+    const rPr = pPr?.children.find((child) => child.local === "rPr" && child.namespace === W_NS);
+    const changed = changedRunProperties(part, rPr, change, styles, revision);
+    return mergedProperties(part, pPr, "w:pPr", PPR_ORDER, new Map([["rPr", changed || null]]));
+}
+/** `w:pPr` bytes without the section properties, for a paragraph copied next to one that ends a section. */
+export function paragraphPropertiesWithoutSection(part, pPr) {
+    if (!pPr)
+        return "";
+    return mergedProperties(part, pPr, "w:pPr", PPR_ORDER, new Map([["sectPr", null]]));
+}
+/**
+ * The start tag of a `w:p` with its id written: the paragraph's own
+ * attributes, `w14:paraId` and `w14:textId` replaced.
+ */
+export function paragraphStartTag(source, id) {
+    const kept = (source?.attributes ?? []).filter((attribute) => attribute.name !== "w14:paraId" && attribute.name !== "w14:textId");
+    const rest = kept.map((a) => ` ${a.name}="${a.rawValue}"`).join("");
+    return `<w:p${rest} w14:paraId="${id}">`;
+}
+/** A whole paragraph from its start tag, property bytes and content. */
+export function paragraphXml(source, id, pPr, content) {
+    return `${paragraphStartTag(source, id)}${pPr}${content}</w:p>`;
+}
+/**
+ * Patches that declare the `w14` namespace on the document root and list
+ * it as ignorable, when the root does not yet; nothing when it does.
+ */
+export function namespacePatches(part) {
+    const root = part.root;
+    const items = [];
+    const has = (name) => root.attributes.find((attribute) => attribute.name === name)?.value;
+    if (has("xmlns:w14") === undefined)
+        items.push(patches.setAttribute(part, root, "xmlns:w14", W14_NS));
+    if (has("xmlns:mc") === undefined)
+        items.push(patches.setAttribute(part, root, "xmlns:mc", MC_NS));
+    const ignorable = has("mc:Ignorable");
+    const listed = ignorable ? ignorable.split(/\s+/).filter(Boolean) : [];
+    if (!listed.includes("w14"))
+        items.push(patches.setAttribute(part, root, "mc:Ignorable", [...listed, "w14"].join(" ")));
+    return items;
+}
+/** Whether the paragraph already carries a `w14:paraId`. */
+export function isAuthored(part, paragraph) {
+    return part.attribute(paragraph, "w14:paraId") !== undefined;
+}