cabloy 5.1.60 → 5.1.61

package/cabloy-docs/frontend/reading-zova-for-vue-developers.md

@@ -0,0 +1,266 @@
+# Reading Zova for Vue Developers
+
+This guide is for readers who already know Vue 3 and want the shortest accurate path to reading Zova source code without forcing generic Vue assumptions onto it.
+
+## Why this page exists
+
+When Vue developers first open Zova code, several things can feel unfamiliar at the same time:
+
+- page and component logic lives in controller classes
+- plain class fields behave reactively
+- derived state is often wired in `__init__`
+- render logic is written in TSX and can live in a controller or a dedicated render bean
+- state sharing is organized through IoC containers and bean scopes rather than a pile of unrelated patterns
+
+If you read Zova as "Vue with unusual syntax," you will miss the architectural point.
+
+A better starting point is:
+
+- **Vue still provides the reactive foundation**
+- **Zova changes the preferred programming model built on top of that foundation**
+
+## The shortest accurate mental model
+
+If you only remember one paragraph, remember this one:
+
+> Zova keeps Vue 3 reactivity underneath, but moves the main authoring surface from `setup()` locals and explicit `ref/reactive` values toward IoC-managed reactive bean instances such as page controllers, component controllers, service beans, and model beans.
+
+That is why Zova code often reads more like controller-oriented application code than like a typical Vue single-file-component or composable-first codebase.
+
+## Quick translation table
+
+| If you usually think in Vue terms | Read Zova like this instead |
+| --- | --- |
+| `setup()` is the main wiring point | `__init__` and bean lifecycle are major wiring points |
+| `ref` / `reactive` are the visible state hosts | controller and bean instances are the visible state hosts |
+| `computed()` creates local derived refs | `$computed()` usually creates instance-level derived state |
+| `useRoute()` pulls route state into the component | page controllers expose `$route`, `$params`, and `$query` as part of the controller surface |
+| `provide/inject`, composables, props, and stores are separate sharing tools | bean scopes and IoC are used to unify more sharing patterns under one model |
+| template or component render is the obvious center | controller-oriented architecture is the center; render can stay in the controller or move into render beans |
+
+## Start from the right assumptions
+
+### 1. Do not assume Zova wants to end at `ref.value`
+
+Zova intentionally aims for code that feels closer to direct variable usage than `ref/reactive`-heavy business code.
+
+That does **not** mean Zova rejects Vue reactivity. It means Zova tries to hide more of the reactive primitive management behind a different framework surface.
+
+Read together with:
+
+- [Design Principles](/frontend/design-principles)
+- [Foundation](/frontend/foundation)
+
+### 2. Do not treat IoC as a small convenience layer
+
+In Zova, IoC is not only about injecting a helper or two.
+
+It is part of the larger architectural answer for:
+
+- state ownership
+- state sharing
+- cross-module composition
+- lifecycle structure
+- extensibility
+
+Read together with:
+
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Module Scope](/frontend/module-scope)
+- [Modules and Suites](/frontend/modules-and-suites)
+
+### 3. Do not collapse page, component, service, and model code into one generic Vue component mental model
+
+Zova gives different bean types different architectural jobs.
+
+For example:
+
+- page controllers organize page-local state and route-aware behavior
+- component controllers organize reusable UI units
+- service beans can own extracted business state or behavior
+- model beans organize broader state categories such as async, local-storage, cookie, or in-memory data
+
+Read together with:
+
+- [Page Guide](/frontend/page-guide)
+- [Component Guide](/frontend/component-guide)
+- [Model Architecture](/frontend/model-architecture)
+- [Model State Guide](/frontend/model-state-guide)
+
+## A concrete specimen to read first
+
+If you want one small example that shows the Zova coding style clearly, start with the demo page controller in the public source tree:
+
+```text
+zova/src/suite/a-demo/modules/demo-basic/src/page/state/controller.tsx
+```
+
+The important things to notice in that file are:
+
+- `count` is a plain class field
+- `count2` is wired in `__init__` through `$computed`
+- actions are plain class methods such as `increment()` and `decrement()`
+- `render()` reads the instance fields directly
+
+A Vue-first reader often expects this kind of code to be rewritten into `setup()` plus `ref` plus `computed`. That is exactly the instinct you should suspend while reading Zova.
+
+## How to read the reactive path under the surface
+
+For the example above, a practical source-reading path is:
+
+1. the example controller in `zova/src/suite/a-demo/modules/demo-basic/src/page/state/controller.tsx`
+2. `zova/packages-zova/zova-core/src/composables/useController.ts`
+3. `zova/packages-zova/zova-core/src/bean/beanContainer.ts`
+4. `zova/packages-zova/zova-core/src/bean/beanBase.ts`
+5. `zova/packages-zova/zova-core/src/core/context/component.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-router/src/monkey.ts`
+
+A compact interpretation of those files is:
+
+- `useController.ts` creates and loads the controller bean
+- `beanContainer.ts` is where bean instances become reactive and container-managed
+- `beanBase.ts` exposes helpers such as `$computed`, `$watch`, and `$toRef`
+- `component.ts` patches the component render flow so controller-driven render logic participates in normal frontend updates
+- `a-router/src/monkey.ts` pushes page route state onto page controllers
+
+This is the main reason Zova can feel so different while still standing on top of Vue runtime behavior.
+
+If you want the next layer down, continue with [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood).
+
+## Six practical differences Vue developers usually feel first
+
+### 1. The visible state host is the controller instance
+
+A Vue developer often expects to see:
+
+```typescript
+const count = ref(0);
+```
+
+A Zova reader will more often see:
+
+```typescript
+count: number = 0;
+```
+
+The important idea is not only less syntax. The important idea is that the framework is making the bean instance itself the main business-facing state surface.
+
+### 2. Derived state is written as instance wiring
+
+Instead of thinking:
+
+```typescript
+const count2 = computed(() => `=== ${count.value} ===`);
+```
+
+Zova often reads more like:
+
+```typescript
+protected async __init__() {
+  this.count2 = this.$computed(() => {
+    return `=== ${this.count} ===`;
+  });
+}
+```
+
+That makes derived state feel like part of object initialization rather than only part of a local `setup()` assembly.
+
+### 3. Actions are ordinary methods
+
+Instead of scattering behavior through closures returned from `setup()`, Zova often keeps page or component actions as plain methods on the controller instance.
+
+That is one reason Zova business code can read more like application controller code.
+
+### 4. Route state is part of the page-controller surface
+
+A Vue reader often looks for `useRoute()` first.
+
+In Zova, a page controller often expects route-aware behavior through members such as:
+
+- `$route`
+- `$params`
+- `$query`
+
+For the route-oriented mental model, also see [Page Route Guide](/frontend/page-route-guide).
+
+### 5. State sharing is more architecture-driven
+
+Vue projects often combine several independent techniques:
+
+- props and emits
+- composables
+- `provide/inject`
+- store layers
+
+Zova tries to keep more of that within the bean and scope architecture, so the first question becomes less "which unrelated mechanism should I use?" and more "which bean owns this state and which scope should that bean live in?"
+
+### 6. Render is controller-oriented, not only component-file-oriented
+
+A Vue reader might assume that moving code out of a large page means immediately creating more composables or child components.
+
+In Zova, a common growth path is:
+
+- start with a single page controller
+- split render into a render bean when the page grows
+- split style into a style bean when needed
+- extract business state or logic into service beans when that becomes clearer
+
+That growth path is one of the main reasons you should read Zova pages through the page/controller architecture instead of through a generic component-file lens.
+
+## A practical reading order for Vue developers
+
+If you want the shortest path from Vue familiarity to Zova fluency, use this order:
+
+1. [Foundation](/frontend/foundation)
+2. [Design Principles](/frontend/design-principles)
+3. [IoC and Beans](/frontend/ioc-and-beans)
+4. [Page Guide](/frontend/page-guide)
+5. [Component Guide](/frontend/component-guide)
+6. [Model Architecture](/frontend/model-architecture)
+7. [Page Route Guide](/frontend/page-route-guide)
+8. [Behavior Guide](/frontend/behavior-guide)
+
+Use this order when:
+
+- you already know Vue
+- you want to read Zova source code accurately
+- you want to avoid rewriting framework-specific code back toward generic Vue habits
+
+## Common mistakes to avoid
+
+### Mistake 1: "This should become a normal Vue SFC"
+
+Usually the better question is whether the existing controller, render bean, style bean, or service/model bean boundaries are already the intended Zova architecture.
+
+### Mistake 2: "If I do not see `ref`, there is no real reactivity"
+
+The reactive foundation is still there. The framework is simply exposing a different authoring surface.
+
+### Mistake 3: "IoC only matters for dependency injection"
+
+In Zova, IoC is tied to structure, sharing scope, extensibility, and long-term maintainability.
+
+### Mistake 4: "Route state should always be pulled locally by composables"
+
+For page controllers, route-aware behavior is deliberately pushed into the controller surface so the page model stays cohesive.
+
+### Mistake 5: "Model state is just another local store choice"
+
+The model layer is one of Zova’s larger architectural answers for unified state categories, SSR-aware state handling, caching, and persistence-oriented behavior.
+
+## Edition note
+
+This reading guide is about the shared Zova frontend architecture, not about one UI library.
+
+That means the architectural reading model applies across Cabloy Basic and Cabloy Start. However, UI-sensitive examples can still diverge:
+
+- Cabloy Basic public examples currently align with DaisyUI + Tailwind CSS
+- Cabloy Start aligns with Vuetify-oriented UI workflows and may differ in modules, SSR site baselines, and project assets
+
+So when your task becomes UI-specific rather than architecture-specific, detect the active edition before assuming a component or theme workflow.
+
+## Final takeaway
+
+If Vue teaches you to think in terms of reactive primitives and local composition, Zova asks you to think in terms of reactive framework-managed objects with explicit architectural roles.
+
+That is the mental shift that makes the rest of the source tree much easier to read.

package/cabloy-docs/frontend/server-data.md

@@ -27,6 +27,8 @@ These layers define the server-data abstraction ladder:
 
 Use `$fetch` when you need a relatively direct HTTP-oriented access path.
 
+When the transport concern itself needs framework-level handling such as auth headers, response-envelope normalization, SSR short-circuiting, or mock fallback, read [Fetch Interceptor Guide](/frontend/fetch-interceptor-guide) together with this page.
+
 ### `$api`
 
 Use `$api` when you want business-oriented service access rather than scattering request details across pages and components.

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

@@ -0,0 +1,295 @@
+# 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)
+- [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
+
+Because of that, form documentation now has three distinct layers:
+
+- [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 explains which files to read first for each source-reading question
+
+Because of that, source reading can become slow for one predictable reason:
+
+- you can find one relevant file such as the form controller
+- but you do not yet know the shortest accurate path to the next runtime layer
+
+This page gives a compact reading order so you can move from public surface to runtime detail without drifting.
+
+## 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
+
+## 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.