cabloy 5.1.60 → 5.1.62

package/cabloy-docs/frontend/zova-app-guide.md

@@ -0,0 +1,251 @@
+# Zova App Guide
+
+This guide explains the root app-shell module in Zova through the current public Cabloy Basic source:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-app
+```
+
+Use this page when you want to understand:
+
+- what `a-app` is responsible for
+- what `a-app` is **not** responsible for
+- how the root app wrapper reaches the routed tree
+- where app-wide behavior wrapping enters the runtime
+- which files to read first when tracing the source
+
+## Why this page exists
+
+Several other frontend guides already explain routing, startup, behavior, and SSR.
+
+What they do not explain directly is the thin root module that connects those concerns at the app host level.
+
+That root module is `a-app`.
+
+In the current Basic source, `a-app` is not a feature module full of pages or business services. It is a small app-shell module whose main job is to host the root app controller, apply app-level metadata, initialize app-wide behaviors, and render the routed tree.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `a-app` exposes the root app component surface
+2. `ZApp` mounts the root controller
+3. `ControllerApp` initializes app meta and root behaviors
+4. `ControllerApp.render()` returns the routed tree through `RouterView`
+5. that routed tree is wrapped by `BeanBehaviorsHolder` so app-wide behaviors can participate around it
+
+That means `a-app` is the root app host, not the owner of every frontend concern.
+
+## What `a-app` is
+
+In the current Basic source, `a-app` is mainly these five things:
+
+- a **module integration surface** through generated metadata
+- a **root component wrapper** through `ZApp`
+- an **app controller** through `ControllerApp`
+- a **root behavior host** through `BeanBehaviorsHolder`
+- a **routed-content host** through `RouterView`
+
+Those roles are enough to make it a real architectural boundary even though the module is small.
+
+## What `a-app` is not
+
+It is equally important to avoid over-assigning responsibilities to `a-app`.
+
+`a-app` does **not** itself define:
+
+- page route records
+- page controllers
+- model beans
+- standalone business services
+- the actual layout implementations
+- the full SSR orchestration flow
+
+Those responsibilities belong to other routing, layout, model, service, and SSR layers.
+
+So when you read `a-app`, read it as the root host that connects those systems, not as the place where all of them are authored.
+
+## The core source-reading path
+
+When reading `a-app`, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/this.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/index.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/component/app.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-app/src/component/app/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-app/src/config/config.ts`
+
+That order moves from module identity, to generated integration surface, to component wrapper, to runtime controller logic, to configuration hook points.
+
+## What each source file clarifies
+
+### `src/.metadata/this.ts`
+
+This file gives the module identity quickly:
+
+- module name is `a-app`
+- module scope is exported as `ScopeModule`
+
+Read this file first when you want to anchor the rest of the source path.
+
+### `src/.metadata/index.ts`
+
+This is the generated integration map for the module.
+
+It shows that `a-app` contributes:
+
+- the app controller registration
+- the `ZApp` component export
+- the module config typing
+- the module scope typing
+
+This file is the best single map of how the module enters the larger Zova container and component records.
+
+### `src/.metadata/component/app.ts`
+
+This file shows the public wrapper component:
+
+- `ZApp` is defined with `defineComponent(...)`
+- it calls `useController(ControllerApp, ...)`
+- it exposes `controllerRef` as a controller-facing hook
+
+The important idea is that `ZApp` is a thin wrapper whose main job is to mount the controller-oriented runtime path.
+
+## `src/component/app/controller.tsx`
+
+This is the real runtime center of the module.
+
+Its main jobs are:
+
+- call `$useMeta(...)` to set app-level document metadata
+- initialize `BeanBehaviorsHolder`
+- read root behaviors from `scope.config.behaviors`
+- render the routed tree through `RouterView`
+
+This is the file that shows the actual app-host responsibilities most clearly.
+
+## `src/config/config.ts`
+
+This file is small but important.
+
+It exposes the module config surface for:
+
+- `behaviors`
+
+That matters because it shows that `a-app` is intentionally designed to receive app-wide behavior configuration from outside the module instead of hard-coding every root behavior locally.
+
+## Runtime flow from `ZApp` to routed content
+
+The shortest practical runtime flow is:
+
+1. `ZApp` calls `useController(ControllerApp, ...)`
+2. the framework creates and loads `ControllerApp`
+3. `ControllerApp.__init__()` sets app-level meta through `$useMeta(...)`
+4. `ControllerApp.__init__()` initializes `BeanBehaviorsHolder`
+5. the holder reads app-wide behavior declarations from `scope.config.behaviors`
+6. `ControllerApp.render()` returns behavior-wrapped `<RouterView />`
+7. the routed page tree continues from the router and layout layers
+
+This page stops at the root app-host boundary. For the deeper behavior-composition path behind `BeanBehaviorsHolder`, continue with [Root Behaviors Guide](/frontend/root-behaviors-guide).
+
+## Relationship to routing
+
+`a-app` does not define the page route records themselves.
+
+Instead, it hosts the routed tree by rendering `RouterView`.
+
+That means routing questions usually split into two layers:
+
+- `a-app` as the root host that renders the routed content entry
+- router and layout layers as the owners of route records, layout choice, guards, and routed-host behavior
+
+Read together with:
+
+- [Page Route Guide](/frontend/page-route-guide)
+- [A-Router Guide](/frontend/a-router-guide)
+- [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+
+## Relationship to behaviors
+
+`a-app` is also the root behavior host in the current Basic source.
+
+Because `ControllerApp` initializes `BeanBehaviorsHolder` from `scope.config.behaviors`, project or module-level code can extend the root app host by contributing behavior configuration.
+
+A practical way to think about this is:
+
+- `a-app` owns the root behavior hosting point
+- other modules can contribute app-wide behavior declarations to that hosting point
+
+Read together with:
+
+- [Behavior Guide](/frontend/behavior-guide)
+- [Root Behaviors Guide](/frontend/root-behaviors-guide)
+
+## Relationship to startup
+
+App startup and `a-app` are related, but they are not the same concept.
+
+- **app startup** decides when the application lifecycle becomes operational
+- **`a-app`** is the root app host component/controller path inside that operational application
+
+That distinction helps avoid placing startup logic into the root app controller just because it feels globally visible.
+
+Read together with:
+
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+
+## Relationship to SSR
+
+`a-app` participates in the frontend runtime side of SSR because it is part of the application render tree.
+
+But it is not the complete SSR orchestration layer.
+
+In the broader SSR model:
+
+- Vona owns request-level SSR orchestration
+- the built frontend bundle provides the SSR entry
+- Zova SSR runtime resolves and renders the frontend route tree
+- `a-app` participates as part of that root render tree
+
+Read together with:
+
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## A compact interpretation of app-wide extension
+
+When you need app-wide overlays or wrappers, the root behavior host is often a better fit than forcing that concern into unrelated page code.
+
+A practical extension model is:
+
+- keep `a-app` as the thin root host
+- let other modules contribute root behavior configuration
+- let those behaviors wrap the routed tree in a reusable way
+
+That keeps the root host small while still making it extensible.
+
+## Where to read next
+
+After this page, the most useful next paths are usually:
+
+- [Root Behaviors Guide](/frontend/root-behaviors-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## Final takeaway
+
+The most accurate way to read `a-app` is not as a generic Vue root component and not as the owner of the whole frontend system.
+
+Read it as the thin Zova app-shell host that:
+
+- mounts the root app controller
+- applies app-level meta
+- hosts root behaviors
+- renders the routed tree
+
+That is the source-confirmed role of `a-app` in the current Basic frontend architecture.

package/cabloy-docs/frontend/zova-form-source-reading-map.md

@@ -0,0 +1,293 @@
+# Zova Form Source Reading Map
+
+This page is a practical map for contributors and AI workflows that need to read Zova Form source code efficiently.
+
+Use this page after [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) when your next question is not the runtime model itself, but which files to read first for a specific form-internals topic.
+
+It answers a narrow question:
+
+> when I need to understand how Zova Form works internally, which files should I read first, and in what order?
+
+Use this page together with:
+
+- [Form Guide](/frontend/form-guide)
+- [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+- [Behavior Guide](/frontend/behavior-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+
+> [!TIP]
+> **Zova Form docs path**
+>
+> 1. **[Form Guide](/frontend/form-guide)** — learn the public authoring surface
+> 2. **[Zova Form Under the Hood](/frontend/zova-form-under-the-hood)** — learn how the runtime pieces cooperate
+> 3. **[Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)** — learn which files to read next
+>
+> **You are here:** step 3.
+> **Previous page:** [Zova Form Under the Hood](/frontend/zova-form-under-the-hood).
+
+## Why this page exists
+
+The `a-form` module sits at the intersection of several Zova concerns at once:
+
+- controller-oriented component design
+- schema-driven rendering
+- Zod and TanStack validation
+- behavior-based field wrapping
+- resource-driven CRUD page integration
+
+This page exists for one narrow job:
+
+- [Form Guide](/frontend/form-guide) explains how to author forms
+- [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) explains how the runtime pieces cooperate
+- this page gives the shortest file-order paths for specific form questions
+
+## How to use this page
+
+For each topic below:
+
+1. start with the public guide to refresh the architectural intent
+2. read the first source file to identify the public surface
+3. continue into the next runtime file only if you still need the implementation detail
+4. stop as soon as you have enough information for the task
+
+The goal is not to read the entire form stack every time. The goal is to choose the shortest correct path.
+
+## 1. Public form surface and wrapper entrypoints
+
+Use this path when you are asking questions like:
+
+- what is the public Zova Form surface?
+- where do `ZForm` and `ZFormField` enter the runtime?
+- how does `controllerRef` reach the controller instance?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Component Guide](/frontend/component-guide)
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/.metadata/component/form.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/.metadata/component/formField.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+5. `zova/packages-zova/zova-core/src/composables/useController.ts`
+
+### What each file clarifies
+
+- metadata wrapper files show how the public component wrappers enter `useController(...)`
+- `form.ts` exposes `ZForm` and its typed controller-facing props surface
+- `formField.ts` exposes `ZFormField` and the controller-aware slot contract
+- `useController.ts` shows how the controller instance is created and bound to the wrapper component lifecycle
+
+## 2. Form controller ownership and form runtime
+
+Use this path when you are asking questions like:
+
+- where is the form instance created?
+- where does `formState` come from?
+- how does `submit()` or `reset()` work in Zova Form?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Zod Guide](/frontend/zod-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/beanControllerFormBase.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/beanControllerPageFormBase.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/form.ts`
+
+### What each file clarifies
+
+- `component/form/controller.tsx` is the main form runtime owner
+- `beanControllerFormBase.ts` shows the shared `$useForm(...)` wrapper around TanStack Form
+- `beanControllerPageFormBase.ts` shows the page-controller-oriented variant for form pages
+- `types/form.ts` shows the exposed type contracts for submit data, state, and events
+
+## 3. Field controller ownership and field render flow
+
+Use this path when you are asking questions like:
+
+- how is one field connected to the parent form?
+- where do `setValue(...)` and `handleBlur()` live?
+- how does one field become a rendered vnode?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/render.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formFieldPreset/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formFieldBlank/controller.tsx`
+
+### What each file clarifies
+
+- `formField/controller.tsx` is the field runtime owner and host-injected child of the form controller
+- `formField/render.tsx` shows the final render handoff through behaviors and `zovaJsx.render(...)`
+- `types/formField.ts` shows field options, layout options, render context, and the `$$FieldProps` marker
+- `formFieldPreset/controller.tsx` shows the preset-driven delegation path
+- `formFieldBlank/controller.tsx` shows the free-row slot-only path
+
+## 4. Schema-driven rendering and CEL/JSX resolution
+
+Use this path when you are asking questions like:
+
+- how does a schema become rendered fields?
+- where do field props come from?
+- how are metadata expressions or render providers resolved?
+
+### Read the docs first
+
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Form Guide](/frontend/form-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/render.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts`
+
+### What each file clarifies
+
+- `form/controller.tsx` shows schema property loading, field CEL scope creation, and top-level field prop extraction
+- `form/render.tsx` shows how schema properties become children when the form body is not manually overridden
+- `types/formField.ts` shows the field render-context shapes that the runtime passes through to renderers and behaviors
+
+## 5. Validation, submit flow, and server error normalization
+
+Use this path when you are asking questions like:
+
+- where is submit wired?
+- how are form-level and field-level validators chosen?
+- how are server validation errors pushed back into the form state?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Zod Guide](/frontend/zod-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/form.ts`
+
+### What each file clarifies
+
+- `form/controller.tsx` shows `submit(...)`, `_createForm()`, `onSubmitInvalid`, `onSubmitData`, and error normalization
+- `formField/controller.tsx` shows how field validators are derived from Zod schema or explicit field options
+- `types/form.ts` shows the public event and submit-type contracts that the rest of the framework consumes
+
+## 6. Provider config, default renderers, and behavior-based layout
+
+Use this path when you are asking questions like:
+
+- where does the default `Input` renderer come from?
+- how does `formProvider` affect field rendering?
+- where do form-field layout behaviors enter the pipeline?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+2. `zova/src/suite/cabloy-basic/modules/basic-adapter/src/config/config.ts`
+3. `zova/src/suite/a-home/modules/home-login/src/page/login/render.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/render.tsx`
+
+### What each file clarifies
+
+- `formField/controller.tsx` shows how field props, layout, options, provider config, and behaviors are merged
+- `basic-adapter/src/config/config.ts` shows the default Basic provider components and layout behaviors
+- `home-login/render.tsx` shows a page-level `formProvider` override for layout behavior
+- `formField/render.tsx` shows how the behavior-wrapped render path leads to the final vnode
+
+## 7. Resource-driven CRUD page integration
+
+Use this path when you are asking questions like:
+
+- how does a resource page feed schema and data into `ZForm`?
+- where do `formMeta`, `formSchema`, and `formProvider` come from in CRUD pages?
+- how does submit delegate back to resource mutation logic?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Tutorial 2: Create Your First CRUD](/fullstack/tutorial-2-first-crud)
+- [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing)
+
+### Then read source in this order
+
+1. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+2. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockForm/controller.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/utils.ts`
+4. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilter/controller.tsx`
+
+### What each file clarifies
+
+- `blockPageEntry/controller.tsx` shows the resource-driven CRUD form orchestration path
+- `blockForm/controller.tsx` shows how a block-level wrapper passes schema/data/provider/meta into `ZForm`
+- `lib/utils.ts` shows the canonical scene-to-form-meta translation helpers
+- `blockFilter/controller.tsx` shows the lighter-weight filter-form branch using the same form module
+
+If your next question becomes how `formScene` becomes `formMeta`, then `pageMeta`, and finally visible shell/tab state, continue with [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide).
+
+## 8. Representative specimens to read before editing the framework
+
+Use this section when you want one small example before reading the framework internals.
+
+### Read these specimens first
+
+1. `zova/src/suite/a-demo/modules/demo-basic/src/page/toolOne/controller.tsx`
+2. `zova/src/suite/a-demo/modules/demo-basic/src/page/toolOne/render.tsx`
+3. `zova/src/suite/a-home/modules/home-login/src/page/login/render.tsx`
+
+### Why these three specimens matter
+
+- `toolOne` shows both schema-driven and manual form usage in one page
+- `home-login` shows a real page using presets, blank rows, and provider-level layout override
+- together they give you the public authoring shape before you descend into the form runtime
+
+## 9. A compact reading strategy
+
+When in doubt, use this order:
+
+1. [Form Guide](/frontend/form-guide)
+2. one real usage specimen such as `toolOne` or `home-login`
+3. the public wrapper metadata under `src/.metadata/component/*.ts`
+4. `component/form/controller.tsx`
+5. `component/formField/controller.tsx`
+6. render beans, types, and integration layers only if you still need more detail
+
+That order usually gets you to the answer faster than starting from the deepest runtime files first.
+
+## 10. Final takeaway
+
+The fastest way to read Zova Form accurately is not to memorize every file in `a-form`.
+
+It is to recognize which question you are asking:
+
+- public wrapper question
+- form-runtime question
+- field-render question
+- validation question
+- resource-CRUD integration question
+
+Then start from the smallest public file that matches that question and only descend into deeper runtime files as needed.