cabloy 5.1.61 → 5.1.63

package/cabloy-docs/frontend/filter-query-select-data-flow-guide.md

@@ -0,0 +1,260 @@
+# Filter to Query to Select Data Flow Guide
+
+This guide explains the list-page data path from filter UI into query state, then into `ModelResource.select(query)`, and finally into table and pager state in Zova.
+
+Use this page when you want to understand:
+
+- how filter UI changes become list-page query state
+- how paging state joins that query
+- how the final query reaches `ModelResource.select(query)`
+- how the resulting paged/list data is consumed by table and pager
+- where permission-driven table-meta refresh sits relative to that data flow
+
+## Why this page exists
+
+Several existing docs already explain nearby pieces:
+
+- [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive) explains the broader list-page runtime assembly
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood) explains the module-level bridge
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook) explains practical authoring for CRUD list pages
+
+What those pages do not isolate directly is the one compact data-flow path from filter UI into the owner-side query execution boundary.
+
+That is the gap this page fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `blockFilter` normalizes user-entered filter values
+2. `blockPage` stores those values in `queryFilterData`
+3. `blockPage` also owns paging state in `queryPaged`
+4. `blockPage` computes one merged `query`
+5. `ModelResource.select(query)` becomes the owner-side query execution boundary
+6. the select result provides both `list` and paged metadata
+7. `blockTable` consumes the list data
+8. `blockPager` consumes the paged metadata
+
+That means the list-page fetch path is not scattered across table, pager, and filter. It is centralized in the page runtime and then handed to the owner.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+2. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilter/controller.tsx`
+3. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPager/controller.tsx`
+4. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+5. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+
+That order moves from the page-owned state source, to filter and pager inputs, to the table bridge, and finally to the owner-side query execution path.
+
+## Runtime path by layer
+
+### 1. Filter UI becomes `queryFilterData`
+
+The filter bridge lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilter/controller.tsx
+```
+
+This block renders `ZForm` with:
+
+- `data={$$page.queryFilterData}`
+- `schema={$$page.schemaFilter}`
+- `schemaScene="filter"`
+
+Its submit and reset flow both pass through `_onFilter(dataOld)`.
+
+The important source-confirmed behavior is:
+
+- nil and empty-string values are removed
+- the normalized object is passed to `$$page.onFilter(dataNew)`
+
+This is the first key rule:
+
+- `blockFilter` does not fetch directly
+- it normalizes filter values and pushes them into page-owned state
+
+### 2. Paging state becomes `queryPaged`
+
+The page runtime owner lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx
+```
+
+Inside `__init__()`, it initializes:
+
+- `queryFilterData = {}`
+- `queryPaged = { pageNo: 1, pageSize: this.$props.pageSize }`
+
+It also owns:
+
+- `gotoPage(pageNo)`
+- `setPageSize(pageSize)`
+
+That means paging is page-owned runtime state, not something the pager block owns independently.
+
+### 3. `query` is the canonical merged state
+
+The same `blockPage` controller computes:
+
+```typescript
+this.query = this.$computed(() => {
+  return Object.assign({}, this.queryFilterData, this.queryPaged);
+});
+```
+
+This is the canonical query object for the list page.
+
+A practical reading rule is:
+
+- filter state and paging state stay separate while they are being edited
+- `query` is the merged runtime shape passed into the owner
+
+### 4. `ModelResource.select(query)` is the owner-side query boundary
+
+The owner-side boundary lives in:
+
+```text
+zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts
+```
+
+`blockPage` uses:
+
+```typescript
+get queryData() {
+  return this.$$modelResource.select(this.query);
+}
+```
+
+Inside the owner:
+
+- `select(query?)` delegates to `selectGeneral(undefined, query)`
+- `selectGeneral(...)` creates a query key shaped like:
+  - `['select', actionPath ?? '', hashkey(query)]`
+- it fetches the list result from the resolved `resourceApi`
+
+This is the second key rule:
+
+- pages assemble query state
+- `ModelResource` owns query execution, query-key identity, and fetch semantics
+
+### 5. The select result becomes both `data` and `paged`
+
+Back in `blockPage`, two important derived surfaces are exposed:
+
+- `data = queryData.data?.list`
+- `paged = queryData.data`
+
+This matters because the select result is not only a list.
+
+It is the paged result surface that both table and pager depend on.
+
+### 6. `blockTable` consumes list data
+
+The table bridge lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx
+```
+
+It consumes the shared page runtime and passes into `ZTable`:
+
+- `data={$$page.data}`
+- `schema={$$page.schemaRow}`
+- `tableScope={$$page.jsxCelScope}`
+
+That means `blockTable` is not the owner of the fetch path.
+
+It is the bridge from page-owned list result into the table runtime.
+
+### 7. `blockPager` consumes paged metadata
+
+The pager block lives in:
+
+```text
+zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPager/controller.tsx
+```
+
+It reads:
+
+- `$$page.paged`
+
+and delegates navigation back into page-owned state with:
+
+- `$$page.gotoPage(...)`
+
+This is the third key rule:
+
+- the pager does not fetch directly
+- it mutates page-owned paging state and lets the central query path react
+
+## Permission-driven table-meta refresh is adjacent, not the data path itself
+
+`blockPage` also watches:
+
+- `permissions`
+
+and refreshes table meta when permission state changes.
+
+That behavior is important, but it is not the same thing as the filter/query/select data path.
+
+A practical rule is:
+
+- filter/paging changes affect query identity and data fetches
+- permission changes affect table metadata and visible action/column behavior
+
+Those are related, but distinct, flows.
+
+## A compact end-to-end trace
+
+The shortest end-to-end trace is:
+
+- filter UI normalizes user input
+- `queryFilterData` changes
+- `queryPaged` changes when navigation changes page
+- `query = { ...queryFilterData, ...queryPaged }`
+- `queryData = $$modelResource.select(query)`
+- `data = queryData.data?.list`
+- `paged = queryData.data`
+- table consumes `data`
+- pager consumes `paged`
+
+That is the source-confirmed filter -> query -> select data path in the current Basic list-page runtime.
+
+## Debugging checklist
+
+If list data looks wrong, ask:
+
+1. did `blockFilter` normalize away a field unexpectedly?
+2. did `queryFilterData` actually change?
+3. did `queryPaged` change as expected?
+4. does the merged `query` contain the expected fields?
+5. did `ModelResource.select(query)` create the expected query-key identity?
+6. is `queryData.data?.list` populated as expected?
+7. is `paged` present and consistent with the list result?
+8. is the issue really data flow, or is it permission-driven table-meta refresh instead?
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want the broader list-page runtime assembly, read [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- if you want the owner internals behind `select(query)`, read [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- if you want practical CRUD authoring guidance, read [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- if you want row/bulk action visibility, read [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
+
+## Final takeaway
+
+The most accurate way to read the current Basic list-page data path is:
+
+- `blockFilter` owns filter normalization
+- `blockPage` owns query state assembly
+- `ModelResource.select(query)` owns owner-side query execution
+- `data` and `paged` are the shared outputs
+- table and pager consume those outputs instead of owning the fetch logic
+
+That is the source-confirmed `filter -> query -> select` runtime path in the current Cabloy Basic frontend architecture.

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

@@ -22,6 +22,7 @@ Use this page together with:
 
 > [!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
@@ -31,6 +32,8 @@ Use this page together with:
 
 If your next question is how these public APIs cooperate internally at runtime, continue with [Zova Form Under the Hood](/frontend/zova-form-under-the-hood).
 
+If your next question is 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).
+
 ## What you should learn first
 
 If you only remember one idea, remember this one:
@@ -48,7 +51,7 @@ That leads to four common authoring surfaces:
 
 To keep the guide concrete, the examples below all use the same teaching resource:
 
-- resource: `demo-student:student`
+- resource: `training-student:student`
 - representative fields: `name`, `level`, and `mobile`
 - common scenes: Student create, Student edit, and Student view
 
@@ -101,10 +104,7 @@ The smallest useful Zova form is usually a mixed Student form with `ZForm`, a co
 
 ```tsx
 <ZForm data={this.studentFormData} onSubmitData={data => this.submitStudent(data)}>
