@blueking/chat-x 0.0.5 → 0.0.7

package/dist/mcp/generated/docs/use-observer-visible-list.md

@@ -0,0 +1,189 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useObserverVisibleList 根据 containerRef、itemRefs、gap、ComputedRef items 与可选 moreItemRef，用 ResizeObserver + 贪心算法得到 visibleItems。 依赖每项真实 offsetWidth，隐藏项需仍挂载于 DOM。返回 calculateVisibleMenuItems 供必要时手动触发。 ShortcutBtns 内部用于快捷指令溢出收入「更多」菜单。
+
+### 关联组件
+- **shortcut-btns** — 唯一内置使用方
+
+---
+<!-- FULL DOC -->
+
+# 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/molecular/shortcut-btns.md) — 快捷指令条与「更多」

package/dist/mcp/generated/docs/use-parent-scrolling.md

@@ -0,0 +1,46 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useParentScrolling(domRef) 在挂载后通过 getScrollParent 找到最近可滚动祖先，监听 scroll 与 scrollend，返回 isScrolling 与 scrollParent。 scroll 时将 isScrolling 置 true，300ms 无滚动或 scrollend 时置 false，适合滚动时隐藏浮层等交互。getScrollParent 可单独导出使用。 当前源码无组件内引用，供业务或后续浮层组件按需集成。
+
+---
+<!-- FULL DOC -->
+
+# 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/dist/mcp/generated/docs/user-feedback.md

