@particle-academy/last-word-ui 0.1.1 → 0.3.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 +85 -0
- package/README.md +58 -5
- package/dist/index.cjs +1175 -809
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +176 -8
- package/dist/index.d.ts +176 -8
- package/dist/index.js +1164 -811
- package/dist/index.js.map +1 -1
- package/dist/styles.css +28 -0
- package/dist/styles.css.map +1 -1
- package/fonts/Carlito-Bold.ttf +0 -0
- package/fonts/Carlito-BoldItalic.ttf +0 -0
- package/fonts/Carlito-Italic.ttf +0 -0
- package/fonts/Carlito-Regular.ttf +0 -0
- package/fonts/NOTICE +24 -0
- package/fonts/OFL.txt +94 -0
- package/package.json +2 -1
package/dist/index.d.cts
CHANGED
|
@@ -189,11 +189,32 @@ interface Page {
|
|
|
189
189
|
size?: PageSize;
|
|
190
190
|
orientation?: Orientation;
|
|
191
191
|
margins?: PageMargins;
|
|
192
|
+
/** Every page, unless a variant below covers it. */
|
|
192
193
|
header?: Band | BlocksBand;
|
|
193
194
|
footer?: Band | BlocksBand;
|
|
195
|
+
/**
|
|
196
|
+
* Page 1 only, in place of `header` / `footer` (last-word 0.16.0, Word's
|
|
197
|
+
* "Different first page"). `{"blocks": []}` blanks page 1's band.
|
|
198
|
+
*/
|
|
199
|
+
firstHeader?: Band | BlocksBand;
|
|
200
|
+
firstFooter?: Band | BlocksBand;
|
|
201
|
+
/**
|
|
202
|
+
* Even pages (2, 4, ...), in place of `header` / `footer` (last-word 0.16.0,
|
|
203
|
+
* Word's "Different odd and even pages"). `{"blocks": []}` blanks them.
|
|
204
|
+
*/
|
|
205
|
+
evenHeader?: Band | BlocksBand;
|
|
206
|
+
evenFooter?: Band | BlocksBand;
|
|
207
|
+
}
|
|
208
|
+
/** Document properties (last-word 0.16.0). */
|
|
209
|
+
interface DocMeta {
|
|
210
|
+
/** Word's Author property: what an `{author}` field in a band shows. */
|
|
211
|
+
author?: string;
|
|
212
|
+
[key: string]: unknown;
|
|
194
213
|
}
|
|
195
214
|
interface Doc {
|
|
215
|
+
/** The document title: what a `{title}` field in a band shows. */
|
|
196
216
|
title?: string;
|
|
217
|
+
meta?: DocMeta;
|
|
197
218
|
blocks: Block[];
|
|
198
219
|
page?: Page;
|
|
199
220
|
defaultFont?: string;
|
|
@@ -209,7 +230,18 @@ interface DocViewerLayout {
|
|
|
209
230
|
pageHeight: number;
|
|
210
231
|
/** The scale the pages are drawn at. */
|
|
211
232
|
scale: number;
|
|
233
|
+
/**
|
|
234
|
+
* What Calibri and unspecified text was measured in. `"carlito"`: the
|
|
235
|
+
* bundled font, so the page count is the same on every machine (and agrees
|
|
236
|
+
* with last-word's `layout()`). `"fallback"`: it could not load (or the
|
|
237
|
+
* runtime has no FontFaceSet), so the count depends on this machine's fonts.
|
|
238
|
+
* `"unused"`: the document has no such text.
|
|
239
|
+
*/
|
|
240
|
+
font: ViewerFont;
|
|
212
241
|
}
|
|
242
|
+
type ViewerFont = "carlito" | "fallback" | "unused";
|
|
243
|
+
/** How long the viewer waits for the bundled font before laying out without it. */
|
|
244
|
+
declare const FONT_LOAD_TIMEOUT_MS = 3000;
|
|
213
245
|
interface DocViewerProps {
|
|
214
246
|
/** The document: last-word JSON, e.g. `new DocxReader().read(bytes)`. */
|
|
215
247
|
doc: Doc;
|
|
@@ -225,6 +257,17 @@ interface DocViewerProps {
|
|
|
225
257
|
maxScale?: number;
|
|
226
258
|
/** Space between pages, in CSS px. Default 16. */
|
|
227
259
|
gap?: number;
|
|
260
|
+
/**
|
|
261
|
+
* What a `{filename}` field in a header or footer shows. The viewer cannot
|
|
262
|
+
* know the file's name, so it is empty unless given.
|
|
263
|
+
*/
|
|
264
|
+
filename?: string;
|
|
265
|
+
/**
|
|
266
|
+
* The moment `{date}` / `{time}` fields show: a Date or an ISO-8601 string
|
|
267
|
+
* (JSON-friendly). Default: the time of the first render. Pass it for
|
|
268
|
+
* deterministic output (tests, agents, a print preview "as of" a date).
|
|
269
|
+
*/
|
|
270
|
+
now?: Date | string;
|
|
228
271
|
/** Called after every layout with JSON-serializable facts about it. */
|
|
229
272
|
onLayout?: (layout: DocViewerLayout) => void;
|
|
230
273
|
/**
|
|
@@ -244,9 +287,35 @@ interface DocViewerProps {
|
|
|
244
287
|
*
|
|
245
288
|
* Stable handles: the root carries `data-lw-viewer`; each page `data-page`
|
|
246
289
|
* (1-based); each block or fragment of one `data-block` (`b0`, `b1`, ... in
|
|
247
|
-
* document order); each footnote `data-footnote`; bands `data-lw-band
|
|
290
|
+
* document order); each footnote `data-footnote`; bands `data-lw-band`, with
|
|
291
|
+
* `data-lw-band-variant` naming the one drawn (`default`, `first`, `even`).
|
|
292
|
+
*
|
|
293
|
+
* Header and footer text takes field tokens -- `{page}`, `{pages}`,
|
|
294
|
+
* `{section}`, `{sectionpages}`, `{author}`, `{title}`, `{filename}`, `{date}`,
|
|
295
|
+
* `{time}`, `{date:FORMAT}`, `{time:FORMAT}` -- drawn as plain text. In the
|
|
296
|
+
* body they stay literal.
|
|
297
|
+
*/
|
|
298
|
+
declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
|
|
299
|
+
|
|
300
|
+
/** The package-unique family the bundled Carlito is declared under (`fonts.ts`). */
|
|
301
|
+
declare const CARLITO_FAMILY = "LW Carlito";
|
|
302
|
+
|
|
303
|
+
interface CarlitoFace {
|
|
304
|
+
file: string;
|
|
305
|
+
weight: 400 | 700;
|
|
306
|
+
style: "normal" | "italic";
|
|
307
|
+
/** sha256 of the upstream file; a test pins the shipped bytes to it. */
|
|
308
|
+
sha256: string;
|
|
309
|
+
}
|
|
310
|
+
declare const CARLITO_FACES: readonly CarlitoFace[];
|
|
311
|
+
/** The four `@font-face` rules, each face at the URL `url(file)` returns. */
|
|
312
|
+
declare function fontFaceCss(url: (file: string) => string): string;
|
|
313
|
+
/**
|
|
314
|
+
* The faces a document draws in the bundled Carlito, as `FontFaceSet.load()`
|
|
315
|
+
* descriptors, in a fixed order. Only those are fetched: a plain memo never
|
|
316
|
+
* downloads the italic faces.
|
|
248
317
|
*/
|
|
249
|
-
declare function
|
|
318
|
+
declare function carlitoFaces(doc: Doc): string[];
|
|
250
319
|
|
|
251
320
|
/**
|
|
252
321
|
* A Doc from what a last-word reader returned -- `new DocxReader().read(bytes)`
|
|
@@ -318,8 +387,21 @@ interface BreakItem {
|
|
|
318
387
|
}
|
|
319
388
|
type PackItem = BlockItem | TableItem | BreakItem;
|
|
320
389
|
interface PackOptions {
|
|
321
|
-
/**
|
|
390
|
+
/**
|
|
391
|
+
* The body height available on a page no variant below covers: every page
|
|
392
|
+
* when neither is given, else the odd pages after the first.
|
|
393
|
+
*/
|
|
322
394
|
pageHeight: number;
|
|
395
|
+
/**
|
|
396
|
+
* The body height of page 1, when its header or footer differs from the
|
|
397
|
+
* rest (a first-page letterhead). `pageHeight` when absent.
|
|
398
|
+
*/
|
|
399
|
+
firstPageHeight?: number;
|
|
400
|
+
/**
|
|
401
|
+
* The body height of the even pages (2, 4, ...), when their bands differ.
|
|
402
|
+
* `pageHeight` when absent. Page 1 is odd, so it never takes this.
|
|
403
|
+
*/
|
|
404
|
+
evenPageHeight?: number;
|
|
323
405
|
/**
|
|
324
406
|
* Height of the separator rule above a page's footnotes, reserved once on
|
|
325
407
|
* any page that holds at least one note. 0 when absent.
|
|
@@ -357,7 +439,16 @@ interface PageLayout {
|
|
|
357
439
|
footnotes: number[];
|
|
358
440
|
/** Body height used, footnotes and separator included. */
|
|
359
441
|
used: number;
|
|
442
|
+
/** The body height this page had to fill (`pageCapacity()` for its index). */
|
|
443
|
+
capacity: number;
|
|
360
444
|
}
|
|
445
|
+
/**
|
|
446
|
+
* The body height of the page at 0-based `index`: page 1 takes
|
|
447
|
+
* `firstPageHeight`, even pages (odd indices) `evenPageHeight`, the rest
|
|
448
|
+
* `pageHeight`. A variant that is absent, non-finite or not positive falls
|
|
449
|
+
* back to `pageHeight`. At least 1, so a page always makes progress.
|
|
450
|
+
*/
|
|
451
|
+
declare function pageCapacity(options: PackOptions, index: number): number;
|
|
361
452
|
declare function paginate(items: PackItem[], options: PackOptions): PageLayout[];
|
|
362
453
|
|
|
363
454
|
/**
|
|
@@ -421,18 +512,95 @@ declare function pageGeometry(doc: Doc): PageGeometry;
|
|
|
421
512
|
*/
|
|
422
513
|
declare function bodyBox(g: PageGeometry, headerHeight: number, footerHeight: number): BodyBox;
|
|
423
514
|
|
|
424
|
-
/**
|
|
515
|
+
/**
|
|
516
|
+
* Which header and footer each page draws (last-word 0.16.0).
|
|
517
|
+
*
|
|
518
|
+
* `page.header` / `page.footer` are the defaults. Beside them:
|
|
519
|
+
* - `firstHeader` / `firstFooter`: page 1 only (Word's "Different first page");
|
|
520
|
+
* - `evenHeader` / `evenFooter`: pages 2, 4, ... (Word's "Different odd and
|
|
521
|
+
* even pages"), the default then being the odd pages'.
|
|
522
|
+
* A kind with no variant shows its default on those pages too. A variant of
|
|
523
|
+
* `{"blocks": []}` (or a one-line band with no text) is present but empty, so
|
|
524
|
+
* it BLANKS that page's band rather than falling back.
|
|
525
|
+
*
|
|
526
|
+
* So pages fall in three classes -- page 1, even pages, other odd pages --
|
|
527
|
+
* and every page of a class draws the same bands, at the same heights. The
|
|
528
|
+
* packer takes one body height per class (`PackOptions.firstPageHeight` /
|
|
529
|
+
* `evenPageHeight` / `pageHeight`) and `pageBodyBoxes` derives them.
|
|
530
|
+
*/
|
|
531
|
+
type BandKind = "header" | "footer";
|
|
532
|
+
/** Which of a kind's bands applies: the default, the first-page or the even-page one. */
|
|
533
|
+
type BandSlot = "default" | "first" | "even";
|
|
534
|
+
/** Page 1, an even page, or an odd page after the first. */
|
|
535
|
+
type PageClass = "first" | "even" | "odd";
|
|
536
|
+
/** Measured band heights per kind and slot, in any one unit; 0 when absent or blank. */
|
|
537
|
+
type BandHeights = Record<BandKind, Record<BandSlot, number>>;
|
|
538
|
+
/** The class of the page at 0-based `index`. */
|
|
539
|
+
declare function pageClass(index: number): PageClass;
|
|
540
|
+
/** The slot a page class draws for one kind: its variant when that is set, else the default. */
|
|
541
|
+
declare function bandSlot(page: Page | undefined, kind: BandKind, cls: PageClass): BandSlot;
|
|
542
|
+
/**
|
|
543
|
+
* The band the page at 0-based `index` draws for `kind`, or null when it
|
|
544
|
+
* draws none (no band, or a blank variant).
|
|
545
|
+
*/
|
|
546
|
+
declare function pageBand(page: Page | undefined, kind: BandKind, index: number): Band | BlocksBand | null;
|
|
547
|
+
/**
|
|
548
|
+
* The body box of each page class from the measured band heights (points):
|
|
549
|
+
* each class uses the header and footer it actually draws, so a tall
|
|
550
|
+
* first-page letterhead moves only page 1's body down.
|
|
551
|
+
*/
|
|
552
|
+
declare function pageBodyBoxes(g: PageGeometry, page: Page | undefined, heights: BandHeights): Record<PageClass, BodyBox>;
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* The live values a header or footer's field tokens take on one page.
|
|
556
|
+
*
|
|
557
|
+
* Only `page` and `pages` are required, so a 0.1.x caller of
|
|
558
|
+
* `substituteFields(text, { page, pages })` is unchanged; every other value
|
|
559
|
+
* has a documented fallback.
|
|
560
|
+
*/
|
|
425
561
|
interface PageFields {
|
|
426
562
|
/** 1-based. */
|
|
427
563
|
page: number;
|
|
428
564
|
pages: number;
|
|
565
|
+
/**
|
|
566
|
+
* `{section}`. A last-word Doc is ONE section, so this is 1 unless a caller
|
|
567
|
+
* says otherwise.
|
|
568
|
+
*/
|
|
569
|
+
section?: number;
|
|
570
|
+
/** `{sectionpages}`. The Doc is one section, so the page total when absent. */
|
|
571
|
+
sectionPages?: number;
|
|
572
|
+
/** `{author}`: `doc.meta.author`. Empty when absent. */
|
|
573
|
+
author?: string;
|
|
574
|
+
/** `{title}`: the top-level `doc.title` (there is deliberately no `meta.title`). Empty when absent. */
|
|
575
|
+
title?: string;
|
|
576
|
+
/** `{filename}`: the viewer cannot know it, so it is a prop. Empty when absent. */
|
|
577
|
+
filename?: string;
|
|
578
|
+
/** `{date}` / `{time}` are "as of" this moment. The current time when absent. */
|
|
579
|
+
now?: Date;
|
|
429
580
|
}
|
|
430
581
|
/**
|
|
431
|
-
* Text with
|
|
432
|
-
*
|
|
433
|
-
*
|
|
582
|
+
* Text with its field tokens replaced by this page's values -- the PAGE,
|
|
583
|
+
* NUMPAGES, SECTION, SECTIONPAGES, AUTHOR, TITLE, FILENAME, DATE and TIME
|
|
584
|
+
* fields last-word writes into a band. Only in bands: in the body the same
|
|
585
|
+
* characters are literal text, as they are in the written file.
|
|
586
|
+
*
|
|
587
|
+
* Returns a plain string; the caller renders it as a React text node, so a
|
|
588
|
+
* value full of markup (an untrusted author) stays text.
|
|
434
589
|
*/
|
|
435
590
|
declare function substituteFields(text: string, fields: PageFields): string;
|
|
591
|
+
/**
|
|
592
|
+
* The `now` prop as a Date: a Date or an ISO-8601 string (JSON-friendly). A
|
|
593
|
+
* missing or unparseable value is the current time.
|
|
594
|
+
*/
|
|
595
|
+
declare function resolveNow(now: Date | string | undefined | null): Date;
|
|
596
|
+
/**
|
|
597
|
+
* A Word date-time picture, formatted in LOCAL time: d dd ddd dddd, M MM MMM
|
|
598
|
+
* MMMM, yy yyyy, h hh (12-hour), H HH (24-hour), m mm, s ss, am/pm, AM/PM.
|
|
599
|
+
* Text in single quotes is literal (an unterminated quote runs to the end);
|
|
600
|
+
* every other character is literal. Names are English, as Word writes them
|
|
601
|
+
* for an English document. Pure string work: no third-party code, no eval.
|
|
602
|
+
*/
|
|
603
|
+
declare function formatDatePicture(date: Date, picture: string): string;
|
|
436
604
|
|
|
437
605
|
interface FootnoteNumbering {
|
|
438
606
|
/** Run object -> its mark number. Keyed by identity, so the Doc must not be cloned between numbering and render. */
|
|
@@ -453,4 +621,4 @@ interface FootnoteNumbering {
|
|
|
453
621
|
*/
|
|
454
622
|
declare function numberFootnotes(doc: Doc): FootnoteNumbering;
|
|
455
623
|
|
|
456
|
-
export { type Align, type Band, type Block, type BlockFragment, type BlockItem, type BlocksBand, type BodyBox, type Border, type BorderStyle, type BoxBorders, type BoxSides, type BreakItem, type ChartBlock, type CodeBlock, type Doc, DocViewer, type DocViewerLayout, type DocViewerProps, type Footnote, type FootnoteMark, type FootnoteNumbering, type Fragment, type HeadingBlock, type HrBlock, type ImageBlock, 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 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, bodyBox, docFromReader, numberFootnotes, pageGeometry, pageMargins, paginate, substituteFields };
|
|
624
|
+
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, 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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -189,11 +189,32 @@ interface Page {
|
|
|
189
189
|
size?: PageSize;
|
|
190
190
|
orientation?: Orientation;
|
|
191
191
|
margins?: PageMargins;
|
|
192
|
+
/** Every page, unless a variant below covers it. */
|
|
192
193
|
header?: Band | BlocksBand;
|
|
193
194
|
footer?: Band | BlocksBand;
|
|
195
|
+
/**
|
|
196
|
+
* Page 1 only, in place of `header` / `footer` (last-word 0.16.0, Word's
|
|
197
|
+
* "Different first page"). `{"blocks": []}` blanks page 1's band.
|
|
198
|
+
*/
|
|
199
|
+
firstHeader?: Band | BlocksBand;
|
|
200
|
+
firstFooter?: Band | BlocksBand;
|
|
201
|
+
/**
|
|
202
|
+
* Even pages (2, 4, ...), in place of `header` / `footer` (last-word 0.16.0,
|
|
203
|
+
* Word's "Different odd and even pages"). `{"blocks": []}` blanks them.
|
|
204
|
+
*/
|
|
205
|
+
evenHeader?: Band | BlocksBand;
|
|
206
|
+
evenFooter?: Band | BlocksBand;
|
|
207
|
+
}
|
|
208
|
+
/** Document properties (last-word 0.16.0). */
|
|
209
|
+
interface DocMeta {
|
|
210
|
+
/** Word's Author property: what an `{author}` field in a band shows. */
|
|
211
|
+
author?: string;
|
|
212
|
+
[key: string]: unknown;
|
|
194
213
|
}
|
|
195
214
|
interface Doc {
|
|
215
|
+
/** The document title: what a `{title}` field in a band shows. */
|
|
196
216
|
title?: string;
|
|
217
|
+
meta?: DocMeta;
|
|
197
218
|
blocks: Block[];
|
|
198
219
|
page?: Page;
|
|
199
220
|
defaultFont?: string;
|
|
@@ -209,7 +230,18 @@ interface DocViewerLayout {
|
|
|
209
230
|
pageHeight: number;
|
|
210
231
|
/** The scale the pages are drawn at. */
|
|
211
232
|
scale: number;
|
|
233
|
+
/**
|
|
234
|
+
* What Calibri and unspecified text was measured in. `"carlito"`: the
|
|
235
|
+
* bundled font, so the page count is the same on every machine (and agrees
|
|
236
|
+
* with last-word's `layout()`). `"fallback"`: it could not load (or the
|
|
237
|
+
* runtime has no FontFaceSet), so the count depends on this machine's fonts.
|
|
238
|
+
* `"unused"`: the document has no such text.
|
|
239
|
+
*/
|
|
240
|
+
font: ViewerFont;
|
|
212
241
|
}
|
|
242
|
+
type ViewerFont = "carlito" | "fallback" | "unused";
|
|
243
|
+
/** How long the viewer waits for the bundled font before laying out without it. */
|
|
244
|
+
declare const FONT_LOAD_TIMEOUT_MS = 3000;
|
|
213
245
|
interface DocViewerProps {
|
|
214
246
|
/** The document: last-word JSON, e.g. `new DocxReader().read(bytes)`. */
|
|
215
247
|
doc: Doc;
|
|
@@ -225,6 +257,17 @@ interface DocViewerProps {
|
|
|
225
257
|
maxScale?: number;
|
|
226
258
|
/** Space between pages, in CSS px. Default 16. */
|
|
227
259
|
gap?: number;
|
|
260
|
+
/**
|
|
261
|
+
* What a `{filename}` field in a header or footer shows. The viewer cannot
|
|
262
|
+
* know the file's name, so it is empty unless given.
|
|
263
|
+
*/
|
|
264
|
+
filename?: string;
|
|
265
|
+
/**
|
|
266
|
+
* The moment `{date}` / `{time}` fields show: a Date or an ISO-8601 string
|
|
267
|
+
* (JSON-friendly). Default: the time of the first render. Pass it for
|
|
268
|
+
* deterministic output (tests, agents, a print preview "as of" a date).
|
|
269
|
+
*/
|
|
270
|
+
now?: Date | string;
|
|
228
271
|
/** Called after every layout with JSON-serializable facts about it. */
|
|
229
272
|
onLayout?: (layout: DocViewerLayout) => void;
|
|
230
273
|
/**
|
|
@@ -244,9 +287,35 @@ interface DocViewerProps {
|
|
|
244
287
|
*
|
|
245
288
|
* Stable handles: the root carries `data-lw-viewer`; each page `data-page`
|
|
246
289
|
* (1-based); each block or fragment of one `data-block` (`b0`, `b1`, ... in
|
|
247
|
-
* document order); each footnote `data-footnote`; bands `data-lw-band
|
|
290
|
+
* document order); each footnote `data-footnote`; bands `data-lw-band`, with
|
|
291
|
+
* `data-lw-band-variant` naming the one drawn (`default`, `first`, `even`).
|
|
292
|
+
*
|
|
293
|
+
* Header and footer text takes field tokens -- `{page}`, `{pages}`,
|
|
294
|
+
* `{section}`, `{sectionpages}`, `{author}`, `{title}`, `{filename}`, `{date}`,
|
|
295
|
+
* `{time}`, `{date:FORMAT}`, `{time:FORMAT}` -- drawn as plain text. In the
|
|
296
|
+
* body they stay literal.
|
|
297
|
+
*/
|
|
298
|
+
declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
|
|
299
|
+
|
|
300
|
+
/** The package-unique family the bundled Carlito is declared under (`fonts.ts`). */
|
|
301
|
+
declare const CARLITO_FAMILY = "LW Carlito";
|
|
302
|
+
|
|
303
|
+
interface CarlitoFace {
|
|
304
|
+
file: string;
|
|
305
|
+
weight: 400 | 700;
|
|
306
|
+
style: "normal" | "italic";
|
|
307
|
+
/** sha256 of the upstream file; a test pins the shipped bytes to it. */
|
|
308
|
+
sha256: string;
|
|
309
|
+
}
|
|
310
|
+
declare const CARLITO_FACES: readonly CarlitoFace[];
|
|
311
|
+
/** The four `@font-face` rules, each face at the URL `url(file)` returns. */
|
|
312
|
+
declare function fontFaceCss(url: (file: string) => string): string;
|
|
313
|
+
/**
|
|
314
|
+
* The faces a document draws in the bundled Carlito, as `FontFaceSet.load()`
|
|
315
|
+
* descriptors, in a fixed order. Only those are fetched: a plain memo never
|
|
316
|
+
* downloads the italic faces.
|
|
248
317
|
*/
|
|
249
|
-
declare function
|
|
318
|
+
declare function carlitoFaces(doc: Doc): string[];
|
|
250
319
|
|
|
251
320
|
/**
|
|
252
321
|
* A Doc from what a last-word reader returned -- `new DocxReader().read(bytes)`
|
|
@@ -318,8 +387,21 @@ interface BreakItem {
|
|
|
318
387
|
}
|
|
319
388
|
type PackItem = BlockItem | TableItem | BreakItem;
|
|
320
389
|
interface PackOptions {
|
|
321
|
-
/**
|
|
390
|
+
/**
|
|
391
|
+
* The body height available on a page no variant below covers: every page
|
|
392
|
+
* when neither is given, else the odd pages after the first.
|
|
393
|
+
*/
|
|
322
394
|
pageHeight: number;
|
|
395
|
+
/**
|
|
396
|
+
* The body height of page 1, when its header or footer differs from the
|
|
397
|
+
* rest (a first-page letterhead). `pageHeight` when absent.
|
|
398
|
+
*/
|
|
399
|
+
firstPageHeight?: number;
|
|
400
|
+
/**
|
|
401
|
+
* The body height of the even pages (2, 4, ...), when their bands differ.
|
|
402
|
+
* `pageHeight` when absent. Page 1 is odd, so it never takes this.
|
|
403
|
+
*/
|
|
404
|
+
evenPageHeight?: number;
|
|
323
405
|
/**
|
|
324
406
|
* Height of the separator rule above a page's footnotes, reserved once on
|
|
325
407
|
* any page that holds at least one note. 0 when absent.
|
|
@@ -357,7 +439,16 @@ interface PageLayout {
|
|
|
357
439
|
footnotes: number[];
|
|
358
440
|
/** Body height used, footnotes and separator included. */
|
|
359
441
|
used: number;
|
|
442
|
+
/** The body height this page had to fill (`pageCapacity()` for its index). */
|
|
443
|
+
capacity: number;
|
|
360
444
|
}
|
|
445
|
+
/**
|
|
446
|
+
* The body height of the page at 0-based `index`: page 1 takes
|
|
447
|
+
* `firstPageHeight`, even pages (odd indices) `evenPageHeight`, the rest
|
|
448
|
+
* `pageHeight`. A variant that is absent, non-finite or not positive falls
|
|
449
|
+
* back to `pageHeight`. At least 1, so a page always makes progress.
|
|
450
|
+
*/
|
|
451
|
+
declare function pageCapacity(options: PackOptions, index: number): number;
|
|
361
452
|
declare function paginate(items: PackItem[], options: PackOptions): PageLayout[];
|
|
362
453
|
|
|
363
454
|
/**
|
|
@@ -421,18 +512,95 @@ declare function pageGeometry(doc: Doc): PageGeometry;
|
|
|
421
512
|
*/
|
|
422
513
|
declare function bodyBox(g: PageGeometry, headerHeight: number, footerHeight: number): BodyBox;
|
|
423
514
|
|
|
424
|
-
/**
|
|
515
|
+
/**
|
|
516
|
+
* Which header and footer each page draws (last-word 0.16.0).
|
|
517
|
+
*
|
|
518
|
+
* `page.header` / `page.footer` are the defaults. Beside them:
|
|
519
|
+
* - `firstHeader` / `firstFooter`: page 1 only (Word's "Different first page");
|
|
520
|
+
* - `evenHeader` / `evenFooter`: pages 2, 4, ... (Word's "Different odd and
|
|
521
|
+
* even pages"), the default then being the odd pages'.
|
|
522
|
+
* A kind with no variant shows its default on those pages too. A variant of
|
|
523
|
+
* `{"blocks": []}` (or a one-line band with no text) is present but empty, so
|
|
524
|
+
* it BLANKS that page's band rather than falling back.
|
|
525
|
+
*
|
|
526
|
+
* So pages fall in three classes -- page 1, even pages, other odd pages --
|
|
527
|
+
* and every page of a class draws the same bands, at the same heights. The
|
|
528
|
+
* packer takes one body height per class (`PackOptions.firstPageHeight` /
|
|
529
|
+
* `evenPageHeight` / `pageHeight`) and `pageBodyBoxes` derives them.
|
|
530
|
+
*/
|
|
531
|
+
type BandKind = "header" | "footer";
|
|
532
|
+
/** Which of a kind's bands applies: the default, the first-page or the even-page one. */
|
|
533
|
+
type BandSlot = "default" | "first" | "even";
|
|
534
|
+
/** Page 1, an even page, or an odd page after the first. */
|
|
535
|
+
type PageClass = "first" | "even" | "odd";
|
|
536
|
+
/** Measured band heights per kind and slot, in any one unit; 0 when absent or blank. */
|
|
537
|
+
type BandHeights = Record<BandKind, Record<BandSlot, number>>;
|
|
538
|
+
/** The class of the page at 0-based `index`. */
|
|
539
|
+
declare function pageClass(index: number): PageClass;
|
|
540
|
+
/** The slot a page class draws for one kind: its variant when that is set, else the default. */
|
|
541
|
+
declare function bandSlot(page: Page | undefined, kind: BandKind, cls: PageClass): BandSlot;
|
|
542
|
+
/**
|
|
543
|
+
* The band the page at 0-based `index` draws for `kind`, or null when it
|
|
544
|
+
* draws none (no band, or a blank variant).
|
|
545
|
+
*/
|
|
546
|
+
declare function pageBand(page: Page | undefined, kind: BandKind, index: number): Band | BlocksBand | null;
|
|
547
|
+
/**
|
|
548
|
+
* The body box of each page class from the measured band heights (points):
|
|
549
|
+
* each class uses the header and footer it actually draws, so a tall
|
|
550
|
+
* first-page letterhead moves only page 1's body down.
|
|
551
|
+
*/
|
|
552
|
+
declare function pageBodyBoxes(g: PageGeometry, page: Page | undefined, heights: BandHeights): Record<PageClass, BodyBox>;
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* The live values a header or footer's field tokens take on one page.
|
|
556
|
+
*
|
|
557
|
+
* Only `page` and `pages` are required, so a 0.1.x caller of
|
|
558
|
+
* `substituteFields(text, { page, pages })` is unchanged; every other value
|
|
559
|
+
* has a documented fallback.
|
|
560
|
+
*/
|
|
425
561
|
interface PageFields {
|
|
426
562
|
/** 1-based. */
|
|
427
563
|
page: number;
|
|
428
564
|
pages: number;
|
|
565
|
+
/**
|
|
566
|
+
* `{section}`. A last-word Doc is ONE section, so this is 1 unless a caller
|
|
567
|
+
* says otherwise.
|
|
568
|
+
*/
|
|
569
|
+
section?: number;
|
|
570
|
+
/** `{sectionpages}`. The Doc is one section, so the page total when absent. */
|
|
571
|
+
sectionPages?: number;
|
|
572
|
+
/** `{author}`: `doc.meta.author`. Empty when absent. */
|
|
573
|
+
author?: string;
|
|
574
|
+
/** `{title}`: the top-level `doc.title` (there is deliberately no `meta.title`). Empty when absent. */
|
|
575
|
+
title?: string;
|
|
576
|
+
/** `{filename}`: the viewer cannot know it, so it is a prop. Empty when absent. */
|
|
577
|
+
filename?: string;
|
|
578
|
+
/** `{date}` / `{time}` are "as of" this moment. The current time when absent. */
|
|
579
|
+
now?: Date;
|
|
429
580
|
}
|
|
430
581
|
/**
|
|
431
|
-
* Text with
|
|
432
|
-
*
|
|
433
|
-
*
|
|
582
|
+
* Text with its field tokens replaced by this page's values -- the PAGE,
|
|
583
|
+
* NUMPAGES, SECTION, SECTIONPAGES, AUTHOR, TITLE, FILENAME, DATE and TIME
|
|
584
|
+
* fields last-word writes into a band. Only in bands: in the body the same
|
|
585
|
+
* characters are literal text, as they are in the written file.
|
|
586
|
+
*
|
|
587
|
+
* Returns a plain string; the caller renders it as a React text node, so a
|
|
588
|
+
* value full of markup (an untrusted author) stays text.
|
|
434
589
|
*/
|
|
435
590
|
declare function substituteFields(text: string, fields: PageFields): string;
|
|
591
|
+
/**
|
|
592
|
+
* The `now` prop as a Date: a Date or an ISO-8601 string (JSON-friendly). A
|
|
593
|
+
* missing or unparseable value is the current time.
|
|
594
|
+
*/
|
|
595
|
+
declare function resolveNow(now: Date | string | undefined | null): Date;
|
|
596
|
+
/**
|
|
597
|
+
* A Word date-time picture, formatted in LOCAL time: d dd ddd dddd, M MM MMM
|
|
598
|
+
* MMMM, yy yyyy, h hh (12-hour), H HH (24-hour), m mm, s ss, am/pm, AM/PM.
|
|
599
|
+
* Text in single quotes is literal (an unterminated quote runs to the end);
|
|
600
|
+
* every other character is literal. Names are English, as Word writes them
|
|
601
|
+
* for an English document. Pure string work: no third-party code, no eval.
|
|
602
|
+
*/
|
|
603
|
+
declare function formatDatePicture(date: Date, picture: string): string;
|
|
436
604
|
|
|
437
605
|
interface FootnoteNumbering {
|
|
438
606
|
/** Run object -> its mark number. Keyed by identity, so the Doc must not be cloned between numbering and render. */
|
|
@@ -453,4 +621,4 @@ interface FootnoteNumbering {
|
|
|
453
621
|
*/
|
|
454
622
|
declare function numberFootnotes(doc: Doc): FootnoteNumbering;
|
|
455
623
|
|
|
456
|
-
export { type Align, type Band, type Block, type BlockFragment, type BlockItem, type BlocksBand, type BodyBox, type Border, type BorderStyle, type BoxBorders, type BoxSides, type BreakItem, type ChartBlock, type CodeBlock, type Doc, DocViewer, type DocViewerLayout, type DocViewerProps, type Footnote, type FootnoteMark, type FootnoteNumbering, type Fragment, type HeadingBlock, type HrBlock, type ImageBlock, 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 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, bodyBox, docFromReader, numberFootnotes, pageGeometry, pageMargins, paginate, substituteFields };
|
|
624
|
+
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, 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 };
|