@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/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
|
-
| `
|
|
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"
|
|
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
|
-
- **
|
|
90
|
-
|
|
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`.
|