@quario/viewer 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @quario/viewer
 
+## 0.9.0
+
+### Minor Changes
+
+- The viewer offers a Word download. Pass a `docx` target in `targets`, and the bar carries a `DOCX`
+  button beside the others. The buttons keep the order you gave. The file carries the content type
+  `application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
+
+  Earlier versions dropped a `docx` target. The viewer rendered no button for it, and it reported no
+  failure.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+  - @quario/layout@0.6.0
+  - @quario/landing@0.2.1
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -2,13 +2,13 @@
 
 **The embeddable report viewer for [quario](https://www.npmjs.com/package/quario), as a custom
 element.** Write `<quario-viewer>`, assign it a compiled report, the export targets you want, and
-data; it lays the report out on pages — the same pages the PDF target writes — paints them on a
+data. It lays the report out on pages — the same pages the PDF target writes — paints them on a
 white sheet in its shadow root, and offers export downloads for the targets you passed.
 
 The viewer is not a render target and compiles nothing. The sheet is `@quario/layout`'s display
-list, painted page by page; you pass the export targets you want, and the viewer wires a button
-to each (`"pdf"`, `"xlsx"`, `"csv"`). The bar always carries the zoom control; with no exportable
-target it carries nothing else.
+list, painted page by page. You pass the export targets you want, and the viewer wires a button
+to each (`"pdf"`, `"xlsx"`, `"csv"`, `"docx"`). The bar always carries the zoom control. With no
+exportable target it carries nothing else.
 
 ## Install
 
@@ -16,10 +16,10 @@ target it carries nothing else.
 npm install quario @quario/viewer
 ```
 
