Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: add triggerRef to Dialog, columnResize plugin to Table, OverflowList.doc.mjs (#1110)

Joey1c82293e1a2d
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 2400214d23..43a6c81bb7 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -147,6 +147,12 @@ function Example() {
description: 'Dialog content.',
required: true,
},
+ {
+ name: 'triggerRef',
+ type: 'RefObject<HTMLElement | null>',
+ description:
+ 'Ref to the trigger element that opened the dialog. When provided, the entry animation slides from the direction of the trigger and focus returns to the trigger on close.',
+ },
{
name: 'width',
type: 'number | string',
@@ -406,6 +412,12 @@ function Example() {
description: '对话框内容。',
required: true,
},
+ {
+ name: 'triggerRef',
+ type: 'RefObject<HTMLElement | null>',
+ description:
+ '打开对话框的触发元素的引用。提供时,进入动画从触发方向滑入,关闭时焦点返回到触发元素。',
+ },
{
name: 'width',
type: 'number | string',
diff --git a/packages/core/src/OverflowList/OverflowList.doc.mjs b/packages/core/src/OverflowList/OverflowList.doc.mjs
new file mode 100644
index 0000000000..f256defe75
--- /dev/null
+++ b/packages/core/src/OverflowList/OverflowList.doc.mjs
@@ -0,0 +1,253 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'OverflowList',
+ description:
+ 'Horizontal list that hides items that overflow the available width and shows a custom indicator. Uses a hidden measurement container to avoid layout flicker.',
+ keywords: [
+ 'overflow',
+ 'truncate',
+ 'collapse',
+ 'breadcrumb',
+ 'toolbar',
+ 'tag-list',
+ 'pill-list',
+ 'more',
+ 'clamp',
+ 'responsive',
+ ],
+ features: [
+ "Hides items that don't fit in the container width",
+ 'Custom overflow indicator via overflowRenderer — receives the list of hidden items',
+ 'Indicator space reserved via hidden measurement — no manual width needed',
+ 'Collapse from start or end',
+ 'Minimum visible items guarantee',
+ 'observeParent behavior for content-sized containers alongside siblings',
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Items to render. Each child should be a single element.',
+ required: true,
+ },
+ {
+ name: 'overflowRenderer',
+ type: '(overflowItems: XDSOverflowItem[]) => ReactNode',
+ description:
+ 'Render function for the overflow indicator. Receives the list of hidden items (each with child and index). Only called when items are overflowing.',
+ },
+ {
+ name: 'gap',
+ type: 'SpacingStep',
+ description:
+ 'Gap between items as a spacing token step (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).',
+ default: '2',
+ },
+ {
+ name: 'minVisibleItems',
+ type: 'number',
+ description: 'Minimum number of items to always show, even when overflowing.',
+ default: '0',
+ },
+ {
+ name: 'collapseFrom',
+ type: "'start' | 'end'",
+ description: 'Which end to collapse items from when overflow occurs.',
+ default: "'end'",
+ },
+ {
+ name: 'behavior',
+ type: "'observeSelf' | 'observeParent'",
+ description:
+ "Controls which element is measured for available width. 'observeSelf' uses the container's own width. 'observeParent' observes the parent element — useful when the list should stay content-sized while still detecting available space.",
+ default: "'observeSelf'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic with overflow button',
+ code: `<XDSOverflowList
+ gap={2}
+ overflowRenderer={(items) => (
+ <XDSButton label={` + "`+${items.length} more`" + `} variant="ghost" />
+ )}>
+ <XDSButton label="Action 1" />
+ <XDSButton label="Action 2" />
+ <XDSButton label="Action 3" />
+ <XDSButton label="Action 4" />
+</XDSOverflowList>`,
+ },
+ {
+ label: 'Overflow into dropdown menu',
+ code: `const labels = ['Save', 'Edit', 'Share', 'Delete'];
+<XDSOverflowList
+ overflowRenderer={(overflowItems) => (
+ <XDSDropdownMenu
+ button={{label: ` + "`+${overflowItems.length}`" + `, variant: 'ghost'}}
+ items={overflowItems.map(({index}) => ({label: labels[index]}))}
+ />
+ )}>
+ {labels.map(l => <XDSButton key={l} label={l} />)}
+</XDSOverflowList>`,
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-overflow-list'},
+ ],
+ },
+ accessibility: [
+ 'The hidden measurement container is aria-hidden and inert — it does not appear in the accessibility tree.',
+ 'The visible container renders a plain div with no implicit role. Add aria-label if the list has semantic meaning.',
+ 'When using overflowRenderer with a dropdown, ensure the trigger has a meaningful label (e.g., "+3 more actions").',
+ ],
+ notes: [
+ 'Overflow detection uses ResizeObserver on the container or its parent, depending on the behavior prop.',
+ 'The overflowRenderer is rendered in a hidden measurement container at full item count to reserve the correct space before any items are hidden.',
+ 'Items are measured in the hidden container without visible paint — switching from hidden to visible is instant with no layout shift.',
+ "For collapseFrom='start', items are hidden from the beginning and the overflow indicator appears at the start.",
+ 'Use minVisibleItems to guarantee at least N items are always visible regardless of available space.',
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
+ name: 'OverflowList',
+ description:
+ '横向列表,当宽度不足时隐藏超出的项目并显示自定义指示器。使用隐藏的测量容器避免布局抖动。',
+ features: [
+ '隐藏超出容器宽度的项目',
+ '通过 overflowRenderer 自定义溢出指示器 — 接收隐藏项目列表',
+ '通过隐藏测量预留指示器空间 — 无需手动指定宽度',
+ '从起始或末尾折叠',
+ '保证最小可见项目数',
+ '支持 observeParent 模式,用于与兄弟元素并排的内容尺寸容器',
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '要渲染的项目,每个子元素应为单一元素。',
+ required: true,
+ },
+ {
+ name: 'overflowRenderer',
+ type: '(overflowItems: XDSOverflowItem[]) => ReactNode',
+ description:
+ '溢出指示器的渲染函数。接收隐藏项目列表(每项包含 child 和 index)。仅在有溢出项时调用。',
+ },
+ {
+ name: 'gap',
+ type: 'SpacingStep',
+ description:
+ '项目间距,使用间距步进值(0、0.5、1、1.5、2、3、4、5、6、8、10)。',
+ default: '2',
+ },
+ {
+ name: 'minVisibleItems',
+ type: 'number',
+ description: '溢出时始终显示的最小项目数。',
+ default: '0',
+ },
+ {
+ name: 'collapseFrom',
+ type: "'start' | 'end'",
+ description: '溢出时从哪一端开始折叠项目。',
+ default: "'end'",
+ },
+ {
+ name: 'behavior',
+ type: "'observeSelf' | 'observeParent'",
+ description:
+ "控制测量可用宽度的元素。'observeSelf' 使用容器自身宽度;'observeParent' 观察父元素,适用于需要内容尺寸但仍检测可用空间的场景。",
+ default: "'observeSelf'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须使用 stylex.create() 的值,而非内联样式对象。',
+ },
+ ],
+ examples: [
+ {
+ label: '基础溢出按钮',
+ code: `<XDSOverflowList
+ gap={2}
+ overflowRenderer={(items) => (
+ <XDSButton label={` + "`+${items.length} 更多`" + `} variant="ghost" />
+ )}>
+ <XDSButton label="操作 1" />
+ <XDSButton label="操作 2" />
+ <XDSButton label="操作 3" />
+ <XDSButton label="操作 4" />
+</XDSOverflowList>`,
+ },
+ {
+ label: '溢出到下拉菜单',
+ code: `const labels = ['保存', '编辑', '分享', '删除'];
+<XDSOverflowList
+ overflowRenderer={(overflowItems) => (
+ <XDSDropdownMenu
+ button={{label: ` + "`+${overflowItems.length}`" + `, variant: 'ghost'}}
+ items={overflowItems.map(({index}) => ({label: labels[index]}))}
+ />
+ )}>
+ {labels.map(l => <XDSButton key={l} label={l} />)}
+</XDSOverflowList>`,
+ },
+ ],
+ accessibility: [
+ '隐藏的测量容器设置了 aria-hidden 和 inert — 不出现在无障碍树中。',
+ '可见容器渲染为普通 div,无隐式角色。如果列表有语义含义,请添加 aria-label。',
+ '使用下拉菜单作为 overflowRenderer 时,确保触发按钮有有意义的标签(如"+3 个更多操作")。',
+ ],
+ notes: [
+ '溢出检测使用 ResizeObserver 监听容器或其父元素,具体取决于 behavior 属性。',
+ 'overflowRenderer 在隐藏测量容器中以完整项目数渲染,以在隐藏任何项目前预留正确的空间。',
+ '项目在隐藏容器中测量,无可见渲染 — 从隐藏切换到可见是即时的,无布局偏移。',
+ "使用 collapseFrom='start' 时,项目从起始处隐藏,溢出指示器出现在起始位置。",
+ '使用 minVisibleItems 保证无论可用空间多少,始终显示至少 N 个项目。',
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'horizontal list w/ overflow indicator — hides items beyond container width',
+ features: [
+ 'hide items beyond container width',
+ 'custom overflow indicator via overflowRenderer — receives hidden items',
+ 'indicator space auto-reserved via hidden measurement',
+ 'collapse from start or end',
+ 'min visible items guarantee',
+ 'observeParent mode for content-sized containers',
+ ],
+ notes: [
+ 'overflow detection: ResizeObserver on container or parent (depends on behavior)',
+ 'overflowRenderer measured at full item count to pre-reserve indicator space',
+ 'instant switch hidden to visible, no layout shift',
+ "collapseFrom='start': items hidden from beginning, indicator at start",
+ 'minVisibleItems: N items always visible regardless of space',
+ ],
+ accessibility: [
+ 'hidden measurement container: aria-hidden + inert, not in a11y tree',
+ 'visible container: plain div, no role, add aria-label if list has semantic meaning',
+ 'overflow dropdown: ensure trigger has meaningful aria-label',
+ ],
+ propDescriptions: {
+ children: 'items to render, each child should be a single element',
+ overflowRenderer: 'renders overflow indicator, receives hidden items w/ index',
+ gap: 'item gap as spacing step',
+ minVisibleItems: 'min items always shown even when overflowing',
+ collapseFrom: 'which end to collapse from',
+ behavior: 'observeSelf (default) or observeParent for content-sized containers',
+ xstyle: 'StyleX styles, use stylex.create() values only',
+ },
+};
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 0f4002a604..c92d05d282 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -17,6 +17,7 @@ export const docs = {
'Sorting via useXDSTableSortable — single or multi-column sort with header indicators',
'Pagination via useXDSTablePagination — client-side, server-side, or cursor-based with auto-rendered controls',
'Column visibility via useXDSTableColumnSettings — toggle, reorder, and reset columns with XDSMultiSelector integration',
+ 'Column resize via useXDSTableColumnResize — drag-to-resize column headers with min/max constraints and proportional-preserving behavior',
'Body rows memoized with custom comparison — only changed rows re-render',
'Auto-generated columns from data object keys when columns prop is omitted',
'Themeable via className — target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',
@@ -173,6 +174,21 @@ const selectionPlugin = useXDSTableSelection<User>(selectionConfig);
<XDSTable data={users} plugins={{highlight: highlightPlugin}} />`,
},
+ {
+ label: 'Column resize plugin',
+ code: `const [columnWidths, setColumnWidths] = useState({});
+const resizePlugin = useXDSTableColumnResize({
+ columnWidths,
+ columns,
+ onColumnResizeEnd: updates => setColumnWidths(prev => ({...prev, ...updates})),
+});
+<XDSTable
+ data={users}
+ columns={columns}
+ idKey="id"
+ plugins={{columnResize: resizePlugin}}
+/>`,
+ },
],
theming: {
targets: [
@@ -193,6 +209,7 @@ const selectionPlugin = useXDSTableSelection<User>(selectionConfig);
'Styling is owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not by plugins — each reads XDSTableContext to apply density, dividers, striped, and hover styles.',
'XDSTable accepts plugins as a named Record<string, TablePlugin<T>> and converts to an ordered array internally; XDSBaseTable accepts an ordered array directly.',
'The selection plugin uses useSyncExternalStore so only the row whose selection state changed re-renders. useXDSTableSelectionState manages the selection set and handles disabled/selectable row filtering for select-all automatically.',
+ 'useXDSTableColumnResize — drag-to-resize column headers. Proportional columns preserve their ratio when neighboring columns are resized. Pass columnWidths state and onColumnResizeEnd to control width persistence. Use minWidth/maxWidth for per-resize constraints.',
'Body rows are memoized via React.memo with a custom comparison. For optimal performance, define columns outside the component or memoize them to avoid triggering full re-renders.',
'Columns can be auto-generated from data keys using generateColumns(); column widths are expressed as proportional (fr-like) or fixed pixel values via the proportional() and pixel() helpers.',
'tableProps on XDSBaseTable passes additional HTML attributes directly to the <table> element.',
@@ -778,6 +795,7 @@ export const docsZh = {
'通过 useXDSTableSortable 实现排序 — 单列或多列排序,表头指示器',
'通过 useXDSTablePagination 实现分页 — 客户端、服务器端或游标分页,自动渲染控件',
'通过 useXDSTableColumnSettings 实现列可见性 — 切换、排序和重置列',
+ '通过 useXDSTableColumnResize 实现列调整 — 拖拽表头调整宽度,支持最小/最大约束和等比例调整',
'主体行使用自定义比较进行记忆化 — 仅重新渲染更改的行',
'省略 columns 属性时,自动从数据对象键生成列',
'通过 className 实现主题化 — 目标选择器:.xds-base-table、.xds-table-row、.xds-table-cell、.xds-table-header-cell',
@@ -934,6 +952,21 @@ const selectionPlugin = useXDSTableSelection<User>(selectionConfig);
<XDSTable data={users} plugins={{highlight: highlightPlugin}} />`,
},
+ {
+ label: '列调整宽度插件',
+ code: `const [columnWidths, setColumnWidths] = useState({});
+const resizePlugin = useXDSTableColumnResize({
+ columnWidths,
+ columns,
+ onColumnResizeEnd: updates => setColumnWidths(prev => ({...prev, ...updates})),
+});
+<XDSTable
+ data={users}
+ columns={columns}
+ idKey="id"
+ plugins={{columnResize: resizePlugin}}
+/>`,
+ },
],
theming: {
targets: [
@@ -954,6 +987,7 @@ const selectionPlugin = useXDSTableSelection<User>(selectionConfig);
'样式由组件(XDSTableRow、XDSTableCell、XDSTableHeaderCell)控制,而非插件 — 每个组件读取 XDSTableContext 来应用密度、分隔线、条纹和悬停样式。',
'XDSTable 接受命名的 Record<string, TablePlugin<T>> 格式的插件,并在内部转换为有序数组;XDSBaseTable 直接接受有序数组。',
'选择插件使用 React Context,使 SelectAllCheckbox 和 SelectionRowCheckbox 独立于行内容重新渲染 — 仅当选择状态变化时更新 context 值。',
+ 'useXDSTableColumnResize — 拖拽表头调整列宽。比例列在调整相邻列时保持比例。传入 columnWidths 状态和 onColumnResizeEnd 控制宽度持久化。使用 minWidth/maxWidth 设置每次调整的约束范围。',
'主体行通过带有自定义比较的 React.memo 进行记忆化。为获得最佳性能,请在组件外部定义列或对其进行记忆化,以避免触发全量重新渲染。',
'可以使用 generateColumns() 从数据键自动生成列;列宽使用 proportional() 和 pixel() 辅助函数表达为比例值(类似 fr)或固定像素值。',
'XDSBaseTable 上的 tableProps 将额外的 HTML 属性直接传递给 <table> 元素。',