werkmap 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,216 @@
+# werkmap
+
+A tiny spreadsheet writer for JavaScript. It writes an `.xlsx` file — rows, typed cells, styles, merged ranges, a frozen header, floating images — and nothing else. It does not read one. _Werkmap_ is Dutch for a workbook, which is the one thing this package makes.
+
+Writing is the whole surface, so the package stays small enough to audit. The container is written against the ZIP specification over `CompressionStream`, every part is a string, and no value ever turns into code — so it runs unchanged under a Content Security Policy with no `unsafe-*` of any kind, which is what a spreadsheet export in the browser usually cannot do.
+
+- **Byte-identical output.** Nothing consults a clock, a locale or a random source, and the ZIP epoch is pinned, so two renders of the same report are the same bytes and a build that caches by content hash keeps working.
+- **Foreign readers accept it.** The suite loads every workbook it writes back through ExcelJS, an independent implementation — so the tests prove a real reader opens the file, not just that the bytes look plausible.
+- **Zero dependencies.** 5.7 kB minified and brotlied, for the whole writer.
+- **Strict CSP, including in the browser.** No `unsafe-eval` and no `unsafe-inline`. A Chromium page under `default-src 'none'; script-src 'self'` writes a workbook and reports any violation back, and the Node suite runs on `--disallow-code-generation-from-strings`.
+- **Write-only, deliberately.** No reader, no formula engine, no chart support — see [Is werkmap the right tool?](#is-werkmap-the-right-tool) before you install it.
+- **Hardened.** 53 tests at 100% branch coverage.
+
+```js
+import { workbook } from "werkmap";
+
+const wb = workbook({ title: "Sales" });
+const sheet = wb.sheet("Report");
+
+sheet.row([{ value: "Product" }, { value: "Amount" }]);
+sheet.row([{ value: "Laptop" }, { value: 1000, style: { numberFormat: "#,##0.00" } }]);
+
+const bytes = await wb.bytes();
+//=> Uint8Array — and running this again produces byte-identical output
+```
+
+<img src="https://getquario.com/favicon.svg" alt="Quario logo" width="16" height="16" /> <b>werkmap</b> is built by the team behind <b><a href="https://getquario.com?utm_source=github&utm_medium=readme&utm_campaign=werkmap">Quario</a></b>, a declarative reporting engine for JavaScript that renders JSON report definitions to <b>HTML, PDF, workbooks, and Word</b> — without <code>eval</code>.
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Is werkmap the right tool?](#is-werkmap-the-right-tool)
+- [API](#api)
+- [Styles](#styles)
+- [Guarantees, not options](#guarantees-not-options)
+- [Determinism](#determinism)
+- [Errors](#errors)
+- [Content Security Policy](#content-security-policy)
+- [Environments](#environments)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
+
+```bash
+npm install werkmap
+```
+
+Node.js 22 or newer, ESM only. TypeScript declarations ship with the package; nothing extra to install.
+
+## Usage
+
+```js
+import { workbook } from "werkmap";
+
+const wb = workbook({ title: "Sales", creator: "Acme BV" });
+const logo = wb.image(png, "png");
+const sheet = wb.sheet("Report");
+
+const head = sheet.row([
+  { value: "Sales", style: { font: { bold: true, size: 16 } } },
+  { value: null },
+]);
+sheet.merge(head, 1, 2);
+
+sheet.row([{ value: "Product" }, { value: "Amount" }]);
+sheet.row([{ value: "Laptop" }, { value: 1000, style: { numberFormat: "#,##0.00" } }]);
+sheet.freeze(head);
+sheet.place(logo, { row: 1, width: 120, height: 40 });
+
+const bytes = await wb.bytes(); // Uint8Array
+```
+
+Writing the file belongs to you: `bytes()` hands back a `Uint8Array`, which Node writes with `fs` and a browser hands to a download.
+
+## Is werkmap the right tool?
+
+werkmap writes the slice of the format a report needs, and refuses the rest.
+
+**It fits when:**
+
+- You produce spreadsheets and never consume them.
+- The output must be reproducible — a content hash, a golden test, a cache key.
+- The code runs under a strict Content Security Policy, in a browser or a worker.
+- You care what the dependency costs: there are none, and the whole writer is one readable file.
+
+**It does not fit when:**
+
+- You need to read, edit or convert an existing workbook.
+- You need formulas, charts, pivot tables, conditional formatting, data validation, hyperlinks, comments or sheet protection.
+- You need column widths or row heights. A reader sizes columns from its own defaults.
+- You have more rows than fit in memory. There is no streaming, row-at-a-time output.
+
+## API
+
+### `workbook(meta?) -> Workbook`
+
+`meta` is one optional bag of optional strings: `{ title, creator, subject, description }`.
+
+Members: `image`, `sheet`, `bytes`.
+
+### `workbook.image(bytes, format) -> number`
+
+`bytes` is a `Uint8Array` and `format` is `"png"` or `"jpeg"`. Returns an id for `sheet.place`.
+
+Identical bytes deduplicate and return the id already issued, so the same logo on twelve sheets is stored once.
+
+### `workbook.sheet(name) -> Sheet`
+
+Any number of sheets, in call order. Throws on a name a reader refuses: empty, over 31 characters, containing `: \ / ? * [ ]`, or a duplicate.
+
+### `workbook.bytes() -> Promise<Uint8Array>`
+
+The finished package. This does not seal the document: call it as often as you like, and the same call sequence yields the same bytes.
+
+### `sheet.row(cells) -> number`
+
+`cells` is an array; the returned number is the row's 1-based position, which `merge`, `freeze` and `place` take.
+
+Each element is `{ value, style }`, or `null` for an empty unstyled cell. `{ value: null, style }` is an empty **styled** cell, which is what a merged span's remaining columns need.
+
+`value` is one of:
+
+| Kind      | Shape                 | Written as                              |
+| --------- | --------------------- | --------------------------------------- |
+| text      | a `string`            | interned into the shared string table   |
+| number    | a finite `number`     | a numeric cell                          |
+| boolean   | `true` / `false`      | a boolean cell                          |
+| date      | a `Date`              | a 1900-system serial, converted in UTC  |
+| rich text | `[{ text, font }, …]` | one formatted run per entry             |
+| empty     | `null`                | an empty cell, written only when styled |
+
+Rich text is a **bare array** — there is no wrapper object, because nothing else in the value domain is an array. Each run carries its font in full, since a run inherits nothing from the cell font.
+
+### `sheet.merge(row, at, width)`
+
+One merged range across `width` columns of `row`, starting at the 1-based column `at`.
+
+### `sheet.freeze(rows)`
+
+Freeze the top `rows` rows. `0` clears.
+
+### `sheet.place(id, { row, col, width, height })`
+
+One floating picture anchored to the top-left of a 1-based cell, drawn at `width` × `height` CSS pixels at 96 dpi.
+
+All indexing is **1-based**, uniformly — rows, columns and image anchors. The XML counts from zero and this package subtracts internally; that off-by-one is its business and appears nowhere in the API.
+
+## Styles
+
+A style is one object, and every part of it is optional:
+
+```js
+{
+  font: { name, size, bold, italic, underline, strikethrough, color },
+  fill: "#eeeeee",
+  border: { top, right, bottom, left },   // each { style, color }, or absent
+  alignment: { horizontal, vertical, wrapText },
+  numberFormat: "#,##0.00",
+}
+```
+
+Colours are `#rrggbb`, with the `#rgb` shorthand accepted. There is no alpha channel: a colour either paints or is absent.
+
+A **fill is a colour**, not a pattern object — solid is the only pattern here, so there is nothing for a wrapper to distinguish. A border side's `style` is `"thin"`, `"dashed"` or `"dotted"`.
+
+Identical fonts, fills, borders and formats collapse to one entry each, so a style repeated down a thousand rows costs one record.
+
+## Guarantees, not options
+
+There is nothing to configure. Each of these is a property of the writer rather than a parameter, because an option is a rule every caller has to hold in their head, and none of these is a choice a caller can make better:
+
+- **Text is always interned** into the shared string table.
+- **Style tables are always interned.**
+- **Dates are the 1900 system**, converted in UTC. A reader's timezone is never consulted, and the phantom 1900-02-29 is accounted for, so a date before March 1900 lands on the day it names.
+- **A date with no format of its own** gets the short-date built-in, so it reads back as a day rather than as the number underneath it.
+- **Media deduplicates by bytes.**
+- **Every element is written in the Open XML SDK's child order.**
+- **Created and modified are always `1970-01-01T00:00:00Z`** and cannot be overridden. Byte-identity is the headline promise, and an overridable clock would quietly redefine "the same input" as "the same input at the same wall time". Put a real timestamp in `description`.
+
+## Determinism
+
+The same calls produce byte-identical output **on the same runtime**, where a runtime means the engine and the zlib build inside it.
+
+That qualifier is real rather than defensive. Deflate is not a single defined output: a conforming compressor may emit any valid stream, and engines differ. Chromium and Node happen to agree; Firefox and WebKit do not, and a Node patch release can carry a new zlib revision. So a digest of the finished archive pins a runtime as much as it pins a document.
+
+If you want a fingerprint that survives all of that, hash the **parts** rather than the archive: unzip, then digest each part's bytes. Those are strings this package assembles, with no compressor anywhere in them.
+
+## Errors
+
+The writer throws native `TypeError` and `RangeError` at the boundary, with a message naming the offending argument. There is no custom error class and no error codes: any one of these is a mistake in the calling code rather than a condition to branch on, and zero dependencies means nothing to import in order to write a `catch`.
+
+Leniency belongs where a document is authored. Strictness belongs here, because the job is never to emit a file a reader offers to repair.
+
+One deliberate exception is silent rather than thrown: **text the format cannot carry**. Control characters other than tab, newline and carriage return are stripped, as are unpaired surrogates, and a literal `_xHHHH_` in your text is escaped so a reader does not decode it. Failing a whole document over one stray byte in a customer's name is the wrong trade.
+
+## Content Security Policy
+
+werkmap never turns a string into code. It runs under a policy with no `unsafe-eval` and no `unsafe-inline`, and its own suite proves it twice: the Node tests run with `--disallow-code-generation-from-strings`, and a Chromium page under `default-src 'none'; script-src 'self'` writes a workbook and reports any violation back.
+
+The source is scanned for the two constructs on every run, so a regression fails the build rather than a deployment.
+
+## Environments
+
+Node.js 22 or newer, and browsers with `CompressionStream` — Chromium 103, Firefox 113, Safari 16.4. Workers included; there is no DOM access anywhere.
+
+The package is plain JavaScript with JSDoc types. There is no build step: what npm installs is what runs.
+
+## Contributing
+
+Run the whole gate with `npm run check`. It formats, lints, checks for dead code and duplication, measures the bundle, runs the suite at 100% coverage, and drives the browser page.
+
+## License
+
+Apache-2.0

package/lib/index.d.ts

@@ -0,0 +1,131 @@
+/** A colour as `#rrggbb`, or the `#rgb` shorthand. There is no alpha channel. */
+export type Colour = string;
+
+/** A font, written in full wherever it appears: an OOXML run inherits nothing. */
+export interface Font {
+  /** Defaults to `Calibri`. */
+  name?: string;
+  /** In points. Defaults to 11. */
+  size?: number;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  color?: Colour;
+}
+
+/** One side of a cell border. */
+export interface Edge {
+  style: "thin" | "dashed" | "dotted";
+  color?: Colour;
+}
+
+export interface Border {
+  left?: Edge | null;
+  right?: Edge | null;
+  top?: Edge | null;
+  bottom?: Edge | null;
+}
+
+export interface Alignment {
+  horizontal?: "left" | "center" | "right" | "justify" | "fill";
+  vertical?: "top" | "center" | "bottom" | "justify";
+  wrapText?: boolean;
+}
+
+export interface Style {
+  font?: Font | null;
+  /** A fill *is* a colour: solid is the only pattern this writer emits. */
+  fill?: Colour | null;
+  border?: Border | null;
+  alignment?: Alignment | null;
+  /**
+   * A number format code, spelled out. A code matching a built-in is written
+   * as that built-in's id; anything else is interned.
+   */
+  numberFormat?: string | null;
+}
+
+/** One stretch of text inside a rich-text cell. */
+export interface Run {
+  text: string;
+  font?: Font | null;
+}
+
+/**
+ * A cell value. `null` is an empty cell, which is still written when the cell
+ * carries a style. Rich text is a bare array of runs.
+ */
+export type Value = string | number | boolean | Date | readonly Run[] | null;
+
+export interface Cell {
+  value?: Value;
+  style?: Style | null;
+}
+
+/** Where a picture sits, and how large it is drawn. */
+export interface Placement {
+  /** 1-based row of the cell the picture anchors to. */
+  row: number;
+  /** 1-based column of that cell. Defaults to 1. */
+  col?: number;
+  /** CSS pixels at 96 dpi. */
+  width: number;
+  /** CSS pixels at 96 dpi. */
+  height: number;
+}
+
+export interface Sheet {
+  /** This sheet's name. */
+  readonly name: string;
+  /**
+   * Append a row. `null` is an empty unstyled cell. Returns the row's 1-based
+   * position, which `merge` and `place` take.
+   */
+  row(cells: readonly (Cell | null)[]): number;
+  /**
+   * Merge `width` columns of `row`, starting at the 1-based column `at`.
+   * Throws on a width below 2, an overlap, or a row that does not exist yet.
+   */
+  merge(row: number, at: number, width: number): void;
+  /** Freeze the top `count` rows. `0` clears. */
+  freeze(count: number): void;
+  /** Float a picture over the sheet, anchored to one cell. */
+  place(id: number, at: Placement): void;
+}
+
+export interface Metadata {
+  title?: string;
+  creator?: string;
+  subject?: string;
+  description?: string;
+}
+
+export interface Workbook {
+  /**
+   * Embed an image. Identical bytes deduplicate and return the id already
+   * issued. The id is what `Sheet.place` takes.
+   */
+  image(bytes: Uint8Array, format: "png" | "jpeg"): number;
+  /**
+   * Add a worksheet. Throws on a name Excel refuses: empty, over 31
+   * characters, containing `: \ / ? * [ ]`, or a duplicate.
+   */
+  sheet(name: string): Sheet;
+  /**
+   * The finished package. Not terminal in the sense of sealing the document:
+   * call it as often as you like, and the same call sequence yields the same
+   * bytes.
+   */
+  bytes(): Promise<Uint8Array>;
+}
+
+/**
+ * Open a workbook.
+ *
+ * The document's created and modified dates are always `1970-01-01T00:00:00Z`
+ * and cannot be overridden: byte-identity for the same input is this writer's
+ * headline promise, and an overridable clock would redefine "the same input"
+ * as "the same input at the same wall time".
+ */
+export declare const workbook: (meta?: Metadata) => Workbook;