@quario/xlsx 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,15 +1,24 @@
-# 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.7.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,
@@ -18,14 +27,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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] - 2026-09-07
+## 0.6.0
 
-### Added
+### 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
@@ -33,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,
@@ -61,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.
@@ -70,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
@@ -110,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

@@ -110,8 +110,10 @@ on the wrong type, or a code the engine cannot read, writes no format.
 
 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` are
-unused, and all of it may change without a breaking change. Bytes too short to carry a size reject
-the render rather than vanish.
+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
 
@@ -145,8 +147,9 @@ table for a share to be a share of.
 
 ### 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/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
@@ -197,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.7.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.7.0",
+    "quario": "^0.8.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.7.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;
-};