cabloy 5.1.59 → 5.1.61

package/cabloy-docs/frontend/reading-zova-for-vue-developers.md

@@ -0,0 +1,266 @@
+# Reading Zova for Vue Developers
+
+This guide is for readers who already know Vue 3 and want the shortest accurate path to reading Zova source code without forcing generic Vue assumptions onto it.
+
+## Why this page exists
+
+When Vue developers first open Zova code, several things can feel unfamiliar at the same time:
+
+- page and component logic lives in controller classes
+- plain class fields behave reactively
+- derived state is often wired in `__init__`
+- render logic is written in TSX and can live in a controller or a dedicated render bean
+- state sharing is organized through IoC containers and bean scopes rather than a pile of unrelated patterns
+
+If you read Zova as "Vue with unusual syntax," you will miss the architectural point.
+
+A better starting point is:
+
+- **Vue still provides the reactive foundation**
+- **Zova changes the preferred programming model built on top of that foundation**
+
+## The shortest accurate mental model
+
+If you only remember one paragraph, remember this one:
+
+> Zova keeps Vue 3 reactivity underneath, but moves the main authoring surface from `setup()` locals and explicit `ref/reactive` values toward IoC-managed reactive bean instances such as page controllers, component controllers, service beans, and model beans.
+
+That is why Zova code often reads more like controller-oriented application code than like a typical Vue single-file-component or composable-first codebase.
+
+## Quick translation table
+
+| If you usually think in Vue terms | Read Zova like this instead |
+| --- | --- |
+| `setup()` is the main wiring point | `__init__` and bean lifecycle are major wiring points |
+| `ref` / `reactive` are the visible state hosts | controller and bean instances are the visible state hosts |
+| `computed()` creates local derived refs | `$computed()` usually creates instance-level derived state |
+| `useRoute()` pulls route state into the component | page controllers expose `$route`, `$params`, and `$query` as part of the controller surface |
+| `provide/inject`, composables, props, and stores are separate sharing tools | bean scopes and IoC are used to unify more sharing patterns under one model |
+| template or component render is the obvious center | controller-oriented architecture is the center; render can stay in the controller or move into render beans |
+
+## Start from the right assumptions
+
+### 1. Do not assume Zova wants to end at `ref.value`
+
+Zova intentionally aims for code that feels closer to direct variable usage than `ref/reactive`-heavy business code.
+
+That does **not** mean Zova rejects Vue reactivity. It means Zova tries to hide more of the reactive primitive management behind a different framework surface.
+
+Read together with:
+
+- [Design Principles](/frontend/design-principles)
+- [Foundation](/frontend/foundation)
+
+### 2. Do not treat IoC as a small convenience layer
+
+In Zova, IoC is not only about injecting a helper or two.
+
+It is part of the larger architectural answer for:
+
+- state ownership
+- state sharing
+- cross-module composition
+- lifecycle structure
+- extensibility
+
+Read together with:
+
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Module Scope](/frontend/module-scope)
+- [Modules and Suites](/frontend/modules-and-suites)
+
+### 3. Do not collapse page, component, service, and model code into one generic Vue component mental model
+
+Zova gives different bean types different architectural jobs.
+
+For example:
+
+- page controllers organize page-local state and route-aware behavior
+- component controllers organize reusable UI units
+- service beans can own extracted business state or behavior
+- model beans organize broader state categories such as async, local-storage, cookie, or in-memory data
+
+Read together with:
+
+- [Page Guide](/frontend/page-guide)
+- [Component Guide](/frontend/component-guide)
+- [Model Architecture](/frontend/model-architecture)
+- [Model State Guide](/frontend/model-state-guide)
+
+## A concrete specimen to read first
+
+If you want one small example that shows the Zova coding style clearly, start with the demo page controller in the public source tree:
+
+```text
+zova/src/suite/a-demo/modules/demo-basic/src/page/state/controller.tsx
+```
+
+The important things to notice in that file are:
+
+- `count` is a plain class field
+- `count2` is wired in `__init__` through `$computed`
+- actions are plain class methods such as `increment()` and `decrement()`
+- `render()` reads the instance fields directly
+
+A Vue-first reader often expects this kind of code to be rewritten into `setup()` plus `ref` plus `computed`. That is exactly the instinct you should suspend while reading Zova.
+
+## How to read the reactive path under the surface
+
+For the example above, a practical source-reading path is:
+
+1. the example controller in `zova/src/suite/a-demo/modules/demo-basic/src/page/state/controller.tsx`
+2. `zova/packages-zova/zova-core/src/composables/useController.ts`
+3. `zova/packages-zova/zova-core/src/bean/beanContainer.ts`
+4. `zova/packages-zova/zova-core/src/bean/beanBase.ts`
+5. `zova/packages-zova/zova-core/src/core/context/component.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-router/src/monkey.ts`
+
+A compact interpretation of those files is:
+
+- `useController.ts` creates and loads the controller bean
+- `beanContainer.ts` is where bean instances become reactive and container-managed
+- `beanBase.ts` exposes helpers such as `$computed`, `$watch`, and `$toRef`
+- `component.ts` patches the component render flow so controller-driven render logic participates in normal frontend updates
+- `a-router/src/monkey.ts` pushes page route state onto page controllers
+
+This is the main reason Zova can feel so different while still standing on top of Vue runtime behavior.
+
+If you want the next layer down, continue with [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood).
+
+## Six practical differences Vue developers usually feel first
+
+### 1. The visible state host is the controller instance
+
+A Vue developer often expects to see:
+
+```typescript
+const count = ref(0);
+```
+
+A Zova reader will more often see:
+
+```typescript
+count: number = 0;
+```
+
+The important idea is not only less syntax. The important idea is that the framework is making the bean instance itself the main business-facing state surface.
+
+### 2. Derived state is written as instance wiring
+
+Instead of thinking:
+
+```typescript
+const count2 = computed(() => `=== ${count.value} ===`);
+```
+
+Zova often reads more like:
+
+```typescript
+protected async __init__() {
+  this.count2 = this.$computed(() => {
+    return `=== ${this.count} ===`;
+  });
+}
+```
+
+That makes derived state feel like part of object initialization rather than only part of a local `setup()` assembly.
+
+### 3. Actions are ordinary methods
+
+Instead of scattering behavior through closures returned from `setup()`, Zova often keeps page or component actions as plain methods on the controller instance.
+
+That is one reason Zova business code can read more like application controller code.
+
+### 4. Route state is part of the page-controller surface
+
+A Vue reader often looks for `useRoute()` first.
+
+In Zova, a page controller often expects route-aware behavior through members such as:
+
+- `$route`
+- `$params`
+- `$query`
+
+For the route-oriented mental model, also see [Page Route Guide](/frontend/page-route-guide).
+
+### 5. State sharing is more architecture-driven
+
+Vue projects often combine several independent techniques:
+
+- props and emits
+- composables
+- `provide/inject`
+- store layers
+
+Zova tries to keep more of that within the bean and scope architecture, so the first question becomes less "which unrelated mechanism should I use?" and more "which bean owns this state and which scope should that bean live in?"
+
+### 6. Render is controller-oriented, not only component-file-oriented
+
+A Vue reader might assume that moving code out of a large page means immediately creating more composables or child components.
+
+In Zova, a common growth path is:
+
+- start with a single page controller
+- split render into a render bean when the page grows
+- split style into a style bean when needed
+- extract business state or logic into service beans when that becomes clearer
+
+That growth path is one of the main reasons you should read Zova pages through the page/controller architecture instead of through a generic component-file lens.
+
+## A practical reading order for Vue developers
+
+If you want the shortest path from Vue familiarity to Zova fluency, use this order:
+
+1. [Foundation](/frontend/foundation)
+2. [Design Principles](/frontend/design-principles)
+3. [IoC and Beans](/frontend/ioc-and-beans)
+4. [Page Guide](/frontend/page-guide)
+5. [Component Guide](/frontend/component-guide)
+6. [Model Architecture](/frontend/model-architecture)
+7. [Page Route Guide](/frontend/page-route-guide)
+8. [Behavior Guide](/frontend/behavior-guide)
+
+Use this order when:
+
+- you already know Vue
+- you want to read Zova source code accurately
+- you want to avoid rewriting framework-specific code back toward generic Vue habits
+
+## Common mistakes to avoid
+
+### Mistake 1: "This should become a normal Vue SFC"
+
+Usually the better question is whether the existing controller, render bean, style bean, or service/model bean boundaries are already the intended Zova architecture.
+
+### Mistake 2: "If I do not see `ref`, there is no real reactivity"
+
+The reactive foundation is still there. The framework is simply exposing a different authoring surface.
+
+### Mistake 3: "IoC only matters for dependency injection"
+
+In Zova, IoC is tied to structure, sharing scope, extensibility, and long-term maintainability.
+
+### Mistake 4: "Route state should always be pulled locally by composables"
+
+For page controllers, route-aware behavior is deliberately pushed into the controller surface so the page model stays cohesive.
+
+### Mistake 5: "Model state is just another local store choice"
+
+The model layer is one of Zova’s larger architectural answers for unified state categories, SSR-aware state handling, caching, and persistence-oriented behavior.
+
+## Edition note
+
+This reading guide is about the shared Zova frontend architecture, not about one UI library.
+
+That means the architectural reading model applies across Cabloy Basic and Cabloy Start. However, UI-sensitive examples can still diverge:
+
+- Cabloy Basic public examples currently align with DaisyUI + Tailwind CSS
+- Cabloy Start aligns with Vuetify-oriented UI workflows and may differ in modules, SSR site baselines, and project assets
+
+So when your task becomes UI-specific rather than architecture-specific, detect the active edition before assuming a component or theme workflow.
+
+## Final takeaway
+
+If Vue teaches you to think in terms of reactive primitives and local composition, Zova asks you to think in terms of reactive framework-managed objects with explicit architectural roles.
+
+That is the mental shift that makes the rest of the source tree much easier to read.

