@particle-academy/last-word-ui 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as react from 'react';
2
- import { CSSProperties } from 'react';
2
+ import { ReactNode, CSSProperties } from 'react';
3
3
 
4
4
  /**
5
5
  * The last-word Doc as this viewer reads it.
@@ -156,6 +156,8 @@ interface ChartBlock {
156
156
  }
157
157
  interface PageBreakBlock {
158
158
  type: "pageBreak";
159
+ /** Change the page from here on: see `docStretches()`. */
160
+ page?: Page;
159
161
  }
160
162
  interface HrBlock {
161
163
  type: "hr";
@@ -222,12 +224,49 @@ interface Doc {
222
224
  [key: string]: unknown;
223
225
  }
224
226
 
227
+ /** What `renderChart` is given for one chart block. */
228
+ interface ChartRenderArgs {
229
+ /** The block as it is in the Doc. */
230
+ block: ChartBlock;
231
+ /**
232
+ * The block's ECharts option laid out for a page: a transparent background,
233
+ * last-word's default palette, no animation and a grid that keeps axis labels
234
+ * inside the box. Every key the block sets wins.
235
+ */
236
+ option: Record<string, unknown>;
237
+ /** CSS px at 100% (before the page's scale), as the page lays the block out. */
238
+ width: number;
239
+ height: number;
240
+ /** The chart's title, or its alt text, or "". */
241
+ title: string;
242
+ }
243
+ /**
244
+ * Draws a chart block instead of the built-in renderer. Return `undefined` to
245
+ * leave that chart to the default (fancy-echarts when installed, else the
246
+ * placeholder). Draw at exactly `width` x `height`: the page was laid out for it.
247
+ */
248
+ type RenderChart = (chart: ChartRenderArgs) => ReactNode | undefined;
249
+ /** last-word's default chart palette (Office's), so an unstyled chart is the colour it is in Word. */
250
+ declare const OFFICE_PALETTE: string[];
251
+ /**
252
+ * A block's option as a page draws it. Defaults only: the block's own keys win.
253
+ * The sheet is white paper in every app colour scheme, so the background is
254
+ * transparent (the paper shows through), and animation is off so a printed or
255
+ * captured page is never caught mid-transition.
256
+ */
257
+ declare function pageChartOption(option: unknown): Record<string, unknown>;
258
+
225
259
  interface DocViewerLayout {
226
260
  /** Number of pages the document laid out to. */
227
261
  pages: number;
228
- /** Page size in points, orientation applied. */
262
+ /** The first page's size in points, orientation applied. */
229
263
  pageWidth: number;
230
264
  pageHeight: number;
265
+ /** Every page's size, when the document's page changes partway. */
266
+ pageSizes?: Array<{
267
+ width: number;
268
+ height: number;
269
+ }>;
231
270
  /** The scale the pages are drawn at. */
232
271
  scale: number;
233
272
  /**
@@ -240,7 +279,7 @@ interface DocViewerLayout {
240
279
  font: ViewerFont;
241
280
  /**
242
281
  * JSON Pointers to page layout the document asks for and this viewer does not
243
- * show (`pageBreak.page`, page keys straight on a break, a top-level `sections`).
282
+ * show (`page` on a nested break, page keys straight on a break, a top-level `sections`).
244
283
  * Absent when there is none. The visible notice says the same thing.
245
284
  */
246
285
  notShown?: string[];
@@ -282,6 +321,14 @@ interface DocViewerProps {
282
321
  * `@particle-academy/last-word-ui/styles.css` instead.
283
322
  */
284
323
  injectStyles?: boolean;
324
+ /**
325
+ * Draws a chart block instead of the default, given the block, its option laid
326
+ * out for a page, and its size in CSS px. Return `undefined` to leave a chart
327
+ * to the default. The default draws with `@particle-academy/fancy-echarts`'
328
+ * `EChart` when it is installed (an optional peer) and a sized placeholder
329
+ * when it is not.
330
+ */
331
+ renderChart?: RenderChart;
285
332
  id?: string;
286
333
  className?: string;
287
334
  style?: CSSProperties;
@@ -296,13 +343,15 @@ interface DocViewerProps {
296
343
  * document order); each footnote `data-footnote`; bands `data-lw-band`, with
297
344
  * `data-lw-band-variant` naming the one drawn (`default`, `first`, `even`);
298
345
  * `data-lw-layout-notice` when the document asks for page layout it does not show.
346
+ * A `pageBreak` carrying `page` changes the page from there on, each page drawn and
347
+ * its text measured at its own size.
299
348
  *
300
349
  * Header and footer text takes field tokens -- `{page}`, `{pages}`,
301
350
  * `{section}`, `{sectionpages}`, `{author}`, `{title}`, `{filename}`, `{date}`,
302
351
  * `{time}`, `{date:FORMAT}`, `{time:FORMAT}` -- drawn as plain text. In the
303
352
  * body they stay literal.
304
353
  */
305
- declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
354
+ declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, renderChart, id, className, style, }: DocViewerProps): react.JSX.Element;
306
355
 
307
356
  /** The package-unique family the bundled Carlito is declared under (`fonts.ts`). */
308
357
  declare const CARLITO_FAMILY = "LW Carlito";
@@ -338,16 +387,18 @@ declare function carlitoFaces(doc: Doc): string[];
338
387
  declare function docFromReader(output: unknown): Doc;
339
388
 
340
389
  /**
341
- * What the viewer says when a document asks for more than one page setup. It draws
342
- * one until per-page geometry lands; drawing nothing, or drawing it wrong in
343
- * silence, are the two worse answers. The same words as fancy-docs.
390
+ * What the viewer says when a document asks for page settings in a form it does not
391
+ * honour. A `page` on a top-level break is drawn; what is left here is what the writers
392
+ * refuse too. Drawing nothing, or drawing it wrong in silence, are the two worse answers.
393
+ * The same words as fancy-docs.
344
394
  */
345
- declare const LAYOUT_NOTICE = "Mixed page orientation isn't shown yet. This document asks for different page settings partway through; every page here uses the document's one page setup.";
395
+ declare const LAYOUT_NOTICE = "Some page settings in this document aren't shown. It sets them somewhere they don't apply: on a page break directly, in a quote or a table cell, or under a sections key.";
346
396
  /**
347
- * JSON Pointers to what this viewer ignores about page layout: `pageBreak.page`,
348
- * the near-miss keys on a break and a top-level `sections`, at any depth. Empty for
349
- * a document with one page setup. The Doc arrives as JSON from any writer, so
350
- * nothing here trusts its shape. A walk, not a recursion: the nesting is the file's.
397
+ * JSON Pointers to what this viewer ignores about page layout: `page` on a nested
398
+ * break or one that is not an object, a background on a break, the near-miss keys on a
399
+ * break and a top-level `sections`, at any depth. The Doc arrives as JSON from any
400
+ * writer, so nothing here trusts its shape. A walk, not a recursion: the nesting is
401
+ * the file's.
351
402
  */
352
403
  declare function unshownLayout(doc: Doc): string[];
353
404
 
@@ -405,6 +456,12 @@ interface TableItem {
405
456
  }
406
457
  interface BreakItem {
407
458
  type: "break";
459
+ /**
460
+ * This break starts a run of pages of another shape, and these are its heights.
461
+ * `firstPageHeight` is its first page when that page is odd and
462
+ * `firstEvenPageHeight` when even: the pages before it decide which.
463
+ */
464
+ stretch?: Pick<PackOptions, "pageHeight" | "firstPageHeight" | "firstEvenPageHeight" | "evenPageHeight">;
408
465
  }
409
466
  type PackItem = BlockItem | TableItem | BreakItem;
410
467
  interface PackOptions {
@@ -423,6 +480,12 @@ interface PackOptions {
423
480
  * `pageHeight` when absent. Page 1 is odd, so it never takes this.
424
481
  */
425
482
  evenPageHeight?: number;
483
+ /**
484
+ * The body height of a stretch's first page when that page is even. Page 1 is
485
+ * odd, so the first stretch never takes it. `firstPageHeight` does not stand in:
486
+ * absent, the page is an ordinary even page.
487
+ */
488
+ firstEvenPageHeight?: number;
426
489
  /**
427
490
  * Height of the separator rule above a page's footnotes, reserved once on
428
491
  * any page that holds at least one note. 0 when absent.
@@ -462,15 +525,18 @@ interface PageLayout {
462
525
  used: number;
463
526
  /** The body height this page had to fill (`pageCapacity()` for its index). */
464
527
  capacity: number;
528
+ /** Which stretch it is in, 0-based. Absent in the first. */
529
+ stretch?: number;
465
530
  }
466
531
  /**
467
- * The body height of the page at 0-based `index`: page 1 takes
468
- * `firstPageHeight`, even pages (odd indices) `evenPageHeight`, the rest
469
- * `pageHeight`. A variant that is absent, non-finite or not positive falls
470
- * back to `pageHeight`. At least 1, so a page always makes progress.
532
+ * The body height of the page at 0-based `index`, in a stretch whose first page is at
533
+ * `start`: that first page takes `firstPageHeight` (`firstEvenPageHeight` on an even
534
+ * page), even pages (odd indices) `evenPageHeight`, the rest `pageHeight`. A variant
535
+ * that is absent, non-finite or not positive falls back. At least 1, so a page always
536
+ * makes progress.
471
537
  */
472
- declare function pageCapacity(options: PackOptions, index: number): number;
473
- declare function paginate(items: PackItem[], options: PackOptions): PageLayout[];
538
+ declare function pageCapacity(options: PackOptions, index: number, start?: number): number;
539
+ declare function paginate(items: PackItem[], initial: PackOptions): PageLayout[];
474
540
 
475
541
  /**
476
542
  * Paper sizes in points, portrait. A4 is 11906 x 16838 twips, which is what
@@ -552,19 +618,25 @@ declare function bodyBox(g: PageGeometry, headerHeight: number, footerHeight: nu
552
618
  type BandKind = "header" | "footer";
553
619
  /** Which of a kind's bands applies: the default, the first-page or the even-page one. */
554
620
  type BandSlot = "default" | "first" | "even";
555
- /** Page 1, an even page, or an odd page after the first. */
556
- type PageClass = "first" | "even" | "odd";
621
+ /**
622
+ * Page 1 or a stretch's first page, an even page, or an odd page after the first.
623
+ * `firstEven` is a stretch's first page on an even number: its first band when it has
624
+ * one, else its even band, per kind.
625
+ */
626
+ type PageClass = "first" | "even" | "odd" | "firstEven";
557
627
  /** Measured band heights per kind and slot, in any one unit; 0 when absent or blank. */
558
628
  type BandHeights = Record<BandKind, Record<BandSlot, number>>;
559
629
  /** The class of the page at 0-based `index`. */
560
630
  declare function pageClass(index: number): PageClass;
631
+ /** The class of the page at 0-based `index`, in a stretch whose first page is at `start`. */
632
+ declare function pageClassIn(index: number, start: number): PageClass;
561
633
  /** The slot a page class draws for one kind: its variant when that is set, else the default. */
562
634
  declare function bandSlot(page: Page | undefined, kind: BandKind, cls: PageClass): BandSlot;
563
635
  /**
564
636
  * The band the page at 0-based `index` draws for `kind`, or null when it
565
637
  * draws none (no band, or a blank variant).
566
638
  */
567
- declare function pageBand(page: Page | undefined, kind: BandKind, index: number): Band | BlocksBand | null;
639
+ declare function pageBand(page: Page | undefined, kind: BandKind, index: number, start?: number): Band | BlocksBand | null;
568
640
  /**
569
641
  * The body box of each page class from the measured band heights (points):
570
642
  * each class uses the header and footer it actually draws, so a tall
@@ -572,6 +644,39 @@ declare function pageBand(page: Page | undefined, kind: BandKind, index: number)
572
644
  */
573
645
  declare function pageBodyBoxes(g: PageGeometry, page: Page | undefined, heights: BandHeights): Record<PageClass, BodyBox>;
574
646
 
647
+ /**
648
+ * A document's runs of pages of one setup: what is before the first `pageBreak`
649
+ * carrying a `page`, then what follows each one. Word calls each a section. A plain
650
+ * break, or one nested in a quote or a table cell, starts no stretch. The same reading
651
+ * as last-word and fine-print's `Schema::stretches()`.
652
+ */
653
+ interface Stretch {
654
+ /** The page as this stretch sees it: margins merged, every other key replaced whole. */
655
+ page: Page | undefined;
656
+ geometry: PageGeometry;
657
+ /** Index of the break that starts it; null for the first. */
658
+ breakAt: number | null;
659
+ }
660
+ declare function docStretches(doc: Doc): Stretch[];
661
+ /** Which stretch each top-level block is in. A break carrying `page` opens the one after it. */
662
+ declare function blockStretches(stretches: Stretch[], count: number): number[];
663
+ interface PackInput {
664
+ items: PackItem[];
665
+ options: PackOptions;
666
+ /** The body box of each page class, per stretch. */
667
+ boxes: Record<PageClass, BodyBox>[];
668
+ }
669
+ /**
670
+ * What the packer is given: the first stretch's heights as its options, and each later
671
+ * stretch's on the break that starts it, because which page class its first page falls
672
+ * in depends on how many pages the stretches before it took.
673
+ */
674
+ declare function packInput(stretches: Stretch[], measured: {
675
+ items: PackItem[];
676
+ stretchBands: BandHeights[];
677
+ footnoteSeparator: number;
678
+ }): PackInput;
679
+
575
680
  /**
576
681
  * The live values a header or footer's field tokens take on one page.
577
682
  *
@@ -583,12 +688,9 @@ interface PageFields {
583
688
  /** 1-based. */
584
689
  page: number;
585
690
  pages: number;
586
- /**
587
- * `{section}`. A last-word Doc is ONE section, so this is 1 unless a caller
588
- * says otherwise.
589
- */
691
+ /** `{section}`: which stretch the page is in, 1-based, as Word's SECTION. 1 when absent. */
590
692
  section?: number;
591
- /** `{sectionpages}`. The Doc is one section, so the page total when absent. */
693
+ /** `{sectionpages}`: the pages of that stretch, as Word's SECTIONPAGES. The page total when absent. */
592
694
  sectionPages?: number;
593
695
  /** `{author}`: `doc.meta.author`. Empty when absent. */
594
696
  author?: string;
@@ -642,4 +744,4 @@ interface FootnoteNumbering {
642
744
  */
643
745
  declare function numberFootnotes(doc: Doc): FootnoteNumbering;
644
746
 
645
- export { type Align, type Band, type BandHeights, type BandKind, type BandSlot, type Block, type BlockFragment, type BlockItem, type BlocksBand, type BodyBox, type Border, type BorderStyle, type BoxBorders, type BoxSides, type BreakItem, CARLITO_FACES, CARLITO_FAMILY, type ChartBlock, type CodeBlock, type Doc, type DocMeta, DocViewer, type DocViewerLayout, type DocViewerProps, FONT_LOAD_TIMEOUT_MS, type Footnote, type FootnoteMark, type FootnoteNumbering, type Fragment, type HeadingBlock, type HrBlock, type ImageBlock, LAYOUT_NOTICE, type ListBlock, type ListItem, type Orientation, PAGE_BAND_DISTANCE_DEFAULT, PAGE_MARGIN_DEFAULT, PAGE_SIZES_PT, PX_PER_PT, type PackItem, type PackOptions, type Page, type PageBreakBlock, type PageClass, type PageFields, type PageGeometry, type PageLayout, type PageMargins, type PageSize, type ParagraphBlock, type ParagraphProps, type QuoteBlock, type ResolvedMargins, type Run, type TableBlock, type TableBorders, type TableCell, type TableFragment, type TableItem, type TableRow, type TableRowItem, type VAlign, type ViewerFont, bandSlot, bodyBox, carlitoFaces, docFromReader, fontFaceCss, formatDatePicture, numberFootnotes, pageBand, pageBodyBoxes, pageCapacity, pageClass, pageGeometry, pageMargins, paginate, resolveNow, substituteFields, unshownLayout };
747
+ export { type Align, type Band, type BandHeights, type BandKind, type BandSlot, type Block, type BlockFragment, type BlockItem, type BlocksBand, type BodyBox, type Border, type BorderStyle, type BoxBorders, type BoxSides, type BreakItem, CARLITO_FACES, CARLITO_FAMILY, type ChartBlock, type ChartRenderArgs, type CodeBlock, type Doc, type DocMeta, DocViewer, type DocViewerLayout, type DocViewerProps, FONT_LOAD_TIMEOUT_MS, type Footnote, type FootnoteMark, type FootnoteNumbering, type Fragment, type HeadingBlock, type HrBlock, type ImageBlock, LAYOUT_NOTICE, type ListBlock, type ListItem, OFFICE_PALETTE, type Orientation, PAGE_BAND_DISTANCE_DEFAULT, PAGE_MARGIN_DEFAULT, PAGE_SIZES_PT, PX_PER_PT, type PackInput, type PackItem, type PackOptions, type Page, type PageBreakBlock, type PageClass, type PageFields, type PageGeometry, type PageLayout, type PageMargins, type PageSize, type ParagraphBlock, type ParagraphProps, type QuoteBlock, type RenderChart, type ResolvedMargins, type Run, type Stretch, type TableBlock, type TableBorders, type TableCell, type TableFragment, type TableItem, type TableRow, type TableRowItem, type VAlign, type ViewerFont, bandSlot, blockStretches, bodyBox, carlitoFaces, docFromReader, docStretches, fontFaceCss, formatDatePicture, numberFootnotes, packInput, pageBand, pageBodyBoxes, pageCapacity, pageChartOption, pageClass, pageClassIn, pageGeometry, pageMargins, paginate, resolveNow, substituteFields, unshownLayout };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as react from 'react';
2
- import { CSSProperties } from 'react';
2
+ import { ReactNode, CSSProperties } from 'react';
3
3
 
4
4
  /**
5
5
  * The last-word Doc as this viewer reads it.
@@ -156,6 +156,8 @@ interface ChartBlock {
156
156
  }
157
157
  interface PageBreakBlock {
158
158
  type: "pageBreak";
159
+ /** Change the page from here on: see `docStretches()`. */
160
+ page?: Page;
159
161
  }
160
162
  interface HrBlock {
161
163
  type: "hr";
@@ -222,12 +224,49 @@ interface Doc {
222
224
  [key: string]: unknown;
223
225
  }
224
226
 
227
+ /** What `renderChart` is given for one chart block. */
228
+ interface ChartRenderArgs {
229
+ /** The block as it is in the Doc. */
230
+ block: ChartBlock;
231
+ /**
232
+ * The block's ECharts option laid out for a page: a transparent background,
233
+ * last-word's default palette, no animation and a grid that keeps axis labels
234
+ * inside the box. Every key the block sets wins.
235
+ */
236
+ option: Record<string, unknown>;
237
+ /** CSS px at 100% (before the page's scale), as the page lays the block out. */
238
+ width: number;
239
+ height: number;
240
+ /** The chart's title, or its alt text, or "". */
241
+ title: string;
242
+ }
243
+ /**
244
+ * Draws a chart block instead of the built-in renderer. Return `undefined` to
245
+ * leave that chart to the default (fancy-echarts when installed, else the
246
+ * placeholder). Draw at exactly `width` x `height`: the page was laid out for it.
247
+ */
248
+ type RenderChart = (chart: ChartRenderArgs) => ReactNode | undefined;
249
+ /** last-word's default chart palette (Office's), so an unstyled chart is the colour it is in Word. */
250
+ declare const OFFICE_PALETTE: string[];
251
+ /**
252
+ * A block's option as a page draws it. Defaults only: the block's own keys win.
253
+ * The sheet is white paper in every app colour scheme, so the background is
254
+ * transparent (the paper shows through), and animation is off so a printed or
255
+ * captured page is never caught mid-transition.
256
+ */
257
+ declare function pageChartOption(option: unknown): Record<string, unknown>;
258
+
225
259
  interface DocViewerLayout {
226
260
  /** Number of pages the document laid out to. */
227
261
  pages: number;
228
- /** Page size in points, orientation applied. */
262
+ /** The first page's size in points, orientation applied. */
229
263
  pageWidth: number;
230
264
  pageHeight: number;
265
+ /** Every page's size, when the document's page changes partway. */
266
+ pageSizes?: Array<{
267
+ width: number;
268
+ height: number;
269
+ }>;
231
270
  /** The scale the pages are drawn at. */
232
271
  scale: number;
233
272
  /**
@@ -240,7 +279,7 @@ interface DocViewerLayout {
240
279
  font: ViewerFont;
241
280
  /**
242
281
  * JSON Pointers to page layout the document asks for and this viewer does not
243
- * show (`pageBreak.page`, page keys straight on a break, a top-level `sections`).
282
+ * show (`page` on a nested break, page keys straight on a break, a top-level `sections`).
244
283
  * Absent when there is none. The visible notice says the same thing.
245
284
  */
246
285
  notShown?: string[];
@@ -282,6 +321,14 @@ interface DocViewerProps {
282
321
  * `@particle-academy/last-word-ui/styles.css` instead.
283
322
  */
284
323
  injectStyles?: boolean;
324
+ /**
325
+ * Draws a chart block instead of the default, given the block, its option laid
326
+ * out for a page, and its size in CSS px. Return `undefined` to leave a chart
327
+ * to the default. The default draws with `@particle-academy/fancy-echarts`'
328
+ * `EChart` when it is installed (an optional peer) and a sized placeholder
329
+ * when it is not.
330
+ */
331
+ renderChart?: RenderChart;
285
332
  id?: string;
286
333
  className?: string;
287
334
  style?: CSSProperties;
@@ -296,13 +343,15 @@ interface DocViewerProps {
296
343
  * document order); each footnote `data-footnote`; bands `data-lw-band`, with
297
344
  * `data-lw-band-variant` naming the one drawn (`default`, `first`, `even`);
298
345
  * `data-lw-layout-notice` when the document asks for page layout it does not show.
346
+ * A `pageBreak` carrying `page` changes the page from there on, each page drawn and
347
+ * its text measured at its own size.
299
348
  *
300
349
  * Header and footer text takes field tokens -- `{page}`, `{pages}`,
301
350
  * `{section}`, `{sectionpages}`, `{author}`, `{title}`, `{filename}`, `{date}`,
302
351
  * `{time}`, `{date:FORMAT}`, `{time:FORMAT}` -- drawn as plain text. In the
303
352
  * body they stay literal.
304
353
  */
305
- declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
354
+ declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, renderChart, id, className, style, }: DocViewerProps): react.JSX.Element;
306
355
 
307
356
  /** The package-unique family the bundled Carlito is declared under (`fonts.ts`). */
308
357
  declare const CARLITO_FAMILY = "LW Carlito";
@@ -338,16 +387,18 @@ declare function carlitoFaces(doc: Doc): string[];
338
387
  declare function docFromReader(output: unknown): Doc;
339
388
 
340
389
  /**
341
- * What the viewer says when a document asks for more than one page setup. It draws
342
- * one until per-page geometry lands; drawing nothing, or drawing it wrong in
343
- * silence, are the two worse answers. The same words as fancy-docs.
390
+ * What the viewer says when a document asks for page settings in a form it does not
391
+ * honour. A `page` on a top-level break is drawn; what is left here is what the writers
392
+ * refuse too. Drawing nothing, or drawing it wrong in silence, are the two worse answers.
393
+ * The same words as fancy-docs.
344
394
  */
345
- declare const LAYOUT_NOTICE = "Mixed page orientation isn't shown yet. This document asks for different page settings partway through; every page here uses the document's one page setup.";
395
+ declare const LAYOUT_NOTICE = "Some page settings in this document aren't shown. It sets them somewhere they don't apply: on a page break directly, in a quote or a table cell, or under a sections key.";
346
396
  /**
347
- * JSON Pointers to what this viewer ignores about page layout: `pageBreak.page`,
348
- * the near-miss keys on a break and a top-level `sections`, at any depth. Empty for
349
- * a document with one page setup. The Doc arrives as JSON from any writer, so
350
- * nothing here trusts its shape. A walk, not a recursion: the nesting is the file's.
397
+ * JSON Pointers to what this viewer ignores about page layout: `page` on a nested
398
+ * break or one that is not an object, a background on a break, the near-miss keys on a
399
+ * break and a top-level `sections`, at any depth. The Doc arrives as JSON from any
400
+ * writer, so nothing here trusts its shape. A walk, not a recursion: the nesting is
401
+ * the file's.
351
402
  */
352
403
  declare function unshownLayout(doc: Doc): string[];
353
404
 
@@ -405,6 +456,12 @@ interface TableItem {
405
456
  }
406
457
  interface BreakItem {
407
458
  type: "break";
459
+ /**
460
+ * This break starts a run of pages of another shape, and these are its heights.
461
+ * `firstPageHeight` is its first page when that page is odd and
462
+ * `firstEvenPageHeight` when even: the pages before it decide which.
463
+ */
464
+ stretch?: Pick<PackOptions, "pageHeight" | "firstPageHeight" | "firstEvenPageHeight" | "evenPageHeight">;
408
465
  }
409
466
  type PackItem = BlockItem | TableItem | BreakItem;
410
467
  interface PackOptions {
@@ -423,6 +480,12 @@ interface PackOptions {
423
480
  * `pageHeight` when absent. Page 1 is odd, so it never takes this.
424
481
  */
425
482
  evenPageHeight?: number;
483
+ /**
484
+ * The body height of a stretch's first page when that page is even. Page 1 is
485
+ * odd, so the first stretch never takes it. `firstPageHeight` does not stand in:
486
+ * absent, the page is an ordinary even page.
487
+ */
488
+ firstEvenPageHeight?: number;
426
489
  /**
427
490
  * Height of the separator rule above a page's footnotes, reserved once on
428
491
  * any page that holds at least one note. 0 when absent.
@@ -462,15 +525,18 @@ interface PageLayout {
462
525
  used: number;
463
526
  /** The body height this page had to fill (`pageCapacity()` for its index). */
464
527
  capacity: number;
528
+ /** Which stretch it is in, 0-based. Absent in the first. */
529
+ stretch?: number;
465
530
  }
466
531
  /**
467
- * The body height of the page at 0-based `index`: page 1 takes
468
- * `firstPageHeight`, even pages (odd indices) `evenPageHeight`, the rest
469
- * `pageHeight`. A variant that is absent, non-finite or not positive falls
470
- * back to `pageHeight`. At least 1, so a page always makes progress.
532
+ * The body height of the page at 0-based `index`, in a stretch whose first page is at
533
+ * `start`: that first page takes `firstPageHeight` (`firstEvenPageHeight` on an even
534
+ * page), even pages (odd indices) `evenPageHeight`, the rest `pageHeight`. A variant
535
+ * that is absent, non-finite or not positive falls back. At least 1, so a page always
536
+ * makes progress.
471
537
  */
472
- declare function pageCapacity(options: PackOptions, index: number): number;
473
- declare function paginate(items: PackItem[], options: PackOptions): PageLayout[];
538
+ declare function pageCapacity(options: PackOptions, index: number, start?: number): number;
539
+ declare function paginate(items: PackItem[], initial: PackOptions): PageLayout[];
474
540
 
475
541
  /**
476
542
  * Paper sizes in points, portrait. A4 is 11906 x 16838 twips, which is what
@@ -552,19 +618,25 @@ declare function bodyBox(g: PageGeometry, headerHeight: number, footerHeight: nu
552
618
  type BandKind = "header" | "footer";
553
619
  /** Which of a kind's bands applies: the default, the first-page or the even-page one. */
554
620
  type BandSlot = "default" | "first" | "even";
555
- /** Page 1, an even page, or an odd page after the first. */
556
- type PageClass = "first" | "even" | "odd";
621
+ /**
622
+ * Page 1 or a stretch's first page, an even page, or an odd page after the first.
623
+ * `firstEven` is a stretch's first page on an even number: its first band when it has
624
+ * one, else its even band, per kind.
625
+ */
626
+ type PageClass = "first" | "even" | "odd" | "firstEven";
557
627
  /** Measured band heights per kind and slot, in any one unit; 0 when absent or blank. */
558
628
  type BandHeights = Record<BandKind, Record<BandSlot, number>>;
559
629
  /** The class of the page at 0-based `index`. */
560
630
  declare function pageClass(index: number): PageClass;
631
+ /** The class of the page at 0-based `index`, in a stretch whose first page is at `start`. */
632
+ declare function pageClassIn(index: number, start: number): PageClass;
561
633
  /** The slot a page class draws for one kind: its variant when that is set, else the default. */
562
634
  declare function bandSlot(page: Page | undefined, kind: BandKind, cls: PageClass): BandSlot;
563
635
  /**
564
636
  * The band the page at 0-based `index` draws for `kind`, or null when it
565
637
  * draws none (no band, or a blank variant).
566
638
  */
567
- declare function pageBand(page: Page | undefined, kind: BandKind, index: number): Band | BlocksBand | null;
639
+ declare function pageBand(page: Page | undefined, kind: BandKind, index: number, start?: number): Band | BlocksBand | null;
568
640
  /**
569
641
  * The body box of each page class from the measured band heights (points):
570
642
  * each class uses the header and footer it actually draws, so a tall
@@ -572,6 +644,39 @@ declare function pageBand(page: Page | undefined, kind: BandKind, index: number)
572
644
  */
573
645
  declare function pageBodyBoxes(g: PageGeometry, page: Page | undefined, heights: BandHeights): Record<PageClass, BodyBox>;
574
646
 
647
+ /**
648
+ * A document's runs of pages of one setup: what is before the first `pageBreak`
649
+ * carrying a `page`, then what follows each one. Word calls each a section. A plain
650
+ * break, or one nested in a quote or a table cell, starts no stretch. The same reading
651
+ * as last-word and fine-print's `Schema::stretches()`.
652
+ */
653
+ interface Stretch {
654
+ /** The page as this stretch sees it: margins merged, every other key replaced whole. */
655
+ page: Page | undefined;
656
+ geometry: PageGeometry;
657
+ /** Index of the break that starts it; null for the first. */
658
+ breakAt: number | null;
659
+ }
660
+ declare function docStretches(doc: Doc): Stretch[];
661
+ /** Which stretch each top-level block is in. A break carrying `page` opens the one after it. */
662
+ declare function blockStretches(stretches: Stretch[], count: number): number[];
663
+ interface PackInput {
664
+ items: PackItem[];
665
+ options: PackOptions;
666
+ /** The body box of each page class, per stretch. */
667
+ boxes: Record<PageClass, BodyBox>[];
668
+ }
669
+ /**
670
+ * What the packer is given: the first stretch's heights as its options, and each later
671
+ * stretch's on the break that starts it, because which page class its first page falls
672
+ * in depends on how many pages the stretches before it took.
673
+ */
674
+ declare function packInput(stretches: Stretch[], measured: {
675
+ items: PackItem[];
676
+ stretchBands: BandHeights[];
677
+ footnoteSeparator: number;
678
+ }): PackInput;
679
+
575
680
  /**
576
681
  * The live values a header or footer's field tokens take on one page.
577
682
  *
@@ -583,12 +688,9 @@ interface PageFields {
583
688
  /** 1-based. */
584
689
  page: number;
585
690
  pages: number;
586
- /**
587
- * `{section}`. A last-word Doc is ONE section, so this is 1 unless a caller
588
- * says otherwise.
589
- */
691
+ /** `{section}`: which stretch the page is in, 1-based, as Word's SECTION. 1 when absent. */
590
692
  section?: number;
591
- /** `{sectionpages}`. The Doc is one section, so the page total when absent. */
693
+ /** `{sectionpages}`: the pages of that stretch, as Word's SECTIONPAGES. The page total when absent. */
592
694
  sectionPages?: number;
593
695
  /** `{author}`: `doc.meta.author`. Empty when absent. */
594
696
  author?: string;
@@ -642,4 +744,4 @@ interface FootnoteNumbering {
642
744
  */
643
745
  declare function numberFootnotes(doc: Doc): FootnoteNumbering;
644
746
 
645
- export { type Align, type Band, type BandHeights, type BandKind, type BandSlot, type Block, type BlockFragment, type BlockItem, type BlocksBand, type BodyBox, type Border, type BorderStyle, type BoxBorders, type BoxSides, type BreakItem, CARLITO_FACES, CARLITO_FAMILY, type ChartBlock, type CodeBlock, type Doc, type DocMeta, DocViewer, type DocViewerLayout, type DocViewerProps, FONT_LOAD_TIMEOUT_MS, type Footnote, type FootnoteMark, type FootnoteNumbering, type Fragment, type HeadingBlock, type HrBlock, type ImageBlock, LAYOUT_NOTICE, type ListBlock, type ListItem, type Orientation, PAGE_BAND_DISTANCE_DEFAULT, PAGE_MARGIN_DEFAULT, PAGE_SIZES_PT, PX_PER_PT, type PackItem, type PackOptions, type Page, type PageBreakBlock, type PageClass, type PageFields, type PageGeometry, type PageLayout, type PageMargins, type PageSize, type ParagraphBlock, type ParagraphProps, type QuoteBlock, type ResolvedMargins, type Run, type TableBlock, type TableBorders, type TableCell, type TableFragment, type TableItem, type TableRow, type TableRowItem, type VAlign, type ViewerFont, bandSlot, bodyBox, carlitoFaces, docFromReader, fontFaceCss, formatDatePicture, numberFootnotes, pageBand, pageBodyBoxes, pageCapacity, pageClass, pageGeometry, pageMargins, paginate, resolveNow, substituteFields, unshownLayout };
747
+ export { type Align, type Band, type BandHeights, type BandKind, type BandSlot, type Block, type BlockFragment, type BlockItem, type BlocksBand, type BodyBox, type Border, type BorderStyle, type BoxBorders, type BoxSides, type BreakItem, CARLITO_FACES, CARLITO_FAMILY, type ChartBlock, type ChartRenderArgs, type CodeBlock, type Doc, type DocMeta, DocViewer, type DocViewerLayout, type DocViewerProps, FONT_LOAD_TIMEOUT_MS, type Footnote, type FootnoteMark, type FootnoteNumbering, type Fragment, type HeadingBlock, type HrBlock, type ImageBlock, LAYOUT_NOTICE, type ListBlock, type ListItem, OFFICE_PALETTE, type Orientation, PAGE_BAND_DISTANCE_DEFAULT, PAGE_MARGIN_DEFAULT, PAGE_SIZES_PT, PX_PER_PT, type PackInput, type PackItem, type PackOptions, type Page, type PageBreakBlock, type PageClass, type PageFields, type PageGeometry, type PageLayout, type PageMargins, type PageSize, type ParagraphBlock, type ParagraphProps, type QuoteBlock, type RenderChart, type ResolvedMargins, type Run, type Stretch, type TableBlock, type TableBorders, type TableCell, type TableFragment, type TableItem, type TableRow, type TableRowItem, type VAlign, type ViewerFont, bandSlot, blockStretches, bodyBox, carlitoFaces, docFromReader, docStretches, fontFaceCss, formatDatePicture, numberFootnotes, packInput, pageBand, pageBodyBoxes, pageCapacity, pageChartOption, pageClass, pageClassIn, pageGeometry, pageMargins, paginate, resolveNow, substituteFields, unshownLayout };