@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/shared-kit/list-kit/kanban/manual-order.ts

@@ -0,0 +1,39 @@
+// 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/>.
+
+import type { DisplayOptions } from "../display/types";
+
+/**
+ * 看板拖拽落库后是否要把排序键切到「手动排序」。
+ *
+ * 看板顺序来自分组查询的排序键（story 默认 createdAt desc，testcase 缺省
+ * manual），拖拽只写 boardOrder。排序键不是 manual 时，落库的 boardOrder 不会
+ * 被读，卡片随即被排回原位（用户感知为「拖拽排序无效」）。故实际发生排序落库后
+ * 切换到 manual，让 boardOrder 立即生效。
+ *
+ * 参数按 string 接收（PR-7b 任务 26 起 testcase 等模块的排序键联合复用本判定，
+ * 不再钉 story 的 OrderKey；返回的 `{ orderBy: "manual" }` 对各模块
+ * Partial<DisplayOptions*> 均可赋值——"manual" 在各模块排序键集内）。
+ */
+export function manualOrderSwitchPatch(
+  orderBy: DisplayOptions["orderBy"] | string,
+  reordered: boolean,
+): { orderBy: "manual" } | null {
+  if (!reordered) return null;
+  if (orderBy === "manual") return null;
+  return { orderBy: "manual" };
+}

package/src/components/shared-kit/list-kit/level-badge.tsx

@@ -0,0 +1,71 @@
+// 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/>.
+
+import type { LucideIcon } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { cn } from "@/lib/utils";
+
+/** 分级徽章 meta 表的一项：label 为展示文案，icon 可选，color 为完整
+ *  Tailwind 工具类字符串（设计 §5.1：`bg-{c}-500/15 text-{c}-600 dark:text-{c}-400`） */
+export interface LevelBadgeMeta {
+  label: string;
+  icon?: LucideIcon;
+  color: string;
+}
+
+export interface LevelBadgeProps {
+  /** 分级 key（如 state / priority 的 value）；不在 meta 中时回退中性态 */
+  level: string;
+  /** level → 展示元数据映射，由调用方传入（纯原子，零业务耦合） */
+  meta: Record<string, LevelBadgeMeta>;
+  /** badge = 徽章形态（图标 + label + color 类）；icon = 纯图标形态（仅 color 的 text 类，无背景） */
+  variant?: "badge" | "icon";
+}
+
+const NEUTRAL_BADGE_COLOR = "bg-muted text-muted-foreground";
+const NEUTRAL_ICON_COLOR = "text-muted-foreground";
+
+/** 从完整工具类字符串中提取字色类（含 `dark:text-*` 等带前缀变体），
+ *  供 icon 变体去掉 `bg-*` 背景底色、只保留字色。
+ *  任务 29 起导出：完整徽章 token 的 META（如 TEST_CASE_STATE_META）被
+ *  icon-only 场景消费时统一走本函数，杜绝「图标带无圆角底色块」过渡态 */
+export function extractTextColors(color: string): string {
+  return color
+    .split(/\s+/)
+    .filter((token) => token.includes("text-"))
+    .join(" ");
+}
+
+export function LevelBadge({ level, meta, variant = "badge" }: LevelBadgeProps) {
+  const entry = meta[level];
+
+  if (variant === "icon") {
+    if (!entry?.icon) return null;
+    const Icon = entry.icon;
+    const textColor = extractTextColors(entry.color) || NEUTRAL_ICON_COLOR;
+    return <Icon aria-hidden className={cn("size-3.5", textColor)} />;
+  }
+
+  const color = entry?.color ?? NEUTRAL_BADGE_COLOR;
+  const Icon = entry?.icon;
+  return (
+    <Badge className={cn(color)}>
+      {Icon && <Icon aria-hidden />}
+      {entry?.label ?? level}
+    </Badge>
+  );
+}

package/src/components/shared-kit/list-kit/toolbar-shell.tsx

