xlsx-to-markdown 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 khatada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# xlsx-to-markdown
+
+Node.js / TypeScript library that converts XLSX files to Markdown.
+
+Mixed content is handled automatically — paragraphs of text and tables can coexist on the same sheet, in any order. Multiple tables per sheet (including side-by-side tables) are supported.
+
+## Installation
+
+```bash
+npm install xlsx-to-markdown
+```
+
+## Quick Start
+
+```ts
+import { convertXlsxToMarkdown } from 'xlsx-to-markdown';
+
+const result = await convertXlsxToMarkdown('report.xlsx');
+console.log(result.markdown);
+```
+
+## API
+
+### `convertXlsxToMarkdown(input, options?)`
+
+Reads a file from disk (path string) or an in-memory buffer and returns a `ConvertResult`.
+
+```ts
+// From file path
+const result = await convertXlsxToMarkdown('report.xlsx');
+
+// From Buffer / Uint8Array
+const buffer = await fs.promises.readFile('report.xlsx');
+const result = await convertXlsxToMarkdown(buffer);
+```
+
+### `convertWorkbook(workbook, options?)`
+
+Converts an already-parsed SheetJS `WorkBook` object. Useful when you manage the SheetJS lifecycle yourself.
+
+```ts
+import * as XLSX from 'xlsx';
+import { convertWorkbook } from 'xlsx-to-markdown';
+
+const wb = XLSX.readFile('report.xlsx', { cellStyles: true });
+const result = convertWorkbook(wb);
+```
+
+### Return value — `ConvertResult`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `markdown` | `string` | Combined Markdown for all selected sheets |
+| `sheets` | `SheetResult[]` | Per-sheet breakdown |
+
+Each `SheetResult` contains:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Sheet name |
+| `index` | `number` | 0-based sheet index in the workbook |
+| `markdown` | `string` | Markdown for this sheet only |
+| `regions` | `Region[]` | Detected content regions with type and rendered Markdown |
+
+Each `Region` contains `type` (`"table"` \| `"paragraph"`), row/column bounds, and `markdown`.
+
+## Options
+
+```ts
+const result = await convertXlsxToMarkdown('report.xlsx', {
+  sheets: ['Summary', 'Detail'],   // include only these sheets (name or 0-based index)
+  sheetHeadings: true,             // prepend "## Sheet Name" before each sheet
+  headerRow: true,                 // treat first row of every table as a header
+  tableDetection: {
+    minColumns: 2,                 // minimum columns to classify a region as a table
+    minRows: 2,                    // minimum rows to classify a region as a table
+    useBorders: true,              // use cell borders as additional table hints
+  },
+  richText: true,                  // convert bold/italic/hyperlinks to inline markup
+  emptyCell: '',                   // placeholder for empty table cells
+  dateFormat: 'YYYY-MM-DD',        // date format tokens: YYYY MM DD HH mm ss
+  blankLinesBetweenRegions: 1,     // blank lines inserted between regions
+});
+```
+
+### Option defaults
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `sheets` | all sheets | |
+| `sheetHeadings` | `"auto"` | Headings added automatically when the workbook has >1 sheet |
+| `headerRow` | `true` | |
+| `tableDetection.minColumns` | `2` | |
+| `tableDetection.minRows` | `2` | |
+| `tableDetection.useBorders` | `true` | |
+| `richText` | `true` | |
+| `emptyCell` | `""` | |
+| `dateFormat` | `"YYYY-MM-DD"` | |
+| `blankLinesBetweenRegions` | `1` | |
+
+## Content Detection
+
+The library uses a recursive row→column→row scan to classify each block of cells as a **table** or **paragraph**.
+
+### Detection algorithm
+
+1. **Row scan** — split the sheet into bands of consecutive non-empty rows (empty rows act as separators)
+2. **Column scan** — within each band, find columns that are entirely empty and use them as split points → column sub-ranges
+3. **Recurse** — each column sub-range is processed independently by the same algorithm
+4. **Classify** — a band that cannot be split further is classified:
+   - **Table** — every row has `≥ minColumns` filled cells, and the band spans `≥ minRows` rows
+   - **Paragraph** — everything else
+
+When `useBorders: true` (default), an empty cell that has both a left and a right border is counted as "filled" — this keeps bordered-but-valueless table cells from breaking table detection. **Exception**: if every cell in a column within a band is blank *and* has no top or bottom border, the column is treated as empty regardless of left/right borders. This ensures that a separator column between two side-by-side tables is still recognised as a gap even when it carries border styles from the adjacent tables.
+
+### Side-by-side tables
+
+Tables placed horizontally on the same rows (separated by at least one empty column) are detected as independent regions:
+
+```
+     A     B     C          E     F     G
+1  Name  Score  Grade      Item   Qty  Price   ← two separate headers
+2  Alice   90    A         Apple   5    100
+3  Bob     75    B         Banana  3     60
+```
+
+Column D is empty → detected as two tables (A–C and E–G), each rendered as its own `<table>`.
+
+The separator column may carry left/right border styles from the adjacent table formatting. As long as it has no top or bottom border and no values anywhere within the row-band, it is still treated as an empty gap.
+
+### Mixed content example
+
+```
+Row 1:  "Section 1: Introduction"          ← paragraph
+Row 2:  (empty)
+Row 3:  Name    | Department | Salary      ← table header
+Row 4:  Alice   | Engineering| 800,000
+Row 5:  Bob     | Marketing  | 650,000
+Row 6:  (empty)
+Row 7:  "* Figures are in JPY"             ← paragraph
+Row 8:  (empty)
+Row 9:  Q1      | Q2                       ← second table
+Row 10: 1,200   | 1,450
+```
+
+Output:
+
+```markdown
+Section 1: Introduction
+
+<table>
+    <tr><th>Name</th><th>Department</th><th style="text-align: right">Salary</th></tr>
+    <tr><td>Alice</td><td>Engineering</td><td style="text-align: right">800,000</td></tr>
+    <tr><td>Bob</td><td>Marketing</td><td style="text-align: right">650,000</td></tr>
+</table>
+
+* Figures are in JPY
+
+<table>
+    <tr><th style="text-align: right">Q1</th><th style="text-align: right">Q2</th></tr>
+    <tr><td style="text-align: right">1,200</td><td style="text-align: right">1,450</td></tr>
+</table>
+```
+
+### Recognized table patterns
+
+The table below summarises which layouts are detected as a table and which fall back to a paragraph.
+
+| Excel layout | Detected as | Reason |
+| --- | --- | --- |
+| 2+ columns × 2+ rows of data | **table** | Meets `minColumns` and `minRows` thresholds |
+| Single column of text | **paragraph** | Below `minColumns` (default 2) |
+| Single row of data | **paragraph** | Below `minRows` (default 2) |
+| Every row has colspan spanning all columns | **paragraph** | Each row renders as one cell — no tabular structure |
+| Header row has colspan, data rows have multiple cells | **table** | At least one row has 2+ visible cells |
+| Cells with `rowspan` spanning multiple rows | **table** | Rendered as `<td rowspan="N">` with no layout breakage |
+| Two blocks separated by an empty column | **two tables** | Column gap triggers independent region detection |
+
+#### Pattern: full-width colspan in all rows → paragraph
+
+When every row in a region is merged across all columns (e.g. a block of title-style cells), the region has no relational structure and is rendered as a paragraph instead of an HTML table.
+
+```
+     A        B        C
+1  [    Title spanning A:C    ]   ← colspan=3
+2  [  Subtitle spanning A:C   ]   ← colspan=3
+3  [  Content spanning A:C    ]   ← colspan=3
+```
+
+Output:
+
+```markdown
+Title
+
+Subtitle
+
+Content
+```
+
+#### Pattern: merged header row + normal data rows → table
+
+A full-width merged header (colspan) in the first row is fine as long as at least one data row has multiple cells.
+
+```
+     A        B        C
+1  [       Report Title       ]   ← colspan=3
+2   Name    Score    Grade        ← 3 normal cells
+3   Alice    90        A
+```
+
+Output:
+
+```html
+<table>
+    <tr>
+    <th colspan="3">Report Title</th>
+    </tr>
+    <tr>
+    <td>Name</td>
+    <td style="text-align: right">Score</td>
+    <td>Grade</td>
+    </tr>
+    <tr>
+    <td>Alice</td>
+    <td style="text-align: right">90</td>
+    <td>A</td>
+    </tr>
+</table>
+```
+
+#### Pattern: rowspan across rows → table
+
+Cells with `rowspan` are rendered using the `rowspan` attribute. Because `<thead>`/`<tbody>` are not emitted, a `<th rowspan="N">` that visually spans into data rows does not cause layout breakage.
+
+```
+     A        B        C
+1   Name    [  Period (B:C)  ]   ← B1:C1 colspan=2
+2  Alice     Q1               ← A2:A3 rowspan=2
+3             Q2
+```
+
+Output:
+
+```html
+<table>
+    <tr>
+    <th>Name</th>
+    <th colspan="2">Period</th>
+    </tr>
+    <tr>
+    <td rowspan="2">Alice</td>
+    <td>Q1</td>
+    </tr>
+    <tr>
+    <td>Q2</td>
+    </tr>
+</table>
+```
+
+## Rich Text
+
+When `richText: true` (default), cell formatting is converted:
+
+| Excel format | Table output (HTML) | Paragraph output (Markdown) |
+| --- | --- | --- |
+| Bold | `<strong>text</strong>` | `**text**` |
+| Italic | `<em>text</em>` | `_text_` |
+| Bold + Italic | `<strong><em>text</em></strong>` | `***text***` |
+| Hyperlink | `<a href="url">text</a>` | `[text](url)` |
+
+## Table Formatting Details
+
+Tables are output as HTML (`<table>`) to support all Excel features:
+
+- **Merged cells** — `colspan` and `rowspan` attributes are set on the master (top-left) cell; child cells are omitted entirely.
+- **Header row** — rendered as `<th>` elements when `headerRow: true`.
+- **Column alignment** — columns whose data cells are all numeric (`cell.t === "n"`) are automatically right-aligned (`style="text-align: right"`), including currency-formatted values such as `¥1,000` or `$100`. Explicit cell alignment takes precedence.
+- **Newlines within cells** — converted to `<br>`.
+- **HTML escaping** — `&`, `<`, `>`, `"` in cell values are escaped to HTML entities.
+- **Formula cells** — the computed value is used; the formula string is never output.
+
+## Architecture Decision Records
+
+Design decisions are documented in [`docs/adr/`](docs/adr/).
+
+## Development
+
+```bash
+npm install
+npm test            # run all tests (vitest)
+npm run build       # compile TypeScript → dist/
+npm run lint        # oxlint
+npm run fmt         # oxfmt
+npm run fmt:check   # check formatting (CI)
+npm run secretlint  # scan for secrets
+```
+
+## License
+
+MIT

