niuma-ui 1.1.12 → 1.2.1

package/dist/components/tabs-utils.d.ts

@@ -0,0 +1,71 @@
+import type { RsContextMenuItem } from './context-menu-utils';
+/** 选项卡项定义 */
+export interface RsTabItem {
+    value: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    badge?: string | number;
+    /** 是否可关闭；未设置时继承 RsTabs 的 closable；fixed 为 true 时强制不可关 */
+    closable?: boolean;
+    /** 固定/常驻标签（对齐 GTabs fixed / 浏览器固定标签），不可关闭、不可被批量关闭 */
+    fixed?: boolean;
+    /** 是否可重命名；未设置时继承 RsTabs 的 renamable */
+    renamable?: boolean;
+}
+/** 选项卡尺寸 */
+export type RsTabsSize = 'sm' | 'md';
+/** line 下划线 · segmented 胶囊 · card 卡片（Ant editable-card） */
+export type RsTabsVariant = 'line' | 'segmented' | 'card';
+/**
+ * 标签栏对齐：start 左齐 · center 居中 · evenly 均分空隙 · stretch 项等宽铺满。
+ * 用于登录等场景，避免业务侧 :deep 改 list/trigger。
+ */
+export type RsTabsJustify = 'start' | 'center' | 'evenly' | 'stretch';
+/**
+ * 标题栏与内容区间距（主要用于 borderless）。
+ * none=0 · sm=8px · md=12px · lg=16px · xl=24px；也可用 CSS 变量 --rs-tabs-content-gap 覆盖。
+ */
+export type RsTabsContentGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+/** 标签过多时的处理方式 */
+export type RsTabsOverflow = 'scroll' | 'dropdown';
+/** 批量关闭动作（顶栏导航右键菜单） */
+export type RsTabsCloseAction = 'close' | 'others' | 'left' | 'right' | 'all';
+/** 判断是否为固定标签 */
+export declare function isTabFixed(item: RsTabItem): boolean;
+/** 判断单项是否展示关闭按钮 */
+export declare function isTabClosable(item: RsTabItem, globalClosable?: boolean): boolean;
+/** 判断单项是否可双击重命名 */
+export declare function isTabRenamable(item: RsTabItem, globalRenamable?: boolean): boolean;
+/** 关闭当前激活项时，解析应切换到的下一项（优先右侧，否则左侧） */
+export declare function getNextTabAfterClose(items: RsTabItem[], closedValue: string, activeValue: string): string | undefined;
+/**
+ * 批量关闭后解析应保留的激活项。
+ * 若当前激活项仍在剩余列表中则保持，否则取锚点（若仍在）或首项。
+ */
+export declare function getNextTabAfterBatchClose(remaining: RsTabItem[], activeValue: string, anchorValue?: string): string | undefined;
+/** 将 dragValue 对应的项移动到 dropValue 之前（fixed 项不可作为拖拽源或落点） */
+export declare function reorderTabItems(items: RsTabItem[], dragValue: string, dropValue: string): RsTabItem[];
+/**
+ * 按动作解析待关闭的 value 列表（跳过 fixed / 不可关闭项）。
+ */
+export declare function resolveTabsToClose(items: RsTabItem[], action: RsTabsCloseAction, anchorValue: string, globalClosable?: boolean): string[];
+export interface BuildTabContextMenuLabels {
+    close: string;
+    closeOthers: string;
+    closeLeft: string;
+    closeRight: string;
+    closeAll: string;
+}
+/**
+ * 构建顶栏导航右键菜单项（关闭 / 关闭其他 / 左 / 右 / 全部）。
+ */
+export declare function buildTabContextMenuItems(items: RsTabItem[], anchor: RsTabItem, globalClosable: boolean, labels: BuildTabContextMenuLabels): RsContextMenuItem[];
+export interface ResolveVisibleTabOptions {
+    /** dropdown 模式下为 false：激活项仅在「更多」展示，不占标签栏 */
+    keepActiveVisible?: boolean;
+}
+/**
+ * 根据各标签宽度与可用宽度，计算应展示的标签 value 集合。
+ */
+export declare function resolveVisibleTabValues(items: RsTabItem[], widths: Map<string, number>, availableWidth: number, activeValue: string, reservedWidth?: number, options?: ResolveVisibleTabOptions): Set<string>;

