@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/story/inline-editors/story-select-dialog.tsx

@@ -18,7 +18,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useDebouncedCallback, SEARCH_DEBOUNCE_MS } from "@/lib/pacer";
 import { cn } from "@/lib/utils";
-import { Search, Sprout, ChevronsUpDown, Check, Trees, ListFilter, Flag } from "lucide-react";
+import { Search, Sprout, ChevronsUpDown, Check, Trees, ListFilter, Flag, X } from "lucide-react";
 import { Badge } from "@/components/ui/badge";
 import { Checkbox } from "@/components/ui/checkbox";
 import { LucideIconByName } from "@/components/shared-kit/icons/lucide-icon-picker/lucide-icon-by-name";
@@ -130,6 +130,8 @@ export function StorySelectDialog({
   const [statePopoverOpen, setStatePopoverOpen] = useState(false);
   const [priorityPopoverOpen, setPriorityPopoverOpen] = useState(false);
   const [depPopoverOpen, setDepPopoverOpen] = useState(false);
+  // 依赖方式黄字提示的关闭状态（X 关闭后本弹窗周期不再显示）
+  const [depHintDismissed, setDepHintDismissed] = useState(false);
   const [selectedStates, setSelectedStates] = useState<Set<string>>(
     () => new Set(ALL_STATES),
   );
@@ -138,6 +140,22 @@ export function StorySelectDialog({
   );
   const requestIdRef = useRef(0);
 
+  // props 身份稳定化：父级 react-query/loader refetch 会换 projects、
+  // defaultSelectedParentIds、excludeIds 的数组身份（内容不变）。弹窗开着时
+  // effect 以数组为依赖重跑，会把已选清空 / 列表重置回第一页（loadMore 结果
+  // 被 requestId 丢弃），表现为「全选后状态莫名跳回」。改以内容签名做依赖，
+  // 数组本体经 ref 读取。
+  const projectsRef = useRef(projects);
+  projectsRef.current = projects;
+  const projectIdsKey = useMemo(() => projects.map((p) => p.id).join("|"), [projects]);
+  const defaultParentIdsKey = useMemo(
+    () => defaultSelectedParentIds?.join("|") ?? "",
+    [defaultSelectedParentIds],
+  );
+  const excludeIdsRef = useRef(excludeIds);
+  excludeIdsRef.current = excludeIds;
+  const excludeKey = useMemo(() => excludeIds.join("|"), [excludeIds]);
+
   const filteredItems = useMemo(() => {
     return items.filter((story) => {
       return selectedStates.has(story.state) && selectedPriorities.has(story.priority);
@@ -183,7 +201,8 @@ export function StorySelectDialog({
 
   useEffect(() => {
     if (open) {
-      const shouldFilterByProject = initialProjectId && projects.some((p) => p.id === initialProjectId);
+      const shouldFilterByProject =
+        initialProjectId && projectsRef.current.some((p) => p.id === initialProjectId);
       if (defaultSelectedParentIds && defaultSelectedParentIds.length > 0) {
         setProjectFilter(shouldFilterByProject ? initialProjectId : ALL_PROJECTS);
         setSelectedIds(defaultSelectedParentIds);
@@ -197,7 +216,8 @@ export function StorySelectDialog({
       return;
     }
     debouncedReset();
-  }, [open, initialProjectId, projects, defaultSelectedParentId, defaultSelectedParentIds, debouncedReset]);
+    // projectIdsKey/defaultParentIdsKey 是数组 props 的内容签名，见上方注释
+  }, [open, initialProjectId, projectIdsKey, defaultSelectedParentId, defaultParentIdsKey, debouncedReset]);
 
   // 搜索 debounce
   const debouncedSearchCallback = useDebouncedCallback(
@@ -222,7 +242,7 @@ export function StorySelectDialog({
         projectId: projectFilter === ALL_PROJECTS ? undefined : projectFilter,
         search: debouncedSearch || undefined,
         excludeStoryId: storyId,
-        excludeIds: excludeIds.length > 0 ? excludeIds : undefined,
+        excludeIds: excludeIdsRef.current.length > 0 ? excludeIdsRef.current : undefined,
         mode,
       },
     })
@@ -240,7 +260,8 @@ export function StorySelectDialog({
         if (reqId !== requestIdRef.current) return;
         setLoading(false);
       });
-  }, [open, projectFilter, debouncedSearch, storyId, excludeIds, mode]);
+    // excludeKey 是 excludeIds 的内容签名（数组本体经 ref 读取），见上方注释
+  }, [open, projectFilter, debouncedSearch, storyId, excludeKey, mode]);
 
   const loadMore = useCallback(async () => {
     if (loading || !hasMore || !nextCursor) return;
@@ -253,7 +274,7 @@ export function StorySelectDialog({
           search: debouncedSearch || undefined,
           cursor: nextCursor,
           excludeStoryId: storyId,
-          excludeIds: excludeIds.length > 0 ? excludeIds : undefined,
+          excludeIds: excludeIdsRef.current.length > 0 ? excludeIdsRef.current : undefined,
           mode,
         },
       });
@@ -267,7 +288,7 @@ export function StorySelectDialog({
     } finally {
       if (reqId === requestIdRef.current) setLoading(false);
     }
-  }, [loading, hasMore, nextCursor, projectFilter, debouncedSearch, storyId, excludeIds, mode]);
+  }, [loading, hasMore, nextCursor, projectFilter, debouncedSearch, storyId, excludeKey, mode]);
 
   // 点击 Popover 外部时关闭（Dialog 嵌套下 Radix 事件被拦截）
   useEffect(() => {
@@ -354,7 +375,7 @@ export function StorySelectDialog({
 
   return (
     <Dialog open={open} onOpenChange={(v) => !submitting && onOpenChange(v)}>
-      <DialogContent className="sm:max-w-260 -mt-50">
+      <DialogContent className="sm:max-w-[min(65rem,calc(100%-4rem))] max-w-[calc(100%-4rem)] flex max-h-[calc(100dvh-2rem)] [@media(min-height:64rem)]:-mt-50 flex-col overflow-hidden">
         <DialogHeader>
           <DialogTitle className="flex items-center gap-2 text-base">
             {resolvedTitle}
@@ -527,7 +548,7 @@ export function StorySelectDialog({
 
           <div
             onScroll={handleScroll}
-            className="h-[28vh] overflow-y-auto px-1"
+            className="h-80 min-h-24 shrink overflow-y-auto px-1 py-1"
           >
             {items.length === 0 && !loading ? (
               <div className="flex flex-col items-center gap-2 py-12 text-center text-sm text-muted-foreground">
@@ -542,7 +563,8 @@ export function StorySelectDialog({
                 {m.story_select_noMatchCurrent()}
               </div>
             ) : (
-              <ul className="space-y-0.5">
+              // 行距 space-y-1：选中行 ring 画在元素外侧，0.5 间距会让相邻选中行边框相触
+              <ul className="space-y-1">
                 {filteredItems.map((story) => {
                     const state = story.state as StoryState;
                     const priority = story.priority as Parameters<typeof PriorityIcon>[0]["priority"];
@@ -640,8 +662,7 @@ export function StorySelectDialog({
         </div>
 
         <DialogFooter className={cn(
-          "items-center gap-3",
-          isMulti && "sm:justify-between"
+          "shrink-0 flex-row flex-wrap items-center justify-between gap-3 sm:justify-between",
         )}>
           {filteredTip ? (
             <span className="text-xs text-muted-foreground ml-5">{filteredTip}</span>
@@ -669,12 +690,28 @@ export function StorySelectDialog({
                 {selectedCount > 0 ? m.story_select_selectedCount({ count: selectedCount }) : m.story_select_pleaseSelect()}
               </span>
               {mode === "dependency" && (
-                <DependencyTypeSelect
-                  value={dependencyType}
-                  onChange={(key) => onDependencyTypeChange?.(key)}
-                  open={depPopoverOpen}
-                  onOpenChange={setDepPopoverOpen}
-                />
+                <>
+                  <DependencyTypeSelect
+                    value={dependencyType}
+                    onChange={(key) => onDependencyTypeChange?.(key)}
+                    open={depPopoverOpen}
+                    onOpenChange={setDepPopoverOpen}
+                  />
+                  {/* 未选择依赖方式时按钮右侧黄字提示（带边框 + X 关闭，关闭后不再显示） */}
+                  {!dependencyType && !depHintDismissed && (
+                    <span className="inline-flex items-center gap-1.5 whitespace-nowrap rounded-md border border-amber-500/30 bg-amber-500/10 px-2 py-1 text-xs text-amber-600 dark:text-amber-400">
+                      {m.story_select_pleaseSelectDependency()}
+                      <button
+                        type="button"
+                        aria-label={m.story_select_cancel()}
+                        className="shrink-0 rounded-sm p-0.5 hover:bg-amber-500/20"
+                        onClick={() => setDepHintDismissed(true)}
+                      >
+                        <X className="size-3" />
+                      </button>
+                    </span>
+                  )}
+                </>
               )}
             </div>
           )}
@@ -694,7 +731,7 @@ export function StorySelectDialog({
                 (mode === "dependency" && !dependencyType)
               }
             >
-              {submitting ? m.story_select_loading() : isMulti ? m.story_select_confirmWithCount({ count: selectedCount }) : m.story_select_confirm()}
+              {submitting ? m.story_select_loading() : m.story_select_confirm()}
             </Button>
           </div>
         </DialogFooter>

package/src/components/story/peek-panel.tsx

@@ -15,7 +15,9 @@
 // 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/>.
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState, type UIEvent } from "react";
+import { createPortal } from "react-dom";
+import { useNavigate } from "@tanstack/react-router";
 import { useHotkey } from "@tanstack/react-hotkeys";
 import { Skeleton } from "@/components/ui/skeleton";
 import { Dialog, DialogContent } from "@/components/ui/dialog";
@@ -34,24 +36,47 @@ import {
 } from "@/server/serverFns/story";
 import { listIterationsFn } from "@/server/serverFns/iteration";
 import type { StoryDetail, UserBrief, CommentWithReplies, ActivityItem, RelationsData } from "./types";
+import { applyStoryPatchToItem, type StoryPatch } from "./display/group-fields";
 import type { StoryState } from "./constants";
 import { StoryDetailBody } from "./detail/story-detail-body";
+import { TestCasePeekPanel } from "@/components/testcase/peek-panel";
+import { BugPeekPanel } from "@/components/bug/peek-panel";
+import type { StoryEntityOverlay } from "./types";
 import { StoryPanelHeader } from "./story-panel-header";
-import type { PeekMode, PeekRelationKind, PeekBreadcrumbItem } from "./story-panel-header";
+import type { PeekRelationKind, PeekBreadcrumbItem } from "./story-panel-header";
+import type { PeekMode } from "@/components/shared-kit/peek/peek-mode";
+import {
+  PEEK_SIDE_PANEL_WIDTH_CLASS,
+  isDockMode,
+  usePeekDockSlot,
+} from "@/components/shared-kit/peek/dock-slot";
+import { useLayoutResponsive, useDockPresence } from "@/lib/layout-responsive";
 import { m } from "@/paraglide/messages.js";
 
 export type { PeekMode };
 
-const CONTENT_CLASS: Record<Exclude<PeekMode, "side-peek">, string> = {
+// modal / full-screen 的固定尺寸（side-dock 与 side-peek 均走自适应宽度，不在此表）
+const CONTENT_CLASS: Record<"modal" | "full-screen", string> = {
   modal: "top-[8.33%] left-[8.33%] w-[83.33%] h-[83.33%] sm:max-w-none",
   "full-screen": "inset-4 w-auto h-auto sm:max-w-none",
 };
 
-const OVERLAY_CLASS: Record<Exclude<PeekMode, "side-peek">, string> = {
+const OVERLAY_CLASS: Record<"modal" | "full-screen", string> = {
   modal: "bg-popover",
   "full-screen": "bg-popover",
 };
 
+/** 侧边浮窗（side-peek）：贴内容区右缘滑出的浮层层，仅左缘直角。
+    四边统一用 ring-1 的 1px 描边（此前额外叠加 border-l 导致左缘约 2px、显粗）。 */
+const SIDE_PEEK_PANEL_CLASS =
+  "flex flex-col overflow-hidden bg-popover [--detail-surface:var(--popover)] rounded-r-2xl rounded-l-none shadow-xl ring-1 ring-foreground/10 @max-[1399px]:rounded-l-2xl";
+
+/** 侧边面板（side-dock）：四角圆角与右侧内容容器一致（rounded-xl）。
+    停靠时额外加边框（独立卡片）；重叠时自身不加边框（避免与内容容器的边框叠成 2px）。 */
+const SIDE_DOCK_PANEL_CLASS =
+  "flex flex-col overflow-hidden bg-popover [--detail-surface:var(--popover)] rounded-xl";
+const DOCKED_PANEL_BORDER_CLASS = "border border-sidebar-border";
+
 interface StoryPeekPanelProps {
   storyId: string;
   users: UserBrief[];
@@ -69,6 +94,15 @@ interface StoryPeekPanelProps {
   onDeleted?: () => void;
   projects?: { id: string; name: string; displayId: string | null; icon: string }[];
   onTransferred?: () => void;
+  /**
+   * 外部（看板卡片内联编辑 / 拖拽换列）落库成功后的字段补丁，由 story-list-view 透传。
+   * 匹配当前展示需求时合并进 data.story，实现面板实时同步。
+   */
+  storyPatches?: { storyId: string; patch: StoryPatch; seq: number } | null;
+  /**
+   * 面板内字段落库成功后的补丁回调，父级据此乐观更新列表/看板（与 storyPatches 方向相反）。
+   */
+  onStoryPatch?: (storyId: string, patch: StoryPatch) => void;
 }
 
 interface PeekLocation {
@@ -105,10 +139,25 @@ export function StoryPeekPanel({
   onDeleted,
   projects,
   onTransferred,
+  storyPatches = null,
+  onStoryPatch,
 }: StoryPeekPanelProps) {
   const [data, setData] = useState<PeekData | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [refreshing, setRefreshing] = useState(false);
+  // 内容区滚动后顶栏显示需求标题（与详情页顶栏同款交互）
+  const [navTitleVisible, setNavTitleVisible] = useState(false);
+  // 面板 body 自身不滚动：StoryDetailBody 传 noScroll，真正滚动的是其
+  // data-slot=story-detail-scroll 层，冒泡的 onScroll 接不到，必须走 capture 阶段
+  const handleBodyScrollCapture = useCallback((e: UIEvent<HTMLDivElement>) => {
+    const el = e.target as HTMLElement;
+    if (el === e.currentTarget || el.dataset?.slot === "story-detail-scroll") {
+      setNavTitleVisible(el.scrollTop > 8);
+    }
+  }, []);
+  // 实体叠加层：用例/BUG 行在面板内打开（覆盖 peek 内容，关闭即返回需求）
+  const [entityOverlay, setEntityOverlay] = useState<StoryEntityOverlay | null>(null);
+  const navigate = useNavigate();
   const [history, setHistory] = useState<PeekLocation[]>([]);
   const [rootIdentifier, setRootIdentifier] = useState<string | undefined>();
   const [rootProjectId, setRootProjectId] = useState<string | undefined>();
@@ -122,6 +171,45 @@ export function StoryPeekPanel({
     });
   }, [storyId]);
 
+  // 以下回调供 memo 化的 StoryDetailBody 消费（顶栏滚动标题 state 翻转的重渲染
+  // 只落在 header），必须引用稳定
+  const handleRelationsUpdate = useCallback(
+    (next: RelationsData | ((prev: RelationsData) => RelationsData)) => {
+      setData((d) => (d ? { ...d, relationsData: typeof next === "function" ? next(d.relationsData) : next } : d));
+    },
+    [],
+  );
+  const handleAppendActivities = useCallback(
+    (items: ActivityItem[]) => setData((d) => (d ? { ...d, activities: [...d.activities, ...items] } : d)),
+    [],
+  );
+  const handleAppendComment = useCallback(
+    (c: CommentWithReplies) => setData((d) => (d ? { ...d, comments: [...d.comments, c] } : d)),
+    [],
+  );
+  const handleRemoveComment = useCallback(
+    (id: string) => setData((d) => (d ? { ...d, comments: d.comments.filter((c) => c.id !== id) } : d)),
+    [],
+  );
+  const handleStoryUpdate = useCallback(
+    (s: StoryDetail) => setData((d) => (d ? { ...d, story: s } : d)),
+    [],
+  );
+
+  // 外部编辑（看板卡片内联编辑 / 拖拽换列）实时同步：字段补丁合并进本地 data.story
+  useEffect(() => {
+    if (!storyPatches || storyPatches.storyId !== effectiveStoryId) return;
+    setData((d) => {
+      if (!d) return d;
+      // 用统一补丁语义展开（assigneeId→assignee、labelIds→labels、日期等），
+      // 而非浅合并——否则外部分组/列表改动不会反映到面板
+      return {
+        ...d,
+        story: applyStoryPatchToItem(d.story, storyPatches.patch, { users, labels: d.labels }) as StoryDetail,
+      };
+    });
+  }, [storyPatches, effectiveStoryId, users]);
+
   const onBackInPanel = useCallback(() => {
     setHistory((prev) => prev.slice(0, -1));
   }, []);
@@ -137,9 +225,25 @@ export function StoryPeekPanel({
     // 阻塞主线程，导致顶部 MorphIcon 关闭/返回按钮的形变动画掉帧卡顿。
     // 改为半透明遮罩过渡，新数据到达后经 key 变化整体替换。
     setRefreshing(data !== null);
+    // 并行化提速：只需 storyId 的请求与 detail 同时发出（原实现先等 detail
+    // 再串行十连发，白付一个 RTT）；仅 labels/stories/iterations 依赖
+    // story.projectId，detail 落地后再补发并二次合并。
+    const detailP = getStoryDetailFn({ data: { storyId: effectiveStoryId } });
+    const restP = Promise.all([
+      listCommentsFn({ data: { storyId: effectiveStoryId } }),
+      listActivitiesFn({ data: { storyId: effectiveStoryId, take: 50 } }),
+      listLabelsFn(),
+      listChildStoriesFn({ data: { parentId: effectiveStoryId } }),
+      getDependenciesFn({ data: { storyId: effectiveStoryId } }),
+      getLinksFn({ data: { storyId: effectiveStoryId } }),
+      getAttachmentsFn({ data: { storyId: effectiveStoryId } }),
+      getLinkedDesignsFn({ data: { storyId: effectiveStoryId } }),
+      getLinkedDocsFn({ data: { storyId: effectiveStoryId } }),
+    ]);
     (async () => {
       try {
-        const story = await getStoryDetailFn({ data: { storyId: effectiveStoryId } });
+        const [story, [comments, activities, labels, childrenStories, dependencies, links, attachments, prds, docs]] =
+          await Promise.all([detailP, restP]);
         if (history.length === 0) {
           setRootIdentifier(story.identifier);
           setRootProjectId(story.projectId);
@@ -151,19 +255,6 @@ export function StoryPeekPanel({
             return prev.map((h, i) => (i === prev.length - 1 ? { ...h, projectId: story.projectId } : h));
           });
         }
-        const [comments, activities, labels, storiesResult, childrenStories, dependencies, links, attachments, prds, docs, iterationsResult] = await Promise.all([
-          listCommentsFn({ data: { storyId: effectiveStoryId } }),
-          listActivitiesFn({ data: { storyId: effectiveStoryId, take: 50 } }),
-          listLabelsFn(),
-          listStoriesFn({ data: { projectId: story.projectId } }),
-          listChildStoriesFn({ data: { parentId: effectiveStoryId } }),
-          getDependenciesFn({ data: { storyId: effectiveStoryId } }),
-          getLinksFn({ data: { storyId: effectiveStoryId } }),
-          getAttachmentsFn({ data: { storyId: effectiveStoryId } }),
-          getLinkedDesignsFn({ data: { storyId: effectiveStoryId } }),
-          getLinkedDocsFn({ data: { storyId: effectiveStoryId } }),
-          story.projectId ? listIterationsFn({ data: { projectId: story.projectId, includeArchived: false } }) : Promise.resolve({ items: [] }),
-        ]);
         const relationsData: RelationsData = {
           hierarchy: {
             parent: null,
@@ -175,10 +266,37 @@ export function StoryPeekPanel({
           attachments,
           knowledge: { prds, docs },
         };
-        if (!cancelled) {
-          setData({ story, comments, activities: activities.items, labels: labels, stories: storiesResult.items.map((s) => ({ id: s.id, identifier: s.identifier, name: s.name, state: s.state })), relationsData, iterations: iterationsResult.items });
-          setRefreshing(false);
-        }
+        if (cancelled) return;
+        setData({
+          story,
+          comments,
+          activities: activities.items,
+          labels: labels,
+          // stories/iterations 依赖 projectId，二次补齐（先到先渲染）
+          stories: [],
+          iterations: [],
+          relationsData,
+        });
+        setRefreshing(false);
+        // projectId 相关补发：完成后二次合并（供父需求选择器/迭代选择器）
+        const [storiesResult, iterationsResult] = await Promise.all([
+          story.projectId
+            ? listStoriesFn({ data: { projectId: story.projectId } })
+            : Promise.resolve({ items: [] }),
+          story.projectId
+            ? listIterationsFn({ data: { projectId: story.projectId, includeArchived: false } })
+            : Promise.resolve({ items: [] }),
+        ]);
+        if (cancelled) return;
+        setData((d) =>
+          d
+            ? {
+                ...d,
+                stories: storiesResult.items.map((s) => ({ id: s.id, identifier: s.identifier, name: s.name, state: s.state })),
+                iterations: iterationsResult.items,
+              }
+            : d,
+        );
       } catch (e) {
         if (!cancelled) {
           setError(e instanceof Error ? e.message : m.story_peek_loadFailed());
@@ -195,16 +313,17 @@ export function StoryPeekPanel({
     enabled: mode === "side-peek" && history.length === 0,
   });
 
+  const dockSlot = usePeekDockSlot(mode);
+  const isDock = isDockMode(mode);
+  const { dockOverlay } = useLayoutResponsive();
+  useDockPresence(isDock);
+
   const canArchive = data?.story
     ? (data.story.state === "done" || data.story.state === "cancelled") && !data.story.archived
     : false;
 
   const closeType: "collapse" | "close" | "back" =
-    history.length > 0
-      ? "back"
-      : mode === "side-peek"
-        ? "collapse"
-        : "close";
+    history.length > 0 ? "back" : mode === "side-peek" ? "collapse" : "close";
 
   const handleClose = useCallback(() => {
     if (history.length > 0) {
@@ -249,24 +368,30 @@ export function StoryPeekPanel({
       closeType={closeType}
       onClose={handleClose}
       onFullscreen={onFullscreen}
-      mode={mode}
-      onModeChange={onModeChange}
-      storyId={storyId}
-      canArchive={canArchive}
-      onPrevious={onPrevious}
-      onNext={onNext}
-      prevDisabled={prevDisabled}
-      nextDisabled={nextDisabled}
-      onArchived={onArchived}
-      onDeleted={onDeleted}
-      projects={projects}
-      currentProjectId={data?.story.projectId ?? null}
-      onTransferred={onTransferred}
-    />
-  );
+          mode={mode}
+          onModeChange={onModeChange}
+          storyId={storyId}
+          canArchive={canArchive}
+          onPrevious={onPrevious}
+          onNext={onNext}
+          prevDisabled={prevDisabled}
+          nextDisabled={nextDisabled}
+          navTitle={
+            navTitleVisible && data
+              ? `${data.story.identifier} ${data.story.name}`
+              : undefined
+          }
+          onArchived={onArchived}
+          onDeleted={onDeleted}
+          projects={projects}
+          currentProjectId={data?.story.projectId ?? null}
+          onTransferred={onTransferred}
+        />
+      );
 
   const body = (
     <div
+      onScrollCapture={handleBodyScrollCapture}
       className={`flex min-h-0 flex-1 flex-col overflow-y-auto px-8 transition-opacity duration-200${refreshing ? " pointer-events-none opacity-50" : ""}`}
       style={{ scrollbarGutter: "stable" } as React.CSSProperties}
     >
@@ -329,23 +454,30 @@ export function StoryPeekPanel({
           projects={projects}
           iterations={data.iterations}
           relationsData={data.relationsData}
-          onRelationsUpdate={(next) => setData((d) => d ? { ...d, relationsData: typeof next === "function" ? next(d.relationsData) : next } : d)}
-          onAppendActivities={(items) => setData((d) => d ? { ...d, activities: [...d.activities, ...items] } : d)}
-          onAppendComment={(c) => setData((d) => d ? { ...d, comments: [...d.comments, c] } : d)}
-          onRemoveComment={(id) => setData((d) => d ? { ...d, comments: d.comments.filter((c) => c.id !== id) } : d)}
-          onStoryUpdate={(s) => setData((d) => d ? { ...d, story: s } : d)}
+          onRelationsUpdate={handleRelationsUpdate}
+          onAppendActivities={handleAppendActivities}
+          onAppendComment={handleAppendComment}
+          onRemoveComment={handleRemoveComment}
+          onStoryUpdate={handleStoryUpdate}
+          onStoryPatch={onStoryPatch}
           onNavigateInPanel={onNavigateInPanel}
+          onOpenEntity={setEntityOverlay}
           breadcrumbItems={breadcrumbItems}
         />
       )}
     </div>
   );
 
-  if (mode === "side-peek") {
-    return (
+  if (mode === "side-dock" || mode === "side-peek") {
+    // 侧边面板（dock）：portal 到右侧内容父容器之外的布局槽，与内容区并排占位。
+    // 槽位就绪时用 relative + 固定宽度让槽位自然占位；未就绪（SSR 首帧 / 布局外渲染）
+    // 时退化为容器内绝对定位覆盖，避免面板消失或首帧布局跳动。
+    // 槽位就绪且未进入窄屏浮层态时才 portal 占位；否则退化为容器内覆盖（浮层）
+    const dockLayout = isDock && dockSlot !== null && !dockOverlay;
+    const panel = (
       <>
         <div
-          className="absolute inset-y-0 right-0 z-20 flex w-[min(100%,max(85vw,560px),1200px)] flex-col overflow-hidden border-l bg-popover rounded-r-2xl rounded-l-none shadow-xl ring-1 ring-foreground/10 @max-[1399px]:rounded-l-2xl"
+          className={`${dockLayout ? `relative h-full w-full ${DOCKED_PANEL_BORDER_CLASS}` : `absolute inset-y-0 right-0 z-20 ${PEEK_SIDE_PANEL_WIDTH_CLASS}`} ${isDock ? SIDE_DOCK_PANEL_CLASS : SIDE_PEEK_PANEL_CLASS}`}
           onClick={(e) => {
             // 仅拦截本容器 DOM 内的点击（防止冒泡到列表背景误关 peek）。
             // Radix 弹层 portal 到 body、不在本容器 DOM 内，其合成事件冒泡会经过这里，
@@ -357,9 +489,38 @@ export function StoryPeekPanel({
         >
           {header}
           {body}
+          {entityOverlay?.kind === "case" && (
+            <TestCasePeekPanel
+              caseItem={entityOverlay.item}
+              folders={entityOverlay.folders}
+              breadcrumbParent={{ identifier: data?.story.identifier ?? undefined, projectId: data?.story.projectId ?? undefined }}
+              mode="side-dock"
+              onModeChange={() => {}}
+              onClose={() => setEntityOverlay(null)}
+            />
+          )}
+          {entityOverlay?.kind === "bug" && (
+            <BugPeekPanel
+              bugId={entityOverlay.id}
+              users={users}
+              labels={data?.labels ?? []}
+              breadcrumbParent={{ identifier: data?.story.identifier ?? undefined, projectId: data?.story.projectId ?? undefined }}
+              onClose={() => setEntityOverlay(null)}
+              onNavigate={() => {}}
+              onFullscreen={() => {
+                navigate({ to: "/bugs/$bugId", params: { bugId: entityOverlay.id } });
+                setEntityOverlay(null);
+              }}
+            />
+          )}
         </div>
       </>
     );
+
+    if (dockLayout && dockSlot) {
+      return createPortal(panel, dockSlot);
+    }
+    return panel;
   }
 
   return (
@@ -367,11 +528,33 @@ export function StoryPeekPanel({
       <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
         <DialogContent
           showCloseButton={false}
-          className={`flex flex-col overflow-hidden shadow-2xl transition-all duration-300 p-0 gap-0 translate-x-0 translate-y-0 data-open:zoom-in-0 data-closed:zoom-out-0 ${OVERLAY_CLASS[mode]} ${CONTENT_CLASS[mode]}`}
+          className={`flex flex-col overflow-hidden shadow-2xl transition-all duration-300 p-0 gap-0 translate-x-0 translate-y-0 data-open:zoom-in-0 data-closed:zoom-out-0 ${OVERLAY_CLASS[mode as "modal" | "full-screen"]} ${CONTENT_CLASS[mode as "modal" | "full-screen"]}`}
           initialFocus={false}
         >
           {header}
           {body}
+          {entityOverlay?.kind === "case" && (
+            <TestCasePeekPanel
+              caseItem={entityOverlay.item}
+              folders={entityOverlay.folders}
+              mode="side-peek"
+              onModeChange={() => {}}
+              onClose={() => setEntityOverlay(null)}
+            />
+          )}
+          {entityOverlay?.kind === "bug" && (
+            <BugPeekPanel
+              bugId={entityOverlay.id}
+              users={users}
+              labels={data?.labels ?? []}
+              onClose={() => setEntityOverlay(null)}
+              onNavigate={() => {}}
+              onFullscreen={() => {
+                navigate({ to: "/bugs/$bugId", params: { bugId: entityOverlay.id } });
+                setEntityOverlay(null);
+              }}
+            />
+          )}
         </DialogContent>
       </Dialog>
     </>