Ordo UI
PatternsApp Patterns

ToolbarRow

@mox-hub/patterns 模式 · App Patterns · canonical

toolbar-row@mox-hub/patternsApp Patternscanonicalsrc/components/toolbar-row.tsx
变体演示toolbar-row

Props API

Prop类型默认值说明
aiId*string——
className*string——
views*ToolbarViewEntry[]——
activeViewId*string——
onSelectView*(id: string) => void——
onCreateView*(name: string, icon?: string) => void——
onUpdateView*(id: string, patch: Partial<Pick<ToolbarViewEntry, "icon" | "name">>) => void——
onDeleteView*(id: string) => void——
isDirty*boolean——
onSaveCurrentView*() => void——
viewStyle*{ value: string; onChange: (value: string) => void; options: ToolbarViewStyleOption[]; layout?: "auto" | "centered" | "dropdown"; }——
filterMenu*false | ToolbarMenuSlot——
displayMenu*false | ToolbarMenuSlot——
downloadMenu*false | ToolbarMenuSlot——
extraActions*ToolbarActionDescriptor[]——
actions*ReactNode——
translate*PatternTranslate——

源码

packages/patterns/src/components/toolbar-row.tsx
import {
  useCallback,
  useEffect,
  useRef,
  useState,
  type ComponentProps,
  type ReactNode,
} from "react";
import { type PatternTranslate } from "../lib/translate";
import { usePatternTranslate } from "../lib/i18n";
import {
  Bot,
  Bug,
  CalendarRange,
  Check,
  CheckCircle2,
  ChevronDown,
  Clock,
  Download,
  Filter,
  Flag,
  FolderOpen,
  Inbox,
  Kanban,
  LayoutGrid,
  List,
  Plus,
  SlidersHorizontal,
  Sparkles,
  Star,
  TableProperties,
  Tag,
  Target,
  User,
  Zap,
  type LucideIcon,
} from "lucide-react";
import { cn } from "@mox-hub/ui";
import { RawButton } from "@mox-hub/ui/components/raw/raw-button";
import { HeaderActionButton } from "./header-action-button";
import { AnchoredMenu } from "@mox-hub/ui/components/anchored-menu";
import { Checkbox } from "@mox-hub/ui/components/checkbox";
import { SegmentedControl, type SegmentedTone } from "@mox-hub/ui/components/segmented-control";
import { Input } from "@mox-hub/ui/components/input";
import {
  MENU_ITEM_CLASS,
  MENU_LABEL_CLASS,
  MENU_SEPARATOR_CLASS,
} from "@mox-hub/ui/components/menu-surface";
import { ContextMenu, type MenuItem } from "@mox-hub/ui/components/context-menu";
import {
  ViewDisplayPopover,
  type ViewDisplayPopoverProps,
} from "./view-display-popover";

/* ────────────────────────────── 类型 ────────────────────────────── */

/** 已保存视图:名称 + 图标 + 页面状态快照(筛选/样式/排序等,结构由页面自定义,天然可扩展) */
export interface ToolbarViewEntry {
  id: string;
  name: string;
  /** 图标 key,经 TOOLBAR_VIEW_ICONS 解析 */
  icon?: string;
  /** 内置视图不可删除 */
  builtIn?: boolean;
  snapshot?: Record<string, unknown>;
}

export interface ToolbarViewStyleOption {
  value: string;
  label: string;
  icon?: LucideIcon;
  /** 激活滑块高亮色调(页面按需传入) */
  tone?: SegmentedTone;
}

export interface ToolbarMenuItem {
  type?: "item" | "label" | "separator" | "checkbox";
  id?: string;
  label?: ReactNode;
  icon?: LucideIcon;
  checked?: boolean;
  disabled?: boolean;
  onSelect?: () => void;
}

