reamkit 1.31.0 → 1.32.0

package/README.md

@@ -208,6 +208,16 @@ 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 from where its glyphs stand: lines and paragraphs at the page's own

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

@@ -30,6 +30,7 @@ function flowRenderOptions(flow) {
 		...flow.pageBackgroundFill ? { pageBackgroundFill: flow.pageBackgroundFill } : {},
 		...flow.gutterAtTop ? { gutterAtTop: true } : {},
 		...flow.typesetBy ? { typesetBy: flow.typesetBy } : {},
+		...flow.floatsOverText ? { floatsOverText: true } : {},
 		...flow.compatibilityMode !== void 0 ? { compatibilityMode: flow.compatibilityMode } : {}
 	};
 }

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/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, Ligatures, 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';

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

@@ -731,6 +731,19 @@ export interface CellDataBar {
      * axis, and which way that is depends on the sign.
      */
     readonly negative?: boolean;
+    /** The bar is one solid colour, not faded from the axis (`<x14:dataBar gradient="0">`). */
+    readonly solid?: boolean;
+}
+/**
+ * How a window flags a cell that carries a note: red for a legacy note, purple
+ * for a threaded comment, in the top corner on the side the cell ends — the
+ * right, or the left on a sheet that reads from the right.
+ */
+export interface CellNoteFlag {
+    readonly kind: 'note' | 'thread';
+    /** The note as one reads it on hover: author and text, a conversation line by line. */
+    readonly text: string;
+    readonly atLeft?: boolean;
 }
 /**
  * A conditional-format icon: a small glyph at the cell's left, chosen by the
@@ -801,6 +814,12 @@ export interface CellProperties {
      * what a merge wants.
      */
     readonly paintColumns?: number;
+    /**
+     * The paint covers the LAST {@link paintColumns} of the span rather than the
+     * first. A sheet that reads from the right runs a cell's text over the
+     * neighbours on its left, so the cell the paint belongs to ends the span.
+     */
+    readonly paintAtEnd?: boolean;
     readonly shading?: CellShading;
     readonly dataBar?: CellDataBar;
     readonly icon?: CellIcon;
