cabloy 5.1.148 → 5.1.150

package/zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionSummary.tsx

@@ -9,6 +9,7 @@ import type { ModelStudent } from 'zova-module-training-student';
 
 import { BeanBase } from 'zova';
 import { TableCell } from 'zova-module-a-table';
+import { ZMarkdownHtml } from 'zova-module-basic-markdown';
 
 declare module 'zova-module-a-openapi' {
   export interface IResourceTableActionRowRecord {
@@ -39,14 +40,24 @@ export class TableCellActionSummary extends BeanBase implements ITableCellRender
             true,
           )) as ModelStudent;
           const querySummary = modelStudent.summary(id);
-          const { data: summary } = await querySummary.refetch();
-          const message = [
-            `${this.scope.locale.Id()}: ${summary?.id ?? '-'}`,
-            `${this.scope.locale.Name()}: ${summary?.name ?? '-'}`,
-            `${this.scope.locale.Level()}: ${summary?.level ?? '-'}`,
-            `${this.scope.locale.Description()}: ${summary?.description ?? '-'}`,
-          ].join('\n');
-          await $host.$performCommand('basic-commands:alert', { text: message }, renderContext);
+          await querySummary.refetch({ bypassPersister: true });
+          $host.$appModal.dialog(
+            {
+              title: this.scope.locale.Summary(),
+              slotDefault: () => (
+                <div class="student-summary-description">
+                  <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />
+                </div>
+              ),
+            },
+            {
+              maxWidth: 720,
+              maxHeight: 'calc(100vh - 2rem)',
+              closeOnBackdrop: true,
+              closeOnEscape: true,
+              showCloseButton: true,
+            },
+          );
         }}
       >
         {this.scope.locale.Summary()}

package/zova/src/suite/cabloy-basic/modules/basic-app/src/bean/behavior.appModal.tsx

@@ -290,6 +290,8 @@ export class BehaviorAppModal extends BeanBehaviorBase<
           }}
         ></div>
         <div
+          role="dialog"
+          aria-modal="true"
           class="card bg-base-100 shadow-2xl relative w-full max-h-[calc(100vh-2rem)]"
           style={style}
         >

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-rest-resource",
-  "version": "5.1.46",
+  "version": "5.1.47",
   "gitHead": "4dece229b6d3f4735930e833afcb4b95ec51bf86",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts

@@ -1,5 +1,5 @@
 import type { TableIdentity } from 'table-identity';
-import type { DataMutation, IDecoratorModelOptions } from 'zova-module-a-model';
+import type { DataMutation, IDecoratorModelOptions, QueryMetaPersister } from 'zova-module-a-model';
 import type {
   IFormMeta,
   IFormProvider,
@@ -27,6 +27,7 @@ interface IModelResourceQueryItemOptions<TData> {
   meta?: {
     disableSuspenseOnInit?: boolean;
     disableErrorEffect?: boolean;
+    persister?: QueryMetaPersister | boolean;
   };
 }
 

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/test/model/resource.types.ts

@@ -17,6 +17,17 @@ void requiredBody.delete(id).mutateAsync({ reason: 'duplicate' });
 void optionalBody.delete(id).mutateAsync();
 void optionalBody.delete(id).mutateAsync({ reason: 'duplicate' });
 
+const queryItem = standard.queryItem({
+  id,
+  action: 'summary',
+  queryFn: async () => ({ id: 1 }),
+});
+void queryItem.refetch({
+  bypassPersister: true,
+  cancelRefetch: false,
+  throwOnError: true,
+});
+
 // @ts-expect-error required DELETE bodies cannot be omitted
 void requiredBody.delete(id).mutateAsync();
 

package/zova/src/suite-vendor/a-cabloy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-suite-a-cabloy",
-  "version": "5.1.47",
+  "version": "5.1.48",
   "gitHead": "4dece229b6d3f4735930e833afcb4b95ec51bf86",
   "description": "",
   "author": "",
@@ -8,7 +8,7 @@
   "type": "module",
   "dependencies": {
     "zova-module-a-rbac": "^5.0.1",
-    "zova-module-rest-resource": "^5.1.46"
+    "zova-module-rest-resource": "^5.1.47"
   },
   "title": "a-cabloy"
 }

