@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/shared-kit/list-kit/display/dropdown.tsx

@@ -0,0 +1,582 @@
+// 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/>.
+
+// list-kit display 参数化工厂（设计 §4.6 / UI 对齐一期 PR-3 任务 13）。
+// 以 story/display/display-dropdown.tsx 为蓝本收拢：键集/文案/图标/分区支持
+// 矩阵经 config 注入（story 携 layout 感知的 resolve* 实现，bug 为静态矩阵），
+// 分区渲染逻辑/交互/hover 类与原实现逐行一致；仅 React 运行时，禁止被
+// serverFn 值导入（类型走 ./types、常量走 ./values）。通用分区文案走
+// list_kit_display_* i18n 域，字段级 label 留各模块 config。
+
+import { useMemo, useState } from "react";
+import {
+  ArrowDownNarrowWide,
+  ArrowUpWideNarrow,
+  Check,
+  ChevronDown,
+  ChevronRight,
+  Lock,
+  type LucideIcon,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Switch } from "@/components/ui/switch";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import { useFeature } from "@/components/billing/use-feature";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { cn } from "@/lib/utils";
+import { implementedModules } from "@/plugins/modules.gen";
+import { m } from "@/paraglide/messages.js";
+import type { DisplayOptionsCore } from "./types";
+
+// ---------------------------------------------------------------------------
+// config 与分区支持矩阵
+// ---------------------------------------------------------------------------
+
+/** 各分区显隐（story 由 LAYOUT_SUPPORT[layout] 派生；bug 为静态矩阵） */
+export interface DisplaySectionsSupport {
+  properties: boolean;
+  groupBy: boolean;
+  subGroupBy: boolean;
+  orderBy: boolean;
+  /** 附加选项区（空组/子需求开关 + 每页数量） */
+  options: boolean;
+  /** 空分组开关行显隐（story 在 options 区恒显；bug 不渲染该行） */
+  showEmptyGroupsRow: boolean;
+  /** 空分组开关值生效（story 语义 = options && groupBy；不支持时强制 false） */
+  showEmptyGroupsEnabled: boolean;
+  /** 子需求开关（story 语义 = layout === "list"，可被 props.showSubItems 覆盖） */
+  showSubItems: boolean;
+}
+
+export interface DisplayDropdownContext<GK extends string = string> {
+  layout?: string;
+  projectId?: string;
+  groupBy: GK;
+}
+
+export interface DisplayDropdownConfig<
+  Opt extends DisplayOptionsCore<GK, OK, P>,
+  GK extends string = string,
+  OK extends string = string,
+  P extends string = string,
+> {
+  /** 分组键全集（per-layout 收敛经 resolveGroupKeys） */
+  groupKeys: readonly GK[];
+  orderKeys: readonly OK[];
+  availableProperties: readonly P[];
+  groupLabels: Record<GK, () => string>;
+  orderLabels: Record<OK, () => string>;
+  propertyLabels: Record<P, () => string>;
+  groupIcons: Record<GK, LucideIcon>;
+  orderIcons: Record<OK, LucideIcon>;
+  pageSizeOptions: readonly number[];
+  /** 「不分组」键（子分组禁用判定） */
+  noneGroupKey: GK;
+  /** 分区支持矩阵：静态（bug）或按 layout/projectId/groupBy 派生（story） */
+  support:
+    | DisplaySectionsSupport
+    | ((ctx: DisplayDropdownContext<GK>) => DisplaySectionsSupport);
+  /** 偏离默认值判定（触发器蓝点） */
+  hasChanges: (filters: Opt, layout?: string) => boolean;
+  resolveGroupKeys?: (ctx: DisplayDropdownContext<GK>) => readonly GK[];
+  resolveSubGroupKeys?: (ctx: DisplayDropdownContext<GK>) => readonly GK[];
+  resolveProperties?: (ctx: { layout?: string }) => readonly P[];
+  /** 排序方向按钮显隐（story：manual 隐藏；bug 缺省恒显） */
+  orderDirVisible?: (filters: Opt) => boolean;
+  triggerIcon: LucideIcon;
+  triggerAriaLabel: () => string;
+  triggerTooltip: () => string;
+  triggerTestId?: string;
+  /** 各分区 data-testid 前缀（bug 形态 display-<name>-section；story 不加） */
+  sectionTestIdPrefix?: string;
+}
+
+export interface DisplayDropdownComponentProps<Opt> {
+  filters: Opt;
+  onChange: (patch: Partial<Opt>) => void;
+  layout?: string;
+  projectId?: string;
+  /** 兼容 story 旧签名（body 恒读 filters.pageSize，此 prop 现状未被消费） */
+  pageSize?: number;
+  onPageSizeChange?: (size: number) => void;
+  /** 排序区与附加选项区之间的插槽（story 保存视图区） */
+  beforeOptions?: React.ReactNode;
+}
+
+export interface DisplayOptionsBodyProps<Opt> extends DisplayDropdownComponentProps<Opt> {
+  /** 覆盖 support.showSubItems（详情页子需求面板传 false 关掉开关） */
+  showSubItems?: boolean;
+}
+
+export interface DisplayDropdownModule<
+  Opt extends DisplayOptionsCore<GK, OK, P>,
+  GK extends string = string,
+  OK extends string = string,
+  P extends string = string,
+> {
+  DisplayDropdown(props: DisplayDropdownComponentProps<Opt>): React.ReactNode;
+  DisplayOptionsBody(props: DisplayOptionsBodyProps<Opt>): React.ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// 工厂
+// ---------------------------------------------------------------------------
+
+export function createDisplayDropdown<
+  Opt extends DisplayOptionsCore<GK, OK, P>,
+  GK extends string = string,
+  OK extends string = string,
+  P extends string = string,
+>(config: DisplayDropdownConfig<Opt, GK, OK, P>): DisplayDropdownModule<Opt, GK, OK, P> {
+  const sectionTestId = (name: string) =>
+    config.sectionTestIdPrefix ? `${config.sectionTestIdPrefix}-${name}-section` : undefined;
+
+  const resolveSupport = (ctx: DisplayDropdownContext<GK>): DisplaySectionsSupport =>
+    typeof config.support === "function" ? config.support(ctx) : config.support;
+
+  /** 单选分区（分组/子分组/排序共用；折叠态局部维护）。K 为该分区键联合
+   * （分组/子分组用 GK、排序用 OK），避免三区共用 GK 导致的交叉断言 */
+  function InlineRadioSection<K extends string>({
+    dataSection,
+    label,
+    value,
+    optionKeys,
+    iconMap,
+    labelMap,
+    disabled = false,
+    onSelect,
+    orderDir,
+    onOrderDirChange,
+  }: {
+    dataSection: string;
+    label: string;
+    value: string;
+    optionKeys: readonly K[];
+    iconMap: Record<K, LucideIcon>;
+    labelMap: Record<K, () => string>;
+    disabled?: boolean;
+    onSelect: (value: K) => void;
+    orderDir?: OrderDirectionLike;
+    onOrderDirChange?: (dir: OrderDirectionLike) => void;
+  }) {
+    const [collapsed, setCollapsed] = useState(false);
+    const options: { value: K; label: string; icon: LucideIcon }[] = optionKeys.map((k) => ({
+      value: k,
+      label: labelMap[k]?.() ?? k,
+      icon: iconMap[k] as LucideIcon,
+    }));
+
+    return (
+      <div
+        data-section={dataSection}
+        data-testid={sectionTestId(dataSection)}
+        className="border-t px-3 py-2"
+      >
+        <div className="mb-1 flex items-center justify-between gap-1">
+          <button
+            type="button"
+            onClick={() => setCollapsed(!collapsed)}
+            className="flex w-full items-center gap-1 text-xs font-medium text-muted-foreground hover:text-foreground"
+          >
+            {collapsed ? <ChevronRight className="size-3" /> : <ChevronDown className="size-3" />}
+            {label}
+          </button>
+          {orderDir !== undefined && onOrderDirChange && (
+            <div className="flex items-center gap-0.5">
+              <div className="flex items-center rounded ">
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  data-testid="order-dir-asc"
+                  aria-label={m.list_kit_display_asc()}
+                  className={cn(
+                    "size-6 rounded p-0 text-xs text-muted-foreground hover:bg-muted hover:text-foreground",
+                    orderDir === "asc" && "bg-muted text-foreground",
+                  )}
+                  onClick={() => onOrderDirChange("asc")}
+                >
+                  <ArrowDownNarrowWide className="size-3" />
+                </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  data-testid="order-dir-desc"
+                  aria-label={m.list_kit_display_desc()}
+                  className={cn(
+                    "size-6 rounded p-0 text-xs text-muted-foreground hover:bg-muted hover:text-foreground",
+                    orderDir === "desc" && "bg-muted text-foreground",
+                  )}
+                  onClick={() => onOrderDirChange("desc")}
+                >
+                  <ArrowUpWideNarrow className="size-3" />
+                </Button>
+              </div>
+            </div>
+          )}
+        </div>
+        {!collapsed && (
+          <div className="flex flex-col gap-0.5">
+            {options.map((o) => {
+              const Icon = o.icon;
+              const selected = o.value === value;
+              return (
+                <button
+                  key={o.value}
+                  type="button"
+                  disabled={disabled}
+                  onClick={() => onSelect(o.value)}
+                  className={cn(
+                    "flex w-full items-center gap-2 rounded-sm px-1.5 py-1 text-xs text-left hover:bg-muted",
+                    disabled && "cursor-not-allowed opacity-50",
+                  )}
+                >
+                  <span
+                    className={cn(
+                      "grid size-3.5 shrink-0 place-items-center rounded-full border",
+                      selected
+                        ? "border-primary bg-primary text-primary-foreground"
+                        : "border-border",
+                    )}
+                  >
+                    {selected && <Check className="size-2.5" strokeWidth={3} />}
+                  </span>
+                  {Icon && <Icon className="size-3.5 shrink-0 text-muted-foreground" />}
+                  <span className="text-foreground">{o.label}</span>
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  /** 属性 chips 区（勾选显隐列） */
+  function PropertiesSection({
+    selected,
+    onChange: onPropsChange,
+    available,
+  }: {
+    selected: P[];
+    onChange: (props: P[]) => void;
+    available: readonly P[];
+  }) {
+    const [collapsed, setCollapsed] = useState(false);
+    const toggle = (prop: P) => {
+      onPropsChange(
+        available.includes(prop)
+          ? selected.includes(prop)
+            ? selected.filter((p) => p !== prop)
+            : [...selected, prop]
+          : selected,
+      );
+    };
+
+    return (
+      <div
+        data-section="properties"
+        data-testid={sectionTestId("properties")}
+        className=" px-3 py-2"
+      >
+        <button
+          type="button"
+          onClick={() => setCollapsed(!collapsed)}
+          className="mb-1.5 flex w-full items-center gap-1 text-xs font-medium text-muted-foreground hover:text-foreground"
+        >
+          {collapsed ? <ChevronRight className="size-3" /> : <ChevronDown className="size-3" />}
+          {m.list_kit_display_showProperties()}
+        </button>
+        {!collapsed && (
+          <div className="flex flex-wrap gap-1.5">
+            {available.map((prop) => {
+              const checked = selected.includes(prop);
+              return (
+                <button
+                  key={prop}
+                  type="button"
+                  onClick={() => toggle(prop)}
+                  className={cn(
+                    "rounded border px-2 py-0.5 text-xs transition-all",
+                    checked
+                      ? "border-primary bg-primary text-primary-foreground"
+                      : "border-border text-muted-foreground hover:bg-muted hover:text-foreground",
+                  )}
+                >
+                  {config.propertyLabels[prop]?.() ?? prop}
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  /** 附加选项区：空组/子需求开关 + 每页数量（500/1000 为 largePageSize 专属） */
+  function OptionsSection({
+    showEmptyGroups,
+    showEmptyGroupsRow,
+    showSubItems,
+    showSubItemsSupported,
+    onShowEmptyChange,
+    onShowSubChange,
+    pageSize,
+    onPageSizeChange,
+  }: {
+    showEmptyGroups: boolean;
+    showEmptyGroupsRow: boolean;
+    showSubItems: boolean;
+    showSubItemsSupported: boolean;
+    onShowEmptyChange: (v: boolean) => void;
+    onShowSubChange: (v: boolean) => void;
+    pageSize: number;
+    onPageSizeChange: (v: number) => void;
+  }) {
+    // OSS 环境（billing 模块未实现）只显示 100/200；Pro 环境显示全部
+    const sizeOptions = implementedModules.billing
+      ? config.pageSizeOptions
+      : ([100, 200] as const);
+    const { enabled: largePageSizeEnabled, loading: largePageSizeLoading } =
+      useFeature("largePageSize");
+
+    const isPageSizeLocked = (v: number) =>
+      v > 200 && !largePageSizeEnabled && !largePageSizeLoading;
+
+    const pageSizeRow = (className: string) => (
+      <div className={className}>
+        <span className="text-xs text-muted-foreground">{m.list_kit_display_pageSize()}</span>
+        <div className="flex items-center gap-0.5 rounded border border-border p-0.5">
+          {sizeOptions.map((v) => {
+            const locked = isPageSizeLocked(v);
+            const checked = v === pageSize && !locked;
+            return (
+              <button
+                key={v}
+                type="button"
+                disabled={locked}
+                onClick={() => onPageSizeChange(v)}
+                className={cn(
+                  "inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[10px] font-medium transition-all",
+                  checked
+                    ? "bg-primary text-primary-foreground"
+                    : locked
+                      ? "cursor-not-allowed text-muted-foreground/50 hover:bg-transparent"
+                      : "text-muted-foreground hover:bg-muted hover:text-foreground",
+                )}
+              >
+                {v}
+                {locked && <Lock size={10} aria-hidden />}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    );
+
+    const showEmptySwitch = showEmptyGroupsRow;
+    const showSubRow = showSubItemsSupported;
+
+    return (
+      <div data-section="options" data-testid={sectionTestId("options")} className="border-t px-3 py-2">
+        <div className="flex items-center justify-between gap-2 py-0.5">
+          <span className="text-xs font-medium text-foreground">
+            {m.list_kit_display_extraOptions()}
+          </span>
+        </div>
+        {showEmptySwitch || showSubRow ? (
+          <div className="mt-1 flex flex-col gap-1">
+            {showEmptySwitch && (
+              <label className="flex cursor-pointer items-center justify-between py-1">
+                <span className="text-xs text-muted-foreground">
+                  {m.list_kit_display_showEmptyGroups()}
+                </span>
+                <Switch checked={showEmptyGroups} onCheckedChange={onShowEmptyChange} size="sm" />
+              </label>
+            )}
+            {showSubRow && (
+              <label className="flex cursor-pointer items-center justify-between py-1">
+                <span className="text-xs text-muted-foreground">
+                  {m.list_kit_display_showSubItems()}
+                </span>
+                <Switch checked={showSubItems} onCheckedChange={onShowSubChange} size="sm" />
+              </label>
+            )}
+            {pageSizeRow("flex items-center justify-between py-1")}
+          </div>
+        ) : (
+          pageSizeRow("mt-1 flex items-center justify-between py-1")
+        )}
+      </div>
+    );
+  }
+
+  /** 分区组合体（详情页等自带 Popover 的消费方直接挂载） */
+  function DisplayOptionsBody({
+    filters,
+    onChange,
+    layout,
+    projectId,
+    onPageSizeChange,
+    showSubItems,
+    beforeOptions,
+  }: DisplayOptionsBodyProps<Opt>) {
+    const ctx: DisplayDropdownContext<GK> = { layout, projectId, groupBy: filters.groupBy };
+    const support = resolveSupport(ctx);
+    const showSubItemsEnabled = showSubItems ?? support.showSubItems;
+    // 子分组/开关字段仅部分模块 options 持有（bug 无 subGroupBy 等），
+    // support 关闭时下方分支不读取，此处 Partial 视角安全
+    const ext = filters as Partial<
+      DisplayOptionsCore<GK, OK, P> & Pick<DisplayOptionsLike<GK>, "subGroupBy" | "showEmptyGroups" | "showSubItems">
+    >;
+    const groupKeys =
+      config.resolveGroupKeys?.(ctx) ?? [...config.groupKeys];
+    const subGroupKeys =
+      config.resolveSubGroupKeys?.(ctx) ??
+      config.groupKeys.filter((k) => k !== filters.groupBy);
+    const availableProperties = config.resolveProperties?.({ layout }) ?? config.availableProperties;
+    const orderDirShown = config.orderDirVisible ? config.orderDirVisible(filters) : true;
+    // 泛型组件边界：subGroupBy/showEmptyGroups/showSubItems 仅部分模块 options
+    // 持有，support 开关关闭时对应分支不读取不发送
+    const patch = (p: object) => p as unknown as Partial<Opt>;
+
+    return (
+      <>
+        {support.properties && (
+          <PropertiesSection
+            selected={filters.properties}
+            onChange={(props) => onChange(patch({ properties: props }))}
+            available={availableProperties}
+          />
+        )}
+        {support.groupBy && (
+          <InlineRadioSection
+            dataSection="groupBy"
+            label={m.list_kit_display_group()}
+            value={filters.groupBy}
+            optionKeys={groupKeys}
+            iconMap={config.groupIcons}
+            labelMap={config.groupLabels}
+            onSelect={(v) => onChange(patch({ groupBy: v }))}
+          />
+        )}
+        {support.subGroupBy && (
+          <InlineRadioSection
+            dataSection="subGroupBy"
+            label={m.list_kit_display_subGroup()}
+            value={ext.subGroupBy ?? config.noneGroupKey}
+            optionKeys={subGroupKeys}
+            iconMap={config.groupIcons}
+            labelMap={config.groupLabels}
+            disabled={filters.groupBy === config.noneGroupKey}
+            onSelect={(v) => onChange(patch({ subGroupBy: v }))}
+          />
+        )}
+        {support.orderBy && (
+          <InlineRadioSection
+            dataSection="orderBy"
+            label={m.list_kit_display_order()}
+            value={filters.orderBy}
+            optionKeys={[...config.orderKeys]}
+            iconMap={config.orderIcons}
+            labelMap={config.orderLabels}
+            onSelect={(v) => onChange(patch({ orderBy: v }))}
+            orderDir={orderDirShown ? filters.orderDir : undefined}
+            onOrderDirChange={(dir) => onChange(patch({ orderDir: dir }))}
+          />
+        )}
+        {beforeOptions}
+        {support.options && (
+          <OptionsSection
+            showEmptyGroups={support.showEmptyGroupsEnabled ? (ext.showEmptyGroups ?? false) : false}
+            showEmptyGroupsRow={support.showEmptyGroupsRow}
+            showSubItems={showSubItemsEnabled ? (ext.showSubItems ?? false) : false}
+            showSubItemsSupported={showSubItemsEnabled}
+            onShowEmptyChange={(v) => onChange(patch({ showEmptyGroups: v }))}
+            onShowSubChange={(v) => onChange(patch({ showSubItems: v }))}
+            pageSize={filters.pageSize}
+            onPageSizeChange={onPageSizeChange ?? ((v) => onChange(patch({ pageSize: v })))}
+          />
+        )}
+      </>
+    );
+  }
+
+  /** 触发器壳（Popover + Tooltip + 蓝点高亮）+ 分区组合体 */
+  function DisplayDropdown({
+    filters,
+    onChange,
+    layout,
+    projectId,
+    onPageSizeChange,
+    beforeOptions,
+  }: DisplayDropdownComponentProps<Opt>) {
+    const changed = useMemo(() => config.hasChanges(filters, layout), [filters, layout]);
+    const TriggerIcon = config.triggerIcon;
+
+    return (
+      <Popover>
+        <Tooltip>
+          <PopoverTrigger render={<TooltipTrigger render={<Button variant="outline"
+                size="sm"
+                aria-label={config.triggerAriaLabel()}
+                data-testid={config.triggerTestId}
+                className={cn(
+                  "relative h-8 gap-1.5 px-2.5 text-sm font-normal",
+                  changed && "border-primary/50 bg-primary/5 text-primary",
+                )} />} />}>
+                <TriggerIcon className="size-4" />
+                {changed && (
+                  <span
+                    className="absolute right-1 top-1 size-1.5 rounded-full bg-primary"
+                    aria-hidden
+                  />
+                )}
+              </PopoverTrigger>
+          <TooltipContent side="bottom">{config.triggerTooltip()}</TooltipContent>
+        </Tooltip>
+        <PopoverContent className="w-75 p-0" align="start">
+          <div className="max-h-[70vh] overflow-y-auto">
+            <DisplayOptionsBody
+              filters={filters}
+              onChange={onChange}
+              layout={layout}
+              projectId={projectId}
+              onPageSizeChange={onPageSizeChange}
+              beforeOptions={beforeOptions}
+            />
+          </div>
+        </PopoverContent>
+      </Popover>
+    );
+  }
+
+  return { DisplayDropdown, DisplayOptionsBody };
+}
+
+// ---------------------------------------------------------------------------
+// 工厂内部结构类型（避免依赖 story 侧类型别名）
+// ---------------------------------------------------------------------------
+
+type OrderDirectionLike = "asc" | "desc";
+
+interface DisplayOptionsLike<GK extends string = string> {
+  subGroupBy: GK;
+  showEmptyGroups: boolean;
+  showSubItems: boolean;
+}

package/src/components/shared-kit/list-kit/display/types.ts

@@ -0,0 +1,64 @@
+// 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/>.
+
+// list-kit display 纯类型层（设计 §4.6：serverFn 可安全 import type——
+// 本文件零运行时导出、零 React/组件依赖；键联合经 `typeof` 引用
+// ./values 的常量，import type 编译期擦除）。
+//
+// 键联合为 story 规范口径（GROUP_KEYS 等常量落 ./values，见其头注）；
+// bug 等其余模块不消费本文件的窄化别名，只消费 DisplayOptionsCore
+// 泛型基型实例化自己的 options 类型（模式同 filters 的 K 泛型先例）。
+
+import type { ORDER_DIRECTIONS, ORDER_KEYS, GROUP_KEYS, ALL_DISPLAY_PROPERTIES, PAGE_SIZE_OPTIONS } from "./values";
+
+export type OrderDirection = (typeof ORDER_DIRECTIONS)[number];
+export type OrderKey = (typeof ORDER_KEYS)[number];
+export type GroupKey = (typeof GROUP_KEYS)[number] | "iteration";
+export type DisplayProperty = (typeof ALL_DISPLAY_PROPERTIES)[number];
+export type PageSize = (typeof PAGE_SIZE_OPTIONS)[number];
+
+/**
+ * 显示选项泛型基型：本仓 list 视图族（story/bug…）共享的字段骨架。
+ * GK/OK/P 由各模块键联合窄化，PS 窄化每页数量档位；子分组/空组开关等
+ * 字段仅部分模块持有，工厂内部按 support 开关按需读取（Partial 视角）。
+ */
+export interface DisplayOptionsCore<
+  GK extends string = string,
+  OK extends string = string,
+  P extends string = string,
+  PS extends number = number,
+> {
+  groupBy: GK;
+  orderBy: OK;
+  orderDir: OrderDirection;
+  properties: P[];
+  pageSize: PS;
+}
+
+/**
+ * story 全量显示选项（含子分组/空组/子需求/列顺序）。"iteration" 为甘特
+ * 专属分组维度：不在 GROUP_KEYS 数组内，仅 timeline 选项可达（跨布局由
+ * filterDisplayOptionsForLayout clamp，见 story/display/use-display-options）。
+ */
+export interface DisplayOptions
+  extends DisplayOptionsCore<GroupKey, OrderKey, DisplayProperty, PageSize> {
+  subGroupBy: GroupKey;
+  showEmptyGroups: boolean;
+  showSubItems: boolean;
+  /** 看板列顺序（仅 groupBy === "state" 时生效） */
+  columnOrder?: string[];
+}