export interface ToolbarMenuSlot {
  /** 自定义按钮文案(未传时按插槽类型采用默认国际化) */
  label?: string;
  /** 完全自定义按钮+弹层节点(如二级级联筛选菜单 FilterCascadeMenu),提供时优先于 content/items */
  render?: () => ReactNode;
  /** 高级显示弹窗配置(直接渲染 Linear 风格 ViewDisplayPopover) */
  displayConfig?: ViewDisplayPopoverProps;
  /** 结构化菜单项 */
  items?: ToolbarMenuItem[];
  /** 完全自定义下拉内容(优先于 items) */
  content?: ReactNode;
  /** 筛选菜单顶部搜索框(内置 300ms 防抖) */
  search?: {
    value: string;
    onChange: (value: string) => void;
    placeholder?: string;
  };
  /** 按钮右上角数字角标(>0 显示,如生效中的筛选数量) */
  badge?: number;
}

/* ─────────────────── Filter 多选状态工具 ─────────────────── */

/**
 * 快照里的筛选项归一为数组:兼容历史单值(string / 'all')与新多值(string[])。
 * 空数组 = 该维度不做筛选(等价于旧 'all')。
 */
export function normalizeFilterSelection(value: unknown): string[] {
  if (Array.isArray(value)) {
    return value.filter((v): v is string => typeof v === "string" && v !== "all");
  }
  return typeof value === "string" && value !== "all" ? [value] : [];
}

/** 勾选/取消勾选一个筛选项(不可变更新) */
export function toggleFilterValue(values: string[], value: string): string[] {
  return values.includes(value) ? values.filter((v) => v !== value) : [...values, value];
}

export interface ToolbarActionDescriptor {
  id: string;
  icon: LucideIcon;
  label: string;
  variant?: "primary" | "outline" | "secondary" | "ghost" | "danger";
  /** 无下拉的直接动作按钮(圆形 hover 展开) */
  onClick?: () => void;
  /** 带下拉的按钮 */
  menu?: ToolbarMenuSlot;
  /** 自定义节点(如进度按钮等无法用 icon/label 描述的动作件),提供时优先于其余字段 */
  render?: () => ReactNode;
}

/** 工具栏文案缺省:全部调用都带中文 fallback,翻译器回落到 fallback 即可。 */

export interface ToolbarRowProps {
  aiId?: string;
  className?: string;
  /** 文案覆写(主仓 i18n 适配层集中传入 t() 包装)。 */
  translate?: PatternTranslate;
  /* 视图管理(左):整体不传(undefined)即隐藏视图胶囊与新增按钮——纯样式切换页(analytics / 类型详情)用 */
  views?: ToolbarViewEntry[];
  activeViewId?: string;
  onSelectView?: (id: string) => void;
  onCreateView?: (name: string, icon?: string) => void;
  onUpdateView?: (id: string, patch: Partial<Pick<ToolbarViewEntry, "name" | "icon">>) => void;
  onDeleteView?: (id: string) => void;
  /** 当前视图是否有未保存变动(指示脏状态) */
  isDirty?: boolean;
  /** 保存当前改动到当前激活视图 */
  onSaveCurrentView?: () => void;
  /* 视图样式切换(居中 / 右侧下拉) */
  viewStyle?: {
    value: string;
    onChange: (value: string) => void;
    options: ToolbarViewStyleOption[];
    /** auto:样式 >3 种时收进右侧按钮组下拉(默认),否则居中 */
    layout?: "auto" | "centered" | "dropdown";
  };
  /* 右侧按钮组:默认 筛选 / 显示 / 下载,传 false 移除 */
  filterMenu?: ToolbarMenuSlot | false;
  displayMenu?: ToolbarMenuSlot | false;
  downloadMenu?: ToolbarMenuSlot | false;
  /** 页面注册的附加按钮(追加在默认按钮之后) */
  extraActions?: ToolbarActionDescriptor[];
  /** 自定义动作/状态节点(渲染在右侧按钮组前) */
  actions?: ReactNode;
}

/** 视图可选图标(存储为字符串 key) */
export const TOOLBAR_VIEW_ICONS: Record<string, LucideIcon> = {
  list: List,
  board: Kanban,
  gantt: CalendarRange,
  table: TableProperties,
  grid: LayoutGrid,
  bot: Bot,
  star: Star,
  flag: Flag,
  inbox: Inbox,
  tag: Tag,
  target: Target,
  zap: Zap,
  bug: Bug,
  folder: FolderOpen,
  clock: Clock,
  user: User,
  check: CheckCircle2,
  sparkles: Sparkles,
};

