reamkit 1.30.0 → 1.32.0

package/README.md

@@ -27,10 +27,12 @@ Runtime dependencies are minimal: `fflate` (ZIP/Deflate) and `fast-xml-parser`.
 ## Usage
 
 Parse once into the format-neutral interlayer, convert to any target. The
-format (docx/xlsx) is sniffed from the bytes; no fonts to wire up — an open
+format is sniffed from the bytes; no fonts to wire up — an open
 metric-compatible substitute font (Arimo for sans, Tinos for serif, Cousine for
 monospace, plus Carlito/Caladea for Calibri/Cambria — the same families LibreOffice
-substitutes) is fetched automatically based on the document's referenced fonts:
+substitutes) is fetched automatically based on the document's referenced fonts,
+with a Noto face for the Japanese, Korean, Chinese, Arabic, Hebrew or Thai text
+the document holds:
 
 ```ts
 import { Ream } from 'reamkit';
@@ -38,7 +40,7 @@ import { Ream } from 'reamkit';
 // e.g. from an <input type="file"> or a fetch() — anything that yields bytes.
 const bytes = new Uint8Array(await file.arrayBuffer());
 
-const doc = Ream.parse(bytes);            // docx, xlsx, pptx or pdf — sniffed
+const doc = Ream.parse(bytes);            // docx, xlsx, pptx, pdf, doc, xls or ppt — sniffed
 const pdf = await doc.convert('pdf');     // async — fetches a font if needed
 const svg = await doc.convert('svg');     // same parse, different target
 const html = await doc.convert('html');   // flowed HTML — needs no fonts at all
@@ -57,6 +59,13 @@ and `doc.convertWithReport(...)` returns `{ bytes, losses }` (pass
 are plain `Uint8Array`s, so wiring this to files, the network, or disk is up
 to you.
 
+An encrypted source opens with its password — a PDF's user password, or an
+Office package's (MS-OFFCRYPTO, Agile and Standard):
+
+```ts
+const doc = Ream.parse(bytes, { password: 'secret' });
+```
+
 ### Bring your own fonts (no network)
 
 To embed specific fonts — or to avoid the network entirely — pass the font
@@ -139,7 +148,7 @@ rendering — inspect or analyze it without converting:
 
 ```ts
 const doc = Ream.parse(bytes);
