cabloy 5.1.60 → 5.1.62

package/cabloy-docs/frontend/generated-contract-consumption-specimen.md

@@ -0,0 +1,203 @@
+# Generated Contract Consumption Specimen
+
+This page is a focused specimen for one narrow frontend question:
+
+> after backend-authored OpenAPI/schema contract material has already been generated into Zova, what does real frontend consumption look like?
+
+Use this page together with:
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Server Data](/frontend/server-data)
+- [SDK Guide](/frontend/sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+> [!TIP]
+> **Generated-contract reading path**
+>
+> 1. **[Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)** — understand how backend-authored truth crosses the stack boundary
+> 2. **[OpenAPI SDK Guide](/frontend/openapi-sdk-guide)** — configure and generate the frontend contract slice
+> 3. **[Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen)** — see how generated contract material is consumed in practice
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+
+## Why this page exists
+
+Several existing docs already explain parts of this story well:
+
+- the fullstack bridge from backend OpenAPI to frontend generation
+- frontend OpenAPI config and module ownership
+- the conceptual roles of `$sdk`, `$apiSchema`, and server-data layers
+- the internals of `a-openapi` and `ModelResource`
+
+What was still missing was one narrow page that shows the practical consumer-side chain after generation.
+
+This page fills that gap.
+
+It is not another generation guide and not another internals page. It is a specimen page about consumption.
+
+## Shortest accurate mental model
+
+A practical generated-contract consumption path looks like this:
+
+1. backend-authored contract truth has already been generated into frontend contract material
+2. frontend accesses that material through generated API/schema surfaces such as `$api`, `$apiSchema`, and `$sdk`
+3. when the API still belongs to one resource boundary, `ModelResource` remains the stable owner
+4. list-page and entry-page shells consume that owner rather than recreating the contract ad hoc
+5. deeper runtime details still belong to the existing under-the-hood pages
+
+That means generated contract consumption is not one thing only.
+
+It usually moves through:
+
+- generated API/schema access
+- owner-level resource consumption
+- page-shell/runtime consumption
+
+## Where generated contract material comes from
+
+This page starts **after** the forward-chain bridge and generation steps.
+
+Those earlier steps are owned by:
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+
+Once that handoff is complete, the frontend can consume generated contract material through several surfaces:
+
+- generated API services
+- generated API schema accessors
+- `$sdk` schema/runtime helpers
+- higher-level resource owners such as `ModelResource`
+
+## Shared consumption chain
+
+A practical shared reading path is:
+
+1. `zova/src/suite/a-training/modules/training-student/src/apiSchema/trainingStudent.ts`
+2. `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+3. optional direct schema/api consumer specimen: `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+
+That short path already shows the shared contract-consumption layers that both list and entry pages depend on:
+
+- generated schema access
+- thin semantic model follow-up when needed
+- stable resource-owner consumption
+
+## `$sdk`, `$apiSchema`, and generated-contract surfaces in one view
+
+A practical split is:
+
+- generated API services expose callable backend operations
+- `$apiSchema` exposes schema-oriented access to those operations
+- `$sdk` is the lower-level schema/runtime bridge beneath those higher-level consumers
+
+A clear direct schema specimen exists in:
+
+- `zova/src/suite/a-training/modules/training-student/src/apiSchema/trainingStudent.ts`
+
+Representative source facts:
+
+- `@ApiSchema()` exposes a schema bean for the module
+- methods such as `select()`, `create()`, `view()`, `delete()`, `update()`, `summary()`, and `deleteForce()` call `this.$sdk.createApiSchemas(...)`
+
+A second useful specimen is:
+
+- `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+
+Representative source fact:
+
+- `schemaLogin` is derived from `this.apiSchemasLogin.requestBody`
+
+Together, these show the first practical boundary in the frontend contract path:
+
+> the generated contract does not jump directly from backend OpenAPI into page internals. It first becomes frontend-accessible through schema- and SDK-oriented surfaces.
+
+## `ModelResource` as the shared owner before branch split
+
+When the generated contract still belongs to one business resource, frontend consumption usually should not create a second competing owner.
+
+A strong public specimen for this pattern exists in:
+
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+
+Representative source facts:
+
+- the module model is a semantic facade, not the primary resource owner
+- it resolves `rest-resource.model.resource` through selector-backed access
+- custom methods such as `summary(id)` and `deleteForce(id)` still delegate to resource-owner query and mutation helpers
+
+This is the practical contract-consumption rule that matters most:
+
+> when the API still belongs to the same resource, keep `ModelResource` as the stable owner and keep frontend follow-up thin.
+
+At this point, the generated contract consumption path splits into two practical branches:
+
+- **list branch** -> list route shell, schema row, query state, and table-facing owner surfaces
+- **entry branch** -> entry route shell, `formMeta`, `formSchema`, `formData`, and submit/page-meta owner surfaces
+
+## Choose the branch that matches your question
+
+### List branch
+
+Use this branch when your question is about:
+
+- list-page schema and data consumption
+- `schemaRow`, `schemaFilter`, and `select(query)`
+- the route shell and `basic-page:blockPage` handoff
+
+Continue with [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch).
+
+### Entry branch
+
+Use this branch when your question is about:
+
+- `formMeta`, `formSchema`, and `formData`
+- `create` / `view` / `update` schema consumption
+- the route shell and `basic-pageentry:blockPageEntry` handoff
+
+Continue with [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach in depth:
+
+- how to configure or generate OpenAPI SDK output -> see [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- the broader server-data abstraction ladder -> see [Server Data](/frontend/server-data)
+- how `$apiSchema` is positioned conceptually -> see [API Schema Guide](/frontend/api-schema-guide)
+- the lower runtime of `$sdk` and schema extraction -> see [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- `ModelResource` internals -> see [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- the broader `rest-resource` runtime bridge -> see [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+
+Its job is only to show the practical consumer-side handoff after generation.
+
+## Where to read next
+
+- If your next question is still on the bridge/generation side, return to [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+- If your next question is about the list-page branch, continue with [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch).
+- If your next question is about the entry-page branch, continue with [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+- If you now want a proof-oriented layer-by-layer consumer-side workflow, continue with [Generated Contract Consumption Verify Playbook](/frontend/generated-contract-consumption-verify-playbook).
+- If the result is already wrong and you want symptom-first diagnosis, continue with [Generated Contract Consumption Debug Checklist](/frontend/generated-contract-consumption-debug-checklist).
+- If your next question is about the conceptual server-data ladder, continue with [Server Data](/frontend/server-data), [SDK Guide](/frontend/sdk-guide), and [API Schema Guide](/frontend/api-schema-guide).
+- If your next question is about the lower runtime beneath `$sdk`, continue with [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood).
+- If your next question is about the resource-owner internals, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive).
+
+## Final takeaway
+
+The cleanest way to read generated contract consumption in Zova is not to jump straight from generated OpenAPI into deep runtime internals.
+
+Instead, read the chain like this:
+
+- generated contract surfaces
+- schema and SDK access
+- stable resource owner
+- pick the list or entry branch
+- deeper runtime internals only if you still need them
+
+That reading order keeps the consumer-side contract path visible without flattening the architecture into one giant runtime story.

package/cabloy-docs/frontend/generated-contract-consumption-verify-playbook.md

@@ -0,0 +1,189 @@
+# Generated Contract Consumption Verify Playbook
+
+This page is a proof-oriented verification companion for one narrow frontend question:
+
+> after generated contract material has already crossed into Zova, what must be true at each layer before I trust the consumer-side path?
+
+Use this page together with:
+
+- [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen)
+- [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch)
+- [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Server Data](/frontend/server-data)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+> [!TIP]
+> **Generated-contract verification path**
+>
+> 1. **[Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen)** — understand the shared consumer-side path
+> 2. **[Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch)** or **[Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch)** — pick the branch that matches your case
+> 3. **[Generated Contract Consumption Verify Playbook](/frontend/generated-contract-consumption-verify-playbook)** — prove the consumer-side path layer by layer
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen), [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch), and [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+
+## Why this page exists
+
+The current frontend generated-contract family already gives you:
+
+- a conceptual hub page
+- a list-branch specimen
+- an entry-branch specimen
+
+What was still missing was one proof-oriented page that tells you what must be true at each consumer layer after a change.
+
+This page fills that gap.
+
+It is not another generation/config page and not another symptom-first debug page. It is the playbook for proving the consumer-side path is correct.
+
+## Phase 1: Scope the consumer path first
+
+Before checking any details, decide what kind of question you actually have.
+
+### Shared contract-surface question
+
+Use this when the issue is still above the branch split:
+
+- does the generated contract surface exist?
+- does the module expose the expected schema/API surface at all?
+
+### List-branch question
+
+Use this when the issue is clearly about:
+
+- list-page schema/data consumption
+- `schemaRow`, `schemaFilter`, and `select(query)`
+- the route shell and `basic-page:blockPage` handoff
+
+### Entry-branch question
+
+Use this when the issue is clearly about:
+
+- `formMeta`, `formSchema`, `formData`
+- `create` / `view` / `update` schema consumption
+- the route shell and `basic-pageentry:blockPageEntry` handoff
+
+### Deeper internals question
+
+If the issue is already below these consumer-side layers, stop here and hand off to the deeper internals pages later instead of forcing this playbook to explain everything.
+
+## Phase 2: Prove the generated contract surface
+
+Start with the smallest shared consumer-side anchors.
+
+Primary anchors:
+
+- `zova/src/suite/a-training/modules/training-student/src/apiSchema/trainingStudent.ts`
+- optional direct schema consumer: `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+
+What to prove:
+
+- the generated schema access surface exists where expected
+- methods such as `select()`, `create()`, `view()`, `update()`, `summary()`, and `deleteForce()` still expose the intended contract slice
+- if the module depends on direct schema-driven consumption, the expected request/response schema access still resolves correctly
+
+If this phase fails, do not debug deeper page/runtime behavior yet. The consumer path is already wrong too early.
+
+## Phase 3: Prove the stable owner boundary
+
+Once the generated surface is present, prove that the module still consumes it through the correct owner boundary.
+
+Primary anchor:
+
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+
+What to prove:
+
+- the module model still keeps `ModelResource` as the stable owner when the API belongs to the same resource
+- thin semantic follow-up still delegates correctly to owner-backed query/mutation helpers
+- the module did not accidentally invent a competing second owner for the same resource contract
+
+A practical rule is:
+
+> if the generated contract still belongs to the same resource, the consumer path should still stay owner-first.
+
+## Phase 4A: Prove the list branch
+
+Only enter this phase when the problem is clearly on the list-page branch.
+
+Primary anchors:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+
+What to prove:
+
+- the list route shell resolves the expected `resource`
+- `apiSchemasSelect.sdk` still autoloads where expected
+- `schemaRow`, `schemaFilter`, and list data flow are still exposed correctly
+- `basic-page:blockPage` still becomes the deeper list runtime owner
+
+If this phase passes, the generated contract has successfully crossed into the list branch.
+
+## Phase 4B: Prove the entry branch
+
+Only enter this phase when the problem is clearly on the entry-page branch.
+
+Primary anchors:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockForm/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockToolbarRow/controller.tsx`
+
+What to prove:
+
+- the entry route shell resolves `resource`, `id`, and `formScene`
+- owner-level `formMeta`, `formSchema`, and `formData` still load correctly
+- `blockForm` and `blockToolbarRow` still consume the correct host context
+- the submit and page-meta path still belongs to the deeper page-entry runtime owner rather than scattered local code
+
+If this phase passes, the generated contract has successfully crossed into the entry branch.
+
+## Phase 5: Escalate only after the proof steps pass
+
+Only after the earlier proof steps already pass should you descend into:
+
+- `a-openapi` lower runtime internals
+- `ModelResource` internals
+- deeper list runtime internals
+- deeper entry runtime internals
+
+That is the boundary that keeps this page useful instead of turning it into a full runtime deep dive.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- frontend OpenAPI config/generation -> see [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- the broader server-data abstraction ladder -> see [Server Data](/frontend/server-data)
+- the conceptual role of `$apiSchema` -> see [API Schema Guide](/frontend/api-schema-guide)
+- lower `a-openapi` runtime internals -> see [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- `ModelResource` internals -> see [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- deeper list runtime -> see [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- deeper entry runtime -> see [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+Its job is only to tell you what must be true at each consumer-side layer before you trust the generated-contract path.
+
+## Where to read next
+
+- If you need the shared consumer-side overview first, return to [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen).
+- If you need the list or entry branch specimen first, continue with [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch) or [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+- If the visible result is already wrong and you want symptom-first diagnosis, continue with [Generated Contract Consumption Debug Checklist](/frontend/generated-contract-consumption-debug-checklist).
+- If the generated surface itself is missing or stale, hand off to [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+- If the issue is below the current boundary, descend into [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood), [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive), [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive), or [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive).
+
+## Final takeaway
+
+The cleanest way to verify a generated-contract consumer path is not to jump straight into deep runtime debugging.
+
+First prove:
+
+- the generated contract surface
+- the stable owner boundary
+- the matching list or entry branch handoff
+
+Only then descend into deeper internals if you still need them.

package/cabloy-docs/frontend/generic-component-guide.md

@@ -13,7 +13,7 @@ This matters in large TypeScript-heavy systems because generic components help k
 Example: convert component `card` into a generic component.
 
 ```bash
-npm run zova :refactor:componentGeneric card -- --module=demo-student
+npm run zova :refactor:componentGeneric card -- --module=training-student
 ```
 
 ## Why the CLI matters here

package/cabloy-docs/frontend/introduction.md

@@ -28,14 +28,22 @@ Use this page as the main frontend hub, then choose the path that matches your t
 
 ### Getting started and architecture spine
 
-Start here when you need the shortest route to the frontend mental model and startup context:
+Start here when you need the shortest route to the frontend mental model and startup context.
+
+A practical rule is:
+
+- if you need the broadest entry page, stay on this page
+- if you need help choosing a topic cluster, continue with [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap)
+- if you already know the topic and want file-order guidance, continue with [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
+Recommended starting set:
 
 - [Quickstart](/frontend/quickstart)
 - [Foundation](/frontend/foundation)
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
 - [IoC and Beans](/frontend/ioc-and-beans)
-- [Behavior Guide](/frontend/behavior-guide)
-- [Modules and Suites](/frontend/modules-and-suites)
-- [Module Scope](/frontend/module-scope)
 - [Design Principles](/frontend/design-principles)
 - [Environment and Config Guide](/frontend/environment-config-guide)
 - [App Startup Guide](/frontend/app-startup-guide)
@@ -51,14 +59,33 @@ Use this path when the task is page-oriented, route-oriented, or the first time
 - [Page Params Guide](/frontend/page-params-guide)
 - [Zod Guide](/frontend/zod-guide)
 - [Page Route Guide](/frontend/page-route-guide)
+- [A-Router Guide](/frontend/a-router-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 Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Page Meta Guide](/frontend/page-meta-guide)
+- [Router Tabs Layout Integration](/frontend/router-tabs-layout-integration)
+- [Router Tabs vs Stack](/frontend/router-tabs-vs-stack)
+- [Router Stack Guide](/frontend/router-stack-guide)
+- [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)
 
 ### Components and UI flow
 
-Use this path when the task is about UI composition, component contracts, or theme work:
+Use this path when the task is about UI composition, component contracts, form or table architecture, form or table internals, form or table source reading, or theme work:
 
 - [Component Guide](/frontend/component-guide)
+- [Form Guide](/frontend/form-guide)
+- [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)
+- [Table Guide](/frontend/table-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
 - [Component Props Guide](/frontend/component-props-guide)
 - [Component v-model Guide](/frontend/component-v-model-guide)
 - [Generic Component Guide](/frontend/generic-component-guide)
@@ -74,6 +101,12 @@ Use this path when the task is about data loading, API contracts, generated SDKs
 - [API Guide](/frontend/api-guide)
 - [Model Architecture](/frontend/model-architecture)
 - [Model State Guide](/frontend/model-state-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
+- [Using ModelResource in Your Module](/frontend/model-resource-usage-guide)
+- [Resource Model Best Practices](/frontend/model-resource-best-practices)
+- [Resource Model Cookbook](/frontend/model-resource-cookbook)
 - [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
 - [API Schema Guide](/frontend/api-schema-guide)
 - [SDK Guide](/frontend/sdk-guide)

package/cabloy-docs/frontend/ioc-and-beans.md

@@ -200,6 +200,12 @@ Read this together with:
 
 Those pages explain how beans fit into module boundaries, scope-based resources, the existing Behavior scene, and the broader Zova architectural model.
 
+If you want a Vue-to-Zova reading bridge or a deeper runtime/source explanation, also read:
+
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
 ## Implementation checks for frontend bean-architecture changes
 
 When editing Zova frontend code, ask:

package/cabloy-docs/frontend/mock-guide.md

@@ -56,6 +56,7 @@ Mocking fits naturally with:
 
 - [API Guide](/frontend/api-guide)
 - [Server Data](/frontend/server-data)
+- [Fetch Interceptor Guide](/frontend/fetch-interceptor-guide)
 - [Page Guide](/frontend/page-guide)
 
 A common workflow is: