u

code/g3soft-libs/docs/content/ui/form/rich-text.md

@@ -0,0 +1,173 @@
+---
+title: RichText 富文本编辑器
+description: 基于 Tiptap 的富文本编辑，支持字体、字号、对齐、文字与背景色、上下标、图片视频上传与表格
+---
+
+# RichText 富文本编辑器
+
+`RichText` 是基于 [Tiptap](https://tiptap.dev) 封装的富文本编辑器，`v-model` 输出干净的 HTML 字符串，可直接作为邮件正文、公告正文等场景使用。
+
+## 何时使用
+
+- 录入需要富文本格式的正文（公告、邮件、通知、帮助文档）；
+- 需要字体 / 字号 / 对齐 / 文字颜色 / 背景颜色 / 上标 / 下标等排版能力时；
+- 需要在正文中嵌入图片 / 视频、插入表格时。
+
+> 纯文本或短文本请用 [Input](/ui/form/input)（`type="textarea"`），不要用富文本承载简单字段。
+
+## 基础用法
+
+`v-model` 双向绑定 HTML 字符串，工具条默认置顶，内置字体 / 字号 / 对齐 / 颜色 / 上下标 / 表格 / 撤销重做。
+
+<demo vue="rich-text/basic.vue" />
+
+## 工具条
+
+工具条按「一天点几次」而不是「功能重不重要」排布，**始终一行、高度恒定 48px**：
+
+- **常驻**（顺序：历史 → 正文格式 → 行内格式 → 对齐 → 颜色 → 列表与插入）：撤销、重做 ｜ 段落格式（正文 / 标题 1-3）｜ 加粗、斜体、下划线 ｜ 对齐（左 / 中 / 右）｜ 字体颜色、背景颜色 ｜ 无序列表、有序列表、链接、图片、插入表格；
+- **收进 `⋯ 更多`**：`字体` / `字号`（二级菜单，选中态跟随光标）、`格式` 组（删除线 / 上标 / 下标 / 引用）、`插入` 组（视频）。菜单项带分组标题与快捷键提示（对着 Tiptap 的真实键位写的，如删除线 `Ctrl+Shift+S`）。
+
+图标 16px、按钮 32px（等于 `--g3-control-height`）、组内间隙 4px、内边距 8px / 10px（左右 10px 让首列图标与正文的 12px 内边距对齐）；图标前景用 `text-1`（88% 黑）而不是 ghost 按钮默认的 `text-2`（65%），描边保持 lucide 原生粗细 —— 实测「发虚」的主因是浅灰前景而不是线宽，所以只加深颜色、不加重描边。整条工具条自然宽度约 **744px**：760px 以上的容器都是一行，再窄才折行，且折行以「组」为单位，不会把分隔线甩到行首/行尾。表格插入按钮留在工具条上而不是进 `⋯`：它要先选行列，收起后承载不了那个面板。
+
+## 对齐与颜色
+
+工具条提供三组排版能力，均作用于选区所在的块（正文段落 / 标题，表格单元格里的内容同样是段落）：
+
+- **对齐**（左 / 居中 / 右）：写 `text-align` 到块元素上；点当前档位即取消对齐，不需要单独的「取消」按钮；
+- **字体颜色**（`A` 图标 + 当前色条）：写 `color`；
+- **背景颜色**（荧光笔图标 + 当前色条）：写 `background-color`。
+
+两个取色按钮都是「图标 + 当前色条」的形式，色条显示选区当前的颜色（未设色时是空位）。点开后是预设色板面板：常用色一屏排满，`无颜色` 清除该属性，右侧彩虹色块打开系统取色器选任意颜色。选完色面板自动收起。
+
+## 图片 / 视频上传
+
+图片和视频通过 `upload-image` / `upload-video` 两个 prop 注入上传函数。上传函数接收 `File`，返回 `{ fileUrl, ... }` 元数据；上传完成后组件会触发 `upload-inline` 事件，把内联资源元数据上报给外层（对齐邮件「inline 附件」模型）。
+
+<demo vue="rich-text/upload.vue" />
+
+```ts
+// 上传函数约定
+type Upload = (file: File) => Promise<{
+  fileUrl: string      // 正文 img / video 的 src
+  fileId?: string      // 后端文件 id
+  cid?: string         // 内联资源 cid（邮件场景）
+  fileName?: string
+  fileSize?: number
+}>
+```
+
+## 只读 / 禁用
+
+`readonly` 可聚焦可复制但不可编辑；`disabled` 整体灰化不可交互。
+
+<demo vue="rich-text/readonly.vue" />
+
+## 表格
+
+工具条「插入表格」按钮弹出行 / 列选择面板（支持关闭表头行）；光标进入表格后，表格下方会浮出就近操作栏：
+
+- **行**：上方插入行、下方插入行、删除行；
+- **列**：左侧插入列、右侧插入列、删除列；
+- **单元格**：合并单元格、拆分单元格（两个独立按钮，不可用时各自置灰）；
+- **表头**：切换表头列、切换表头单元格；
+- **删除**：整表删除（与增删行列用分隔线隔开，防误点）。
+
+单元格内文字的对齐、颜色在顶部工具条里设置（单元格内容也是普通段落），操作栏不再重复提供。
+
+列宽拖拽：悬停列分隔线出现 `col-resize` 光标，左右拖动调整列宽。拖拽采用 `table-layout: fixed`，**只动被拖列、其余列纹丝不动**（Excel 语义）；列宽以 `colwidth` 属性持久化进 HTML，最小列宽 10px。拖宽后表格总宽超过容器时，在表格容器内横向滚动，不撑破编辑器内容区。`Tab` / `Shift+Tab` 在单元格间跳转，末格 `Tab` 自动追加行。
+
+> 行列数限制为 1–20，超出会在插入时自动夹回，避免一次性生成超大表格卡死编辑器。
+
+## 获取纯文本
+
+通过 `ref` 调用 `getText()` 拿到纯文本（邮件 `text/plain` 备选），`getHTML()` 拿 HTML，`clear()` 清空。
+
+<demo vue="rich-text/methods.vue" />
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string` | `''` | 双向绑定的 HTML 字符串 |
+| `placeholder` | `string` | — | 占位文案 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `readonly` | `boolean` | `false` | 只读态：可聚焦、可复制，但不可编辑 |
+| `toolbar` | `'top' \| 'bottom' \| false` | `'top'` | 工具条位置；`false` 隐藏工具条 |
+| `minHeight` | `number \| string` | `200` | 编辑区最小高度 |
+| `maxHeight` | `number \| string` | — | 编辑区最大高度（超出滚动） |
+| `uploadImage` | `(file: File) => Promise<RichTextUploadResult>` | — | 图片上传函数，返回完整元数据 |
+| `uploadVideo` | `(file: File) => Promise<RichTextUploadResult>` | — | 视频上传函数，返回完整元数据 |
+| `fonts` | `RichTextFontOption[]` | 内置字体表 | 「更多」菜单里字体子菜单的选项 |
+| `fontSizes` | `RichTextFontSizeOption[]` | 内置字号表 | 「更多」菜单里字号子菜单的选项 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(html: string)` | 内容变化时触发 |
+| `focus` | `(event: FocusEvent)` | 获得焦点 |
+| `blur` | `(event: FocusEvent)` | 失去焦点 |
+| `upload-inline` | `(result: RichTextUploadResult, kind: 'image' \| 'video')` | 内联资源上传完成，上报给外层收集 |
+| `upload-error` | `(error: Error, kind: 'image' \| 'video')` | 上传失败 |
+
+### Exposed（通过 ref 调用）
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `editor` | `Editor` | 底层 Tiptap 实例（进阶用法） |
+| `getHTML` | `() => string` | 当前 HTML |
+| `getText` | `() => string` | 纯文本（邮件 text/plain） |
+| `focus` | `() => void` | 聚焦 |
+| `clear` | `() => void` | 清空内容 |
+
+### 类型定义
+
+```ts
+export interface RichTextUploadResult {
+  fileUrl: string
+  fileId?: string
+  cid?: string
+  fileName?: string
+  fileSize?: number
+  [key: string]: unknown
+}
+
+export interface RichTextFontOption {
+  label: string
+  value: string
+}
+
+export interface RichTextFontSizeOption {
+  label: string
+  value: string
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-border-color` | `#d9d9d9` | 容器 / 表格边框 |
+| `--g3-radius` | `6px` | 容器圆角 |
+| `--g3-fill` | `rgba(0,0,0,.04)` | 工具条背景、表头背景 |
+| `--g3-color-primary` | `#18181b` | 激活态、链接、引用竖线颜色、聚焦时正文区的 2px 描边 |
+| `--g3-color-primary-soft` | 主色 12% | 按钮激活底、选中单元格底 |
+| `--g3-rich-text-toolbar-shadow-near` | `rgba(34,47,62,.1)` | 工具条投影近层（`0 2px 2px -2px`，`toolbar="bottom"` 时翻到上方） |
+| `--g3-rich-text-toolbar-shadow-far` | `rgba(34,47,62,.07)` | 工具条投影远层（`0 8px 8px -4px` 弥散） |
+
+## 实现说明
+
+- **选型 Tiptap**：MIT 协议、Vue 3 官方绑定（`@tiptap/vue-3`）、headless 架构便于贴合 G3 设计体系；相比 HugeRTE（TinyMCE 的 MIT fork）在 Vue 集成与 UI 定制上更契合组件库封装；
+- **不含代码块**：从 `starter-kit` 剔除了 Code / CodeBlock（ERP 场景不需要）；
+- **字体 / 字号 / 颜色 / 背景色**：用官方 `TextStyleKit`（内置 `setFontFamily` / `setFontSize` / `setColor` / `setBackgroundColor` 命令），行高保持关闭；颜色只写 `textStyle` 记号（`<span style="color: …">`），不引入额外的 mark；
+- **对齐**：官方 `@tiptap/extension-text-align`，只挂到 `heading` / `paragraph`，`alignments` 限左中右；面板里是 `toggleTextAlign`，点当前档位即取消；
+- **内容区即编辑区**：`minHeight` / `maxHeight` 作用在内容区上，可编辑区（`.tiptap`）用 `flex: 1 0 auto` 撑满 —— 内容短时整块都能点（点空白即聚焦、光标落到正文末尾），内容长时按内容高度撑开、由内容区滚动且不裁切。注意 EditorContent 会在内容区与可编辑区之间再插一层包裹 DOM，所以 `.tiptap` 上的 `min-height: inherit` 取的是那一层的值（恒为 0），撑不高可编辑区；
+- **聚焦高亮只给正文区**：编辑器获得焦点时（根节点 `:focus-within`），正文区四周亮起 2px 主色内描边，工具条不参与 —— 谁可编辑谁亮。用 `inset box-shadow` 而不是 `border`（不参与布局，聚焦不挤动正文），也不用 TinyMCE 那种 `::after` 覆盖层（正文区就是滚动容器，覆盖层会跟着正文滚走，而滚动容器的阴影不随内容滚动，天然钉在内容盒上）；
+- **工具条密度与「更多」**：按钮 32px（等于 `--g3-control-height`）+ 组内 4px 间隙，字体 / 字号与低频功能收进 `⋯` 菜单，自然宽度从 928px 降到 744px；`⋯` 用 `G3Dropdown` 现成的 `type: 'label'`（分组标题）/ `children`（子菜单）/ `shortcut` / `selected` 能力拼出来，与工具条共用同一份 `ToolButton` 定义，激活态与禁用态一致。菜单内容约 295px，靠 Dropdown 默认的视口上限（`calc(100vh - 48px)`）保证面板内部不出滚动条，不需要额外传 `menuMaxHeight`；
+- **图标分量**：16px 图标 + lucide 原生描边（16px 下约 1.33px），只把前景从 ghost 默认的 `text-2`（65%）提到 `text-1`（88%）。试过描边 2.5 与放大到 24px，都偏重；实测「发虚」的主因是浅灰前景，动颜色这一项性价比最高；
+- **视频自写 node**：Tiptap 官方无视频扩展，`VideoNode.ts` 定义了轻量 `video` block node，输出 `<video controls>` 标签；邮件场景由业务层决定是否降级为「封面图 + 附件」（编辑器不绑定邮件语义）；
+- **内联资源上报**：图片 / 视频上传后 `emit('upload-inline', result, kind)`，外层把 `result` 收集进 `inlines` 数组，与邮件「inline 附件」模型对齐（参考 Email-Vue 的 `@upload-image`）；
+- **依赖策略**：Tiptap 核心走 `peerDependencies`，扩展走 `dependencies`，不把编辑器全家桶强塞给所有 `@g3soft/ui` 使用者。

code/g3soft-libs/docs/content/ui/form/slider-captcha.md

@@ -0,0 +1,124 @@
+---
+title: SliderCaptcha 滑块验证码
+description: 按住滑块拖到行内结束端完成验证，支持键盘操作与 RTL
+---
+
+# SliderCaptcha 滑块验证码
+
+`SliderCaptcha` 是一个「按住滑块拖到最右端」的验证控件，`v-model` 绑 `boolean`，`true` 表示**已验证通过**。
+
+## 何时使用
+
+- 登录 / 注册 / 短信验证码等需要「一次人为停顿」的入口；
+- 轻量混淆脚本、降低误触强度的场景；
+- **不要**把它当安全边界：拖拽与键盘都能被脚本模拟，它能挡住的只是「顺手连点」，真正的风控要靠服务端。
+
+## 基础用法
+
+`v-model` 绑 `boolean`；`success` 在通过的那一刻触发一次，方便埋点或联动下一步。
+
+<demo vue="captcha/basic.vue" />
+
+`text` / `successText` 可覆盖语言包文案（默认取 `captcha` 语言包分组）。
+
+## 尺寸
+
+`size` 取 `small` / `medium` / `large`，高度分别跟随 `--g3-control-height-sm` / `--g3-control-height` / `--g3-control-height-lg`；手柄是正方形，宽度自动等于高度。
+
+<demo vue="captcha/sizes.vue" />
+
+## 与表单一起使用
+
+放进 `G3FormItem` 时，label 与校验交给表单，滑块只负责提供值。验证是有状态的，**每轮提交都要复位**：清掉绑定值后调 `resume()`，让用户重新拖一次。
+
+<demo vue="captcha/in-form.vue" />
+
+## 键盘与无障碍
+
+手柄是 `role="slider"`，带 `aria-valuemin` / `aria-valuemax` / `aria-valuenow`（0~100 的完成度）与 `aria-valuetext`（当前提示文案，通过后是成功文案），读屏可直接播报状态。
+
+| 按键 | 行为 |
+| --- | --- |
+| `Tab` | 聚焦手柄（未通过时才可聚焦，通过后 `tabindex="-1"`） |
+| `→` / `↑` | 沿屏幕上「向右」推进一档（行程的 1/10，最少 20px） |
+| `←` / `↓` | 回退一档 |
+| `Home` | 回到起点（不复位通过状态） |
+| `End` | 直达终点并通过验证 |
+
+`keyboard={false}` 可关掉键盘通道（只保留指针拖拽）。
+
+## RTL
+
+位置用逻辑属性 `inset-inline-start` 表达，镜像由 `dir` 自动完成：RTL 下手柄从**右侧**起步、向**左**拖到终点。指针位移按行内方向折算（`useDirection`），方向键的左右也随方向翻转 —— 对用户而言始终是「朝屏幕上那个方向推到底」。
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `boolean` | `false` | 双向绑定：是否已验证通过 |
+| `text` | `string` | 语言包 | 未通过时的提示文案 |
+| `successText` | `string` | 语言包 | 通过后的文案 |
+| `disabled` | `boolean` | `false` | 禁用态：不响应拖拽与键盘（样式不作整体半透明） |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 尺寸 |
+| `keyboard` | `boolean` | `true` | 是否支持键盘操作 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: boolean)` | 验证状态变化 |
+| `success` | `({ isPassing: true })` | 通过时触发一次 |
+| `start` | `(event: PointerEvent)` | 开始拖拽 |
+| `move` | `({ event, moveDistance, offset })` | 拖拽过程中触发（键盘操作不触发） |
+| `end` | `(event: PointerEvent)` | 拖拽结束（含取消） |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `text` | `{ isPassing }` | 覆盖提示文案 |
+| `action` | `{ isPassing }` | 覆盖手柄里的图标（默认 `ChevronsRight` / 通过后 `Check`，RTL 下由全库的图标镜像规则翻面） |
+
+### 实例方法
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `resume` | `() => void` | 复位到未通过状态（清绑定值 + 回弹动画），校验失败后调用 |
+
+### 类型定义
+
+```ts
+export type SliderCaptchaSize = 'small' | 'medium' | 'large'
+
+export interface SliderCaptchaProps {
+  modelValue?: boolean
+  text?: string
+  successText?: string
+  disabled?: boolean
+  size?: SliderCaptchaSize
+  keyboard?: boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-control-height` | `32px` | 默认高度（手柄宽 = 高度） |
+| `--g3-control-height-sm` | `24px` | `size="small"` 的高度 |
+| `--g3-control-height-lg` | `40px` | `size="large"` 的高度 |
+| `--g3-fill` | `rgba(0, 0, 0, 0.04)` | 轨道底色 |
+| `--g3-border-color` | `#d9d9d9` | 轨道描边 |
+| `--g3-color-success` | `hsl(144 57% 58%)` | 进度条与通过后的手柄图标色 |
+| `--g3-bg-container` | `#fff` | 手柄底色 |
+
+## 实现说明
+
+- **拖拽走 Pointer Events + `setPointerCapture`**（与 `bindDrag` / `bindResize` 同一套）：指针移出组件、触屏、手写笔都能正确收尾，不需要往 `document` 上挂全局监听；捕获失败的老环境会退化成「移出即松手」，不会卡住。
+- **跟手不加过渡**：拖拽期间进度条与手柄必须实时跟随指针，只有回弹 / `Home` / `End` 跳转才启用 300ms 过渡（`is-returning`），否则会有「拖不动」的手感。
+- **行程 = 容器宽 - 手柄宽**：每次交互开始时量一次 `getBoundingClientRect()`，因此容器宽度自适应、字体缩放、`size` 变化都不需要监听 resize。
+- **只有从「已通过」回退时才 `emit('update:modelValue', false)`**：中途松手的回弹不该对外重复报一次 `false`。
+- **文案不硬编码**：默认值来自语言包 `captcha.slide` / `captcha.verified` / `captcha.sliderLabel`。
+- 初始 `modelValue = true`（回填已通过状态）时，手柄在挂载后一帧落到行程末端，不会停在起点。