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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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> 元素。',