cabloy 5.1.61 → 5.1.63

package/cabloy-docs/frontend/zova-source-reading-map.md

@@ -12,14 +12,15 @@ Use this page together with the architectural guides:
 - [Design Principles](/frontend/design-principles)
 - [IoC and Beans](/frontend/ioc-and-beans)
 - [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap)
 - [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
 
 ## Why this page exists
 
 In a framework-sized codebase, source reading usually becomes slow for one reason:
 
-- you can already find *a* relevant file
-- but you do not yet know the shortest path to the *next* file
+- you can already find _a_ relevant file
+- but you do not yet know the shortest path to the _next_ file
 
 Zova especially benefits from a reading map because several layers cooperate at once:
 
@@ -144,6 +145,9 @@ Use this path when you are asking questions like:
 ### Read the docs first
 
 - [Page Route Guide](/frontend/page-route-guide)
+- [A-Router Guide](/frontend/a-router-guide)
+- [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
 - [Page Params Guide](/frontend/page-params-guide)
 - [Page Query Guide](/frontend/page-query-guide)
 - [Navigation Guards Guide](/frontend/navigation-guards-guide)
@@ -164,7 +168,64 @@ Use this path when you are asking questions like:
 - route schema sources show typed parsing behavior for params and query
 - `beanControllerPageBase.ts` shows the page-controller refresh hook surface
 
-## 5. Model state, cache-oriented state, and broader data ownership
+### When to continue into routed hosts
+
+If your next question becomes any of these:
+
+- why this route lands in one shell host rather than another
+- where keep-alive participation is decided after route resolution
+- where `tabKey` / `componentKey` are derived for routed pages
+- how the active layout consumes routed-host state
+
+then continue immediately with:
+
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+- section 5 on this page for the compact source-reading path
+
+## 5. Router-view hosts, routertabs, and routerstack
+
+Use this path when you are asking questions like:
+
+- why does one routed page use an empty host while another behaves like a tabbed workbench?
+- where do `tabKey`, `componentKey`, and keep-alive inclusion actually come from?
+- how do `routerViewTabs` and `routerViewStack` differ at runtime?
+- which layout files are the real consumers of routed-host behavior?
+
+### Read the docs first
+
+- [Page Route Guide](/frontend/page-route-guide)
+- [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Tabs vs Stack](/frontend/router-tabs-vs-stack)
+- [Router Stack Guide](/frontend/router-stack-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-router/src/lib/routerViewBase.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-router/src/component/routerViewEmpty/controller.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/component/routerViewTabs/controller.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-routerstack/src/component/routerViewStack/controller.tsx`
+6. `zova/src/suite-vendor/a-zova/modules/a-routerstack/src/model/stack.ts`
+7. the active layout controller/render pair that consumes the host you care about
+
+### What each file clarifies
+
+- `routerViewBase.tsx` shows the shared host contract for routed-page render, keep-alive, and host callbacks
+- `routerViewEmpty/controller.tsx` shows the minimal routed host without the richer tabs/stack model
+- `routerViewTabs/controller.tsx` shows the controller-facing tabs host entrypoint
+- `model/tabs.ts` shows workspace grouping, tab-item state, page-meta updates, and keep-alive inclusion
+
+If your next question becomes specifically about task-level title, dirty state, or form-scene presentation after the routed item is already open, continue with [Page Meta Guide](/frontend/page-meta-guide).
+
+- `routerViewStack/controller.tsx` shows the stack-host entrypoint with a smaller contract than tabs
+- `model/stack.ts` shows the fullPath-based stack identity model and recency-based pruning
+- active layout consumers show how the current shell turns host state into visible Admin or Web behavior
+
+## 6. Model state, cache-oriented state, and broader data ownership
 
 Use this path when you are asking questions like:
 
@@ -192,7 +253,7 @@ Use this path when you are asking questions like:
 - built-in model beans show how the architecture is used in nontrivial cases
 - consuming code shows whether the state really belongs in the model or only uses the model result
 
-## 6. Command scene and command-bean invocation
+## 7. Command scene and command-bean invocation
 
 Use this path when you are asking questions like:
 
@@ -224,7 +285,40 @@ Use this path when you are asking questions like:
 - generated downstream metadata shows the real command names and bean full names exposed by consuming modules
 - representative command beans show when to use the plain, bulk, row, or scene-sensitive command shapes
 
-## 7. Behavior scene and render-time interception
+## App-shell root host and `a-app`
+
+Use this path when you are asking questions like:
+
+- what is the root app host in Zova?
+- where does the routed tree first enter the app controller path?
+- where do app-wide behaviors wrap the routed content?
+- how should I read `a-app` without confusing it with routes, layouts, or SSR orchestration?
+
+### Read the docs first
+
+- [Zova App Guide](/frontend/zova-app-guide)
+- [Root Behaviors Guide](/frontend/root-behaviors-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/this.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/index.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/component/app.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-app/src/component/app/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-app/src/config/config.ts`
+
+### What each file clarifies
+
+- `this.ts` shows the module identity quickly
+- `.metadata/index.ts` shows the generated integration surface for controller, component, config, and scope
+- `.metadata/component/app.ts` shows the thin `ZApp` wrapper that mounts `ControllerApp` through `useController(...)`
+- `controller.tsx` shows app-level meta setup, behavior-holder initialization, and behavior-wrapped `RouterView` render
+- `config.ts` shows the root behavior injection point through `scope.config.behaviors`
+
+## 8. Behavior scene and render-time interception
 
 Use this path when you are asking questions like:
 
@@ -251,7 +345,7 @@ Use this path when you are asking questions like:
 - composer/service files show how behavior chains are normalized and executed
 - host dependencies show why host-scoped injection is part of the behavior design
 
-## 8. SSR runtime and hydration handoff
+## 9. SSR runtime and hydration handoff
 
 Use this path when you are asking questions like:
 
@@ -280,7 +374,7 @@ Use this path when you are asking questions like:
 - page/controller/model files show whether the bug is actually page-level logic
 - the Vona side shows whether the problem happens before the Zova runtime is even entered
 
-## 9. Modules, suites, and architectural placement
+## 10. Modules, suites, and architectural placement
 
 Use this path when you are asking questions like:
 

package/cabloy-docs/frontend/zova-table-controller-render-supplement.md

@@ -0,0 +1,225 @@
+# Zova Table Controller Render Deep Dive
+
+This page is a small lower-level supplement for the Zova Table runtime.
+
+Use it when you already understand the broader table architecture and now want to inspect the controller micro-pipeline more precisely:
+
+- how `ControllerTable` boots
+- how visible columns and render functions are assembled
+- how `tableCell` render providers are normalized and resolved
+- how cell render preparation and transient-object handoff work
+
+## Why this supplement exists
+
+The existing table docs already cover the broad architecture well:
+
+- [Table Guide](/frontend/table-guide)
+- [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+
+What those pages do not isolate directly is the controller/render micro-pipeline inside `ControllerTable`.
+
+That is the only gap this supplement fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `BeanControllerTableBase.$useTable(...)` owns the TanStack bridge at controller level
+2. `ControllerTable.__init__()` prepares schema properties, metadata, columns, and the table instance
+3. `_createTableMeta()` decides which properties are visible and which render function each one should use
+4. `_createColumnRender()` resolves either a `tableCell` bean-backed render path or a general render target
+5. `cellRenderPrepare()` can preload nested bean-backed renders
+6. `_cellRender()` / `_cellRenderInner()` hand off row/cell scope, fallback values, and transient `getValue(...)` state into final rendering
+
+That means the controller micro-pipeline is where schema, visibility, bean resolution, and render contexts finally converge.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.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/types/tableCell.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-table/src/types/tableColumn.ts`
+5. `zova/packages-utils/zova-jsx/src/lib/zovaJsx.ts`
+6. `zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx`
+
+That order moves from the controller/TanStack bridge, to the main controller runtime, to the render contracts, to the JSX runtime handoff, and finally to a concrete `tableCell` specimen.
+
+## `BeanControllerTableBase.$useTable(...)`
+
+The TanStack bridge lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-table/src/lib/beanControllerTableBase.ts
+```
+
+The key source-confirmed behavior is:
+
+- `useVueTable(...)` is called inside `instanceScope(...)`
+- the returned table instance is `markRaw(...)`
+
+This is the first important lower-level rule:
+
+- the table instance is still controller-owned runtime
+- TanStack is the underlying table engine, but the controller remains the effective Zova runtime owner
+
+## `ControllerTable.__init__()` boot sequence
+
+The main runtime file is:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
+```
+
+The source confirms this boot sequence:
+
+1. register `$$table`
+2. create the CEL environment and `ZovaJsx` instance
+3. create schema-driven properties
+4. refresh metadata
+5. watch `schema` for meta refresh
+6. create the TanStack table instance
+
+That is the core controller-level assembly path.
+
+## `_createTableMeta()` as visible-column/render assembly point
+
+Inside the same controller, `_createTableMeta()` is the clearest metadata-assembly step.
+
+It:
+
+- iterates schema-derived properties
+- builds column scope
+- builds render context
+- merges top-level column props
+- checks visibility
+- creates per-column render functions
+- stores the surviving visible properties and render map in `tableMeta`
+
+This is the most important micro-pipeline rule:
+
+- schema properties do not automatically become rendered columns
+- they are filtered and converted through controller-owned metadata assembly first
+
+## `getRenderProvider()` normalization and `_createColumnRender()`
+
+The render-resolution path also lives in `ControllerTable`.
+
+It decides whether a column render should be treated as:
+
+- text fallback
+- a general render target
+- a `tableCell` bean-backed renderer
+
+`_createColumnRender()` is the main resolution point where:
+
+- render provider is normalized
+- bean-backed providers are resolved
+- decorator options are merged
+- visibility hooks such as `checkVisible(...)` can participate
+
+This is the lower-level rule to remember:
+
+- render resolution is not only “take whatever the schema says”
+- the controller resolves and normalizes that render contract first
+
+## `cellRenderPrepare()` and nested render preloading
+
+`cellRenderPrepare()` is the preloading step for bean-backed renderers.
+
+This matters most for nested or action-heavy cells, because it lets the controller prepare the concrete `tableCell` beans before final render.
+
+A practical reading rule is:
+
+- `cellRenderPrepare()` is part of render readiness, not only a cosmetic helper
+
+A good current specimen is:
+
+- `basic-table/src/bean/tableCell.actionOperationsRow.tsx`
+
+because it prepares the nested row-action render set based on visibility.
+
+## `_cellRender()` / `_cellRenderInner()` and transient value handoff
+
+The final cell rendering path uses:
+
+- column scope
+- cell scope
+- fallback value
+- actual cell value
+- transient `getValue(...)` handoff through `ZovaJsx`
+
+This is where the lower-level scope handoff matters most.
+
+The current runtime uses the `ZovaJsx` transient-object path so cell renderers can see the active value context while still staying inside the controller-driven runtime.
+
+A practical reading rule is:
+
+- the final cell render is not only a plain function call
+- it is a scoped runtime handoff with controller-owned context
+
+## Table-cell contract in types
+
+The render contracts live in:
+
+- `a-table/src/types/tableCell.ts`
+- `a-table/src/types/tableColumn.ts`
+
+These files confirm the lower-level boundary types for:
+
+- `ITableCellRender`
+- `checkVisible(...)`
+- column scope vs cell scope
+- render contexts passed into cell renderers
+
+That makes them the right files to read when the runtime feels confusing even though the broad table docs are already understood.
+
+## Concrete specimen: operations-row tableCell
+
+A good concrete specimen is:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx
+```
+
+This file is useful because it shows several lower-level pieces in one place:
+
+- `checkVisible(...)`
+- permission-based render filtering
+- nested render preparation
+- final action-row rendering through the table cell contract
+
+So it is the best small specimen for understanding why the micro-pipeline matters in practice.
+
+## What this page does not re-explain
+
+This supplement does **not** fully re-explain:
+
+- broad table authoring -> see [Table Guide](/frontend/table-guide)
+- full runtime architecture -> see [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- general file-order map -> see [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+- row/bulk permission semantics -> see [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+
+Its job is only to explain the controller/render micro-pipeline.
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want the broad table runtime again, read [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- if you want the file-order map, read [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
+- if you want row/bulk visibility behavior, read [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- if you want the list-page runtime that feeds `ZTable`, read [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+
+## Final takeaway
+
+The most accurate way to read this lower-level table supplement is:
+
+- `BeanControllerTableBase` owns the TanStack bridge at controller scope
+- `ControllerTable` owns metadata assembly and render resolution
+- `tableCell` beans participate through explicit controller-managed resolution and scope handoff
+- `cellRenderPrepare()` and `_cellRender()` are part of the real runtime pipeline, not only helper details
+
+That is the source-confirmed controller/render micro-pipeline in the current Cabloy Basic table runtime.