knight-ui 1.1.2 → 1.1.4

package/component/ai/AIChatDialogue.d.ts

@@ -44,6 +44,10 @@ export declare class AIChatDialogue extends AbstractUI<AIChatDialogueProps, AICh
     private scrollToBottom;
     private getMsgKey;
     private isEmptyNode;
+    /** 正文区是否正处于流式输出(有内容)—— 内容活跃时思考区不再显示等待指示,保证同一时刻只有一个指示 */
+    private isStreamingContent;
+    /** “思考中”流式指示:纯思考/工具执行阶段正文尚未流出时,以动效文字替代孤立光标 */
+    private renderThinkingIndicator;
     /** 思考显示开关：showThinking !== false 时显示思考块 */
     private thinkingEnabled;
     /** 是否正处于"只吐思考、还没出正文"的流式阶段 */
@@ -60,6 +64,16 @@ export declare class AIChatDialogue extends AbstractUI<AIChatDialogueProps, AICh
     private syncThinkingClock;
     private renderThinkingBlock;
     private renderAvatar;
+    /**
+     * 点击"复制"：先跑调用方的 onCopy，再弹 Toast 提示。
+     *
+     * 组件自己不碰剪贴板 —— content 是 ReactNode，可能是节点而不是文本，"该拷什么"只有调用方
+     * 说得清(演示里就是 String(msg.content))，所以复制动作始终由 onCopy 完成，这里只负责反馈。
+     * 也正因为如此，提示是"复制动作已发出"，不是组件核实过的结果：onCopy 若是异步写入且被浏览器
+     * 拒绝，这里无从得知(要真结果就得把组件改成自己写剪贴板，并把 content 收窄成 string)。
+     * 传 copyTip={false} 可关掉提示，把反馈交回调用方。
+     */
+    private handleCopy;
     private renderActionBtn;
     protected OnRenderContent(): React.ReactElement;
 }
