@blueking/chat-x 0.0.51-beta.2 → 0.0.51-beta.3

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

@@ -1,188 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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/theme/theme.md

@@ -1,431 +0,0 @@
-# 主题配置
-
-> since 1.0.0
-
-说明通过 SCSS 变量（尺寸、颜色、z-index）、字号主题 CSS 变量（data-ai-size 切换 small/normal）与 CSS 类覆盖自定义主题。 ChatContainer.size 控制根节点 data-ai-size；浮层同步 document.body.dataset.aiSize。含渐变边框 mixin、骨架屏类 ai-skeleton-element 等。
-
-**关联**：chat-container（整体布局与侧栏）、chat-input（输入区与渐变边框）、message-container（消息区样式上下文）
-
----
-
-# 主题配置
-
-> **分类**：theme
-
-`@blueking/chat-x` 使用 SCSS 变量和 CSS 类来控制样式，支持通过覆盖变量或样式来自定义主题。
-
-## 样式引入
-
-组件库的样式会在引入组件时自动加载，无需单独引入：
-
-```typescript
-// 引入组件时会自动引入样式
-import { ChatInput, MessageContainer } from '@blueking/chat-x';
-```
-
-## 字号主题
-
-组件库通过根节点 `[data-ai-size]` 切换两档字号主题，内部组件统一引用 CSS 变量（均带兜底值，无 provider 时退回 `small`）。
-
-### 切换方式
-
-| 方式 | 说明 |
-| ---- | ---- |
-| `ChatContainer` 的 `size` prop | 推荐。根节点 `.ai-chat-container` 设置 `data-ai-size`；同时通过 `useGlobalConfig` 注入 `size` 供逻辑层读取 |
-| 手动设置 `data-ai-size` | 在任意祖先元素上设置 `data-ai-size="small"` 或 `data-ai-size="normal"`，后代继承 CSS 变量 |
-| `document.body.dataset.aiSize` | `ChatContainer` 会自动同步，供 Tippy / Teleport 等挂载到 `body` 的浮层继承字号变量；容器卸载时清理 |
-
-```vue
-<template>
-  <ChatContainer v-model="input" :messages="messages" size="normal" />
-</template>
-```
-
-### CSS 变量
-
-定义于 `src/styles/size-theme.scss`，随 `global.scss` 自动引入：
-
-| 变量名 | `small`（默认） | `normal` | 说明 |
-| ------ | --------------- | -------- | ---- |
-| `--ai-font-size` | `12px` | `14px` | 基准字号 |
-| `--ai-line-height` | `20px` | `24px` | 标准行高 |
-| `--ai-line-height-compact` | `20px` | `22px` | 紧凑行高 |
-| `--ai-spacing-comfortable` | `8px` | `12px` | 舒适间距（如消息气泡水平内边距） |
-| `--ai-icon-size` | `16px` | `20px` | 标准图标尺寸 |
-| `--ai-icon-size-sm` | `16px` | `18px` | 小号图标尺寸 |
-
-组件样式中统一使用 `var(--ai-font-size, 12px)` 等形式引用，保证无 `data-ai-size` 时仍退回 small 档位。
-
-```scss
-// 示例：在自定义样式中复用字号主题变量
-.my-custom-panel {
-  font-size: var(--ai-font-size, 12px);
-  line-height: var(--ai-line-height, 20px);
-}
-```
-
-### 骨架屏
-
-全局类 `.ai-skeleton-element` 用于加载占位（如 FlowAgent 节点详情、UserFeedback 原因列表）。可通过 `.skeleton-element-lg` 修饰尺寸。详见各业务组件文档中的加载态说明。
-
-## SCSS 变量
-
-组件库使用以下 SCSS 变量，可以在项目中覆盖：
-
-### 尺寸变量
-
-```scss
-// 输入框尺寸
-$chat-input-min-width: 350px;
-$chat-input-max-width: 700px;
-```
-
-### 颜色变量
-
-```scss
-// 主题色
-$primary-color: #3a84ff;
-
-// 文字颜色
-$text-color-primary: #313238;
-$text-color-secondary: #4d4f56;
-$text-color-placeholder: #979ba5;
-
-// 背景色
-$bg-color-white: #fff;
-$bg-color-light: #f5f7fa;
-$bg-color-hover: #f0f1f5;
-
-// 边框色
-$border-color: #dcdee5;
-$border-color-hover: #c4c6cc;
-```
-
-### Z-Index 变量
-
-组件库使用分层的 z-index 管理：
-
-```scss
-// 基础 z-index
-$chat-z-index: 9999;
-
-// 编辑器 z-index
-$editor-z-index: $chat-z-index + 1;
-
-// 编辑器菜单 z-index
-$editor-menu-z-index: $editor-z-index + 1;
-
-// 快捷指令菜单 z-index
-$shortcut-menu-z-index: $editor-menu-z-index + 1;
-
-// 划选弹窗 z-index
-$selection-z-index: $shortcut-menu-z-index + 1;
-```
-
-## CSS 类覆盖
-
-### 输入框样式
-
-```scss
-// 覆盖输入框容器样式
-.ai-chat-input-container {
-  .chat-input {
-    min-height: 120px; // 自定义最小高度
-    max-height: 250px; // 自定义最大高度
-    background: #fafafa; // 自定义背景色
-
-    // 覆盖边框渐变
-    &::before {
-      background: linear-gradient(180deg, #ff6b6b, #ff8e53);
-    }
-  }
-}
-```
-
-### 消息样式
-
-```scss
-// 用户消息样式
-.ai-user-message {
-  &-content {
-    background-color: #d4edda; // 自定义背景色
-    border-radius: 8px;
-  }
-}
-
-// AI 消息样式
-.assistant-message {
-  &-content {
-    background-color: #f8f9fa;
-    border-left: 3px solid #3a84ff;
-    padding-left: 12px;
-  }
-}
-```
-
-### 快捷指令按钮样式
-
-```scss
-// 快捷指令按钮
-.ai-shortcut-btns {
-  &-item {
-    background: linear-gradient(135deg, #667eea, #764ba2);
-    color: #fff;
-
-    &:hover {
-      transform: translateY(-2px);
-      box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
-    }
-
-    // 移除默认渐变边框
-    &::before {
-      display: none;
-    }
-  }
-}
-```
-
-### 消息工具栏样式
-
-```scss
-// 工具按钮
-.tool-btn {
-  width: 24px;
-  height: 24px;
-  font-size: 16px;
-
-  &:hover {
-    background-color: #e1ecff;
-    color: #3a84ff;
-  }
-}
-```
-
-### Markdown 内容样式
-
-```scss
-// Markdown 内容
-.ai-markdown-content {
-  .ai-markdown-body {
-    font-size: 14px;
-    line-height: 1.6;
-
-    // 代码块样式
-    pre code.hljs {
-      background-color: #1e1e1e;
-      border-radius: 8px;
-    }
-
-    // 表格样式
-    table {
-      border-collapse: collapse;
-
-      th,
-      td {
-        border: 1px solid #dcdee5;
-        padding: 8px 12px;
-      }
-
-      th {
-        background-color: #f5f7fa;
-      }
-    }
-  }
-}
-```
-
-## 主题切换示例
-
-### 暗色主题
-
-```scss
-// 暗色主题变量
-.dark-theme {
-  // 输入框
-  .ai-chat-input-container .chat-input {
-    background: #2d2d2d;
-
-    &::before {
-      background: linear-gradient(180deg, #4a90d9, #357abd);
-    }
-  }
-
-  // 用户消息
-  .ai-user-message-content {
-    background-color: #3d5a80;
-    color: #fff;
-  }
-
-  // AI 消息
-  .assistant-message {
-    color: #e0e0e0;
-  }
-
-  // Markdown 内容
-  .ai-markdown-content .ai-markdown-body {
-    color: #e0e0e0;
-
-    h1,
-    h2,
-    h3,
-    h4,
-    h5,
-    h6 {
-      color: #fff;
-    }
-
-    a {
-      color: #6cb2eb;
-    }
-
-    code {
-      background-color: #3d3d3d;
-      color: #e0e0e0;
-    }
-  }
-
-  // 快捷指令
-  .ai-shortcut-btns-item {
-    background: #3d3d3d;
-    color: #e0e0e0;
-
-    &::before {
-      background: linear-gradient(105deg, #4a90d940, #9b59b640);
-    }
-  }
-
-  // 工具按钮
-  .tool-btn {
-    color: #9e9e9e;
-
-    &:hover {
-      background-color: #424242;
-      color: #fff;
-    }
-  }
-}
-```
-
-### 使用暗色主题
-
-```vue
-<template>
-  <div :class="{ 'dark-theme': isDark }">
-    <ChatInput v-model="input" />
-    <MessageContainer :messages="messages" />
-  </div>
-</template>
-
-<script setup lang="ts">
-  import { ref } from 'vue';
-  import { ChatInput, MessageContainer } from '@blueking/chat-x';
-
-  const isDark = ref(false);
-  const input = ref('');
-  const messages = ref([]);
-</script>
-```
-
-## 渐变边框
-
-组件库使用 CSS mask 实现渐变边框效果：
-
-```scss
-// 渐变边框 mixin
-@mixin linear-gradient-border($angle: 105deg, $start-color: #235dfa40, $end-color: #bc81ef40) {
-  content: '';
-  position: absolute;
-  inset: 0;
-  padding: 1px;
-  background: linear-gradient($angle, $start-color, $end-color);
-  mask:
-    linear-gradient(#fff 0 0) content-box,
-    linear-gradient(#fff 0 0);
-  mask-composite: xor;
-  mask-composite: exclude;
-  border-radius: inherit;
-  pointer-events: none;
-}
-```
-
-使用示例：
-
-```scss
-.custom-card {
-  position: relative;
-  border-radius: 8px;
-
-  &::before {
-    @include linear-gradient-border(180deg, #6cbaff, #3a84ff);
-  }
-}
-```
-
-## 动画效果
-
-### 淡入动画
-
-```scss
-// 全局淡入动画
-@keyframes ai-markdown-fade-in {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}
-
-.ai-blueking-markdown-fade-in {
-  animation: ai-markdown-fade-in 0.2s ease-out forwards;
-}
-```
-
-### 弹窗过渡
-
-```scss
-// 选择弹窗过渡
-.ai-fade-enter-active,
-.ai-fade-leave-active {
-  transition:
-    opacity 0.2s ease,
-    transform 0.2s ease;
-}
-
-.ai-fade-enter-from,
-.ai-fade-leave-to {
-  opacity: 0;
-  transform: translateY(4px);
-}
-```
-
-## 响应式设计
-
-```scss
-// 移动端适配
-@media (max-width: 768px) {
-  .ai-chat-input-container .chat-input {
-    min-width: 100%;
-    max-width: 100%;
-  }
-
-  .ai-shortcut-btns {
-    min-width: 100%;
-    max-width: 100%;
-  }
-}
-```
-
-## 注意事项
-
-1. **样式优先级**：覆盖样式时可能需要使用更高优先级的选择器
-2. **变量位置**：SCSS 变量需要在组件样式之前定义
-3. **构建配置**：确保项目配置支持 SCSS 处理
-4. **组件隔离**：使用 scoped 样式时，深度选择器 `::v-deep` 或 `:deep()` 可能需要
-
-## 关联组件
-
-- [ChatContainer](../components/setup/chat-container) — 布局与字号主题根节点（`size` prop）
-- [useGlobalConfig](../composables/use-global-config) — 注入 `size` 供后代读取
-- [ChatInput](../components/input/chat-input) — 输入区变量与类名
-- [MessageContainer](../components/setup/message-container) — 消息列表区域