cabloy 5.1.166 → 5.1.168

package/zova/src/suite/cabloy-basic/modules/basic-app/src/component/routedDialog/controller.tsx

@@ -0,0 +1,55 @@
+import type { IComponentOptions } from 'zova';
+
+import { h } from 'vue';
+import { BeanControllerBase, cast } from 'zova';
+import { Controller } from 'zova-module-a-bean';
+import { ZRouterViewStack } from 'zova-module-a-routerstack';
+
+import { IModalRoutedDialogItem, routedDialogContextKey } from '../../types/appModal.js';
+
+export interface ControllerRoutedDialogProps {
+  item: IModalRoutedDialogItem;
+}
+
+@Controller()
+export class ControllerRoutedDialog extends BeanControllerBase {
+  static $propsDefault = {};
+  static $componentOptions: IComponentOptions = { inheritAttrs: false };
+
+  private $$modelStack: object | undefined;
+
+  protected async __init__() {
+    const item = (this.$props as ControllerRoutedDialogProps).item as IModalRoutedDialogItem;
+    const router = item.state.router;
+    if (!router) return;
+    const scene = `routedDialog:${item.id}`;
+    this.bean._setBean('a-router.bean.router', router);
+    this.$$modelStack = await this.bean._getBeanSelector(
+      'a-routerstack.model.stack',
+      true,
+      scene,
+      scene,
+      {},
+    );
+  }
+
+  protected render() {
+    const item = (this.$props as ControllerRoutedDialogProps).item as IModalRoutedDialogItem;
+    if (item.state.status === 'error') {
+      return <div class="text-error whitespace-pre-wrap">{String(item.state.error)}</div>;
+    }
+    if (!this.$$modelStack) return <div class="loading loading-spinner"></div>;
+    const router = item.state.router;
+    if (!router) return <div class="text-error">Router unavailable</div>;
+    const vnode = h(ZRouterViewStack, {
+      pageHostProviders: {
+        [routedDialogContextKey]: item.state.context,
+      },
+    });
+    cast(vnode).zovaHostProviders = {
+      'a-router.bean.router': router,
+      '$$modelStack': this.$$modelStack,
+    };
+    return vnode;
+  }
+}

package/zova/src/suite/cabloy-basic/modules/basic-app/src/config/config.ts

@@ -40,6 +40,25 @@ export const config = (_sys: ZovaSys) => {
           showCloseButton: false,
         },
       },
