cabloy 5.1.98 → 5.1.100

package/cabloy-docs/frontend/use-state-data-best-practices.md

@@ -0,0 +1,384 @@
+# `$useStateData` Best Practices
+
+This guide explains how to use `$useStateData(...)` well in Zova, especially when you are deciding whether a piece of async frontend data should behave like render-time state or interaction-time ad hoc fetch logic.
+
+Read [Model Architecture](/frontend/model-architecture) first if you want the broader role of Model.
+
+Read [Model State Guide](/frontend/model-state-guide) first if you want the larger helper-family overview.
+
+Use this page when your real design question is one of these:
+
+- should this async value live in a model query or stay inside one controller?
+- should the query be established during render or only during interaction?
+- should I use `enabled: false` or let the query participate in the normal lifecycle?
+- how should I think about `disableSuspenseOnInit: true`?
+- if I remove a manual `ensure...()` helper, can interaction still wait for query readiness when needed?
+
+## Why this page exists
+
+`$useStateData(...)` is easy to misuse if it is treated only as a request helper.
+
+The larger value is architectural:
+
+- model-owned async state gets one stable owner
+- query identity, persistence, restore, and refetch behavior stay in one place
+- render logic can consume a formal query state instead of rebuilding mini loading/cache systems in controllers
+
+The common failure mode is not that the code stops working immediately.
+
+The common failure mode is that the code keeps working while the state model becomes increasingly command-oriented, duplicated, and difficult to reason about.
+
+## The core mental model
+
+The best starting point is simple:
+
+> treat `$useStateData(...)` as a model-owned async state source, not only as a function that happens to fetch data.
+
+That changes several downstream decisions.
+
+If a value affects:
+
+- whether a button can be clicked
+- accepted file types
+- maximum upload size
+- whether a UI branch is shown
+- whether a flow can continue safely
+
+then that value is usually not just a click-time fetch result.
+It is part of the page's real interaction state.
+
+## Practical rule 1: prefer model ownership for reusable async state
+
+When a value has broader reuse, persistence, or lifecycle requirements, prefer model ownership.
+
+Typical good fits are:
+
+- upload policy by scene
+- resource bootstrap
+- schema metadata
+- permission/capability state
+- query-style domain state reused across pages or components
+
+Typical weak fits are:
+
+- a one-off page-local toggle
+- a tiny local interaction detail with no reuse value
+- temporary page-only state that does not benefit from caching or restore semantics
+
+### Review question
+
+Ask:
+
+> if another controller needed this same async value tomorrow, would I want the ownership and lifecycle policy to already exist in one model?
+
+If the answer is yes, that state usually belongs in a model.
+
+## Practical rule 2: if the value affects render or interaction rules, establish the query during render
+
+If a value determines runtime interaction conditions, prefer this shape:
+
+1. model exposes `getXxx(...)`
+2. controller/page establishes the query during render
+3. render consumes `data`, `pending`, and derived values
+4. interaction consumes that existing query state instead of inventing a second lifecycle
+
+### Why this is good
+
+This keeps the UI honest.
+
+The rendered UI can already know:
+
+- whether interaction should wait
+- which accept/multiple flags apply
+- which validation path should be used
+
+### Smell
+
+A controller renders as though the interaction is ready, but clicking the button is what really begins the important state lookup.
+
+That is a sign that a query-state concern may have been pushed too far into imperative interaction code.
+
+## Practical rule 3: `disableSuspenseOnInit: true` disables the init-time `query.suspense()` kick, not the query itself
+
+This point needs precise wording.
+
+Current model runtime shows that `$useStateData(...)` creates the query wrapper first, then, only on first creation, optionally calls `query.suspense()`:
+
+```ts
+if (!this[SymbolUseQueries][queryHash]) {
+  const useQuery = this.$useQuery(options, queryClient);
+  this[SymbolUseQueries][queryHash] = useQuery;
+  if (!options.meta?.disableSuspenseOnInit) {
+    useQuery.suspense();
+  }
+}
+```
+
+Two details matter:
+
+- the query is already created either way
+- the runtime does **not** use `await` there
+
+So `disableSuspenseOnInit: true` does **not** mean “block vs do not block render” in a strict synchronous sense.
+
+It more precisely means:
+
+- with default behavior, the first consumer of that query immediately kicks one init-time `query.suspense()` call
+- with `disableSuspenseOnInit: true`, that automatic init-time kick is skipped
+
+This option is often a good fit when you want:
+
+- query state to exist immediately
+- persistence/restore/refetch behavior to remain normal
+- no automatic init-time `query.suspense()` kick on first creation
+
+Representative pattern:
+
+```ts
+getUploadPolicy(imageScene?: string) {
+  if (!imageScene) return undefined;
+  return this.$useStateData({
+    queryKey: ['uploadPolicy', 'image', imageScene],
+    queryFn: async () => {
+      return this.scope.api.image.getUploadPolicy({ imageScene });
+    },
+    meta: {
+      disableSuspenseOnInit: true,
+    },
+  });
+}
+```
+
+### What it does not mean
+
+It does not mean:
+
+- no query should be created
+- no request should run
+- no persisted value should be restored
+- no refetch should happen later
+- interaction can never explicitly wait for query readiness
+
+That distinction matters a lot.
+
+## Practical rule 4: distinguish three different semantics
+
+A useful review habit is to keep these three behaviors separate.
+
+| Case                                                            | What happens                                                                       | What it does **not** mean                                                          | Best fit                                                                                                                         |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Default `$useStateData(...)`                                    | On first query creation, runtime immediately calls `query.suspense()` once         | It does **not** synchronously `await` readiness in that call site                  | Data where “first consumer should eagerly kick one refresh/update semantic” is a good default                                    |
+| `$useStateData(..., { meta: { disableSuspenseOnInit: true } })` | Query still exists, but the automatic init-time `query.suspense()` kick is skipped | It does **not** disable the query, persistence, restore, or later refetch behavior | Data that is relatively stable inside the current frontend process and does not need an automatic first-consumer kick every time |
+| `await query.suspense()`                                        | Current logic sequence explicitly waits until the query is ready                   | It is **not** merely a hint or passive kickoff                                     | Interaction or orchestration boundaries where later logic must not continue until the value is ready                             |
+
+Two practical consequences follow from this table:
+
+1. multiple synchronous `query.suspense()` calls can still deduplicate at the query runtime level
+2. only explicit `await query.suspense()` introduces a true sequencing guarantee for the current logic path
+
+## Practical rule 5: be cautious with `enabled: false` and `staleTime: Infinity`
+
+These options are useful, but they are easy to over-apply.
+
+### `enabled: false`
+
+Use it when the query should not exist yet because a real prerequisite is missing.
+
+Good examples:
+
+- required params are absent
+- the page is in a branch where the query truly does not apply
+- the query would be meaningless or invalid before some explicit condition
+
+Be cautious when the real motivation is only:
+
+- “I want to fetch later when the user clicks”
+
+That often means you are taking a state concern and turning it back into a command concern.
+
+### `staleTime: Infinity`
+
+Use it when the value is effectively static for the relevant session.
+
+Be cautious when the underlying backend configuration may change.
+
+If backend scene config can change, letting the query participate in normal freshness/refetch rules is usually healthier than freezing it forever.
+
+## Practical rule 6: removing a manual `ensure...()` helper does not mean interaction can never wait
+
+A common over-correction is:
+
+- first version: controller manually owns fetching through `ensure...()`
+- second version: remove `ensure...()` and assume interaction must never wait for anything
+
+The better middle ground is:
+
+- query lifecycle remains model-owned
+- query is established during render
+- interaction consumes the existing query
+- if an edge timing window appears, interaction may wait for the existing query to finish
+
+That is very different from rebuilding a second fetch lifecycle.
+
+## Practical rule 7: derive render-time state once per render when possible
+
+Even when the query object is reused, a controller can still become noisy if it repeatedly derives the same values in several helper calls.
+
+A good cleanup pattern is to derive one local state object such as:
+
+- `acceptAttr`
+- `multiple`
+- `pending`
+
+and let input/button/render branches consume that shared result.
+
+### Why this helps
+
+It makes one render pass easier to understand:
+
+- what query-backed state is being consumed
+- which UI props come from that state
+- where the interaction gate really is
+
+### Smell
+
+The controller repeatedly:
+
+- grabs the same query
+- re-reads the same policy data
+- re-derives the same `multiple` or `accept` value in several places
+
+That is often a sign that local render-time derivation should be consolidated.
+
+## Practical rule 8: design query keys so the ownership boundary is obvious
+
+Prefer keys that make the domain explicit.
+
+For example:
+
+- `['uploadPolicy', 'image', imageScene]`
+- `['uploadPolicy', 'file', fileScene]`
+
+This is usually better than ambiguous cross-domain shapes such as:
+
+- `['uploadPolicy', scene]`
+
+### Why this matters
+
+Readable keys improve:
+
+- debugging
+- tracing cache behavior
+- future refactors when similar query families grow
+
+## Anti-pattern: command-first controller state
+
+A common anti-pattern looks like this:
+
+- model query is disabled by default
+- controller clicks trigger `ensure...()`
+- controller maintains the important timing logic itself
+- render does not fully know the interaction conditions yet
+
+### Why this is harmful
+
+- the model no longer owns the full lifecycle cleanly
+- restore/refetch semantics are weakened or bypassed
+- controller responsibilities grow too large
+- interaction rules become harder to inspect from the render path
+
+## Better pattern: model-owned query, render-owned derivation, interaction-owned orchestration
+
+A healthier split is:
+
+### Model owns
+
+- `queryKey`
+- `queryFn`
+- persistence/restore/refetch lifecycle
+- the stable meaning of the async state
+
+### Controller/page owns
+
+- how the query-backed state is rendered
+- derived props needed by the current UI
+- user interaction flow
+- edge-timing waits on the already-existing query when necessary
+
+This creates a much cleaner division of responsibilities.
+
+## Representative examples
+
+### Example A: resource entry pages usually prefer the default init-time kick
+
+A good counterexample to overusing `disableSuspenseOnInit: true` is the resource entry-page branch.
+
+Useful reading pages are:
+
+- [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+In that branch, the practical expectation is often:
+
+- opening a row page may show an already-known value first
+- but entering that page should still eagerly kick one update semantic for the item-level state
+- the page benefits from the default “first consumer kicks `query.suspense()` once” behavior
+
+This makes entry pages a good mental model for queries where the default init-time kick is healthy:
+
+- the query is a real page-state dependency
+- the first consumer should actively nudge freshness
+- you usually do not want every caller to remember to add that kickoff manually
+
+This is not about synchronous blocking.
+It is about preserving the default eager-init semantic when the first consumer of that page state appears.
+
+### Example B: upload policy prefers `disableSuspenseOnInit: true`
+
+Representative files in the Cabloy Basic frontend:
+
+- `zova/src/suite/cabloy-basic/modules/basic-image/src/model/image.ts`
+- `zova/src/suite/cabloy-basic/modules/basic-file/src/model/file.ts`
+- `zova/src/suite/cabloy-basic/modules/basic-image/src/component/formFieldImage/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-file/src/component/formFieldFile/controller.tsx`
+
+### What this example demonstrates
+
+- `getUploadPolicy(...)` stays in the model
+- the query is created as formal state instead of a one-off click helper
+- `disableSuspenseOnInit: true` skips the automatic init-time `query.suspense()` kick while preserving the query as formal state
+- render derives `acceptAttr`, `multiple`, and `pending`
+- interaction reuses that state
+- interaction may still `await query.suspense()` on the already-created query if an edge timing window requires it
+
+Why this is a good fit:
+
+- upload policy is a real query-backed state
+- it is relatively stable within the current frontend process
+- every first consumer does not need to auto-kick one eager init-time refresh semantic
+- the strict-ready moment is the interaction boundary, not every initial render consumer
+
+Taken together, Example A and Example B show the most important design contrast on this page:
+
+- entry-page item state is a good example of why the default init-time kick can be valuable
+- upload policy is a good example of why a stable state may still be a formal query while skipping that init-time kick
+
+## Checklist before you use `$useStateData(...)`
+
+Ask these questions:
+
+1. Is this value really a reusable async state source rather than a one-off action result?
+2. Will this value affect render or interaction conditions?
+3. Should another page or controller be able to consume the same lifecycle and cache policy later?
+4. Is `disableSuspenseOnInit: true` enough, instead of disabling the query entirely?
+5. Would `enabled: false` or `staleTime: Infinity` accidentally cut off useful restore/refetch behavior?
+6. If interaction needs a safety wait, can it wait on the existing query rather than reintroducing a manual `ensure...()` lifecycle?
+7. Can I derive the render-time state once and reuse it across the UI branch?
+
+## Final takeaway
+
+The most important usage insight is simple:
+
+> `$useStateData(...)` is strongest when it models async state that the UI can render from, persist, restore, and refresh naturally.
+
+When that mindset is clear, controllers become thinner, models become more authoritative, and query lifecycle decisions become easier to reason about.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.98",
+  "version": "5.1.100",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/scripts/upgrade.ts

@@ -50,6 +50,7 @@ const OVERWRITE_DIRS: string[] = [
 const MERGE_DIRS: string[] = [
   // Claude project assets
   '.claude/commands',
+  '.claude/hooks',
   '.claude/skills',
   // Vona Claude project assets
   'vona/.claude/commands',
@@ -67,6 +68,7 @@ const BLACKLIST_DIRS: string[] = [
 const WHITELIST_FILES: string[] = [
   // root
   'CLAUDE.md',
+  '.claude/settings.json',
   'tsconfig.json',
   'tsconfig.base.json',
   'tsconfig.base.esm.json',

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.128",
+  "version": "1.1.129",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.126",
+  "version": "1.1.127",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.71",
+  "version": "5.1.72",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/packages-vona/vona-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.31",
+  "version": "5.1.32",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/bean/beanBase.ts

@@ -1,29 +1,29 @@
 import type winston from 'winston';
 
 import type { ILoggerChildRecord, ILoggerClientRecord } from '../../types/interface/logger.ts';
-import type { IModuleLocaleText } from './resource/locale/type.ts';
+// import type { IModuleLocaleText } from './resource/locale/type.ts';
 import type { IBeanScopeContainer } from './scope/beanScopeContainer.ts';
 
 import { BeanBaseSimple, SymbolBeanInstanceKey, SymbolModuleBelong } from './beanBaseSimple.ts';
 
-const SymbolText = Symbol('SymbolText');
+// const SymbolText = Symbol('SymbolText');
 const SymbolLogger = Symbol('SymbolLogger');
 const SymbolLoggerChildren = Symbol('SymbolLoggerChildren');
 
 export class BeanBase extends BeanBaseSimple {
-  private [SymbolText]: IModuleLocaleText;
+  // private [SymbolText]: IModuleLocaleText;
   private [SymbolLogger]: Record<keyof ILoggerClientRecord, winston.Logger> = {} as any;
   private [SymbolLoggerChildren]: Record<
     keyof ILoggerClientRecord,
     Record<string, winston.Logger>
   > = {} as any;
 
-  protected get $text(): IModuleLocaleText {
-    if (!this[SymbolText]) {
-      this[SymbolText] = this.app.meta.locale.createLocaleText(this[SymbolModuleBelong]);
-    }
-    return this[SymbolText];
-  }
+  // protected get $text(): IModuleLocaleText {
+  //   if (!this[SymbolText]) {
+  //     this[SymbolText] = this.app.meta.locale.createLocaleText(this[SymbolModuleBelong]);
+  //   }
+  //   return this[SymbolText];
+  // }
 
   protected get $logger() {
     return this.$loggerClient('default');

package/vona/packages-vona/vona-mock/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-mock",
-  "version": "6.1.31",
+  "version": "6.1.32",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona mock",
   "keywords": [