/* ─────────────────────────── useToolbarViews ─────────────────────────── */

interface UseToolbarViewsOptions {
  /** localStorage key 后缀:toolbar-views:<key> */
  key: string;
  /** 默认视图(至少一个),本地无存储时兜底 */
  defaults: ToolbarViewEntry[];
  /** 切换视图时恢复快照到页面状态 */
  onApply?: (snapshot: Record<string, unknown> | undefined) => void;
}

const storageKeyOf = (key: string) => `toolbar-views:${key}`;

function loadViews(key: string, defaults: ToolbarViewEntry[]): ToolbarViewEntry[] {
  try {
    const raw = localStorage.getItem(storageKeyOf(key));
    if (!raw) return defaults;
    const parsed: unknown = JSON.parse(raw);
    if (!Array.isArray(parsed) || parsed.length === 0) return defaults;
    return parsed as ToolbarViewEntry[];
  } catch {
    return defaults;
  }
}

/**
 * 已保存视图状态管理:持久化到 localStorage(每页独立 key)。
 */
export function useToolbarViews({ key, defaults, onApply }: UseToolbarViewsOptions) {
  const [initialState] = useState(() => {
    const loaded = loadViews(key, defaults);
    return { views: loaded, activeViewId: loaded[0]?.id ?? "" };
  });
  const [views, setViews] = useState<ToolbarViewEntry[]>(initialState.views);
  const [activeViewId, setActiveViewId] = useState<string>(initialState.activeViewId);
  const [isDirty, setIsDirty] = useState(false);

  const onApplyRef = useRef(onApply);
  const viewsRef = useRef(views);
  const activeIdRef = useRef(activeViewId);
  const snapshotRef = useRef<Record<string, unknown> | undefined>(initialState.views[0]?.snapshot);

  const [loadedKey, setLoadedKey] = useState(key);
  if (loadedKey !== key) {
    setLoadedKey(key);
    const reloaded = loadViews(key, defaults);
    setViews(reloaded);
    setActiveViewId(reloaded[0]?.id ?? "");
    setIsDirty(false);
  }

  useEffect(() => {
    onApplyRef.current = onApply;
    viewsRef.current = views;
    activeIdRef.current = activeViewId;
    const activeSnapshot = views.find((v) => v.id === activeViewId)?.snapshot;
    if (activeSnapshot !== undefined) snapshotRef.current = activeSnapshot;
  });

  useEffect(() => {
    try {
      localStorage.setItem(storageKeyOf(key), JSON.stringify(views));
    } catch {
      /* 存储不可用时静默降级为内存态 */
    }
  }, [key, views]);

  const selectView = useCallback((id: string) => {
    const target = viewsRef.current.find((v) => v.id === id);
    if (!target || id === activeIdRef.current) return;
    snapshotRef.current = target.snapshot;
    setActiveViewId(id);
    setIsDirty(false);
    onApplyRef.current?.(target.snapshot);
  }, []);

  /** 页面状态变化时上报,写入当前激活视图的快照 */
  const updateActiveSnapshot = useCallback((snapshot: Record<string, unknown>) => {
    snapshotRef.current = snapshot;
    setViews((prev) => {
      let changed = false;
      const next = prev.map((v) => {
        if (v.id !== activeIdRef.current) return v;
        if (JSON.stringify(v.snapshot) === JSON.stringify(snapshot)) return v;
        changed = true;
        return { ...v, snapshot };
      });
      return changed ? next : prev;
    });
  }, []);

  /** 以当前页面状态为快照新建视图并激活 */
  const createView = useCallback((name: string, icon?: string) => {
    const id = `view-${Date.now().toString(36)}`;
    const snapshot = snapshotRef.current ?? {};
    setViews((prev) => [...prev, { id, name: name.trim() || "View", icon: icon ?? "star", snapshot }]);
    setActiveViewId(id);
    setIsDirty(false);
  }, []);

  const updateView = useCallback(
    (id: string, patch: Partial<Pick<ToolbarViewEntry, "name" | "icon">>) => {
      setViews((prev) => prev.map((v) => (v.id === id ? { ...v, ...patch } : v)));
    },
    [],
  );

  const deleteView = useCallback((id: string) => {
    const current = viewsRef.current;
    const target = current.find((v) => v.id === id);
    if (!target || target.builtIn || current.length <= 1) return;
    const next = current.filter((v) => v.id !== id);
    setViews(next);
    if (id === activeIdRef.current) {
      const fallback = next[0];
      snapshotRef.current = fallback.snapshot;
      setActiveViewId(fallback.id);
      setIsDirty(false);
      onApplyRef.current?.(fallback.snapshot);
    }
  }, []);

  const saveCurrentToActive = useCallback(() => {
    if (snapshotRef.current) {
      updateActiveSnapshot(snapshotRef.current);
      setIsDirty(false);
    }
  }, [updateActiveSnapshot]);

  return {
    views,
    activeViewId,
    selectView,
    updateActiveSnapshot,
    createView,
    updateView,
    deleteView,
    isDirty,
    saveCurrentToActive,
  };
}

