@ibiz-template-plugin/ai-chat 0.0.117 → 0.0.119

package/dist/types/components/chat-messages/use-virtual-list.d.ts

@@ -1,156 +0,0 @@
-import { RefObject } from 'preact';
-import { ReadonlySignal, Signal } from '@preact/signals';
-
-/**
- * 虚拟列表项
- *
- * @author zpc
- * @date 2026-09-20
- */
-export interface VirtualItem {
-    /**
-     * 数据源中的实际索引
-     *
-     * @type {number}
-     */
-    index: number;
-    /**
-     * 稳定 key（如 messageid），用于测量缓存
-     *
-     * @type {string}
-     */
-    key: string;
-    /**
-     * 该项在列表中的 top 偏移（累计高度）
-     *
-     * @type {number}
-     */
-    start: number;
-    /**
-     * 当前高度（实测或预估）
-     *
-     * @type {number}
-     */
-    size: number;
-    /**
-     * 绑定到项包裹元素的 ref，用于 ResizeObserver 实测高度
-     *
-     * @type {(el: HTMLElement | null) => void}
-     */
-    measureRef: (el: HTMLElement | null) => void;
-}
-export interface UseVirtualListOptions {
-    /**
-     * 总条数
-     *
-     * @type {number}
-     */
-    count: number;
-    /**
-     * 根据索引返回稳定 key（用于按 key 缓存实测高度，避免前插/删除时按下标错位）
-     *
-     * @type {(index: number) => string}
-     */
-    getItemKey: (index: number) => string;
-    /**
-     * 未渲染项的预估高度
-     *
-     * @type {(index: number) => number}
-     */
-    estimateSize: (index: number) => number;
-    /**
-     * 可视区上下各多渲染的条数
-     *
-     * @type {number}
-     */
-    overscan?: number;
-}
-export interface UseVirtualListResult {
-    /**
-     * 挂到滚动容器上的 ref
-     *
-     * @type {RefObject<HTMLDivElement>}
-     */
-    containerRef: RefObject<HTMLDivElement>;
-    /**
-     * 当前可视区内的虚拟项
-     *
-     * @type {VirtualItem[]}
-     */
-    virtualItems: VirtualItem[];
-    /**
-     * 整个列表的总高度（spacer 高度）
-     *
-     * @type {number}
-     */
-    totalSize: number;
-    /**
-     * 每项起始偏移的前缀和（长度 count + 1，最后一项为总高度）
-     *
-     * @type {number[]}
-     */
-    offsets: number[];
-    /**
-     * 取某下标的起始偏移（供滚动锚定使用）
-     *
-     * @type {(index: number) => number}
-     */
-    getOffset: (index: number) => number;
-    /**
-     * @description 恢复滚动条位置
-     * @memberof UseVirtualListResult
-     */
-    restoreScrollPosition: () => void;
-    /**
-     * 响应式总高度：依赖测量版本号（实测高度回填）与条数，供自定义滚动条订阅
-     *
-     * @type {ReadonlySignal<number>}
-     */
-    totalSizeSignal: ReadonlySignal<number>;
-    /**
-     * 容器 scrollTop 信号（供自定义滚动条计算 thumb 位置）
-     *
-     * @type {Signal<number>}
-     */
-    scrollTopSignal: Signal<number>;
-    /**
-     * 容器可视高度信号
-     *
-     * @type {Signal<number>}
-     */
-    clientHeightSignal: Signal<number>;
-    /**
-     * 自定义滚动条拖动状态：拖动中跳过头部前插的 scrollTop 补偿，由滚动条按指针比例重映射接管
-     *
-     * @type {Signal<boolean>}
-     */
-    isDragging: Signal<boolean>;
-    /**
-     * 程序化设置滚动位置：同步 scrollTop 信号 + 直接写容器 scrollTop（clamp 到当前可滚动范围）
-     *
-     * @type {(top: number) => void}
-     */
-    setScrollTop: (top: number) => void;
-}
-/**
- * 动态高度虚拟列表 Hook
- *
- * ## 核心思想
- * 消息列表里每条消息高度都不同（markdown、代码块、图片、折叠、流式增长），
- * 若全部渲染 DOM 节点会随消息数线性增长导致卡顿。本 Hook 只渲染「视口内 + overscan」的消息：
- * - 用一条 `height: totalSize` 的 spacer div 撑起可滚动总高度；
- * - 每条消息用 `position:absolute + transform:translateY(start)` 定位到对应偏移；
- * - 已渲染项用 ResizeObserver 实测真实高度，未渲染项用 `estimateSize` 预估占位。
- *
- * ## 为什么按 key 缓存而非按下标
- * 消息会「头部前插」（加载历史）和「删除」，导致已有消息的数组下标整体平移。
- * 若按下标缓存实测高度，前插后所有测量值会错位。因此用 `getItemKey`（messageid）作为测量缓存的键。
- *
- * ## 数据流
- * scrollTop / clientHeight / measureVersion 三个信号变化 → useMemo 重算 offsets（前缀和）
- * → 二分查找可视区间 → 产出 virtualItems → 组件只渲染这些项。
- *
- * @author zpc
- * @date 2026-09-20
- */
-export declare const useVirtualList: (options: UseVirtualListOptions) => UseVirtualListResult;

