@particle-academy/last-word-ui 0.5.0 → 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,59 @@ 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
+
13
66
  ## [0.5.0] - 2026-11-04
14
67
 
15
68
  ### Added
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
package/dist/index.cjs CHANGED
@@ -53,6 +53,122 @@ function bodyBox(g, headerHeight, footerHeight) {
53
53
  const bottom = Math.max(g.margins.bottom, footerHeight > 0 ? g.margins.footer + footerHeight : 0);
54
54
  return { top, bottom, height: Math.max(1, g.height - top - bottom) };
55
55
  }
56
+ var OFFICE_PALETTE = ["#4472C4", "#ED7D31", "#A5A5A5", "#FFC000", "#5B9BD5", "#70AD47", "#264478", "#9E480E"];
57
+ var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
58
+ function pageChartOption(option) {
59
+ const o = isObj(option) ? option : {};
60
+ const hasAxes = o.xAxis !== void 0 || o.yAxis !== void 0;
61
+ const legendShown = isObj(o.legend) && o.legend.show !== false;
62
+ return {
63
+ backgroundColor: "transparent",
64
+ color: OFFICE_PALETTE,
65
+ animation: false,
66
+ ...o,
67
+ ...hasAxes ? {
68
+ grid: o.grid ?? {
69
+ top: o.title ? 36 : 16,
70
+ right: 16,
71
+ bottom: 8 + (legendShown ? 28 : 0),
72
+ left: 8,
73
+ outerBoundsMode: "same",
74
+ outerBoundsContain: "all"
75
+ }
76
+ } : {}
77
+ };
78
+ }
79
+ function chartTitle(block) {
80
+ const title = isObj(block.option) ? block.option.title : void 0;
81
+ if (typeof title === "string") return title;
82
+ if (isObj(title) && typeof title.text === "string") return title.text;
83
+ return typeof block.alt === "string" ? block.alt : "";
84
+ }
85
+ var PENDING = { status: "pending" };
86
+ var MISSING = { status: "missing" };
87
+ var peer = PENDING;
88
+ var loading = null;
89
+ var listeners = /* @__PURE__ */ new Set();
90
+ function loadPeer() {
91
+ if (loading) return;
92
+ loading = import('@particle-academy/fancy-echarts').then((ns) => {
93
+ const mod = ns;
94
+ const EChart = mod.EChart;
95
+ if (typeof EChart !== "function" && typeof EChart !== "object") return MISSING;
96
+ mod.registerAll?.();
97
+ return { status: "ready", EChart };
98
+ }).catch(() => MISSING).then((state) => {
99
+ peer = state;
100
+ listeners.forEach((l) => l());
101
+ });
102
+ }
103
+ function subscribe(listener) {
104
+ listeners.add(listener);
105
+ loadPeer();
106
+ return () => listeners.delete(listener);
107
+ }
108
+ var getSnapshot = () => peer;
109
+ var getServerSnapshot = () => PENDING;
110
+ var warned = false;
111
+ function warnMissing() {
112
+ if (warned) return;
113
+ const env = globalThis.process?.env;
114
+ if (env?.NODE_ENV === "production") return;
115
+ warned = true;
116
+ console.warn(
117
+ "[last-word-ui] This document has charts, but @particle-academy/fancy-echarts is not installed, so they draw as placeholders. Install it (npm i @particle-academy/fancy-echarts echarts) to draw them, or pass DocViewer a renderChart prop."
118
+ );
119
+ }
120
+ var PAPER_THEME = {};
121
+ function ChartBox({ block, width, height: height2, measuring, renderChart }) {
122
+ const title = chartTitle(block);
123
+ return /* @__PURE__ */ jsxRuntime.jsx(
124
+ "div",
125
+ {
126
+ "data-lw-chart": "",
127
+ role: measuring ? void 0 : "img",
128
+ "aria-label": measuring || !title ? void 0 : title,
129
+ style: { width, height: height2, overflow: "hidden" },
130
+ children: measuring ? null : /* @__PURE__ */ jsxRuntime.jsx(ChartContent, { block, width, height: height2, title, renderChart })
131
+ }
132
+ );
133
+ }
134
+ function ChartContent({ block, width, height: height2, title, renderChart }) {
135
+ const option = react.useMemo(() => pageChartOption(block.option), [block.option]);
136
+ if (renderChart) {
137
+ const custom = renderChart({ block, option, width, height: height2, title });
138
+ if (custom !== void 0) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: custom });
139
+ }
140
+ return /* @__PURE__ */ jsxRuntime.jsx(DefaultChart, { option, width, height: height2, title });
141
+ }
142
+ function DefaultChart({ option, width, height: height2, title }) {
143
+ const state = react.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
144
+ if (state.status === "ready") {
145
+ const { EChart } = state;
146
+ return /* @__PURE__ */ jsxRuntime.jsx(EChart, { option, theme: PAPER_THEME, renderer: "svg", autoResize: false, style: { width, height: height2 } });
147
+ }
148
+ if (state.status === "missing") return /* @__PURE__ */ jsxRuntime.jsx(Placeholder, { width, height: height2, title });
149
+ return null;
150
+ }
151
+ function Placeholder({ width, height: height2, title }) {
152
+ react.useEffect(warnMissing, []);
153
+ return /* @__PURE__ */ jsxRuntime.jsx(
154
+ "div",
155
+ {
156
+ "data-lw-chart-placeholder": "",
157
+ style: {
158
+ width,
159
+ height: height2,
160
+ border: "0.75pt dashed #9CA3AF",
161
+ color: "#6B7280",
162
+ fontSize: "9pt",
163
+ display: "flex",
164
+ alignItems: "center",
165
+ justifyContent: "center",
166
+ boxSizing: "border-box"
167
+ },
168
+ children: title ? `Chart: ${title}` : "Chart"
169
+ }
170
+ );
171
+ }
56
172
 
