@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/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 DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
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
- /** The body height available on every page. */
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
- /** The live values a header or footer's `{page}` / `{pages}` fields take on one page. */
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 `{page}` and `{pages}` replaced by this page's numbers -- the PAGE
432
- * and NUMPAGES fields last-word writes into a band. Only in bands: in the body
433
- * the same characters are literal text, as they are in the written file.
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 DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
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
- /** The body height available on every page. */
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
- /** The live values a header or footer's `{page}` / `{pages}` fields take on one page. */
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 `{page}` and `{pages}` replaced by this page's numbers -- the PAGE
432
- * and NUMPAGES fields last-word writes into a band. Only in bands: in the body
433
- * the same characters are literal text, as they are in the written file.
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 };