@quario/xlsx 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,15 +1,39 @@
-# Changelog
+# @quario/xlsx
 
-All notable changes to @quario/xlsx are documented in this file.
+## 0.7.1
 
-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).
+### Patch Changes
 
-## [Unreleased]
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - quario@0.8.0
 
-## [0.6.0] - 2026-09-07
+## 0.7.0
 
-### Added
+### Minor Changes
+
+- **Styled runs become rich text.** A cell of more than one styled run is written
+  as rich text, each run's font merged over the cell's — so bold, italic,
+  underline, strikethrough, size, face and colour survive into the grid. A
+  run-level `background` is not read: a spreadsheet's rich-text runs carry fonts
+  only, and filling the cell would colour text nobody asked to colour. A cell of
+  exactly one run stays a typed cell, so a single styled amount is still a
+  number.
+- **A run inside a sentence presents its value.** A run holding one
+  interpolation under a `format` shows the same decimals here as on the page,
+  where a mixed cell used to show the bare value.
+
+## 0.6.0
+
+### Minor Changes
 
 - **A date cell's number format follows the `form` its report declares.** The
   four forms map to `dd/mm/yy`, `dd mmm yyyy`, `dd mmmm yyyy` and
@@ -17,26 +41,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   weekday name is spelled in stays the reader's, because that is what a
   spreadsheet application supplies and pinning it would stop the file reading
   naturally for whoever opens it.
-
 - **A declared digit count builds the pattern.** A `number` cell asking for
   three digits writes `#,##0.000`, and a `currency` cell asking for none writes
   `"EUR"#,##0` — the same count the page presents, taken off the declaration
   the engine resolved rather than computed here.
-
 - **A cell's own `currency` code picks the number format**, ahead of the
   instance's default: `"JPY"#,##0` where the row says `JPY`, since the code
   decides the digits too. The cell stays a number either way. A code the engine
   could not accept writes no number format at all, rather than labelling the
   cell in the instance's currency.
-
-### Changed
-
 - **A `date` cell with no declared form now writes `dd mmm yyyy`, not
   `yyyy-mm-dd`.** A bare `date` means the `medium` form throughout, so the grid
   agrees with the page. A report that wants the ISO shape has no form for it;
   the nearest is `{ "kind": "date", "form": "short" }`, which writes
   `dd/mm/yy`. The cell is still a real typed date either way.
-
 - **A cell's number format now comes from the engine's fraction-digit count
   rather than from four patterns this target held of its own.** The visible
   change is `currency`: the pattern followed the currency's own minor units,
@@ -45,7 +63,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`#,##0.00`), `percent` (`0.00%`) and `date` (`yyyy-mm-dd`) are unchanged in
   a worksheet; what changed for those is that HTML and PDF now show the same
   decimals the grid always did, instead of their own.
-
 - A `currency` code that is not a readable currency no longer produces a number
   format at all. The cell keeps its value; before, the code was pasted straight
   into a pattern while every other target fell back to the unformatted value.
@@ -54,39 +71,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   position still come from the application that opens the file, which is what
   lets one workbook read naturally wherever it is opened.
 
-### Fixed
-
 - A `format` kind reaching this target from an `=` expression is now looked up
   as an own key. Before, a kind resolving to the name of a built-in object
   member threw out of the render (`valueOf`, `hasOwnProperty`) or wrote
   `[object Undefined]` into the cell's number format (`toString`). A literal
   was never affected: it is checked against the four kinds.
-
-### Fixed
-
 - **An image whose size cannot be read now names the item that asked for it.**
   The failure said only that the size could not be read from the bytes, so a
   report with two pictures gave no way to tell which one was bad. The message
   now begins with the item's `source` path, as every other render error does
   and as it does from every other target.
 
-## [0.5.0] - 2026-09-05
+## 0.5.0
 
-### Added
+### Minor Changes
 
 - **Chrome merges, data does not.** A cell spanning several columns in the
   header row or a total row is written into the first column it covers, the
   rest of the range is written empty, and the range is merged. Nothing in the
   data region merges, so sort, filter and column selection keep working over
   it.
