Zova Table Source Reading Map

This page is a practical map for contributors and AI workflows that need to read Zova Table source code efficiently.

Use this page after Zova Table Under the Hood when your next question is not the runtime model itself, but which files to read first for a specific table-internals topic.

It answers a narrow question:

when I need to understand how Zova Table works internally, which files should I read first, and in what order?

Use this page together with:

• Table Guide
• TableCell Authoring Cookbook
• Table + Resource CRUD Cookbook
• Zova Table Under the Hood
• Zova Table Controller Render Deep Dive
• Rest Resource Under the Hood
• Rest Resource Source Reading Map
• Zova Source Reading Map
• Bean Scene Authoring
• API Schema Guide
• Model Resource Owner Pattern

TIP

Zova Table docs path

1. Table Guide — learn the public authoring surface
2. Zova Table Under the Hood — learn how the runtime pieces cooperate
3. Zova Table Source Reading Map — learn which files to read next

You are here: step 3. Previous page: Zova Table Under the Hood.

Why this page exists

The a-table module sits at the intersection of several Zova concerns at once:

• controller-oriented component design
• schema-driven column metadata
• TanStack Table integration
• bean-scene-based cell rendering
• resource-page integration through basic-page

This page exists for one narrow job:

• Table Guide explains how to author tables
• Zova Table Under the Hood explains how the runtime pieces cooperate
• this page gives the shortest file-order paths for specific table questions

How to use this page

For each topic below:

1. start with the public guide to refresh the architectural intent
2. read the first source file to identify the public surface
3. continue into the next runtime file only if you still need the implementation detail
4. stop as soon as you have enough information for the task

The goal is not to read the entire table stack every time. The goal is to choose the shortest correct path.

1. Public table surface and wrapper entrypoints

Use this path when you are asking questions like:

• what is the public Zova Table surface?
• where does ZTable enter the runtime?
• how does controllerRef reach the controller instance?

Read the docs first

• Table Guide
• Component Guide
• Reading Zova for Vue Developers

Then read source in this order

1. zova/src/suite-vendor/a-zova/modules/a-table/src/.metadata/component/table.ts
2. zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
3. zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx
4. zova/packages-zova/zova-core/src/composables/useController.ts

What each file clarifies

• metadata wrapper files show how the public component wrapper enters useController(...)
• table.ts exposes ZTable and its typed controller-facing props surface
• controller.tsx shows the table runtime owner
• render.tsx shows the default DOM render path
• useController.ts shows how the controller instance is created and bound to the wrapper lifecycle

2. Table controller ownership and TanStack bridge

Use this path when you are asking questions like:

• where is the TanStack table instance created?
• where do columns and tableMeta come from?
• why does the table runtime live in a controller bean?

Read the docs first

• Table Guide
• Reading Zova for Vue Developers

Then read source in this order

1. zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
2. zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.ts
3. zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerPageTableBase.ts
4. zova/src/suite-vendor/a-zova/modules/a-table/src/types/table.ts

What each file clarifies

• component/table/controller.tsx is the main table runtime owner
• beanControllerTableBase.ts shows the shared $useTable(...) wrapper around TanStack useVueTable(...)
• beanControllerPageTableBase.ts shows the page-controller-oriented variant
• types/table.ts shows the exposed type contracts for table, columns, metadata, and getColumns(...)

3. Schema-driven columns and metadata overlays

Use this path when you are asking questions like:

• how does a row schema become visible columns?
• where do visible, order, render, and columnProps come from?
• how does the table scene differ from form or filter scenes?

Read the docs first

• Table Guide
• API Schema Guide

Then read source in this order

1. zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
2. zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts
3. zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts

What each file clarifies

• controller.tsx shows _createProperties(), _createTableMeta(), and _createColumnsMiddle()
• schema.ts shows loadSchemaProperties(...), $ref resolution, and scene-specific rest overlays
• rest.ts shows the schema extension contract, including rest.table and table-related render types

4. tableCell bean-scene contract and decorator surface

Use this path when you are asking questions like:

• what exactly is a tableCell bean?
• where does @TableCell(...) come from?
• how is the scene registered for metadata and typing?

Read the docs first

• Bean Scene Authoring
• Table Guide

Then read source in this order

1. zova/src/suite-vendor/a-zova/modules/a-table/src/lib/tableCell.ts
2. zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableCell.ts
3. zova/src/suite-vendor/a-zova/modules/a-table/package.json
4. zova/src/suite-vendor/a-zova/modules/a-table/cli/tableCell/boilerplate/..tsx_
5. zova/src/suite-vendor/a-zova/modules/a-table/cli/tableActionRow/boilerplate/..tsx_

What each file clarifies