-  <ZFormFieldPreset
-    name="name"
-    layout={{ label: 'Student Name:' }}
-  ></ZFormFieldPreset>
+  <ZFormFieldPreset name="name" layout={{ label: 'Student Name:' }}></ZFormFieldPreset>
 
   <ZFormFieldPreset
     name="level"
@@ -276,8 +276,11 @@ Use `onShowError` when you want a centralized user-facing error handler.
 
 ```tsx
 <ZForm
-  onShowError={({ error }) => {
-    window.alert(error.message)
+  onShowError={async ({ error }) => {
+    await this.$performCommand('basic-commands:alert', {
+      type: 'error',
+      text: error.message,
+    });
   }}
 ></ZForm>
 ```
@@ -325,19 +328,13 @@ That is the best default when:
 You can also provide validators directly on a field.
 
 ```tsx
-<ZFormFieldPreset
-  name="name"
-  validators={{ onDynamic: z.string().min(3) }}
-></ZFormFieldPreset>
+<ZFormFieldPreset name="name" validators={{ onDynamic: z.string().min(3) }}></ZFormFieldPreset>
 ```
 
 Or, for a custom Student field:
 
 ```tsx
-<ZFormField
-  name="mobile"
-  validators={{ onBlur: z.string().min(6) }}
-></ZFormField>
+<ZFormField name="mobile" validators={{ onBlur: z.string().min(6) }}></ZFormField>
 ```
 
 The common validator hooks are:
@@ -368,7 +365,7 @@ Zova Form also normalizes server validation failures back into the form pipeline
 this.studentFormMeta = {
   formMode: 'edit',
   editMode: 'update',
-}
+};
 ```
 
 A practical way to read it is:
@@ -396,10 +393,7 @@ In practice, Student field rendering can be influenced by:
 ### Use `layout` for label and wrapper concerns
 
 ```tsx
-<ZFormFieldPreset
-  name="level"
-  layout={{ label: 'Student Level:' }}
-></ZFormFieldPreset>
+<ZFormFieldPreset name="level" layout={{ label: 'Student Level:' }}></ZFormFieldPreset>
 ```
 
 Use `layout` for concerns such as:
@@ -430,7 +424,7 @@ Use `options` when the concrete Student field renderer needs its own input optio
 
 ```tsx
 <ZForm
-  formProvider={{ behaviors: { FormFieldLayout: 'demo-student:formFieldLayoutStudent' } }}
+  formProvider={{ behaviors: { FormFieldLayout: 'training-student:formFieldLayoutStudent' } }}
 >
 ```
 
@@ -546,7 +540,7 @@ protected async __init__() {
   this.$$modelResource = await this.bean._getBeanSelector(
     'rest-resource.model.resource',
     true,
-    'demo-student:student',
+    'training-student:student',
   );
 
   this.studentFormMeta = this.$computed(() => {
@@ -575,7 +569,7 @@ async submitStudent(data: TypeFormOnSubmitData<StudentFormData>) {
 
 Read that example as four ownership boundaries:
 
-- `demo-student:student` identifies the business resource
+- `training-student:student` identifies the business resource
 - `ModelResource` owns resource-level Student form schema/data/provider lookup
 - `studentFormMeta` decides whether the Student page is create/edit/view
 - `submitStudent` delegates to the Student mutation policy instead of inventing a page-local submit rule
@@ -592,8 +586,11 @@ Once the Student model side is prepared, the render side can stay thin:
   formMeta={this.studentFormMeta}
   formProvider={this.studentFormProvider}
   onSubmitData={data => this.submitStudent(data)}
-  onShowError={({ error }) => {
-    window.alert(error.message)
+  onShowError={async ({ error }) => {
+    await this.$performCommand('basic-commands:alert', {
+      type: 'error',
+      text: error.message,
+    });
   }}
 ></ZForm>
 ```
@@ -638,11 +635,11 @@ Read together with:
 
 Use this table when you are unsure which style to choose.
 
-| Style | Best fit | Strengths | Trade-offs |
-| --- | --- | --- | --- |
-| Schema-driven | resource CRUD pages, contract-first forms, metadata-rich pages | least duplication, easiest to keep aligned with backend truth, fastest way to scale many forms | less suitable when one page has unusual UI structure |
-| Manual | highly custom UI, one-off interaction-heavy forms | maximum render control | easiest way to drift away from contract truth and duplicate field wiring |
-| Mixed | most business pages | keeps standard fields cheap while leaving room for custom rows or custom renderers | requires discipline about which layer should own each customization |
+| Style         | Best fit                                                       | Strengths                                                                                      | Trade-offs                                                               |
+| ------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Schema-driven | resource CRUD pages, contract-first forms, metadata-rich pages | least duplication, easiest to keep aligned with backend truth, fastest way to scale many forms | less suitable when one page has unusual UI structure                     |
+| Manual        | highly custom UI, one-off interaction-heavy forms              | maximum render control                                                                         | easiest way to drift away from contract truth and duplicate field wiring |
+| Mixed         | most business pages                                            | keeps standard fields cheap while leaving room for custom rows or custom renderers             | requires discipline about which layer should own each customization      |
 
 A practical recommendation is: