Skip to content

XLV-2: javascript-excel/render, the render model (+ resolveColor) - #96

Merged
securedeveloper merged 8 commits into
mainfrom
xlv-2-render
Nov 16, 2026
Merged

securedeveloper merged 8 commits into
mainfrom
xlv-2-render

Conversation

@securedeveloper

@securedeveloper securedeveloper commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

XLV-2: javascript-excel/render, the render model react-xlsx-viewer draws from (its design decision Q2: framework-free, in the engine). The API section is written first, in docs/api.md §5.8. §5.6 is /import and §5.7 is /format.

Release timing: the same decision as /format (Afzal, 2026-11-16): /render ships in 2.0. The minor changeset goes into the next 2.0 prerelease, and the docs say "Part of 2.0". The branch has main merged in, with /import (§5.6) and /format (§5.7), so /render is §5.8. It also carries #97's wording fix for /format (identical change), so the two merge cleanly in either order.

What it provides (docs/api.md §5.8)

import { createRenderSheet, renderCell, rowAt, colAt, edge, rangeAsTsv } from "javascript-excel/render";
const s = createRenderSheet(workbook, 0, { format: formatCell /* optional, from /format */, locale: "de-DE" });
  • Extent and settings. sheetExtent is the used range plus a margin (default 50 rows, 10 columns), capped at Excel's grid. sheetSettings returns freeze, RTL, grid lines, headers, zoom, active cell, selection and tab colour.
  • Geometry. rowTop/rowHeight/colLeft/colWidth come from Float64Array prefix sums (pt × 96/72; characters to px with the file-width formula and maxDigitWidth). Hidden rows and columns have size 0. rowAt/colAt binary-search and never return a hidden index.
  • Merges. mergeAt uses a row-bucket index. Covered cells render null, and the anchor carries merge: { rows, cols }.
  • Cells (renderCell, lazy, bounded cache):
    • Display text. It comes from the optional format hook; formatCell from JSE-18: javascript-excel/format, the number-format renderer #92 fits structurally, so there's no dependency on /format. ARGB colours become #RRGGBB. Without a hook, cellText is used and alignment follows the value type.
    • Rich-text runs carry resolved fonts.
    • Formula text for the formula bar: = plus the formula, with _xlfn./_xlfn._xlws./_xlpm. removed outside string literals. arrayFormula and noCachedValue flags are set where they apply.
    • Hyperlinks. External links are checked against the scheme allowlist (scheme/malformed reasons). Internal locations and defined names resolve to a sheet index and reference.
  • Styles. Concrete RenderStyles are cached in a WeakMap keyed by the model's style object. The reader's frozen shared styles therefore resolve once per xf; the test checks a.style === b.style on a written-then-read file.
    • Fonts fall back to the workbook default.
    • Solid, pattern and gradient fills, borders, alignment and reading order are resolved.
    • Empty cells in styled rows or columns use that style.
  • Border edges. Each cell draws top and left, plus right and bottom at the extent's end. The shared edge goes to the heavier style (a fixed weight order, [to verify] against Excel), with ties to the lower/right cell. Covered merge cells lend the anchor's style, and an empty cell under a bordered cell is drawn for that edge.
  • Navigation. step (arrow keys, merge-aware, skips hidden), edge (Ctrl+arrow, Excel's data-region rule), lastUsedCell (Ctrl+End).
  • Copy.
    • rangeAsTsv: TAB/CRLF, Excel-style quoting, merges once, displayed or raw values.
    • rangeAsHtml: an escaped <table> with inline styles and spans; hostile text and font names are tested.
    • rangeStats: count, numeric count, sum and average over cached values (dates as serials), with a scan limit.

The core entry also gains resolveColor. §4.4 already documented it, but it wasn't implemented:

  • theme colours, with the swapped first two pairs, the file's theme or the Office theme the writer embeds, and the tint on HSL luminance;
  • indexed colours (file palette or default; 64/65 system colours);
  • RGB and string forms, and automatic colours.

Tested values include Excel's "Accent 1, Lighter 80%" (DAE3F3).

Measured (docs/api.md §5.8.5; Apple M2, Node 26.13.1, npm run bench:render)

cells create (ms) memory retained (MB) 50 × 20 window, first / cached (ms) scroll per window p50 / max (ms) Ctrl+Down full column (ms) TSV + HTML of 10,000 cells (ms)
100,000 1.0 0.11 1.65 / 0.09 0.05 / 0.73 1.6 16.2
1,000,000 3.6 0.77 0.22 / 0.04 0.05 / 0.54 14.3 15.1
  • Memory. The handle costs O(rows + columns): about 8 bytes per row and column for the offset tables. Per-cell results are capped at 20,000 cached cells.
  • A fix the benchmark caught. Evicting the cache one oldest key at a time made copy after a long scroll take 111 ms, because later Map lookups skip deleted entries. The cache now clears when full.
  • CI. The Benchmarks job runs this script too, and reports to its summary and artifact.

In CI (GitHub Actions, Node 24, Benchmarks job)

cells create (ms) memory retained (MB) window first / cached (ms) scroll p50 / max (ms) Ctrl+Down (ms) TSV + HTML 10k (ms)
100,000 1.78 0.11 2.65 / 0.1 0.08 / 1.98 1.99 32.25
1,000,000 0.92 0.74 0.49 / 0.06 0.05 / 0.59 7.89 29.62

Checks

  • Tests: test/render/render.test.ts has 25 Node tests: geometry and hit testing, extent and settings, merges, shared styles from a real write→read, fills/fonts/alignment/row-style fallback, the border rule (weight, tie, empty-cell edge, merge neighbours), text/format hook/rich text, formula text, hyperlinks, navigation, TSV/HTML/stats, and resolveColor.
  • Packaging. New subpath ./render with types conditions. tsdown entry, entries test, smoke/consumer expectations (runtime, type fixture, tree-shaking marker), TypeDoc entry, README row.
  • Zero runtime dependencies. It imports only the address, cellText, dateToSerial and resolveColor helpers from the core.
  • /format compatibility is now a test, since /format is on main: const hook: RenderFormatter = formatCell type-checks. With locale: 'de-DE' it renders (1.234,50) in #FF0000 for #,##0.00;[Red](#,##0.00), and 15.01.2024 for id 14.
  • Local (Node 26.13.1): typecheck clean, npm test 857 passed (main with /import and /format merged in), publint, smoke (tsc node16/nodenext/bundler; unused-entry tree-shaking drops /render), docs snippets, and the API reference builds with no warnings.

Notes for the viewer design

  • createRenderSheet accepts Workbook<CellInput> (reader output and built workbooks with bare values alike), not only Workbook<Cell>.
  • RenderCell has edges (the resolved borders it draws) next to style.border (its own borders). The viewer design had the resolved edges inside the shared style. They can't be shared per style, because they depend on neighbours.
  • fill is { char, at }, like /format's, so the UI knows where to repeat the character.

No new dependencies.

@securedeveloper
securedeveloper merged commit 46581cf into main Nov 16, 2026
9 checks passed
@securedeveloper
securedeveloper deleted the xlv-2-render branch November 16, 2026 14:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant