@particle-academy/last-word-ui 0.4.1 → 0.6.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,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [0.6.0] - 2026-11-15
14
+
15
+ **What you must do:** to see charts drawn, install the optional peer:
16
+ `npm install @particle-academy/fancy-echarts echarts`. Without it nothing
17
+ breaks and nothing moves: charts stay sized placeholders, as in 0.5.0, now with
18
+ a development warning. Page breaks do not move either way: a chart's box is the
19
+ same size as before.
20
+
21
+ ### Fixed
22
+
23
+ - **Charts draw as charts** (last-word-ui#1). Every chart block from
24
+ last-word's native charts drew as a dashed "Chart: <title>" placeholder,
25
+ although the `.docx` was correct. The block's ECharts `option` is now drawn
26
+ by fancy-echarts' `EChart` at the block's size, inside the page: column, bar,
27
+ line and pie. The sheet is white paper in every colour scheme, so the chart
28
+ gets an explicit light theme (left unset, fancy-echarts picks its dark theme
29
+ from the OS and draws light text on the white page), a transparent
30
+ background, the SVG renderer (sharp under the page scale and in print) and no
31
+ animation. The block's own keys win over each default.
32
+ - **The viewer has a box while it lays out.** Until the font loaded and the
33
+ first layout ran (up to `FONT_LOAD_TIMEOUT_MS`, 3 s), `DocViewer`'s root held
34
+ only the offscreen measuring copy, so it was 0 px high: the page jumped when
35
+ the sheets arrived, and a kit-site inspector measuring early saw a viewer
36
+ with no box at all. It now draws one blank sheet (`data-lw-pending`) at the
37
+ first page's scaled size and marks the root `aria-busy="true"` until the
38
+ pages replace it. Measuring, page breaks and `onLayout` are unchanged.
39
+ Nothing to do; if you style the viewer, `[data-lw-pending]` is the new handle.
40
+
41
+ ### Added
42
+
43
+ - `@particle-academy/fancy-echarts` (`>=6.1.0 <7.0.0`) as an **optional** peer.
44
+ It is imported dynamically on first use, in the browser only, so a document
45
+ with no charts loads no charting engine and server rendering draws the empty,
46
+ sized box with no hydration mismatch.
47
+ - `renderChart` prop on `DocViewer`: draw a chart yourself, given
48
+ `{ block, option, width, height, title }`. Return `undefined` to leave a
49
+ chart to the default.
50
+ - `pageChartOption()`, `OFFICE_PALETTE`, and the `ChartRenderArgs` and
51
+ `RenderChart` types.
52
+ - Chart blocks carry `data-lw-chart`. Without fancy-echarts, a placeholder
53
+ still carries `data-lw-chart-placeholder`, and a development warning (once)
54
+ names the package to install and the `renderChart` alternative.
55
+
56
+ ### Changed
57
+
58
+ - The hidden measuring copy draws a chart's box only, never the chart, so a
59
+ chart is never initialised twice. The box is the size it was, so page breaks
60
+ do not move.
61
+ - **Releases need a lab-run certificate.** `publish.yml` gains a read-only
62
+ `lab-certificate` job that every publishing job needs: a tag is published only
63
+ when the fancy-labs lab has certified that exact version and commit. Consumers
64
+ do nothing; this changes how releases are cut, not what the package does.
65
+
66
+ ## [0.5.0] - 2026-11-04
67
+
68
+ ### Added
69
+
70
+ - **Mixed page orientation.** A `pageBreak` carrying `page` changes the page from there on: each page is drawn at its own size and margins, with its own bands, and its text measured at its own width. `margins` merge side by side, every other key is replaced whole, `firstHeader` / `firstFooter` are never inherited and on a break mean the first page after it, and even bands follow the page number. `{section}` counts the stretches and `{sectionpages}` is the page count of the current one, as Word's `SECTION` and `SECTIONPAGES`. One scale serves every page, from the widest.
71
+ - `docStretches()`, `blockStretches()`, `packInput()`, `pageClassIn()`. `paginate()` takes a `stretch` on a break item and `firstEvenPageHeight`; `pageCapacity()` a stretch's first page index.
72
+ - `onLayout` reports `pageSizes` when the document's page changes partway. `pageWidth` and `pageHeight` stay the first page's.
73
+
74
+ ### Changed
75
+
76
+ - The notice no longer fires for a `page` on a top-level break, because that is drawn now. It still fires for what the writers refuse (a nested `page`, a background on a break, page keys straight on a break, a top-level `sections`), in new words. **Consumer action:** none, unless you compared `LAYOUT_NOTICE`'s text.
77
+ - `tests/fixtures/viewer-agreement.json` has a tenth case, recorded in headless Chromium; the first nine did not move.
78
+
13
79
  ## [0.4.1] - 2026-11-03
14
80
 
15
81
  **What you must do: nothing.** A document with a `colSpan` of 1000 or less draws
package/README.md CHANGED
@@ -53,8 +53,35 @@ so a deep clone between numbering and render would lose the marks.
53
53
  | `now` | `Date \| string` | first render | the moment `{date}` / `{time}` show; an ISO string is fine |
54
54
  | `onLayout` | `(l) => void` | | `{ pages, pageWidth, pageHeight, scale, font }`, JSON; see *Fonts* |
55
55
  | `injectStyles` | `boolean` | `true` | see *Styles* |
56
+ | `renderChart` | `(chart) => ReactNode \| undefined` | | draws a chart block instead of the default; see *Charts* |
56
57
  | `id`, `className`, `style` | | | on the root |
57
58
 
59
+ ### Charts
60
+
61
+ A chart block (last-word's native Word charts: column, bar, line, pie) is drawn
62
+ by `EChart` from `@particle-academy/fancy-echarts`, an optional peer, at the
63
+ block's size inside the page. Install it to draw charts:
64
+
65
+ ```bash
66
+ npm install @particle-academy/fancy-echarts echarts
67
+ ```
68
+
69
+ It is loaded on first use, in the browser only, so a document with no charts
70
+ never loads a charting engine and server rendering draws the empty, sized box.
71
+ The sheet is white paper in every colour scheme, so the chart is drawn in a
72
+ light theme with a transparent background, as SVG (sharp at any scale and in
73
+ print), with animation off. `pageChartOption(option)` is that option, and the
74
+ block's own keys win.
75
+
76
+ Without fancy-echarts, each chart is a sized, labelled placeholder, so the
77
+ page breaks where it would with the chart, and a development warning says so.
78
+
79
+ `renderChart` replaces the default for any chart: it gets
80
+ `{ block, option, width, height, title }` (size in CSS px at 100%) and returns
81
+ what to draw at exactly that size, or `undefined` to leave that chart to the
82
+ default. Chart blocks carry `data-lw-chart`; a placeholder carries
83
+ `data-lw-chart-placeholder`.
84
+
58
85
  ### Stable handles
59
86
 
60
87
  The root carries `data-lw-viewer`. Each page carries `data-page` (1-based), each
@@ -146,11 +173,10 @@ unmodified under the SIL Open Font License 1.1 (`fonts/OFL.txt`, `fonts/NOTICE`)
146
173
  vertical alignment, spans), paragraph alignment, shading, borders, indents
147
174
  and spacing, run styling (bold, italic, underline, strike, colour, highlight,
148
175
  size, font, small caps, letter spacing, inline code, links), headings,
149
- lists, quotes, code, images and rules.
176
+ lists, quotes, code, images, charts (see *Charts*) and rules.
150
177
 
151
178
  ### Not yet (v0)
152
179
 
153
- - Charts draw as a sized, labelled placeholder, so pagination stays right.
154
180
  - A table **row** taller than a page is not split. It is placed alone and
155
181
  flagged with `data-lw-overflow`.
156
182
  - A block with no line breaks that is taller than a page (a huge image) is cut