-
 - **`valign`** writes the cell's vertical alignment for table cells and split
   slots. Undeclared writes nothing, so the spreadsheet application keeps its
   own default.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Changed
+### Minor Changes
 
 - **A date string under `format: "date"` now reaches the grid as a date.**
   The cell carries a real date value under the `yyyy-mm-dd` number format
@@ -94,83 +105,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   cell declaring the kind is affected; a string in a form the engine does not
   read stays text. See the `quario` changelog for the forms.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Added
+### Minor Changes
 
 - **`format` maps to a number format; the cell stays typed.** `number` is
   `#,##0.00`, `percent` `0.00%`, `date` `yyyy-mm-dd`, `currency` the
   instance currency code as `"USD"#,##0.00`. A kind on the wrong type
   contributes nothing.
-
 - **Cell borders map; padding and flow spacing do not.** `solid` is exceljs
   `thin`; `dashed` and `dotted` keep their names. A header-row, row, or
   total-row box fans onto that row's cells; a cell that named any of a
   side's three keys owns that side whole. Padding is unread: a worksheet
   cell has no inset. Flow spacing is unread: a grid has no flow.
-
 - **`page.margin` and report-header `height` are unread.** A grid has no
   page top to pin from.
-
-### Changed
-
 - **A table total emits N rows.** Each `total-row` is one worksheet row, as
   each data row is.
-
 - **A cell whose display contains a newline wraps.** `wrapText` is this
   target's mapping of a literal newline as a line break, so `"one\ntwo"` is
   two lines in the grid. Single-line cells are unchanged.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **The report default reaches every cell.** A report's top-level `style`
   replaces this target's baseline, so a document declaring a face and size gets
   them in cells that declare nothing of their own. It is the layer under the
   band-role defaults — a report declaring `size: 12` still writes its report
   header at 14 — and under each cell's own style.
-
 - **`uppercase` is accepted and deliberately not read.** A spreadsheet font
   has no text-transform, and writing capitals into the cell instead would turn
   presentation into data — the cell would stop round-tripping and would sort
   differently. The cell keeps the text you wrote; every other declaration on
   it still applies. Same posture as the column widths this target withdrew.
-
 - **A split is one row, its slots the cells across it.** The grid's own
   reading of values placed beside each other. Slot `width` shares go unread,
   on exactly the ground the table's column widths do — a worksheet's columns
   are global to the sheet. The split's own style is what its slots sit under,
   layering the way a table row's does, and a slot that renders nothing writes
   an empty cell so the cells either side keep their columns.
-
-### Changed
-
 - **Every cell is written at 10 points unless something declares otherwise.**
   The size was previously left to the writer's own default of 11. Now that a
   report can declare its own size, this target and the PDF carrying different
   numbers for one declaration is exactly what the targets' agreement rule
   forbids. A worksheet's row height follows its font size, so existing unstyled
   sheets come out slightly tighter.
-
 - **Display-text `Date`s join as ISO 8601 UTC.** A `Date` inside a mixed
   cell (literal text plus interpolation) joined through `String(date)`, which
   bakes the host's timezone and locale into the worksheet. It now joins
   through the engine's shared display rule as `toISOString()` text. Typed
   cells are untouched: a cell that is one bare `Date` interpolation still
   writes a native date.
-
-### Fixed
-
 - **Cells carry their font face explicitly.** Text declaring no `family` used
   to inherit whatever the workbook writer defaulted to, which agreed with the
   other targets only by coincidence. It now writes the same face that
   `family: "sans"` resolves to, so the baseline is a rule rather than a
   property of the library underneath.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **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

package/README.md