@@ -0,0 +1,103 @@
+// 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/>.
+
+import { useEffect, useRef, useState, type ReactNode, type Ref } from "react";
+
+/**
+ * 列表工具栏紧凑档判定 hook（行宽 <920px）。
+ *
+ * 紧凑档驱动「更多」菜单的业务件显隐（如新建需求项收纳进菜单）——菜单 portal 到
+ * body 后脱离 @container 祖先，容器查询类（@max-[920px]）失效，必须 JS 判定。
+ * ref 接到被观察元素（通常经 ToolbarShell 的 rowRef 挂到三列网格行上）。
+ */
+export function useToolbarCompact(): {
+  ref: React.RefObject<HTMLDivElement | null>;
+  compact: boolean;
+} {
+  const ref = useRef<HTMLDivElement>(null);
+  const [compact, setCompact] = useState(false);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const ro = new ResizeObserver(() => setCompact(el.clientWidth < 920));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  return { ref, compact };
+}
+
+export interface ToolbarShellProps {
+  /** 左簇业务件（项目按钮 / 视图选择器 / 总数等）。壳提供 `flex items-center gap-2` 簇容器 */
+  left?: ReactNode;
+  /** 中列搜索输入框本体（业务件：图标 + 受控 Input）。壳包降级容器
+   *  `relative w-full min-w-30 max-w-60`——`@max-[530px]:hidden` 阈值类挂容器
+   *  外层，窄容器下整格隐藏不留空白（内层隐藏外层仍占满宽是反模式） */
+  search?: ReactNode;
+  /** ≤530px 的搜索降级件（story 形态：图标按钮 + Popover 内 autoFocus 输入框），
+   *  与 search 同列并排；显隐类（默认 hidden、`@max-[530px]:flex`）由消费方自带 */
+  searchFallback?: ReactNode;
+  /** 右簇业务件（筛选 / 显示 / 视图切换 / 新建 / 更多）。壳提供
+   *  `flex shrink-0 items-center gap-2 justify-self-end` 簇容器 */
+  right?: ReactNode;
+  /** 工具栏行下方附属区（筛选行 / 已应用过滤 / 对话框等），直排于外层 flex-col */
+  below?: ReactNode;
+  /** 外部观察句柄：接 `useToolbarCompact()` 返回的 ref，壳挂到三列网格行元素上 */
+  rowRef?: Ref<HTMLDivElement>;
+}
+
+/**
+ * 列表工具栏三列网格壳（story 工具栏布局抽取，list-kit 共享）。
+ *
+ * 三列网格：两侧 1fr 等宽 + 中列 0.5fr → 中列中心恒等于行中心（两侧等宽时
+ * 1.25 × 单元宽 = 行宽一半），项目/视图名称长度变化不会移动搜索框；
+ * 空间不足时三列按比例收缩（中列下限 min-w-30，超过 15rem 由输入框 max-w-60 封顶），
+ * 窄到放不下时（<530px）输入框隐藏、由 searchFallback 图标按钮接管。
+ *
+ * 降级阶梯（消费方业务件自带断点类，壳保证 @container 祖先）：
+ * `@max-[530px]` 搜索 → 图标按钮 + Popover / `@max-[780px]` 项目按钮降级 /
+ * `@max-[920px]` 新建收纳「更多」（portal 后容器查询失效，配 useToolbarCompact
+ * JS 判定）/ `@max-[1000px]` 视图选择器 / `@max-[1100px]` 总数隐藏。
+ *
+ * ⚠️ @container containment 塌缩约束：三列网格行是 inline-size containment，
+ * 若壳被放在「按内容定宽」的水平 flex item 内（行内还有树开关等兄弟件，如
+ * testcase list-view），行宽会塌缩到 min-content，三列网格与断点降级全部失真。
+ * 消费方必须让壳拿到确定宽度：水平 flex 行内套 `min-w-0 flex-1` 包装层
+ * （testcase list-view 先例）；flex-col 直排（story / bug list-view）子项默认
+ * stretch 拿满宽，无需包装。
+ */
+export function ToolbarShell({ left, search, searchFallback, right, below, rowRef }: ToolbarShellProps) {
+  return (
+    <div className="flex flex-col gap-3">
+      <div ref={rowRef} className="grid grid-cols-[1fr_0.5fr_1fr] items-center gap-2 @container">
+        {/* 左簇 */}
+        <div className="flex items-center gap-2">{left}</div>
+
+        {/* 中列：w-full 填满列宽（≤15rem 封顶、≥min-w-30），居中放置输入框 */}
+        <div className="flex items-center justify-center gap-2">
+          {search && (
+            <div className="relative w-full min-w-30 max-w-60 @max-[530px]:hidden">{search}</div>
+          )}
+          {searchFallback}
+        </div>
+
+        {/* 右簇 */}
+        <div className="flex shrink-0 items-center gap-2 justify-self-end">{right}</div>
+      </div>
+      {below}
+    </div>
+  );
+}

