@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/io/xlsx/data-validation.d.ts

@@ -3,20 +3,25 @@ import type { Worksheet } from '../../core/worksheet.ts';
 import { type CollectingPass } from '../../xml/xml-read.ts';
 /** The standard `<dataValidations>` element for the rules stored in the legacy form, or '' when the
  * sheet has none of them, so a sheet with only extended (or no) validations stays byte-clean here.
- * The extended rules are emitted separately by {@link dataValidationsExtXml}. */
-export declare function dataValidationsXml(entries: readonly DataValidationEntry[]): string;
+ * The extended rules are emitted separately by {@link dataValidationsExtXml}.
+ *
+ * An operand is stored with the function prefixes a cell formula takes, as Excel stores it;
+ * `formulaNames` is `formulaNamesInScope` for the sheet. */
+export declare function dataValidationsXml(entries: readonly DataValidationEntry[], formulaNames: ReadonlySet<string>): string;
 /** The `<ext>` carrying the extended (`<x14:dataValidation>`) rules, or '' when the sheet declares
  * none. Emitted bare (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single
  * `<extLst>` beside the conditional-formatting extension: a worksheet may carry at most one. */
-export declare function dataValidationsExtXml(entries: readonly DataValidationEntry[]): string;
+export declare function dataValidationsExtXml(entries: readonly DataValidationEntry[], formulaNames: ReadonlySet<string>): string;
 /** A pass gathering the standard `<dataValidation>` elements of a worksheet part, for a caller
- * reading the part alongside its other readers in one parse. */
-export declare function dataValidationPass(): CollectingPass<DataValidationEntry[]>;
+ * reading the part alongside its other readers in one parse. An operand sheds its function prefixes
+ * against `definedNames`, the workbook's names as `definedNameKeys` spells them. */
+export declare function dataValidationPass(definedNames: ReadonlySet<string>): CollectingPass<DataValidationEntry[]>;
 /** A pass gathering the extended `<x14:dataValidation>` elements of a worksheet's `<extLst>`, so a
  * cross-sheet or whole-column list validation Excel stored only in the 2009 extension form is read
  * back rather than dropped. The standard pass ignores these (they are prefixed); this one,
- * symmetrically, handles only the prefixed elements. */
-export declare function extendedDataValidationPass(): CollectingPass<DataValidationEntry[]>;
+ * symmetrically, handles only the prefixed elements. An operand sheds its function prefixes against
+ * `definedNames`, as the standard pass's does. */
+export declare function extendedDataValidationPass(definedNames: ReadonlySet<string>): CollectingPass<DataValidationEntry[]>;
 /** Fold parsed validations onto a sheet, each bound to its original range and carrying its form: an
  * `extended` entry is re-attached as extended so a round-trip writes it back to the x14 block. */
 export declare function applyDataValidations(sheet: Worksheet, entries: readonly DataValidationEntry[]): void;

package/dist/io/xlsx/data-validation.js

@@ -1,26 +1,30 @@
-import { isDataValidationErrorStyle, isDataValidationOperator, isDataValidationType, } from '../../core/data-validation.js';
-import { stripFormulaEquals } from '../../core/formula.js';
+import { isDataValidationErrorStyle, isDataValidationImeMode, isDataValidationOperator, isDataValidationType, } from '../../core/data-validation.js';
+import { mangleFormula, stripFormulaEquals, unmangleFunctions } from '../../core/formula.js';
 import { decodeSqrefRects } from '../../core/merge.js';
-import { coerceNumericLiteral } from '../../xml/xml-attrs.js';
+import { coerceNumericLiteral, enumToken } from '../../xml/xml-attrs.js';
 import { TextCapture } from '../../xml/xml-read.js';
 import { boolStrict, localName } from '../../xml/xml-scan.js';
 import { checkedToken, escapeAttr, escapeText, textAttr } from '../../xml/xml.js';
+import { admitting } from '../read-policy/read-repair.js';
 import { DATA_VALIDATION_EXT_URI, isExtensionElement, isMainNamespaceElement, XM_NS, } from './namespaces.js';
