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

package/CHANGELOG.md

@@ -10,6 +10,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-01
+
+Renders last-word 0.16.0's band variants and field tokens. **Consumer action:
+none.** Both new props are optional, and a document without the new page keys
+or tokens renders exactly as it did on 0.1.1. Pass `filename` and `now` only
+if your bands use `{filename}`, `{date}` or `{time}`.
+
+### Added
+
+- **First-page and even-page bands:** `page.firstHeader`, `page.firstFooter`,
+  `page.evenHeader` and `page.evenFooter`, in the same forms as `page.header`
+  (a one-line band or `{blocks}`). Page 1 draws the first variant when
+  present, even pages (2, 4, ...) the even variant, every other page the
+  default. `{"blocks": []}` as a variant blanks that page's band. Each band
+  carries `data-lw-band-variant` (`default`, `first` or `even`).
+- **Per-page body heights.** Each page's body is sized by the bands it
+  actually draws, so a tall first-page letterhead moves only page 1's body
+  down. `paginate()` takes optional `firstPageHeight` and `evenPageHeight`
+  beside `pageHeight`, and each `PageLayout` reports its `capacity`. Without
+  the new options, pagination is unchanged.
+- **Field tokens in band text:** `{section}` and `{sectionpages}` (a Doc is one
+  section: `1` and the page total), `{author}` (`doc.meta.author`), `{title}`
+  (the top-level `doc.title`; there is no `meta.title`), `{filename}`, and
+  `{date}` / `{time}` in the browser locale, or `{date:FORMAT}` /
+  `{time:FORMAT}` with a Word date-time picture (d to dddd, M to MMMM, yy,
+  yyyy, h, hh, H, HH, m, mm, s, ss, am/pm, AM/PM, single-quoted literals,
+  English names). Tokens follow last-word's grammar exactly; anything else in
+  braces stays literal. In the body every token stays literal text. Values
+  render as plain text only.
+- **Props:** `filename` (what `{filename}` shows; empty when absent) and `now`
+  (a Date or an ISO string; the moment `{date}` / `{time}` show, for
+  deterministic output).
+- **Exports:** `pageCapacity`, `pageBand`, `pageClass`, `bandSlot`,
+  `pageBodyBoxes`, `formatDatePicture`, `resolveNow`, and the `BandKind`,
+  `BandSlot`, `PageClass`, `BandHeights` and `DocMeta` types. `PageFields`
+  gains optional `section`, `sectionPages`, `author`, `title`, `filename` and
+  `now`; `substituteFields(text, { page, pages })` still works as before.
+
+## [0.1.1] - 2026-11-01
+
+### Changed
+- Test environment: `jsdom` moved from 26 to 30 (devDependency only). jsdom 26
+  pulled in `whatwg-encoding`, which is deprecated upstream and printed a
+  deprecation warning on every `npm ci`. Nothing in the published package
+  changes. **Consumer action: none.**
+
 ## [0.1.0] - 2026-11-01
 
 First release. **What you must do:** install it beside `react` 19 and

package/README.md

@@ -49,6 +49,8 @@ so a deep clone between numbering and render would lose the marks.
 | `scale` | `number` | | a fixed scale; overrides `fit` |
 | `maxScale` | `number` | `1` | the most `fit` will enlarge a page |
 | `gap` | `number` | `16` | px between pages |
+| `filename` | `string` | `""` | what a `{filename}` band field shows |
+| `now` | `Date \| string` | first render | the moment `{date}` / `{time}` show; an ISO string is fine |
 | `onLayout` | `(l) => void` | | `{ pages, pageWidth, pageHeight, scale }`, JSON |
 | `injectStyles` | `boolean` | `true` | see *Styles* |
 | `id`, `className`, `style` | | | on the root |
@@ -58,7 +60,8 @@ so a deep clone between numbering and render would lose the marks.
 The root carries `data-lw-viewer`. Each page carries `data-page` (1-based), each
 block or fragment of a block carries `data-block` (`b0`, `b1`, ... in document
 order), each footnote carries `data-footnote`, and the bands carry
-`data-lw-band="header" | "footer"`. Table fragments carry `data-lw-rows`, plus
+`data-lw-band="header" | "footer"`, with `data-lw-band-variant="default" |
+"first" | "even"` naming the band drawn. Table fragments carry `data-lw-rows`, plus
 `data-lw-repeated-header` on continuation pages.
 
 ### Styles
@@ -86,8 +89,22 @@ import "@particle-academy/last-word-ui/styles.css";
   edge (36pt when absent). They are either a left / centre / right band or
   blocks (a letterhead logo, address lines). A tall header pushes the body down,
   as in Word.
-- **Page numbers:** `{page}` and `{pages}` become live numbers on each page,
-  in bands only. In the body they stay literal text, as in the file.
+- **First-page and even-page bands** (last-word 0.16.0): page 1 draws
+  `page.firstHeader` / `page.firstFooter` when present, even pages (2, 4, ...)
+  `page.evenHeader` / `page.evenFooter`, and every other page the default.
+  `{"blocks": []}` as a variant blanks that page's band. Each page's body is
+  sized by the bands it actually draws, so a tall first-page letterhead moves
+  only page 1's body down.
+- **Fields in bands:** `{page}`, `{pages}`; `{section}` and `{sectionpages}`
+  (a Doc is one section, so `1` and the page total); `{author}`
+  (`doc.meta.author`); `{title}` (the top-level `doc.title`; there is no
+  `meta.title`); `{filename}` (the `filename` prop); `{date}` and `{time}` in
+  the browser's locale, or `{date:FORMAT}` / `{time:FORMAT}` with a Word
+  picture (`d dd ddd dddd M MM MMM MMMM yy yyyy h hh H HH m mm s ss am/pm
+  AM/PM`, text in single quotes literal, English names). Unknown values are
+  empty. Names are lower-case and exact; anything else in braces stays
+  literal. All of it is drawn as plain text. In the body every token stays
+  literal text, as in the file.
 - **Footnotes:** numbered 1, 2, 3 in document order and set at the foot of the
   mark's page, under a short rule. Their height comes off that page's body.
 - **Content:** tables (widths, header rows, cell shading, borders, padding,