@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/CHANGELOG.md +66 -0
- package/README.md +28 -2
- package/dist/index.cjs +353 -103
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +129 -27
- package/dist/index.d.ts +129 -27
- package/dist/index.js +349 -105
- package/dist/index.js.map +1 -1
- package/package.json +7 -1
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
|
-
/**
|
|
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 (`
|
|
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
|
|
342
|
-
*
|
|
343
|
-
* silence, are the two worse answers.
|
|
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 = "
|
|
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: `
|
|
348
|
-
*
|
|
349
|
-
* a
|
|
350
|
-
* nothing here trusts its shape. A walk, not a recursion: the nesting is
|
|
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
|
|
468
|
-
* `
|
|
469
|
-
*
|
|
470
|
-
*
|
|
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[],
|
|
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
|
-
/**
|
|
556
|
-
|
|
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}
|
|
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
|
-
/**
|
|
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 (`
|
|
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
|
|
342
|
-
*
|
|
343
|
-
* silence, are the two worse answers.
|
|
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 = "
|
|
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: `
|
|
348
|
-
*
|
|
349
|
-
* a
|
|
350
|
-
* nothing here trusts its shape. A walk, not a recursion: the nesting is
|
|
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
|
|
468
|
-
* `
|
|
469
|
-
*
|
|
470
|
-
*
|
|
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[],
|
|
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
|
-
/**
|
|
556
|
-
|
|
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}
|
|
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 };
|