@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/story/views/story-list/__tests__/frozen-headers.test.tsx

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// story 列表吸附组头（任务 22）：旧「滚动容器外常驻冻结层」（固定 top 覆盖渲染、
+// threshold+1 容差、无顶出）已迁离，判定走共享 computeFrozenHeader——等价原生
+// sticky：活跃才渲染副本、被下个组头逐像素顶出、边界不留容差、满宽实色底色盒。
+// 公式本体在 list-kit/__tests__/frozen-header.test.ts 覆盖；此处断言 story 接线
+// （jsdom：行高走 estimateSize 精确值，scrollTop 直写 + rAF 节流，bug 同款）。
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render, fireEvent, cleanup, act } from "@testing-library/react";
+
+// createServerFn 需 tanstackStart 插件编译（vitest 无该插件），显式空实现保模块求值
+vi.mock("@/server/serverFns/story", () => ({
+  createStoryFn: vi.fn(),
+  bulkArchiveStoriesFn: vi.fn(),
+  bulkDeleteStoriesFn: vi.fn(),
+  bulkUpdateStoriesFn: vi.fn(),
+  reorderStoriesFn: vi.fn(),
+}));
+vi.mock("../row", () => ({ StoryListRow: () => null }));
+vi.mock("../batch-toolbar", () => ({ BatchToolbar: () => null }));
+vi.mock("../../inline-story-creator", () => ({
+  InlineStoryCreator: () => null,
+}));
+
+import { StoryList } from "../index";
+import { DEFAULT_DISPLAY_OPTIONS } from "@/shared/list-kit/display-values";
+import type { PagedGroupNode } from "../../../display/use-paged-story-groups";
+import type { StoryListItem } from "@/shared/story/types";
+
+const testUser = {
+  id: "u1",
+  username: "alice",
+  email: "alice@example.com",
+  avatarConfig: null,
+  bgShape: null,
+  bgColor: null,
+};
+
+function makeStory(id: string): StoryListItem {
+  return {
+    id,
+    identifier: "STORY-1",
+    name: `需求 ${id}`,
+    description: null,
+    state: "todo",
+    priority: "none",
+    archived: false,
+    startDate: null,
+    targetDate: null,
+    boardOrder: 0,
+    projectId: "p1",
+    parentId: null,
+    parent: null,
+    assignee: null,
+    createdBy: testUser,
+    labels: [],
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+/** 双层分组夹具（estimateSize 估高：header/subHeader 36、story 44、tail 40）：
+ *   0 G1(待处理)          0
+ *   1 S(严重)             36
+ *   2 story s1            72
+ *   3 tail               116
+ *   4 S(较低)            156
+ *   5 story s2           192
+ *   6 tail               236
+ *   7 G2(已修复)         276
+ *   8 S(严重)            312
+ *   9 story s3           356
+ *  10 tail               400 */
+const groups: PagedGroupNode[] = [
+  {
+    key: "todo",
+    label: "待处理",
+    totalCount: 2,
+    items: [makeStory("s1"), makeStory("s2")],
+    subGroups: [
+      { key: "high", label: "严重", totalCount: 1, items: [makeStory("s1")] },
+      { key: "low", label: "较低", totalCount: 1, items: [makeStory("s2")] },
+    ],
+  },
+  {
+    key: "done",
+    label: "已修复",
+    totalCount: 1,
+    items: [makeStory("s3")],
+    subGroups: [{ key: "high", label: "严重", totalCount: 1, items: [makeStory("s3")] }],
+  },
+];
+
+const baseProps = {
+  groups,
+  displayFilters: DEFAULT_DISPLAY_OPTIONS,
+  users: [],
+  labels: [],
+  projects: [],
+  onRefresh: () => {},
+  onPatchStory: () => {},
+  onOpenStory: () => {},
+};
+
+const frozenLayer = (container: HTMLElement) =>
+  container.querySelector<HTMLElement>('[data-slot="story-frozen-headers"]');
+
+async function scrollStoryList(container: HTMLElement, top: number) {
+  const el = container.querySelector<HTMLElement>(".overflow-auto");
+  if (!el) throw new Error("scroll container not found");
+  Object.defineProperty(el, "scrollTop", { configurable: true, value: top });
+  await act(async () => {
+    fireEvent.scroll(el);
+    // 组件内 rAF 节流：排进同帧队列，等下一帧回调执行完
+    await new Promise((r) => requestAnimationFrame(r));
+  });
+}
+
+describe("StoryList 吸附组头（共享 computeFrozenHeader）", () => {
+  afterEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+  });
+
+  it("首屏即吸附（首个组头容器坐标恰为 0）：主/子双层满宽实色底色盒 offset 0", () => {
+    const { container } = render(<StoryList {...baseProps} />);
+    const layer = frozenLayer(container);
+    expect(layer).toBeTruthy();
+    const bands = layer!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands.length).toBe(2);
+    // 子组头带在下（top 36 = HEADER_ROW_HEIGHT）、主组头带在上（top 0）
+    expect(bands[0]!.textContent).toContain("严重");
+    expect(bands[0]!.style.transform).toBe("translateY(0px)");
+    expect(bands[0]!.style.top).toBe("36px");
+    expect(bands[1]!.textContent).toContain("待处理");
+    expect(bands[1]!.style.transform).toBe("translateY(0px)");
+    // 满宽实色底色盒（与在流行/组头 sticky 变体同源，任务 22 单一来源）
+    expect(bands[0]!.className).toContain("bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]");
+    expect(bands[1]!.className).toContain("bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]");
+  });
+
+  it("下个组头逼近：主组头被顶出负值、子组头随区段结束滑出", async () => {
+    const { container } = render(<StoryList {...baseProps} />);
+    await scrollStoryList(container, 275);
+    const bands = frozenLayer(container)!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands[1]!.textContent).toContain("待处理");
+    expect(bands[1]!.style.transform).toBe("translateY(-35px)");
+    expect(bands[0]!.textContent).toContain("较低");
+    expect(bands[0]!.style.transform).toBe("translateY(-71px)");
+  });
+
+  it("组切换边界零跳变：新组头 offset 0 就位，子组头切换为新组首个子组", async () => {
+    const { container } = render(<StoryList {...baseProps} />);
+    await scrollStoryList(container, 276);
+    const bands = frozenLayer(container)!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands[1]!.textContent).toContain("已修复");
+    expect(bands[1]!.style.transform).toBe("translateY(0px)");
+    expect(bands[0]!.textContent).toContain("严重");
+    expect(bands[0]!.style.transform).toBe("translateY(0px)");
+  });
+
+  it("子组头被下个同级子组头顶出（组内滚动）", async () => {
+    const { container } = render(<StoryList {...baseProps} />);
+    await scrollStoryList(container, 100);
+    const bands = frozenLayer(container)!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands[1]!.textContent).toContain("待处理");
+    expect(bands[1]!.style.transform).toBe("translateY(0px)");
+    expect(bands[0]!.textContent).toContain("严重");
+    expect(bands[0]!.style.transform).toBe("translateY(-16px)");
+  });
+});

