@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/bug/bug-list-view.tsx

@@ -17,18 +17,47 @@
 
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useNavigate } from "@tanstack/react-router";
+import { usePresenceListRefresh } from "@/lib/collab/use-presence-list-refresh";
+import { toastError } from "@/lib/toast-error";
+import { toast } from "@/components/ui/toast";
 import { BugToolbar, type BugFilters } from "./bug-toolbar";
 import { type FilterCondition } from "./filters";
 import { listUsersBriefFn } from "@/server/serverFns/story";
 import { listProjectsBriefFn } from "@/server/serverFns/project";
+import {
+  listBugViewsFn,
+  createBugViewFn,
+  updateBugViewFn,
+  deleteBugViewFn,
+  reorderBugsFn,
+} from "@/server/serverFns/bug";
 import type { UserBrief } from "@/components/story/types";
-import { usePagedBugGroups } from "./display/use-paged-bug-groups";
+import { usePagedBugGroups, type PagedBugGroupNode } from "./display/use-paged-bug-groups";
 import { useBugDisplayOptions } from "./display/use-bug-display-options";
+import type { BugGroupKey } from "./display/types";
+import type { PeekMode } from "@/components/shared-kit/peek/peek-mode";
 import { BugList } from "./views/bug-list";
-import { BugListTable } from "./bug-list-table";
+import { BugBoardView, type BugBoardGroupDimension } from "./views/board-view";
+import type { ReorderEntry } from "@/components/shared-kit/list-kit/kanban/drop-commit";
+import { manualOrderSwitchPatch } from "@/components/shared-kit/list-kit/kanban/manual-order";
+// 纯函数跨层复用（bug-group-query 运行时零服务端依赖，use-paged-bug-groups 同款先例）
+import { BUG_STATE_GROUP_KEYS, BUG_SEVERITY_GROUP_KEYS } from "@/server/serverFns/bug/bug-group-query";
+import type { BugListItem } from "./types";
 import { CreateBugDialog } from "./create-bug-dialog";
 import { BugPeekPanel } from "./peek-panel";
-import type { BugView } from "./views/view-switcher";
+import { CreateViewDialog, type CreateViewDialogPayload } from "./views/create-view-dialog";
+import {
+  DEFAULT_BUG_VIEW_ICON,
+  DEFAULT_VIEW_ID,
+  buildDefaultView,
+  isBugView,
+  toSavedView,
+  toViewFilters,
+  viewFiltersToConditions,
+  withViewIcon,
+  type BugView,
+  type BugViewModel,
+} from "./views/view-types";
 import { Button } from "@/components/ui/button";
 import { Bug as BugIcon } from "lucide-react";
 import { m } from "@/paraglide/messages.js";
