@allbluecn/web-app 0.18.2 → 0.19.0

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

@@ -0,0 +1,133 @@
+// 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 { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { BatchToolbarShell } from "../batch-toolbar-shell";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function renderShell(overrides: Partial<Parameters<typeof BatchToolbarShell>[0]> = {}) {
+  const props = {
+    selectedCount: 2,
+    total: 5,
+    allSelected: false,
+    onToggleAll: vi.fn(),
+    onClear: vi.fn(),
+    ...overrides,
+  };
+  const utils = render(
+    <TooltipProvider>
+      <BatchToolbarShell {...props}>
+        <div data-testid="shell-actions">actions</div>
+      </BatchToolbarShell>
+    </TooltipProvider>,
+  );
+  return { ...utils, props };
+}
+
+describe("BatchToolbarShell 容器", () => {
+  it("容器含 sticky bottom-0 z-10 h-10 border-t bg-background", () => {
+    const { container } = renderShell();
+    const bar = container.firstElementChild as HTMLElement;
+    expect(bar.className).toContain("sticky");
+    expect(bar.className).toContain("bottom-0");
+    expect(bar.className).toContain("z-10");
+    expect(bar.className).toContain("h-10");
+    expect(bar.className).toContain("border-t");
+    expect(bar.className).toContain("bg-background");
+  });
+
+  it("children 动作区渲染进容器，位于全选簇之后", () => {
+    const { getByTestId } = renderShell();
+    const actions = getByTestId("shell-actions");
+    // children 是 sticky 容器的直接子节点（全选簇的兄弟）
+    expect(actions.parentElement!.className).toContain("sticky bottom-0");
+  });
+
+  it("selectedCount 为 0 时不渲染且不抬升 AI 悬浮球", () => {
+    // 前序测试的归零清理会在 documentElement 残留 "0px"，先移除建立干净基线
+    document.documentElement.style.removeProperty("--ai-fab-lift");
+    const { container } = renderShell({ selectedCount: 0 });
+    expect(container.firstChild).toBeNull();
+    expect(document.documentElement.style.getPropertyValue("--ai-fab-lift")).toBe("");
+  });
+});
+
+describe("BatchToolbarShell 三态全选", () => {
+  it("allSelected=false 且 selectedCount>0 时复选框 indeterminate", () => {
+    renderShell();
+    const checkbox = screen.getByRole("checkbox", { name: "全选" });
+    expect(checkbox.getAttribute("aria-checked")).toBe("mixed");
+  });
+
+  it("allSelected=true 时复选框全选态", () => {
+    renderShell({ allSelected: true });
+    const checkbox = screen.getByRole("checkbox", { name: "全选" });
+    expect(checkbox.getAttribute("aria-checked")).toBe("true");
+  });
+
+  it("未设 allSelected 但 selectedCount===total 时为全选态（story 语义保持）", () => {
+    renderShell({ selectedCount: 5, total: 5 });
+    const checkbox = screen.getByRole("checkbox", { name: "全选" });
+    expect(checkbox.getAttribute("aria-checked")).toBe("true");
+  });
+
+  it("显示已选计数，点击复选框触发 onToggleAll", () => {
+    const { props } = renderShell();
+    expect(screen.getByText("已选 2 条")).toBeTruthy();
+    fireEvent.click(screen.getByRole("checkbox", { name: "全选" }));
+    expect(props.onToggleAll).toHaveBeenCalledOnce();
+  });
+
+  it("点击清空按钮触发 onClear", () => {
+    const { props, container } = renderShell();
+    // 壳内唯一按钮是清空（动作区测试桩不含按钮）
+    const clearBtn = container.querySelector("button");
+    expect(clearBtn).not.toBeNull();
+    fireEvent.click(clearBtn!);
+    expect(props.onClear).toHaveBeenCalledOnce();
+  });
+});
+
+describe("BatchToolbarShell AI 悬浮球抬升引用计数", () => {
+  it("挂载抬升 3.5rem；两实例卸载一个变量仍在，全卸载计数归零才复位", () => {
+    const a = renderShell();
+    const b = renderShell();
+    expect(document.documentElement.style.getPropertyValue("--ai-fab-lift")).toBe("3.5rem");
+
+    a.unmount();
+    // 另一实例仍在，抬升不能被复位
+    expect(document.documentElement.style.getPropertyValue("--ai-fab-lift")).toBe("3.5rem");
+
+    b.unmount();
+    // 计数归零才回落
+    expect(document.documentElement.style.getPropertyValue("--ai-fab-lift")).toBe("0px");
+  });
+
+  it("渲染 null 的实例（selectedCount=0）不参与计数", () => {
+    const lifted = renderShell();
+    renderShell({ selectedCount: 0 });
+    expect(document.documentElement.style.getPropertyValue("--ai-fab-lift")).toBe("3.5rem");
+    lifted.unmount();
+    expect(document.documentElement.style.getPropertyValue("--ai-fab-lift")).toBe("0px");
+  });
+});

