@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 CHANGED
@@ -10,6 +10,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [0.3.0] - 2026-11-01
14
+
15
+ **What you must do: probably nothing, but expect page breaks to move.** Calibri
16
+ and default text now draws in a bundled font with kerning off, so a document
17
+ can break differently from 0.2.0, on every machine, including ones that had
18
+ real Calibri or only Arial. That is the point: the count is now the same
19
+ everywhere and matches last-word's `Agent::layout()`. Under a strict CSP you
20
+ already import `styles.css`; allow its font files in `font-src`. On the
21
+ CommonJS build, import `styles.css` too, or the viewer reports
22
+ `font: "fallback"`.
23
+
24
+ ### Added
25
+
26
+ - **A bundled Carlito** (1.104, from googlefonts/carlito, unmodified, SIL OFL
27
+ 1.1 with a NOTICE in `fonts/`), declared as `"LW Carlito"` in regular, bold,
28
+ italic and bold italic. Metric-compatible with Calibri: every printable
29
+ ASCII and Latin-1 advance is equal in all four styles. The package now
30
+ publishes `fonts/` (about 2.7 MB of TTF; Carlito is not published as woff2
31
+ upstream, and these are the files as published). A browser fetches only the
32
+ faces a document uses.
33
+ - `styles.css` declares the same `@font-face` rules, with URLs relative to the
34
+ stylesheet, for the strict-CSP route.
35
+ - `DocViewerLayout.font`: `"carlito"`, `"fallback"` or `"unused"`, and
36
+ `data-lw-font` on the root, so a caller can tell a deterministic page count
37
+ from one that depends on the machine.
38
+ - `FONT_LOAD_TIMEOUT_MS` (3000) and the `ViewerFont` type.
39
+ - `demo/agreement.html`: the harness that renders documents in the viewer and
40
+ records the page layout last-word's `layout()` is held to. The fixtures it
41
+ produced are in `tests/fixtures/viewer-agreement.json` (the same bytes as in
42
+ last-word; both pin the sha256).
43
+
44
+ ### Changed
45
+
46
+ - **Calibri and unspecified text draws in the bundled Carlito, first in the
47
+ stack**, ahead of `Calibri`, `Carlito`, `Segoe UI` and `Arial`. Pages may
48
+ break differently from 0.2.0 on any machine: where real Calibri was
49
+ installed, because kerning is now off; where it was not, because the text is
50
+ no longer in Segoe UI or Arial. Every other explicit font keeps its stack,
51
+ and its breaks still depend on the machine.
52
+ - **Kerning and ligatures are off** (`font-kerning: none`,
53
+ `font-variant-ligatures: none`), as in Word by default, and
54
+ `text-rendering: geometricPrecision`.
55
+ - **The viewer waits for the font before it measures.** No pages and no
56
+ `onLayout` until the faces the document draws have loaded (or 3 s pass).
57
+ 0.2.0 drew pages in the fallback first and re-laid them out when web fonts
58
+ arrived, so `onLayout` could report a count that changed a moment later.
59
+
60
+ ## [0.2.0] - 2026-11-01
61
+
62
+ Renders last-word 0.16.0's band variants and field tokens. **Consumer action:
63
+ none.** Both new props are optional, and a document without the new page keys
64
+ or tokens renders exactly as it did on 0.1.1. Pass `filename` and `now` only
65
+ if your bands use `{filename}`, `{date}` or `{time}`.
66
+
67
+ ### Added
68
+
69
+ - **First-page and even-page bands:** `page.firstHeader`, `page.firstFooter`,
70
+ `page.evenHeader` and `page.evenFooter`, in the same forms as `page.header`
71
+ (a one-line band or `{blocks}`). Page 1 draws the first variant when
72
+ present, even pages (2, 4, ...) the even variant, every other page the
73
+ default. `{"blocks": []}` as a variant blanks that page's band. Each band
74
+ carries `data-lw-band-variant` (`default`, `first` or `even`).
75
+ - **Per-page body heights.** Each page's body is sized by the bands it
76
+ actually draws, so a tall first-page letterhead moves only page 1's body
77
+ down. `paginate()` takes optional `firstPageHeight` and `evenPageHeight`
78
+ beside `pageHeight`, and each `PageLayout` reports its `capacity`. Without
79
+ the new options, pagination is unchanged.
80
+ - **Field tokens in band text:** `{section}` and `{sectionpages}` (a Doc is one
81
+ section: `1` and the page total), `{author}` (`doc.meta.author`), `{title}`
82
+ (the top-level `doc.title`; there is no `meta.title`), `{filename}`, and
83
+ `{date}` / `{time}` in the browser locale, or `{date:FORMAT}` /
84
+ `{time:FORMAT}` with a Word date-time picture (d to dddd, M to MMMM, yy,
85
+ yyyy, h, hh, H, HH, m, mm, s, ss, am/pm, AM/PM, single-quoted literals,
86
+ English names). Tokens follow last-word's grammar exactly; anything else in
87
+ braces stays literal. In the body every token stays literal text. Values
88
+ render as plain text only.
89
+ - **Props:** `filename` (what `{filename}` shows; empty when absent) and `now`
90
+ (a Date or an ISO string; the moment `{date}` / `{time}` show, for
91
+ deterministic output).
92
+ - **Exports:** `pageCapacity`, `pageBand`, `pageClass`, `bandSlot`,
93
+ `pageBodyBoxes`, `formatDatePicture`, `resolveNow`, and the `BandKind`,
94
+ `BandSlot`, `PageClass`, `BandHeights` and `DocMeta` types. `PageFields`
95
+ gains optional `section`, `sectionPages`, `author`, `title`, `filename` and
96
+ `now`; `substituteFields(text, { page, pages })` still works as before.
97
+
13
98
  ## [0.1.1] - 2026-11-01