/* ─────────────────────────── 内部子组件 ─────────────────────────── */

function ToolbarSearchBox({
  value,
  onChange,
  placeholder,
}: NonNullable<ToolbarMenuSlot["search"]>) {
  const [buffer, setBuffer] = useState(value);
  const [prevValue, setPrevValue] = useState(value);
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  if (prevValue !== value) {
    setPrevValue(value);
    setBuffer(value);
  }

  useEffect(() => {
    clearTimeout(timer.current);
  }, [value]);

  useEffect(() => () => clearTimeout(timer.current), []);

  const handleChange = (next: string) => {
    setBuffer(next);
    clearTimeout(timer.current);
    timer.current = setTimeout(() => onChange(next), 300);
  };

  return (
    <Input
      value={buffer}
      onChange={(event) => handleChange(event.target.value)}
      onKeyDown={(event) => {
        if (event.key === "Enter") {
          clearTimeout(timer.current);
          onChange(buffer);
        }
      }}
      placeholder={placeholder}
      className="h-control-sm text-xs"
    />
  );
}

function ToolbarMenuItems({ items, close }: { items: ToolbarMenuItem[]; close: () => void }) {
  return (
    <div className="min-w-40">
      {items.map((item, index) => {
        const key = item.id ?? index;
        if (item.type === "separator") {
          return <div key={key} className={MENU_SEPARATOR_CLASS} />;
        }
        if (item.type === "label") {
          return (
            <div key={key} className={MENU_LABEL_CLASS}>
              {item.label}
            </div>
          );
        }
        const Icon = item.icon;
        const isCheckbox = item.type === "checkbox";
        return (
          <RawButton
            key={key}
            type="button"
            disabled={item.disabled}
            onClick={() => {
              item.onSelect?.();
              if (!isCheckbox) close();
            }}
            className={cn(
              MENU_ITEM_CLASS,
              "text-xs",
              item.disabled && "pointer-events-none opacity-50",
            )}
          >
            {isCheckbox ? (
              <Checkbox
                className="me-2"
                checked={item.checked ?? false}
                render={<span aria-hidden="true" />}
              />
            ) : Icon ? (
              <Icon className="me-2 size-4 shrink-0" strokeWidth={1.75} />
            ) : null}
            <span className="truncate">{item.label}</span>
          </RawButton>
        );
      })}
    </div>
  );
}