57
173
  // src/fields.ts
58
174
  var FIELD = /\{(?:(page|pages|section|sectionpages|author|title|filename)|(date|time)(?::([^{}"\\]+))?)\}/g;
@@ -536,7 +652,7 @@ function BlockView({ block }) {
536
652
  case "image":
537
653
  return /* @__PURE__ */ jsxRuntime.jsx(ImageView, { block });
538
654
  case "chart":
539
- return /* @__PURE__ */ jsxRuntime.jsx(ChartPlaceholder, { block });
655
+ return /* @__PURE__ */ jsxRuntime.jsx(ChartView, { block });
540
656
  case "hr":
541
657
  return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-kind": "hr", style: { display: "flow-root", paddingBottom: pt(ctx.spaceAfter) }, children: /* @__PURE__ */ jsxRuntime.jsx("div", { style: { height: pt(ctx.size * SINGLE_LINE), display: "flex", alignItems: "flex-end" }, children: /* @__PURE__ */ jsxRuntime.jsx(reactFancy.Separator, { className: "w-full" }) }) });
542
658
  case "pageBreak":
@@ -588,7 +704,7 @@ function ImageView({ block }) {
588
704
  }
589
705
  ) });
590
706
  }
591
- function ChartPlaceholder({ block }) {
707
+ function ChartView({ block }) {
592
708
  const ctx = react.useContext(RenderCtx);
593
709
  const maxPx = ctx.contentWidth * PX_PER_PT;
594
710
  const width = Math.min(
@@ -596,26 +712,7 @@ function ChartPlaceholder({ block }) {
596
712
  num(block.widthPx, typeof block.width === "number" && block.width > 0 ? maxPx * Math.min(100, block.width) / 100 : maxPx)
597
713
  );
598
714
  const height2 = num(block.heightPx, width * 0.6);
599
- const option = block.option ?? {};
600
- const title = typeof option.title === "string" ? option.title : option.title && typeof option.title.text === "string" ? option.title.text : typeof block.alt === "string" ? block.alt : "";
601
- return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-kind": "chart", style: { display: "flow-root", paddingBottom: pt(ctx.spaceAfter) }, children: /* @__PURE__ */ jsxRuntime.jsx(
602
- "div",
603
- {
604
- "data-lw-chart-placeholder": "",
605
- style: {
606
- width,
607
- height: height2,
608
- border: "0.75pt dashed #9CA3AF",
609
- color: "#6B7280",
610
- fontSize: pt(9),
611
- display: "flex",
612
- alignItems: "center",
613
- justifyContent: "center",
614
- boxSizing: "border-box"
615
- },
616
- children: title ? `Chart: ${title}` : "Chart"
617
- }
618
- ) });
715
+ return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-kind": "chart", style: { display: "flow-root", paddingBottom: pt(ctx.spaceAfter) }, children: /* @__PURE__ */ jsxRuntime.jsx(ChartBox, { block, width, height: height2, measuring: ctx.measuring, renderChart: ctx.renderChart }) });
619
716
  }
620
717
  var DEFAULT_TABLE_BORDER = { style: "single", width: 0.5 };
621
718
  var DEFAULT_CELL_PADDING = { top: 3, right: 5.4, bottom: 3, left: 5.4 };
@@ -1384,6 +1481,7 @@ function DocViewer({
1384
1481
  now,
1385
1482
  onLayout,
1386
1483
  injectStyles = true,
1484
+ renderChart,
1387
1485
  id,
1388
1486
  className,
1389
1487
  style
@@ -1427,9 +1525,10 @@ function DocViewer({
1427
1525
  marks: numbering.marks,
1428
1526
  size: num(doc?.defaultSize, DEFAULT_SIZE),
1429
1527
  spaceAfter: DEFAULT_SPACE_AFTER,
1430
- contentWidth: geometry.contentWidth
1528
+ contentWidth: geometry.contentWidth,
1529
+ ...renderChart ? { renderChart } : {}
1431
1530
  }),
1432
- [numbering, doc, geometry]
1531
+ [numbering, doc, geometry, renderChart]
1433
1532
  );
1434
1533
  const ctxOf = (k) => ({ ...ctx, contentWidth: stretches[k].geometry.contentWidth });
1435
1534
  react.useEffect(() => {
@@ -1500,6 +1599,7 @@ function DocViewer({
1500
1599
  "data-lw-viewer": "",
1501
1600
  "data-lw-pages": ready && pageCount || void 0,
1502
1601
  "data-lw-font": ready ? font : void 0,
1602
+ "aria-busy": ready ? void 0 : true,
1503
1603
  className,
1504
1604
  style: { position: "relative", ...style },
1505
1605
  children: [
@@ -1529,7 +1629,7 @@ function DocViewer({
1529
1629
  if (!hasBand(band)) return null;
1530
1630
  const n = slot === "even" ? 2 : 1;
1531
1631
  const at = k === 0 ? `${kind}:${slot}` : `${k + 1}:${kind}:${slot}`;
1532
- return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-measure-band": at, style: stretches.length > 1 ? { width: pt(stretch.geometry.contentWidth) } : void 0, children: /* @__PURE__ */ jsxRuntime.jsx(RenderCtx.Provider, { value: { ...ctxOf(k), fields: { ...docFields, section: k + 1, page: n, pages: n } }, children: /* @__PURE__ */ jsxRuntime.jsx(BandView, { band }) }) }, at);
1632
+ return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-measure-band": at, style: stretches.length > 1 ? { width: pt(stretch.geometry.contentWidth) } : void 0, children: /* @__PURE__ */ jsxRuntime.jsx(RenderCtx.Provider, { value: { ...ctxOf(k), measuring: true, fields: { ...docFields, section: k + 1, page: n, pages: n } }, children: /* @__PURE__ */ jsxRuntime.jsx(BandView, { band }) }) }, at);
1533
1633
  })
1534
1634
  )
1535
1635
  ),
@@ -1540,19 +1640,31 @@ function DocViewer({
1540
1640
  {
1541
1641
  "data-lw-measure-block": i,
1542
1642
  style: { display: "flow-root", ...stretches.length > 1 ? { width: pt(stretches[k].geometry.contentWidth) } : {} },
1543
- children: /* @__PURE__ */ jsxRuntime.jsx(RenderCtx.Provider, { value: ctxOf(k), children: /* @__PURE__ */ jsxRuntime.jsx(BlockView, { block: b }) })
1643
+ children: /* @__PURE__ */ jsxRuntime.jsx(RenderCtx.Provider, { value: { ...ctxOf(k), measuring: true }, children: /* @__PURE__ */ jsxRuntime.jsx(BlockView, { block: b }) })
1544
1644
  },
1545
1645
  i
1546
1646
  );
1547
1647
  }),
1548
1648
  numbering.notes.map((n) => {
1549
1649
  const k = noteStretch.get(n.id) ?? 0;
1550
- return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-measure-footnote": n.id, style: stretches.length > 1 ? { width: pt(stretches[k].geometry.contentWidth) } : void 0, children: /* @__PURE__ */ jsxRuntime.jsx(RenderCtx.Provider, { value: ctxOf(k), children: /* @__PURE__ */ jsxRuntime.jsx(FootnoteView, { id: n.id, footnote: n.footnote }) }) }, n.id);
1650
+ return /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-measure-footnote": n.id, style: stretches.length > 1 ? { width: pt(stretches[k].geometry.contentWidth) } : void 0, children: /* @__PURE__ */ jsxRuntime.jsx(RenderCtx.Provider, { value: { ...ctxOf(k), measuring: true }, children: /* @__PURE__ */ jsxRuntime.jsx(FootnoteView, { id: n.id, footnote: n.footnote }) }) }, n.id);
1551
1651
  }),
1552
1652
  numbering.notes.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-measure-separator": "", children: /* @__PURE__ */ jsxRuntime.jsx(FootnoteSeparator, { height: pt(FOOTNOTE_SEPARATOR_PT) }) })
1553
1653
  ] })
1554
1654
  }
1555
1655
  ),
1656
+ !ready && /* @__PURE__ */ jsxRuntime.jsx(
1657
+ "div",
1658
+ {
1659
+ "data-lw-pending": "",
1660
+ style: {
1661
+ width: px(stretches[0].geometry.width * PX_PER_PT * scale),
1662
+ maxWidth: "100%",
1663
+ height: px(stretches[0].geometry.height * PX_PER_PT * scale),
1664
+ margin: "0 auto"
1665
+ }
1666
+ }
1667
+ ),
1556
1668
  ready && layout && /* @__PURE__ */ jsxRuntime.jsx("div", { "data-lw-page-stack": "", style: { display: "flex", flexDirection: "column", alignItems: "center", gap }, children: layout.pages.map((p) => {
1557
1669
  const k = p.stretch ?? 0;
1558
1670
  const inStretch = layout.pages.filter((x) => (x.stretch ?? 0) === k);
@@ -1714,6 +1826,7 @@ exports.CARLITO_FAMILY = CARLITO_FAMILY;
1714
1826
  exports.DocViewer = DocViewer;
1715
1827
  exports.FONT_LOAD_TIMEOUT_MS = FONT_LOAD_TIMEOUT_MS;
1716
1828
  exports.LAYOUT_NOTICE = LAYOUT_NOTICE;
1829
+ exports.OFFICE_PALETTE = OFFICE_PALETTE;
1717
1830
  exports.PAGE_BAND_DISTANCE_DEFAULT = PAGE_BAND_DISTANCE_DEFAULT;
1718
1831
  exports.PAGE_MARGIN_DEFAULT = PAGE_MARGIN_DEFAULT;
1719
1832
  exports.PAGE_SIZES_PT = PAGE_SIZES_PT;
@@ -1731,6 +1844,7 @@ exports.packInput = packInput;
1731
1844
  exports.pageBand = pageBand;
1732
1845
  exports.pageBodyBoxes = pageBodyBoxes;
1733
1846
  exports.pageCapacity = pageCapacity;
1847
+ exports.pageChartOption = pageChartOption;
1734
1848
  exports.pageClass = pageClass;
1735
1849
  exports.pageClassIn = pageClassIn;
1736
1850
  exports.pageGeometry = pageGeometry;