@docx4j/core-ts 0.3.2 → 0.5.0

package/dist/model/customxml/CustomXmlPartCollection.d.mts

@@ -5,6 +5,7 @@ import { CustomXmlPart, type CustomXmlPartOwner } from './CustomXmlPart.mjs';
 import type { CustomXmlPartLookup } from './XmlMapping.mjs';
 import type { XPathEngine } from './xpath.mjs';
 import { type BindingResult } from './bindings.mjs';
+import { type XhtmlHost, type XhtmlBindingOptions } from './xhtml.mjs';
 /**
  * What the collection needs of its package. A structural interface, so that this module does not
  * import `WordprocessingMLPackage` (which imports it): the package hands itself in.
@@ -18,6 +19,8 @@ export interface CustomXmlHost {
     boundBodies(): Body[];
     /** Where a new custom XML part's relationship goes: the main document part (Word drops parts related from the package alone). */
     customXmlRelationshipSource(): Part;
+    /** The package, for the XHTML pass (list definitions, styles, relationships); absent, XHTML controls are left and noted. */
+    readonly xhtmlHost?: XhtmlHost;
 }
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export declare class CustomXmlPartCollection implements CustomXmlPartOwner, CustomXmlPartLookup {
@@ -62,7 +65,9 @@ export declare class CustomXmlPartCollection implements CustomXmlPartOwner, Cust
      * which is what Word does when it opens the document. Unmarshals the main document part (and the
      * headers and footers it has) and parses the custom XML parts.
      */
-    applyBindings(): Promise<BindingResult>;
+    applyBindings(options?: {
+        html?: XhtmlBindingOptions;
+    }): Promise<BindingResult>;
     /**
      * docx4j `UpdateXmlFromDocumentSurface.updateCustomXmlParts`: writes what the controls now show
      * back into the custom XML. The reverse of `applyBindings`, and what makes an edit to a bound

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -14,6 +14,8 @@ import { parseXml, decodeXmlText } from '../../xml/dom.mjs';
 import { createDatastoreItem } from '@docx4j/generated-objects-ts/factory/org_docx4j_customXmlProperties';
 import { CustomXmlPart } from './CustomXmlPart.mjs';
 import { applyBindingsTo, updateFromControls } from './bindings.mjs';
+import { applyXhtmlBindingsTo, isXhtmlBound } from './xhtml.mjs';
+import { applyPictureHandlersTo, updateFromPictureControls } from './pictures.mjs';
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export class CustomXmlPartCollection {
     constructor(host) {
@@ -133,9 +135,19 @@ export class CustomXmlPartCollection {
      * which is what Word does when it opens the document. Unmarshals the main document part (and the
      * headers and footers it has) and parses the custom XML parts.
      */
-    async applyBindings() {
+    async applyBindings(options = {}) {
+        var _a, _b;
         await this.load();
-        return applyBindingsTo(this.controlsOf(await this.host.getBoundBodies()));
+        const controls = this.controlsOf(await this.host.getBoundBodies());
+        const result = applyBindingsTo(controls);
+        // od:Handler=picture through the tag's od:xpath entry (CR-005 section 9): after the text bindings, which took the picture controls.
+        applyPictureHandlersTo(controls, this, result);
+        // Escaped XHTML through the tag's od:xpath entry (CR-005 section 8.2): after the text bindings, asynchronous.
+        if (this.host.xhtmlHost)
+            await applyXhtmlBindingsTo(controls, this, this.host.xhtmlHost, result, (_a = options.html) !== null && _a !== void 0 ? _a : {});
+        else if (controls.some(isXhtmlBound))
+            ((_b = result.notes) !== null && _b !== void 0 ? _b : (result.notes = [])).push('XHTML-bound controls left: the collection has no package to make their lists, styles and links');
+        return result;
     }
     /**
      * docx4j `UpdateXmlFromDocumentSurface.updateCustomXmlParts`: writes what the controls now show
@@ -144,7 +156,11 @@ export class CustomXmlPartCollection {
      */
     async updateFromContentControls() {
         await this.load();
-        return updateFromControls(this.controlsOf(await this.host.getBoundBodies()));
+        const controls = this.controlsOf(await this.host.getBoundBodies());
+        const result = updateFromControls(controls);
+        // a mapped picture control's image back to its node, as Word 15 writes it (CR-005 section 9, check 38)
+        await updateFromPictureControls(controls, result);
+        return result;
     }
     controlsOf(bodies) {
         return bodies.flatMap((body) => body.contentControls);

package/dist/model/customxml/bindings.d.mts

@@ -12,6 +12,8 @@ export interface BindingResult {
     updated: number;
     /** Controls left alone: the part is missing, the XPath selects nothing, or the kind is not handled. */
     skipped: number;
+    /** What the XHTML and picture passes left or dropped, one line each (CR-005 sections 8.2 and 9; REQ-076). */
+    notes?: string[];
 }
 /**
  * Whether a node's value is a Flat OPC package: what Word writes into the node of a mapped rich
@@ -32,9 +34,10 @@ export declare function formatDate(pattern: string, date: Date, locale?: string)
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
  * false when nothing was written: no binding, no part, an XPath that selects nothing, a kind
- * this phase does not handle (pictures, explicit rich text), or a node holding a Flat OPC package.
+ * this phase does not handle (explicit rich text), a node holding a Flat OPC package, or a
+ * picture control whose node holds no image (`notes` says which; CR-005 section 9).
  */
-export declare function applyBindingTo(control: ContentControl): boolean;
+export declare function applyBindingTo(control: ContentControl, notes?: string[]): boolean;
 /** `applyBindings` over a list of controls. */
 export declare function applyBindingsTo(controls: ContentControl[]): BindingResult;
 /**

package/dist/model/customxml/bindings.mjs

@@ -1,6 +1,7 @@
 import { deepCopy } from '@docx4j/generated-objects-ts';
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { bindPicture } from './pictures.mjs';
 /** The style Word gives placeholder text, and the text docx4j's placeholder.xml carries. */
 export const PLACEHOLDER_STYLE = 'PlaceholderText';
 export const PLACEHOLDER_TEXT = 'Click here to enter text.';
@@ -114,9 +115,10 @@ function dateOf(value) {
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
  * false when nothing was written: no binding, no part, an XPath that selects nothing, a kind
- * this phase does not handle (pictures, explicit rich text), or a node holding a Flat OPC package.
+ * this phase does not handle (explicit rich text), a node holding a Flat OPC package, or a
+ * picture control whose node holds no image (`notes` says which; CR-005 section 9).
  */
-export function applyBindingTo(control) {
+export function applyBindingTo(control, notes) {
     var _a;
     const mapping = control.xmlMapping;
     if (!mapping.isMapped)
@@ -125,9 +127,14 @@ export function applyBindingTo(control) {
     if (!node)
         return false;
     const value = node.text.trim();
-    // A picture binding carries base64 image data; docx4j replaces the a:blip embed. Deferred (section 12).
-    if (control.type === 'Picture')
-        return false;
+    // A picture control's node holds base64 image data: the picture's a:blip is pointed at a new
+    // image part and the drawing kept, as docx4j's bind.xslt mode picture3 does (CR-005 section 9).
+    if (control.type === 'Picture') {
+        const outcome = bindPicture(control, value, { kind: 'keep' }, control.title || control.tag || `picture control ${control.id}`);
+        if (outcome.note)
+            notes === null || notes === void 0 ? void 0 : notes.push(outcome.note);
+        return outcome.done;
+    }
     // Explicit rich text is bound from flat OPC or XHTML in docx4j; deferred, as it is there for this route.
     if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
         return false;
@@ -169,15 +176,18 @@ export function applyBindingTo(control) {
 /** `applyBindings` over a list of controls. */
 export function applyBindingsTo(controls) {
     const result = { bound: 0, updated: 0, skipped: 0 };
+    const notes = [];
     for (const control of controls) {
         if (!control.xmlMapping.isMapped)
             continue;
         result.bound++;
-        if (applyBindingTo(control))
+        if (applyBindingTo(control, notes))
             result.updated++;
         else
             result.skipped++;
     }
+    if (notes.length > 0)
+        result.notes = notes;
     return result;
 }
 /**
@@ -194,6 +204,8 @@ export function updateFromControl(control) {
     const node = mapping.customXmlNode;
     if (!node)
         return false;
+    // A picture control is the asynchronous pass's (updateFromPictureControl, CR-005 section 9): its
+    // image's bytes go back to the node as base64, as Word 15 writes them (check 38).
     if (control.type === 'Picture')
         return false;
     if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
@@ -236,6 +248,9 @@ export function updateFromControls(controls) {
     for (const control of controls) {
         if (!control.xmlMapping.isMapped)
             continue;
+        // counted by the picture pass, which reads the image part (CR-005 section 9)
+        if (control.type === 'Picture')
+            continue;
         result.bound++;
         if (updateFromControl(control))
             result.updated++;

package/dist/model/customxml/index.d.mts

@@ -5,3 +5,6 @@ export { XmlMapping, type CustomXmlPartLookup } from './XmlMapping.mjs';
 export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
 export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, holdsFlatOpc, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT, type BindingResult } from './bindings.mjs';
 export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';
+export { tagParamsOf, xpathsEntriesOf, selectEntryNode, OPENDOPE_XPATHS_NS, XHTML_CONTENT_TYPE, PICTURE_HANDLER, type XPathsEntry } from './opendope.mjs';
+export { applyXhtmlBindingTo, applyXhtmlBindingsTo, isXhtmlBound, type XhtmlHost, type XhtmlBindingOptions } from './xhtml.mjs';
+export { applyPictureHandlerTo, applyPictureHandlersTo, isPictureHandlerBound, bindPicture, pictureWidthOf, updateFromPictureControl, updateFromPictureControls, type PictureWidth, type PictureOutcome } from './pictures.mjs';

package/dist/model/customxml/index.mjs

@@ -7,3 +7,6 @@ export { XmlMapping } from './XmlMapping.mjs';
 export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
 export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, holdsFlatOpc, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT } from './bindings.mjs';
 export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';
+export { tagParamsOf, xpathsEntriesOf, selectEntryNode, OPENDOPE_XPATHS_NS, XHTML_CONTENT_TYPE, PICTURE_HANDLER } from './opendope.mjs';
+export { applyXhtmlBindingTo, applyXhtmlBindingsTo, isXhtmlBound } from './xhtml.mjs';
+export { applyPictureHandlerTo, applyPictureHandlersTo, isPictureHandlerBound, bindPicture, pictureWidthOf, updateFromPictureControl, updateFromPictureControls } from './pictures.mjs';

package/dist/model/customxml/opendope.d.mts

@@ -0,0 +1,32 @@
+import type { CustomXmlPartLookup } from './XmlMapping.mjs';
+import type { CustomXmlNode } from './CustomXmlPart.mjs';
+export declare const OPENDOPE_XPATHS_NS = "http://opendope.org/xpaths";
+export declare const XHTML_CONTENT_TYPE = "application/xhtml+xml";
+/** The tag's `od:Handler` value for a picture (the specification's section 9.3; CR-005 section 9). */
+export declare const PICTURE_HANDLER = "picture";
+/** The tag's parameters, `key=value` pairs separated by `&`, in order; a value is as written (the content type keeps its `/` and `+`). */
+export declare function tagParamsOf(tag: string): Map<string, string>;
+/**
+ * An XPaths part entry: `<xpath id="x1"><dataBinding storeItemID xpath prefixMappings/></xpath>`.
+ * The attributes are unqualified (`xpaths.xsd`: `attributeFormDefault="unqualified"`; docx4j's
+ * `org.opendope.xpaths.Xpaths` and its invoice.docx write them so); a `w:`-qualified form, which
+ * this package's own check 37 and 38 files were made with, is read as well.
+ */
+export interface XPathsEntry {
+    id: string;
+    storeItemID: string;
+    xpath: string;
+    prefixMappings: string;
+}
+/** The XPaths part's entries by id, from the first custom XML part in the OpenDoPE XPaths namespace; empty without one. */
+export declare function xpathsEntriesOf(parts: CustomXmlPartLookup): Map<string, XPathsEntry>;
+/**
+ * The node an `od:xpath` entry selects: the entry's XPath over the part its `storeItemID` names
+ * (the id compared without braces or case, as `getItem` does). What a tag-bound control's pass
+ * starts from; the note says why there is no node.
+ */
+export declare function selectEntryNode(entryId: string, parts: CustomXmlPartLookup): {
+    node: CustomXmlNode;
+} | {
+    note: string;
+};

package/dist/model/customxml/opendope.mjs

@@ -0,0 +1,56 @@
+export const OPENDOPE_XPATHS_NS = 'http://opendope.org/xpaths';
+export const XHTML_CONTENT_TYPE = 'application/xhtml+xml';
+/** The tag's `od:Handler` value for a picture (the specification's section 9.3; CR-005 section 9). */
+export const PICTURE_HANDLER = 'picture';
+/** The tag's parameters, `key=value` pairs separated by `&`, in order; a value is as written (the content type keeps its `/` and `+`). */
+export function tagParamsOf(tag) {
+    const out = new Map();
+    for (const pair of tag.split('&')) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = pair.slice(0, eq).trim();
+        if (!out.has(key))
+            out.set(key, pair.slice(eq + 1).trim());
+    }
+    return out;
+}
+/** The XPaths part's entries by id, from the first custom XML part in the OpenDoPE XPaths namespace; empty without one. */
+export function xpathsEntriesOf(parts) {
+    const out = new Map();
+    const part = parts.items.find((p) => p.namespaceUri === OPENDOPE_XPATHS_NS);
+    if (!part)
+        return out;
+    const root = part.document.documentElement;
+    if (!root)
+        return out;
+    const entries = root.getElementsByTagNameNS(OPENDOPE_XPATHS_NS, 'xpath');
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const id = entry.getAttribute('id');
+        const binding = entry.getElementsByTagNameNS(OPENDOPE_XPATHS_NS, 'dataBinding')[0];
+        if (!id || !binding)
+            continue;
+        const read = (name) => binding.getAttribute(name) || binding.getAttributeNS('http://schemas.openxmlformats.org/wordprocessingml/2006/main', name) || binding.getAttribute(`w:${name}`) || '';
+        out.set(id, { id, storeItemID: read('storeItemID'), xpath: read('xpath'), prefixMappings: read('prefixMappings') });
+    }
+    return out;
+}
+/**
+ * The node an `od:xpath` entry selects: the entry's XPath over the part its `storeItemID` names
+ * (the id compared without braces or case, as `getItem` does). What a tag-bound control's pass
+ * starts from; the note says why there is no node.
+ */
+export function selectEntryNode(entryId, parts) {
+    var _a;
+    const entry = xpathsEntriesOf(parts).get(entryId);
+    if (!entry)
+        return { note: `od:xpath=${entryId}: no such entry in the XPaths part` };
+    const part = (_a = parts.getItem(entry.storeItemID)) !== null && _a !== void 0 ? _a : parts.items.find((p) => p.id.replace(/[{}]/g, '').toLowerCase() === entry.storeItemID.replace(/[{}]/g, '').toLowerCase());
+    if (!part)
+        return { note: `od:xpath=${entryId}: no custom XML part ${entry.storeItemID}` };
+    const node = part.selectSingleNode(entry.xpath, entry.prefixMappings);
+    if (!node)
+        return { note: `od:xpath=${entryId}: ${entry.xpath} selects nothing` };
+    return { node };
+}

package/dist/model/customxml/pictures.d.mts

@@ -0,0 +1,57 @@
+import type { ContentControl } from '../content/ContentControl.mjs';
+import type { CustomXmlPartLookup } from './XmlMapping.mjs';
+import type { BindingResult } from './bindings.mjs';
+/**
+ * What the tag's `width` says: absent keeps the control's drawing and replaces its image; `auto`
+ * a new inline picture at its natural size, scaled down to the text width; `N` the same, scaled
+ * down to N twips when that is narrower than the text width (a value that is neither is `auto`,
+ * which is what docx4j does with one it cannot parse).
+ */
+export type PictureWidth = {
+    kind: 'keep';
+} | {
+    kind: 'auto';
+} | {
+    kind: 'twips';
+    twips: number;
+};
+export interface PictureOutcome {
+    done: boolean;
+    /** Why the control was left as it was. */
+    note?: string;
+}
+/** Whether a control is bound to a picture through its tag (`od:Handler=picture` with an `od:xpath`). */
+export declare function isPictureHandlerBound(control: ContentControl): boolean;
+/** The tag's `width` parameter, read as `PictureWidth` says. */
+export declare function pictureWidthOf(params: Map<string, string>): PictureWidth;
+/**
+ * Binds one control to a value: base64 image data (a data URL accepted). With `keep`, the first
+ * `a:blip` is pointed at a new image part and the drawing is left as it is, as Word binds a picture
+ * control (`setBlipImage`: a raster image in `r:embed`, the `asvg:svgBlip` taken away; an SVG under
+ * the `asvg:svgBlip`, `r:embed` taken away; the effects kept; CR-002 section 52); a picture
+ * control holding no picture gets a new inline one at its natural size instead (docx4j's pre-v3
+ * fallback), a tag-bound control holding none is left and noted. Otherwise the control's content
+ * becomes one run holding a new inline picture, sized as `PictureWidth` says, in the first
+ * paragraph of a block-level control (its properties kept) or as a run-level control's content.
+ * An empty value, a value that is not an image this package reads (PNG, JPEG, GIF, BMP; SVG where
+ * the drawing is kept, since it has no pixel size to place a new picture at), and a body with no
+ * part each leave the control as it was, with a note. The image part the control showed before
+ * stays in the package, as docx4j leaves it.
+ */
+export declare function bindPicture(control: ContentControl, value: string, width: PictureWidth, label: string): PictureOutcome;
+/** Binds one tag-bound control (shape b): the entry's node, the tag's width. */
+export declare function applyPictureHandlerTo(control: ContentControl, parts: CustomXmlPartLookup): PictureOutcome;
+/** The picture pass over the tag-bound controls, after the text bindings: counted into the result, what was left said in its notes. */
+export declare function applyPictureHandlersTo(controls: ContentControl[], parts: CustomXmlPartLookup, result: BindingResult): void;
+/**
+ * The reverse direction for a mapped picture control (docx4j's `UpdateXmlFromDocumentSurface`
+ * skips pictures; Word 15 writes the picture back, check 38): the bytes of the image part the
+ * first `a:blip` shows, as base64, into the node: its `asvg:svgBlip`'s SVG where it has one, as
+ * `InlinePicture.getBase64` gives (CR-002 section 52), else its `r:embed`'s image. Nothing is written when the node already holds
+ * those bytes (compared decoded, so Word's line-wrapped base64 counts as the same), when the
+ * control shows no picture, or when the blip's part is not an image part. Asynchronous, since a
+ * part's bytes may still be in the container.
+ */
+export declare function updateFromPictureControl(control: ContentControl): Promise<boolean>;
+/** `updateFromContentControls`' picture pass: the mapped picture controls, counted into the result. */
+export declare function updateFromPictureControls(controls: ContentControl[], result: BindingResult): Promise<void>;

package/dist/model/customxml/pictures.mjs

@@ -0,0 +1,192 @@
+import { find } from '../content/tree.mjs';
+import { addImage, addImagePart, writableWidthEmu, setBlipImage, svgBlipOf } from '../content/InlinePicture.mjs';
+import { ContentTypes } from '../../opc/ContentTypes.mjs';
+import { ImagePart } from '../../parts/BinaryPart.mjs';
+import { base64Decode, base64Encode } from '../../xml/dom.mjs';
+import { enclosingCellOf } from '../properties/table.mjs';
+import { tagParamsOf, selectEntryNode, PICTURE_HANDLER } from './opendope.mjs';
+const EMU_PER_TWIP = 635;
+const BLIP = 'org_docx4j_dml.CTBlip';
+/** Whether a control is bound to a picture through its tag (`od:Handler=picture` with an `od:xpath`). */
+export function isPictureHandlerBound(control) {
+    const params = tagParamsOf(control.tag);
+    return params.get('od:Handler') === PICTURE_HANDLER && params.has('od:xpath');
+}
+/** The tag's `width` parameter, read as `PictureWidth` says. */
+export function pictureWidthOf(params) {
+    const width = params.get('width');
+    if (width === undefined)
+        return { kind: 'keep' };
+    const twips = /^\d+$/.test(width.trim()) ? Number(width) : 0;
+    return twips > 0 ? { kind: 'twips', twips } : { kind: 'auto' };
+}
+/** The node's value as base64: a data URL's prefix dropped, whitespace left to the lenient decoder. */
+function base64Of(value) {
+    return value.replace(/^\s*data:[^,]*,/, '').trim();
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** The first `a:blip` anywhere in the control's content, whose `r:embed` is the image. */
+function firstBlipOf(control) {
+    var _a;
+    for (const blip of find((_a = control.sdt.sdtContent) !== null && _a !== void 0 ? _a : {}, BLIP))
+        return blip;
+    return undefined;
+}
+/** A width stated in twips (`dxa`, or no type), else undefined. */
+function twipsOf(width) {
+    return width && typeof width.w === 'number' && width.w >= 0 && (width.type === undefined || width.type === 'dxa') ? width.w : undefined;
+}
+/**
+ * Word's default cell margins, 108 twips left and right (the `Normal Table` style's
+ * `w:tblCellMar`, which every table inherits), taken where neither the cell nor the table states
+ * one; a table style stating other margins is not read.
+ */
+const DEFAULT_CELL_MARGIN_TWIPS = 108;
+/** The cell's left and right margins together, in twips: `w:tcMar`, else the table's `w:tblCellMar`, else Word's defaults. */
+function cellMarginsTwips(tc, tbl) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const own = (_a = tc.tcPr) === null || _a === void 0 ? void 0 : _a.tcMar;
+    const table = (_b = tbl.tblPr) === null || _b === void 0 ? void 0 : _b.tblCellMar;
+    const left = (_e = (_c = twipsOf(own === null || own === void 0 ? void 0 : own.left)) !== null && _c !== void 0 ? _c : twipsOf((_d = table === null || table === void 0 ? void 0 : table.left) !== null && _d !== void 0 ? _d : table === null || table === void 0 ? void 0 : table.start)) !== null && _e !== void 0 ? _e : DEFAULT_CELL_MARGIN_TWIPS;
+    const right = (_h = (_f = twipsOf(own === null || own === void 0 ? void 0 : own.right)) !== null && _f !== void 0 ? _f : twipsOf((_g = table === null || table === void 0 ? void 0 : table.right) !== null && _g !== void 0 ? _g : table === null || table === void 0 ? void 0 : table.end)) !== null && _h !== void 0 ? _h : DEFAULT_CELL_MARGIN_TWIPS;
+    return left + right;
+}
+/**
+ * The width a new picture must fit, in EMU: the cell's `w:tcW` less its margins when the control
+ * is in a table cell and the width is stated in twips (a percentage or `auto` falls to the page),
+ * else the page's text width; narrowed to `width=N`. Undefined where nothing states a width (a
+ * header's body has no `w:sectPr`): the natural size then.
+ */
+function maxWidthEmu(control, width) {
+    var _a;
+    const cell = enclosingCellOf(control.element.value);
+    const tcW = cell ? twipsOf((_a = cell.tc.tcPr) === null || _a === void 0 ? void 0 : _a.tcW) : undefined;
+    const inner = cell && tcW !== undefined ? tcW - cellMarginsTwips(cell.tc, cell.tbl) : undefined;
+    const cellEmu = inner !== undefined && inner > 0 ? inner * EMU_PER_TWIP : undefined;
+    const text = cellEmu !== null && cellEmu !== void 0 ? cellEmu : writableWidthEmu(control.parentBody.container);
+    if (width.kind === 'twips') {
+        const wanted = width.twips * EMU_PER_TWIP;
+        return text === undefined ? wanted : Math.min(wanted, text);
+    }
+    return text;
+}
+/**
+ * Binds one control to a value: base64 image data (a data URL accepted). With `keep`, the first
+ * `a:blip` is pointed at a new image part and the drawing is left as it is, as Word binds a picture
+ * control (`setBlipImage`: a raster image in `r:embed`, the `asvg:svgBlip` taken away; an SVG under
+ * the `asvg:svgBlip`, `r:embed` taken away; the effects kept; CR-002 section 52); a picture
+ * control holding no picture gets a new inline one at its natural size instead (docx4j's pre-v3
+ * fallback), a tag-bound control holding none is left and noted. Otherwise the control's content
+ * becomes one run holding a new inline picture, sized as `PictureWidth` says, in the first
+ * paragraph of a block-level control (its properties kept) or as a run-level control's content.
+ * An empty value, a value that is not an image this package reads (PNG, JPEG, GIF, BMP; SVG where
+ * the drawing is kept, since it has no pixel size to place a new picture at), and a body with no
+ * part each leave the control as it was, with a note. The image part the control showed before
+ * stays in the package, as docx4j leaves it.
+ */
+export function bindPicture(control, value, width, label) {
+    const base64 = base64Of(value);
+    if (base64 === '')
+        return { done: false, note: `${label}: the node is empty; the control is left as it is` };
+    const source = control.parentBody.part;
+    if (!source)
+        return { done: false, note: `${label}: the control's body has no part to hold an image` };
+    if (width.kind === 'keep') {
+        const blip = firstBlipOf(control);
+        if (blip) {
+            try {
+                const added = addImagePart(source, base64);
+                setBlipImage(blip, added.relId, added.info.contentType === ContentTypes.IMAGE_SVG);
+            }
+            catch (e) {
+                return { done: false, note: `${label}: not an image this package reads (${messageOf(e)})` };
+            }
+            control.isShowingPlaceholder = false;
+            return { done: true };
+        }
+        if (control.type !== 'Picture')
+            return { done: false, note: `${label}: the control holds no a:blip to point at the image (od:Handler=picture without width keeps the drawing)` };
+        width = { kind: 'auto' };
+    }
+    let run;
+    try {
+        run = addImage(source, base64, control.parentBody.container, maxWidthEmu(control, width)).run;
+    }
+    catch (e) {
+        return { done: false, note: `${label}: not an image this package reads (${messageOf(e)})` };
+    }
+    control.setBoundContent([run]);
+    return { done: true };
+}
+/** Binds one tag-bound control (shape b): the entry's node, the tag's width. */
+export function applyPictureHandlerTo(control, parts) {
+    var _a;
+    const params = tagParamsOf(control.tag);
+    const entryId = (_a = params.get('od:xpath')) !== null && _a !== void 0 ? _a : '';
+    const selected = selectEntryNode(entryId, parts);
+    if ('note' in selected)
+        return { done: false, note: selected.note };
+    return bindPicture(control, selected.node.text, pictureWidthOf(params), `od:xpath=${entryId}`);
+}
+/** The picture pass over the tag-bound controls, after the text bindings: counted into the result, what was left said in its notes. */
+export function applyPictureHandlersTo(controls, parts, result) {
+    var _a;
+    for (const control of controls) {
+        if (!isPictureHandlerBound(control))
+            continue;
+        result.bound++;
+        const outcome = applyPictureHandlerTo(control, parts);
+        if (outcome.done)
+            result.updated++;
+        else
+            result.skipped++;
+        if (outcome.note)
+            ((_a = result.notes) !== null && _a !== void 0 ? _a : (result.notes = [])).push(outcome.note);
+    }
+}
+/**
+ * The reverse direction for a mapped picture control (docx4j's `UpdateXmlFromDocumentSurface`
+ * skips pictures; Word 15 writes the picture back, check 38): the bytes of the image part the
+ * first `a:blip` shows, as base64, into the node: its `asvg:svgBlip`'s SVG where it has one, as
+ * `InlinePicture.getBase64` gives (CR-002 section 52), else its `r:embed`'s image. Nothing is written when the node already holds
+ * those bytes (compared decoded, so Word's line-wrapped base64 counts as the same), when the
+ * control shows no picture, or when the blip's part is not an image part. Asynchronous, since a
+ * part's bytes may still be in the container.
+ */
+export async function updateFromPictureControl(control) {
+    var _a, _b;
+    const mapping = control.xmlMapping;
+    if (!mapping.isMapped || control.type !== 'Picture')
+        return false;
+    const node = mapping.customXmlNode;
+    if (!node)
+        return false;
+    const blip = firstBlipOf(control);
+    const source = control.parentBody.part;
+    const relId = ((_a = svgBlipOf(blip)) === null || _a === void 0 ? void 0 : _a.embed) || (blip === null || blip === void 0 ? void 0 : blip.embed);
+    if (!relId || !source)
+        return false;
+    const part = (_b = source.relationshipsPart) === null || _b === void 0 ? void 0 : _b.getPart(relId);
+    if (!(part instanceof ImagePart))
+        return false;
+    const bytes = await part.getBytes();
+    const held = base64Decode(node.text);
+    if (held.length === bytes.length && held.every((b, i) => b === bytes[i]))
+        return false;
+    node.text = base64Encode(bytes);
+    return true;
+}
+/** `updateFromContentControls`' picture pass: the mapped picture controls, counted into the result. */
+export async function updateFromPictureControls(controls, result) {
+    for (const control of controls) {
+        if (control.type !== 'Picture' || !control.xmlMapping.isMapped)
+            continue;
+        result.bound++;
+        if (await updateFromPictureControl(control))
+            result.updated++;
+        else
+            result.skipped++;
+    }
+}

package/dist/model/customxml/xhtml.d.mts

@@ -0,0 +1,42 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { PropertyResolver } from '../properties/index.mjs';
+import type { ContentControl } from '../content/ContentControl.mjs';
+import type { CustomXmlPartLookup } from './XmlMapping.mjs';
+import type { BindingResult } from './bindings.mjs';
+/** What the XHTML pass needs of the package. */
+export interface XhtmlHost {
+    numbering: {
+        newList(options?: {
+            bullet?: boolean;
+        }): Promise<string>;
+        restart(numId: string): string;
+    };
+    styles: {
+        ensure(ids: readonly string[]): Promise<string[]>;
+    };
+    requireStyles(ids: Iterable<string>): void;
+    getPropertyResolver(): Promise<PropertyResolver>;
+    getMainDocumentPart(): {
+        styleDefinitionsPart?: {
+            readContents(): Promise<wml.Styles>;
+        } | undefined;
+    };
+}
+export interface XhtmlBindingOptions {
+    /** The HTML parser: a browser's `DOMParser` by default; jsdom's or linkedom's in Node. */
+    parser?: (html: string) => Document;
+}
+/** Whether a control is bound to XHTML through its tag. */
+export declare function isXhtmlBound(control: ContentControl): boolean;
+/**
+ * Binds one XHTML control. Returns what was done, or a note saying why not: no entry, no part, no
+ * node, no parser in this runtime. The content the markup gave that the control cannot hold is in
+ * `dropped` (a run-level control's blocks after the first, and what the converter dropped).
+ */
+export declare function applyXhtmlBindingTo(control: ContentControl, parts: CustomXmlPartLookup, host: XhtmlHost, options?: XhtmlBindingOptions): Promise<{
+    done: boolean;
+    note?: string;
+    dropped?: Record<string, number>;
+}>;
+/** The XHTML pass over the controls, after the text bindings: counted into the result, what was left said in its notes. */
+export declare function applyXhtmlBindingsTo(controls: ContentControl[], parts: CustomXmlPartLookup, host: XhtmlHost, result: BindingResult, options?: XhtmlBindingOptions): Promise<void>;