imean-service-engine-htmx-plugin 1.2.0 → 2.0.0

package/docs/design-principles.md

@@ -0,0 +1,102 @@
+# 设计原则
+
+## 后端控制交换目标
+
+### 核心原则
+
+**交换目标的控制应该完全交由后端控制，前端不应该设置 `hx-target` 和 `hx-swap` 属性。**
+
+### 为什么？
+
+1. **简洁性**：提供一个简单易用的后台管理框架，代码应该简洁
+2. **灵活性**：后端可以根据请求参数（如 `?dialog=true`）动态决定交换目标
+3. **错误处理**：如果请求失败，后端可以返回错误通知而不替换任何内容，不影响用户的现有工作状态
+
+### 示例场景
+
+#### 场景 1：弹框模式
+
+用户点击一个链接，链接是 `?dialog=true`，后端应该：
+- 检测到 `dialog=true` 参数
+- 设置 `HX-Retarget: #dialog-container` 和 `HX-Reswap: innerHTML`
+- 返回 Dialog 组件包装的内容
+
+**前端代码**：
+```tsx
+// ✅ 正确：使用 hx-get 触发 HTMX 请求，保留 href 用于普通跳转或新窗口打开
+<a 
+  href="/admin/articles/detail/1?dialog=true"
+  hx-get="/admin/articles/detail/1?dialog=true"
+>
+  在弹框中打开文章详情
+</a>
+
+// ❌ 错误：不应该在前端设置 hx-target，后端会根据 ?dialog=true 自动设置
+<a 
+  href="/admin/articles/detail/1?dialog=true"
+  hx-get="/admin/articles/detail/1?dialog=true"
+  hx-target="#dialog-container"
+  hx-swap="innerHTML"
+>
+  在弹框中打开文章详情
+</a>
+
+// ✅ 正确：只使用 href，用于普通跳转或新窗口打开（右键菜单）
+<a href="/admin/articles/detail/1">
+  在新窗口打开文章详情
+</a>
+```
+
+#### 场景 2：错误处理
+
+如果请求失败（例如权限不足、服务器错误等），后端应该：
+- 返回错误通知（OOB swap）
+- 设置 `HX-Reswap: none` 阻止替换任何内容
+- 不影响用户的现有工作状态
+
+**后端代码**：
+```typescript
+// HTMX 请求失败时
+if (isHtmxRequest) {
+  return ctx.html(
+    <>
+      <div id="error-container" hx-swap-oob="beforeend">
+        <ErrorAlert
+          type="error"
+          title="请求失败"
+          message={errorMessage}
+        />
+      </div>
+      <title>错误</title>
+    </>,
+    500,
+    {
+      "HX-Reswap": "none", // 关键：不替换任何内容
+    }
+  );
+}
+```
+
+### 实现细节
+
+1. **检测弹框模式**：
+   - 通过 `?dialog=true` 查询参数
+   - 通过 `HX-Target: #dialog-container` 请求头
+   - 通过 `Referer` 头中的 `dialog=true`
+
+2. **设置响应头**：
+   - 弹框模式：`HX-Retarget: #dialog-container`, `HX-Reswap: innerHTML`
+   - 普通模式：`HX-Retarget: #main-content`, `HX-Reswap: outerHTML`
+   - 错误/通知：`HX-Reswap: none`（不替换任何内容）
+
+3. **错误处理**：
+   - 所有错误都应该返回通知而不是替换内容
+   - 使用 OOB swap 将通知插入到 `#error-container`
+   - 设置 `HX-Reswap: none` 阻止内容替换
+
+### 优势
+
+1. **代码简洁**：前端代码不需要关心交换目标，只需要提供链接
+2. **灵活控制**：后端可以根据业务逻辑动态决定交换目标
+3. **错误友好**：错误不会破坏用户的当前工作状态
+4. **易于维护**：交换逻辑集中在一个地方，易于修改和测试

package/docs/quick-reference.md

@@ -481,6 +481,50 @@ interface FormField {
 - `GET /{basePath}/new?dialog=true`: 对话框新建
 - `GET /{basePath}/edit/:id?dialog=true`: 对话框编辑
 
+### 弹窗配置
+
+#### 弹窗大小
+
+支持的大小选项：
+- `"sm"`: 小（max-w-md，约 448px）
+- `"md"`: 中（max-w-lg，约 512px）
+- `"lg"`: 大（max-w-2xl，约 672px）- **默认值**
+- `"xl"`: 超大（max-w-4xl，约 896px）
+- `"full"`: 全屏（max-w-7xl，约 1280px）
+
+#### 遮罩关闭配置
+
+- `closeOnBackdropClick: true`（默认）：允许点击遮罩关闭
+- `closeOnBackdropClick: false`：禁止点击遮罩关闭，只能通过关闭按钮关闭
+
+#### 配置示例
+
+```typescript
+// 通过 crud() 方法配置
+this.features.crud({
+  permissionPrefix: "articles",
+  // ... 其他配置
+  dialogSizes: {
+    detail: "xl",
+    edit: "xl",
+    create: "xl",
+  },
+  closeOnBackdropClick: {
+    edit: false,   // 编辑时禁止点击遮罩关闭
+    create: false, // 创建时禁止点击遮罩关闭
+    detail: true,  // 详情页允许点击遮罩关闭
+  },
+});
+
+// 通过 CustomFeature 配置
+this.features.custom("my-feature", new CustomFeature({
+  name: "my-feature",
+  dialogSize: "xl",
+  closeOnBackdropClick: false,
+  // ... 其他配置
+}));
+```
+
 ## 调试技巧
 
 ### 1. 查看响应头

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "imean-service-engine-htmx-plugin",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "HtmxAdminPlugin for IMean Service Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsup",
-    "dev": "tsx examples/index.ts",
+    "dev": "tsx examples-v2/index.ts",
     "test": "vitest --run",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --run --coverage",
+    "test:unit": "vitest --run --project unit",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
     "prepublishOnly": "npm run build && npm run test"
   },
   "keywords": [
@@ -35,10 +39,13 @@
     "zod": "^4.1.13"
   },
   "devDependencies": {
+    "@playwright/test": "^1.57.0",
     "@types/node": "^25.0.1",
+    "@vitest/browser-playwright": "^4.0.16",
     "@vitest/coverage-v8": "4.0.15",
     "@vitest/ui": "^4.0.15",
     "imean-service-client": "^1.6.0",
+    "playwright": "^1.57.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",