@@ -810,6 +829,12 @@ export interface CellProperties {
      * dropdown affordance at the cell's right edge (a small button + ▾ glyph).
      */
     readonly dropdown?: boolean;
+    /**
+     * A note or comment on the cell, as a WINDOW flags it (E-SHEET W7): a small
+     * triangle in the cell's top corner, the note's text shown on hover where
+     * the medium can. Set by screen projections only — paper never shows it.
+     */
+    readonly noteFlag?: CellNoteFlag;
     /**
      * 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`
@@ -867,6 +892,13 @@ export interface RowProperties {
      * header row `w:firstRow="1"` so it is painted like the first.
      */
     readonly conditional?: RowConditionalFormat;
+    /**
+     * Where a spreadsheet row's top stands on its sheet, measured down from the
+     * sheet's first row in the frame its table's drawings are placed in (see
+     * {@link TableOverlay}). A row the sheet does not have — the printed column
+     * letters — carries none.
+     */
+    readonly sheetTopPt?: Pt;
 }
 /** §17.4.7 — the row-level conditional-format flags a `w:cnfStyle` declares. */
 export interface RowConditionalFormat {
@@ -900,6 +932,14 @@ export interface TableProperties {
     readonly layout?: 'auto' | 'fixed';
     readonly defaultCellMargins?: CellMargins;
     readonly borders?: CellBorders;
+    /**
+     * A worksheet's gridlines as its WINDOW draws them (§18.3.1.87), where the
+     * sheet was projected for a screen: the line a cell's edge takes when no
+     * border claims it — but not around a filled cell, whose fill covers them.
+     * A screen-only hint: the paginated layout draws a grid only where the
+     * sheet PRINTS one, and that comes as `borders`.
+     */
+    readonly gridlines?: Border;
     /**
      * ECMA-376 §17.4.27 (`w:jc`) / xlsx `<printOptions horizontalCentered>`.
      * Centers or right-aligns a table narrower than the content width; absent ⇒ left.
@@ -946,6 +986,32 @@ export interface Table {
     readonly properties: TableProperties;
     readonly grid: ReadonlyArray<Pt>;
     readonly rows: ReadonlyArray<TableRow>;
+    /** The drawings that lie over a spreadsheet grid and print with it. */
+    readonly overlay?: TableOverlay;
+}
+/**
+ * §20.5 — a spreadsheet's drawings over the part of the sheet one table
+ * prints. A drawing is anchored to cells, not to paper: each page the table
+ * spans shows the part of every drawing that lies over the rows and columns it
+ * prints, and cuts it off where they end — a chart across a page break is
+ * printed in two pieces, a drawing in the repeated title rows on every page,
+ * and what runs out of the print area not at all. Excel prints a sheet so.
+ */
+export interface TableOverlay {
+    /** Where the sheet's columns this table prints begin, in the drawings' frame. */
+    readonly sheetLeftPt: Pt;
+    /** How wide those columns run. */
+    readonly widthPt: Pt;
+    /** Where they stand in the table, from its left edge (past a printed row-number column). */
+    readonly leftPt: Pt;
+    /** §18.3.1.87 — the sheet reads from the right: its first column stands at the right. */
+    readonly mirrored?: boolean;
+    /**
+     * The drawings, out-of-flow floats placed in the sheet's own frame: `posH`
+     * from the sheet's left edge, `posV` from its top, the frame of
+     * {@link RowProperties.sheetTopPt}.
+     */
+    readonly drawings: ReadonlyArray<BodyElement>;
 }
 /**
  * ECMA-376 Part 1 §20.4.2.8 — a block-level image (`wp:inline` picture extent).
@@ -1430,6 +1496,16 @@ export interface Chart {
     readonly categories: ReadonlyArray<string>;
     /** §21.2.2.24 `c:cat/…/c:f` — where the categories live, when uncached. */
     readonly categoriesRef?: string;
+    /**
+     * §21.2.2.115 `c:multiLvlStrCache` — the outer levels of a category axis
+     * labelled on more than one: each level's groups, innermost level first,
+     * each group from the category it starts at to the next group's start.
+     * {@link Chart.categories} is the innermost level, one label per category.
+     */
+    readonly categoryGroups?: ReadonlyArray<ReadonlyArray<{
+        readonly start: number;
+        readonly label: string;
+    }>>;
     readonly series: ReadonlyArray<ChartSeries>;
     readonly hasLegend: boolean;
     readonly legendPos?: 'r' | 'l' | 't' | 'b';
@@ -1450,6 +1526,27 @@ export interface Chart {
      * and we printed the ranking upside down).
      */
     readonly catAxisReversed?: boolean;
+    /**
+     * §21.2.2.33/§21.2.2.34 `c:catAx/c:crosses`, `c:crossesAt` — where along the
+     * value axis the category axis lies, and so where bars grow from: at the
+     * axis's minimum or maximum, or at a stated value. Absent ⇒ `autoZero`, at
+     * zero (or the end of the value axis nearest it).
+     */
+    readonly catAxisCrosses?: 'min' | 'max' | number;
+    /**
+     * §21.2.2.207 `c:catAx/c:tickLblPos` — where the category labels stand: at
+     * the low or high end of the value axis, or nowhere. Absent ⇒ `nextTo`,
+     * beside the category axis wherever it crosses — on the zero line of a chart
+     * with values below zero.
+     */
+    readonly catTickLabelPos?: 'low' | 'high' | 'none';
+    /**
+     * §21.2.2.33 `c:valAx/c:crosses` — where along the category axis the value
+     * axis lies: at the last category (`max`) or the first (absent, `autoZero`).
+     * The first is at the far end when the categories run backwards
+     * ({@link Chart.catAxisReversed}): a ranked bar chart has its values on top.
+     */
+    readonly valAxisCrosses?: 'min' | 'max' | number;
     readonly valAxisTitle?: string;
     /** §21.2.2.168 — the title of the secondary value axis, when one is drawn. */
     readonly secondaryValAxisTitle?: string;
@@ -1480,6 +1577,11 @@ export interface Chart {
      */
     readonly valAxisMin?: number;
     readonly valAxisMax?: number;
+    /**
+     * §21.2.2.98 `c:valAx/c:majorUnit` — the step between the value axis's
+     * labels, when the author fixed it. Absent ⇒ the application's own choice.
+     */
+    readonly valAxisMajorUnit?: 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
@@ -1744,6 +1846,16 @@ export interface SectionColumns {
 export interface Section {
     readonly properties: SectionProperties;
     readonly endIndex: number;
+    /**
+     * The worksheet this section IS, where a workbook was projected for a screen
+     * rather than for paper (`ProjectSheetOptions.screen`): its tab's name. Such
+     * a section is one surface with no pages — the grid as Excel shows it — and
+     * a float in it is placed from the surface's top-left corner, which is the
+     * corner of the first cell.
+     */
+    readonly sheet?: {
+        readonly name: string;
+    };
 }
 /** The parsed WordprocessingML document: body, stylesheet, numbering and section setup. */
 export interface DocumentModel {

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

@@ -118,17 +118,30 @@ export interface Scale {
     readonly step: number;
 }
 /**
- * Compute a human-friendly axis {@link Scale} for the data range using
- * Heckbert's "nice numbers" algorithm: rounded endpoints and a 1/2/5·10ⁿ step
- * that yields about `maxTicks` ticks. A degenerate range (`dataMin === dataMax`)
- * is widened by 1 so the axis is non-empty.
+ * The scale Excel gives a value axis it is left to choose, measured against
+ * Excel's own PDF of eight column charts (2026-10-01):
  *
- * @param dataMin  The smallest data value to cover.
- * @param dataMax  The largest data value to cover.
- * @param maxTicks Target upper bound on tick count (default 6).
+ *  - the ends: values all of one sign put the axis's near end at zero —
+ *    unless their spread is under a sixth of the largest of them, when it
+ *    stops half a spread short of the nearest (93…97 runs from 91) — and the
+ *    far end, like both ends of a range across zero, takes 5% of the spread
+ *    beyond the data before it is rounded out to the step;
+ *  - the step: the smallest 1, 2 or 5 × 10ⁿ that leaves at most ten intervals
+ *    (`maxIntervals`), whatever the chart's height — 3 750 runs 0…4 000 by 500
+ *    on a 150pt chart as on a 400pt one. Only an axis too short to hold the
+ *    labels asks for fewer, and the caller says so.
+ *
+ * Every case of the probe lands where Excel puts it: −1…1.2 on −1.5…1.5 by
+ * 0.5, 0.3…4.7 on 0…5 by 0.5, 120…950 on 0…1 000 by 100, 0.012…0.047 on
+ * 0…0.05 by 0.005. Heckbert's nice numbers with a budget of ticks by height
+ * stepped the budget chart by 1 000 and started 93…97 at zero.
+ *
+ * @param dataMin      The smallest value to cover.
+ * @param dataMax      The largest value to cover.
+ * @param maxIntervals At most this many steps between the ends (default 10).
  * @returns The rounded min/max and tick step.
  */
-export declare function niceScale(dataMin: number, dataMax: number, maxTicks?: number): Scale;
+export declare function niceScale(dataMin: number, dataMax: number, maxIntervals?: number): Scale;
 /**
  * Format an axis tick value, choosing decimal places from the tick `step` so
  * `0.25`-spaced ticks read `0.25` while integer steps drop the fraction.