package/cabloy-docs/frontend/router-tabs-admin-web-comparison.md

@@ -0,0 +1,206 @@
+# Router Tabs Admin and Web Comparison
+
+This guide compares how the router-tabs mechanism appears in the Admin and Web layouts in Zova within the Cabloy monorepo.
+
+Read this together with:
+
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)
+
+## Why this comparison matters
+
+The current Cabloy Basic frontend source uses one shared router-tabs state model in more than one layout.
+
+That means future contributors should not assume that the mechanism is identical to one specific tab-row UI.
+
+The shared contract is the workbench-state and route-grouping model. The visible layout expression can vary.
+
+## The shared foundation
+
+Both layouts reuse the same router-tabs model.
+
+They both depend on the same ideas:
+
+- `tabKey` as the level-1 workspace grouping identity
+- `componentKey` as the page-instance identity
+- tab activation through router navigation
+- keep-alive integration through the router-tabs controller
+- cache, pruning, and item-state behavior in the shared model
+
+Representative shared implementation:
+
+- `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts`
+- `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/component/routerViewTabs/controller.tsx`
+
+## The main difference in one sentence
+
+The Admin layout shows the workbench model as an explicit two-level tab UI, while the Web layout uses the same underlying state model but presents the top-level workspaces through a horizontal menu-like surface.
+
+## Admin layout view
+
+Representative sources:
+
+- `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`
+
+### What users see
+
+In the Admin layout, users can see the two levels directly:
+
+- a first row for workspace-level tabs
+- a second row for task-level items inside the current workspace
+
+This is the clearest visual expression of the router-tabs workbench model.
+
+### How level-1 behaves
+
+In Admin, level-1 tabs are rendered from `RouteTab` records.
+
+The visible title and icon are usually derived from menu-backed tab info rather than from the active inner page title.
+
+That means the first row behaves like a business workspace selector.
+
+### How level-2 behaves
+
+In Admin, level-2 items are rendered from `tabCurrent.items`.
+
+The second row shows task-level state such as:
+
+- page title
+- dirty state
+- create/edit form state
+- close actions for inner work items
+
+The Admin layout also deliberately skips the anchor item when rendering the second row. That keeps the second level focused on additional work items rather than on the workspace anchor itself.
+
+### When Admin is the best mental model
+
+Use the Admin layout as the primary mental model when explaining:
+
+- why router tabs are two-level in business meaning
+- how one workspace can hold several work items
+- how page metadata affects task-level presentation
+
+## Web layout view
+
+Representative sources:
+
+- `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`
+
+### What users see
+
+In the Web layout, the same router-tabs model is presented differently.
+
+The top-level workspace surface is rendered more like a horizontal menu, with support for folders, leaves, and separators.
+
+This means the visual experience is less like an IDE-style double tab bar and more like a menu-driven workspace shell.
+
+### How top-level behavior works
+
+The Web layout still uses `$$modelTabs.tabs` as the current workspace list.
+
+However, instead of rendering a lifted tab row plus a bordered second row, it renders menu items that can:
+
+- behave as top-level workspace entries
+- expand folders
+- navigate through menu leaf links
+- highlight the active workspace
+
+This is an important reminder that router tabs are not only a cosmetic tab component. They are a route-grouping and workbench-state mechanism that a layout can present in different ways.
+
+### How grouping differs visually
+
+In the Web layout, the grouping meaning can still be present even when the UI does not emphasize the second level in the same direct way as Admin.
+
+That means the mechanism is still doing grouping and workspace-state management, but the visual expression is tuned for a different frontend shell style.
+
+### When Web is the better mental model
+
+Use the Web layout as the primary mental model when explaining:
+
+- that the router-tabs model is reusable beyond one tab-row UI
+- that top-level workspaces can be expressed through a menu-like shell
+- that the framework contract is broader than the Admin visual treatment
+
+## Comparison table
+
+| Topic                     | Admin layout                           | Web layout                                             |
+| ------------------------- | -------------------------------------- | ------------------------------------------------------ |
+| Shared model              | router-tabs model                      | router-tabs model                                      |
+| Top-level presentation    | explicit lifted tab row                | horizontal menu-like workspace surface                 |
+| Second-level presentation | explicit bordered task row             | not emphasized in the same direct double-row way       |
+| Primary user signal       | workbench tabs                         | menu-oriented workspace navigation                     |
+| Best use as explanation   | business meaning of two levels         | portability of the shared mechanism                    |
+| Risk if misread           | assuming Admin UI is the only contract | assuming menu presentation means tabs are not involved |
+
+## What is shared and should stay shared
+
+Future contributors should preserve these shared behaviors across layouts unless there is an intentional framework change:
+
+- route-to-workspace mapping
+- `tabKey` and `componentKey` semantics
+- activation through router navigation
+- keep-alive integration
+- cache and pruning behavior in the shared model
+
+If one layout needs different visuals, it should change the presentation layer first rather than casually rewriting the shared state semantics.
+
+## What may differ safely by layout
+
+These areas are more naturally layout-specific:
+
+- how top-level workspaces are styled
+- whether the second level is displayed explicitly
+- icon placement and density
+- close-button visibility
+- whether the shell feels tab-centric or menu-centric
+
+The key rule is:
+
+- layout-specific UI may vary
+- workbench-state semantics should stay intentional
+
+## Common mistakes to avoid
+
+Avoid these assumptions:
+
+### Mistake 1: Admin rendering is the whole contract
+
+This can lead contributors to hard-code two-row visual assumptions into framework-level decisions.
+
+### Mistake 2: Web rendering means router tabs are not involved
+
+This can lead contributors to ignore the shared state model and accidentally break workspace continuity.
+
+### Mistake 3: layout differences justify changing `tabKey` or `componentKey` semantics
+
+Usually they do not.
+
+Those keys belong to the shared routing and state model, not only to one specific layout theme.
+
+## Recommended guidance for future docs and implementation work
+
+When documenting or extending this area:
+
+1. explain the shared mechanism first
+2. use Admin as the clearest business-meaning example
+3. use Web as the proof that the mechanism is presentation-independent
+4. keep route-meta guidance layout-neutral unless a real layout-specific exception exists
+
+## Summary
+
+The Admin and Web layouts do not represent two different router-tabs mechanisms.
+
+They represent two different UI expressions of the same underlying workbench-state model.
+
+Admin is the clearest example of explicit two-level tabs. Web is the clearest example that the same grouping and state model can power a different shell style without changing the core semantics.
+
+## See also
+
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)

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

