cabloy 5.1.60 → 5.1.62

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.

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

@@ -0,0 +1,279 @@
+# Resource List Page Deep Dive
+
+This guide explains the runtime path of a resource list page in Zova through the current public Cabloy Basic source.
+
+Use this page when you want to understand:
+
+- how a `/rest/resource/:resource` route becomes a working list page
+- where the thin `rest-resource` list shell stops
+- how `basic-page:blockPage` takes over the deeper list runtime
+- where `blockFilter`, `blockTable`, and `blockPager` fit into that runtime
+- how `ZTable` and `ModelResource` cooperate under the list-page shell
+
+## Why this page exists
+
+Several existing docs already explain important parts of the story:
+
+- [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-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
+- [Table Guide](/frontend/table-guide) and [Zova Table Under the Hood](/frontend/zova-table-under-the-hood) explain the table runtime
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook) explains authoring-oriented CRUD assembly
+
+What those pages do not isolate directly is the one cohesive list-page runtime path from route entry into the deeper Basic page and table runtime.
+
+That is the gap this page fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `rest-resource` declares the generic resource list route
+2. a generated page wrapper binds that route to `ControllerPageResource`
+3. `ControllerPageResource` is a thin shell that resolves the current `resource`, loads top-level schema state, and renders `schemaRow.rest.blocks`
+4. those blocks usually enter `basic-page:blockPage`
+5. `blockPage` becomes the deeper list runtime owner for filter state, paging state, query state, and resource-backed list data
+6. `blockFilter`, `blockTable`, and `blockPager` are specialized consumers of that shared page runtime/context
+7. `ZTable` is the final schema-driven table runtime endpoint under that list-page runtime
+
+That means the resource list page is not one controller doing everything. It is a route shell plus downstream reusable list/runtime blocks.
+
+This page focuses only on the list-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/resource.ts`
+3. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx`
+4. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+5. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+6. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilter/controller.tsx`
+7. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+8. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPager/controller.tsx`
+9. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
+10. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+
+That order moves from public route surface, to route wrapper, to list shell, to resource owner, to deeper list runtime, and finally to the schema-driven table runtime endpoint.
+
+## Runtime path by layer
+
+### 1. Route list entry
+
+The public route surface lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/routes.ts
+```
+
+The list route is:
+
+- `:resource`
+
+That already shows the public list-page contract:
+
+- the route is generic
+- runtime identity comes from `route.params.resource`
+- the shared `tabKey(route)` keeps list and entry pages grouped under one resource-oriented workspace
+
+### 2. Generated page wrapper
+
+The list-page wrapper lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/resource.ts
+```
+
+This file shows that the route enters runtime through the standard Zova page-controller path:
+
+- `createZovaComponentPage(ControllerPageResource, ...)`
+
+That means the list page still begins as a controller-oriented page surface, not as ad hoc local route code.
+
+### 3. Thin `rest-resource` list shell
+
+The list shell lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx
+```
+
+Its main jobs are:
+
+- resolve the current selector-backed `ModelResource`
+- autoload select API schemas
+- read `schemaRow?.rest?.blocks`
+- render those blocks through `ZovaJsx`
+
+This is the first key architectural boundary:
+
+- `ControllerPageResource` is a **thin list shell**
+- it does not own the whole list runtime by itself
+
+Its role is to interpret resource context, load top-level schema state, and let schema-defined blocks take over the deeper behavior.
+
+### 4. `ModelResource` as the stable owner boundary
+
+The owner model lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts
+```
+
+Its main jobs are:
+
+- bootstrap the resource API path
+- expose `permissions`
+- expose schema surfaces such as `schemaFilter` and `schemaRow`
+- expose `select(query)` for list data
+- expose item/view/create/update/delete mutation/query helpers
+
+This is the core owner boundary for the list page.
+
+It is the stable resource-level runtime, even though the deeper list behavior is later assembled through Basic blocks.
+
+### 5. `basic-page:blockPage` becomes the deeper list runtime owner
+
+The most important current Basic list-runtime file is:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx
+```
+
+This controller becomes the deeper owner for:
+
+- selector-backed `ModelResource`
+- `queryFilterData`
+- `queryPaged`
+- computed `query`
+- `select(this.query)` list data
+- `schemaFilter`, `schemaRow`, and `permissions`
+- the shared page JSX/render context (`$$page`)
+- permission-driven table-meta refresh through `tableRef.refreshMeta()`
+
+This is the second key architectural boundary:
+
+- the route shell chooses the resource context
+- `blockPage` owns the real list/runtime state after blocks are rendered
+
+### 6. `blockFilter` consumes the shared list-page context
+
+The filter block lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilter/controller.tsx
+```
+
+This block is a specialized consumer of the shared `$$page` runtime context.
+
+Its role is to turn schema-driven filter UI into filter-state updates that flow back into the list-page query path.
+
+That means filter state is not a separate unrelated subsystem. It is part of the shared list-page runtime owned by `blockPage`.
+
+### 7. `blockTable` bridges the page runtime into `ZTable`
+
+The table bridge lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx
+```
+
+This controller consumes `$$page` and passes the canonical page-owned values into `ZTable`, including:
+
+- `data`
+- `schemaRow`
+- `tableScope`
+
+It also captures the table controller ref back onto `$$page.tableRef`.
+
+This is the clearest proof that `blockTable` is a bridge into table runtime, not the main owner of list state.
+
+### 8. `blockPager` consumes paged state
+
+The pager block lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPager/controller.tsx
+```
+
+Its role is to read paged state and delegate page changes back into the shared list-page runtime.
+
+Like the filter and table blocks, it is another specialized consumer of the page runtime owned by `blockPage`.
+
+### 9. `ZTable` is the schema-driven runtime endpoint
+
+The deeper table endpoint lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx
+zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx
+```
+
+This table runtime:
+
+- loads schema properties for table rendering
+- computes table metadata and columns
+- creates column renderers
+- turns schema-driven row metadata into visible table output
+
+This is the final endpoint under the list-page runtime chain.
+
+## The shared handoff model
+
+A useful rule is:
+
+- the route shell resolves resource context
+- schema-defined blocks choose which deeper list runtime pieces should appear
+- `blockPage` becomes the shared host runtime owner
+- `blockFilter`, `blockTable`, and `blockPager` are specialized consumers of that host-owned context
+- `ZTable` is the final schema-driven render endpoint for rows and cells
+
+That means the shared handoff is through `$$page`, not through scattered local page state.
+
+## What this guide does not re-explain
+
+This page does **not** fully re-explain:
+
+- the internals of `ModelResource` ownership -> see [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- the internals of `ZTable` itself -> see [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- table authoring recipes -> see [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+
+Its job is only to explain how the list-page runtime is assembled across route shell, resource owner, Basic blocks, and table runtime.
+
+## Debugging checklist
+
+If a resource list page behaves unexpectedly, ask:
+
+1. is the route resolving the expected `resource`?
+2. is `ControllerPageResource` loading the expected `schemaRow.rest.blocks`?
+3. is the expected `basic-page:*` block actually present in the schema?
+4. is `blockPage` resolving the expected `ModelResource` selector state?
+5. is filter state flowing into `queryFilterData` as expected?
+6. is pager state flowing into `queryPaged` as expected?
+7. is `blockTable` receiving the expected `schemaRow`, `data`, and `permissions` scope?
+8. is table meta stale because the permission-driven refresh path is not firing where expected?
+
+## 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 owner internals behind this runtime: [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- if you want the narrower filter/query/select data path: [Filter to Query to Select Data Flow Guide](/frontend/filter-query-select-data-flow-guide)
+- if you want the table runtime branch: [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- if you want row/bulk action visibility and permission gating: [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+- if you want the entry-page counterpart: [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+## Final takeaway
+
+The most accurate way to read a resource list page in the current Basic frontend is:
+
+- `rest-resource` list page is the thin route shell
+- `ModelResource` is the stable owner boundary
+- `basic-page:blockPage` owns the real list runtime
+- `blockFilter`, `blockTable`, and `blockPager` consume the same shared page runtime context
+- `ZTable` is the schema-driven runtime endpoint under that list-page chain
+
+That is the source-confirmed list-page runtime path in the current Cabloy Basic frontend architecture.