@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/parts/XmlPart.d.mts

@@ -21,6 +21,12 @@ export declare class XmlPart<T = unknown> extends Part {
     rootName: RootName | undefined;
     /** Runs over the DOM before unmarshalling; the package sets its MCE preprocessor here. */
     preprocessor: DomPreprocessor | undefined;
+    /**
+     * The namespace declarations the source root element carried, prefix to URI, recorded when the
+     * part was parsed. They are what `mc:Ignorable` prefixes the object model does not bind are
+     * re-declared from on marshal; see `declareIgnorablePrefixes`.
+     */
+    private sourceDeclarations;
     constructor(partName: PartName | string, contentType: string, relationshipType: string, rootName?: RootName);
     /** True once contents were unmarshalled or set; the part is then re-marshalled on save. */
     get isUnmarshalled(): boolean;
@@ -31,6 +37,16 @@ export declare class XmlPart<T = unknown> extends Part {
     get typedElement(): Jsonix.TypedNamedValue<T> | undefined;
     /** Unmarshals on first call (docx4j getContents()). */
     getContents(): Promise<T>;
+    /**
+     * The contents as a **private tree**, without marking the part unmarshalled - so a part read
+     * this way is still written back from its source bytes, byte for byte. The live tree is
+     * returned when the part is already unmarshalled, since then the part is re-marshalled
+     * anyway and a second copy would only go stale.
+     *
+     * This is what a reader that must not cost a part its round trip uses: `PropertyResolver`
+     * reads the styles and numbering parts of a document nobody has otherwise touched.
+     */
+    readContents(): Promise<T>;
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value: T, rootName?: RootName): void;
     /** Replaces the contents with raw XML bytes; they are unmarshalled on the next getContents(). */
@@ -43,4 +59,21 @@ export declare class XmlPart<T = unknown> extends Part {
     getBytes(): Promise<Uint8Array>;
     /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
     marshalToNode(): Promise<Element>;
+    /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
+    private recordDeclarations;
+    /**
+     * Every prefix the marshalled root's `mc:Ignorable` names must be declared on that root
+     * (ECMA-376 Part 3 10.1.2; Word and Excel treat an undeclared one as a corrupt part and offer
+     * to repair the file). The object model binds only the namespaces it has modules for, so an
+     * `mc:Ignorable` prefix whose content was dropped on unmarshal - `xr6`, `xr10` and `xr2` on
+     * Excel's `xl/workbook.xml`, for instance - loses its declaration: the runtime declares one
+     * prefix per entry of the objects package's table and the facade can only *remove* unused
+     * declarations, never add one it never made (CR-001 section 17).
+     *
+     * So the part re-declares them itself: from what the source root declared, else from the
+     * objects package's `NAMESPACE_PREFIXES`. A prefix neither knows is dropped from
+     * `mc:Ignorable` - an undeclared prefix is the one thing that must not be written - and warned
+     * about once.
+     */
+    private declareIgnorablePrefixes;
 }

package/dist/parts/XmlPart.mjs

@@ -1,7 +1,23 @@
-import { unmarshalNode, marshalNode } from '@docx4j/generated-objects-ts';
+import { unmarshalNode, marshalNode, NAMESPACE_PREFIXES } from '@docx4j/generated-objects-ts';
 import { Part } from './Part.mjs';
+import { Namespaces } from './Namespaces.mjs';
 import { Docx4JException } from '../opc/exceptions.mjs';
 import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION } from '../xml/dom.mjs';