package/src/components/story/views/story-list/group.tsx

@@ -53,6 +53,17 @@ interface VirtualGroupHeaderProps {
   showRoleLabel: boolean;
 }
 
+/**
+ * 组头吸附层底色单一来源（任务 22）：在流行（index.tsx 虚拟化行 wrapper）、
+ * 吸附层满宽底色盒与 VirtualGroupHeader 的 sticky 变体三处共用，防漂移。
+ * 必须是实色（color-mix 两实色变量）：吸附层要完全遮挡其下滚动的行，
+ * 半透明底会透出下层内容（AGENTS.md「底色 columnSurface 单一来源」同规）。
+ */
+export const groupHeaderSurfaceClass = (depth: number) =>
+  depth === 0
+    ? "bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]"
+    : "bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]";
+
 export const VirtualGroupHeader = memo(function VirtualGroupHeader({ node, depth, collapsed, collapseKey, onToggle, onCreate, onRetry, sticky, hideCreate, selectState, onToggleSelect, showSelect, groupDimension, showRoleLabel }: VirtualGroupHeaderProps) {
   const textColor =
     node.color?.split(" ").find((c) => c.startsWith("text")) ?? "text-muted-foreground";
@@ -63,7 +74,7 @@ export const VirtualGroupHeader = memo(function VirtualGroupHeader({ node, depth
     : undefined;
 
   return (
-    <div className={cn("flex h-full items-center", sticky ? (depth === 0 ? "bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]" : "bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]") : depth === 0 ? "bg-muted/50" : "bg-muted/35", depth > 0 && "pl-4")}>
+    <div className={cn("flex h-full items-center", sticky ? groupHeaderSurfaceClass(depth) : depth === 0 ? "bg-muted/50" : "bg-muted/35", depth > 0 && "pl-4")}>
       {showSelect && (
         <Checkbox
           checked={selectState === true}

package/src/components/story/views/story-list/index.tsx

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
-import { defaultRangeExtractor, useVirtualizer } from "@tanstack/react-virtual";
+import { useVirtualizer } from "@tanstack/react-virtual";
 import { Plus } from "lucide-react";
 import {
   createStoryFn,
@@ -31,10 +31,13 @@ import type { StoryState, StoryPriority } from "@/shared/story/constants";
 import type { DisplayOptions } from "../../display/types";
 import type { PagedGroupNode } from "../../display/use-paged-story-groups";
 import { BUTTON_ROW_HEIGHT, useFlatRows } from "./use-flat-rows";
-import { VirtualGroupHeader, GroupTailRow } from "./group";
+import { VirtualGroupHeader, GroupTailRow, groupHeaderSurfaceClass } from "./group";
 import { StoryListRow } from "./row";
 import { BatchToolbar } from "./batch-toolbar";
-import { computeFrozenHeader, type FrozenHeader } from "@/components/shared-kit/list-kit/frozen-header";
+// 任务 22：吸附组头判定统一走共享 computeFrozenHeader（等价原生 sticky：
+// 活跃才渲染副本、被下个组头逐像素顶出、边界不留容差），替代旧的
+// 「滚动容器外常驻冻结层」（固定 top、无顶出、threshold+1 容差——违规存量）。
+import { computeFrozenHeader, type FrozenHeaderResult } from "@/components/shared-kit/list-kit/frozen-header";
 import { computeMove, canMove } from "@/components/shared-kit/list-kit/move";
 import { computeGroupCheckState, toggleGroupSelection } from "./group-select";
 import { GROUP_FIELD, toGroupFieldPatch, type GroupField, type StoryPatch } from "../../display/group-fields";
@@ -43,6 +46,7 @@ import { WavePhysicsLoader } from "@/components/shared-kit/loading/wave-physics-
 import { useDeferredFlag } from "@/components/shared-kit/loading/use-deferred-flag";
 import { m } from "@/paraglide/messages.js";
 import { toastError } from "@/lib/toast-error";
+import { cn } from "@/lib/utils";
 
 const HEADER_ROW_HEIGHT = 36;
 const STORY_ROW_HEIGHT = 44;
@@ -148,12 +152,13 @@ export function StoryList({ groups, isLoading = false, displayFilters, users, la
   }, [groupBy, subGroupBy, onRefresh, projectId]);
 
   const scrollRef = useRef<HTMLDivElement>(null);
-  // 冻结组头渲染在滚动容器外层（容器外天然不受横滚影响），位置固定（组头 top:0、
-  // 子组头 top:36），滚动时唯一变化的是「当前活跃组头索引」——仅在跨越分组边界时改变。
-  // 因此不存每帧变化的 scrollTop，只存派生结果，并用 ref 去重：组内连续滚动零 setState
-  // → 零整表重渲染，仅跨边界帧更新一次。
-  const [frozenHeader, setFrozenHeader] = useState<FrozenHeader | null>(null);
-  const frozenHeaderRef = useRef<FrozenHeader | null>(null);
+  // 吸附组头（任务 22 前为滚动容器外常驻冻结层）：computeFrozenHeader 派生活跃
+  // （主/子）组头及顶出位移。副本仍渲染在滚动容器外层（容器外天然不受横滚影响），
+  // 但仅在组头越过吸附位后才出现，并被下一个组头逐像素顶出——与原生 sticky 等价。
+  // 不存每帧变化的 scrollTop，只存派生结果（index+offset 双值），ref 去重：
+  // 组内连续滚动零 setState → 零整表重渲染，仅顶出/切换帧更新。
+  const [frozen, setFrozen] = useState<FrozenHeaderResult | null>(null);
+  const frozenRef = useRef<FrozenHeaderResult | null>(null);
   const frozenRafRef = useRef<number | null>(null);
   // 滚动层纵向滚动条占位宽：冻结层右缘对齐滚动层可视右缘（非卡片右缘），
   // 否则冻结层加号比原位组头加号（sticky right-0 钉滚动条内侧）偏右一个滚动条宽。
@@ -371,8 +376,6 @@ export function StoryList({ groups, isLoading = false, displayFilters, users, la
     return map;
   }, [flatRows]);
 
-  const activeStickyRef = useRef<{ groupIdx: number; subIdx: number | null }>({ groupIdx: 0, subIdx: null });
-
   const estimateSize = useCallback((i: number) => {
     const row = flatRows[i];
     if (!row) return HEADER_ROW_HEIGHT;
@@ -386,46 +389,40 @@ export function StoryList({ groups, isLoading = false, displayFilters, users, la
     getScrollElement: () => scrollRef.current,
     estimateSize,
     overscan: OVERSCAN,
-    rangeExtractor: useCallback(
-      (range) => {
-        const activeGroupIdx = [...groupHeaderIndexes].reverse().find((i) => range.startIndex >= i);
-        let activeSubIdx: number | null = null;
-        if (activeGroupIdx != null) {
-          const candidate = [...subGroupHeaderIndexes].reverse().find((i) => i <= range.startIndex);
-          if (candidate != null && parentGroupOfSub.get(candidate) === activeGroupIdx) {
-            activeSubIdx = candidate;
-          }
-        }
-        activeStickyRef.current = { groupIdx: activeGroupIdx ?? 0, subIdx: activeSubIdx };
-        const idx = new Set(defaultRangeExtractor(range));
-        if (activeGroupIdx != null) idx.add(activeGroupIdx);
-        if (activeSubIdx != null) idx.add(activeSubIdx);
-        return [...idx].sort((a, b) => a - b);
-      },
-      [groupHeaderIndexes, subGroupHeaderIndexes, parentGroupOfSub],
-    ),
+    // 任务 22：不再用 rangeExtractor 强留活跃组头行——吸附层从 flatRows 数据直接
+    // 渲染（与 kanban 同构），在流行按虚拟窗口自然进出（越顶的活跃行被吸附副本遮挡）
     enabled: flatRows.length > 0,
   });
   const virtualRows = rowVirtualizer.getVirtualItems();
   const totalHeight = rowVirtualizer.getTotalSize();
   const remeasureRows = useCallback(() => rowVirtualizer.measure(), [rowVirtualizer]);
 
-  // 冻结组头派生：读取当前滚动位置算出活跃（主/子）组头，仅在结果变化时提交 state
+  // 吸附组头派生：读取当前滚动位置算出活跃（主/子）组头与顶出位移，仅在结果
+  // （index+offset 双值）变化时提交 state
   const recomputeFrozenHeader = useCallback(() => {
     frozenRafRef.current = null;
     const el = scrollRef.current;
     if (!el) return;
-    const next = computeFrozenHeader(
-      el.scrollTop,
-      rowVirtualizer.measurementsCache,
-      groupHeaderIndexes,
-      subGroupHeaderIndexes,
+    const next = computeFrozenHeader(el.scrollTop, rowVirtualizer.measurementsCache, {
+      groupIndexes: groupHeaderIndexes,
+      subIndexes: subGroupHeaderIndexes,
       parentGroupOfSub,
-    );
-    const prev = frozenHeaderRef.current;
-    if (prev?.groupIdx === next?.groupIdx && prev?.subIdx === next?.subIdx) return;
-    frozenHeaderRef.current = next;
-    setFrozenHeader(next);
+      // 滚动容器 overflow-auto 无上内边距：测量原点 = 滚动口顶
+      pad: 0,
+      // 子组头吸附在吸附主组头正下方（组头行高 36）
+      subPinTop: HEADER_ROW_HEIGHT,
+    });
+    const prev = frozenRef.current;
+    if (
+      prev?.group?.index === next.group?.index &&
+      prev?.group?.offset === next.group?.offset &&
+      prev?.sub?.index === next.sub?.index &&
+      prev?.sub?.offset === next.sub?.offset
+    ) {
+      return;
+    }
+    frozenRef.current = next;
+    setFrozen(next);
   }, [rowVirtualizer, groupHeaderIndexes, subGroupHeaderIndexes, parentGroupOfSub]);
 
   // rAF 节流：每帧最多重算一次（滚动事件可能一帧多次触发）
@@ -467,7 +464,7 @@ export function StoryList({ groups, isLoading = false, displayFilters, users, la
         <div
           key={row.key}
           style={{ ...baseStyle, height: HEADER_ROW_HEIGHT }}
-          className={`flex ${row.depth === 0 ? "bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]" : "bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]"}`}
+          className={cn("flex", groupHeaderSurfaceClass(row.depth))}
         >
           <div className="sticky left-0 h-full w-fit">
             <VirtualGroupHeader
@@ -546,31 +543,27 @@ export function StoryList({ groups, isLoading = false, displayFilters, users, la
     return null;
   };
 
-  const renderFrozenHeader = (idx: number, top: number, depth: number, zIndex: number) => {
+  // 吸附层组头内容渲染：与在流组头同一渲染单元（VirtualGroupHeader 同 props 形态，
+  // sticky 实色变体），保证吸附态与在流态视觉与交互完全一致（kanban renderSubHeaderButton 同规）
+  const renderFrozenHeaderRow = (idx: number, depth: 0 | 1) => {
     const row = flatRows[idx];
     if (!row || row.kind !== "header") return null;
     return (
-      <div
-        key={row.key}
-        className="absolute overflow-hidden"
-        style={{ top, left: 0, right: scrollbarW, zIndex, height: HEADER_ROW_HEIGHT }}
-      >
-        <VirtualGroupHeader
-          node={row.node}
-          onRetry={onRefresh}
-          depth={row.depth}
-          collapsed={row.isCollapsed}
-          collapseKey={row.key}
-          onCreate={onCreateByKey.get(row.node.key)}
-          onToggle={toggleCollapse}
-          sticky
-          selectState={computeGroupCheckState(groupStoryIds.get(row.key) ?? [], selectedIds)}
-          onToggleSelect={() => toggleGroup(row.key)}
-          showSelect={selectedIds.size > 0}
-          groupDimension={depth === 0 ? groupBy : subGroupBy}
-          showRoleLabel={showRoleLabel}
-        />
-      </div>
+      <VirtualGroupHeader
+        node={row.node}
+        onRetry={onRefresh}
+        depth={row.depth}
+        collapsed={row.isCollapsed}
+        collapseKey={row.key}
+        onCreate={onCreateByKey.get(row.node.key)}
+        onToggle={toggleCollapse}
+        sticky
+        selectState={computeGroupCheckState(groupStoryIds.get(row.key) ?? [], selectedIds)}
+        onToggleSelect={() => toggleGroup(row.key)}
+        showSelect={selectedIds.size > 0}
+        groupDimension={depth === 0 ? groupBy : subGroupBy}
+        showRoleLabel={showRoleLabel}
+      />
     );
   };
 
@@ -587,11 +580,51 @@ export function StoryList({ groups, isLoading = false, displayFilters, users, la
           </div>
         )}
       </div>
-      {frozenHeader && (
-        <>
-          {frozenHeader.subIdx != null && renderFrozenHeader(frozenHeader.subIdx, HEADER_ROW_HEIGHT, 1, 9)}
-          {renderFrozenHeader(frozenHeader.groupIdx, 0, 0, 10)}
-        </>
+      {/* 吸附组头副本（任务 22，替代旧常驻冻结层）：仅在组头越过吸附位后渲染
+          （computeFrozenHeader），并被下一个组头逐像素顶出（translateY 负值），
+          与原生 sticky 等价。结构照 kanban 吸附层同款：
+          - 外层 pointer-events-none + overflow-hidden：顶出越界部分裁在滚动口顶
+          - 满宽实色底色盒（groupHeaderSurfaceClass，与在流行同源）无纵向内边距
+            ——纵向范围 = 组头行自身盒子（高 HEADER_ROW_HEIGHT），多留内边距会把
+            紧邻首行顶部一起盖住；上方无需遮挡带（未越过时本层根本不渲染）
+          - 内容包 pointer-events-auto：组头可点（折叠/勾选/创建），带外点击穿透
+          - right 预留纵向滚动条宽：与在流组头 sticky right-0 加号对齐
+          - 子组头层在下、主组头层在上（z 9/10）：组切换顶出阶段两层同带滑出，
+            露出主组头（旧常驻层 z 序，行为保持） */}
+      {frozen && (frozen.group || frozen.sub) && (
+        <div
+          data-slot="story-frozen-headers"
+          className="pointer-events-none absolute inset-0 z-10 overflow-hidden"
+          style={{ right: scrollbarW }}
+        >
+          {frozen.sub && (
+            <div
+              className={cn("absolute inset-x-0 z-[9]", groupHeaderSurfaceClass(1))}
+              style={{
+                top: HEADER_ROW_HEIGHT,
+                height: HEADER_ROW_HEIGHT,
+                transform: `translateY(${frozen.sub.offset}px)`,
+              }}
+            >
+              <div className="pointer-events-auto h-full">
+                {renderFrozenHeaderRow(frozen.sub.index, 1)}
+              </div>
+            </div>
+          )}
+          {frozen.group && (
+            <div
+              className={cn("absolute inset-x-0 top-0 z-10", groupHeaderSurfaceClass(0))}
+              style={{
+                height: HEADER_ROW_HEIGHT,
+                transform: `translateY(${frozen.group.offset}px)`,
+              }}
+            >
+              <div className="pointer-events-auto h-full">
+                {renderFrozenHeaderRow(frozen.group.index, 0)}
+              </div>
+            </div>
+          )}
+        </div>
       )}
         {!isLoading && groups.length === 0 && (
           <div className="flex h-40 items-center justify-center text-sm text-muted-foreground">

package/src/components/testcase/__tests__/case-row.test.tsx

@@ -28,8 +28,12 @@ vi.mock("@tanstack/react-start", () => ({
   useServerFn: (fn: unknown) => fn,
 }));
 
-// 虚拟化桩：默认全量 items（断言行渲染契约）；窗口化测试置 stub=false 走真实实现
-const virtualState = vi.hoisted(() => ({ stub: true }));
+// 虚拟化桩：默认全量 items（断言行渲染契约）；窗口化测试置 stub=false 走真实实现。
+// scrollToIndex 桩透传 virtualState.scrollToIndex（默认 no-op），供 ↑↓ 定位断言注入。
+const virtualState = vi.hoisted(() => ({
+  stub: true,
+  scrollToIndex: null as null | ((index: number, options?: { align?: string }) => void),
+}));
 vi.mock("@tanstack/react-virtual", async (importOriginal) => {
   const actual = await importOriginal<typeof import("@tanstack/react-virtual")>();
   return {
@@ -46,6 +50,8 @@ vi.mock("@tanstack/react-virtual", async (importOriginal) => {
             })),
           getTotalSize: () => opts.count * 44,
           measure: () => {},
+          scrollToIndex: (index: number, options?: { align?: string }) =>
+            virtualState.scrollToIndex?.(index, options),
         };
       }
       return actual.useVirtualizer(opts);
@@ -164,6 +170,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   updateTestCaseFn.mockResolvedValue({ ...baseCase });
   intersectionFire = null;
+  virtualState.scrollToIndex = null;
   vi.stubGlobal("IntersectionObserver", MockIntersectionObserver);
 });
 
@@ -447,6 +454,39 @@ describe("GroupedList 分组虚拟列表", () => {
     expect(onSelect).toHaveBeenLastCalledWith("c1");
   });
 
+  it("↑↓ 定位行走 scrollToIndex（任务 21）：选中照旧，定位传扁平行 index（含组头偏移）+ align auto", () => {
+    const onSelect = vi.fn();
+    const scrollToIndex = vi.fn();
+    virtualState.scrollToIndex = scrollToIndex;
+    // groupBy none：扁平行 = 用例行，c2 的 flat index = 1
+    renderList({ selectedId: "c1", onSelect });
+    const scrollEl = screen.getByTestId("grouped-list-scroll");
+    fireEvent.keyDown(scrollEl, { key: "ArrowDown" });
+    expect(onSelect).toHaveBeenLastCalledWith("c2");
+    expect(scrollToIndex).toHaveBeenLastCalledWith(1, { align: "auto" });
+    fireEvent.keyDown(scrollEl, { key: "ArrowUp" });
+    expect(scrollToIndex).toHaveBeenLastCalledWith(0, { align: "auto" });
+    // 首行上移保持：选中停在 c1，仍定位 index 0
+    fireEvent.keyDown(scrollEl, { key: "ArrowUp" });
+    expect(scrollToIndex).toHaveBeenLastCalledWith(0, { align: "auto" });
+  });
+
+  it("↑↓ 定位 flat index 含组头偏移：groupBy state 下目标行 index 计入其组头", () => {
+    const onSelect = vi.fn();
+    const scrollToIndex = vi.fn();
+    virtualState.scrollToIndex = scrollToIndex;
+    const groups: TestCaseGroupInfo[] = [
+      { key: "approved", label: "approved", count: 2 },
+      { key: "draft", label: "draft", count: 1 },
+    ];
+    // 扁平顺序：header(approved)=0, c1=1, c3=2, header(draft)=3, c2=4
+    // caseIds=[c1,c3,c2]；从 c3 下移到 c2：caseIds index 2 ≠ flat index 4（差两个组头）
+    renderList({ groupBy: "state", groups, selectedId: "c3", onSelect });
+    fireEvent.keyDown(screen.getByTestId("grouped-list-scroll"), { key: "ArrowDown" });
+    expect(onSelect).toHaveBeenLastCalledWith("c2");
+    expect(scrollToIndex).toHaveBeenLastCalledWith(4, { align: "auto" });
+  });
+
   it("窗口化渲染计数断言（1k 性能口径替代）：真实虚拟化下 DOM 行数远小于总行数", () => {
     virtualState.stub = false;
     // virtual-core 的 getRect 读视口尺寸（非 gBCR）：3.19.5 及以前读 offsetWidth/
@@ -484,4 +524,96 @@ describe("GroupedList 分组虚拟列表", () => {
       virtualState.stub = true;
     }
   });
+
+  it("定位行虚拟窗口外一步到位（任务 21 验收，旧 querySelector 实现在此静默失效）：scrollToIndex 按测量值写 scrollTop", () => {
+    virtualState.stub = false;
+    let fireResize: () => void = () => {};
+    class CapturableResizeObserver {
+      constructor(cb: ResizeObserverCallback) {
+        fireResize = () => cb([], this as unknown as ResizeObserver);
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    }
+    vi.stubGlobal("ResizeObserver", CapturableResizeObserver);
+    try {
+      const big = Array.from({ length: 1000 }, (_, i) =>
+        makeCase({ id: `c${i}`, identifier: `PERF-TC${i + 1}` }),
+      );
+      const { container } = render(<GroupedList groupBy="none" groups={[]} cases={big} folders={folders} users={users} hasMore={false} selectedId="c799" onSelect={vi.fn()} onPatchCase={vi.fn()} onLoadMore={vi.fn()} />);
+      const scrollEl = container.querySelector<HTMLElement>('[data-testid="grouped-list-scroll"]')!;
+      Object.defineProperty(scrollEl, "offsetHeight", { configurable: true, value: 600 });
+      Object.defineProperty(scrollEl, "offsetWidth", { configurable: true, value: 800 });
+      Object.defineProperty(scrollEl, "clientHeight", { configurable: true, value: 600 });
+      Object.defineProperty(scrollEl, "clientWidth", { configurable: true, value: 800 });
+      // scrollPaddingStart 落点会被 getMaxScrollOffset（scrollHeight − clientHeight）钳制，
+      // jsdom 无布局 scrollHeight 恒 0——注入内容总高，令钳制上限真实（44000 − 600）
+      Object.defineProperty(scrollEl, "scrollHeight", { configurable: true, value: big.length * 44 });
+      // jsdom 无 Element.scrollTo（virtual-core elementScroll 静默 no-op）：桩捕获 scrollTop 写入
+      //（scrollTo 带 (x, y) 重载，桩按 options 签名注入需收窄赋值）
+      const scrollToSpy = vi.fn<(options?: ScrollToOptions) => void>();
+      scrollEl.scrollTo = scrollToSpy as unknown as typeof scrollEl.scrollTo;
+      act(() => {
+        fireResize();
+      });
+      // 前置：目标行 c800（flat index 800）在窗口外，DOM 节点不存在——
+      // 旧实现 querySelector 命中 null 即失效，新实现不依赖 DOM 节点
+      expect(container.querySelector('[data-case-id="c800"]')).toBeNull();
+      const callsBefore = scrollToSpy.mock.calls.length;
+      fireEvent.keyDown(scrollEl, { key: "ArrowDown" });
+      // 一次 scrollTo 到位（无 rAF 二跳）：align auto 向下越界 → 行底对齐视口底
+      //（scrollPaddingEnd 0），top = 行 end − 视口高 = 801*44 − 600
+      expect(scrollToSpy.mock.calls.length).toBe(callsBefore + 1);
+      expect(scrollToSpy).toHaveBeenLastCalledWith({ top: 801 * 44 - 600, behavior: "auto" });
+    } finally {
+      virtualState.stub = true;
+    }
+  });
+
+  it("定位行窗口内零滚动（等价旧 nearest，裁决 T21-2）：行已可见时仅写当前 offset 无位移", () => {
+    virtualState.stub = false;
+    let fireResize: () => void = () => {};
+    class CapturableResizeObserver {
+      constructor(cb: ResizeObserverCallback) {
+        fireResize = () => cb([], this as unknown as ResizeObserver);
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    }
+    vi.stubGlobal("ResizeObserver", CapturableResizeObserver);
+    try {
+      const big = Array.from({ length: 1000 }, (_, i) =>
+        makeCase({ id: `c${i}`, identifier: `PERF-TC${i + 1}` }),
+      );
+      const onSelect = vi.fn();
+      const { container } = render(<GroupedList groupBy="none" groups={[]} cases={big} folders={folders} users={users} hasMore={false} selectedId="c29" onSelect={onSelect} onPatchCase={vi.fn()} onLoadMore={vi.fn()} />);
+      const scrollEl = container.querySelector<HTMLElement>('[data-testid="grouped-list-scroll"]')!;
+      Object.defineProperty(scrollEl, "offsetHeight", { configurable: true, value: 600 });
+      Object.defineProperty(scrollEl, "offsetWidth", { configurable: true, value: 800 });
+      Object.defineProperty(scrollEl, "clientHeight", { configurable: true, value: 600 });
+      Object.defineProperty(scrollEl, "clientWidth", { configurable: true, value: 800 });
+      Object.defineProperty(scrollEl, "scrollHeight", { configurable: true, value: big.length * 44 });
+      const scrollToSpy = vi.fn<(options?: ScrollToOptions) => void>();
+      scrollEl.scrollTo = scrollToSpy as unknown as typeof scrollEl.scrollTo;
+      act(() => {
+        fireResize();
+      });
+      // 模拟滚到 1000：jsdom 赋 scrollTop 不派发 scroll 事件，手动派发让 virtualizer 读回
+      scrollEl.scrollTop = 1000;
+      act(() => {
+        fireEvent.scroll(scrollEl);
+      });
+      const callsBefore = scrollToSpy.mock.calls.length;
+      // 目标行 c30 [1320, 1364] 完全落在可视区（顶部组头补偿线 1036 之下、视口底 1600 之上）：
+      // 旧 nearest 不滚动；auto 解析为当前 offset，写入无位移
+      fireEvent.keyDown(scrollEl, { key: "ArrowDown" });
+      expect(onSelect).toHaveBeenLastCalledWith("c30");
+      expect(scrollToSpy.mock.calls.length).toBe(callsBefore + 1);
+      expect(scrollToSpy).toHaveBeenLastCalledWith({ top: 1000, behavior: "auto" });
+    } finally {
+      virtualState.stub = true;
+    }
+  });
 });

package/src/components/testcase/__tests__/peek-panel.test.tsx

@@ -171,6 +171,14 @@ class MockIntersectionObserver {
   disconnect() {}
 }
 
+// useAppHotkeys 需要 HotkeysProvider appHotkeys 挂载；单测无全局 Provider，
+import { appHotkeys } from "@/lib/hotkeys/registry"
+// 局部替换该 hook 返回应用声明，其余（useHotkey/useHotkeys）保持官方真实实现
+vi.mock("@tanstack/react-hotkeys", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@tanstack/react-hotkeys")>()
+  return { ...actual, useAppHotkeys: () => appHotkeys }
+})
+
 import { TestCasePeekPanel } from "../peek-panel";
 import { TestCaseListView } from "../list-view";
 import type { TestCaseSummary } from "@/server/serverFns/testcase/types";