package/src/components/shared-kit/loading/__tests__/use-deferred-flag.test.tsx

@@ -0,0 +1,115 @@
+// 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/>.
+
+// useDeferredFlag：真实等待才显示加载指示（follow-up A）。
+// active=true 超过 delayMs 才转 true；期间 active 变 false 立即复位，
+// 快请求（<delayMs 完成）全程不产出 true，消除 loading 闪烁。
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useDeferredFlag } from "../use-deferred-flag";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("useDeferredFlag", () => {
+  it("active=false 时恒为 false", () => {
+    const { result } = renderHook(() => useDeferredFlag(false, 400));
+    expect(result.current).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("active=true 后 delayMs 内保持 false（快请求零闪烁）", () => {
+    const { result } = renderHook(() => useDeferredFlag(true, 400));
+    expect(result.current).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(399);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("active=true 超过 delayMs 后转为 true（真实等待才显示）", () => {
+    const { result } = renderHook(() => useDeferredFlag(true, 400));
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(result.current).toBe(true);
+  });
+
+  it("delayMs 未到时 active 变 false 立即复位且定时器不再触发", () => {
+    const { result, rerender } = renderHook(({ active }) => useDeferredFlag(active, 400), {
+      initialProps: { active: true },
+    });
+    expect(result.current).toBe(false);
+    rerender({ active: false });
+    expect(result.current).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it("延迟显示后 active 变 false 立即复位（不等下一帧）", () => {
+    const { result, rerender } = renderHook(({ active }) => useDeferredFlag(active, 400), {
+      initialProps: { active: true },
+    });
+    act(() => {
+      vi.advanceTimersByTime(400);
+    });
+    expect(result.current).toBe(true);
+    rerender({ active: false });
+    expect(result.current).toBe(false);
+  });
+
+  it("active 重新变 true 时重新计时", () => {
+    const { result, rerender } = renderHook(({ active }) => useDeferredFlag(active, 400), {
+      initialProps: { active: true },
+    });
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+    rerender({ active: false });
+    rerender({ active: true });
+    act(() => {
+      vi.advanceTimersByTime(399);
+    });
+    expect(result.current).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(result.current).toBe(true);
+  });
+
+  it("默认 delayMs 为 400", () => {
+    const { result } = renderHook(() => useDeferredFlag(true));
+    act(() => {
+      vi.advanceTimersByTime(399);
+    });
+    expect(result.current).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(result.current).toBe(true);
+  });
+});

package/src/components/shared-kit/loading/use-deferred-flag.ts

@@ -0,0 +1,35 @@
+// 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/>.
+
+// active 为 true 超过 delayMs 才返回 true（真实等待才显示加载指示）；
+// active 变 false 立即复位。用于消除快请求下的 loading 闪烁。
+import { useEffect, useState } from "react";
+
+export function useDeferredFlag(active: boolean, delayMs = 400): boolean {
+  const [deferred, setDeferred] = useState(false);
+
+  useEffect(() => {
+    if (!active) {
+      setDeferred(false);
+      return;
+    }
+    const timer = setTimeout(() => setDeferred(true), delayMs);
+    return () => clearTimeout(timer);
+  }, [active, delayMs]);
+
+  return deferred;
+}

package/src/components/shared-kit/peek/dock-slot.ts

@@ -0,0 +1,62 @@
+// 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/>.
+
+// Peek 面板（story / testcase 跨模块共享）侧边面板（side-dock）态的布局槽位解析与应用。
+//
+// 「侧边面板」与其余三种「浮窗」态的本质差异：浮窗态是绝对定位叠加在内容区
+// 之上（不参与布局流），而侧边面板态要把面板搬到右侧内容父容器之外，靠 flex
+// 自然占位把内容区挤窄。因此它必须 portal 到布局级的挂载点
+// （sidebar-03 的 #peek-dock-panel-slot），而不是渲染在自己的
+// `relative` 容器内。
+//
+// 槽位查找是「首帧 → null → 下一帧命中」的两段式：SSR 阶段与首次客户端渲染
+// 时 document 尚未包含布局槽（或 hydration 未完成），若在渲染期直接查 DOM 会
+// 造成 SSR/CSR 结构不一致。故用 useState(null) + useEffect 在提交后解析，
+// 未命中期间退化为非 dock 渲染路径。
+
+import { useEffect, useState } from "react";
+import { PEEK_MODE_DOCK, type PeekMode } from "./peek-mode";
+
+import { PEEK_DOCK_SLOT_ID, PEEK_SIDE_PANEL_WIDTH_CLASS } from "@/lib/peek-dock";
+
+// 常量统一定义在 lib/peek-dock（供布局壳直接引用而不拉入 story serverFn 链），此处再导出给面板消费。
+export { PEEK_DOCK_SLOT_ID, PEEK_SIDE_PANEL_WIDTH_CLASS };
+
+/** 当前模式是否走侧边面板（布局占位）路径。 */
+export function isDockMode(mode: PeekMode): boolean {
+  return mode === PEEK_MODE_DOCK;
+}
+
+/**
+ * 解析侧边面板的 portal 挂载点。
+ *
+ * 返回 null 表示当前不可用（模式非 dock / SSR 首帧 / 布局槽不存在），
+ * 调用方应回退到容器内渲染，避免面板整体消失。
+ */
+export function usePeekDockSlot(mode: PeekMode): HTMLElement | null {
+  const [slot, setSlot] = useState<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!isDockMode(mode)) {
+      setSlot(null);
+      return;
+    }
+    setSlot(document.getElementById(PEEK_DOCK_SLOT_ID));
+  }, [mode]);
+
+  return slot;
+}

package/src/components/shared-kit/peek/peek-mode.ts

@@ -0,0 +1,34 @@
+// 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/>.
+
+// Peek 面板的四种展示模式定义（story / testcase 跨模块共享）。
+// label 为惰性求值函数：模块加载时不触发 paraglide 求值，渲染时才取当前语言文案。
+
+import { Fullscreen, PanelLeft, PanelLeftDashed, ScanSquare } from "lucide-react";
+import { m } from "@/paraglide/messages.js";
+
+export type PeekMode = "side-dock" | "side-peek" | "modal" | "full-screen";
+
+/** 侧边面板（dock）态：面板沉入布局槽，与内容区、AI 助手全屏槽三级并排。 */
+export const PEEK_MODE_DOCK: PeekMode = "side-dock";
+
+export const PEEK_MODE_OPTIONS: { value: PeekMode; label: () => string; icon: typeof PanelLeft }[] = [
+  { value: "side-dock", label: m.story_panel_mode_sideDock, icon: PanelLeft },
+  { value: "side-peek", label: m.story_panel_mode_sidePeek, icon: PanelLeftDashed },
+  { value: "modal", label: m.story_panel_mode_modal, icon: ScanSquare },
+  { value: "full-screen", label: m.story_panel_mode_fullScreen, icon: Fullscreen },
+];

package/src/components/shared-kit/theme/animated-theme-toggler.tsx

@@ -18,9 +18,10 @@
 import { useCallback, useEffect, useRef, useState } from "react"
 import { Moon, Sun } from "lucide-react"
 import { flushSync } from "react-dom"
-import { useTheme } from "next-themes"
 
 import { cn } from "@/lib/utils"
+import { useThemeMode } from "@/providers/theme-mode-provider"
+import { m } from "@/paraglide/messages.js"
 
 export type TransitionVariant =
   | "circle"
@@ -142,6 +143,11 @@ function getThemeTransitionClipPaths(
   }
 }
 
+/**
+ * 主题切换器：在明暗之间切换（clip-path 展开动画）。
+ * 未手动切换过时主题按系统外观 + 深色时段自动变化（见 ThemeModeProvider）；
+ * 一旦点击即记为手动选择，此后不再自动切换。
+ */
 export const AnimatedThemeToggler = ({
   className,
   duration = 400,
@@ -150,13 +156,13 @@ export const AnimatedThemeToggler = ({
   ...props
 }: AnimatedThemeTogglerProps) => {
   const shape = variant ?? "circle"
-  const { theme, setTheme } = useTheme()
+  const { resolved, toggle } = useThemeMode()
   const [isDark, setIsDark] = useState(false)
   const buttonRef = useRef<HTMLButtonElement>(null)
 
   useEffect(() => {
-    setIsDark(theme === "dark")
-  }, [theme])
+    setIsDark(resolved === "dark")
+  }, [resolved])
 
   const toggleTheme = useCallback(() => {
     const button = buttonRef.current
@@ -189,7 +195,7 @@ export const AnimatedThemeToggler = ({
     }
 
     const syncNextThemes = () => {
-      setTheme(newTheme ? "dark" : "light")
+      toggle()
     }
 
     if (typeof document.startViewTransition !== "function") {
@@ -254,7 +260,7 @@ export const AnimatedThemeToggler = ({
         )
       })
     }
-  }, [shape, fromCenter, duration, isDark, setTheme])
+  }, [shape, fromCenter, duration, isDark, toggle])
 
   return (
     <button
@@ -265,7 +271,7 @@ export const AnimatedThemeToggler = ({
       {...props}
     >
       {isDark ? <Sun className={cn("size-5", className)} /> : <Moon className={cn("size-5", className)} />}
-      <span className="sr-only">Toggle theme</span>
+      <span className="sr-only">{m.common_command_toggleTheme()}</span>
     </button>
   )
 }

package/src/components/shared-kit/theme/theme-toggle.tsx

@@ -15,18 +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/>.
 
-import { useTheme } from "next-themes";
 import { Moon, Sun } from "lucide-react";
 import { Button } from "@/components/ui/button";
-import { useEffect, useState } from "react";
+import { useThemeMode } from "@/providers/theme-mode-provider";
+import { m } from "@/paraglide/messages.js";
 
 export function ThemeToggle() {
-  const { theme, setTheme } = useTheme();
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    setMounted(true);
-  }, []);
+  const { toggle, resolved, mounted } = useThemeMode();
 
   if (!mounted) {
     return (
@@ -36,23 +31,17 @@ export function ThemeToggle() {
     );
   }
 
-  const toggleTheme = () => {
-    setTheme(theme === "dark" ? "light" : "dark");
-  };
+  const isDark = resolved === "dark";
 
   return (
     <Button
       variant="ghost"
       size="icon"
       className="h-8 w-8 rounded-full"
-      onClick={toggleTheme}
+      onClick={toggle}
+      aria-label={m.common_command_toggleTheme()}
     >
-      {theme === "dark" ? (
-        <Moon className="size-5" />
-      ) : (
-        <Sun className="size-5" />
-      )}
-      <span className="sr-only">Toggle theme</span>
+      {isDark ? <Moon className="size-5" /> : <Sun className="size-5" />}
     </Button>
   );
 }

package/src/components/shared-kit/views/view-icon.tsx

@@ -0,0 +1,49 @@
+// 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/>.
+
+import { List, type LucideIcon } from "lucide-react";
+import { LucideIconByName } from "@/components/shared-kit/icons/lucide-icon-picker/lucide-icon-by-name";
+import { VIEW_ICONS } from "@/components/story/views/view-types";
+
+/**
+ * 视图图标存储的是 lucide kebab-case 名（由 LucideIconPicker 写入，可为任意 lucide 图标）。
+ * VIEW_ICONS 只覆盖早期 12 个短名（grid/range/branch/kanban 等并非 lucide 官方名），
+ * 故先查旧映射，未命中再按 lucide 官方名解析（精选集同步 + Lab 集异步），仍无效回退 List。
+ */
+const LEGACY_VIEW_ICONS: Record<string, LucideIcon> = Object.fromEntries(
+  VIEW_ICONS.map((v) => [v.name, v.icon]),
+);
+
+interface ViewIconProps {
+  /** 图标名（lucide kebab-case 或早期短名） */
+  name?: string;
+  className?: string;
+  size?: number;
+}
+
+export function ViewIcon({ name, className, size = 16 }: ViewIconProps) {
+  const Legacy = name ? LEGACY_VIEW_ICONS[name] : undefined;
+  if (Legacy) return <Legacy className={className} aria-hidden />;
+  return (
+    <LucideIconByName
+      name={name}
+      size={size}
+      className={className}
+      fallback={<List className={className} aria-hidden />}
+    />
+  );
+}