Tables

Witan supports Excel ListObject tables as normal workbook table parts. Use table APIs when you want structured references, table styling, totals rows, calculated columns, filters, and an editable Excel table saved in the workbook.

ListObject tables are separate from What-If Data Tables and chart data tables.

Table Model

getListObject returns the workbook table metadata:

witan xlsx exec model.xlsx --expr 'await xlsx.getListObject(wb, "SalesTable")'

The returned model includes the table name, sheet, ref, header/data/totals ranges, table style flags, auto-filter visibility, and column definitions. Columns can include:

• totalsRowFunction
• totalsRowLabel
• totalsRowFormula
• calculatedColumnFormula

Supported totals-row functions are sum, min, max, average, count, countNums, stdDev, var, and custom.

Add A Table

Use addListObject to create a table and optionally populate rows in the same operation:

witan xlsx exec model.xlsx --save --stdin <<'WITAN'
const result = await xlsx.addListObject(wb, "Sheet1", {
  name: "SalesTable",
  ref: "A1:C4",
  showTotalsRow: true,
  showAutoFilter: true,
  tableStyleName: "TableStyleMedium2",
  columns: [
    { name: "Region", totalsRowLabel: "Total" },
    { name: "Sales", totalsRowFunction: "sum" },
    { name: "DoubleSales", calculatedColumnFormula: "=B2*2" }
  ],
  rows: [
    [{ value: "North" }, { value: 10 }, {}],
    [{ value: "South" }, { value: 20 }, {}]
  ]
})

return {
  table: result.listObject,
  touched: result.touched,
  errors: result.errors
}
WITAN

The mutation result includes the created table, recalculated touched cells, changed addresses, formula errors, invalidated render tiles, and updated sheet metadata.

Update A Table

Use setListObject to update table range, columns, styling flags, and rows:

await xlsx.setListObject(wb, "SalesTable", {
  ref: "A1:D6",
  showTotalsRow: true,
  showFirstColumn: true,
  columns: [
    { name: "Region", totalsRowLabel: "Total" },
    { name: "Sales", totalsRowFunction: "sum" },
    { name: "Units", totalsRowFunction: "sum" },
    { name: "Average", calculatedColumnFormula: "=B2/C2" }
  ]
})

setListObject updates the existing table. It does not rename a table; create a new table name with addListObject when a rename is required.

Table updates can resize the table, toggle the header row, totals row, and auto-filter visibility, change table style flags, update totals-row metadata, and apply calculated-column formulas. When rows are provided, Witan writes table data and table formulas as part of the same workbook mutation.

Delete A Table

Delete a table by name:

await xlsx.deleteListObject(wb, "SalesTable")

Deleting a ListObject removes the table object and preserves the worksheet cells. Formulas that reference the table are recalculated where affected.

Structured References

Witan Calc resolves Excel structured references such as SalesTable[Sales] and recalculates formulas that depend on them. Table edits that change the range or calculated-column formulas update the dependency graph before later recalculation.

For label-based lookup across detected sheet regions, use Search and Discovery. That page covers describeSheet and tableLookup.

See xlsx API for exact table signatures.