package/dist/components/tabs-utils.js

@@ -0,0 +1,147 @@
+//#region src/components/tabs-utils.ts
+/** 判断是否为固定标签 */
+function isTabFixed(item) {
+	return item.fixed === true;
+}
+/** 判断单项是否展示关闭按钮 */
+function isTabClosable(item, globalClosable = false) {
+	if (isTabFixed(item)) return false;
+	if (item.closable !== void 0) return item.closable;
+	return globalClosable;
+}
+/** 判断单项是否可双击重命名 */
+function isTabRenamable(item, globalRenamable = false) {
+	if (item.renamable !== void 0) return item.renamable;
+	return globalRenamable;
+}
+/** 关闭当前激活项时，解析应切换到的下一项（优先右侧，否则左侧） */
+function getNextTabAfterClose(items, closedValue, activeValue) {
+	if (activeValue !== closedValue) return activeValue;
+	const index = items.findIndex((item) => item.value === closedValue);
+	if (index < 0) return void 0;
+	const remaining = items.filter((item) => item.value !== closedValue);
+	if (!remaining.length) return void 0;
+	return remaining[index]?.value ?? remaining[index - 1]?.value ?? remaining[0]?.value;
+}
+/**
+* 批量关闭后解析应保留的激活项。
+* 若当前激活项仍在剩余列表中则保持，否则取锚点（若仍在）或首项。
+*/
+function getNextTabAfterBatchClose(remaining, activeValue, anchorValue) {
+	if (!remaining.length) return void 0;
+	if (remaining.some((item) => item.value === activeValue)) return activeValue;
+	if (anchorValue && remaining.some((item) => item.value === anchorValue)) return anchorValue;
+	return remaining[0]?.value;
+}
+/** 将 dragValue 对应的项移动到 dropValue 之前（fixed 项不可作为拖拽源或落点） */
+function reorderTabItems(items, dragValue, dropValue) {
+	const from = items.findIndex((item) => item.value === dragValue);
+	const to = items.findIndex((item) => item.value === dropValue);
+	if (from < 0 || to < 0 || from === to) return items;
+	const dragItem = items[from];
+	const dropItem = items[to];
+	if (!dragItem || !dropItem || isTabFixed(dragItem) || isTabFixed(dropItem)) return items;
+	const next = [...items];
+	const [moved] = next.splice(from, 1);
+	if (!moved) return items;
+	next.splice(to, 0, moved);
+	return next;
+}
+/**
+* 按动作解析待关闭的 value 列表（跳过 fixed / 不可关闭项）。
+*/
+function resolveTabsToClose(items, action, anchorValue, globalClosable = false) {
+	const index = items.findIndex((item) => item.value === anchorValue);
+	if (index < 0 && action !== "all") return [];
+	const canClose = (item) => isTabClosable(item, globalClosable);
+	switch (action) {
+		case "close": {
+			const item = items[index];
+			return item && canClose(item) ? [item.value] : [];
+		}
+		case "others": return items.filter((item) => item.value !== anchorValue && canClose(item)).map((item) => item.value);
+		case "left": return items.filter((item, i) => i < index && canClose(item)).map((item) => item.value);
+		case "right": return items.filter((item, i) => i > index && canClose(item)).map((item) => item.value);
+		case "all": return items.filter((item) => canClose(item)).map((item) => item.value);
+		default: return [];
+	}
+}
+/**
+* 构建顶栏导航右键菜单项（关闭 / 关闭其他 / 左 / 右 / 全部）。
+*/
+function buildTabContextMenuItems(items, anchor, globalClosable, labels) {
+	if (items.findIndex((item) => item.value === anchor.value) < 0) return [];
+	const canCloseAnchor = isTabClosable(anchor, globalClosable);
+	const others = resolveTabsToClose(items, "others", anchor.value, globalClosable);
+	const left = resolveTabsToClose(items, "left", anchor.value, globalClosable);
+	const right = resolveTabsToClose(items, "right", anchor.value, globalClosable);
+	const all = resolveTabsToClose(items, "all", anchor.value, globalClosable);
+	return [
+		{
+			key: "close",
+			label: labels.close,
+			icon: "x",
+			disabled: !canCloseAnchor
+		},
+		{
+			key: "sep-1",
+			label: "",
+			separator: true
+		},
+		{
+			key: "others",
+			label: labels.closeOthers,
+			icon: "copy-x",
+			disabled: others.length === 0
+		},
+		{
+			key: "left",
+			label: labels.closeLeft,
+			icon: "arrow-left-to-line",
+			disabled: left.length === 0
+		},
+		{
+			key: "right",
+			label: labels.closeRight,
+			icon: "arrow-right-to-line",
+			disabled: right.length === 0
+		},
+		{
+			key: "sep-2",
+			label: "",
+			separator: true
+		},
+		{
+			key: "all",
+			label: labels.closeAll,
+			icon: "trash-2",
+			danger: true,
+			disabled: all.length === 0
+		}
+	];
+}
+/**
+* 根据各标签宽度与可用宽度，计算应展示的标签 value 集合。
+*/
+function resolveVisibleTabValues(items, widths, availableWidth, activeValue, reservedWidth = 0, options = {}) {
+	const keepActiveVisible = options.keepActiveVisible ?? true;
+	if (availableWidth <= 0 || !items.length) return new Set(items.map((item) => item.value));
+	const budget = Math.max(0, availableWidth - reservedWidth);
+	const visible = [];
+	let used = 0;
+	for (const item of items) {
+		const width = widths.get(item.value) ?? 0;
+		if (used + width > budget) break;
+		visible.push(item.value);
+		used += width;
+	}
+	if (keepActiveVisible && !visible.includes(activeValue)) {
+		if (items.findIndex((item) => item.value === activeValue) >= 0) {
+			if (visible.length > 1) visible.pop();
+			if (!visible.includes(activeValue)) visible.push(activeValue);
+		}
+	}
+	return new Set(visible);
+}
+//#endregion
+export { buildTabContextMenuItems, getNextTabAfterBatchClose, getNextTabAfterClose, isTabClosable, isTabFixed, isTabRenamable, reorderTabItems, resolveTabsToClose, resolveVisibleTabValues };

