@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/story/display/__tests__/use-collapsed-subgroups.test.ts

@@ -0,0 +1,158 @@
+// 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, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import {
+  COLLAPSED_SUBGROUPS_KEY,
+  collapseKey,
+  isCollapseKey,
+  parseCollapsed,
+  serializeCollapsed,
+  setCollapsedMany,
+  toggleCollapsed,
+  useCollapsedSubGroups,
+} from "../use-collapsed-subgroups";
+
+describe("collapseKey", () => {
+  it("列键 + 子分组维度 + 子分组键用冒号拼接（同一子分组在各列独立）", () => {
+    expect(collapseKey("todo", "priority", "high")).toBe("todo:priority:high");
+    expect(collapseKey("done", "priority", "high")).not.toBe(
+      collapseKey("todo", "priority", "high"),
+    );
+  });
+});
+
+describe("isCollapseKey", () => {
+  it("接受列级键（含子键带冒号的标签名），拒绝旧版维度级键", () => {
+    expect(isCollapseKey("todo:priority:high")).toBe(true);
+    expect(isCollapseKey("todo:labels:P0: urgent")).toBe(true);
+    expect(isCollapseKey("priority:urgent")).toBe(false);
+  });
+});
+
+describe("parseCollapsed", () => {
+  it("null 与空串返回空数组", () => {
+    expect(parseCollapsed(null)).toEqual([]);
+    expect(parseCollapsed("")).toEqual([]);
+  });
+
+  it("非法 JSON 返回空数组（不抛错）", () => {
+    expect(parseCollapsed("{oops")).toEqual([]);
+  });
+
+  it("非数组返回空数组", () => {
+    expect(parseCollapsed('{"a":1}')).toEqual([]);
+  });
+
+  it("过滤非字符串元素", () => {
+    expect(parseCollapsed('["a",1,null,"b"]')).toEqual(["a", "b"]);
+  });
+});
+
+describe("serializeCollapsed", () => {
+  it("Set 序列化为 JSON 数组", () => {
+    expect(serializeCollapsed(new Set(["a", "b"]))).toBe('["a","b"]');
+  });
+});
+
+describe("toggleCollapsed", () => {
+  it("不存在则加入、存在则移除，且不修改原集合", () => {
+    const base = new Set(["a"]);
+    const added = toggleCollapsed(base, "b");
+    expect([...added]).toEqual(["a", "b"]);
+    expect([...base]).toEqual(["a"]);
+    expect([...toggleCollapsed(added, "a")]).toEqual(["b"]);
+  });
+});
+
+describe("setCollapsedMany", () => {
+  it("折叠时批量加入目标键，保留其他键", () => {
+    const next = setCollapsedMany(new Set(["other:x"]), ["todo:priority:high", "todo:priority:low"], true);
+    expect([...next].sort()).toEqual(["other:x", "todo:priority:high", "todo:priority:low"]);
+  });
+
+  it("展开时批量移除目标键，保留其他键", () => {
+    const base = new Set(["todo:priority:high", "todo:priority:low", "other:x"]);
+    const next = setCollapsedMany(base, ["todo:priority:high", "todo:priority:low"], false);
+    expect([...next]).toEqual(["other:x"]);
+    expect([...base]).toEqual(["todo:priority:high", "todo:priority:low", "other:x"]);
+  });
+});
+
+describe("useCollapsedSubGroups", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  it("挂载后从 localStorage 恢复折叠键", () => {
+    window.localStorage.setItem(COLLAPSED_SUBGROUPS_KEY, '["todo:priority:high"]');
+    const { result } = renderHook(() => useCollapsedSubGroups());
+    expect([...result.current.collapsed]).toEqual(["todo:priority:high"]);
+  });
+
+  it("已有保存值时挂载不会被默认空集合覆盖", () => {
+    window.localStorage.setItem(COLLAPSED_SUBGROUPS_KEY, '["todo:priority:high"]');
+    renderHook(() => useCollapsedSubGroups());
+    expect(window.localStorage.getItem(COLLAPSED_SUBGROUPS_KEY)).toBe(
+      '["todo:priority:high"]',
+    );
+  });
+
+  it("丢弃旧版维度级折叠键，下次写入时从存储中清除", () => {
+    window.localStorage.setItem(
+      COLLAPSED_SUBGROUPS_KEY,
+      '["priority:urgent","todo:priority:high"]',
+    );
+    const { result } = renderHook(() => useCollapsedSubGroups());
+    expect([...result.current.collapsed]).toEqual(["todo:priority:high"]);
+    act(() => result.current.toggle("todo:priority:low"));
+    expect(
+      parseCollapsed(window.localStorage.getItem(COLLAPSED_SUBGROUPS_KEY)).sort(),
+    ).toEqual(["todo:priority:high", "todo:priority:low"]);
+  });
+
+  it("toggle 后写入 localStorage", () => {
+    const { result } = renderHook(() => useCollapsedSubGroups());
+    act(() => result.current.toggle("todo:priority:high"));
+    expect(parseCollapsed(window.localStorage.getItem(COLLAPSED_SUBGROUPS_KEY))).toEqual([
+      "todo:priority:high",
+    ]);
+  });
+
+  it("setMany 只影响目标列的子分组键", () => {
+    window.localStorage.setItem(
+      COLLAPSED_SUBGROUPS_KEY,
+      '["done:priority:high"]',
+    );
+    const { result } = renderHook(() => useCollapsedSubGroups());
+    act(() =>
+      result.current.setMany(["todo:priority:high", "todo:priority:low"], true),
+    );
+    expect(parseCollapsed(window.localStorage.getItem(COLLAPSED_SUBGROUPS_KEY)).sort()).toEqual([
+      "done:priority:high",
+      "todo:priority:high",
+      "todo:priority:low",
+    ]);
+    act(() =>
+      result.current.setMany(["todo:priority:high", "todo:priority:low"], false),
+    );
+    expect(parseCollapsed(window.localStorage.getItem(COLLAPSED_SUBGROUPS_KEY))).toEqual([
+      "done:priority:high",
+    ]);
+  });
+});

