@bendyline/squisq-formats 1.3.1 → 1.4.1

package/src/xlsx/export.ts

@@ -0,0 +1,253 @@
+/**
+ * XLSX export — MarkdownDocument → SpreadsheetML (.xlsx).
+ *
+ * Tables-only fidelity (honestly documented): every `table` node in the
+ * markdown AST becomes one worksheet; all other content (headings, prose,
+ * lists, images, …) is dropped except that the nearest preceding heading is
+ * used to name the sheet. This mirrors the import side (`xlsxToMarkdownDoc`),
+ * which turns each worksheet grid back into a markdown table.
+ *
+ * Cells are emitted as inline strings (`t="inlineStr"`) so no sharedStrings
+ * part is needed, except values matching a plain-number pattern, which are
+ * emitted as numeric cells. The package is assembled with the shared ooxml/
+ * writer (auto-generates `[Content_Types].xml` + `_rels`), so only the
+ * SpreadsheetML-specific parts (workbook, worksheets, styles) are written here.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from '@bendyline/squisq/markdown';
+ * import { markdownDocToXlsx } from '@bendyline/squisq-formats/xlsx';
+ *
+ * const md = parseMarkdown('# Metrics\n\n| A | B |\n| - | - |\n| 1 | 2 |');
+ * const buffer = await markdownDocToXlsx(md);
+ * ```
+ */
+
+import type { Doc } from '@bendyline/squisq/schemas';
+import { docToMarkdown } from '@bendyline/squisq/doc';
+import type {
+  MarkdownDocument,
+  MarkdownBlockNode,
+  MarkdownTable,
+  MarkdownTableRow,
+} from '@bendyline/squisq/markdown';
+
+import { createPackage } from '../ooxml/writer.js';
+import { xmlDeclaration, escapeXml } from '../ooxml/xmlUtils.js';
+import { extractPlainText } from '../shared/text.js';
+import {
+  NS_SML,
+  NS_R,
+  REL_OFFICE_DOCUMENT,
+  REL_STYLES,
+  REL_WORKSHEET,
+  CONTENT_TYPE_XLSX_WORKBOOK,
+  CONTENT_TYPE_XLSX_WORKSHEET,
+  CONTENT_TYPE_XLSX_STYLES,
+} from '../ooxml/namespaces.js';
+
+/**
+ * Options for XLSX export.
+ */
+export interface XlsxExportOptions {
+  /** Workbook title (written to core properties). */
+  title?: string;
+  /** Workbook author (written to core properties). */
+  author?: string;
+  /** Prefix used for auto-named sheets when no heading precedes a table. Default: "Sheet". */
+  sheetNamePrefix?: string;
+}
+
+interface SheetData {
+  name: string;
+  /** Grid of cell text: first row is the header. */
+  grid: string[][];
+}
+
+/** A plain integer or decimal (optionally negative) — emitted as a numeric cell. */
+const NUMERIC_RE = /^-?\d+(\.\d+)?$/;
+
+/**
+ * Sanitize a candidate name into a valid, unique Excel sheet name.
+ * Strips characters Excel forbids (`[]:*?/\`), caps at 31 chars, and
+ * de-duplicates against already-used names by appending 2, 3, …
+ */
+function sanitizeSheetName(raw: string, used: Set<string>, fallback: string): string {
+  let name = raw.replace(/[[\]:*?/\\]/g, '').trim();
+  if (name.length === 0) name = fallback;
+  name = name.slice(0, 31);
+
+  if (!used.has(name)) {
+    used.add(name);
+    return name;
+  }
+  // Dedupe: "Name", "Name2", "Name3", … keeping within the 31-char cap.
+  for (let n = 2; ; n++) {
+    const suffix = String(n);
+    const base = name.slice(0, 31 - suffix.length);
+    const candidate = `${base}${suffix}`;
+    if (!used.has(candidate)) {
+      used.add(candidate);
+      return candidate;
+    }
+  }
+}
+
+/** Convert a table node into a grid of plain-text cells. */
+function tableToGrid(table: MarkdownTable): string[][] {
+  return table.children.map((row: MarkdownTableRow) =>
+    row.children.map((cell) => extractPlainText(cell.children)),
+  );
+}
+
+/** Walk the document, pairing each table with the nearest preceding heading. */
+function collectSheets(doc: MarkdownDocument, prefix: string): SheetData[] {
+  const used = new Set<string>();
+  const sheets: SheetData[] = [];
+  let pendingHeading: string | null = null;
+
+  const visit = (nodes: MarkdownBlockNode[]): void => {
+    for (const node of nodes) {
+      if (node.type === 'heading') {
+        pendingHeading = extractPlainText(node.children);
+      } else if (node.type === 'table') {
+        const fallback = `${prefix}${sheets.length + 1}`;
+        const name = sanitizeSheetName(pendingHeading ?? fallback, used, fallback);
+        sheets.push({ name, grid: tableToGrid(node) });
+        pendingHeading = null;
+      }
+    }
+  };
+
+  visit(doc.children);
+  return sheets;
+}
+
+/** Column letters for a zero-based index (0 → "A", 26 → "AA"). */
+function columnLetter(index: number): string {
+  let n = index + 1;
+  let letters = '';
+  while (n > 0) {
+    const rem = (n - 1) % 26;
+    letters = String.fromCharCode(65 + rem) + letters;
+    n = Math.floor((n - 1) / 26);
+  }
+  return letters;
+}
+
+function cellXml(value: string, ref: string): string {
+  if (NUMERIC_RE.test(value)) {
+    return `<c r="${ref}"><v>${escapeXml(value)}</v></c>`;
+  }
+  return `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${escapeXml(value)}</t></is></c>`;
+}
+
+function worksheetXml(grid: string[][]): string {
+  const rows: string[] = [];
+  for (let r = 0; r < grid.length; r++) {
+    const cells = grid[r]!;
+    const cellsXml = cells.map((value, c) => cellXml(value, `${columnLetter(c)}${r + 1}`)).join('');
+    rows.push(`<row r="${r + 1}">${cellsXml}</row>`);
+  }
+  return (
+    `${xmlDeclaration()}\n` +
+    `<worksheet xmlns="${NS_SML}" xmlns:r="${NS_R}">` +
+    `<sheetData>${rows.join('')}</sheetData>` +
+    `</worksheet>`
+  );
+}
+
+function workbookXml(sheets: SheetData[]): string {
+  const sheetEls = sheets
+    .map(
+      (sheet, i) =>
+        `<sheet name="${escapeXml(sheet.name)}" sheetId="${i + 1}" r:id="rId${i + 1}"/>`,
+    )
+    .join('');
+  return (
+    `${xmlDeclaration()}\n` +
+    `<workbook xmlns="${NS_SML}" xmlns:r="${NS_R}">` +
+    `<sheets>${sheetEls}</sheets>` +
+    `</workbook>`
+  );
+}
+
+/** Minimal but valid styles part (Excel expects the referenced collections to exist). */
+function stylesXml(): string {
+  return (
+    `${xmlDeclaration()}\n` +
+    `<styleSheet xmlns="${NS_SML}">` +
+    `<fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>` +
+    `<fills count="1"><fill><patternFill patternType="none"/></fill></fills>` +
+    `<borders count="1"><border/></borders>` +
+    `<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>` +
+    `<cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs>` +
+    `</styleSheet>`
+  );
+}
+
+/**
+ * Convert a MarkdownDocument to a .xlsx file (tables-only fidelity).
+ *
+ * Each markdown `table` becomes one worksheet; a document with no tables
+ * yields a single empty sheet (a valid, openable file — never throws).
+ */
+export async function markdownDocToXlsx(
+  doc: MarkdownDocument,
+  options: XlsxExportOptions = {},
+): Promise<ArrayBuffer> {
+  const prefix = options.sheetNamePrefix ?? 'Sheet';
+  let sheets = collectSheets(doc, prefix);
+
+  // Zero tables → one empty sheet so the file is still valid.
+  if (sheets.length === 0) {
+    sheets = [{ name: `${prefix}1`, grid: [] }];
+  }
+
+  const pkg = createPackage();
+
+  // Worksheets + workbook→worksheet relationships.
+  sheets.forEach((sheet, i) => {
+    const sheetPath = `xl/worksheets/sheet${i + 1}.xml`;
+    pkg.addPart(sheetPath, worksheetXml(sheet.grid), CONTENT_TYPE_XLSX_WORKSHEET);
+    pkg.addRelationship('xl/workbook.xml', {
+      id: `rId${i + 1}`,
+      type: REL_WORKSHEET,
+      target: `worksheets/sheet${i + 1}.xml`,
+    });
+  });
+
+  // Styles part (referenced after the sheet relationships).
+  pkg.addPart('xl/styles.xml', stylesXml(), CONTENT_TYPE_XLSX_STYLES);
+  pkg.addRelationship('xl/workbook.xml', {
+    id: `rId${sheets.length + 1}`,
+    type: REL_STYLES,
+    target: 'styles.xml',
+  });
+
+  // Workbook + root relationship.
+  pkg.addPart('xl/workbook.xml', workbookXml(sheets), CONTENT_TYPE_XLSX_WORKBOOK);
+  pkg.addRelationship('', {
+    id: 'rId1',
+    type: REL_OFFICE_DOCUMENT,
+    target: 'xl/workbook.xml',
+  });
+
+  if (options.title || options.author) {
+    pkg.setCoreProperties({
+      title: options.title,
+      creator: options.author,
+      created: new Date().toISOString(),
+      modified: new Date().toISOString(),
+    });
+  }
+
+  return pkg.toArrayBuffer();
+}
+
+/**
+ * Convert a squisq Doc to a .xlsx file (via the markdown table model).
+ */
+export async function docToXlsx(doc: Doc, options?: XlsxExportOptions): Promise<ArrayBuffer> {
+  return markdownDocToXlsx(docToMarkdown(doc), options);
+}