function ToolbarMenuButton({
  icon,
  label,
  variant = "outline",
  menu,
  ...buttonProps
}: {
  icon: LucideIcon;
  label: string;
  variant?: ToolbarActionDescriptor["variant"];
  menu: ToolbarMenuSlot;
} & Omit<ComponentProps<typeof HeaderActionButton>, "icon" | "label" | "variant">) {
  const [open, setOpen] = useState(false);
  const anchorRef = useRef<HTMLButtonElement>(null);
  const close = useCallback(() => setOpen(false), []);

  return (
    <span className="relative inline-flex shrink-0">
      <HeaderActionButton
        ref={anchorRef}
        icon={icon}
        label={label}
        variant={variant}
        pinned={open}
        trailing={<ChevronDown className="ms-0.5 size-3 opacity-70" />}
        aria-haspopup="menu"
        aria-expanded={open}
        onClick={() => setOpen((prev) => !prev)}
        {...buttonProps}
      />
      {menu.badge && menu.badge > 0 ? (
        <span className="pointer-events-none absolute -top-1 end-0 flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-xs font-medium leading-none text-destructive-foreground">
          {menu.badge > 99 ? "99+" : menu.badge}
        </span>
      ) : null}
      <AnchoredMenu open={open} onClose={close} anchor={anchorRef}>
        {menu.displayConfig ? (
          <ViewDisplayPopover {...menu.displayConfig} />
        ) : (
          menu.content ?? (
            <div className="flex max-h-80 flex-col">
              {menu.search ? (
                <div className="mb-1 shrink-0">
                  <ToolbarSearchBox {...menu.search} />
                </div>
              ) : null}
              <div className="min-h-0 overflow-y-auto">
                <ToolbarMenuItems items={menu.items ?? []} close={close} />
              </div>
            </div>
          )
        )}
      </AnchoredMenu>
    </span>
  );
}

function ExtraActionButton({ action }: { action: ToolbarActionDescriptor }) {
  if (action.render) {
    return <>{action.render()}</>;
  }
  if (action.menu) {
    return (
      <ToolbarMenuButton
        icon={action.icon}
        label={action.label}
        variant={action.variant}
        menu={action.menu}
        data-ai-component={action.id}
      />
    );
  }
  return (
    <HeaderActionButton
      icon={action.icon}
      label={action.label}
      variant={action.variant}
      onClick={action.onClick}
      data-ai-component={action.id}
    />
  );
}

const PRESET_VIEW_NAMES = [
  { key: "all", label: "全部工单", icon: "list" },
  { key: "mine", label: "我的待办", icon: "star" },
  { key: "board", label: "按状态看板", icon: "board" },
  { key: "timeline", label: "时间线排期", icon: "gantt" },
  { key: "bugs", label: "高优缺陷", icon: "bug" },
  { key: "ai", label: "AI 自动化", icon: "bot" },
];

/** 视图新建/编辑面板(AnchoredMenu 内容) */
function ViewEditorPanel({
  initialName = "",
  initialIcon,
  builtIn,
  mode,
  submitText,
  onSubmit,
  onDelete,
}: {
  initialName?: string;
  initialIcon?: string;
  builtIn?: boolean;
  mode: "create" | "edit";
  submitText: string;
  onSubmit: (name: string, icon: string) => void;
  onDelete?: () => void;
}) {
  const [name, setName] = useState(initialName);
  const [icon, setIcon] = useState(initialIcon ?? "star");
  const t = usePatternTranslate("toolbarRow", {});

  return (
    <form
      className="flex w-72 flex-col gap-2.5 p-3"
      onSubmit={(event) => {
        event.preventDefault();
        onSubmit(name.trim() || t("viewEditor.defaultName", "View"), icon);
      }}
    >
      <div className="text-xs font-semibold text-foreground">
        {mode === "create"
          ? t("viewEditor.create", "新建自定义视图")
          : t("viewEditor.edit", "编辑视图")}
      </div>

      <Input
        value={name}
        onChange={(event) => setName(event.target.value)}
        placeholder={t("viewEditor.namePlaceholder", "输入视图名称...")}
        className="h-control-sm text-xs"
        autoFocus
      />

      {mode === "create" ? (
        <div className="flex flex-wrap gap-1">
          {PRESET_VIEW_NAMES.map((preset) => {
            const presetLabel = t(
              `viewEditor.presets.${preset.key}`,
              preset.label,
            );
            return (
            <RawButton
              key={preset.key}
              type="button"
              onClick={() => {
                setName(presetLabel);
                setIcon(preset.icon);
              }}
              className="rounded-md border border-border bg-muted/30 px-1.5 py-0.5 text-2xs text-muted-foreground hover:bg-muted hover:text-foreground"
            >
              {presetLabel}
            </RawButton>
            );
          })}
        </div>
      ) : null}

      <div className="text-2xs text-muted-foreground">{t("viewEditor.iconLabel", "选择代表图标")}</div>
      <div className="grid grid-cols-6 gap-1.5 max-h-36 overflow-y-auto pe-1">
        {Object.entries(TOOLBAR_VIEW_ICONS).map(([key, Icon]) => (
          <RawButton
            key={key}
            type="button"
            onClick={() => setIcon(key)}
            aria-label={key}
            className={cn(
              "flex size-control-sm items-center justify-center rounded-md border transition-colors",
              icon === key
                ? "border-primary bg-primary/10 text-primary shadow-xs"
                : "border-transparent text-muted-foreground hover:bg-muted hover:text-foreground",
            )}
          >
            <Icon className="size-4" strokeWidth={1.75} />
          </RawButton>
        ))}
      </div>

      <div className="flex items-center gap-2 pt-1">
        <RawButton
          type="submit"
          className="inline-flex h-control-sm flex-1 items-center justify-center rounded-md bg-primary px-3 text-xs font-medium text-primary-foreground shadow-xs transition-colors hover:bg-primary/90"
        >
          {submitText}
        </RawButton>
        {onDelete && !builtIn ? (
          <RawButton
            type="button"
            onClick={onDelete}
            className="inline-flex h-control-sm items-center justify-center rounded-md border border-border px-3 text-xs font-medium text-destructive transition-colors hover:bg-destructive/10"
          >
            {t("viewEditor.delete", "删除")}
          </RawButton>
        ) : null}
      </div>
    </form>
  );
}