14
99
 
15
100
  ### Changed
package/README.md CHANGED
@@ -49,7 +49,9 @@ so a deep clone between numbering and render would lose the marks.
49
49
  | `scale` | `number` | | a fixed scale; overrides `fit` |
50
50
  | `maxScale` | `number` | `1` | the most `fit` will enlarge a page |
51
51
  | `gap` | `number` | `16` | px between pages |
52
- | `onLayout` | `(l) => void` | | `{ pages, pageWidth, pageHeight, scale }`, JSON |
52
+ | `filename` | `string` | `""` | what a `{filename}` band field shows |
53
+ | `now` | `Date \| string` | first render | the moment `{date}` / `{time}` show; an ISO string is fine |
54
+ | `onLayout` | `(l) => void` | | `{ pages, pageWidth, pageHeight, scale, font }`, JSON; see *Fonts* |
53
55
  | `injectStyles` | `boolean` | `true` | see *Styles* |
54
56
  | `id`, `className`, `style` | | | on the root |
55
57
 
@@ -58,7 +60,8 @@ so a deep clone between numbering and render would lose the marks.
58
60
  The root carries `data-lw-viewer`. Each page carries `data-page` (1-based), each
59
61
  block or fragment of a block carries `data-block` (`b0`, `b1`, ... in document
60
62
  order), each footnote carries `data-footnote`, and the bands carry
61
- `data-lw-band="header" | "footer"`. Table fragments carry `data-lw-rows`, plus
63
+ `data-lw-band="header" | "footer"`, with `data-lw-band-variant="default" |
64
+ "first" | "even"` naming the band drawn. Table fragments carry `data-lw-rows`, plus
62
65
  `data-lw-repeated-header` on continuation pages.
63
66
 
64
67
  ### Styles
@@ -72,6 +75,41 @@ rules instead:
72
75
  import "@particle-academy/last-word-ui/styles.css";