package/src/xlsx/import.ts

@@ -0,0 +1,159 @@
+/**
+ * XLSX import — SpreadsheetML (.xlsx) → MarkdownDocument.
+ *
+ * Reuses the shared ooxml/ reader (zip + DOMParser). Reads the workbook's
+ * sheet list, resolves each sheet part via relationships, pulls shared strings,
+ * and turns each worksheet's cell grid into a markdown table (first row treated
+ * as the header). By default every sheet is imported, each preceded by an H1 of
+ * the sheet name; pass `options.sheet` (index or name) to import just one.
+ */
+
+import type {
+  MarkdownBlockNode,
+  MarkdownDocument,
+  MarkdownTable,
+  MarkdownTableCell,
+  MarkdownTableRow,
+} from '@bendyline/squisq/markdown';
+import { getPartXml, getPartRelationships, openPackage } from '../ooxml/reader.js';
+import type { OoxmlPackage } from '../ooxml/types.js';
+import { NS_R, NS_SML } from '../ooxml/namespaces.js';
+
+export interface XlsxImportOptions {
+  /** Which sheet to import (0-based index or sheet name). Default: all sheets. */
+  sheet?: number | string;
+}
+
+interface SheetRef {
+  name: string;
+  path: string;
+}
+
+function attrNS(el: Element, ns: string, local: string, fallback: string): string | null {
+  return el.getAttributeNS(ns, local) ?? el.getAttribute(fallback);
+}
+
+/** Resolve a relationship target (relative to its part's dir) to a zip path. */
+function resolveTarget(baseDir: string, target: string): string {
+  if (target.startsWith('/')) return target.replace(/^\//, '');
+  const stack = baseDir ? baseDir.split('/') : [];
+  for (const seg of target.split('/')) {
+    if (seg === '..') stack.pop();
+    else if (seg !== '.') stack.push(seg);
+  }
+  return stack.join('/');
+}
+
+async function readSheets(pkg: OoxmlPackage): Promise<SheetRef[]> {
+  const wb = await getPartXml(pkg, 'xl/workbook.xml');
+  if (!wb) return [];
+  const rels = await getPartRelationships(pkg, 'xl/workbook.xml');
+  const relById = new Map(rels.map((r) => [r.id, r.target]));
+  const out: SheetRef[] = [];
+  const sheetEls = wb.getElementsByTagNameNS(NS_SML, 'sheet');
+  for (let i = 0; i < sheetEls.length; i++) {
+    const el = sheetEls[i]!;
+    const name = el.getAttribute('name') ?? `Sheet${i + 1}`;
+    const rid = attrNS(el, NS_R, 'id', 'r:id');
+    const target = rid ? relById.get(rid) : undefined;
+    if (target) out.push({ name, path: resolveTarget('xl', target) });
+  }
+  return out;
+}
+
+async function readSharedStrings(pkg: OoxmlPackage): Promise<string[]> {
+  const doc = await getPartXml(pkg, 'xl/sharedStrings.xml');
+  if (!doc) return [];
+  const siEls = doc.getElementsByTagNameNS(NS_SML, 'si');
+  const out: string[] = [];
+  for (let i = 0; i < siEls.length; i++) out.push(siEls[i]!.textContent ?? '');
+  return out;
+}
+
+/** Column letters of a cell ref ("B7" → 1, "AA1" → 26). */
+function colIndex(ref: string): number {
+  const m = /^([A-Za-z]+)/.exec(ref);
+  if (!m) return 0;
+  let n = 0;
+  for (const ch of m[1]!.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64);
+  return n - 1;
+}
+
+function cellText(cell: Element, shared: string[]): string {
+  const t = cell.getAttribute('t');
+  if (t === 'inlineStr') {
+    const is = cell.getElementsByTagNameNS(NS_SML, 't');
+    return is.length ? (is[0]!.textContent ?? '') : '';
+  }
+  const vEls = cell.getElementsByTagNameNS(NS_SML, 'v');
+  const v = vEls.length ? (vEls[0]!.textContent ?? '') : '';
+  if (t === 's') return shared[Number.parseInt(v, 10)] ?? '';
+  if (t === 'b') return v === '1' ? 'TRUE' : 'FALSE';
+  return v;
+}
+
+async function sheetToGrid(pkg: OoxmlPackage, path: string, shared: string[]): Promise<string[][]> {
+  const doc = await getPartXml(pkg, path);
+  if (!doc) return [];
+  const rowEls = doc.getElementsByTagNameNS(NS_SML, 'row');
+  const grid: string[][] = [];
+  for (let r = 0; r < rowEls.length; r++) {
+    const cells = rowEls[r]!.getElementsByTagNameNS(NS_SML, 'c');
+    const rowArr: string[] = [];
+    for (let c = 0; c < cells.length; c++) {
+      const cell = cells[c]!;
+      const ref = cell.getAttribute('r');
+      const idx = ref ? colIndex(ref) : rowArr.length;
+      while (rowArr.length < idx) rowArr.push('');
+      rowArr[idx] = cellText(cell, shared);
+    }
+    grid.push(rowArr);
+  }
+  return grid;
+}
+
+function gridToTable(grid: string[][]): MarkdownTable {
+  const maxCols = grid.reduce((m, r) => Math.max(m, r.length), 1);
+  const rows: MarkdownTableRow[] = grid.map((cells, rowIdx) => {
+    const children: MarkdownTableCell[] = [];
+    for (let c = 0; c < maxCols; c++) {
+      const value = cells[c] ?? '';
+      children.push({
+        type: 'tableCell',
+        ...(rowIdx === 0 ? { isHeader: true } : {}),
+        children: value ? [{ type: 'text', value }] : [],
+      });
+    }
+    return { type: 'tableRow', children };
+  });
+  return { type: 'table', children: rows };
+}
+
+export async function xlsxToMarkdownDoc(
+  data: ArrayBuffer | Blob,
+  options: XlsxImportOptions = {},
+): Promise<MarkdownDocument> {
+  const pkg = await openPackage(data);
+  const sheets = await readSheets(pkg);
+  const shared = await readSharedStrings(pkg);
+
+  let selected = sheets;
+  if (options.sheet !== undefined) {
+    const picked =
+      typeof options.sheet === 'number'
+        ? sheets[options.sheet]
+        : sheets.find((s) => s.name === options.sheet);
+    selected = picked ? [picked] : [];
+  }
+
+  const children: MarkdownBlockNode[] = [];
+  const single = selected.length === 1 && options.sheet !== undefined;
+  for (const sheet of selected) {
+    const grid = await sheetToGrid(pkg, sheet.path, shared);
+    if (!single) {
+      children.push({ type: 'heading', depth: 1, children: [{ type: 'text', value: sheet.name }] });
+    }
+    if (grid.length > 0) children.push(gridToTable(grid));
+  }
+  return { type: 'document', children };
+}

package/src/xlsx/index.ts

@@ -1,78 +1,35 @@
 /**
- * @bendyline/squisq-formats XLSX Module (Stub)
+ * @bendyline/squisq-formats XLSX Module
  *
- * Placeholder for Excel .xlsx import/export support.
- * Will use SpreadsheetML (`<spreadsheet>`, `<worksheet>`, `<sheetData>`)
- * via the shared ooxml/ infrastructure.
+ * Excel .xlsx support via SpreadsheetML and the shared ooxml/ infrastructure.
+ * Both directions are implemented: import (`xlsxToMarkdownDoc` / `xlsxToDoc`)
+ * turns each worksheet grid into a markdown table; export (`markdownDocToXlsx`
+ * / `docToXlsx`) turns each markdown table into a worksheet. Export is
+ * tables-only fidelity — non-table content is dropped (headings only survive
+ * as sheet names). See export.ts for details.
  *
  * @example
  * ```ts
- * import { markdownDocToXlsx } from '@bendyline/squisq-formats/xlsx';
+ * import { xlsxToMarkdownDoc, markdownDocToXlsx } from '@bendyline/squisq-formats/xlsx';
  * ```
  */
 
-import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
 import type { Doc } from '@bendyline/squisq/schemas';
+import { type XlsxImportOptions, xlsxToMarkdownDoc } from './import.js';
 
-/**
- * Options for XLSX export (placeholder).
- */
-export interface XlsxExportOptions {
-  /** Workbook title */
-  title?: string;
-  /** Workbook author */
-  author?: string;
-}
-
-/**
- * Options for XLSX import (placeholder).
- */
-export interface XlsxImportOptions {
-  /** Which sheet to import (0-based index or name). Default: 0 */
-  sheet?: number | string;
-}
-
-/**
- * Convert a MarkdownDocument to a .xlsx Blob.
- *
- * @throws Error — XLSX support is not yet implemented
- */
-export async function markdownDocToXlsx(
-  _doc: MarkdownDocument,
-  _options?: XlsxExportOptions,
-): Promise<Blob> {
-  throw new Error('XLSX export is not yet implemented');
-}
+export type { XlsxImportOptions } from './import.js';
+export { xlsxToMarkdownDoc } from './import.js';
 
-/**
- * Convert a squisq Doc to a .xlsx Blob.
- *
- * @throws Error — XLSX support is not yet implemented
- */
-export async function docToXlsx(_doc: Doc, _options?: XlsxExportOptions): Promise<Blob> {
-  throw new Error('XLSX export is not yet implemented');
-}
+export type { XlsxExportOptions } from './export.js';
+export { markdownDocToXlsx, docToXlsx } from './export.js';
 
 /**
- * Convert a .xlsx file to a MarkdownDocument.
- *
- * @throws Error — XLSX support is not yet implemented
- */
-export async function xlsxToMarkdownDoc(
-  _data: ArrayBuffer | Blob,
-  _options?: XlsxImportOptions,
-): Promise<MarkdownDocument> {
-  throw new Error('XLSX import is not yet implemented');
-}
-
-/**
- * Convert a .xlsx file to a squisq Doc.
- *
- * @throws Error — XLSX support is not yet implemented
+ * Convert a .xlsx file to a squisq Doc (via the markdown table model).
  */
 export async function xlsxToDoc(
-  _data: ArrayBuffer | Blob,
-  _options?: XlsxImportOptions,
+  data: ArrayBuffer | Blob,
+  options?: XlsxImportOptions,
 ): Promise<Doc> {
-  throw new Error('XLSX import is not yet implemented');
+  return markdownToDoc(await xlsxToMarkdownDoc(data, options));
 }