/** 胶囊风格 ViewPill:rounded-full 胶囊、取消三个点、右键呼出系统 ContextMenu */
function ViewPill({
  view,
  active,
  isDirty,
  onSelect,
  onUpdate,
  onDelete,
  onSaveCurrent,
  translate,
}: {
  view: ToolbarViewEntry;
  active: boolean;
  isDirty?: boolean;
  onSelect: (id: string) => void;
  onUpdate: (id: string, patch: Partial<Pick<ToolbarViewEntry, "name" | "icon">>) => void;
  onDelete: (id: string) => void;
  onSaveCurrent?: () => void;
  translate?: PatternTranslate;
}) {
  const [editing, setEditing] = useState(false);
  const anchorRef = useRef<HTMLButtonElement>(null);
  const Icon = view.icon ? TOOLBAR_VIEW_ICONS[view.icon] : undefined;
  const providerT = usePatternTranslate('toolbarRow', {});
  const t = translate ?? providerT;

  const contextMenuItems: MenuItem[] = [
    ...(active && isDirty && onSaveCurrent
      ? [
          {
            id: "save",
            label: t("viewActions.save", "保存当前改动到视图"),
            onClick: () => onSaveCurrent(),
          },
        ]
      : []),
    {
      id: "edit",
      label: t("viewActions.edit", "编辑名称与图标"),
      onClick: () => setEditing(true),
    },
    ...(!view.builtIn
      ? [
          {
            id: "delete",
            label: t("viewActions.delete", "删除视图"),
            destructive: true,
            onClick: () => onDelete(view.id),
          },
        ]
      : []),
  ];

  const displayName =
    view.builtIn && (view.id === 'all' || view.name === 'All')
      ? t('common.all', '全部')
      : view.name;

  return (
    <div className="relative inline-flex shrink-0">
      <ContextMenu items={contextMenuItems}>
        <RawButton
          ref={anchorRef}
          type="button"
          onClick={() => onSelect(view.id)}
          title={`${displayName} (${t("viewActions.manageHint", "右键管理")})`}
          aria-label={displayName}
          className={cn(
            "flex h-control-2xs shrink-0 items-center gap-1.5 rounded-full border px-3 text-xs font-medium transition-[background-color,color,box-shadow,transform] select-none [transition-duration:var(--motion-fast)]",
            active
              ? "border-border bg-card text-foreground shadow-xs font-semibold"
              : "border-border/40 bg-transparent text-muted-foreground hover:bg-muted hover:text-foreground",
          )}
        >
          {Icon ? <Icon className="size-3.5 shrink-0 opacity-80" strokeWidth={1.75} /> : null}
          <span className="max-w-32 truncate">{displayName}</span>
          {active && isDirty ? (
            <span
              title={t("viewState.dirty", "包含未保存的筛选或显示改动")}
              className="size-1.5 rounded-full bg-accent-yellow ring-1 ring-accent-yellow/40"
            />
          ) : null}
        </RawButton>
      </ContextMenu>

      <AnchoredMenu
        open={editing}
        onClose={() => setEditing(false)}
        anchor={anchorRef}
        mode="dialog"
        ariaLabel={t("viewEditor.dialogLabel", "视图设置")}
      >
        <ViewEditorPanel
          initialName={view.name}
          initialIcon={view.icon}
          builtIn={view.builtIn}
          mode="edit"
          submitText={t("viewEditor.save", "保存")}
          onSubmit={(name, icon) => {
            onUpdate(view.id, { name, icon });
            setEditing(false);
          }}
          onDelete={() => {
            onDelete(view.id);
            setEditing(false);
          }}
        />
      </AnchoredMenu>
    </div>
  );
}

