feat: enhance permission directive denied UI

SeasonsChange422 · SeasonsChange422 · commit 60e831d0be42 · 2026-01-04T20:52:36.000+08:00
diff --git a/docs/directives/permission.md b/docs/directives/permission.md
@@ -104,6 +104,50 @@ createPermissionDirective({
 })
 ```
 
+### 展示原文 + 删除线（showOriginal / strikeOriginal）
+
+在常见的“原价划线 + 折扣价”场景下，可以在 `replace` 模式启用“展示原文”能力：
+
+```ts
+createPermissionDirective({
+  rules: {
+    'product.price': {
+      whenDenied: {
+        mode: 'replace',
+        replaceText: '80',
+        showOriginal: true,
+        strikeOriginal: true
+      }
+    }
+  },
+  resolvePermission: () => false
+})
+```
+
+> 注意：该能力面向 **文本展示** 的 replace 目标节点；若目标节点包含复杂子树（组件/事件/多层 DOM），替换与恢复会退化为 `textContent` 模型，原子节点结构会丢失。
+
+## 禁用提示（disableTooltip）
+
+在 `disable` 模式下，可以配置 denied tooltip，在 hover/focus 时展示提示文案：
+
+```ts
+createPermissionDirective({
+  rules: {
+    'order.submit': {
+      whenDenied: {
+        mode: 'disable',
+        disableTooltip: {
+          text: '无权限操作'
+          // class?: 'your-class'
+          // style?: { maxWidth: '240px' }
+        }
+      }
+    }
+  },
+  resolvePermission: () => false
+})
+```
+
 ## 权限等级（byLevel）
 
 当你的权限解析器返回“等级”时（例如 `none/masked/full`），可以按等级分别配置行为：
@@ -148,7 +192,7 @@ createPermissionDirective({
 ## 行为说明
 
 - `hide`：设置宿主元素 `display: none`
-- `disable`：保持可见但不可交互（`cursor: not-allowed` + `aria-disabled="true"`；并在捕获阶段拦截 `click` 事件以阻止默认行为与事件传播；对可禁用表单控件会设置 `disabled=true`）
+- `disable`：保持可见但不可交互（`cursor: not-allowed` + `aria-disabled="true"`；并在捕获阶段拦截 `click` 事件以阻止默认行为与事件传播；对可禁用表单控件会设置 `disabled=true`；可选 `disableTooltip` 在 hover/focus 时提示原因）
 - `replace`：仅对宿主元素内部带标识属性的子元素设置 `textContent`
 - `allow`：不处理并恢复原始状态
 
@@ -221,6 +265,15 @@ export type PermissionMode = 'allow' | 'hide' | 'disable' | 'replace'
 export interface PermissionBehavior {
   mode: PermissionMode
   replaceText?: string
+
+  disableTooltip?: {
+    text: string
+    class?: string
+    style?: Partial<CSSStyleDeclaration>
+  }
+
+  showOriginal?: boolean
+  strikeOriginal?: boolean
 }
 
 export type PermissionByLevelConfig = Partial<Record<string, PermissionBehavior>>
diff --git a/openspec/changes/enhance-permission-directive-denied-ui/design.md b/openspec/changes/enhance-permission-directive-denied-ui/design.md
@@ -0,0 +1,28 @@
+## Context
+`v-permission` 当前支持 `hide/disable/replace/allow`：
+- `disable`：设置 `cursor`/`aria-disabled`，并阻止 click 默认行为与事件传播。
+- `replace`：仅替换宿主元素内部带标识属性的子元素 `textContent`（默认 `data-permission-replace`）。
+
+本变更为 denied 状态增强两类 UI 表达：禁用时提示气泡、替换时可展示原文并划线。
+
+## Goals / Non-Goals
+- Goals
+  - 在不引入外部依赖前提下，为 `disable` 提供可选 tooltip DOM。
+  - 为 `replace` 提供可选的“原文 + 划线 + 替换文案”渲染。
+  - 维持现有默认行为与 API 兼容。
+- Non-Goals
+  - 不新增复杂的 Popover 组件、定位引擎、或全局管理器。
+  - 不支持对任意复杂子树（包含组件/事件绑定）的无损替换；仅面向文本展示场景。
+
+## Decisions
+- Tooltip 实现：使用指令在宿主元素上注册 hover/focus 监听，在 `document.body` 中创建/定位一个 tooltip 元素（内容使用 `textContent` 写入），在 restore/unmount 时移除与解绑。
+- Tooltip 样式：提供 `class` 与 `style` 配置；默认样式使用项目已有 CSS 变量（`--tml-*`）以避免硬编码新颜色/阴影。
+- Replace 原文划线：在 replace 目标元素内部，用 DOM 节点组合（原文 span + 分隔符 + 替换 span）进行渲染；恢复时还原为原始文本（保持与既有 `textContent` 替换模型一致）。
+
+## Risks / Trade-offs
+- `replace` 目标节点若包含复杂子树（非纯文本），替换与恢复会丢失原子节点结构（与当前 `textContent` 替换模型一致）。文档需强调仅用于文本展示目标。
+- Tooltip 需要注意滚动/窗口变化时的位置更新；本变更默认在 show 时计算位置，并在窗口 scroll/resize 时同步更新（或在最小实现下仅 show 时计算，待需求明确）。
+
+## Open Questions
+- Tooltip 是否需要支持常显（非 hover/focus）或自定义触发事件。
+- Replace “展示原内容”是否需要额外的样式配置（如原文灰色、小号、间距）。
diff --git a/openspec/changes/enhance-permission-directive-denied-ui/proposal.md b/openspec/changes/enhance-permission-directive-denied-ui/proposal.md
@@ -0,0 +1,26 @@
+# Change: Enhance v-permission denied UX (tooltip + strike-through)
+
+## Why
+当前 `v-permission` 的 `disable` 与 `replace` 模式缺少更直观的“被拒绝原因/替代展示”能力：
+- `disable` 仅禁用交互，无法提示原因/文案。
+- `replace` 仅替换目标文本，无法覆盖“原价划线 + 折扣价”这类常见展示。
+
+## What Changes
+- 为 `mode: 'disable'` 增加可选的“气泡提示（tooltip）”能力：文本可配置，样式可配置。
+- 为 `mode: 'replace'` 增加可选的“展示原内容并划线”能力（用于原价/折扣价展示）。
+- 保持现有 `hide/disable/replace/allow` 行为兼容；未配置新选项时行为不变。
+
+## Impact
+- Affected capability: `permission-directive`
+- Affected code:
+  - `src/directives/permission/types.ts`
+  - `src/directives/permission/index.ts`
+  - `tests/directives/permission.spec.ts`
+  - `docs/directives/permission.md`
+
+## Notes / Gaps
+- 当前 `permission-directive` 的规范仅存在于历史归档变更中（`openspec/changes/archive/2025-12-15-add-permission-directive/...`），未出现在 `openspec/specs/` 列表。本变更将以 delta spec 的形式补齐新增/修改的需求；后续归档阶段应将 capability 纳入 `openspec/specs/`（按项目流程执行）。
+
+## Open Questions
+- `disable` 的“气泡”触发方式：默认按 hover/focus 展示是否符合预期？是否需要支持常显？
+- `replace` 的“展示原内容”：默认仅作用于带替换标识属性的目标节点（例如 `data-permission-replace`）是否符合预期？
diff --git a/openspec/changes/enhance-permission-directive-denied-ui/specs/permission-directive/spec.md b/openspec/changes/enhance-permission-directive-denied-ui/specs/permission-directive/spec.md
@@ -0,0 +1,52 @@
+## MODIFIED Requirements
+
+### Requirement: Configurable modes (hide/disable/replace)
+系统 SHALL 支持至少三种权限表现：隐藏、禁用、替换。
+
+#### Scenario: Disable mode (base behavior)
+- **GIVEN** 某 key 的规则 mode 为 `disable`
+- **WHEN** 当前用户不具备该 key 权限
+- **THEN** 指令 SHALL 禁用目标元素（保持可见但不可交互）
+- **AND** 指令 SHALL 为目标元素设置 `cursor: not-allowed`
+- **AND** 指令 SHALL 阻止点击事件的默认行为与事件传播
+
+#### Scenario: Disable mode with tooltip
+- **GIVEN** 某 key 的规则 mode 为 `disable`
+- **AND** 该规则配置了禁用提示（tooltip）文本
+- **WHEN** 当前用户不具备该 key 权限
+- **THEN** 指令 SHALL 在用户 hover 或 focus 目标元素时展示一个气泡提示
+- **AND** 气泡提示文本 SHALL 来自配置项
+- **AND** 气泡提示样式 SHALL 支持通过配置项自定义
+- **AND** 当权限变为允许或指令 unmounted 时，气泡提示相关 DOM 与事件监听 SHALL 被清理
+
+### Requirement: Replace mode only affects marked descendants
+系统 SHALL NOT 直接改写宿主元素整体内容；`replace` 模式 SHALL 仅替换宿主元素内部带标识属性的子元素内容。
+
+#### Scenario: Replace mode shows original with strike-through (optional)
+- **GIVEN** 某 key 的规则 mode 为 `replace`
+- **AND** 目标元素内部存在带有“标识属性”的子元素（默认 `data-permission-replace`）
+- **AND** 该规则配置了“展示原内容”（showOriginal）
+- **WHEN** 当前用户不具备该 key 权限
+- **THEN** 指令 SHALL 在被替换的目标子元素内同时展示原内容与替换文案
+- **AND** 若配置了“原内容划线”（strikeOriginal），原内容 SHALL 以删除线样式展示
+- **AND** 当权限变为允许或指令 updated/unmounted 时，目标子元素 SHALL 恢复原始内容
+
+## ADDED Requirements
+
+### Requirement: Disable tooltip is configurable
+系统 SHALL 允许为 `disable` 模式配置提示文案与样式。
+
+#### Scenario: Configure tooltip text and style
+- **GIVEN** 使用方在规则中为 `disable` 行为配置 tooltip 文案
+- **AND** 使用方可选配置 tooltip 的 class/style
+- **WHEN** 指令应用 `disable` 行为
+- **THEN** tooltip 文案 SHALL 按配置展示
+- **AND** tooltip 样式 SHALL 按配置应用
+
+### Requirement: Replace can optionally preserve original content
+系统 SHALL 允许 `replace` 模式在替换目标中保留原内容用于展示。
+
+#### Scenario: Preserve original content for discounted price
+- **GIVEN** 使用方为 `replace` 行为配置 showOriginal 与 strikeOriginal
+- **WHEN** 当前用户不具备该 key 权限
+- **THEN** 替换目标 SHALL 展示“原内容（可选划线） + 替换文案”
diff --git a/openspec/changes/enhance-permission-directive-denied-ui/tasks.md b/openspec/changes/enhance-permission-directive-denied-ui/tasks.md
@@ -0,0 +1,20 @@
+## 1. Proposal Validation
+- [x] 1.1 Run `openspec validate enhance-permission-directive-denied-ui --strict` and fix all issues
+
+## 2. Types & API
+- [x] 2.1 Extend `PermissionBehavior` to support disable tooltip configuration
+- [x] 2.2 Extend `PermissionBehavior` to support replace "show original + strike" configuration
+- [x] 2.3 Ensure backward compatibility for existing `replaceText` usage
+
+## 3. Directive Implementation
+- [x] 3.1 Implement tooltip lifecycle for `mode: 'disable'` (bind/unbind, create/remove DOM)
+- [x] 3.2 Implement replace rendering for "show original + strike" option
+- [x] 3.3 Ensure `restoreAll()` fully restores tooltip/replace states on updates/unmount
+
+## 4. Tests
+- [x] 4.1 Add unit tests for disable tooltip creation and cleanup
+- [x] 4.2 Add unit tests for replace showOriginal/strikeOriginal rendering and restore
+
+## 5. Docs
+- [x] 5.1 Update `docs/directives/permission.md` with new options and examples
+- [x] 5.2 Document limitations (replace targets should be text-only)
diff --git a/src/App.vue b/src/App.vue
@@ -199,7 +199,18 @@
               >
                 {{ hasPermissionKey('order.delete') ? '已授权' : '未授权' }}
               </tml-button>
-              <span class="permission-hint">（whenDenied: disable）</span>
+              <span class="permission-hint">（whenDenied: disable + disableTooltip）</span>
+            </div>
+
+            <div class="permission-control">
+              <span class="permission-label">product.discountPrice:</span>
+              <tml-button
+                :type="hasPermissionKey('product.discountPrice') ? 'success' : 'warning'"
+                @click="togglePermissionKey('product.discountPrice')"
+              >
+                {{ hasPermissionKey('product.discountPrice') ? '已授权' : '未授权' }}
+              </tml-button>
+              <span class="permission-hint">（whenDenied: replace + showOriginal/strikeOriginal）</span>
             </div>
 
             <div class="permission-control">
@@ -237,6 +248,18 @@
               <span class="permission-hint">（仅替换带 data-permission-replace 的文本）</span>
             </p>
           </div>
+
+          <div class="permission-card" v-permission="'product.discountPrice'">
+            <p class="permission-row">
+              <span class="permission-label">商品:</span>
+              <span>示例商品</span>
+            </p>
+            <p class="permission-row">
+              <span class="permission-label">促销价:</span>
+              <span data-permission-replace>{{ productOriginalPriceText }}</span>
+              <span class="permission-hint">（无权限时：原价划线 + 展示替换价）</span>
+            </p>
+          </div>
         </div>
       </section>
 
@@ -489,6 +512,8 @@ type PricePermissionLevel = 'none' | 'masked' | 'full'
 const grantedPermissionKeys = ref<string[]>(['order.create', 'order.delete'])
 const pricePermissionLevel = ref<PricePermissionLevel>('none')
 const productPriceText = ref('¥ 199.00')
+const productOriginalPriceText = ref('¥ 199.00')
+const productDiscountPriceText = ref('¥ 159.00')
 
 const hasPermissionKey = (key: string) => grantedPermissionKeys.value.includes(key)
 
@@ -503,18 +528,13 @@ const togglePermissionKey = (key: string) => {
 
 const vPermission = createPermissionDirective<PricePermissionLevel>({
   rules: {
-    'order.create': {
-      byLevel: {
-        none: { mode: 'hide' },
-        masked: { mode: 'disable' },
-        full: { mode: 'allow' }
-      }
-    },
+    'order.create': { whenDenied: { mode: 'hide' } },
     'order.delete': {
-      byLevel: {
-        none: { mode: 'disable' },
-        masked: { mode: 'disable' },
-        full: { mode: 'allow' }
+      whenDenied: {
+        mode: 'disable',
+        disableTooltip: {
+          text: '无权限删除'
+        }
       }
     },
     'product.price': {
@@ -523,10 +543,19 @@ const vPermission = createPermissionDirective<PricePermissionLevel>({
         masked: { mode: 'replace', replaceText: '**.**' },
         full: { mode: 'allow' }
       }
+    },
+    'product.discountPrice': {
+      whenDenied: {
+        mode: 'replace',
+        replaceText: productDiscountPriceText.value,
+        showOriginal: true,
+        strikeOriginal: true
+      }
     }
   },
-  resolvePermission: (_key) => {
-    return pricePermissionLevel.value
+  resolvePermission: (key) => {
+    if (key === 'product.price') return pricePermissionLevel.value
+    return hasPermissionKey(key)
   }
 })
 
diff --git a/src/directives/permission/index.ts b/src/directives/permission/index.ts
diff --git a/src/directives/permission/types.ts b/src/directives/permission/types.ts
diff --git a/tests/directives/permission.spec.ts b/tests/directives/permission.spec.ts