package/dist/types/components/chat-scrollbar/chat-scrollbar.d.ts

@@ -1,102 +0,0 @@
-import { RefObject } from 'preact';
-import { ReadonlySignal, Signal } from '@preact/signals';
-
-export interface ChatScrollbarProps {
-    /**
-     * 滚动容器 ref（与 useVirtualList 的 containerRef 同源）
-     *
-     * @type {RefObject<HTMLDivElement | null>}
-     */
-    containerRef: RefObject<HTMLDivElement | null>;
-    /**
-     * 容器 scrollTop 信号
-     *
-     * @type {Signal<number>}
-     */
-    scrollTop: Signal<number>;
-    /**
-     * 容器可视高度信号
-     *
-     * @type {Signal<number>}
-     */
-    clientHeight: Signal<number>;
-    /**
-     * 内容总高度信号（依赖实测高度回填）
-     *
-     * @type {ReadonlySignal<number>}
-     */
-    totalSize: ReadonlySignal<number>;
-    /**
-     * 程序化写滚动位置（同步信号 + 写容器 scrollTop）
-     *
-     * @type {(top: number) => void}
-     */
-    setScrollTop: (top: number) => void;
-    /**
-     * 拖动到顶部附近的通知（触发加载更早历史）
-     *
-     * 拖到顶部且前插补偿被跳过时，scrollTop 值可能不变导致浏览器不派发 scroll 事件，
-     * 因此不能只依赖 scroll 事件，需在此处直接通知
-     *
-     * @type {() => void}
-     */
-    onNearTop?: () => void;
-    /**
-     * 拖动状态回调（父组件转发给 useVirtualList 的 setIsDragging）
-     *
-     * @type {(dragging: boolean) => void}
-     */
-    onDragStateChange?: (dragging: boolean) => void;
-    /**
-     * thumb 最小高度，避免内容过长时不可抓取
-     *
-     * @type {number}
-     */
-    minThumbSize?: number;
-}
-/**
- * 自定义虚拟滚动条
- *
- * ## 为什么不用原生滚动条
- * 动态高度虚拟列表中未测量的项用预估高度占位，快速拖动原生滚动条时新项不断被实测，
- * totalSize（scrollHeight）持续变化，原生 thumb 按比例重定位导致滚动条乱跳。
- *
- * ## 核心策略
- * 隐藏原生滚动条绘制，保留原生 scrollTop 驱动内容（wheel/键盘/触摸不变），自绘 thumb：
- * - 拖动期间 thumb 定位用指针比例（dragRatio），不依赖异步的 scroll 事件回读，无滞后抖动；
- * - 拖动期间 totalSize 变化（测量回填/历史前插）时，按指针比例重映射 scrollTop，
- *   thumb 始终钉在指针下方，内容坐标系在其下方重排。
- *
- * ## 与 useVirtualList 的数据流交联
- * 本组件不持有滚动状态，全部通过 props 注入 useVirtualList 暴露的信号与回调，
- * 二者是「显示层 ↔ 驱动层」的关系：
- *
- * ```
- * useVirtualList                          ChatScrollbar
- * ────────────                          ──────────────
- * totalSizeSignal ─────────────────────► totalSize     （thumb 高度/比例）
- * clientHeightSignal ──────────────────► clientHeight  （thumb 高度/比例）
- * scrollTopSignal ─────────────────────► scrollTop     （非拖动期 thumb 位置）
- * setScrollTop ◄──────────────────────── 拖动/翻页      （程序化写滚动位置）
- * onDragStateChange ──► isDragging ──► 前插补偿跳过
- * onNearTop ──────────────────────────► 加载更早历史
- * ```
- *
- * 正向（useVirtualList → 本组件）：
- * - 滚动/测量回填/历史前插 → totalSize、scrollTop 信号变化 → 本组件重渲染更新 thumb；
- * - totalSizeSignal 是懒求值信号（只依赖测量版本号），滚动过程中零额外计算。
- *
- * 反向（本组件 → useVirtualList）：
- * - 拖动/点击翻页 → setScrollTop：同步写 scrollTop 信号 + 写容器 DOM，
- *   信号先行避免下一帧用旧值闪跳；虚拟列表据此重算可视区；
- * - onDragStateChange → 虚拟列表的 isDragging 信号置 true：
- *   拖动期间「头部前插补偿」被跳过（use-virtual-list.ts:373），
- *   前插导致的 totalSize 变化改由本组件的重锚定 effect 按指针比例重映射 scrollTop 接管，
- *   两端不会同时争抢滚动位置；
- * - onNearTop：拖到顶部时直接通知父级加载历史——前插补偿被跳过后 scrollTop 可能不变，
- *   浏览器不派发 scroll 事件，不能只依赖滚动事件触发加载。
- *
- * @author zpc
- * @date 2026-10-12
- */
-export declare const ChatScrollbar: (props: ChatScrollbarProps) => import("preact").JSX.Element | null;