// Worksheet hyperlinks. // // External URLs land in `xl/worksheets/_rels/sheetN.xml.rels` (one rel per // Hyperlink entry, type "...relationships/hyperlink", TargetMode="External"). // Internal jumps (`#'Sheet 2'!A1`) live entirely in the `` attribute and don't need a rel. import { OpenXmlSchemaError } from '../utils/exceptions.js'; export interface Hyperlink { /** Cell or range the hyperlink covers — "A1" or "A1:B5". */ ref: string; /** External URL or relative target path. Mutually exclusive with `location`-only links. */ target?: string; /** Anchor inside the workbook (e.g. `'Sheet 2'!A1`). */ location?: string; /** Tooltip shown on hover. */ tooltip?: string; /** Visible link text — typically falls back to the referenced cell value. */ display?: string; /** Worksheet-rels rId. Populated on read; assigned by the writer when missing. */ rId?: string; } /** * Anything the OPC `Target` attribute (`xsd:anyURI`) cannot carry: whitespace, * C0/C1 controls, and DEL. Excel does not ignore the one bad link — it refuses * the whole package and drops content on repair. */ const ILLEGAL_TARGET_CHAR = /[\u0000-\u0020\u007f-\u009f]/; /** The authority of a `scheme://authority/…` target, if the target has one. */ const AUTHORITY = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/([^/?#]*)/; const describeChar = (ch: string): string => ch === ' ' ? 'a space' : `U+${ch.codePointAt(0)?.toString(16).toUpperCase().padStart(4, '0')}`; /** * Reject a target the writer would emit verbatim into the rels and Excel would * then refuse. Applied when the hyperlink is authored, not when one is read * back off disk — a file that already carries a broken target still loads, so * it can be inspected and repaired. */ function assertValidTarget(target: string): void { if (target.length === 0) { throw new OpenXmlSchemaError( 'Hyperlink: target is empty — pass a URI, or use `location` for an in-workbook jump', ); } const illegal = ILLEGAL_TARGET_CHAR.exec(target); if (illegal?.[0] !== undefined) { throw new OpenXmlSchemaError( `Hyperlink: target "${target}" contains ${describeChar(illegal[0])} at index ${illegal.index}. ` + 'The rels Target attribute is xsd:anyURI and Excel refuses the file; percent-encode it or drop it.', ); } const authority = AUTHORITY.exec(target)?.[1]; if (authority !== undefined && /[^\u0021-\u007e]/.test(authority)) { throw new OpenXmlSchemaError( `Hyperlink: target "${target}" has a non-ASCII host. Percent-encoding does not rescue it — ` + 'convert the host to punycode (xn--…).', ); } } /** * Build a validated {@link Hyperlink}. `target` is checked against what the * OPC `Target` attribute accepts, so a bad URL fails here rather than as an * Excel repair prompt on a package that has already been written. */ export function makeHyperlink(opts: Partial & { ref: string }): Hyperlink { if (opts.ref === undefined || opts.ref.length === 0) { throw new OpenXmlSchemaError('Hyperlink: ref is required'); } if (opts.target !== undefined) assertValidTarget(opts.target); return { ref: opts.ref, ...(opts.target !== undefined ? { target: opts.target } : {}), ...(opts.location !== undefined ? { location: opts.location } : {}), ...(opts.tooltip !== undefined ? { tooltip: opts.tooltip } : {}), ...(opts.display !== undefined ? { display: opts.display } : {}), ...(opts.rId !== undefined ? { rId: opts.rId } : {}), }; } // ---- Worksheet ergonomic helpers ---------------------------------------- import type { Worksheet } from './worksheet.js'; const replaceHyperlink = (ws: Worksheet, hl: Hyperlink): Hyperlink => { const idx = ws.hyperlinks.findIndex((h) => h.ref === hl.ref); if (idx >= 0) ws.hyperlinks[idx] = hl; else ws.hyperlinks.push(hl); return hl; }; /** * Add an external URL hyperlink to a cell or range. The URL goes into the * worksheet rels as a hyperlink relationship; the writer generates an rId on * save. */ export const addUrlHyperlink = ( ws: Worksheet, ref: string, url: string, opts: { tooltip?: string; display?: string } = {}, ): Hyperlink => { return replaceHyperlink( ws, makeHyperlink({ ref, target: url, ...(opts.tooltip !== undefined ? { tooltip: opts.tooltip } : {}), ...(opts.display !== undefined ? { display: opts.display } : {}), }), ); }; /** * Add an in-workbook jump hyperlink (e.g. to `'Sheet2'!A1` or a defined-name). * No rels entry is written — the location is inline in the `` attribute. */ export const addInternalHyperlink = ( ws: Worksheet, ref: string, location: string, opts: { tooltip?: string; display?: string } = {}, ): Hyperlink => { return replaceHyperlink( ws, makeHyperlink({ ref, location, ...(opts.tooltip !== undefined ? { tooltip: opts.tooltip } : {}), ...(opts.display !== undefined ? { display: opts.display } : {}), }), ); }; /** `mailto:` shortcut. */ export const addMailtoHyperlink = ( ws: Worksheet, ref: string, email: string, opts: { subject?: string; tooltip?: string; display?: string } = {}, ): Hyperlink => { const url = opts.subject ? `mailto:${email}?subject=${encodeURIComponent(opts.subject)}` : `mailto:${email}`; return addUrlHyperlink(ws, ref, url, { ...(opts.tooltip !== undefined ? { tooltip: opts.tooltip } : {}), ...(opts.display !== undefined ? { display: opts.display } : {}), }); };