-import { admitting } from './read-repair.js';
 import { x14Ext } from './x14-ext.js';
 const TYPED = new Set(['whole', 'decimal', 'date', 'time', 'textLength']);
-export function dataValidationsXml(entries) {
+export function dataValidationsXml(entries, formulaNames) {
     const standard = entries.filter((entry) => !entry.extended);
     if (standard.length === 0)
         return '';
-    const items = standard.map(({ sqref, rule }) => dataValidationXml(sqref, rule)).join('');
+    const items = standard
+        .map(({ sqref, rule }) => dataValidationXml(sqref, rule, formulaNames))
+        .join('');
     return `<dataValidations count="${standard.length}">${items}</dataValidations>`;
 }
-export function dataValidationsExtXml(entries) {
+export function dataValidationsExtXml(entries, formulaNames) {
     const extended = entries.filter((entry) => entry.extended);
     if (extended.length === 0)
         return '';
-    const items = extended.map(({ sqref, rule }) => extendedDataValidationXml(sqref, rule)).join('');
+    const items = extended
+        .map(({ sqref, rule }) => extendedDataValidationXml(sqref, rule, formulaNames))
+        .join('');
     return x14Ext(DATA_VALIDATION_EXT_URI, `<x14:dataValidations count="${extended.length}" xmlns:xm="${XM_NS}">${items}</x14:dataValidations>`);
 }
 function ruleAttrs(rule) {
@@ -28,10 +32,14 @@ function ruleAttrs(rule) {
         (rule.errorStyle === undefined
             ? ''
             : ` errorStyle="${checkedToken(rule.errorStyle, isDataValidationErrorStyle, 'data validation error style')}"`) +
+        (rule.imeMode === undefined
+            ? ''
+            : ` imeMode="${checkedToken(rule.imeMode, isDataValidationImeMode, 'data validation IME mode')}"`) +
         (rule.operator === undefined
             ? ''
             : ` operator="${checkedToken(rule.operator, isDataValidationOperator, 'data validation operator')}"`) +
         (rule.allowBlank ? ' allowBlank="1"' : '') +
+        (rule.suppressDropDown ? ' showDropDown="1"' : '') +
         (rule.showInputMessage ? ' showInputMessage="1"' : '') +
         (rule.showErrorMessage ? ' showErrorMessage="1"' : '') +
         textAttr('errorTitle', rule.errorTitle) +
@@ -39,30 +47,28 @@ function ruleAttrs(rule) {
         textAttr('promptTitle', rule.promptTitle) +
         textAttr('prompt', rule.prompt));
 }
-function dataValidationXml(sqref, rule) {
-    const [f1, f2] = operands(rule);
-    const body = (f1 !== undefined ? `<formula1>${escapeText(stripFormulaEquals(f1))}</formula1>` : '') +
-        (f2 !== undefined ? `<formula2>${escapeText(stripFormulaEquals(f2))}</formula2>` : '');
+function dataValidationXml(sqref, rule, formulaNames) {
+    const [f1, f2] = rule.formulae ?? [];
+    const body = (f1 !== undefined ? `<formula1>${operandText(f1, formulaNames)}</formula1>` : '') +
+        (f2 !== undefined ? `<formula2>${operandText(f2, formulaNames)}</formula2>` : '');
     return `<dataValidation${ruleAttrs(rule)} sqref="${escapeAttr(sqref)}">${body}</dataValidation>`;
 }
-function operands(rule) {
-    const drop = (v) => typeof v === 'number' && !Number.isFinite(v) ? undefined : v;
+function extendedDataValidationXml(sqref, rule, formulaNames) {
     const [f1, f2] = rule.formulae ?? [];
-    return [drop(f1), drop(f2)];
-}
-function extendedDataValidationXml(sqref, rule) {
-    const [f1, f2] = operands(rule);
     const body = (f1 !== undefined
-        ? `<x14:formula1><xm:f>${escapeText(stripFormulaEquals(f1))}</xm:f></x14:formula1>`
+        ? `<x14:formula1><xm:f>${operandText(f1, formulaNames)}</xm:f></x14:formula1>`
         : '') +
         (f2 !== undefined
-            ? `<x14:formula2><xm:f>${escapeText(stripFormulaEquals(f2))}</xm:f></x14:formula2>`
+            ? `<x14:formula2><xm:f>${operandText(f2, formulaNames)}</xm:f></x14:formula2>`
             : '') +
         `<xm:sqref>${escapeText(sqref)}</xm:sqref>`;
     return `<x14:dataValidation${ruleAttrs(rule)}>${body}</x14:dataValidation>`;
 }
+function operandText(operand, formulaNames) {
+    return escapeText(mangleFormula(stripFormulaEquals(operand), formulaNames));
+}
 const FORMULA_ELEMENTS = new Set(['formula1', 'formula2']);
-export function dataValidationPass() {
+export function dataValidationPass(definedNames) {
     const entries = [];
     let current;
     const formula = new TextCapture(FORMULA_ELEMENTS);
@@ -88,7 +94,7 @@ export function dataValidationPass() {
                 return;
             }
             if (ln === 'dataValidation' && current !== undefined) {
-                const built = buildEntry(current.attrs, current.formulae);
+                const built = buildEntry(current.attrs, current.formulae, definedNames);
                 if (built !== undefined)
                     entries.push(built);
                 current = undefined;
@@ -97,14 +103,14 @@ export function dataValidationPass() {
     };
     return { handlers, result: () => entries };
 }
-function buildEntry(attrs, formulae) {
+function buildEntry(attrs, formulae, definedNames) {
     const { sqref } = attrs;
     if (sqref === undefined)
         return undefined;
-    const rule = buildRule(attrs, formulae);
+    const rule = buildRule(attrs, formulae, definedNames);
     return rule === undefined ? undefined : { sqref, rule };
 }
-function buildRule(attrs, formulae) {
+function buildRule(attrs, formulae, definedNames) {
     const { type } = attrs;
     if (type === undefined || !isDataValidationType(type))
         return undefined;
@@ -118,12 +124,17 @@ function buildRule(attrs, formulae) {
     }
     if (boolStrict(attrs.allowBlank))
         rule.allowBlank = true;
+    if (boolStrict(attrs.showDropDown))
+        rule.suppressDropDown = true;
     if (boolStrict(attrs.showInputMessage))
         rule.showInputMessage = true;
     if (boolStrict(attrs.showErrorMessage))
         rule.showErrorMessage = true;
     if (attrs.errorStyle !== undefined && isDataValidationErrorStyle(attrs.errorStyle))
         rule.errorStyle = attrs.errorStyle;
+    const imeMode = enumToken(attrs.imeMode, isDataValidationImeMode);
+    if (imeMode !== undefined)
+        rule.imeMode = imeMode;
     if (attrs.error !== undefined)
         rule.error = attrs.error;
     if (attrs.errorTitle !== undefined)
@@ -134,12 +145,13 @@ function buildRule(attrs, formulae) {
         rule.promptTitle = attrs.promptTitle;
     const parsed = formulae
         .filter((f) => f !== undefined)
+        .map((f) => unmangleFunctions(f, definedNames))
         .map((f) => (type === 'list' || type === 'custom' ? f : coerceNumericLiteral(f)));
     if (parsed.length > 0)
         rule.formulae = parsed;
     return rule;
 }
-export function extendedDataValidationPass() {
+export function extendedDataValidationPass(definedNames) {
     const entries = [];
     let current;
     let slot;
@@ -181,7 +193,7 @@ export function extendedDataValidationPass() {
                 slot = undefined;
             }
             else if (ln === 'dataValidation' && extension && current !== undefined) {
-                const built = buildExtendedEntry(current.attrs, current.formulae, current.sqref);
+                const built = buildExtendedEntry(current.attrs, current.formulae, current.sqref, definedNames);
                 if (built !== undefined)
                     entries.push(built);
                 current = undefined;
@@ -190,10 +202,10 @@ export function extendedDataValidationPass() {
     };
     return { handlers, result: () => entries };
 }
-function buildExtendedEntry(attrs, formulae, sqref) {
+function buildExtendedEntry(attrs, formulae, sqref, definedNames) {
     if (sqref === '')
         return undefined;
-    const rule = buildRule(attrs, formulae);
+    const rule = buildRule(attrs, formulae, definedNames);
     return rule === undefined ? undefined : { sqref, rule, extended: true };
 }
 export function applyDataValidations(sheet, entries) {

package/dist/io/xlsx/edit-vba.js

@@ -1,8 +1,9 @@
-import { strFromU8, strToU8, zipSync } from 'fflate';
+import { strToU8, zipSync } from 'fflate';
 import { VbaAuthorError } from '../../vba/errors.js';
 import { addVbaReference, removeVbaModule, } from '../../vba/project-editor.js';
+import { elementRange } from '../../xml/xml-read.js';
 import { relsPathFor, resolveRelativePart } from '../opc/part-paths.js';
-import { parseRelationshipRecords, readPartRelationships } from '../opc/read-opc.js';
+import { packageAccessors, parseRelationshipRecords, readPartRelationships, } from '../opc/read-opc.js';
 import { DEFAULT_MAX_UNCOMPRESSED } from '../opc/read-options.js';
 import { inflateSpreadsheetPackage } from '../opc/sniff-format.js';
 import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
@@ -17,56 +18,62 @@ export function editXlsxVbaAddReference(xlsx, ref, options = {}) {
 }
 function applyToVbaProjectPart(xlsx, options, apply) {
     const files = inflateSpreadsheetPackage(xlsx, options.maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED);
-    const binPath = locateVbaProjectPart(files);
-    const bin = binPath === undefined ? undefined : files[binPath];
-    if (binPath === undefined || bin === undefined) {
+    const pkg = packageAccessors(files);
+    const binPath = locateVbaProjectPart(pkg);
+    const binKey = binPath === undefined ? undefined : pkg.partKey(binPath);
+    const bin = binKey === undefined ? undefined : files[binKey];
+    if (binPath === undefined || binKey === undefined || bin === undefined) {
         throw new VbaAuthorError('package has no VBA project to edit');
     }
-    files[binPath] = apply(bin);
-    dropStaleSignature(files, binPath);
+    files[binKey] = apply(bin);
+    dropStaleSignature(files, pkg, binPath);
     return zipSync(files, { mtime: FIXED_ENTRY_MTIME });
 }
-function locateVbaProjectPart(files) {
-    const partText = (path) => textPart(files, path);
-    const workbookPath = readPartRelationships('', partText).targetPath(OFFICE_DOCUMENT_REL);
+function locateVbaProjectPart(pkg) {
+    const workbookPath = readPartRelationships('', pkg.partText).targetPath(OFFICE_DOCUMENT_REL);
     if (workbookPath === undefined)
         return undefined;
-    return readPartRelationships(workbookPath, partText).targetPath(VBA_PROJECT_REL);
+    return readPartRelationships(workbookPath, pkg.partText).targetPath(VBA_PROJECT_REL);
 }
-function dropStaleSignature(files, binPath) {
-    const binRelsPath = relsPathFor(binPath);
-    const binRels = textPart(files, binRelsPath);
-    if (binRels === undefined)
+function dropStaleSignature(files, pkg, binPath) {
+    const binRelsKey = pkg.partKey(relsPathFor(binPath));
+    const binRels = binRelsKey === undefined ? undefined : pkg.partText(binRelsKey);
+    if (binRelsKey === undefined || binRels === undefined)
         return;
     const signatureRels = parseRelationshipRecords(binRels).filter((rel) => !rel.external && rel.type.includes(VBA_SIGNATURE_REL_INFIX));
     if (signatureRels.length === 0)
         return;
-    let contentTypes = textPart(files, '[Content_Types].xml');
+    const contentTypesKey = pkg.partKey(CONTENT_TYPES_PART);
+    let contentTypes = contentTypesKey === undefined ? undefined : pkg.partText(contentTypesKey);
     let rels = binRels;
     for (const rel of signatureRels) {
         const partPath = resolveRelativePart(binPath, rel.target);
-        delete files[partPath];
-        rels = removeRelationshipById(rels, rel.id);
-        if (contentTypes !== undefined)
-            contentTypes = removeContentTypeOverride(contentTypes, partPath);
+        const partKey = pkg.partKey(partPath);
+        if (partKey !== undefined)
+            delete files[partKey];
+        const partName = `/${partPath}`.toLowerCase();
+        rels = removeElements(rels, 'Relationship', (attrs) => attrs.Id === rel.id);
+        if (contentTypes !== undefined) {
+            contentTypes = removeElements(contentTypes, 'Override', (attrs) => attrs.PartName?.toLowerCase() === partName);
+        }
     }
     if (parseRelationshipRecords(rels).length === 0)
-        delete files[binRelsPath];
+        delete files[binRelsKey];
     else
-        files[binRelsPath] = strToU8(rels);
-    if (contentTypes !== undefined)
-        files['[Content_Types].xml'] = strToU8(contentTypes);
-}
-function textPart(files, path) {
-    const bytes = files[path];
-    return bytes === undefined ? undefined : strFromU8(bytes);
-}
-function removeRelationshipById(xml, id) {
-    return xml.replace(/<Relationship\b[^>]*?\/>|<Relationship\b[\s\S]*?<\/Relationship>/g, (element) => (new RegExp(`\\bId="${escapeRegExp(id)}"`).test(element) ? '' : element));
-}
-function removeContentTypeOverride(xml, partPath) {
-    return xml.replace(/<Override\b[^>]*?\/>/g, (element) => element.includes(`PartName="/${partPath}"`) ? '' : element);
+        files[binRelsKey] = strToU8(rels);
+    if (contentTypesKey !== undefined && contentTypes !== undefined) {
+        files[contentTypesKey] = strToU8(contentTypes);
+    }
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const CONTENT_TYPES_PART = '[Content_Types].xml';
+function removeElements(xml, local, drop) {
+    let kept = '';
+    let rest = xml;
+    let range = elementRange(rest, [local]);
+    while (range !== undefined) {
+        kept += rest.slice(0, drop(range.attrs) ? range.start : range.end);
+        rest = rest.slice(range.end);
+        range = elementRange(rest, [local]);
+    }
+    return kept + rest;
 }

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

@@ -1,61 +1,26 @@
-import type { Cell } from '../../core/cell.ts';
+import type { Hyperlink } from '../../core/hyperlink.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
 import { type CollectingPass } from '../../xml/xml-read.ts';
-import type { RelIdAllocator } from './package-plan.ts';
-/** A hyperlink gathered from a sheet for serialisation: the cell it sits on, its target, and an
- * optional tooltip. The visible label is the cell's own value and is serialised as that value.
- *
- * `row`/`col` are the anchor's position, kept so links gathered from separate passes (the sheet's live
- * rows, and the rows the streaming writer already flushed and evicted) can be merged back into the
- * row-major order Excel writes them in. They are not serialised; `ref` is.
- */
-export interface CollectedHyperlink {
-    readonly ref: string;
-    readonly row: number;
-    readonly col: number;
-    readonly target: string;
-    readonly tooltip?: string;
-}
+import type { RelationshipLedger } from './package-plan.ts';
 /** A hyperlink resolved for serialisation. An external target carries a `relId` (the sheet
- * relationship holding the URL) plus that `target`; an internal target carries a `location` (the
- * in-workbook reference). Exactly one of `relId`/`location` is ever set. */
+ * relationship holding the URL); an internal target carries a `location` (the in-workbook
+ * reference). Exactly one of `relId`/`location` is ever set. */
 export interface HyperlinkPlan {
     readonly ref: string;
     readonly relId?: string;
-    readonly target?: string;
     readonly location?: string;
     readonly tooltip?: string;
 }
 /**
- * Gather every hyperlink among a run of cells.
+ * Split a sheet's links into internal (location, no rel) and external (relationship) forms, recording
+ * each external link's URL in the sheet's ledger so its relationship follows every other sheet-local
+ * relationship in canonical order. An internal (`#`-prefixed) link records nothing.
  *
- * Takes the cells rather than the sheet, because the streaming writer has to ask this question of a
- * row at the moment it commits: after that the row's cells are evicted, and a post-hoc walk of
- * `sheet.rows()` finds nothing. Both writers therefore ask the same function, over whatever cells
- * they still hold.
+ * The links keep the order the sheet holds them in. That order is what decides which of two links over
+ * one cell `Worksheet.hyperlinkAt` reports, and a re-read adds them in document order, so writing them
+ * any other way would change the answer across a save.
  */
-export declare function collectHyperlinks(cells: Iterable<Cell>): CollectedHyperlink[];
-/** Every cell a sheet still holds, row-major: the live half of what a writer must gather. */
-export declare function liveCells(sheet: Worksheet): Generator<Cell, void, undefined>;
-/** An external hyperlink: the two fields a `TargetMode="External"` relationship needs, both present. */
-export type ExternalHyperlinkPlan = HyperlinkPlan & {
-    readonly relId: string;
-    readonly target: string;
-};
-/**
- * Whether a planned hyperlink is the external kind, narrowing it so the relationship writer reads
- * `relId` and `target` as the strings they are.
- *
- * A predicate rather than a filter plus two casts: the filter already proved both fields present, and
- * a cast repeating that proof one line later is a claim the compiler cannot check against the filter
- * it is supposed to be echoing. `planHyperlinks` sets exactly one of `relId`/`location`, so testing
- * either field is testing the kind.
- */
-export declare function isExternalHyperlink(link: HyperlinkPlan): link is ExternalHyperlinkPlan;
-/** Split collected links into internal (location, no rel) and external (relationship) forms, drawing
- * each external link's relationship id from the sheet's allocator so external ids follow every other
- * sheet-local relationship in canonical order. An internal ('#'-prefixed) link consumes no id. */
-export declare function planHyperlinks(links: readonly CollectedHyperlink[], rels: RelIdAllocator): HyperlinkPlan[];
+export declare function planHyperlinks(links: readonly Hyperlink[], rels: RelationshipLedger): HyperlinkPlan[];
 /** The `<hyperlinks>` element, or '' when the sheet has none. Attribute order follows CT_Hyperlink:
  * `ref`, `r:id`, `location`, `tooltip`. */
 export declare function hyperlinksXml(links: readonly HyperlinkPlan[]): string;
@@ -70,9 +35,10 @@ interface ParsedHyperlink {
 /** A pass gathering every `<hyperlink>` element of a worksheet part, for a caller reading the part
  * alongside its other readers in one parse. */
 export declare function sheetHyperlinkPass(): CollectingPass<ParsedHyperlink[]>;
-/** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
- * label) into a {@link HyperlinkValue}. `targetOf` resolves a relationship id to its raw Target: a
- * URL for the external links hyperlinks almost always are, so it must stay unresolved against the
- * package rather than being handed over as a part path. */
+/**
+ * Put parsed hyperlinks on a sheet, in document order, whatever the cells they cover hold. `targetOf`
+ * resolves a relationship id to its raw Target: a URL for the external links hyperlinks almost always
+ * are, so it must stay unresolved against the package rather than being handed over as a part path.
+ */
 export declare function applyHyperlinks(sheet: Worksheet, links: readonly ParsedHyperlink[], targetOf: (relId: string) => string | undefined): void;
 export {};

package/dist/io/xlsx/hyperlinks.js

@@ -1,39 +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';
 import { relAttr } from '../opc/namespaces.js';
-export function collectHyperlinks(cells) {
-    const links = [];
-    for (const cell of cells) {
-        const value = cell.value;
-        if (isHyperlinkValue(value)) {
-            links.push({
-                ref: value.range ?? cell.address,
-                row: cell.row,
-                col: cell.col,
-                target: value.hyperlink,
-                ...(value.tooltip !== undefined ? { tooltip: value.tooltip } : {}),
-            });
-        }
-    }
-    return links;
-}
-export function* liveCells(sheet) {
-    for (const { cells } of sheet.rows())
-        yield* cells;
-}
-export function isExternalHyperlink(link) {
-    return link.relId !== undefined && link.target !== undefined;
-}
+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) {
@@ -77,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;