Architecture guide · src/v12

How the table tree is assembled

v12 separates table values, reusable tag templates, and the outer table scaffold. The builder combines them into inspectable JSON. A renderer is a later, separate step.

Datacolumns and row records
Templatesreusable tag descriptions
Builderclone, fill, place
JSON treeinspectable output
Rendereroptional DOM step

Public table-building path

The package entry src/index.js re-exports src/v12/index.js. Its main function is tableFromData (also exported as buildTable).

  1. It takes inData, optional inSpec, and optional inTable. Missing specification and scaffold values use exported defaults.
  2. collectionFromKey maps column contexts through the header template.
  3. collectionFromInternal maps records to rows. It uses Object.values(row), passes each value as { rowValue }, and fills the row template's children with generated cells.
  4. tableFromData clones the scaffold, finds direct thead and tbody children, assigns generated headers to the first header row, and replaces the body's children with generated rows.

This implementation populates the header and body insertion points. A scaffold may contain other elements, but this function does not populate a colgroup or tfoot.

Template application

applyTemplate clones a template with structuredClone. It walks supported content: string values, textContent, attribute values, and child nodes. commonReplace substitutes every ${name} token matching \w+ in a string. A missing property leaves its token unchanged.

Template application produces JSON objects; it does not call DOM APIs. The consumer chooses whether to inspect the JSON or pass it to a renderer.

Sample instruction path

The samples also explore a configurable composition pattern. An instruction connects a data key, a template key, a registered helper, and a destination path in a cloned table scaffold:

{
  "sourceKey": "columns",
  "templateKey": "buildHeader",
  "func": "collectionFromKey",
  "destinationPath": ["children", 1, "children", 0, "children"]
}

The sample JavaScript resolves the source and template, dispatches through its local function registry, then writes the result at destinationPath. This instruction loop is sample-level orchestration; it is not the implementation of the public tableFromData API.

Each case owns its instruction list and helper registry. The shared fields express the relationship between data, template, operation, and scaffold location; the chosen path must match the scaffold's nested arrays. The public table builder uses its own fixed header/body path.

For example, the browser integration uses html/buildSpec/index.js with its instruction file to fill header and footer positions. Its scaffold also contains colgroup and body positions, but this builder's current instruction list does not fill them.

Four v12 sample cases

These are four top-level explorations under samples/tableTypes/v12. The nested html/buildSpec folder is part of the browser integration case.

CaseWhat it exploresCurrent behavior in the files
columnsReusing column data for colgroup, heading, and footer templates.The colgroup destination is indexed correctly. Header and footer destination paths omit the row index, so those generated lists do not populate the scaffold's cell arrays as intended. Evidence: instructions, templates, scaffold.
rowsMapping each data record to repeated body rows with collectionFromKey.The selected buildBody template is only a tr with attributes; it has no cell children. This case produces empty rows. Evidence: instructions, templates.
rows_goodComposing colgroup, header, body, and footer through a full set of instructions.The spec defines buildBody1 with outer and inner templates, but the body instruction selects buildBody, the bare row. It therefore produces empty rows and leaves buildBody1 unused. Although the runner registers collectionFromInternal, no instruction selects it. Evidence: instructions, templates.
htmlConnecting a JSON table description to browser rendering.The nested builder fills header and footer from instructions. The page passes the JSON tree to window.ks.jsonToTag.buildSpecElement. That builder does not fill colgroup or body. Evidence: instructions, scaffold, page.

These descriptions reflect the current sample files, including incomplete paths and unused templates; folder names do not imply that every case is a finished output.

Implementation boundaries