@alosha/xlsx 0.3.0 → 0.4.0

package/README.md

@@ -118,7 +118,7 @@ functions accept a `ReadOptions` (reserved for future use).
 | Multiple worksheets, sheet state (visible / hidden / veryHidden) | ✅ | ✅ | |
 | Workbook & sheet views (freeze/split, zoom, active tab) | ✅ | ✅ | round-trip as data |
 | Workbook metadata (creator, dates, title, …) | ✅ | ✅ | |
-| Hyperlink cells | ⚠️ | ⚠️ | round-trip as display **text** — see limitations |
+| Hyperlink cells (external URL/mailto) | ✅ | ✅ | real OOXML relationship, round-trips as `{ text, hyperlink, tooltip? }`; internal `location=` links deferred |
 | Streaming read/write | ❌ | ❌ | deferred |
 | Drawings / images / charts | ❌ | ❌ | deferred |
 | Data validation, conditional formatting, comments | ❌ | ❌ | deferred |
@@ -138,7 +138,6 @@ behave as you'd expect. Common differences to watch for:
 - **Clearer row inheritance.** Instead of ExcelJS's `'i' | 'o' | 'i+' | 'o+'` DSL, `addRow` /
   `insertRow` take `{ inheritFrom: "above" | "below", includeEmpty?: boolean }`.
 - **ESM-first.** The package is ESM with a CJS fallback; prefer `import` over `require`.
-- **Hyperlinks round-trip as text** (see below).
 
 Not everything ExcelJS does is implemented yet — check the feature matrix and limitations before
 porting a workbook that leans on drawings, streaming, or data validation.
@@ -151,16 +150,18 @@ behavioural notes to check before porting.
 
 ## Known limitations
 
