组件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* | boolean | true | — |
| collapsed* | boolean | — | — |
| onToggle* | () => void | — | — |
| defaultCollapsed* | boolean | false | — |
| expandLabel* | string | — | — |
| collapseLabel* | string | — | — |
| className* | string | — | — |
| headerClassName* | string | — | — |
| contentClassName* | string | — | — |
| children* | ReactNode | — | — |
源码
/**
* 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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
详情页可收缩分区,标题加内容平铺;用于描述、子任务等分组。