@blueking/chat-x 0.0.51 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/composables/use-observer-visible-list.md

@@ -0,0 +1,188 @@
+# useObserverVisibleList
+
+> 导入：`import { useObserverVisibleList } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useObserverVisibleList 根据 containerRef、itemRefs、gap、ComputedRef items 与可选 moreItemRef，用 ResizeObserver + 贪心算法得到 visibleItems。 依赖每项真实 offsetWidth，隐藏项需仍挂载于 DOM。返回 calculateVisibleMenuItems 供必要时手动触发。 ShortcutBtns 内部用于快捷指令溢出收入「更多」菜单。
+
+**关联**：shortcut-btns（唯一内置使用方）
+
+---
+
+# useObserverVisibleList 可见列表计算
+
+> **分类**：composable
+
+基于 `ResizeObserver` 的容器宽度感知组合式函数：遍历列表项的实际 `offsetWidth`，使用贪心算法计算在容器中能完整显示的项目子集，并为"更多"按钮动态预留空间。
+
+> 该 composable 仅在 `ShortcutBtns` 内部使用，**通常直接使用 `ShortcutBtns` 组件即可**。
+
+## 工作原理
+
+```
+calculateVisibleMenuItems():
+  await nextTick()
+  containerWidth = containerRef.value.offsetWidth
+
+  Set<T> list = {}
+  totalWidth = 0
+
+  for i in params.items.value:   // items 是 ComputedRef<T[]>，通过 .value 访问
+    itemRef = itemRefs.value[i]
+    buttonWidth = itemRef.offsetWidth
+    gap = list.size > 0 ? params.gap : 0          // 首项不加 gap
+    neededWidth = totalWidth + buttonWidth + gap
+    moreItemWidth = moreItemRef?.value?.$el?.offsetWidth ?? 0  // 动态读取
+
+    if neededWidth + params.gap + moreItemWidth <= containerWidth:
+      list.add(item)
+      totalWidth = neededWidth
+    else:
+      break  ← 立即中止，不跳过尝试后续项
+
+  visibleItems.value = Array.from(list)
+
+触发时机：
+  ├── onMounted：ResizeObserver.observe(containerRef) + nextTick 初始计算
+  ├── watch([itemRefs, moreItemRef])：DOM 引用更新时（nextTick 后）重新计算
+  └── onScopeDispose：ResizeObserver.disconnect()
+```
+
+## 渲染示例
+
+`ShortcutBtns` 内部使用 `useObserverVisibleList`，缩放浏览器窗口观察溢出效果：
+
+## 直接使用示例
+
+```vue
+<template>
+  <div
+    ref="containerRef"
+    class="btn-bar"
+  >
+    <!-- 所有项始终渲染，溢出项用 CSS 隐藏（offsetWidth 仍可读） -->
+    <template
+      v-for="(item, i) in items"
+      :key="item.id"
+    >
+      <button
+        :ref="el => setItemRef(el as HTMLElement, i)"
+        :class="['btn-item', { 'btn-item--hidden': !visibleItems.includes(item) }]"
+        @click="handleClick(item)"
+      >
+        {{ item.name }}
+      </button>
+    </template>
+
+    <!-- 更多按钮：仅在有隐藏项时显示 -->
+    <MoreBtn
+      v-show="hiddenItems.length > 0"
+      ref="moreBtnRef"
+      @click="showMoreMenu"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { computed, shallowRef, useTemplateRef } from 'vue';
+  import { useObserverVisibleList } from '@blueking/chat-x';
+
+  interface Item {
+    id: string;
+    name: string;
+  }
+
+  const containerRef = useTemplateRef<HTMLElement>('containerRef');
+  const moreBtnRef = useTemplateRef('moreBtnRef');
+
+  // 必须是 ShallowRef，由调用方维护（DOM 更新后写入）
+  const itemRefs = shallowRef<(HTMLElement | null)[]>([]);
+
+  const items = shallowRef<Item[]>([
+    { id: '1', name: '按钮 1' },
+    { id: '2', name: '按钮 2' },
+    { id: '3', name: '按钮 3' },
+    { id: '4', name: '按钮 4' },
+    { id: '5', name: '按钮 5' },
+  ]);
+
+  const { visibleItems, calculateVisibleMenuItems } = useObserverVisibleList<Item>(containerRef, itemRefs, {
+    gap: 4, // 按钮间距（必填）
+    items: computed(() => items.value), // 需传入 ComputedRef<T[]>，内部通过 .value 访问
+    moreItemRef: moreBtnRef, // 可选，动态读取"更多"按钮宽度
+  });
+
+  const hiddenItems = computed(() => items.value.filter(i => !visibleItems.value.includes(i)));
+
+  const setItemRef = (el: HTMLElement | null, index: number) => {
+    itemRefs.value[index] = el;
+  };
+
+  // items 变化时：重置 itemRefs（触发 watch → 重新计算）
+  watch(items, () => {
+    itemRefs.value = new Array(items.value.length).fill(null);
+  });
+</script>
+
+<style scoped>
+  .btn-bar {
+    display: flex;
+    gap: 4px;
+    overflow: hidden;
+  }
+
+  /* 隐藏项必须保持在 DOM 中（offsetWidth 才可读），用定位脱离文档流 */
+  .btn-item--hidden {
+    position: absolute;
+    visibility: hidden;
+    pointer-events: none;
+    opacity: 0;
+  }
+</style>
+```
+
+## API
+
+```typescript
+function useObserverVisibleList<T>(
+  containerRef: TemplateRef<HTMLElement>,
+  itemRefs: ShallowRef<(HTMLElement | null)[]>,
+  params: {
+    gap: number; // 必填，按钮间距（px）
+    items: ComputedRef<T[]>; // 必填，响应式项目数组（ComputedRef）
+    moreItemRef?: TemplateRef<InstanceType<typeof ShortcutBtn>>; // 可选，"更多"按钮引用
+  },
+): {
+  visibleItems: ShallowRef<T[]>;
+  calculateVisibleMenuItems: () => Promise<void>;
+};
+```
+
+### 参数说明
+
+| 参数                 | 类型                                  | 必填 | 说明                                                                                                        |
+| -------------------- | ------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------- |
+| `containerRef`       | `TemplateRef<HTMLElement>`            | 是   | 容器 DOM 引用；`ResizeObserver` 监听此元素宽度变化                                                          |
+| `itemRefs`           | `ShallowRef<(HTMLElement \| null)[]>` | 是   | 各项 DOM 引用数组；`watch` 监听其变化触发重新计算                                                           |
+| `params.gap`         | `number`                              | 是   | 相邻按钮间距（px）；首项不加 gap                                                                            |
+| `params.items`       | `ComputedRef<T[]>`                    | 是   | **响应式**项目数组，需传入 `ComputedRef`（如 `computed(() => list.value)`）；内部通过 `.value` 访问最新数据 |
+| `params.moreItemRef` | `TemplateRef<ShortcutBtn>`            | 否   | "更多"按钮引用；每次计算从 `$el.offsetWidth` 动态读取宽度；缺省时按 0 计算                                  |
+
+### 返回值
+
+| 属性名                      | 类型                  | 说明                                                               |
+| --------------------------- | --------------------- | ------------------------------------------------------------------ |
+| `visibleItems`              | `ShallowRef<T[]>`     | 当前能完整放入容器的项目子集（引用与 `params.items` 中的对象一致） |
+| `calculateVisibleMenuItems` | `() => Promise<void>` | 手动触发计算（内部有 `await nextTick()`）；一般无需调用            |
+
+## 注意事项
+
+1. **`items` 必须为 `ComputedRef`**：`params.items` 现在接受 `ComputedRef<T[]>` 类型，内部通过 `.value` 读取最新数据。建议使用 `computed(() => props.shortcuts)` 包装后传入，确保 items 变化时计算逻辑能访问到最新数据。注意 `itemRefs` 的重置仍需在外部维护（`itemRefs.value = new Array(items.value.length).fill(null)`），以触发 `watch([itemRefs, moreItemRef])` 重新计算
+2. **隐藏项必须留在 DOM**：算法依赖 `itemRef.offsetWidth` 读取每项实际宽度；使用 `position: absolute; visibility: hidden` 隐藏而非 `display: none`
+3. **算法贪心且单调**：遇到第一个放不下的项就立即 `break`，不跳过继续尝试后续较短的项
+4. **`moreItemRef` 宽度动态读取**：每次计算循环中实时读取 `$el.offsetWidth`，宽度可以随内容变化（如显示隐藏数量文字时）
+5. **`ResizeObserver` 仅在 `onMounted` 时绑定一次**：若 `containerRef.value` 在挂载时为 `null`，则不会监听容器宽度变化
+6. **`moreItemRef` 类型限定为 `ShortcutBtn`**：强依赖内部 `$el` expose，若用于其他组件需确保 expose 了 `$el`
+
+## 关联组件
+
+- [ShortcutBtns](../components/input/shortcut-btns.md) — 快捷指令条与「更多」

package/skills/blueking-chat-x/references/composables/use-parent-scrolling.md

@@ -0,0 +1,46 @@
+# useParentScrolling
+
+> 导入：`import { useParentScrolling } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useParentScrolling(domRef) 在挂载后通过 getScrollParent 找到最近可滚动祖先，监听 scroll 与 scrollend，返回 isScrolling 与 scrollParent。 scroll 时将 isScrolling 置 true，300ms 无滚动或 scrollend 时置 false，适合滚动时隐藏浮层等交互。getScrollParent 可单独导出使用。 当前源码无组件内引用，供业务或后续浮层组件按需集成。
+
+---
+
+# useParentScrolling 父容器滚动监听
+
+> **分类**：composable
+
+向上递归查找**最近可滚动祖先**，监听其 `scroll` / `scrollend` 事件，提供 `isScrolling` 状态。常用于滚动时自动关闭浮层、禁用交互等场景。
+
+同时导出辅助函数 `getScrollParent`，可单独使用。
+
+## 工作原理
+
+```
+getScrollParent(node):
+  ├── !node → null
+  ├── !(node instanceof HTMLElement) → getScrollParent(parentElement) 或 document.body
+  ├── scrollHeight > clientHeight
+  │     && overflowY in ['scroll', 'auto', 'overlay'] → return node（找到）
+  └── else → getScrollParent(parentElement) 或 document.body（fallback）
+
+useParentScrolling(domRef):
+  onMounted:
+    scrollParent = getScrollParent(toValue(domRef))
+    removeEventListener（防御性清理）
+    addEventListener('scroll', handleScroll)    ← 非 passive
+    addEventListener('scrollend', handleScrollEnd)
+
+  handleScroll:
+    isScrolling = true
+    clearTimeout(timer)
+    timer = setTimeout(() => isScrolling = false, 300)  ← 300ms 无滚动后重置
+
+  handleScrollEnd:
+    isScrolling = false  ← 原生 scrollend 事件立即重置（浏览器兼容性见下）
+
+  onScopeDispose:
+    removeEventListener（自动清理）
+```
+
+## 渲染示例