package/dist/components/terminal-utils.d.ts

@@ -0,0 +1,59 @@
+import type { ITheme, Terminal } from '@xterm/xterm';
+export type RsTerminalThemeMode = 'auto' | 'light' | 'dark';
+export type RsResolvedTerminalTheme = 'light' | 'dark';
+export type RsTerminalAction = 'copy' | 'paste' | 'selectAll' | 'clear' | 'askAi';
+export type RsTerminalGeometry = {
+    cols: number;
+    rows: number;
+};
+/** `RsTerminal` 通过 `defineExpose` 公开的命令式接口。 */
+export interface RsTerminalExpose {
+    write: (data: string) => void;
+    clear: () => void;
+    focus: () => void;
+    fit: () => Promise<void>;
+    copySelection: () => Promise<void>;
+    pasteFromClipboard: () => Promise<void>;
+    selectAll: () => void;
+    getSelection: () => string;
+    hasSelection: () => boolean;
+    getGeometry: () => RsTerminalGeometry | null;
+    /**
+     * 逃生舱口：直接取 xterm 实例。
+     * 终端选项由组件按 props 托管，外部改写 `terminal.options` 会与之打架（尤其整体替换该对象
+     * 会逐项重设、触发全量重测）。需要什么能力优先提为 prop 或加进本接口。
+     */
+    getTerminal: () => Terminal | null;
+}
+/** 将 CSS 颜色规范为 #RRGGBB（支持 hex 与 computed rgb） */
+export declare function normalizeTerminalHexColor(value: string): string | null;
+/** 将 lab()/color() 等现代 CSS 色值转为 xterm 可解析的 #RRGGBB */
+export declare function resolveCssColorForXterm(value: string): string | null;
+/** 从全局 `--rs-terminal-*` token 构建 xterm 调色板（须已加载 styles.css） */
+export declare function readTerminalThemeFromCss(mode: RsResolvedTerminalTheme): ITheme;
+export declare function resolveTerminalTheme(mode?: RsTerminalThemeMode): RsResolvedTerminalTheme;
+export declare function getTerminalThemePalette(mode: RsResolvedTerminalTheme): ITheme;
+export declare function mergeTerminalTheme(mode: RsResolvedTerminalTheme, overrides?: Partial<ITheme>): ITheme;
+/** 读取斑马纹行底色（`--rs-terminal-row-stripe`，解析后供 xterm decoration 使用） */
+export declare function readTerminalRowStripeFromCss(mode: RsResolvedTerminalTheme): string;
+/** PTY 输出是否含终端控制序列（ESC / CSI），此类数据不应批量延迟。 */
+export declare function containsEscapeSequence(data: string): boolean;
+/** 检测 ncurses/vim/top 等全屏刷新常用的光标定位与清屏序列 */
+export declare function containsTuiRefreshSequence(data: string): boolean;
+/** 全屏清屏（top/vim 新一轮绘制常见） */
+export declare function containsFullScreenClear(data: string): boolean;
+/** 数据块以光标归位首行开头（top 每轮刷新常见） */
+export declare function startsWithCursorHome(data: string): boolean;
+/**
+ * 在本地解析层重置滚动边距等模式（不发给 PTY）。
+ * 仅在全屏清屏等明确「新一轮绘制」时调用，避免打断进行中的 TUI 光标位置。
+ */
+export declare function resetLocalTerminalModes(terminal: Terminal): void;
+export declare function snapTerminalViewportToBottom(terminal: Terminal): void;
+/** 处理 PTY 写入前的视口/模式准备（不移动写入光标，避免输入错位） */
+export declare function prepareTerminalForPtyWrite(terminal: Terminal, data: string): void;
+export declare function isMacPlatform(): boolean;
+/** 菜单/文档展示的修饰键标签 */
+export declare function terminalShortcutLabel(key: string): string;
+/** ANSI 16 色演示文本 */
+export declare function buildAnsiColorDemo(): string;