73
76
  ```
74
77
 
78
+ `styles.css` also declares the bundled font (below) with URLs relative to
79
+ itself (`../fonts/*.ttf`), so the bundler that imports it emits the font files.
80
+ Allow them in `font-src` (`'self'` covers it when you serve them from your own
81
+ origin).
82
+
83
+ ### Fonts: the same page count on every machine
84
+
85
+ Calibri, and text with no font named, draws in a **bundled Carlito** (family
86
+ `"LW Carlito"`, first in the stack). Carlito is metric-compatible with Calibri:
87
+ every printable ASCII and Latin-1 advance is identical in all four styles, so
88
+ lines break where Calibri's would. Because the font ships with the package, a
89
+ document paginates the same on a machine with Calibri, with Arial, or with
90
+ neither, and the count agrees with last-word's `Agent::layout()` (PHP, 0.17.0),
91
+ which measures with the same font's metrics.
92
+
93
+ - Kerning and ligatures are off, as they are in Word by default, so a line is
94
+ exactly the sum of its advances.
95
+ - The viewer **waits for the font** before it measures: no pages are drawn and
96
+ `onLayout` is not called until the faces the document uses have loaded (only
97
+ those are fetched; a plain memo never downloads the italics). After
98
+ `FONT_LOAD_TIMEOUT_MS` (3 s) it lays out without it.
99
+ - `onLayout` reports `font`: `"carlito"` (deterministic), `"fallback"` (the
100
+ font could not load, so the count depends on this machine) or `"unused"` (no
101
+ Calibri text). The root carries the same value as `data-lw-font`.
102
+ - Only Calibri and default text is deterministic. Any other font in the
103
+ document draws in that font as installed, as before.
104
+ - With `injectStyles` (the default) the `@font-face` rules point at the files
105
+ through `new URL("../fonts/...", import.meta.url)`, which Vite, webpack 5,
106
+ Rollup and Parcel resolve to emitted assets. The CommonJS build has no
107
+ `import.meta`, so there it reports `"fallback"`: import `styles.css` instead.
108
+
109
+ The four TTFs are Carlito 1.104 from
110
+ [googlefonts/carlito](https://github.com/googlefonts/carlito), shipped
111
+ unmodified under the SIL Open Font License 1.1 (`fonts/OFL.txt`, `fonts/NOTICE`).
112
+
75
113
  ## What it renders
76
114
 
77
115
  - **Pages:** letter, legal and a4, portrait or landscape, with margins as the
@@ -86,8 +124,22 @@ import "@particle-academy/last-word-ui/styles.css";
86
124
  edge (36pt when absent). They are either a left / centre / right band or
87
125
  blocks (a letterhead logo, address lines). A tall header pushes the body down,
88
126
  as in Word.
89
- - **Page numbers:** `{page}` and `{pages}` become live numbers on each page,
90
- in bands only. In the body they stay literal text, as in the file.
127
+ - **First-page and even-page bands** (last-word 0.16.0): page 1 draws
128
+ `page.firstHeader` / `page.firstFooter` when present, even pages (2, 4, ...)
129
+ `page.evenHeader` / `page.evenFooter`, and every other page the default.
130
+ `{"blocks": []}` as a variant blanks that page's band. Each page's body is
131
+ sized by the bands it actually draws, so a tall first-page letterhead moves
132
+ only page 1's body down.
133
+ - **Fields in bands:** `{page}`, `{pages}`; `{section}` and `{sectionpages}`
134
+ (a Doc is one section, so `1` and the page total); `{author}`
135
+ (`doc.meta.author`); `{title}` (the top-level `doc.title`; there is no
136
+ `meta.title`); `{filename}` (the `filename` prop); `{date}` and `{time}` in
137
+ the browser's locale, or `{date:FORMAT}` / `{time:FORMAT}` with a Word
138
+ picture (`d dd ddd dddd M MM MMM MMMM yy yyyy h hh H HH m mm s ss am/pm
139
+ AM/PM`, text in single quotes literal, English names). Unknown values are
140
+ empty. Names are lower-case and exact; anything else in braces stays
141
+ literal. All of it is drawn as plain text. In the body every token stays
142
+ literal text, as in the file.
91
143
  - **Footnotes:** numbered 1, 2, 3 in document order and set at the foot of the
92
144
  mark's page, under a short rule. Their height comes off that page's body.
93
145
  - **Content:** tables (widths, header rows, cell shading, borders, padding,
@@ -133,4 +185,5 @@ npm run demo # vite demo: a multi-page memo, wide and narrow
133
185
 
134
186
  ## License
135
187
 
136
- MIT
188
+ MIT, except the fonts in `fonts/`: Carlito, SIL Open Font License 1.1, see
189
+ `fonts/OFL.txt` and `fonts/NOTICE`.