package/src/components/story/display/__tests__/use-display-options.test.ts

@@ -67,6 +67,23 @@ describe("filterDisplayOptionsForLayout", () => {
     expect(r.orderDir).toBe("asc");
   });
 
+  it("manual 排序被归一化为升序（忽略 desc）", () => {
+    const r = filterDisplayOptionsForLayout(
+      { ...DEFAULT_DISPLAY_OPTIONS, orderBy: "manual", orderDir: "desc" },
+      "list",
+    );
+    expect(r.orderBy).toBe("manual");
+    expect(r.orderDir).toBe("asc");
+  });
+
+  it("非 manual 排序保留 desc", () => {
+    const r = filterDisplayOptionsForLayout(
+      { ...DEFAULT_DISPLAY_OPTIONS, orderBy: "created", orderDir: "desc" },
+      "list",
+    );
+    expect(r.orderDir).toBe("desc");
+  });
+
   it("board 布局保留分组，但 showSubItems 回退默认（仅 list 支持）", () => {
     const r = filterDisplayOptionsForLayout(raw, "board");
     expect(r.groupBy).toBe("project");
@@ -92,12 +109,24 @@ describe("filterDisplayOptionsForLayout", () => {
     expect(r.showSubItems).toBe(false);
   });
 
-  it("timeline 布局 orderBy 保留，groupBy/properties 回退默认", () => {
+  it("timeline 布局保留分组，subGroupBy/properties 回退默认", () => {
     const r = filterDisplayOptionsForLayout(raw, "timeline");
     expect(r.orderBy).toBe("dueDate");
-    expect(r.groupBy).toBe(DEFAULT_DISPLAY_OPTIONS.groupBy);
+    expect(r.groupBy).toBe("project");
+    expect(r.subGroupBy).toBe(DEFAULT_DISPLAY_OPTIONS.subGroupBy);
     expect(r.properties).toEqual(DEFAULT_DISPLAY_OPTIONS.properties);
-    expect(r.showEmptyGroups).toBe(false);
+    expect(r.showEmptyGroups).toBe(true);
+  });
+
+  it("board 布局保留 columnOrder（列拖拽排序不丢失）", () => {
+    const withOrder = { ...raw, columnOrder: ["doing", "todo", "done"] };
+    const r = filterDisplayOptionsForLayout(withOrder, "board");
+    expect(r.columnOrder).toEqual(["doing", "todo", "done"]);
+  });
+
+  it("board 布局 columnOrder 缺失时为 undefined", () => {
+    const r = filterDisplayOptionsForLayout(raw, "board");
+    expect(r.columnOrder).toBeUndefined();
   });
 });
 

package/src/components/story/display/__tests__/use-fit-count.test.ts

@@ -0,0 +1,198 @@
+// 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, beforeEach, afterEach, vi } from "vitest";
+import { createElement } from "react";
+import { render, screen, act, cleanup } from "@testing-library/react";
+import { useFitCount } from "../use-fit-count";
+import { computeFitCount } from "../use-fit-count";
+
+class FakeResizeObserver {
+  static instances: FakeResizeObserver[] = [];
+  callback: ResizeObserverCallback;
+  observed: Element[] = [];
+  disconnected = false;
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    FakeResizeObserver.instances.push(this);
+  }
+  observe(el: Element) {
+    this.observed.push(el);
+  }
+  unobserve() {}
+  disconnect() {
+    this.disconnected = true;
+  }
+  emit() {
+    this.callback([], this as unknown as ResizeObserver);
+  }
+}
+
+const rafQueue: FrameRequestCallback[] = [];
+const flushRaf = () => {
+  const queue = rafQueue.splice(0);
+  queue.forEach((cb) => cb(0));
+};
+
+function stubRect(el: Element, width: number) {
+  const spy = vi.fn(() => ({ width }) as DOMRect);
+  el.getBoundingClientRect = spy as unknown as () => DOMRect;
+  return spy;
+}
+
+let renderCount = 0;
+function Harness({
+  itemCount = 3,
+  gap = 1,
+  enabled = true,
+}: {
+  itemCount?: number;
+  gap?: number;
+  enabled?: boolean;
+}) {
+  const { containerRef, measureRef, indicatorRef, visibleCount } = useFitCount(
+    itemCount,
+    gap,
+    enabled,
+  );
+  renderCount += 1;
+  return createElement(
+    "div",
+    null,
+    createElement("div", { ref: containerRef, "data-testid": "container" }),
+    createElement(
+      "div",
+      { ref: measureRef, "data-testid": "measure" },
+      createElement("span"),
+      createElement("span"),
+      createElement("span"),
+    ),
+    createElement("span", { ref: indicatorRef, "data-testid": "indicator" }),
+    createElement("output", { "data-testid": "count" }, visibleCount),
+  );
+}
+
+describe("useFitCount", () => {
+  beforeEach(() => {
+    FakeResizeObserver.instances = [];
+    rafQueue.length = 0;
+    renderCount = 0;
+    vi.stubGlobal("ResizeObserver", FakeResizeObserver);
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+      rafQueue.push(cb);
+      return rafQueue.length;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("enabled=false 时不创建观察者、不测量", () => {
+    render(createElement(Harness, { enabled: false }));
+    expect(FakeResizeObserver.instances).toHaveLength(0);
+    expect(screen.getByTestId("count").textContent).toBe("3");
+  });
+
+  it("同一帧内多次 ResizeObserver 回调只触发一次测量", () => {
+    render(createElement(Harness));
+    const observer = FakeResizeObserver.instances[0];
+    const containerSpy = stubRect(screen.getByTestId("container"), 100);
+
+    act(() => {
+      observer.emit();
+      observer.emit();
+      observer.emit();
+    });
+    // 三次回调被合并成一帧内的一次 measure
+    expect(rafQueue).toHaveLength(1);
+    expect(containerSpy).not.toHaveBeenCalled();
+
+    act(() => {
+      flushRaf();
+    });
+    expect(containerSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("测量结果未变化时不触发额外渲染", () => {
+    render(createElement(Harness));
+    const observer = FakeResizeObserver.instances[0];
+    stubRect(screen.getByTestId("container"), 100);
+    stubRect(screen.getByTestId("indicator"), 8);
+    screen
+      .getByTestId("measure")
+      .querySelectorAll("span")
+      .forEach((span) => stubRect(span, 20));
+
+    const before = renderCount;
+    act(() => {
+      observer.emit();
+      flushRaf();
+    });
+    // 容器足够宽（全放得下），可见数量不变（仍为 3）→ 不重渲染
+    expect(screen.getByTestId("count").textContent).toBe("3");
+    expect(renderCount).toBe(before);
+  });
+
+  it("宽度变窄时重算出可见数量", () => {
+    render(createElement(Harness));
+    const observer = FakeResizeObserver.instances[0];
+    stubRect(screen.getByTestId("container"), 30);
+    stubRect(screen.getByTestId("indicator"), 8);
+    screen
+      .getByTestId("measure")
+      .querySelectorAll("span")
+      .forEach((span) => stubRect(span, 20));
+
+    act(() => {
+      observer.emit();
+      flushRaf();
+    });
+    expect(screen.getByTestId("count").textContent).toBe("1");
+  });
+});
+
+describe("computeFitCount", () => {
+  it("全部装得下时返回全部数量（无需 +N）", () => {
+    expect(computeFitCount([10, 10, 10], 40, 8, 2)).toBe(3);
+  });
+
+  it("装不下时按 +N 占位后的可用宽度返回能放下的数量", () => {
+    // 可用 = 30 - 8(+N) - 2(gap) = 20；两项需 10 + 2 + 10 = 22 > 20，故只放 1 项
+    expect(computeFitCount([10, 10, 10], 30, 8, 2)).toBe(1);
+  });
+
+  it("一个都放不下时返回 0（只显示 +N）", () => {
+    expect(computeFitCount([50], 30, 8, 2)).toBe(0);
+  });
+
+  it("gap 参与计算（间距不同结果不同）", () => {
+    // 无间距：3 项 = 30 <= 30 全放；有间距：30 + 4 = 34 > 30 被迫让位
+    expect(computeFitCount([10, 10, 10], 30, 8, 0)).toBe(3);
+    expect(computeFitCount([10, 10, 10], 30, 8, 2)).toBe(1);
+  });
+
+  it("容器宽度为 0（测量未就绪）时回落显示全部", () => {
+    expect(computeFitCount([10, 10, 10], 0, 8, 2)).toBe(3);
+  });
+
+  it("空数组返回 0", () => {
+    expect(computeFitCount([], 40, 8, 2)).toBe(0);
+  });
+});

package/src/components/story/display/__tests__/use-paged-story-groups.test.ts

@@ -363,13 +363,15 @@ describe("usePagedStoryGroups", () => {
       expect(result.current.groups[0].items[0].priority).toBe("urgent");
     });
 
-    it("触发分组规则：回退全量 refresh", async () => {
+    it("触发分组规则且目标组未加载：本地创建目标组（不 refresh）", async () => {
       const result = await setup();
+      const callsBefore = h.listStoryGroupsFn.mock.calls.length;
 
       act(() => result.current.patchStory("a", { state: "done" }));
 
-      expect(h.listStoryGroupsFn.mock.calls.length).toBeGreaterThan(1); // refresh 触发重新加载
-      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      expect(h.listStoryGroupsFn.mock.calls.length).toBe(callsBefore); // 未触发 refresh
+      const done = result.current.groups.find((g) => g.key === "done")!;
+      expect(done.items.map((s) => s.id)).toEqual(["a"]);
     });
 
     it("排序=updated 时任意字段编辑触发组内重插（updatedAt 变最新）", async () => {
@@ -422,5 +424,77 @@ describe("usePagedStoryGroups", () => {
       expect(parent.subGroups?.[0].items[0].priority).toBe("low");
       expect(parent.totalCount).toBe(2); // 父组计数不变
     });
+
+    it("触发顶层分组规则：本地移动到目标组（不 refresh）", async () => {
+      h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "high", total: 2 }, { key: "low", total: 0 }] });
+      h.listAllGroupsItemsFn.mockResolvedValue({
+        grouped: {
+          high: [makeStory({ id: "a", priority: "high" }), makeStory({ id: "b", priority: "high" })],
+          low: [],
+        },
+      });
+      const { result } = renderHook(() =>
+        usePagedStoryGroups(makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "priority" } })),
+      );
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      const callsBefore = h.listStoryGroupsFn.mock.calls.length;
+
+      act(() => result.current.patchStory("a", { priority: "low" }));
+
+      expect(h.listStoryGroupsFn.mock.calls.length).toBe(callsBefore); // 未触发 refresh
+      expect(result.current.groups.find((g) => g.key === "high")!.items.map((s) => s.id)).toEqual(["b"]);
+      expect(result.current.groups.find((g) => g.key === "low")!.items.map((s) => s.id)).toEqual(["a"]);
+    });
+
+    it("子组模式：顶层分组变化本地移动到目标父组子组", async () => {
+      h.listStoryGroupsFn
+        .mockResolvedValueOnce({ groups: [{ key: "high", total: 1 }, { key: "low", total: 0 }] })
+        .mockResolvedValueOnce({ groups: [{ key: "todo", total: 1 }] })
+        .mockResolvedValueOnce({ groups: [{ key: "todo", total: 0 }] });
+      h.listStoriesInGroupFn.mockImplementation(({ data }: { data: { groupKey: string } }) =>
+        Promise.resolve({
+          items: data.groupKey === "high" ? [makeStory({ id: "a", priority: "high", state: "todo" })] : [],
+          total: data.groupKey === "high" ? 1 : 0,
+          hasMore: false,
+        }),
+      );
+      const { result } = renderHook(() =>
+        usePagedStoryGroups(
+          makeArgs({ display: { ...DEFAULT_DISPLAY_OPTIONS, groupBy: "priority", subGroupBy: "state" } }),
+        ),
+      );
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+      const callsBefore = h.listStoryGroupsFn.mock.calls.length;
+
+      act(() => result.current.patchStory("a", { priority: "low" }));
+
+      expect(h.listStoryGroupsFn.mock.calls.length).toBe(callsBefore); // 未触发 refresh
+      // 源父组唯一子组清空 → 父组删除
+      expect(result.current.groups.find((g) => g.key === "high")).toBeUndefined();
+      const low = result.current.groups.find((g) => g.key === "low")!;
+      expect(low.subGroups?.[0].items.map((s) => s.id)).toEqual(["a"]);
+    });
+  });
+
+  // 任务 42 必带②（对照 bug 侧 54bc6c65c 先例）：返回回调须引用稳定——core 回调经
+  // ref 读最新实现恒定，包装层 useCallback 固定；内联箭头每次渲染换引用，会把
+  // 消费方直传的 loadMore/patchStory 依赖拖垮（下游经 useMemo 装配的 config 全失效）。
+  it("引用稳定：重渲染后 loadMore/patchStory/refresh 引用不变", async () => {
+    h.listStoryGroupsFn.mockResolvedValue({ groups: [{ key: "todo", total: 0 }] });
+    h.listAllGroupsItemsFn.mockResolvedValue({ grouped: {} });
+
+    const { result, rerender } = renderHook(() => usePagedStoryGroups(makeArgs()));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const first = {
+      loadMore: result.current.loadMore,
+      patchStory: result.current.patchStory,
+      refresh: result.current.refresh,
+    };
+    // 同 props 重渲染（数据 state.groups 换新对象，回调引用不得变）
+    rerender();
+    expect(result.current.loadMore).toBe(first.loadMore);
+    expect(result.current.patchStory).toBe(first.patchStory);
+    expect(result.current.refresh).toBe(first.refresh);
   });
 });

