@shbernal/ts-xlsx 1.0.0

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

@@ -0,0 +1,258 @@
+// Data validation I/O — the sheet-level `<dataValidations>` element and the reader that folds each
+// rule back onto its range.
+//
+// A validation stores its operands in `<formula1>`/`<formula2>` child elements and its target in a
+// `sqref` attribute. The operand text carries NO leading '=' (the '=' is an authoring convention, not
+// part of the stored formula), so the writer strips one and the reader keeps whatever it finds. A
+// numeric-typed rule's literal operand parses to a number; a cell reference, defined name, or list
+// source keeps its string, so a reference is never coerced to NaN and lost.
+//
+// The extended `<x14:dataValidation>` form (2009 extension schema) carries the validations a legacy
+// element cannot express — chiefly a list whose source lives on another sheet. It lives in the
+// worksheet `<extLst>`, keeps its target in a `<xm:sqref>` child rather than a `sqref` attribute, and
+// wraps each operand in an `<xm:f>` under `<x14:formula1>`/`<x14:formula2>`. A rule read from that
+// form is tagged `extended` so it is written back there; the two forms are parsed and serialised by
+// prefix so neither reader mistakes one for the other.
+import { escapeAttr, escapeText, stripFormulaEquals } from "../../xml/xml.js";
+import { boolStrict, coerceNumericLiteral, localName, parseXml } from "../../xml/xml-read.js";
+// The x14/xm extension namespaces and `DATA_VALIDATION_EXT_URI` are declared inline on the elements
+// that need them, exactly as Excel writes them, so the block is self-contained and the worksheet root
+// needs no extra namespace declaration.
+import { DATA_VALIDATION_EXT_URI, XM_NS } from "./namespaces.js";
+import { x14Ext } from "./x14-ext.js";
+// The typed validations whose literal operands are numbers; `list`/`custom` operands stay strings.
+const TYPED = new Set(['whole', 'decimal', 'date', 'time', 'textLength']);
+/** 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 function dataValidationsXml(entries) {
+    const standard = entries.filter((entry) => !entry.extended);
+    if (standard.length === 0)
+        return '';
+    const items = standard.map(({ sqref, rule }) => dataValidationXml(sqref, rule)).join('');
+    return `<dataValidations count="${standard.length}">${items}</dataValidations>`;
+}
+/** 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 function dataValidationsExtXml(entries) {
+    const extended = entries.filter((entry) => entry.extended);
+    if (extended.length === 0)
+        return '';
+    const items = extended.map(({ sqref, rule }) => extendedDataValidationXml(sqref, rule)).join('');
+    return x14Ext(DATA_VALIDATION_EXT_URI, `<x14:dataValidations count="${extended.length}" xmlns:xm="${XM_NS}">${items}</x14:dataValidations>`);
+}
+// The shared attributes of a validation, in CT_DataValidation order: type, errorStyle, operator,
+// allowBlank, showInputMessage, showErrorMessage, errorTitle, error, promptTitle, prompt. The target
+// range differs between the two forms (a `sqref` attribute vs an `<xm:sqref>` child), so it is not
+// part of this shared prefix.
+function ruleAttrs(rule) {
+    return (` type="${rule.type}"` +
+        (rule.errorStyle !== undefined ? ` errorStyle="${rule.errorStyle}"` : '') +
+        (rule.operator !== undefined ? ` operator="${rule.operator}"` : '') +
+        (rule.allowBlank ? ' allowBlank="1"' : '') +
+        (rule.showInputMessage ? ' showInputMessage="1"' : '') +
+        (rule.showErrorMessage ? ' showErrorMessage="1"' : '') +
+        (rule.errorTitle !== undefined ? ` errorTitle="${escapeAttr(rule.errorTitle)}"` : '') +
+        (rule.error !== undefined ? ` error="${escapeAttr(rule.error)}"` : '') +
+        (rule.promptTitle !== undefined ? ` promptTitle="${escapeAttr(rule.promptTitle)}"` : '') +
+        (rule.prompt !== undefined ? ` prompt="${escapeAttr(rule.prompt)}"` : ''));
+}
+// The standard element: shared attributes, then `sqref` last, then `<formula1>`/`<formula2>` bodies.
+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>` : '');
+    return `<dataValidation${ruleAttrs(rule)} sqref="${escapeAttr(sqref)}">${body}</dataValidation>`;
+}
+// A rule's two operands with any non-finite numeric bound dropped: a NaN/±Infinity operand (e.g. a
+// date validation whose bound failed to coerce to a serial) has no OOXML representation, so it is
+// omitted rather than serialised as the literal "NaN" — the same graceful degradation a non-finite
+// cell value gets.
+function operands(rule) {
+    const drop = (v) => typeof v === 'number' && !Number.isFinite(v) ? undefined : v;
+    const [f1, f2] = rule.formulae ?? [];
+    return [drop(f1), drop(f2)];
+}
+// The extended element: same shared attributes, but each operand wraps in `<x14:formula1><xm:f>…` and
+// the target range is an `<xm:sqref>` child that follows the formulae. The `xr:uid` Excel adds is
+// revision metadata it regenerates freely, so it is not modelled or re-emitted.
+function extendedDataValidationXml(sqref, rule) {
+    const [f1, f2] = operands(rule);
+    const body = (f1 !== undefined
+        ? `<x14:formula1><xm:f>${escapeText(stripFormulaEquals(f1))}</xm:f></x14:formula1>`
+        : '') +
+        (f2 !== undefined
+            ? `<x14:formula2><xm:f>${escapeText(stripFormulaEquals(f2))}</xm:f></x14:formula2>`
+            : '') +
+        `<xm:sqref>${escapeText(sqref)}</xm:sqref>`;
+    return `<x14:dataValidation${ruleAttrs(rule)}>${body}</x14:dataValidation>`;
+}
+/** Parse every standard `<dataValidation>` out of a worksheet part into range-bound rules. */
+export function parseDataValidations(xml) {
+    const entries = [];
+    let current;
+    let slot;
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const ln = localName(name);
+            // Only the standard, unprefixed element — an `x14:dataValidation` is left for the extended path.
+            if (ln === 'dataValidation' && !name.includes(':')) {
+                current = { attrs, formulae: [] };
+            }
+            else if (current !== undefined && ln === 'formula1') {
+                slot = 0;
+                current.formulae[0] = '';
+            }
+            else if (current !== undefined && ln === 'formula2') {
+                slot = 1;
+                current.formulae[1] = '';
+            }
+        },
+        onText(text) {
+            if (current !== undefined && slot !== undefined) {
+                current.formulae[slot] = (current.formulae[slot] ?? '') + text;
+            }
+        },
+        onClose(name) {
+            const ln = localName(name);
+            if (ln === 'formula1' || ln === 'formula2') {
+                slot = undefined;
+                return;
+            }
+            if (ln === 'dataValidation' && current !== undefined) {
+                const built = buildEntry(current.attrs, current.formulae);
+                if (built !== undefined)
+                    entries.push(built);
+                current = undefined;
+            }
+        },
+    });
+    return entries;
+}
+function buildEntry(attrs, formulae) {
+    const { sqref } = attrs;
+    if (sqref === undefined)
+        return undefined;
+    const rule = buildRule(attrs, formulae);
+    return rule === undefined ? undefined : { sqref, rule };
+}
+// The rule carried by a validation element of either form: its attributes decide the type, operator,
+// flags, and messages; its `<formula1>`/`<formula2>` operands become `formulae`. The target range is
+// supplied separately by each form's caller, so it is not read here.
+function buildRule(attrs, formulae) {
+    const { type } = attrs;
+    if (type === undefined)
+        return undefined;
+    const rule = { type: type };
+    if (attrs.operator !== undefined) {
+        rule.operator = attrs.operator;
+    }
+    else if (TYPED.has(type)) {
+        // Excel omits `operator="between"` because it is the default for a typed rule; restore it so a
+        // reader sees the operator the rule actually enforces.
+        rule.operator = 'between';
+    }
+    if (boolStrict(attrs.allowBlank))
+        rule.allowBlank = true;
+    if (boolStrict(attrs.showInputMessage))
+        rule.showInputMessage = true;
+    if (boolStrict(attrs.showErrorMessage))
+        rule.showErrorMessage = true;
+    if (attrs.errorStyle !== undefined)
+        rule.errorStyle = attrs.errorStyle;
+    if (attrs.error !== undefined)
+        rule.error = attrs.error;
+    if (attrs.errorTitle !== undefined)
+        rule.errorTitle = attrs.errorTitle;
+    if (attrs.prompt !== undefined)
+        rule.prompt = attrs.prompt;
+    if (attrs.promptTitle !== undefined)
+        rule.promptTitle = attrs.promptTitle;
+    // A `list`/`custom` operand is always a string (a source list or an expression); every other
+    // type's literal operand coerces to a number when it is one, so a numeric bound reads back as a
+    // number while a cell reference or defined name survives as its verbatim string.
+    const parsed = formulae
+        .filter((f) => f !== undefined)
+        .map((f) => (type === 'list' || type === 'custom' ? f : coerceNumericLiteral(f)));
+    if (parsed.length > 0)
+        rule.formulae = parsed;
+    return rule;
+}
+/** Parse every extended `<x14:dataValidation>` out of a worksheet's `<extLst>` into range-bound
+ * rules tagged `extended`, 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 parser ignores these (they are
+ * prefixed); this one, symmetrically, handles only the prefixed elements. */
+export function parseExtendedDataValidations(xml) {
+    const entries = [];
+    let current;
+    // Which operand an `<xm:f>` feeds (set by the enclosing `<x14:formula1>`/`<x14:formula2>`), and
+    // which child element's text is currently being gathered.
+    let slot;
+    let capture;
+    let text = '';
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const ln = localName(name);
+            const prefixed = name.includes(':');
+            // A `<x14:dataValidation>`; its attributes (type, flags, messages) build the rule.
+            if (ln === 'dataValidation' && prefixed) {
+                current = { attrs, formulae: [], sqref: '' };
+            }
+            else if (current !== undefined && prefixed && ln === 'formula1') {
+                slot = 0;
+            }
+            else if (current !== undefined && prefixed && ln === 'formula2') {
+                slot = 1;
+            }
+            else if (current !== undefined && ln === 'f') {
+                capture = 'formula';
+                text = '';
+            }
+            else if (current !== undefined && ln === 'sqref') {
+                capture = 'sqref';
+                text = '';
+            }
+        },
+        onText(chunk) {
+            if (capture !== undefined)
+                text += chunk;
+        },
+        onClose(name) {
+            const ln = localName(name);
+            if (ln === 'f' && capture === 'formula') {
+                if (current !== undefined && slot !== undefined)
+                    current.formulae[slot] = text;
+                capture = undefined;
+            }
+            else if (ln === 'sqref' && capture === 'sqref') {
+                if (current !== undefined)
+                    current.sqref = text;
+                capture = undefined;
+            }
+            else if ((ln === 'formula1' || ln === 'formula2') && name.includes(':')) {
+                slot = undefined;
+            }
+            else if (ln === 'dataValidation' && name.includes(':') && current !== undefined) {
+                const built = buildExtendedEntry(current.attrs, current.formulae, current.sqref);
+                if (built !== undefined)
+                    entries.push(built);
+                current = undefined;
+            }
+        },
+    });
+    return entries;
+}
+function buildExtendedEntry(attrs, formulae, sqref) {
+    if (sqref === '')
+        return undefined;
+    const rule = buildRule(attrs, formulae);
+    return rule === undefined ? undefined : { sqref, rule, extended: true };
+}
+/** 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 function applyDataValidations(sheet, entries) {
+    for (const { sqref, rule, extended } of entries) {
+        sheet.addDataValidation(sqref, rule, extended ? { extended: true } : {});
+    }
+}

package/dist/io/xlsx/edit-vba.d.ts

@@ -0,0 +1,23 @@
+import { type VbaLibraryReference } from '../../vba/project-editor.ts';
+/**
+ * Remove a standard module from an existing macro-enabled package's VBA project, returning new package
+ * bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see {@link removeVbaModule} for
+ * what changes within it), and any digital signature over the old project is dropped because it cannot
+ * validate the new bytes.
+ *
+ * @throws {VbaAuthorError} if the package carries no VBA project, `name` is not in the project, or names
+ *   a `document`/`designer` module.
+ * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
+ */
+export declare function editXlsxVbaRemoveModule(xlsx: Uint8Array, name: string): Uint8Array;
+/**
+ * Add a registered (COM type-library) reference to an existing macro-enabled package's VBA project,
+ * returning new package bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see
+ * {@link addVbaReference} for what changes within it), and any digital signature over the old project is
+ * dropped because it cannot validate the new bytes.
+ *
+ * @throws {VbaAuthorError} if the package carries no VBA project, or any field of `ref` is invalid (see
+ *   {@link VbaLibraryReference}).
+ * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
+ */
+export declare function editXlsxVbaAddReference(xlsx: Uint8Array, ref: VbaLibraryReference): Uint8Array;

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