• tableCell.ts shows the decorator definition
• types/tableCell.ts shows the runtime contract, scene typing, and NextTableCellRender
• package.json shows zovaModule.onions.tableCell and boilerplate metadata
• the boilerplate files show the intended scaffold shape for normal cells and row-action cells

5. Cell render pipeline and CEL/JSX scope

Use this path when you are asking questions like:

• how does one column render become one real cell vnode?
• where do getValue(...) and cell scope come from?
• how are JSX props evaluated for a cell bean?

Read the docs first

• Zova Table Under the Hood
• Reading Zova for Vue Developers

Then read source in this order

1. zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
2. zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableColumn.ts
3. zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableCell.ts

What each file clarifies

• controller.tsx shows getColumnJsxRenderContext(...), getCellJsxRenderContext(...), cellRenderPrepare(...), cellRender(...), and _cellRenderInner(...)
• tableColumn.ts shows column scope, cell scope, and table column render types
• tableCell.ts shows the render-context contract received by a tableCell bean

6. Representative built-in cell renderers

Use this path when you are asking questions like:

• what does a simple formatter-style table cell look like?
• what does a row-action cell look like?
• how should I design my own custom table cell?

Read the docs first

• Table Guide
• Bean Scene Authoring

Then read source in this order

1. zova/src/suite/cabloy-basic/modules/basic-text/src/bean/tableCell.text.tsx
2. zova/src/suite/cabloy-basic/modules/basic-date/src/bean/tableCell.date.tsx
3. zova/src/suite/cabloy-basic/modules/basic-select/src/bean/tableCell.select.tsx
4. zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx

What each file clarifies

• tableCell.text.tsx shows the minimal pass-through plus optional wrapper pattern
• tableCell.date.tsx shows formatting around next()
• tableCell.select.tsx shows value-to-item mapping
• actionOperationsRow.tsx shows advanced visibility checks, nested action rendering, and permission-aware orchestration

7. Custom columns through getColumns(...)

Use this path when you are asking questions like:

• how should I add one page-local operations column?
• how can I reuse the existing cell-render pipeline from custom columns?
• where is createColumnRender(...) defined?

Read the docs first

• Table Guide
• Zova Table Under the Hood

Then read source in this order

1. zova/src/suite-vendor/a-zova/modules/a-table/src/types/table.ts
2. zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
3. zova/src/suite/cabloy-basic/modules/basic-table/src/component/table/render.tsx

What each file clarifies

• types/table.ts shows TypeTableGetColumns and TypeTableCreateColumnRender
• controller.tsx shows how custom columns are given next(...), createColumnRender(...), and the table controller itself
• basic-table/render.tsx shows a module-level consumer wrapping ZTable rather than replacing its runtime

8. Resource-page integration

Use this path when you are asking questions like:

• how does a resource list page feed schema and data into ZTable?
• where do data, schemaRow, and tableScope come from?
• where should permission-sensitive table refresh be debugged?

Read the docs first

• Table Guide
• Model Resource Owner Pattern

Then read source in this order

1. zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx
2. zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx
3. vona/src/suite-vendor/a-test/modules/test-rest/src/dto/productSelectResItem.tsx

What each file clarifies

• blockPage/controller.tsx shows resource ownership, query state, page CEL scope, permissions, and table refresh integration
• blockTable/controller.tsx shows the direct bridge from page block to ZTable
• the Vona DTO specimen shows the block-based page composition consumed from backend-owned metadata

9. Representative specimens to read before editing the framework

Use this section when you want one small example before reading framework internals.

Read these specimens first

1. zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx
2. zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx
3. zova/src/suite/cabloy-basic/modules/basic-text/src/bean/tableCell.text.tsx

Why these three specimens matter

• blockTable shows the public integration path from a page into ZTable
• actionOperationsRow shows the advanced tableCell orchestration path
• tableCell.text shows the smallest custom-cell authoring shape

Together they give you the public integration, the advanced cell path, and the minimal cell path before you descend into the whole table runtime.

10. A compact reading strategy

When in doubt, use this order:

1. Table Guide
2. one real usage specimen such as blockTable
3. the public wrapper metadata under src/.metadata/component/table.ts
4. component/table/controller.tsx
5. lib/beanControllerTableBase.ts
6. types/tableCell.ts and representative cell beans only if you still need more detail

That order usually gets you to the answer faster than starting from the deepest runtime files first.

11. Final takeaway

The fastest way to read Zova Table accurately is not to memorize every file in a-table.

It is to recognize which question you are asking:

• wrapper-entry question
• controller-runtime question
• schema-column question
• tableCell scene question
• cell-render question
• resource-page integration question

Then start from the smallest public file that matches that question and only descend into deeper runtime files as needed.