@@ -41,6 +70,15 @@ interface BugListViewProps {
 
 const BUG_PROJECT_FILTER_KEY = "bug.projectFilter";
 const BUG_SEARCH_KEY = "bug.search";
+// 任务 31：视图布局与 Peek 模式本地持久化（key 前缀同既有 bug.* 惯例，story.* 同构）。
+// view 值域任务 34 定版 list|board（存量旧值经 isBugView 守卫回落 list）；peekMode
+// 四形态与 story 共用 shared-kit/peek 值域（任务 35 已挂 mode 切换 UI 并消费 onModeChange）
+const BUG_VIEW_KEY = "bug.view";
+const BUG_PEEK_MODE_KEY = "bug.peekMode";
+const BUG_PEEK_MODES: PeekMode[] = ["side-dock", "side-peek", "modal", "full-screen"];
+function isPeekMode(v: string | null): v is PeekMode {
+  return v != null && (BUG_PEEK_MODES as string[]).includes(v);
+}
 
 export function BugListView({ users: initialUsers, projects: initialProjects, labels }: BugListViewProps) {
   const navigate = useNavigate();
@@ -52,16 +90,55 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
   // 显示选项：首屏拉 per-user 持久化偏好，变更乐观更新 + updateBugDisplayOptionsFn 落库
   const { filters: display, updateFilters: updateDisplayOptions } = useBugDisplayOptions();
   const [view, setView] = useState<BugView>("list");
+  // Peek 展示模式（任务 31 落持久化机制，值域四形态与 story 一致；默认 side-peek
+  // 同 story）。任务 35 起 mode/onModeChange 已接到 BugPeekPanel（面板头部布局切换）
+  const [peekMode, setPeekMode] = useState<PeekMode>("side-peek");
   // 新建弹窗开关：工具栏按钮与空状态 CTA 共用同一入口
   const [createOpen, setCreateOpen] = useState(false);
-  // 详情侧滑 peek：list/table 行点击共用（table 行 onOpenBug 此前已备未接线）
+  // 详情侧滑 peek：list/board 行（卡片）点击共用
   const [peekBugId, setPeekBugId] = useState<string | null>(null);
+  // 保存视图（任务 30）：内置默认视图不落库（__default__），DB 行经 toSavedView
+  // 转客户端模型；对话框双模式（创建=存当前筛选，编辑=回填被编辑视图）
+  const [views, setViews] = useState<BugViewModel[]>([]);
+  const [activeViewId, setActiveViewId] = useState<string>(DEFAULT_VIEW_ID);
+  const [viewDialog, setViewDialog] = useState<{ mode: "create" | "edit"; view: BugViewModel | null }>({ mode: "create", view: null });
+  const [viewDialogOpen, setViewDialogOpen] = useState(false);
+
+  // ── 看板维度收敛（任务 33，testcase list-view boardGroupBy 同构）──
+  // 看板无单列形态，groupBy=none 一律按 state 渲染；createdBy 为不可变更字段、
+  // 无跨列拖拽语义，同样收敛 state（设计 §7.1 bug 看板维度 = state/severity/
+  // assignee/labels；labels 数据层无桶分来源，落地前不进看板维度）。收敛只落
+  // 看板数据面：display 原样传工具栏/列表，不静默改用户显示选项。
+  const boardGroupBy: Exclude<BugBoardGroupDimension, "labels"> =
+    display.groupBy === "none" || display.groupBy === "createdBy"
+      ? "state"
+      : display.groupBy;
+  // 看板列内子分组维度（任务 41，BUG-E 收尾）：按用户 subGroupBy 选项传递
+  // （任务 33 的强制 none 演进为「仅维度冲突时收敛」——与看板分组维度同值时
+  // 无子组语义，回落 none；display-dropdown 本就排除同值选项，此兜底覆盖
+  // 看板维度收敛面：groupBy=none/createdBy 收敛为 state 后与子组维度同值）。
+  // display 原样传工具栏/列表，不静默改用户显示选项。
+  const boardSubGroupBy: BugGroupKey =
+    display.subGroupBy !== "none" && display.subGroupBy !== boardGroupBy
+      ? display.subGroupBy
+      : "none";
+  // board 模式下分组数据按看板维度拉取（paged hook 签名含 groupBy，切视图自动重拉）。
+  // 子分组开启时走 paged 双层分组（父组不直挂条目，各子组独立首屏/分页）
+  const boardDisplay = useMemo(
+    () =>
+      view === "board"
+        ? { ...display, groupBy: boardGroupBy, subGroupBy: boardSubGroupBy }
+        : display,
+    [view, display, boardGroupBy, boardSubGroupBy],
+  );
 
   // 分组视图数据（组查询 + 组内分页 + 乐观 patch 全在此 hook）
+  // 看板（view=board，PR-10 任务 33）复用同一数据面：分组维度按看板收敛值拉取
+  // （见 boardGroupBy），列表视图不受影响（display 原样传入）
   const paged = usePagedBugGroups({
     filters: { projectId, search: searchText },
     conditions: filterConditions,
-    display,
+    display: boardDisplay,
     users,
     labels,
   });
@@ -88,6 +165,8 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
   useEffect(() => {
     let restoredProjectId: string | undefined;
     let restoredSearch: string | undefined;
+    let restoredView: BugView | undefined;
+    let restoredPeekMode: PeekMode | undefined;
     try {
       const stored = localStorage.getItem(BUG_PROJECT_FILTER_KEY) ?? undefined;
       // 清理过期残留（项目已删除或 localStorage 跨账号残留），避免列表查询空集
@@ -97,17 +176,128 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
         restoredProjectId = stored;
       }
       restoredSearch = localStorage.getItem(BUG_SEARCH_KEY) ?? undefined;
+      // 视图布局/Peek 模式恢复：非法值（含任务 34 收缩后的旧值）守卫回落默认
+      const storedView = localStorage.getItem(BUG_VIEW_KEY);
+      if (isBugView(storedView)) restoredView = storedView;
+      const storedPeekMode = localStorage.getItem(BUG_PEEK_MODE_KEY);
+      if (isPeekMode(storedPeekMode)) restoredPeekMode = storedPeekMode;
     } catch {
       return;
     }
     if (restoredProjectId !== undefined) setProjectId(restoredProjectId);
     if (restoredSearch !== undefined) setSearchText(restoredSearch);
+    if (restoredView !== undefined) setView(restoredView);
+    if (restoredPeekMode !== undefined) setPeekMode(restoredPeekMode);
   }, []);
 
   const handleFilterConditionsChange = useCallback((conditions: FilterCondition[]) => {
     setFilterConditions(conditions);
   }, []);
 
+  // ── 保存视图（任务 30，testcase list-view 视图接线同构）──
+  const allViews = useMemo(() => [buildDefaultView(), ...views], [views]);
+
+  // 首屏拉视图清单（失败静默：视图区为空，列表主链路不受影响）
+  useEffect(() => {
+    listBugViewsFn()
+      .then((rows) => setViews(rows.map(toSavedView)))
+      .catch(() => {});
+  }, []);
+
+  // applyView：conditions 由视图 filters 回填（补生成行 id）；displayOptions 五键
+  // 整组写回（useBugDisplayOptions 乐观更新 + 保留行落库；icon 在模型字段不入显示域）。
+  // 默认视图 = 全部复位（空筛选 + 显示选项回落默认值）
+  const applyView = useCallback(
+    (target: BugViewModel) => {
+      setActiveViewId(target.id);
+      setFilterConditions(viewFiltersToConditions(target.filters));
+      updateDisplayOptions({ ...target.displayOptions });
+    },
+    [updateDisplayOptions],
+  );
+
+  const reloadViews = useCallback(async () => {
+    const rows = await listBugViewsFn();
+    setViews(rows.map(toSavedView));
+    return rows.map(toSavedView);
+  }, []);
+
+  // 创建/编辑（保存）视图提交：filters 经 toViewFilters 收敛三键（去 id）落库；
+  // icon 随 displayOptions JSON 存取（BugFilterView 无 icon 列，见 view-types 说明）。
+  // 编辑仅同步元数据（name/filters/icon），显示快照不动；若编辑的是当前激活视图，
+  // 保存后重新应用使变更生效。提交错误由对话框内联展示。
+  const handleViewDialogSubmit = useCallback(
+    async (payload: CreateViewDialogPayload) => {
+      if (payload.id) {
+        const target = views.find((v) => v.id === payload.id);
+        await updateBugViewFn({
+          data: {
+            id: payload.id,
+            name: payload.name,
+            filters: toViewFilters(payload.filters),
+            ...(target ? { displayOptions: withViewIcon(target.displayOptions, payload.icon) } : {}),
+          },
+        });
+        const nextViews = await reloadViews();
+        if (activeViewId === payload.id) {
+          const updated = nextViews.find((v) => v.id === payload.id);
+          if (updated) applyView(updated);
+        }
+        return;
+      }
+      await createBugViewFn({
+        data: {
+          name: payload.name,
+          projectId: null,
+          filters: toViewFilters(payload.filters),
+          displayOptions: withViewIcon(display, payload.icon),
+        },
+      });
+      await reloadViews();
+    },
+    [views, display, activeViewId, applyView, reloadViews],
+  );
+
+  // ── 视图管理入口（工具栏「存为视图」/选择器加号共用；testcase 22 同构）──
+  const openCreateView = useCallback(() => {
+    setViewDialog({ mode: "create", view: null });
+    setViewDialogOpen(true);
+  }, []);
+
+  const handleEditView = useCallback((target: BugViewModel) => {
+    setViewDialog({ mode: "edit", view: target });
+    setViewDialogOpen(true);
+  }, []);
+
+  const handleDeleteView = useCallback(
+    async (target: BugViewModel) => {
+      try {
+        await deleteBugViewFn({ data: { id: target.id } });
+        await reloadViews();
+        if (activeViewId === target.id) applyView(buildDefaultView());
+      } catch (e) {
+        toastError(e, m.bug_view_deleteFailed());
+      }
+    },
+    [activeViewId, applyView, reloadViews],
+  );
+
+  // 对话框初值：编辑态回填被编辑视图（filters 补行 id 供 FilterRow 渲染）；
+  // 创建态快照当前页面筛选。引用随 viewDialog/filterConditions 变化（open 期间
+  // 对话框 useEffect 以其复位表单）
+  const viewDialogInitialValues = useMemo(
+    () =>
+      viewDialog.mode === "edit" && viewDialog.view
+        ? {
+            id: viewDialog.view.id,
+            name: viewDialog.view.name,
+            icon: viewDialog.view.icon,
+            filters: viewFiltersToConditions(viewDialog.view.filters),
+          }
+        : { name: "", icon: DEFAULT_BUG_VIEW_ICON, filters: filterConditions },
+    [viewDialog, filterConditions],
+  );
+
   const handleFilterChange = (next: BugFilters) => {
     setProjectId(next.projectId);
     setSearchText(next.search);
@@ -132,6 +322,90 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
     search: searchText,
   };
 
+  // 视图切换本地持久化（与项目筛选/搜索同模式）：默认值渲染 + 挂载后恢复，
+  // 规避 SSR/hydration 不一致；peekMode 切换入口已接 BugPeekPanel（任务 35 四形态）
+  const handleViewChange = (v: BugView) => {
+    setView(v);
+    try {
+      localStorage.setItem(BUG_VIEW_KEY, v);
+    } catch {
+      // localStorage 不可用（隐私模式等）时静默降级为不持久化
+    }
+  };
+
+  const handlePeekModeChange = (mode: PeekMode) => {
+    setPeekMode(mode);
+    try {
+      localStorage.setItem(BUG_PEEK_MODE_KEY, mode);
+    } catch {
+      // 忽略持久化失败
+    }
+  };
+
+  // 列表实时刷新（§7.1）：presence 信号（成员进出本模块实体页）+ 回前台 +
+  // 轮询兜底 → 走既有重拉入口（协同落库不 bump updatedAt，列表无推送通道）
+  const refreshBugList = useCallback(() => {
+    paged.refresh();
+  }, [paged.refresh]);
+  usePresenceListRefresh({ module: "bugs", refresh: refreshBugList });
+
+  // ── 看板列组装（任务 33 / 任务 41）：paged groups 条目数据 → Record<列 key, items> ──
+  // 取舍：bug 无 board 专用 columns serverFn（testcase 的 listTestCaseBoardColumnsFn
+  // 同位物缺位），看板直接消费 paged groups 的条目数据（组内条目级分页已备，
+  // 设计 §7.1）。state/severity 显式补全列集（含空列，键序 = 规范序；DB String
+  // 列的未知值兜底附后）；assignee 无客户端可枚举全集，保持服务端组 keys 返回序。
+  // 双层分组（任务 41）：父组不直挂条目，按子组顺序展平——连续分区是共享层
+  // buildRuns 切分子组区的前提。
+  const boardColumns = useMemo(() => {
+    const pickItems = (g: PagedBugGroupNode | undefined): BugListItem[] => {
+      if (!g) return [];
+      const subs = g.subGroups ?? [];
+      return subs.length > 0 ? subs.flatMap((sg) => sg.items) : g.items;
+    };
+    const columns: Record<string, BugListItem[]> = {};
+    const canonical =
+      boardGroupBy === "state"
+        ? BUG_STATE_GROUP_KEYS
+        : boardGroupBy === "severity"
+          ? BUG_SEVERITY_GROUP_KEYS
+          : null;
+    if (canonical) {
+      for (const key of canonical) {
+        columns[key] = pickItems(paged.groups.find((g) => g.key === key));
+      }
+      for (const g of paged.groups) {
+        if (!(g.key in columns)) columns[g.key] = pickItems(g);
+      }
+    } else {
+      for (const g of paged.groups) columns[g.key] = pickItems(g);
+    }
+    return columns;
+  }, [boardGroupBy, paged.groups]);
+
+  // 列尾加载更多：paged 既有条目级分页（skip/take）直通，无独立 cursor 通道。
+  // 子分组开启时不提供列级加载更多：条目按子组容器分页（paged.mergePage 直挂
+  // 子组 items），列级整拉会写入父组 g.items 被展平丢弃（假加载）。
+  const handleLoadMoreColumn = useCallback(
+    (columnKey: string) => {
+      void paged.loadMore(columnKey);
+    },
+    [paged.loadMore],
+  );
+
+  // 手动排序（拖拽列内/跨列均写目标列 boardOrder）：reorderBugsFn 批量落库
+  const handleBoardReorder = useCallback(async (orders: ReorderEntry[]) => {
+    if (orders.length === 0) return;
+    await reorderBugsFn({ data: { items: orders } });
+  }, []);
+
+  // 排序键不是 manual 时 boardOrder 不被读取（拖拽会被排回原位），落库后自动切换
+  const handleBoardAutoSwitchManual = useCallback(async () => {
+    const patch = manualOrderSwitchPatch(display.orderBy, true);
+    if (!patch) return;
+    updateDisplayOptions(patch);
+    toast.info(m.bug_board_manualOrderEnabled());
+  }, [display.orderBy, updateDisplayOptions]);
+
   return (
     <div className="relative flex h-full min-h-0 flex-col gap-3 overflow-hidden p-4">
       <BugToolbar
@@ -150,9 +424,16 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
           listProjectsBriefFn().then((rows) => setProjects(rows)).catch(() => {});
         }}
         view={view}