package/dist/__tests__/helpers.d.ts

@@ -0,0 +1,16 @@
+import * as XLSX from "xlsx";
+/**
+ * Build a simple WorkBook from a 2-D array of cell values.
+ * Row/column indices are 0-based.
+ * Pass `undefined` for empty cells.
+ */
+export declare function buildWorkbook(sheets: {
+    name: string;
+    data: (string | number | undefined)[][];
+}[]): XLSX.WorkBook;
+/**
+ * Normalise whitespace/newlines in markdown output so test assertions are
+ * not fragile against trailing spaces.
+ */
+export declare function normalise(md: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/__tests__/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/__tests__/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,CAAA;CAAE,EAAE,GAClE,IAAI,CAAC,QAAQ,CAOf;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAM5C"}

package/dist/__tests__/helpers.js

@@ -0,0 +1,63 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorkbook = buildWorkbook;
+exports.normalise = normalise;
+const XLSX = __importStar(require("xlsx"));
+/**
+ * Build a simple WorkBook from a 2-D array of cell values.
+ * Row/column indices are 0-based.
+ * Pass `undefined` for empty cells.
+ */
+function buildWorkbook(sheets) {
+    const wb = XLSX.utils.book_new();
+    for (const { name, data } of sheets) {
+        const ws = XLSX.utils.aoa_to_sheet(data.map((row) => row.map((v) => v ?? null)));
+        XLSX.utils.book_append_sheet(wb, ws, name);
+    }
+    return wb;
+}
+/**
+ * Normalise whitespace/newlines in markdown output so test assertions are
+ * not fragile against trailing spaces.
+ */
+function normalise(md) {
+    return md
+        .split("\n")
+        .map((l) => l.trimEnd())
+        .join("\n")
+        .trim();
+}
+//# sourceMappingURL=helpers.js.map

package/dist/__tests__/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/__tests__/helpers.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOA,sCASC;AAMD,8BAMC;AA5BD,2CAA6B;AAE7B;;;;GAIG;AACH,SAAgB,aAAa,CAC3B,MAAmE;IAEnE,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IACjC,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QACjF,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,SAAgB,SAAS,CAAC,EAAU;IAClC,OAAO,EAAE;SACN,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvB,IAAI,CAAC,IAAI,CAAC;SACV,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/dist/cell-formatter.d.ts

@@ -0,0 +1,16 @@
+import * as XLSX from "xlsx";
+import type { CellData, ResolvedOptions } from "./types.js";
+/**
+ * Escape pipe and backslash characters inside a GFM table cell value.
+ * @deprecated Not used in HTML table rendering; kept for potential external use.
+ */
+export declare function escapeTableCell(value: string): string;
+/**
+ * Escape HTML special characters for safe embedding in HTML attributes and text.
+ */
+export declare function escapeHtml(value: string): string;
+/**
+ * Extract a CellData object from an xlsx cell.
+ */
+export declare function extractCellData(cell: XLSX.CellObject | undefined, mergedChildCells: Set<string>, cellAddress: string, opts: ResolvedOptions): CellData;
+//# sourceMappingURL=cell-formatter.d.ts.map

package/dist/cell-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-formatter.d.ts","sourceRoot":"","sources":["../src/cell-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqE5D;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,CAAC,UAAU,GAAG,SAAS,EACjC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,EAC7B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,eAAe,GACpB,QAAQ,CAoIV"}

package/dist/cell-formatter.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeTableCell = escapeTableCell;
+exports.escapeHtml = escapeHtml;
+exports.extractCellData = extractCellData;
+const XLSX = __importStar(require("xlsx"));
+/**
+ * Format a date serial number (Excel date) to a string using a simple format.
+ * Tokens: YYYY, MM, DD, HH, mm, ss
+ */
+function formatDate(dateSerial, fmt) {
+    // Excel date serial: days since 1899-12-30 (accounting for the Lotus 1-2-3 bug)
+    const date = XLSX.SSF.parse_date_code(dateSerial);
+    if (!date)
+        return String(dateSerial);
+    const pad = (n) => String(n).padStart(2, "0");
+    return fmt
+        .replace("YYYY", String(date.y))
+        .replace("MM", pad(date.m))
+        .replace("DD", pad(date.d))
+        .replace("HH", pad(date.H))
+        .replace("mm", pad(date.M))
+        .replace("ss", pad(date.S));
+}
+/**
+ * Apply rich-text inline markdown (bold/italic) to a string.
+ */
+function applyInlineFormatting(text, bold, italic) {
+    if (!text)
+        return text;
+    if (bold && italic)
+        return `***${text}***`;
+    if (bold)
+        return `**${text}**`;
+    if (italic)
+        return `_${text}_`;
+    return text;
+}
+/**
+ * Unescape XML character entities.
+ */
+function unescapeXml(s) {
+    return s
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'");
+}
+/**
+ * Parse XLSX rich-text XML (cell.r) into an array of styled text runs.
+ * Returns null when the input is not rich-text XML or contains no runs.
+ *
+ * Expected XML format (OOXML shared-string rich text):
+ *   <r><rPr><b/></rPr><t xml:space="preserve">bold </t></r><r><t>normal</t></r>
+ */
+function parseRichTextRuns(xml) {
+    if (!xml.includes("<r>") && !xml.includes("<r "))
+        return null;
+    const runs = [];
+    const rPattern = /<r>([\s\S]*?)<\/r>/g;
+    let m;
+    while ((m = rPattern.exec(xml)) !== null) {
+        const inner = m[1];
+        const rPr = (/<rPr>([\s\S]*?)<\/rPr>/.exec(inner) ?? [])[1] ?? "";
+        const bold = /<b\b[^>]*\/?>/.test(rPr);
+        const italic = /<i\b[^>]*\/?>/.test(rPr);
+        const tMatch = /<t[^>]*>([\s\S]*?)<\/t>/.exec(inner);
+        if (tMatch) {
+            runs.push({ text: unescapeXml(tMatch[1]), bold, italic });
+        }
+    }
+    return runs.length > 0 ? runs : null;
+}
+/**
+ * Escape pipe and backslash characters inside a GFM table cell value.
+ * @deprecated Not used in HTML table rendering; kept for potential external use.
+ */
+function escapeTableCell(value) {
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+/**
+ * Escape HTML special characters for safe embedding in HTML attributes and text.
+ */
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Extract a CellData object from an xlsx cell.
+ */
+function extractCellData(cell, mergedChildCells, cellAddress, opts) {
+    const isMergedChild = mergedChildCells.has(cellAddress);
+    if (!cell || cell.v === undefined || cell.v === null) {
+        return {
+            rawValue: "",
+            value: "",
+            bold: false,
+            italic: false,
+            isMergedChild,
+            hasBorder: false,
+        };
+    }
+    // --- Extract style-independent fields up front ---
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const style = cell.s;
+    // Hyperlinks
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const links = cell.l;
+    let hyperlink;
+    if (links?.Target) {
+        hyperlink = links.Target;
+    }
+    // Issue 4: =HYPERLINK("url", ...) formula — cell.l is absent for formula-based links
+    if (!hyperlink && cell.f) {
+        const match = cell.f.match(/^HYPERLINK\s*\(\s*"([^"]+)"/i);
+        if (match)
+            hyperlink = match[1];
+    }
+    // Border detection
+    let hasBorder = false;
+    if (style?.border) {
+        const b = style.border;
+        hasBorder = !!(b.top?.style || b.bottom?.style || b.left?.style || b.right?.style);
+    }
+    // Alignment
+    let alignment;
+    if (style?.alignment?.horizontal) {
+        const h = style.alignment.horizontal;
+        if (h === "center" || h === "right")
+            alignment = h;
+        else
+            alignment = "left";
+    }
+    // --- Inline rich text: parse cell.r XML (ADR-0019) ---
+    if (opts.richText && cell.r) {
+        const runs = parseRichTextRuns(String(cell.r));
+        if (runs) {
+            const nl = (s) => s.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+            const rawText = nl(runs.map((r) => r.text).join(""));
+            // Move leading/trailing whitespace outside bold/italic markers so that
+            // CommonMark right-flanking delimiter rules are satisfied:
+            // "**bold** " instead of "**bold **" (trailing space inside breaks rendering).
+            let markdownText = runs
+                .map((r) => {
+                const text = nl(r.text);
+                if (!r.bold && !r.italic)
+                    return text;
+                const lead = /^\s*/.exec(text)[0];
+                const trail = /\s*$/.exec(text)[0];
+                const core = text.slice(lead.length, text.length - trail.length);
+                return core ? lead + applyInlineFormatting(core, r.bold, r.italic) + trail : text;
+            })
+                .join("");
+            if (hyperlink)
+                markdownText = `[${markdownText}](${hyperlink})`;
+            const richTextHtml = runs
+                .map((r) => {
+                let t = escapeHtml(nl(r.text)).replace(/\n/g, "<br>");
+                if (r.bold && r.italic)
+                    t = `<strong><em>${t}</em></strong>`;
+                else if (r.bold)
+                    t = `<strong>${t}</strong>`;
+                else if (r.italic)
+                    t = `<em>${t}</em>`;
+                return t;
+            })
+                .join("");
+            return {
+                rawValue: rawText,
+                value: markdownText,
+                bold: false,
+                italic: false,
+                hyperlink,
+                alignment,
+                isMergedChild,
+                hasBorder,
+                richTextHtml,
+            };
+        }
+    }
+    // --- Fallback: plain value extraction ---
+    let value = "";
+    if (cell.t === "d") {
+        // Date
+        const raw = typeof cell.v === "number" ? cell.v : Number(cell.v);
+        value = formatDate(raw, opts.dateFormat);
+    }
+    else if (cell.t === "n") {
+        // Number: use formatted value if available, otherwise toString
+        value = cell.w ?? String(cell.v);
+    }
+    else if (cell.t === "b") {
+        value = cell.v ? "TRUE" : "FALSE";
+    }
+    else {
+        value = cell.w ?? String(cell.v);
+    }
+    // Normalize newlines within cells (for table rendering, replace with <br>)
+    value = value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    // Cell-level style (bold/italic applied to whole cell)
+    let bold = false;
+    let italic = false;
+    if (opts.richText && style) {
+        bold = !!style.font?.bold;
+        italic = !!style.font?.italic;
+    }
+    const formatted = opts.richText ? applyInlineFormatting(value, bold, italic) : value;
+    const final = hyperlink ? `[${formatted}](${hyperlink})` : formatted;
+    return {
+        rawValue: value,
+        value: final,
+        bold,
+        italic,
+        hyperlink,
+        alignment,
+        isMergedChild,
+        hasBorder,
+    };
+}
+//# sourceMappingURL=cell-formatter.js.map