cabloy 5.1.172 → 5.1.174

package/zova/packages-zova/zova-core/src/composables/useController.ts

@@ -9,6 +9,7 @@ import {
 
 import type { IBeanRecord, IControllerData } from '../bean/type.ts';
 import type { Constructable } from '../decorator/index.ts';
+import type { IControllerLoadEvent } from '../types/interface/monkey.ts';
 
 import {
   BeanControllerIdentifier,
@@ -16,6 +17,7 @@ import {
   BeanStyleIdentifier,
   SymbolControllerRefDisable,
 } from '../bean/type.ts';
+import { normalizeError } from '../core/component/error.ts';
 import { ZovaContext } from '../core/context/index.ts';
 import { sys } from '../core/sys/sys.ts';
 
@@ -81,6 +83,7 @@ async function _useController(
 ) {
   // ctx
   const ctx = new ZovaContext(getCurrentInstance()!);
+  setLoadBoundaryOptions(controllerBeanFullName);
   // ctx: monkey
   if (ctx.app) {
     ctx.app.meta.module._monkeyModuleSync(true, 'appContextInitialize', undefined, ctx);
@@ -97,24 +100,31 @@ async function _useController(
       ctx,
     );
   }
-  if (process.env.CLIENT) {
-    // dispose
-    onBeforeUnmount(() => {
-      if (ctx.disposed) return;
-      // undefined better than null
-      setControllerRef(ctx, false);
-      if (ctx.bean !== ctx.app.bean) {
-        ctx.bean.dispose();
-      }
-    });
-    onUnmounted(() => {
-      ctx.dispose();
-    });
+
+  let retryPromise: Promise<void> | undefined;
+  let loadBeans = new Set<object>();
+
+  function setLoadBoundaryOptions(controllerBeanFullName: Constructable | string) {
+    const boundary = (controllerBeanFullName as any).$componentOptions?.boundary;
+    ctx.meta.state.setLoadRenderMode(boundary?.renderMode);
+    ctx.meta.state.setLoadRetryEnabled(boundary?.retry);
   }
 
-  async function __load() {
+  function isAttemptActive(attemptId: number) {
+    return ctx.meta.state.isLoadAttemptActive(attemptId);
+  }
+
+  function getLoadLoadingDelay() {
+    const delay =
+      (controllerBeanFullName as any).$componentOptions?.boundary?.loading?.delay ??
+      sys.config.boundary.loading?.delay;
+    const delayNumber = Number(delay);
+    return Number.isFinite(delayNumber) && delayNumber > 0 ? delayNumber : 0;
+  }
+
+  async function __loadBeans(attemptId: number) {
     // controller
-    if (ctx.disposed) return;
+    if (!isAttemptActive(attemptId)) return false;
     await ctx.bean._newBeanInner(
       true,
       BeanControllerIdentifier,
@@ -122,9 +132,17 @@ async function _useController(
       controllerBeanFullName,
       true,
       false,
+      controller => {
+        loadBeans.add(controller as object);
+        ctx.meta.state.setLoadBeanAttempt(controller as object, attemptId);
+        if (!isAttemptActive(attemptId)) return;
+        ctx.meta.state.setLoadController(controller);
+        setLoadBoundaryOptions((controller as any).constructor);
+      },
     );
+    if (!isAttemptActive(attemptId)) return false;
+    // style
     if (styleBeanFullName) {
-      if (ctx.disposed) return;
       await ctx.bean._newBeanInner(
         true,
         BeanStyleIdentifier,
@@ -132,10 +150,15 @@ async function _useController(
         styleBeanFullName,
         true,
         false,
+        style => {
+          loadBeans.add(style as object);
+          ctx.meta.state.setLoadBeanAttempt(style as object, attemptId);
+        },
       );
     }
+    if (!isAttemptActive(attemptId)) return false;
+    // render
     if (renderBeanFullName) {
-      if (ctx.disposed) return;
       await ctx.bean._newBeanInner(
         true,
         BeanRenderIdentifier,
@@ -143,14 +166,23 @@ async function _useController(
         renderBeanFullName,
         true,
         false,
+        render => {
+          loadBeans.add(render as object);
+          ctx.meta.state.setLoadBeanAttempt(render as object, attemptId);
+        },
       );
     }
-    // must touch inited on server/client, force router.use effect
-    if (ctx.disposed) return;
-    ctx.meta.state.inited.touch();
+    return isAttemptActive(attemptId);
+  }
+
+  async function __load(attemptId: number) {
+    if (!(await __loadBeans(attemptId))) return;
+    if (!isAttemptActive(attemptId)) return;
+    ctx.meta.state.setLoadReady();
     if (process.env.CLIENT) {
       ctx.util.instanceScope(() => {
         queuePostFlushCb(() => {
+          if (!isAttemptActive(attemptId)) return;
           setControllerRef(ctx, true);
           ctx.meta.hooks.invokeHook('mounted');
         });
@@ -158,15 +190,113 @@ async function _useController(
     }
   }
 
-  // load
-  ctx.meta.hooks.onCreated(async () => {
-    if (ctx.disposed) return;
+  async function runLoadAttempt(
+    attemptId: number,
+    beforeLoad?: () => void | Promise<void>,
+  ): Promise<void> {
     try {
-      return await __load();
+      await beforeLoad?.();
+      if (!isAttemptActive(attemptId)) return;
+      await __load(attemptId);
     } catch (err) {
+      if (!isAttemptActive(attemptId)) return;
+      const result = ctx.app?.meta.error.handleLoadError(err, ctx, ctx.instance as any) ?? {
+        err: normalizeError(err),
+        disposition: 'fallback' as const,
+      };
+      if (!isAttemptActive(attemptId)) return;
+      if (result.disposition === 'handled') {
+        ctx.meta.state.setLoadHandled();
+        return;
+      }
+      ctx.app?.meta.module._monkeyModuleSync(true, 'controllerLoad', undefined, {
+        phase: 'fallback',
+        ctx,
+        controllerBeanFullName,
+        controllerBeanName:
+          typeof controllerBeanFullName === 'string'
+            ? controllerBeanFullName
+            : controllerBeanFullName.name,
+        error: result.err,
+        controllerRecorded: !!ctx.meta.state.loadController,
+      });
+      if (!isAttemptActive(attemptId)) return;
+      ctx.meta.state.setLoadError(result.err);
+    }
+  }
+
+  function retry() {
+    if (!ctx.meta.state.isLoadRetryAvailable) return Promise.resolve();
+    if (retryPromise) return retryPromise;
+    const promise = (async () => {
+      const attemptId = ctx.meta.state.beginLoadAttempt(getLoadLoadingDelay());
+      const previousLoadBeans = loadBeans;
+      loadBeans = new Set();
+      ctx.meta.hooks.clearMounted();
+      setControllerRef(ctx, false);
+      await runLoadAttempt(attemptId, () => {
+        ctx.bean.retryReset(previousLoadBeans);
+      });
+    })();
+    retryPromise = promise;
+    void promise.finally(() => {
+      if (retryPromise === promise) {
+        retryPromise = undefined;
+      }
+    });
+    return promise;
+  }
+
+  ctx.meta.state.setLoadRetry(retry);
+  if (process.env.CLIENT) {
+    ctx.meta.hooks.onHydrated(() => {
+      if (!ctx.disposed) {
+        ctx.meta.state.setLoadRetryReady();
+      }
+    });
+    // dispose
+    onBeforeUnmount(() => {
       if (ctx.disposed) return;
-      throw err;
+      // undefined better than null
+      setControllerRef(ctx, false);
+      if (ctx.bean !== ctx.app.bean) {
+        ctx.bean.dispose();
+      }
+    });
+    onUnmounted(() => {
+      ctx.dispose();
+    });
+  }
+
+  // load
+  ctx.meta.hooks.onCreated(async () => {
+    if (ctx.disposed) return;
+    const loadEvent: IControllerLoadEvent = {
+      phase: 'prepare',
+      ctx,
+      controllerBeanFullName,
+      controllerBeanName:
+        typeof controllerBeanFullName === 'string'
+          ? controllerBeanFullName
+          : controllerBeanFullName.name,
+    };
+    ctx.app?.meta.module._monkeyModuleSync(true, 'controllerLoad', undefined, loadEvent);
+    if (loadEvent.replayError) {
+      const attemptId = ctx.meta.state.beginLoadAttempt();
+      if (loadEvent.replayControllerRecorded) {
+        try {
+          await __loadBeans(attemptId);
+        } catch {
+          // The server's fallback decision is authoritative during initial hydration.
+        }
+      }
+      if (!ctx.disposed) {
+        ctx.meta.state.setLoadError(loadEvent.replayError);
+      }
+      return;
     }
+    const attemptId = ctx.meta.state.beginLoadAttempt(getLoadLoadingDelay());
+    await runLoadAttempt(attemptId);
   });
   if (process.env.SERVER) {
     onServerPrefetch(() => {

package/zova/packages-zova/zova-core/src/core/component/error.ts

@@ -1,7 +1,12 @@
 import type { ComponentPublicInstance } from 'vue';
 
 import type { IErrorObject } from '../../bean/resource/error/errorObject.ts';
-import type { IErrorInstanceInfo, IModuleError } from '../../bean/resource/error/type.ts';
+import type {
+  IErrorHandlerLoad,
+  IErrorInstanceInfo,
+  IModuleError,
+} from '../../bean/resource/error/type.ts';
+import type { ZovaContext } from '../context/context.ts';
 
 import { ErrorClass } from '../../bean/resource/error/errorClass.ts';
 import { SymbolErrorInstanceInfo } from '../../bean/resource/error/type.ts';
@@ -42,6 +47,22 @@ export class AppError extends ErrorClass {
     };
   }
 
+  public handleLoadError(
+    originalError: unknown,
+    ctx: ZovaContext,
+    instance?: ComponentPublicInstance | null,
+  ) {
+    const err = normalizeError(originalError);
+    const load: IErrorHandlerLoad = {
+      kind: 'controller-load',
+      ctx,
+      originalError,
+      disposition: 'fallback',
+    };
+    this._handleError(err, instance, 'useController:load', load);
+    return { err, disposition: load.disposition };
+  }
+
   private _handleUnhandledError(error: Error, infoDefault: string) {
     if (error instanceof Error) {
       const errorInfo: IErrorInstanceInfo | undefined = error[SymbolErrorInstanceInfo];
@@ -61,6 +82,7 @@ export class AppError extends ErrorClass {
     err: Error,
     instance: ComponentPublicInstance | null | undefined,
     info: string | undefined,
+    load?: IErrorHandlerLoad,
   ) {
     if (!this.app) {
       // means destroyed
@@ -69,7 +91,7 @@ export class AppError extends ErrorClass {
     }
     const err2 = this.app.meta.event.emitSync(
       'app:errorHandler',
-      { err: err as Error, instance, info },
+      { err: err as Error, instance, info, load },
       data => {
         return data.err;
       },
@@ -77,10 +99,45 @@ export class AppError extends ErrorClass {
     // only log error in client
     if (process.env.CLIENT) {
       if (!err2 || !(err2 instanceof Error)) return err2;
-      if (!info || !['useMutationData'].includes(info)) {
-        console.error(err2);
-      }
+      console.error(err2);
     }
     return err2;
   }
 }
+
+export function normalizeError(error: unknown) {
+  if (error instanceof Error) return error;
+  const normalized = new Error(getErrorMessage(error));
+  if (error && (typeof error === 'object' || typeof error === 'function')) {
+    for (const key of ['code', 'status', 'pagePath', 'url']) {
+      const descriptor = Object.getOwnPropertyDescriptor(error, key);
+      if (!descriptor || !('value' in descriptor)) continue;
+      const value = descriptor.value;
+      if (
+        (key === 'code' || key === 'status') &&
+        (typeof value === 'number' || typeof value === 'string')
+      ) {
+        (normalized as any)[key] = value;
+      }
+      if ((key === 'pagePath' || key === 'url') && typeof value === 'string') {
+        (normalized as any)[key] = value;
+      }
+    }
+  }
+  return normalized;
+}
+
+function getErrorMessage(error: unknown) {
+  if (
+    error === null ||
+    error === undefined ||
+    typeof error === 'string' ||
+    typeof error === 'number' ||
+    typeof error === 'boolean' ||
+    typeof error === 'bigint' ||
+    typeof error === 'symbol'
+  ) {
+    return String(error);
+  }
+  return 'Unknown error';
+}

package/zova/packages-zova/zova-core/src/core/context/component.ts

@@ -21,8 +21,12 @@ export class CtxComponent extends BeanSimple {
     const self = this;
     instance[renderMethod] = function (this, ...args) {
       if (instance.isUnmounted) return;
-      if (!self.ctx.meta.state.inited.state) {
-        return self._bean_render_original.call(this, ...args);
+      const loadStatus = self.ctx.meta.state.loadStatus;
+      if (loadStatus === 'loading') {
+        return self.ctx.meta.state.loadLoadingVisible ? self._renderLoading() : null;
+      }
+      if (loadStatus === 'error') {
+        return self._renderError(self.ctx.meta.state.loadError);
       }
       const render = self._getRender();
       if (!render) {
@@ -77,6 +81,30 @@ export class CtxComponent extends BeanSimple {
     this._ssrRenderReset = false;
   }
 
+  private _renderLoading() {
+    const renderMode = this.ctx.meta.state.loadRenderMode;
+    const controller = this.ctx.meta.state.loadController as any;
+    if (controller?.renderLoading) {
+      return controller.renderLoading(renderMode);
+    }
+    const renderLoading = this.sys.config.boundary.renderLoading;
+    return renderLoading?.(this.ctx, renderMode) ?? null;
+  }
+
+  private _renderError(error: unknown) {
+    const renderMode = this.ctx.meta.state.loadRenderMode;
+    const retry = this.ctx.meta.state.loadRetry;
+    const controller = this.ctx.meta.state.loadController as any;
+    if (controller?.renderError) {
+      return controller.renderError(error, renderMode, retry);
+    }
+    const renderError = this.sys.config.boundary.renderError;
+    if (renderError) {
+      return renderError(this.ctx, error, renderMode, retry);
+    }
+    return _renderErrorDefault(error);
+  }
+
   private _getRender(): any {
     const render = this.bean._getBeanSyncOnly<BeanControllerBase>(BeanControllerIdentifier);
     if (!render) return;
@@ -85,3 +113,10 @@ export class CtxComponent extends BeanSimple {
     return this.bean._getBeanSyncOnly(BeanRenderIdentifier);
   }
 }
+
+function _renderErrorDefault(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/zova/packages-zova/zova-core/src/core/context/hooks.ts

@@ -1,6 +1,6 @@
 import { BeanSimple } from '../../bean/beanSimple.ts';
 
-export type ZovaHookType = 'created' | 'mounted';
+export type ZovaHookType = 'created' | 'mounted' | 'hydrated';
 
 export const SymbolHooksFns = Symbol('SymbolHooksFns');
 export const SymbolHooksState = Symbol('SymbolHooksState');
@@ -18,10 +18,21 @@ export class CtxHooks extends BeanSimple {
     this._onHook('created', fn);
   }
 
-  onMounted(fn: any) {
+  onMounted(fn: any, owner?: object) {
+    if (owner && !this.ctx.meta.state.isLoadBeanActive(owner)) return;
     this._onHook('mounted', fn);
   }
 
+  /** @internal */
+  public onHydrated(fn: any) {
+    this._onHook('hydrated', fn);
+  }
+
+  clearMounted() {
+    if (this[SymbolHooksState].mounted) return;
+    this[SymbolHooksFns].mounted = undefined;
+  }
+
   private _onHook(type: ZovaHookType, fn: any) {
     if (this[SymbolHooksState][type]) {
       this.ctx.util.instanceScope(fn);

package/zova/packages-zova/zova-core/src/core/context/meta.ts

@@ -23,6 +23,7 @@ export class CtxMeta extends BeanSimple {
 
   /** @internal */
   public dispose() {
+    this.state.dispose();
     this.component.dispose();
     this.hooks.dispose();
   }

package/zova/packages-zova/zova-core/src/core/context/state.ts

@@ -1,17 +1,42 @@
+import type {
+  TypeComponentBoundaryRenderMode,
+  TypeComponentBoundaryRetry,
+} from '../../bean/type.ts';
+
 import { BeanSimple } from '../../bean/beanSimple.ts';
 import { StateLock } from '../../utils/stateLock.ts';
 
+export type CtxLoadStatus = 'loading' | 'ready' | 'error';
+
 let __id: number = 0;
 
 export class CtxState extends BeanSimple {
   private _id: number;
   private _inited: StateLock;
+  private _loadStatus: CtxLoadStatus = 'loading';
+  private _loadRenderMode: TypeComponentBoundaryRenderMode = 'block';
+  private _loadRetryEnabled = false;
+  private _loadRetryReady = false;
+  private _loadRetry?: TypeComponentBoundaryRetry;
+  private _loadAttemptId = 0;
+  private _loadBeanAttempts = new WeakMap<object, number>();
+  private _loadError: unknown;
+  private _loadController: unknown;
+  /** @internal SSR hydration protocol key. */
+  public controllerLoadKey?: string;
+  private _loadLoadingVisible = false;
+  private _loadLoadingTimer: ReturnType<typeof setTimeout> | undefined;
 
   protected __init__() {
     this._id = ++__id;
     this._inited = StateLock.create();
   }
 
+  /** @internal */
+  public dispose() {
+    this._clearLoadLoadingTimer();
+  }
+
   get id() {
     return this._id;
   }
@@ -19,4 +44,140 @@ export class CtxState extends BeanSimple {
   get inited() {
     return this._inited;
   }
+
+  get loadStatus() {
+    return this._loadStatus;
+  }
+
+  get loadRenderMode() {
+    return this._loadRenderMode;
+  }
+
+  get loadRetry() {
+    if (!this.isLoadRetryAvailable) return undefined;
+    return this._loadRetry;
+  }
+
+  get isLoadRetryAvailable() {
+    return (
+      this._loadRetryEnabled &&
+      this._loadRetryReady &&
+      this._loadStatus === 'error' &&
+      !this.ctx.disposed &&
+      !!this._loadRetry
+    );
+  }
+
+  get loadAttemptId() {
+    return this._loadAttemptId;
+  }
+
+  get loadError() {
+    return this._loadError;
+  }
+
+  get loadController() {
+    return this._loadController;
+  }
+
+  get loadLoadingVisible() {
+    return this._loadLoadingVisible;
+  }
+
+  setLoadController(controller: unknown) {
+    this._loadController = controller;
+  }
+
+  setLoadRenderMode(renderMode: unknown) {
+    this._loadRenderMode = renderMode === 'inline' ? 'inline' : 'block';
+  }
+
+  setLoadRetryEnabled(retryEnabled: unknown) {
+    this._loadRetryEnabled = retryEnabled === true;
+  }
+
+  setLoadRetry(retry: TypeComponentBoundaryRetry) {
+    this._loadRetry = retry;
+  }
+
+  setLoadRetryReady() {
+    this._loadRetryReady = true;
+  }
+
+  beginLoadAttempt(delay?: number) {
+    this._clearLoadLoadingTimer();
+    this._loadAttemptId++;
+    this._loadStatus = 'loading';
+    this._loadError = undefined;
+    this._loadController = undefined;
+    this._loadLoadingVisible = false;
+    if (delay !== undefined) {
+      this.startLoadLoading(delay);
+    }
+    return this._loadAttemptId;
+  }
+
+  isLoadAttemptActive(attemptId: number) {
+    return !this.ctx.disposed && this._loadAttemptId === attemptId;
+  }
+
+  setLoadBeanAttempt(bean: object, attemptId: number) {
+    this._loadBeanAttempts.set(bean, attemptId);
+  }
+
+  getLoadBeanAttempt(bean: object) {
+    return this._loadBeanAttempts.get(bean);
+  }
+
+  isLoadBeanActive(bean: object) {
+    const attemptId = this._loadBeanAttempts.get(bean);
+    return attemptId === undefined || this.isLoadAttemptActive(attemptId);
+  }
+
+  startLoadLoading(delay: number) {
+    this._clearLoadLoadingTimer();
+    if (delay === 0) {
+      this._loadLoadingVisible = true;
+      return;
+    }
+    this._loadLoadingTimer = setTimeout(() => {
+      this._loadLoadingTimer = undefined;
+      if (this.ctx.disposed || this._loadStatus !== 'loading') return;
+      this._loadLoadingVisible = true;
+    }, delay);
+  }
+
+  /**
+   * Resolves the Controller-load terminal lock consumed by the custom SSR hydration runtime.
+   * A settled load is not necessarily a successful load: error and handled control-flow paths
+   * must also allow the rendered boundary subtree to hydrate.
+   */
+  settleLoad() {
+    this._inited.touch();
+  }
+
+  setLoadReady() {
+    this._clearLoadLoadingTimer();
+    this._loadError = undefined;
+    this._loadStatus = 'ready';
+    this.settleLoad();
+  }
+
+  setLoadError(error: unknown) {
+    this._clearLoadLoadingTimer();
+    this._loadError = error;
+    this._loadStatus = 'error';
+    this.settleLoad();
+  }
+
+  setLoadHandled() {
+    this._clearLoadLoadingTimer();
+    this.settleLoad();
+  }
+
+  private _clearLoadLoadingTimer() {
+    if (this._loadLoadingTimer === undefined) return;
+    clearTimeout(this._loadLoadingTimer);
+    this._loadLoadingTimer = undefined;
+  }
 }

package/zova/packages-zova/zova-core/src/core/sys/config.ts

@@ -1,5 +1,6 @@
 import type { ZovaConfigMeta } from '@cabloy/module-info';
 import type ms from 'ms';
+import type { VNodeChild } from 'vue';
 
 import type {
   ILayoutRecord,
@@ -8,9 +9,14 @@ import type {
 } from '../../bean/resource/component/type.ts';
 import type { ILocaleRecord } from '../../bean/resource/locale/type.ts';
 import type { ZovaConfigRoutes } from '../../bean/resource/page/type.ts';
-import type { IBeanScopeConfig } from '../../bean/type.ts';
+import type {
+  IBeanScopeConfig,
+  TypeComponentBoundaryRenderMode,
+  TypeComponentBoundaryRetry,
+} from '../../bean/type.ts';
 import type { ZovaConfigEnv } from '../../types/utils/env.ts';
 import type { PowerPartial } from '../../types/utils/powerPartial.ts';
+import type { ZovaContext } from '../context/context.ts';
 import type { ConfigLogger } from '../logger/types.ts';
 
 export function configDefault(env: ZovaConfigEnv): PowerPartial<ZovaConfig> {
@@ -20,10 +26,33 @@ export function configDefault(env: ZovaConfigEnv): PowerPartial<ZovaConfig> {
       mode: env.META_MODE,
       appMode: env.META_APP_MODE,
     },
+    boundary: {},
   };
   return config;
 }
 
+export interface ZovaConfigApp {
+  name: string;
+  title: string;
+  description: string;
+  version: string;
+}
+
+export interface ZovaConfigBoundaryLoading {
+  delay?: number;
+}
+
+export interface ZovaConfigBoundary {
+  loading?: ZovaConfigBoundaryLoading;
+  renderLoading?: (ctx: ZovaContext, renderMode: TypeComponentBoundaryRenderMode) => VNodeChild;
+  renderError?: (
+    ctx: ZovaContext,
+    error: unknown,
+    renderMode: TypeComponentBoundaryRenderMode,
+    retry?: TypeComponentBoundaryRetry,
+  ) => VNodeChild;
+}
+
 export interface ZovaConfigSsrResponseCachePolicy {
   expires?: number | ms.StringValue;
 }
@@ -35,12 +64,8 @@ export interface ZovaConfigSsrProfile {
 
 export interface ZovaConfig {
   meta: ZovaConfigMeta;
-  app: {
-    name: string;
-    title: string;
-    description: string;
-    version: string;
-  };
+  app: ZovaConfigApp;
+  boundary: ZovaConfigBoundary;
   api: {
     baseURL: string;
     prefix: string;