-The engine is a peer; the viewer itself depends on no target package. Install the targets you want
-to export with (`@quario/pdf`, `@quario/xlsx`, `@quario/csv`) and pass them in. Its own runtime
-dependencies are [Lit](https://lit.dev) (`lit` + `@lit/task`) and `@quario/layout`, the paged
-layout it paints, plain ESM like everything else here. ESM-only, and
+The engine is a peer. The viewer itself depends on no target package. Install the targets you want
+to export with (`@quario/pdf`, `@quario/xlsx`, `@quario/csv`, `@quario/docx`) and pass them in. Its
+own runtime dependencies are [Lit](https://lit.dev) (`lit` + `@lit/task`) and `@quario/layout`, the
+paged layout it paints, plain ESM like everything else here. ESM-only, and
 browser-only by nature: the element needs a DOM. CSP-safe like the rest of quario. No
 string-to-code paths, chrome styled through constructed stylesheets, so your `style-src` never
 sees a style tag.
@@ -28,6 +28,7 @@ sees a style tag.
 
 ```js
 import { csv } from "@quario/csv";
+import { docx } from "@quario/docx";
 import { pdf } from "@quario/pdf";
 import { xlsx } from "@quario/xlsx";
 import { quario } from "quario";
@@ -35,14 +36,14 @@ import "@quario/viewer/register";
 
 const view = document.querySelector("quario-viewer");
 view.report = quario().report(schema, funcs);
-view.targets = [pdf(), xlsx(), csv()];
+view.targets = [pdf(), xlsx(), csv(), docx()];
 view.data = data;
 view.filename = "sales";
 ```
 
 with `<quario-viewer></quario-viewer>` in your markup, sized by your own CSS. The element is
-`display: block`, and its chrome is laid out to fit a width of **320px** — a phone-width embed is
-the narrowest the bar is designed for. Narrower than that and the export buttons push the zoom
+`display: block`, and its chrome fits a width of **320px**, a phone-width embed and the narrowest
+the bar supports. Narrower than that and the export buttons push the zoom
 control off the left of the bar, quietly: the bar does not wrap or scroll. Importing
 `@quario/viewer` defines nothing: the main entry exports the `QuarioViewer` class and is
 side-effect-free, and `@quario/viewer/register` performs the one-line
@@ -67,14 +68,14 @@ package to install. See [Using with React, Vue and Svelte](#using-with-react-vue
 | `colorScheme` | `"light"`, `"dark"`, or `"auto"`                | `"light"`   |
 
 Properties, not attributes: `report`, `targets`, `data`, `page` and `fonts` are values no attribute
-could carry. `targets` mirrors `report.render(target, data)` for the exports: `"pdf"`/`"xlsx"`/`"csv"`
-targets become export buttons, in the order given, and the sheet needs none of them. The quario
-instance (and with it the license and the registry) stays yours: the element takes the compiled
-report, never a schema.
+could carry. `targets` mirrors `report.render(target, data)` for the exports:
+`"pdf"`/`"xlsx"`/`"csv"`/`"docx"` targets become export buttons, in the order given, and the
+sheet needs none of them. The quario instance (and with it the license and the registry) stays
+yours: the element takes the compiled report, never a schema.
 
 Assigning `data` (or any of the others) re-renders. Rapid successive writes render only the newest
 state: a slow render can never overwrite a newer one, and a superseded render fires no event.
-Assignments are compared by identity, so to re-render from the same object, assign a fresh one
+The viewer compares assignments by identity, so to re-render from the same object, assign a fresh one
 (`view.data = { ...data }`).
 
 `page` and `fonts` are the pdf target's own options: the viewer lays the report out on them, so
@@ -90,32 +91,32 @@ view.addEventListener("error", ({ detail: { error, kind } }) => {});
 await view.renderComplete; // true when the newest render landed on the sheet
 ```
 
-`rendered` fires each time a render lands on the sheet; `error` fires for every failure you should
+`rendered` fires each time a render lands on the sheet. `error` fires for every failure you should
 know about, with `detail.kind` naming which: `"mount-render"` until a render has ever landed,
 `"update-render"` after, `"export"` for a download that could not be produced. Both events are
-non-bubbling, like `<img>`'s. Listen on the element. (Because the event is named `error`, an
-inline `onerror` attribute on the element would fire too; `window.onerror` never sees it.)
+non-bubbling, like `<img>`'s. Listen on the element. (Because the event carries the name `error`, an
+inline `onerror` attribute on the element would fire too. `window.onerror` never sees it.)
 
 `renderComplete` awaits the newest render settling: `true` when it landed on the sheet with the pages
 on screen finished trying to paint, `false` when it failed or there was nothing to render. It never
-rejects; failures arrive on the `error` event. `rendered` fires at that same moment. Like every
-outcome here, it answers for the newest render only. A superseded render's failure is reported to no
+rejects. Failures arrive on the `error` event. `rendered` fires at that same moment. Like every
+outcome here, it answers for the newest render only. A superseded render's failure reaches no
 one.
 
 An image the browser cannot decode — pixel data corrupt past the size in its header, which is all
 the engine reads — is drawn as nothing, and the page is drawn around it. That is not a render
-failure: `renderComplete` answers `true`, `rendered` fires, and no `error` event is raised. A face in
-`fonts` is a different story: it is parsed while the report is measured, so bytes that will not parse
-are a render error with a panel.
+failure: `renderComplete` answers `true`, `rendered` fires, and no `error` event follows. A face in
+`fonts` is a different story. The layout parses it while it measures the report, so bytes that will
+not parse are a render error with a panel.
 
 Your own mistakes surface on the same channel: a report that is not compiled, or a malformed
 option property, becomes a `TypeError` naming the property, on the `error` event and the
-[error panel](#errors). No particular target is required — the sheet is the layout's own.
+[error panel](#errors). The viewer needs no particular target — the sheet is the layout's own.
 
 ## Lifecycle
 
 There is no `destroy()`. Removing the element from the DOM abandons in-flight work and releases
-its observers; an export that settles after removal downloads nothing. The properties persist, and
+its observers. An export that settles after removal downloads nothing. The properties persist, and
 re-inserting the element re-renders from them, so reparenting is safe, and discarding a viewer is
 just discarding the element. Two viewers, or a viewer beside your own components, coexist: each
 element owns its own shadow root.
@@ -123,7 +124,7 @@ element owns its own shadow root.
 ## Using with React, Vue and Svelte
 
 No wrapper packages: each framework sets properties on custom elements directly, so the samples
-below are the whole integration. All three were run before landing here. Import
+below are the whole integration. Each of the three ran before landing here. Import
 `@quario/viewer/register` once, anywhere before the component mounts, and size the element with
 your own CSS.
 
@@ -150,7 +151,7 @@ function Report({ report, targets, data }) {
 }
 ```
 
-Re-rendering with a new `data` prop re-renders the report; the newest write wins, as always.
+Re-rendering with a new `data` prop re-renders the report. The newest write wins, as always.
 (React 18 and earlier stringify unknown props to attributes. There, hold a `ref` and assign the
 properties and listeners in an effect.)
 
@@ -213,46 +214,47 @@ listeners:
 
 The bar's magnifier opens the zoom menu: **Fit page** on its own, then 25%, 50%, 75%, 100%, 150%
 and 200%. A check marks the current mode — Fit page whenever the viewer is fitting, whatever
-percentage that came out at — and the percentage on screen is what the trigger is named after
+percentage that came out at — and the trigger carries the percentage on screen in its name
 ("Zoom, 62%"), so nothing in the bar changes width as it moves. The `zoom` property picks the mode
 the viewer opens in: a percentage between 25 and 200 — continuous, not one of the menu's stops — or
 `"fit"`, the default. A percentage the menu does not offer leaves every row unchecked.
 
 Fit sizes one page to the viewer's width and **only ever shrinks**: given room to spare it stops at
-100%, so the report is shown at its true point size rather than blown up. It has no floor, so a
+100%, so the report keeps its true point size rather than growing past it. It has no floor, so a
 narrow pane fits at whatever percentage that takes — below 25% the menu has no row to return to it,
 and **Fit page** is the only way back. A fitted viewer follows its own box, so a collapsing panel
 or a resized window re-fits on its own.
 
-The preview **scales; it never reflows.** Zooming repaints the pages larger or smaller, like a
+The preview **scales. It never reflows.** Zooming repaints the pages larger or smaller, like a
 photograph that stays sharp. Line breaks, column widths and point sizes stay what they are at
 100%, because the layout never changes under a zoom.
 
-Only the pages near the viewport are painted — the ones on screen and one screenful either side.
+The viewer paints only the pages near the viewport — the ones on screen and one screenful either side.
 Every page keeps its size, so the scrollbar and the scroll extent are the whole report from the
-start; a page further off is blank paper until you scroll to it, which is why a zoom step costs the
+start. A page further off is blank paper until you scroll to it, which is why a zoom step costs the
 same on a thousand-page report as on a five-page one.
 
 ## What the preview is
 
 The pages on screen are the pages the PDF export writes: both consume one layout, `@quario/layout`'s
-display list, laid out on your `page` and `fonts`. A report shorter than a page is one page; a
-longer one is as many as the layout breaks it into, stacked down the sheet. Sizing a container to a
-viewer showing a short report therefore reserves a full page — set `zoom` to a percentage small
-enough where the box has to stay small.
-
-Each page is a canvas, and text on it is drawn in the face the document will use. A TrueType
-family you pass as `fonts` is registered from your own bytes and drawn as the browser shapes it —
+display list, laid out on your `page` and `fonts`. A report shorter than a page is one page. A
+longer one is as many pages as the layout breaks it into, stacked down the sheet. Sizing a
+container to a viewer that draws a short report therefore reserves a full page. Set `zoom` to a
+percentage small enough where the box has to stay small.
+
+Each page is a canvas, and text on it is drawn in the face the document will use. The viewer
+registers a TrueType family you pass as `fonts` from your own bytes and draws it as the browser
+shapes it —
 the same shaping the PDF gets from the same file, so ligatures, joined scripts and accents look
 here the way they will on paper. Text in the built-in families is drawn character by character at
 the advances the layout measured, because the font a browser has for Helvetica, Times or Courier
 only stands in for the one the PDF writes, and the correction is what makes a line fill the same
 width and break in the same place the document does. Inside one run of a family you supply, a
-browser may kern by a fraction more than the document; where lines break and pages end is the
-layout's, and identical. Images are decoded from their bytes — no `data:` URIs, so a host page's
+browser may kern by a fraction more than the document. Where lines break and pages end is the
+layout's, and identical. The viewer decodes images from their bytes — no `data:` URIs, so a host page's
 Content Security Policy needs no `img-src` grant for them.
 
-Rendering an unlicensed evaluation, the marking is painted across every page, the way the PDF
+Rendering an unlicensed evaluation, the viewer paints the marking across every page, the way the PDF
 export marks every page: it rides on the layout, so what you see is what the document carries. A
 licensed render carries none.
 
@@ -262,8 +264,8 @@ reads `aria-busy="true"`. It reports that the viewer is working, not how far alo
 engine streams events and cannot know how many are still coming.
 
 There is no Print button, because the sheet is the wrong thing to print. Your page's stylesheets do
-not cross into the shadow root, so `@media print` rules never reach the report; and the pages are
-painted at whatever zoom the reader happened to leave them, so printing the page puts the viewer's
+not cross into the shadow root, so `@media print` rules never reach the report. The viewer also
+paints the pages at whatever zoom the reader happened to leave them, so printing the page puts the viewer's
 chrome on paper at that zoom. What a printer wants is the pdf target's
 document, the same bytes the PDF export hands over. A host that wants its own Print button owns
 two lines:
@@ -280,19 +282,23 @@ the export is, watermark and all.
 
 ## Errors
 
-When a render or an export fails, the viewer says so on the **error panel**, a strip across the top
-of the sheet carrying a short label — "Could not render the report", "Could not update the report — showing the previous version", or "Could not export PDF" — and the error's own message. It replaces rather than stacks, is
-dismissed by its own button, and is cleared by the next render that lands on the sheet. A successful
-export leaves it up, because the panel describes what you are looking at and a download says
-nothing about that.
+When a render or an export fails, the viewer says so on the **error panel**. The panel is a strip
+across the top of the sheet, carrying the error's own message under one of three short labels:
+
+- "Could not render the report"
+- "Could not update the report — showing the previous version"
+- "Could not export PDF" It replaces rather than stacks, its own
+  button dismisses it, and the next render that lands on the sheet clears it. A successful
+  export leaves it up, because the panel describes what you are looking at and a download says
+  nothing about that.
 
-Every failure the panel draws, and every export failure, also fires the `error` event; nothing is
-rethrown to the platform behind it. Failures after the element is removed are not reported, and a
+Every failure the panel draws, and every export failure, also fires the `error` event. The viewer rethrows
+nothing to the platform behind it. Failures after the element leaves the DOM go unreported, and a
 render that a newer one has already superseded reports to no one at all.
 
 The message carries quario's **located error**, the band/item path and the offending source, as in
-`detail[0] [{{ @.amount.toFixed(2) }}]: ...`. Showing it is safe because report definitions are
-trusted configuration; report _data_ never is, and none of it appears in the path. What can carry
+`detail[0] [{{ @.amount.toFixed(2) }}]: ...`. Drawing it is safe because report definitions are
+trusted configuration. Report _data_ never is, and none of it appears in the path. What can carry
 data is the message itself, if your own registry functions interpolate a row into what they throw.
 That is your call, and the panel puts it on screen as text, never as markup. Compile errors are not
 part of this: `q.report(schema)` raises those before the viewer is ever handed a report.
@@ -300,7 +306,7 @@ part of this: `q.report(schema)` raises those before the viewer is ever handed a
 ## Color scheme
 
 `colorScheme` paints the **chrome** — backdrop, bar, controls, progress strip, error
-panel — and never the sheet. `"light"` (the default) and `"dark"` pin; `"auto"` follows
+panel — and never the sheet. `"light"` (the default) and `"dark"` pin. `"auto"` follows
 the OS via CSS `color-scheme`. The pages stay white, marking included.
 
 Chrome styles live on `--qv-*` custom properties under stable `qv-*` class names. A
@@ -323,10 +329,10 @@ specification of what a report may declare, and
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key once, on the instance; it is verified offline:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/index.d.ts

@@ -67,7 +67,7 @@ export class QuarioViewer extends LitElement {
   report: ViewableReport | undefined;
   /**
    * The export targets, as passed to `report.render`: ones named
-   * `"pdf"`/`"xlsx"`/`"csv"` become export buttons, in array order. The
+   * `"pdf"`/`"xlsx"`/`"csv"`/`"docx"` become export buttons, in array order. The
    * sheet needs none of them — it is the layout's own. An empty array is
    * a viewer with nothing to export.
    */

package/lib/toolbar.js

@@ -22,6 +22,7 @@ export let EXPORTS = {
   pdf: "application/pdf",
   xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
   csv: "text/csv",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
 };
 
 // The anchor joins the document for the click — detached-anchor downloads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/viewer",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The embeddable report viewer shell for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -44,22 +44,22 @@
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/landing": "^0.2.0",
-    "@quario/layout": "^0.5.0",
+    "@quario/landing": "^0.2.1",
+    "@quario/layout": "^0.6.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
-    "@cantoo/pdf-lib": "^2.9.1",
+    "@cantoo/pdf-lib": "~2.9.1",
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
     "exceljs": "^4.4.0",
-    "quario": "^0.8.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.8.0"
+    "quario": "^0.9.0"
   },
   "size-limit": [
     {