@@ -0,0 +1,106 @@
+# Router Tabs Introduction
+
+This guide is the landing page for the router-tabs documentation set in Zova within the Cabloy monorepo.
+
+Use it to understand what the router-tabs mechanism is, which questions each companion document answers, and what order to read them in.
+
+## What router tabs are
+
+Router tabs provide a workbench-style navigation model for frontend layouts that need more than a simple route-transition model.
+
+In the current Cabloy Basic source, the mechanism supports:
+
+- stable workspace-level grouping
+- task-level page-instance switching inside a workspace
+- keep-alive integration for routed work items
+- optional cache restoration for workbench state
+- more than one layout presentation on top of the same shared model
+
+That means router tabs are not only a visual tab bar. They are a route-grouping and workbench-state mechanism.
+
+## Start here when you need to answer these questions
+
+### What business problem does this solve?
+
+Read [Router Tabs Overview](/frontend/router-tabs-overview).
+
+This document explains:
+
+- why admin-style applications need more than a simple menu transition model
+- why workspace identity and task identity should stay separate
+- how the mechanism supports parallel work and workbench continuity
+
+### How does the mechanism work in code?
+
+Read [Router Tabs Mechanism](/frontend/router-tabs-mechanism).
+
+This document explains:
+
+- the shared state model
+- `tabKey` and `componentKey`
+- page metadata, keep-alive, cache, and pruning behavior
+- the relationship between the shared model and concrete layouts
+
+### How should I author route meta for this?
+
+Read [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook).
+
+This document explains:
+
+- practical recipes for `tabKey`
+- when to use `componentKeyMode`
+- when to define explicit `componentKey`
+- when to disable keep-alive
+- common authoring mistakes to avoid
+
+### How do Admin and Web layouts differ?
+
+Read [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison).
+
+This document explains:
+
+- what both layouts share
+- how Admin exposes the two-level model directly
+- how Web reuses the same model with a different shell style
+- why layout-specific UI should not be confused with shared mechanism semantics
+
+## Recommended reading paths
+
+### Product or architecture perspective
+
+Recommended order:
+
+1. [Router Tabs Overview](/frontend/router-tabs-overview)
+2. [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
+3. [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+
+### Frontend implementation perspective
+
+Recommended order:
+
+1. [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+2. [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)
+3. [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
+
+### Maintenance and refactor perspective
+
+Recommended order:
+
+1. [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+2. [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
+3. `.docs-internal/architecture/router-tabs-design-boundaries.md`
+
+## Scope boundary
+
+The public router-tabs docs explain the shared frontend mechanism and how to use it.
+
+For internal design boundaries, maintenance invariants, and refactor safety rules, see:
+
+- `.docs-internal/architecture/router-tabs-design-boundaries.md`
+
+## See also
+
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)
+- [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)