An open source design system that's fully customizable and agent ready
TypeScript
refactor(Table): decompose useXDSTableColumnSettings into state + plugin + adapter (#1161)
Cindy Zhang0daef1b23170
diff --git a/apps/storybook/stories/TableColumnSettings.stories.tsx b/apps/storybook/stories/TableColumnSettings.stories.tsxindex 124b6b1da2..bbf618c62a 100644--- a/apps/storybook/stories/TableColumnSettings.stories.tsx+++ b/apps/storybook/stories/TableColumnSettings.stories.tsx@@ -3,6 +3,7 @@ import type {Meta, StoryObj} from '@storybook/react';import {XDSTable,useXDSTableColumnSettings,+ useXDSTableColumnSettingsState,useXDSTableSelection,useXDSTableSelectionState,} from '@xds/core/Table';@@ -111,11 +112,17 @@ export const BasicColumnToggle: Story = {const [activeKeys, setActiveKeys] =useState<UserColumnKey[]>(defaultActiveKeys);- const columnSettings = useXDSTableColumnSettings<User, UserColumnKey>({+ const state = useXDSTableColumnSettingsState<UserColumnKey>({columns: columnOptions,activeColumnKeys: activeKeys,onChangeActiveColumnKeys: setActiveKeys,});+ const plugin = useXDSTableColumnSettings<User>(state.columnSettingsConfig);+ const selectorOptions = columnOptions.map(c => ({+ value: c.key,+ label: c.label,+ disabled: c.isAlwaysVisible === true,+ }));return (<div style={{maxWidth: 700}}>@@ -126,9 +133,9 @@ export const BasicColumnToggle: Story = {<XDSMultiSelectorlabel="Columns"isLabelHidden- options={columnSettings.columnOptions}- value={[...columnSettings.activeColumnKeys]}- onChange={columnSettings.setActiveColumnKeys}+ options={selectorOptions}+ value={[...state.activeColumnKeys]}+ onChange={state.setActiveColumnKeys}/>}/>@@ -136,7 +143,7 @@ export const BasicColumnToggle: Story = {data={users}columns={allColumns}idKey="id"- plugins={{columnSettings: columnSettings.plugin}}+ plugins={{columnSettings: plugin}}/></div>);@@ -151,11 +158,17 @@ export const DisabledColumns: Story = {'role',]);- const columnSettings = useXDSTableColumnSettings<User, UserColumnKey>({+ const state = useXDSTableColumnSettingsState<UserColumnKey>({columns: columnOptions,activeColumnKeys: activeKeys,onChangeActiveColumnKeys: setActiveKeys,});+ const plugin = useXDSTableColumnSettings<User>(state.columnSettingsConfig);+ const selectorOptions = columnOptions.map(c => ({+ value: c.key,+ label: c.label,+ disabled: c.isAlwaysVisible === true,+ }));return (<div style={{maxWidth: 700}}>@@ -169,9 +182,9 @@ export const DisabledColumns: Story = {<XDSMultiSelectorlabel="Columns"isLabelHidden- options={columnSettings.columnOptions}- value={[...columnSettings.activeColumnKeys]}- onChange={columnSettings.setActiveColumnKeys}+ options={selectorOptions}+ value={[...state.activeColumnKeys]}+ onChange={state.setActiveColumnKeys}/>}/>@@ -179,7 +192,7 @@ export const DisabledColumns: Story = {data={users}columns={allColumns}idKey="id"- plugins={{columnSettings: columnSettings.plugin}}+ plugins={{columnSettings: plugin}}/></div>);@@ -190,15 +203,20 @@ export const ResetToDefault: Story = {render: () => {const defaultKeys: UserColumnKey[] = ['name', 'email', 'role'];- const [activeKeys, setActiveKeys] =- useState<UserColumnKey[]>(defaultKeys);+ const [activeKeys, setActiveKeys] = useState<UserColumnKey[]>(defaultKeys);- const columnSettings = useXDSTableColumnSettings<User, UserColumnKey>({+ const state = useXDSTableColumnSettingsState<UserColumnKey>({columns: columnOptions,activeColumnKeys: activeKeys,onChangeActiveColumnKeys: setActiveKeys,defaultColumnKeys: defaultKeys,});+ const plugin = useXDSTableColumnSettings<User>(state.columnSettingsConfig);+ const selectorOptions = columnOptions.map(c => ({+ value: c.key,+ label: c.label,+ disabled: c.isAlwaysVisible === true,+ }));return (<div style={{maxWidth: 700}}>@@ -214,14 +232,14 @@ export const ResetToDefault: Story = {<XDSButtonlabel="Reset to default"variant="secondary"- onClick={columnSettings.resetToDefault}+ onClick={state.resetToDefault}/><XDSMultiSelectorlabel="Columns"isLabelHidden- options={columnSettings.columnOptions}- value={[...columnSettings.activeColumnKeys]}- onChange={columnSettings.setActiveColumnKeys}+ options={selectorOptions}+ value={[...state.activeColumnKeys]}+ onChange={state.setActiveColumnKeys}/></>}@@ -230,7 +248,7 @@ export const ResetToDefault: Story = {data={users}columns={allColumns}idKey="id"- plugins={{columnSettings: columnSettings.plugin}}+ plugins={{columnSettings: plugin}}/></div>);@@ -243,11 +261,19 @@ export const WithSelection: Story = {useState<UserColumnKey[]>(defaultActiveKeys);const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());- const columnSettings = useXDSTableColumnSettings<User, UserColumnKey>({+ const state = useXDSTableColumnSettingsState<UserColumnKey>({columns: columnOptions,activeColumnKeys: activeKeys,onChangeActiveColumnKeys: setActiveKeys,});+ const columnPlugin = useXDSTableColumnSettings<User>(+ state.columnSettingsConfig,+ );+ const selectorOptions = columnOptions.map(c => ({+ value: c.key,+ label: c.label,+ disabled: c.isAlwaysVisible === true,+ }));const {selectionConfig} = useXDSTableSelectionState<User>({data: users,@@ -270,9 +296,9 @@ export const WithSelection: Story = {<XDSMultiSelectorlabel="Columns"isLabelHidden- options={columnSettings.columnOptions}- value={[...columnSettings.activeColumnKeys]}- onChange={columnSettings.setActiveColumnKeys}+ options={selectorOptions}+ value={[...state.activeColumnKeys]}+ onChange={state.setActiveColumnKeys}/>}/>@@ -281,7 +307,7 @@ export const WithSelection: Story = {columns={allColumns}idKey="id"plugins={{- columnSettings: columnSettings.plugin,+ columnSettings: columnPlugin,selection: selectionPlugin,}}/>diff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.tsindex 4fbe1b24b7..69e557d453 100644--- a/packages/core/src/Table/index.ts+++ b/packages/core/src/Table/index.ts@@ -20,6 +20,7 @@ export {useXDSTableSelectionState} from './plugins/selection';export {useXDSTableSortable} from './plugins/sortable';export {useXDSTablePagination} from './plugins/pagination';export {useXDSTableColumnSettings} from './plugins/columnSettings';+export {useXDSTableColumnSettingsState} from './plugins/columnSettings';export {useXDSTableColumnResize} from './plugins/columnResize';export {useXDSTableFiltering,@@ -77,9 +78,12 @@ export type {} from './plugins/pagination';export type {UseXDSTableColumnSettingsConfig,- UseXDSTableColumnSettingsReturn,XDSColumnSettingsOption,} from './plugins/columnSettings';+export type {+ UseXDSTableColumnSettingsStateConfig,+ UseXDSTableColumnSettingsStateReturn,+} from './plugins/columnSettings';export type {UseXDSTableColumnResizeConfig} from './plugins/columnResize';export type {UseXDSTableFilteringConfig,diff --git a/packages/core/src/Table/plugins/columnSettings/index.ts b/packages/core/src/Table/plugins/columnSettings/index.tsindex ef76fbfc54..e4890fbbce 100644--- a/packages/core/src/Table/plugins/columnSettings/index.ts+++ b/packages/core/src/Table/plugins/columnSettings/index.ts@@ -1,6 +1,10 @@export {useXDSTableColumnSettings} from './useXDSTableColumnSettings';export type {UseXDSTableColumnSettingsConfig,- UseXDSTableColumnSettingsReturn,XDSColumnSettingsOption,} from './useXDSTableColumnSettings';+export {useXDSTableColumnSettingsState} from './useXDSTableColumnSettingsState';+export type {+ UseXDSTableColumnSettingsStateConfig,+ UseXDSTableColumnSettingsStateReturn,+} from './useXDSTableColumnSettingsState';diff --git a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.test.tsx b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.test.tsxindex cdd89725f3..a7618168be 100644--- a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.test.tsx+++ b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.test.tsx@@ -1,20 +1,21 @@/*** @file useXDSTableColumnSettings.test.tsx- * @input useXDSTableColumnSettings, XDSTable, React testing utilities- * @output Functional tests for the column settings plugin- * @position Test file; validates column visibility, toggling, column options+ * @input useXDSTableColumnSettings, useXDSTableColumnSettingsState, XDSTable, React testing utilities+ * @output Functional tests for the column settings plugin, selector adapter, and integration+ * @position Test file; validates plugin behavior and integration*/import {describe, it, expect, vi} from 'vitest';import {useState} from 'react';import {render, screen} from '@testing-library/react';-import {renderHook, act} from '@testing-library/react';+import {renderHook} from '@testing-library/react';import {XDSTable} from '../../XDSTable';import {useXDSTableColumnSettings,type UseXDSTableColumnSettingsConfig,type XDSColumnSettingsOption,} from './useXDSTableColumnSettings';+import {useXDSTableColumnSettingsState} from './useXDSTableColumnSettingsState';import type {XDSTableColumn} from '../../types';// =============================================================================@@ -66,487 +67,106 @@ const columnOptions: XDSColumnSettingsOption[] = [];// =============================================================================-// Helpers-// =============================================================================--function renderColumnSettingsHook(- overrides: Partial<UseXDSTableColumnSettingsConfig> = {},-) {- const defaultConfig: UseXDSTableColumnSettingsConfig = {- columns: columnOptions,- activeColumnKeys: ['name', 'email', 'role'],- onChangeActiveColumnKeys: vi.fn(),- ...overrides,- };-- return renderHook(() =>- useXDSTableColumnSettings<User>(defaultConfig),- );-}--// =============================================================================-// Hook Return Value+// Plugin Hook Tests// =============================================================================describe('useXDSTableColumnSettings', () => {- describe('return value', () => {- it('returns plugin object with transformColumns', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.plugin).toBeDefined();- expect(result.current.plugin.transformColumns).toBeInstanceOf(- Function,- );- });-- it('transformColumns filters and reorders columns by activeColumnKeys', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['role', 'name'], // reversed order, missing 'email'- });-- const allColumns: XDSTableColumn<User>[] = [- {key: 'name', header: 'Name'},- {key: 'email', header: 'Email'},- {key: 'role', header: 'Role'},- ];-- const filtered = result.current.plugin.transformColumns!(allColumns);- expect(filtered.map(c => c.key)).toEqual(['role', 'name']);- });-- it('returns activeColumns function', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.activeColumns).toBeInstanceOf(Function);- });-- it('returns toggleColumn function', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.toggleColumn).toBeInstanceOf(Function);- });-- it('returns isColumnActive function', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.isColumnActive).toBeInstanceOf(Function);- });-- it('returns isColumnToggleable function', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.isColumnToggleable).toBeInstanceOf(Function);- });-- it('returns activeColumnKeys passthrough', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- });- expect(result.current.activeColumnKeys).toEqual(['name', 'email']);- });+ function renderPluginHook(+ overrides: Partial<UseXDSTableColumnSettingsConfig> = {},+ ) {+ const defaultConfig: UseXDSTableColumnSettingsConfig = {+ columns: columnOptions,+ activeColumnKeys: ['name', 'email', 'role'],+ onChangeActiveColumnKeys: vi.fn(),+ ...overrides,+ };++ return renderHook(() => useXDSTableColumnSettings<User>(defaultConfig));+ }++ it('returns a TablePlugin with transformColumns', () => {+ const {result} = renderPluginHook();+ expect(result.current).toBeDefined();+ expect(result.current.transformColumns).toBeInstanceOf(Function);});- // ===========================================================================- // activeColumns helper- // ===========================================================================-- describe('activeColumns', () => {- it('filters columns to only active keys', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email', 'role'],- });- const filtered = result.current.activeColumns(allTableColumns);- expect(filtered).toHaveLength(3);- expect(filtered.map((c) => c.key)).toEqual(['name', 'email', 'role']);- });-- it('preserves activeColumnKeys order', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['role', 'name', 'email'],- });- const filtered = result.current.activeColumns(allTableColumns);- expect(filtered.map((c) => c.key)).toEqual(['role', 'name', 'email']);- });-- it('handles unknown keys gracefully', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'nonexistent', 'email'],- });- const filtered = result.current.activeColumns(allTableColumns);- expect(filtered).toHaveLength(2);- expect(filtered.map((c) => c.key)).toEqual(['name', 'email']);- });-- it('returns empty array for empty activeColumnKeys', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: [],- });- const filtered = result.current.activeColumns(allTableColumns);- expect(filtered).toHaveLength(0);+ it('transformColumns filters columns by activeColumnKeys', () => {+ const {result} = renderPluginHook({+ activeColumnKeys: ['name', 'email'],});- it('returns all columns when all keys active', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email', 'role', 'status', 'lastLogin'],- });- const filtered = result.current.activeColumns(allTableColumns);- expect(filtered).toHaveLength(5);- });-- it('maintains XDSTableColumn shape', () => {- const columnsWithRenderCell: XDSTableColumn<User>[] = [- {key: 'name', header: 'Name', renderCell: (item) => item.name},- {key: 'email', header: 'Email'},- ];- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- });- const filtered = result.current.activeColumns(columnsWithRenderCell);- expect(filtered[0].key).toBe('name');- expect(filtered[0].header).toBe('Name');- expect(filtered[0].renderCell).toBeInstanceOf(Function);- });+ const filtered = result.current.transformColumns!(allTableColumns);+ expect(filtered.map(c => c.key)).toEqual(['name', 'email']);});- // ===========================================================================- // toggleColumn- // ===========================================================================-- describe('toggleColumn', () => {- it('removes active column', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email', 'role'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.toggleColumn('email'));- expect(onChange).toHaveBeenCalledWith(['name', 'role']);- });-- it('adds inactive column at end', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.toggleColumn('status'));- expect(onChange).toHaveBeenCalledWith(['name', 'email', 'status']);- });-- it('no-op for isAlwaysVisible columns', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.toggleColumn('name'));- expect(onChange).not.toHaveBeenCalled();+ it('transformColumns reorders columns by activeColumnKeys order', () => {+ const {result} = renderPluginHook({+ activeColumnKeys: ['role', 'name'],});- it('calls onChangeActiveColumnKeys with new array', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.toggleColumn('role'));- expect(onChange).toHaveBeenCalledTimes(1);- expect(onChange).toHaveBeenCalledWith(['name', 'email', 'role']);- });+ const filtered = result.current.transformColumns!(allTableColumns);+ expect(filtered.map(c => c.key)).toEqual(['role', 'name']);});- // ===========================================================================- // isColumnActive- // ===========================================================================-- describe('isColumnActive', () => {- it('returns true for active columns', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- });- expect(result.current.isColumnActive('name')).toBe(true);- expect(result.current.isColumnActive('email')).toBe(true);- });-- it('returns false for inactive columns', () => {- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email'],- });- expect(result.current.isColumnActive('role')).toBe(false);- expect(result.current.isColumnActive('status')).toBe(false);- });+ it('plugin reference is stable across renders', () => {+ const {result, rerender} = renderPluginHook();+ const firstPlugin = result.current;+ rerender();+ expect(result.current).toBe(firstPlugin);});+});- // ===========================================================================- // isColumnToggleable- // ===========================================================================-- describe('isColumnToggleable', () => {- it('returns true for normal columns', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.isColumnToggleable('email')).toBe(true);- expect(result.current.isColumnToggleable('role')).toBe(true);- });-- it('returns false for always-visible columns', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.isColumnToggleable('name')).toBe(false);- });- });-- // ===========================================================================- // showAllColumns- // ===========================================================================-- describe('showAllColumns', () => {- it('sets all column keys as active in columns config order', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.showAllColumns());- expect(onChange).toHaveBeenCalledWith([- 'name',- 'email',- 'role',- 'status',- 'lastLogin',- ]);- });- });-- // ===========================================================================- // resetToDefault- // ===========================================================================-- describe('resetToDefault', () => {- it('resets to defaultColumnKeys when provided', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name', 'email', 'role', 'status', 'lastLogin'],- onChangeActiveColumnKeys: onChange,- defaultColumnKeys: ['name', 'email'],- });-- act(() => result.current.resetToDefault());- expect(onChange).toHaveBeenCalledWith(['name', 'email']);- });-- it('shows all columns when no defaultColumnKeys', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- activeColumnKeys: ['name'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.resetToDefault());- expect(onChange).toHaveBeenCalledWith([- 'name',- 'email',- 'role',- 'status',- 'lastLogin',- ]);- });- });-- // ===========================================================================- // columnOptions- // ===========================================================================-- describe('columnOptions', () => {- it('generates one item per column for ungrouped columns', () => {- const {result} = renderColumnSettingsHook();- expect(result.current.columnOptions).toHaveLength(5);- });-- it('marks always-visible columns as disabled', () => {- const {result} = renderColumnSettingsHook();- const items = result.current.columnOptions;- // First item is 'name' with isAlwaysVisible- const nameItem = items[0];- expect(nameItem).toHaveProperty('disabled', true);- // Second item is 'email' without isAlwaysVisible- const emailItem = items[1];- expect(emailItem).toHaveProperty('disabled', false);- });-- it('generates items with value and label', () => {- const {result} = renderColumnSettingsHook();- const items = result.current.columnOptions;- const first = items[0] as {value: string; label: string};- expect(first.value).toBe('name');- expect(first.label).toBe('Name');- });-- it('groups columns by group field into sections', () => {- const groupedColumns: XDSColumnSettingsOption[] = [- {key: 'name', label: 'Name', isAlwaysVisible: true, group: 'Basic'},- {key: 'email', label: 'Email', group: 'Basic'},- {key: 'role', label: 'Role', group: 'Details'},- {key: 'status', label: 'Status'},- ];-- const {result} = renderColumnSettingsHook({columns: groupedColumns});- const items = result.current.columnOptions;-- // Should have 2 sections + 1 ungrouped item- const sections = items.filter(- (i) => typeof i === 'object' && 'type' in i && i.type === 'section',- );- expect(sections).toHaveLength(2);-- const basicSection = sections[0] as {- type: 'section';- title: string;- options: Array<{value: string}>;- };- expect(basicSection.title).toBe('Basic');- expect(basicSection.options).toHaveLength(2);-- // Ungrouped item ('status') appears after sections- const lastItem = items[items.length - 1] as {value: string};- expect(lastItem.value).toBe('status');- });- });-- // ===========================================================================- // setActiveColumnKeys- // ===========================================================================-- describe('setActiveColumnKeys', () => {- it('passes selected values to onChangeActiveColumnKeys', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- onChangeActiveColumnKeys: onChange,- });-- act(() =>- result.current.setActiveColumnKeys(['name', 'email', 'status']),- );- expect(onChange).toHaveBeenCalledWith(- expect.arrayContaining(['name', 'email', 'status']),- );- });-- it('enforces isAlwaysVisible columns remain in set', () => {- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- onChangeActiveColumnKeys: onChange,- });-- // Try to deselect 'name' (isAlwaysVisible) by not including it- act(() => result.current.setActiveColumnKeys(['email']));- const calledWith = onChange.mock.calls[0][0] as string[];- expect(calledWith).toContain('name');- expect(calledWith).toContain('email');- });- });-- // ===========================================================================- // Integration with XDSTable- // ===========================================================================-- describe('integration with XDSTable', () => {- function ColumnSettingsTable({- initialActiveKeys,- }: {- initialActiveKeys: string[];- }) {- const [activeKeys, setActiveKeys] = useState(initialActiveKeys);-- const columnSettings = useXDSTableColumnSettings<User>({- columns: columnOptions,- activeColumnKeys: activeKeys,- onChangeActiveColumnKeys: setActiveKeys,- });-- return (- <XDSTable- data={testUsers}- columns={columnSettings.activeColumns(allTableColumns)}- plugins={[columnSettings.plugin]}- idKey="id"- />- );- }-- it('table renders only active columns', () => {- render(- <ColumnSettingsTable initialActiveKeys={['name', 'email', 'role']} />,- );-- // Active columns should be visible- expect(screen.getByText('Name')).toBeInTheDocument();- expect(screen.getByText('Email')).toBeInTheDocument();- expect(screen.getByText('Role')).toBeInTheDocument();-- // Inactive columns should not be visible- expect(screen.queryByText('Status')).not.toBeInTheDocument();- expect(screen.queryByText('Last Login')).not.toBeInTheDocument();- });-- it('column order matches activeColumnKeys order', () => {- render(- <ColumnSettingsTable initialActiveKeys={['role', 'name', 'email']} />,- );+// =============================================================================+// Integration: state hook + plugin hook + XDSTable+// =============================================================================- const headers = screen.getAllByRole('columnheader');- expect(headers[0]).toHaveTextContent('Role');- expect(headers[1]).toHaveTextContent('Name');- expect(headers[2]).toHaveTextContent('Email');- });+describe('integration with XDSTable', () => {+ function ColumnSettingsTable({+ initialActiveKeys,+ }: {+ initialActiveKeys: string[];+ }) {+ const [activeKeys, setActiveKeys] = useState(initialActiveKeys);++ const state = useXDSTableColumnSettingsState({+ columns: columnOptions,+ activeColumnKeys: activeKeys,+ onChangeActiveColumnKeys: setActiveKeys,+ });++ const plugin = useXDSTableColumnSettings<User>(state.columnSettingsConfig);++ return (+ <XDSTable+ data={testUsers}+ columns={allTableColumns}+ plugins={{columnSettings: plugin}}+ idKey="id"+ />+ );+ }++ it('table renders only active columns', () => {+ render(+ <ColumnSettingsTable initialActiveKeys={['name', 'email', 'role']} />,+ );++ expect(screen.getByText('Name')).toBeInTheDocument();+ expect(screen.getByText('Email')).toBeInTheDocument();+ expect(screen.getByText('Role')).toBeInTheDocument();++ expect(screen.queryByText('Status')).not.toBeInTheDocument();+ expect(screen.queryByText('Last Login')).not.toBeInTheDocument();});- // ===========================================================================- // Edge Cases- // ===========================================================================+ it('column order matches activeColumnKeys order', () => {+ render(+ <ColumnSettingsTable initialActiveKeys={['role', 'name', 'email']} />,+ );- describe('edge cases', () => {- it('handles empty columns config', () => {- const {result} = renderColumnSettingsHook({- columns: [],- activeColumnKeys: [],- });-- expect(result.current.columnOptions).toHaveLength(0);- expect(result.current.activeColumns(allTableColumns)).toHaveLength(0);- });-- it('handles single column with isAlwaysVisible', () => {- const {result} = renderColumnSettingsHook({- columns: [{key: 'name', label: 'Name', isAlwaysVisible: true}],- activeColumnKeys: ['name'],- });-- expect(result.current.isColumnToggleable('name')).toBe(false);- expect(result.current.isColumnActive('name')).toBe(true);- });-- it('handles all columns isAlwaysVisible', () => {- const allVisible: XDSColumnSettingsOption[] = [- {key: 'name', label: 'Name', isAlwaysVisible: true},- {key: 'email', label: 'Email', isAlwaysVisible: true},- ];-- const onChange = vi.fn();- const {result} = renderColumnSettingsHook({- columns: allVisible,- activeColumnKeys: ['name', 'email'],- onChangeActiveColumnKeys: onChange,- });-- act(() => result.current.toggleColumn('name'));- act(() => result.current.toggleColumn('email'));- expect(onChange).not.toHaveBeenCalled();- });-- it('plugin reference is stable across renders', () => {- const {result, rerender} = renderColumnSettingsHook();- const firstPlugin = result.current.plugin;- rerender();- expect(result.current.plugin).toBe(firstPlugin);- });+ const headers = screen.getAllByRole('columnheader');+ expect(headers[0]).toHaveTextContent('Role');+ expect(headers[1]).toHaveTextContent('Name');+ expect(headers[2]).toHaveTextContent('Email');});});diff --git a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsxindex 0cdcf25c09..73eaedd116 100644--- a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx+++ b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx@@ -2,21 +2,24 @@/*** @file useXDSTableColumnSettings.tsx- * @input React, Table types, MultiSelector types- * @output Exports useXDSTableColumnSettings hook and config/return types+ * @input React, Table types+ * @output Exports useXDSTableColumnSettings plugin hook and types* @position Column settings plugin; consumed by XDSTable via plugins prop*- * Headless column visibility and ordering management for XDSTable.- * The consumer owns all state — the hook provides filtered columns,- * toggle helpers, and pre-built XDSMultiSelector options.+ * Pure plugin hook — takes column settings config, returns a TablePlugin+ * that filters and reorders columns via `transformColumns`.+ *+ * For state management (toggle, reset, visibility checks), use+ * `useXDSTableColumnSettingsState` which produces the config this hook needs.** SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Table/plugins/columnSettings/index.ts (exports)* - /packages/core/src/Table/index.ts (exports)*/-import {useCallback, useMemo, useRef} from 'react';+import {useMemo, useRef} from 'react';import type {TablePlugin, XDSTableColumn} from '../../types';-import type {XDSMultiSelectorOptionType} from '../../../MultiSelector/types';+import type {UseXDSTableColumnSettingsStateConfig} from './useXDSTableColumnSettingsState';// =============================================================================// Config Types@@ -27,9 +30,7 @@ import type {XDSMultiSelectorOptionType} from '../../../MultiSelector/types';* Separate from XDSTableColumn because the settings UI needs metadata* (label, group, disableability) that the table column doesn't carry.*/-export interface XDSColumnSettingsOption<- TColumnKey extends string = string,-> {+export interface XDSColumnSettingsOption<TColumnKey extends string = string> {/** Column key — must match XDSTableColumn.key */key: TColumnKey;/** Human-readable label for the column settings UI */@@ -52,191 +53,41 @@ export interface XDSColumnSettingsOption</*** Configuration for useXDSTableColumnSettings.*- * Headless column visibility and ordering management for XDSTable.- * The consumer owns all state. The hook provides filtered columns- * and a plugin for table integration.+ * This is the same shape as UseXDSTableColumnSettingsStateConfig —+ * you can pass `state.columnSettingsConfig` directly, or construct+ * it manually if you don't need the state hook.** @template TColumnKey - String literal union of column keys- *- * @example- * ```- * const allColumns = [- * { key: 'name', header: 'Name' },- * { key: 'email', header: 'Email' },- * { key: 'role', header: 'Role' },- * { key: 'status', header: 'Status' },- * ];- *- * 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,- * });- *- * <XDSTable- * data={data}- * columns={columnSettings.activeColumns(allColumns)}- * plugins={[columnSettings.plugin]}- * />- * ```- *- * @example- * ```- * <XDSMultiSelector- * label="Columns"- * options={columnSettings.columnOptions}- * value={[...columnSettings.activeColumnKeys]}- * onChange={columnSettings.setActiveColumnKeys}- * hasSelectAll- * />- * ```*/-export interface UseXDSTableColumnSettingsConfig<+export type UseXDSTableColumnSettingsConfig<TColumnKey extends string = string,-> {- /**- * All available columns with metadata for the settings UI.- * This defines the universe of columns the user can toggle.- */- columns: ReadonlyArray<XDSColumnSettingsOption<TColumnKey>>;-- /**- * Currently active column keys, in display order.- * Only columns with keys in this array are shown in the table.- * The array order determines column display order.- */- activeColumnKeys: ReadonlyArray<TColumnKey>;-- /**- * Called when active columns change (toggle, reorder).- * Consumer updates their own state.- */- onChangeActiveColumnKeys: (keys: ReadonlyArray<TColumnKey>) => void;-- /**- * The default column set for "Reset to default" functionality.- * When omitted, resetToDefault shows all columns.- */- defaultColumnKeys?: ReadonlyArray<TColumnKey>;-}+> = UseXDSTableColumnSettingsStateConfig<TColumnKey>;// =============================================================================-// Return Type+// Plugin Hook// =============================================================================/**- * Return value of useXDSTableColumnSettings.- */-export interface UseXDSTableColumnSettingsReturn<- T extends Record<string, unknown>,- TColumnKey extends string = string,-> {- /** The TablePlugin to pass to XDSTable's plugins prop. */- plugin: TablePlugin<T>;-- /**- * Filters and reorders the full columns array based on activeColumnKeys.- * Returns only active columns, in the order specified by activeColumnKeys.- *- * **Note:** When using the plugin with XDSTable, you typically don't need- * this — the plugin's `transformColumns` handles filtering automatically.- * Pass all columns to XDSTable and let the plugin do the work.- * Use `activeColumns()` when you need the filtered array for non-table- * purposes (e.g., rendering column headers in a toolbar or export).- *- * @example- * ```- * // Preferred: let the plugin filter via transformColumns- * <XDSTable columns={allColumns} plugins={{ columnSettings: cs.plugin }} />- *- * // Manual: for non-table usage- * const visibleCols = cs.activeColumns(allColumns);- * ```- */- activeColumns: (columns: XDSTableColumn<T>[]) => XDSTableColumn<T>[];-- /**- * Toggle a column's visibility.- * If the column is active, removes it. If inactive, adds it to the end.- * No-op for columns with `isAlwaysVisible: true`.- */- toggleColumn: (key: TColumnKey) => void;-- /**- * Whether a specific column is currently active (visible).- */- isColumnActive: (key: TColumnKey) => boolean;-- /**- * Whether a specific column can be toggled.- * Returns false for columns with `isAlwaysVisible: true`.- */- isColumnToggleable: (key: TColumnKey) => boolean;-- /**- * Show all columns.- */- showAllColumns: () => void;-- /**- * Reset to the default column set.- * Uses `defaultColumnKeys` if provided, otherwise shows all columns.- */- resetToDefault: () => void;-- /**- * Column options formatted for XDSMultiSelector.- * Each option represents a column; always-visible columns are disabled.- * Columns with a `group` are rendered as sections.- *- * @example- * ```- * <XDSMultiSelector- * label="Columns"- * options={columnSettings.columnOptions}- * value={[...columnSettings.activeColumnKeys]}- * onChange={columnSettings.setActiveColumnKeys}- * />- * ```- */- columnOptions: XDSMultiSelectorOptionType[];-- /**- * Set active column keys from a list of key strings.- * Enforces that `isAlwaysVisible` columns remain in the active set.- * Pass directly as `onChange` to XDSMultiSelector.- */- setActiveColumnKeys: (keys: string[]) => void;-- /** Currently active column keys (pass-through from config). */- activeColumnKeys: ReadonlyArray<TColumnKey>;-}--// =============================================================================-// Hook-// =============================================================================--/**- * Headless column visibility and ordering management for XDSTable.+ * Column settings table plugin — filters and reorders columns based on+ * the active column keys.*- * Manages which columns are visible and in what order, provides a table plugin- * for integration, and generates pre-built items for XDSMultiSelector.- * The consumer owns all state — the hook provides helpers and a stable plugin.+ * Returns a `TablePlugin` directly (same pattern as `useXDSTableSortable`,+ * `useXDSTableSelection`, etc.).** @example* ```- * const columnSettings = useXDSTableColumnSettings({- * columns: [- * { key: 'name', label: 'Name', isAlwaysVisible: true },- * { key: 'email', label: 'Email' },- * ],+ * // With the state hook (recommended)+ * const state = useXDSTableColumnSettingsState({ columns, activeColumnKeys, onChangeActiveColumnKeys });+ * const plugin = useXDSTableColumnSettings(state.columnSettingsConfig);+ *+ * <XDSTable columns={allColumns} plugins={{ columnSettings: plugin }} />+ * ```+ *+ * @example+ * ```+ * // Without state hook — manual config+ * const plugin = useXDSTableColumnSettings({+ * columns: columnDefs,* activeColumnKeys: activeKeys,* onChangeActiveColumnKeys: setActiveKeys,* });@@ -245,163 +96,13 @@ export interface UseXDSTableColumnSettingsReturn<export function useXDSTableColumnSettings<T extends Record<string, unknown>,TColumnKey extends string = string,->(- config: UseXDSTableColumnSettingsConfig<TColumnKey>,-): UseXDSTableColumnSettingsReturn<T, TColumnKey> {- const {columns, activeColumnKeys} = config;-- // Keep config in a ref so the plugin and callbacks always read- // the latest version without forcing new object identity.+>(config: UseXDSTableColumnSettingsConfig<TColumnKey>): TablePlugin<T> {+ // Keep config in a ref so the plugin reads the latest values+ // without changing plugin identity.const configRef = useRef(config);configRef.current = config;- // Build lookup sets for fast checks- const activeSet = useMemo(- () => new Set(activeColumnKeys),- [activeColumnKeys],- );-- const alwaysVisibleSet = useMemo(- () => new Set(columns.filter((c) => c.isAlwaysVisible).map((c) => c.key)),- [columns],- );-- // --- Column operations ----- const toggleColumn = useCallback(- (key: TColumnKey) => {- const cfg = configRef.current;- const avSet = new Set(- cfg.columns.filter((c) => c.isAlwaysVisible).map((c) => c.key),- );- if (avSet.has(key)) return;-- const currentKeys = cfg.activeColumnKeys;- const currentSet = new Set(currentKeys);- if (currentSet.has(key)) {- cfg.onChangeActiveColumnKeys(currentKeys.filter((k) => k !== key));- } else {- cfg.onChangeActiveColumnKeys([...currentKeys, key]);- }- },- // configRef is stable — no deps needed beyond the ref- [],- );-- const isColumnActive = useCallback(- (key: TColumnKey) => activeSet.has(key),- [activeSet],- );-- const isColumnToggleable = useCallback(- (key: TColumnKey) => !alwaysVisibleSet.has(key),- [alwaysVisibleSet],- );-- const showAllColumns = useCallback(() => {- const cfg = configRef.current;- cfg.onChangeActiveColumnKeys(cfg.columns.map((c) => c.key));- }, []);-- const resetToDefault = useCallback(() => {- const cfg = configRef.current;- if (cfg.defaultColumnKeys) {- cfg.onChangeActiveColumnKeys([...cfg.defaultColumnKeys]);- } else {- cfg.onChangeActiveColumnKeys(cfg.columns.map((c) => c.key));- }- }, []);-- // --- Column filtering helper ----- const activeColumns = useCallback(- (allColumns: XDSTableColumn<T>[]): XDSTableColumn<T>[] => {- const columnMap = new Map(allColumns.map((c) => [c.key, c]));- return activeColumnKeys- .map((key) => columnMap.get(key))- .filter((c): c is XDSTableColumn<T> => c != null);- },- [activeColumnKeys],- );-- // --- Column options for XDSMultiSelector ----- const columnOptions = useMemo((): XDSMultiSelectorOptionType[] => {- const hasGroups = columns.some((c) => c.group);-- if (!hasGroups) {- return columns.map((col) => ({- value: col.key,- label: col.label,- disabled: col.isAlwaysVisible === true,- }));- }-- // Build grouped sections- const groups = new Map<- string,- XDSColumnSettingsOption<TColumnKey>[]- >();- const ungrouped: XDSColumnSettingsOption<TColumnKey>[] = [];-- for (const col of columns) {- if (col.group) {- const group = groups.get(col.group) ?? [];- group.push(col);- groups.set(col.group, group);- } else {- ungrouped.push(col);- }- }-- const items: XDSMultiSelectorOptionType[] = [];-- for (const [groupName, groupCols] of groups) {- items.push({- type: 'section' as const,- title: groupName,- options: groupCols.map((col) => ({- value: col.key,- label: col.label,- disabled: col.isAlwaysVisible === true,- })),- });- }-- for (const col of ungrouped) {- items.push({- value: col.key,- label: col.label,- disabled: col.isAlwaysVisible === true,- });- }-- return items;- }, [columns]);-- // --- Set active column keys ----- const setActiveColumnKeys = useCallback(- (value: string[]) => {- const cfg = configRef.current;- const avSet = new Set(- cfg.columns.filter((c) => c.isAlwaysVisible).map((c) => c.key),- );- // Ensure always-visible columns remain in the set- const valueSet = new Set(value);- for (const key of avSet) {- valueSet.add(key);- }- cfg.onChangeActiveColumnKeys(- Array.from(valueSet) as unknown as TColumnKey[],- );- },- [],- );-- // --- Plugin (uses transformColumns to filter/reorder) ----- const plugin = useMemo(+ return useMemo((): TablePlugin<T> => ({transformColumns(columns: XDSTableColumn<T>[]): XDSTableColumn<T>[] {const cfg = configRef.current;@@ -411,7 +112,7 @@ export function useXDSTableColumnSettings<cfg.activeColumnKeys.map((key, index) => [key, index]),);return columns- .filter((col) => activeSet.has(col.key as TColumnKey))+ .filter(col => activeSet.has(col.key as TColumnKey)).sort((a, b) => {const orderA = orderMap.get(a.key as TColumnKey) ?? Infinity;const orderB = orderMap.get(b.key as TColumnKey) ?? Infinity;@@ -421,17 +122,4 @@ export function useXDSTableColumnSettings<}),[],);-- return {- plugin,- activeColumns,- toggleColumn,- isColumnActive,- isColumnToggleable,- showAllColumns,- resetToDefault,- columnOptions,- setActiveColumnKeys,- activeColumnKeys,- };}diff --git a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.test.tsx b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.test.tsxnew file mode 100644index 0000000000..ec4b9bbea9--- /dev/null+++ b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.test.tsx@@ -0,0 +1,294 @@+/**+ * @file useXDSTableColumnSettingsState.test.tsx+ * @input useXDSTableColumnSettingsState, React testing utilities+ * @output Functional tests for the column settings state hook+ * @position Test file; validates state operations independent of the plugin+ */++import {describe, it, expect, vi} from 'vitest';+import {renderHook, act} from '@testing-library/react';+import {+ useXDSTableColumnSettingsState,+ type UseXDSTableColumnSettingsStateConfig,+} from './useXDSTableColumnSettingsState';+import type {XDSColumnSettingsOption} from './useXDSTableColumnSettings';++// =============================================================================+// Test Data+// =============================================================================++const columnOptions: XDSColumnSettingsOption[] = [+ {key: 'name', label: 'Name', isAlwaysVisible: true},+ {key: 'email', label: 'Email'},+ {key: 'role', label: 'Role'},+ {key: 'status', label: 'Status'},+ {key: 'lastLogin', label: 'Last Login'},+];++// =============================================================================+// Helpers+// =============================================================================++function renderStateHook(+ overrides: Partial<UseXDSTableColumnSettingsStateConfig> = {},+) {+ const defaultConfig: UseXDSTableColumnSettingsStateConfig = {+ columns: columnOptions,+ activeColumnKeys: ['name', 'email', 'role'],+ onChangeActiveColumnKeys: vi.fn(),+ ...overrides,+ };++ return renderHook(() => useXDSTableColumnSettingsState(defaultConfig));+}++// =============================================================================+// Tests+// =============================================================================++describe('useXDSTableColumnSettingsState', () => {+ // ===========================================================================+ // Return value shape+ // ===========================================================================++ describe('return value', () => {+ it('returns columnSettingsConfig that matches input config', () => {+ const config: UseXDSTableColumnSettingsStateConfig = {+ columns: columnOptions,+ activeColumnKeys: ['name', 'email'],+ onChangeActiveColumnKeys: vi.fn(),+ };+ const {result} = renderHook(() => useXDSTableColumnSettingsState(config));+ expect(result.current.columnSettingsConfig).toBe(config);+ });++ it('returns activeColumnKeys passthrough', () => {+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email'],+ });+ expect(result.current.activeColumnKeys).toEqual(['name', 'email']);+ });++ it('returns all operation functions', () => {+ const {result} = renderStateHook();+ expect(result.current.toggleColumn).toBeInstanceOf(Function);+ expect(result.current.isColumnActive).toBeInstanceOf(Function);+ expect(result.current.isColumnToggleable).toBeInstanceOf(Function);+ expect(result.current.showAllColumns).toBeInstanceOf(Function);+ expect(result.current.resetToDefault).toBeInstanceOf(Function);+ expect(result.current.setActiveColumnKeys).toBeInstanceOf(Function);+ });+ });++ // ===========================================================================+ // toggleColumn+ // ===========================================================================++ describe('toggleColumn', () => {+ it('removes active column', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email', 'role'],+ onChangeActiveColumnKeys: onChange,+ });++ act(() => result.current.toggleColumn('email'));+ expect(onChange).toHaveBeenCalledWith(['name', 'role']);+ });++ it('adds inactive column at end', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email'],+ onChangeActiveColumnKeys: onChange,+ });++ act(() => result.current.toggleColumn('status'));+ expect(onChange).toHaveBeenCalledWith(['name', 'email', 'status']);+ });++ it('no-op for isAlwaysVisible columns', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email'],+ onChangeActiveColumnKeys: onChange,+ });++ act(() => result.current.toggleColumn('name'));+ expect(onChange).not.toHaveBeenCalled();+ });+ });++ // ===========================================================================+ // isColumnActive+ // ===========================================================================++ describe('isColumnActive', () => {+ it('returns true for active columns', () => {+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email'],+ });+ expect(result.current.isColumnActive('name')).toBe(true);+ expect(result.current.isColumnActive('email')).toBe(true);+ });++ it('returns false for inactive columns', () => {+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email'],+ });+ expect(result.current.isColumnActive('role')).toBe(false);+ expect(result.current.isColumnActive('status')).toBe(false);+ });+ });++ // ===========================================================================+ // isColumnToggleable+ // ===========================================================================++ describe('isColumnToggleable', () => {+ it('returns true for normal columns', () => {+ const {result} = renderStateHook();+ expect(result.current.isColumnToggleable('email')).toBe(true);+ expect(result.current.isColumnToggleable('role')).toBe(true);+ });++ it('returns false for always-visible columns', () => {+ const {result} = renderStateHook();+ expect(result.current.isColumnToggleable('name')).toBe(false);+ });+ });++ // ===========================================================================+ // showAllColumns+ // ===========================================================================++ describe('showAllColumns', () => {+ it('sets all column keys as active in columns config order', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ activeColumnKeys: ['name'],+ onChangeActiveColumnKeys: onChange,+ });++ act(() => result.current.showAllColumns());+ expect(onChange).toHaveBeenCalledWith([+ 'name',+ 'email',+ 'role',+ 'status',+ 'lastLogin',+ ]);+ });+ });++ // ===========================================================================+ // resetToDefault+ // ===========================================================================++ describe('resetToDefault', () => {+ it('resets to defaultColumnKeys when provided', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ activeColumnKeys: ['name', 'email', 'role', 'status', 'lastLogin'],+ onChangeActiveColumnKeys: onChange,+ defaultColumnKeys: ['name', 'email'],+ });++ act(() => result.current.resetToDefault());+ expect(onChange).toHaveBeenCalledWith(['name', 'email']);+ });++ it('shows all columns when no defaultColumnKeys', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ activeColumnKeys: ['name'],+ onChangeActiveColumnKeys: onChange,+ });++ act(() => result.current.resetToDefault());+ expect(onChange).toHaveBeenCalledWith([+ 'name',+ 'email',+ 'role',+ 'status',+ 'lastLogin',+ ]);+ });+ });++ // ===========================================================================+ // setActiveColumnKeys+ // ===========================================================================++ describe('setActiveColumnKeys', () => {+ it('passes selected values to onChangeActiveColumnKeys', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ onChangeActiveColumnKeys: onChange,+ });++ act(() =>+ result.current.setActiveColumnKeys(['name', 'email', 'status']),+ );+ expect(onChange).toHaveBeenCalledWith(+ expect.arrayContaining(['name', 'email', 'status']),+ );+ });++ it('enforces isAlwaysVisible columns remain in set', () => {+ const onChange = vi.fn();+ const {result} = renderStateHook({+ onChangeActiveColumnKeys: onChange,+ });++ // Try to deselect 'name' (isAlwaysVisible) by not including it+ act(() => result.current.setActiveColumnKeys(['email']));+ const calledWith = onChange.mock.calls[0][0] as string[];+ expect(calledWith).toContain('name');+ expect(calledWith).toContain('email');+ });+ });++ // ===========================================================================+ // Edge Cases+ // ===========================================================================++ describe('edge cases', () => {+ it('handles empty columns config', () => {+ const {result} = renderStateHook({+ columns: [],+ activeColumnKeys: [],+ });++ expect(result.current.activeColumnKeys).toEqual([]);+ });++ it('handles single column with isAlwaysVisible', () => {+ const {result} = renderStateHook({+ columns: [{key: 'name', label: 'Name', isAlwaysVisible: true}],+ activeColumnKeys: ['name'],+ });++ expect(result.current.isColumnToggleable('name')).toBe(false);+ expect(result.current.isColumnActive('name')).toBe(true);+ });++ it('handles all columns isAlwaysVisible', () => {+ const allVisible: XDSColumnSettingsOption[] = [+ {key: 'name', label: 'Name', isAlwaysVisible: true},+ {key: 'email', label: 'Email', isAlwaysVisible: true},+ ];++ const onChange = vi.fn();+ const {result} = renderStateHook({+ columns: allVisible,+ activeColumnKeys: ['name', 'email'],+ onChangeActiveColumnKeys: onChange,+ });++ act(() => result.current.toggleColumn('name'));+ act(() => result.current.toggleColumn('email'));+ expect(onChange).not.toHaveBeenCalled();+ });+ });+});diff --git a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsx b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsxnew file mode 100644index 0000000000..993dc8d137--- /dev/null+++ b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsx@@ -0,0 +1,280 @@+'use client';++/**+ * @file useXDSTableColumnSettingsState.tsx+ * @input React, column settings types+ * @output Exports useXDSTableColumnSettingsState hook and config/return types+ * @position Column settings state helper; manages column visibility and ordering.+ * Pairs with useXDSTableColumnSettings (plugin hook).+ *+ * Follows the same pattern as useXDSTableSelectionState: the state hook+ * manages operations and produces a config object that feeds directly+ * into the plugin hook. Renderer-agnostic — works with any column+ * picker UI (MultiSelector, drag-and-drop, checkbox list, etc.).+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Table/plugins/columnSettings/index.ts (exports)+ * - /packages/core/src/Table/index.ts (exports)+ */++import {useCallback, useMemo, useRef} from 'react';+import type {XDSColumnSettingsOption} from './useXDSTableColumnSettings';++// =============================================================================+// Config Type+// =============================================================================++/**+ * Configuration for useXDSTableColumnSettingsState.+ *+ * The consumer owns the active keys state. This hook provides column+ * visibility operations (toggle, show all, reset) and a config object+ * that feeds directly into `useXDSTableColumnSettings`.+ *+ * @template TColumnKey - String literal union of column keys+ *+ * @example+ * ```+ * const [activeKeys, setActiveKeys] = useState(['name', 'email', 'role']);+ *+ * const columnState = useXDSTableColumnSettingsState({+ * columns: [+ * { key: 'name', label: 'Name', isAlwaysVisible: true },+ * { key: 'email', label: 'Email' },+ * { key: 'role', label: 'Role' },+ * { key: 'status', label: 'Status' },+ * ],+ * activeColumnKeys: activeKeys,+ * onChangeActiveColumnKeys: setActiveKeys,+ * });+ *+ * const plugin = useXDSTableColumnSettings(columnState.columnSettingsConfig);+ *+ * <XDSTable+ * data={data}+ * columns={allColumns}+ * plugins={{ columnSettings: plugin }}+ * />+ * ```+ */+export interface UseXDSTableColumnSettingsStateConfig<+ TColumnKey extends string = string,+> {+ /**+ * All available columns with metadata for the settings UI.+ * This defines the universe of columns the user can toggle.+ */+ columns: ReadonlyArray<XDSColumnSettingsOption<TColumnKey>>;++ /**+ * Currently active column keys, in display order.+ * Only columns with keys in this array are shown in the table.+ * The array order determines column display order.+ */+ activeColumnKeys: ReadonlyArray<TColumnKey>;++ /**+ * Called when active columns change (toggle, reorder).+ * Consumer updates their own state.+ */+ onChangeActiveColumnKeys: (keys: ReadonlyArray<TColumnKey>) => void;++ /**+ * The default column set for "Reset to default" functionality.+ * When omitted, resetToDefault shows all columns.+ */+ defaultColumnKeys?: ReadonlyArray<TColumnKey>;+}++// =============================================================================+// Return Type+// =============================================================================++/**+ * Return value of useXDSTableColumnSettingsState.+ */+export interface UseXDSTableColumnSettingsStateReturn<+ TColumnKey extends string = string,+> {+ /**+ * Ready-to-use config for useXDSTableColumnSettings.+ * Pass this directly to the plugin hook.+ *+ * @example+ * ```+ * const state = useXDSTableColumnSettingsState({ ... });+ * const plugin = useXDSTableColumnSettings(state.columnSettingsConfig);+ * ```+ */+ columnSettingsConfig: UseXDSTableColumnSettingsStateConfig<TColumnKey>;++ /** Currently active column keys (pass-through from config). */+ activeColumnKeys: ReadonlyArray<TColumnKey>;++ /**+ * Toggle a column's visibility.+ * If the column is active, removes it. If inactive, adds it to the end.+ * No-op for columns with `isAlwaysVisible: true`.+ */+ toggleColumn: (key: TColumnKey) => void;++ /**+ * Whether a specific column is currently active (visible).+ */+ isColumnActive: (key: TColumnKey) => boolean;++ /**+ * Whether a specific column can be toggled.+ * Returns false for columns with `isAlwaysVisible: true`.+ */+ isColumnToggleable: (key: TColumnKey) => boolean;++ /**+ * Show all columns.+ */+ showAllColumns: () => void;++ /**+ * Reset to the default column set.+ * Uses `defaultColumnKeys` if provided, otherwise shows all columns.+ */+ resetToDefault: () => void;++ /**+ * Set active column keys from a list of key strings.+ * Enforces that `isAlwaysVisible` columns remain in the active set.+ * Useful as an `onChange` handler for any list-based column picker.+ */+ setActiveColumnKeys: (keys: string[]) => void;+}++// =============================================================================+// Hook+// =============================================================================++/**+ * Headless column visibility and ordering state management.+ *+ * Manages which columns are active, provides toggle/reset operations,+ * and produces a config object for `useXDSTableColumnSettings`.+ * Renderer-agnostic — pair with any column picker UI.+ *+ * @example+ * ```+ * const [activeKeys, setActiveKeys] = useState(['name', 'email']);+ *+ * const state = useXDSTableColumnSettingsState({+ * columns: [+ * { key: 'name', label: 'Name', isAlwaysVisible: true },+ * { key: 'email', label: 'Email' },+ * { key: 'role', label: 'Role' },+ * ],+ * activeColumnKeys: activeKeys,+ * onChangeActiveColumnKeys: setActiveKeys,+ * });+ *+ * // Feed into the plugin hook+ * const plugin = useXDSTableColumnSettings(state.columnSettingsConfig);+ *+ * // Build your own column picker UI using state helpers+ * state.columns.map(col => (+ * <Checkbox+ * key={col.key}+ * checked={state.isColumnActive(col.key)}+ * disabled={!state.isColumnToggleable(col.key)}+ * onChange={() => state.toggleColumn(col.key)}+ * label={col.label}+ * />+ * ));+ * ```+ */+export function useXDSTableColumnSettingsState<+ TColumnKey extends string = string,+>(+ config: UseXDSTableColumnSettingsStateConfig<TColumnKey>,+): UseXDSTableColumnSettingsStateReturn<TColumnKey> {+ const {columns, activeColumnKeys} = config;++ // Keep config in a ref so callbacks always read the latest version.+ const configRef = useRef(config);+ configRef.current = config;++ // Build lookup sets for fast checks+ const activeSet = useMemo(+ () => new Set(activeColumnKeys),+ [activeColumnKeys],+ );++ const alwaysVisibleSet = useMemo(+ () => new Set(columns.filter(c => c.isAlwaysVisible).map(c => c.key)),+ [columns],+ );++ // --- Column operations ---++ const toggleColumn = useCallback((key: TColumnKey) => {+ const cfg = configRef.current;+ const avSet = new Set(+ cfg.columns.filter(c => c.isAlwaysVisible).map(c => c.key),+ );+ if (avSet.has(key)) return;++ const currentKeys = cfg.activeColumnKeys;+ const currentSet = new Set(currentKeys);+ if (currentSet.has(key)) {+ cfg.onChangeActiveColumnKeys(currentKeys.filter(k => k !== key));+ } else {+ cfg.onChangeActiveColumnKeys([...currentKeys, key]);+ }+ }, []);++ const isColumnActive = useCallback(+ (key: TColumnKey) => activeSet.has(key),+ [activeSet],+ );++ const isColumnToggleable = useCallback(+ (key: TColumnKey) => !alwaysVisibleSet.has(key),+ [alwaysVisibleSet],+ );++ const showAllColumns = useCallback(() => {+ const cfg = configRef.current;+ cfg.onChangeActiveColumnKeys(cfg.columns.map(c => c.key));+ }, []);++ const resetToDefault = useCallback(() => {+ const cfg = configRef.current;+ if (cfg.defaultColumnKeys) {+ cfg.onChangeActiveColumnKeys([...cfg.defaultColumnKeys]);+ } else {+ cfg.onChangeActiveColumnKeys(cfg.columns.map(c => c.key));+ }+ }, []);++ const setActiveColumnKeys = useCallback((value: string[]) => {+ const cfg = configRef.current;+ const avSet = new Set(+ cfg.columns.filter(c => c.isAlwaysVisible).map(c => c.key),+ );+ // Ensure always-visible columns remain in the set+ const valueSet = new Set(value);+ for (const key of avSet) {+ valueSet.add(key);+ }+ cfg.onChangeActiveColumnKeys(+ Array.from(valueSet) as unknown as TColumnKey[],+ );+ }, []);++ return {+ columnSettingsConfig: config,+ activeColumnKeys,+ toggleColumn,+ isColumnActive,+ isColumnToggleable,+ showAllColumns,+ resetToDefault,+ setActiveColumnKeys,+ };+}