Skip to content

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.tsx
index 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.mjs
index 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 file
diff --git a/packages/core/src/Toolbar/XDSToolbar.tsx b/packages/core/src/Toolbar/XDSToolbar.tsx
index 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'>;