@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/xlsx/hyperlinks.js

@@ -1,31 +1,16 @@
-import { tryDecodeRange } from '../../core/address.js';
-import { isHyperlinkValue, isRichTextValue } from '../../core/value.js';
+import { boundedRect, tryDecodeRange } from '../../core/address.js';
 import {} from '../../xml/xml-read.js';
 import { localName } from '../../xml/xml-scan.js';
 import { escapeAttr, textAttr } from '../../xml/xml.js';
-export function collectHyperlinks(sheet) {
-    const links = [];
-    for (const { cells } of sheet.rows()) {
-        for (const cell of cells) {
-            const value = cell.value;
-            if (isHyperlinkValue(value)) {
-                links.push({
-                    ref: value.range ?? cell.address,
-                    target: value.hyperlink,
-                    ...(value.tooltip !== undefined ? { tooltip: value.tooltip } : {}),
-                });
-            }
-        }
-    }
-    return links;
-}
+import { relAttr } from '../opc/namespaces.js';
+import { REL } from './relationships.js';
 export function planHyperlinks(links, rels) {
     return links.map((link) => {
         const tooltip = link.tooltip !== undefined ? { tooltip: link.tooltip } : {};
         if (link.target.startsWith('#')) {
             return { ref: link.ref, location: link.target.slice(1), ...tooltip };
         }
-        return { ref: link.ref, relId: rels.next(), target: link.target, ...tooltip };
+        return { ref: link.ref, relId: rels.addExternal(REL.hyperlink, link.target), ...tooltip };
     });
 }
 export function hyperlinksXml(links) {
@@ -45,15 +30,16 @@ export function sheetHyperlinkPass() {
     const links = [];
     return {
         handlers: {
-            onOpen(name, attrs) {
+            onOpen(name, attrs, _selfClosing, scope) {
                 if (localName(name) !== 'hyperlink')
                     return;
                 const ref = attrs.ref;
                 if (ref === undefined)
                     return;
+                const rid = relAttr(scope, attrs, 'id');
                 links.push({
                     ref,
-                    ...(attrs['r:id'] !== undefined ? { rid: attrs['r:id'] } : {}),
+                    ...(rid !== undefined ? { rid } : {}),
                     ...(attrs.location !== undefined ? { location: attrs.location } : {}),
                     ...(attrs.tooltip !== undefined ? { tooltip: attrs.tooltip } : {}),
                 });
@@ -68,19 +54,13 @@ export function applyHyperlinks(sheet, links, targetOf) {
         if (target === undefined)
             continue;
         const decoded = tryDecodeRange(link.ref);
-        if (decoded === undefined || decoded.tl.col === undefined || decoded.tl.row === undefined)
+        if (decoded === undefined || boundedRect(decoded) === undefined)
             continue;
-        const cell = sheet.getCell(decoded.tl.address);
-        const cellValue = cell.value;
-        const text = typeof cellValue === 'string' ? cellValue : isRichTextValue(cellValue) ? cellValue : '';
-        const spansRange = decoded.tl.address !== decoded.br.address;
-        const value = {
-            hyperlink: target,
-            text,
+        sheet.addHyperlink({
+            ref: link.ref,
+            target,
             ...(link.tooltip !== undefined ? { tooltip: link.tooltip } : {}),
-            ...(spansRange ? { range: link.ref } : {}),
-        };
-        cell.value = value;
+        });
     }
 }
 function resolveTarget(link, targetOf) {

package/dist/io/xlsx/images.d.ts

@@ -1,20 +1,32 @@
-import { type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs } from '../../core/image.ts';
+import { type AnchorPoint, type Extent, type ImageAnchor, type ImageCrop, type ImageEditAs, type PictureProperties } from '../../core/image.ts';
 /** The content type for a media part's `<Default Extension>` entry in `[Content_Types].xml`. */
 export declare function imageContentType(extension: string): string;
-/** One image placed in a drawing: where it sits and the drawing-local relationship id that ties it
- * to its media bytes. */
+/** One image placed in a drawing: where it sits, the drawing-local relationship id that ties it to its
+ * media bytes, and the picture's own properties. */
 export interface DrawingImage {
     readonly anchor: ImageAnchor;
     /** The `r:embed` id referencing this image's entry in the drawing's own `.rels`. */
     readonly embedId: string;
+    readonly properties: PictureProperties;
+    /** The `r:id` of the hyperlink relationship in the drawing's own `.rels`, when the picture is a link. */
+    readonly hyperlinkId?: string;
 }
 /** The `xl/drawings/drawing{n}.xml` part: one anchor per image, two-cell or one-cell by its shape. */
 export declare function drawingXml(images: readonly DrawingImage[]): string;
-/** The drawing's `_rels/drawing{n}.xml.rels`: one image relationship per anchor, in `embedId` order
- * (`rId1`, `rId2`, …), each pointing at the media part the anchor shows. */
-export declare function drawingRelsXml(mediaTargets: readonly string[]): string;
+/**
+ * A drawing kept from a file with pictures added to it: each picture's anchor goes after the drawing's
+ * own content, so it draws on top, as a picture inserted last does in Excel.
+ *
+ * A drawing numbers its shapes by `cNvPr id`, unique within it, so the pictures take ids past the
+ * highest one there. Their `r:embed` and link ids are the caller's, allocated past the relationships
+ * the drawing already holds.
+ *
+ * @throws {AuthoringError} if the kept part has no `<wsDr>` root to add a picture to.
+ */
+export declare function mergePictures(drawing: string, images: readonly DrawingImage[]): string;
 /** An image anchor parsed from a drawing part, with the `r:embed` id that names its media. A two-cell
- * anchor carries `to` (and may carry `editAs`); a one-cell anchor carries `ext` instead. */
+ * anchor carries `to` and its `editAs`, the schema default filled in; a one-cell anchor carries `ext`
+ * instead. */
 export interface ParsedImageAnchor {
     readonly from: AnchorPoint;
     readonly to?: AnchorPoint;
@@ -22,13 +34,34 @@ export interface ParsedImageAnchor {
     readonly editAs?: ImageEditAs;
     readonly rotation?: number;
     readonly embed: string;
+    readonly description?: string;
+    readonly title?: string;
+    readonly crop?: ImageCrop;
+    /** The `r:id` of the picture's `a:hlinkClick`, for the caller to resolve against the drawing's rels. */
+    readonly hyperlinkId?: string;
+    readonly tooltip?: string;
 }
-/** Parse a drawing part into its image anchors (both `<xdr:twoCellAnchor>` and `<xdr:oneCellAnchor>`).
- * Anchors that are not pictures (a chart, a shape) carry no `<a:blip r:embed>` and are skipped, so a
- * mixed drawing yields only its images. */
-export declare function parseDrawing(xml: string): ParsedImageAnchor[];
-/** Whether a drawing part holds anchor content beyond plain pictures: a chart, shape, connector, or
- * group. Excel packs every one of a sheet's anchors into a single drawing part, so a sheet with both a
- * picture and a chart yields a mixed drawing; modeling only its pictures and re-serialising from them
- * would drop the chart. The reader uses this to fall back to whole-drawing byte-preservation instead. */
-export declare function drawingHasUnmodeledContent(xml: string): boolean;
+/** A drawing part as the reader sees it: the picture anchors it could model, and whether those anchors
+ * are the whole of it. */
+export interface ParsedDrawing {
+    readonly anchors: readonly ParsedImageAnchor[];
+    /**
+     * Whether every anchor is a two-cell or one-cell anchor holding exactly one embedded picture. When it
+     * is not, writing the drawing back from `anchors` would leave the rest out, so the reader keeps the
+     * whole part byte for byte instead.
+     */
+    readonly fullyModeled: boolean;
+}
+/**
+ * Parse a drawing part into its picture anchors (`<xdr:twoCellAnchor>` and `<xdr:oneCellAnchor>`), and
+ * decide in the same scan whether they are the whole drawing. It is fully modeled only when every
+ * anchor holds exactly one picture whose bytes are embedded; anything else in it, including a picture
+ * that links its image rather than embedding it, has no place in the image model.
+ *
+ * This used to be two scans: one listing the content the model skips, and this one. The list missed
+ * an absolute anchor and a linked picture, so a drawing holding either counted as modeled and lost them
+ * on write. What an anchor holds is now judged by what the parse found in it, one embedded picture or
+ * not, so no kind of anchor content can slip past unnamed; the list left names only the anchor kinds
+ * and wrappers this parse does not otherwise open an anchor for.
+ */
+export declare function parseDrawing(xml: string): ParsedDrawing;

package/dist/io/xlsx/images.js

@@ -1,11 +1,11 @@
 import { isImageEditAs, isOneCellAnchor, } from '../../core/image.js';
-import { parseXml, TextCapture } from '../../xml/xml-read.js';
-import { enumToken, localName, numFinite } from '../../xml/xml-scan.js';
-import { checkedToken, numAttr, numberText, XML_DECLARATION } from '../../xml/xml.js';
-import { RELATIONSHIPS_NS } from '../opc/namespaces.js';
-import { relationship, relationshipsPart } from '../opc/rels.js';
+import { assertWritableNumber, AuthoringError } from '../../errors.js';
+import { enumToken, numFinite, numInteger } from '../../xml/xml-attrs.js';
+import { elementRange, openElements, parseXml, TextCapture } from '../../xml/xml-read.js';
+import { localName } from '../../xml/xml-scan.js';
+import { checkedToken, escapeAttr, intAttr, numAttr, numberText, textAttr, XML_DECLARATION, } from '../../xml/xml.js';
+import { relAttr, RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { DRAWINGML_NS, XDR_NS } from './namespaces.js';
-const IMAGE_REL_TYPE = `${RELATIONSHIPS_NS}/image`;
 const IMAGE_CONTENT_TYPES = new Map([
     ['png', 'image/png'],
     ['jpg', 'image/jpeg'],
@@ -22,81 +22,185 @@ export function imageContentType(extension) {
     const ext = extension.toLowerCase();
     return IMAGE_CONTENT_TYPES.get(ext) ?? `image/${ext}`;
 }
+const ANCHOR_NAMESPACES = ` xmlns:xdr="${XDR_NS}" xmlns:a="${DRAWINGML_NS}" xmlns:r="${RELATIONSHIPS_NS}"`;
 export function drawingXml(images) {
-    const anchors = images.map((image, i) => anchorXml(image, i + 1)).join('');
-    return (XML_DECLARATION +
-        `<xdr:wsDr xmlns:xdr="${XDR_NS}" xmlns:a="${DRAWINGML_NS}" xmlns:r="${RELATIONSHIPS_NS}">` +
-        anchors +
-        '</xdr:wsDr>');
+    const anchors = images.map((image, i) => anchorXml(image, i + 1, '')).join('');
+    return `${XML_DECLARATION}<xdr:wsDr${ANCHOR_NAMESPACES}>${anchors}</xdr:wsDr>`;
 }
-function anchorXml(image, id) {
+export function mergePictures(drawing, images) {
+    const root = elementRange(drawing, ['wsDr']);
+    if (root === undefined) {
+        throw new AuthoringError('cannot add a picture to a kept drawing that has no <wsDr> root');
+    }
+    let lastId = 0;
+    for (const { attrs } of openElements(drawing, 'cNvPr')) {
+        lastId = Math.max(lastId, numInteger(attrs.id, 0) ?? 0);
+    }
+    const anchors = images
+        .map((image, i) => anchorXml(image, lastId + i + 1, ANCHOR_NAMESPACES))
+        .join('');
+    if (root.contentStart === root.end) {
+        const open = drawing.slice(root.start, root.end).replace(/\s*\/>$/, '>');
+        return `${drawing.slice(0, root.start)}${open}${anchors}</${root.name}>${drawing.slice(root.end)}`;
+    }
+    return drawing.slice(0, root.contentEnd) + anchors + drawing.slice(root.contentEnd);
+}
+function anchorXml(image, id, namespaces) {
     const { anchor } = image;
+    const pic = picXml(image, id, anchor.rotation);
     return isOneCellAnchor(anchor)
-        ? oneCellAnchorXml(anchor.from, anchor.ext, anchor.rotation, image.embedId, id)
-        : twoCellAnchorXml(anchor.from, anchor.to, anchor.editAs ?? 'oneCell', anchor.rotation, image.embedId, id);
+        ? oneCellAnchorXml(anchor.from, anchor.ext, pic, namespaces)
+        : twoCellAnchorXml(anchor.from, anchor.to, anchor.editAs ?? 'oneCell', pic, namespaces);
 }
-function twoCellAnchorXml(from, to, editAs, rotation, embedId, id) {
-    return (`<xdr:twoCellAnchor editAs="${checkedToken(editAs, isImageEditAs, 'image anchor edit mode')}">` +
+function twoCellAnchorXml(from, to, editAs, pic, namespaces) {
+    return (`<xdr:twoCellAnchor${namespaces} editAs="${checkedToken(editAs, isImageEditAs, 'image anchor edit mode')}">` +
         `<xdr:from>${anchorPointXml(from)}</xdr:from>` +
         `<xdr:to>${anchorPointXml(to)}</xdr:to>` +
-        picXml(embedId, id, rotation) +
+        pic +
         '<xdr:clientData/>' +
         '</xdr:twoCellAnchor>');
 }
-function oneCellAnchorXml(from, ext, rotation, embedId, id) {
-    return ('<xdr:oneCellAnchor>' +
+function oneCellAnchorXml(from, ext, pic, namespaces) {
+    return (`<xdr:oneCellAnchor${namespaces}>` +
         `<xdr:from>${anchorPointXml(from)}</xdr:from>` +
         `<xdr:ext${numAttr('cx', ext.cx)}${numAttr('cy', ext.cy)}/>` +
-        picXml(embedId, id, rotation) +
+        pic +
         '<xdr:clientData/>' +
         '</xdr:oneCellAnchor>');
 }
-function picXml(embedId, id, rotation) {
+function picXml(image, id, rotation) {
+    const { embedId, properties, hyperlinkId } = image;
     const xfrm = rotation !== undefined ? `<a:xfrm${numAttr('rot', rotation)}/>` : '';
+    const attributes = textAttr('descr', properties.description) + textAttr('title', properties.title);
+    const link = hyperlinkId === undefined
+        ? ''
+        : `<a:hlinkClick r:id="${escapeAttr(hyperlinkId)}"` +
+            `${textAttr('tooltip', properties.hyperlink?.tooltip)}/>`;
+    const cNvPr = link === ''
+        ? `<xdr:cNvPr id="${id}" name="Picture ${id}"${attributes}/>`
+        : `<xdr:cNvPr id="${id}" name="Picture ${id}"${attributes}>${link}</xdr:cNvPr>`;
     return ('<xdr:pic>' +
-        `<xdr:nvPicPr><xdr:cNvPr id="${id}" name="Picture ${id}"/>` +
+        `<xdr:nvPicPr>${cNvPr}` +
         '<xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr></xdr:nvPicPr>' +
         `<xdr:blipFill><a:blip r:embed="${embedId}"/>` +
+        srcRectXml(properties.crop) +
         '<a:stretch><a:fillRect/></a:stretch></xdr:blipFill>' +
         `<xdr:spPr>${xfrm}<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr>` +
         '</xdr:pic>');
 }
+const CROP_UNITS = 100_000;
+const INT_MAX = 2_147_483_647;
+function srcRectXml(crop) {
+    if (crop === undefined)
+        return '';
+    const edge = (name, fraction) => {
+        if (fraction === undefined)
+            return '';
+        assertWritableNumber(fraction);
+        const units = Math.round(fraction * CROP_UNITS);
+        if (units > INT_MAX) {
+            throw new AuthoringError(`cannot write the picture crop ${name}="${units}": past xsd:int`);
+        }
+        return units === 0 ? '' : intAttr(name, units, -INT_MAX - 1);
+    };
+    const attributes = edge('l', crop.left) + edge('t', crop.top) + edge('r', crop.right) + edge('b', crop.bottom);
+    return attributes === '' ? '' : `<a:srcRect${attributes}/>`;
+}
+function cropEdge(value) {
+    if (value === undefined)
+        return undefined;
+    const percent = value.endsWith('%') ? numFinite(value.slice(0, -1)) : undefined;
+    const units = percent === undefined ? numInteger(value) : Math.round(percent * 1000);
+    if (units === undefined || units === 0 || units > INT_MAX || units < -INT_MAX - 1) {
+        return undefined;
+    }
+    return units / CROP_UNITS;
+}
 function anchorPointXml(point) {
     return (`<xdr:col>${numberText(point.col)}</xdr:col>` +
         `<xdr:colOff>${numberText(point.colOff ?? 0)}</xdr:colOff>` +
         `<xdr:row>${numberText(point.row)}</xdr:row>` +
         `<xdr:rowOff>${numberText(point.rowOff ?? 0)}</xdr:rowOff>`);
 }
-export function drawingRelsXml(mediaTargets) {
-    return relationshipsPart(mediaTargets.map((target, i) => relationship(`rId${i + 1}`, IMAGE_REL_TYPE, target)));
-}
 function blankPoint() {
     return { col: 0, row: 0, colOff: 0, rowOff: 0 };
 }
+const UNMODELED_CONTENT = new Set([
+    'graphicFrame',
+    'sp',
+    'cxnSp',
+    'grpSp',
+    'contentPart',
+    'absoluteAnchor',
+    'AlternateContent',
+]);
 export function parseDrawing(xml) {
     const anchors = [];
+    let fullyModeled = true;
     let from = null;
     let to = null;
     let ext;
     let editAs;
     let rotation;
     let embed;
+    let pictures = 0;
+    let properties = {};
     let target = null;
     let picDepth = 0;
     const coord = new TextCapture(COORDINATES);
     parseXml(xml, {
-        onOpen(name, attrs, selfClosing) {
+        onOpen(name, attrs, selfClosing, scope) {
             const local = localName(name);
-            if (local === 'twoCellAnchor' || local === 'oneCellAnchor') {
+            if (UNMODELED_CONTENT.has(local)) {
+                fullyModeled = false;
+            }
+            else if (local === 'twoCellAnchor' || local === 'oneCellAnchor') {
                 from = blankPoint();
                 to = local === 'twoCellAnchor' ? blankPoint() : null;
                 ext = undefined;
                 rotation = undefined;
                 embed = undefined;
-                editAs = enumToken(attrs.editAs, isImageEditAs);
+                pictures = 0;
+                properties = {};
+                editAs =
+                    local === 'twoCellAnchor'
+                        ? (enumToken(attrs.editAs, isImageEditAs) ?? 'twoCell')
+                        : undefined;
             }
             else if (local === 'pic') {
                 picDepth++;
+                pictures++;
+            }
+            else if (local === 'cNvPr' && picDepth > 0) {
+                if (attrs.descr !== undefined && attrs.descr !== '')
+                    properties.description = attrs.descr;
+                if (attrs.title !== undefined && attrs.title !== '')
+                    properties.title = attrs.title;
+            }
+            else if (local === 'hlinkClick' && picDepth > 0) {
+                const id = relAttr(scope, attrs, 'id');
+                if (id !== undefined && id !== '') {
+                    properties.hyperlinkId = id;
+                    if (attrs.tooltip !== undefined)
+                        properties.tooltip = attrs.tooltip;
+                }
+            }
+            else if (local === 'srcRect' && picDepth > 0) {
+                const crop = {};
+                const left = cropEdge(attrs.l);
+                const top = cropEdge(attrs.t);
+                const right = cropEdge(attrs.r);
+                const bottom = cropEdge(attrs.b);
+                if (left !== undefined)
+                    crop.left = left;
+                if (top !== undefined)
+                    crop.top = top;
+                if (right !== undefined)
+                    crop.right = right;
+                if (bottom !== undefined)
+                    crop.bottom = bottom;
+                if (Object.keys(crop).length > 0)
+                    properties.crop = crop;
             }
             else if (local === 'xfrm' && picDepth > 0) {
                 const rot = numFinite(attrs.rot);
@@ -116,9 +220,11 @@ export function parseDrawing(xml) {
                     ext = { cx, cy };
             }
             else if (local === 'blip') {
-                const value = attrs['r:embed'] ?? attrs.embed;
+                const value = relAttr(scope, attrs, 'embed');
                 if (value !== undefined)
                     embed = value;
+                if (relAttr(scope, attrs, 'link') !== undefined)
+                    fullyModeled = false;
             }
             else if (target !== null) {
                 coord.open(local, selfClosing);
@@ -142,15 +248,19 @@ export function parseDrawing(xml) {
                 picDepth--;
             }
             else if (local === 'twoCellAnchor' || local === 'oneCellAnchor') {
-                if (from !== null && embed !== undefined) {
-                    const rot = rotation !== undefined ? { rotation } : {};
-                    if (to !== null) {
-                        const mode = editAs !== undefined ? { editAs } : {};
-                        anchors.push({ from: { ...from }, to: { ...to }, ...mode, ...rot, embed });
-                    }
-                    else if (ext !== undefined) {
-                        anchors.push({ from: { ...from }, ext, ...rot, embed });
-                    }
+                const rot = rotation !== undefined ? { rotation } : {};
+                if (from === null || embed === undefined || pictures !== 1) {
+                    fullyModeled = false;
+                }
+                else if (to !== null) {
+                    const mode = editAs !== undefined ? { editAs } : {};
+                    anchors.push({ from: { ...from }, to: { ...to }, ...mode, ...rot, embed, ...properties });
+                }
+                else if (ext !== undefined) {
+                    anchors.push({ from: { ...from }, ext, ...rot, embed, ...properties });
+                }
+                else {
+                    fullyModeled = false;
                 }
                 from = null;
                 to = null;
@@ -158,18 +268,7 @@ export function parseDrawing(xml) {
             }
         },
     });
-    return anchors;
-}
-const UNMODELED_DRAWING_CONTENT = new Set(['graphicFrame', 'sp', 'cxnSp', 'grpSp']);
-export function drawingHasUnmodeledContent(xml) {
-    let found = false;
-    parseXml(xml, {
-        onOpen(name) {
-            if (!found && UNMODELED_DRAWING_CONTENT.has(localName(name)))
-                found = true;
-        },
-    });
-    return found;
+    return { anchors, fullyModeled };
 }
 const COORDINATES = new Set(['col', 'colOff', 'row', 'rowOff']);
 function setCoordinate(point, coord, value) {

package/dist/io/xlsx/namespaces.d.ts

@@ -9,6 +9,7 @@
  * The package-level URIs (`.rels`, content types, the relationship vocabulary) describe the
  * container rather than the spreadsheet inside it, and live in `../opc/namespaces.ts`.
  */
+import type { NamespaceScope } from '../../xml/xml-namespaces.ts';
 /**
  * SpreadsheetML main namespace: the default `xmlns` of the workbook,
  * worksheet, styles, sharedStrings, comments, table and pivot parts.
@@ -53,3 +54,26 @@ export declare const DATABAR_LINK_EXT_URI = "{B025F937-C7B1-47D3-B67F-A62EFF666E
 export declare const DATA_VALIDATION_EXT_URI = "{CCE6A557-97BC-4b89-ADB6-D9C93CAAB3DF}";
 export declare const SLICER_LIST_EXT_URI = "{A8765BA9-456A-4dab-B4F3-ACF838C121DE}";
 export declare const SLICER_CACHES_EXT_URI = "{BBE1A952-AA13-448e-AADC-164F8A28A991}";
+/** The extension a dynamic-array formula's cell-metadata block carries its properties in. */
+export declare const DYNAMIC_ARRAY_PROPERTIES_EXT_URI = "{bdbb8cdc-fa1e-496e-a857-3c3f30c029c3}";
+/** The 2017 dynamic-array namespace (`xda:`), which scopes those properties in `xl/metadata.xml`. */
+export declare const DYNAMIC_ARRAY_NS = "http://schemas.microsoft.com/office/spreadsheetml/2017/dynamicarray";
+/** The extension a rich-value metadata block names its rich value in (`<xlrd:rvb i>`). */
+export declare const RICH_VALUE_BLOCK_EXT_URI = "{3e2802c4-a4d2-4d8b-9148-e3be6c30e623}";
+/** The 2017 rich-data namespace (`xlrd:`): the rich values, their structures, and the blocks naming them. */
+export declare const RICH_DATA_NS = "http://schemas.microsoft.com/office/spreadsheetml/2017/richdata";
+/**
+ * Whether an element belongs to the standard SpreadsheetML vocabulary rather than to an extension.
+ *
+ * This used to be spelled `!name.includes(':')`, on the assumption that only extension elements carry
+ * a prefix. A worksheet may bind the *main* namespace to a prefix instead, which is legal and which
+ * real toolchains emit, and then every element has a colon in it: such a file had every one of its
+ * data validations and conditional formats read as an unknown extension and dropped, silently.
+ *
+ * An unprefixed element counts even when the part declares no default namespace. A part with no
+ * `xmlns` at all is not conforming OOXML, but this scanner does not reject it, such parts were read
+ * before, and a fix that gains files by resolving namespaces should not lose files that have none.
+ */
+export declare function isMainNamespaceElement(scope: NamespaceScope, name: string): boolean;
+/** The complement of {@link isMainNamespaceElement}: an element of one of the extension vocabularies. */
+export declare function isExtensionElement(scope: NamespaceScope, name: string): boolean;

package/dist/io/xlsx/namespaces.js

@@ -11,3 +11,14 @@ export const DATABAR_LINK_EXT_URI = '{B025F937-C7B1-47D3-B67F-A62EFF666E3E}';
 export const DATA_VALIDATION_EXT_URI = '{CCE6A557-97BC-4b89-ADB6-D9C93CAAB3DF}';
 export const SLICER_LIST_EXT_URI = '{A8765BA9-456A-4dab-B4F3-ACF838C121DE}';
 export const SLICER_CACHES_EXT_URI = '{BBE1A952-AA13-448e-AADC-164F8A28A991}';
+export const DYNAMIC_ARRAY_PROPERTIES_EXT_URI = '{bdbb8cdc-fa1e-496e-a857-3c3f30c029c3}';
+export const DYNAMIC_ARRAY_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2017/dynamicarray';
+export const RICH_VALUE_BLOCK_EXT_URI = '{3e2802c4-a4d2-4d8b-9148-e3be6c30e623}';
+export const RICH_DATA_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2017/richdata';
+export function isMainNamespaceElement(scope, name) {
+    const namespace = scope.elementNamespace(name);
+    return namespace === SPREADSHEETML_NS || (namespace === undefined && !name.includes(':'));
+}
+export function isExtensionElement(scope, name) {
+    return !isMainNamespaceElement(scope, name);
+}

package/dist/io/xlsx/package-plan.d.ts

@@ -5,29 +5,60 @@ import type { Table } from '../../core/table.ts';
 import type { Workbook } from '../../core/workbook.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
 import type { CommentCell } from './comments.ts';
-import type { DrawingImage } from './images.ts';
-export declare class SheetRelIds {
+import type { HyperlinkPlan } from './hyperlinks.ts';
+import { type DrawingImage } from './images.ts';
+/** One relationship a generated `.rels` part declares, its target already relative to the owner. */
+export interface PlannedRelationship {
+    readonly id: string;
+    readonly type: string;
+    readonly target: string;
+    readonly external?: boolean;
+}
+/**
+ * The relationships one part owns, recorded as their ids are handed out.
+ *
+ * An id and the relationship it names are one fact, so they are written down in one call. When the
+ * ids came from a counter and the `.rels` part was listed somewhere else, a sheet's set was spelled
+ * three times: once where ids were drawn, once in the rels renderer in another order, and once more in
+ * a nine-way condition deciding whether the rels part existed at all. A tenth kind of part needed all
+ * three edits, and missing the last dropped the `.rels` part while the sheet XML still cited the id.
+ * Now the ledger is the rels part, and a part with an empty ledger has none.
+ *
+ * Ids run `rId1`, `rId2`, … in the order parts are added, so no id is derived by summing the ones
+ * before it, and the `.rels` part lists them in that same order. One ledger per owning part; ids are
+ * scoped to it. A ledger adding to a part kept from a file skips the ids that part already holds.
+ */
+export declare class RelationshipLedger {
     #private;
-    /** The next relationship id (`rId1`, `rId2`, …), advancing the counter. */
-    next(): string;
+    /**
+     * @param owner the package path of the part whose `.rels` this is, `''` for the package root.
+     * @param taken the ids the part's `.rels` already holds, none of which a new relationship may take.
+     */
+    constructor(owner: string, taken?: ReadonlySet<string>);
+    /** Record a relationship to a package part, named by its package path, and return its id. */
+    add(type: string, partPath: string): string;
+    /** Record a relationship to a target outside the package (a hyperlink's URL) and return its id. */
+    addExternal(type: string, url: string): string;
+    /** Record a relationship to a place inside this document (a picture link's `#Sheet1!C3`), kept as
+     * written rather than resolved as a part path, and return its id. */
+    addInDocument(type: string, location: string): string;
+    /** Every relationship recorded, in id order. */
+    get relationships(): readonly PlannedRelationship[];
 }
 export interface PivotPlan {
     readonly number: number;
     readonly cacheId: string;
     readonly table: PivotTable;
-    readonly sheetRelId: string;
     workbookRelId: string;
 }
 export interface CommentPlan {
     readonly number: number;
     readonly comments: readonly CommentCell[];
     readonly vmlRelId: string;
-    readonly commentsRelId: string;
 }
 export interface ThreadedCommentPlan {
     readonly number: number;
     readonly threads: readonly CommentThread[];
-    readonly relId: string;
 }
 export interface PrinterSettingsPlan {
     readonly number: number;
@@ -41,8 +72,6 @@ export interface TablePlan {
 }
 export interface BackgroundPlan {
     readonly relId: string;
-    readonly mediaNumber: number;
-    readonly extension: string;
 }
 export interface PreservedPartPlan {
     readonly path: string;
@@ -84,11 +113,8 @@ export interface PreservedPlan {
 export interface DrawingPlan {
     readonly number: number;
     readonly relId: string;
-    readonly images: readonly ImagePlan[];
-}
-export interface ImagePlan extends DrawingImage {
-    readonly mediaNumber: number;
-    readonly extension: string;
+    readonly images: readonly DrawingImage[];
+    readonly relationships: readonly PlannedRelationship[];
 }
 export interface MediaPart {
     readonly number: number;
@@ -108,4 +134,23 @@ export interface MediaPlan {
     resolve(id: number): ResolvedMedia;
 }
 export declare function planMedia(workbook: Workbook, sheets: readonly Worksheet[]): MediaPlan;
-export declare function planPreservedParts(workbook: Workbook, generatedDrawingCount: number, generatedMediaCount: number): PreservedPlan;
+/**
+ * The pictures a sheet adds to the drawing it kept from a file, laid out once that drawing's path in the
+ * package is known: each picture's media and link relationships go into `ledger`, the drawing's own,
+ * which already skips the ids the drawing holds.
+ */
+export type PicturesJoiningDrawing = (ledger: RelationshipLedger) => readonly DrawingImage[];
+export declare function planPreservedParts(workbook: Workbook, generatedDrawingCount: number, generatedMediaCount: number, generatedPivotCount: number, pictures: ReadonlyMap<string, PicturesJoiningDrawing>): PreservedPlan;
+export interface SheetPlan {
+    /** Every relationship the sheet's `.rels` part declares, in id order; empty when it needs none. */
+    readonly relationships: readonly PlannedRelationship[];
+    readonly tables: TablePlan[];
+    readonly drawing: DrawingPlan | null;
+    readonly comments: CommentPlan | null;
+    readonly threadedComments: ThreadedCommentPlan | null;
+    readonly printerSettings: PrinterSettingsPlan | null;
+    readonly hyperlinks: HyperlinkPlan[];
+    readonly background: BackgroundPlan | null;
+    readonly preservedRefs: PreservedReferencePlan[];
+    readonly pivots: PivotPlan[];
+}