@bendyline/squisq-formats 1.4.0 → 1.4.1

package/src/__tests__/sharedImages.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Tests for the consolidated ext→MIME map (`shared/images.ts`) and the html
+ * `inferMimeType` wrapper that now delegates to it. This map is the union of
+ * the three previously-drifting copies (docx/pptx importers + html export).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { extToMime } from '../shared/images';
+import { inferMimeType } from '../html/imageUtils';
+
+describe('extToMime', () => {
+  it('is dot-tolerant and case-insensitive', () => {
+    expect(extToMime('png')).toBe('image/png');
+    expect(extToMime('.png')).toBe('image/png');
+    expect(extToMime('.PNG')).toBe('image/png');
+    expect(extToMime('PNG')).toBe('image/png');
+  });
+
+  it('resolves .avif to image/avif (the correct answer where the old maps disagreed)', () => {
+    // html's map had avif→image/avif; the docx/pptx maps omitted it entirely
+    // (would have fallen back to octet-stream). The union picks image/avif.
+    expect(extToMime('avif')).toBe('image/avif');
+    expect(extToMime('.avif')).toBe('image/avif');
+  });
+
+  it('covers the union of all three previous maps', () => {
+    // Raster/vector (all three had most of these)
+    expect(extToMime('jpg')).toBe('image/jpeg');
+    expect(extToMime('jpeg')).toBe('image/jpeg');
+    expect(extToMime('gif')).toBe('image/gif');
+    expect(extToMime('webp')).toBe('image/webp');
+    expect(extToMime('bmp')).toBe('image/bmp');
+    expect(extToMime('svg')).toBe('image/svg+xml');
+    // Only docx/pptx had these
+    expect(extToMime('tiff')).toBe('image/tiff');
+    expect(extToMime('tif')).toBe('image/tiff');
+    expect(extToMime('emf')).toBe('image/emf');
+    expect(extToMime('wmf')).toBe('image/wmf');
+    // Only html had these
+    expect(extToMime('ico')).toBe('image/x-icon');
+    expect(extToMime('mp3')).toBe('audio/mpeg');
+    expect(extToMime('wav')).toBe('audio/wav');
+    expect(extToMime('ogg')).toBe('audio/ogg');
+    expect(extToMime('mp4')).toBe('video/mp4');
+    expect(extToMime('webm')).toBe('video/webm');
+  });
+
+  it('returns application/octet-stream for unknown / empty extensions', () => {
+    expect(extToMime('xyz')).toBe('application/octet-stream');
+    expect(extToMime('')).toBe('application/octet-stream');
+  });
+});
+
+describe('inferMimeType (html wrapper)', () => {
+  it('delegates to extToMime, keying off the filename extension', () => {
+    expect(inferMimeType('images/hero.PNG')).toBe('image/png');
+    expect(inferMimeType('photo.avif')).toBe('image/avif');
+    expect(inferMimeType('clip.webm')).toBe('video/webm');
+    expect(inferMimeType('noextension')).toBe('application/octet-stream');
+  });
+});

