Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Row and column STRUCTURE: insert, delete, move, resize, freeze, hide.
//
// EVERY FUNCTION HERE IS A PATCH FACTORY. It reads a sheet and returns what the
// store should commit — it never writes. That is not tidiness: the same Patch
// objects are the undo entries, the future CRDT ops and the agent API
// (store.ts:26-29), so a structural edit that mutated the document directly
// would be an edit with no inverse, no op and no way to undo it. The one
// function that writes is `applySheetProps`, and it is a store CASE BODY rather
// than a helper — it says so where it is declared.
//
// A RID IS NEVER REUSED. Row ids are what overrides (`cells["<colId>:<rid>"]`),
// notes and — soon — CRDT node identity attach to, so handing a fresh row the
// number of a deleted one resurrects the deleted row's corrections onto data
// that has nothing to do with them. That is a wrong number wearing a right
// number's clothes, which is the failure class this app exists to refuse. The
// same reasoning runs down the COLUMN axis and is sharper there, because column
// ids are not random: import mints them by slugging the header (import.ts:270),
// so re-importing a CSV after deleting a column produces the SAME id — and any
// override left behind by that delete lands on the fresh column silently. So a
// delete here takes its overrides with it, in the same commit, so undo restores
// both.
//
// BOUNDS CLAMP, IDENTITY REFUSES. A drag can legitimately run past the end of
// the sheet, so positions, counts and widths are clamped rather than thrown —
// an exception mid-gesture is a broken UI. A duplicate column id, a missing
// column, or column data whose length disagrees with the row count are caller
// bugs that corrupt the file quietly, so those throw. `applyPatch` takes the
// same line ("refusing loudly is the point").
import { RID_BLOCK } from './model.ts'
import type { Column, ColumnData, ColumnType, TableSheet } from './model.ts'
import type { Patch, Touched } from './store.ts'
import { formatValue, TYPE_LABEL } from './format.ts'
// --- shared -----------------------------------------------------------------
const rowsOf = (sheet: TableSheet): number => sheet.rids.reduce((n, [, c]) => n + c, 0)
/**
* Every rid in row order. The run-length encoding is what makes 4200 rows cost
* 20 bytes, but structural edits are far easier to get RIGHT on a flat list and
* they are rare (an import, an insert, a delete) rather than per-keystroke —
* store.ts expands for the same reason.
*/
const ridsInOrder = (sheet: TableSheet): number[] => {
const out: number[] = []
for (const [start, count] of sheet.rids) for (let i = 0; i < count; i++) out.push(start + i)
return out
}
// An override key is "<colId>:<rid>", split at the FIRST colon — the same split
// applyPatch uses, so a colon in a column id cannot make these two disagree.
const colOfKey = (k: string): string => {
const i = k.indexOf(':')
return i < 0 ? k : k.slice(0, i)
}
const ridOfKey = (k: string): number => {
const i = k.indexOf(':')
return i < 0 ? NaN : Number(k.slice(i + 1))
}
const clamp = (v: number, lo: number, hi: number): number =>
!Number.isFinite(v) ? lo : v < lo ? lo : v > hi ? hi : v
const clampInt = (v: number, lo: number, hi: number): number => Math.floor(clamp(v, lo, hi))
/**
* `pack` is an opaque archive encoding, and applyPatch's row splices skip it
* (store.ts:263-270 handles `raw` and `dict` only). A row inserted into a sheet
* holding a packed column therefore shifts every OTHER column by one against
* it: every value below the insert reads off the wrong row, invisibly, forever.
* So this refuses at mint time. The call site promotes to `raw` first, which is
* the policy `writeCell` already states for single-cell writes.
*/
function refusePacked(sheet: TableSheet, doing: string): void {
for (const [id, d] of Object.entries(sheet.data)) {
if (d.enc === 'pack') {
throw new Error(
`cannot ${doing} sheet "${sheet.id}": column "${id}" is packed — promote it to raw first`,
)
}
}
}
// --- rows -------------------------------------------------------------------
/**
* The next rid this sheet may mint, as a floor over everything the file can
* still be shown to have used:
*
* - the live rows;
* - every rid still NAMED by an override, even if its row is gone. A row
* deleted by a raw `deleteRows` patch (or by an older build) leaves its
* `cells` entries behind, and that orphan is exactly the override a reused
* rid would resurrect. Reading it is what makes reuse safe rather than
* merely unlikely;
* - an explicit `nextRid` stamp, if the document carries one.
*
* `deleteRowsAt` clears the overrides it orphans, so after a delete through
* this module there is nothing left to resurrect and the numbers may be minted
* again without harm. That is a TODAY argument, not a forever one: once row
* identity is also a CRDT node key, two replicas must never mint the same rid
* for different rows, and the water mark has to be durable. `nextRid` is read
* here so that stamping it is a one-line change at the call site the moment a
* patch op can write a sheet field — see SetSheetProps below.
*/
/**
* This replica's rid block while a collaborative session is live, or `null`
* when the document is solo.
*
* Module state rather than a threaded argument because minting happens deep
* inside patch construction and the block belongs to the SESSION, not to any
* one sheet or edit — the same shape the kernel uses for the encryption
* password. `setRidBlock(null)` restores the solo numbering exactly.
*/
let ridBlock: { base: number; high: number } | null = null
/**
* Point minting at an actor's block. See model.ts's rid-partitioning note.
*
* `high` is an in-memory high-water mark for THIS session, and it is what stops
* a rid being reused after a delete inside the block: the durable
* `sheet.nextRid` watermark cannot serve here, because it is a maximum across
* every actor's rids and would push this replica straight out of its own block
* and into someone else's.
*
* Across sessions the question does not arise — an actor id is fresh per
* session instance, so a reconnecting replica gets a different block and cannot
* collide with what it minted before.
*/
export function setRidBlock(base: number | null): void {
ridBlock = base === null || base <= 1 ? null : { base, high: base - 1 }
}
/**
* Rows a COMMENT still names, live or not.
*
* A comment anchors to a rid and is deliberately never rewritten when its row
* is deleted — it becomes an orphan, kept and flagged, so that anything
* restoring the rid (an undo, a re-import, a collaborator) re-attaches the
* remark byte-identically. That is only safe while the rid is never handed to
* a DIFFERENT row: without this, a workbook whose rows were deleted by a build
* predating the watermark could mint one again, and somebody's sentence would
* reappear attached to a number it was never about.
*
* The same hazard the header above describes for overrides, and the same fix.
*/
function commentRids(sheet: TableSheet): number[] {
const out: number[] = []
for (const c of sheet.comments ?? []) {
const a = c?.anchor as { kind?: unknown; rid?: unknown } | undefined
if (a && a.kind === 'cell' && typeof a.rid === 'number' && Number.isFinite(a.rid)) out.push(a.rid)
}
return out
}
function nextRidFloor(sheet: TableSheet): number {
const blk = ridBlock
if (blk) {
// The maximum WITHIN this block. Other replicas' rids live in other blocks
// and are irrelevant — taking a global maximum is exactly what would break
// the partition.
const top = blk.base + RID_BLOCK - 1
let hi = blk.high
const inBlock = (rid: number) => rid >= blk.base && rid <= top
for (const [start, count] of sheet.rids) {
const last = start + count - 1
if (inBlock(last)) hi = Math.max(hi, last)
else if (inBlock(start)) hi = Math.max(hi, start)
}
for (const k of Object.keys(sheet.cells ?? {})) {
const rid = ridOfKey(k)
if (Number.isFinite(rid) && inBlock(rid)) hi = Math.max(hi, rid)
}
for (const rid of commentRids(sheet)) if (inBlock(rid)) hi = Math.max(hi, rid)
blk.high = hi
return hi + 1
}
let hi = 0
for (const [start, count] of sheet.rids) hi = Math.max(hi, start + count - 1)
for (const k of Object.keys(sheet.cells ?? {})) {
const rid = ridOfKey(k)
if (Number.isFinite(rid)) hi = Math.max(hi, rid)
}
for (const rid of commentRids(sheet)) hi = Math.max(hi, rid)
const stamped = sheet.nextRid
if (typeof stamped === 'number' && Number.isFinite(stamped)) hi = Math.max(hi, stamped - 1)
return hi + 1
}
/**
* Insert `count` blank rows so the first lands at row position `at`.
*
* `at` is a DATA position, not a screen row: when a sort is active the grid
* reads through `store.order`, and "insert above the row I am looking at" has
* to be mapped through that vector by the caller. Inserting at the position the
* user is scrolled to would otherwise put the row somewhere else entirely.
*/
export function insertRowsAt(sheet: TableSheet, at: number, count: number): Patch[] {
const n = Math.floor(count)
// Nothing to do returns NOTHING, rather than an empty patch: `commit([])`
// still pushes an undo entry, and a ⌘Z that visibly does nothing is a bug
// report.
if (!(n > 0)) return []
refusePacked(sheet, 'insert rows into')
const pos = clampInt(at, 0, rowsOf(sheet))
const first = nextRidFloor(sheet)
if (ridBlock) ridBlock.high = Math.max(ridBlock.high, first + n - 1)
const rids: number[] = []
const ats: number[] = []
// Contiguous and ascending, so `at[i]` stays valid as earlier splices land
// (applyPatch sorts by position) and the run-length encoding stays one run.
for (let i = 0; i < n; i++) { rids.push(first + i); ats.push(pos + i) }
return [{ op: 'insertRows', sheet: sheet.id, rids, at: ats }]
}
/**
* Delete `count` rows starting at data position `at`, and every cell override
* attached to them.
*
* The overrides go in the SAME commit, before the rows, so undo (which applies
* inverses in reverse) puts the rows back first and then their corrections.
* Leaving them behind would keep a deleted row's note, `was` value and author
* in the shared file, and would leave a live orphan for a later rid to inherit.
*/
export function deleteRowsAt(sheet: TableSheet, at: number, count: number): Patch[] {
const rows = rowsOf(sheet)
const from = clampInt(at, 0, rows)
const n = Math.min(Math.floor(count), rows - from)
if (!(n > 0)) return []
refusePacked(sheet, 'delete rows from')
const rids = ridsInOrder(sheet).slice(from, from + n)
const doomed = new Set(rids)
const keys = Object.keys(sheet.cells ?? {}).filter((k) => doomed.has(ridOfKey(k)))
const out: Patch[] = []
if (keys.length) {
out.push({
op: 'setOverrides', sheet: sheet.id, keys,
v: keys.map(() => undefined),
// an apply-then-undo that leaves `"cells": {}` behind is not a round trip
dropEmpty: true,
})
}
out.push({ op: 'deleteRows', sheet: sheet.id, rids })
return out
}
// --- columns ----------------------------------------------------------------
const dataLength = (d: ColumnData): number =>
d.enc === 'raw' ? d.v.length : d.enc === 'dict' ? d.idx.length : d.n
/**
* A column's stored values must be exactly as long as the sheet has rows.
*
* Short is ordinary — a column added to an existing sheet is blank in the rows
* that already exist — so it is padded. Measured, a short `raw` column READS
* the same as a padded one inside this build, because `readCell` answers `??
* null` past the end and `splice` past the end appends; the length is what
* differs, and the length is what leaves the building. The file is the product:
* a column with 2 values on a 4-row sheet is malformed to every other reader of
* that JSON — an agent, a chart binding, a re-encode to `pack`, whose `n` is
* authoritative — and each of them has to guess whether the tail is missing or
* blank. Padding here means nothing downstream ever has to guess.
*
* LONG is refused rather than trimmed. It means the values came from a
* different sheet, a different sort or a stale read, and trimming would pick an
* arbitrary prefix of someone's data and call it the column.
*/
function fitToRows(d: ColumnData, rows: number, colId: string): ColumnData {
const len = dataLength(d)
if (len === rows) return d
if (len > rows) {
throw new Error(`column "${colId}" carries ${len} values for a sheet with ${rows} rows`)
}
if (d.enc === 'pack') {
throw new Error(`packed column "${colId}" is ${len} values short; promote it to raw first`)
}
const pad = Array.from({ length: rows - len }, () => null)
// copied, never appended in place — the caller's object is not ours to grow
return d.enc === 'raw'
? { enc: 'raw', v: [...d.v, ...pad] }
: { enc: 'dict', dict: [...d.dict], idx: [...d.idx, ...pad] }
}
/**
* Insert a column at index `at`.
*
* The id is refused if the sheet already has it, because `data`, `cells` and
* `totals` are all keyed by column id: a duplicate does not collide loudly, it
* makes two columns share one set of values and one set of overrides, and the
* second one to be edited overwrites the first.
*/
export function insertColumn(
sheet: TableSheet, at: number, col: Column, data?: ColumnData,
): Patch[] {
if (sheet.columns.some((c) => c.id === col.id)) {
throw new Error(`sheet "${sheet.id}" already has a column "${col.id}"`)
}
// A formula column has no stored values by design (store.ts:83-85): storing
// them would let the file carry a number that disagrees with the expression
// that is supposed to produce it.
if (col.formula && data) {
throw new Error(`column "${col.id}" has a formula, so it cannot also carry stored data`)
}
const pos = clampInt(at, 0, sheet.columns.length)
const fitted = data ? fitToRows(data, rowsOf(sheet), col.id) : undefined
return [{
op: 'addColumn', sheet: sheet.id, column: col, at: pos,
...(fitted ? { data: fitted } : {}),
}]
}
/**
* Delete a column, its values AND its cell overrides.
*
* `removeColumn` alone drops `columns[i]` and `data[colId]` and stops there, so
* every `"<colId>:<rid>"` override survives the column that gave them meaning.
* They are not merely dead bytes: import derives column ids from the header
* text (import.ts:270), so the very next import of the same CSV re-creates the
* id — and the ghosts attach to fresh data as hand-made corrections, complete
* with an author and a reason. Clearing them here, in the same commit, makes
* the delete undoable as a whole.
*
* KNOWN GAP: `totals[colId]` cannot be cleared, because no patch op reaches
* `sheet.totals`. An orphan there is invisible (the grid iterates columns) but
* would come back with a re-imported id, so it wants the same treatment once
* there is an op that can write it.
*/
export function deleteColumn(sheet: TableSheet, colId: string): Patch[] {
if (!sheet.columns.some((c) => c.id === colId)) {
throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
}
const keys = Object.keys(sheet.cells ?? {}).filter((k) => colOfKey(k) === colId)
const out: Patch[] = []
if (keys.length) {
out.push({
op: 'setOverrides', sheet: sheet.id, keys,
v: keys.map(() => undefined), dropEmpty: true,
})
}
out.push({ op: 'removeColumn', sheet: sheet.id, col: colId })
return out
}
/**
* Move a column so that it ENDS UP at index `toIndex`.
*
* The off-by-one lives here. Moving right and moving left are not symmetric if
* you think in terms of the original array — remove-then-insert-at-toIndex on
* the ORIGINAL indices lands one short when the column came from the left of
* the target. Taking the column out FIRST and splicing into the shortened list
* makes `toIndex` mean the same thing in both directions: the index the column
* occupies when the move is done, which is the only definition a drag can
* express.
*
* The emitted order is always a FULL permutation. `reorderColumns` rebuilds
* `sheet.columns` from the ids it is given and filters out what it cannot find
* (store.ts:353), so an order that omits a column DELETES it — its data stays
* behind orphaned, and undo cannot bring it back, because the inverse is
* rebuilt from the columns that survived.
*/
export function moveColumn(sheet: TableSheet, colId: string, toIndex: number): Patch[] {
const ids = sheet.columns.map((c) => c.id)
const from = ids.indexOf(colId)
if (from < 0) throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
// `splice` clamps its own index, so this is not what makes the move land —
// it is what stops `to === from` being compared against NaN or a fraction,
// which would emit a patch that reorders nothing.
const to = clampInt(toIndex, 0, ids.length - 1)
if (to === from) return []
// spliced by POSITION, not filtered by id: a frozen document is never id-
// repaired (model.ts:470), so duplicate ids exist and a filter would remove
// both of them.
const order = ids.slice()
order.splice(from, 1)
order.splice(to, 0, colId)
return [{ op: 'reorderColumns', sheet: sheet.id, order }]
}
/** Below this a column cannot show its own sort arrow; above it, nothing fits beside it. */
const MIN_W = 56
const MAX_W = 420
/**
* Set a column's rendered width.
*
* Clamped and rounded rather than validated: this arrives from a live drag, so
* a value out of range is normal and an exception is a broken gesture. A
* non-finite width from a drag computation is clamped for a sharper reason —
* `JSON.stringify(NaN)` is `null`, so it would reach the file as `"w": null`
* and the grid would emit `width:nullpx`. Integers keep the JSON small and make
* a resize idempotent.
*/
export function resizeColumn(sheet: TableSheet, colId: string, w: number): Patch {
if (!sheet.columns.some((c) => c.id === colId)) {
throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
}
return {
op: 'setColumn', sheet: sheet.id, col: colId,
patch: { w: Math.round(clamp(w, MIN_W, MAX_W)) },
}
}
// --- auto-fit ---------------------------------------------------------------
//
// THIS IS AN ESTIMATE, and deliberately a pure one. There is no DOM here — the
// rigs run in node and this file is the half of the app that has to stay
// testable — so width is counted in characters against a per-type weight
// instead of measured. The UI may and should refine it with a real measurement
// (a canvas `measureText` over the visible rows costs nothing at 40 rows); it
// is one number and nothing downstream depends on how it was arrived at.
// Weights are biased HIGH by roughly a character, because a column a few pixels
// too wide looks fine and a column a few pixels too narrow clips a digit — and
// a clipped digit is a wrong number.
/** px per character at the grid's body size. Digits are wider than lowercase. */
const CHAR_W: Record<ColumnType, number> = {
text: 7.2, enum: 7.2, date: 7.4, bool: 8, number: 8, money: 8, percent: 8,
}
/** The header is the name plus the type control, and it must not clip either. */
const HEAD_CHAR_W = 7.6
const HEAD_CHROME = 34
/** left + right cell padding, plus a character of slack */
const CELL_PAD = 20
/**
* Rows read per column. A full pass over 250k rows to fit one column is a
* visible stall, and the sample is spread by STRIDE rather than taken off the
* top: a CSV sorted by date or name keeps its longest values at the end, and a
* first-N sample gets those columns wrong every time. The last row is always
* read, because that is where an appended total or a "grand total" label sits.
*/
const SAMPLE = 500
export function autoFitWidth(
get: (row: number) => unknown,
col: Column,
rows: number,
opts?: { max?: number },
): number {
// TYPE_LABEL is the English label; a localized one is a few px different and
// that is inside the slack this estimate already carries.
let widest = col.name.length * HEAD_CHAR_W
+ (TYPE_LABEL[col.type] ?? String(col.type ?? '')).length * 6.2 + HEAD_CHROME
+ (col.formula ? 18 : 0) + (col.failed ? 14 : 0)
const n = Math.max(0, Math.floor(rows))
const stride = Math.max(1, Math.ceil(n / SAMPLE))
const w = CHAR_W[col.type] ?? CHAR_W.text
const measure = (row: number): void => {
const v = get(row)
if (v == null) return
// formatted, not raw: the reader sees "$1,234.50" where the model holds
// 1234.5, and it is the rendered string that has to fit
const s = formatValue(v, col)
const px = s.length * w + CELL_PAD
if (px > widest) widest = px
}
for (let i = 0; i < n; i += stride) measure(i)
if (n > 0) measure(n - 1)
return Math.ceil(clamp(widest, MIN_W, Math.max(MIN_W, opts?.max ?? MAX_W)))
}
// --- sheet-level state: freeze --------------------------------------------
//
// THE ONE OP THIS MODULE NEEDS THAT `Patch` DOES NOT HAVE. Freeze is sheet
// state — frozen ROWS cannot be expressed as a column field — and `Patch`
// reaches exactly four places in the document: cell values, cell overrides,
// column objects and `doc.measures`/`doc.title`. Nothing writes a sheet field.
//
// So `setSheetProps` is declared here rather than faked. It is one case in
// `applyPatch`, whose whole body is `applySheetProps` below:
//
// case 'setSheetProps': return applySheetProps(table(doc, p.sheet), p)
//
// and one member on the `Patch` union. Until it lands, `SheetPatch` is the
// honest return type — a union that COLLAPSES to `Patch` the moment store.ts
// adopts the op, so nothing has to change here or at the call sites. The
// alternative was casting a foreign op to `Patch`, which compiles and then
// throws at commit time: an edit the user believes landed.
export interface SetSheetProps {
op: 'setSheetProps'
sheet: string
/** keys to SET */
props: Record<string, unknown>
/**
* keys to DELETE, listed rather than set to `undefined`, because these
* objects are also the wire format: `JSON.stringify({frozen: undefined})`
* drops the key entirely and the delete would arrive as a no-op.
*/
drop?: string[]
}
export type SheetPatch = Patch | SetSheetProps
/**
* Sheet keys `setSheetProps` refuses. Structure moves through the typed patches
* that know how to invert it — a props op that could rewrite `data` or `rids`
* would be an unbounded edit carrying an unbounded inverse, and the byte-capped
* history exists precisely to prevent that.
*/
const STRUCTURAL = new Set([
'id', 'kind', 'columns', 'data', 'rids', 'cells', 'steps',
// The SPREADSHEET kind's column widths and row heights, listed here for the
// same reason and only reachable since this op stopped being dataset-only:
// both are unbounded maps with a typed patch of their own (`setCanvasSizes`,
// which creates and removes the container and inverts one key at a time).
// Writing them wholesale here would put a document-sized inverse into a
// byte-capped history — exactly what this list exists to prevent.
'cols', 'rows',
])
/**
* The store case body for `setSheetProps` — the ONLY function in this file that
* writes, and it writes because `applyPatch` does. Returns the inverse, built
* from what it displaced, in the shape `applyPatch` returns.
*
* ANY SHEET KIND, and that is not a widening for its own sake. The body has
* never looked at a column or a rid — it displaces named keys on an object and
* refuses the structural ones — but the parameter said `TableSheet`, so
* `applyPatch` narrowed with `table(doc, id)` and THREW on everything else.
* A name is a property of a SHEET, not of a dataset: renaming a spreadsheet tab
* built a perfectly good patch and then died at commit with `no table sheet`,
* and the tab strip's context menu shipped a deliberately disabled Rename item
* describing a limitation of the rename box rather than the real one. Frozen
* panes, filters and `totals` are still dataset concepts; they are simply not
* concepts this function has ever known about.
*/
export function applySheetProps(
sheet: { id: string }, p: SetSheetProps,
): { inverse: SetSheetProps; touched: Touched } {
const s = sheet as unknown as Record<string, unknown>
const props: Record<string, unknown> = {}
const drop: string[] = []
const dropping = new Set(p.drop ?? [])
const displace = (k: string): void => {
if (STRUCTURAL.has(k)) {
throw new Error(`setSheetProps may not write "${k}" — structure moves through typed patches`)
}
// absent, so the inverse must DELETE rather than restore `undefined`:
// apply-then-undo has to leave the file byte-identical, and a key holding
// undefined is a key the next writer sees
if (k in s) props[k] = s[k]
else drop.push(k)
}
for (const k of Object.keys(p.props)) {
if (dropping.has(k)) throw new Error(`setSheetProps sets and drops "${k}" in one patch`)
if (p.props[k] === undefined) {
// Deleting has exactly ONE spelling, and it is `drop`. Accepting this as
// a delete too would mean the same intent travels two ways, one of which
// (`JSON.stringify({k: undefined})`) evaporates on the wire — the delete
// would land locally and reach no other replica. Refusing is how that
// stays impossible rather than merely discouraged.
throw new Error(`setSheetProps: to remove "${k}" list it in \`drop\`, not props`)
}
displace(k)
s[k] = p.props[k]
}
for (const k of dropping) {
displace(k)
delete s[k]
}
return {
inverse: { op: 'setSheetProps', sheet: p.sheet, props, ...(drop.length ? { drop } : {}) },
touched: { sheet: p.sheet, structural: true },
}
}
export interface Frozen {
rows: number
cols: number
}
/**
* Read the frozen panes, defensively: this is an additive field, so an older
* build, a hand edit or a future one can put anything there and the grid still
* has to draw. Anything unreadable means "not frozen", which is the state every
* reader can agree on.
*/
export function readFrozen(sheet: TableSheet): Frozen {
const f = sheet.frozen
if (typeof f !== 'object' || f === null || Array.isArray(f)) return { rows: 0, cols: 0 }
const o = f as Record<string, unknown>
const num = (v: unknown): number =>
typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0
return { rows: num(o.rows), cols: num(o.cols) }
}
/**
* Freeze `rows` rows and `cols` columns of this sheet.
*
* Clamped to leave at least one row and one column FREE, which is Excel's rule
* and, here, a correctness fix rather than politeness: a pane that freezes
* everything leaves nothing to scroll, so a stray `frozen.rows` of 1e9 (a bad
* drag, a hand-edited file) would render a grid that cannot move.
*
* Freezing nothing DROPS the field instead of storing zeroes. An additive field
* that means "no" should be absent — otherwise freezing and unfreezing leaves
* the file changed, every reader diffs it, and collab ships an op for a
* document that is back where it started.
*/
export function freezeAt(sheet: TableSheet, rows: number, cols: number): SheetPatch {
const r = clampInt(rows, 0, Math.max(0, rowsOf(sheet) - 1))
const c = clampInt(cols, 0, Math.max(0, sheet.columns.length - 1))
return r === 0 && c === 0
? { op: 'setSheetProps', sheet: sheet.id, props: {}, drop: ['frozen'] }
: { op: 'setSheetProps', sheet: sheet.id, props: { frozen: { rows: r, cols: c } } }
}
// --- hidden columns ---------------------------------------------------------
//
// Hiding is DOCUMENT data, not view state, and that is the opposite call from
// sorting. A sort belongs to the reader (store.ts's `view()`), but hiding a
// column is an editorial act — the author decided the working column is not
// part of the story — and two people opening one file have to see the same
// grid or they are reading different documents. It rides on the COLUMN, where
// unknown fields survive a round trip (model.ts:90), so a build that has never
// heard of hiding still preserves it.
export function hiddenSet(sheet: TableSheet): Set<string> {
const out = new Set<string>()
for (const c of sheet.columns) if (c.hidden === true) out.add(c.id)
return out
}
/**
* Show or hide one column.
*
* Showing writes `undefined`, not `false`: `JSON.stringify` omits an undefined
* value, so a column that was hidden and shown again leaves the file exactly as
* it found it. `false` would be honest in memory and would accumulate a dead
* flag on every column anyone ever touched, in every saved copy, forever.
*/
export function setHidden(sheet: TableSheet, colId: string, hidden: boolean): Patch {
if (!sheet.columns.some((c) => c.id === colId)) {
throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
}
// `undefined` is NOT a value JSON can carry: JSON.stringify drops the key,
// so `{hidden: undefined}` arrives as `{}` and the un-hide becomes a silent
// no-op over any wire — a saved file, a collaboration op, the agent API.
// Send `false`. (This file solves the identical hazard for `w` above.)
return {
op: 'setColumn', sheet: sheet.id, col: colId,
patch: { hidden },
}
}
/** Exposed for the rig, as store.ts does — not part of the app's surface. */
export const _internals = {
nextRidFloor, ridsInOrder, fitToRows, MIN_W, MAX_W, SAMPLE, CHAR_W,
}