@particle-academy/last-word-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Pre-1.0:** breaking changes land in MINOR releases. Until 1.0 the minor
+> number is not a compatibility promise. Read the entry, not the version.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-01
+
+First release. **What you must do:** install it beside `react` 19 and
+`@particle-academy/react-fancy` 5, then render `<DocViewer doc={doc} />` with the
+JSON a last-word reader returns. last-word itself is NOT a dependency: read the
+file on the server, or with `@particle-academy/last-word`, and pass the result in.
+
+### Added
+
+- **`<DocViewer doc />`**, a read-only, paged view of a last-word `Doc`:
+  - every page at its paper size and orientation (letter, legal, a4);
+  - pages broken by CONTENT HEIGHT, as well as at explicit `pageBreak`s.
+    Paragraphs, headings, lists, quotes and code split between lines, with
+    Word's widow/orphan rule on paragraphs. Tables split between rows, repeat
+    their header rows on each continuation page, and never break inside a row
+    span. Headings keep with the next block;
+  - header and footer at their distances (`page.margins.header` / `.footer`,
+    36pt when absent), as a one-line left/centre/right band or as blocks (a
+    letterhead logo, address lines). The body moves down when a header is
+    taller than the top margin, as Word does;
+  - `{page}` / `{pages}` as live numbers on every page, in bands only;
+  - footnotes (the last-word 0.15.0 model: a run `{"text": "", "footnote":
+    {"blocks": [...]}}`), numbered 1, 2, 3 in document order and set at the
+    foot of the page holding the mark, under a separator rule. Their height
+    comes off that page's body;
+  - tables (widths, header rows and their default fill, cell shading, borders,
+    padding, vertical alignment, column and row spans), paragraph alignment,
+    shading, borders, indents and spacing, run styling, headings, lists,
+    quotes, code, images and rules, all as the reader returns them;
+  - scales whole pages to fit the panel (`fit`, `scale`, `maxScale`) and never
+    reflows;
+  - stable handles: `data-page`, `data-block` (`b0`, `b1`, ...),
+    `data-footnote`, `data-lw-band`; `onLayout` reports `{pages, pageWidth,
+    pageHeight, scale}` as JSON.
+- **`paginate(items, options)`**, the pure page packer behind the viewer:
+  heights in, page assignments out, no DOM.
+- **`pageGeometry(doc)`, `pageMargins(doc)`, `bodyBox()`**: the page model,
+  with the ONE place margin defaults are applied (72pt a side, 36pt to each
+  band), mirroring PHP last-word's `Schema::pageMargins()`.
+- **`docFromReader(output)`**: accepts a reader's Doc, or its JSON string.
+- `numberFootnotes(doc)` and `substituteFields(text, fields)`.
+
+### Security
+
+- A Doc is untrusted input. Links render only for `http(s)`, `mailto`, `tel`
+  and `#anchor` URLs, so a `javascript:` link never reaches an `href`. Images
+  render only from embedded `data:image/...` URLs, so a document cannot make
+  the reader's browser fetch a remote URL (a tracking pixel). Colours reach CSS
+  only as `#RRGGBB`, and font names are reduced to safe characters.
+
+### Not yet
+
+- Charts draw as a sized, labelled placeholder (pagination stays right).
+- A table ROW taller than a page is not split; it is placed alone and flagged
+  `data-lw-overflow`. A footnote taller than the space left does not continue
+  onto the next page. Page `background` and `border` are not drawn yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# @particle-academy/last-word-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A read-only, **paged** React viewer for a [last-word](https://github.com/Particle-Academy/last-word-js)
+`Doc`, drawn as the pages it prints on. Each page sits at its paper size, breaks
+fall where the content runs out, the header and footer sit at Word's distances
+with live page numbers, and footnotes sit at the foot of the page that holds
+their mark. In a narrow preview panel it scales the whole page down and never
+reflows the text.
+
+> **Pre-1.0:** breaking changes land in MINOR releases. Read the
+> [CHANGELOG](./CHANGELOG.md) entry before taking one.
+
+## Install
+
+```bash
+npm install @particle-academy/last-word-ui @particle-academy/react-fancy react react-dom
+```
+
+## Use
+
+```tsx
+import { DocViewer } from "@particle-academy/last-word-ui";
+
+<DocViewer doc={doc} />;
+```
+
+`doc` is last-word JSON: what `new DocxReader().read(bytes)` returns in
+`@particle-academy/last-word`, or the same JSON from the PHP or Python
+packages, sent over the wire. This package does not read `.docx` bytes itself,
+so last-word is not a dependency. Read on the server, or with last-word-js:
+
+```tsx
+import { DocxReader } from "@particle-academy/last-word";
+import { DocViewer, docFromReader } from "@particle-academy/last-word-ui";
+
+const doc = docFromReader(new DocxReader().read(bytes)); // or a JSON string
+<DocViewer doc={doc} onLayout={({ pages }) => setPageCount(pages)} />;
+```
+
+Render the object you were given. Footnote numbering is keyed by run identity,
+so a deep clone between numbering and render would lose the marks.
+
+### Props
+
+| prop | type | default | |
+|---|---|---|---|
+| `doc` | `Doc` | (required) | last-word JSON |
+| `fit` | `"width" \| "none"` | `"width"` | scale pages down to the viewer's width |
+| `scale` | `number` | | a fixed scale; overrides `fit` |
+| `maxScale` | `number` | `1` | the most `fit` will enlarge a page |
+| `gap` | `number` | `16` | px between pages |
+| `onLayout` | `(l) => void` | | `{ pages, pageWidth, pageHeight, scale }`, JSON |
+| `injectStyles` | `boolean` | `true` | see *Styles* |
+| `id`, `className`, `style` | | | on the root |
+
+### Stable handles
+
+The root carries `data-lw-viewer`. Each page carries `data-page` (1-based), each
+block or fragment of a block carries `data-block` (`b0`, `b1`, ... in document
+order), each footnote carries `data-footnote`, and the bands carry
+`data-lw-band="header" | "footer"`. Table fragments carry `data-lw-rows`, plus
+`data-lw-repeated-header` on continuation pages.
+
+### Styles
+
+The viewer renders its few CSS rules (react-fancy's `<table>` and `<hr>` take no
+style prop) as a React 19 hoisted `<style>`. Under a CSP without
+`'unsafe-inline'` styles, pass `injectStyles={false}` and import the same
+rules instead:
+
+```ts
+import "@particle-academy/last-word-ui/styles.css";
+```
+
+## What it renders
+
+- **Pages:** letter, legal and a4, portrait or landscape, with margins as the
+  reader returns them. A missing side is the default of 72pt (the reader drops
+  1-inch sides).
+- **Breaks:** by content height, and at every `pageBreak`. Paragraphs,
+  headings, lists, quotes and code split between lines, and paragraphs follow
+  Word's widow and orphan rule. Tables split between rows, repeat their header
+  rows on each continuation page, and never split inside a row span. Headings
+  keep with the next block.
+- **Header and footer:** at `page.margins.header` / `.footer` from the page
+  edge (36pt when absent). They are either a left / centre / right band or
+  blocks (a letterhead logo, address lines). A tall header pushes the body down,
+  as in Word.
+- **Page numbers:** `{page}` and `{pages}` become live numbers on each page,
+  in bands only. In the body they stay literal text, as in the file.
+- **Footnotes:** numbered 1, 2, 3 in document order and set at the foot of the
+  mark's page, under a short rule. Their height comes off that page's body.
+- **Content:** tables (widths, header rows, cell shading, borders, padding,
+  vertical alignment, spans), paragraph alignment, shading, borders, indents
+  and spacing, run styling (bold, italic, underline, strike, colour, highlight,
+  size, font, small caps, letter spacing, inline code, links), headings,
+  lists, quotes, code, images and rules.
+
+### Not yet (v0)
+
+- Charts draw as a sized, labelled placeholder, so pagination stays right.
+- A table **row** taller than a page is not split. It is placed alone and
+  flagged with `data-lw-overflow`.
+- A block with no line breaks that is taller than a page (a huge image) is cut
+  at the page height, with `data-lw-forced`.
+- A footnote taller than the room left does not continue onto the next page.
+- Page `background` and the page `border` frame are not drawn.
+
+## Security
+
+A Doc is untrusted input, and this viewer renders it in your origin:
+
+- Links render only for `http(s)`, `mailto`, `tel` and `#anchor` URLs.
+- Images render only from embedded `data:image/...` URLs. A remote `src` is
+  never requested.
+- Colours reach CSS only as `#RRGGBB`.
+
+## Lower-level API
+
+`paginate(items, { pageHeight, footnoteSeparator })` is the pure page packer.
+It takes heights in and returns page assignments, with no DOM. Use it with
+`pageGeometry(doc)`, `pageMargins(doc)` (the one place margin defaults are
+applied), `bodyBox()`, `numberFootnotes(doc)` and `substituteFields()` to lay
+pages out elsewhere.
+
+## Develop
+
+```bash
+npm test        # vitest + jsdom
+npm run lint    # tsc + eslint
+npm run demo    # vite demo: a multi-page memo, wide and narrow
+```
+
+## License
+
+MIT