-- **Hyperlink cells round-trip as their display text.** Setting a `{ text, hyperlink }` value
-  writes the visible text; the clickable link relationship is not yet persisted, and reading a
-  workbook with hyperlinks yields the text only. Real hyperlink relationships are planned.
+- **Internal (in-workbook) hyperlinks are deferred.** External `http(s)`/`mailto` cell hyperlinks
+  round-trip as real OOXML relationships (`{ text, hyperlink, tooltip? }`). Links to a location
+  within the same workbook (ExcelJS's `location="Sheet2!A1"` form, no external relationship) aren't
+  written or read yet.
 - **No streaming.** Reading and writing are buffer-based (the whole workbook lives in memory). A
   streaming API for very large sheets is deferred.
 - **No drawings, images, or charts.** These parts are ignored on read and not emitted on write.
 - **No data validation, conditional formatting, or comments** yet.
 
-See [`BENCHMARKS.md`](./BENCHMARKS.md) for write/read throughput and output-size numbers against
-ExcelJS, and [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
+See [`BENCHMARKS.md`](https://github.com/avlisodraude/alosha-xlsx/blob/main/BENCHMARKS.md) for
+write/read throughput and output-size numbers against ExcelJS, and
+[`CHANGELOG.md`](https://github.com/avlisodraude/alosha-xlsx/blob/main/CHANGELOG.md) for release notes.
 
 ## Development
 

package/dist/{chunk-6XXKAKLS.js → chunk-C67HH2MR.js}

@@ -1692,7 +1692,8 @@ var REL_TYPE = {
   worksheet: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet",
   styles: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
   sharedStrings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings",
-  theme: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+  theme: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme",
+  hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
 };
 var PART_PATH = {
   contentTypes: "[Content_Types].xml",
@@ -1993,11 +1994,23 @@ function openPackage(bytes) {
       relsMap.set(rel.id, { type: rel.type, target: resolveRelTarget(workbookDir, rel.target) });
     }
   }
+  const partRels = (partPath) => {
+    const dir = dirname(partPath);
+    const relsXml = text(relsPathFor(partPath));
+    const map = /* @__PURE__ */ new Map();
+    if (relsXml === void 0) return map;
+    for (const rel of parseRels(relsXml)) {
+      const target = rel.mode === "External" ? rel.target : resolveRelTarget(dir, rel.target);
+      map.set(rel.id, { type: rel.type, target, mode: rel.mode });
+    }
+    return map;
+  };
   return {
     entry,
     text,
     workbookRels: () => relsMap,
-    workbookPath: () => workbookPath
+    workbookPath: () => workbookPath,
+    partRels
   };
 }
 function readZip(bytes) {
@@ -2019,7 +2032,8 @@ function parseRels(xml) {
       rels.push({
         id: child.attrs.Id ?? "",
         type: child.attrs.Type ?? "",
-        target: child.attrs.Target ?? ""
+        target: child.attrs.Target ?? "",
+        mode: child.attrs.TargetMode === "External" ? "External" : "Internal"
       });
     });
   }
@@ -2923,6 +2937,7 @@ function parseWorksheet(ws, xml, ctx) {
   while (ev && !(ev.kind === "open" && localName(ev.name) === "worksheet")) ev = c.next();
   if (ev?.kind !== "open" || ev.selfClosing) return;
   const merges = [];
+  const hyperlinks = [];
   c.eachChild(ev.name, (child) => {
     switch (localName(child.name)) {
       case "cols":
@@ -2934,11 +2949,17 @@ function parseWorksheet(ws, xml, ctx) {
       case "mergeCells":
         if (!child.selfClosing) collectMerges(c, child.name, merges);
         break;
+      case "hyperlinks":
+        if (!child.selfClosing) collectHyperlinks(c, child.name, hyperlinks);
+        break;
       default:
         if (!child.selfClosing) c.textUntilClose(child.name);
     }
   });
   for (const ref of merges) ws.mergeCells(ref);
+  if (ctx.rels) {
+    for (const link of hyperlinks) applyHyperlink(ws, link, ctx.rels);
+  }
 }
 function parseCols(c, container, ws, ctx) {
   c.eachChild(container, (col) => {
@@ -3079,6 +3100,35 @@ function collectMerges(c, container, merges) {
     }
   });
 }
+function collectHyperlinks(c, container, hyperlinks) {
+  c.eachChild(container, (child) => {
+    if (localName(child.name) !== "hyperlink") {
+      if (!child.selfClosing) c.textUntilClose(child.name);
+      return;
+    }
+    const ref = child.attrs.ref;
+    const rId = relId2(child);
+    if (ref === void 0 || rId === "") return;
+    const tooltip = child.attrs.tooltip;
+    hyperlinks.push(tooltip !== void 0 ? { ref, rId, tooltip } : { ref, rId });
+  });
+}
+function applyHyperlink(ws, link, rels) {
+  const rel = rels.get(link.rId);
+  if (!rel) return;
+  const topLeft = link.ref.split(":")[0] ?? link.ref;
+  const cell = ws.getCell(topLeft);
+  const text = typeof cell.value === "string" ? cell.value : "";
+  cell.value = link.tooltip !== void 0 ? { text, hyperlink: rel.target, tooltip: link.tooltip } : { text, hyperlink: rel.target };
+}
+function relId2(el) {
+  const direct = el.attrs["r:id"];
+  if (direct !== void 0) return direct;
+  for (const key of Object.keys(el.attrs)) {
+    if (localName(key) === "id") return el.attrs[key] ?? "";
+  }
+  return "";
+}
 function decodeBool(raw) {
   if (raw === "1" || raw === "true" || raw === "TRUE") return true;
   if (raw === "0" || raw === "false" || raw === "FALSE") return false;
@@ -3116,7 +3166,9 @@ function readWorkbookBuffer(bytes, _options) {
     const target = rels.get(sheet.rId)?.target;
     if (target === void 0) continue;
     const sheetXml = pkg.text(target);
-    if (sheetXml !== void 0) parseWorksheet(ws, sheetXml, ctx);
+    if (sheetXml !== void 0) {
+      parseWorksheet(ws, sheetXml, { ...ctx, rels: pkg.partRels(target) });
+    }
   }
   const coreXml = pkg.text(PART_PATH.coreProps);
   if (coreXml !== void 0) applyCoreProps(wb, coreXml);
@@ -3382,6 +3434,22 @@ function renderWorkbookRels(rels) {
   return w.toString();
 }
 
+// src/xlsx/parts/worksheet-rels.ts
+function renderWorksheetRels(rels) {
+  const w = new XmlWriter();
+  w.open("Relationships", { xmlns: NS.packageRels });
+  for (const rel of rels) {
+    w.leaf("Relationship", {
+      Id: rel.rId,
+      Type: REL_TYPE.hyperlink,
+      Target: rel.target,
+      TargetMode: rel.mode
+    });
+  }
+  w.close("Relationships");
+  return w.toString();
+}
+
 // src/xlsx/parts/worksheet.ts
 var DEFAULT_DATE_NUMFMT = "mm-dd-yy";
 function renderWorksheet(ws, ctx) {
@@ -3399,11 +3467,13 @@ function renderWorksheet(ws, ctx) {
     defaultRowHeight: model.properties.defaultRowHeight ?? 15,
     defaultColWidth: model.properties.defaultColWidth
   });
+  const hyperlinks = [];
   renderCols(w, model.columns, ctx);
-  renderSheetData(w, model.rows, ctx);
+  renderSheetData(w, model.rows, ctx, hyperlinks);
   renderMergeCells(w, model.merges);
+  const rels = renderHyperlinks(w, hyperlinks);
   w.close("worksheet");
-  return w.toString();
+  return { xml: w.toString(), rels };
 }
 function renderCols(w, columns, ctx) {
   if (!columns || columns.length === 0) return;
@@ -3429,13 +3499,13 @@ function renderCols(w, columns, ctx) {
   for (const f of fragments) w.raw(f);
   w.close("cols");
 }
-function renderSheetData(w, rows, ctx) {
+function renderSheetData(w, rows, ctx, hyperlinks) {
   w.open("sheetData");
   for (const row of rows) {
     const styleId = row.style ? ctx.styles.addStyle(row.style) : 0;
     let cellsXml = "";
     for (const cell of row.cells) {
-      cellsXml += renderCell(cell, ctx);
+      cellsXml += renderCell(cell, ctx, hyperlinks);
     }
     const hasAttrs = row.height !== void 0 || row.hidden || (row.outlineLevel ?? 0) !== 0 || styleId !== 0;
     if (cellsXml === "" && !hasAttrs) continue;
@@ -3453,7 +3523,7 @@ function renderSheetData(w, rows, ctx) {
   }
   w.close("sheetData");
 }
-function renderCell(cell, ctx) {
+function renderCell(cell, ctx, hyperlinks) {
   const styleId = cell.style ? ctx.styles.addStyle(cell.style) : 0;
   const r = cell.address;
   switch (cell.type) {
@@ -3472,8 +3542,11 @@ function renderCell(cell, ctx) {
       return valueCell(r, styleId, "e", cell.value.error);
     case 2 /* String */:
       return stringCell(r, styleId, cell.value, ctx);
-    case 7 /* Hyperlink */:
-      return stringCell(r, styleId, cell.value.text, ctx);
+    case 7 /* Hyperlink */: {
+      const link = cell.value;
+      hyperlinks.push({ ref: r, target: link.hyperlink, tooltip: link.tooltip });
+      return stringCell(r, styleId, link.text, ctx);
+    }
     case 6 /* RichText */:
       return richTextCell(r, styleId, cell.value, ctx);
     case 8 /* Formula */:
@@ -3547,6 +3620,18 @@ function renderMergeCells(w, merges) {
   for (const ref of merges) w.leaf("mergeCell", { ref });
   w.close("mergeCells");
 }
+function renderHyperlinks(w, hyperlinks) {
+  if (hyperlinks.length === 0) return void 0;
+  const rels = [];
+  w.open("hyperlinks");
+  hyperlinks.forEach((h, i) => {
+    const rId = `rId${i + 1}`;
+    w.leaf("hyperlink", { ref: h.ref, "r:id": rId, tooltip: h.tooltip });
+    rels.push({ rId, target: h.target, mode: "External" });
+  });
+  w.close("hyperlinks");
+  return renderWorksheetRels(rels);
+}
 
 // src/xlsx/write-workbook.ts
 function writeWorkbookBuffer(wb, options) {
@@ -3610,7 +3695,10 @@ function writeWorkbookBuffer(wb, options) {
   put(PART_PATH.styles, styles.toXml());
   if (sharedStringsXml !== void 0) put(PART_PATH.sharedStrings, sharedStringsXml);
   put(PART_PATH.theme, renderTheme());
-  for (const [file, xml] of worksheetXml) put(`xl/worksheets/${file}`, xml);
+  for (const [file, { xml, rels }] of worksheetXml) {
+    put(`xl/worksheets/${file}`, xml);
+    if (rels !== void 0) put(`xl/worksheets/_rels/${file}.rels`, rels);
+  }
   return writeZipArchive(entries);
 }
 async function writeWorkbookFile(wb, path, options) {
@@ -3659,5 +3747,5 @@ Object.defineProperty(Workbook.prototype, "xlsx", {
 var version = "0.0.0";
 
 export { AloshaXlsxError, Cell, CellType, Column, DEFAULT_COLUMN_WIDTH, DuplicateWorksheetNameError, FormulaType, InvalidAddressError, InvalidCellValueError, InvalidPackageError, InvalidRangeError, InvalidRowNumberError, InvalidWorksheetNameError, MergeConflictError, Range, ReservedWorksheetNameError, Row, UnsupportedFeatureError, Workbook, Worksheet, WorksheetNameTooLongError, colLetterToNumber, colNumberToLetter, createSharedStrings, createStyles, dateToSerial, decodeAddress, decodeEx, detectType, effectiveType, encodeAddress, fromStored, isAloshaXlsxError, readWorkbookBuffer, readWorkbookFile, resolveCellStyle, serialToDate, toCsv, toStored, toText, validateAddress, version, writeWorkbookBuffer, writeWorkbookFile };
-//# sourceMappingURL=chunk-6XXKAKLS.js.map
-//# sourceMappingURL=chunk-6XXKAKLS.js.map
+//# sourceMappingURL=chunk-C67HH2MR.js.map
+//# sourceMappingURL=chunk-C67HH2MR.js.map