cupertino-files / NumbersDocument
Class: NumbersDocument
Defined in: src/numbers/document.ts:34
Extends
Properties
container
readonlycontainer:IWorkContainer
Defined in: src/tsa/document.ts:125
Inherited from
format
readonlyformat:FormatInfo
Defined in: src/tsa/document.ts:127
Inherited from
store
readonlystore:ObjectStore
Defined in: src/tsa/document.ts:126
Inherited from
Accessors
app
Get Signature
get app():
IWorkApp
Defined in: src/tsa/document.ts:167
Returns
Inherited from
era
Get Signature
get era():
"iwork13"|"iwork16"|"iwork19"|"modern"|"current"|"future"
Defined in: src/tsa/document.ts:316
Format era this document was written by (see tsp/version.ts).
Returns
"iwork13" | "iwork16" | "iwork19" | "modern" | "current" | "future"
Inherited from
Methods
addSheet()
addSheet(
options?):SheetInfo
Defined in: src/numbers/document.ts:189
Add a sheet by copying an existing one.
A sheet is a container for drawables, and a Numbers document with an empty one is perfectly valid — but the tables on a sheet are what make it useful, and building a table from nothing means synthesising tiles, header buckets, data lists and a calc-engine owner. Copying is both simpler and closer to what Numbers does when you duplicate a tab.
By default the copy keeps its tables (a duplicate); pass withContent: false for an empty sheet.
Parameters
options?
at?
number
copyOf?
number
name?
string
withContent?
boolean
Returns
Agent Tool
manage_sheets
addTable()
addTable(
sheetId,options?):TableModel
Defined in: src/numbers/document.ts:331
Add a table to a sheet.
Building a table from nothing means synthesising tiles, header buckets, data lists and a calc-engine owner — the same reason sheets and slides are created by copying. Without copyOf, the source is the embedded Apple-made blank table (the same donor blank() documents are born with): the new table arrives empty and neutrally styled, inheriting nobody's widths, fills or wrap styles. Pass copyOf to duplicate a table already in the document instead.
The copy is renamed, because Numbers addresses tables by name: two tables called "Table 1" on one sheet make every cross-table formula ambiguous. Names must be unique per sheet, not per document, so a copy onto a different sheet can keep the original's name.
withContent: false clears a copyOf duplicate's cells but keeps the shape, styling and header bands. Either way, what the new table keeps is the caller's decision: row and column count and widths arrive at the donor's shape and rarely fit the new table as they are.
Parameters
sheetId
bigint
options?
copyOf?
bigint
name?
string
withContent?
boolean
x?
number
y?
number
Returns
Agent Tool
manage_sheets
allText()
allText():
string
Defined in: src/tsa/document.ts:259
Concatenated plain text of all in-document storages (reading order approximation).
Returns
string
Inherited from
audit()
audit():
AuditFinding[]
Defined in: src/tsa/document.ts:239
Every fault this library knows how to recognise offline, across the whole document — the checks a person otherwise performs by opening the file in an app. Each finding names a state some review round has already watched an app refuse, repair destructively, or render against the author's intent. save() refuses the error classes it can see; audit() reports them without saving, warnings included, so a builder can ask "what would a person object to?" before shipping a document.
Returns
Agent Tool
audit_document
Inherited from
charts()
charts():
ChartModel[]
Defined in: src/tsa/document.ts:207
Every chart, with its plotted data (see ChartModel).
Returns
Inherited from
compact()
compact():
number
Defined in: src/tsa/document.ts:341
Drop archives nothing can reach, returning how many went.
What this collects today is very little, and that is worth knowing before reaching for it. Removing a sheet or a table unlinks it from the document tree, but the calc engine keeps its own references to every table it ever knew, so those archives stay genuinely reachable. The gap is in removal — unregistering a table's formula owners is calc-engine surgery this library does not do yet — not in the walk. What compaction does reclaim is objects created and then abandoned.
Roots are the package metadata, each component's first object, and every selection archive; see ObjectStore.prune for the scan and for why it errs towards keeping things. It is a no-op on every untouched document in the corpus, which is the property that matters: a collector that trims a file nobody edited is broken.
Returns
number
Inherited from
compatibility()
compatibility():
CompatibilityReport
Defined in: src/tsa/document.ts:297
What this library can and cannot do with THIS document: declared versions, the era they place it in, structural probes (unknown type IDs, cell-storage generation, patch archives, collaboration state) and any unsupported features. Loading never fails on version grounds — this is how a caller finds out what to expect.
Returns
Inherited from
compatibilitySummary()
compatibilitySummary():
string
Defined in: src/tsa/document.ts:311
One-line human summary of compatibility.
Returns
string
Inherited from
IWorkDocument.compatibilitySummary
drawables()
drawables():
DrawableModel[]
Defined in: src/tsa/document.ts:192
Every object that carries drawable geometry (shapes, images, boxes).
Returns
Inherited from
images()
images():
ImageModel[]
Defined in: src/tsa/document.ts:212
Every image, with filter/mask access (see ImageModel).
Returns
Inherited from
moveSheet()
moveSheet(
from,to):void
Defined in: src/numbers/document.ts:262
Move a sheet to a new position in tab order.
Parameters
from
number
to
number
Returns
void
Agent Tool
manage_sheets
object()
object(
id):IwaObject|undefined
Defined in: src/tsa/document.ts:266
Parameters
id
bigint
Returns
IwaObject | undefined
Inherited from
pruneRoots()
protectedpruneRoots():bigint[]
Defined in: src/tsa/document.ts:353
Objects that must survive compact.
The package metadata anchors the component and data tables, and each component's first object anchors that component — a component whose objects all vanished would still be listed in the metadata, which is a worse state than a few extra archives.
Returns
bigint[]
Inherited from
removeSheet()
removeSheet(
index):void
Defined in: src/numbers/document.ts:232
Remove a sheet from the document's tab order.
Parameters
index
number
Returns
void
Agent Tool
manage_sheets
removeTable()
removeTable(
sheetId,tableInfoId):boolean
Defined in: src/numbers/document.ts:407
Take a table off its sheet.
The archives stay in the package, as everywhere else here; what removes the table is the sheet no longer listing it.
Parameters
sheetId
bigint
tableInfoId
bigint
Returns
boolean
renameSheet()
renameSheet(
index,name):void
Defined in: src/numbers/document.ts:247
Rename a sheet. Names must be unique, as they are in the app.
Parameters
index
number
name
string
Returns
void
Agent Tool
manage_sheets
save()
save():
Uint8Array
Defined in: src/tsa/document.ts:372
Returns
Uint8Array
Inherited from
setActiveSheet()
setActiveSheet(
index):void
Defined in: src/numbers/document.ts:290
Make a sheet the one the document opens on.
Numbers remembers the selected tab in its UI state — every TN.SheetSelectionArchive names a sheet through a reference — and ignores tab order when deciding where to open, so a document rearranged with moveSheet still opens on whatever sheet was active at the last save. This re-points every stored sheet selection at the given sheet.
Parameters
index
number
Returns
void
Agent Tool
manage_sheets
sheetContainer()
sheetContainer(
sheetId):DrawableContainer
Defined in: src/numbers/document.ts:168
A sheet's drawable list — tables, charts, shapes and images alike.
Numbers keeps one list with no separate z-order, so paint order is the list order.
Parameters
sheetId
bigint
Returns
sheets()
sheets():
SheetInfo[]
Defined in: src/numbers/document.ts:151
The document's sheets (id + name), in tab order.
Returns
stats()
stats():
DocumentStats
Defined in: src/tsa/document.ts:274
Returns
Inherited from
stylesheets()
stylesheets():
StylesheetModel[]
Defined in: src/tsa/document.ts:183
All stylesheets (document + theme).
Returns
Inherited from
tables()
tables(
sheetId?):TableModel[]
Defined in: src/numbers/document.ts:125
Tables of one sheet, or of the whole document when no sheet is given.
Document order either way: sheets in tab order, each sheet's tables in its drawable order — so tables()[0] is the first sheet's first table whatever was added this session. Tables no sheet lists (an unattached clone mid-construction) come last, in storage order.
Parameters
sheetId?
bigint
Returns
Overrides
tablesOnSheet()
tablesOnSheet(
sheetId):TableModel[]
Defined in: src/numbers/document.ts:305
The tables on one sheet, in the order the sheet lists them.
Parameters
sheetId
bigint
Returns
textStorages()
textStorages(
kind?):TextStorage[]
Defined in: src/tsa/document.ts:172
Every text storage in the document (bodies, headers, cells, notes …).
Parameters
kind?
number
Returns
Inherited from
typeNameOf()
typeNameOf(
obj):string|undefined
Defined in: src/tsa/document.ts:270
Parameters
obj
Returns
string | undefined
Inherited from
blank()
staticblank():NumbersDocument
Defined in: src/numbers/document.ts:113
A new, empty Numbers spreadsheet — one sheet, one table, A4 paper, no template file needed.
The embedded donor is an Apple-written corpus fixture (already iso-a4) emptied by blankFrom, so every style and identity in the "new" document was authored by an Apple app. scripts/make-blanks.ts records its provenance.
Returns
NumbersDocument
Agent Tool
create_document
blankFrom()
staticblankFrom(template,options?):NumbersDocument
Defined in: src/numbers/document.ts:70
A new, empty spreadsheet built from a document you supply.
There is no from-nothing constructor, and there will not be one. A Numbers document is dozens of interlinked archives — theme, stylesheet, calc-engine owners, table styles — and inventing that graph would produce a file nothing offline could validate. What is safe is emptying a real one: every identity, style and reference stays exactly as an Apple app wrote it, and only the content goes.
The result keeps one sheet holding one blank table, laid out like the template's first. Everything else — extra sheets, extra tables, their data — is removed.
Reach for a document you own or one the user hands you; any .numbers will do, including an empty one saved from Numbers.
Parameters
template
Uint8Array
options?
sheetName?
string
tableName?
string
Returns
NumbersDocument
load()
staticload(bytes):NumbersDocument
Defined in: src/numbers/document.ts:42
Parameters
bytes
Uint8Array
Returns
NumbersDocument
loadStore()
protectedstaticloadStore(bytes,app,extractors):object
Defined in: src/tsa/document.ts:152
Parameters
bytes
Uint8Array
app
extractors
ReadonlyMap<number, ReferenceExtractor>
Returns
object
container
container:
IWorkContainer
store
store:
ObjectStore
Inherited from
open()
staticopen(bytes):IWorkDocument
Defined in: src/tsa/document.ts:139
Load any modern iWork document, auto-detecting the app. Prefer the app subclasses' load when the type is known — they expose richer APIs.
Parameters
bytes
Uint8Array