cabloy 5.1.60 → 5.1.62

package/cabloy-docs/frontend/router-tabs-layout-integration.md

@@ -0,0 +1,367 @@
+# Router Tabs Layout Integration
+
+This guide explains how the current Cabloy Basic layouts turn `ModelTabs` into visible router shell behavior in Zova.
+
+Use this page after [Router View Hosts Guide](/frontend/router-view-hosts-guide) and [Router Tabs Mechanism](/frontend/router-tabs-mechanism) when your next question is no longer “how does the tabs model work?” but “how do the real layout controllers and render beans turn that model into the Admin or Web shell?”.
+
+Read this page together with:
+
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Page Meta Guide](/frontend/page-meta-guide)
+- [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
+> [!TIP]
+> **Router ecosystem docs path**
+> 1. **[Page Route Guide](/frontend/page-route-guide)** — learn the public route-record and layout surface
+> 2. **[Zova Router Under the Hood](/frontend/zova-router-under-the-hood)** — learn how the core router runtime cooperates
+> 3. **[Router View Hosts Guide](/frontend/router-view-hosts-guide)** — learn how routed pages are actually hosted
+> 4. **[Router Tabs Mechanism](/frontend/router-tabs-mechanism)** — learn how the tabs host turns route visits into state
+> 5. **[Router Tabs Layout Integration](/frontend/router-tabs-layout-integration)** — learn how the current Basic layouts turn that state into visible shell behavior
+> 6. **[Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)** — learn how route metadata intentionally drives the model
+>
+> **You are here:** step 5.
+> **Previous pages:** [Router View Hosts Guide](/frontend/router-view-hosts-guide) and [Router Tabs Mechanism](/frontend/router-tabs-mechanism).
+> **Next recommended page:** [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook).
+
+## Why this page exists
+
+The current router-tabs docs already explain:
+
+- the business meaning of router tabs
+- the shared `ModelTabs` mechanism
+- the Admin vs Web visual comparison
+- the route-meta inputs that drive the model
+
+What contributors and AI workflows still often want next is the layout-integration bridge:
+
+- where `ModelTabs` is created inside a real layout controller
+- how the layout chooses `tabsOptions`
+- how the render bean turns `tabs` into a visible shell
+- which parts are shared model semantics and which parts are layout presentation
+
+This page is that bridge.
+
+If your next question is specifically about how page code feeds task-level title, dirty state, or form scene into the visible shell, continue with [Page Meta Guide](/frontend/page-meta-guide).
+
+## The shortest accurate mental model
+
+For the current public Cabloy Basic source, the shortest accurate model is:
+
+1. the layout controller loads menus and creates a `ModelTabs` selector bean
+2. the layout passes layout-specific `tabsOptions` such as `scene`, `max`, `maxItems`, and `cache`
+3. the shared `ZRouterViewTabs` host keeps route visits and keep-alive behavior synchronized with `ModelTabs`
+4. the layout render bean reads `$$modelTabs.tabs`, `tabCurrent`, and related state to produce the visible shell
+5. Admin and Web reuse the same underlying tabs model but project it into different top-level UI structures
+
+That is why layout integration is not merely cosmetic. It is the point where shared router-tabs state becomes the concrete shell experience.
+
+## The source files that matter most
+
+### Admin layout integration
+
+- `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/controller.tsx`
+- `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/render.tabs.tsx`
+- `zova/src/suite/a-home/modules/home-layoutadmin/src/config/config.ts`
+
+### Web layout integration
+
+- `zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/controller.tsx`
+- `zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/render.tabs.tsx`
+- `zova/src/suite/a-home/modules/home-layoutweb/src/config/config.ts`
+
+### Shared host/model layer used by both
+
+- `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/component/routerViewTabs/controller.tsx`
+- `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts`
+
+## Step-by-step layout integration path
+
+### 1. The layout controller, not the render bean, creates `ModelTabs`
+
+The real integration starts in the layout controller.
+
+In both Admin and Web, the controller is where:
+
+- menus are loaded
+- tabs config is read from the layout scope config
+- a selector-scoped `ModelTabs` bean is created
+- later menu changes refresh or reset visible tab info
+
+This is the first important source-level fact about layout integration:
+
+- **the render bean does not own tabs state**
+- **the layout controller owns the decision to create and configure the tabs model**
+
+## 2. Admin layout integration
+
+Representative controller source:
+
+```text
+zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/controller.tsx
+```
+
+### Zova-native role
+
+The Admin layout controller creates a workbench-oriented tabs model whose top level is anchored to menu-backed business workspaces.
+
+### Source-confirmed runtime behavior
+
+Inside `_initTabs()` the Admin layout:
+
+- reads `this.scope.config.tabs`
+- builds `tabsOptions`
+- uses `this.bean._getBeanSelector('a-routertabs.model.tabs', true, configTabs.scene, tabsOptions)`
+- keeps the selected model on `this.$$modelTabs`
+- watches menu data and calls `updateAllTabInfos()` when menus change
+
+The important Admin-specific `tabsOptions` behavior is:
+
+- `getInitialTabs()` returns `[{ tabKey: '/', affix: true }]` once menus are available
+- `getTabInfo(tabKey)` resolves title and icon from the menu model by `link`
+
+That means the Admin layout does two important things for the shared tabs model:
+
+1. it guarantees a fixed affixed top-level home workspace
+2. it derives visible workspace labels from menu-backed business information rather than from temporary page state
+
+### Why this matters
+
+This is why Admin level-1 tabs feel stable and business-oriented.
+
+The model itself is generic, but the layout controller injects business-facing tab identity and the initial affixed workspace rule.
+
+## 3. Admin render integration
+
+Representative render source:
+
+```text
+zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/render.tabs.tsx
+```
+
+### Zova-native role
+
+The Admin render bean turns `ModelTabs` into an explicit two-level workbench shell.
+
+### Source-confirmed runtime behavior
+
+The render bean exposes three main surfaces:
+
+- `renderTabs()` for level-1 workspace tabs
+- `renderTabItems()` for level-2 task items
+- `_renderRouterViewTabs()` for the actual routed host outlet
+
+Important details:
+
+- level-1 rows iterate over `$$modelTabs.tabs`
+- clicking a level-1 tab calls `$$modelTabs.activeTab(tabKey)`
+- non-affix level-1 tabs expose `deleteTab(tabKey)`
+- level-2 rows read `$$modelTabs.tabCurrent.items`
+- the anchor item is intentionally skipped when `componentKey === tabKey`
+- clicking a level-2 item calls `activeTabItem(tabKey, componentKey)`
+- deleting a level-2 item calls `deleteTabItem(...)`
+- page-level icon state is derived from `pageMeta` such as `pageDirty` and `formMeta.formScene`
+- the actual routed content still enters through `<ZRouterViewTabs>`
+
+For the authoring-side write path that produces those `pageMeta` values, see [Page Meta Guide](/frontend/page-meta-guide).
+
+This is the second important source-level fact about layout integration:
+
+- **the layout render bean does not replace the router host**
+- **it wraps the shared host with a visible shell that reads the same model state**
+
+### What the Admin shell makes visible
+
+Admin makes these model semantics explicit:
+
+- level-1 workspace grouping
+- level-2 task items
+- dirty indicators
+- create/edit task indicators
+- close actions for both outer and inner levels
+
+That is why Admin is the clearest business-meaning specimen for router tabs.
+
+## 4. Web layout integration
+
+Representative controller source:
+
+```text
+zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/controller.tsx
+```
+
+### Zova-native role
+
+The Web layout controller creates a tabs model that is still shared in semantics, but whose initial top-level state is derived from the menu tree rather than from one affixed home workspace.
+
+### Source-confirmed runtime behavior
+
+Inside `_initTabs()` the Web layout:
+
+- reads `this.scope.config.tabs`
+- builds `tabsOptions`
+- creates the same selector-scoped `ModelTabs` bean
+- watches menu data and calls `resetAllTabInfos()` when menus change
+
+The important Web-specific `tabsOptions` behavior is:
+
+- `getInitialTabs()` returns one item per top-level menu tree entry
+- each initial tab uses `item.folder ? item.name : item.link` as `tabKey`
+- `info` is stored directly from the menu tree item
+
+That means the Web layout treats top-level workspace entries more like shell navigation nodes than like one pre-affixed home workspace plus later-opened work areas.
+
+### Why this matters
+
+This is why the Web shell can feel menu-driven at the top level while still relying on the same `ModelTabs` state underneath.
+
+The model stays shared, but the controller chooses a different initialization strategy.
+
+## 5. Web render integration
+
+Representative render source:
+
+```text
+zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/render.tabs.tsx
+```
+
+### Zova-native role
+
+The Web render bean projects the same tabs model into a horizontal menu-like shell.
+
+### Source-confirmed runtime behavior
+
+The render bean:
+
+- iterates over `$$modelTabs.tabs`
+- renders top-level entries through `_renderMenuItem(...)`
+- supports folder, separator, and leaf menu shapes
+- uses `tabKey === $$modelTabs.tabKeyCurrent` for top-level active state
+- lets top-level shell clicks call `$$modelTabs.activeTab(tabKey)`
+- lets nested leaf links navigate through `RouterLink`
+- still renders the actual routed content through `<ZRouterViewTabs>`
+
+This is the third important source-level fact about layout integration:
+
+- **Web does not abandon the tabs model**
+- **it simply renders the top-level workspace state through a menu-oriented shell instead of an explicit lifted tab row**
+
+## 6. Config is part of layout integration, not an afterthought
+
+Representative config sources:
+
+- `zova/src/suite/a-home/modules/home-layoutadmin/src/config/config.ts`
+- `zova/src/suite/a-home/modules/home-layoutweb/src/config/config.ts`
+
+### Current Basic source values
+
+Admin:
+
+- `scene: ''`
+- `max: 6`
+- `maxItems: 3`
+- `cache: true`
+- `tabItem.maxWidth: '130px'`
+
+Web:
+
+- `scene: 'web'`
+- `max: 6`
+- `maxItems: 6`
+- `cache: false`
+
+### Why this matters
+
+These config differences directly shape shell behavior:
+
+- `scene` chooses the selector-space identity of the tabs model
+- `max` and `maxItems` change pruning density
+- `cache` changes whether shell state is restored through cached model state
+- Admin-only `tabItem.maxWidth` shapes inner task-row presentation
+
+A practical reading takeaway is:
+
+- **layout integration includes controller logic, render logic, and config together**
+
+## 7. What is shared vs what is layout-specific
+
+### Shared semantics
+
+These remain in the shared model/host layer:
+
+- route-to-workspace mapping
+- `tabKey` and `componentKey` meaning
+- keep-alive inclusion
+- activation and pruning behavior
+- page-meta storage on tab items
+- routed content entering through `ZRouterViewTabs`
+
+### Layout-specific behavior
+
+These belong mainly to the layout integration layer:
+
+- how top-level entries are initialized from menu state
+- whether there is an affixed home workspace
+- whether the second level is shown explicitly
+- whether the top level looks like tabs or a horizontal menu
+- how close buttons, item width, and icon density are presented
+
+This is the key boundary to preserve:
+
+- **change shared semantics in the host/model layer only when the framework contract should change**
+- **change visual shell behavior in the layout layer when only presentation should change**
+
+## 8. A practical reading order for source readers
+
+If your question is specifically about how `ModelTabs` becomes a visible shell, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/component/routerViewTabs/controller.tsx`
+3. `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/controller.tsx`
+4. `zova/src/suite/a-home/modules/home-layoutadmin/src/component/layoutAdmin/render.tabs.tsx`
+5. `zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/controller.tsx`
+6. `zova/src/suite/a-home/modules/home-layoutweb/src/component/layoutWeb/render.tabs.tsx`
+7. the two layout config files
+
+Use Admin first when you want the clearest expression of the workbench model.
+Use Web next when you want to confirm that the same model can back a different shell style.
+
+## Common mistakes to avoid
+
+### Mistake 1: treating the layout render bean as the tabs state owner
+
+It is not.
+
+The render bean projects state visually. The controller and shared model own the state.
+
+### Mistake 2: assuming Admin-specific tab rows define the whole router-tabs contract
+
+They do not.
+
+Admin is one visible projection of a broader routed-host and tabs-model contract.
+
+### Mistake 3: assuming Web is not using router tabs because it looks like a menu
+
+It is still using `ModelTabs` and `ZRouterViewTabs`.
+
+Only the shell projection differs.
+
+### Mistake 4: changing layout presentation when the real change belongs in `ModelTabs`
+
+If the behavior should be shared across shells, change the shared model/host layer first.
+
+If only the visible shell should differ, change the layout layer first.
+
+## Edition note
+
+This guide is source-confirmed against the current public Cabloy Basic layouts.
+
+That means the integration story here is accurate for the current Basic Admin and Web shells, but should not be overgeneralized to every future edition or downstream layout without verification.
+
+## Final takeaway
+
+If [Router Tabs Mechanism](/frontend/router-tabs-mechanism) explains how the shared tabs model works, this page explains how the real Basic layouts turn that shared model into visible shell behavior.
+
+That is the missing bridge between framework-level tabs semantics and the actual layout code contributors edit.

package/cabloy-docs/frontend/router-tabs-mechanism.md

@@ -4,6 +4,10 @@ This guide explains how the router-tabs mechanism works in Zova within the Cablo
 
 For the business meaning of the mechanism, see [Router Tabs Overview](/frontend/router-tabs-overview).
 
+If you came here from [Router View Hosts Guide](/frontend/router-view-hosts-guide), this page is the next layer down: the host guide explains routed-host choice, while this page explains the shared `ModelTabs` semantics behind that host.
+
+If your next question becomes specifically about how a page author should update task-level title, dirty state, or form scene through `$router.setPageMeta(...)`, continue with [Page Meta Guide](/frontend/page-meta-guide).
+
 ## Why this mechanism exists
 
 The router-tabs mechanism is designed to support a workbench-style frontend navigation model.
@@ -288,6 +292,8 @@ Representative page metadata includes:
 
 This metadata shapes the visible state of the level-2 tab.
 
+For authoring-focused guidance on when page code should call `$router.setPageMeta(...)` and how to keep that separate from route meta, see [Page Meta Guide](/frontend/page-meta-guide).
+
 ### `pageTitle`
 
 `pageTitle` is typically used as the displayed title of the level-2 item.

package/cabloy-docs/frontend/router-tabs-route-meta-cookbook.md

@@ -2,12 +2,15 @@
 
 This guide provides practical route-meta recipes for the router-tabs mechanism in Zova within the Cabloy monorepo.
 
+If you came here from [Router View Hosts Guide](/frontend/router-view-hosts-guide), [Router Tabs Mechanism](/frontend/router-tabs-mechanism), or [Router Tabs Layout Integration](/frontend/router-tabs-layout-integration), this page is the authoring layer: the earlier pages explain host/runtime behavior, and this page explains how route metadata intentionally drives it.
+
 Read this together with:
 
 - [Router Tabs Introduction](/frontend/router-tabs-introduction)
 - [Page Route Guide](/frontend/page-route-guide)
 - [Router Tabs Overview](/frontend/router-tabs-overview)
 - [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Tabs Layout Integration](/frontend/router-tabs-layout-integration)
 
 ## Why this cookbook exists
 
@@ -39,6 +42,10 @@ Representative source definition:
 
 Use this decision split first:
 
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide) explains where host-level routed identity is consumed
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism) explains how `ModelTabs` turns route data into tab state
+- this page explains how to choose the route-meta inputs that drive that model
+
 - `tabKey` answers: which level-1 workspace should this route belong to?
 - `componentKey` answers: should this route visit reuse an existing page instance or remain separately open?
 

package/cabloy-docs/frontend/router-tabs-vs-stack.md

@@ -0,0 +1,167 @@
+# Router Tabs vs Stack
+
+This guide explains when to think in **Router Tabs** and when to think in **Router Stack** in Zova.
+
+Use this page when you want to answer questions like:
+
+- should this routed host behave like a workbench or like a linear routed stack?
+- when do I need `tabKey` and `componentKey`?
+- when is `fullPath` identity enough?
+- when should page-meta-aware work items exist, and when are they unnecessary?
+
+## Why this comparison exists
+
+The current frontend docs already explain the two nearby branches separately:
+
+- [Router Tabs Introduction](/frontend/router-tabs-introduction) and the rest of the tabs series explain the workbench-tabs branch
+- [Router Stack Guide](/frontend/router-stack-guide) explains the stack branch
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide) explains the shared routed-host layer above both
+
+What many readers still need next is a decision page.
+
+That is the gap this guide fills.
+
+This page is intentionally a chooser between two host models. For the shared host boundary, keep [Router View Hosts Guide](/frontend/router-view-hosts-guide) as the main reference, and use this page only when the host question has already narrowed to tabs vs stack.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+- **Router Tabs** = a workbench model with business/workspace grouping plus page-instance identity
+- **Router Stack** = a linear routed-cache model where each route visit is one host identity
+
+If you need grouped workspaces and task-level state, think in Tabs.
+
+If you need a simple per-visit routed stack, think in Stack.
+
+## The core difference in one table
+
+| Question                                         | Router Tabs                                 | Router Stack                                            |
+| ------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------- |
+| What owns the host state?                        | `ModelTabs`                                 | `ModelStack`                                            |
+| What is the host controller?                     | `ControllerRouterViewTabs`                  | `ControllerRouterViewStack`                             |
+| What is the main identity model?                 | `tabKey` + `componentKey`                   | `fullPath`                                              |
+| What is `tabKey` for?                            | level-1 workspace grouping                  | same as `fullPath` identity                             |
+| What is `componentKey` for?                      | level-2 page-instance identity              | same as `fullPath` identity                             |
+| Does it support workbench semantics?             | yes                                         | no                                                      |
+| Does it support page-meta-aware task updates?    | yes                                         | no dedicated stack equivalent                           |
+| What kind of pruning does it do?                 | tab/work-item pruning inside the tabs model | linear recency-based pruning                            |
+| What is the current public Basic shell emphasis? | visible and central                         | framework primitive, not the main visible shell pattern |
+
+## Identity model: Tabs
+
+The tabs branch separates two questions:
+
+1. which business/workspace does this route belong to?
+2. which page instance inside that workspace is this?
+
+That is why `ModelTabs` works with both:
+
+- `tabKey`
+- `componentKey`
+
+A compact interpretation is:
+
+- `tabKey` = level-1 grouping identity
+- `componentKey` = level-2 page-instance identity
+
+This is the right model when multiple routed visits should still belong to one durable business workspace.
+
+## Identity model: Stack
+
+The stack branch collapses routed identity to `fullPath`.
+
+In `ModelStack.prepareRouteMeta(...)`, the stack host returns:
+
+- `tabKey = route.fullPath`
+- `componentKey = route.fullPath`
+- `fullPath = route.fullPath`
+
+That means a stack visit is treated as one linear routed entry.
+
+This is the right model when per-visit identity is enough and you do not need a separate workspace grouping layer.
+
+## Page-meta and workbench semantics
+
+The tabs branch supports richer task/workbench semantics.
+
+In the current public source:
+
+- `ControllerRouterViewTabs` forwards `setPageMeta(...)`
+- `ModelTabs` stores and updates page-meta information per routed work item
+
+That makes tabs a good fit for:
+
+- workbench titles
+- dirty state
+- task-level UI state that belongs to an open work item
+
+The stack branch does not add that richer page-meta ownership model.
+
+That is why stack should not be treated as “tabs with fewer UI decorations.” It is a different host model.
+
+## Choose Tabs when
+
+Choose Router Tabs when you need:
+
+- stable business/workspace grouping
+- more than one open work item inside that grouping
+- page-instance reuse decisions separate from workspace identity
+- task-level page-meta behavior
+- the current public Basic Admin/Web-style workbench semantics
+
+This is the normal fit for the existing Router Tabs series.
+
+## Choose Stack when
+
+Choose Router Stack when you need:
+
+- a simpler per-visit routed host
+- one identity per route visit
+- bounded linear routed caching
+- recency-based pruning without workbench grouping
+- no tabs-style page-meta/workspace semantics
+
+This is the normal fit when `fullPath` identity is the main thing that matters.
+
+## Current Cabloy Basic visibility note
+
+In the current public Basic source:
+
+- Router Tabs are the visibly emphasized shell model in the existing public layout docs
+- Router Stack exists as a real framework host primitive
+- Router Stack should therefore be understood as an available routed-host strategy, not as the most prominent visible Basic shell pattern
+
+This distinction matters because the framework capability and the currently emphasized public shell are not always the same thing.
+
+## Suggested decision rule
+
+Use this quick rule:
+
+1. do you need a durable business/workspace grouping layer?
+   - yes -> choose **Router Tabs**
+   - no -> continue
+2. do you only need each route visit to behave like one linear cached routed item?
+   - yes -> choose **Router Stack**
+   - no -> re-check whether you actually need tabs-level semantics
+
+## Read together with
+
+Use this page together with:
+
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Stack Guide](/frontend/router-stack-guide)
+- [A-Router Guide](/frontend/a-router-guide)
+
+## Final takeaway
+
+The most accurate distinction is:
+
+- **Router Tabs** are for grouped workbench semantics
+- **Router Stack** is for linear routed-cache semantics
+
+If you need workspace grouping, task identity, and page-meta-aware work items, think in Tabs.
+
+If you need one identity per route visit with simpler recency-based caching, think in Stack.