feat: add modal and drawer components and examples (#4229)

* feat: add modal component

* feat: add drawer component

* feat: apply new modal and drawer components to the layout

* chore: typo

* feat: add some unit tests

packages/@core/ui-kit/popup-ui/src/drawer/__tests__/drawer-api.test.ts

@@ -0,0 +1,113 @@
+import type { DrawerState } from '../drawer';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { DrawerApi } from '../drawer-api';
+
+// 模拟 Store 类
+vi.mock('@vben-core/shared', () => {
+  return {
+    isFunction: (fn: any) => typeof fn === 'function',
+    Store: class {
+      private _state: DrawerState;
+      private options: any;
+
+      constructor(initialState: DrawerState, options: any) {
+        this._state = initialState;
+        this.options = options;
+      }
+
+      batch(cb: () => void) {
+        cb();
+      }
+
+      setState(fn: (prev: DrawerState) => DrawerState) {
+        this._state = fn(this._state);
+        this.options.onUpdate();
+      }
+
+      get state() {
+        return this._state;
+      }
+    },
+  };
+});
+
+describe('drawerApi', () => {
+  let drawerApi: DrawerApi;
+  let drawerState: DrawerState;
+
+  beforeEach(() => {
+    drawerApi = new DrawerApi();
+    drawerState = drawerApi.store.state;
+  });
+
+  it('should initialize with default state', () => {
+    expect(drawerState.isOpen).toBe(false);
+    expect(drawerState.cancelText).toBe('取消');
+    expect(drawerState.confirmText).toBe('确定');
+  });
+
+  it('should open the drawer', () => {
+    drawerApi.open();
+    expect(drawerApi.store.state.isOpen).toBe(true);
+  });
+
+  it('should close the drawer if onBeforeClose allows it', () => {
+    drawerApi.open();
+    drawerApi.close();
+    expect(drawerApi.store.state.isOpen).toBe(false);
+  });
+
+  it('should not close the drawer if onBeforeClose returns false', () => {
+    const onBeforeClose = vi.fn(() => false);
+    const drawerApiWithHook = new DrawerApi({ onBeforeClose });
+    drawerApiWithHook.open();
+    drawerApiWithHook.close();
+    expect(drawerApiWithHook.store.state.isOpen).toBe(true);
+    expect(onBeforeClose).toHaveBeenCalled();
+  });
+
+  it('should trigger onCancel and keep drawer open if onCancel is provided', () => {
+    const onCancel = vi.fn();
+    const drawerApiWithHook = new DrawerApi({ onCancel });
+    drawerApiWithHook.open();
+    drawerApiWithHook.onCancel();
+    expect(onCancel).toHaveBeenCalled();
+    expect(drawerApiWithHook.store.state.isOpen).toBe(true); // 关闭逻辑不在 onCancel 内
+  });
+
+  it('should update shared data correctly', () => {
+    const testData = { key: 'value' };
+    drawerApi.setData(testData);
+    expect(drawerApi.getData()).toEqual(testData);
+  });
+
+  it('should set state correctly using an object', () => {
+    drawerApi.setState({ title: 'New Title' });
+    expect(drawerApi.store.state.title).toBe('New Title');
+  });
+
+  it('should set state correctly using a function', () => {
+    drawerApi.setState((prev) => ({ ...prev, confirmText: 'Yes' }));
+    expect(drawerApi.store.state.confirmText).toBe('Yes');
+  });
+
+  it('should call onOpenChange when state changes', () => {
+    const onOpenChange = vi.fn();
+    const drawerApiWithHook = new DrawerApi({ onOpenChange });
+    drawerApiWithHook.open();
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it('should batch state updates', () => {
+    const batchSpy = vi.spyOn(drawerApi.store, 'batch');
+    drawerApi.batchStore(() => {
+      drawerApi.setState({ title: 'Batch Title' });
+      drawerApi.setState({ confirmText: 'Batch Confirm' });
+    });
+    expect(batchSpy).toHaveBeenCalled();
+    expect(drawerApi.store.state.title).toBe('Batch Title');
+    expect(drawerApi.store.state.confirmText).toBe('Batch Confirm');
+  });
+});

packages/@core/ui-kit/popup-ui/src/drawer/drawer-api.ts

@@ -0,0 +1,123 @@
+import type { DrawerApiOptions, DrawerState } from './drawer';
+
+import { isFunction, Store } from '@vben-core/shared';
+
+export class DrawerApi {
+  private api: Pick<
+    DrawerApiOptions,
+    'onBeforeClose' | 'onCancel' | 'onConfirm' | 'onOpenChange'
+  >;
+  // private prevState!: DrawerState;
+  private state!: DrawerState;
+
+  // 共享数据
+  public sharedData: Record<'payload', any> = {
+    payload: {},
+  };
+
+  public store: Store<DrawerState>;
+
+  constructor(options: DrawerApiOptions = {}) {
+    const {
+      connectedComponent: _,
+      onBeforeClose,
+      onCancel,
+      onConfirm,
+      onOpenChange,
+      ...storeState
+    } = options;
+
+    const defaultState: DrawerState = {
+      cancelText: '取消',
+      closable: true,
+      confirmLoading: false,
+      confirmText: '确定',
+      footer: true,
+      isOpen: false,
+      loading: false,
+      modal: true,
+      sharedData: {},
+      title: '',
+    };
+
+    this.store = new Store<DrawerState>(
+      {
+        ...defaultState,
+        ...storeState,
+      },
+      {
+        onUpdate: () => {
+          const state = this.store.state;
+          if (state?.isOpen === this.state?.isOpen) {
+            this.state = state;
+          } else {
+            this.state = state;
+            this.api.onOpenChange?.(!!state?.isOpen);
+          }
+        },
+      },
+    );
+
+    this.api = {
+      onBeforeClose,
+      onCancel,
+      onConfirm,
+      onOpenChange,
+    };
+  }
+
+  // 如果需要多次更新状态，可以使用 batch 方法
+  batchStore(cb: () => void) {
+    this.store.batch(cb);
+  }
+
+  /**
+   * 关闭弹窗
+   */
+  close() {
+    // 通过 onBeforeClose 钩子函数来判断是否允许关闭弹窗
+    // 如果 onBeforeClose 返回 false，则不关闭弹窗
+    const allowClose = this.api.onBeforeClose?.() ?? true;
+    if (allowClose) {
+      this.store.setState((prev) => ({ ...prev, isOpen: false }));
+    }
+  }
+
+  getData<T extends object = Record<string, any>>() {
+    return (this.sharedData?.payload ?? {}) as T;
+  }
+
+  /**
+   * 取消操作
+   */
+  onCancel() {
+    this.api.onCancel?.();
+  }
+
+  /**
+   * 确认操作
+   */
+  onConfirm() {
+    this.api.onConfirm?.();
+  }
+
+  open() {
+    this.store.setState((prev) => ({ ...prev, isOpen: true }));
+  }
+
+  setData<T>(payload: T) {
+    this.sharedData.payload = payload;
+  }
+
+  setState(
+    stateOrFn:
+      | ((prev: DrawerState) => Partial<DrawerState>)
+      | Partial<DrawerState>,
+  ) {
+    if (isFunction(stateOrFn)) {
+      this.store.setState(stateOrFn);
+    } else {
+      this.store.setState((prev) => ({ ...prev, ...stateOrFn }));
+    }
+  }
+}

packages/@core/ui-kit/popup-ui/src/drawer/drawer.ts

@@ -0,0 +1,93 @@
+import type { DrawerApi } from './drawer-api';
+
+import type { Component, Ref } from 'vue';
+
+export interface DrawerProps {
+  /**
+   * 取消按钮文字
+   */
+  cancelText?: string;
+
+  /**
+   * 是否显示右上角的关闭按钮
+   * @default true
+   */
+  closable?: boolean;
+  /**
+   * 确定按钮 loading
+   * @default false
+   */
+  confirmLoading?: boolean;
+  /**
+   * 确定按钮文字
+   */
+  confirmText?: string;
+  /**
+   * 弹窗描述
+   */
+  description?: string;
+  /**
+   * 是否显示底部
+   * @default true
+   */
+  footer?: boolean;
+  /**
+   * 弹窗是否显示
+   * @default false
+   */
+  loading?: boolean;
+  /**
+   * 是否显示遮罩
+   * @default true
+   */
+  modal?: boolean;
+  /**
+   * 弹窗标题
+   */
+  title?: string;
+  /**
+   * 弹窗标题提示
+   */
+  titleTooltip?: string;
+}
+
+export interface DrawerState extends DrawerProps {
+  /** 弹窗打开状态 */
+  isOpen?: boolean;
+  /**
+   * 共享数据
+   */
+  sharedData?: Record<string, any>;
+}
+
+export type ExtendedDrawerApi = {
+  useStore: <T = NoInfer<DrawerState>>(
+    selector?: (state: NoInfer<DrawerState>) => T,
+  ) => Readonly<Ref<T>>;
+} & DrawerApi;
+
+export interface DrawerApiOptions extends DrawerState {
+  /**
+   * 独立的弹窗组件
+   */
+  connectedComponent?: Component;
+  /**
+   * 关闭前的回调，返回 false 可以阻止关闭
+   * @returns
+   */
+  onBeforeClose?: () => void;
+  /**
+   * 点击取消按钮的回调
+   */
+  onCancel?: () => void;
+  /**
+   * 点击确定按钮的回调
+   */
+  onConfirm?: () => void;
+  /**
+   * 弹窗状态变化回调
+   * @param isOpen
+   * @returns
+   */
+  onOpenChange?: (isOpen: boolean) => void;
+}

packages/@core/ui-kit/popup-ui/src/drawer/drawer.vue

@@ -0,0 +1,141 @@
+<script lang="ts" setup>
+import type { DrawerProps, ExtendedDrawerApi } from './drawer';
+
+import { usePriorityValue } from '@vben-core/composables';
+import { Info, X } from '@vben-core/icons';
+import {
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  VbenButton,
+  VbenIconButton,
+  VbenLoading,
+  VbenTooltip,
+  VisuallyHidden,
+} from '@vben-core/shadcn-ui';
+import { cn } from '@vben-core/shared';
+
+interface Props extends DrawerProps {
+  class?: string;
+  contentClass?: string;
+  drawerApi?: ExtendedDrawerApi;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  class: '',
+  contentClass: '',
+  drawerApi: undefined,
+});
+
+const state = props.drawerApi?.useStore?.();
+
+const title = usePriorityValue('title', props, state);
+const description = usePriorityValue('description', props, state);
+const titleTooltip = usePriorityValue('titleTooltip', props, state);
+const showFooter = usePriorityValue('footer', props, state);
+const showLoading = usePriorityValue('loading', props, state);
+const closable = usePriorityValue('closable', props, state);
+const modal = usePriorityValue('modal', props, state);
+const confirmLoading = usePriorityValue('confirmLoading', props, state);
+const cancelText = usePriorityValue('cancelText', props, state);
+const confirmText = usePriorityValue('confirmText', props, state);
+</script>
+<template>
+  <Sheet
+    :modal="modal"
+    :open="state?.isOpen"
+    @update:open="() => drawerApi?.close()"
+  >
+    <SheetContent :class="cn('flex w-[520px] flex-col', props.class, {})">
+      <SheetHeader
+        :class="
+          cn('!flex flex-row items-center justify-between border-b px-6 py-5', {
+            'px-4 py-3': closable,
+          })
+        "
+      >
+        <div>
+          <SheetTitle v-if="title">
+            <slot name="title">
+              {{ title }}
+
+              <VbenTooltip v-if="titleTooltip" side="right">
+                <template #trigger>
+                  <Info class="inline-flex size-5 cursor-pointer pb-1" />
+                </template>
+                {{ titleTooltip }}
+              </VbenTooltip>
+            </slot>
+          </SheetTitle>
+          <SheetDescription v-if="description" class="mt-1 text-xs">
+            <slot name="description">
+              {{ description }}
+            </slot>
+          </SheetDescription>
+        </div>
+
+        <VisuallyHidden v-if="!title || !description">
+          <SheetTitle v-if="!title" />
+          <SheetDescription v-if="!description" />
+        </VisuallyHidden>
+
+        <div class="flex-center">
+          <slot name="extra"></slot>
+          <SheetClose
+            v-if="closable"
+            as-child
+            class="data-[state=open]:bg-secondary ml-[2px] cursor-pointer rounded-full opacity-80 transition-opacity hover:opacity-100 focus:outline-none disabled:pointer-events-none"
+          >
+            <VbenIconButton>
+              <X class="size-4" />
+            </VbenIconButton>
+          </SheetClose>
+        </div>
+      </SheetHeader>
+
+      <div
+        :class="
+          cn('relative flex-1 p-3', contentClass, {
+            'overflow-y-auto': !showLoading,
+          })
+        "
+      >
+        <VbenLoading v-if="showLoading" class="size-full" spinning />
+
+        <slot></slot>
+      </div>
+
+      <SheetFooter
+        v-if="showFooter"
+        class="w-full items-center border-t p-2 px-3"
+      >
+        <slot name="prepend-footer"></slot>
+        <slot name="footer">
+          <VbenButton
+            size="sm"
+            variant="ghost"
+            @click="() => drawerApi?.onCancel()"
+          >
+            <slot name="cancelText">
+              {{ cancelText }}
+            </slot>
+          </VbenButton>
+          <VbenButton
+            :loading="confirmLoading"
+            size="sm"
+            @click="() => drawerApi?.onConfirm()"
+          >
+            <slot name="confirmText">
+              {{ confirmText }}
+            </slot>
+          </VbenButton>
+        </slot>
+        <slot name="append-footer"></slot>
+      </SheetFooter>
+    </SheetContent>
+  </Sheet>
+</template>

packages/@core/ui-kit/popup-ui/src/drawer/index.ts

@@ -0,0 +1,3 @@
+export type * from './drawer';
+export { default as VbenDrawer } from './drawer.vue';
+export { useVbenDrawer } from './use-drawer';

packages/@core/ui-kit/popup-ui/src/drawer/use-drawer.ts

@@ -0,0 +1,105 @@
+import type {
+  DrawerApiOptions,
+  DrawerProps,
+  ExtendedDrawerApi,
+} from './drawer';
+
+import { defineComponent, h, inject, nextTick, provide, reactive } from 'vue';
+
+import { useStore } from '@vben-core/shared';
+
+import VbenDrawer from './drawer.vue';
+import { DrawerApi } from './drawer-api';
+
+const USER_DRAWER_INJECT_KEY = Symbol('VBEN_DRAWER_INJECT');
+
+export function useVbenDrawer<
+  TParentDrawerProps extends DrawerProps = DrawerProps,
+>(options: DrawerApiOptions = {}) {
+  // Drawer一般会抽离出来，所以如果有传入 connectedComponent，则表示为外部调用，与内部组件进行连接
+  // 外部的Drawer通过provide/inject传递api
+
+  const { connectedComponent } = options;
+  if (connectedComponent) {
+    const extendedApi = reactive({});
+    const Drawer = defineComponent(
+      (props: TParentDrawerProps, { attrs, slots }) => {
+        provide(USER_DRAWER_INJECT_KEY, {
+          extendApi(api: ExtendedDrawerApi) {
+            // 不能直接给 reactive 赋值，会丢失响应
+            // 不能用 Object.assign,会丢失 api 的原型函数
+            Object.setPrototypeOf(extendedApi, api);
+          },
+          options,
+        });
+        checkProps(extendedApi as ExtendedDrawerApi, {
+          ...props,
+          ...attrs,
+          ...slots,
+        });
+        return () => h(connectedComponent, { ...props, ...attrs }, slots);
+      },
+      {
+        inheritAttrs: false,
+        name: 'VbenParentDrawer',
+      },
+    );
+    return [Drawer, extendedApi as ExtendedDrawerApi] as const;
+  }
+
+  const injectData = inject<any>(USER_DRAWER_INJECT_KEY, {});
+
+  const mergedOptions = {
+    ...injectData.options,
+    ...options,
+  } as DrawerApiOptions;
+
+  // mergedOptions.onOpenChange = (isOpen: boolean) => {
+  //   options.onOpenChange?.(isOpen);
+  //   injectData.options?.onOpenChange?.(isOpen);
+  // };
+  const api = new DrawerApi(mergedOptions);
+
+  const extendedApi: ExtendedDrawerApi = api as never;
+
+  extendedApi.useStore = (selector) => {
+    return useStore(api.store, selector);
+  };
+
+  const Drawer = defineComponent(
+    (props: DrawerProps, { attrs, slots }) => {
+      return () =>
+        h(VbenDrawer, { ...props, ...attrs, drawerApi: extendedApi }, slots);
+    },
+    {
+      inheritAttrs: false,
+      name: 'VbenDrawer',
+    },
+  );
+  injectData.extendApi?.(extendedApi);
+  return [Drawer, extendedApi] as const;
+}
+
+async function checkProps(api: ExtendedDrawerApi, attrs: Record<string, any>) {
+  if (!attrs || Object.keys(attrs).length === 0) {
+    return;
+  }
+  await nextTick();
+
+  const state = api?.store?.state;
+
+  if (!state) {
+    return;
+  }
+
+  const stateKeys = new Set(Object.keys(state));
+
+  for (const attr of Object.keys(attrs)) {
+    if (stateKeys.has(attr)) {
+      // connectedComponent存在时，不要传入Drawer的props，会造成复杂度提升，如果你需要修改Drawer的props，请使用 useVbenDrawer 或者api
+      console.warn(
+        `[Vben Drawer]: When 'connectedComponent' exists, do not set props or slots '${attr}', which will increase complexity. If you need to modify the props of Drawer, please use useVbenDrawer or api.`,
+      );
+    }
+  }
+}