@bendyline/squisq-formats 2.5.0 → 2.6.0

package/dist/{chunk-AD2WT564.js → chunk-Q77KNJIN.js}

@@ -1,8 +1,19 @@
+import {
+  planDataSidecar,
+  sidecarReferenceDoc
+} from "./chunk-DXYWKZ52.js";
+
 // src/csv/index.ts
 import { markdownToDoc } from "@bendyline/squisq/doc";
+import { stringifyMarkdown } from "@bendyline/squisq/markdown";
+import { MemoryContentContainer } from "@bendyline/squisq/storage";
 var DEFAULT_MAX_CSV_CELLS = 1e5;
 var DEFAULT_MAX_CSV_ROWS = 1e4;
 var DEFAULT_MAX_CSV_FIELD_CHARS = 1024 * 1024;
+var SIDECAR_CSV_LIMITS = Object.freeze({
+  maxCells: 2e7,
+  maxRows: 2e6
+});
 async function toText(data) {
   if (typeof data === "string") return data;
   if (typeof Blob !== "undefined" && data instanceof Blob) return data.text();
@@ -122,6 +133,37 @@ async function csvToMarkdownDoc(data, options = {}) {
 async function csvToDoc(data, options = {}) {
   return markdownToDoc(await csvToMarkdownDoc(data, options));
 }
+async function csvToContainer(data, options = {}) {
+  const plan = planDataSidecar(options.sourceName, "data.csv");
+  const mode = options.sidecar ?? "auto";
+  const text = (await toText(data)).replace(/^\uFEFF/, "");
+  const maxInlineRows = options.maxInlineRows ?? 100;
+  const maxInlineBytes = options.maxInlineBytes ?? 256 * 1024;
+  const originalBytes = typeof data === "string" ? new TextEncoder().encode(data).buffer : data instanceof Blob ? await data.arrayBuffer() : data;
+  let spillNeeded = mode === "always";
+  if (!spillNeeded && mode === "auto") {
+    const hasHeader = options.hasHeader ?? true;
+    const lineCount = (text.match(/\n/g) ?? []).length + (text.endsWith("\n") || !text ? 0 : 1);
+    const dataRows = Math.max(lineCount - (hasHeader ? 1 : 0), 0);
+    spillNeeded = originalBytes.byteLength > maxInlineBytes || dataRows > maxInlineRows;
+  }
+  const markdownDoc = spillNeeded ? sidecarReferenceDoc(plan) : await csvToMarkdownDoc(text, options);
+  const container = new MemoryContentContainer();
+  await container.writeDocument(stringifyMarkdown(markdownDoc), plan.markdownFilename);
+  if (spillNeeded) {
+    await container.writeFile(plan.sidecarPath, originalBytes, "text/csv");
+  }
+  return container;
+}
+function serializeCsvRows(rows, options = {}) {
+  const delimiter = validateDelimiter(options.delimiter ?? ",");
+  const newline = options.newline ?? "\n";
+  const handling = options.formulaHandling ?? "preserve";
+  const body = rows.map(
+    (row) => row.map((cell) => escapeCsvField(neutralizeSpreadsheetFormula(cell, handling), delimiter)).join(delimiter)
+  ).join(newline);
+  return options.trailingNewline === false ? body : `${body}${newline}`;
+}
 function escapeCsvField(value, delimiter) {
   if (value.includes('"') || value.includes(delimiter) || /[\r\n]/.test(value)) {
     return `"${value.replace(/"/g, '""')}"`;
@@ -166,8 +208,11 @@ function markdownDocToCsv(doc, options = {}) {
 }
 
 export {
+  SIDECAR_CSV_LIMITS,
   parseCsv,
   csvToMarkdownDoc,
   csvToDoc,
+  csvToContainer,
+  serializeCsvRows,
   markdownDocToCsv
 };

package/dist/{chunk-5PUIFU5I.js → chunk-VDTGQ4MW.js}

@@ -1,7 +1,7 @@
 import {
   convert,
   defaultRegistry
-} from "./chunk-JTGWQK5V.js";
+} from "./chunk-GRKQTQOF.js";
 import {
   ConversionError
 } from "./chunk-KXOZMWBS.js";

package/dist/{chunk-6RQOV3B3.js → chunk-VPWPEMZJ.js}

@@ -1,6 +1,6 @@
 import {
   extToMime
-} from "./chunk-AONELFLA.js";
+} from "./chunk-B7GEAZBI.js";
 
 // src/html/imageUtils.ts
 function inferMimeType(filename) {

package/dist/{chunk-FIOSE4BO.js → chunk-XJNOZTAY.js}

@@ -5,6 +5,9 @@ import {
   normalizeOoxmlHex,
   sanitizeOfficeHyperlink
 } from "./chunk-A6N6IN3I.js";
+import {
+  extToMime
+} from "./chunk-B7GEAZBI.js";
 import {
   stripHtmlTags
 } from "./chunk-AVOZAKGP.js";
@@ -47,6 +50,9 @@ import {
   requireMainPartPath,
   resolveTarget
 } from "./chunk-S5PCVMKU.js";
+import {
+  renumberFootnotes
+} from "./chunk-BXWNU4T5.js";
 import {
   buildContainer
 } from "./chunk-IIQYS2YH.js";
@@ -56,12 +62,6 @@ import {
   fontAwesomeGlyph,
   obfuscateDocxFont
 } from "./chunk-USU6HTKB.js";
-import {
-  extToMime
-} from "./chunk-AONELFLA.js";
-import {
-  renumberFootnotes
-} from "./chunk-BXWNU4T5.js";
 
 // src/docx/export.ts
 import { resolveFontFamily } from "@bendyline/squisq/schemas";

package/dist/csv/index.d.ts

@@ -1,5 +1,6 @@
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
 import { Doc } from '@bendyline/squisq/schemas';
+import { ContentContainer } from '@bendyline/squisq/storage';
 
 /**
  * @bendyline/squisq-formats CSV Module
@@ -28,6 +29,27 @@ interface CsvImportOptions {
     maxFieldChars?: number;
     /** Cancel during parsing checkpoints. */
     signal?: AbortSignal;
+    /**
+     * Sidecar spill mode — only honored by `csvToContainer`, which can actually
+     * write the sidecar file. `'auto'` (default) spills past the inline
+     * thresholds; `'always'` always sidecars (the CSV-open-as-document mode:
+     * opening a data file means the FILE is the content); `'never'` keeps the
+     * inline table (`csvToMarkdownDoc`'s only behavior).
+     */
+    sidecar?: 'auto' | 'always' | 'never';
+    /** Max data rows kept inline before spilling (container import). Default 100. */
+    maxInlineRows?: number;
+    /** Max source bytes kept inline before spilling (container import). Default 256 KiB. */
+    maxInlineBytes?: number;
+}
+/** Options for {@link csvToContainer}. */
+interface CsvContainerOptions extends CsvImportOptions {
+    /**
+     * Source file name (e.g. `'Q3 Transactions.csv'`) — names the document
+     * (`q3-transactions.md`) and the sidecar path
+     * (`q3-transactions_files/data/Q3 Transactions.csv`). Default `'data.csv'`.
+     */
+    sourceName?: string;
 }
 interface CsvExportOptions {
     /** Field delimiter. Default `,`. */
@@ -56,12 +78,56 @@ interface CsvSafetyLimits {
     maxFieldChars?: number;
     signal?: AbortSignal;
 }
+/**
+ * Generous caps for the DATA-SIDECAR tier — the grid ingest and the
+ * full-body sidecar readers. The conservative `parseCsv` defaults protect
+ * the INLINE pipeline (a 100k-cell markdown table can't reparse anyway),
+ * but sidecar data exists precisely because it is big: it renders windowed
+ * and virtualized, so the ceiling here is the columnar store's ~20M-cell
+ * design wall, not the editor debounce. Every sidecar-path caller passes
+ * these; without them a 20 MB upload silently dead-ends at the parser cap.
+ */
+declare const SIDECAR_CSV_LIMITS: CsvSafetyLimits;
 /** Parse CSV text into a grid of string cells (RFC 4180: quotes, escaped quotes). */
 declare function parseCsv(text: string, delimiter?: string, limits?: CsvSafetyLimits): string[][];
 /** Convert CSV to a MarkdownDocument containing a single table. */
 declare function csvToMarkdownDoc(data: ArrayBuffer | Blob | string, options?: CsvImportOptions): Promise<MarkdownDocument>;
 /** Convert CSV to a squisq Doc. */
 declare function csvToDoc(data: ArrayBuffer | Blob | string, options?: CsvImportOptions): Promise<Doc>;
+/**
+ * Import a CSV into a ContentContainer: the markdown document plus, when the
+ * data crosses the inline thresholds (or `sidecar: 'always'`), the ORIGINAL
+ * bytes as a `<docbasename>_files/data/<name>` sidecar referenced via
+ * `{[dataTable src=…]}` with a body link.
+ *
+ * Below the thresholds the markdown is byte-identical to `csvToMarkdownDoc`'s
+ * output and no sidecar is written.
+ */
+declare function csvToContainer(data: ArrayBuffer | Blob | string, options?: CsvContainerOptions): Promise<ContentContainer>;
+/** Options for {@link serializeCsvRows}. */
+interface SerializeCsvRowsOptions {
+    /** Field delimiter. Default `,`. */
+    delimiter?: string;
+    /** Line terminator. Default `\n`. */
+    newline?: '\r\n' | '\n';
+    /** Emit a terminating newline after the last row. Default true. */
+    trailingNewline?: boolean;
+    /**
+     * Formula neutralization. Default **`'preserve'`** — the OPPOSITE of the
+     * export default, deliberately: this API re-serializes EXISTING data (the
+     * grid's save path), and `SPREADSHEET_FORMULA_PREFIX` matches a leading
+     * `-`/`+`, so blanket escaping would corrupt every negative number in a
+     * re-saved file. Callers neutralize specific cells themselves (the grid
+     * escapes only journal-edited, non-numeric cells).
+     */
+    formulaHandling?: 'escape' | 'preserve';
+}
+/**
+ * Serialize a plain row matrix to CSV text — the write half of `parseCsv`,
+ * used by the grid's sidecar save. RFC-4180 quoting via the same escaper
+ * the exporter uses.
+ */
+declare function serializeCsvRows(rows: readonly (readonly string[])[], options?: SerializeCsvRowsOptions): string;
 /**
  * Serialize one table in a MarkdownDocument to CSV text.
  *
@@ -72,4 +138,4 @@ declare function csvToDoc(data: ArrayBuffer | Blob | string, options?: CsvImport
  */
 declare function markdownDocToCsv(doc: MarkdownDocument, options?: CsvExportOptions): string;
 
-export { type CsvExportOptions, type CsvImportOptions, type CsvSafetyLimits, csvToDoc, csvToMarkdownDoc, markdownDocToCsv, parseCsv };
+export { type CsvContainerOptions, type CsvExportOptions, type CsvImportOptions, type CsvSafetyLimits, SIDECAR_CSV_LIMITS, type SerializeCsvRowsOptions, csvToContainer, csvToDoc, csvToMarkdownDoc, markdownDocToCsv, parseCsv, serializeCsvRows };

package/dist/csv/index.js

@@ -1,12 +1,19 @@
 import {
+  SIDECAR_CSV_LIMITS,
+  csvToContainer,
   csvToDoc,
   csvToMarkdownDoc,
   markdownDocToCsv,
-  parseCsv
-} from "../chunk-AD2WT564.js";
+  parseCsv,
+  serializeCsvRows
+} from "../chunk-Q77KNJIN.js";
+import "../chunk-DXYWKZ52.js";
 export {
+  SIDECAR_CSV_LIMITS,
+  csvToContainer,
   csvToDoc,
   csvToMarkdownDoc,
   markdownDocToCsv,
-  parseCsv
+  parseCsv,
+  serializeCsvRows
 };

package/dist/data/index.d.ts

@@ -0,0 +1,78 @@
+import { DataSourceReader } from '@bendyline/squisq/doc';
+import { ContentContainer } from '@bendyline/squisq/storage';
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+
+/**
+ * Sidecar data readers — the format implementations behind core's
+ * `DataSourceReader` seam (`resolveDataReferences`).
+ *
+ * Core stays parser-free; these readers decode the actual bytes of a
+ * `{[dataTable src=…]}` sidecar into the bounded `DataSourceTable` window the
+ * projections render. CSV/TSV wrap the RFC-4180 parser, XLSX reuses the
+ * import pipeline's typed region detection (`xlsxToTables`), and parquet
+ * loads hyparquet lazily so its bytes never reach consumers that don't
+ * reference parquet files.
+ */
+
+declare const csvDataReader: DataSourceReader;
+declare const xlsxDataReader: DataSourceReader;
+declare const parquetDataReader: DataSourceReader;
+/** The full reader set for `resolveDataReferences({ readers })`. */
+declare function defaultDataReaders(): DataSourceReader[];
+
+/**
+ * Materialize `{[dataTable src=…]}` sidecar references into inline markdown
+ * tables — the FULL data, not the bounded preview. Used by exports that
+ * embed values (XLSX: a src-referenced block would otherwise contribute no
+ * table and silently vanish from the workbook).
+ *
+ * Never throws: a missing container, unreadable file, or absent reader
+ * degrades to an `onWarning` message and the reference block is left as-is
+ * (its body link simply doesn't survive a tables-only export).
+ */
+
+/**
+ * Returns a copy of `markdownDoc` where every heading annotated with a
+ * resolvable data `src` is followed by the full source table. The input
+ * document is returned unchanged (same object) when nothing materialized.
+ */
+declare function materializeDataReferences(markdownDoc: MarkdownDocument, container: ContentContainer | null | undefined, onWarning?: (message: string) => void): Promise<MarkdownDocument>;
+
+/**
+ * Sidecar naming shared by the spill-capable importers (`xlsxToContainer`,
+ * `csvToContainer`): one place decides the document filename and the
+ * `<docbasename>_files/data/<file>` path a spilled reference points at, so
+ * the markdown `src` param and the container write can never disagree.
+ */
+
+/** Strip any path components from a user-supplied source file name. */
+declare function sanitizeSourceFileName(name: string | undefined, fallback: string): string;
+/**
+ * Doc basename slug for a source file name — the outside-in `slugStem`
+ * rules (NFKD, strip marks, lowercase, non-alphanumeric → `-`), applied to
+ * the name without its extension. `'Q3 Report.xlsx'` → `'q3-report'`.
+ */
+declare function docSlugForFileName(fileName: string): string;
+/** Where a spill-capable import writes its document and sidecar. */
+interface DataSidecarPlan {
+    /** Doc basename slug, e.g. `'q3-report'`. */
+    slug: string;
+    /** Document filename inside the container, e.g. `'q3-report.md'`. */
+    markdownFilename: string;
+    /** Sidecar file name (source name, path components stripped). */
+    fileName: string;
+    /** Container path the `src` param references, e.g. `'q3-report_files/data/Q3 Report.xlsx'`. */
+    sidecarPath: string;
+}
+declare function planDataSidecar(sourceName: string | undefined, fallbackName: string): DataSidecarPlan;
+/**
+ * The reference block a fully-sidecarred data file becomes: an annotated
+ * heading (`# <title> {[dataTable src=…]}`) plus the graceful-degradation
+ * body link. Built as an AST so annotation quoting and link escaping go
+ * through the one stringifier that knows the rules.
+ */
+declare function sidecarReferenceDoc(plan: DataSidecarPlan): MarkdownDocument;
+/** {@link sidecarReferenceDoc} as serialized markdown source. */
+declare function sidecarReferenceMarkdown(plan: DataSidecarPlan): string;
+
+export { type DataSidecarPlan, csvDataReader, defaultDataReaders, docSlugForFileName, materializeDataReferences, parquetDataReader, planDataSidecar, sanitizeSourceFileName, sidecarReferenceDoc, sidecarReferenceMarkdown, xlsxDataReader };

package/dist/data/index.js

@@ -0,0 +1,30 @@
+import {
+  csvDataReader,
+  defaultDataReaders,
+  materializeDataReferences,
+  parquetDataReader,
+  xlsxDataReader
+} from "../chunk-FLR2ARKC.js";
+import "../chunk-OBADJV7C.js";
+import "../chunk-Q77KNJIN.js";
+import {
+  docSlugForFileName,
+  planDataSidecar,
+  sanitizeSourceFileName,
+  sidecarReferenceDoc,
+  sidecarReferenceMarkdown
+} from "../chunk-DXYWKZ52.js";
+import "../chunk-S5PCVMKU.js";
+import "../chunk-7AWFHP5U.js";
+export {
+  csvDataReader,
+  defaultDataReaders,
+  docSlugForFileName,
+  materializeDataReferences,
+  parquetDataReader,
+  planDataSidecar,
+  sanitizeSourceFileName,
+  sidecarReferenceDoc,
+  sidecarReferenceMarkdown,
+  xlsxDataReader
+};

package/dist/docx/index.js

@@ -4,17 +4,17 @@ import {
   docxToDoc,
   docxToMarkdownDoc,
   markdownDocToDocx
-} from "../chunk-FIOSE4BO.js";
+} from "../chunk-XJNOZTAY.js";
 import "../chunk-A6N6IN3I.js";
+import "../chunk-B7GEAZBI.js";
 import "../chunk-AVOZAKGP.js";
 import "../chunk-ILCJ3WFD.js";
 import "../chunk-JU2RHXUB.js";
 import "../chunk-S5PCVMKU.js";
 import "../chunk-7AWFHP5U.js";
+import "../chunk-BXWNU4T5.js";
 import "../chunk-IIQYS2YH.js";
 import "../chunk-USU6HTKB.js";
-import "../chunk-AONELFLA.js";
-import "../chunk-BXWNU4T5.js";
 export {
   docToDocx,
   docxToContainer,

package/dist/epub/index.js

@@ -1,13 +1,13 @@
 import {
   docToEpub,
   markdownDocToEpub
-} from "../chunk-2LT3JL7U.js";
+} from "../chunk-3ITGQRL5.js";
+import "../chunk-VPWPEMZJ.js";
+import "../chunk-B7GEAZBI.js";
 import "../chunk-AVOZAKGP.js";
 import "../chunk-JU2RHXUB.js";
-import "../chunk-USU6HTKB.js";
-import "../chunk-6RQOV3B3.js";
-import "../chunk-AONELFLA.js";
 import "../chunk-BXWNU4T5.js";
+import "../chunk-USU6HTKB.js";
 export {
   docToEpub,
   markdownDocToEpub