Ordo UI
组件Semantic

DetailSection

@mox-hub/ui 组件 · Semantic · canonical

detail-section@mox-hub/uiSemanticcanonicalsrc/components/detail-section.tsx
变体演示detail-section
描述(3)
这里是分区内容区,点击右上角三角可以收起或展开。

Props API

Prop类型默认值说明
icon*ReactNode——
title*string——
count*ReactNode——
action*ReactNode——
collapsible*booleantrue—
collapsed*boolean——
onToggle*() => void——
defaultCollapsed*booleanfalse—
expandLabel*string——
collapseLabel*string——
className*string——
headerClassName*string——
contentClassName*string——
children*ReactNode——

源码

packages/ui/src/components/detail-section.tsx
/**
 * DetailSection - 详情页主栏统一「可收缩分区」(Linear 风格平铺形态)
 *
 * 收编 task/bug 详情页主栏六处手写同构分区(描述/自定义字段/子任务/执行项/
 * 验收契约预览/依赖关系):分区头(图标 + uppercase 小标题 + 计数 + 右侧动作)
 * + grid-rows 流畅收缩动画。与右栏 SidebarPanel 同构不同形——本件平铺无卡底,
 * SidebarPanel 是磨砂圆角卡,各自独立登记(2026-10-02 裁决①)。
 *
 * 约定:
 * - 标题档 text-xs(中文 12px 下限,§2.4;2026-10-02 裁决②,右栏 text-3xs 不在本件口径)
 * - 图标 size-3.5、计数 text-3xs tabular-nums,分区头默认 px-6 py-2(headerClassName 可覆)
 * - 收缩钮内置(RawButton + ChevronDown 旋转 + aria-expanded),collapsible={false} 关闭
 *   (描述区等不收缩分区);支持受控(collapsed/onToggle)与不受控(defaultCollapsed)
 */
import { useState, type ComponentProps, type ReactNode } from 'react';
import { ChevronDown } from 'lucide-react';
import { cn } from '../lib/utils';
import { RawButton } from './raw/raw-button';
import { useMessages } from '../i18n';

export interface DetailSectionProps extends ComponentProps<'div'> {
  /** 分区头图标(消费方自渲染 lucide 节点,统一 size-3.5;颜色继承 muted) */
  icon?: ReactNode;
  title: string;
  /** 标题右侧计数((N) 或 done/total),text-3xs normal-case tabular-nums */
  count?: ReactNode;
  /** 分区头右侧动作区(收缩三角之前的自定义内容,如编辑/新增钮) */
  action?: ReactNode;
  /** 是否渲染内置收缩三角与收缩动画(默认 true;描述区等常开分区传 false) */
  collapsible?: boolean;
  /** 受控:是否收起 */
  collapsed?: boolean;
  /** 受控:折叠切换回调 */
  onToggle?: () => void;
  /** 不受控:初始是否收起(默认展开) */
  defaultCollapsed?: boolean;
  /** 折叠按钮展开 aria-label(缺省「展开」);i18n 去耦后由消费方注入(2026-11-08) */
  expandLabel?: string;
  /** 折叠按钮收起 aria-label(缺省「收起」) */
  collapseLabel?: string;
  /** 分区头附加类(覆默认 px-6 py-2,如描述区 px-6 pt-4 pb-2) */
  headerClassName?: string;
  /** 内容包裹层附加类(各区内容自带 px-6 时可不传) */
  contentClassName?: string;
  children: ReactNode;
}


export function DetailSection({
  icon,
  title,
  count,
  action,
  collapsible = true,
  collapsed: collapsedProp,
  onToggle,
  defaultCollapsed = false,
  expandLabel,
  collapseLabel,
  className,
  headerClassName,
  contentClassName,
  children,
  ...rest
}: DetailSectionProps) {
  const M = useMessages();
  const expand = expandLabel ?? M.detailSection.expand;
  const collapse = collapseLabel ?? M.detailSection.collapse;
  const [open, setOpen] = useState(!defaultCollapsed);
  const collapsed = collapsible && collapsedProp !== undefined ? collapsedProp : collapsible ? !open : false;
  const toggle = onToggle ?? (() => setOpen((v) => !v));

  return (
    <div data-slot="detail-section" className={cn('shrink-0', className)} {...rest}>
      {/* 分区头 */}
      <div
        data-slot="detail-section-header"
        className={cn('flex items-center justify-between py-2', headerClassName ?? 'px-6')}
      >
        <div className="flex min-w-0 items-center gap-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
          {icon ? <span className="shrink-0">{icon}</span> : null}
          <span className="truncate">{title}</span>
          {count != null ? (
            <span className="text-3xs font-normal normal-case tabular-nums">{count}</span>
          ) : null}
        </div>
        <div className="flex shrink-0 items-center gap-0.5">
          {action}
          {collapsible && (
            <RawButton
              type="button"
              onClick={toggle}
              className="inline-flex size-5 items-center justify-center rounded-md text-muted-foreground transition-colors duration-fast hover:bg-muted hover:text-foreground pointer-coarse:size-11"
              aria-label={collapsed ? expand : collapse}
              aria-expanded={!collapsed}
            >
              <ChevronDown
                className={cn('size-3 transition-transform duration-fast', !collapsed && 'rotate-180')}
              />
            </RawButton>
          )}
        </div>
      </div>

      {/* 内容区:grid-rows 动画实现流畅展开 / 收起(与 SidebarPanel 同一手势) */}
      {collapsible ? (
        <div
          className={cn(
            'grid transition-[grid-template-rows] duration-slow ease-out',
            collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]',
          )}
        >
          <div
            data-slot="detail-section-content"
            className={cn('overflow-hidden', contentClassName)}
            inert={collapsed || undefined}
          >
            {children}
          </div>
        </div>
      ) : (
        <div data-slot="detail-section-content" className={contentClassName}>
          {children}
        </div>
      )}
    </div>
  );
}

可访问性与 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。

用法说明

详情页可收缩分区,标题加内容平铺;用于描述、子任务等分组。