/** 胶囊风格新增视图按钮:rounded-full 微虚线 */
function AddViewButton({ onCreate }: { onCreate: (name: string, icon?: string) => void }) {
  const [open, setOpen] = useState(false);
  const anchorRef = useRef<HTMLButtonElement>(null);
  const t = usePatternTranslate("toolbarRow", {});

  return (
    <>
      <RawButton
        ref={anchorRef}
        type="button"
        onClick={() => setOpen(true)}
        aria-label={t("viewActions.add", "Add view")}
        title={t("viewActions.add", "Add view")}
        className="flex h-control-2xs shrink-0 items-center justify-center rounded-full border border-dashed border-border/70 px-2 text-xs text-muted-foreground transition-colors hover:border-primary/50 hover:bg-primary/5 hover:text-primary"
      >
        <Plus className="size-3.5" strokeWidth={2} aria-hidden />
      </RawButton>
      <AnchoredMenu
        open={open}
        onClose={() => setOpen(false)}
        anchor={anchorRef}
        mode="dialog"
        ariaLabel={t("viewEditor.dialogLabel", "视图设置")}
      >
        <ViewEditorPanel
          mode="create"
          submitText={t("viewEditor.createAction", "新建")}
          onSubmit={(name, icon) => {
            onCreate(name, icon);
            setOpen(false);
          }}
        />
      </AnchoredMenu>
    </>
  );
}

function ViewStyleDropdown({
  value,
  onChange,
  options,
  translate,
}: {
  value: string;
  onChange: (value: string) => void;
  options: ToolbarViewStyleOption[];
  translate?: PatternTranslate;
}) {
  const providerT = usePatternTranslate('toolbarRow', {});
  const t = translate ?? providerT;
  const [open, setOpen] = useState(false);
  const anchorRef = useRef<HTMLButtonElement>(null);
  const current = options.find((option) => option.value === value) ?? options[0];
  if (!current) return null;

  const currentLabel =
    typeof current.label === "string"
      ? t(`viewDisplay.views.${current.value}`, current.label)
      : current.label;

  return (
    <>
      <HeaderActionButton
        ref={anchorRef}
        icon={current.icon ?? LayoutGrid}
        label={currentLabel}
        variant="outline"
        pinned
        trailing={<ChevronDown className="ms-0.5 size-3 opacity-70" />}
        aria-haspopup="menu"
        aria-expanded={open}
        onClick={() => setOpen((prev) => !prev)}
      />
      <AnchoredMenu
        open={open}
        onClose={() => setOpen(false)}
        anchor={anchorRef}
        mode="dialog"
        ariaLabel={t("viewEditor.dialogLabel", "视图设置")}
      >
        <div className="min-w-36">
          {options.map((option) => {
            const Icon = option.icon;
            const label =
              typeof option.label === "string"
                ? t(`viewDisplay.views.${option.value}`, option.label)
                : option.label;
            return (
              <RawButton
                key={option.value}
                type="button"
                onClick={() => {
                  onChange(option.value);
                  setOpen(false);
                }}
                className={cn(MENU_ITEM_CLASS, "text-xs")}
              >
                {Icon ? <Icon className="me-2 size-4 shrink-0" strokeWidth={1.75} /> : null}
                <span className="flex-1 truncate">{label}</span>
                {option.value === current.value ? (
                  <Check className="ms-2 size-3.5 shrink-0 text-primary" strokeWidth={2.5} />
                ) : null}
              </RawButton>
            );
          })}
        </div>
      </AnchoredMenu>
    </>
  );
}

