@particle-academy/last-word-ui 0.5.0 → 0.7.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/AGENTS.md +76 -0
- package/CHANGELOG.md +85 -0
- package/README.md +35 -10
- package/dist/index.cjs +210 -42
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +80 -4
- package/dist/index.d.ts +80 -4
- package/dist/index.js +206 -44
- package/dist/index.js.map +1 -1
- package/package.json +9 -2
package/AGENTS.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Using @particle-academy/last-word-ui — guide for agents
|
|
2
|
+
|
|
3
|
+
How an agent installs and uses this package in a consumer app. What the package
|
|
4
|
+
is, is in [README.md](./README.md). Notes for working ON this repo's code are in
|
|
5
|
+
[CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @particle-academy/last-word-ui @particle-academy/react-fancy react react-dom
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- **Peers:** `@particle-academy/react-fancy` `>=5.0.0`, `react ^19`,
|
|
14
|
+
`react-dom ^19`. **Node:** `>=22`.
|
|
15
|
+
- **Charts are optional:** install `@particle-academy/fancy-echarts echarts` to
|
|
16
|
+
draw chart blocks; without them each chart is a sized, labelled placeholder.
|
|
17
|
+
- **The viewer does not read `.docx` bytes.** Read on the server (PHP
|
|
18
|
+
`particle-academy/last-word`, Python `fancy-last-word`) and send the JSON, or
|
|
19
|
+
read in the browser with `@particle-academy/last-word`.
|
|
20
|
+
|
|
21
|
+
## Find it on the Fancy MCP server
|
|
22
|
+
|
|
23
|
+
The catalog server is `https://ui.particle.academy/mcp` (streamable HTTP, no API
|
|
24
|
+
key; MCP id `fancy-ui`). This package's registry entry is
|
|
25
|
+
`last-word-ui-doc-viewer`. Find it with `search-components` ("document
|
|
26
|
+
viewer", "docx"), use `install-instructions` for the exact commands and
|
|
27
|
+
`get-component` for the source bundle. Vendored source:
|
|
28
|
+
`npx fancy-cli@latest add last-word-ui-doc-viewer`. The readers and writers are
|
|
29
|
+
found with `search-backend-packages`.
|
|
30
|
+
|
|
31
|
+
## API essentials
|
|
32
|
+
|
|
33
|
+
- `import { DocViewer, docFromReader } from "@particle-academy/last-word-ui"`;
|
|
34
|
+
`<DocViewer doc={doc} />`. `docFromReader()` takes a reader result or a JSON
|
|
35
|
+
string.
|
|
36
|
+
- **Props:** `doc`, `fit` (`"width" | "none"`), `scale`, `maxScale`, `gap`,
|
|
37
|
+
`filename`, `now`, `onLayout`, `injectStyles`, `renderChart`, `id`,
|
|
38
|
+
`className`, `style`. The full table is in the [README](./README.md).
|
|
39
|
+
- **`onLayout`** reports `{ pages, pageWidth, pageHeight, scale, font }` as
|
|
40
|
+
JSON; `font` is `"carlito"` (deterministic), `"fallback"` or `"unused"`.
|
|
41
|
+
- **Stable handles:** `data-lw-viewer` on the root, `data-page` (1-based) per
|
|
42
|
+
page, `data-block` (`b0`, `b1`, ...) per block or fragment, `data-footnote`,
|
|
43
|
+
`data-lw-band` / `data-lw-band-variant`, `data-lw-rows`,
|
|
44
|
+
`data-lw-repeated-header`, `data-lw-chart`, `data-lw-chart-placeholder`,
|
|
45
|
+
`data-lw-font`, `data-lw-tracked-changes` / `data-lw-tracked-changes-notice`.
|
|
46
|
+
- **Lower level:** `paginate()`, `pageGeometry()`, `pageMargins()`,
|
|
47
|
+
`bodyBox()`, `numberFootnotes()`, `substituteFields()` lay pages out without
|
|
48
|
+
the DOM.
|
|
49
|
+
|
|
50
|
+
## Traps
|
|
51
|
+
|
|
52
|
+
- **Render the object you were given.** Footnote numbering is keyed by run
|
|
53
|
+
identity, so deep-cloning the Doc between numbering and render loses the
|
|
54
|
+
marks.
|
|
55
|
+
- **Under a CSP without `'unsafe-inline'` styles**, pass
|
|
56
|
+
`injectStyles={false}` and `import "@particle-academy/last-word-ui/styles.css"`.
|
|
57
|
+
Allow the bundled font files in `font-src`.
|
|
58
|
+
- **The CommonJS build cannot resolve the bundled font** (no `import.meta`), so
|
|
59
|
+
it reports `font: "fallback"`; import `styles.css` there.
|
|
60
|
+
- **Only Calibri and default text paginate deterministically** (the bundled
|
|
61
|
+
Carlito). Other fonts draw as installed on the machine.
|
|
62
|
+
- **Nothing is drawn until the font loads**, up to `FONT_LOAD_TIMEOUT_MS`
|
|
63
|
+
(3 s).
|
|
64
|
+
- **Tracked changes are not shown, and that is a fail-safe.** A `doc` carrying any
|
|
65
|
+
`revision` key draws with a notice (`data-lw-tracked-changes-notice`), deleted and
|
|
66
|
+
moved-away runs (`delete`, `moveFrom`, or a revision it cannot read) are hidden,
|
|
67
|
+
and inserted text draws as normal text. Check `hasRevisions(doc)` (or `onLayout`'s
|
|
68
|
+
`revisions`) before showing a document, and have the person accept or reject the
|
|
69
|
+
changes first. The viewer never edits the model, so the revisions survive for
|
|
70
|
+
whatever writes the file back.
|
|
71
|
+
- **Not yet handled:** a table row taller than a page (`data-lw-overflow`), an
|
|
72
|
+
unbreakable block taller than a page (`data-lw-forced`), a footnote that does
|
|
73
|
+
not fit, page backgrounds and border frames.
|
|
74
|
+
- **A Doc is untrusted input:** links render only for `http(s)`, `mailto`,
|
|
75
|
+
`tel` and `#anchor`; images only from `data:image/...`; colours only as
|
|
76
|
+
`#RRGGBB`.
|
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.7.0] - 2026-11-22
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **Fail-safe: a document with tracked changes no longer draws deleted text as live
|
|
18
|
+
text.** last-word's model is gaining tracked-changes authoring: a `revision` key on
|
|
19
|
+
runs (`insert`, `delete`, `moveFrom`, `moveTo`, `format`), on paragraph and heading
|
|
20
|
+
blocks and on list items. This viewer cannot show revisions, and before this it drew
|
|
21
|
+
them as if they were not there, so deleted text read as part of the document. Now,
|
|
22
|
+
when a `doc` carries any `revision`: a run that was deleted or moved away
|
|
23
|
+
(`delete`, `moveFrom`) is not drawn, on the pages or in the measuring copy, and its
|
|
24
|
+
footnote is not numbered; inserted, moved-here and reformatted text draws as
|
|
25
|
+
before; a block-level mark keeps its text. A notice above the pages says so
|
|
26
|
+
(`TRACKED_CHANGES_NOTICE`, handle `data-lw-tracked-changes-notice` with
|
|
27
|
+
`data-lw-revisions`, the count), and the root gains `data-lw-tracked-changes`. A
|
|
28
|
+
`revision` this viewer cannot read counts as deleted: hiding text under a notice is
|
|
29
|
+
recoverable, showing deleted text as live is not. The viewer never changes the
|
|
30
|
+
model: the revisions are still there for the host to write back. This is a guard,
|
|
31
|
+
not support; there is no review UI. New exports: `hasRevisions(doc)`,
|
|
32
|
+
`revisionPaths(doc)` (JSON Pointers) and `isDeletedRun(run)`; `onLayout` gains
|
|
33
|
+
`revisions` (the same pointers), absent when there are none. A document without
|
|
34
|
+
revisions draws exactly as before; nothing to do.
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
|
|
38
|
+
- **CI: the lab-certificate gate verifies against the lab's rotated key list.**
|
|
39
|
+
The lab's first signing key is retired: certificates it already issued still
|
|
40
|
+
verify, and nothing new it signs ever can. Consumers do nothing.
|
|
41
|
+
|
|
42
|
+
- **Docs:** `AGENTS.md` is now the guide to using this package (install, its entries on the Fancy MCP catalog server, API essentials, traps), and it ships in the package. The contributor notes it held moved to `CONTRIBUTING.md`, and `CLAUDE.md` is now a symlink to it. The README points to the MCP server and to `AGENTS.md`. No code changed; nothing to do.
|
|
43
|
+
- CI: re-pin org third-party allowlist to 2614224
|
|
44
|
+
|
|
45
|
+
## [0.6.0] - 2026-11-15
|
|
46
|
+
|
|
47
|
+
**What you must do:** to see charts drawn, install the optional peer:
|
|
48
|
+
`npm install @particle-academy/fancy-echarts echarts`. Without it nothing
|
|
49
|
+
breaks and nothing moves: charts stay sized placeholders, as in 0.5.0, now with
|
|
50
|
+
a development warning. Page breaks do not move either way: a chart's box is the
|
|
51
|
+
same size as before.
|
|
52
|
+
|
|
53
|
+
### Fixed
|
|
54
|
+
|
|
55
|
+
- **Charts draw as charts** (last-word-ui#1). Every chart block from
|
|
56
|
+
last-word's native charts drew as a dashed "Chart: <title>" placeholder,
|
|
57
|
+
although the `.docx` was correct. The block's ECharts `option` is now drawn
|
|
58
|
+
by fancy-echarts' `EChart` at the block's size, inside the page: column, bar,
|
|
59
|
+
line and pie. The sheet is white paper in every colour scheme, so the chart
|
|
60
|
+
gets an explicit light theme (left unset, fancy-echarts picks its dark theme
|
|
61
|
+
from the OS and draws light text on the white page), a transparent
|
|
62
|
+
background, the SVG renderer (sharp under the page scale and in print) and no
|
|
63
|
+
animation. The block's own keys win over each default.
|
|
64
|
+
- **The viewer has a box while it lays out.** Until the font loaded and the
|
|
65
|
+
first layout ran (up to `FONT_LOAD_TIMEOUT_MS`, 3 s), `DocViewer`'s root held
|
|
66
|
+
only the offscreen measuring copy, so it was 0 px high: the page jumped when
|
|
67
|
+
the sheets arrived, and a kit-site inspector measuring early saw a viewer
|
|
68
|
+
with no box at all. It now draws one blank sheet (`data-lw-pending`) at the
|
|
69
|
+
first page's scaled size and marks the root `aria-busy="true"` until the
|
|
70
|
+
pages replace it. Measuring, page breaks and `onLayout` are unchanged.
|
|
71
|
+
Nothing to do; if you style the viewer, `[data-lw-pending]` is the new handle.
|
|
72
|
+
|
|
73
|
+
### Added
|
|
74
|
+
|
|
75
|
+
- `@particle-academy/fancy-echarts` (`>=6.1.0 <7.0.0`) as an **optional** peer.
|
|
76
|
+
It is imported dynamically on first use, in the browser only, so a document
|
|
77
|
+
with no charts loads no charting engine and server rendering draws the empty,
|
|
78
|
+
sized box with no hydration mismatch.
|
|
79
|
+
- `renderChart` prop on `DocViewer`: draw a chart yourself, given
|
|
80
|
+
`{ block, option, width, height, title }`. Return `undefined` to leave a
|
|
81
|
+
chart to the default.
|
|
82
|
+
- `pageChartOption()`, `OFFICE_PALETTE`, and the `ChartRenderArgs` and
|
|
83
|
+
`RenderChart` types.
|
|
84
|
+
- Chart blocks carry `data-lw-chart`. Without fancy-echarts, a placeholder
|
|
85
|
+
still carries `data-lw-chart-placeholder`, and a development warning (once)
|
|
86
|
+
names the package to install and the `renderChart` alternative.
|
|
87
|
+
|
|
88
|
+
### Changed
|
|
89
|
+
|
|
90
|
+
- The hidden measuring copy draws a chart's box only, never the chart, so a
|
|
91
|
+
chart is never initialised twice. The box is the size it was, so page breaks
|
|
92
|
+
do not move.
|
|
93
|
+
- **Releases need a lab-run certificate.** `publish.yml` gains a read-only
|
|
94
|
+
`lab-certificate` job that every publishing job needs: a tag is published only
|
|
95
|
+
when the fancy-labs lab has certified that exact version and commit. Consumers
|
|
96
|
+
do nothing; this changes how releases are cut, not what the package does.
|
|
97
|
+
|
|
13
98
|
## [0.5.0] - 2026-11-04
|
|
14
99
|
|
|
15
100
|
### Added
|
package/README.md
CHANGED
|
@@ -10,6 +10,13 @@ reflows the text.
|
|
|
10
10
|
> **Pre-1.0:** breaking changes land in MINOR releases. Read the
|
|
11
11
|
> [CHANGELOG](./CHANGELOG.md) entry before taking one.
|
|
12
12
|
|
|
13
|
+
<!-- fancy-agents-note:start -->
|
|
14
|
+
> **For agents.** This package is listed on the Fancy MCP catalog server at
|
|
15
|
+
> `https://ui.particle.academy/mcp` (streamable HTTP, no API key; MCP id `fancy-ui`),
|
|
16
|
+
> with install commands and docs, alongside the rest of the kit. How an agent
|
|
17
|
+
> installs and uses this package is in [AGENTS.md](https://github.com/Particle-Academy/last-word-ui/blob/main/AGENTS.md).
|
|
18
|
+
<!-- fancy-agents-note:end -->
|
|
19
|
+
|
|
13
20
|
## Install
|
|
14
21
|
|
|
15
22
|
```bash
|
|
@@ -53,8 +60,35 @@ so a deep clone between numbering and render would lose the marks.
|
|
|
53
60
|
| `now` | `Date \| string` | first render | the moment `{date}` / `{time}` show; an ISO string is fine |
|
|
54
61
|
| `onLayout` | `(l) => void` | | `{ pages, pageWidth, pageHeight, scale, font }`, JSON; see *Fonts* |
|
|
55
62
|
| `injectStyles` | `boolean` | `true` | see *Styles* |
|
|
63
|
+
| `renderChart` | `(chart) => ReactNode \| undefined` | | draws a chart block instead of the default; see *Charts* |
|
|
56
64
|
| `id`, `className`, `style` | | | on the root |
|
|
57
65
|
|
|
66
|
+
### Charts
|
|
67
|
+
|
|
68
|
+
A chart block (last-word's native Word charts: column, bar, line, pie) is drawn
|
|
69
|
+
by `EChart` from `@particle-academy/fancy-echarts`, an optional peer, at the
|
|
70
|
+
block's size inside the page. Install it to draw charts:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npm install @particle-academy/fancy-echarts echarts
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
It is loaded on first use, in the browser only, so a document with no charts
|
|
77
|
+
never loads a charting engine and server rendering draws the empty, sized box.
|
|
78
|
+
The sheet is white paper in every colour scheme, so the chart is drawn in a
|
|
79
|
+
light theme with a transparent background, as SVG (sharp at any scale and in
|
|
80
|
+
print), with animation off. `pageChartOption(option)` is that option, and the
|
|
81
|
+
block's own keys win.
|
|
82
|
+
|
|
83
|
+
Without fancy-echarts, each chart is a sized, labelled placeholder, so the
|
|
84
|
+
page breaks where it would with the chart, and a development warning says so.
|
|
85
|
+
|
|
86
|
+
`renderChart` replaces the default for any chart: it gets
|
|
87
|
+
`{ block, option, width, height, title }` (size in CSS px at 100%) and returns
|
|
88
|
+
what to draw at exactly that size, or `undefined` to leave that chart to the
|
|
89
|
+
default. Chart blocks carry `data-lw-chart`; a placeholder carries
|
|
90
|
+
`data-lw-chart-placeholder`.
|
|
91
|
+
|
|
58
92
|
### Stable handles
|
|
59
93
|
|
|
60
94
|
The root carries `data-lw-viewer`. Each page carries `data-page` (1-based), each
|
|
@@ -146,11 +180,10 @@ unmodified under the SIL Open Font License 1.1 (`fonts/OFL.txt`, `fonts/NOTICE`)
|
|
|
146
180
|
vertical alignment, spans), paragraph alignment, shading, borders, indents
|
|
147
181
|
and spacing, run styling (bold, italic, underline, strike, colour, highlight,
|
|
148
182
|
size, font, small caps, letter spacing, inline code, links), headings,
|
|
149
|
-
lists, quotes, code, images and rules.
|
|
183
|
+
lists, quotes, code, images, charts (see *Charts*) and rules.
|
|
150
184
|
|
|
151
185
|
### Not yet (v0)
|
|
152
186
|
|
|
153
|
-
- Charts draw as a sized, labelled placeholder, so pagination stays right.
|
|
154
187
|
- A table **row** taller than a page is not split. It is placed alone and
|
|
155
188
|
flagged with `data-lw-overflow`.
|
|
156
189
|
- A block with no line breaks that is taller than a page (a huge image) is cut
|
|
@@ -175,14 +208,6 @@ It takes heights in and returns page assignments, with no DOM. Use it with
|
|
|
175
208
|
applied), `bodyBox()`, `numberFootnotes(doc)` and `substituteFields()` to lay
|
|
176
209
|
pages out elsewhere.
|
|
177
210
|
|
|
178
|
-
## Develop
|
|
179
|
-
|
|
180
|
-
```bash
|
|
181
|
-
npm test # vitest + jsdom
|
|
182
|
-
npm run lint # tsc + eslint
|
|
183
|
-
npm run demo # vite demo: a multi-page memo, wide and narrow
|
|
184
|
-
```
|
|
185
|
-
|
|
186
211
|
## License
|
|
187
212
|
|
|
188
213
|
MIT, except the fonts in `fonts/`: Carlito, SIL Open Font License 1.1, see
|