cupertino-files / NumbersDocument
Class: NumbersDocument
Defined in: src/numbers/document.ts:39
Extends
Properties
container
readonlycontainer:IWorkContainer
Defined in: src/tsa/document.ts:128
Inherited from
format
readonlyformat:FormatInfo
Defined in: src/tsa/document.ts:130
Inherited from
store
readonlystore:ObjectStore
Defined in: src/tsa/document.ts:129
Inherited from
Accessors
app
Get Signature
get app():
IWorkApp
Defined in: src/tsa/document.ts:170
Returns
Inherited from
era
Get Signature
get era():
"iwork13"|"iwork16"|"iwork19"|"modern"|"current"|"future"
Defined in: src/tsa/document.ts:336
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:275
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:419
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:279
Concatenated plain text of all in-document storages (reading order approximation).
Returns
string
Inherited from
audit()
audit():
AuditFinding[]
Defined in: src/tsa/document.ts:242
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
canvasComments()
canvasComments():
CanvasComment[]
Defined in: src/numbers/document.ts:223
The comments pinned to the sheets' canvases, every sheet in tab order; cellComments() on a table reads the ones on cells.
Returns
CanvasComment[]
Agent Tool
list_comments
charts()
charts():
ChartModel[]
Defined in: src/tsa/document.ts:210
Every chart, with its plotted data (see ChartModel).
Returns
Inherited from
compact()
compact():
number
Defined in: src/tsa/document.ts:363
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, and the Data/ files (a removed picture's bytes) that no surviving object names; the count is archives and files together.
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, and ObjectStore.collectData for how a file is known to be live. 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:317
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:331
One-line human summary of compatibility.
Returns
string
Inherited from
IWorkDocument.compatibilitySummary
drawables()
drawables():
DrawableModel[]
Defined in: src/tsa/document.ts:195
Every object that carries drawable geometry (shapes, images, boxes).
Returns
Inherited from
images()
images():
ImageModel[]
Defined in: src/tsa/document.ts:215
Every image, with filter/mask access (see ImageModel).
Returns
Inherited from
moveSheet()
moveSheet(
from,to):void
Defined in: src/numbers/document.ts:348
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:286
Parameters
id
bigint
Returns
IwaObject | undefined
Inherited from
pruneRoots()
protectedpruneRoots():bigint[]
Defined in: src/tsa/document.ts:375
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:318
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:486
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:333
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:394
Returns
Uint8Array
Inherited from
setActiveSheet()
setActiveSheet(
index):void
Defined in: src/numbers/document.ts:378
Re-point the stored sheet selections at a sheet, best-effort.
Numbers ignores tab order when deciding where a document opens, so a document rearranged with moveSheet still opens on whatever sheet was active at the last save. Every TN.SheetSelectionArchive in the UI state names a sheet through a reference, and this re-points all of them at the given sheet. That has proved necessary but not sufficient: a document with every selection re-pointed has opened on the chosen sheet in one review round and elsewhere in another, so the state that decides it is still unmeasured.
Parameters
index
number
Returns
void
Agent Tool
manage_sheets
sheetContainer()
sheetContainer(
sheetId):DrawableContainer
Defined in: src/numbers/document.ts:254
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:208
The document's sheets (id + name), in tab order.
Returns
stats()
stats():
DocumentStats
Defined in: src/tsa/document.ts:294
Returns
Inherited from
stylesheets()
stylesheets():
StylesheetModel[]
Defined in: src/tsa/document.ts:186
All stylesheets (document + theme).
Returns
Inherited from
tables()
tables(
sheetId?):TableModel[]
Defined in: src/numbers/document.ts:182
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:393
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:175
Every text storage in the document (bodies, headers, cells, notes …).
Parameters
kind?
number
Returns
Inherited from
toMarkdown()
toMarkdown(
_options?):string
Defined in: src/numbers/document.ts:232
The document as Markdown: a top-level heading per sheet, each table under its name (when it shows one) as a pipe table and each chart as a table of its series, in the sheet's own order.
Parameters
_options?
MarkdownOptions = {}
Returns
string
Overrides
typeNameOf()
typeNameOf(
obj):string|undefined
Defined in: src/tsa/document.ts:290
Parameters
obj
Returns
string | undefined
Inherited from
blank()
staticblank():NumbersDocument
Defined in: src/numbers/document.ts:170
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:75
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
fromCsv()
staticfromCsv(csv,name?,options?):NumbersDocument
Defined in: src/numbers/document.ts:151
A new document holding one table written from CSV (RFC 4180): the first row is the header row, numbers and TRUE/FALSE become such.
Parameters
csv
string
name?
string
options?
template?
Uint8Array<ArrayBufferLike>
Returns
NumbersDocument
fromMarkdown()
staticfromMarkdown(markdown,options?):NumbersDocument
Defined in: src/numbers/document.ts:116
A new document written from Markdown: a top-level heading names a sheet (the first renames the blank document's own; each later one adds a sheet), and each pipe table becomes a table on the current sheet, sized to its rows and named by the nearest lower heading above it (or "Table N"); the first table on a sheet fills the sheet's own. Text outside tables has no home in Numbers and is dropped. With template, the document is that one emptied (blankFrom).
Parameters
markdown
string
options?
template?
Uint8Array<ArrayBufferLike>
Returns
NumbersDocument
load()
staticload(bytes):NumbersDocument
Defined in: src/numbers/document.ts:47
Parameters
bytes
Uint8Array
Returns
NumbersDocument
loadStore()
protectedstaticloadStore(bytes,app,extractors):object
Defined in: src/tsa/document.ts:155
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:142
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