/* ─────────────────────────── ToolbarRow ─────────────────────────── */

export function ToolbarRow({
  aiId,
  className,
  views,
  activeViewId,
  onSelectView,
  onCreateView,
  onUpdateView,
  onDeleteView,
  isDirty,
  onSaveCurrentView,
  viewStyle,
  filterMenu,
  displayMenu,
  downloadMenu,
  extraActions,
  actions,
  translate,
}: ToolbarRowProps) {
  const providerT = usePatternTranslate('toolbarRow', {});
  const t = translate ?? providerT;

  // 当 layout 为 centered 时优先居中;若未显式指定,当选项 > 3 种时自动下拉收纳(兼容历史规则)
  const styleLayout =
    viewStyle?.layout === "centered" || viewStyle?.layout === "dropdown"
      ? viewStyle.layout
      : viewStyle && viewStyle.options.length > 3
        ? "dropdown"
        : "centered";

  return (
    <header
      className={cn(
        "sticky top-10 z-sticky grid w-full shrink-0 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-b border-border bg-background px-page py-2",
        className,
      )}
      data-ai-component={aiId ? `${aiId}.context-bar` : "ui.toolbar-row"}
      data-ai-role="filter"
    >
      <div className="flex min-w-0 items-center gap-1.5 overflow-x-auto">
        {views && onSelectView && onUpdateView && onDeleteView ? (
          <>
            {views.map((view) => (
              <ViewPill
                key={view.id}
                view={view}
                active={view.id === activeViewId}
                isDirty={view.id === activeViewId ? isDirty : false}
                onSelect={onSelectView}
                onUpdate={onUpdateView}
                onDelete={onDeleteView}
                onSaveCurrent={onSaveCurrentView}
                translate={translate}
              />
            ))}
            {onCreateView ? <AddViewButton onCreate={onCreateView} /> : null}
          </>
        ) : null}
      </div>

      {viewStyle && styleLayout === "centered" ? (
        <div className="min-w-0 max-w-full justify-self-center overflow-x-auto">
          <SegmentedControl
            variant="rect"
            value={viewStyle.value}
            onChange={viewStyle.onChange}
            options={viewStyle.options.map((option) => {
              const Icon = option.icon;
              const label =
                typeof option.label === "string"
                  ? t(`viewDisplay.views.${option.value}`, option.label)
                  : option.label;
              return {
                value: option.value,
                label,
                icon: Icon ? <Icon className="size-3.5" strokeWidth={1.75} /> : undefined,
                tone: option.tone,
              };
            })}
          />
        </div>
      ) : (
        <div />
      )}

      <div className="flex min-w-0 items-center justify-end gap-2 overflow-x-auto">
        {actions}
        {viewStyle && styleLayout === "dropdown" ? (
          <ViewStyleDropdown
            value={viewStyle.value}
            onChange={viewStyle.onChange}
            options={viewStyle.options}
            translate={translate}
          />
        ) : null}
        {filterMenu ? (
          filterMenu.render ? (
            filterMenu.render()
          ) : (
            <ToolbarMenuButton
              icon={Filter}
              label={filterMenu.label ?? t("common.filters", "Filter")}
              menu={filterMenu}
            />
          )
        ) : null}
        {displayMenu ? (
          displayMenu.render ? (
            displayMenu.render()
          ) : (
            <ToolbarMenuButton
              icon={SlidersHorizontal}
              label={displayMenu.label ?? t("viewDisplay.display", "Display")}
              menu={displayMenu}
            />
          )
        ) : null}
        {downloadMenu ? (
          <ToolbarMenuButton
            icon={Download}
            label={downloadMenu.label ?? t("common.download", "Download")}
            menu={downloadMenu}
          />
        ) : null}
        {extraActions?.map((action) => (
          <ExtraActionButton key={action.id} action={action} />
        ))}
      </div>
    </header>
  );
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

页面工具栏:视图胶囊 + 视图样式切换 + 筛选/显示/下载菜单 + 附加动作;useToolbarViews 持 localStorage 视图状态,文案经 translate 注入。