@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/story/display/group-resolver.tsx

@@ -23,11 +23,18 @@ import { STORY_STATES, STATE_LABEL, STATE_COLOR, STATE_ICON, STORY_PRIORITIES, P
 import { PRIORITY_COLOR } from "../priority-icon";
 import type { StoryListItem } from "../types";
 import type { GroupContext, GroupKey, GroupNode } from "./types";
+import { GROUP_FIELD } from "./group-fields";
 import { m } from "@/paraglide/messages.js";
 
 type KeyResolver = (item: StoryListItem) => string[];
 
-const RESOLVERS: Record<Exclude<GroupKey, "none">, KeyResolver> = {
+const STATE_KEYS: string[] = STORY_STATES.map((s) => s.value);
+const PRIORITY_KEYS: string[] = STORY_PRIORITIES.map((p) => p.value);
+
+// iteration 不在 RESOLVERS：甘特专属维度（mappers 自建桶语义），列表/看板
+// 选项不含此键（GROUP_KEYS 数组未纳入），groupBy 内有兜底单桶防 crafted
+// 持久值走 undefined resolver 崩栈
+const RESOLVERS: Record<Exclude<GroupKey, "none" | "iteration">, KeyResolver> = {
   state: (item) => [item.state],
   priority: (item) => [item.priority],
   assignee: (item) => [item.assignee?.id ?? "unassigned"],
@@ -40,6 +47,11 @@ export function groupBy(items: StoryListItem[], key: GroupKey, ctx: GroupContext
   if (key === "none") {
     return [{ key: "all", label: m.story_group_all(), items: [...items] }];
   }
+  if (key === "iteration") {
+    // 甘特专属维度兜底：合法路径不可达（filterDisplayOptionsForLayout 已按
+    // 布局 clamp），防御 crafted 持久值——单桶平铺而非崩溃
+    return [{ key: "iteration", label: m.iterations_title(), items: [...items] }];
+  }
   const resolver = RESOLVERS[key];
   const buckets = new Map<string, StoryListItem[]>();
   const order: string[] = [];
@@ -62,16 +74,50 @@ export function groupBy(items: StoryListItem[], key: GroupKey, ctx: GroupContext
 
 function sortGroupKeys(keys: string[], groupKey: GroupKey, includeEmpty: boolean): string[] {
   if (groupKey === "state") {
-    const all = STORY_STATES.map(s => s.value);
-    return includeEmpty ? all : all.filter(v => keys.includes(v));
+    return includeEmpty ? STATE_KEYS : STATE_KEYS.filter(v => keys.includes(v));
   }
   if (groupKey === "priority") {
-    const all = STORY_PRIORITIES.map(p => p.value);
-    return includeEmpty ? all : all.filter(v => keys.includes(v));
+    return includeEmpty ? PRIORITY_KEYS : PRIORITY_KEYS.filter(v => keys.includes(v));
   }
   return keys;
 }
 
+/** 维度的完整分组 key 全集。labels/createdBy 既不可跨组写字段也无可枚举的全集，返回空 */
+function universeKeys(groupKey: Exclude<GroupKey, "none">, ctx: GroupContext): string[] {
+  if (groupKey === "state") return STATE_KEYS;
+  if (groupKey === "priority") return PRIORITY_KEYS;
+  if (groupKey === "assignee") return [...ctx.users.map(u => u.id), "unassigned"];
+  if (groupKey === "project") return [...ctx.projects.map(p => p.id), "no-project"];
+  return [];
+}
+
+/**
+ * 拖拽期「虚显列」：按当前分组维度动态枚举全集，返回 items 为空的列节点。
+ * 看板在拖拽时把这些尚未渲染的列临时插入（否则空列不在 value 里，dnd-kit 认不出容器、无法投放），
+ * 松手即向该列对应的分组字段写值，刷新后成为真实列。
+ */
+export function groupUniverse(groupKey: GroupKey, ctx: GroupContext): GroupNode[] {
+  if (groupKey === "none" || GROUP_FIELD[groupKey] == null) return [];
+  return universeKeys(groupKey, ctx).map(k => ({
+    key: k,
+    label: resolveGroupLabel(k, groupKey, ctx),
+    icon: resolveGroupIcon(k, groupKey, ctx),
+    color: resolveGroupColor(k, groupKey),
+    items: [],
+  }));
+}
+
+/**
+ * 列元数据表（key → 节点）：服务端分组优先，缺失时回落到维度全集。
+ * 刚落卡而服务端尚未返回的列只有全集里有节点，回落保证标题取 i18n 文案而不是原始 key。
+ */
+export function buildGroupMeta(groups: GroupNode[], universe: GroupNode[]): Record<string, GroupNode> {
+  const map: Record<string, GroupNode> = {};
+  for (const node of universe) map[node.key] = node;
+  for (const group of groups) map[group.key] = group;
+  return map;
+}
+
 export function resolveGroupLabel(k: string, groupKey: GroupKey, ctx: GroupContext): string {
   if (groupKey === "state") return STATE_LABEL[k as keyof typeof STATE_LABEL]?.() ?? k;
   if (groupKey === "priority") return PRIORITY_LABEL[k as keyof typeof PRIORITY_LABEL]?.() ?? k;
@@ -144,4 +190,81 @@ export function resolveGroupColor(k: string, groupKey: GroupKey) {
   if (groupKey === "state") return STATE_COLOR[k as keyof typeof STATE_COLOR];
   if (groupKey === "priority") return PRIORITY_COLOR[k as keyof typeof PRIORITY_COLOR];
   return undefined;
+}
+
+/**
+ * 列浅底浓度由主题变量控制（globals.css：:root 5% / .dark 10%）——
+ * 浅色列是纯白卡片，同样浓度比深色下更重，故两套浓度分开。
+ */
+const TINT_ALPHA = "var(--kanban-column-tint)";
+
+/**
+ * tint 的合成基色 = 列实际所在的表面（globals.css 的 --kanban-column-tint-base 指向 main 背景）。
+ * 必须合成成**实色**而非 `transparent`：列内吸附的子分组头要用同色实底完全遮挡下层滚动内容，
+ * 半透明底会透出下层卡片。基色取表面色，故列本身外观与「透明叠在表面上」逐像素一致。
+ */
+const TINT_BASE = "var(--kanban-column-tint-base)";
+
+/** 无颜色来源的分组键统一用 muted，避免「没有色相还要染一层」的脏底 */
+const NEUTRAL_TINT = "bg-muted";
+
+export interface ColumnTint {
+  /** 语义色类（仅中性态使用） */
+  className?: string;
+  /** 行内底色（调色板变量或 hex + color-mix 按主题浓度淡化） */
+  backgroundColor?: string;
+}
+
+function mixTint(color: string): ColumnTint {
+  return { backgroundColor: `color-mix(in srgb, ${color} ${TINT_ALPHA}, ${TINT_BASE})` };
+}
+
+/**
+ * 状态列浅底色相（Tailwind 调色板变量）。浓度必须走 color-mix 变量而不能写成
+ * `bg-blue-500/10` 类名——类名的透明度写死，浅/深主题无法取不同浓度。
+ * 与 STATE_COLOR 的同族关系由 group-resolver.test.ts 锁定。
+ */
+export const STATE_COLUMN_TINT: Record<string, ColumnTint> = {
+  backlog: { className: NEUTRAL_TINT },
+  todo: mixTint("var(--color-blue-500)"),
+  in_progress: mixTint("var(--color-amber-500)"),
+  done: mixTint("var(--color-green-500)"),
+  cancelled: { className: NEUTRAL_TINT },
+};
+
+/**
+ * 优先级列浅底色相：PRIORITY_COLOR 只给文字色，列底色需单独给出同色系。
+ * 取 -600 与列头文字的 text-*-600 同色号（同族关系由单测锁定）。
+ */
+export const PRIORITY_COLUMN_TINT: Record<string, ColumnTint> = {
+  urgent: mixTint("var(--color-red-600)"),
+  high: mixTint("var(--color-orange-600)"),
+  medium: mixTint("var(--color-blue-600)"),
+  low: { className: NEUTRAL_TINT },
+  none: {},
+};
+
+/**
+ * 看板列底色。spec：分组图标/标签颜色的同色系较浅颜色，浓度随主题（见 globals.css）。
+ * - state：STATE_COLUMN_TINT（色相同族由单测锁定）
+ * - priority：PRIORITY_COLUMN_TINT
+ * - assignee：用户头像背景色；labels：标签色；均 color-mix 淡化
+ * - createdBy / project / none：无颜色来源，不着色（沿用 Card 的 bg-card）
+ */
+export function resolveColumnTint(
+  k: string,
+  groupKey: GroupKey,
+  ctx: GroupContext,
+): ColumnTint {
+  if (groupKey === "state") return STATE_COLUMN_TINT[k] ?? {};
+  if (groupKey === "priority") return PRIORITY_COLUMN_TINT[k] ?? {};
+  if (groupKey === "assignee" && k !== "unassigned") {
+    const bgColor = ctx.users.find((u) => u.id === k)?.bgColor;
+    return bgColor ? mixTint(bgColor) : {};
+  }
+  if (groupKey === "labels" && k !== "no-labels") {
+    const color = ctx.labels.find((l) => l.id === k)?.color;
+    return color ? mixTint(color) : {};
+  }
+  return {};
 }

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

@@ -15,40 +15,32 @@
 // 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 { StoryListItem, UserBrief } from "../types";
-
-export const GROUP_KEYS = [
-  "state", "priority", "assignee", "labels", "createdBy", "project", "none",
-] as const;
-export type GroupKey = (typeof GROUP_KEYS)[number];
-
-export const ORDER_KEYS = [
-  "manual", "created", "updated", "startDate", "dueDate", "priority",
-] as const;
-export type OrderKey = (typeof ORDER_KEYS)[number];
-
-export const ORDER_DIRECTIONS = ["asc", "desc"] as const;
-export type OrderDirection = (typeof ORDER_DIRECTIONS)[number];
+// story 显示选项类型桶 = 共享 list-kit display 类型/常量的 story 口径 re-export
+// （UI 对齐一期 PR-3 任务 13：类型收拢至 shared-kit/list-kit/display，键联合
+// 与运行时常量为 story 规范口径落共享层 values.ts，此处仅透传保持消费方
+// import 不变）。story 专属的 GroupNode/GroupContext 留本文件。
 
-export const ALL_DISPLAY_PROPERTIES = [
-  "id", "project", "assignee", "startDate", "dueDate",
-  "labels", "priority", "state", "subCount", "attachmentCount",
-] as const;
-export type DisplayProperty = (typeof ALL_DISPLAY_PROPERTIES)[number];
+import type { StoryListItem, UserBrief } from "../types";
 
-export interface DisplayOptions {
-  groupBy: GroupKey;
-  subGroupBy: GroupKey;
-  orderBy: OrderKey;
-  orderDir: OrderDirection;
-  properties: DisplayProperty[];
-  showEmptyGroups: boolean;
-  showSubItems: boolean;
-  pageSize: PageSize;
-}
+export {
+  GROUP_KEYS,
+  ORDER_KEYS,
+  ORDER_DIRECTIONS,
+  resolveOrderDir,
+  ALL_DISPLAY_PROPERTIES,
+  PAGE_SIZE_OPTIONS,
+  DEFAULT_DISPLAY_OPTIONS,
+} from "@/components/shared-kit/list-kit/display/values";
 
-export const PAGE_SIZE_OPTIONS = [100, 200, 500, 1000] as const;
-export type PageSize = (typeof PAGE_SIZE_OPTIONS)[number];
+export type {
+  DisplayOptions,
+  DisplayOptionsCore,
+  DisplayProperty,
+  GroupKey,
+  OrderDirection,
+  OrderKey,
+  PageSize,
+} from "@/components/shared-kit/list-kit/display/types";
 
 export interface GroupNode {
   key: string;
@@ -72,14 +64,3 @@ export interface GroupContext {
   labels: { id: string; name: string; color: string }[];
   projects: { id: string; name: string; displayId: string | null; icon: string }[];
 }
-
-export const DEFAULT_DISPLAY_OPTIONS: DisplayOptions = {
-  groupBy: "state",
-  subGroupBy: "none",
-  orderBy: "created",
-  orderDir: "desc",
-  properties: ["id", "project", "assignee", "startDate", "dueDate", "labels", "priority", "state"],
-  showEmptyGroups: false,
-  showSubItems: false,
-  pageSize: 100,
-};

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

@@ -0,0 +1,109 @@
+// 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 { useCallback, useEffect, useRef, useState } from "react";
+
+export const COLLAPSED_SUBGROUPS_KEY = "story.kanban.collapsedSubGroups";
+
+/** 折叠键 = 列 key + 子分组维度 + 子分组 key：同一子分组在各列内独立折叠 */
+export function collapseKey(columnKey: string, subGroupBy: string, subKey: string): string {
+  return `${columnKey}:${subGroupBy}:${subKey}`;
+}
+
+export function parseCollapsed(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((value): value is string => typeof value === "string");
+  } catch {
+    return [];
+  }
+}
+
+export function serializeCollapsed(keys: ReadonlySet<string>): string {
+  return JSON.stringify([...keys]);
+}
+
+/** 折叠键至少 2 个冒号（列键 + 维度 + 子键）；旧版「维度级」键只有 1 个，无法映射到列，读取时丢弃 */
+export function isCollapseKey(value: string): boolean {
+  return value.split(":").length >= 3;
+}
+
+export function toggleCollapsed(keys: ReadonlySet<string>, key: string): Set<string> {
+  const next = new Set(keys);
+  if (next.has(key)) next.delete(key);
+  else next.add(key);
+  return next;
+}
+
+/** 批量设置（列头的「全部展开 / 全部折叠」）：整体添加或删除，不动其他列的键 */
+export function setCollapsedMany(
+  keys: ReadonlySet<string>,
+  targets: readonly string[],
+  collapsed: boolean,
+): Set<string> {
+  const next = new Set(keys);
+  for (const key of targets) {
+    if (collapsed) next.add(key);
+    else next.delete(key);
+  }
+  return next;
+}
+
+/**
+ * 子分组折叠状态（localStorage 持久化）。
+ * 读写分居两个 effect：restore effect 用 skipWriteRef 抑制同一次 commit 内 write effect 的默认值回写，
+ * 否则挂载瞬间会用空集合覆盖已保存值（该信号必须走 ref，不能靠额外的 restored state gate——restore 不触发重渲时 gate 形同虚设）。
+ */
+export function useCollapsedSubGroups() {
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set<string>());
+  const skipWriteRef = useRef(false);
+
+  useEffect(() => {
+    let saved: string | null = null;
+    try {
+      saved = window.localStorage.getItem(COLLAPSED_SUBGROUPS_KEY);
+    } catch {
+      saved = null;
+    }
+    skipWriteRef.current = saved !== null;
+    setCollapsed(new Set(parseCollapsed(saved).filter(isCollapseKey)));
+  }, []);
+
+  useEffect(() => {
+    if (skipWriteRef.current) {
+      skipWriteRef.current = false;
+      return;
+    }
+    try {
+      window.localStorage.setItem(COLLAPSED_SUBGROUPS_KEY, serializeCollapsed(collapsed));
+    } catch {
+      // 隐私模式 / 配额超限：折叠状态退化为会话内状态
+    }
+  }, [collapsed]);
+
+  const toggle = useCallback((key: string) => {
+    setCollapsed((prev) => toggleCollapsed(prev, key));
+  }, []);
+
+  const setMany = useCallback((targets: readonly string[], collapsed: boolean) => {
+    setCollapsed((prev) => setCollapsedMany(prev, targets, collapsed));
+  }, []);
+
+  return { collapsed, toggle, setMany } as const;
+}

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

@@ -18,7 +18,7 @@
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import type { StoryView } from "../views/view-switcher";
 import type { DisplayOptions } from "./types";
-import { DEFAULT_DISPLAY_OPTIONS } from "./types";
+import { DEFAULT_DISPLAY_OPTIONS, resolveOrderDir } from "./types";
 import { LAYOUT_SUPPORT } from "./constants";
 import { getStoryDisplayOptionsFn, updateStoryDisplayOptionsFn } from "@/server/serverFns/story-display-options";
 
@@ -28,10 +28,19 @@ export function filterDisplayOptionsForLayout(
 ): DisplayOptions {
   const support = LAYOUT_SUPPORT[layout];
   const orderBy = support.orderBy ? options.orderBy : DEFAULT_DISPLAY_OPTIONS.orderBy;
-  const orderDir = support.orderBy ? options.orderDir : DEFAULT_DISPLAY_OPTIONS.orderDir;
+  const orderDir = support.orderBy
+    ? resolveOrderDir(orderBy, options.orderDir)
+    : DEFAULT_DISPLAY_OPTIONS.orderDir;
+  // iteration 为甘特专属维度（GROUP_KEYS 数组之外）：持久化的 DisplayOptions
+  // 全局共享一份，timeline 存下的 iteration 流到 list/board 会命中
+  // group-resolver 无桶语义的键——非 timeline 布局 clamp 回默认分组
   return {
-    groupBy: support.groupBy ? options.groupBy : DEFAULT_DISPLAY_OPTIONS.groupBy,
-    subGroupBy: support.subGroupBy ? options.subGroupBy : DEFAULT_DISPLAY_OPTIONS.subGroupBy,
+    groupBy: support.groupBy && (options.groupBy !== "iteration" || layout === "timeline")
+      ? options.groupBy
+      : DEFAULT_DISPLAY_OPTIONS.groupBy,
+    subGroupBy: support.subGroupBy && options.subGroupBy !== "iteration"
+      ? options.subGroupBy
+      : DEFAULT_DISPLAY_OPTIONS.subGroupBy,
     orderBy,
     orderDir,
     properties: support.properties ? options.properties : DEFAULT_DISPLAY_OPTIONS.properties,
@@ -42,6 +51,7 @@ export function filterDisplayOptionsForLayout(
     showSubItems:
       layout === "list" ? options.showSubItems : DEFAULT_DISPLAY_OPTIONS.showSubItems,
     pageSize: options.pageSize,
+    columnOrder: options.columnOrder,
   };
 }
 
@@ -73,7 +83,13 @@ export function useDisplayOptions(layout: StoryView): DisplayOptionsState {
   const updateFilters = useCallback((patch: Partial<DisplayOptions>) => {
     setRawFilters((prev) => {
       const next = { ...prev, ...patch };
-      void updateStoryDisplayOptionsFn({ data: next }).catch(() => {});
+      // subGroupBy 无 iteration 维度（GROUP_KEYS 数组不含、UI 不可达）——
+      // 持久化前归一，对齐 serverFn validator 的 GROUP_KEYS 严格集
+      const persistableSubGroupBy =
+        next.subGroupBy === "iteration" ? "none" : next.subGroupBy;
+      void updateStoryDisplayOptionsFn({
+        data: { ...next, subGroupBy: persistableSubGroupBy },
+      }).catch(() => {});
       return next;
     });
   }, []);

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

@@ -0,0 +1,124 @@
+// 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 { useCallback, useEffect, useRef, useState } from "react";
+import type { RefObject } from "react";
+
+/**
+ * 计算一行内能完整显示的项数（宽度自适应）。
+ *
+ * - 全部装得下 → 返回全部数量（调用方无需渲染 +N 指示器）
+ * - 装不下时按「+N 指示器 + 间距」占位后的可用宽度求前缀项数，返回 0 表示只显示指示器
+ * - `containerWidth <= 0`（SSR / jsdom 未测量）→ 回落返回全部数量，避免首帧隐藏内容
+ */
+export function computeFitCount(
+  itemWidths: number[],
+  containerWidth: number,
+  indicatorWidth: number,
+  gap: number,
+): number {
+  const total = prefixWidth(itemWidths, itemWidths.length, gap);
+  if (containerWidth <= 0 || total <= containerWidth) return itemWidths.length;
+  const available = containerWidth - indicatorWidth - gap;
+  for (let count = itemWidths.length - 1; count >= 1; count -= 1) {
+    if (prefixWidth(itemWidths, count, gap) <= available) return count;
+  }
+  return 0;
+}
+
+function prefixWidth(widths: number[], count: number, gap: number): number {
+  let total = 0;
+  for (let i = 0; i < count; i += 1) {
+    total += widths[i] + (i > 0 ? gap : 0);
+  }
+  return total;
+}
+
+interface FitCountRefs {
+  /** 可视容器：宽度即可用空间 */
+  containerRef: RefObject<HTMLDivElement | null>;
+  /** 隐藏测量层：子元素为全量项目（顺序与可视项一致） */
+  measureRef: RefObject<HTMLDivElement | null>;
+  /** 隐藏的 +N 指示器：提供指示器实际宽度 */
+  indicatorRef: RefObject<HTMLSpanElement | null>;
+  visibleCount: number;
+}
+
+/**
+ * 宽度自适应「能放几个」：隐藏测量层取各项目与指示器实宽，
+ * ResizeObserver 监听容器/测量层尺寸（列宽变化、文案变化）后重算。
+ * 测量未就绪时（SSR、jsdom）返回全部数量。
+ *
+ * - ResizeObserver 回调合并到单帧执行（同帧多次尺寸变化只测一次，避免连续强制重排）。
+ * - 重算结果与当前一致时不写 state，避免无意义的重渲染连锁。
+ * - `enabled=false` 时不观察、不测量（如拖拽中卡片被整体重排，逐帧测量只是纯开销）。
+ */
+export function useFitCount(itemCount: number, gap: number, enabled = true): FitCountRefs {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const measureRef = useRef<HTMLDivElement | null>(null);
+  const indicatorRef = useRef<HTMLSpanElement | null>(null);
+  const [visibleCount, setVisibleCount] = useState(itemCount);
+  const frameRef = useRef<number | null>(null);
+
+  const measure = useCallback(() => {
+    const container = containerRef.current;
+    const measureLayer = measureRef.current;
+    if (!container || !measureLayer) return;
+    const itemWidths = Array.from(measureLayer.children).map(
+      (el) => el.getBoundingClientRect().width,
+    );
+    const indicatorWidth = indicatorRef.current?.getBoundingClientRect().width ?? 0;
+    const next = computeFitCount(
+      itemWidths,
+      container.getBoundingClientRect().width,
+      indicatorWidth,
+      gap,
+    );
+    setVisibleCount((prev) => (prev === next ? prev : next));
+  }, [gap]);
+
+  const scheduleMeasure = useCallback(() => {
+    if (typeof requestAnimationFrame === "undefined") {
+      measure();
+      return;
+    }
+    if (frameRef.current !== null) return;
+    frameRef.current = requestAnimationFrame(() => {
+      frameRef.current = null;
+      measure();
+    });
+  }, [measure]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(scheduleMeasure);
+    if (containerRef.current) observer.observe(containerRef.current);
+    if (measureRef.current) observer.observe(measureRef.current);
+    if (indicatorRef.current) observer.observe(indicatorRef.current);
+    return () => {
+      observer.disconnect();
+      if (frameRef.current !== null && typeof cancelAnimationFrame !== "undefined") {
+        cancelAnimationFrame(frameRef.current);
+      }
+      frameRef.current = null;
+    };
+  }, [measure, scheduleMeasure, itemCount, enabled]);
+
+  return { containerRef, measureRef, indicatorRef, visibleCount };
+}