package/zova/src/suite-vendor/a-zova/modules/a-form/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-form",
-  "version": "5.1.48",
+  "version": "5.1.50",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts

@@ -24,12 +24,21 @@ export function resolveFormLayout(
   layout: IFormLayout,
   properties: ISchemaObjectExtensionField[] | undefined,
 ): IResolvedFormLayout {
+  const visibleProperties = properties?.filter(item => item.rest?.visible !== false) ?? [];
   const propertyNames = new Set(
-    properties
-      ?.filter(item => item.rest?.visible !== false)
-      .map(item => item.key)
-      .filter(Boolean) as string[],
+    visibleProperties.map(item => item.key).filter(Boolean) as string[],
   );
+  const propertyAliases = new Map<string, Set<string>>();
+  for (const property of visibleProperties) {
+    if (!property.key) continue;
+    const schemaKeys = [property.schemaKey, ...(property.schemaKeys ?? [])];
+    for (const schemaKey of schemaKeys) {
+      if (!schemaKey || schemaKey === property.key) continue;
+      const aliases = propertyAliases.get(schemaKey) ?? new Set<string>();
+      aliases.add(property.key);
+      propertyAliases.set(schemaKey, aliases);
+    }
+  }
   const fieldNames = new Set<string>();
   const nodeIds = new Set<string>();
   const diagnostics: IFormLayoutDiagnostic[] = [];
@@ -41,6 +50,7 @@ export function resolveFormLayout(
         [index],
         [],
         propertyNames,
+        propertyAliases,
         fieldNames,
         nodeIds,
         diagnostics,
@@ -62,13 +72,22 @@ function resolveNode(
   indexPath: number[],
   tabPath: IResolvedFormLayout['fieldTabPaths'][string],
   propertyNames: Set<string>,
+  propertyAliases: Map<string, Set<string>>,
   fieldNames: Set<string>,
   nodeIds: Set<string>,
   diagnostics: IFormLayoutDiagnostic[],
   fieldTabPaths: IResolvedFormLayout['fieldTabPaths'],
 ): IResolvedFormLayoutNode | undefined {
   if (node.type === 'field') {
-    return resolveField(node, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths);
+    return resolveField(
+      node,
+      tabPath,
+      propertyNames,
+      propertyAliases,
+      fieldNames,
+      diagnostics,
+      fieldTabPaths,
+    );
   }
   if (node.type === 'block') {
     return node;
@@ -78,6 +97,7 @@ function resolveNode(
       node,
       indexPath,
       propertyNames,
+      propertyAliases,
       fieldNames,
       nodeIds,
       diagnostics,
@@ -89,7 +109,15 @@ function resolveNode(
   if (node.type === 'section') {
     const children = node.children
       .map(item =>
-        resolveLeaf(item, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths),
+        resolveLeaf(
+          item,
+          tabPath,
+          propertyNames,
+          propertyAliases,
+          fieldNames,
+          diagnostics,
+          fieldTabPaths,
+        ),
       )
       .filter(Boolean) as IResolvedFormLayoutLeaf[];
     return children.length ? { ...node, id, children } : undefined;
@@ -101,6 +129,7 @@ function resolveNode(
         [...indexPath, index],
         tabPath,
         propertyNames,
+        propertyAliases,
         fieldNames,
         nodeIds,
         diagnostics,
@@ -117,18 +146,28 @@ function resolveLeaf(
   node: IFormLayoutLeaf,
   tabPath: IResolvedFormLayout['fieldTabPaths'][string],
   propertyNames: Set<string>,
+  propertyAliases: Map<string, Set<string>>,
   fieldNames: Set<string>,
   diagnostics: IFormLayoutDiagnostic[],
   fieldTabPaths: IResolvedFormLayout['fieldTabPaths'],
 ): IResolvedFormLayoutLeaf | undefined {
   if (node.type === 'block') return node;
-  return resolveField(node, tabPath, propertyNames, fieldNames, diagnostics, fieldTabPaths);
+  return resolveField(
+    node,
+    tabPath,
+    propertyNames,
+    propertyAliases,
+    fieldNames,
+    diagnostics,
+    fieldTabPaths,
+  );
 }
 
 function resolveTabs(
   node: IFormLayoutTabs,
   indexPath: number[],
   propertyNames: Set<string>,
+  propertyAliases: Map<string, Set<string>>,
   fieldNames: Set<string>,
   nodeIds: Set<string>,
   diagnostics: IFormLayoutDiagnostic[],
@@ -143,6 +182,7 @@ function resolveTabs(
         [...indexPath, index],
         id,
         propertyNames,
+        propertyAliases,
         fieldNames,
         nodeIds,
         diagnostics,
@@ -158,6 +198,7 @@ function resolveTab(
   indexPath: number[],
   tabsId: string,
   propertyNames: Set<string>,
+  propertyAliases: Map<string, Set<string>>,
   fieldNames: Set<string>,
   nodeIds: Set<string>,
   diagnostics: IFormLayoutDiagnostic[],
@@ -173,6 +214,7 @@ function resolveTab(
         [...indexPath, index],
         tabPath,
         propertyNames,
+        propertyAliases,
         fieldNames,
         nodeIds,
         diagnostics,
@@ -189,21 +231,36 @@ function resolveField(
   node: IFormLayoutField,
   tabPath: IResolvedFormLayout['fieldTabPaths'][string],
   propertyNames: Set<string>,
+  propertyAliases: Map<string, Set<string>>,
   fieldNames: Set<string>,
   diagnostics: IFormLayoutDiagnostic[],
   fieldTabPaths: IResolvedFormLayout['fieldTabPaths'],
 ): IResolvedFormLayoutField | undefined {
-  if (!propertyNames.has(node.name)) {
+  const name = resolveFieldName(node.name, propertyNames, propertyAliases);
+  if (!name) {
     diagnostics.push({ type: 'unknownField', value: node.name });
     return;
   }
-  if (fieldNames.has(node.name)) {
+  if (fieldNames.has(name)) {
     diagnostics.push({ type: 'duplicateField', value: node.name });
     return;
   }
-  fieldNames.add(node.name);
-  fieldTabPaths[node.name] = tabPath;
-  return node;
+  fieldNames.add(name);
+  fieldTabPaths[name] = tabPath;
+  return name === node.name ? node : { ...node, name };
+}
+
+function resolveFieldName(
+  name: string,
+  propertyNames: Set<string>,
+  propertyAliases: Map<string, Set<string>>,
+) {
+  if (propertyNames.has(name)) return name;
+  const aliases = propertyAliases.get(name);
+  if (aliases?.size === 1) return aliases.values().next().value;
+  const fieldSourcePrefix = `${name}.`;
+  const fieldSources = [...propertyNames].filter(item => item.startsWith(fieldSourcePrefix));
+  return fieldSources.length === 1 ? fieldSources[0] : undefined;
 }
 
 function resolveId(node: { type: string; id?: string }, indexPath: number[]) {

package/zova/src/suite-vendor/a-zova/modules/a-form/test/lib/formLayout.test.ts

@@ -0,0 +1,157 @@
+import type { IFormLayout, ISchemaObjectExtensionField } from 'zova-module-a-openapi';
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { resolveFormLayout } from '../../src/lib/formLayout.js';
+
+function createProperties(...properties: ISchemaObjectExtensionField[]) {
+  return properties;
+}
+
+function createTabsLayout(name: string): IFormLayout {
+  return {
+    children: [
+      {
+        type: 'tabs',
+        children: [
+          {
+            type: 'tab',
+            title: 'Content',
+            children: [{ type: 'section', children: [{ type: 'field', name }] }],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function getTabFieldNames(resolved: ReturnType<typeof resolveFormLayout>) {
+  const tabs = resolved.children[0] as any;
+  return tabs.children[0].children[0].children.map((item: any) => item.name);
+}
+
+test('Form Layout resolves a real relation name to its unique canonical source', () => {
+  const resolved = resolveFormLayout(
+    createTabsLayout('content'),
+    createProperties({ key: 'content.descriptionMarkdown', type: 'string' }),
+  );
+
+  assert.deepEqual(getTabFieldNames(resolved), ['content.descriptionMarkdown']);
+  assert.deepEqual(resolved.fieldTabPaths, {
+    'content.descriptionMarkdown': [{ tabsId: 'tabs-0', tabId: 'tab-0-0' }],
+  });
+  assert.deepEqual(resolved.diagnostics, []);
+});
+
+test('Form Layout resolves a virtual schema alias to its canonical source', () => {
+  const resolved = resolveFormLayout(
+    createTabsLayout('_descriptionMarkdown'),
+    createProperties({
+      key: 'content.descriptionMarkdown',
+      schemaKey: '_descriptionMarkdown',
+      type: 'string',
+    }),
+  );
+
+  assert.deepEqual(getTabFieldNames(resolved), ['content.descriptionMarkdown']);
+  assert.deepEqual(resolved.fieldTabPaths, {
+    'content.descriptionMarkdown': [{ tabsId: 'tabs-0', tabId: 'tab-0-0' }],
+  });
+  assert.deepEqual(resolved.diagnostics, []);
+});
+
+test('Form Layout accepts every preserved alias for the same canonical source', () => {
+  const resolved = resolveFormLayout(
+    createTabsLayout('studentContentForm'),
+    createProperties({
+      key: 'content.descriptionMarkdown',
+      schemaKey: '_descriptionMarkdown',
+      schemaKeys: ['studentContentForm'],
+      type: 'string',
+    }),
+  );
+
+  assert.deepEqual(getTabFieldNames(resolved), ['content.descriptionMarkdown']);
+  assert.deepEqual(resolved.diagnostics, []);
+});
+
+test('Form Layout prefers an exact canonical field over a colliding alias', () => {
+  const resolved = resolveFormLayout(
+    { children: [{ type: 'field', name: 'content' }] },
+    createProperties(
+      { key: 'content', type: 'object' },
+      {
+        key: 'content.descriptionMarkdown',
+        schemaKey: 'content',
+        type: 'string',
+      },
+    ),
+  );
+
+  assert.deepEqual(resolved.children, [
+    { type: 'field', name: 'content' },
+    { type: 'field', name: 'content.descriptionMarkdown' },
+  ]);
+  assert.deepEqual(resolved.diagnostics, []);
+});
+
+test('Form Layout detects duplicate alias and canonical declarations by canonical key', () => {
+  const resolved = resolveFormLayout(
+    {
+      children: [
+        { type: 'field', name: '_descriptionMarkdown' },
+        { type: 'field', name: 'content.descriptionMarkdown' },
+      ],
+    },
+    createProperties({
+      key: 'content.descriptionMarkdown',
+      schemaKey: '_descriptionMarkdown',
+      type: 'string',
+    }),
+  );
+
+  assert.deepEqual(resolved.children, [{ type: 'field', name: 'content.descriptionMarkdown' }]);
+  assert.deepEqual(resolved.diagnostics, [
+    { type: 'duplicateField', value: 'content.descriptionMarkdown' },
+  ]);
+});
+
+test('Form Layout keeps ambiguous aliases and relation prefixes unknown', () => {
+  const resolved = resolveFormLayout(
+    {
+      children: [
+        { type: 'field', name: '_content' },
+        { type: 'field', name: 'content' },
+      ],
+    },
+    createProperties(
+      { key: 'content.descriptionMarkdown', schemaKey: '_content', type: 'string' },
+      { key: 'content.descriptionHtml', schemaKey: '_content', type: 'string' },
+    ),
+  );
+
+  assert.deepEqual(resolved.children, [
+    { type: 'field', name: 'content.descriptionMarkdown' },
+    { type: 'field', name: 'content.descriptionHtml' },
+  ]);
+  assert.deepEqual(resolved.diagnostics, [
+    { type: 'unknownField', value: '_content' },
+    { type: 'unknownField', value: 'content' },
+  ]);
+});
+
+test('Form Layout does not resolve or append invisible aliases', () => {
+  const resolved = resolveFormLayout(
+    { children: [{ type: 'field', name: '_descriptionMarkdown' }] },
+    createProperties({
+      key: 'content.descriptionMarkdown',
+      schemaKey: '_descriptionMarkdown',
+      type: 'string',
+      rest: { visible: false },
+    }),
+  );
+
+  assert.deepEqual(resolved.children, []);
+  assert.deepEqual(resolved.diagnostics, [{ type: 'unknownField', value: '_descriptionMarkdown' }]);
+});

package/zova/src/suite-vendor/a-zova/modules/a-model/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-model",
-  "version": "5.1.35",
+  "version": "5.1.36",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "core",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts

@@ -7,6 +7,7 @@ import { SymbolBeanFullName } from 'zova';
 import type { QueryMetaPersister } from '../../types/index.js';
 
 import { CookieWrapper } from '../../common/cookieWrapper.js';
+import { createQueryPersister } from '../../lib/queryPersister.js';
 import { resolveMaxAgeTime } from '../../types/index.js';
 import { BeanModelLast } from './bean.model.last.js';
 
@@ -145,13 +146,14 @@ export class BeanModelPersister extends BeanModelLast {
   protected _createPersister(options?: QueryMetaPersister | boolean): any {
     options = this._adjustPersisterOptions(options);
     if (!options) return undefined;
-    return experimental_createQueryPersister({
+    const persisterFn = experimental_createQueryPersister({
       storage: this._getPersisterStorage(options) as any,
       maxAge: options.maxAge as number,
       refetchOnRestore: options.refetchOnRestore,
       prefix: options.prefix,
       buster: options.buster,
     }).persisterFn;
+    return createQueryPersister(persisterFn);
   }
 
   protected _adjustPersisterOptions(options?: QueryMetaPersister | boolean) {

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts

@@ -1,12 +1,4 @@
-import type {
-  DefaultError,
-  QueryClient,
-  QueryKey,
-  UseQueryDefinedReturnType,
-  UseQueryOptions,
-  UseQueryReturnType,
-} from '@tanstack/vue-query';
-import type { UnwrapNestedRefs } from 'vue';
+import type { DefaultError, QueryClient, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
 
 import { checkErrorJwtExpired } from '@cabloy/utils';
 import { useQuery } from '@tanstack/vue-query';
@@ -16,7 +8,9 @@ import type {
   DefinedInitialQueryOptions,
   UndefinedInitialQueryOptions,
 } from '../../common/types.js';
+import type { ModelUseQueryDefinedReturnType, ModelUseQueryReturnType } from '../../types/query.js';
 
+import { createQueryRefetch } from '../../lib/queryRefetch.js';
 import { resolveStaleTime } from '../../types/index.js';
 import { BeanModelQuery } from './bean.model.query.js';
 
@@ -29,7 +23,7 @@ export class BeanModelUseQuery extends BeanModelQuery {
   >(
     options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
+  ): ModelUseQueryReturnType<TData, TError>;
   $useQuery<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -38,7 +32,7 @@ export class BeanModelUseQuery extends BeanModelQuery {
   >(
     options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryDefinedReturnType<TData, TError>>;
+  ): ModelUseQueryDefinedReturnType<TData, TError>;
   $useQuery<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -47,7 +41,7 @@ export class BeanModelUseQuery extends BeanModelQuery {
   >(
     options: UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
+  ): ModelUseQueryReturnType<TData, TError>;
   $useQuery(options, queryClient) {
     const queryKey = this.self._forceQueryKeyPrefix(options.queryKey);
     const persister = this._createPersister(options.meta?.persister);
@@ -81,7 +75,11 @@ export class BeanModelUseQuery extends BeanModelQuery {
       };
     }
     return this.ctx.util.instanceScope(() => {
-      return useQuery(options, queryClient);
+      const query = useQuery(options, queryClient) as unknown as ModelUseQueryReturnType<any, any>;
+      query.refetch = createQueryRefetch(query.refetch, () =>
+        this.$queryFind({ queryKey }),
+      ) as typeof query.refetch;
+      return query;
     });
   }
 }

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useState.ts

@@ -4,11 +4,8 @@ import type {
   QueryClient,
   QueryKey,
   QueryMeta,
-  UseQueryDefinedReturnType,
   UseQueryOptions,
-  UseQueryReturnType,
 } from '@tanstack/vue-query';
-import type { UnwrapNestedRefs } from 'vue';
 
 import { hashKey } from '@tanstack/vue-query';
 import { deepExtend } from 'zova';
@@ -17,7 +14,12 @@ import type {
   DefinedInitialQueryOptions,
   UndefinedInitialQueryOptions,
 } from '../../common/types.js';
-import type { QueryMetaPersister, UseQueryComputedOptions } from '../../types/query.js';
+import type {
+  ModelUseQueryDefinedReturnType,
+  ModelUseQueryReturnType,
+  QueryMetaPersister,
+  UseQueryComputedOptions,
+} from '../../types/query.js';
 
 import { BeanModelUseQuery } from './bean.model.useQuery.js';
 
@@ -311,7 +313,7 @@ export class BeanModelUseState extends BeanModelUseQuery {
   >(
     options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
+  ): ModelUseQueryReturnType<TData, TError>;
   $useStateData<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -320,7 +322,7 @@ export class BeanModelUseState extends BeanModelUseQuery {
   >(
     options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryDefinedReturnType<TData, TError>>;
+  ): ModelUseQueryDefinedReturnType<TData, TError>;
   $useStateData<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -329,7 +331,7 @@ export class BeanModelUseState extends BeanModelUseQuery {
   >(
     options: UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
+  ): ModelUseQueryReturnType<TData, TError>;
   $useStateData(options, queryClient) {
     const queryKey = this.self._forceQueryKeyPrefix(options.queryKey);
     const queryHash = hashKey(queryKey);

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useStateGeneral.ts

@@ -1,17 +1,10 @@
-import type {
-  DefaultError,
-  QueryClient,
-  QueryKey,
-  UseQueryDefinedReturnType,
-  UseQueryOptions,
-  UseQueryReturnType,
-} from '@tanstack/vue-query';
-import type { UnwrapNestedRefs } from 'vue';
+import type { DefaultError, QueryClient, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
 
 import type {
   DefinedInitialQueryOptions,
   UndefinedInitialQueryOptions,
 } from '../../common/types.js';
+import type { ModelUseQueryDefinedReturnType, ModelUseQueryReturnType } from '../../types/query.js';
 import type { StateType } from '../../types/query.js';
 
 import { BeanModelUseState } from './bean.model.useState.js';
@@ -56,7 +49,7 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
     stateType: 'data',
     options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
+  ): ModelUseQueryReturnType<TData, TError>;
   $useState<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -66,7 +59,7 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
     stateType: 'data',
     options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryDefinedReturnType<TData, TError>>;
+  ): ModelUseQueryDefinedReturnType<TData, TError>;
   $useState<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -76,7 +69,7 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
     stateType: 'data',
     options: UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
     queryClient?: QueryClient,
-  ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
+  ): ModelUseQueryReturnType<TData, TError>;
   $useState(stateType: StateType, options, queryClient) {
     switch (stateType) {
       case 'localAsync':

package/zova/src/suite-vendor/a-zova/modules/a-model/src/lib/queryPersister.ts

@@ -0,0 +1,17 @@
+import type { QueryPersister } from '@tanstack/query-core';
+
+// TanStack's FetchMeta is internal to the public QueryPersister call path.
+type QueryFetchMeta = {
+  bypassPersister?: boolean;
+};
+
+export function createQueryPersister<T, TQueryKey extends readonly unknown[]>(
+  persisterFn: QueryPersister<T, TQueryKey>,
+): QueryPersister<T, TQueryKey> {
+  return (queryFn, context, query) => {
+    if ((query.state.fetchMeta as QueryFetchMeta | null)?.bypassPersister === true) {
+      return queryFn(context);
+    }
+    return persisterFn(queryFn, context, query);
+  };
+}