package/src/components/story/display/constants.ts

@@ -15,12 +15,14 @@
 // 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 { CircleDotDashed, ArrowUpDown, User, Tag, UserPlus, Trees, X, CircleFadingArrowUp, ArrowDownUp, Plus, RefreshCw, CalendarPlus2, CalendarCheck, Hash, GitBranch, Paperclip, LayoutList, FolderKanban, type LucideIcon } from "lucide-react";
+import { CircleDotDashed, ArrowUpDown, User, Tag, UserPlus, Trees, X, CircleFadingArrowUp, ArrowDownUp, Plus, RefreshCw, CalendarPlus2, CalendarCheck, CalendarRange, Hash, GitBranch, Paperclip, LayoutList, FolderKanban, type LucideIcon } from "lucide-react";
 import type { StoryView } from "../views/view-switcher";
 import { m } from '@/paraglide/messages.js';
 import type { GroupKey, OrderKey, DisplayProperty } from "./types";
 import { ALL_DISPLAY_PROPERTIES } from "./types";
 
+// iteration 为甘特专属维度（GROUP_KEYS 数组不含，仅 timeline 选项可达），
+// label 复用既有 iterations_title 词条，图标与迭代周期语义对齐
 export const GROUP_LABELS: Record<GroupKey, () => string> = {
   state: m.story_display_group_state,
   priority: m.story_display_group_priority,
@@ -28,6 +30,7 @@ export const GROUP_LABELS: Record<GroupKey, () => string> = {
   labels: m.story_display_group_labels,
   createdBy: m.story_display_group_createdBy,
   project: m.story_display_group_project,
+  iteration: m.iterations_title,
   none: m.story_display_group_none,
 };
 
@@ -60,6 +63,7 @@ export const GROUP_ICONS: Record<GroupKey, LucideIcon> = {
   labels: Tag,
   createdBy: UserPlus,
   project: Trees,
+  iteration: CalendarRange,
   none: X,
 };
 
@@ -95,9 +99,26 @@ export const LAYOUT_SUPPORT: LayoutSupport = {
   board:    { groupBy: true,  subGroupBy: true,  orderBy: true,  properties: true,  options: true  },
   table:    { groupBy: false, subGroupBy: false, orderBy: true,  properties: true,  options: true  },
   calendar: { groupBy: false, subGroupBy: false, orderBy: true,  properties: false, options: false },
-  timeline: { groupBy: false, subGroupBy: false, orderBy: true,  properties: false, options: true  },
+  timeline: { groupBy: true,  subGroupBy: false, orderBy: true,  properties: false, options: true  },
 };
 
+/**
+ * 甘特 timeline 分组白名单（R-9，单一事实源）：dropdown 的分组选项
+ * （LAYOUT_GROUP_KEYS.timeline）与 timeline-view 的 effectiveGroupBy 防御性
+ * clamp 两处同源消费，禁止再写字面副本。iteration/priority/assignee/labels
+ * 已由 mappers 实现；GROUP_KEYS 其余键（createdBy/project）不列入是产品收敛
+ * （甘特入口不提供）而非能力缺失。
+ */
+export const TIMELINE_GROUP_KEYS = [
+  "none",
+  "state",
+  "priority",
+  "assignee",
+  "labels",
+  "iteration",
+] as const;
+export type TimelineGroupKey = (typeof TIMELINE_GROUP_KEYS)[number];
+
 export const LAYOUT_PROPERTIES: Record<StoryView, DisplayProperty[]> = {
   list:     ["id", "assignee", "startDate", "dueDate", "labels", "priority", "state"],
   board:    ["id", "assignee", "startDate", "dueDate", "labels", "priority", "state"],