package/skills/blueking-chat-x/references/directives/index.md

@@ -0,0 +1,61 @@
+# 指令总览
+
+`@blueking/chat-x` 目前提供以下 Vue 自定义指令：
+
+---
+
+# 指令总览
+
+`@blueking/chat-x` 目前提供以下 Vue 自定义指令：
+
+| 指令              | 说明                       | 关键特性                                                                | 文档                       |
+| ----------------- | -------------------------- | ----------------------------------------------------------------------- | -------------------------- |
+| `v-overflow-tips` | 水平溢出时悬浮显示完整内容 | `IntersectionObserver` 懒绑定，按需创建 Tippy 实例，`onHidden` 自动销毁 | [查看](./overflow-tips.md) |
+
+## 引入方式
+
+### 组件内局部使用（推荐）
+
+```vue
+<template>
+  <div
+    v-overflow-tips
+    class="ellipsis"
+  >
+    这是一段很长的文本，超出容器宽度时悬浮显示完整内容
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+</script>
+
+<style scoped>
+  .ellipsis {
+    width: 200px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>
+```
+
+### 全局注册
+
+```typescript
+import { createApp } from 'vue';
+import { OverflowTips } from '@blueking/chat-x';
+
+const app = createApp(App);
+app.directive('overflow-tips', OverflowTips);
+app.mount('#app');
+```
+
+全局注册后，所有组件可直接使用 `v-overflow-tips`，无需单独引入。
+
+## 注意事项
+
+- **仅检测水平溢出**：通过 `scrollWidth > clientWidth` 判断，多行 `-webkit-line-clamp` 截断不会触发 tooltip
+- **无 `update` 钩子**：`binding.value` 运行时变化（如 `disabled` 切换）仅在下次 `mouseenter` 生效
+- **勿覆盖 `onHidden`**：指令依赖 `onHidden` 回调自动销毁 Tippy 实例，覆盖会导致内存泄漏
+- **默认主题**：`'ai-chat-box'`（组件库内置），替换为其他主题需引入对应 Tippy CSS

