cabloy 5.1.61 → 5.1.63

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
 

package/cabloy-docs/frontend/resource-entry-page-deep-dive.md

@@ -0,0 +1,271 @@
+# Resource Entry Page Deep Dive
+
+This guide explains the runtime path of a resource entry page in Zova through the current public Cabloy Basic source.
+
+Use this page when you want to understand:
+
+- how a `/rest/resource/...` entry route becomes a working entry page
+- where the thin `rest-resource` page shell stops
+- how `basic-pageentry` takes over the deeper entry runtime
+- where `blockForm` and `blockToolbarRow` fit into that runtime
+- how submit flow and page-meta updates connect back to the routed shell
+
+## Why this page exists
+
+Several existing docs already explain important parts of the story:
+
+- [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch) explains the consumer-side handoff before the deeper runtime begins
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood) explains the module-level runtime bridge
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map) explains the shortest file path into the module
+- [Form Guide](/frontend/form-guide) and [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) explain the form runtime
+- [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) explains the cross-layer `formScene -> formMeta -> pageMeta` chain
+
+What those pages do not isolate directly is the one cohesive entry-page runtime path from route entry into the deeper Basic form/page runtime.
+
+That is the gap this page fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `rest-resource` declares generic resource entry routes
+2. generated page wrappers bind those routes to `ControllerPageEntry`
+3. `ControllerPageEntry` is a thin shell that resolves `resource`, `id`, and `formScene`
+4. that shell derives `formMeta`, loads `formSchema`, and renders `formSchema.rest.blocks`
+5. those blocks usually enter `basic-pageentry:blockPageEntry`
+6. `blockPageEntry` becomes the deeper runtime owner for `ModelResource`, `formData`, submit flow, and page-meta updates
+7. `blockForm` bridges into `ZForm`
+8. `blockToolbarRow` renders the action row from the shared page-entry render context
+
+That means the entry page is not “one big page controller that does everything.” It is a route-shell plus downstream reusable block runtime.
+
+This page focuses only on the entry-page branch. For the broader module-level shell-to-runtime map shared by both list and entry pages, keep [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map) as the general reference.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/routes.ts`
+2. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/entry.ts`
+3. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
+4. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/.metadata/index.ts`
+5. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+6. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockForm/controller.tsx`
+7. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockToolbarRow/controller.tsx`
+
+That order moves from public route surface, to route wrapper, to resource entry shell, to Basic block registry, to the real entry-page runtime owner, then to the form bridge and action row.
+
+## Runtime path by layer
+
+### 1. Route entry
+
+The public route surface lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/routes.ts
+```
+
+The entry routes are:
+
+- `:resource/create`
+- `:resource/:id/:formScene?`
+
+This already shows the public entry-page contract:
+
+- resource identity comes from the route
+- row identity comes from `id`
+- scene can come explicitly from `formScene`, or later fall back by runtime rule
+
+The shared `tabKey(route)` also shows that entry pages stay grouped under one resource-oriented workspace rather than creating a brand-new workspace per row.
+
+### 2. Generated page wrapper
+
+The route component wrapper lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/entry.ts
+```
+
+This file is thin but important.
+
+It shows that the page does not enter runtime through ad hoc local setup code. Instead, it enters the standard Zova page-controller path through:
+
+- `createZovaComponentPage(ControllerPageEntry, ...)`
+
+That means the route entry is still controller-oriented from the beginning.
+
+### 3. Thin `rest-resource` entry shell
+
+The actual entry shell lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx
+```
+
+Its main jobs are:
+
+- resolve `resource`
+- resolve `entryId`
+- resolve `formScene`
+- derive `formMeta`
+- resolve `formProvider`
+- resolve `formSchema`
+- autoload form API schemas
+- render `formSchema?.rest?.blocks`
+
+This is the first key architectural boundary:
+
+- `ControllerPageEntry` is a **thin shell**
+- it does not own the whole entry runtime by itself
+
+Its role is to interpret route context, resolve resource/form schema state, and let schema-defined blocks take over the deeper behavior.
+
+### 4. `basic-pageentry` block registry
+
+The Basic block registry lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pageentry/src/.metadata/index.ts
+```
+
+This file shows the reusable entry-page runtime surface exported by the module:
+
+- `basic-pageentry:blockPageEntry`
+- `basic-pageentry:blockForm`
+- `basic-pageentry:blockToolbarRow`
+
+That matters because the deeper entry-page behavior is not hidden inside one giant page file.
+
+It is split into reusable controller-backed blocks.
+
+### 5. `blockPageEntry` becomes the deeper runtime owner
+
+The most important current Basic file is:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx
+```
+
+This is the deeper entry runtime owner.
+
+Its main jobs are:
+
+- resolve selector-backed `ModelResource`
+- derive `formMeta` and `schemaScene`
+- derive `formProvider`, `formSchema`, and `formData`
+- prepare the shared JSX render context
+- autoload view/query data
+- own submit flow through `submitData(...)`
+- update page meta through `setPageMeta(...)`
+- expose `$$pageEntry` into the render context for downstream blocks
+
+This is the second key architectural boundary:
+
+- the route shell chooses the resource/scene context
+- `blockPageEntry` owns the deeper entry-page runtime once blocks are rendered
+
+### 6. `blockForm` bridges into `ZForm`
+
+The form bridge lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockForm/controller.tsx
+```
+
+This controller does not re-derive entry-page state.
+
+Instead, it consumes `$$pageEntry` from the host render context and passes the canonical page-entry-owned values into `ZForm`, including:
+
+- `data`
+- `schema`
+- `schemaScene`
+- `formMeta`
+- `formProvider`
+- `formScope`
+- submit callback
+- change callback
+
+This is the clearest source-confirmed proof that `blockForm` is a bridge, not the main owner of entry-page orchestration.
+
+### 7. `blockToolbarRow` renders the action row
+
+The action row lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockToolbarRow/controller.tsx
+```
+
+Its role is to consume the same `$$pageEntry` render context and render action buttons based on:
+
+- current permissions
+- current `formScene`
+- action render definitions
+
+This is important because it shows that action visibility and entry-page state stay attached to the same host context, instead of being recomputed independently by unrelated components.
+
+## The shared handoff model
+
+A useful rule is:
+
+- the route shell resolves context
+- schema blocks choose which entry-page runtime pieces should appear
+- `blockPageEntry` becomes the shared host runtime owner
+- `blockForm` and `blockToolbarRow` are specialized consumers of that host-owned context
+
+That means the shared handoff is through `$$pageEntry`, not through scattered local state.
+
+## Submit flow and page-meta flow
+
+The entry runtime also connects cleanly to the wider shell/task model.
+
+Inside `blockPageEntry`:
+
+- data loading initializes page state
+- submit flow delegates to `ModelResource` mutation logic
+- `setPageMeta(...)` updates the routed shell title / dirty / form-scene state
+
+This is why the entry-page runtime should be read together with [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) and [Page Meta Guide](/frontend/page-meta-guide).
+
+## What this guide does not re-explain
+
+This page does **not** fully re-explain:
+
+- the internals of `ZForm` itself -> see [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- the full `formScene -> formMeta -> pageMeta` bridge -> see [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide)
+- the routed-shell host mechanics -> see [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+
+Its job is only to explain how the entry page runtime is assembled across route shell, Basic blocks, and shared host context.
+
+## Debugging checklist
+
+If a resource entry page behaves unexpectedly, ask:
+
+1. is the route resolving the expected `resource`, `id`, and `formScene`?
+2. is `ControllerPageEntry` loading the expected `formSchema.rest.blocks`?
+3. is the expected `basic-pageentry:*` block actually present in the schema?
+4. is `blockPageEntry` resolving the expected `ModelResource` selector state?
+5. is `blockForm` receiving the correct `schemaScene`, `formMeta`, and `formData`?
+6. is `blockToolbarRow` consuming the expected `$$pageEntry` context?
+7. is submit/page-meta flow failing in `blockPageEntry`, rather than in the outer route shell?
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want the resource module bridge: [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- if you want the shortest source map: [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
+- if you want the form runtime branch: [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- if you want the `formScene -> formMeta -> pageMeta` chain: [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide)
+- if you want action visibility rules: [Permission, formScene, and Action Visibility Guide](/frontend/permission-formscene-action-visibility-guide)
+
+## Final takeaway
+
+The most accurate way to read a resource entry page in the current Basic frontend is:
+
+- `rest-resource` entry page is the thin route shell
+- schema-defined blocks choose the deeper runtime pieces
+- `basic-pageentry:blockPageEntry` owns the real entry runtime
+- `blockForm` and `blockToolbarRow` consume the same shared host context
+- submit flow and page-meta flow live in that deeper runtime layer
+
+That is the source-confirmed entry-page runtime path in the current Cabloy Basic frontend architecture.