cupertino-files / TableModel
Class: TableModel
Defined in: src/tst/tables.ts:633
Constructors
Constructor
new TableModel(
store,object,infoObject?):TableModel
Defined in: src/tst/tables.ts:639
Parameters
store
object
infoObject?
Returns
TableModel
Properties
infoObject
readonlyinfoObject:IwaObject|undefined
Defined in: src/tst/tables.ts:637
The TST.TableInfoArchive drawable owning this model, when known.
object
readonlyobject:IwaObject
Defined in: src/tst/tables.ts:635
store
readonlystore:ObjectStore
Defined in: src/tst/tables.ts:634
Accessors
columnCount
Get Signature
get columnCount():
number
Defined in: src/tst/tables.ts:677
Returns
number
footerRowCount
Get Signature
get footerRowCount():
number
Defined in: src/tst/tables.ts:2550
Returns
number
hasReadableCells
Get Signature
get hasReadableCells():
boolean
Defined in: src/tst/tables.ts:1419
True when cells decodes every cell in this table.
Always true for v5 storage. For pre-BNC it means every record matched a measured shape — the interesting case is false, which says the list cells() returns is short and undecodedPreBncCells says by how much.
Returns
boolean
headerColumnCount
Get Signature
get headerColumnCount():
number
Defined in: src/tst/tables.ts:685
Returns
number
headerColumnsFrozen
Get Signature
get headerColumnsFrozen():
boolean
Defined in: src/tst/tables.ts:2559
Returns
boolean
headerRowCount
Get Signature
get headerRowCount():
number
Defined in: src/tst/tables.ts:681
Returns
number
headerRowsFrozen
Get Signature
get headerRowsFrozen():
boolean
Defined in: src/tst/tables.ts:2555
Header rows stay visible while the table scrolls (Numbers).
Returns
boolean
name
Get Signature
get name():
string|undefined
Defined in: src/tst/tables.ts:645
Returns
string | undefined
Set Signature
set name(
value):void
Defined in: src/tst/tables.ts:649
Parameters
value
string
Returns
void
nameVisible
Get Signature
get nameVisible():
boolean
Defined in: src/tst/tables.ts:665
Whether the app draws the table's name above it.
table_name_enabled — true on 29 corpus tables, absent on 23; a renamed table with the flag unset keeps its new name in the file and shows nothing, which reads as the rename having failed.
Returns
boolean
Set Signature
set nameVisible(
value):void
Defined in: src/tst/tables.ts:669
Parameters
value
boolean
Returns
void
repeatingHeaderColumns
Get Signature
get repeatingHeaderColumns():
boolean
Defined in: src/tst/tables.ts:2568
Returns
boolean
repeatingHeaderRows
Get Signature
get repeatingHeaderRows():
boolean
Defined in: src/tst/tables.ts:2564
Header rows repeat at the top of each page/slide the table spans.
Returns
boolean
rowCount
Get Signature
get rowCount():
number
Defined in: src/tst/tables.ts:673
Returns
number
storageGeneration
Get Signature
get storageGeneration():
"empty"|"v5"|"preBNC"
Defined in: src/tst/tables.ts:1387
Cell-storage generation used by this table:
- "v5" "BNC" storage — readable. Observed in files as early as the 2018-era apps (format 3.2.13), not only Numbers 10+.
- "preBNC" storage versions 3/4 written by iWork '13/'15-era apps — NOT readable (undocumented layout; the reference Python implementation refuses these too)
- "empty" no tile rows at all
Returns
"empty" | "v5" | "preBNC"
Methods
activeCategories()
activeCategories():
TableCategories|undefined
Defined in: src/tst/tables.ts:4179
The category definition the app is currently applying, if any.
Returns
TableCategories | undefined
audit()
audit():
AuditFinding[]
Defined in: src/tst/tables.ts:1070
The faults a person finds only by opening the document, checked offline: each entry names a state some review round has already watched an app reject, ignore, or render wrong. An error is a state Numbers refuses or repairs destructively; a warning is one it opens but renders against the author's evident intent.
Returns
bandStyle()
bandStyle(
band):TableStyleHandle|undefined
Defined in: src/tst/tables.ts:3105
Cell formatting of a named band — fill, borders, padding, alignment.
A band has two styles, not one: this covers the cell (background and borders); bandTextStyle covers the text inside it. Making a header row bold means editing the text style, not this one.
Parameters
band
Returns
TableStyleHandle | undefined
bandTextStyle()
bandTextStyle(
band):StyleHandle|undefined
Defined in: src/tst/tables.ts:3116
Character formatting of a named band's text.
A TSWP.CharacterStyleArchive, so it takes the same CharacterFormatting as any other text in the suite.
Parameters
band
Returns
StyleHandle | undefined
categories()
categories():
TableCategories[]
Defined in: src/tst/tables.ts:4174
The table's category (row grouping) definitions.
More than one can exist — Numbers keeps a definition around when grouping is switched off — so enabled says which is live.
Returns
cellBorders()
cellBorders(
row,column):CellBorders
Defined in: src/tst/tables.ts:3342
A cell's borders as the sidecar states them — the mechanism the app actually draws. The style bag's per-side strokes (older files, and this library's own pre-sidecar output) are the fallback.
Parameters
row
number
column
number
Returns
cellComment()
cellComment(
row,column):CellComment|undefined
Defined in: src/tst/tables.ts:796
The comment on one cell, if the app left one there.
Parameters
row
number
column
number
Returns
CellComment | undefined
Agent Tool
list_comments
cellComments()
cellComments():
CellComment[]
Defined in: src/tst/tables.ts:776
Every comment on this table's cells, in row-major order.
Comments are the app's own annotation channel and the review loop's reply channel: a returned file carries its findings here, so a reading that skips them reads a clean file where the verdict sits. The library reads and preserves them — writing one is the app's job.
Returns
Agent Tool
list_comments
cellControl()
cellControl(
row,column):CellControl|undefined
Defined in: src/tst/tables.ts:3863
The control on one cell, if it has one.
Parameters
row
number
column
number
Returns
CellControl | undefined
cellFormat()
cellFormat(
row,column):CellFormat|undefined
Defined in: src/tst/tables.ts:887
How a cell's value is displayed, or undefined when it has no explicit format and the app falls back to its automatic rendering.
Parameters
row
number
column
number
Returns
CellFormat | undefined
cellFormatting()
cellFormatting(
row,column):CellFormatting
Defined in: src/tst/tables.ts:3130
Read the formatting in effect for a cell, or {} when it has none.
Parameters
row
number
column
number
Returns
cellFormula()
cellFormula(
row,column):string|undefined
Defined in: src/tst/tables.ts:1225
The formula in a cell, as text, or undefined when it holds a literal.
Rendered from the cell's position because references are stored as offsets from the cell using them — one formula entry is shared by every cell in a filled-down column, and each renders differently.
Function names come from a registry the format does not contain (see formulas.ts); an unrecognised one renders as FUNCTION_<id> rather than a guess. Use cellFormulaDetail to see what was unnamed.
Parameters
row
number
column
number
Returns
string | undefined
cellFormulaDetail()
cellFormulaDetail(
row,column):RenderedFormula|undefined
Defined in: src/tst/tables.ts:1230
cellFormula plus the ids and node types it could not name.
Parameters
row
number
column
number
Returns
RenderedFormula | undefined
cells()
cells():
CellInfo[]
Defined in: src/tst/tables.ts:1432
All non-empty cells in reading order.
Reads pre-BNC (storage version 4) tables too, for the record shapes that have been measured — see ./prebnc.ts. A cell whose shape is unmeasured is omitted, and undecodedPreBncCells counts them, so "this table read clean" and "this table half-read" stay distinguishable.
Returns
CellInfo[]
cellStyle()
cellStyle(
row,column):TableStyleHandle|undefined
Defined in: src/tst/tables.ts:3122
The cell style applied to one cell, if it has an explicit one.
Parameters
row
number
column
number
Returns
TableStyleHandle | undefined
cellStyleId()
cellStyleId(
row,column):number|undefined
Defined in: src/tst/tables.ts:4224
cell_style_id of a cell, if its record carries one.
Parameters
row
number
column
number
Returns
number | undefined
cellText()
cellText(
row,column):string
Defined in: src/tst/tables.ts:1571
Convenience: cell text/number as a display string ("" for empty).
Parameters
row
number
column
number
Returns
string
cellValue()
cellValue(
row,column):CellValue|undefined
Defined in: src/tst/tables.ts:1563
One cell's typed value, or undefined when the cell is empty.
undefined also covers a pre-BNC cell whose record shape has not been measured — see undecodedPreBncCells, which is how the two are told apart.
Parameters
row
number
column
number
Returns
CellValue | undefined
clearAllCells()
clearAllCells():
void
Defined in: src/tst/tables.ts:2502
Clear every cell, keeping the table's shape, styling and bands.
A blank table laid out like the one it was copied from, which is what "add a table" usually means — as opposed to a duplicate of the data. Covered cells are cleared too: leaving them would strand values inside a merge whose anchor is now empty.
Returns
void
clearCell()
clearCell(
row,column):void
Defined in: src/tst/tables.ts:1639
Clear a cell's value, keeping its styling.
Parameters
row
number
column
number
Returns
void
clearConditionalStyles()
clearConditionalStyles():
void
Defined in: src/tst/tables.ts:3562
Remove every conditional-formatting rule from the table: the keys on cell records, the ledger records behind them, and the rule sets they name.
The content-less clone path calls this. A clone keeps its donor's cell records, and clearing a cell's value deliberately keeps its rule — the same edit in the app does — so the donor's rules arrive keyed into copied rule sets the clone's fresh engine owner has no ledger records for: the inspector shows them, nothing ever evaluates them.
Returns
void
clearFormula()
clearFormula(
row,column):boolean
Defined in: src/tst/tables.ts:1759
Remove a cell's formula, keeping the value it last cached.
Returns false when the cell had none. This is what "convert to value" does in the app: the number stays, the recipe goes.
Parameters
row
number
column
number
Returns
boolean
clearStoredHiddenStates()
clearStoredHiddenStates():
void
Defined in: src/tst/tables.ts:3825
Drop the table's stored hidden row/column states.
For a fresh copy only: a copy inheriting its donor's state list — entries naming the donor's rows — made Numbers open the document filtered against its own flags and killed the filter toggle after one use. A copy starts as a filter that never ran: no states. On a table whose filter has run, the list stays — it is the machinery a later enable engages, and the app never rebuilds a missing one from a panel toggle.
Returns
void
columnWidth()
columnWidth(
column):number
Defined in: src/tst/tables.ts:2620
Parameters
column
number
Returns
number
conditionalRuleId()
conditionalRuleId(
row,column):number|undefined
Defined in: src/tst/tables.ts:3606
The second conditional id a cell record carries, meaning unconfirmed.
Sits in the COND_RULE_STYLE_ID slot, which by position corresponds to CellArchive.conditional_style_applied_rule — the rule that last matched. The corpus does not bear that out: in the one fixture with real rules, every cell sharing a one-rule set carries the same value (15) regardless of content, and cells on other sets carry 0, which is not a valid key in any of the table's lists. So it is exposed raw and preserved byte-for-byte rather than interpreted. See docs/VERIFICATION.md.
Parameters
row
number
column
number
Returns
number | undefined
conditionalRules()
conditionalRules(
row,column):ConditionalRule[]
Defined in: src/tst/tables.ts:3624
The conditional-formatting rules on a cell, in evaluation order.
Conditions render against the cell asked about, so a rule on B4 reads B4<0. Nothing here evaluates them: deciding which rule matches means running the calc engine over the document, and a wrong answer would be indistinguishable from a right one.
Parameters
row
number
column
number
Returns
conditionalStyleKey()
conditionalStyleKey(
row,column):number|undefined
Defined in: src/tst/tables.ts:3546
Key into conditionalStyleSets carried by a cell's record.
Parameters
row
number
column
number
Returns
number | undefined
conditionalStyleSet()
conditionalStyleSet(
row,column):ConditionalStyleSet|undefined
Defined in: src/tst/tables.ts:3611
The rule set governing one cell, if it has one.
Parameters
row
number
column
number
Returns
ConditionalStyleSet | undefined
conditionalStyleSets()
conditionalStyleSets():
Map<number,ConditionalStyleSet>
Defined in: src/tst/tables.ts:3410
Every conditional-formatting rule set the table interns, by key.
Rule sets are shared: one entry covers every cell it was applied to, and its refcount is that cell count. So this returns a handful of sets even for a table where hundreds of cells are conditionally formatted.
Returns
Map<number, ConditionalStyleSet>
controlKey()
controlKey(
row,column):number|undefined
Defined in: src/tst/tables.ts:3858
Key into controls carried by a cell's record, if it has one.
Parameters
row
number
column
number
Returns
number | undefined
controls()
controls():
Map<number,CellControl>
Defined in: src/tst/tables.ts:3853
Data-entry controls (checkbox, slider, stepper, pop-up menu) the table interns, by key. A cell's record points at one through CONTROL_ID.
Empty for every corpus document — see src/tst/controls.ts.
Returns
Map<number, CellControl>
deleteColumns()
deleteColumns(
at,count?):void
Defined in: src/tst/tables.ts:2821
Delete columns starting at at.
Parameters
at
number
count?
number = 1
Returns
void
Agent Tool
modify_table
deleteRows()
deleteRows(
at,count?):void
Defined in: src/tst/tables.ts:2766
Delete rows starting at at.
Parameters
at
number
count?
number = 1
Returns
void
Agent Tool
modify_table
filterRules()
filterRules(
set):FilterRule[]
Defined in: src/tst/tables.ts:3843
A filter set's rules with this table's owner registry supplied, so a rule reaching into another table names it instead of rendering OTHER_TABLE::.
FilterSet.rules takes the registry as an argument rather than finding it itself: a FilterSet is constructible from any object and has no table to ask.
Parameters
set
FilterSet | undefined
Returns
filterSets()
filterSets():
object
Defined in: src/tst/tables.ts:3798
The table's row and column filter sets.
Reached through hidden_states_owner, because a filter set belongs to a hidden-state extent rather than to the table directly — the extent records which rows ended up hidden, the filter set records why. Tables written before that structure existed have neither.
Returns
object
columns
columns:
FilterSet|undefined
rows
rows:
FilterSet|undefined
formatTable()
formatTable(
formatting):void
Defined in: src/tst/tables.ts:972
Apply table-level formatting — the setter tableStyle().setTable reaches, surfaced here because a method named formatTable that silently does nothing was a reported trap.
Parameters
formatting
Returns
void
formulaArchiveAt()
formulaArchiveAt(
row,column):RawMessage|undefined
Defined in: src/tst/tables.ts:1262
The raw TSCE.FormulaArchive behind a cell, if it has one.
The unrendered truth — what cellFormulaDetail renders, and the yardstick formula writing is measured against: a rebuilt formula is proven by comparing bytes with what Apple stored here.
Parameters
row
number
column
number
Returns
RawMessage | undefined
formulaId()
formulaId(
row,column):number|undefined
Defined in: src/tst/tables.ts:1268
formula_id of a cell, if its record carries one.
Parameters
row
number
column
number
Returns
number | undefined
formulas()
formulas():
object[]
Defined in: src/tst/tables.ts:1302
Every formula cell in the table, with its rendered text.
Walks the row records for a formula id rather than going through cells: a formula the app wrote carries a cached value, but a freshly authored one does not until the app recomputes, and it is a formula either way.
Returns
object[]
Agent Tool
list_formulas
grid()
grid(): (
CellValue|null)[][]
Defined in: src/tst/tables.ts:1543
Dense 2-D array of the table (null = empty cell).
Returns
(CellValue | null)[][]
insertColumns()
insertColumns(
at,count?):void
Defined in: src/tst/tables.ts:2788
Insert blank columns before at.
Parameters
at
number
count?
number = 1
Returns
void
Agent Tool
modify_table
insertRows()
insertRows(
at,count?):void
Defined in: src/tst/tables.ts:2706
Insert blank rows before at.
The whole table's storage is rebuilt rather than patched: tiles, row headers and per-column cell counts all have to agree afterwards, and shifting them independently is how those three drift apart.
Formula references are not adjusted. Relative references survive by construction — they are offsets from the cell using them, so a formula that moves keeps pointing at the same relative neighbour — but an absolute range spanning the insertion point still names its old bounds. Adjusting those correctly is calc-engine work; see docs/FORMAT.md §14.7.
Parameters
at
number
count?
number = 1
Returns
void
Agent Tool
modify_table
isColumnHidden()
isColumnHidden(
column):boolean
Defined in: src/tst/tables.ts:2655
Parameters
column
number
Returns
boolean
isCovered()
isCovered(
row,column):boolean
Defined in: src/tst/tables.ts:1373
True when a cell is swallowed by a merge anchored elsewhere.
Such a cell is not displayed at all: the anchor's content spans it. Writing to it produces a value nobody will ever see.
Parameters
row
number
column
number
Returns
boolean
isRowHidden()
isRowHidden(
row):boolean
Defined in: src/tst/tables.ts:2651
True when the row or column is hidden.
Parameters
row
number
Returns
boolean
mergeAt()
mergeAt(
row,column):MergeRange|undefined
Defined in: src/tst/tables.ts:1357
The merge covering a cell, if any — including the one it anchors.
Parameters
row
number
column
number
Returns
MergeRange | undefined
mergeCells()
mergeCells(
row,column,rowCount,columnCount):void
Defined in: src/tst/tables.ts:2209
Merge a rectangle of cells, anchored at its top-left.
A merge is not a property of the cells. It is a formula owned by the calc engine: TableModelArchive.merge_owner.formula_store holds one colon-tract AST node per merged rectangle, and the covered cells are simply deleted — Apple leaves them with no record at all, which is why cellValue returns undefined for them rather than "empty".
Every table in every document examined already carries a merge_owner with an owner id, merged or not, so nothing here has to mint a calc engine identity. A table that somehow lacks one is refused rather than guessed at: an owner the engine does not know about is worse than no merge, because the document would load and then behave oddly.
The anchor's value survives; everything the rectangle covers is discarded, exactly as merging does in the app.
Parameters
row
number
column
number
rowCount
number
columnCount
number
Returns
void
Agent Tool
merge_cells
merges()
merges():
MergeRange[]
Defined in: src/tst/tables.ts:818
Merged cell ranges, anchored at their top-left cell.
Two encodings exist and the documented one is not the one current apps use. DataStore.merge_region_map holds packed CellRange values, but no document in the corpus — Numbers or Pages, 2013 through 26.x — actually has one. Real merges live in the calc engine, as colon-tract AST nodes inside TableModelArchive.merge_owner.formula_store. A reader that only knows the region map silently reports zero merges for every merged table it will ever meet, so the formula store is read first and the region map kept as a fallback.
Ranges are deduplicated: a table can carry the same rectangle in both encodings, and the same merge more than once in the formula store.
Returns
orphanReferences()
orphanReferences():
object[]
Defined in: src/tst/tables.ts:1035
Records whose string or rich-text reference has no entry in this table's own data list. Empty on every corpus table (0 of 5019 records); anything here reloads as an empty cell, so a save that would persist one is refused (verifyCellStorageIntegrity).
Returns
object[]
regroupCategories()
regroupCategories():
number
Defined in: src/tst/tables.ts:4213
Put rows back in the groups their current values call for.
The fix for what staleCategoryGroups reports. Returns the number of rows that moved — zero when the tree was already correct, in which case the archive is rewritten to the same bytes.
Throws if a row's value has no group: see TableCategories.regroup for why creating one is refused.
Returns
number
removeCellControl()
removeCellControl(
row,column):boolean
Defined in: src/tst/tables.ts:4079
Take the widget off a cell, keeping its value. Returns false if none.
Parameters
row
number
column
number
Returns
boolean
richTextStorage()
richTextStorage(
row,column):IwaObject|undefined
Defined in: src/tst/tables.ts:2532
The TSWP storage backing a rich-text cell, for editing its runs.
Parameters
row
number
column
number
Returns
IwaObject | undefined
rowHeight()
rowHeight(
row):number
Defined in: src/tst/tables.ts:2615
Height of a row in points, falling back to the table default.
Parameters
row
number
Returns
number
setBands()
setBands(
bands):void
Defined in: src/tst/tables.ts:2582
Change how many leading rows/columns are header bands, and how those bands behave.
Bands are presentation only — cell storage is identical either way — so this is a safe edit that does not touch the tiles. Counts are clamped to the table's real size: a header count past the last row would leave the app with no body.
Parameters
bands
footerRows?
number
freezeHeaderColumns?
boolean
freezeHeaderRows?
boolean
Keep header rows on screen while scrolling (Numbers).
headerColumns?
number
headerRows?
number
repeatHeaderColumns?
boolean
repeatHeaderRows?
boolean
Repeat header rows on every page the table spans (Pages/Numbers print).
Returns
void
Agent Tool
set_table_bands
setCell()
setCell(
row,column,input,options?):void
Defined in: src/tst/tables.ts:1592
Write a value into an existing cell.
Presentation the record already carries — cell and text style ids, number formats, comments, conditional styles — is preserved, except that format ids tied to the old value type are dropped when the type changes (a date format on a number cell would render nonsense). Writing a literal also clears any formula on the cell.
Rich text ({ type: "richText" }) cannot be written: the value lives in a separate TSWP storage object. Set plain text instead, or edit the existing rich-text storage through richTextStorage.
Parameters
row
number
column
number
input
options?
WriteOptions = {}
Returns
void
Agent Tool
set_cells
setCellControl()
setCellControl(
row,column,control,options?):number
Defined in: src/tst/tables.ts:3890
Put a data-entry widget on a cell — checkbox, star rating, slider or stepper.
The spec is interned in the table's control table exactly as strings and formats are, and the cell's record points at it through CONTROL_ID. Identical specs are shared: a column of checkboxes is one archive and forty pointers, which is what the app writes.
The value still lives in the cell, and the widget only changes how it is edited. A checkbox therefore needs a boolean in its cell and a slider a number; writing the widget without the value gives a control with nothing to show, so the value is set here when one is supplied.
A pop-up menu additionally needs a chooser_control_popup_model — a separate archive holding the list of choices — which is created here and shared between cells given the same items. That part is built from the vendored schema rather than measured against a real menu, so it is the one widget here nobody has yet seen work; see buildPopupMenuModel. setPopupMenu still attaches a model a caller already has.
Parameters
row
number
column
number
control
{ value?: boolean; widget: "checkbox"; } | { value?: number; widget: "starRating"; } | { increment: number; maximum: number; minimum: number; value?: number; widget: "slider" | "stepper"; } | { items: readonly PopupItem[]; startsWithFirstItem?: boolean; value?: string | number; widget: "popupMenu"; }
Type Literal
{ items: readonly PopupItem[]; startsWithFirstItem?: boolean; value?: string | number; widget: "popupMenu"; }
items
readonly PopupItem[]
startsWithFirstItem?
boolean
Whether the menu starts on its first choice rather than blank.
Measured: with this off, Numbers offers the model's None entry as a selectable row above the real choices. With it on — the default — the menu shows only the items given here.
value?
string | number
widget
"popupMenu"
options?
WriteOptions = {}
Returns
number
setCellFormat()
setCellFormat(
row,column,format):void
Defined in: src/tst/tables.ts:908
Set how a cell's value is displayed.
A cell shows one format, so any format the record already carried is cleared first — leaving a stale currency id beside a new date id would make the display depend on which flag the app happens to read first.
Parameters
row
number
column
number
format
Returns
void
Agent Tool
set_cell_format
setCellFormatting()
setCellFormatting(
row,column,formatting):void
Defined in: src/tst/tables.ts:3142
Style one cell: fill, borders, padding, vertical alignment, wrapping.
A new cell style is created, based on the cell's current one so unspecified properties are inherited rather than lost, registered in the table's style table and referenced from the cell record. Styling a cell therefore never disturbs its neighbours, even when they shared a style.
Parameters
row
number
column
number
formatting
Returns
void
setCells()
setCells(
row,column,values,options?):void
Defined in: src/tst/tables.ts:2519
Write a rectangular block anchored at row,column.
Parameters
row
number
column
number
values
readonly readonly CellInput[][]
options?
WriteOptions = {}
Returns
void
setColumnWidth()
setColumnWidth(
column,points):void
Defined in: src/tst/tables.ts:2644
Set one column's width in points.
Parameters
column
number
points
number
Returns
void
Agent Tool
modify_table
setConditionalRules()
setConditionalRules(
row,column,conditions,span?):number
Defined in: src/tst/tables.ts:3442
Attach a conditional-formatting rule set to a cell, or to a block of them via span.
(row, column) first, like every other cell method — the reader conditionalRules is positional, and taking a range object here made the pair read as two unrelated APIs.
The set is interned in the table's conditional-style table and every cell in the range points at it — which is how the app writes it too: three sets cover 1921 cells in one corpus document, because a rule is authored once and applied to a column.
Only the four comparisons whose predicate_type has been observed can be written. > and >= are predicted to be 7 and 8, and a rule stored under a wrong code is one the condition editor shows as a different condition while the formula says the truth — a disagreement that is very hard to spot. Refused rather than guessed.
Parameters
row
number
column
number
conditions
readonly ConditionalCondition[]
span?
columnCount?
number
rowCount?
number
Returns
number
setConditionalStyleKey()
setConditionalStyleKey(
row,column,key):void
Defined in: src/tst/tables.ts:3638
Apply an existing rule set to another cell.
Only re-points a cell at a set the table already interns — the sets themselves come from the app. That covers the common edit (extend this conditional format to more cells) without asserting a rule layout no fixture demonstrates.
Parameters
row
number
column
number
key
number | undefined
Returns
void
setFormula()
setFormula(
row,column,formula,options?):void
Defined in: src/tst/tables.ts:1672
Write a formula into a cell.
The formula is compiled to a TSCE AST, interned in the table's formula table, and the cell's record points at it — the same three steps the app performs. Relative references are stored as offsets from this cell, so =A1+1 in B2 and in B3 compile to different bytes, exactly as in the app.
Nothing here evaluates. A cell record carries the formula and its cached result, and the apps display the cache until the engine recalculates. value is that cache: supply it and the cell reads correctly before any app has touched the file; omit it and whatever the cell held is kept, which is right when the formula reproduces the value already there and wrong otherwise. There is no third option that does not involve implementing Apple's calc engine.
The dependency tracker is not written — and does not need to be. The calc engine keeps its own per-cell ledger (TSCE.FormulaOwnerDependenciesArchive) that this method leaves alone. Numbers rebuilds it on open rather than trusting it: the e2e recompute probe writes a formula with a deliberately wrong cached value and the app reports the recomputed result on every npm run test:e2e.
Refuses a function it has no index for rather than inventing one — see authorableFunctions() for the 272 it knows.
Parameters
row
number
column
number
formula
string | FormulaExpression
options?
WriteOptions & object = {}
Returns
void
Agent Tool
set_formula
setPopupMenu()
setPopupMenu(
row,column,popupModelId,options?):number
Defined in: src/tst/tables.ts:4058
Point a cell at a pop-up menu model that already exists.
Kept alongside setCellControl, which builds a model from a list of items, for the case where a caller already has one — from another cell, or another document — and wants that exact archive shared rather than a second copy of the same choices.
itemType decides the cell's format, and the default is "string" because text menus are the common case. Passing the wrong one leaves a numeric menu formatted as text; passing none on a numeric menu does the same. This path shipped for a while with no format at all, which is the defect that made every other widget invisible — a spec without a format is a control the app never draws.
Parameters
row
number
column
number
popupModelId
bigint
options?
itemType?
"string" | "number"
startsWithFirstItem?
boolean
Returns
number
setRangeFormat()
setRangeFormat(
row,column,rowCount,columnCount,format):void
Defined in: src/tst/tables.ts:952
Apply one format across a rectangular block.
Parameters
row
number
column
number
rowCount
number
columnCount
number
format
Returns
void
Agent Tool
set_cell_format
setRangeFormatting()
setRangeFormatting(
row,column,rowCount,columnCount,formatting):void
Defined in: src/tst/tables.ts:3388
Apply the same formatting to a rectangular block of cells — fill, borders, padding, alignment, wrap — leaving every cell's value untouched.
Parameters
row
number
column
number
rowCount
number
columnCount
number
formatting
Returns
void
Agent Tool
format_cells
setRow()
setRow(
row,values,options?):void
Defined in: src/tst/tables.ts:2512
Write a whole row left-to-right, padding with empties.
Parameters
row
number
values
readonly CellInput[]
options?
WriteOptions = {}
Returns
void
setRowHeight()
setRowHeight(
row,points):void
Defined in: src/tst/tables.ts:2633
Set an explicit row height; 0 restores the table default.
Parameters
row
number
points
number
Returns
void
Agent Tool
modify_table
staleCategoryGroups()
staleCategoryGroups():
object[]
Defined in: src/tst/tables.ts:4191
Groups whose cached membership no longer matches the cells.
The group tree is what the app worked out last time it grouped the rows; editing cells here does not regroup them. Unlike a table of contents, the staleness is checkable, because the grouping column's values are in the table.
Returns
object[]
tableStyle()
tableStyle():
TableStyleHandle|undefined
Defined in: src/tst/tables.ts:3093
The table's own style (banded rows, grid strokes, visibility toggles).
Editing it affects every table sharing the style — Numbers' stock themes give each table its own, but a document built by duplication may not. styleTable is where per-cell styles live instead.
Returns
TableStyleHandle | undefined
textStyle()
textStyle(
row,column):TableStyleHandle|undefined
Defined in: src/tst/tables.ts:1285
The TSWP.CharacterStyleArchive behind a cell's text, as a handle.
Parameters
row
number
column
number
Returns
TableStyleHandle | undefined
textStyleId()
textStyleId(
row,column):number|undefined
Defined in: src/tst/tables.ts:1280
text_style_id of a cell, if its record carries one — the style-table key, same currency as cellStyleId. textStyle resolves it to a handle.
Parameters
row
number
column
number
Returns
number | undefined
uidMap()
uidMap():
ColumnRowUidMap
Defined in: src/tst/tables.ts:4164
Row and column identities, for the parts of the format that address cells by UID rather than position.
Returns
undecodedPreBncCells()
undecodedPreBncCells():
number
Defined in: src/tst/tables.ts:1524
How many pre-BNC cells this table holds that cells could not decode — zero for a v5 table, and zero for a pre-BNC table that read cleanly.
Exposed because a partial read is the one outcome a caller must be able to detect: cells() returning fewer rows than the file contains is otherwise indistinguishable from a sparse table.
Returns
number
unmergeCells()
unmergeCells(
row,column):boolean
Defined in: src/tst/tables.ts:2381
Remove the merge anchored at a cell, returning false if there is none.
The cells it covered come back empty, which is what the app does: the values they held before merging were discarded at merge time and are not recoverable from the file.
Parameters
row
number
column
number
Returns
boolean
Agent Tool
merge_cells