+      routedDialog: {
+        default: {
+          maxWidth: {
+            default: 640,
+            md: 768,
+            lg: 1024,
+          },
+          topGutter: {
+            default: 16,
+            md: 32,
+            lg: 48,
+          },
+          maxHeight: 'calc(100vh - 2rem)',
+          closeOnBackdrop: false,
+          closeOnEscape: true,
+          showCloseButton: true,
+          showBackButton: true,
+        },
+      },
       dialog: {
         default: {
           maxWidth: 640,

package/zova/src/suite/cabloy-basic/modules/basic-app/src/config/locale/en-us.ts

@@ -1,4 +1,5 @@
 export default {
+  Back: 'Back',
   Close: 'Close',
   Yes: 'Yes',
   No: 'No',

package/zova/src/suite/cabloy-basic/modules/basic-app/src/config/locale/zh-cn.ts

@@ -1,4 +1,5 @@
 export default {
+  Back: '返回',
   Close: '关闭',
   Yes: '是',
   No: '否',

package/zova/src/suite/cabloy-basic/modules/basic-app/src/lib/routedDialogHistory.ts

@@ -0,0 +1,76 @@
+import type { RouterHistory } from '@cabloy/vue-router';
+
+import { createMemoryHistory } from '@cabloy/vue-router';
+
+export class RoutedDialogHistory {
+  private readonly sourceHistory = createMemoryHistory();
+  private position = 0;
+  private length = 1;
+  private listeners = new Set<(canGoBack: boolean) => void>();
+  public readonly history: RouterHistory;
+
+  constructor() {
+    const sourceHistory = this.sourceHistory;
+    this.history = {
+      get base() {
+        return sourceHistory.base;
+      },
+      get location() {
+        return sourceHistory.location;
+      },
+      get state() {
+        return sourceHistory.state;
+      },
+      createHref: (...args) => sourceHistory.createHref(...args),
+      push: (...args) => {
+        this._push();
+        sourceHistory.push(...args);
+      },
+      replace: (...args) => {
+        sourceHistory.replace(...args);
+      },
+      go: (...args) => {
+        const [delta] = args;
+        const position = Math.max(0, Math.min(this.position + delta, this.length - 1));
+        this._setPosition(position);
+        sourceHistory.go(...args);
+      },
+      listen: (...args) => sourceHistory.listen(...args),
+      destroy: () => {
+        sourceHistory.destroy();
+      },
+    };
+  }
+
+  public get canGoBack() {
+    return this.position > 0;
+  }
+
+  public onCanGoBackChange(listener: (canGoBack: boolean) => void) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  public destroy() {
+    this.history.destroy();
+    this.position = 0;
+    this.length = 1;
+    this.listeners.clear();
+  }
+
+  private _push() {
+    this.length = this.position + 2;
+    this._setPosition(this.position + 1);
+  }
+
+  private _setPosition(position: number) {
+    const canGoBack = this.canGoBack;
+    this.position = position;
+    if (this.canGoBack === canGoBack) return;
+    for (const listener of this.listeners) {
+      listener(this.canGoBack);
+    }
+  }
+}

package/zova/src/suite/cabloy-basic/modules/basic-app/src/service/appModal.ts

@@ -1,7 +1,9 @@
+import { shallowReactive } from 'vue';
 import { BeanBase } from 'zova';
 import { Service } from 'zova-module-a-bean';
 
 import { AppModalItem } from '../lib/appModalItem.js';
+import { RoutedDialogHistory } from '../lib/routedDialogHistory.js';
 import {
   IModalAlertOptions,
   IModalConfirmOptions,
@@ -10,12 +12,29 @@ import {
   IModalItem,
   IModalMessageOptions,
   IModalPromptOptions,
+  IModalRoutedDialogOptions,
+  IModalRoutedDialogPresentationOptions,
+  IModalRoutedDialogItem,
+  IModalRoutedDialogState,
+  IRoutedDialogContext,
+  IRoutedDialogHandle,
 } from '../types/appModal.js';
 
 @Service()
 export class ServiceAppModal extends BeanBase {
   public modalItems: IModalItem[] = [];
   private modalItemIdCounter: number = 0;
+  private routedDialogReadySettlers = new Map<
+    number,
+    { resolve: () => void; reject: (error: unknown) => void }
+  >();
+
+  private routedDialogResultSettlers = new Map<
+    number,
+    { resolve: (value: unknown | undefined) => void; reject: (error: unknown) => void }
+  >();
+
+  private routedDialogHistories = new Map<number, RoutedDialogHistory>();
 
   protected async __init__() {}
 
@@ -89,10 +108,198 @@ export class ServiceAppModal extends BeanBase {
     return new AppModalItem(this, modalItem);
   }
 
-  public close(id: number) {
+  public routedDialog<
+    TResult = unknown,
+    TProps extends Record<string, unknown> = Record<string, unknown>,
+    TSession = unknown,
+  >(
+    options: IModalRoutedDialogOptions<TProps, TSession>,
+    dialogOptions?: IModalRoutedDialogPresentationOptions,
+  ): IRoutedDialogHandle<TResult> {
+    const id = this.newModalItemId();
+    let resolveReady!: () => void;
+    let rejectReady!: (error: unknown) => void;
+    const ready = new Promise<void>((resolve, reject) => {
+      resolveReady = resolve;
+      rejectReady = reject;
+    });
+    let resolveResult!: (value: TResult | undefined) => void;
+    let rejectResult!: (error: unknown) => void;
+    const result = new Promise<TResult | undefined>((resolve, reject) => {
+      resolveResult = resolve;
+      rejectResult = reject;
+    });
+    // Both promises remain observable through the handle without becoming
+    // unhandled rejections when callers only need one lifecycle channel.
+    void ready.catch(() => {});
+    void result.catch(() => {});
+    let modalItem!: IModalRoutedDialogItem<TResult, TProps, TSession>;
+    const context: IRoutedDialogContext<TResult, TProps, TSession> = {
+      id,
+      props: options.props,
+      session: options.session as TSession,
+      resolve: value => this._resolveRoutedDialog(modalItem, value),
+      cancel: () => this.close(id),
+    };
+    modalItem = {
+      id,
+      type: 'routedDialog',
+      options,
+      dialogOptions,
+      state: shallowReactive<IModalRoutedDialogState<TResult, TProps, TSession>>({
+        status: 'loading',
+        canGoBack: false,
+        ready,
+        result,
+        context,
+      }),
+    };
+    this.modalItems.push(modalItem);
+    this.routedDialogReadySettlers.set(id, { resolve: resolveReady, reject: rejectReady });
+    this.routedDialogResultSettlers.set(id, {
+      resolve: value => resolveResult(value as TResult | undefined),
+      reject: rejectResult,
+    });
+    const handle = new AppModalItem(this, modalItem) as IRoutedDialogHandle<TResult>;
+    Object.defineProperties(handle, {
+      ready: { enumerable: true, get: () => ready },
+      result: { enumerable: true, get: () => result },
+      push: {
+        enumerable: true,
+        value: (to: any) => this._navigateRoutedDialog(modalItem, to, false),
+      },
+      replace: {
+        enumerable: true,
+        value: (to: any) => this._navigateRoutedDialog(modalItem, to, true),
+      },
+    });
+    void this._initRoutedDialog(modalItem);
+    return handle;
+  }
+
+  private async _initRoutedDialog(modalItem: Extract<IModalItem, { type: 'routedDialog' }>) {
+    let router: IModalRoutedDialogState['router'];
+    try {
+      if (!process.env.CLIENT) throw new Error('routedDialog is client-only');
+      const history = new RoutedDialogHistory();
+      this.routedDialogHistories.set(modalItem.id, history);
+      history.onCanGoBackChange(canGoBack => {
+        if (!this._isRoutedDialogOpen(modalItem)) return;
+        modalItem.state.canGoBack = canGoBack;
+      });
+      router = await this.app.bean._newBean('a-router.bean.router', false, {
+        mainRouter: false,
+        embeddedView: 'page',
+        prepareNavigation: to => this.app.meta.$router.ensureRoute(String(to)),
+        routerOptions: {
+          history: history.history,
+        },
+      });
+      router.afterEach((to, _from, failure) => {
+        if (failure || !this._isRoutedDialogOpen(modalItem)) return;
+        modalItem.state.currentRoute = to;
+        modalItem.state.canGoBack = history.canGoBack;
+      });
+      if (!this._isRoutedDialogOpen(modalItem)) {
+        router.dispose();
+        history.destroy();
+        this.routedDialogHistories.delete(modalItem.id);
+        return;
+      }
+      modalItem.state.router = router;
+      const result = await router.replace(modalItem.options.route as any);
+      if (result) throw result;
+      await router.isReady();
+      if (!this._isRoutedDialogOpen(modalItem)) {
+        router.dispose();
+        history.destroy();
+        this.routedDialogHistories.delete(modalItem.id);
+        modalItem.state.router = undefined;
+        return;
+      }
+      modalItem.state.currentRoute = router.currentRoute.value;
+      modalItem.state.canGoBack = history.canGoBack;
+      modalItem.state.status = 'ready';
+      this._settleRoutedDialogReady(modalItem.id, 'resolve');
+    } catch (error) {
+      router?.dispose();
+      this.routedDialogHistories.get(modalItem.id)?.destroy();
+      this.routedDialogHistories.delete(modalItem.id);
+      if (!this._isRoutedDialogOpen(modalItem)) return;
+      modalItem.state.router = undefined;
+      modalItem.state.status = 'error';
+      modalItem.state.error = error;
+      this._settleRoutedDialogReady(modalItem.id, 'reject', error);
+      this._settleRoutedDialogResult(modalItem.id, 'reject', error);
+    }
+  }
+
+  private async _navigateRoutedDialog(
+    modalItem: Extract<IModalItem, { type: 'routedDialog' }>,
+    to: any,
+    replace: boolean,
+  ) {
+    this._ensureRoutedDialogOpen(modalItem);
+    await modalItem.state.ready;
+    this._ensureRoutedDialogOpen(modalItem);
+    const router = modalItem.state.router;
+    if (!router) throw new Error('routedDialog router is unavailable');
+    const result = replace ? await router.replace(to) : await router.push(to);
+    this._ensureRoutedDialogOpen(modalItem);
+    return result;
+  }
+
+  private _isRoutedDialogOpen(modalItem: Extract<IModalItem, { type: 'routedDialog' }>) {
+    return !modalItem.state.closed && this.modalItems.some(item => item.id === modalItem.id);
+  }
+
+  private _ensureRoutedDialogOpen(modalItem: Extract<IModalItem, { type: 'routedDialog' }>) {
+    if (!this._isRoutedDialogOpen(modalItem)) {
+      throw new Error('routedDialog is closed');
+    }
+  }
+
+  private _settleRoutedDialogReady(id: number, action: 'resolve' | 'reject', error?: unknown) {
+    const settler = this.routedDialogReadySettlers.get(id);
+    if (!settler) return;
+    this.routedDialogReadySettlers.delete(id);
+    if (action === 'resolve') settler.resolve();
+    else settler.reject(error);
+  }
+
+  private _settleRoutedDialogResult(id: number, action: 'resolve' | 'reject', value?: unknown) {
+    const settler = this.routedDialogResultSettlers.get(id);
+    if (!settler) return;
+    this.routedDialogResultSettlers.delete(id);
+    if (action === 'resolve') settler.resolve(value);
+    else settler.reject(value);
+  }
+
+  private _resolveRoutedDialog(
+    modalItem: Extract<IModalItem, { type: 'routedDialog' }>,
+    value: unknown,
+  ) {
+    if (!this._isRoutedDialogOpen(modalItem)) return;
+    this._settleRoutedDialogResult(modalItem.id, 'resolve', value);
+    this.close(modalItem.id);
+  }
+
+  public close(id: number, _reason: string = 'api') {
     const [index, modalItem] = this.findModalItem(id);
     if (index === -1 || !modalItem) return;
     this.modalItems.splice(index, 1);
+    if (modalItem.type === 'routedDialog') {
+      modalItem.state.closed = true;
+      modalItem.state.status = 'closed';
+      modalItem.state.router?.dispose();
+      this.routedDialogHistories.get(modalItem.id)?.destroy();
+      this.routedDialogHistories.delete(modalItem.id);
+      modalItem.state.router = undefined;
+      this._settleRoutedDialogReady(modalItem.id, 'reject', new Error('routedDialog is closed'));
+      this._settleRoutedDialogResult(modalItem.id, 'resolve');
+      modalItem.options.onClose?.();
+      return;
+    }
     if (modalItem.type === 'dialog') {
       const options = modalItem.options as IModalDialogRenderOptions | undefined;
       options?.onClose?.();

package/zova/src/suite/cabloy-basic/modules/basic-app/src/types/appModal.ts

@@ -1,14 +1,44 @@
+import type {
+  NavigationFailure,
+  RouteLocationNormalizedLoadedGeneric,
+  RouteLocationRaw,
+} from '@cabloy/vue-router';
 import type { VNode } from 'vue';
 import type { IIconRecord } from 'zova-module-a-icon';
+import type { BeanRouter } from 'zova-module-a-router';
 
+import type { AppModalItem } from '../lib/appModalItem.js';
 import type { ServiceAppModal } from '../service/appModal.js';
 
-export type ModalType = 'alert' | 'confirm' | 'prompt' | 'dialog';
+export type ModalType = 'alert' | 'confirm' | 'prompt' | 'dialog' | 'routedDialog';
+export type ModalCloseReason = 'api' | 'backdrop' | 'escape' | 'button' | 'error' | 'unmount';
 export type AlertType = 'success' | 'info' | 'warning' | 'error';
+export type ModalWidth = number | string;
+
+/**
+ * Mobile-first maximum-width values for routed dialogs.
+ *
+ * `md` and `lg` use the Cabloy Basic Tailwind breakpoints. Omitted values
+ * inherit the last applicable lower breakpoint through the CSS cascade.
+ */
+export interface IModalResponsiveMaxWidth {
+  default?: ModalWidth;
+  md?: ModalWidth;
+  lg?: ModalWidth;
+}
+
+export interface IModalResponsiveTopGutter {
+  default?: ModalWidth;
+  md?: ModalWidth;
+  lg?: ModalWidth;
+}
+
+export type ModalRoutedDialogMaxWidth = ModalWidth | IModalResponsiveMaxWidth;
+export type ModalRoutedDialogTopGutter = ModalWidth | IModalResponsiveTopGutter;
 
 export interface IModalBaseOptions {
-  maxWidth?: number | string;
-  maxHeight?: number | string;
+  maxWidth?: ModalWidth;
+  maxHeight?: ModalWidth;
   closeOnBackdrop?: boolean;
   closeOnEscape?: boolean;
 }
@@ -19,6 +49,15 @@ export interface IModalDialogOptions extends IModalBaseOptions {
 
 export interface IModalMessageOptions extends IModalBaseOptions {}
 
+export interface IModalRoutedDialogPresentationOptions extends Omit<
+  IModalDialogOptions,
+  'maxWidth'
+> {
+  maxWidth?: ModalRoutedDialogMaxWidth;
+  topGutter?: ModalRoutedDialogTopGutter;
+  showBackButton?: boolean;
+}
+
 export interface IModalDialogRenderContext {
   id: number;
   close: () => void;
@@ -32,6 +71,76 @@ export interface IModalDialogRenderOptions {
   onClose?: () => void;
 }
 
+export const routedDialogContextKey = '$routedDialogContext';
+
+export interface IRoutedDialogContext<
+  TResult = unknown,
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TSession = unknown,
+> {
+  readonly id: number;
+  readonly props?: TProps;
+  readonly session: TSession;
+  resolve(value: TResult): void;
+  cancel(): void;
+}
+
+export interface IModalRoutedDialogOptions<
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TSession = unknown,
+> extends IModalRoutedDialogPresentationOptions {
+  route: RouteLocationRaw;
+  icon?: keyof IIconRecord;
+  title?: string;
+  props?: TProps;
+  session?: TSession;
+  onClose?: () => void;
+}
+
+export interface IModalRoutedDialogState<
+  TResult = unknown,
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TSession = unknown,
+> {
+  status: 'loading' | 'ready' | 'error' | 'closed';
+  closed?: boolean;
+  error?: unknown;
+  router?: BeanRouter;
+  currentRoute?: RouteLocationNormalizedLoadedGeneric;
+  canGoBack: boolean;
+  ready: Promise<void>;
+  result: Promise<TResult | undefined>;
+  context: IRoutedDialogContext<TResult, TProps, TSession>;
+}
+
+export type IModalRoutedDialogInput<
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TSession = unknown,
+> = Omit<IModalRoutedDialogOptions<TProps, TSession>, 'route'>;
+
+export interface IModalRoutedDialogNavigate {
+  navigate(to: RouteLocationRaw, replace?: boolean): Promise<NavigationFailure | void | undefined>;
+}
+
+export interface IModalRoutedDialogItem<
+  TResult = unknown,
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+  TSession = unknown,
+> {
+  id: number;
+  type: 'routedDialog';
+  options: IModalRoutedDialogOptions<TProps, TSession>;
+  dialogOptions?: IModalRoutedDialogPresentationOptions;
+  state: IModalRoutedDialogState<TResult, TProps, TSession>;
+}
+
+export interface IRoutedDialogHandle<TResult = unknown> extends AppModalItem {
+  readonly ready: Promise<void>;
+  readonly result: Promise<TResult | undefined>;
+  push(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>;
+  replace(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>;
+}
+
 export interface IModalAlertOptions {
   type?: AlertType;
   icon?: keyof IIconRecord;
@@ -60,16 +169,18 @@ export interface IModalPromptOptionsInner extends IModalPromptOptions {
   onCallback?: (res: string | undefined) => void;
 }
 
-export interface IModalItem {
-  id: number;
-  type: ModalType;
-  options?:
-    | IModalAlertOptions
-    | IModalConfirmOptionsInner
-    | IModalPromptOptionsInner
-    | IModalDialogRenderOptions;
-  dialogOptions?: IModalDialogOptions | IModalMessageOptions;
-}
+export type IModalItem =
+  | {
+      id: number;
+      type: 'alert' | 'confirm' | 'prompt' | 'dialog';
+      options?:
+        | IModalAlertOptions
+        | IModalConfirmOptionsInner
+        | IModalPromptOptionsInner
+        | IModalDialogRenderOptions;
+      dialogOptions?: IModalDialogOptions | IModalMessageOptions;
+    }
+  | IModalRoutedDialogItem;
 
 declare module 'zova' {
   export interface BeanBase {

package/zova/src/suite/cabloy-basic/modules/basic-app/test/lib/routedDialogHistory.test.ts

@@ -0,0 +1,92 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { RoutedDialogHistory } from '../../src/lib/routedDialogHistory.js';
+
+function createHistory() {
+  const routedDialogHistory = new RoutedDialogHistory();
+  return { history: routedDialogHistory.history, routedDialogHistory };
+}
+
+test('routed dialog history establishes replace as the root entry', () => {
+  const { history, routedDialogHistory } = createHistory();
+
+  history.replace('/entry');
+
+  assert.equal(routedDialogHistory.canGoBack, false);
+});
+
+test('routed dialog history updates Back availability before navigation listeners', () => {
+  const { history, routedDialogHistory } = createHistory();
+  const canGoBackOnChange: boolean[] = [];
+  const canGoBackOnNavigation: boolean[] = [];
+
+  routedDialogHistory.onCanGoBackChange(canGoBack => {
+    canGoBackOnChange.push(canGoBack);
+  });
+  history.listen(() => {
+    canGoBackOnNavigation.push(routedDialogHistory.canGoBack);
+  });
+  history.replace('/entry');
+  history.push('/detail');
+  history.replace('/detail-edited');
+  assert.equal(routedDialogHistory.canGoBack, true);
+
+  history.go(-1);
+  assert.equal(routedDialogHistory.canGoBack, false);
+  history.go(1);
+  assert.equal(routedDialogHistory.canGoBack, true);
+
+  assert.deepEqual(canGoBackOnChange, [true, false, true]);
+  assert.deepEqual(canGoBackOnNavigation, [false, true]);
+});
+
+test('routed dialog history truncates forward entries after a new push', () => {
+  const { history, routedDialogHistory } = createHistory();
+
+  history.replace('/entry');
+  history.push('/detail/1');
+  history.push('/detail/2');
+  history.go(-1);
+  history.push('/detail/3');
+  history.go(1);
+  assert.equal(history.location, '/detail/3');
+  assert.equal(routedDialogHistory.canGoBack, true);
+
+  history.go(-2);
+  assert.equal(history.location, '/entry');
+  assert.equal(routedDialogHistory.canGoBack, false);
+});
+
+test('routed dialog history mirrors a silent rejected-pop repair', () => {
+  const { history, routedDialogHistory } = createHistory();
+
+  history.replace('/entry');
+  history.push('/detail');
+  history.go(-1);
+  assert.equal(routedDialogHistory.canGoBack, false);
+
+  // Vue Router repairs a rejected pop with history.go(-delta, false).
+  history.go(1, false);
+  assert.equal(history.location, '/detail');
+  assert.equal(routedDialogHistory.canGoBack, true);
+});
+
+test('routed dialog histories remain independent and reset after destruction', () => {
+  const first = createHistory();
+  const second = createHistory();
+  const firstChanges: boolean[] = [];
+
+  first.routedDialogHistory.onCanGoBackChange(canGoBack => {
+    firstChanges.push(canGoBack);
+  });
+  first.history.replace('/first');
+  second.history.replace('/second');
+  first.history.push('/first-detail');
+  assert.equal(first.routedDialogHistory.canGoBack, true);
+  assert.equal(second.routedDialogHistory.canGoBack, false);
+
+  first.routedDialogHistory.destroy();
+  assert.deepEqual(firstChanges, [true]);
+  assert.equal(first.routedDialogHistory.canGoBack, false);
+});