@particle-academy/last-word-ui 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -189,11 +189,32 @@ interface Page {
     size?: PageSize;
     orientation?: Orientation;
     margins?: PageMargins;
+    /** Every page, unless a variant below covers it. */
     header?: Band | BlocksBand;
     footer?: Band | BlocksBand;
+    /**
+     * Page 1 only, in place of `header` / `footer` (last-word 0.16.0, Word's
+     * "Different first page"). `{"blocks": []}` blanks page 1's band.
+     */
+    firstHeader?: Band | BlocksBand;
+    firstFooter?: Band | BlocksBand;
+    /**
+     * Even pages (2, 4, ...), in place of `header` / `footer` (last-word 0.16.0,
+     * Word's "Different odd and even pages"). `{"blocks": []}` blanks them.
+     */
+    evenHeader?: Band | BlocksBand;
+    evenFooter?: Band | BlocksBand;
+}
+/** Document properties (last-word 0.16.0). */
+interface DocMeta {
+    /** Word's Author property: what an `{author}` field in a band shows. */
+    author?: string;
+    [key: string]: unknown;
 }
 interface Doc {
+    /** The document title: what a `{title}` field in a band shows. */
     title?: string;
+    meta?: DocMeta;
     blocks: Block[];
     page?: Page;
     defaultFont?: string;
@@ -225,6 +246,17 @@ interface DocViewerProps {
     maxScale?: number;
     /** Space between pages, in CSS px. Default 16. */
     gap?: number;
+    /**
+     * What a `{filename}` field in a header or footer shows. The viewer cannot
+     * know the file's name, so it is empty unless given.
+     */
+    filename?: string;
+    /**
+     * The moment `{date}` / `{time}` fields show: a Date or an ISO-8601 string
+     * (JSON-friendly). Default: the time of the first render. Pass it for
+     * deterministic output (tests, agents, a print preview "as of" a date).
+     */
+    now?: Date | string;
     /** Called after every layout with JSON-serializable facts about it. */
     onLayout?: (layout: DocViewerLayout) => void;
     /**
@@ -244,9 +276,15 @@ interface DocViewerProps {
  *
  * Stable handles: the root carries `data-lw-viewer`; each page `data-page`
  * (1-based); each block or fragment of one `data-block` (`b0`, `b1`, ... in
- * document order); each footnote `data-footnote`; bands `data-lw-band`.
+ * document order); each footnote `data-footnote`; bands `data-lw-band`, with
+ * `data-lw-band-variant` naming the one drawn (`default`, `first`, `even`).
+ *
+ * Header and footer text takes field tokens -- `{page}`, `{pages}`,
+ * `{section}`, `{sectionpages}`, `{author}`, `{title}`, `{filename}`, `{date}`,
+ * `{time}`, `{date:FORMAT}`, `{time:FORMAT}` -- drawn as plain text. In the
+ * body they stay literal.
  */
-declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
+declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
 
 /**
  * A Doc from what a last-word reader returned -- `new DocxReader().read(bytes)`
@@ -318,8 +356,21 @@ interface BreakItem {
 }
 type PackItem = BlockItem | TableItem | BreakItem;
 interface PackOptions {
-    /** The body height available on every page. */
+    /**
+     * The body height available on a page no variant below covers: every page
+     * when neither is given, else the odd pages after the first.
+     */
     pageHeight: number;
+    /**
+     * The body height of page 1, when its header or footer differs from the
+     * rest (a first-page letterhead). `pageHeight` when absent.
+     */
+    firstPageHeight?: number;
+    /**
+     * The body height of the even pages (2, 4, ...), when their bands differ.
+     * `pageHeight` when absent. Page 1 is odd, so it never takes this.
+     */
+    evenPageHeight?: number;
     /**
      * Height of the separator rule above a page's footnotes, reserved once on
      * any page that holds at least one note. 0 when absent.
@@ -357,7 +408,16 @@ interface PageLayout {
     footnotes: number[];
     /** Body height used, footnotes and separator included. */
     used: number;
+    /** The body height this page had to fill (`pageCapacity()` for its index). */
+    capacity: number;
 }
+/**
+ * The body height of the page at 0-based `index`: page 1 takes
+ * `firstPageHeight`, even pages (odd indices) `evenPageHeight`, the rest
+ * `pageHeight`. A variant that is absent, non-finite or not positive falls
+ * back to `pageHeight`. At least 1, so a page always makes progress.
+ */
+declare function pageCapacity(options: PackOptions, index: number): number;
 declare function paginate(items: PackItem[], options: PackOptions): PageLayout[];
 
 /**
@@ -421,18 +481,95 @@ declare function pageGeometry(doc: Doc): PageGeometry;
  */
 declare function bodyBox(g: PageGeometry, headerHeight: number, footerHeight: number): BodyBox;
 
-/** The live values a header or footer's `{page}` / `{pages}` fields take on one page. */
+/**
+ * Which header and footer each page draws (last-word 0.16.0).
+ *
+ * `page.header` / `page.footer` are the defaults. Beside them:
+ * - `firstHeader` / `firstFooter`: page 1 only (Word's "Different first page");
+ * - `evenHeader` / `evenFooter`: pages 2, 4, ... (Word's "Different odd and
+ *   even pages"), the default then being the odd pages'.
+ * A kind with no variant shows its default on those pages too. A variant of
+ * `{"blocks": []}` (or a one-line band with no text) is present but empty, so
+ * it BLANKS that page's band rather than falling back.
+ *
+ * So pages fall in three classes -- page 1, even pages, other odd pages --
+ * and every page of a class draws the same bands, at the same heights. The
+ * packer takes one body height per class (`PackOptions.firstPageHeight` /
+ * `evenPageHeight` / `pageHeight`) and `pageBodyBoxes` derives them.
+ */
+type BandKind = "header" | "footer";
+/** Which of a kind's bands applies: the default, the first-page or the even-page one. */
+type BandSlot = "default" | "first" | "even";
+/** Page 1, an even page, or an odd page after the first. */
+type PageClass = "first" | "even" | "odd";
+/** Measured band heights per kind and slot, in any one unit; 0 when absent or blank. */
+type BandHeights = Record<BandKind, Record<BandSlot, number>>;
+/** The class of the page at 0-based `index`. */
+declare function pageClass(index: number): PageClass;
+/** The slot a page class draws for one kind: its variant when that is set, else the default. */
+declare function bandSlot(page: Page | undefined, kind: BandKind, cls: PageClass): BandSlot;
+/**
+ * The band the page at 0-based `index` draws for `kind`, or null when it
+ * draws none (no band, or a blank variant).
+ */
+declare function pageBand(page: Page | undefined, kind: BandKind, index: number): Band | BlocksBand | null;
+/**
+ * The body box of each page class from the measured band heights (points):
+ * each class uses the header and footer it actually draws, so a tall
+ * first-page letterhead moves only page 1's body down.
+ */
+declare function pageBodyBoxes(g: PageGeometry, page: Page | undefined, heights: BandHeights): Record<PageClass, BodyBox>;
+
+/**
+ * The live values a header or footer's field tokens take on one page.
+ *
+ * Only `page` and `pages` are required, so a 0.1.x caller of
+ * `substituteFields(text, { page, pages })` is unchanged; every other value
+ * has a documented fallback.
+ */
 interface PageFields {
     /** 1-based. */
     page: number;
     pages: number;
+    /**
+     * `{section}`. A last-word Doc is ONE section, so this is 1 unless a caller
+     * says otherwise.
+     */
+    section?: number;
+    /** `{sectionpages}`. The Doc is one section, so the page total when absent. */
+    sectionPages?: number;
+    /** `{author}`: `doc.meta.author`. Empty when absent. */
+    author?: string;
+    /** `{title}`: the top-level `doc.title` (there is deliberately no `meta.title`). Empty when absent. */
+    title?: string;
+    /** `{filename}`: the viewer cannot know it, so it is a prop. Empty when absent. */
+    filename?: string;
+    /** `{date}` / `{time}` are "as of" this moment. The current time when absent. */
+    now?: Date;
 }
 /**
- * Text with `{page}` and `{pages}` replaced by this page's numbers -- the PAGE
- * and NUMPAGES fields last-word writes into a band. Only in bands: in the body
- * the same characters are literal text, as they are in the written file.
+ * Text with its field tokens replaced by this page's values -- the PAGE,
+ * NUMPAGES, SECTION, SECTIONPAGES, AUTHOR, TITLE, FILENAME, DATE and TIME
+ * fields last-word writes into a band. Only in bands: in the body the same
+ * characters are literal text, as they are in the written file.
+ *
+ * Returns a plain string; the caller renders it as a React text node, so a
+ * value full of markup (an untrusted author) stays text.
  */
 declare function substituteFields(text: string, fields: PageFields): string;
+/**
+ * The `now` prop as a Date: a Date or an ISO-8601 string (JSON-friendly). A
+ * missing or unparseable value is the current time.
+ */
+declare function resolveNow(now: Date | string | undefined | null): Date;
+/**
+ * A Word date-time picture, formatted in LOCAL time: d dd ddd dddd, M MM MMM
+ * MMMM, yy yyyy, h hh (12-hour), H HH (24-hour), m mm, s ss, am/pm, AM/PM.
+ * Text in single quotes is literal (an unterminated quote runs to the end);
+ * every other character is literal. Names are English, as Word writes them
+ * for an English document. Pure string work: no third-party code, no eval.
+ */
+declare function formatDatePicture(date: Date, picture: string): string;
 
 interface FootnoteNumbering {
     /** Run object -> its mark number. Keyed by identity, so the Doc must not be cloned between numbering and render. */
@@ -453,4 +590,4 @@ interface FootnoteNumbering {
  */
 declare function numberFootnotes(doc: Doc): FootnoteNumbering;
 
-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 };
+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, type ChartBlock, type CodeBlock, type Doc, type DocMeta, 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 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, bandSlot, bodyBox, docFromReader, formatDatePicture, numberFootnotes, pageBand, pageBodyBoxes, pageCapacity, pageClass, pageGeometry, pageMargins, paginate, resolveNow, substituteFields };

package/dist/index.d.ts

@@ -189,11 +189,32 @@ interface Page {
     size?: PageSize;
     orientation?: Orientation;
     margins?: PageMargins;
+    /** Every page, unless a variant below covers it. */
     header?: Band | BlocksBand;
     footer?: Band | BlocksBand;
+    /**
+     * Page 1 only, in place of `header` / `footer` (last-word 0.16.0, Word's
+     * "Different first page"). `{"blocks": []}` blanks page 1's band.
+     */
+    firstHeader?: Band | BlocksBand;
+    firstFooter?: Band | BlocksBand;
+    /**
+     * Even pages (2, 4, ...), in place of `header` / `footer` (last-word 0.16.0,
+     * Word's "Different odd and even pages"). `{"blocks": []}` blanks them.
+     */
+    evenHeader?: Band | BlocksBand;
+    evenFooter?: Band | BlocksBand;
+}
+/** Document properties (last-word 0.16.0). */
+interface DocMeta {
+    /** Word's Author property: what an `{author}` field in a band shows. */
+    author?: string;
+    [key: string]: unknown;
 }
 interface Doc {
+    /** The document title: what a `{title}` field in a band shows. */
     title?: string;
+    meta?: DocMeta;
     blocks: Block[];
     page?: Page;
     defaultFont?: string;
@@ -225,6 +246,17 @@ interface DocViewerProps {
     maxScale?: number;
     /** Space between pages, in CSS px. Default 16. */
     gap?: number;
+    /**
+     * What a `{filename}` field in a header or footer shows. The viewer cannot
+     * know the file's name, so it is empty unless given.
+     */
+    filename?: string;
+    /**
+     * The moment `{date}` / `{time}` fields show: a Date or an ISO-8601 string
+     * (JSON-friendly). Default: the time of the first render. Pass it for
+     * deterministic output (tests, agents, a print preview "as of" a date).
+     */
+    now?: Date | string;
     /** Called after every layout with JSON-serializable facts about it. */
     onLayout?: (layout: DocViewerLayout) => void;
     /**
@@ -244,9 +276,15 @@ interface DocViewerProps {
  *
  * Stable handles: the root carries `data-lw-viewer`; each page `data-page`
  * (1-based); each block or fragment of one `data-block` (`b0`, `b1`, ... in
- * document order); each footnote `data-footnote`; bands `data-lw-band`.
+ * document order); each footnote `data-footnote`; bands `data-lw-band`, with
+ * `data-lw-band-variant` naming the one drawn (`default`, `first`, `even`).
+ *
+ * Header and footer text takes field tokens -- `{page}`, `{pages}`,
+ * `{section}`, `{sectionpages}`, `{author}`, `{title}`, `{filename}`, `{date}`,
+ * `{time}`, `{date:FORMAT}`, `{time:FORMAT}` -- drawn as plain text. In the
+ * body they stay literal.
  */
-declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
+declare function DocViewer({ doc, fit, scale: fixedScale, maxScale, gap, filename, now, onLayout, injectStyles, id, className, style, }: DocViewerProps): react.JSX.Element;
 
 /**
  * A Doc from what a last-word reader returned -- `new DocxReader().read(bytes)`
@@ -318,8 +356,21 @@ interface BreakItem {
 }
 type PackItem = BlockItem | TableItem | BreakItem;
 interface PackOptions {
-    /** The body height available on every page. */
+    /**
+     * The body height available on a page no variant below covers: every page
+     * when neither is given, else the odd pages after the first.
+     */
     pageHeight: number;
+    /**
+     * The body height of page 1, when its header or footer differs from the
+     * rest (a first-page letterhead). `pageHeight` when absent.
+     */
+    firstPageHeight?: number;
+    /**
+     * The body height of the even pages (2, 4, ...), when their bands differ.
+     * `pageHeight` when absent. Page 1 is odd, so it never takes this.
+     */
+    evenPageHeight?: number;
     /**
      * Height of the separator rule above a page's footnotes, reserved once on
      * any page that holds at least one note. 0 when absent.
@@ -357,7 +408,16 @@ interface PageLayout {
     footnotes: number[];
     /** Body height used, footnotes and separator included. */
     used: number;
+    /** The body height this page had to fill (`pageCapacity()` for its index). */
+    capacity: number;
 }
+/**
+ * The body height of the page at 0-based `index`: page 1 takes
+ * `firstPageHeight`, even pages (odd indices) `evenPageHeight`, the rest
+ * `pageHeight`. A variant that is absent, non-finite or not positive falls
+ * back to `pageHeight`. At least 1, so a page always makes progress.
+ */
+declare function pageCapacity(options: PackOptions, index: number): number;
 declare function paginate(items: PackItem[], options: PackOptions): PageLayout[];
 
 /**
@@ -421,18 +481,95 @@ declare function pageGeometry(doc: Doc): PageGeometry;
  */
 declare function bodyBox(g: PageGeometry, headerHeight: number, footerHeight: number): BodyBox;
 
-/** The live values a header or footer's `{page}` / `{pages}` fields take on one page. */
+/**
+ * Which header and footer each page draws (last-word 0.16.0).
+ *
+ * `page.header` / `page.footer` are the defaults. Beside them:
+ * - `firstHeader` / `firstFooter`: page 1 only (Word's "Different first page");
+ * - `evenHeader` / `evenFooter`: pages 2, 4, ... (Word's "Different odd and
+ *   even pages"), the default then being the odd pages'.
+ * A kind with no variant shows its default on those pages too. A variant of
+ * `{"blocks": []}` (or a one-line band with no text) is present but empty, so
+ * it BLANKS that page's band rather than falling back.
+ *
+ * So pages fall in three classes -- page 1, even pages, other odd pages --
+ * and every page of a class draws the same bands, at the same heights. The
+ * packer takes one body height per class (`PackOptions.firstPageHeight` /
+ * `evenPageHeight` / `pageHeight`) and `pageBodyBoxes` derives them.
+ */
+type BandKind = "header" | "footer";
+/** Which of a kind's bands applies: the default, the first-page or the even-page one. */
+type BandSlot = "default" | "first" | "even";
+/** Page 1, an even page, or an odd page after the first. */
+type PageClass = "first" | "even" | "odd";
+/** Measured band heights per kind and slot, in any one unit; 0 when absent or blank. */
+type BandHeights = Record<BandKind, Record<BandSlot, number>>;
+/** The class of the page at 0-based `index`. */
+declare function pageClass(index: number): PageClass;
+/** The slot a page class draws for one kind: its variant when that is set, else the default. */
+declare function bandSlot(page: Page | undefined, kind: BandKind, cls: PageClass): BandSlot;
+/**
+ * The band the page at 0-based `index` draws for `kind`, or null when it
+ * draws none (no band, or a blank variant).
+ */
+declare function pageBand(page: Page | undefined, kind: BandKind, index: number): Band | BlocksBand | null;
+/**
+ * The body box of each page class from the measured band heights (points):
+ * each class uses the header and footer it actually draws, so a tall
+ * first-page letterhead moves only page 1's body down.
+ */
+declare function pageBodyBoxes(g: PageGeometry, page: Page | undefined, heights: BandHeights): Record<PageClass, BodyBox>;
+
+/**
+ * The live values a header or footer's field tokens take on one page.
+ *
+ * Only `page` and `pages` are required, so a 0.1.x caller of
+ * `substituteFields(text, { page, pages })` is unchanged; every other value
+ * has a documented fallback.
+ */
 interface PageFields {
     /** 1-based. */
     page: number;
     pages: number;
+    /**
+     * `{section}`. A last-word Doc is ONE section, so this is 1 unless a caller
+     * says otherwise.
+     */
+    section?: number;
+    /** `{sectionpages}`. The Doc is one section, so the page total when absent. */
+    sectionPages?: number;
+    /** `{author}`: `doc.meta.author`. Empty when absent. */
+    author?: string;
+    /** `{title}`: the top-level `doc.title` (there is deliberately no `meta.title`). Empty when absent. */
+    title?: string;
+    /** `{filename}`: the viewer cannot know it, so it is a prop. Empty when absent. */
+    filename?: string;
+    /** `{date}` / `{time}` are "as of" this moment. The current time when absent. */
+    now?: Date;
 }
 /**
- * Text with `{page}` and `{pages}` replaced by this page's numbers -- the PAGE
- * and NUMPAGES fields last-word writes into a band. Only in bands: in the body
- * the same characters are literal text, as they are in the written file.
+ * Text with its field tokens replaced by this page's values -- the PAGE,
+ * NUMPAGES, SECTION, SECTIONPAGES, AUTHOR, TITLE, FILENAME, DATE and TIME
+ * fields last-word writes into a band. Only in bands: in the body the same
+ * characters are literal text, as they are in the written file.
+ *
+ * Returns a plain string; the caller renders it as a React text node, so a
+ * value full of markup (an untrusted author) stays text.
  */
 declare function substituteFields(text: string, fields: PageFields): string;
+/**
+ * The `now` prop as a Date: a Date or an ISO-8601 string (JSON-friendly). A
+ * missing or unparseable value is the current time.
+ */
+declare function resolveNow(now: Date | string | undefined | null): Date;
+/**
+ * A Word date-time picture, formatted in LOCAL time: d dd ddd dddd, M MM MMM
+ * MMMM, yy yyyy, h hh (12-hour), H HH (24-hour), m mm, s ss, am/pm, AM/PM.
+ * Text in single quotes is literal (an unterminated quote runs to the end);
+ * every other character is literal. Names are English, as Word writes them
+ * for an English document. Pure string work: no third-party code, no eval.
+ */
+declare function formatDatePicture(date: Date, picture: string): string;
 
 interface FootnoteNumbering {
     /** Run object -> its mark number. Keyed by identity, so the Doc must not be cloned between numbering and render. */
@@ -453,4 +590,4 @@ interface FootnoteNumbering {
  */
 declare function numberFootnotes(doc: Doc): FootnoteNumbering;
 
-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 };
+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, type ChartBlock, type CodeBlock, type Doc, type DocMeta, 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 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, bandSlot, bodyBox, docFromReader, formatDatePicture, numberFootnotes, pageBand, pageBodyBoxes, pageCapacity, pageClass, pageGeometry, pageMargins, paginate, resolveNow, substituteFields };