-doc.format;     // 'docx' | 'xlsx' | 'pptx' | 'pdf'
+doc.format;     // 'docx' | 'xlsx' | 'pptx' | 'pdf' | 'doc' | 'xls' | 'ppt'
 doc.flow.body;  // paragraphs / tables / images / charts …
 doc.losses;     // read-time losses
 ```
@@ -157,7 +166,9 @@ const pdf = await doc.convert('pdf', { fonts, hyphenator });
 `convert` accepts (beyond the above): `info` (PDF `/Info` metadata — also read
 automatically from the document's `docProps/core.xml`), `attachments`
 (PDF/A-3 associated files), `tagged` (logical structure without full PDF/A),
-`pageWidth`/`pageHeight`/margins overrides.
+`encrypt` (AES-256 with a user and an owner password and the permissions a
+reader keeps: printing, copying, modifying, …), `pageWidth`/`pageHeight`/margins
+overrides.
 
 ### Lower-level APIs
 
@@ -166,6 +177,9 @@ automatically from the document's `docProps/core.xml`), `attachments`
   keeping unused formats out of your bundle); `layoutStyledDocument` produces the
   frozen page model (`PageItem` pages in a top-left `Pt` frame) the page-based
   writers consume (`docxWriter` works from the flow model, before layout).
+- `createConverter({ readers })` — a converter over a reader registry of your
+  own: `detect` names the reader that recognises the bytes, and `convert` reads
+  and converts them in one call, returning `{ bytes, losses }`.
 - `renderStyledPdf` drives the layout engine directly; the typed document
   model is on the `reamkit/document-model` subpath.
 
@@ -187,27 +201,59 @@ encryption, digital signatures (PKCS#7/ECDSA/PAdES/RFC 3161), SVG page
 preview, flowed HTML export, and **docx + xlsx output** (write WordprocessingML
 / SpreadsheetML back out, incl. round-trips). Reads OOXML Transitional and Strict.
 
+A Word document is laid out by Word's own rules, each measured in Word: a line
+as tall as Word sets its faces, two paragraphs standing the larger of their
+spacings apart rather than the sum, widow and orphan control, a heading kept with
+what it heads, table borders that take the room they are wide, a Word 2010
+table placed by its first cell's text, and sections whose lines run down the
+sheet.
+
+A workbook is drawn the way Excel draws it, each rule checked against Excel's
+own PDF: columns in the Normal font's digit as Excel counts it, a table in the
+style it names, a theme colour's tint to the digit, a sheet that reads from the
+right turned round, the notes it shows beside their cells, its drawings over
+the cells and cut where its pages are, a chart's axes scaled and crossed where
+Excel puts them. As HTML a workbook comes out as Excel's window shows it —
+every tab, its gridlines, a noted cell flagged with the note on hover — and as
+SVG as pictures of its sheets, each whole, its text drawn from the faces' own
+outlines.
+
 **Reads PDF, too.** `Ream.parse` accepts a PDF and reconstructs a `FlowDoc` — a
 tagged PDF from its structure tree (headings, tables, lists, reading order), an
-untagged one heuristically from glyph positions (lines, paragraphs, headings,
-and a clean two-column split). It lifts back the text (via each font's
-`/ToUnicode`, or the embedded program's own `cmap` where there is none, or the
-glyph names its `/Encoding` states — which is all a PDF from TeX gives), the
-font programs themselves, raster images (JPEG verbatim; PNG/Flate/LZW/CCITT-fax
-and **JBIG2** decoded and re-encoded), `/Link` hyperlinks, form-XObject content,
-annotation appearances (drawing one itself where the file supplies none),
-colour set through a named space — device, CIE (`CalGray`, `Lab`) or a
-`Separation`/`DeviceN` run through its own tint transform — and the page's
-artwork: filled / stroked / gradient shapes, clipping paths, tiling patterns,
-stencil image masks, constant alpha, and the Type 3 glyphs that are drawings
-rather than letters. It honours the layers a file turns off (§8.11 optional
-content) and the box it says to show (`/CropBox`), and it decides for itself
-whether a file is a document to re-flow or a page to keep — a paper is mostly
-lines, a form is mostly marks — and there is nothing to configure: a caller
-cannot know which of the two it was handed. It reads modern compressed files (cross-reference
-+ object streams) and encrypted ones (RC4 / AES — the user password is passed to
-`Ream.parse(bytes, { password })`, defaulting to the permissions-only case); a
-filter it does not carry can be handed to it through
+untagged one from where its glyphs stand: lines and paragraphs at the page's own
+pitch, with their indents and alignment; headings and list items; columns of
+any number, breaking and balancing where the page does; tables ruled or set out
+on stops, within a column or across them; code listings; figures, a drawing and
+the labels set on it kept as one group; the hanging entries of an index; and a
+heading's bar as its shading. Running heads and feet become headers and footers,
+their numbers PAGE fields counted in the page's own numerals — a book's roman
+front matter, and a foot of its own for each side of its spreads.
+
+It lifts back the text (via each font's `/ToUnicode`, or the embedded program's
+own `cmap` where there is none, or the glyph names its `/Encoding` states — which
+is all a PDF from TeX gives, its Greek and mathematics included) and the font
+programs themselves: written to `.docx`, each face the page drew with travels
+with the document, rebuilt as TrueType with the page's own advances, kerning and
+ligatures, and embedded where its licence (OS/2 `fsType`) allows — so a line
+breaks where the page broke it, on a machine that has none of its fonts. Raster
+images come back (JPEG verbatim, a CMYK one re-coloured; PNG/Flate/LZW/CCITT-fax
+and **JBIG2** decoded and re-encoded), with `/Link` hyperlinks, form-XObject
+content, annotation and form appearances (drawing one itself where the file
+supplies none), colour set through a named space — device, CIE (`CalGray`,
+`CalRGB`, `Lab`), ICC-based, or a `Separation`/`DeviceN` run through its own
+tint transform — and the page's artwork: filled / stroked / gradient shapes,
+dashes and caps, clipping paths, tiling patterns, stencil image masks, opacity,
+and the Type 3 glyphs that are drawings rather than letters.
+
+It honours the layers a file turns off (§8.11 optional content), the box it says
+to show (`/CropBox`) and the way it turns a page (`/Rotate` — a page whose words
+run down its sheet comes back as a section set that way), and it decides for
+itself whether a file is a document to re-flow or a page to keep — a paper is
+mostly lines, a form is mostly marks — and there is nothing to configure: a
+caller cannot know which of the two it was handed. It reads modern compressed
+files (cross-reference + object streams) and encrypted ones (RC4 / AES — the
+user password is passed to `Ream.parse(bytes, { password })`, defaulting to the
+permissions-only case); a filter it does not carry can be handed to it through
 `Ream.parse(bytes, { filters })`.
 
 A form or a drawing is not a reflowable document, so the reader keeps it as a

package/dist/esm/core/bidi/index.d.ts

@@ -36,6 +36,16 @@ export declare function analyzeString(text: string, dir?: Direction): StringBidi
  *          or Arabic presentation-form ranges.
  */
 export declare function hasBidiCharacters(text: string): boolean;
+/**
+ * The direction of a string's first strong character (UAX #9 P2): `rtl` for
+ * an `R` or `AL` one, `ltr` for an `L` one, undefined when it has none — a
+ * number, punctuation, a blank. This is what an application means by a
+ * "context" reading order.
+ *
+ * @param text The string to scan.
+ * @returns The direction its first strong character sets, if any.
+ */
+export declare function firstStrongDirection(text: string): 'ltr' | 'rtl' | undefined;
 /**
  * Reverse a string by code point (so surrogate pairs stay intact). Used to emit
  * an RTL run's glyphs in visual (right-to-left) order, since our glyph placement

package/dist/esm/core/bidi/index.js

@@ -1,4 +1,4 @@
-import "./char-types.js";
+import { bidiClass } from "./char-types.js";
 import { computeBidi } from "./algorithm.js";
 import "./segments.js";
 //#region src/core/bidi/index.ts
@@ -39,6 +39,22 @@ function hasBidiCharacters(text) {
 	return false;
 }
 /**
+* The direction of a string's first strong character (UAX #9 P2): `rtl` for
+* an `R` or `AL` one, `ltr` for an `L` one, undefined when it has none — a
+* number, punctuation, a blank. This is what an application means by a
+* "context" reading order.
+*
+* @param text The string to scan.
+* @returns The direction its first strong character sets, if any.
+*/
+function firstStrongDirection(text) {
+	for (const ch of text) {
+		const cls = bidiClass(ch.codePointAt(0));
+		if (cls === "L") return "ltr";
+		if (cls === "R" || cls === "AL") return "rtl";
+	}
+}
+/**
 * Reverse a string by code point (so surrogate pairs stay intact). Used to emit
 * an RTL run's glyphs in visual (right-to-left) order, since our glyph placement
 * advances left-to-right.
@@ -50,4 +66,4 @@ function reverseByCodePoint(text) {
 	return [...text].reverse().join("");
 }
 //#endregion
-export { analyzeString, hasBidiCharacters, reverseByCodePoint };
+export { analyzeString, firstStrongDirection, hasBidiCharacters, reverseByCodePoint };

package/dist/esm/core/converter/facade.js

@@ -11,6 +11,7 @@ import { projectSheetDoc } from "../../excel/sheet-to-flow.js";
 import { xlsxReader } from "../../excel/xlsx-reader.js";
 import { chainProviders } from "../fonts/provider.js";
 import { flowRenderOptions } from "./project.js";
+import { layoutSheetImages } from "./sheet-images.js";
 import { writeDocx } from "../../word/docx-writer.js";
 import { writeXlsx } from "../../excel/xlsx-writer.js";
 import { writeHtml } from "../../html/html-writer.js";
@@ -78,7 +79,10 @@ function createConverter(opts = {}) {
 			};
 		}
 		if (to === "html") {
-			const { doc: flow, losses: readLosses } = readToFlow(reader, bytes, rest.now ? { now: rest.now } : void 0);
+			const { doc: flow, losses: readLosses } = readToFlow(reader, bytes, {
+				...rest.now ? { now: rest.now } : {},
+				screen: true
+			});
 			losses.push(...readLosses);
 			const html = writeHtml(flow);
 			losses.push(...html.losses);
@@ -123,10 +127,11 @@ function createConverter(opts = {}) {
 		if (to === "svg") {
 			const fonts = conv.fonts ?? (conv.fontBytes ? { regular: conv.fontBytes } : void 0);
 			if (!fonts) throw new Error("to: 'svg' requires options.fonts/fontBytes or fontProviders");
-			const { doc: flow } = readToFlow(reader, bytes, rest.now ? { now: rest.now } : void 0);
-			const svg = writeSvg(layoutStyledDocument(flow.body, {
-				registry: FontRegistry.fromBytes(fonts),
-				...flowRenderOptions(flow)
+			const { doc } = reader.read(bytes);
+			const registry = FontRegistry.fromBytes(fonts);
+			const svg = writeSvg(doc.kind === "sheet" ? layoutSheetImages(doc, { registry }, rest.now ? { now: rest.now } : {}) : layoutStyledDocument(doc.body, {
+				registry,
+				...flowRenderOptions(doc)
 			}));
 			losses.push(...svg.losses);
 			if (strict && losses.length > 0) throw new ConversionLossError(losses[0]);

package/dist/esm/core/converter/project.js

@@ -28,7 +28,10 @@ function flowRenderOptions(flow) {
 		...flow.doNotExpandShiftReturn ? { doNotExpandShiftReturn: true } : {},
 		...flow.pageBackgroundColorHex ? { pageBackgroundColorHex: flow.pageBackgroundColorHex } : {},
 		...flow.pageBackgroundFill ? { pageBackgroundFill: flow.pageBackgroundFill } : {},
-		...flow.gutterAtTop ? { gutterAtTop: true } : {}
+		...flow.gutterAtTop ? { gutterAtTop: true } : {},
+		...flow.typesetBy ? { typesetBy: flow.typesetBy } : {},
+		...flow.floatsOverText ? { floatsOverText: true } : {},
+		...flow.compatibilityMode !== void 0 ? { compatibilityMode: flow.compatibilityMode } : {}
 	};
 }
 //#endregion

package/dist/esm/core/converter/ream.js

@@ -9,6 +9,7 @@ import { renderStyledPdf, renderStyledPdfEncrypted } from "../../pdf/styled-page
 import "../../pdf/index.js";
 import { projectSheetDoc } from "../../excel/sheet-to-flow.js";
 import { flowRenderOptions } from "./project.js";
+import { layoutSheetImages } from "./sheet-images.js";
 import { writeDocx } from "../../word/docx-writer.js";
 import { writeXlsx } from "../../excel/xlsx-writer.js";
 import { writeHtml } from "../../html/html-writer.js";
@@ -128,7 +129,11 @@ var Ream = class Ream {
 			...options.fileName ? { fileName: options.fileName } : {}
 		}) : this.flow;
 		if (to === "html") {
-			const html = writeHtml(flow);
+			const html = writeHtml(this.sheet ? projectSheetDoc(this.sheet, {
+				...options.now ? { now: options.now } : {},
+				...options.fileName ? { fileName: options.fileName } : {},
+				screen: true
+			}) : flow);
 			losses.push(...html.losses);
 			this.enforceStrict(options, losses);
 			return {
@@ -173,15 +178,21 @@ var Ream = class Ream {
 		}
 		const { fonts, registriesByFamily } = await this.resolveFonts(options, losses, flow);
 		const registry = FontRegistry.fromBytes(fonts);
-		const paginated = this.sheet ? projectSheetDoc(this.sheet, {
+		const sheetOptions = {
 			...options.now ? { now: options.now } : {},
 			...options.fileName ? { fileName: options.fileName } : {},
 			digitWidthPt: createFontMeasure(registry.resolveByStyle(false, false).parsed).textWidthPt("0", DEFAULT_WORKBOOK_FONT_PT)
-		}) : flow;
+		};
+		const { fonts: _a, fontBytes: _b, fontFamily: _c, fontFetch: _d, fontProviders: _e, strict: _f, embedSource, signature, info: callerInfo, attachments: callerAttachments, ...renderOptions } = options;
 		if (to === "svg") {
-			const svg = writeSvg(layoutStyledDocument(paginated.body, {
+			const faces = {
 				registry,
-				...flowRenderOptions(paginated)
+				...registriesByFamily ? { registriesByFamily } : {}
+			};
+			const svg = writeSvg(this.sheet ? layoutSheetImages(this.sheet, faces, sheetOptions, renderOptions) : layoutStyledDocument(flow.body, {
+				...faces,
+				...flowRenderOptions(flow),
+				...renderOptions
 			}));
 			losses.push(...svg.losses);
 			this.enforceStrict(options, losses);
@@ -190,7 +201,7 @@ var Ream = class Ream {
 				losses
 			};
 		}
-		const { fonts: _a, fontBytes: _b, fontFamily: _c, fontFetch: _d, fontProviders: _e, strict: _f, embedSource, signature, info: callerInfo, attachments: callerAttachments, ...renderOptions } = options;
+		const paginated = this.sheet ? projectSheetDoc(this.sheet, sheetOptions) : flow;
 		const info = paginated.info || callerInfo ? {
 			...paginated.info,
 			...callerInfo

package/dist/esm/core/converter/sheet-images.d.ts

@@ -0,0 +1,17 @@
+import { SheetDoc } from '../ir/sheet.js';
+import { ProjectSheetOptions } from '../../excel/sheet-to-flow.js';
+import { LaidOutDocument } from '../../layout/page-doc.js';
+import { StyledRenderOptions } from '../../pdf/index.js';
+/**
+ * Lay a workbook out as images of its sheets: the screen projection, one page a
+ * sheet with room for all of it, each page then cut to its content.
+ *
+ * @param sheet   The workbook.
+ * @param faces   The faces the sheets are measured and drawn in: the registry,
+ *                and one per family where the document names several.
+ * @param options The projection's other knobs (reference date, file name, the
+ *                render face's digit width).
+ * @param render  The caller's own layout options, over the document's.
+ * @returns One page per visible sheet, each as large as what it holds.
+ */
+export declare function layoutSheetImages(sheet: SheetDoc, faces: Pick<StyledRenderOptions, 'registry' | 'registriesByFamily'>, options?: Omit<ProjectSheetOptions, 'screen' | 'wholeSheetPages'>, render?: Partial<StyledRenderOptions>): LaidOutDocument;

package/dist/esm/core/converter/sheet-images.js

@@ -0,0 +1,33 @@
+import { layoutStyledDocument } from "../../layout/styled-layout.js";
+import { projectSheetDoc } from "../../excel/sheet-to-flow.js";
+import { flowRenderOptions } from "./project.js";
+import { fitPagesToContent } from "../../layout/fit-pages.js";
+//#region src/core/converter/sheet-images.ts
+/** The room kept past a sheet's content, as the layout keeps it before it. */
+var SHEET_IMAGE_PAD_PT = 2;
+/**
+* Lay a workbook out as images of its sheets: the screen projection, one page a
+* sheet with room for all of it, each page then cut to its content.
+*
+* @param sheet   The workbook.
+* @param faces   The faces the sheets are measured and drawn in: the registry,
+*                and one per family where the document names several.
+* @param options The projection's other knobs (reference date, file name, the
+*                render face's digit width).
+* @param render  The caller's own layout options, over the document's.
+* @returns One page per visible sheet, each as large as what it holds.
+*/
+function layoutSheetImages(sheet, faces, options = {}, render = {}) {
+	const flow = projectSheetDoc(sheet, {
+		...options,
+		screen: true,
+		wholeSheetPages: true
+	});
+	return fitPagesToContent(layoutStyledDocument(flow.body, {
+		...faces,
+		...flowRenderOptions(flow),
+		...render
+	}), SHEET_IMAGE_PAD_PT);
+}
+//#endregion
+export { layoutSheetImages };

package/dist/esm/core/crypto/offcrypto.js

@@ -1,5 +1,5 @@
-import { openCfb } from "../ole/cfb.js";
 import { aesCbcDecrypt, aesEcbDecrypt, sha1, sha256, sha384, sha512 } from "./primitives.js";
+import { openCfb } from "../ole/cfb.js";
 //#region src/core/crypto/offcrypto.ts
 /** Thrown when the bytes are encrypted and the password does not open them. */
 var WrongPasswordError = class extends Error {

package/dist/esm/core/document-model/index.d.ts

@@ -5,4 +5,4 @@
  *
  * @packageDocumentation
  */
-export type { AbstractNumbering, Alignment, Border, BorderStyle, BodyElement, Comment, CellBorders, CellMerge, DocumentInfo, CellMargins, CellProperties, CellShading, CellDataBar, CellIcon, CellIconShape, CellSparkline, Chart, ChartBlock, ChartDataPoint, ChartLineStyle, ChartMarker, ChartMarkerSymbol, ChartSeries, ChartType, CustomGeometry, CustomPathCmd, DocumentModel, FontFamilyMap, HeaderFooterReference, HeaderFooterType, ImageBlock, ImageCrop, InlineImage, MathAccent, MathBar, MathDelimiter, MathEqArray, MathFraction, MathFunc, MathGroupChr, MathLimit, MathMatrix, MathNary, MathNode, MathRadical, MathRow, MathRun, MathScript, Numbering, NumberingFormat, NumberingInstance, NumberingLevel, PictureBullet, PictureOutline, NumberingReference, PageMargins, PageSize, Paragraph, ParagraphProperties, FrameProperties, RelativeSize, TabStop, Run, RunProperties, TextOutline, RowConditionalFormat, RowProperties, Section, FloatAnchor, SectionColumns, SectionProperties, ShapeBlock, ShapeShadow, ShapeDash, ShapeFill, ShapeFillKind, ShapeGeometry, ShapeGroupChild, ShapeLine, LineEnd, ShapeTextBody, ShapeTransform, Style, StyleSheet, StyleType, Table, TableCell, TableLook, TableProperties, TableStyleCondition, TableStyleConditionType, TableStyleLayer, TableRow, UnderlineStyle, VerticalAlign, } from './types.js';
+export type { AbstractNumbering, Alignment, Border, BorderStyle, BodyElement, Comment, CellBorders, CellMerge, DocumentInfo, CellMargins, CellProperties, CellShading, CellDataBar, CellIcon, CellNoteFlag, CellIconShape, CellSparkline, Chart, ChartBlock, ChartDataPoint, ChartLineStyle, ChartMarker, ChartMarkerSymbol, ChartSeries, ChartType, CustomGeometry, CustomPathCmd, DocumentModel, FontFamilyMap, HeaderFooterReference, HeaderFooterType, ImageBlock, ImageCrop, InlineImage, MathAccent, MathBar, MathDelimiter, MathEqArray, MathFraction, MathFunc, MathGroupChr, MathLimit, MathMatrix, MathNary, MathNode, MathRadical, MathRow, MathRun, MathScript, Numbering, NumberingFormat, NumberingInstance, NumberingLevel, PictureBullet, PictureOutline, NumberingReference, PageMargins, PageSize, Paragraph, ParagraphProperties, FrameProperties, RelativeSize, TabStop, Run, RunProperties, TextOutline, Ligatures, RowConditionalFormat, RowProperties, Section, FloatAnchor, SectionColumns, SectionProperties, ShapeBlock, ShapeShadow, ShapeDash, ShapeFill, ShapeFillKind, ShapeGeometry, ShapeGroupChild, ShapeLine, LineEnd, ShapeTextBody, ShapeTransform, Style, StyleSheet, StyleType, Table, TableCell, TableLook, TableOverlay, TableProperties, TableStyleCondition, TableStyleConditionType, TableStyleLayer, TableRow, UnderlineStyle, VerticalAlign, } from './types.js';