package/skills/blueking-chat-x/references/directives/overflow-tips.md

@@ -0,0 +1,205 @@
+# OverflowTips
+
+> 导入：`import { OverflowTips } from '@blueking/chat-x'` ｜ since 1.0.0
+
+v-overflow-tips 在元素水平溢出（scrollWidth > clientWidth）时于 mouseenter 懒创建 Tippy，展示完整文本或自定义 text/content。 结合 IntersectionObserver 仅在可见时绑定悬停；隐藏时销毁实例。指令值为 Partial<TippyProps> 与 disabled 等。 DescPanel、ExecutionSummary、ToolcallRender、InputMenuPanel 等用于标题或列表溢出提示。
+
+**关联**：desc-panel（工具描述面板溢出）、execution-summary（执行摘要标签溢出）、toolcall-render（工具标题行溢出）、input-menu-panel（菜单条目名称溢出）
+
+---
+
+# OverflowTips 溢出提示指令
+
+> **分类**：directive
+
+当元素文本**水平溢出**（`scrollWidth > clientWidth`）时，鼠标悬停自动弹出 Tippy tooltip 显示完整内容；未溢出时不创建实例，零性能损耗。
+
+## 工作原理
+
+```
+元素挂载
+   │
+   ▼
+IntersectionObserver 监听可见性（threshold=0.1）
+   │
+   ├─ 可见 → 绑定 mouseenter / mouseleave
+   └─ 不可见 → 解绑 mouseenter / mouseleave
+                    │
+                    ▼ mouseenter 触发
+              scrollWidth > clientWidth ?
+               │               │
+              否               是
+               │               │
+            直接返回      创建 Tippy 实例
+                          [trigger: mouseenter]
+                          [delay: 300ms, 0ms]
+                               │
+                    ┌──────────┴──────────┐
+                  onShow              onHidden
+              再次校验溢出         destroy() 销毁实例
+              false → 取消          instance = undefined
+```
+
+## 基础用法
+
+文本未溢出时不会弹出 tooltip；只有超出容器宽度才触发。元素需自行设置省略号 CSS。
+
+```vue
+<template>
+  <div
+    v-overflow-tips
+    class="ellipsis"
+  >
+    这是一段很长的文本内容，会触发溢出省略效果并弹出 tooltip 提示完整内容
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+</script>
+
+<style scoped>
+  .ellipsis {
+    width: 240px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>
+```
+
+## 自定义提示内容
+
+通过 `text` 或 `content`（别名）指定 tooltip 显示内容，优先级：`text > content > el.innerText`。
+
+```vue
+<template>
+  <div
+    v-overflow-tips="{ text: '自定义 tooltip 内容：完整的蓝鲸智云 AI 小鲸组件使用说明' }"
+    class="ellipsis"
+  >
+    悬浮查看自定义 tooltip 内容（与元素 innerText 不同）
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+</script>
+```
+
+## 控制 placement 和禁用
+
+`placement` 默认 `'auto'`（Tippy 自动选择最优方向）；`disabled: true` 完全跳过 tooltip 创建。
+
+```vue
+<template>
+  <div
+    v-overflow-tips="{ placement: 'bottom', disabled: isDisabled }"
+    class="ellipsis"
+  >
+    可以切换弹出方向或禁用 tooltip
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { OverflowTips as vOverflowTips } from '@blueking/chat-x';
+
+  const isDisabled = ref(false);
+</script>
+```
+
+## API
+
+### 指令值类型
+
+```typescript
+type OverflowTipsValue = Partial<TippyProps> & {
+  disabled?: boolean; // 禁用 tooltip
+  text?: string; // 自定义提示内容（优先级最高）
+  content?: string; // text 的别名
+};
+```
+
+指令值是 `Partial<TippyProps>` 的超集，所有 Tippy.js 配置均可透传，但覆盖 `onHidden` 会导致实例无法自动销毁。
+
+### 常用配置项
+
+| 属性        | 类型                         | 默认值          | 说明                                            |
+| ----------- | ---------------------------- | --------------- | ----------------------------------------------- |
+| `text`      | `string`                     | `el.innerText`  | 自定义提示内容，优先级最高                      |
+| `content`   | `string`                     | `el.innerText`  | `text` 的别名，`text` 存在时忽略                |
+| `placement` | `Placement`                  | `'auto'`        | tooltip 弹出方向，支持所有 Tippy placement 值   |
+| `disabled`  | `boolean`                    | `false`         | `true` 时跳过 tooltip 创建，mouseenter 直接返回 |
+| `delay`     | `number \| [number, number]` | `[300, 0]`      | 显示/隐藏延迟（ms）                             |
+| `theme`     | `string`                     | `'ai-chat-box'` | Tippy 主题，默认使用组件库内置主题              |
+
+### 其他 Tippy.js 配置
+
+可直接传入任何 `tippy.js` 的 `Props`，如 `arrow`、`maxWidth`、`offset` 等，会覆盖上述默认值（除内部的 `trigger`、`onShow`、`onHidden` 逻辑外）。
+
+> **注意**：不要覆盖 `onHidden`，否则 Tippy 实例无法在隐藏后自动销毁，导致内存泄漏。
+
+## 溢出检测规则
+
+指令通过 `scrollWidth > clientWidth` 判断**水平溢出**：
+
+- 仅检测水平方向，多行文本的垂直截断（`-webkit-line-clamp`）无法被检测到
+- `onShow` 会在 tooltip 即将显示时**再次校验**溢出状态，动态缩放容器后同样有效
+- 若两次校验均未溢出，tooltip 不会弹出
+
+## 生命周期细节
+
+| 时机                | 行为                                                                  |
+| ------------------- | --------------------------------------------------------------------- |
+| `mounted`           | 创建 `IntersectionObserver`（阈值 10%），注册 `unObserverFunc` 到元素 |
+| 元素进入视口        | 绑定 `mouseenter` / `mouseleave` 事件                                 |
+| 元素离开视口        | 解绑 `mouseenter` / `mouseleave`                                      |
+| `mouseenter` + 溢出 | 创建 Tippy 实例；`DelayMs+16ms` 后补偿首次不显示的 bug                |
+| `onHidden`          | 销毁实例（`destroy()`），`instance = undefined`                       |
+| `beforeUnmount`     | 解绑所有事件，调用 `unObserverFunc` 停止 Observer                     |
+
+> **无 `update` 钩子**：`binding.value` 在运行时变化（如 `disabled` 切换）不会更新已创建的 Tippy 实例，只影响下一次 `mouseenter` 时的行为。
+
+## 样式要求
+
+指令不会自动设置省略号 CSS，需在元素上手动添加：
+
+**单行截断**：
+
+```css
+.ellipsis {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+```
+
+**多行截断（`-webkit-line-clamp`）**：
+
+```css
+/* 注意：多行截断时 scrollWidth <= clientWidth，tooltip 不会触发 */
+.ellipsis-multiline {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+> 多行截断通过 `-webkit-line-clamp` 实现，`scrollWidth` 不变，指令**无法检测**此类溢出，tooltip 不会弹出。
+
+## 注意事项
+
+1. **仅检测水平溢出**：`scrollWidth > clientWidth`，多行 `line-clamp` 溢出无效
+2. **无 `update` 钩子**：`disabled` 等状态变化仅在下次 `mouseenter` 生效
+3. **勿覆盖 `onHidden`**：会导致 Tippy 实例无法自动销毁
+4. **默认主题**：`'ai-chat-box'` 是组件库内置主题，替换为其他主题需引入对应 CSS
+5. **事件冒泡**：`mouseenter` 内调用了 `stopPropagation()`，父元素不会收到该事件
+
+## 关联组件
+
+- [DescPanel](../components/rendering/desc-panel) — 描述区溢出
+- [ExecutionSummary](../components/agent/execution-summary) — 侧栏摘要标签
+- [ToolcallRender](../components/agent/toolcall-render) — 工具调用标题
+- [InputMenuPanel](../components/input/input-menu-panel) — 菜单条目名称溢出