package/src/components/shared-kit/list-kit/__tests__/frozen-header.test.ts

@@ -0,0 +1,89 @@
+// 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 { describe, it, expect } from "vitest";
+import { computeFrozenHeader } from "../frozen-header";
+
+// 平铺行布局（index → 行类型 → start）：
+//   0 grp0    0
+//   1 sub0   36
+//   2 story  80
+//   3 grp1  200
+//   4 sub1  236
+const measurements = [
+  { start: 0 },
+  { start: 36 },
+  { start: 80 },
+  { start: 200 },
+  { start: 236 },
+];
+const groupHeaderIndexes = [0, 3];
+const subGroupHeaderIndexes = [1, 4];
+const parentGroupOfSub = new Map<number, number>([
+  [1, 0],
+  [4, 3],
+]);
+
+const compute = (scrollTop: number) =>
+  computeFrozenHeader(scrollTop, measurements, groupHeaderIndexes, subGroupHeaderIndexes, parentGroupOfSub);
+
+describe("computeFrozenHeader", () => {
+  it("首屏（未滚动）激活第一个主组、无子组", () => {
+    expect(compute(0)).toEqual({ groupIdx: 0, subIdx: null });
+  });
+
+  it("组内滚动但未到子组头：仍激活主组、无子组", () => {
+    expect(compute(20)).toEqual({ groupIdx: 0, subIdx: null });
+  });
+
+  it("滚动到子组头：激活该子组", () => {
+    expect(compute(36)).toEqual({ groupIdx: 0, subIdx: 1 });
+  });
+
+  it("start == scrollTop + 1 边界：+1 容差视为已到达", () => {
+    expect(compute(35)).toEqual({ groupIdx: 0, subIdx: 1 });
+  });
+
+  it("跨到第二个主组：子组重置为 null（不属于该主组）", () => {
+    expect(compute(200)).toEqual({ groupIdx: 3, subIdx: null });
+  });
+
+  it("第二主组内滚动到其子组头：激活对应子组", () => {
+    expect(compute(236)).toEqual({ groupIdx: 3, subIdx: 4 });
+  });
+
+  it("滚过末尾：冻结组头停在最后一个主组及其子组", () => {
+    expect(compute(10000)).toEqual({ groupIdx: 3, subIdx: 4 });
+  });
+
+  it("子组头属于其他主组时不激活（parent 判定生效）", () => {
+    // st=236 时索引 1（start 36）虽已越过，但它属于 group0，不应被选
+    expect(compute(236)?.subIdx).toBe(4);
+  });
+
+  it("测量缺失的组头被忽略；全部缺失时返回 null", () => {
+    expect(computeFrozenHeader(100, [{ start: 0 }], [0, 3], [1, 4], parentGroupOfSub)).toEqual({
+      groupIdx: 0,
+      subIdx: null,
+    });
+    expect(computeFrozenHeader(0, [], [0, 3], [1, 4], parentGroupOfSub)).toBeNull();
+  });
+
+  it("负数 scrollTop（overscroll）不崩且激活首个主组", () => {
+    expect(compute(-5)).toEqual({ groupIdx: 0, subIdx: null });
+  });
+});

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

@@ -0,0 +1,85 @@
+// 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 { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import { CircleCheckBig } from "lucide-react";
+import { LevelBadge, type LevelBadgeMeta } from "../level-badge";
+
+const META: Record<string, LevelBadgeMeta> = {
+  todo: {
+    label: "To Do",
+    icon: CircleCheckBig,
+    color: "bg-blue-500/15 text-blue-600 dark:text-blue-400",
+  },
+  urgent: {
+    label: "紧急",
+    color: "bg-red-500/15 text-red-600 dark:text-red-400",
+  },
+};
+
+describe("LevelBadge variant=badge", () => {
+  it("渲染 meta 表的 label 与 color 类（含 bg-*-500/15）", () => {
+    const { container, getByText } = render(<LevelBadge level="todo" meta={META} />);
+    expect(getByText("To Do")).toBeTruthy();
+    const className = container.firstElementChild?.className ?? "";
+    expect(className).toContain("bg-blue-500/15");
+    expect(className).toContain("text-blue-600");
+    expect(className).toContain("dark:text-blue-400");
+  });
+
+  it("meta 带图标时渲染 svg 图标", () => {
+    const { container } = render(<LevelBadge level="todo" meta={META} />);
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("meta 无图标时不渲染 svg，仅 label", () => {
+    const { container, getByText } = render(<LevelBadge level="urgent" meta={META} />);
+    expect(container.querySelector("svg")).toBeNull();
+    expect(getByText("紧急")).toBeTruthy();
+  });
+
+  it("未知 level 回退中性 muted（label 显示原始 level 值）", () => {
+    const { container, getByText } = render(<LevelBadge level="mystery" meta={META} />);
+    expect(getByText("mystery")).toBeTruthy();
+    const className = container.firstElementChild?.className ?? "";
+    expect(className).toContain("bg-muted");
+    expect(className).toContain("text-muted-foreground");
+  });
+});
+
+describe("LevelBadge variant=icon", () => {
+  it("渲染纯图标：带 color 的 text 类、不带 bg 背景类", () => {
+    const { container } = render(<LevelBadge level="todo" meta={META} variant="icon" />);
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    const className = svg?.getAttribute("class") ?? "";
+    expect(className).toContain("text-blue-600");
+    expect(className).toContain("dark:text-blue-400");
+    expect(className).not.toContain("bg-");
+  });
+
+  it("未知 level 不渲染任何内容（无图标可显）", () => {
+    const { container } = render(<LevelBadge level="mystery" meta={META} variant="icon" />);
+    expect(container.firstElementChild).toBeNull();
+  });
+
+  it("meta 项缺 icon 字段时不渲染", () => {
+    const { container } = render(<LevelBadge level="urgent" meta={META} variant="icon" />);
+    expect(container.firstElementChild).toBeNull();
+  });
+});

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

@@ -0,0 +1,178 @@
+// 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 { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render } from "@testing-library/react";
+import { Input } from "@/components/ui/input";
+import { ToolbarShell, useToolbarCompact } from "../toolbar-shell";
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+/** 找到带三列网格类的行元素 */
+function findRow(container: HTMLElement): HTMLElement {
+  const row = Array.from(container.querySelectorAll("div")).find((el) =>
+    el.className.includes("grid-cols-[1fr_0.5fr_1fr]"),
+  );
+  expect(row).toBeDefined();
+  return row!;
+}
+
+describe("ToolbarShell 三列网格", () => {
+  it("行元素带 grid-cols-[1fr_0.5fr_1fr] 与 @container", () => {
+    const { container } = render(<ToolbarShell />);
+    const row = findRow(container);
+    expect(row.className).toContain("@container");
+    expect(row.className).toContain("items-center");
+    expect(row.className).toContain("gap-2");
+  });
+
+  it("left/right 业务件渲染进簇容器：左簇 flex items-center gap-2、右簇 justify-self-end", () => {
+    const { getByTestId, container } = render(
+      <ToolbarShell
+        left={<div data-testid="left-slot">L</div>}
+        right={<div data-testid="right-slot">R</div>}
+      />,
+    );
+    const left = getByTestId("left-slot");
+    const right = getByTestId("right-slot");
+    expect(left.parentElement?.className).toContain("flex items-center gap-2");
+    expect(right.parentElement?.className).toContain("justify-self-end");
+    expect(right.parentElement?.className).toContain("shrink-0");
+    // 两簇 + 中列都在同一行网格内
+    const row = findRow(container);
+    expect(row.contains(left)).toBe(true);
+    expect(row.contains(right)).toBe(true);
+  });
+
+  it("below 附属区渲染在网格行之后、同一 flex-col 外层内", () => {
+    const { getByTestId, container } = render(
+      <ToolbarShell below={<div data-testid="below-slot">B</div>} />,
+    );
+    const below = getByTestId("below-slot");
+    const outer = container.firstElementChild!;
+    expect(outer.className).toContain("flex flex-col gap-3");
+    expect(outer.firstElementChild).not.toBe(below);
+    // below 直排于外层 flex-col，紧跟网格行之后
+    expect(findRow(container).nextElementSibling).toBe(below);
+  });
+});
+
+describe("ToolbarShell 中列搜索", () => {
+  it("search 传入时中列以 min-w-30 max-w-60 降级容器包裹输入框", () => {
+    const { getByTestId, container } = render(
+      <ToolbarShell search={<Input data-testid="shell-search" />} />,
+    );
+    const input = getByTestId("shell-search");
+    const wrap = input.parentElement!;
+    expect(wrap.className).toContain("min-w-30");
+    expect(wrap.className).toContain("max-w-60");
+    expect(wrap.className).toContain("relative");
+    // 容器在中列（居中 flex）内
+    const middle = wrap.parentElement!;
+    expect(middle.className).toContain("justify-center");
+    expect(findRow(container).contains(input)).toBe(true);
+  });
+
+  it("@max-[530px] 阈值类挂搜索容器外层（容器 hidden、输入框本体无该类）", () => {
+    const { getByTestId } = render(
+      <ToolbarShell search={<Input data-testid="shell-search" />} />,
+    );
+    const input = getByTestId("shell-search");
+    const wrap = input.parentElement!;
+    expect(wrap.className).toContain("@max-[530px]:hidden");
+    expect(input.className).not.toContain("@max-[530px]");
+  });
+
+  it("search 缺省时不渲染搜索容器；searchFallback 与 search 同列并排", () => {
+    const { getByTestId, container } = render(
+      <ToolbarShell
+        searchFallback={<button data-testid="fallback-btn">go</button>}
+      />,
+    );
+    expect(getByTestId("fallback-btn")).toBeDefined();
+    // 无 search 时不应存在 min-w-30 搜索容器
+    expect(
+      Array.from(container.querySelectorAll("div")).some((el) =>
+        el.className.includes("min-w-30"),
+      ),
+    ).toBe(false);
+
+    cleanup();
+    const { getByTestId: get2, container: c2 } = render(
+      <ToolbarShell
+        search={<Input data-testid="shell-search" />}
+        searchFallback={<button data-testid="fallback-btn">go</button>}
+      />,
+    );
+    const fallback = get2("fallback-btn");
+    const searchWrap = get2("shell-search").parentElement!;
+    // fallback 与搜索容器是同一中列的相邻子节点
+    expect(fallback.parentElement).toBe(searchWrap.parentElement);
+    expect(Array.from(c2.querySelectorAll("div")).some((el) =>
+      el.className.includes("min-w-30"),
+    )).toBe(true);
+  });
+});
+
+describe("useToolbarCompact", () => {
+  /** 把 hook 的 ref 挂到真实 DOM 上，compact 注入 data 属性便于断言 */
+  function Harness() {
+    const { ref, compact } = useToolbarCompact();
+    return <div ref={ref} data-testid="compact-harness" data-compact={String(compact)} />;
+  }
+
+  it("mock ResizeObserver 行宽 900（<920）时 compact 为 true，恢复 1000 后为 false", () => {
+    let fireResize: () => void = () => {};
+    let observed: Element | null = null;
+    class CapturableResizeObserver {
+      constructor(cb: ResizeObserverCallback) {
+        fireResize = () => cb([], this as unknown as ResizeObserver);
+      }
+      observe(el: Element) {
+        observed = el;
+      }
+      unobserve() {}
+      disconnect() {}
+    }
+    vi.stubGlobal("ResizeObserver", CapturableResizeObserver);
+
+    const { getByTestId } = render(<Harness />);
+    const el = getByTestId("compact-harness");
+    expect(observed).toBe(el);
+    expect(el.getAttribute("data-compact")).toBe("false");
+
+    const setWidth = (width: number) => {
+      Object.defineProperty(observed, "clientWidth", {
+        configurable: true,
+        value: width,
+      });
+      act(() => {
+        fireResize();
+      });
+    };
+
+    setWidth(900);
+    expect(el.getAttribute("data-compact")).toBe("true");
+
+    setWidth(1000);
+    expect(el.getAttribute("data-compact")).toBe("false");
+  });
+});

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

@@ -0,0 +1,111 @@
+// 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, type ReactNode } from "react";
+import { BATCH_CLEAR_ICON } from "./icon-semantics";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Button } from "@/components/ui/button";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { m } from "@/paraglide/messages.js";
+
+const AI_FAB_LIFT = "3.5rem";
+let batchToolbarLiftCount = 0;
+
+export interface BatchToolbarShellProps {
+  selectedCount: number;
+  total: number;
+  allSelected: boolean;
+  onToggleAll: () => void;
+  onClear: () => void;
+  /** 预留：忙态接线（消费方后续可映射为壳内控件禁用）；当前壳不消费 */
+  busy?: boolean;
+  /** 动作区：全选簇与分隔线之后的业务件（移动/转移/归档删除按钮、批量编辑器滚动区等） */
+  children?: ReactNode;
+}
+
+/**
+ * 批量操作条共享壳（三态全选 + 已选计数 + 清空 + AI 悬浮球抬升引用计数）。
+ *
+ * 消费方约定：sticky 吸附滚动区底部，须挂在长列表容器内部末尾；滚动容器必须用
+ * overflow-clip（clip 不创建滚动容器，sticky 仍生效；hidden 会失效）。
+ */
+export function BatchToolbarShell({
+  selectedCount,
+  total,
+  allSelected,
+  onToggleAll,
+  onClear,
+  children,
+}: BatchToolbarShellProps) {
+  // 批量条显示期间抬升全局 AI 悬浮球（fixed bottom-4），避免遮挡右端按钮。
+  // 页面可能同时存在多个批量条实例（需求列表 + 详情面板各一），用模块级
+  // 引用计数：任一实例卸载不能复位其他实例设置的抬升，计数归零才回落。
+  // 仅在批量条真正渲染（selectedCount>0）时计数——渲染 null 的实例不参与。
+  const lifted = selectedCount > 0;
+  useEffect(() => {
+    if (!lifted) return;
+    batchToolbarLiftCount += 1;
+    document.documentElement.style.setProperty("--ai-fab-lift", AI_FAB_LIFT);
+    return () => {
+      batchToolbarLiftCount -= 1;
+      if (batchToolbarLiftCount === 0) {
+        document.documentElement.style.setProperty("--ai-fab-lift", "0px");
+      }
+    };
+  }, [lifted]);
+
+  if (selectedCount === 0) return null;
+
+  const checked =
+    allSelected || selectedCount === total
+      ? true
+      : selectedCount > 0
+        ? "indeterminate"
+        : false;
+
+  return (
+    // z-10：盖过列表行即可。更高会穿透 PeekPanel（z-20）浮到面板上层
+    <div className="sticky bottom-0 z-10 flex h-10 shrink-0 items-center gap-2 border-t bg-background px-3">
+      <div className="flex shrink-0 items-center gap-2">
+        <Checkbox
+          checked={checked === true}
+          indeterminate={checked === "indeterminate"}
+          onCheckedChange={onToggleAll}
+          aria-label={m.list_kit_batch_selectAll()}
+          className="-ml-1"
+        />
+        <span className="text-xs shrink-0 text-muted-foreground">
+          {m.list_kit_batch_selected({ count: selectedCount })}
+        </span>
+        <Tooltip>
+          <TooltipTrigger render={<Button variant="ghost"
+              size="icon"
+              className="size-7 text-muted-foreground hover:text-foreground"
+              aria-label={m.list_kit_batch_clear()}
+              onClick={onClear} />}>
+              <BATCH_CLEAR_ICON className="size-4" />
+            </TooltipTrigger>
+          <TooltipContent side="top" className="text-xs">
+            {m.list_kit_batch_clear()}
+          </TooltipContent>
+        </Tooltip>
+        <div className="mx-1 h-4 w-px shrink-0 bg-border" />
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/components/shared-kit/list-kit/csv-download.ts

@@ -0,0 +1,46 @@
+// 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/>.
+
+// CSV 客户端下载共享 helper（四期 Q8 任务 45）。testcase/bug 两工具栏「更多」
+// 菜单导出入口共用；落 list-kit（共享列表件域，与 toolbar-shell 同级）。
+// 下载链路照 design-engine/engine/export-node.ts 先例：Blob(text/csv;charset=
+// utf-8) → createObjectURL → a[download] → click → 下一拍 remove + revoke
+// （setTimeout 0：Safari 需锚在 DOM 内完成点击派发后再摘除/回收）。
+
+/** Blob 下载触发（CSV 专用 MIME 带 charset，Excel 正确识别 UTF-8） */
+export function downloadCsvFile(csv: string, filename: string): void {
+  const blob = new Blob([csv], { type: "text/csv;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  setTimeout(() => {
+    anchor.remove();
+    URL.revokeObjectURL(url);
+  }, 0);
+}
+
+/** 导出文件名：`{prefix}-{yyyyMMdd}.csv`（本地时区日期，零填充） */
+export function csvExportFileName(prefix: string): string {
+  const now = new Date();
+  const ymd =
+    `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, "0")}` +
+    `${String(now.getDate()).padStart(2, "0")}`;
+  return `${prefix}-${ymd}.csv`;
+}