stitchkit 0.115.0 → 0.117.0

package/llms/xlsx.txt

@@ -0,0 +1,107 @@
+# stitchkit/xlsx — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: XLSX  (docs/guide/xlsx.md) · API reference: `stitchkit/xlsx`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: XLSX  (docs/guide/xlsx.md)
+==============================================================================
+
+# XLSX
+
+`stitchkit/xlsx` turns rows into a workbook. It is evolving, it needs nothing beyond the `zod` the package
+already requires, and it runs wherever
+`CompressionStream` does: Bun, Node and a browser.
+
+```ts
+import { defineMoney } from 'stitchkit/primitives'
+import { renderXlsx, XLSX_MEDIA_TYPE } from 'stitchkit/xlsx'
+
+const rub = defineMoney('RUB')
+
+const bytes = await renderXlsx({
+  sheets: [
+    {
+      name: 'Orders',
+      columns: [
+        { key: 'title', header: 'Title', type: 'text' },
+        { key: 'count', header: 'Count', type: 'number', format: '0.00' },
+        { key: 'day', header: 'Day', type: 'date' },
+        { key: 'at', header: 'Created', type: 'datetime', timeZone: 'Asia/Bangkok' },
+        { key: 'total', header: 'Total', type: 'money', currency: 'RUB', scale: 2 },
+        { key: 'paid', header: 'Paid', type: 'boolean' },
+      ],
+      rows: [
+        {
+          title: 'First order',
+          count: '2.5',
+          day: '2026-11-03',
+          at: new Date(),
+          total: rub.create('504182'),
+          paid: true,
+        },
+      ],
+    },
+  ],
+})
+
+return new Response(bytes, {
+  headers: {
+    'content-type': XLSX_MEDIA_TYPE,
+    'content-disposition': `attachment; filename*=UTF-8''${encodeURIComponent('Übersicht.xlsx')}`,
+  },
+})
+```
+
+A missing or `null` value leaves the cell empty. The first row holds the headers, stays frozen and carries a
+filter. The same input produces the same bytes on one runtime; Bun and Node compress differently.
+
+## Column types
+
+| `type` | Cell value | In the file |
+|---|---|---|
+| `text` | string | text, whatever it looks like: `007` keeps its zeros |
+| `number` | number, bigint or decimal string | a number, with an optional Excel `format` |
+| `date` | `YYYY-MM-DD` | a date serial; a calendar date has no time zone to get wrong |
+| `datetime` | `Date` or ISO instant with an offset | the wall clock of the column's `timeZone` to the second, since a cell stores no zone |
+| `money` | `Money` in the column's `currency` | a number with `scale` places and the currency in its format |
+| `boolean` | boolean | a boolean |
+
+## What it refuses
+
+A value of the wrong type throws `XlsxCellError` naming the cell, such as `sheet "Orders" B2: expected a
+number or a decimal string`, instead of landing as a wrong cell.
+
+Excel keeps numbers as doubles, so 15 significant digits are what survives. A decimal string or `Money` with
+more refuses rather than turning into a different amount. Keep such a value in a `text` column if it must
+stay exact and needs no arithmetic. Dates before 1900-03-01 refuse too: Excel counts a leap day that never
+happened, so its serials before it are off by one.
+
+A wall clock cannot tell the two hours of a daylight-saving change apart: 05:30Z and 06:30Z on a New York
+autumn night are the same cell. Use `UTC` for a column whose order must survive that hour.
+
+## Text is never a formula
+
+Cells are written as inline strings, so `=HYPERLINK("x")` from a user's input is text a reader shows,
+and the file has no formula element at all. A cell that starts with `=`, `+`, `-` or `@` also carries Excel's
+quote prefix, so it stays text when a person edits that cell.
+
+## Limits
+
+Everything is built in memory, up to Excel's own 1 048 576 rows per sheet. There is no reading, no
+charts, no merged cells and no streaming: an application that needs them takes a library.
+
+==============================================================================
+# API reference: `stitchkit/xlsx`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/xlsx`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `renderXlsx` | function | a workbook from rows and typed columns as XLSX bytes; deterministic, no formula in the file |
+| `XLSX_MEDIA_TYPE` | constant | the media type for `defineExportOperation` and a download response |
+| `XlsxCellError` | class | a value of the wrong type, or one Excel cannot hold exactly, with the cell's address |
+| `XlsxWorkbookSchema` / `XlsxWorkbook` / `XlsxSheetSchema` / `XlsxColumnSchema` / `XlsxColumn` | schemas / _types_ | the workbook, its sheets and the six column types |