reamkit 1.30.0 → 1.32.0

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

@@ -6,6 +6,12 @@ export type Alignment = 'left' | 'right' | 'center' | 'both' | 'distribute';
 export type UnderlineStyle = 'none' | 'single' | 'double' | 'thick' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'wave';
 /** Run vertical alignment (`w:vertAlign`): baseline or super/subscript. */
 export type VerticalAlign = 'baseline' | 'superscript' | 'subscript';
+/**
+ * [MS-DOCX] ST_Ligatures — which of a face's OpenType ligatures a run is set
+ * with (`w14:ligatures`): the standard ones (`liga`), the contextual (`clig`),
+ * the historical (`hlig`) and the discretionary (`dlig`), alone or together.
+ */
+export type Ligatures = 'none' | 'standard' | 'contextual' | 'historical' | 'discretional' | 'standardContextual' | 'standardHistorical' | 'contextualHistorical' | 'standardDiscretional' | 'contextualDiscretional' | 'historicalDiscretional' | 'standardContextualHistorical' | 'standardContextualDiscretional' | 'standardHistoricalDiscretional' | 'contextualHistoricalDiscretional' | 'all';
 /**
  * The four script slots of `w:rFonts` (§17.3.2.26). A character picks its font
  * from the slot its Unicode range maps to (ASCII, high-ANSI, complex-script,
@@ -63,6 +69,21 @@ export interface RunProperties {
      * (negative tightens). Word states it in twentieths of a point.
      */
     readonly letterSpacingPt?: Pt;
+    /**
+     * §17.3.2.43 `w:w` — each character set at this share of its own width
+     * (1 is as the face sets it), the glyph itself narrowed or widened.
+     */
+    readonly widthScale?: number;
+    /**
+     * §17.3.2.19 `w:kern` — the run's glyph pairs are KERNED, at this size and
+     * above (0 turns kerning off). Word kerns nothing a run does not ask for.
+     */
+    readonly kerningMinPt?: Pt;
+    /**
+     * [MS-DOCX] `w14:ligatures` — the face's ligatures the run is set with.
+     * Word forms none at all in a document it opens in compatibility mode.
+     */
+    readonly ligatures?: Ligatures;
     /**
      * §21.1.2.3.9 `a:rPr/a:ln` — a line drawn round the glyphs themselves, which
      * DrawingML puts on a run and ISO 32000-1 §9.3.6 calls a text rendering mode
@@ -220,6 +241,24 @@ export interface ParagraphProperties {
      * starts on a fresh page even if there is room on the current one.
      */
     readonly pageBreakBefore?: boolean;
+    /**
+     * ECMA-376 Part 1 §17.3.1.14 — `w:keepNext`. The paragraph stands on the
+     * same page as the start of the one after it: a heading is not left at the
+     * foot of a page with its text on the next.
+     */
+    readonly keepNext?: boolean;
+    /**
+     * ECMA-376 Part 1 §17.3.1.15 — `w:keepLines`. The paragraph's lines stand on
+     * one page, wherever one page holds them all.
+     */
+    readonly keepLines?: boolean;
+    /**
+     * ECMA-376 Part 1 §17.3.1.44 — `w:widowControl`. When on, a page or column
+     * break that would leave the paragraph's first line alone at the foot of one
+     * page, or its last line alone at the head of the next, is moved so that
+     * neither stands alone. Word applies it wherever nothing says otherwise.
+     */
+    readonly widowControl?: boolean;
     /**
      * ECMA-376 §17.3.1.6 — `w:bidi`. Sets the paragraph's base direction to RTL,
      * so the BiDi paragraph embedding level is 1 and default alignment is right.
@@ -692,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
@@ -762,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;
@@ -771,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`
@@ -828,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 {
@@ -861,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.
@@ -907,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).
@@ -1176,6 +1281,13 @@ export interface ShapeTextBody {
     readonly insetRight?: Pt;
     readonly insetBottom?: Pt;
     readonly anchor?: 't' | 'ctr' | 'b';
+    /**
+     * §20.1.2.1.1 `a:bodyPr @wrap="none"` — the lines run as far as their words
+     * do, whatever the box's width. A label placed where a page set it is sized
+     * to the words it was measured from, and set in a face a little wider it
+     * broke inside its one word.
+     */
+    readonly noWrap?: boolean;
     /**
      * §20.1.10.83 ST_TextVerticalType (`a:bodyPr @vert`) — text set along the
      * box's long axis rather than across it. `vert` reads top-to-bottom (turned a
@@ -1384,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';
@@ -1404,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;
@@ -1434,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
@@ -1543,6 +1691,12 @@ export interface SectionProperties {
      * printed with. Absent ⇒ the count carries on from the section before.
      */
     readonly pageNumberStart?: number;
+    /**
+     * §17.6.12 `w:pgNumType w:fmt` — how a PAGE field prints the section's page
+     * numbers (§17.18.59): `lowerRoman` numbers a book's front matter i, ii,
+     * iii before its body starts again at 1. Absent ⇒ decimal.
+     */
+    readonly pageNumberFormat?: NumberingFormat;
     /** §17.6.8 `w:lnNumType` — line numbers printed in the margin beside the text. */
     readonly lineNumbering?: {
         /** Print every `countBy`-th line (default 1). */
@@ -1579,6 +1733,17 @@ export interface SectionProperties {
      * distinguished from `nextPage`.)
      */
     readonly sectionStart?: 'continuous' | 'nextPage' | 'oddPage' | 'evenPage';
+    /**
+     * §17.6.20 `w:textDirection` — which way the section's lines run. `tbRl`
+     * sets each line top to bottom and the next one to the left of it: the
+     * text turned a quarter clockwise on the sheet, which is how a viewer shows
+     * a page turned by `/Rotate 90` whose words stood upright in its box. Word
+     * lays a section out that way for `btLr` as well, so the layout reads both
+     * alike. Only the body's text turns: the headers, the footers and every
+     * drawing anchored to the page keep the sheet's own axes. Absent ⇒ left to
+     * right, top to bottom.
+     */
+    readonly textDirection?: 'tbRl' | 'btLr';
     /**
      * §17.6.5 `w:docGrid` — the line grid a `lines`/`linesAndChars` section rules
      * its text onto, as the pitch in points. Every line of the section's text is
@@ -1681,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.