Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* useSidebarPeek —— 左侧栏「完全隐藏态 hover 临时浮出(peek)」状态机
* ---------------------------------------------------------------------------
* 侧栏被 ⌘B / 折叠按钮完全隐藏(w-0)后,鼠标悬停 ChromeActions 的折叠按钮
* (触发钮)时,侧栏以 fixed overlay 抽屉形式临时滑出预览完整列表;指针离开
* (既不在抽屉也不在触发钮上)后延迟收回;点击触发钮 / ⌘B = 固定展开(pin)。
* 仅作用于「完全隐藏」态;rail 窄轨(isCollapsed=false)不触发。
*
* 状态机(4 态,正常展开/收起仍由 Sidebar 的 CSS width transition 承担):
* idle → 无 peek(正常流内布局,含隐藏/rail/展开)
* peeking → fixed 抽屉滑入并停留
* peekClosing → fixed 抽屉滑出动画中(200ms 后落回 idle)
* pinning → peek 中被固定展开:抽屉 fixed 冻结,流内 spacer 跑宽度动画
* 推开主区,300ms 后一帧内交换回 static(消除 fixed→流内跳变)
*
* 关键机制:
* - hover intent:悬停触发钮 120ms 后才浮出,防手滑扫过误触;
* - hoverLock:任何收起动作(isCollapsed false→true)自动上锁,指针真正离开
* 过触发钮才解锁 —— 防止收起瞬间指针恰停在按钮上原地回弹 peek;
* - 收回双路径:抽屉 onMouseLeave(relatedTarget 是触发钮则不收)+ peeking 期
* 全局 pointermove 兜底(白名单含 Radix portal,否则抽屉内右键菜单/下拉
* 一开、指针落在 portal 上就会误判「已离开」把抽屉收走);
* - pin 统一入口:peek 中 isCollapsed 翻 false(点击/⌘B/菜单)一律进 pinning,
* 无特例分支;
* - 全部用 setTimeout 驱动、不依赖 transitionend —— reduced-motion 下动画
* 归零也不会卡死,且可用 fake timers 单测。
*/
import { useCallback, useEffect, useRef, useState } from 'react';
export type SidebarPeekState = 'idle' | 'peeking' | 'peekClosing' | 'pinning';
/** hover intent:悬停触发钮多久后浮出(对齐 useHoverOpenMenu 的量级)。 */
export const PEEK_OPEN_DELAY_MS = 120;
/** 指针离开抽屉/触发钮后的收回宽限(与 useHoverOpenMenu closeDelay 一致)。 */
export const PEEK_CLOSE_GRACE_MS = 160;
/** 滑出动画时长 —— 与 Sidebar.tsx peekClosing 的 duration-200 保持一致。 */
export const PEEK_CLOSE_ANIM_MS = 200;
/** pin 冻结时长 —— 覆盖流内 spacer 的 250ms 宽度动画 + 余量。 */
export const PEEK_PIN_FREEZE_MS = 300;
/** 全局 pointermove 兜底的「视为仍在 peek 交互内」白名单:抽屉、触发钮、
* Radix portal(右键菜单/下拉/hover 菜单)、对话框。 */
const PEEK_KEEPALIVE_SELECTOR =
'[data-sidebar-peek-drawer],[data-sidebar-peek-trigger],[data-radix-popper-content-wrapper],[role="dialog"]';
export interface SidebarPeekTriggerProps {
onMouseEnter: () => void;
onMouseLeave: () => void;
'data-sidebar-peek-trigger': string;
}
export interface SidebarPeekDrawerProps {
onMouseEnter: () => void;
onMouseLeave: (event: React.MouseEvent<HTMLElement>) => void;
'data-sidebar-peek-drawer': string;
}
export interface UseSidebarPeekOptions {
/** MainLayout 的持久化收起态(⌘B / 折叠按钮)。false 时 peek 永不触发。 */
isCollapsed: boolean;
/** 设置页等 Sidebar 不渲染的路由传 false —— 立即重置状态机。 */
enabled: boolean;
}
export interface UseSidebarPeekResult {
peekState: SidebarPeekState;
/** peeking | peekClosing | pinning —— Sidebar 需要以 fixed 抽屉渲染。 */
isPeekVisible: boolean;
/** 展开在 ChromeActions 折叠按钮上。 */
triggerProps: SidebarPeekTriggerProps;
/** 展开在 Sidebar 的 aside 上(仅 peek 可见期需要生效)。 */
drawerProps: SidebarPeekDrawerProps;
}
function eventTargetElement(target: EventTarget | null): Element | null {
if (target instanceof Element) return target;
if (target instanceof Node) return target.parentElement;
return null;
}
export function useSidebarPeek({ isCollapsed, enabled }: UseSidebarPeekOptions): UseSidebarPeekResult {
const [peekState, setPeekState] = useState<SidebarPeekState>('idle');
// hoverLock 用 state 而非 ref:锁定期要挂全局 pointermove 解锁监听(见下方 effect)。
const [hoverLocked, setHoverLocked] = useState(false);
// 事件回调/定时器回调里读取最新值,避免闭包陈旧。
const stateRef = useRef(peekState);
stateRef.current = peekState;
const isCollapsedRef = useRef(isCollapsed);
isCollapsedRef.current = isCollapsed;
const enabledRef = useRef(enabled);
enabledRef.current = enabled;
const hoverLockedRef = useRef(hoverLocked);
hoverLockedRef.current = hoverLocked;
const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
const closeGraceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
const closeAnimTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
const pinTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
const clearTimer = (ref: React.MutableRefObject<ReturnType<typeof setTimeout> | null>) => {
if (ref.current) {
clearTimeout(ref.current);
ref.current = null;
}
};
const clearAllTimers = useCallback(() => {
clearTimer(openTimer);
clearTimer(closeGraceTimer);
clearTimer(closeAnimTimer);
clearTimer(pinTimer);
}, []);
// 卸载时清掉挂起的定时器,避免对已卸载组件 setState。
useEffect(() => clearAllTimers, [clearAllTimers]);
/** 立即进入滑出动画(peekClosing),200ms 后落回 idle。 */
const beginClose = useCallback(() => {
if (stateRef.current !== 'peeking') return;
clearTimer(closeGraceTimer);
setPeekState('peekClosing');
closeAnimTimer.current = setTimeout(() => {
closeAnimTimer.current = null;
setPeekState('idle');
}, PEEK_CLOSE_ANIM_MS);
}, []);
/** 排一个收回宽限:160ms 内指针回到抽屉/触发钮会被取消。 */
const scheduleClose = useCallback(() => {
if (stateRef.current !== 'peeking') return;
if (closeGraceTimer.current) return;
closeGraceTimer.current = setTimeout(() => {
closeGraceTimer.current = null;
beginClose();
}, PEEK_CLOSE_GRACE_MS);
}, [beginClose]);
const cancelScheduledClose = useCallback(() => {
clearTimer(closeGraceTimer);
}, []);
const handleTriggerEnter = useCallback(() => {
if (!enabledRef.current || !isCollapsedRef.current || hoverLockedRef.current) return;
const state = stateRef.current;
if (state === 'peeking') {
// 已浮出:指针回到触发钮,取消排队中的收回即可。
cancelScheduledClose();
return;
}
if (state === 'pinning') return;
if (openTimer.current) return;
openTimer.current = setTimeout(() => {
openTimer.current = null;
// 120ms 后条件可能已变(被收起锁上/已 pin),重新校验。
if (!enabledRef.current || !isCollapsedRef.current || hoverLockedRef.current) return;
const current = stateRef.current;
if (current !== 'idle' && current !== 'peekClosing') return;
// 正在滑出时重新进入:掐掉收尾定时器直接回到 peeking(CSS transition 自然反向)。
clearTimer(closeAnimTimer);
setPeekState('peeking');
}, PEEK_OPEN_DELAY_MS);
}, [cancelScheduledClose]);
const handleTriggerLeave = useCallback(() => {
// 指针真正离开过触发钮 → 解除收起时上的 hover 锁(MivoCanvas 语义)。
setHoverLocked(false);
clearTimer(openTimer);
scheduleClose();
}, [scheduleClose]);
const handleDrawerEnter = useCallback(() => {
cancelScheduledClose();
}, [cancelScheduledClose]);
const handleDrawerLeave = useCallback(
(event: React.MouseEvent<HTMLElement>) => {
// 移向触发钮不算离开(抽屉与按钮之间有缝隙)。
const next = event.relatedTarget instanceof Element ? event.relatedTarget : null;
if (next?.closest('[data-sidebar-peek-trigger]')) return;
scheduleClose();
},
[scheduleClose],
);
// isCollapsed 翻转 —— peek 与「固定展开/收起」的汇合点:
// false→true(任何收起入口:折叠按钮 / ⌘B / 菜单):自动上 hover 锁;
// true→false 且 peek 可见中:统一视为 pin,进入 pinning 冻结过渡。
const prevCollapsedRef = useRef(isCollapsed);
useEffect(() => {
const prev = prevCollapsedRef.current;
prevCollapsedRef.current = isCollapsed;
if (prev === isCollapsed) return;
if (isCollapsed) {
setHoverLocked(true);
clearTimer(openTimer);
// 边界:pinning 冻结期又被立刻收起 —— 直接落回 idle,让 aside 回到 w-0。
if (stateRef.current === 'pinning') {
clearTimer(pinTimer);
setPeekState('idle');
}
return;
}
setHoverLocked(false);
const state = stateRef.current;
if (state === 'peeking' || state === 'peekClosing') {
clearAllTimers();
setPeekState('pinning');
pinTimer.current = setTimeout(() => {
pinTimer.current = null;
setPeekState('idle');
}, PEEK_PIN_FREEZE_MS);
}
}, [isCollapsed, clearAllTimers]);
// enabled 关闭(如进入设置页)→ 整体重置。
useEffect(() => {
if (enabled) return;
clearAllTimers();
setPeekState('idle');
setHoverLocked(false);
}, [enabled, clearAllTimers]);
// peeking 期全局 pointermove 兜底:指针落点不在白名单内 → 排收回;在 → 取消。
// 覆盖 mouseleave 收不到的路径(如指针快速跳过抽屉边缘、经由 portal 菜单绕出)。
useEffect(() => {
if (peekState !== 'peeking') return;
const onPointerMove = (event: PointerEvent) => {
const element = eventTargetElement(event.target);
if (element?.closest(PEEK_KEEPALIVE_SELECTOR)) {
cancelScheduledClose();
} else {
scheduleClose();
}
};
window.addEventListener('pointermove', onPointerMove, { passive: true });
return () => window.removeEventListener('pointermove', onPointerMove);
}, [peekState, cancelScheduledClose, scheduleClose]);
// peeking 期窗口失焦(⌘Tab 切走等收不到 mouseleave)→ 立即滑出。
useEffect(() => {
if (peekState !== 'peeking') return;
const onBlur = () => beginClose();
window.addEventListener('blur', onBlur);
return () => window.removeEventListener('blur', onBlur);
}, [peekState, beginClose]);
// hover 锁的第二条解锁路径:指针移动且落点不在触发钮上 → 解锁。
// 覆盖「⌘B 收起时指针根本不在按钮上」的情况(否则锁永远等不到 trigger mouseleave)。
useEffect(() => {
if (!hoverLocked) return;
const onPointerMove = (event: PointerEvent) => {
const element = eventTargetElement(event.target);
if (element?.closest('[data-sidebar-peek-trigger]')) return;
setHoverLocked(false);
};
window.addEventListener('pointermove', onPointerMove, { passive: true });
return () => window.removeEventListener('pointermove', onPointerMove);
}, [hoverLocked]);
return {
peekState,
isPeekVisible: peekState !== 'idle',
triggerProps: {
onMouseEnter: handleTriggerEnter,
onMouseLeave: handleTriggerLeave,
'data-sidebar-peek-trigger': 'true',
},
drawerProps: {
onMouseEnter: handleDrawerEnter,
onMouseLeave: handleDrawerLeave,
'data-sidebar-peek-drawer': 'true',
},
};
}