reamkit 1.15.3 → 1.16.0

package/dist/esm/core/converter/facade.d.ts

@@ -24,6 +24,11 @@ export interface ConvertOptions extends ConvertDocxOptions {
      * never the wall clock; omitted ⇒ those clock-relative rules no-op.
      */
     readonly now?: Date;
+    /**
+     * §18.3.1.34 `&F` — the workbook's file name, for a spreadsheet whose header
+     * or footer prints it. Absent, the code is dropped.
+     */
+    readonly fileName?: string;
     /**
      * Font resolution chain (ir-design §8). When set (and no caller `fonts`),
      * the facade resolves the default font set through these providers — e.g.

package/dist/esm/core/converter/ream.d.ts

@@ -54,6 +54,12 @@ export interface ReamConvertOptions extends Omit<StyledRenderOptions, 'registry'
      * unchanged.
      */
     readonly now?: Date;
+    /**
+     * §18.3.1.34 `&F` — the workbook's file name, for a spreadsheet whose header
+     * or footer prints it. A byte-oriented reader cannot know it; supplied here,
+     * the code resolves, and omitted it is dropped exactly as before.
+     */
+    readonly fileName?: string;
 }
 /**
  * The object face of the library: parse a document once into the format-neutral

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

@@ -1,5 +1,6 @@
 import { fetchFontSet } from "../fonts/remote-fonts.js";
 import { FontRegistry } from "../font/font-registry.js";
+import { createFontMeasure } from "../font/measure.js";
 import { ConversionLossError } from "../ir/loss.js";
 import { layoutStyledDocument } from "../../layout/styled-layout.js";
 import { signPdf } from "../../pdf/signature.js";
@@ -12,8 +13,14 @@ import { writeXlsx } from "../../excel/xlsx-writer.js";
 import { writeHtml } from "../../html/html-writer.js";
 import { writeSvg } from "../../svg/svg-writer.js";
 import { resolveDocxAutoFonts } from "../../word/docx-to-pdf.js";
+import { isCfb, openCfb } from "../ole/cfb.js";
 import { DEFAULT_READERS, resolveFontsViaChain, toFlowDoc } from "./facade.js";
 //#region src/core/converter/ream.ts
+/**
+* The point size Excel's column-width unit is quoted at — its default theme
+* font is 11 pt, and 8.43 of its digits are the documented 64 px column.
+*/
+var DEFAULT_WORKBOOK_FONT_PT = 11;
 /** OOXML / legacy MIME types by reader id, for the PDF/A-3 embedded source file. */
 var SOURCE_MIME = {
 	docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -71,7 +78,10 @@ var Ream = class Ream {
 	static parse(bytes, options = {}) {
 		const readers = options.readers ?? DEFAULT_READERS;
 		const reader = readers.find((r) => r.sniff(bytes));
-		if (!reader) throw new Error(`Unrecognized document format (readers: ${readers.map((r) => r.id).join(", ")})`);
+		if (!reader) {
+			if (isEncryptedOoxml(bytes)) throw new Error("Password-protected OOXML document (ECMA-376 §2.3 EncryptedPackage) — re-save it without a password");
+			throw new Error(`Unrecognized document format (readers: ${readers.map((r) => r.id).join(", ")})`);
+		}
 		const { doc, losses } = reader.read(bytes, { password: options.password });
 		const sheet = doc.kind === "sheet" ? doc : void 0;
 		return new Ream(toFlowDoc(doc), sheet, losses, bytes, reader.id);
@@ -106,7 +116,10 @@ var Ream = class Ream {
 	*/
 	async convertWithReport(to, options = {}) {
 		const losses = [...this.losses];
-		const flow = this.sheet && options.now ? projectSheetDoc(this.sheet, { now: options.now }) : this.flow;
+		const flow = this.sheet && (options.now || options.fileName) ? projectSheetDoc(this.sheet, {
+			...options.now ? { now: options.now } : {},
+			...options.fileName ? { fileName: options.fileName } : {}
+		}) : this.flow;
 		if (to === "html") {
 			const html = writeHtml(flow);
 			losses.push(...html.losses);
@@ -137,10 +150,15 @@ var Ream = class Ream {
 		}
 		const { fonts, registriesByFamily } = await this.resolveFonts(options, losses);
 		const registry = FontRegistry.fromBytes(fonts);
+		const paginated = this.sheet ? projectSheetDoc(this.sheet, {
+			...options.now ? { now: options.now } : {},
+			...options.fileName ? { fileName: options.fileName } : {},
+			digitWidthPt: createFontMeasure(registry.resolveByStyle(false, false).parsed).textWidthPt("0", DEFAULT_WORKBOOK_FONT_PT)
+		}) : flow;
 		if (to === "svg") {
-			const svg = writeSvg(layoutStyledDocument(flow.body, {
+			const svg = writeSvg(layoutStyledDocument(paginated.body, {
 				registry,
-				...flowRenderOptions(flow)
+				...flowRenderOptions(paginated)
 			}));
 			losses.push(...svg.losses);
 			this.enforceStrict(options, losses);
@@ -150,8 +168,8 @@ var Ream = class Ream {
 			};
 		}
 		const { fonts: _a, fontBytes: _b, fontFamily: _c, fontFetch: _d, fontProviders: _e, strict: _f, embedSource, signature, info: callerInfo, attachments: callerAttachments, ...renderOptions } = options;
-		const info = flow.info || callerInfo ? {
-			...flow.info,
+		const info = paginated.info || callerInfo ? {
+			...paginated.info,
 			...callerInfo
 		} : void 0;
 		const attachments = [...callerAttachments ?? []];
@@ -165,13 +183,13 @@ var Ream = class Ream {
 		const styled = {
 			registry,
 			...registriesByFamily ? { registriesByFamily } : {},
-			...flowRenderOptions(flow),
+			...flowRenderOptions(paginated),
 			...info ? { info } : {},
 			...attachments.length > 0 ? { attachments } : {},
 			...signature ? { signaturePlaceholder: signature } : {},
 			...renderOptions
 		};
-		let pdf = styled.encrypt ? await renderStyledPdfEncrypted(flow.body, styled) : renderStyledPdf(flow.body, styled);
+		let pdf = styled.encrypt ? await renderStyledPdfEncrypted(paginated.body, styled) : renderStyledPdf(paginated.body, styled);
 		if (signature) pdf = await signPdf(pdf, signature);
 		this.enforceStrict(options, losses);
 		return {
@@ -214,5 +232,13 @@ var Ream = class Ream {
 		if (options.strict && losses.length > 0) throw new ConversionLossError(losses[0]);
 	}
 };
+function isEncryptedOoxml(bytes) {
+	if (!isCfb(bytes)) return false;
+	try {
+		return openCfb(bytes).hasStream("EncryptedPackage");
+	} catch {
+		return false;
+	}
+}
 //#endregion
 export { Ream };

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, ChartSeries, ChartType, CustomGeometry, CustomPathCmd, DocumentModel, FontFamilyMap, HeaderFooterReference, HeaderFooterType, ImageBlock, InlineImage, MathAccent, MathBar, MathDelimiter, MathEqArray, MathFraction, MathFunc, MathGroupChr, MathLimit, MathMatrix, MathNary, MathNode, MathRadical, MathRow, MathRun, MathScript, Numbering, NumberingFormat, NumberingInstance, NumberingLevel, NumberingReference, PageMargins, PageSize, Paragraph, ParagraphProperties, Run, RunProperties, RowProperties, Section, FloatAnchor, SectionColumns, SectionProperties, ShapeBlock, ShapeDash, ShapeFill, ShapeFillKind, ShapeGeometry, ShapeLine, 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, CellIconShape, CellSparkline, Chart, ChartBlock, ChartDataPoint, ChartLineStyle, ChartMarker, ChartMarkerSymbol, ChartSeries, ChartType, CustomGeometry, CustomPathCmd, DocumentModel, FontFamilyMap, HeaderFooterReference, HeaderFooterType, ImageBlock, InlineImage, MathAccent, MathBar, MathDelimiter, MathEqArray, MathFraction, MathFunc, MathGroupChr, MathLimit, MathMatrix, MathNary, MathNode, MathRadical, MathRow, MathRun, MathScript, Numbering, NumberingFormat, NumberingInstance, NumberingLevel, NumberingReference, PageMargins, PageSize, Paragraph, ParagraphProperties, Run, RunProperties, RowProperties, Section, FloatAnchor, SectionColumns, SectionProperties, ShapeBlock, ShapeShadow, ShapeDash, ShapeFill, ShapeFillKind, ShapeGeometry, ShapeLine, ShapeTextBody, ShapeTransform, Style, StyleSheet, StyleType, Table, TableCell, TableLook, TableProperties, TableStyleCondition, TableStyleConditionType, TableStyleLayer, TableRow, UnderlineStyle, VerticalAlign, } from './types.js';

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

@@ -385,7 +385,7 @@ export interface StyleSheet {
     readonly styles: ReadonlyMap<string, Style>;
 }
 /** §17.18.2 ST_Border — a cell-border line style (the subset Ream renders). */
-export type BorderStyle = 'none' | 'single' | 'double' | 'thick' | 'dotted' | 'dashed';
+export type BorderStyle = 'none' | 'single' | 'double' | 'thick' | 'dotted' | 'dashed' | 'dashDot' | 'dashDotDot';
 /** One border edge: its line style plus optional width and colour. */
 export interface Border {
     readonly style: BorderStyle;
@@ -428,6 +428,12 @@ export interface CellDataBar {
     readonly fraction: number;
     readonly colorHex: string;
     readonly startFraction?: number;
+    /**
+     * The bar runs LEFT from the axis (a negative value in a mixed-sign range),
+     * so its solid end is its right one. Excel fades a data bar away from the
+     * axis, and which way that is depends on the sign.
+     */
+    readonly negative?: boolean;
 }
 /**
  * A conditional-format icon: a small glyph at the cell's left, chosen by the
@@ -478,6 +484,18 @@ export interface CellProperties {
     readonly merge?: CellMerge;
     readonly borders?: CellBorders;
     readonly margins?: CellMargins;
+    /**
+     * How many of the spanned columns the cell's own PAINT covers, when that is
+     * fewer than `colSpan`.
+     *
+     * Text overflow is modelled as a span — a cell whose value does not fit runs
+     * across the empty neighbours to its right — but Excel runs the TEXT over an
+     * unpainted cell without painting it. With one width for both, a filled cell
+     * carried its fill along: 54436.xlsx ran its pivot header's blue a whole
+     * column past the pivot. Absent ⇒ the paint covers the whole span, which is
+     * what a merge wants.
+     */
+    readonly paintColumns?: number;
     readonly shading?: CellShading;
     readonly dataBar?: CellDataBar;
     readonly icon?: CellIcon;
@@ -487,6 +505,28 @@ export interface CellProperties {
      * dropdown affordance at the cell's right edge (a small button + ▾ glyph).
      */
     readonly dropdown?: boolean;
+    /**
+     * The cell's text is not allowed to wrap: it renders on one line and whatever
+     * does not fit the cell box is cut, as a spreadsheet cell without `wrapText`
+     * does. Only the paginated layout honours it — an HTML view has no page edge
+     * to clip against and lets the browser decide.
+     */
+    readonly noWrap?: boolean;
+    /**
+     * The cell holds a NUMBER under a format of its own, so it may not be shown
+     * truncated: a date cut to "4/30/201" is not a shorter date, it is the wrong
+     * one. Excel and LibreOffice fill such a cell with `#` instead, which says
+     * "widen me" and cannot be misread. Text is exempt — a clipped word is still
+     * recognisably that word.
+     */
+    readonly hashOnOverflow?: boolean;
+    /**
+     * Where the cell's content sits in a box taller than itself. A spreadsheet
+     * cell defaults to `'bottom'` — §18.8.1, and both Excel and LibreOffice do it
+     * — which is visible on any row taller than its text. Absent ⇒ the top, which
+     * is a word-processor table's default.
+     */
+    readonly verticalAlign?: 'top' | 'center' | 'bottom';
 }
 /** §17.4.81 `w:trPr` — a table row's properties: height, split/header flags. */
 export interface RowProperties {
@@ -668,6 +708,21 @@ export interface ShapeTextBody {
  * paragraph's properties for block spacing / alignment, mirroring
  * {@link ImageBlock}.
  */
+/**
+ * §20.1.8.40 `a:outerShdw` — the drop shadow under a shape: how far it is
+ * displaced, how soft its edge is, and in what colour. `dxPt`/`dyPt` are the
+ * displacement in page coordinates (y grows DOWN), resolved from the spec's
+ * polar `dist`/`dir`.
+ */
+export interface ShapeShadow {
+    readonly dxPt: number;
+    readonly dyPt: number;
+    /** `blurRad` in points; 0 is a hard edge. */
+    readonly blurPt: number;
+    readonly colorHex: string;
+    /** 0..1, from the shadow colour's `a:alpha` (absent ⇒ opaque). */
+    readonly alpha: number;
+}
 export interface ShapeBlock {
     /** §20.4.2.3 — present when the drawing is anchored (floating). */
     readonly float?: FloatAnchor;
@@ -678,6 +733,8 @@ export interface ShapeBlock {
     readonly line?: ShapeLine;
     readonly transform?: ShapeTransform;
     readonly text?: ShapeTextBody;
+    /** §20.1.8.40 — the shape's drop shadow, direct or from its style reference. */
+    readonly shadow?: ShapeShadow;
     readonly paragraphProperties: ParagraphProperties;
     /** `wp:docPr @descr/@title` — alternate text for the tagged-PDF Figure (`/Alt`). */
     readonly altText?: string;
@@ -699,16 +756,91 @@ export interface ChartDataPoint {
 /** One chart data series (`c:ser`): its name, values and colour overrides. */
 export interface ChartSeries {
     readonly name?: string;
+    /**
+     * §21.2.2 — the chart group this series came from, when it is NOT the group
+     * that gave {@link Chart.type}. A `c:plotArea` may hold several groups: a
+     * combo chart writes `c:barChart` and `c:lineChart` side by side, and reading
+     * only the first drops the other's series off the page entirely (57362.xlsx
+     * loses its line). Absent ⇒ the series draws as the chart's own type.
+     */
+    readonly type?: ChartType;
+    /**
+     * §21.2.2.9 `c:axId` — the series plots against the SECONDARY value axis: its
+     * group names a `c:valAx` other than the one the first group uses. 57362.xlsx
+     * puts its line on an axis of its own at `axPos="r"`, and plotting it on the
+     * primary scale puts every point at the wrong height whenever the two ranges
+     * differ.
+     */
+    readonly secondaryAxis?: boolean;
     readonly values: ReadonlyArray<number>;
     readonly xValues?: ReadonlyArray<number>;
     readonly colorHex?: string;
     readonly pointColors?: ReadonlyArray<ChartDataPoint>;
+    /**
+     * §21.2.2.49 `c:dLbl/c:tx` — a data label the author typed rather than one
+     * the chart computes, by point index. Excel and Calc print it verbatim: it
+     * is the only place a label like "Промышленные потребители; 22,7млрд.кВтч;
+     * 67,3%" exists, and generating one from the value instead loses the whole
+     * sentence.
+     */
+    readonly pointLabels?: ReadonlyArray<{
+        readonly idx: number;
+        readonly text: string;
+    }>;
+    /**
+     * §21.2.2.59 `c:val/c:numRef/c:f` and §21.2.2.215 `c:tx/c:strRef/c:f` — where
+     * the series reads its numbers and its name FROM, when the chart part carries
+     * no cache of them. A chart written without caches is not a chart without
+     * data: the reader resolves these against the workbook.
+     */
+    readonly valuesRef?: string;
+    readonly nameRef?: string;
+    /**
+     * §21.2.2.106 `c:marker` — the symbol this series stamps on each of its
+     * points. Absent ⇒ the reader's own default.
+     */
+    readonly marker?: ChartMarker;
+    /**
+     * §21.2.2.198 `c:ser/c:spPr/a:ln` — the series' OWN rule. `<a:noFill/>` is
+     * how Excel writes "scatter with markers only": the group still says
+     * `lineMarker`, and it is this line that says the points are not joined.
+     * SimpleScatterChart.xlsx is two loose dots in both references and we ran a
+     * line between them.
+     */
+    readonly line?: ChartLineStyle;
+}
+/**
+ * §21.2.2.107 `c:symbol` (ST_MarkerStyle) — the shape of a scatter/line
+ * series' point marker. `auto` and `picture` are left to the reader, so they
+ * are not carried here.
+ */
+export type ChartMarkerSymbol = 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'plus' | 'square' | 'star' | 'triangle' | 'x';
+/**
+ * §21.2.2.106 `c:marker` — a series' point symbol and its size in points
+ * (§21.2.2.153 `c:size`, 2–72). chartTitle_noTitle.xlsx asks for a 5pt circle
+ * at every point and both references draw one; we stamped a square.
+ */
+export interface ChartMarker {
+    readonly symbol: ChartMarkerSymbol;
+    readonly sizePt?: number;
+}
+/**
+ * §21.2.2.196 `c:spPr/a:ln` on an axis or its gridlines — the rule the author
+ * gave it. `none` is `<a:ln><a:noFill/>`, which means the axis draws no line at
+ * all: 57362.xlsx hides its secondary value axis that way and keeps its labels.
+ */
+export interface ChartLineStyle {
+    readonly none?: boolean;
+    readonly colorHex?: string;
+    readonly widthPt?: number;
 }
 /** A parsed chart (§21.2): its type, title, categories, series and rendering options. */
 export interface Chart {
     readonly type: ChartType;
     readonly title?: string;
     readonly categories: ReadonlyArray<string>;
+    /** §21.2.2.24 `c:cat/…/c:f` — where the categories live, when uncached. */
+    readonly categoriesRef?: string;
     readonly series: ReadonlyArray<ChartSeries>;
     readonly hasLegend: boolean;
     readonly legendPos?: 'r' | 'l' | 't' | 'b';
@@ -716,8 +848,62 @@ export interface Chart {
     readonly grouping?: 'clustered' | 'stacked' | 'percentStacked' | 'standard';
     readonly doughnut?: boolean;
     readonly showValues?: boolean;
+    /**
+     * §21.2.2.75 `c:gapWidth` — the gap between category slots as a percentage
+     * of the bar width. Absent ⇒ the schema's 150.
+     */
+    readonly gapPercent?: number;
     readonly catAxisTitle?: string;
+    /**
+     * §21.2.2.134 `c:catAx/c:scaling/c:orientation` = `maxMin` — the category
+     * axis runs the other way. A ranked bar chart is written this way so its
+     * first row reads at the TOP (dataValidationTableRange.xlsx ranks 38 counties
+     * and we printed the ranking upside down).
+     */
+    readonly catAxisReversed?: boolean;
     readonly valAxisTitle?: string;
+    /** §21.2.2.168 — the title of the secondary value axis, when one is drawn. */
+    readonly secondaryValAxisTitle?: string;
+    /**
+     * §21.2.2.161 `c:scatterStyle` — whether a scatter's points are joined by a
+     * line, marked, or both. The schema's default is `marker`; Excel writes
+     * `lineMarker` for the chart most people insert.
+     */
+    readonly scatterStyle?: 'none' | 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker';
+    /**
+     * §21.2.2.106 `c:marker` on a `c:lineChart` — whether the group's series mark
+     * their data points. WithChart.xlsx asks for them and we drew bare lines.
+     */
+    readonly lineMarkers?: boolean;
+    /** §21.2.2.196 — the category axis's own rule. */
+    readonly catAxisLine?: ChartLineStyle;
+    /** §21.2.2.196 — the value axis's own rule. */
+    readonly valAxisLine?: ChartLineStyle;
+    /** §21.2.2.196 — the secondary value axis's own rule. */
+    readonly secondaryValAxisLine?: ChartLineStyle;
+    /** §21.2.2.87 `c:majorGridlines/c:spPr/a:ln` — the gridlines' own rule. */
+    readonly gridLine?: ChartLineStyle;
+    /**
+     * §21.2.2.157 `c:valAx/c:scaling/c:min|c:max` — the value axis the AUTHOR
+     * fixed. Absent means "auto", and only then is the range read off the data:
+     * a chart whose cells all read zero still has the axis its author pinned, and
+     * scaling it to the data drew 0…1 where every reader draws 0…300.
+     */
+    readonly valAxisMin?: number;
+    readonly valAxisMax?: number;
+    /**
+     * §21.2.2.198 `c:chartSpace/c:spPr` — the frame around the whole chart: its
+     * background fill and its outline. Excel writes both on every chart it
+     * creates, and both references draw them.
+     */
+    readonly frameFillHex?: string;
+    readonly frameLineHex?: string;
+    /**
+     * §21.2.2.121 `c:valAx/c:numFmt@formatCode` — the number format the value
+     * axis's tick labels and the data labels are drawn in, in the same code
+     * grammar cells use (§18.8.31). Absent ⇒ a plain numeric render.
+     */
+    readonly numberFormat?: string;
     /**
      * MS-ODRAWXML `chartColorStyle` (`colorsN.xml`): the cycle of series colours;
      * overrides the built-in Office accent cycle when present.

package/dist/esm/core/drawingml/chart-geometry.d.ts

@@ -51,6 +51,13 @@ export interface ChartLabel {
     readonly sizePt: number;
     readonly colorHex: string;
     readonly align: LabelAlign;
+    /**
+     * §21.2.2.216 `c:title/c:txPr/a:bodyPr@rot` — a value-axis title reads
+     * bottom-to-top (`rot="-5400000"`, the default every reader applies). Degrees
+     * counter-clockwise about the anchor; `align` then runs along the ROTATED
+     * reading direction.
+     */
+    readonly rotationDeg?: number;
 }
 /**
  * The fully laid-out chart: rectangles, polylines, wedges and labels (plus
@@ -64,6 +71,15 @@ export interface ChartScene {
     readonly wedges: ReadonlyArray<ChartWedge>;
     readonly labels: ReadonlyArray<ChartLabel>;
     readonly polygons?: ReadonlyArray<ChartPolygon>;
+    /** §21.2.2.198 chart-space fill + outline: drawn under everything else. */
+    readonly background?: ChartRect;
+    /**
+     * Major gridlines, drawn UNDER the plotted data. Kept apart from the other
+     * polylines because z-order is the whole point: gridlines over the bars strip
+     * every one of them with the axis's own ruling, which is not what any
+     * spreadsheet draws.
+     */
+    readonly gridlines?: ReadonlyArray<ChartPolyline>;
 }
 /**
  * Injected text-width measurer: the rendered advance width (points) of `text` at
@@ -127,6 +143,18 @@ export declare function formatTick(v: number, step: number): string;
  * @returns The positioned scene primitives.
  */
 export declare function buildBarScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
+/**
+ * The name a series shows in the legend: its own `c:tx`, or Excel's positional
+ * `SeriesN` when it has none. Exported because the SUBSET has to know it too —
+ * a name invented at draw time is a name no glyph collector ever saw, and
+ * 57362.xlsx drew its unnamed series as "eries1", the capital S appearing
+ * nowhere else on the page and so nowhere in the font.
+ *
+ * @param series The series.
+ * @param index  Its zero-based index in the chart.
+ * @returns The legend text.
+ */
+export declare function legendSeriesName(series: ChartSeries, index: number): string;
 /**
  * Lay out an area {@link Chart} into a {@link ChartScene}: each series becomes a
  * filled polygon down to the value baseline (stacked when `chart.grouping` is