@@ -79,7 +79,7 @@ as that order alone. Group boundaries add no rows of their own, and `break: "pag
 `reset: "page"` are ignored, as are `page.margin` and a report header's `height`.
 
 Each item takes one row with its cell in the first column, unmerged; a split takes one row with its
-slots as the cells across it (slot widths unread, a slot rendering nothing an empty cell), and a
+slots as the cells across it (slot widths withdrawn, a slot rendering nothing an empty cell), and a
 spanning header or total cell is a merged range. 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.
@@ -109,9 +109,11 @@ on the wrong type, or a code the engine cannot read, writes no format.
 ### 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. Bytes too short to carry a size reject
-the render rather than vanish.
+drawing at its natural pixel size. Placement here is best-effort. `fit`, `alt`, and `style` are
+unused, and all of it may change without a breaking change (see the
+[support matrix](https://getquario.com/docs/reference/support-matrix/#output)). Bytes too short to
+carry a size never reach this target: the engine reads every image's size and rejects them for
+every target alike.
 
 ### Styles
 
@@ -136,17 +138,18 @@ The first table's header row anchors the frozen view. Everything from that row u
 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
+### Widths are withdrawn
 
 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
+### Page columns are withdrawn
 
-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.
+A [page column](https://getquario.com/docs/reference/support-matrix/#page-and-pagination) 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
 
@@ -161,6 +164,17 @@ The document model is deterministic: the workbook's dates are pinned rather than
 `meta` is opt-in. The **bytes** are not. The writer stamps archive entries with the packing time.
 Compare extracted content, not digests.
 
+The full contract is [The XLSX target](https://getquario.com/docs/diving-deeper/xlsx-target/),
+with each declaration's fate in the
+[support matrix](https://getquario.com/docs/reference/support-matrix/).
+
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare, and
+[`@quario/xlsx`](https://getquario.com/docs/reference/xlsx/) is this package's own API.
+
 ## License
 
 Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer

package/lib/cell.js

@@ -2,12 +2,13 @@
  * 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. Display text that contains a
- * newline gains `wrapText` so the break is visible in the grid.
+ * the sheet), the worksheet's rich-text shape when the cell holds more than
+ * one styled run, and the display-text join otherwise. `format` is the
+ * resolved cell-level formatting from the style module. Display text that
+ * contains a newline gains `wrapText` so the break is visible in the grid.
  */
-import { currencyOf, text, typed } from "quario";
-import { format as look, merge } from "./style.js";
+import { currencyOf, display, format as present, styledRuns, text, typed } from "quario";
+import { font, format as look, merge } from "./style.js";
 
 // The digit count is the engine's, never this target's: it rides on the
 // resolved declaration the stream carries, the same one HTML and PDF
@@ -87,14 +88,62 @@ let paintWrap = (out, shown) => {
     out.alignment = { ...out.alignment, wrapText: true };
 };
 
+// One run's presented text: literals verbatim, every value through the
+// declaration that run resolved. A run holding a single value token presents
+// it, so a formatted amount inside a sentence reads the same here as it does
+// on the page -- SCHEMA.md pins that the fraction digits are the same in every
+// target that presents, and this target presents (ADR 0061). A run the engine
+// withdrew the declaration from has nothing to present with and falls to
+// display text, which is what the whole cell used to do.
+/** @type {(tokens: any[], style: any, intl: any) => string} */
+let shownText = (tokens, style, intl) => {
+  let out = "";
+  for (let token of tokens)
+    out +=
+      "literal" in token
+        ? token.literal
+        : (present(token.value, style, intl) ?? display(token.value));
+  return out;
+};
+
+// A cell of more than one styled run takes the worksheet's rich-text shape:
+// each run's **font half** merged over the cell font, and nothing else. A
+// run-level `background` is inert -- spreadsheet rich-text runs carry fonts
+// only, and filling the cell would colour text the author did not name -- and
+// so is a run-level number format, since a cell has one and this cell is text.
+// No typed cell is lost: a cell of more than one run holds more than one token
+// and was display text already.
+/** @type {(cell: any, styled: any[], under: any, intl: any) => any} */
+let rich = (cell, styled, under, intl) => {
+  let base = merge(under, cell.style);
+  let out = look(base);
+  let parts = styled.map((one) => {
+    let style = one.style ? merge(base, one.style) : base;
+    return { font: font(style), text: shownText(one.tokens, style, intl) };
+  });
+  paintWrap(out, parts.map((part) => part.text).join(""));
+  return { value: { richText: parts }, format: out };
+};
+
+// The style a cell of one styled run wears: that run's resolved answer, which
+// already carries the cell's own declarations, or the cell's where it has no
+// run at all.
+/** @type {(cell: any, styled: any[]) => any} */
+let soleStyle = (cell, styled) => styled[0]?.style ?? cell.style;
+
 /**
  * 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).
  *
+ * A cell of exactly one styled run wears that run's answer whole, so a single
+ * styled amount is still a number in the grid.
+ *
  * @type {(cell: { tokens: any[], style?: any }, under: any, intl?: any) => { value: any, format: any }}
  */
 let field = (cell, under, intl) => {
-  let resolved = merge(under, cell.style);
+  let styled = styledRuns(cell.tokens);
+  if (styled.length > 1) return rich(cell, styled, under, intl);
+  let resolved = merge(under, soleStyle(cell, styled));
   let shown = shownOf(cell, resolved?.format);
   let out = look(resolved);
   paintFmt(out, resolved, shown, intl);

package/lib/index.js

@@ -15,10 +15,9 @@
  * the packing time. Byte-for-byte output is a goal for the writer that will
  * replace `workbook.js`.
  */
-import { imageError, walk } from "quario";
+import { walk } from "quario";
 import { field } from "./cell.js";
 import { merge as under } from "./style.js";
-import { pixels } from "./image.js";
 import { append, create, embed, freeze, mark, place, save, sheet, span } from "./workbook.js";
 
 // The options are described once, in the hand-written public declarations, and
@@ -27,17 +26,19 @@ import { append, create, embed, freeze, mark, place, save, sheet, span } from ".
 
 // 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.
+// band writes plain cells. SCHEMA.md states the pair, 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.
+// them.
+//
+// `test/omakase-defaults.test.js` is what holds the copies in agreement. This
+// comment names the gate rather than listing the files, because the list is
+// what rotted: it used to name `packages/viewer/lib/style.js` and a `style.js`
+// of the PDF target's own, and neither file exists.
 /** @type {Record<string, any>} */
 let ROLES = {
   "report-header": { bold: true, size: 14 },
@@ -195,15 +196,14 @@ export function xlsx(options) {
       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"). Named on the item through the engine's
-          // own mint, so this failure reads the same from here as it does from
-          // a target that paints or embeds.
-          if (!size) throw imageError(event.path, "could not read the image's size from its bytes");
-          known = { ...size, id: embed(workbook, event.bytes, event.format) };
+          // The event states the size in pixels, which is the unit a floating
+          // drawing is placed in, so this target has nothing to work out: the
+          // engine read the header once for every target (`docs/adr/0067`).
+          known = {
+            width: event.width,
+            height: event.height,
+            id: embed(workbook, event.bytes, event.format),
+          };
           images.set(event.bytes, known);
         }
         if (split) {

package/lib/style.js

@@ -22,6 +22,7 @@ let FAMILY = { sans: "Calibri", serif: "Times New Roman", mono: "Courier New" };
 
 // A declared colour as an ARGB string, or null when the value is not one.
 /** @type {(value: any) => string | null} */
+// fallow-ignore-next-line code-duplication -- each target reads a declared hex into its own type; neither may import a sibling, and the engine's stream is all they share
 let argb = (value) => {
   let match = typeof value === "string" && HEX.exec(value);
   if (!match) return null;
@@ -138,4 +139,4 @@ let format = (style) => {
   return put(out, "alignment", alignment(style));
 };
 
-export { format, merge };
+export { font, format, merge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "The spreadsheet render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -42,12 +42,12 @@
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/node": "^22.20.1",
-    "quario": "^0.6.0",
+    "quario": "^0.8.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.6.0"
+    "quario": "^0.8.0"
   },
   "size-limit": [
     {

package/lib/image.js

@@ -1,45 +0,0 @@
-/**
- * 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];
-
-// 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) => {
-  // A PNG carries the two numbers in its IHDR at a fixed offset.
-  let size = format === "png" ? { width: word(bytes, 18), height: word(bytes, 22) } : jpeg(bytes);
-  return size.width > 0 && size.height > 0 ? size : null;
-};