@@ -73,6 +87,8 @@ export interface AIChatDialogueProps extends UIProps {
     showAvatar?: boolean;
     showNickname?: boolean;
     maxHeight?: number;
+    /** 是否给助手回复内容加边框(含内边距与圆角) @default false */
+    showAssistantBorder?: boolean;
     /** 是否显示"思考过程"块 @default true */
     showThinking?: boolean;
     /** 思考块标题 @default "思考过程" */
@@ -83,6 +99,8 @@ export interface AIChatDialogueProps extends UIProps {
     thinkingBodyMaxHeight?: number;
     emptyContent?: React.ReactNode;
     onCopy?: (msg: AIMessage) => void;
+    /** 点击复制后弹出的 Toast 文案；传 false 关闭提示，反馈由调用方自理 @default "已复制" */
+    copyTip?: React.ReactNode | false;
     onRetry?: (msg: AIMessage, index: number) => void;
 }
 interface AIChatDialogueState extends UIState {

package/component/ai/AIChatInput.d.ts

@@ -33,7 +33,7 @@ export interface AIChatInputProps extends UIProps {
     disabled?: boolean;
     loading?: boolean;
     attachments?: Attachment[];
-    /** 最小行数 @default 1 */
+    /** 最小(初始)行数 @default 2 */
     minRows?: number;
     /** 最大行数,超出后滚动 @default 4 */
     maxRows?: number;

package/component/basic/Button.d.ts

@@ -10,8 +10,9 @@ export interface ButtonGroupProps extends UIProps {
 /**
  * 按钮。
  */
-export declare class Button extends AbstractUI<ButtonProps, UIState> {
+export declare class Button extends AbstractUI<ButtonProps, ButtonState> {
     static Group: typeof ButtonGroup;
+    constructor(props: ButtonProps);
     /** 按钮聚焦 */
     focus(): void;
     /** 按钮失焦 */
@@ -21,6 +22,10 @@ export declare class Button extends AbstractUI<ButtonProps, UIState> {
     private getPadding;
     private getColorStyle;
 }
+interface ButtonState extends UIState {
+    hovered: boolean;
+    pressed: boolean;
+}
 export interface ButtonProps extends UIProps {
     type?: ButtonVariant;
     theme?: ButtonTheme;

package/component/display/Calendar.d.ts

@@ -1,6 +1,5 @@
 import React from "react";
 import { AbstractUI, type UIProps, type UIState } from "../../base";
-type CalendarMode = "month" | "year" | "day";
 /**
  * 日历。
  */
@@ -15,7 +14,6 @@ export declare class Calendar extends AbstractUI<CalendarProps, CalendarState> {
 }
 export interface CalendarProps extends UIProps {
     value?: Date;
-    mode?: CalendarMode;
     isToday?: (date: Date) => boolean;
     disabledDate?: (date: Date) => boolean;
     onChange?: (date: Date) => void;
@@ -23,6 +21,5 @@ export interface CalendarProps extends UIProps {
 interface CalendarState extends UIState {
     viewDate: Date;
     value: Date;
-    hoveredDate: Date | null;
 }
 export {};

package/component/display/Cropper.d.ts

@@ -35,7 +35,6 @@ export interface CropResult {
 export interface CropperProps extends UIProps {
     src?: string;
     cropShape?: CropShape;
-    aspectRatio?: number;
     onCrop?: (result: CropResult) => void;
 }
 interface CropperState extends UIState {

package/component/display/Table.d.ts

@@ -1,33 +1,65 @@
 import React from "react";
 import { AbstractUI, type UIProps, type UIState } from "../../base";
+export interface TableFilterOption {
+    text: string;
+    value: string;
+}
 export interface TableColumn {
     key: string;
     title: React.ReactNode;
     dataIndex?: string;
     width?: number;
     render?: (value: any, record: Record<string, any>, index: number) => React.ReactNode;
-    sorter?: (a: any, b: any) => number;
-    filters?: {
-        text: string;
-        value: string;
-    }[];
+    /**
+     * 排序比较函数。给了就在表头出排序按钮。
+     * 给 true 则"只出按钮、不排本地数据" —— 排序发生在服务端, 拿到 onChange 后自己重新取数。
+     * (入参是该列的取值, 不是整条记录)
+     */
+    sorter?: ((a: any, b: any) => number) | boolean;
+    /**
+     * 不想写比较函数时给 true —— 按该列的原始值排(数字按数值比, 其余按本地化字符串比)。
+     * 与 sorter 二选一, 同时给以 sorter 为准。
+     */
+    sortable?: boolean;
+    /** 初始排序方向。设了它, 这一列挂载时就是排好序的状态 */
+    defaultSortOrder?: "ascend" | "descend";
+    /** 表头筛选候选。给了就在表头出漏斗按钮 */
+    filters?: TableFilterOption[];
+    /** 判定某条记录是否命中某个筛选值。列内多选取"或", 跨列取"与" */
     onFilter?: (value: string, record: Record<string, any>) => boolean;
+    /** 是否多选, 默认 true; 给 false 走单选(等价于点一条即确定) */
+    filterMultiple?: boolean;
 }
 /**
  * 数据表格。
  */
 export declare class Table extends AbstractUI<TableProps, TableState> {
     private scrollEl;
+    private filterZIndex;
+    private filterOutsideHandler;
     constructor(props: TableProps);
+    componentWillUnmount(): void;
     private onScrollRef;
     private onScrollWheel;
     componentDidUpdate(prevProps: Readonly<TableProps>): void;
     protected OnRenderContent(): React.ReactElement;
     private sortData;
+    private filterData;
     private toggleSort;
+    private notifyChange;
+    private openFilter;
+    private closeFilter;
+    private toggleDraft;
+    private commitFilter;
+    private resetFilter;
+    private renderFilterPanel;
     private toggleSelectAll;
     private toggleSelectRow;
 }
+export interface TableSorter {
+    key: string | null;
+    order: "ascend" | "descend" | null;
+}
 export interface TableProps extends UIProps {
     columns?: TableColumn[];
     dataSource?: Record<string, any>[];
@@ -50,10 +82,23 @@ export interface TableProps extends UIProps {
     selectedRowKeys?: (string | number)[];
     defaultSelectedRowKeys?: (string | number)[];
     onRowSelectionChange?: (selectedRowKeys: (string | number)[]) => void;
+    /** 表头排序/筛选发生变化时回调(服务端分页时可据此重新取数) */
+    onChange?: (sorter: TableSorter, filters: Record<string, string[]>) => void;
 }
 interface TableState extends UIState {
     sortKey: string | null;
     sortOrder: string | null;
     selectedRowKeys: (string | number)[];
+    /** 已生效的筛选: 列 key → 选中的值 */
+    filters: Record<string, string[]>;
+    filterOpenKey: string | null;
+    filterRect: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    } | null;
+    /** 面板里的草稿, 点"确定"才写回 filters */
+    filterDraft: string[];
 }
 export {};

package/component/display/UserGuide.d.ts

@@ -11,11 +11,24 @@ export interface GuideStep {
  */
 export declare class UserGuide extends AbstractUI<UserGuideProps, UserGuideState> {
     constructor(props: UserGuideProps);
+    componentDidMount(): void;
     componentDidUpdate(prevProps: Readonly<UserGuideProps>): void;
+    componentWillUnmount(): void;
+    private rafId;
+    private onViewportChange;
     private goTo;
     private handleSkip;
     private handleFinish;
     protected OnRenderContent(): React.ReactElement;
+    /** 量目标的视口矩形; 选择器为空或选不中时返回 null */
+    private measureTarget;
+    /**
+     * 卡片落位。有目标就贴着高亮环按 placement 摆, 没有目标就退回底部居中。
+     * 水平方向做视口夹取 —— 卡片固定 360 宽, 目标贴边时不做夹取会有一半在屏幕外。
+     * 竖直方向必须留"塞不塞得下"的判断: 引导卡片是整屏唯一的操作入口, 飞到视口外
+     * 就等于引导卡死(遮罩还在、点不掉、也看不到按钮), 宁可压住目标也不能出屏。
+     */
+    private calcCardPosition;
 }
 export interface UserGuideProps extends UIProps {
     steps?: GuideStep[];

package/component/display/index.d.ts

@@ -39,7 +39,7 @@ export type { ScrollListProps } from "./ScrollList";
 export { SideSheet } from "./SideSheet";
 export type { SideSheetProps } from "./SideSheet";
 export { Table } from "./Table";
-export type { TableProps, TableColumn } from "./Table";
+export type { TableProps, TableColumn, TableFilterOption, TableSorter } from "./Table";
 export { Timeline } from "./Timeline";
 export type { TimelineProps, TimelineItemProps } from "./Timeline";
 export { Tooltip } from "./Tooltip";

package/component/feedback/Banner.d.ts

@@ -14,7 +14,11 @@ export declare class Banner extends AbstractUI<BannerProps, BannerState> {
     componentDidMount(): void;
     componentDidUpdate(prevProps: Readonly<BannerProps>): void;
     componentWillUnmount(): void;
+    /** 可关闭与否由 closable 明确控制, 不看有没有接 onClose —— 要不要能关是横幅自己的呈现属性,
+     *  和"关了要不要通知别人"是两回事: 有的横幅关掉不需要回调(纯粹自己消失即可)。 */
+    private get closable();
     private handleClose;
+    private closeSelf;
     protected OnRenderContent(): React.ReactElement;
 }
 export interface BannerProps extends UIProps {
@@ -26,6 +30,9 @@ export interface BannerProps extends UIProps {
     bordered?: boolean;
     fullMode?: boolean;
     actions?: React.ReactNode;
+    /** 是否可关闭(点击横幅主体关闭)。默认 true; 置 false 得到一条纯静态横幅: 光标不变手型, 点击无反应。 */
+    closable?: boolean;
+    /** 关闭回调。触发时机由 closable 决定, 与本回调是否传入无关。 */
     onClose?: () => void;
 }
 export {};

package/component/feedback/Popconfirm.d.ts

@@ -29,7 +29,7 @@ export declare class Popconfirm extends AbstractUI<PopconfirmProps, PopconfirmSt
     private handleCancel;
     private handleTriggerClick;
     protected OnRenderContent(): React.ReactElement;
-    private arrowPosition;
+    private arrowStyle;
 }
 type PopconfirmAnimPhase = "entering" | "entered" | "leaving" | "exited";
 export interface PopconfirmProps extends UIProps {

package/component/input/ColorPicker.d.ts

@@ -35,6 +35,9 @@ export declare class ColorPicker extends AbstractUI<ColorPickerProps, ColorPicke
     constructor(props: ColorPickerProps);
     private resolveInitValue;
     componentDidUpdate(prevProps: Readonly<ColorPickerProps>): void;
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    private onClickOutside;
     private openEyeDropper;
     private startDrag;
     private onDocMouseMove;

package/component/internal/Mask.d.ts

@@ -1,4 +1,28 @@
 import React from "react";
+/**
+ * 把一张 mask 图写成遮罩声明: 铺满整块、不平铺, 标准属性与 -webkit- 前缀都写。
+ * 前缀只写一套的话旧 Safari 会整个忽略挖洞, 且不报错, 只是蒙版糊满全图。
+ */
+export declare function maskStyle(image: string): React.CSSProperties;
+/**
+ * 矩形挖洞的 mask 图 —— **一条** SVG 路径, 不是四条 mask 图层拼出来的。
+ *
+ * 多图层接边必留缝, 而且和"四块元素拼"是同一个病根: 每个图层都是一张独立纹理, 按
+ * size/position 摆位时要重新采样一次, 边缘那一两个像素会跟图层外的透明混掉, alpha 掉到 1 以下;
+ * 相邻两条图层的边缘于是都"半透", 蒙版正好在那条线上缺了一角。位置还会被吸附到整数设备像素,
+ * 缝隙/重叠同样是 1px 级的。两种机制都指向同一句话: 别在多图层之间接边。
+ * 半透明 + 模糊把这点差异放大成了肉眼可见的一道缝(纯色蒙版上根本看不出来)。
+ *
+ * 一条路径里没有"图层边界"这回事: 外框一个子路径、洞一个子路径, evenodd 把中间挖掉。
+ * viewBox 取遮罩自身的像素尺寸(1 用户单位 = 1px), 配 mask-size 100% 100% + preserveAspectRatio='none',
+ * 于是它按布局尺寸一次性栅格化, 全程没有二次缩放 —— 洞的边上只剩那一次抗锯齿。
+ *
+ * 注意 mask 图是"白色 = 保留": 只画洞的话是反的, 得连外框一起画再用 evenodd 挖。
+ *
+ * @param boxW/boxH 遮罩自身的尺寸(px, 不是图片的)
+ * @param x/y/w/h   洞的位置与大小, 同一坐标系
+ */
+export declare function rectHoleMaskImage(boxW: number, boxH: number, x: number, y: number, w: number, h: number): string;
 /**
  * Mask — 遮罩层组件.
  * 用于 Modal/SideSheet/Drawer 等浮层的背景遮罩.
@@ -12,4 +36,23 @@ export declare class Mask {
      * @param duration 过渡时长(ms)
      */
     static render(zIndex: number, opacity: number, onClick?: () => void, duration?: number): React.ReactElement;
+    /**
+     * 带"洞"的遮罩 —— rect 那一块不被遮住, 用于 UserGuide 高亮目标。
+     *
+     * 洞是在**同一块遮罩、同一条 mask 路径**上挖的(见 rectHoleMaskImage 的说明),
+     * 不是四块遮罩拼的, 也不是几条 mask 图层拼的 —— 那两种都会在接边处留下一道缝,
+     * 半透明 + 模糊会把它放大到肉眼可见。
+     *
+     * 这里只管几何: 洞只保证"不压暗、不模糊"。洞是否可点, 取决于调用方有没有在
+     * 遮罩之上再放一层铺满视口的容器 —— 有的话点击会被那层收走(它仍是模态的),
+     * 没有的话点击就会落到页面上(能直接操作被高亮的控件)。两种都是合理设计, 由调用方定。
+     *
+     * @param rect 视口坐标; 传 null 退化成整片遮罩(没有目标的步骤)
+     */
+    static renderHole(rect: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    } | null, zIndex: number, duration?: number): React.ReactElement;
 }

package/component/internal/index.d.ts

@@ -1,5 +1,5 @@
 export { Portal } from "./Portal";
-export { Mask } from "./Mask";
+export { Mask, maskStyle, rectHoleMaskImage } from "./Mask";
 export { OverlayZIndex } from "./OverlayZIndex";
 export { BodyScrollLock } from "./BodyScrollLock";
 export { ClickOutside } from "./ClickOutside";

package/component/plus/AudioPlayer.d.ts

@@ -16,6 +16,8 @@ export interface AudioPlayerState {
     playing: boolean;
     currentTime: number;
     duration: number;
+    /** 已缓冲到的位置(秒)。进度体上"已加载"那一段用它。 */
+    buffered: number;
     volume: number;
     muted: boolean;
     playbackRate: number;
@@ -25,6 +27,7 @@ interface InternalState extends UIState {
     playing: boolean;
     currentTime: number;
     duration: number;
+    buffered: number;
     volume: number;
     muted: boolean;
     playbackRate: number;
@@ -37,6 +40,12 @@ export declare class AudioPlayer extends AbstractUI<AudioPlayerProps, InternalSt
     private volumeLeaveTimer;
     private speedLeaveTimer;
     private _api;
+    /** 正在拖进度。放字段而不是 state —— 它只影响事件处理, 不参与渲染, 进 state 每动一下都白渲一次。 */
+    private scrubbing;
+    /** 正在拖音量。同上, 也是字段。 */
+    private volumeScrubbing;
+    /** 音量条当前的 DOM 节点 —— 滚轮要挂原生监听, 得留住引用才能解绑。 */
+    private volumeBarEl;
     constructor(props: AudioPlayerProps);
     componentWillUnmount(): void;
     getAPI(): AudioPlayerAPI;
@@ -45,8 +54,28 @@ export declare class AudioPlayer extends AbstractUI<AudioPlayerProps, InternalSt
     private handleTimeUpdate;
     private handleLoadedMetadata;
     private handleEnded;
-    private handleProgressClick;
-    private handleVolumeBarClick;
+    /** 把横坐标折算成进度并写回 audio。拖动过程中的每一次移动都走它。 */
+    private seekFromClientX;
+    private handleScrubDown;
+    private handleScrubMove;
+    private handleScrubUp;
+    /** 音量写回 audio。拖 / 滚轮都收敛到这里, 免得两边各写一份 clamp。 */
+    private setVolumeFromRatio;
+    /** 纵坐标折成 0-1 的音量。条子底端是 0, 所以是 1 减。 */
+    private volumeFromClientY;
+    private handleVolumeScrubDown;
+    private handleVolumeScrubMove;
+    private handleVolumeScrubUp;
+    /**
+     * 滚轮调音量, 每格 5%。
+     * 必须用**原生**监听而不是 onWheel: React 19 在根节点上把 wheel 注册成 passive 的,
+     * onWheel 里调 preventDefault 不生效(只会打一条警告), 结果是音量变了、页面也跟着滚了。
+     * 每次 ±0.05 而不是按 deltaY 的原始值 —— 不同鼠标一格 deltaY 从 1 到 120 都有, 直接用会
+     * 一格从 0 蹦到爆表。
+     */
+    private handleVolumeWheel;
+    /** 回调 ref: 气泡是条件渲染的, 挂载/卸载时在这里接上/摘掉滚轮监听。 */
+    private bindVolumeWheel;
     private openVolume;
     private scheduleVolumeClose;
     private openSpeed;

package/component/plus/Chat.d.ts

@@ -15,11 +15,31 @@ interface ChatMessage {
  */
 export declare class Chat extends AbstractUI<ChatProps, ChatState> {
     private listRef;
+    private taRef;
+    private emojiBtnRef;
+    private emojiPanelRef;
+    private emojiZIndex;
+    private outsideHandler;
+    private trackHandler;
     constructor(props: ChatProps);
-    componentDidUpdate(prevProps: Readonly<ChatProps>): void;
+    componentDidUpdate(prevProps: Readonly<ChatProps>, prevState: Readonly<ChatState>): void;
     componentDidMount(): void;
+    componentWillUnmount(): void;
     private scrollToBottom;
+    /**
+     * 让输入框在 rows ~ maxRows 行之间跟着内容长高, 越过 maxRows 之后框内滚动。
+     * 改前是一个单行 <input>, 长文本只能左右滚动, 换行内容完全看不见 —— 这是本次要修的问题。
+     */
+    private resizeInput;
     private handleSend;
+    private insertEmoji;
+    private toggleEmoji;
+    private openEmoji;
+    private closeEmoji;
+    private teardownEmoji;
+    private emojiPanelStyle;
+    private renderEmojiPanel;
+    private renderInput;
     protected OnRenderContent(): React.ReactElement;
 }
 export interface ChatProps extends UIProps {
@@ -32,8 +52,23 @@ export interface ChatProps extends UIProps {
     showInput?: boolean;
     placeholder?: string;
     sendText?: string;
+    /** 是否显示头像, 默认 true */
+    showAvatar?: boolean;
+    /** 是否显示名称(msg.name), 默认 true */
+    showName?: boolean;
+    /** 是否显示气泡底板, 默认 true。关掉后内容直接铺在面板上, 并放宽到整行 —— 适合长文 / Markdown 正文 */
+    showBubble?: boolean;
+    /** 是否显示消息时间(msg.time), 默认 false */
+    showTime?: boolean;
+    /** 输入框的初始行数(最小高度), 默认 1 */
+    rows?: number;
+    /** 输入框最多撑到几行, 超出后框内滚动, 默认 5 */
+    maxRows?: number;
+    /** 输入框左下角的表情按钮与表情面板, 默认 true(仅 showInput 时有效) */
+    showEmoji?: boolean;
 }
 interface ChatState extends UIState {
     inputValue: string;
+    emojiOpen: boolean;
 }
 export {};

package/component/plus/CodeEditor.d.ts

@@ -57,7 +57,7 @@ export interface CodeEditorProps extends UIProps {
     width?: number | string;
     /** 编辑器最小宽度(px) */
     minWidth?: number;
-    /** Monaco 主题 @default "vs-dark" */
+    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
     theme?: "vs-dark" | "light" | "hc-black";
     /** 只读 @default false */
     readOnly?: boolean;

package/component/plus/CodeHighlight.d.ts

@@ -21,6 +21,7 @@ export declare class CodeHighlight extends AbstractUI<CodeHighlightProps, CodeHi
 export interface CodeHighlightProps extends UIProps {
     code?: string;
     language?: string;
+    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
     theme?: "vs-dark" | "light" | "hc-black";
     showLineNumbers?: boolean;
     height?: number | string;

package/component/plus/JsonViewer.d.ts

@@ -26,6 +26,7 @@ export interface JsonViewerProps extends UIProps {
     readOnly?: boolean;
     onChange?: (value: string) => void;
     height?: number;
+    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
     theme?: "vs-dark" | "light";
 }
 interface JsonViewerState extends UIState {

package/component/plus/VideoPlayer.d.ts

@@ -44,6 +44,12 @@ export declare class VideoPlayer extends AbstractUI<VideoPlayerProps, InternalSt
     private volumeLeaveTimer;
     private speedLeaveTimer;
     private _api;
+    /** 正在拖进度。放字段而不是 state —— 它只影响事件处理, 不参与渲染, 进 state 每动一下都白渲一次。 */
+    private scrubbing;
+    /** 正在拖音量。同上, 也是字段。 */
+    private volumeScrubbing;
+    /** 音量条当前的 DOM 节点 —— 滚轮要挂原生监听, 得留住引用才能解绑。 */
+    private volumeBarEl;
     constructor(props: VideoPlayerProps);
     componentDidMount(): void;
     componentWillUnmount(): void;
@@ -55,8 +61,28 @@ export declare class VideoPlayer extends AbstractUI<VideoPlayerProps, InternalSt
     private handleTimeUpdate;
     private handleLoadedMetadata;
     private handleEnded;
-    private handleProgressClick;
-    private handleVolumeBarClick;
+    /** 把横坐标折算成进度并写回 video。拖动过程中的每一次移动都走它。 */
+    private seekFromClientX;
+    private handleScrubDown;
+    private handleScrubMove;
+    private handleScrubUp;
+    /** 音量写回 video。拖 / 滚轮都收敛到这里, 免得两边各写一份 clamp。 */
+    private setVolumeFromRatio;
+    /** 纵坐标折成 0-1 的音量。条子底端是 0, 所以是 1 减。 */
+    private volumeFromClientY;
+    private handleVolumeScrubDown;
+    private handleVolumeScrubMove;
+    private handleVolumeScrubUp;
+    /**
+     * 滚轮调音量, 每格 5%。
+     * 必须用**原生**监听而不是 onWheel: React 19 在根节点上把 wheel 注册成 passive 的,
+     * onWheel 里调 preventDefault 不生效(只会打一条警告), 结果是音量变了、页面也跟着滚了。
+     * 每次 ±0.05 而不是按 deltaY 的原始值 —— 不同鼠标一格 deltaY 从 1 到 120 都有, 直接用会
+     * 一格从 0 蹦到爆表。
+     */
+    private handleVolumeWheel;
+    /** 回调 ref: 气泡是条件渲染的, 挂载/卸载时在这里接上/摘掉滚轮监听。 */
+    private bindVolumeWheel;
     private openVolume;
     private scheduleVolumeClose;
     private openSpeed;

package/component/tokens/index.d.ts

@@ -1,33 +1,36 @@
 /**
- * 编程式 Token 访问 — 读取 :root 上定义的 --ku-* CSS 变量.
- * 主要用于组件内需要动态计算样式值时通过 JS 获取 token 值.
+ * 内容色板的 JS 出口 —— 全库仅剩这一处需要 JS 参与的颜色拼串。
+ *
+ * 为什么这点事也得有 JS: **CSS 里写不出"随主题变档位号"的颜色**。内容色板的同一个色相在两个
+ * 主题下落的是不同档(blue 暗色第 7 档、亮色第 4 档), 而组件拿到的只是色相名。拼成
+ * `rgb(var(--ku-content-blue))` 交给内联样式是最省的做法 —— 它跟随主题自动变, 不需要 JS 读色、
+ * 不需要重渲染, 调用方也不必知道档位号。
+ *
+ * 真正定义颜色的是 palette.css 里的 `--ku-content-<hue>`, 由 `scripts/gen-palette.mjs` 按
+ * "该主题下 L 最接近该主题目标明度"的规则选出; **这里一个字面量都不存**。
+ *
+ * ── 剪掉的整族 ──
+ * 曾经还有一层"读取已解析颜色"的桥: `currentTheme` / `readToken` / `readTokens` / `readTriplet` /
+ * `rgb` / `hex` / `valueToHex` / `contentStep` / `contentColor` / `contentHex`。它们服务的两个
+ * 消费者现在都不存在了 ——
+ *   ① 内容色板不需要读色: 字符串拼装就够了(这正是 contentVar 存在的理由);
+ *   ② Monaco 那一版已整体撤掉: 代码面现在完全用 VS 自带的 `vs-dark`, 不注册自定义主题,
+ *      于是 `valueToHex`(为"只吃 #RRGGBB 的注册表"而写)也一并没了用处。
+ * 所以按"整族剪"处理, 一个不留 —— 养一批无人调用的导出, 比真要用时重写它们(~70 行:
+ * `getComputedStyle` + 展开嵌套 `var()` + 十六进制转换)贵得多。
+ *
+ * ── 连带删掉的产物 ──
+ * 那一族原本依赖 `palette.gen.ts`(生成器产出的色板 JS 常量镜像)做 SSR 兜底。既然没有 importer
+ * 了, 这份常量表也一并从生成器里删掉 —— 没有消费者的副本只会漂移。所以这个文件里**一个色值
+ * 都没有**, 颜色的唯一定义处是 `palette.css`。
  */
-export declare const Tokens: {
-    primary: () => string;
-    primaryHover: () => string;
-    primaryActive: () => string;
-    primaryDisabled: () => string;
-    primaryLightDefault: () => string;
-    primaryLightHover: () => string;
-    primaryLightActive: () => string;
-    success: () => string;
-    warning: () => string;
-    danger: () => string;
-    info: () => string;
-    bgDeepest: () => string;
-    bgPanel: () => string;
-    bgElevated: () => string;
-    bgHover: () => string;
-    bgBorder: () => string;
-    textPrimary: () => string;
-    textSecondary: () => string;
-    textPlaceholder: () => string;
-    textDisabled: () => string;
-    fontSize: (key: "xs" | "sm" | "base" | "md" | "lg") => string;
-    radius: (key: "xs" | "sm" | "base" | "md" | "lg" | "xl") => string;
-    spacing: (key: "xs" | "sm" | "base" | "md" | "lg" | "xl") => string;
-    zMask: () => number;
-    zOverlay: () => number;
-    zModal: () => number;
-    zToast: () => number;
-};
+/**
+ * 内容色的**字符串形式** —— `rgb(var(--ku-content-blue))`。
+ *
+ * 这是 Tag / Avatar / VChart 该用的那一个: 它原样进内联样式, 跟随主题自动变, 不需要 JS 读色、
+ * 不需要重渲染、也不需要知道档位号。改造前 Tag 那套 `hexToRgba(hex, alpha)` 就是被它取代的 ——
+ * 那种做法必须在 JS 里持有 hex, 于是每个消费方都攒出自己的一份内容色板。
+ */
+export declare function contentVar(hue: string): string;
+/** 内容色的浅底 / 描边 —— `rgba(var(--ku-content-blue), 0.15)` */
+export declare function contentTintVar(hue: string, alpha: number): string;