+import { log } from '../model/properties/log.mjs';
+const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
+const MC_NS = Namespaces.MARKUP_COMPATIBILITY;
+/** The objects package's prefix table the other way round, prefix to URI, built once. */
+let prefixToUri;
+function knownUriOf(prefix) {
+    if (prefixToUri === undefined) {
+        prefixToUri = new Map();
+        for (const [uri, p] of Object.entries(NAMESPACE_PREFIXES))
+            if (p !== '' && !prefixToUri.has(p))
+                prefixToUri.set(p, uri);
+    }
+    return prefixToUri.get(prefix);
+}
+const warnedPrefixes = new Set();
 /**
  * A part whose content is a typed element of the object model (docx4j JaxbXmlPart<E>). `T` is the
  * root element's value type (`Document`, `Styles`, ...). Contents are unmarshalled on first
@@ -38,6 +54,7 @@ export class XmlPart extends Part {
             if (bytes === undefined)
                 throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
             const doc = parseXml(decodeXmlText(bytes));
+            this.recordDeclarations(doc);
             (_b = this.preprocessor) === null || _b === void 0 ? void 0 : _b.call(this, doc, this);
             this.element = await unmarshalNode(doc);
             (_c = this.rootName) !== null && _c !== void 0 ? _c : (this.rootName = { namespaceURI: this.element.name.namespaceURI, localPart: this.element.name.localPart });
@@ -45,6 +62,27 @@ export class XmlPart extends Part {
         }
         return this.element.value;
     }
+    /**
+     * The contents as a **private tree**, without marking the part unmarshalled - so a part read
+     * this way is still written back from its source bytes, byte for byte. The live tree is
+     * returned when the part is already unmarshalled, since then the part is re-marshalled
+     * anyway and a second copy would only go stale.
+     *
+     * This is what a reader that must not cost a part its round trip uses: `PropertyResolver`
+     * reads the styles and numbering parts of a document nobody has otherwise touched.
+     */
+    async readContents() {
+        var _a, _b;
+        if (this.element !== undefined)
+            return this.element.value;
+        const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
+        if (bytes === undefined)
+            throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
+        const doc = parseXml(decodeXmlText(bytes));
+        this.recordDeclarations(doc);
+        (_b = this.preprocessor) === null || _b === void 0 ? void 0 : _b.call(this, doc, this);
+        return (await unmarshalNode(doc)).value;
+    }
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value, rootName) {
         var _a, _b;
@@ -82,6 +120,71 @@ export class XmlPart extends Part {
     async marshalToNode() {
         if (this.element === undefined)
             await this.getContents();
-        return marshalNode(this.element);
+        const root = await marshalNode(this.element);
+        this.declareIgnorablePrefixes(root);
+        return root;
+    }
+    /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
+    recordDeclarations(doc) {
+        var _a;
+        const root = doc.documentElement;
+        if (!root)
+            return;
+        const map = new Map();
+        for (const attr of Array.from(root.attributes)) {
+            if (attr.name === 'xmlns')
+                map.set('', attr.value);
+            else if (attr.namespaceURI === XMLNS_NS || attr.name.startsWith('xmlns:'))
+                map.set((_a = attr.localName) !== null && _a !== void 0 ? _a : attr.name.slice(6), attr.value);
+        }
+        this.sourceDeclarations = map;
+    }
+    /**
+     * Every prefix the marshalled root's `mc:Ignorable` names must be declared on that root
+     * (ECMA-376 Part 3 10.1.2; Word and Excel treat an undeclared one as a corrupt part and offer
+     * to repair the file). The object model binds only the namespaces it has modules for, so an
+     * `mc:Ignorable` prefix whose content was dropped on unmarshal - `xr6`, `xr10` and `xr2` on
+     * Excel's `xl/workbook.xml`, for instance - loses its declaration: the runtime declares one
+     * prefix per entry of the objects package's table and the facade can only *remove* unused
+     * declarations, never add one it never made (CR-001 section 17).
+     *
+     * So the part re-declares them itself: from what the source root declared, else from the
+     * objects package's `NAMESPACE_PREFIXES`. A prefix neither knows is dropped from
+     * `mc:Ignorable` - an undeclared prefix is the one thing that must not be written - and warned
+     * about once.
+     */
+    declareIgnorablePrefixes(root) {
+        var _a, _b;
+        const attr = Array.from(root.attributes).find((a) => { var _a; return a.namespaceURI === MC_NS && ((_a = a.localName) !== null && _a !== void 0 ? _a : a.name) === 'Ignorable'; });
+        if (!attr)
+            return;
+        const prefixes = attr.value.split(/\s+/).filter((p) => p !== '');
+        if (prefixes.length === 0)
+            return;
+        const kept = [];
+        let dropped = false;
+        for (const prefix of prefixes) {
+            if (root.getAttributeNS(XMLNS_NS, prefix) || root.getAttribute(`xmlns:${prefix}`)) {
+                kept.push(prefix);
+                continue;
+            }
+            const uri = (_b = (_a = this.sourceDeclarations) === null || _a === void 0 ? void 0 : _a.get(prefix)) !== null && _b !== void 0 ? _b : knownUriOf(prefix);
+            if (uri === undefined) {
+                dropped = true;
+                if (!warnedPrefixes.has(prefix)) {
+                    warnedPrefixes.add(prefix);
+                    log.warn(`${this.partName}: mc:Ignorable names the prefix "${prefix}", which nothing declares; dropping it (an undeclared prefix makes Word and Excel offer to repair the file)`);
+                }
+                continue;
+            }
+            root.setAttributeNS(XMLNS_NS, `xmlns:${prefix}`, uri);
+            kept.push(prefix);
+        }
+        if (!dropped)
+            return;
+        if (kept.length === 0)
+            root.removeAttributeNode(attr);
+        else
+            root.setAttributeNS(MC_NS, attr.name, kept.join(' '));
     }
 }

package/dist/parts/pml/defaults.d.mts

@@ -0,0 +1,6 @@
+/** `/ppt/slideMasters/slideMaster1.xml` as docx4j's `SlideMasterPart.createSldMaster()` writes it. */
+export declare const DEFAULT_SLIDE_MASTER_XML: string;
+/** `/ppt/slideLayouts/slideLayout1.xml` as docx4j's `SlideLayoutPart.createSldLayout()` writes it. */
+export declare const DEFAULT_SLIDE_LAYOUT_XML: string;
+/** `/ppt/slides/slide1.xml` as docx4j's `SlidePart.createSld()` writes it. */
+export declare const DEFAULT_SLIDE_XML: string;

package/dist/parts/pml/defaults.mjs

@@ -0,0 +1,53 @@
+// The template markup `PresentationMLPackage.createPackage()` starts a new presentation from, as
+// docx4j builds it (docx4j VERSION_17_1_1 a58cf10b8):
+//
+//   docx4j-core/src/main/java/org/docx4j/openpackaging/parts/PresentationML/JaxbPmlPart.java
+//     COMMON_SLIDE_DATA, COLOR_MAPPING
+//   .../PresentationML/SlideMasterPart.java      createSldMaster()
+//   .../PresentationML/SlideLayoutPart.java      createSldLayout()   (cSld name "Title Slide")
+//   .../PresentationML/SlidePart.java            createSld()
+//
+// docx4j unmarshals those fragments into a JAXB tree and marshals it back out; here they are the
+// whole part, so a created slide, layout or master that nobody touches is written byte for byte
+// as docx4j writes it.  Generated content, not hand markup: do not edit without the Java.
+//
+// The placeholder shapes a created layout and slide also carry are not here either: they are
+// built with the generated factories in `placeholders.mts`, because PowerPoint offers
+// "Click to add title" only where the slide itself holds them (CR-001 section 17.2). So the
+// layout and the slide are unmarshalled during creation and are no longer written byte for byte
+// as they are below; the master still is.
+//
+// The theme part is not here: `createPackage()` uses the same embedded Office themes as
+// `WordprocessingMLPackage.createPackage()` (`src/model/fonts/themes.generated.mts`), so which
+// theme a new presentation carries follows `pkg.fonts.defaultTheme`, as it does for a new
+// document.  docx4j instead ships one fixed
+// `org/docx4j/openpackaging/parts/PresentationML/theme.xml` (CR-001 section 16).
+const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>';
+const NS = ' xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"'
+    + ' xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"'
+    + ' xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"';
+/** docx4j `JaxbPmlPart.COMMON_SLIDE_DATA`: an empty shape tree. `name` is the `p:cSld/@name`. */
+function commonSlideData(name) {
+    return `<p:cSld${name === undefined ? '' : ` name="${name}"`}>`
+        + '<p:spTree>'
+        + '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>'
+        + '<p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr>'
+        + '</p:spTree>'
+        + '</p:cSld>';
+}
+/** docx4j `JaxbPmlPart.COLOR_MAPPING`: the identity colour map a master needs. */
+const COLOR_MAPPING = '<p:clrMap bg1="lt1" tx1="dk1" bg2="lt2" tx2="dk2" accent1="accent1"'
+    + ' accent2="accent2" accent3="accent3" accent4="accent4" accent5="accent5" accent6="accent6"'
+    + ' hlink="hlink" folHlink="folHlink"/>';
+/** `/ppt/slideMasters/slideMaster1.xml` as docx4j's `SlideMasterPart.createSldMaster()` writes it. */
+export const DEFAULT_SLIDE_MASTER_XML = `${XML_DECL}<p:sldMaster${NS}>`
+    + commonSlideData() + COLOR_MAPPING + '<p:sldLayoutIdLst/>'
+    + '</p:sldMaster>';
+/** `/ppt/slideLayouts/slideLayout1.xml` as docx4j's `SlideLayoutPart.createSldLayout()` writes it. */
+export const DEFAULT_SLIDE_LAYOUT_XML = `${XML_DECL}<p:sldLayout${NS}>`
+    + commonSlideData('Title Slide')
+    + '</p:sldLayout>';
+/** `/ppt/slides/slide1.xml` as docx4j's `SlidePart.createSld()` writes it. */
+export const DEFAULT_SLIDE_XML = `${XML_DECL}<p:sld${NS}>`
+    + commonSlideData()
+    + '</p:sld>';

package/dist/parts/pml/index.d.mts

@@ -4,21 +4,83 @@ import { XmlPart } from '../XmlPart.mjs';
 import { BinaryPart } from '../BinaryPart.mjs';
 import { Part } from '../Part.mjs';
 import { PartName } from '../../opc/PartName.mjs';
+import type { AddPartBehaviour } from '../RelationshipsPart.mjs';
 import { ThemePart } from '../dml/index.mjs';
+/**
+ * A new `p:sldId/@id` (docx4j `JaxbPmlPart.getSlideId()`, ECMA-376 4.8.17 ST_SlideId: 256 to
+ * 2147483647). Random, as docx4j's is: nothing in the package numbers them.
+ */
+export declare function nextSlideId(): number;
+/**
+ * A new `p:sldLayoutId/@id` or `p:sldMasterId/@id` (docx4j
+ * `JaxbPmlPart.getSlideLayoutOrMasterId()`, ECMA-376 4.8.18 and 4.8.20: above 2147483648).
+ */
+export declare function nextSlideLayoutOrMasterId(): number;
 export declare class MainPresentationPart extends XmlPart<pml.Presentation> {
     themePart: ThemePart | undefined;
+    notesMasterPart: NotesMasterPart | undefined;
+    commentAuthorsPart: CommentAuthorsPart | undefined;
+    presentationPropertiesPart: PresentationPropertiesPart | undefined;
+    viewPropertiesPart: ViewPropertiesPart | undefined;
+    tableStylesPart: TableStylesPart | undefined;
     constructor(partName?: PartName | string, contentType?: string);
     setPartShortcut(part: Part, relationshipType: string): boolean;
+    /**
+     * The slides, in `p:sldIdLst` order (docx4j `getSlideParts()`), once the part is unmarshalled;
+     * before that, in relationship order, which is the order they were added in.
+     */
     get slideParts(): SlidePart[];
+    /** The slides in `p:sldIdLst` order, unmarshalling the part first (docx4j `getSlideParts()`). */
+    getSlideParts(): Promise<SlidePart[]>;
+    /** The slide masters, in `p:sldMasterIdLst` order once the part is unmarshalled. */
+    get slideMasterParts(): SlideMasterPart[];
+    /** The slide at an index of `p:sldIdLst` (docx4j `getSlide(int)`). */
+    getSlide(index: number): SlidePart;
+    /** docx4j `getSlideCount()`. */
+    get slideCount(): number;
+    /**
+     * Adds a slide part as a target and appends a `p:sldId` for it (docx4j
+     * `addSlideIdListEntry(SlidePart)`); the part must be unmarshalled.
+     */
+    addSlideIdListEntry(slidePart: SlidePart, mode?: AddPartBehaviour): pml.Presentation.SldIdLst.SldId;
+    /**
+     * docx4j `addSlide(SlidePart)` / `addSlide(int, SlidePart)`: appends the slide, or inserts it
+     * at `index`, renaming the part if the name is taken (PowerPoint cannot open a package in which
+     * two relationships target the same slide, so a slide is never added twice).
+     *
+     * `layoutPart`, when given, becomes the slide's layout relationship, as a slide needs one.
+     */
+    addSlide(slidePart: SlidePart, index?: number, layoutPart?: SlideLayoutPart): pml.Presentation.SldIdLst.SldId;
+    /** docx4j `addSlideMasterIdListEntry(SlideMasterPart)`. */
+    addSlideMasterIdListEntry(masterPart: SlideMasterPart): pml.Presentation.SldMasterIdLst.SldMasterId;
+    /** docx4j `removeSlide(int)`: the `p:sldId`, the relationship and the part. */
+    removeSlide(index: number): SlidePart;
+    private sldIdLst;
 }
 export declare class SlidePart extends XmlPart<pml.Sld> {
-    constructor(partName: PartName | string);
+    slideLayoutPart: SlideLayoutPart | undefined;
+    notesSlidePart: NotesSlidePart | undefined;
+    commentsPart: PresentationCommentsPart | undefined;
+    constructor(partName?: PartName | string);
+    setPartShortcut(part: Part, relationshipType: string): boolean;
 }
 export declare class SlideLayoutPart extends XmlPart<pml.SldLayout> {
-    constructor(partName: PartName | string);
+    /** docx4j `SlideLayoutPart.getSlideMasterPart()`. */
+    slideMasterPart: SlideMasterPart | undefined;
+    constructor(partName?: PartName | string);
+    setPartShortcut(part: Part, relationshipType: string): boolean;
 }
 export declare class SlideMasterPart extends XmlPart<pml.SldMaster> {
-    constructor(partName: PartName | string);
+    themePart: ThemePart | undefined;
+    constructor(partName?: PartName | string);
+    setPartShortcut(part: Part, relationshipType: string): boolean;
+    /**
+     * Adds a layout part as a target and appends a `p:sldLayoutId` for it (docx4j
+     * `addSlideLayoutIdListEntry`); the master must be unmarshalled.
+     */
+    addSlideLayoutIdListEntry(slideLayoutPart: SlideLayoutPart): pml.SlideLayoutIdList.SldLayoutId;
+    /** This master's layouts, in `p:sldLayoutIdLst` order once the master is unmarshalled. */
+    get slideLayoutParts(): SlideLayoutPart[];
 }
 export declare class NotesSlidePart extends XmlPart<pml.Notes> {
     constructor(partName: PartName | string);
@@ -51,3 +113,4 @@ export declare class TagsPart extends XmlPart<pml.TagLst> {
 export declare class FontDataPart extends BinaryPart {
     constructor(partName: PartName | string);
 }
+export { type SlideTextOptions, type Rect, placeholderGeometry, placeholderShape, slidePlaceholders, layoutPlaceholders, addShapes, bodyLines, placeholdersOf, slidePlaceholdersFor, } from './placeholders.mjs';

package/dist/parts/pml/index.mjs

@@ -1,41 +1,239 @@
+import { createPresentationSldIdLstSldId, createPresentationSldMasterIdLstSldMasterId, createSlideLayoutIdListSldLayoutId, } from '@docx4j/generated-objects-ts/factory/org_pptx4j_pml';
 import { XmlPart } from '../XmlPart.mjs';
 import { BinaryPart } from '../BinaryPart.mjs';
 import { ContentTypes } from '../../opc/ContentTypes.mjs';
 import { Namespaces } from '../Namespaces.mjs';
+import { Pptx4jException } from '../../opc/exceptions.mjs';
 const P = 'http://schemas.openxmlformats.org/presentationml/2006/main';
 const A = 'http://schemas.openxmlformats.org/drawingml/2006/main';
+/** The parts an id list's `r:id`s point at, in list order, skipping any that is not of the class. */
+function partsByRelId(entries, rp, cls) {
+    const out = [];
+    for (const entry of entries) {
+        const part = rp.getPart(entry.rid);
+        if (part instanceof cls)
+            out.push(part);
+    }
+    return out;
+}
+/**
+ * A new `p:sldId/@id` (docx4j `JaxbPmlPart.getSlideId()`, ECMA-376 4.8.17 ST_SlideId: 256 to
+ * 2147483647). Random, as docx4j's is: nothing in the package numbers them.
+ */
+export function nextSlideId() {
+    return Math.floor(Math.random() * 2147483392) + 256;
+}
+/**
+ * A new `p:sldLayoutId/@id` or `p:sldMasterId/@id` (docx4j
+ * `JaxbPmlPart.getSlideLayoutOrMasterId()`, ECMA-376 4.8.18 and 4.8.20: above 2147483648).
+ */
+export function nextSlideLayoutOrMasterId() {
+    return Math.floor(Math.random() * 2147483647) + 2147483648;
+}
 export class MainPresentationPart extends XmlPart {
     constructor(partName = '/ppt/presentation.xml', contentType = ContentTypes.PRESENTATIONML_MAIN) {
         super(partName, contentType, Namespaces.PRESENTATIONML_MAIN, { namespaceURI: P, localPart: 'presentation' });
     }
     setPartShortcut(part, relationshipType) {
-        if (relationshipType === Namespaces.THEME) {
-            this.themePart = part;
-            return true;
+        switch (relationshipType) {
+            case Namespaces.THEME:
+                this.themePart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_NOTES_MASTER:
+                this.notesMasterPart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_COMMENT_AUTHORS:
+                this.commentAuthorsPart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_PRES_PROPS:
+                this.presentationPropertiesPart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_VIEW_PROPS:
+                this.viewPropertiesPart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_TABLE_STYLES:
+                this.tableStylesPart = part;
+                return true;
+            default: return false;
         }
-        return false;
     }
+    /**
+     * The slides, in `p:sldIdLst` order (docx4j `getSlideParts()`), once the part is unmarshalled;
+     * before that, in relationship order, which is the order they were added in.
+     */
     get slideParts() {
+        var _a;
         const rp = this.relationshipsPart;
         if (!rp)
             return [];
+        if (this.isUnmarshalled) {
+            const entries = (_a = this.contents.sldIdLst) === null || _a === void 0 ? void 0 : _a.sldId;
+            if (entries)
+                return partsByRelId(entries, rp, SlidePart);
+        }
         return rp.getRelationshipsByType(Namespaces.PRESENTATIONML_SLIDE).map((r) => rp.getPart(r)).filter((p) => p instanceof SlidePart);
     }
+    /** The slides in `p:sldIdLst` order, unmarshalling the part first (docx4j `getSlideParts()`). */
+    async getSlideParts() {
+        await this.getContents();
+        return this.slideParts;
+    }
+    /** The slide masters, in `p:sldMasterIdLst` order once the part is unmarshalled. */
+    get slideMasterParts() {
+        var _a;
+        const rp = this.relationshipsPart;
+        if (!rp)
+            return [];
+        if (this.isUnmarshalled) {
+            const entries = (_a = this.contents.sldMasterIdLst) === null || _a === void 0 ? void 0 : _a.sldMasterId;
+            if (entries)
+                return partsByRelId(entries, rp, SlideMasterPart);
+        }
+        return rp.getRelationshipsByType(Namespaces.PRESENTATIONML_SLIDE_MASTER).map((r) => rp.getPart(r)).filter((p) => p instanceof SlideMasterPart);
+    }
+    /** The slide at an index of `p:sldIdLst` (docx4j `getSlide(int)`). */
+    getSlide(index) {
+        const slides = this.slideParts;
+        const slide = slides[index];
+        if (!slide)
+            throw new Pptx4jException(`No slide at index ${index}. (There are ${slides.length} slides)`);
+        return slide;
+    }
+    /** docx4j `getSlideCount()`. */
+    get slideCount() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.contents.sldIdLst) === null || _a === void 0 ? void 0 : _a.sldId) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0;
+    }
+    /**
+     * Adds a slide part as a target and appends a `p:sldId` for it (docx4j
+     * `addSlideIdListEntry(SlidePart)`); the part must be unmarshalled.
+     */
+    addSlideIdListEntry(slidePart, mode = 'OVERWRITE_IF_NAME_EXISTS') {
+        const rel = this.addTargetPart(slidePart, mode);
+        const entry = createPresentationSldIdLstSldId({ id: nextSlideId(), rid: rel.id });
+        this.sldIdLst().sldId.push(entry);
+        return entry;
+    }
+    /**
+     * docx4j `addSlide(SlidePart)` / `addSlide(int, SlidePart)`: appends the slide, or inserts it
+     * at `index`, renaming the part if the name is taken (PowerPoint cannot open a package in which
+     * two relationships target the same slide, so a slide is never added twice).
+     *
+     * `layoutPart`, when given, becomes the slide's layout relationship, as a slide needs one.
+     */
+    addSlide(slidePart, index, layoutPart) {
+        const sldId = this.sldIdLst().sldId;
+        if (index !== undefined && (index < 0 || index > sldId.length)) {
+            throw new Pptx4jException(`Can't add slide at index ${index}. (There are ${sldId.length} slides) `);
+        }
+        const rel = this.addTargetPart(slidePart, 'RENAME_IF_NAME_EXISTS');
+        const entry = createPresentationSldIdLstSldId({ id: nextSlideId(), rid: rel.id });
+        if (index === undefined)
+            sldId.push(entry);
+        else
+            sldId.splice(index, 0, entry);
+        if (layoutPart)
+            slidePart.addTargetPart(layoutPart);
+        return entry;
+    }
+    /** docx4j `addSlideMasterIdListEntry(SlideMasterPart)`. */
+    addSlideMasterIdListEntry(masterPart) {
+        var _a, _b;
+        var _c;
+        const rel = this.addTargetPart(masterPart);
+        const entry = createPresentationSldMasterIdLstSldMasterId({ id: nextSlideLayoutOrMasterId(), rid: rel.id });
+        const lst = ((_a = (_c = this.contents).sldMasterIdLst) !== null && _a !== void 0 ? _a : (_c.sldMasterIdLst = { sldMasterId: [] }));
+        ((_b = lst.sldMasterId) !== null && _b !== void 0 ? _b : (lst.sldMasterId = [])).push(entry);
+        return entry;
+    }
+    /** docx4j `removeSlide(int)`: the `p:sldId`, the relationship and the part. */
+    removeSlide(index) {
+        const sldId = this.sldIdLst().sldId;
+        const entry = sldId[index];
+        if (!entry)
+            throw new Pptx4jException(`No slide at index ${index}. (There are ${sldId.length} slides) `);
+        sldId.splice(index, 1);
+        const rp = this.relationshipsPart;
+        const part = rp.getPart(entry.rid);
+        rp.removePart(part.partName);
+        return part;
+    }
+    sldIdLst() {
+        var _a, _b;
+        const contents = this.contents;
+        const lst = ((_a = contents.sldIdLst) !== null && _a !== void 0 ? _a : (contents.sldIdLst = { sldId: [] }));
+        (_b = lst.sldId) !== null && _b !== void 0 ? _b : (lst.sldId = []);
+        return lst;
+    }
 }
 export class SlidePart extends XmlPart {
-    constructor(partName) {
+    constructor(partName = '/ppt/slides/slide1.xml') {
         super(partName, ContentTypes.PRESENTATIONML_SLIDE, Namespaces.PRESENTATIONML_SLIDE, { namespaceURI: P, localPart: 'sld' });
     }
+    setPartShortcut(part, relationshipType) {
+        switch (relationshipType) {
+            case Namespaces.PRESENTATIONML_SLIDE_LAYOUT:
+                this.slideLayoutPart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_NOTES_SLIDE:
+                this.notesSlidePart = part;
+                return true;
+            case Namespaces.PRESENTATIONML_COMMENTS:
+                this.commentsPart = part;
+                return true;
+            default: return false;
+        }
+    }
 }
 export class SlideLayoutPart extends XmlPart {
-    constructor(partName) {
+    constructor(partName = '/ppt/slideLayouts/slideLayout1.xml') {
         super(partName, ContentTypes.PRESENTATIONML_SLIDE_LAYOUT, Namespaces.PRESENTATIONML_SLIDE_LAYOUT, { namespaceURI: P, localPart: 'sldLayout' });
     }
+    setPartShortcut(part, relationshipType) {
+        if (relationshipType === Namespaces.PRESENTATIONML_SLIDE_MASTER) {
+            this.slideMasterPart = part;
+            return true;
+        }
+        return false;
+    }
 }
 export class SlideMasterPart extends XmlPart {
-    constructor(partName) {
+    constructor(partName = '/ppt/slideMasters/slideMaster1.xml') {
         super(partName, ContentTypes.PRESENTATIONML_SLIDE_MASTER, Namespaces.PRESENTATIONML_SLIDE_MASTER, { namespaceURI: P, localPart: 'sldMaster' });
     }
+    setPartShortcut(part, relationshipType) {
+        if (relationshipType === Namespaces.THEME) {
+            this.themePart = part;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Adds a layout part as a target and appends a `p:sldLayoutId` for it (docx4j
+     * `addSlideLayoutIdListEntry`); the master must be unmarshalled.
+     */
+    addSlideLayoutIdListEntry(slideLayoutPart) {
+        var _a, _b;
+        var _c;
+        const rel = this.addTargetPart(slideLayoutPart);
+        const entry = createSlideLayoutIdListSldLayoutId({ id: nextSlideLayoutOrMasterId(), rid: rel.id });
+        const lst = ((_a = (_c = this.contents).sldLayoutIdLst) !== null && _a !== void 0 ? _a : (_c.sldLayoutIdLst = { sldLayoutId: [] }));
+        ((_b = lst.sldLayoutId) !== null && _b !== void 0 ? _b : (lst.sldLayoutId = [])).push(entry);
+        return entry;
+    }
+    /** This master's layouts, in `p:sldLayoutIdLst` order once the master is unmarshalled. */
+    get slideLayoutParts() {
+        var _a;
+        const rp = this.relationshipsPart;
+        if (!rp)
+            return [];
+        if (this.isUnmarshalled) {
+            const entries = (_a = this.contents.sldLayoutIdLst) === null || _a === void 0 ? void 0 : _a.sldLayoutId;
+            if (entries)
+                return partsByRelId(entries, rp, SlideLayoutPart);
+        }
+        return rp.getRelationshipsByType(Namespaces.PRESENTATIONML_SLIDE_LAYOUT).map((r) => rp.getPart(r)).filter((p) => p instanceof SlideLayoutPart);
+    }
 }
 export class NotesSlidePart extends XmlPart {
     constructor(partName) {
@@ -88,3 +286,4 @@ export class FontDataPart extends BinaryPart {
         super(partName, ContentTypes.PRESENTATIONML_FONT_DATA, Namespaces.PRESENTATIONML_FONT_DATA);
     }
 }
+export { placeholderGeometry, placeholderShape, slidePlaceholders, layoutPlaceholders, addShapes, bodyLines, placeholdersOf, slidePlaceholdersFor, } from './placeholders.mjs';

package/dist/parts/pml/placeholders.d.mts

@@ -0,0 +1,71 @@
+import type * as pml from '@docx4j/generated-objects-ts/modules/org_pptx4j_pml';
+/** The text of a created slide's placeholders; `body` is one paragraph per line, or per entry. */
+export interface SlideTextOptions {
+    /** The title placeholder's text; the placeholder is left empty (its prompt) when absent. */
+    title?: string;
+    /** The body placeholder's text: a string (split on newlines) or one string per paragraph. */
+    body?: string | string[];
+}
+/** A rectangle in EMU, as `a:xfrm` carries it. */
+export interface Rect {
+    x: number;
+    y: number;
+    cx: number;
+    cy: number;
+}
+/**
+ * Where the title and body placeholders sit, as fractions of the slide: PowerPoint's own
+ * Title and Content layout at 4:3 (title 685800, 457200, 7772400 x 1143000; body 685800,
+ * 1600200, 7772400 x 4525963 of 9144000 x 6858000), so any slide size is laid out the same way.
+ */
+export declare function placeholderGeometry(sldSz: {
+    cx?: number;
+    cy?: number;
+} | undefined): {
+    title: Rect;
+    body: Rect;
+};
+/** The body text as paragraphs: a string is split on newlines, as Office JS's `insertText` does. */
+export declare function bodyLines(body: string | string[] | undefined): string[];
+/**
+ * One placeholder shape (docx4j's `SAMPLE_SHAPE` in `PresentationMLPackage`, and the layout
+ * markup of its `SlidePlaceholder` sample): `p:sp` with `a:spLocks noGrp`, the `p:ph`, an
+ * optional `a:xfrm` and a `p:txBody` of the lines given.
+ */
+export declare function placeholderShape(options: {
+    id: number;
+    name: string;
+    type?: pml.STPlaceholderType;
+    idx?: number;
+    xfrm?: Rect;
+    lines?: string[];
+}): pml.Shape;
+/**
+ * The title (`p:ph type="title"`) and body (`p:ph idx="1"`) shapes a created **slide** carries,
+ * with no geometry of their own: each inherits the layout's, which is what a placeholder is for.
+ */
+export declare function slidePlaceholders(text?: SlideTextOptions): pml.Shape[];
+/**
+ * The same pair for the **layout**, with the geometry the slides inherit and PowerPoint's own
+ * prompt text. Without these the slide's placeholders would have nothing to inherit from and
+ * PowerPoint would draw them at the origin with no size.
+ */
+export declare function layoutPlaceholders(sldSz: {
+    cx?: number;
+    cy?: number;
+} | undefined): pml.Shape[];
+/** The placeholder shapes of a slide, layout or master, in shape-tree order. */
+export declare function placeholdersOf(cSld: pml.CommonSlideData | undefined): {
+    shape: pml.Shape;
+    ph: pml.CTPlaceholder;
+}[];
+/**
+ * The placeholders a new slide on this layout carries: one shape per placeholder the layout
+ * defines (bar the date, footer and slide-number ones), with the layout's `type` and `idx` so
+ * that each inherits that layout shape's position and text style, and with the text given in the
+ * first title and the first body one. A layout that defines none - docx4j's own - gets the
+ * default title and body pair.
+ */
+export declare function slidePlaceholdersFor(layout: pml.CommonSlideData | undefined, text?: SlideTextOptions): pml.Shape[];
+/** Puts shapes into a slide's or layout's shape tree (docx4j `cSld.getSpTree().getSpOrGrpSpOrGraphicFrame().add(...)`). */
+export declare function addShapes(spTree: pml.GroupShape, shapes: pml.Shape[]): void;