-        onViewChange={setView}
+        onViewChange={handleViewChange}
         displayFilters={display}
         onDisplayOptionsChange={updateDisplayOptions}
+        views={allViews}
+        activeViewId={activeViewId}
+        onApplyView={applyView}
+        onEditView={handleEditView}
+        onDeleteView={handleDeleteView}
+        onAddView={openCreateView}
+        onSaveAsView={openCreateView}
       />
 
       {createOpen && (
@@ -169,6 +450,16 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
         />
       )}
 
+      <CreateViewDialog
+        open={viewDialogOpen}
+        onOpenChange={setViewDialogOpen}
+        mode={viewDialog.mode}
+        initialValues={viewDialogInitialValues}
+        users={users}
+        labels={labels}
+        onSubmit={handleViewDialogSubmit}
+      />
+
       <div className="flex min-h-0 flex-1 flex-col">
         {total === 0 && !paged.isLoading ? (
           <div className="flex flex-1 flex-col items-center justify-center gap-3 text-center">
@@ -183,15 +474,19 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
               {m.bug_create_empty_cta()}
             </Button>
           </div>
-        ) : view === "table" ? (
-          <BugListTable
-            groups={paged.groups}
+        ) : view === "board" ? (
+          <BugBoardView
+            columns={boardColumns}
+            groupBy={boardGroupBy}
+            subGroupBy={boardSubGroupBy}
             properties={display.properties}
-            orderBy={display.orderBy}
-            orderDir={display.orderDir}
-            onLoadMoreGroup={paged.loadMore}
-            onOrderChange={(orderBy, orderDir) => updateDisplayOptions({ orderBy, orderDir })}
+            users={users}
             onOpenBug={setPeekBugId}
+            onLoadMoreColumn={boardSubGroupBy === "none" ? handleLoadMoreColumn : undefined}
+            onPatchBug={paged.patchBug}
+            onReorder={handleBoardReorder}
+            onAutoSwitchManual={handleBoardAutoSwitchManual}
+            onRefresh={refreshBugList}
           />
         ) : (
           <BugList
@@ -212,6 +507,8 @@ export function BugListView({ users: initialUsers, projects: initialProjects, la
       {peekBugId && (
         <BugPeekPanel
           bugId={peekBugId}
+          mode={peekMode}
+          onModeChange={handlePeekModeChange}
           users={users}
           labels={labels}
           onClose={() => setPeekBugId(null)}

package/src/components/bug/bug-panel-header.tsx

@@ -15,10 +15,13 @@
 // 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/>.
 
-// BUG 面板工具条（照 StoryPanelHeader 裁剪）：关闭/全屏/上一条下一条/复制链接/
-// 归档与删除（NameConfirmDialog 输入 identifier 确认）。归档删除直接调任务 3 serverFn。
-import { useState } from "react";
-import type { ReactElement } from "react";
+// BUG 面板工具条（照 StoryPanelHeader 裁剪）：关闭/全屏/布局切换/上一条下一条/
+// 复制链接/归档与删除（NameConfirmDialog 输入 identifier 确认）。归档删除直接调任务 3 serverFn。
+// navTitle 滚动渐显（story 详情页同款交互）：监听 BugDetailBody 的
+// data-slot=bug-detail-scroll 容器（scrollTop>8），capture 阶段挂 document——
+// scroll 不冒泡且 header 与滚动区是兄弟而非祖先，onScrollCapture 接不到。
+import { useEffect, useRef, useState } from "react";
+import type { ReactElement, ReactNode } from "react";
 import { Link } from "@tanstack/react-router";
 import {
   Archive,
@@ -30,6 +33,7 @@ import {
   Maximize2,
   MoreHorizontal,
   Trash2,
+  X,
 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
@@ -38,16 +42,20 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { toast } from "@/components/ui/toast";
 import { NameConfirmDialog } from "@/components/shared-kit/dialogs/name-confirm-dialog";
+import { PEEK_MODE_OPTIONS, type PeekMode } from "@/components/shared-kit/peek/peek-mode";
 import { archiveBugFn, deleteBugFn } from "@/server/serverFns/bug";
+import { cn } from "@/lib/utils";
 import { m } from "@/paraglide/messages.js";
 import { toastError } from "@/lib/toast-error";
 
-export type BugPanelCloseType = "collapse" | "back";
+export type BugPanelCloseType = "collapse" | "close" | "back";
 
 interface BugPanelHeaderProps {
   closeType?: BugPanelCloseType;
@@ -55,6 +63,9 @@ interface BugPanelHeaderProps {
   /** 独立路由模式：关闭按钮渲染为返回 /bugs 的 Link */
   backTo?: string;
   onFullscreen?: () => void;
+  /** Peek 展示模式（与 onModeChange 同时传入时渲染布局切换器，story panel-header 同位） */
+  mode?: PeekMode;
+  onModeChange?: (mode: PeekMode) => void;
   onPrevious?: () => void;
   onNext?: () => void;
   prevDisabled?: boolean;
@@ -64,6 +75,8 @@ interface BugPanelHeaderProps {
   canArchive?: boolean;
   onArchived?: () => void;
   onDeleted?: () => void;
+  /** 滚动联动标题内容（identifier + 标题；提供时随详情滚动渐显/渐隐，story navTitle 同位） */
+  navTitle?: ReactNode;
 }
 
 export function BugPanelHeader({
@@ -71,6 +84,8 @@ export function BugPanelHeader({
   onClose,
   backTo,
   onFullscreen,
+  mode,
+  onModeChange,
   onPrevious,
   onNext,
   prevDisabled = false,
@@ -80,13 +95,42 @@ export function BugPanelHeader({
   canArchive = false,
   onArchived,
   onDeleted,
+  navTitle,
 }: BugPanelHeaderProps) {
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
   const [archiveLoading, setArchiveLoading] = useState(false);
+  // 内容区滚动后顶栏渐显标题（peek 面板 body 自身不滚动：真正滚动的是
+  // BugDetailBody 的 data-slot=bug-detail-scroll 层，scroll 不冒泡，必须在
+  // document 上 capture 拦截）；scope 校验（header 所在面板根包含滚动源）
+  // 防未来多面板实例串扰。story 模式对照：peek-panel/route 父级 onScrollCapture。
+  const headerRowRef = useRef<HTMLDivElement>(null);
+  const [navTitleVisible, setNavTitleVisible] = useState(false);
+  useEffect(() => {
+    const onScroll = (e: Event) => {
+      const el = e.target as HTMLElement | null;
+      if (!el || el.dataset?.slot !== "bug-detail-scroll") return;
+      const scope = headerRowRef.current?.parentElement;
+      if (!scope || !scope.contains(el)) return;
+      setNavTitleVisible(el.scrollTop > 8);
+    };
+    document.addEventListener("scroll", onScroll, true);
+    return () => document.removeEventListener("scroll", onScroll, true);
+  }, []);
+  // 换 bug（peek 上下条导航复用同一 header 实例）：新详情 scrollTop=0 且无
+  // scroll 事件，主动复位避免残留上一条的渐显标题
+  useEffect(() => {
+    setNavTitleVisible(false);
+  }, [bugId]);
 
+  const currentMode = PEEK_MODE_OPTIONS.find((o) => o.value === mode) ?? PEEK_MODE_OPTIONS[0];
+  const CurrentModeIcon = currentMode.icon;
   const closeTooltip =
-    closeType === "back" ? m.bug_panel_back() : m.bug_panel_collapse();
-  const CloseIcon = closeType === "back" ? ArrowLeft : ArrowRight;
+    closeType === "back"
+      ? m.bug_panel_back()
+      : closeType === "collapse"
+        ? m.bug_panel_collapse()
+        : m.bug_panel_close();
+  const CloseIcon = closeType === "back" ? ArrowLeft : closeType === "collapse" ? ArrowRight : X;
 
   const closeButton = (
     <Button
@@ -134,7 +178,7 @@ export function BugPanelHeader({
 
   return (
     <>
-      <div className="flex h-11 shrink-0 items-center gap-1.5 mt-2 px-3">
+      <div ref={headerRowRef} className="flex h-11 shrink-0 items-center gap-1.5 mt-2 px-3">
         <Tooltip>
           <TooltipTrigger render={closeButtonWithLink as ReactElement} />
           <TooltipContent>{closeTooltip}</TooltipContent>
@@ -153,6 +197,26 @@ export function BugPanelHeader({
           </Tooltip>
         )}
 
+        {mode && onModeChange && (
+          <DropdownMenu>
+            <DropdownMenuTrigger
+              render={<Button variant="ghost" size="icon" className="size-8" aria-label={m.story_panel_switchLayout()} data-testid="peek-mode-switcher" />}
+            >
+              <CurrentModeIcon className="size-4" />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="center" className="w-40" sideOffset={4}>
+              <DropdownMenuRadioGroup value={mode} onValueChange={(v) => onModeChange(v as PeekMode)}>
+                {PEEK_MODE_OPTIONS.map((o) => (
+                  <DropdownMenuRadioItem key={o.value} value={o.value}>
+                    <o.icon className="mr-2 size-4" />
+                    {o.label()}
+                  </DropdownMenuRadioItem>
+                ))}
+              </DropdownMenuRadioGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        )}
+
         {(onPrevious || onNext) && (
           <>
             {/* 外层 div 限高：Separator 默认 h-full，直接写 h-4 无法覆盖（story-panel-header 同款） */}
@@ -200,6 +264,18 @@ export function BugPanelHeader({
           </>
         )}
 
+        {navTitle && (
+          <span
+            data-testid="bug-nav-title"
+            className={cn(
+              "ml-1 min-w-0 truncate text-sm font-medium transition-opacity duration-200",
+              navTitleVisible ? "opacity-100" : "pointer-events-none opacity-0",
+            )}
+          >
+            {navTitle}
+          </span>
+        )}
+
         <div className="ml-auto flex items-center gap-1.5">
           <Tooltip>
             <TooltipTrigger