An open source design system that's fully customizable and agent ready
TypeScript
docs: fix Storybook compat issues, document Table sort/pagination/column plugins (#1057)
Joeyb57287f8a17e
diff --git a/packages/core/src/PowerSearch/XDSPowerSearch.tsx b/packages/core/src/PowerSearch/XDSPowerSearch.tsxindex 5431db6d64..361a8de234 100644--- a/packages/core/src/PowerSearch/XDSPowerSearch.tsx+++ b/packages/core/src/PowerSearch/XDSPowerSearch.tsx@@ -443,10 +443,11 @@ type PopoverState =* />* ```*+ * Use contentSearchFieldKey to designate a field for free-text search.+ * When set, unstructured text input is routed to that field.+ ** @example* ```- * // Use contentSearchFieldKey to designate a field for free-text search.- * // When set, unstructured text input is routed to this field.* const config = {* name: 'IssueSearch',* contentSearchFieldKey: 'title',diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjsindex 7f49fdaccf..0f4002a604 100644--- a/packages/core/src/Table/Table.doc.mjs+++ b/packages/core/src/Table/Table.doc.mjs@@ -14,6 +14,9 @@ export const docs = {'Divider styles: rows, columns, grid, none','Striped even rows and hover highlight via XDSTableContext','Selection via useXDSTableSelectionState + useXDSTableSelection — checkboxes, select-all, disabled row handling',+ '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','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',@@ -539,6 +542,218 @@ const selectionPlugin = useXDSTableSelection<User>(selectionConfig);data={users}columns={columns}plugins={{selection: selectionPlugin}}+/>`,+ },+ ],+ },+ {+ name: 'useXDSTableSortable',+ description:+ 'Headless multi-sort plugin for XDSTable. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.',+ props: [+ {+ name: 'sort',+ type: 'XDSTableSortState<TSortKey>',+ description:+ 'Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.',+ required: true,+ },+ {+ name: 'onSortChange',+ type: '(sort: XDSTableSortState<TSortKey>) => void',+ description:+ 'Called when the user clicks a header cell to change sort.',+ required: true,+ },+ {+ name: 'allowUnsortedState',+ type: 'boolean',+ description:+ 'Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.',+ default: 'false',+ },+ {+ name: 'isMultiSortEnabled',+ type: 'boolean',+ description:+ 'Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Single-column sort',+ code: `const [sort, setSort] = useState<XDSTableSortState>([+ { sortKey: 'name', direction: 'ascending' },+]);++const sortPlugin = useXDSTableSortable({+ sort,+ onSortChange: setSort,+});++<XDSTable+ data={users}+ columns={columns}+ plugins={{ sort: sortPlugin }}+/>`,+ },+ ],+ },+ {+ name: 'useXDSTablePagination',+ description:+ 'Headless pagination plugin for XDSTable. Supports client-side slicing, server-side pagination, and cursor-based pagination. Renders XDSPagination controls automatically above, below, or both.',+ props: [+ {+ name: 'page',+ type: 'number',+ description: 'Current page number (1-based).',+ required: true,+ },+ {+ name: 'onPageChange',+ type: '(page: number) => void',+ description: 'Called when the page changes.',+ required: true,+ },+ {+ name: 'totalItems',+ type: 'number',+ description:+ 'Total number of items across all pages. Used to calculate total page count.',+ },+ {+ name: 'totalPages',+ type: 'number',+ description:+ 'Total number of pages. Use when you know the page count but not item count.',+ },+ {+ name: 'hasMore',+ type: 'boolean',+ description:+ 'Whether more pages exist. Use for cursor-based pagination where the total is unknown.',+ },+ {+ name: 'pageSize',+ type: 'number',+ description: 'Number of items per page.',+ default: '10',+ },+ {+ name: 'onPageSizeChange',+ type: '(pageSize: number) => void',+ description:+ 'Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions.',+ },+ {+ name: 'pageSizeOptions',+ type: 'number[]',+ description:+ 'Available page size options. Shows a page size selector when provided.',+ },+ {+ name: 'variant',+ type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",+ description: 'Visual variant for the pagination controls.',+ default: "'pages'",+ },+ {+ name: 'position',+ type: "'below' | 'above' | 'both' | 'none'",+ description:+ 'Where to render pagination controls relative to the table.',+ default: "'below'",+ },+ {+ name: 'align',+ type: "'start' | 'center' | 'end'",+ description:+ 'Horizontal alignment of the pagination controls.',+ default: "'center'",+ },+ ],+ examples: [+ {+ label: 'Client-side pagination',+ code: `const [page, setPage] = useState(1);++const pagination = useXDSTablePagination({+ page,+ onPageChange: setPage,+ totalItems: data.length,+ pageSize: 20,+});++<XDSTable+ data={pagination.paginatedData(data)}+ columns={columns}+ plugins={{ pagination: pagination.plugin }}+/>`,+ },+ ],+ },+ {+ name: 'useXDSTableColumnSettings',+ description:+ 'Headless column visibility and ordering management for XDSTable. Provides filtered columns, toggle helpers, and pre-built XDSMultiSelector options for a column picker UI.',+ props: [+ {+ name: 'columns',+ type: 'XDSColumnSettingsOption[]',+ description:+ 'All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.',+ required: true,+ },+ {+ name: 'activeColumnKeys',+ type: 'string[]',+ description:+ 'Currently active column keys, in display order. Only columns with keys in this array are shown.',+ required: true,+ },+ {+ name: 'onChangeActiveColumnKeys',+ type: '(keys: string[]) => void',+ description:+ 'Called when active columns change (toggle, reorder).',+ required: true,+ },+ {+ name: 'defaultColumnKeys',+ type: 'string[]',+ description:+ 'Default column set for "Reset to default". When omitted, reset shows all columns.',+ },+ ],+ examples: [+ {+ label: 'Column visibility with MultiSelector',+ code: `const [activeKeys, setActiveKeys] = useState(['name', 'email', 'role']);++const columnSettings = useXDSTableColumnSettings({+ columns: [+ { key: 'name', label: 'Name', isAlwaysVisible: true },+ { key: 'email', label: 'Email' },+ { key: 'role', label: 'Role' },+ { key: 'status', label: 'Status' },+ ],+ activeColumnKeys: activeKeys,+ onChangeActiveColumnKeys: setActiveKeys,+});++<XDSMultiSelector+ label="Columns"+ options={columnSettings.columnOptions}+ value={[...columnSettings.activeColumnKeys]}+ onChange={columnSettings.setActiveColumnKeys}+ hasSelectAll+/>++<XDSTable+ data={data}+ columns={columnSettings.activeColumns(allColumns)}/>`,},],@@ -560,6 +775,9 @@ export const docsZh = {'分隔线样式:行、列、网格、无','通过 XDSTableContext 实现偶数行条纹和悬停高亮','通过 useXDSTableSelection 实现选择功能 — 复选框、全选、aria-selected',+ '通过 useXDSTableSortable 实现排序 — 单列或多列排序,表头指示器',+ '通过 useXDSTablePagination 实现分页 — 客户端、服务器端或游标分页,自动渲染控件',+ '通过 useXDSTableColumnSettings 实现列可见性 — 切换、排序和重置列','主体行使用自定义比较进行记忆化 — 仅重新渲染更改的行','省略 columns 属性时,自动从数据对象键生成列','通过 className 实现主题化 — 目标选择器:.xds-base-table、.xds-table-row、.xds-table-cell、.xds-table-header-cell',@@ -1016,6 +1234,170 @@ const selectionPlugin = useXDSTableSelection<User>(selectionConfig);data={users}columns={columns}plugins={{selection: selectionPlugin}}+/>`,+ },+ ],+ },+ {+ name: 'useXDSTableSortable',+ description:+ '无头多列排序插件。用户拥有排序状态并提供回调。Shift+点击启用二级排序列。排序指示器自动渲染在表头单元格中。',+ props: [+ {+ name: 'sort',+ type: 'XDSTableSortState<TSortKey>',+ description:+ '当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。',+ required: true,+ },+ {+ name: 'onSortChange',+ type: '(sort: XDSTableSortState<TSortKey>) => void',+ description:+ '用户点击表头单元格更改排序时调用。',+ required: true,+ },+ {+ name: 'allowUnsortedState',+ type: 'boolean',+ description:+ '允许循环回到未排序状态。为 true 时:升序、降序、未排序。为 false 时:升序、降序、升序。',+ default: 'false',+ },+ {+ name: 'isMultiSortEnabled',+ type: 'boolean',+ description:+ '通过 Shift+点击启用多列排序。普通点击仍替换整个排序状态。',+ default: 'false',+ },+ ],+ examples: [+ {+ label: '单列排序',+ code: `const [sort, setSort] = useState<XDSTableSortState>([+ { sortKey: 'name', direction: 'ascending' },+]);++const sortPlugin = useXDSTableSortable({+ sort,+ onSortChange: setSort,+});++<XDSTable+ data={users}+ columns={columns}+ plugins={{ sort: sortPlugin }}+/>`,+ },+ ],+ },+ {+ name: 'useXDSTablePagination',+ description:+ '无头分页插件。支持客户端切片、服务器端分页和游标分页。自动渲染 XDSPagination 控件。',+ props: [+ {+ name: 'page',+ type: 'number',+ description: '当前页码(从 1 开始)。',+ required: true,+ },+ {+ name: 'onPageChange',+ type: '(page: number) => void',+ description: '页面更改时调用。',+ required: true,+ },+ {+ name: 'totalItems',+ type: 'number',+ description:+ '所有页面的总项目数。用于计算总页数。',+ },+ {+ name: 'pageSize',+ type: 'number',+ description: '每页项目数。',+ default: '10',+ },+ {+ name: 'variant',+ type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",+ description: '分页控件的视觉变体。',+ default: "'pages'",+ },+ {+ name: 'position',+ type: "'below' | 'above' | 'both' | 'none'",+ description: '分页控件相对于表格的渲染位置。',+ default: "'below'",+ },+ ],+ examples: [+ {+ label: '客户端分页',+ code: `const [page, setPage] = useState(1);++const pagination = useXDSTablePagination({+ page,+ onPageChange: setPage,+ totalItems: data.length,+ pageSize: 20,+});++<XDSTable+ data={pagination.paginatedData(data)}+ columns={columns}+ plugins={{ pagination: pagination.plugin }}+/>`,+ },+ ],+ },+ {+ name: 'useXDSTableColumnSettings',+ description:+ '无头列可见性和排序管理。提供筛选后的列、切换帮助方法和 XDSMultiSelector 选项。',+ props: [+ {+ name: 'columns',+ type: 'XDSColumnSettingsOption[]',+ description:+ '所有可用列及其设置 UI 的元数据。每个条目包含 key、label、可选的 isAlwaysVisible 和 group。',+ required: true,+ },+ {+ name: 'activeColumnKeys',+ type: 'string[]',+ description:+ '当前活动的列键,按显示顺序排列。',+ required: true,+ },+ {+ name: 'onChangeActiveColumnKeys',+ type: '(keys: string[]) => void',+ description: '活动列更改时调用。',+ required: true,+ },+ ],+ examples: [+ {+ label: '列可见性与 MultiSelector',+ code: `const [activeKeys, setActiveKeys] = useState(['name', 'email']);++const columnSettings = useXDSTableColumnSettings({+ columns: [+ { key: 'name', label: 'Name', isAlwaysVisible: true },+ { key: 'email', label: 'Email' },+ { key: 'role', label: 'Role' },+ ],+ activeColumnKeys: activeKeys,+ onChangeActiveColumnKeys: setActiveKeys,+});++<XDSTable+ data={data}+ columns={columnSettings.activeColumns(allColumns)}/>`,},],@@ -1035,6 +1417,9 @@ export const docsDense = {'Divider styles: rows, columns, grid, none','Striped even rows + hover highlight via XDSTableContext','Selection via useXDSTableSelectionState + useXDSTableSelection — checkboxes, select-all, disabled row handling',+ 'Sorting via useXDSTableSortable — single/multi-column sort w/ header indicators',+ 'Pagination via useXDSTablePagination — client-side, server-side, cursor-based w/ auto-rendered controls',+ 'Column visibility via useXDSTableColumnSettings — toggle, reorder, reset w/ XDSMultiSelector integration','Body rows memoized w/ custom comparison; only changed rows re-render','Auto-generated columns from data object keys when columns omitted','Themeable via className; target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',@@ -1118,5 +1503,37 @@ export const docsDense = {getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',},},+ {+ name: 'useXDSTableSortable',+ description: 'Headless multi-sort plugin. Consumer owns sort state + callback. Shift+click for secondary sort. Sort indicators auto-render in header cells.',+ propDescriptions: {+ sort: 'Current sort state; ordered array of {sortKey, direction} entries.',+ onSortChange: 'Called on header click to change sort.',+ allowUnsortedState: 'Allow cycling to unsorted. true: asc>desc>unsorted. false: asc>desc>asc.',+ isMultiSortEnabled: 'Enable multi-sort via Shift+click. Regular click replaces sort state.',+ },+ },+ {+ name: 'useXDSTablePagination',+ description: 'Headless pagination plugin. Client-side slicing, server-side, or cursor-based. Auto-renders XDSPagination above/below/both.',+ propDescriptions: {+ page: 'Current page (1-based).',+ onPageChange: 'Called on page change.',+ totalItems: 'Total items across all pages.',+ pageSize: 'Items per page. Default 10.',+ variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",+ position: "Render position: 'below'|'above'|'both'|'none'.",+ },+ },+ {+ name: 'useXDSTableColumnSettings',+ description: 'Headless column visibility/ordering. Provides filtered columns, toggle helpers, XDSMultiSelector options.',+ propDescriptions: {+ columns: 'All available columns w/ metadata (key, label, isAlwaysVisible, group).',+ activeColumnKeys: 'Active column keys in display order.',+ onChangeActiveColumnKeys: 'Called on column toggle/reorder.',+ defaultColumnKeys: 'Default column set for reset. Omit = show all.',+ },+ },],};\ No newline at end of filediff --git a/packages/core/src/Toolbar/XDSToolbar.tsx b/packages/core/src/Toolbar/XDSToolbar.tsxindex a564ba0377..935a5308d6 100644--- a/packages/core/src/Toolbar/XDSToolbar.tsx+++ b/packages/core/src/Toolbar/XDSToolbar.tsx@@ -159,8 +159,8 @@ export interface XDSToolbarProps extends XDSBaseProps<HTMLDivElement> {* Which sides should have divider borders.* Passed through to XDSSection.* @example- * ```tsx- * dividers={['bottom']} // toolbar with a bottom border+ * ```+ * dividers={['bottom']}* ```*/dividers?: Array<'top' | 'bottom' | 'start' | 'end'>;