package/dist/components/terminal-utils.js

@@ -0,0 +1,210 @@
+import { readDocumentTheme } from "./code-editor-utils.js";
+//#region src/components/terminal-utils.ts
+var TERMINAL_CSS_KEYS = [
+	["background", "--rs-terminal-bg"],
+	["foreground", "--rs-terminal-fg"],
+	["cursor", "--rs-terminal-cursor"],
+	["cursorAccent", "--rs-terminal-cursor-accent"],
+	["selectionBackground", "--rs-terminal-selection-bg"],
+	["selectionForeground", "--rs-terminal-selection-fg"],
+	["black", "--rs-terminal-ansi-black"],
+	["red", "--rs-terminal-ansi-red"],
+	["green", "--rs-terminal-ansi-green"],
+	["yellow", "--rs-terminal-ansi-yellow"],
+	["blue", "--rs-terminal-ansi-blue"],
+	["magenta", "--rs-terminal-ansi-magenta"],
+	["cyan", "--rs-terminal-ansi-cyan"],
+	["white", "--rs-terminal-ansi-white"],
+	["brightBlack", "--rs-terminal-ansi-bright-black"],
+	["brightRed", "--rs-terminal-ansi-bright-red"],
+	["brightGreen", "--rs-terminal-ansi-bright-green"],
+	["brightYellow", "--rs-terminal-ansi-bright-yellow"],
+	["brightBlue", "--rs-terminal-ansi-bright-blue"],
+	["brightMagenta", "--rs-terminal-ansi-bright-magenta"],
+	["brightCyan", "--rs-terminal-ansi-bright-cyan"],
+	["brightWhite", "--rs-terminal-ansi-bright-white"]
+];
+var themeProbeCache = /* @__PURE__ */ new Map();
+function channelToHex(raw) {
+	const value = raw.endsWith("%") ? Math.round(Number(raw.slice(0, -1)) / 100 * 255) : Math.round(Number(raw));
+	if (!Number.isFinite(value)) return null;
+	return Math.max(0, Math.min(255, value)).toString(16).padStart(2, "0");
+}
+function parseRgbChannels(value) {
+	if (!value.toLowerCase().startsWith("rgb")) return null;
+	const open = value.indexOf("(");
+	const close = value.indexOf(")", open + 1);
+	if (open === -1 || close === -1) return null;
+	const parts = value.slice(open + 1, close).replaceAll("/", " ").replaceAll(",", " ").trim().split(/\s+/).filter(Boolean);
+	if (parts.length < 3) return null;
+	const r = channelToHex(parts[0]);
+	const g = channelToHex(parts[1]);
+	const b = channelToHex(parts[2]);
+	if (!r || !g || !b) return null;
+	return [
+		r,
+		g,
+		b
+	];
+}
+/** 将 CSS 颜色规范为 #RRGGBB（支持 hex 与 computed rgb） */
+function normalizeTerminalHexColor(value) {
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	if (/^#[0-9a-fA-F]{6}$/.test(trimmed)) return trimmed.toLowerCase();
+	if (/^#[0-9a-fA-F]{3}$/.test(trimmed)) {
+		const [, r, g, b] = trimmed;
+		return `#${r}${r}${g}${g}${b}${b}`.toLowerCase();
+	}
+	const rgb = parseRgbChannels(trimmed);
+	if (!rgb) return null;
+	return `#${rgb[0]}${rgb[1]}${rgb[2]}`;
+}
+/** 将 lab()/color() 等现代 CSS 色值转为 xterm 可解析的 #RRGGBB */
+function resolveCssColorForXterm(value) {
+	const direct = normalizeTerminalHexColor(value);
+	if (direct) return direct;
+	if (typeof document === "undefined") return null;
+	const canvas = document.createElement("canvas");
+	canvas.width = 1;
+	canvas.height = 1;
+	const ctx = canvas.getContext("2d", { willReadFrequently: true });
+	if (!ctx) return null;
+	try {
+		ctx.fillStyle = "#000000";
+		ctx.fillStyle = value;
+		if (typeof ctx.fillStyle !== "string") return null;
+		ctx.fillRect(0, 0, 1, 1);
+		const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+		if (a === 0) return null;
+		return `#${[
+			r,
+			g,
+			b
+		].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
+	} catch {
+		return null;
+	}
+}
+var BACKGROUND_THEME_KEYS = /* @__PURE__ */ new Set(["background", "selectionBackground"]);
+function readResolvedCssColor(cssVar, source, asBackground) {
+	const probe = document.createElement("span");
+	probe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none";
+	if (asBackground) probe.style.backgroundColor = `var(${cssVar})`;
+	else probe.style.color = `var(${cssVar})`;
+	source.appendChild(probe);
+	const computed = getComputedStyle(probe);
+	const raw = asBackground ? computed.backgroundColor : computed.color;
+	probe.remove();
+	return raw;
+}
+function themeProbeElement(mode) {
+	const cached = themeProbeCache.get(mode);
+	if (cached) return cached;
+	const probe = document.createElement("div");
+	probe.dataset.rsTheme = mode;
+	probe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none";
+	document.body.appendChild(probe);
+	themeProbeCache.set(mode, probe);
+	return probe;
+}
+function themeSourceElement(mode) {
+	if (document.documentElement.dataset.rsTheme === mode) return document.documentElement;
+	return themeProbeElement(mode);
+}
+/** 从全局 `--rs-terminal-*` token 构建 xterm 调色板（须已加载 styles.css） */
+function readTerminalThemeFromCss(mode) {
+	if (typeof document === "undefined" || typeof getComputedStyle === "undefined") return {};
+	const source = themeSourceElement(mode);
+	const theme = {};
+	for (const [key, cssVar] of TERMINAL_CSS_KEYS) {
+		const value = resolveCssColorForXterm(readResolvedCssColor(cssVar, source, BACKGROUND_THEME_KEYS.has(key)));
+		if (value) theme[key] = value;
+	}
+	return theme;
+}
+function resolveTerminalTheme(mode = "auto") {
+	return mode === "auto" ? readDocumentTheme() : mode;
+}
+function getTerminalThemePalette(mode) {
+	return readTerminalThemeFromCss(mode);
+}
+function mergeTerminalTheme(mode, overrides) {
+	return {
+		...readTerminalThemeFromCss(mode),
+		...overrides
+	};
+}
+/** PTY 输出是否含终端控制序列（ESC / CSI），此类数据不应批量延迟。 */
+function containsEscapeSequence(data) {
+	return data.includes("\x1B") || data.includes("›");
+}
+var TUI_REFRESH_PATTERN = /\x1b\[[0-9;]*[Hf]|\x1b\[2J|\x1b\[\?1049[hl]|\x1b\[\?47[hl]|\x1b\[1049[hl]/;
+/** 检测 ncurses/vim/top 等全屏刷新常用的光标定位与清屏序列 */
+function containsTuiRefreshSequence(data) {
+	return TUI_REFRESH_PATTERN.test(data);
+}
+var FULL_SCREEN_CLEAR_PATTERN = /\x1b\[[0-9;]*2J|\x1b\[[0-9;]*3J/;
+/** 全屏清屏（top/vim 新一轮绘制常见） */
+function containsFullScreenClear(data) {
+	return FULL_SCREEN_CLEAR_PATTERN.test(data);
+}
+/**
+* 在本地解析层重置滚动边距等模式（不发给 PTY）。
+* 仅在全屏清屏等明确「新一轮绘制」时调用，避免打断进行中的 TUI 光标位置。
+*/
+function resetLocalTerminalModes(terminal) {
+	terminal.write("\x1B[r");
+}
+function snapTerminalViewportToBottom(terminal) {
+	terminal.scrollToBottom();
+}
+/** 处理 PTY 写入前的视口/模式准备（不移动写入光标，避免输入错位） */
+function prepareTerminalForPtyWrite(terminal, data) {
+	if (containsFullScreenClear(data)) {
+		resetLocalTerminalModes(terminal);
+		return;
+	}
+	const buffer = terminal.buffer.active;
+	if (buffer.viewportY < buffer.baseY) snapTerminalViewportToBottom(terminal);
+}
+function isMacPlatform() {
+	if (typeof navigator === "undefined") return false;
+	return /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+}
+/** 菜单/文档展示的修饰键标签 */
+function terminalShortcutLabel(key) {
+	return isMacPlatform() ? `⌘${key}` : `Ctrl+${key}`;
+}
+/** ANSI 16 色演示文本 */
+function buildAnsiColorDemo() {
+	const names = [
+		"black",
+		"red",
+		"green",
+		"yellow",
+		"blue",
+		"magenta",
+		"cyan",
+		"white"
+	];
+	const rows = [0, 1].map((row) => {
+		const base = row === 0 ? 30 : 90;
+		let line = "";
+		for (let i = 0; i < 8; i += 1) line += `\x1b[${base + i}m ${names[i].padEnd(8)} \x1b[0m`;
+		return line;
+	});
+	let gradient = "";
+	for (let i = 16; i < 52; i += 1) gradient += `\x1b[48;5;${i}m \x1b[0m`;
+	return `${[
+		"\x1B[1mANSI 16 colors\x1B[0m",
+		...rows,
+		"",
+		"\x1B[1mStyles\x1B[0m  \x1B[1mbold\x1B[0m  \x1B[3mitalic\x1B[0m  \x1B[4munderline\x1B[0m  \x1B[9mstrikethrough\x1B[0m",
+		"",
+		"\x1B[38;5;196m256-color\x1B[0m sample:",
+		gradient
+	].join("\r\n")}\r\n`;
+}
+//#endregion
+export { buildAnsiColorDemo, containsEscapeSequence, containsFullScreenClear, containsTuiRefreshSequence, getTerminalThemePalette, isMacPlatform, mergeTerminalTheme, normalizeTerminalHexColor, prepareTerminalForPtyWrite, readTerminalThemeFromCss, resetLocalTerminalModes, resolveCssColorForXterm, resolveTerminalTheme, snapTerminalViewportToBottom, terminalShortcutLabel };

package/dist/components/terminal-wheel.d.ts

@@ -0,0 +1,24 @@
+import type { Terminal } from '@xterm/xterm';
+export type RsTerminalWheelScrollModifier = 'none' | 'shift';
+/** 视口是否已滚入 scrollback（非底部跟随） */
+export declare function isTerminalViewportScrolledUp(terminal: Terminal): boolean;
+export declare function isAlternateTerminalBuffer(terminal: Terminal | null | undefined): boolean;
+/**
+ * shift：仅全屏 TUI（备用屏，vim/top/less）把滚轮转成方向键；
+ * 普通 shell 必须滚 scrollback，否则 bash/zsh 会当成历史命令。
+ */
+export declare function shouldConvertWheelToArrowKeys(options: {
+    modifier: RsTerminalWheelScrollModifier;
+    shiftKey: boolean;
+    alternateBuffer: boolean;
+}): boolean;
+/**
+ * 滚轮策略：shell 里滚历史缓冲；仅备用屏才把滚轮发给 PTY。
+ * 按住 Shift 时始终原生滚动。
+ */
+export declare function attachWheelScrollGuard(hostEl: HTMLElement, options: {
+    modifier: () => RsTerminalWheelScrollModifier;
+    inputEnabled: () => boolean;
+    onArrowKeys: (data: string) => void;
+    isAlternateBuffer?: () => boolean;
+}): () => void;

package/dist/components/terminal-wheel.js

@@ -0,0 +1,42 @@
+//#region src/components/terminal-wheel.ts
+function isAlternateTerminalBuffer(terminal) {
+	return terminal?.buffer.active.type === "alternate";
+}
+/**
+* shift：仅全屏 TUI（备用屏，vim/top/less）把滚轮转成方向键；
+* 普通 shell 必须滚 scrollback，否则 bash/zsh 会当成历史命令。
+*/
+function shouldConvertWheelToArrowKeys(options) {
+	if (options.shiftKey || options.modifier === "none") return false;
+	return options.alternateBuffer;
+}
+/**
+* 滚轮策略：shell 里滚历史缓冲；仅备用屏才把滚轮发给 PTY。
+* 按住 Shift 时始终原生滚动。
+*/
+function attachWheelScrollGuard(hostEl, options) {
+	const viewport = hostEl.querySelector(".xterm-scrollable-element") ?? hostEl.querySelector(".xterm-viewport");
+	if (!viewport) return () => void 0;
+	const handler = (ev) => {
+		if (!shouldConvertWheelToArrowKeys({
+			modifier: options.modifier(),
+			shiftKey: ev.shiftKey,
+			alternateBuffer: options.isAlternateBuffer?.() ?? false
+		})) return;
+		ev.preventDefault();
+		ev.stopImmediatePropagation();
+		if (!options.inputEnabled() || ev.deltaY === 0) return;
+		const steps = Math.min(5, Math.max(1, Math.round(Math.abs(ev.deltaY) / 40)));
+		const seq = ev.deltaY > 0 ? "\x1B[B" : "\x1B[A";
+		options.onArrowKeys(seq.repeat(steps));
+	};
+	viewport.addEventListener("wheel", handler, {
+		capture: true,
+		passive: false
+	});
+	return () => {
+		viewport.removeEventListener("wheel", handler, { capture: true });
+	};
+}
+//#endregion
+export { attachWheelScrollGuard, isAlternateTerminalBuffer, shouldConvertWheelToArrowKeys };

package/dist/components/time-picker-utils.d.ts

@@ -0,0 +1,51 @@
+export interface RsParsedTime {
+    hour: number;
+    minute: number;
+    second: number;
+}
+export interface RsTimeRangeValue {
+    start?: string;
+    end?: string;
+}
+export declare const EMPTY_TIME_RANGE: RsTimeRangeValue;
+export declare function scheduleAfterPaint(callback: () => void): () => void;
+export declare function rangeInclusive(max: number): number[];
+/** 时分秒列选项（value + 预格式化 label，避免模板内反复 padStart） */
+export interface RsTimeUnitOption {
+    value: number;
+    label: string;
+}
+/** 时间列单位 */
+export type RsTimeUnit = 'hour' | 'minute' | 'second';
+export declare function formatTimeUnitLabel(value: number): string;
+/** 小时列固定选项 00–23 */
+export declare const TIME_HOUR_OPTIONS: readonly RsTimeUnitOption[];
+/** 秒列固定选项 00–59 */
+export declare const TIME_SECOND_OPTIONS: readonly RsTimeUnitOption[];
+/** 按步进缓存分钟列选项，默认 step=1 为 00–59 */
+export declare function getTimeMinuteOptions(step?: number): readonly RsTimeUnitOption[];
+/**
+ * 将时间列滚到指定 value，只改容器 scrollTop。
+ * 避免 scrollIntoView 带动外层页面 / Popover 滚动。
+ */
+export declare function scrollTimeColumnToValue(container: HTMLElement | null | undefined, value: number): void;
+export declare function parseTimeValue(value?: string, withSeconds?: boolean): RsParsedTime | null;
+export declare function formatTimeParts(hour: number, minute: number, second?: number): string;
+export declare function formatTimeFromParts(hour: number, minute: number, second: number, withSeconds?: boolean): string;
+export declare function getCurrentTime(): RsParsedTime;
+export declare function formatTimeValue(value?: string): string;
+export declare function timeToSeconds(hour: number, minute: number, second?: number): number;
+export declare function parseTimeToSeconds(value: string, withSeconds?: boolean): number | null;
+export declare function isTimeWithinBounds(hour: number, minute: number, second: number, options?: {
+    minTime?: string;
+    maxTime?: string;
+    withSeconds?: boolean;
+}): boolean;
+export declare function isTimeRangeEmpty(value: RsTimeRangeValue): boolean;
+export declare function isTimeRangeOrdered(range: RsTimeRangeValue, withSeconds?: boolean): boolean;
+export declare function isTimeRangeOrderedValues(start: string, end: string, withSeconds?: boolean): boolean;
+export declare function pickEarlierTime(a?: string, b?: string, withSeconds?: boolean): string | undefined;
+export declare function pickLaterTime(a?: string, b?: string, withSeconds?: boolean): string | undefined;
+export declare function formatTimeRangeDisplay(range: RsTimeRangeValue, options?: {
+    separator?: string;
+}): string;