pandax 0.0.1

package/skills/pandax-frontend-use-modal/SKILL.md

@@ -0,0 +1,621 @@
+---
+name: "pandax-frontend-use-modal"
+category: "frontend"
+description: "基于 Vue 3 + Element Plus 生成 useModal Hook，支持弹窗/抽屉、多实例、嵌套、国际化与全局默认配置。Invoke when 用户需要创建弹窗/抽屉 Hook、封装 modal、useModal、嵌套弹窗或全局弹窗管理。"
+---
+
+# Pandax useModal Hook 生成规范
+
+本 skill 用于生成基于 Vue 3 Composition API + Element Plus 的 `useModal` Hook。支持弹窗（Dialog）和抽屉（Drawer），支持多实例、嵌套、国际化、全局默认配置。
+
+## 触发条件
+
+- 用户需要创建弹窗/抽屉管理 Hook
+- 提到 `useModal`、`modal`、`dialog`、`drawer`、`弹窗`、`抽屉`
+- 需要支持嵌套弹窗、多实例弹窗
+- 需要弹窗内容组件通信、按钮回调联动
+- 需要全局默认配置或国际化
+
+## 文件位置
+
+遵循 [pandax-frontend-standards](../pandax-frontend-standards/SKILL.md) 命名规范：目录名全小写 + 短横线，非入口文件使用 PascalCase。
+
+```text
+src/
+├── composables/              # Vue 组合式函数（推荐）
+│   └── use-modal/            # 目录名：全小写 + 短横线
+│       ├── index.ts          # Hook 主入口（入口文件保持小写）
+│       ├── Types.ts          # 类型定义（PascalCase）
+│       ├── Render.tsx        # 弹窗渲染组件（可选，PascalCase）
+│       ├── Config.ts        # 全局默认配置（PascalCase）
+│       └── index.module.scss # 样式隔离（CSS Modules）
+```
+
+如果项目使用 `hooks/` 目录，统一放到 `src/hooks/use-modal/`。
+
+## 核心能力
+
+- `type: 'dialog' | 'drawer'` 区分弹窗/抽屉
+- 多实例管理，支持嵌套（A 打开 B，B 打开 C）
+- Header / Content / Footer 支持字符串或组件
+- 按钮点击优先调用内容组件暴露的方法，再执行配置的 `onClick`
+- 内容组件注入 `close`、`setContentLoading`、`setButtonLoading`、`getData`、`emit`、`triggerButtonClick`、`open`
+- 支持 `configureModal` 全局默认配置
+- 支持国际化 `i18n`
+
+## 实现步骤
+
+### 1. 定义类型（Types.ts）
+
+```typescript
+import type { Component, VNode } from 'vue';
+
+export type ModalType = 'dialog' | 'drawer';
+export type DrawerDirection = 'left' | 'right' | 'top' | 'bottom';
+
+export interface ButtonConfig {
+  key: string;
+  label: string | (() => string);
+  type?: 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'default';
+  plain?: boolean;
+  size?: 'large' | 'default' | 'small';
+  disabled?: boolean | (() => boolean);
+  loading?: boolean | (() => boolean);
+  visible?: boolean | (() => boolean);
+  closeOnClick?: boolean;
+  exposeName?: string;
+  onClick?: (ctx: ButtonContext) => boolean | Promise<boolean | void> | void;
+}
+
+export interface ButtonContext {
+  id: string | number;
+  close: () => void;
+  setContentLoading: (loading: boolean) => void;
+  setButtonLoading: (key: string, loading: boolean) => void;
+  getData: <T = unknown>() => T;
+  emit: (event: string, ...args: unknown[]) => void;
+  triggerButtonClick: (key: string) => void;
+  open: (options: ModalOptions) => ModalController;
+  triggerConfirm: () => void;
+  triggerCancel: () => void;
+}
+
+export interface ModalOptions {
+  type?: ModalType;
+  title?: string | Component | VNode | (() => VNode);
+  header?: string | Component | VNode | (() => VNode);
+  content?: string | Component | VNode | (() => VNode);
+  footer?: string | Component | VNode | (() => VNode);
+  data?: Record<string, unknown>;
+  width?: string | number;
+  size?: string | number;
+  direction?: DrawerDirection;
+  showHeader?: boolean;
+  showClose?: boolean;
+  showFooter?: boolean;
+  destroyOnClose?: boolean;
+  appendToBody?: boolean;
+  linkContentLoading?: boolean;
+  closeOnParentClose?: boolean;
+  parentId?: string | number;
+  buttons?: ButtonConfig[];
+  buttonOrder?: string[];
+  zIndex?: number;
+  className?: string;
+  customClass?: string;
+  beforeClose?: (done: () => void) => void | boolean | Promise<boolean | void>;
+  onOpen?: () => void;
+  onOpened?: () => void;
+  onClose?: () => boolean | Promise<boolean | void> | void;
+  onClosed?: () => void;
+  i18n?: Record<string, string>;
+  elProps?: Record<string, unknown>;
+  injectType?: 'props' | 'provide' | false;
+}
+
+export interface GlobalModalConfig extends Omit<ModalOptions, 'content' | 'data' | 'onOpen' | 'onOpened' | 'onClose' | 'onClosed' | 'parentId'> {}
+
+export interface ModalController {
+  id: string | number;
+  visible: boolean;
+  close: () => void;
+  setContentLoading: (loading: boolean) => void;
+  setButtonLoading: (key: string, loading: boolean) => void;
+  getData: <T = unknown>() => T;
+  triggerButtonClick: (key: string) => void;
+  open: (options: ModalOptions) => ModalController;
+}
+
+export interface ModalInstance {
+  id: string | number;
+  parentId?: string | number;
+  options: Required<ModalOptions>;
+  controller: ModalController;
+  visible: boolean;
+}
+```
+
+### 2. 全局默认配置（Config.ts）
+
+```typescript
+import type { GlobalModalConfig } from './Types';
+
+let globalConfig: GlobalModalConfig = {};
+
+export function configureModal(config: GlobalModalConfig) {
+  globalConfig = { ...globalConfig, ...config };
+}
+
+export function getGlobalConfig(): GlobalModalConfig {
+  return { ...globalConfig };
+}
+```
+
+### 3. Hook 主体（index.ts）
+
+```typescript
+import { ref, computed, h, render, nextTick, provide, inject, type Component, type VNode } from 'vue';
+import { ElDialog, ElDrawer } from 'element-plus';
+import type {
+  ModalOptions,
+  ModalController,
+  ModalInstance,
+  ButtonConfig,
+  ButtonContext,
+  GlobalModalConfig,
+} from './Types';
+import { getGlobalConfig } from './Config';
+
+let seed = 0;
+const stack = ref<ModalInstance[]>([]);
+
+// 默认文案遵循文案规范：使用具体动作而非模糊的"确定"
+const defaultI18n = { cancelText: '取消', confirmText: '确认' };
+
+function getI18nText(local?: Record<string, string>, key: string): string {
+  const merged = { ...defaultI18n, ...getGlobalConfig().i18n, ...local };
+  return merged[key] || defaultI18n[key as keyof typeof defaultI18n] || key;
+}
+
+function buildDefaultButtons(options: ModalOptions): ButtonConfig[] {
+  if (options.showFooter === false) return [];
+  return [
+    { key: 'cancel', label: () => getI18nText(options.i18n, 'cancelText'), closeOnClick: true },
+    { key: 'confirm', label: () => getI18nText(options.i18n, 'confirmText'), type: 'primary', closeOnClick: true },
+  ];
+}
+
+function resolveLabel(label: ButtonConfig['label']): string {
+  if (typeof label === 'function') return label();
+  return label;
+}
+
+function resolveBool(value: boolean | (() => boolean) | undefined, fallback: boolean): boolean {
+  if (typeof value === 'function') return value();
+  return value ?? fallback;
+}
+
+function resolveRender(node: unknown): VNode | string | null {
+  if (!node) return null;
+  if (typeof node === 'string') return h('span', null, node);
+  if (typeof node === 'function') return (node as () => VNode)();
+  return h(node as Component);
+}
+
+function createController(instance: ModalInstance): ModalController {
+  return {
+    id: instance.id,
+    get visible() {
+      return instance.visible;
+    },
+    close: () => closeModal(instance.id),
+    setContentLoading: (loading: boolean) => {
+      instance.options.linkContentLoading = loading;
+    },
+    setButtonLoading: (key: string, loading: boolean) => {
+      const btn = instance.options.buttons?.find((b) => b.key === key);
+      if (btn) btn.loading = loading;
+    },
+    getData: <T = unknown>() => (instance.options.data as T) ?? ({} as T),
+    triggerButtonClick: (key: string) => handleButtonClick(instance, key),
+    open: (options: ModalOptions) => openModal({ ...options, parentId: instance.id }),
+  };
+}
+
+async function callExposedMethod(instance: ModalInstance, button: ButtonConfig): Promise<boolean | void> {
+  // 注入方法到 content 组件时通过 props 或 provide 暴露
+  // 这里通过 controller 上的方法模拟暴露调用
+  return undefined;
+}
+
+async function handleButtonClick(instance: ModalInstance, key: string) {
+  const buttons = instance.options.buttons || [];
+  const button = buttons.find((b) => b.key === key);
+  if (!button) return;
+
+  const ctx: ButtonContext = {
+    id: instance.id,
+    close: () => closeModal(instance.id),
+    setContentLoading: (loading: boolean) => {
+      instance.options.linkContentLoading = loading;
+    },
+    setButtonLoading: (k: string, loading: boolean) => {
+      const target = buttons.find((b) => b.key === k);
+      if (target) target.loading = loading;
+    },
+    getData: <T = unknown>() => (instance.options.data as T) ?? ({} as T),
+    emit: (event: string, ...args: unknown[]) => {
+      // 触发自定义事件，可向外暴露
+      console.log('modal:emit', event, args);
+    },
+    triggerButtonClick: (k: string) => handleButtonClick(instance, k),
+    open: (options: ModalOptions) => openModal({ ...options, parentId: instance.id }),
+    triggerConfirm: () => handleButtonClick(instance, 'confirm'),
+    triggerCancel: () => handleButtonClick(instance, 'cancel'),
+  };
+
+  // 1. 优先调用内容组件暴露的方法
+  const exposeName = button.exposeName || `on${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+  // 实际调用在 render 组件中通过 ref 获取内容组件实例执行
+  // 这里先执行 onClick
+  let shouldClose = button.closeOnClick !== false;
+  if (button.onClick) {
+    const result = await button.onClick(ctx);
+    if (result === false) shouldClose = false;
+  }
+  if (shouldClose) closeModal(instance.id);
+}
+
+function openModal(options: ModalOptions): ModalController {
+  const final: Required<ModalOptions> = {
+    type: 'dialog',
+    title: '',
+    header: '',
+    content: '',
+    footer: '',
+    data: {},
+    width: '50%',
+    size: '30%',
+    direction: 'right',
+    showHeader: true,
+    showClose: true,
+    showFooter: true,
+    destroyOnClose: true,
+    appendToBody: true,
+    linkContentLoading: false,
+    closeOnParentClose: false,
+    parentId: undefined,
+    buttons: [],
+    buttonOrder: [],
+    zIndex: 2000,
+    className: '',
+    customClass: '',
+    beforeClose: () => true,
+    onOpen: () => {},
+    onOpened: () => {},
+    onClose: () => true,
+    onClosed: () => {},
+    i18n: {},
+    elProps: {},
+    injectType: 'props',
+    ...getGlobalConfig(),
+    ...options,
+  };
+
+  if (!final.buttons || final.buttons.length === 0) {
+    final.buttons = buildDefaultButtons(final);
+  }
+
+  const id = ++seed;
+  const instance: ModalInstance = {
+    id,
+    parentId: final.parentId,
+    options: final,
+    visible: true,
+    controller: null as unknown as ModalController,
+  };
+  instance.controller = createController(instance);
+  stack.value.push(instance);
+  return instance.controller;
+}
+
+function closeModal(id: string | number) {
+  const idx = stack.value.findIndex((i) => i.id === id);
+  if (idx === -1) return;
+  const instance = stack.value[idx];
+
+  // 关闭子弹窗
+  if (instance.options.closeOnParentClose) {
+    stack.value.filter((i) => i.parentId === id).forEach((child) => closeModal(child.id));
+  }
+
+  instance.visible = false;
+  nextTick(() => {
+    stack.value.splice(idx, 1);
+    instance.options.onClosed();
+  });
+}
+
+export function useModal() {
+  const visible = computed(() => stack.value.length > 0);
+
+  return {
+    open: openModal,
+    close: (id?: string | number) => {
+      const target = id ?? stack.value[stack.value.length - 1]?.id;
+      if (target !== undefined) closeModal(target);
+    },
+    closeAll: () => {
+      [...stack.value].forEach((i) => closeModal(i.id));
+    },
+    getStack: () => stack.value.map((i) => i.controller),
+    visible,
+  };
+}
+
+export { configureModal } from './Config';
+export type * from './Types';
+```
+
+### 4. 渲染组件（Render.tsx，可选）
+
+> 说明：本组件是 Hook 内部使用的渲染组件，并非通用业务组件，因此保留 `.tsx` + `defineComponent` 渲染函数形式（通用业务组件必须用 `<script setup lang="ts">` + `index.vue`）。代码组织仍遵循 [pandax-frontend-standards](../pandax-frontend-standards/SKILL.md) 的 `// #region` 区域约定；样式通过 `index.module.scss` 做 CSS Modules 隔离。
+
+```tsx
+import { defineComponent, computed, ref, watch, h, inject, provide, type PropType } from 'vue';
+import { ElDialog, ElDrawer } from 'element-plus';
+import type { ModalInstance, ButtonConfig } from '../Types';
+import styles from './index.module.scss';
+
+export default defineComponent({
+  name: 'UseModalRender',
+  props: {
+    instance: { type: Object as PropType<ModalInstance>, required: true },
+  },
+  setup(props) {
+    // #region Props - 组件属性定义
+    // instance 由父级传入，承载弹窗实例的全部状态
+    // #endregion
+
+    // #region Types - 组件内部类型
+    // 当前组件未使用额外内部类型
+    // #endregion
+
+    // #region State - 响应式数据
+    const visible = computed({
+      get: () => props.instance.visible,
+      set: (v) => {
+        if (!v) props.instance.controller.close();
+      },
+    });
+
+    const contentRef = ref<Record<string, unknown> | null>(null);
+    const provideKey = `__modal_controller_${props.instance.id}__`;
+    provide(provideKey, props.instance.controller);
+    // #endregion
+
+    // #region Computed - 计算属性
+    // 当前组件未使用
+    // #endregion
+
+    // #region Watch - 监听器
+    // 当前组件未使用
+    // #endregion
+
+    // #region Lifecycle - onBeforeMount
+    // 在挂载开始之前调用
+    // 当前组件未使用
+    // #endregion
+
+    // #region Lifecycle - onMounted
+    // 组件挂载完成后调用
+    // 当前组件未使用
+    // #endregion
+
+    // #region Lifecycle - onBeforeUpdate
+    // 组件更新前调用
+    // 当前组件未使用
+    // #endregion
+
+    // #region Lifecycle - onUpdated
+    // 组件更新后调用
+    // 当前组件未使用
+    // #endregion
+
+    // #region Lifecycle - onBeforeUnmount
+    // 组件卸载前调用
+    // 当前组件未使用
+    // #endregion
+
+    // #region Lifecycle - onUnmounted
+    // 组件卸载后调用
+    // 当前组件未使用
+    // #endregion
+
+    // #region Methods - 组件内部方法
+    function renderContent() {
+      const content = props.instance.options.content;
+      if (!content) return null;
+      const injectMethods = props.instance.options.injectType === 'props'
+        ? props.instance.controller
+        : {};
+      if (typeof content === 'string') return h('span', null, content);
+      if (typeof content === 'function') return (content as () => unknown)();
+      return h(content as any, {
+        ref: contentRef,
+        ...injectMethods,
+        data: props.instance.options.data,
+      });
+    }
+
+    function renderHeader() {
+      const { header, title, showHeader, showClose } = props.instance.options;
+      if (!showHeader) return null;
+      if (header) {
+        const node = typeof header === 'function' ? header() : header;
+        return typeof node === 'string' ? h('span', null, node) : h(node as any);
+      }
+      return (
+        <div class={styles.header}>
+          <span class={styles.title}>{typeof title === 'string' ? title : ''}</span>
+        </div>
+      );
+    }
+
+    function renderFooter() {
+      const { showFooter, buttons, buttonOrder } = props.instance.options;
+      if (!showFooter || !buttons?.length) return null;
+      const order = buttonOrder?.length ? buttonOrder : buttons.map((b) => b.key);
+      const ordered = order
+        .map((key) => buttons.find((b) => b.key === key))
+        .filter(Boolean) as ButtonConfig[];
+
+      return ordered.map((btn) => (
+        <el-button
+          key={btn.key}
+          type={btn.type || 'default'}
+          plain={btn.plain}
+          size={btn.size || 'default'}
+          loading={typeof btn.loading === 'function' ? btn.loading() : btn.loading}
+          disabled={typeof btn.disabled === 'function' ? btn.disabled() : btn.disabled}
+          onClick={() => props.instance.controller.triggerButtonClick(btn.key)}
+        >
+          {typeof btn.label === 'function' ? btn.label() : btn.label}
+        </el-button>
+      ));
+    }
+
+    function renderWrapper() {
+      const { type, width, size, direction, zIndex, className, customClass, elProps } = props.instance.options;
+      const common = {
+        modelValue: visible.value,
+        'onUpdate:modelValue': (v: boolean) => {
+          if (!v) props.instance.controller.close();
+        },
+        zIndex,
+        class: [styles.wrapper, className, customClass].filter(Boolean).join(' ') || undefined,
+        destroyOnClose: true,
+        ...elProps,
+      };
+
+      const slots = {
+        header: renderHeader,
+        default: renderContent,
+        footer: renderFooter,
+      };
+
+      if (type === 'drawer') {
+        return h(ElDrawer, { ...common, size, direction }, slots);
+      }
+      return h(ElDialog, { ...common, width }, slots);
+    }
+    // #endregion
+
+    // #region Expose - 对外暴露
+    // 当前组件未对外暴露方法
+    // #endregion
+
+    return () => renderWrapper();
+  },
+});
+```
+
+配套的 `index.module.scss`：
+
+```scss
+.wrapper {
+  // 弹窗/抽屉容器外壳样式（按需扩展）
+}
+
+.header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.title {
+  font-weight: 600;
+}
+```
+
+### 5. 全局挂载（main.ts）
+
+```typescript
+import { configureModal } from '@/composables/use-modal';
+
+configureModal({
+  showHeader: true,
+  showClose: true,
+  showFooter: true,
+  linkContentLoading: true,
+  destroyOnClose: true,
+  appendToBody: true,
+  i18n: { cancelText: '取消', confirmText: '确认' },
+});
+```
+
+## 使用示例
+
+### 基础弹窗
+
+```typescript
+import { useModal } from '@/composables/use-modal';
+import ConfirmContent from './ConfirmContent.vue';
+
+const modal = useModal();
+
+modal.open({
+  title: '确认删除',
+  content: '确定要删除该记录吗？',
+  buttons: [
+    { key: 'cancel', label: '取消', closeOnClick: true },
+    { key: 'confirm', label: '确认删除', type: 'primary', onClick: async () => {
+      await deleteRecord();
+      return true;
+    }},
+  ],
+});
+```
+
+### 嵌套弹窗
+
+```typescript
+// ComponentA.vue
+const props = defineProps<{
+  open: (options: any) => any;
+}>();
+
+const openB = () => {
+  props.open({
+    title: 'B 弹窗',
+    content: ComponentB,
+  });
+};
+```
+
+### 内容组件与按钮联动
+
+```typescript
+// UserForm.vue
+const props = defineProps<{
+  close?: () => void;
+  triggerButtonClick?: (key: string) => void;
+}>();
+
+const handleCustomConfirm = async () => {
+  await props.triggerButtonClick?.('confirm');
+};
+```
+
+## 输出要求
+
+1. 优先生成 `src/composables/use-modal/` 下的文件，命名遵循 [pandax-frontend-standards](../pandax-frontend-standards/SKILL.md)：目录全小写 + 短横线，非入口文件 PascalCase（`Types.ts` / `Config.ts` / `Render.tsx`）
+2. 类型定义必须完整，导出 `ModalOptions`、`ModalController`、`ButtonConfig`
+3. 必须支持 `configureModal` 全局配置
+4. 必须支持 `dialog` 和 `drawer` 两种类型
+5. 按钮点击逻辑必须优先调用内容组件暴露的方法，再执行 `onClick`
+6. 内容组件注入方法必须包含 `close`、`setContentLoading`、`setButtonLoading`、`getData`、`emit`、`triggerButtonClick`、`open`
+7. 代码必须写清楚 TODO 或注意点，不能含糊
+8. 渲染组件代码必须按 `// #region` 区域（Props / Types / State / Computed / Watch / Lifecycle / Methods / Expose）组织；样式必须使用 `index.module.scss` 做 CSS Modules 隔离，禁止裸 class
+9. 按钮文案遵循文案规范：使用具体动作（如"确认删除"、"保存"），避免模糊的"确定"
+10. 生成后给出 2 个使用示例：基础弹窗、嵌套弹窗

package/templates/pandax-monorepo/.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig 与 Prettier 保持一致：https://editorconfig.org/
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2

package/templates/pandax-monorepo/.husky/commit-msg

@@ -0,0 +1,2 @@
+# Husky v9 hook：校验 commit message 是否符合 Conventional Commits
+pnpm exec commitlint --edit "$1"

package/templates/pandax-monorepo/.husky/pre-commit

@@ -0,0 +1,2 @@
+# Husky v9 hook：提交前对暂存区文件跑 ESLint + Prettier
+pnpm exec lint-staged

package/templates/pandax-monorepo/.prettierrc.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf",
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "htmlWhitespaceSensitivity": "css",
+  "vueIndentScriptAndStyle": false,
+  "overrides": [
+    {
+      "files": ["*.json", "*.json5", "*.jsonc"],
+      "options": { "trailingComma": "none" }
+    },
+    {
+      "files": ["*.md", "*.mdx"],
+      "options": { "proseWrap": "preserve", "printWidth": 120 }
+    },
+    {
+      "files": ["*.yml", "*.yaml"],
+      "options": { "singleQuote": false }
+    }
+  ]
+}

package/templates/pandax-monorepo/apps/base/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/pandax-monorepo/apps/base/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pandax Base App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>