@@ -0,0 +1,139 @@
+// Structurally edit an existing `.xlsm` at the *package* level: remove a module, or add a reference,
+// returning new package bytes with every other part preserved byte-for-byte. Only `xl/vbaProject.bin` is
+// rewritten (plus dropping a now-stale signature); worksheets, styles, drawings, and every other part
+// ride through untouched.
+//
+// This is the highest-fidelity way to tweak an existing macro project. The alternative — `readXlsx` →
+// the matching `Workbook` method → `writeXlsx` — rebuilds the whole package from the parsed model, which
+// re-serialises every part and so only preserves what the model captures. For a rich, real-world
+// workbook that round-trip can perturb parts Excel is strict about; splicing the original bytes cannot,
+// because it never re-authors anything but the macro project. Use this when the input is a real file
+// whose non-macro content must be preserved exactly.
+//
+// Authoring or editing module SOURCE is not here: Excel runs a module's compiled p-code, not its source,
+// so that needs the offline `tools/vba-compiler` (VBIDE), which can produce a whole edited `.xlsm`
+// directly (ADR 0019).
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+import { VbaAuthorError } from "../../vba/errors.js";
+import { addVbaReference, removeVbaModule, } from "../../vba/project-editor.js";
+import { relsPathFor } from "../opc/part-paths.js";
+import { parseRelationshipRecords, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from "../opc/read-opc.js";
+const OFFICE_DOCUMENT_REL = 'officeDocument';
+const VBA_PROJECT_REL = 'vbaProject';
+// Every signature flavour Excel writes over a VBA project (legacy, agile, V3) shares this local-name
+// prefix; all become stale the instant the project's bytes change and must be dropped with it.
+const VBA_SIGNATURE_REL_INFIX = 'vbaProjectSignature';
+/**
+ * Remove a standard module from an existing macro-enabled package's VBA project, returning new package
+ * bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see {@link removeVbaModule} for
+ * what changes within it), and any digital signature over the old project is dropped because it cannot
+ * validate the new bytes.
+ *
+ * @throws {VbaAuthorError} if the package carries no VBA project, `name` is not in the project, or names
+ *   a `document`/`designer` module.
+ * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
+ */
+export function editXlsxVbaRemoveModule(xlsx, name) {
+    return applyToVbaProjectPart(xlsx, (bin) => removeVbaModule(bin, name));
+}
+/**
+ * Add a registered (COM type-library) reference to an existing macro-enabled package's VBA project,
+ * returning new package bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see
+ * {@link addVbaReference} for what changes within it), and any digital signature over the old project is
+ * dropped because it cannot validate the new bytes.
+ *
+ * @throws {VbaAuthorError} if the package carries no VBA project, or any field of `ref` is invalid (see
+ *   {@link VbaLibraryReference}).
+ * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
+ */
+export function editXlsxVbaAddReference(xlsx, ref) {
+    return applyToVbaProjectPart(xlsx, (bin) => addVbaReference(bin, ref));
+}
+// Shared plumbing for every package-level VBA edit: unzip, locate `xl/vbaProject.bin`, replace it with
+// whatever `apply` produces, drop a now-stale signature, and re-zip. `apply` is expected to validate
+// fail-closed itself (every project-editor primitive does), so a bad edit throws before `files` is
+// touched.
+function applyToVbaProjectPart(xlsx, apply) {
+    // Widen off fflate's `Uint8Array<ArrayBuffer>` element type so spliced/re-serialised parts (whose
+    // buffers are `ArrayBufferLike`) assign back into the map.
+    const files = unzipSync(xlsx);
+    const binPath = locateVbaProjectPart(files);
+    const bin = binPath === undefined ? undefined : files[binPath];
+    if (binPath === undefined || bin === undefined) {
+        throw new VbaAuthorError('package has no VBA project to edit');
+    }
+    files[binPath] = apply(bin);
+    dropStaleSignature(files, binPath);
+    return zipSync(files);
+}
+// Resolve the package's `xl/vbaProject.bin` part the way the reader does: `_rels/.rels` → the
+// officeDocument (workbook) part → its `.rels` → the `vbaProject` relationship, each target resolved
+// relative to its referrer. undefined when the package declares no such relationship (a macro-free book).
+function locateVbaProjectPart(files) {
+    const rootRels = textPart(files, '_rels/.rels');
+    if (rootRels === undefined)
+        return undefined;
+    const workbookTarget = relationshipTargetByType(rootRels, OFFICE_DOCUMENT_REL);
+    if (workbookTarget === undefined)
+        return undefined;
+    const workbookPath = resolveRelativePart('', workbookTarget);
+    const workbookRels = textPart(files, relsPathFor(workbookPath));
+    if (workbookRels === undefined)
+        return undefined;
+    const vbaTarget = relationshipTargetByType(workbookRels, VBA_PROJECT_REL);
+    if (vbaTarget === undefined)
+        return undefined;
+    return resolveVbaTarget(workbookPath, vbaTarget);
+}
+// The workbook's vbaProject relationship uses a workbook-relative target (`vbaProject.bin`); resolve it
+// through the workbook-part rule so both that and an absolute `/xl/vbaProject.bin` land on the part path.
+function resolveVbaTarget(workbookPath, target) {
+    if (target.startsWith('/'))
+        return target.slice(1);
+    if (workbookPath.startsWith('xl/'))
+        return resolveWorkbookPart(target);
+    return resolveRelativePart(workbookPath, target);
+}
+// Editing the project invalidates any signature over it, so remove every signature part the project's
+// `.rels` reaches, the relationships that point at them, and their content-type overrides — leaving a
+// package that advertises no signature rather than a broken one (mirrors Workbook.vbaProjectBytes).
+function dropStaleSignature(files, binPath) {
+    const binRelsPath = relsPathFor(binPath);
+    const binRels = textPart(files, binRelsPath);
+    if (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');
+    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);
+    }
+    if (parseRelationshipRecords(rels).length === 0)
+        delete files[binRelsPath];
+    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);
+}
+// Drop the `<Relationship>` element carrying a given Id, matching the element as a whole (self-closing
+// or paired) so attribute order does not matter.
+function removeRelationshipById(xml, id) {
+    return xml.replace(/<Relationship\b[^>]*?\/>|<Relationship\b[\s\S]*?<\/Relationship>/g, (element) => (new RegExp(`\\bId="${escapeRegExp(id)}"`).test(element) ? '' : element));
+}
+// Drop the `<Override>` naming a given part path; PartName is the full, unambiguous package path.
+function removeContentTypeOverride(xml, partPath) {
+    return xml.replace(/<Override\b[^>]*?\/>/g, (element) => element.includes(`PartName="/${partPath}"`) ? '' : element);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,17 @@
+import { XlsxError } from '../../errors.ts';
+/**
+ * Thrown when an `.xlsx` package's XML content is well-formed but does not describe a workbook this
+ * library can act on — a `xl/workbook.xml` that declares no worksheets, say.
+ *
+ * It sits between two neighbours. {@link XmlParseError} reports that the *markup* did not parse;
+ * {@link UnsupportedFormatError} reports that the *container* is not one we read at all. This one
+ * fires when both of those were fine and the document itself is nonetheless not a workbook.
+ *
+ * The reader is deliberately lenient about content it does not recognise — an unknown element is
+ * skipped, not fatal — so this is rare by design, and reaching it means something a workbook cannot
+ * do without being corrupt.
+ */
+export declare class XlsxParseError extends XlsxError {
+    readonly name = "XlsxParseError";
+    readonly code = "malformed-input";
+}

package/dist/io/xlsx/errors.js

@@ -0,0 +1,17 @@
+import { XlsxError } from "../../errors.js";
+/**
+ * Thrown when an `.xlsx` package's XML content is well-formed but does not describe a workbook this
+ * library can act on — a `xl/workbook.xml` that declares no worksheets, say.
+ *
+ * It sits between two neighbours. {@link XmlParseError} reports that the *markup* did not parse;
+ * {@link UnsupportedFormatError} reports that the *container* is not one we read at all. This one
+ * fires when both of those were fine and the document itself is nonetheless not a workbook.
+ *
+ * The reader is deliberately lenient about content it does not recognise — an unknown element is
+ * skipped, not fatal — so this is rare by design, and reaching it means something a workbook cannot
+ * do without being corrupt.
+ */
+export class XlsxParseError extends XlsxError {
+    name = 'XlsxParseError';
+    code = 'malformed-input';
+}

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

@@ -0,0 +1,42 @@
+import type { Worksheet } from '../../core/worksheet.ts';
+import type { SheetRelIds } 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. */
+export interface CollectedHyperlink {
+    readonly ref: string;
+    readonly target: string;
+    readonly tooltip?: string;
+}
+/** 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. */
+export interface HyperlinkPlan {
+    readonly ref: string;
+    readonly relId?: string;
+    readonly target?: string;
+    readonly location?: string;
+    readonly tooltip?: string;
+}
+/** Gather every hyperlink cell on a sheet, in row-major order. */
+export declare function collectHyperlinks(sheet: Worksheet): CollectedHyperlink[];
+/** 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: SheetRelIds): 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;
+/** A hyperlink parsed from a sheet: its cell reference plus whichever of `rid`/`location`/`tooltip`
+ * the `<hyperlink>` element carried. */
+interface ParsedHyperlink {
+    readonly ref: string;
+    readonly rid?: string;
+    readonly location?: string;
+    readonly tooltip?: string;
+}
+/** Parse every `<hyperlink>` element out of a worksheet part. */
+export declare function parseSheetHyperlinks(xml: string): ParsedHyperlink[];
+/** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
+ * label) into a {@link HyperlinkValue}. `rels` maps a relationship id to its target URL. */
+export declare function applyHyperlinks(sheet: Worksheet, links: readonly ParsedHyperlink[], rels: Map<string, string>): void;
+export {};

package/dist/io/xlsx/hyperlinks.js

@@ -0,0 +1,139 @@
+// Cell hyperlinks — the sheet-level `<hyperlinks>` element, its external relationships, and the
+// reader that folds a link back onto its cell's value.
+//
+// A hyperlink is not stored inside the cell in OOXML: the `<c>` holds only the visible label (a
+// normal string value), while a separate `<hyperlink>` child of `<worksheet>` ties an A1 reference
+// to a destination. An EXTERNAL destination (a URL) is reached indirectly, through a sheet
+// relationship carrying `TargetMode="External"` that the `<hyperlink>` names by `r:id`. An INTERNAL
+// destination (a location inside the same workbook, which the author writes as a `#`-prefixed value)
+// is held directly in a `location` attribute with NO relationship — emitting an internal target as an
+// external relationship makes a strict consumer resolve both the rel and the location and render the
+// destination doubled.
+import { decodeRange } from "../../core/address.js";
+import { isHyperlinkValue, isRichTextValue } from "../../core/value.js";
+import { escapeAttr } from "../../xml/xml.js";
+import { localName, parseXml } from "../../xml/xml-read.js";
+/** Gather every hyperlink cell on a sheet, in row-major order. */
+export function collectHyperlinks(sheet) {
+    const links = [];
+    for (const { cells } of sheet.rows()) {
+        for (const cell of cells) {
+            const value = cell.value;
+            if (isHyperlinkValue(value)) {
+                // A link that spans a range carries its extent in `range`; the anchor cell (this one) is the
+                // range's top-left. Emit that extent as `ref` so the clickable area survives, falling back to
+                // the single cell for an ordinary link.
+                links.push({
+                    ref: value.range ?? cell.address,
+                    target: value.hyperlink,
+                    ...(value.tooltip !== undefined ? { tooltip: value.tooltip } : {}),
+                });
+            }
+        }
+    }
+    return links;
+}
+/** 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 function planHyperlinks(links, rels) {
+    return links.map((link) => {
+        const tooltip = link.tooltip !== undefined ? { tooltip: link.tooltip } : {};
+        // A '#'-prefixed target is an internal document location: held verbatim in `location`, with no
+        // relationship. Everything else is an external URL reached through a relationship.
+        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 };
+    });
+}
+/** The `<hyperlinks>` element, or '' when the sheet has none. Attribute order follows CT_Hyperlink:
+ * `ref`, `r:id`, `location`, `tooltip`. */
+export function hyperlinksXml(links) {
+    if (links.length === 0)
+        return '';
+    const items = links
+        .map((link) => {
+        const rid = link.relId !== undefined ? ` r:id="${link.relId}"` : '';
+        const location = link.location !== undefined ? ` location="${escapeAttr(link.location)}"` : '';
+        const tooltip = link.tooltip !== undefined ? ` tooltip="${escapeAttr(link.tooltip)}"` : '';
+        return `<hyperlink ref="${escapeAttr(link.ref)}"${rid}${location}${tooltip}/>`;
+    })
+        .join('');
+    return `<hyperlinks>${items}</hyperlinks>`;
+}
+/** Parse every `<hyperlink>` element out of a worksheet part. */
+export function parseSheetHyperlinks(xml) {
+    const links = [];
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            if (localName(name) !== 'hyperlink')
+                return;
+            const ref = attrs.ref;
+            if (ref === undefined)
+                return;
+            links.push({
+                ref,
+                ...(attrs['r:id'] !== undefined ? { rid: attrs['r:id'] } : {}),
+                ...(attrs.location !== undefined ? { location: attrs.location } : {}),
+                ...(attrs.tooltip !== undefined ? { tooltip: attrs.tooltip } : {}),
+            });
+        },
+    });
+    return links;
+}
+/** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
+ * label) into a {@link HyperlinkValue}. `rels` maps a relationship id to its target URL. */
+export function applyHyperlinks(sheet, links, rels) {
+    for (const link of links) {
+        const target = resolveTarget(link, rels);
+        if (target === undefined)
+            continue;
+        // A hyperlink may span a range (`ref="D1:H1"`); Excel anchors the link at the range's top-left
+        // cell. Decode once so a multi-cell link folds onto that anchor rather than asking the sheet for
+        // a range address it cannot resolve. A ref that does not decode is skipped, not fatal.
+        const decoded = decodeRefSafe(link.ref);
+        if (decoded === undefined)
+            continue;
+        const cell = sheet.getCell(decoded.tl.address);
+        // The visible label is the cell's own value: a plain string, or rich text when the label
+        // carried per-run formatting. Any other value kind has no textual label, so it reads as empty.
+        const cellValue = cell.value;
+        const text = typeof cellValue === 'string' ? cellValue : isRichTextValue(cellValue) ? cellValue : '';
+        // Record the extent only when the link genuinely spans more than the anchor, so an ordinary
+        // single-cell link stays a plain value and the range survives verbatim for a multi-cell one.
+        const spansRange = decoded.tl.address !== decoded.br.address;
+        const value = {
+            hyperlink: target,
+            text,
+            ...(link.tooltip !== undefined ? { tooltip: link.tooltip } : {}),
+            ...(spansRange ? { range: link.ref } : {}),
+        };
+        cell.value = value;
+    }
+}
+// A hyperlink's `ref` decoded to a range (a single-cell ref decodes to a range whose corners
+// coincide), so the caller can both anchor on the top-left and tell whether the link spans further.
+// Returns undefined for a ref that does not decode, so a malformed hyperlink is dropped rather than
+// crashing the load.
+function decodeRefSafe(ref) {
+    try {
+        return decodeRange(ref);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveTarget(link, rels) {
+    if (link.rid !== undefined) {
+        const base = rels.get(link.rid);
+        if (base === undefined)
+            return undefined;
+        // A foreign file may split an external URL's fragment into the `location` attribute, apart from
+        // the relationship Target; rejoin them so the whole URL survives. Our own writer keeps the
+        // fragment in the Target, so a link we wrote never carries both.
+        return link.location !== undefined ? `${base}#${link.location}` : base;
+    }
+    // No relationship: an internal ('#'-prefixed) target held verbatim in `location`.
+    return link.location !== undefined ? `#${link.location}` : undefined;
+}