package/src/__tests__/xlsxExport.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest';
+import JSZip from 'jszip';
+import { parseMarkdown, type MarkdownDocument } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
+
+import { markdownDocToXlsx, docToXlsx } from '../xlsx/export';
+import { xlsxToMarkdownDoc } from '../xlsx/import';
+
+/** Read the workbook.xml + all worksheet XML out of an exported .xlsx buffer. */
+async function unzip(buffer: ArrayBuffer): Promise<{
+  workbook: string;
+  sheets: string[];
+  paths: string[];
+}> {
+  const zip = await JSZip.loadAsync(buffer);
+  const paths = Object.keys(zip.files).sort();
+  const workbook = (await zip.file('xl/workbook.xml')?.async('string')) ?? '';
+  const sheetPaths = paths.filter((p) => /^xl\/worksheets\/sheet\d+\.xml$/.test(p));
+  const sheets = await Promise.all(sheetPaths.map((p) => zip.file(p)!.async('string')));
+  return { workbook, sheets, paths };
+}
+
+/** Extract sheet names (in order) from a workbook.xml string. */
+function sheetNames(workbook: string): string[] {
+  return [...workbook.matchAll(/<sheet\s+name="([^"]*)"/g)].map((m) => m[1]!);
+}
+
+/** Build a single-heading + single-table document without touching the parser. */
+function docWithHeading(headingText: string): MarkdownDocument {
+  return {
+    type: 'document',
+    children: [
+      { type: 'heading', depth: 1, children: [{ type: 'text', value: headingText }] },
+      {
+        type: 'table',
+        children: [
+          {
+            type: 'tableRow',
+            children: [
+              { type: 'tableCell', isHeader: true, children: [{ type: 'text', value: 'A' }] },
+            ],
+          },
+          {
+            type: 'tableRow',
+            children: [{ type: 'tableCell', children: [{ type: 'text', value: 'x' }] }],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe('markdownDocToXlsx', () => {
+  it('produces a structurally valid package (content types + rels + workbook)', async () => {
+    const md = parseMarkdown('# Data\n\n| A | B |\n| - | - |\n| 1 | 2 |\n');
+    const buffer = await markdownDocToXlsx(md);
+    const { paths } = await unzip(buffer);
+
+    expect(paths).toContain('[Content_Types].xml');
+    expect(paths).toContain('_rels/.rels');
+    expect(paths).toContain('xl/workbook.xml');
+    expect(paths).toContain('xl/_rels/workbook.xml.rels');
+    expect(paths).toContain('xl/worksheets/sheet1.xml');
+    expect(paths).toContain('xl/styles.xml');
+  });
+
+  it('names each sheet from the nearest preceding heading', async () => {
+    const md = parseMarkdown('# Sales\n\n| A |\n| - |\n| x |\n');
+    const { workbook } = await unzip(await markdownDocToXlsx(md));
+    expect(sheetNames(workbook)).toEqual(['Sales']);
+  });
+
+  it('sanitizes invalid Excel characters and caps names at 31 chars', async () => {
+    const { workbook } = await unzip(await markdownDocToXlsx(docWithHeading('a:b/c\\d[e]f?g*h')));
+    expect(sheetNames(workbook)).toEqual(['abcdefgh']);
+
+    const { workbook: wb2 } = await unzip(await markdownDocToXlsx(docWithHeading('X'.repeat(50))));
+    expect(sheetNames(wb2)[0]!.length).toBe(31);
+  });
+
+  it('de-duplicates repeated sheet names (Name, Name2, Name3, …)', async () => {
+    const md = parseMarkdown(
+      '# Report\n\n| A |\n| - |\n| 1 |\n\n# Report\n\n| B |\n| - |\n| 2 |\n\n# Report\n\n| C |\n| - |\n| 3 |\n',
+    );
+    const { workbook } = await unzip(await markdownDocToXlsx(md));
+    expect(sheetNames(workbook)).toEqual(['Report', 'Report2', 'Report3']);
+  });
+
+  it('falls back to Sheet1, Sheet2 when a table has no preceding heading', async () => {
+    const md = parseMarkdown('| A |\n| - |\n| 1 |\n\n| B |\n| - |\n| 2 |\n');
+    const { workbook } = await unzip(await markdownDocToXlsx(md));
+    expect(sheetNames(workbook)).toEqual(['Sheet1', 'Sheet2']);
+  });
+
+  it('emits plain numbers as numeric cells and everything else as inline strings', async () => {
+    const md = parseMarkdown(
+      '# T\n\n| Label | N |\n| - | - |\n| Alpha | 42 |\n| Neg | -3.5 |\n| Mixed | 120 req/s |\n',
+    );
+    const { sheets } = await unzip(await markdownDocToXlsx(md));
+    const xml = sheets[0]!;
+
+    // Numeric cells: <v>…</v> without t="inlineStr"
+    expect(xml).toContain('<v>42</v>');
+    expect(xml).toContain('<v>-3.5</v>');
+    // String cells: inlineStr
+    expect(xml).toContain('t="inlineStr"');
+    expect(xml).toContain('>Alpha<');
+    expect(xml).toContain('>120 req/s<');
+    // "120 req/s" must NOT be numeric
+    expect(xml).not.toContain('<v>120 req/s</v>');
+  });
+
+  it('maps multiple tables to multiple worksheets', async () => {
+    const md = parseMarkdown('# First\n\n| A |\n| - |\n| 1 |\n\n# Second\n\n| B |\n| - |\n| 2 |\n');
+    const { sheets, workbook } = await unzip(await markdownDocToXlsx(md));
+    expect(sheets.length).toBe(2);
+    expect(sheetNames(workbook)).toEqual(['First', 'Second']);
+  });
+
+  it('produces a valid empty file (single sheet) when there are no tables', async () => {
+    const md = parseMarkdown('# Just prose\n\nNo tables here at all.\n');
+    const buffer = await markdownDocToXlsx(md);
+    const { sheets, workbook } = await unzip(buffer);
+    expect(sheets.length).toBe(1);
+    expect(sheetNames(workbook)).toEqual(['Sheet1']);
+
+    // Still round-trips without throwing.
+    const roundTrip = await xlsxToMarkdownDoc(buffer);
+    expect(roundTrip.type).toBe('document');
+  });
+
+  it('honors a custom sheetNamePrefix for auto-named sheets', async () => {
+    const md = parseMarkdown('| A |\n| - |\n| 1 |\n');
+    const { workbook } = await unzip(await markdownDocToXlsx(md, { sheetNamePrefix: 'Tab' }));
+    expect(sheetNames(workbook)).toEqual(['Tab1']);
+  });
+
+  it('survives a full round-trip (cell text preserved through import)', async () => {
+    const md = parseMarkdown(
+      '# Metrics\n\n| Metric | Value |\n| - | - |\n| Throughput | 120 |\n| Errors | 0.2% |\n',
+    );
+    const roundTrip = await xlsxToMarkdownDoc(await markdownDocToXlsx(md));
+    const table = roundTrip.children.find((n) => n.type === 'table');
+    expect(table).toBeDefined();
+
+    const flat = JSON.stringify(roundTrip);
+    for (const cell of ['Metric', 'Value', 'Throughput', '120', 'Errors', '0.2%']) {
+      expect(flat).toContain(cell);
+    }
+  });
+
+  it('docToXlsx converts a Doc via the markdown table model', async () => {
+    const doc = markdownToDoc(parseMarkdown('# Report\n\n| K | V |\n| - | - |\n| Users | 99 |\n'));
+    const buffer = await docToXlsx(doc);
+    const { sheets, workbook } = await unzip(buffer);
+    expect(sheets.length).toBeGreaterThanOrEqual(1);
+    expect(sheetNames(workbook).length).toBeGreaterThanOrEqual(1);
+
+    const roundTrip = await xlsxToMarkdownDoc(buffer);
+    const flat = JSON.stringify(roundTrip);
+    expect(flat).toContain('Users');
+    expect(flat).toContain('99');
+  });
+});

package/src/csv/index.ts

@@ -31,6 +31,12 @@ export interface CsvImportOptions {
 export interface CsvExportOptions {
   /** Field delimiter. Default `,`. */
   delimiter?: string;
+  /**
+   * Zero-based index of the table to export when the document contains more
+   * than one. Default 0 (the first table). An explicitly provided index that
+   * doesn't match a table in the document is an error.
+   */
+  tableIndex?: number;
 }
 
 async function toText(data: ArrayBuffer | Blob | string): Promise<string> {
@@ -152,10 +158,27 @@ function cellText(cell: MarkdownTableCell): string {
   return walk(cell.children);
 }
 
-/** Serialize the first table in a MarkdownDocument to CSV text. */
+/**
+ * Serialize one table in a MarkdownDocument to CSV text.
+ *
+ * By default the first table is exported. Documents with multiple tables can
+ * select another via `options.tableIndex` (zero-based). An explicit
+ * `tableIndex` that is out of range throws; the implicit first-table default
+ * on a table-less document returns an empty string (back-compat).
+ */
 export function markdownDocToCsv(doc: MarkdownDocument, options: CsvExportOptions = {}): string {
   const delimiter = options.delimiter ?? ',';
-  const table = doc.children.find((n) => n.type === 'table') as MarkdownTable | undefined;
+  const tables = doc.children.filter((n): n is MarkdownTable => n.type === 'table');
+  const index = options.tableIndex ?? 0;
+  if (
+    options.tableIndex !== undefined &&
+    (!Number.isInteger(index) || index < 0 || index >= tables.length)
+  ) {
+    throw new Error(
+      `CSV export: tableIndex ${index} is out of range — the document contains ${tables.length} table(s).`,
+    );
+  }
+  const table = tables[index];
   if (!table) return '';
   return table.children
     .map((row) =>

package/src/docx/import.ts

@@ -50,8 +50,9 @@ import type {
 import { openPackage, getPartXml, getPartBinary, getPartRelationships } from '../ooxml/reader.js';
 import type { OoxmlPackage, Relationship } from '../ooxml/types.js';
 import { NS_WML, NS_R } from '../ooxml/namespaces.js';
-import { MemoryContentContainer } from '@bendyline/squisq/storage';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import { buildContainer } from '../shared/container.js';
+import { extToMime } from '../shared/images.js';
 import {
   HEADING_STYLE_MAP,
   QUOTE_STYLE_IDS,
@@ -141,33 +142,15 @@ export async function docxToContainer(
   const ctx = await buildImportContext(pkg, { ...options, extractImages: true });
 
   const documentXml = await getPartXml(pkg, 'word/document.xml');
-  if (!documentXml) {
-    const container = new MemoryContentContainer();
-    await container.writeDocument('');
-    return container;
-  }
+  if (!documentXml) return buildContainer('', []);
 
   const body = getFirstElement(documentXml, 'body');
-  if (!body) {
-    const container = new MemoryContentContainer();
-    await container.writeDocument('');
-    return container;
-  }
+  if (!body) return buildContainer('', []);
 
   const blocks = await convertBody(body, ctx);
   const markdownDoc: MarkdownDocument = { type: 'document', children: blocks };
 
-  const markdown = stringifyMarkdown(markdownDoc);
-
-  // Build container with markdown + images
-  const container = new MemoryContentContainer();
-  await container.writeDocument(markdown);
-
-  for (const [path, { data: imageData, mimeType }] of ctx.extractedImages) {
-    await container.writeFile(path, new Uint8Array(imageData), mimeType);
-  }
-
-  return container;
+  return buildContainer(stringifyMarkdown(markdownDoc), ctx.extractedImages);
 }
 
 // ============================================
@@ -630,7 +613,7 @@ async function extractImage(el: Element, ctx: ImportContext): Promise<MarkdownIm
   // Determine extension and MIME type
   const dot = target.lastIndexOf('.');
   const ext = dot !== -1 ? target.slice(dot).toLowerCase() : '.png';
-  const mimeType = IMAGE_MIME_MAP[ext] ?? 'application/octet-stream';
+  const mimeType = extToMime(ext);
 
   // Generate a unique image path
   ctx.imageCounter++;
@@ -650,20 +633,6 @@ async function extractImage(el: Element, ctx: ImportContext): Promise<MarkdownIm
   };
 }
 
-const IMAGE_MIME_MAP: Record<string, string> = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.bmp': 'image/bmp',
-  '.tiff': 'image/tiff',
-  '.tif': 'image/tiff',
-  '.svg': 'image/svg+xml',
-  '.webp': 'image/webp',
-  '.emf': 'image/emf',
-  '.wmf': 'image/wmf',
-};
-
 /** Recursively find the first descendant element with the given local name. */
 function findDescendant(el: Element, localName: string): Element | null {
   for (const child of Array.from(el.children)) {

package/src/html/imageUtils.ts

@@ -5,31 +5,17 @@
  * and inferring MIME types from filenames.
  */
 
-/** Map of file extensions to MIME types */
-const MIME_MAP: Record<string, string> = {
-  jpg: 'image/jpeg',
-  jpeg: 'image/jpeg',
-  png: 'image/png',
-  gif: 'image/gif',
-  webp: 'image/webp',
-  svg: 'image/svg+xml',
-  ico: 'image/x-icon',
-  bmp: 'image/bmp',
-  avif: 'image/avif',
-  mp3: 'audio/mpeg',
-  wav: 'audio/wav',
-  ogg: 'audio/ogg',
-  mp4: 'video/mp4',
-  webm: 'video/webm',
-};
+import { extToMime } from '../shared/images.js';
 
 /**
  * Infer a MIME type from a filename's extension.
  * Returns 'application/octet-stream' for unknown types.
+ *
+ * Thin wrapper over the shared {@link extToMime} map so html export, docx
+ * import, and pptx import all agree on extension → MIME.
  */
 export function inferMimeType(filename: string): string {
-  const ext = filename.split('.').pop()?.toLowerCase() ?? '';
-  return MIME_MAP[ext] ?? 'application/octet-stream';
+  return extToMime(filename.split('.').pop() ?? '');
 }
 
 /**

package/src/index.ts

@@ -7,12 +7,15 @@
  * Supported formats:
  * - **DOCX** — Microsoft Word (import + export) ✅
  * - **PDF**  — Portable Document Format (import + export) ✅
- * - **PPTX** — Microsoft PowerPoint (export ✅, import ✅)
- * - **XLSX** — Microsoft Excel (import ✅, export planned)
+ * - **PPTX** — Microsoft PowerPoint (import + export ✅; import extracts slide-level embedded images)
+ * - **XLSX** — Microsoft Excel (import ✅, export ✅ tables-only)
  * - **CSV**  — Comma-separated values (import ✅, export ✅)
+ * - **HTML** — import + export (single-file, ZIP, plain, and player-embedding)
+ * - **EPUB** — export ✅
  *
  * All converters run in the browser — no server or native binaries required.
- * The shared `ooxml/` subpath export provides reusable OOXML infrastructure.
+ * The shared `ooxml/` subpath export provides reusable OOXML infrastructure, and the
+ * `registry` subpath exposes a format registry + `convert()` pipeline over all of the above.
  *
  * @example
  * ```ts
@@ -29,11 +32,11 @@
 export { markdownDocToDocx, docToDocx, docxToMarkdownDoc, docxToDoc } from './docx/index.js';
 export type { DocxExportOptions, DocxImportOptions } from './docx/index.js';
 
-// PPTX (export implemented, import stub)
+// PPTX (import + export)
 export { markdownDocToPptx, docToPptx, pptxToMarkdownDoc, pptxToDoc } from './pptx/index.js';
 export type { PptxExportOptions, PptxImportOptions } from './pptx/index.js';
 
-// XLSX (import implemented, export stub)
+// XLSX (import + export; export is tables-only → one worksheet per markdown table)
 export { markdownDocToXlsx, docToXlsx, xlsxToMarkdownDoc, xlsxToDoc } from './xlsx/index.js';
 export type { XlsxExportOptions, XlsxImportOptions } from './xlsx/index.js';
 
@@ -60,3 +63,24 @@ export type { HtmlImportOptions } from './html/index.js';
 // EPUB (export)
 export { markdownDocToEpub, docToEpub } from './epub/index.js';
 export type { EpubExportOptions } from './epub/index.js';
+
+// Format registry + programmatic convert()
+export {
+  convert,
+  createRegistry,
+  defaultRegistry,
+  defaultFormats,
+  ConversionError,
+  BUILTIN_FORMAT_IDS,
+} from './registry/index.js';
+export type {
+  FormatId,
+  ConversionResult,
+  NormalizedInput,
+  ConvertOptions,
+  FormatDefinition,
+  FormatRegistry,
+  ConvertSource,
+  ConversionErrorCode,
+  ConversionErrorOptions,
+} from './registry/index.js';

package/src/ooxml/index.ts

@@ -91,4 +91,7 @@ export {
   REL_SLIDE_LAYOUT,
   REL_SLIDE_MASTER,
   CONTENT_TYPE_XLSX_WORKBOOK,
+  CONTENT_TYPE_XLSX_WORKSHEET,
+  CONTENT_TYPE_XLSX_STYLES,
+  REL_WORKSHEET,
 } from './namespaces.js';

package/src/ooxml/namespaces.ts

@@ -184,3 +184,13 @@ export const REL_SLIDE_MASTER =
 
 export const CONTENT_TYPE_XLSX_WORKBOOK =
   'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml';
+
+export const CONTENT_TYPE_XLSX_WORKSHEET =
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml';
+
+export const CONTENT_TYPE_XLSX_STYLES =
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml';
+
+/** Relationship type: Worksheet */
+export const REL_WORKSHEET =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet';