cabloy 5.1.60 → 5.1.62

package/cabloy-docs/frontend/permission-formscene-action-visibility-guide.md

@@ -0,0 +1,263 @@
+# Permission, formScene, and Action Visibility Guide
+
+This guide explains how action visibility works in current Cabloy Basic entry pages when `formScene` participates in the decision.
+
+Use this page when you want to understand:
+
+- how `permissionHint.formScene` works
+- how it interacts with `$$pageEntry.formMeta.formScene`
+- how that differs from `$passport.checkPermission(...)`
+- why some actions can be scene-gated while others cannot
+- why bulk actions do not currently support `formScene`
+
+## Why this page exists
+
+Several existing docs already explain nearby pieces:
+
+- [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) explains how `formScene` becomes `formMeta`, then `pageMeta`
+- [Page Meta Guide](/frontend/page-meta-guide) explains shell/task presentation
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) and related resource-model docs explain permissions as part of resource ownership
+
+What those pages do not isolate directly is the specific runtime rule for entry-page action visibility.
+
+That is the gap this page fills.
+
+In the current Basic source, `formScene` participates in action visibility as a **UI visibility filter** layered in front of the normal permission authorization check.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. page-entry runtime decides the current `formScene`
+2. `formMetaFromFormScene(...)` derives `formMeta`
+3. `$$pageEntry.formMeta.formScene` becomes the current scene surface for entry-page blocks
+4. `blockToolbarRow` reads `permissionHint.formScene`
+5. if the current scene does not match, the action is hidden immediately
+6. if the scene matches, `$passport.checkPermission(...)` still decides whether the action is allowed by permission rules
+7. the action renders only if both checks pass
+
+That means `formScene` is not itself a permission engine. It is a scene-aware visibility prefilter.
+
+## What this guide is not
+
+This page is not a general permission guide for every frontend action surface.
+
+It is specifically about the current **entry-page** action visibility flow.
+
+It is also not a guide to page-meta propagation. `pageMeta.formMeta` is part of the surrounding story, but the actual visibility authority for entry-page actions is the local page-entry runtime context.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/utils.ts`
+2. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+3. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockToolbarRow/controller.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/permissions.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formActionRow.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/tableActionRow.ts`
+7. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/tableActionBulk.ts`
+8. optional comparison: `zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx`
+
+That order moves from scene/meta translation, to page-entry runtime ownership, to action-row filtering, to permission-hint typing, and finally to the bulk-action limitation and row-action comparison.
+
+## Visibility flow step by step
+
+### 1. `formScene` becomes canonical runtime metadata
+
+The canonical helper lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-form/src/lib/utils.ts
+```
+
+The current source confirms:
+
+- `view` -> `formMode: 'view'`
+- `create` -> `formMode: 'edit', editMode: 'create'`
+- `edit` -> `formMode: 'edit', editMode: 'update'`
+
+This matters because action visibility does not read an arbitrary raw string from anywhere in the app. It reads the current page-entry scene after that scene has already become part of the page-entry runtime metadata.
+
+### 2. `blockPageEntry` exposes the current scene through `$$pageEntry`
+
+The key entry-page runtime file is:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx
+```
+
+This controller:
+
+- resolves `formScene`
+- computes `formMeta`
+- builds the shared JSX render context
+- exposes `$$pageEntry` into that context
+
+That is the key boundary for action visibility:
+
+- entry-page actions do not need to rediscover the current scene
+- they can read it from `$$pageEntry.formMeta.formScene`
+
+## 3. `blockToolbarRow` checks scene first, then permission
+
+The most important source file for this guide is:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockToolbarRow/controller.tsx
+```
+
+Its action loop does two different checks:
+
+1. `_checkFormScene(permissionHint)`
+2. `$passport.checkPermission(...)`
+
+The order matters.
+
+### Scene prefilter
+
+`_checkFormScene(...)`:
+
+- reads `$$pageEntry.formMeta.formScene`
+- reads `permissionHint?.formScene`
+- accepts a single scene or an array of scenes
+- treats no `formScene` hint as “all scenes”
+
+If the scene does not match, the action does not continue into the permission check.
+
+### Authorization check
+
+Only after the scene passes does the controller call:
+
+- `$passport.checkPermission(this.permissions, actionName, permissionHint)`
+
+This is the critical source-confirmed distinction:
+
+- **scene filtering** decides whether this action should even be considered in the current page-entry scene
+- **permission checking** decides whether the user is allowed to perform it
+
+## 4. What `permissionHint.formScene` really means
+
+`permissionHint.formScene` should be read as:
+
+- a UI visibility filter tied to the current page-entry scene
+
+It should **not** be read as:
+
+- a replacement for permission authorization
+- a generic global permission-engine rule
+- a page-meta-driven shell rule
+
+A practical reading rule is:
+
+- if the scene is wrong, hide the action
+- if the scene is right, still run the real permission check
+
+## 5. What the permission types confirm
+
+The permission hint types live in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/permissions.ts
+```
+
+The important source-confirmed detail is:
+
+- `IPermissionHintGeneral` can carry `formScene`
+- `IPermissionHintTableActionRow` can carry `formScene`
+- `IPermissionHintTableActionBulk` does **not** carry `formScene`
+
+This matches the current runtime split:
+
+- entry-page row/form action visibility can be scene-aware
+- bulk-action visibility is not scene-aware in the same way today
+
+## 6. Row/form action types vs bulk action types
+
+The row/form action option types live in:
+
+- `a-openapi/src/types/resource/formActionRow.ts`
+- `a-openapi/src/types/resource/tableActionRow.ts`
+
+They both use `permission?: IPermissionHintTableActionRow`.
+
+That means row-style action definitions can express `formScene` in their permission hints.
+
+By contrast, bulk action options live in:
+
+- `a-openapi/src/types/resource/tableActionBulk.ts`
+
+That type uses:
+
+- `permission?: IPermissionHintTableActionBulk`
+
+And that bulk hint type does not have `formScene`.
+
+This is the clearest public type-level explanation for the current limitation.
+
+## 7. Why bulk actions are different today
+
+Bulk actions are typed around bulk permission hints, not row/form-scene hints.
+
+So in current Basic source, you should not claim that bulk actions support scene-based filtering the same way entry-page toolbar actions do.
+
+This is not only a docs distinction. It is a source-confirmed contract distinction.
+
+## 8. Comparison with table row actions
+
+A useful comparison file is:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx
+```
+
+This table-row action surface uses permission checks, but it does not add the same local page-entry `formScene` prefilter path as `blockToolbarRow`.
+
+That makes the current entry-page toolbar flow more specific:
+
+- it is tied to entry-page runtime context
+- it is not the universal rule for every action surface in the frontend
+
+## 9. Boundary with page meta
+
+A common confusion is to think that because `formMeta` also becomes part of page meta, page meta is the authority for action visibility.
+
+That is not the current source-confirmed rule.
+
+The better boundary is:
+
+- `pageMeta.formMeta` is shell/task presentation state
+- `$$pageEntry.formMeta.formScene` is the local page-entry runtime surface that `blockToolbarRow` reads for scene filtering
+
+So for action visibility, the local page-entry context is the authority.
+
+## 10. Bulk-action limitation
+
+The current public Basic source supports this rule clearly:
+
+- row/form action hints can be scene-aware
+- bulk action hints are not scene-aware today
+
+If a contributor needs scene-aware bulk visibility, they should first verify whether the type and runtime contracts are being extended, rather than assuming the row-action rule applies automatically.
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want the full `formScene -> formMeta -> pageMeta -> shell/tab` bridge, read [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide)
+- if you want the broader entry-page runtime path, read [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+- if you want the list-page row/bulk contrast, read [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- if you want shell/task presentation semantics, read [Page Meta Guide](/frontend/page-meta-guide)
+- if you want the underlying resource permission/model context, read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+
+## Final takeaway
+
+The most accurate rule for current Cabloy Basic entry-page action visibility is:
+
+- `permissionHint.formScene` is a scene-aware visibility prefilter
+- `$$pageEntry.formMeta.formScene` is the current scene source
+- `$passport.checkPermission(...)` is still the actual authorization check
+- the action renders only if both layers pass
+- bulk actions do not currently carry `formScene` in their permission hints
+
+That is the source-confirmed `permission / formScene / action visibility` path in the current Basic frontend architecture.

package/cabloy-docs/frontend/quickstart.md

@@ -127,8 +127,10 @@ This is why route metadata, guards, aliases, and theme/header/menu behavior shou
 Read together with:
 
 - [Page Route Guide](/frontend/page-route-guide)
-- [Navigation Guards Guide](/frontend/navigation-guards-guide)
 - [Route Alias Guide](/frontend/route-alias-guide)
+- [Navigation Guards Guide](/frontend/navigation-guards-guide)
+- [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
 - [Theme Guide](/frontend/theme-guide)
 
 ## Step 6: reach the first routed page
@@ -150,6 +152,8 @@ Read next:
 - [Frontend CLI](/frontend/cli)
 - [Page Guide](/frontend/page-guide)
 - [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)
 
 ## Step 7: understand menu and CLI ergonomics
 
@@ -173,6 +177,8 @@ Read next:
 - [Frontend Scripts](/frontend/scripts)
 - [Environment and Config Guide](/frontend/environment-config-guide)
 - [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)
 - [Theme Guide](/frontend/theme-guide)
 
 ### I want to understand startup and routing
@@ -180,14 +186,20 @@ Read next:
 - [System Startup Guide](/frontend/system-startup-guide)
 - [App Startup Guide](/frontend/app-startup-guide)
 - [Page Route Guide](/frontend/page-route-guide)
-- [Navigation Guards Guide](/frontend/navigation-guards-guide)
 - [Route Alias Guide](/frontend/route-alias-guide)
+- [Navigation Guards Guide](/frontend/navigation-guards-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 Layout Integration](/frontend/router-tabs-layout-integration)
 
 ### I want to create my first page
 
 - [Frontend CLI](/frontend/cli)
 - [Page Guide](/frontend/page-guide)
 - [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)
 
 ### I need edition-sensitive guidance
 
@@ -200,4 +212,8 @@ Read next:
 
 - [Frontend (Zova)](/frontend/introduction)
 - [Frontend Foundation](/frontend/foundation)
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
 - [Design Principles](/frontend/design-principles)

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.