@particle-academy/holy-sheet 2.10.2 → 2.11.1

package/CHANGELOG.md

@@ -10,6 +10,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.11.1] - 2026-10-27
+
+### Fixed
+
+- **An explicit `{value: <string>}` cell is now written as a string, exactly
+  as given**, matching PHP holy-sheet and holy-sheet-py. Numeric-string
+  coercion used to run on the object form too, so `{value: "+1"}` was written
+  as the number 1, `{value: "007"}` as 7 and `{value: "1e5"}` as 100000: a
+  phone prefix, zip code or part number lost its characters with no error.
+  This applies in `rows` and in the sparse `cells` map, under any column type
+  or number format, and to a `set_cell` op's `value`. Unchanged: a BARE string
+  in a row or a `cells` entry is still coerced (`"+1"` is still 1) and a bare
+  `"=..."` is still a formula; an object value that is already a number is
+  still a number; and a string under a `date` / `datetime` display format is
+  still converted to a date serial. `read()` returns such a cell as the same
+  string.
+  **What a consumer must do:** if you relied on `{value: "100"}` becoming a
+  number, pass the number (`{value: 100}`) or the bare string (`"100"`).
+  Otherwise nothing.
+
+## [2.11.0] - 2026-10-27
+
+### Added
+
+- **Excel `.xltx` templates read, and `.ots` templates marked.** `read()` /
+  `describe()` read an `.xltx` exactly as its `.xlsx` twin and add
+  `sourceKind: "template"`; an `.ots` (already read, unmarked) now says so too.
+  `Workbook` gains a trailing optional `sourceKind` (default `"document"`).
+  Document reads are unchanged and carry no `sourceKind` key, so nothing to do
+  unless you want to tell the two apart. Mirrors PHP holy-sheet.
+- **`Agent.convertTemplate(bytes, to?)`** (also on `HolySheet`) and the new
+  `holy-sheet` bin, `npx holy-sheet template:convert <in> <out>
+  [--to=document|template] [--force]`, turn a template into its workbook twin
+  and back. Only the declaration is rewritten: the workbook part's content-type
+  value (OOXML), or the `mimetype` entry plus the manifest root's `media-type`
+  (ODF 1.3 Part 2 section 3.3 requires them to agree). Every other zip member is
+  copied as its original record, byte for byte; `mimetype` stays first and
+  stored. The bin is Node-only and never imported by the isomorphic index.
+- `OfficeTemplateRefused` with a constant `reason`.
+
+### Changed
+
+- **A macro-enabled template (`.xltm`) is now refused** with
+  `OfficeTemplateRefused("macro_enabled")`; it used to be read as a workbook with
+  its VBA silently ignored. So is an `.xltx` carrying a `vbaProject.bin`. An
+  `.xlsm` still reads as before but is never converted.
+- A package that declares a template of another family is refused with
+  `family_mismatch` instead of being read as whatever its parts looked like.
+
 ## [2.10.2] - 2026-10-26
 
 ### Security

package/README.md

@@ -76,6 +76,33 @@ when there is one). What maps and what does not is listed in the PHP package's
 [`docs/ReadPath.md`](https://github.com/Particle-Academy/holy-sheet/blob/main/docs/ReadPath.md#opendocument-spreadsheets-ods);
 this port reads the same fixtures and is diffed against it.
 
+### Excel and LibreOffice templates (.xltx, .ots)
+
+An `.xltx` is an `.xlsx` whose workbook part is declared a template; an `.ots`
+is an `.ods` whose `mimetype` (and manifest root entry) says
+`spreadsheet-template`. `read()` / `describe()` read both exactly as their twins
+and add `sourceKind: "template"` (also `Workbook#sourceKind` from
+`readWorkbook()`). A document read has no `sourceKind` key, as before.
+
+```ts
+Agent.read(xltxBytes);                 // { ..., sourceKind: "template" }
+Agent.convertTemplate(xltxBytes);      // .xlsx bytes ("document" | "template" | null = flip)
+```
+
+```
+npx holy-sheet template:convert budget.xltx budget.xlsx
+npx holy-sheet template:convert budget.ods budget.ots --to=template
+```
+
+Conversion rewrites only the declaration: the content-type value in
+`[Content_Types].xml`, or the ODF `mimetype` entry plus the manifest's root
+`media-type` (ODF 1.3 requires the two to match). Every other member is copied
+as its original zip record, byte for byte; `mimetype` stays first and stored.
+Refused with `OfficeTemplateRefused` (a constant `reason`): macro-enabled `.xltm`
+(`macro_enabled`; an `.xlsm` is never converted either) and a package declaring
+a template of another family (`family_mismatch`). The archive guards apply
+first. Mirrors PHP `Agent::convertTemplate()`.
+
 ### Versions as diffs
 
 `Agent.diff(a, b)` returns the ops that turn one schema into another, and