@quario/xlsx 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to @quario/xlsx are documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- **A workbook from the same compiled report.** Bands become rows; a bare
+  interpolation that is a number, boolean, or Date stays that type. The first
+  table freezes its header row. exceljs writes the file. Column width
+  percentages are unread: a worksheet has no table for a share to be a share
+  of.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -0,0 +1,153 @@
+# @quario/xlsx
+
+**The spreadsheet render target for [quario](https://www.npmjs.com/package/quario).** Renders a
+report definition to an `.xlsx` workbook with cells typed as a number, boolean, or Date, and a frozen
+header row.
+
+Numbers stay numbers, dates stay dates, and booleans stay booleans. Your users get a workbook they
+can keep working in, not a grid of strings.
+
+## Install
+
+```bash
+npm install quario @quario/xlsx
+```
+
+[exceljs](https://github.com/exceljs/exceljs) comes along as a dependency; the engine is a peer, installed beside it. ESM-only,
+Node 22+, and browser-ready through any standards-based ESM bundler. The renderer returns bytes,
+so you decide where they go.
+
+> The writer is an implementation detail: exceljs is confined to a single internal module, so it
+> can be swapped behind this exact API without a breaking change.
+
+## Quick start
+
+```js
+import { writeFileSync } from "node:fs";
+import { xlsx } from "@quario/xlsx";
+import { quario } from "quario";
+
+const report = quario().report(schema, funcs);
+const bytes = await report.render(xlsx({ meta: { title: "Sales 2026" } }), data);
+
+writeFileSync("sales.xlsx", bytes);
+```
+
+Any schema the other targets render works here unchanged. A spreadsheet has no pages, so page bands
+are ignored.
+
+One tip that changes the output a lot: **interpolate the bare value, not a formatter.** A cell
+written `{{ @.amount }}` becomes a real numeric cell; `{{ currency(@.amount) }}` becomes text,
+because the formatter already turned the number into a string. Let the spreadsheet do the
+formatting it is good at.
+
+## API
+
+### `xlsx(options?)`
+
+The target factory: it takes this target's host options and returns the target you pass to
+`render`. `report()` compiles once and `report.render(xlsx(options), data)` resolves the
+workbook bytes. Compile at startup, render per request. Definition problems throw at
+`report()`, at compile time.
+
+```js
+const report = quario().report(schema, funcs);
+const bytes = await report.render(xlsx(), data);
+```
+
+The compiled report carries `stream` (the raw event generator), `names`, `functions`, and
+`paths`, like every quario report. Engine-level options (`query` budgets, the license key)
+live on the instance, and `q.license` settles with the verification result.
+
+Rendering is asynchronous and hands the loop back between batches, so a large report never blocks the
+host. Render-time failures reject with located errors.
+
+### Options
+
+```js
+{
+  meta: { title, author, subject },   // optional document properties — strings only, never a date
+}
+```
+
+## Mapping
+
+One worksheet, named `Report`, with the banded walk flattened onto it as rows in render order:
+report-header items, then per group instance its header items, nested content, and footer items,
+then the table's header row, data rows, and total row, then report-footer items. Grouping shows up
+as that order alone. Group boundaries add no rows of their own, and `break: "page"` is ignored.
+
+Each item takes one row with its cell in the first column, unmerged. Two band roles carry an
+omakase default that the author's own style always overrides: report-header items render bold at
+size 14, group-header items render bold.
+
+### Typed cells
+
+A cell whose value is one bare interpolation writes its pre-stringify value as a number, boolean, or
+Date. Every other cell (mixed literal and interpolation, a lone null, any non-numeric value) joins
+to display text.
+
+**String cells are never formulas.** Cell text beginning with `=`, or anything else, arrives as
+inert literal text: no formula-injection surface, and no apostrophe mangling either.
+
+A hidden cell keeps its column slot as an empty cell that retains its style.
+
+### Images
+
+An image item is not a cell: it takes one worksheet row as its anchor and floats over the sheet as a
+drawing at its natural pixel size. Placement here is best-effort. `fit`, `alt`, and `style` go
+unread, and all of it may change without a breaking change.
+
+### Styles
+
+| Declaration                                            | Maps to                                                                                                                              |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `family`                                               | `sans` → Calibri, `serif` → Times New Roman, `mono` → Courier New; any other name passes through for the host application to resolve |
+| `size`, `bold`, `italic`, `underline`, `strikethrough` | Font (`strikethrough` → writer's `strike`)                                                                                           |
+| `color`, `background`                                  | Font colour, solid fill                                                                                                              |
+| `align`                                                | Horizontal alignment                                                                                                                 |
+
+Style blocks layer row under cell, as everywhere in quario.
+
+### Freeze
+
+The first table's header row anchors the frozen view. Everything from that row up stays visible
+while the body scrolls, the spreadsheet analogue of the PDF target's repeated headers. A report
+without a table freezes nothing. This is normative.
+
+### Widths are not read
+
+Column `width` percentages size nothing here, and every worksheet column keeps the application
+default. A width is a share of the _table_ width, and a worksheet's columns are global to the sheet.
+Column A carries the flattened band item rows and the table's first column alike, so there is no
+table for a share to be a share of.
+
+### Page columns are not read
+
+A page column count sizes and splits nothing here, and will not change, as `break: "page"` is
+ignored. Page columns are strips of a page, and this target has no page to strip.
+
+## Unlicensed marking
+
+An unlicensed render writes the wording from `report-start.marking` twice: as a styled banner in
+row 1 (so the whole report, frozen view included, sits one row lower than a licensed render), and
+as the workbook's description property. Both are normative; banner styling is best-effort. A
+licensed render has no banner and no description marking.
+
+## Determinism
+
+The document model is deterministic: the workbook's dates are pinned rather than stamped, and
+`meta` is opt-in. The **bytes** are not. The writer stamps archive entries with the packing time.
+Compare extracted content, not digests.
+
+## License
+
+Commercial software with readable source. Free, unlimited, watermarked evaluation; 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:
+
+```js
+const q = quario({ license: "quario_..." });
+await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
+```

package/lib/cell.js

@@ -0,0 +1,26 @@
+/**
+ * From an event cell to a plain cell descriptor `{ value, format }`, built on
+ * the engine's `typed` stream rule. `value` is a native number, boolean, or
+ * Date when the cell is one bare interpolation (so numbers stay computable in
+ * the sheet), and the display-text join otherwise. `format` is the resolved
+ * cell-level formatting from the style module.
+ */
+import { text, typed } from "quario";
+import { format, merge } from "./style.js";
+
+/**
+ * Resolve one event cell against its enclosing style (a row's style, or an
+ * item's band-role default — the layer under the cell's own).
+ *
+ * @type {(cell: { tokens: any[], style?: any }, under: any) => { value: any, format: any }}
+ */
+let field = (cell, under) => {
+  let resolved = merge(under, cell.style);
+  let value = typed(cell.tokens);
+  return {
+    value: value !== undefined ? value : text(cell.tokens),
+    format: format(resolved),
+  };
+};
+
+export { field };

package/lib/image.js

@@ -0,0 +1,47 @@
+/**
+ * An image's own size, read from its header. A floating drawing is placed in
+ * pixels, and the event carries the bytes and the format the engine sniffed
+ * but no dimensions, so the one thing this target needs to place a picture is
+ * worked out here — from the header alone, never by decoding the image.
+ *
+ * The PDF target reads the same two headers for its own placement, in points.
+ * Restated per target rather than shared, like every other coercion at a
+ * target's edge: neither package imports the other, and the engine's stream is
+ * all they have in common.
+ */
+
+/** @type {(bytes: Uint8Array, at: number) => number} */
+let word = (bytes, at) => (bytes[at] << 8) | bytes[at + 1];
+
+/** @type {(bytes: Uint8Array) => { width: number, height: number }} */
+let png = (bytes) => ({ width: word(bytes, 18), height: word(bytes, 22) });
+
+// The dimensions live in the frame header, the first SOFn marker: every
+// code in C0..CF except the three in that range that are not frames --
+// DHT, the JPG extension, and DAC.
+/** @type {Record<number, number>} */
+let SKIP = { 0xc4: 1, 0xc8: 1, 0xcc: 1 };
+/** @type {(code: number) => any} */
+let sof = (code) => code >= 0xc0 && code <= 0xcf && !SKIP[code];
+
+/** @type {(bytes: Uint8Array) => { width: number, height: number }} */
+let jpeg = (bytes) => {
+  for (let at = 2; at + 9 < bytes.length; at += 2 + word(bytes, at + 2)) {
+    if (bytes[at] !== 0xff) break;
+    if (sof(bytes[at + 1])) return { width: word(bytes, at + 7), height: word(bytes, at + 5) };
+  }
+  return { width: 0, height: 0 };
+};
+
+/**
+ * The image's size in pixels, or null when the header does not carry one —
+ * bytes the engine vouched the magic numbers of, truncated before the size.
+ *
+ * @param {Uint8Array} bytes The image file.
+ * @param {string} format The engine's sniff: `"png"` or `"jpeg"`.
+ * @returns {{ width: number, height: number } | null} The size, if readable.
+ */
+export let pixels = (bytes, format) => {
+  let size = format === "png" ? png(bytes) : jpeg(bytes);
+  return size.width > 0 && size.height > 0 ? size : null;
+};

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+import type { Target } from "quario";
+
+/** Optional document information; never includes dates, so the document model stays deterministic. */
+export interface XlsxMeta {
+  title?: string;
+  author?: string;
+  subject?: string;
+}
+
+/** Host controls, taken at the factory call. */
+export interface XlsxOptions {
+  meta?: XlsxMeta;
+}
+
+/**
+ * The spreadsheet render target:
+ * `quario().report(schema).render(xlsx(), data)` resolves the
+ * workbook bytes described in SCHEMA.md ("The XLSX target").
+ */
+export function xlsx(options?: XlsxOptions): Target<"xlsx", Promise<Uint8Array>>;

package/lib/index.js

@@ -0,0 +1,127 @@
+/**
+ * @quario/xlsx — the spreadsheet render target: a pure consumer of the
+ * engine's public event stream, passed to a compiled report's `render`, flattening the
+ * banded walk onto one worksheet in render order. Cells that are one bare interpolation keep their native type
+ * (numbers stay numbers), the first table
+ * anchors the frozen header row, and the closed style
+ * vocabulary maps to fonts, fills, and alignment. Column `width` percentages
+ * are read by no part of this target: a worksheet's columns are global to the
+ * sheet, so there is no table for a share to be a share of. This target is unpaginated,
+ * so `report-start.page` band closures and `break: 'page'` are ignored — the
+ * same posture as the HTML target.
+ *
+ * The document model is deterministic — the workbook carries no dates of its
+ * own — but the bytes are not: the current writer stamps archive entries with
+ * the packing time. Byte-for-byte output is a goal for the writer that will
+ * replace `workbook.js`.
+ */
+import { walk } from "quario";
+import { field } from "./cell.js";
+import { pixels } from "./image.js";
+import { append, create, embed, freeze, mark, place, save, sheet } from "./workbook.js";
+
+// The options are described once, in the hand-written public declarations, and
+// read back here — a second copy in JSDoc is a copy that drifts.
+/** @import { XlsxOptions } from './index.d.ts' */
+
+// Band-role omakase defaults, applied under the author's own style so a
+// declared style always wins. Only the headline roles carry one; every other
+// band writes plain cells. The PDF target carries the same two, byte-identical,
+// in its own `style.js` — SCHEMA.md states the pair for both, so they move
+// together, and a target imports only public engine helpers so there is nowhere
+// to share them from.
+//
+// `@quario/html` deliberately carries none of them: its consumer has a
+// stylesheet and the `q-*` classes are the seam, where a worksheet has neither.
+// The rule is docs/adr/0014-a-target-supplies-defaults-only-where-its-consumer-has-no-seam.md —
+// a target supplies defaults only where its consumer has no seam to supply
+// them. `@quario/html/style.css` and `packages/viewer/lib/style.js` supply them for
+// that target; keep all four in agreement.
+/** @type {Record<string, any>} */
+let ROLES = { "report-header": { bold: true, size: 14 }, "group-header": { bold: true } };
+
+// The unlicensed-output marking (LICENSE section 6): one styled banner row
+// above the report, written only on keyless renders through the same cell
+// path as every other row. This is the banner's look; the wording arrives on
+// `report-start`.
+let BANNER = { bold: true, background: "#fff2cc" };
+
+/**
+ * The spreadsheet render target:
+ * `quario().report(schema).render(xlsx(), data)` resolves the
+ * complete workbook as a `Uint8Array` (the host writes the file). Rendering
+ * runs the engine's `walk` driver over the handlers below, so large reports
+ * stay cooperative.
+ *
+ * @param {XlsxOptions} [options] Host controls (see SCHEMA.md, "The XLSX target").
+ * @returns {{name: "xlsx", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
+ *   The target (see SCHEMA.md, "Instances and targets").
+ */
+export function xlsx(options) {
+  /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
+  let compile = (stream) => async (data) => {
+    let workbook = create(options?.meta);
+    let worksheet = sheet(workbook);
+    // The first table anchors the frozen header row. It is global to the
+    // sheet, so later tables never move it.
+    let frozen = false;
+    // Every image this render has already embedded, keyed by the array the
+    // source expression yielded and holding what a second placement of the
+    // same bytes needs: the media id and the size read off the header. A logo
+    // down a thousand rows is one copy in the file rather than a thousand.
+    /** @type {Map<Uint8Array, any>} */
+    let images = new Map();
+    // A table row and a total row differ only in the style they sit under.
+    let record = (/** @type {any} */ event, /** @type {any} */ under) =>
+      append(
+        worksheet,
+        event.cells.map((/** @type {any} */ cell) => field(cell, under)),
+      );
+    await walk(stream(data), {
+      "report-start": (event) => {
+        if (event.marking) {
+          mark(workbook, event.marking);
+          append(worksheet, [field({ tokens: [{ literal: event.marking }], style: BANNER }, null)]);
+        }
+      },
+      item: (event) => {
+        let role = Object.hasOwn(ROLES, event.role) ? ROLES[event.role] : null;
+        append(worksheet, [field({ tokens: event.tokens, style: event.style }, role)]);
+      },
+      // An image is not a cell: it takes one row as its anchor and floats
+      // over the sheet from there, at its own pixel size. `fit` is not read
+      // -- a worksheet has no content width for a share to be a share of,
+      // the same ground the column widths go unread on (ADR 0008) -- and
+      // neither is `alt` or `style`. All of this is best-effort and may
+      // change (SCHEMA.md, "The XLSX target").
+      image: (event) => {
+        let known = images.get(event.bytes);
+        if (!known) {
+          let size = pixels(event.bytes, event.format);
+          // The engine vouched for the magic numbers, not for the rest of the
+          // file. A header too short to carry a size leaves nothing to place a
+          // drawing at, and failing beats dropping the picture in silence
+          // (SCHEMA.md, "Image item").
+          if (!size) throw Error("image: could not read the image's size from its bytes");
+          known = { ...size, id: embed(workbook, event.bytes, event.format) };
+          images.set(event.bytes, known);
+        }
+        // The anchor: a row of its own, with nothing written in it, which the
+        // picture then floats over.
+        place(worksheet, known.id, known, append(worksheet, []));
+      },
+      "table-start": (event) => {
+        let headers = event.columns.map((/** @type {any} */ column) => field(column.header, null));
+        let row = append(worksheet, headers);
+        if (!frozen) {
+          freeze(worksheet, row);
+          frozen = true;
+        }
+      },
+      row: (event) => record(event, event.style),
+      "total-row": (event) => record(event, null),
+    });
+    return save(workbook);
+  };
+  return { name: "xlsx", compile };
+}

package/lib/style.js

@@ -0,0 +1,92 @@
+/**
+ * The XLSX target's reading of the closed style vocabulary — the counterpart
+ * of the CSS table in the HTML target and the points-and-colours module in
+ * the PDF target. Declarations are lenient at render: a value of the wrong
+ * shape contributes nothing rather than reaching the sheet. Everything
+ * produced here is plain data shaped for the workbook writer; nothing in this
+ * module touches the writer itself.
+ *
+ * `finite`/`HEX` are restated per target on purpose: the coercions are each
+ * target's own edge, never shared engine code.
+ */
+
+/** @type {(value: any) => boolean} */
+let finite = (value) => typeof value === "number" && Number.isFinite(value);
+let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+// The generic families as the fonts spreadsheet apps ship with; any other
+// name passes through verbatim for the host application to resolve.
+/** @type {Record<string, string>} */
+let FAMILY = { sans: "Calibri", serif: "Times New Roman", mono: "Courier New" };
+let ALIGNMENTS = ["left", "center", "right"];
+
+// A declared colour as an ARGB string, or null when the value is not one.
+/** @type {(value: any) => string | null} */
+let argb = (value) => {
+  let match = typeof value === "string" && HEX.exec(value);
+  if (!match) return null;
+  // `#abc` is `#aabbcc`.
+  let digits = match[1].length === 3 ? match[1].replace(/./g, (d) => d + d) : match[1];
+  return "FF" + digits.toUpperCase();
+};
+
+// Style blocks layer outward-in: row under cell.
+/** @type {(under: any, over: any) => any} */
+let merge = (under, over) => (under ? (over ? { ...under, ...over } : under) : over || {});
+
+/** @type {(out: any, key: string, value: any) => any} */
+let put = (out, key, value) => {
+  if (!value) return out;
+  (out ??= {})[key] = value;
+  return out;
+};
+
+/** @type {(family: any) => string} */
+let face = (family) => {
+  if (typeof family !== "string" || !family) return "";
+  let key = family.toLowerCase();
+  // Own-key lookup: `constructor` must not resolve an inherited member.
+  return Object.hasOwn(FAMILY, key) ? FAMILY[key] : family;
+};
+
+/** @type {(value: any) => number | null} */
+let size = (value) => (finite(value) && value > 0 ? value : null);
+/** @type {(value: any) => true | null} */
+let flag = (value) => (value ? true : null);
+/** @type {(value: any) => { argb: string } | null} */
+let tint = (value) => {
+  let color = argb(value);
+  return color ? { argb: color } : null;
+};
+
+// The font half of a resolved style, or null when the style declares none
+// of it.
+/** @type {(style: any) => any} */
+let font = (style) => {
+  let out = put(null, "name", face(style.family));
+  out = put(out, "size", size(style.size));
+  out = put(out, "bold", flag(style.bold));
+  out = put(out, "italic", flag(style.italic));
+  out = put(out, "underline", flag(style.underline));
+  // exceljs names the flag `strike`; the authoring surface says strikethrough.
+  out = put(out, "strike", flag(style.strikethrough));
+  return put(out, "color", tint(style.color));
+};
+
+/** @type {(value: any) => any} */
+let fill = (value) => {
+  let color = argb(value);
+  return color ? { type: "pattern", pattern: "solid", fgColor: { argb: color } } : null;
+};
+/** @type {(value: any) => any} */
+let align = (value) => (ALIGNMENTS.includes(value) ? { horizontal: value } : null);
+
+// The whole-cell reading: the font plus the parts only a cell can carry.
+/** @type {(style: any) => any} */
+let format = (style) => {
+  let out = put(null, "font", font(style));
+  out = put(out, "fill", fill(style.background));
+  return put(out, "alignment", align(style.align));
+};
+
+export { format, merge };

package/lib/workbook.js

@@ -0,0 +1,96 @@
+/**
+ * The workbook writer — the only module that talks to exceljs, so replacing
+ * the writer later means replacing this file and nothing else. It consumes
+ * plain cell descriptors and style objects; every other module in the package
+ * emits data, never writer calls.
+ *
+ * The default import is deliberate: the writer is CommonJS and its named
+ * exports are not visible to Node's ESM loader.
+ */
+import ExcelJS from "exceljs";
+
+// Host metadata keys as the workbook properties they become.
+/** @type {Record<string, string>} */
+let META = { title: "title", author: "creator", subject: "subject" };
+/** @type {(workbook: any, meta: any) => any} */
+let describe = (workbook, meta) => {
+  if (!meta) return workbook;
+  for (let from in META) if (typeof meta[from] === "string") workbook[META[from]] = meta[from];
+  return workbook;
+};
+
+// A fresh workbook. Never the current time: a timestamp would make the same
+// input produce a different document model on every run.
+/** @type {(meta: any) => any} */
+let create = (meta) => {
+  let workbook = new ExcelJS.Workbook();
+  workbook.created = new Date(0);
+  workbook.modified = new Date(0);
+  return describe(workbook, meta);
+};
+
+/** @type {(workbook: any) => any} */
+let sheet = (workbook) => workbook.addWorksheet("Report");
+
+let KEYS = ["font", "fill", "alignment"];
+/** @type {(cell: any, format: any) => void} */
+let paint = (cell, format) => {
+  for (let key of KEYS) if (format[key]) cell[key] = format[key];
+};
+
+// Write one worksheet row from cell descriptors; returns the row number.
+/** @type {(worksheet: any, fields: { value: any, format: any }[]) => number} */
+let append = (worksheet, fields) => {
+  let row = worksheet.addRow(fields.map((field) => field.value));
+  for (let index = 0; index < fields.length; index++) {
+    let field = fields[index];
+    if (field.format) paint(row.getCell(index + 1), field.format);
+  }
+  return row.number;
+};
+
+// One image in the workbook's media, as the engine's sniffed format calls it.
+// The id comes back so a caller that places the same bytes twice can embed
+// them once: this writer keeps no such tally, and adding the same buffer twice
+// writes two copies into the file.
+/** @type {(workbook: any, bytes: Uint8Array, format: string) => number} */
+let embed = (workbook, bytes, format) => workbook.addImage({ buffer: bytes, extension: format });
+
+// One picture, floating over the row it is anchored to. Wholly best-effort
+// placement (SCHEMA.md): the drawing hangs from the top-left of that row at
+// the size it was measured at, over whatever follows it down the sheet.
+/** @type {(worksheet: any, id: number, size: any, row: number) => void} */
+let place = (worksheet, id, size, row) => {
+  worksheet.addImage(id, {
+    // exceljs counts anchors from zero, while a row number starts at one.
+    tl: { col: 0, row: row - 1 },
+    ext: { width: size.width, height: size.height },
+  });
+};
+
+// Freeze everything above the body so the header row stays visible.
+/** @type {(worksheet: any, row: number) => void} */
+let freeze = (worksheet, row) => {
+  worksheet.views = [{ state: "frozen", ySplit: row }];
+};
+
+// The unlicensed-output marking on the document itself (LICENSE section 6):
+// the workbook description carries the engine's wording wherever file
+// properties show.
+/** @type {(workbook: any, text: string) => void} */
+let mark = (workbook, text) => {
+  workbook.description = text;
+};
+
+// The finished document. `writeBuffer()` resolves a Node Buffer or, in the
+// browser build, a bundled polyfill over an ArrayBuffer — both normalize to
+// a plain view without copying.
+/** @type {(workbook: any) => Promise<Uint8Array>} */
+let save = async (workbook) => {
+  let out = await workbook.xlsx.writeBuffer();
+  return out instanceof Uint8Array
+    ? new Uint8Array(out.buffer, out.byteOffset, out.byteLength)
+    : new Uint8Array(out);
+};
+
+export { append, create, embed, freeze, mark, place, save, sheet };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@quario/xlsx",
+  "version": "0.1.0",
+  "description": "The spreadsheet render target for quario — in the makings, not yet released",
+  "homepage": "https://getquario.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/xlsx"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "test:browser": "node test/browser/setup.js",
+    "test:types": "tsc && attw --pack . --profile esm-only",
+    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "@types/node": "^22.20.1",
+    "quario": "^0.1.0",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "quario": "^0.1.0"
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "ignore": [
+        "quario",
+        "exceljs"
+      ],
+      "limit": "2 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}