Skip to content

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.tsx
index 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 = {
<XDSMultiSelector
label="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 = {
<XDSMultiSelector
label="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 = {
<XDSButton
label="Reset to default"
variant="secondary"
- onClick={columnSettings.resetToDefault}
+ onClick={state.resetToDefault}
/>
<XDSMultiSelector
label="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 = {
<XDSMultiSelector
label="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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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,
+ };
+}