@@ -0,0 +1,229 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+UserFeedback 在点赞或踩之后展示原因收集面板：多选预设标签、补充说明与异步加载原因列表（骨架屏）。 由 MessageTools 在 like/unlike 流程中挂载，提交后向父级回传原因列表与备注。
+
+### 关联组件
+- **message-tools** — 点赞/踩操作触发并收集反馈
+
+---
+<!-- FULL DOC -->
+
+# MessageUserFeedback 用户反馈
+
+> **层级**：分子组件 · **功能域**：工具与反馈
+
+AI 消息点赞/踩后收集用户具体反馈原因的弹出面板。支持多选预设原因标签、补充文字说明（textarea）、异步加载原因列表（骨架屏）。
+
+> **通常不需要直接使用。** `MessageTools` 在用户点击 `like`/`unlike` 工具按钮时，会通过内置 Tippy 弹出层自动呈现本组件，并驱动 `loading` 和 `reasonList`。
+
+## 组件结构
+
+```
+.ai-user-feedback（width: 400px，padding: 16px，gap: 16px）
+├── .ai-feedback-title（font-size: 16px，color: #313238）
+│     props.title
+│
+├── .ai-feedback-reason-list（flex-wrap，gap: 4px）
+│     loading=true  → 8 × .reason-item.ai-skeleton-element（每项 width: 70px）
+│     loading=false → v-for reasonList → .reason-item
+│                       is-active（已选）：color #1768ef，bg #e1ecff
+│                       :hover        ：同上（与 is-active 共享样式）
+│
+├── .ai-feedback-other
+│     bkui-vue Input（type=textarea，rows=3，placeholder="说出您的想法"）
+│     → v-model 绑定内部 shallowRef otherReason
+│
+└── .ai-feedback-footer（justify-content: flex-end，gap: 8px）
+      Button primary "提交"（width: 64px，disabled：selectedReasons 空且 otherReason 空）
+      Button default "取消"（width: 64px）
+```
+
+## 基础用法
+
+```vue
+<template>
+  <MessageUserFeedback
+    title="什么原因让你满意？"
+    :reason-list="reasonList"
+    @submit="handleSubmit"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageUserFeedback } from '@blueking/chat-x';
+
+  const reasonList = ['回答准确', '信息全面', '表达清晰', '解决了问题', '示例恰当'];
+
+  const handleSubmit = (selectedReasons: string[], otherReason: string) => {
+    // selectedReasons: 当前已勾选的原因（提交后组件不自动清空）
+    // otherReason: textarea 中的补充说明（可为空字符串）
+    console.log('已选原因:', selectedReasons, '补充说明:', otherReason);
+  };
+
+  const handleCancel = () => {
+    // cancel 触发前组件已清空 selectedReasons 和 otherReason
+    console.log('用户取消了反馈');
+  };
+</script>
+```
+
+**满意反馈**
+
+**不满意反馈**
+
+## 加载状态
+
+原因列表通常需要异步获取，将 `loading` 设为 `true` 时渲染 **8 个**骨架屏占位块（固定数量，与 `reasonList` 无关），数据就绪后切换为 `false`：
+
+```vue
+<template>
+  <MessageUserFeedback
+    title="什么原因让你满意？"
+    :reason-list="reasonList"
+    :loading="isLoading"
+    @submit="handleSubmit"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { MessageUserFeedback } from '@blueking/chat-x';
+
+  const isLoading = ref(true);
+  const reasonList = ref<string[]>([]);
+
+  async function fetchReasons() {
+    isLoading.value = true;
+    try {
+      reasonList.value = await fetchFeedbackReasons();
+    } finally {
+      isLoading.value = false;
+    }
+  }
+</script>
+```
+
+**骨架屏效果**
+
+## 交互说明
+
+| 操作         | 行为说明                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------- |
+| 点击原因标签 | **多选**，高亮（`is-active`）；再次点击取消选中；hover 效果与选中态相同                                       |
+| 填写补充说明 | 可选；不选任何标签时，仅有补充说明文本也可解锁提交按钮                                                        |
+| 点击提交     | `selectedReasons.length === 0 && otherReason === ''` 时禁用；点击后触发 `submit` 事件，**组件不自动清空状态** |
+| 点击取消     | 先将 `selectedReasons` 和 `otherReason` 清空（两者均重置），再触发 `cancel` 事件                              |
+
+> **提交与取消的状态差异**：点击"提交"后内部 `selectedReasons` / `otherReason` **不重置**，由父组件决定后续行为（如关闭弹层）；点击"取消"则**立即重置**两者，再触发事件。
+
+## 与 MessageTools 配合使用
+
+`MessageUserFeedback` 在实际场景中由 `MessageTools` 驱动，整体流程：
+
+```
+用户点击 like / unlike
+    ↓
+MessageTools 内部：loading=true，弹出反馈面板（骨架屏）
+    ↓
+调用 onAction(tool) → 返回 string[]（支持 async）
+    ↓
+loading=false，展示原因标签列表
+    ↓
+用户选择原因 → 点击提交
+    ↓
+触发 onAgentFeedback(tool, messages, reasonList, otherReason)
+```
+
+```vue
+<template>
+  <MessageContainer
+    :messages="messages"
+    :on-agent-action="handleAgentAction"
+    :on-agent-feedback="handleFeedback"
+  />
+</template>
+
+<script setup lang="ts">
+  import { MessageContainer, type IToolBtn, type Message } from '@blueking/chat-x';
+
+  const messages: Message[] = [
+    /* ... */
+  ];
+
+  // 点击 like/unlike 时调用，返回原因列表（支持异步）
+  const handleAgentAction = async (tool: IToolBtn): Promise<string[]> => {
+    if (tool.id === 'like') {
+      return ['回答准确', '信息全面', '表达清晰', '解决了问题'];
+    }
+    if (tool.id === 'unlike') {
+      return ['信息错误', '回答不相关', '解释不清楚', '没有解决问题'];
+    }
+    return [];
+  };
+
+  // 用户提交反馈后触发
+  const handleFeedback = (tool: IToolBtn, messages: Message[], reasonList: string[], otherReason: string) => {
+    console.log(`${tool.id} 反馈:`, { reasonList, otherReason });
+    // 上报到后端
+  };
+</script>
+```
+
+若需在自定义位置独立使用，可配合 `vue-tippy`：
+
+```vue
+<template>
+  <Tippy
+    :arrow="false"
+    interactive
+    trigger="click"
+    theme="ai-chat-box-light light"
+    :offset="[0, 6]"
+    :append-to="() => document.body"
+  >
+    <button>👍 点赞</button>
+    <template #content>
+      <MessageUserFeedback
+        title="什么原因让你满意？"
+        :reason-list="reasonList"
+        :loading="isLoading"
+        @submit="handleSubmit"
+        @cancel="handleCancel"
+      />
+    </template>
+  </Tippy>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名     | 类型       | 必填 | 默认值  | 说明                                                   |
+| ---------- | ---------- | ---- | ------- | ------------------------------------------------------ |
+| title      | `string`   | ✓    | —       | 面板标题文本                                           |
+| reasonList | `string[]` | ✓    | —       | 预设原因标签列表；`loading=true` 时列表不渲染          |
+| loading    | `boolean`  | —    | `false` | `true` 时显示 8 个骨架屏占位块，隐藏 `reasonList` 内容 |
+
+### Events
+
+| 事件名 | 参数签名                                      | 触发时机                                                    |
+| ------ | --------------------------------------------- | ----------------------------------------------------------- |
+| submit | `(reasonList: string[], otherReason: string)` | 点击提交按钮时（至少一项原因或补充说明不为空）              |
+| cancel | —                                             | 点击取消按钮时（内部已重置 selectedReasons 和 otherReason） |
+
+### 内部状态
+
+以下为组件内部 `shallowRef` 状态，不暴露为 props/emits：
+
+| 状态名          | 类型       | 说明                                        |
+| --------------- | ---------- | ------------------------------------------- |
+| selectedReasons | `string[]` | 当前已选原因列表；取消时重置，提交时不重置  |
+| otherReason     | `string`   | textarea 补充说明；取消时重置，提交时不重置 |
+
+## 关联组件
+
+- [MessageTools](./message-tools.md) — 点赞/踩入口与反馈联动