Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Table): useXDSTableFiltering plugin #978 (#1020)

Cindy Zhangb3b3d97ee70e
diff --git a/apps/storybook/stories/TableFiltering.stories.tsx b/apps/storybook/stories/TableFiltering.stories.tsx
new file mode 100644
index 0000000000..8f07627f5e
--- /dev/null
+++ b/apps/storybook/stories/TableFiltering.stories.tsx
@@ -0,0 +1,491 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSTable,
+ useXDSTableFiltering,
+ useXDSTableSelection,
+ useXDSTableSelectionState,
+ useXDSTableSortable,
+ useXDSTableColumnResize,
+ toSearchFilters,
+} from '@xds/core/Table';
+import type {
+ XDSTableColumn,
+ XDSTableFilterState,
+ XDSTableFilterValue,
+ XDSTableSortState,
+} from '@xds/core/Table';
+import {usePowerSearchConfig} from '@xds/core/PowerSearch';
+import type {PowerSearchFilter} from '@xds/core/PowerSearch';
+
+interface Employee extends Record<string, unknown> {
+ id: string;
+ name: string;
+ email: string;
+ role: string;
+ department: string;
+ level: number;
+}
+
+const employees: Employee[] = [
+ {
+ id: '1',
+ name: 'Alice',
+ email: '[email protected]',
+ role: 'Engineer',
+ department: 'Platform',
+ level: 5,
+ },
+ {
+ id: '2',
+ name: 'Bob',
+ email: '[email protected]',
+ role: 'Designer',
+ department: 'Product',
+ level: 4,
+ },
+ {
+ id: '3',
+ name: 'Charlie',
+ email: '[email protected]',
+ role: 'Manager',
+ department: 'Platform',
+ level: 6,
+ },
+ {
+ id: '4',
+ name: 'Diana',
+ email: '[email protected]',
+ role: 'Engineer',
+ department: 'Infrastructure',
+ level: 5,
+ },
+ {
+ id: '5',
+ name: 'Eve',
+ email: '[email protected]',
+ role: 'Admin',
+ department: 'Operations',
+ level: 3,
+ },
+];
+
+const fieldDefs = [
+ {key: 'name', type: 'string', label: 'Name'},
+ {key: 'email', type: 'string', label: 'Email'},
+ {
+ key: 'role',
+ type: 'enum',
+ label: 'Role',
+ enumValues: [
+ {value: 'Engineer', label: 'Engineer'},
+ {value: 'Designer', label: 'Designer'},
+ {value: 'Manager', label: 'Manager'},
+ {value: 'Admin', label: 'Admin'},
+ ],
+ },
+ {
+ key: 'department',
+ type: 'enum_list',
+ label: 'Department',
+ enumValues: [
+ {value: 'Platform', label: 'Platform'},
+ {value: 'Product', label: 'Product'},
+ {value: 'Infrastructure', label: 'Infrastructure'},
+ {value: 'Operations', label: 'Operations'},
+ ],
+ },
+ {key: 'level', type: 'number', label: 'Level'},
+] as const;
+
+function useFilterState() {
+ const [filters, setFilters] = useState<XDSTableFilterState>({});
+ const onFilterChange = (key: string, value: XDSTableFilterValue | null) => {
+ setFilters(prev => {
+ const next = {...prev};
+ if (value == null) delete next[key];
+ else next[key] = value;
+ return next;
+ });
+ };
+ return {filters, onFilterChange};
+}
+
+const meta: Meta = {
+ title: 'Core/XDSTable/Filtering',
+ tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const TextFilter: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name', filter: 'name'},
+ {key: 'email', header: 'Email', filter: 'email'},
+ {key: 'role', header: 'Role'},
+ {key: 'department', header: 'Department'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Showing {data.length}/{employees.length} rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const SelectorFilter: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'role', header: 'Role', filter: 'role'},
+ {key: 'department', header: 'Department'},
+ {key: 'level', header: 'Level'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Enum → selector. Showing {data.length}/{employees.length} rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const MultiSelectorFilter: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'role', header: 'Role'},
+ {key: 'department', header: 'Department', filter: 'department'},
+ {key: 'level', header: 'Level'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Enum list → multi-selector. Showing {data.length}/{employees.length}{' '}
+ rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const NumberFilter: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'role', header: 'Role'},
+ {key: 'level', header: 'Level', filter: 'level'},
+ {key: 'department', header: 'Department'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Number field → numeric input. Showing {data.length}/{employees.length}{' '}
+ rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const InlineVariant: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name', filter: 'name'},
+ {key: 'role', header: 'Role', filter: 'role'},
+ {key: 'level', header: 'Level', filter: 'level'},
+ {key: 'department', header: 'Department'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ variant: 'inline',
+ searchConfig: config,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Inline variant. Showing {data.length}/{employees.length} rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const WithSelection: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const [selectedKeys, setSelectedKeys] = useState(new Set<string>());
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name', filter: 'name'},
+ {key: 'role', header: 'Role', filter: 'role'},
+ {key: 'department', header: 'Department', filter: 'department'},
+ {key: 'level', header: 'Level'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const {selectionConfig} = useXDSTableSelectionState({
+ data: employees,
+ idKey: 'id',
+ selectedKeys,
+ setSelectedKeys,
+ });
+ const selectionPlugin = useXDSTableSelection<Employee>(selectionConfig);
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Filtering + Selection. Selected: {selectedKeys.size} | Showing{' '}
+ {data.length}/{employees.length} rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{selection: selectionPlugin, filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const WithSorting: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const [sort, setSort] = useState<XDSTableSortState>([]);
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name', sortable: true, filter: 'name'},
+ {key: 'role', header: 'Role', sortable: true, filter: 'role'},
+ {key: 'level', header: 'Level', sortable: true, filter: 'level'},
+ {key: 'department', header: 'Department'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const sortPlugin = useXDSTableSortable<Employee>({
+ sort,
+ onSortChange: setSort,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Filtering + Sorting. Showing {data.length}/{employees.length} rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{sort: sortPlugin, filter: filterPlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const WithResize: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const [columnWidths, setColumnWidths] = useState<Record<string, number>>(
+ {},
+ );
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name', filter: 'name'},
+ {key: 'role', header: 'Role', filter: 'role'},
+ {key: 'level', header: 'Level', filter: 'level'},
+ {key: 'department', header: 'Department'},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ variant: 'inline',
+ searchConfig: config,
+ });
+ const resizePlugin = useXDSTableColumnResize<Employee>({
+ columnWidths,
+ onColumnResizeEnd: updates =>
+ setColumnWidths(prev => ({...prev, ...updates})),
+ columns,
+ });
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 800}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ Inline filtering + Resize. Showing {data.length}/{employees.length}{' '}
+ rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin, resize: resizePlugin}}
+ />
+ </div>
+ );
+ },
+};
+
+export const WithAllPlugins: Story = {
+ render: () => {
+ const {config, applyFilters} = usePowerSearchConfig(fieldDefs);
+ const {filters, onFilterChange} = useFilterState();
+ const [sort, setSort] = useState<XDSTableSortState>([]);
+ const [columnWidths, setColumnWidths] = useState<Record<string, number>>(
+ {},
+ );
+ const [selectedKeys, setSelectedKeys] = useState(new Set<string>());
+ const columns: XDSTableColumn<Employee>[] = [
+ {key: 'name', header: 'Name', sortable: true, filter: 'name'},
+ {key: 'role', header: 'Role', sortable: true, filter: 'role'},
+ {key: 'level', header: 'Level', sortable: true, filter: 'level'},
+ {key: 'department', header: 'Department', sortable: true},
+ ];
+ const filterPlugin = useXDSTableFiltering<Employee>({
+ filters,
+ onFilterChange,
+ searchConfig: config,
+ });
+ const sortPlugin = useXDSTableSortable<Employee>({
+ sort,
+ onSortChange: setSort,
+ });
+ const resizePlugin = useXDSTableColumnResize<Employee>({
+ columnWidths,
+ onColumnResizeEnd: updates =>
+ setColumnWidths(prev => ({...prev, ...updates})),
+ columns,
+ });
+ const {selectionConfig} = useXDSTableSelectionState({
+ data: employees,
+ idKey: 'id',
+ selectedKeys,
+ setSelectedKeys,
+ });
+ const selectionPlugin = useXDSTableSelection<Employee>(selectionConfig);
+ const data = applyFilters(
+ toSearchFilters(filters, columns, config) as PowerSearchFilter[],
+ employees,
+ );
+ return (
+ <div style={{maxWidth: 900}}>
+ <p style={{marginBottom: 8, fontSize: 14, color: '#666'}}>
+ All plugins. Selected: {selectedKeys.size} | Showing {data.length}/
+ {employees.length} rows.
+ </p>
+ <XDSTable
+ data={data}
+ columns={columns}
+ idKey="id"
+ plugins={{
+ selection: selectionPlugin,
+ sort: sortPlugin,
+ filter: filterPlugin,
+ resize: resizePlugin,
+ }}
+ />
+ </div>
+ );
+ },
+};
diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsx
index 84defc2d9b..4cd710bf69 100644
--- a/packages/core/src/Table/XDSBaseTable.tsx
+++ b/packages/core/src/Table/XDSBaseTable.tsx
@@ -12,6 +12,7 @@
import {memo, useRef, type ReactElement, type ReactNode, type Ref} from 'react';
import * as stylex from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
import type {
XDSBaseTableProps,
XDSTableColumn,
@@ -42,6 +43,17 @@ const styles = stylex.create({
borderSpacing: '0',
tableLayout: 'fixed',
},
+ /**
+ * Inline flex row that keeps the header label and any "after" slot content
+ * (sort icons, filter buttons, etc.) on the same line with a small gap.
+ * Applied only when `after` is present so plain cells are unaffected.
+ */
+ headerLabelRow: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-0-5'],
+ minWidth: 0,
+ },
});
/**
@@ -308,8 +320,9 @@ function XDSBaseTableInner<T extends Record<string, unknown>>({
typeof resolvedContent === 'string' && resolvedContent.length > 0
? {title: resolvedContent}
: {};
- const {before, after, overlay} = cellRenderProps;
- const hasSlots = before != null || after != null || overlay != null;
+ const {before, after, overlay, below} = cellRenderProps;
+ const hasSlots =
+ before != null || after != null || overlay != null || below != null;
return (
<HeaderCellComponent
@@ -320,9 +333,16 @@ function XDSBaseTableInner<T extends Record<string, unknown>>({
{hasSlots ? (
<>
{before}
- {resolvedContent}
- {after}
+ {after != null ? (
+ <div {...stylex.props(styles.headerLabelRow)}>
+ {resolvedContent}
+ {after}
+ </div>
+ ) : (
+ resolvedContent
+ )}
{overlay}
+ {below}
</>
) : (
resolvedContent
diff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.ts
index 95cc9685b9..01ea0a96ec 100644
--- a/packages/core/src/Table/index.ts
+++ b/packages/core/src/Table/index.ts
@@ -21,6 +21,7 @@ export {useXDSTableSortable} from './plugins/sortable';
export {useXDSTablePagination} from './plugins/pagination';
export {useXDSTableColumnSettings} from './plugins/columnSettings';
export {useXDSTableColumnResize} from './plugins/columnResize';
+export {useXDSTableFiltering, toSearchFilters} from './plugins/filtering';
export {useXDSBaseTablePlugins} from './useXDSBaseTablePlugins';
export {
proportional,
@@ -76,3 +77,10 @@ export type {
XDSColumnSettingsOption,
} from './plugins/columnSettings';
export type {UseXDSTableColumnResizeConfig} from './plugins/columnResize';
+export type {
+ UseXDSTableFilteringConfig,
+ XDSTableFilterState,
+ XDSTableFilterVariant,
+ XDSTableFilterValue,
+ XDSTableFilterFieldRef,
+} from './plugins/filtering';
diff --git a/packages/core/src/Table/plugins/filtering/index.ts b/packages/core/src/Table/plugins/filtering/index.ts
new file mode 100644
index 0000000000..45c7a7f2ef
--- /dev/null
+++ b/packages/core/src/Table/plugins/filtering/index.ts
@@ -0,0 +1,8 @@
+export {useXDSTableFiltering, toSearchFilters} from './useXDSTableFiltering';
+export type {
+ UseXDSTableFilteringConfig,
+ XDSTableFilterState,
+ XDSTableFilterVariant,
+ XDSTableFilterValue,
+ XDSTableFilterFieldRef,
+} from './useXDSTableFiltering';
diff --git a/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.test.tsx b/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.test.tsx
new file mode 100644
index 0000000000..dec4577bbf
--- /dev/null
+++ b/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.test.tsx
@@ -0,0 +1,319 @@
+/**
+ * @file useXDSTableFiltering.test.tsx
+ * @input useXDSTableFiltering, XDSTable, React testing utilities
+ * @output Functional tests for the filtering plugin
+ * @position Test file; validates filter rendering, interaction, and accessibility
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {useState} from 'react';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSTable} from '../../XDSTable';
+import {useXDSTableFiltering, toSearchFilters} from './useXDSTableFiltering';
+import type {
+ XDSTableFilterState,
+ XDSTableFilterVariant,
+ XDSTableFilterValue,
+} from './useXDSTableFiltering';
+import type {PowerSearchConfig} from '../../../PowerSearch/types';
+import type {XDSTableColumn} from '../../types';
+
+// =============================================================================
+// Test Data
+// =============================================================================
+
+interface TestRow extends Record<string, unknown> {
+ id: string;
+ name: string;
+ status: string;
+ age: number;
+ tags: string;
+}
+
+const testData: TestRow[] = [
+ {id: '1', name: 'Alice', status: 'active', age: 30, tags: 'admin'},
+ {id: '2', name: 'Bob', status: 'inactive', age: 25, tags: 'user'},
+ {id: '3', name: 'Charlie', status: 'active', age: 35, tags: 'user'},
+];
+
+// =============================================================================
+// Shared PowerSearch Config
+// =============================================================================
+
+const statusOptions = [
+ {value: 'active', label: 'Active'},
+ {value: 'inactive', label: 'Inactive'},
+];
+
+const tagOptions = [
+ {value: 'admin', label: 'Admin'},
+ {value: 'user', label: 'User'},
+];
+
+const searchConfig: PowerSearchConfig = {
+ name: 'test',
+ fields: [
+ {
+ key: 'name',
+ label: 'Name',
+ defaultOperator: 'contains',
+ operators: [
+ {key: 'contains', label: 'contains', value: {type: 'string'}},
+ ],
+ },
+ {
+ key: 'status',
+ label: 'Status',
+ defaultOperator: 'is',
+ operators: [
+ {key: 'is', label: 'is', value: {type: 'enum', values: statusOptions}},
+ ],
+ },
+ {
+ key: 'age',
+ label: 'Age',
+ defaultOperator: 'equals',
+ operators: [
+ {
+ key: 'equals',
+ label: 'equals',
+ value: {type: 'integer', minValue: 0, maxValue: 120},
+ },
+ ],
+ },
+ {
+ key: 'tags',
+ label: 'Tags',
+ defaultOperator: 'includes',
+ operators: [
+ {
+ key: 'includes',
+ label: 'includes',
+ value: {type: 'enum_list', values: tagOptions},
+ },
+ ],
+ },
+ ],
+};
+
+// =============================================================================
+// Test Columns
+// =============================================================================
+
+const defaultColumns: XDSTableColumn<TestRow>[] = [
+ {key: 'name', header: 'Name', filter: 'name'},
+ {key: 'status', header: 'Status', filter: 'status'},
+ {key: 'age', header: 'Age', filter: 'age'},
+];
+
+const allFilterColumns: XDSTableColumn<TestRow>[] = [
+ {key: 'name', header: 'Name', filter: 'name'},
+ {key: 'status', header: 'Status', filter: 'status'},
+ {key: 'age', header: 'Age', filter: 'age'},
+ {key: 'tags', header: 'Tags', filter: 'tags'},
+];
+
+// =============================================================================
+// Test Helper Component
+// =============================================================================
+
+function FilterTable({
+ columns = defaultColumns,
+ variant = 'popover' as XDSTableFilterVariant,
+}) {
+ const [filters, setFilters] = useState<XDSTableFilterState>({});
+
+ const filterPlugin = useXDSTableFiltering<TestRow>({
+ filters,
+ onFilterChange: (key: string, value: XDSTableFilterValue | null) => {
+ setFilters(prev => {
+ const next = {...prev};
+ if (value == null) {
+ delete next[key];
+ } else {
+ next[key] = value;
+ }
+ return next;
+ });
+ },
+ variant,
+ searchConfig,
+ });
+
+ return (
+ <XDSTable
+ data={testData}
+ columns={columns}
+ idKey="id"
+ plugins={{filter: filterPlugin}}
+ />
+ );
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('useXDSTableFiltering', () => {
+ describe('popover variant — rendering', () => {
+ it('renders filter icon for filterable columns', () => {
+ render(<FilterTable />);
+ const filterButtons = screen.getAllByRole('button', {name: /Filter /});
+ expect(filterButtons).toHaveLength(3);
+ });
+
+ it('renders no filter icon for columns without filter config', () => {
+ const noFilterColumns: XDSTableColumn<TestRow>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'status', header: 'Status'},
+ ];
+ render(<FilterTable columns={noFilterColumns} />);
+ expect(screen.queryAllByLabelText(/Filter /)).toHaveLength(0);
+ });
+
+ it('filter trigger button is clickable', async () => {
+ const user = userEvent.setup();
+ render(<FilterTable />);
+ const filterButton = screen.getByRole('button', {name: 'Filter Name'});
+ await user.click(filterButton);
+ // Button exists and is interactive
+ expect(filterButton).toBeInTheDocument();
+ });
+ });
+
+ describe('inline variant — rendering', () => {
+ it('renders inline filter controls', () => {
+ render(<FilterTable variant="inline" />);
+ const textInputs = screen.getAllByRole('textbox');
+ expect(textInputs.length).toBeGreaterThanOrEqual(1);
+ });
+
+ it('renders text input for string field', () => {
+ render(<FilterTable variant="inline" />);
+ const textInputs = screen.getAllByPlaceholderText('Filter...');
+ expect(textInputs.length).toBeGreaterThanOrEqual(1);
+ });
+
+ it('renders number input for integer field', () => {
+ render(<FilterTable variant="inline" />);
+ const numberInputs = screen.getAllByRole('spinbutton');
+ expect(numberInputs.length).toBeGreaterThanOrEqual(1);
+ });
+ });
+
+ describe('inline variant — interaction', () => {
+ it('updates text filter on type', async () => {
+ const user = userEvent.setup();
+ render(<FilterTable variant="inline" />);
+ const textInputs = screen.getAllByPlaceholderText('Filter...');
+ await user.type(textInputs[0], 'Alice');
+ expect(textInputs[0]).toHaveValue('Alice');
+ });
+ });
+
+ describe('field reference forms', () => {
+ it('supports object form { field, operator }', () => {
+ const columns: XDSTableColumn<TestRow>[] = [
+ {
+ key: 'name',
+ header: 'Name',
+ filter: {field: 'name', operator: 'contains'},
+ },
+ ];
+ render(<FilterTable columns={columns} variant="inline" />);
+ const textInputs = screen.getAllByPlaceholderText('Filter...');
+ expect(textInputs.length).toBeGreaterThanOrEqual(1);
+ });
+
+ it('ignores unresolvable field references', () => {
+ const columns: XDSTableColumn<TestRow>[] = [
+ {key: 'name', header: 'Name', filter: 'nonexistent_field'},
+ ];
+ expect(() => render(<FilterTable columns={columns} />)).not.toThrow();
+ });
+ });
+
+ describe('toSearchFilters', () => {
+ it('converts table filter state to PowerSearchFilter[]', () => {
+ const filters: XDSTableFilterState = {name: 'alice', status: 'active'};
+ const result = toSearchFilters(filters, defaultColumns, searchConfig);
+ expect(result).toHaveLength(2);
+ expect(result[0]).toEqual({
+ field: 'name',
+ operator: 'contains',
+ value: {type: 'string', value: 'alice'},
+ });
+ expect(result[1]).toEqual({
+ field: 'status',
+ operator: 'is',
+ value: {type: 'enum', value: 'active'},
+ });
+ });
+
+ it('skips columns with no filter value', () => {
+ const filters: XDSTableFilterState = {name: 'alice'};
+ const result = toSearchFilters(filters, defaultColumns, searchConfig);
+ expect(result).toHaveLength(1);
+ });
+
+ it('skips columns with no filter config', () => {
+ const filters: XDSTableFilterState = {name: 'alice'};
+ const noFilterColumns = [{key: 'name', header: 'Name'}];
+ const result = toSearchFilters(filters, noFilterColumns, searchConfig);
+ expect(result).toHaveLength(0);
+ });
+
+ it('handles integer values', () => {
+ const filters: XDSTableFilterState = {age: 30};
+ const result = toSearchFilters(filters, defaultColumns, searchConfig);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toEqual({
+ field: 'age',
+ operator: 'equals',
+ value: {type: 'integer', value: 30},
+ });
+ });
+
+ it('handles enum_list values', () => {
+ const filters: XDSTableFilterState = {tags: ['admin', 'user']};
+ const result = toSearchFilters(filters, allFilterColumns, searchConfig);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toEqual({
+ field: 'tags',
+ operator: 'includes',
+ value: {type: 'enum_list', value: ['admin', 'user']},
+ });
+ });
+ });
+
+ describe('plugin stability', () => {
+ it('returns a referentially stable plugin object', () => {
+ const plugins: ReturnType<typeof useXDSTableFiltering>[] = [];
+
+ function Capture() {
+ const plugin = useXDSTableFiltering({
+ filters: {},
+ onFilterChange: () => {},
+ searchConfig,
+ });
+ plugins.push(plugin);
+ return null;
+ }
+
+ const {rerender} = render(<Capture />);
+ rerender(<Capture />);
+ expect(plugins[0]).toBe(plugins[1]);
+ });
+
+ it('works with no filterable columns', () => {
+ const noFilterColumns: XDSTableColumn<TestRow>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'status', header: 'Status'},
+ ];
+ expect(() =>
+ render(<FilterTable columns={noFilterColumns} />),
+ ).not.toThrow();
+ });
+ });
+});
diff --git a/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx
new file mode 100644
index 0000000000..2645ce6b0b
--- /dev/null
+++ b/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx
@@ -0,0 +1,1319 @@
+'use client';
+
+/**
+ * @file useXDSTableFiltering.tsx
+ * @input React, types, XDS components, theme tokens
+ * @output Exports useXDSTableFiltering hook and filter type definitions
+ * @position Filtering plugin; consumed by XDSTable via plugins prop
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/Table.doc.mjs (filtering documentation)
+ * - /packages/core/src/Table/index.ts (exports)
+ */
+
+import {
+ createContext,
+ useContext,
+ useRef,
+ useMemo,
+ useState,
+ useCallback,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {spacingVars, radiusVars} from '../../../theme/tokens.stylex';
+import {XDSIcon} from '../../../Icon';
+import {XDSButton} from '../../../Button';
+import {XDSPopover} from '../../../Popover';
+import {XDSTextInput} from '../../../TextInput';
+import {XDSNumberInput} from '../../../NumberInput';
+import {XDSDateInput} from '../../../DateInput';
+import type {ISODateString} from '../../../Calendar';
+import {XDSTimeInput} from '../../../TimeInput';
+import type {ISOTimeString} from '../../../utils/timeParser';
+import {XDSSelector} from '../../../Selector';
+import {XDSMultiSelector} from '../../../MultiSelector';
+import {XDSTokenizer} from '../../../Tokenizer';
+import type {
+ TablePlugin,
+ XDSTableColumn,
+ HeaderCellRenderProps,
+} from '../../types';
+import type {
+ PowerSearchConfig,
+ PowerSearchField,
+ PowerSearchOperator,
+ PowerSearchFilter,
+ FilterValue,
+ OperatorValue,
+} from '../../../PowerSearch/types';
+
+// =============================================================================
+// Filter Value Types
+// =============================================================================
+
+/** Text filter: free-form string search */
+export type XDSTableFilterTextValue = string;
+
+/** Number filter: exact numeric match */
+export type XDSTableFilterNumberValue = number;
+
+/** Number range filter: min/max bounds (either or both may be set) */
+export interface XDSTableFilterNumberRangeValue {
+ min?: number;
+ max?: number;
+}
+
+/** Selector filter: single selected value */
+export type XDSTableFilterSelectorValue = string;
+
+/** Multi-selector filter: set of selected values */
+export type XDSTableFilterMultiSelectorValue = string[];
+
+/** Date filter: ISO date string (YYYY-MM-DD) */
+export type XDSTableFilterDateValue = string;
+
+/** Time filter: ISO time string (HH:MM) */
+export type XDSTableFilterTimeValue = string;
+
+/** String list filter: array of free-form string tags */
+export type XDSTableFilterStringListValue = string[];
+
+/** Union of all filter value types */
+export type XDSTableFilterValue =
+ | XDSTableFilterTextValue
+ | XDSTableFilterNumberValue
+ | XDSTableFilterNumberRangeValue
+ | XDSTableFilterSelectorValue
+ | XDSTableFilterMultiSelectorValue
+ | XDSTableFilterDateValue
+ | XDSTableFilterTimeValue
+ | XDSTableFilterStringListValue;
+
+// =============================================================================
+// Filter Type Discriminated Union (per-column config)
+// =============================================================================
+
+/** Option for selector-based filters. */
+export interface XDSTableFilterOption {
+ /** The value stored when this option is selected */
+ value: string;
+ /** Display label. Defaults to `value` if omitted. */
+ label?: string;
+}
+
+/** Text filter — free-form text input. */
+export interface XDSTableFilterTypeText {
+ type: 'text';
+ /** Placeholder text for the input. @default 'Filter...' */
+ placeholder?: string;
+}
+
+/** Number filter — numeric input for exact match. */
+export interface XDSTableFilterTypeNumber {
+ type: 'number';
+ /** Placeholder text. @default 'Filter...' */
+ placeholder?: string;
+ /** Minimum allowed value */
+ min?: number;
+ /** Maximum allowed value */
+ max?: number;
+ /** Step increment. @default 1 */
+ step?: number;
+}
+
+/** Number range filter — two numeric inputs for min/max bounds. */
+export interface XDSTableFilterTypeNumberRange {
+ type: 'number-range';
+ /** Placeholder for min input. @default 'Min' */
+ minPlaceholder?: string;
+ /** Placeholder for max input. @default 'Max' */
+ maxPlaceholder?: string;
+ /** Minimum allowed value */
+ min?: number;
+ /** Maximum allowed value */
+ max?: number;
+ /** Step increment. @default 1 */
+ step?: number;
+}
+
+/** Selector filter — single-select dropdown. */
+export interface XDSTableFilterTypeSelector {
+ type: 'selector';
+ /** Available options */
+ options: XDSTableFilterOption[];
+ /** Placeholder when no value is selected. @default 'All' */
+ placeholder?: string;
+}
+
+/** Multi-selector filter — multi-select checkboxes. */
+export interface XDSTableFilterTypeMultiSelector {
+ type: 'multi-selector';
+ /** Available options */
+ options: XDSTableFilterOption[];
+ /** Show a "Select all" option. @default true */
+ hasSelectAll?: boolean;
+ /** Enable typeahead search within options. @default false */
+ isSearchable?: boolean;
+ /** Placeholder when no values are selected. @default 'All' */
+ placeholder?: string;
+}
+
+/** Date filter — date picker input (ISO date string). */
+export interface XDSTableFilterTypeDate {
+ type: 'date';
+ /** Placeholder text. @default 'Filter...' */
+ placeholder?: string;
+ /** Minimum allowed date (ISO string) */
+ min?: string;
+ /** Maximum allowed date (ISO string) */
+ max?: string;
+}
+
+/** Time filter — time picker input (ISO time string). */
+export interface XDSTableFilterTypeTime {
+ type: 'time';
+ /** Placeholder text. @default 'Filter...' */
+ placeholder?: string;
+ /** Minimum allowed time */
+ min?: string;
+ /** Maximum allowed time */
+ max?: string;
+}
+
+/** String list filter — tokenizer for free-form string tags. */
+export interface XDSTableFilterTypeStringList {
+ type: 'string-list';
+ /** Placeholder text. @default 'Add...' */
+ placeholder?: string;
+}
+
+/** Discriminated union of all filter type configs. */
+export type XDSTableFilterType =
+ | XDSTableFilterTypeText
+ | XDSTableFilterTypeNumber
+ | XDSTableFilterTypeNumberRange
+ | XDSTableFilterTypeSelector
+ | XDSTableFilterTypeMultiSelector
+ | XDSTableFilterTypeDate
+ | XDSTableFilterTypeTime
+ | XDSTableFilterTypeStringList;
+
+/**
+ * Reference to a PowerSearch field.
+ * Instead of defining the filter inline, point to a field in a shared
+ * `PowerSearchConfig`. The plugin resolves the operator's value type
+ * and renders the appropriate control.
+ *
+ * - **String form** — field key only, uses the field's `defaultOperator`:
+ * `filter: 'status'`
+ *
+ * - **Object form** — field key + explicit operator:
+ * `filter: { field: 'status', operator: 'is_not' }`
+ *
+ * Both require `searchConfig` on the plugin config.
+ */
+export interface XDSTableFilterFieldRef {
+ /** Key of the PowerSearchField in the searchConfig. */
+ field: string;
+ /**
+ * Key of the operator on that field. When omitted, uses the field's
+ * `defaultOperator` or the first operator.
+ */
+ operator?: string;
+}
+
+// =============================================================================
+// PowerSearch → Table Filter Resolution
+// =============================================================================
+
+/**
+ * Resolve the operator for a PowerSearch field.
+ * Uses the specified operator key, the field's defaultOperator, or the first.
+ */
+function resolveOperator(
+ field: PowerSearchField,
+ operatorKey?: string,
+): PowerSearchOperator | undefined {
+ if (operatorKey) {
+ return field.operators.find(o => o.key === operatorKey);
+ }
+ if (field.defaultOperator) {
+ return field.operators.find(o => o.key === field.defaultOperator);
+ }
+ return field.operators[0];
+}
+
+/**
+ * Convert a PowerSearch OperatorValue to the table filter's XDSTableFilterType.
+ *
+ * Maps:
+ * - string → text
+ * - integer / float → number
+ * - enum → selector
+ * - enum_list → multi-selector
+ *
+ * Unsupported operator value types (date, entity_list, nested, custom, etc.)
+ * return undefined — the column is treated as non-filterable.
+ */
+function operatorValueToFilterType(
+ opValue: OperatorValue,
+): XDSTableFilterType | undefined {
+ switch (opValue.type) {
+ case 'string':
+ return {type: 'text'};
+ case 'integer':
+ return {
+ type: 'number',
+ min: opValue.minValue,
+ max: opValue.maxValue,
+ step: 1,
+ };
+ case 'float':
+ return {
+ type: 'number',
+ min: opValue.minValue,
+ max: opValue.maxValue,
+ };
+ case 'enum':
+ return {
+ type: 'selector',
+ options: opValue.values.map(v => ({value: v.value, label: v.label})),
+ };
+ case 'enum_list':
+ return {
+ type: 'multi-selector',
+ options: opValue.values.map(v => ({value: v.value, label: v.label})),
+ };
+ case 'date_absolute':
+ return {type: 'date'};
+ case 'time':
+ return {type: 'time'};
+ case 'string_list':
+ case 'entity_list':
+ return {type: 'string-list'};
+ default:
+ // date_relative, date_range, nested, custom, empty —
+ // no simple single-control equivalent yet
+ return undefined;
+ }
+}
+
+/**
+ * Resolve a column's filter field reference to a concrete filter type.
+ *
+ * - String → field key, uses defaultOperator.
+ * - Object with `field` → look up field + optional operator.
+ * - Returns undefined if the field/operator can't be resolved.
+ */
+function resolveFilterConfig(
+ filter: XDSTableFilterFieldRef | string,
+ searchConfig: PowerSearchConfig,
+): XDSTableFilterType | undefined {
+ const fieldKey = typeof filter === 'string' ? filter : filter.field;
+ const operatorKey = typeof filter === 'string' ? undefined : filter.operator;
+
+ const field = searchConfig.fields.find(f => f.key === fieldKey);
+ if (!field) return undefined;
+
+ const operator = resolveOperator(field, operatorKey);
+ if (!operator) return undefined;
+
+ return operatorValueToFilterType(operator.value);
+}
+
+/**
+ * Convert table filter state to PowerSearchFilter[] for use with `applyFilters`.
+ *
+ * Maps each non-empty entry in the filter state to a `PowerSearchFilter`,
+ * resolving the field and operator from the column config + searchConfig.
+ * This bridges the table filtering UI with PowerSearch's client-side
+ * filter engine — define filters once, apply everywhere.
+ *
+ * @example
+ * ```
+ * const { config, applyFilters } = usePowerSearchConfig(defs);
+ * const searchFilters = toSearchFilters(filters, columns, config);
+ * const filteredData = applyFilters(searchFilters, data);
+ * ```
+ */
+export function toSearchFilters<T extends Record<string, unknown>>(
+ filters: XDSTableFilterState,
+ columns: ReadonlyArray<{
+ key: string;
+ filter?: XDSTableFilterFieldRef | string;
+ }>,
+ searchConfig: PowerSearchConfig,
+): PowerSearchFilter[] {
+ const result: PowerSearchFilter[] = [];
+
+ for (const col of columns) {
+ if (!col.filter) continue;
+ const value = filters[col.key];
+ if (value == null) continue;
+
+ const fieldKey =
+ typeof col.filter === 'string' ? col.filter : col.filter.field;
+ const operatorKey =
+ typeof col.filter === 'string' ? undefined : col.filter.operator;
+
+ const field = searchConfig.fields.find(f => f.key === fieldKey);
+ if (!field) continue;
+
+ const operator = resolveOperator(field, operatorKey);
+ if (!operator) continue;
+
+ const filterValue = tableValueToFilterValue(value, operator.value);
+ if (!filterValue) continue;
+
+ result.push({field: fieldKey, operator: operator.key, value: filterValue});
+ }
+
+ return result;
+}
+
+/**
+ * Convert a table filter value to a PowerSearch FilterValue
+ * based on the operator's value type.
+ */
+function tableValueToFilterValue(
+ value: XDSTableFilterValue,
+ opValue: OperatorValue,
+): FilterValue | undefined {
+ switch (opValue.type) {
+ case 'string':
+ return typeof value === 'string' ? {type: 'string', value} : undefined;
+ case 'integer':
+ return typeof value === 'number' ? {type: 'integer', value} : undefined;
+ case 'float':
+ return typeof value === 'number' ? {type: 'float', value} : undefined;
+ case 'enum':
+ return typeof value === 'string' ? {type: 'enum', value} : undefined;
+ case 'enum_list':
+ return Array.isArray(value)
+ ? {type: 'enum_list', value: value as string[]}
+ : undefined;
+ case 'date_absolute':
+ return typeof value === 'string'
+ ? {
+ type: 'date_absolute',
+ unixSeconds: Math.floor(new Date(value).getTime() / 1000),
+ }
+ : undefined;
+ case 'time':
+ return typeof value === 'string' ? {type: 'time', value} : undefined;
+ case 'string_list':
+ return Array.isArray(value)
+ ? {type: 'string_list', value: value as string[]}
+ : undefined;
+ case 'entity_list':
+ return Array.isArray(value)
+ ? {
+ type: 'entity_list',
+ value: (value as string[]).map(id => ({id, label: id})),
+ }
+ : undefined;
+ default:
+ return undefined;
+ }
+}
+
+// =============================================================================
+// Filter State
+// =============================================================================
+
+/**
+ * Complete filter state — a map from column key to filter value.
+ * Missing keys or `undefined` values mean "no filter applied" for that column.
+ *
+ * @example
+ * ```
+ * const filters: XDSTableFilterState = {
+ * name: 'alice',
+ * status: 'active',
+ * age: { min: 18, max: 65 },
+ * tags: ['admin', 'user'],
+ * };
+ * ```
+ */
+export type XDSTableFilterState = Record<
+ string,
+ XDSTableFilterValue | undefined
+>;
+
+/**
+ * Display variant for the filter UI.
+ *
+ * - `'popover'` — filter icon in header; clicking opens a popover with the filter control
+ * - `'inline'` — filter control rendered directly below header text inside the header cell
+ * - `'inline-compact'` — same as inline but with compact-sized controls
+ */
+export type XDSTableFilterVariant = 'popover' | 'inline' | 'inline-compact';
+
+// =============================================================================
+// Hook Config
+// =============================================================================
+
+/**
+ * Configuration for useXDSTableFiltering.
+ *
+ * @example
+ * ```
+ * const [filters, setFilters] = useState<XDSTableFilterState>({});
+ *
+ * const filterPlugin = useXDSTableFiltering({
+ * filters,
+ * onFilterChange: (columnKey, value) => {
+ * setFilters(prev => {
+ * const next = { ...prev };
+ * if (value == null) {
+ * delete next[columnKey];
+ * } else {
+ * next[columnKey] = value;
+ * }
+ * return next;
+ * });
+ * },
+ * });
+ *
+ * <XDSTable plugins={[filterPlugin]} ... />
+ * ```
+ */
+export interface UseXDSTableFilteringConfig {
+ /** Current filter state — map from column key to filter value. */
+ filters: XDSTableFilterState;
+ /** Called when the user changes a filter value. `null` clears the filter. */
+ onFilterChange: (
+ columnKey: string,
+ value: XDSTableFilterValue | null,
+ ) => void;
+ /**
+ * Display variant for filter controls.
+ *
+ * @default 'popover'
+ */
+ variant?: XDSTableFilterVariant;
+ /**
+ * PowerSearch configuration that defines the available filter fields.
+ * Columns reference fields by key; the plugin resolves the operator's
+ * value type and renders the matching control.
+ *
+ * Use `createPowerSearchConfig` or `usePowerSearchConfig` to build this
+ * from field definitions — the same config can be shared with
+ * `XDSPowerSearch` for a unified filtering experience.
+ */
+ searchConfig: PowerSearchConfig;
+}
+
+// =============================================================================
+// Filter Store & Context
+// =============================================================================
+
+interface FilterStore {
+ getConfig: () => UseXDSTableFilteringConfig;
+}
+
+const FilterStoreContext = createContext<FilterStore | null>(null);
+
+/** Variant is stable per plugin instance — kept in a separate context so
+ * slot components can read it without going through the mutable store. */
+const FilterVariantContext = createContext<XDSTableFilterVariant>('popover');
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const filterStyles = stylex.create({
+ afterPopover: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ flexShrink: 0,
+ },
+ afterInline: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-1'],
+ marginTop: spacingVars['--spacing-1'],
+ minWidth: 0,
+ },
+ triggerButton: {
+ background: 'none',
+ border: 'none',
+ cursor: 'pointer',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: spacingVars['--spacing-1'],
+ borderRadius: radiusVars['--radius-element'],
+ flexShrink: 0,
+ // Minimum 44px touch target on coarse pointer devices (iOS guideline).
+ '@media (pointer: coarse)': {
+ minWidth: '44px',
+ minHeight: '44px',
+ },
+ },
+ triggerInactive: {
+ opacity: {
+ default: 0.35,
+ ':is(th:hover *)': 1,
+ ':focus-visible': 1,
+ },
+ },
+ triggerActive: {
+ opacity: 1,
+ },
+ popoverContent: {
+ padding: spacingVars['--spacing-2'],
+ width: '240px',
+ },
+ popoverActions: {
+ display: 'flex',
+ justifyContent: 'flex-end',
+ gap: spacingVars['--spacing-2'],
+ marginTop: spacingVars['--spacing-2'],
+ },
+ numberRangeRow: {
+ display: 'flex',
+ gap: spacingVars['--spacing-2'],
+ },
+ placeholder: {
+ height: '32px',
+ },
+ placeholderCompact: {
+ height: '28px',
+ },
+});
+
+// =============================================================================
+// Filter Control Components
+// =============================================================================
+
+function TextFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeText;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const config = store.getConfig();
+ const value = config.filters[columnKey];
+ const strValue = typeof value === 'string' ? value : '';
+
+ return (
+ <XDSTextInput
+ label={`Filter ${header}`}
+ isLabelHidden
+ value={strValue}
+ onChange={(newValue: string) => {
+ store
+ .getConfig()
+ .onFilterChange(columnKey, newValue === '' ? null : newValue);
+ }}
+ placeholder={filterConfig.placeholder ?? 'Filter...'}
+ size={size}
+ />
+ );
+}
+
+function NumberFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeNumber;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const config = store.getConfig();
+ const value = config.filters[columnKey];
+ const numValue = typeof value === 'number' ? value : null;
+
+ return (
+ <XDSNumberInput
+ label={`Filter ${header}`}
+ isLabelHidden
+ value={numValue}
+ onChange={(newValue: number) => {
+ store.getConfig().onFilterChange(columnKey, newValue);
+ }}
+ placeholder={filterConfig.placeholder ?? 'Filter...'}
+ min={filterConfig.min ?? null}
+ max={filterConfig.max ?? null}
+ step={filterConfig.step ?? null}
+ size={size}
+ />
+ );
+}
+
+function NumberRangeFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeNumberRange;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const config = store.getConfig();
+ const value = config.filters[columnKey];
+ const rangeValue =
+ value != null && typeof value === 'object' && !Array.isArray(value)
+ ? (value as XDSTableFilterNumberRangeValue)
+ : undefined;
+
+ const handleMinChange = useCallback(
+ (newMin: number) => {
+ const cfg = store.getConfig();
+ const current = cfg.filters[columnKey];
+ const existing =
+ current != null &&
+ typeof current === 'object' &&
+ !Array.isArray(current)
+ ? (current as XDSTableFilterNumberRangeValue)
+ : {};
+ cfg.onFilterChange(columnKey, {...existing, min: newMin});
+ },
+ [store, columnKey],
+ );
+
+ const handleMaxChange = useCallback(
+ (newMax: number) => {
+ const cfg = store.getConfig();
+ const current = cfg.filters[columnKey];
+ const existing =
+ current != null &&
+ typeof current === 'object' &&
+ !Array.isArray(current)
+ ? (current as XDSTableFilterNumberRangeValue)
+ : {};
+ cfg.onFilterChange(columnKey, {...existing, max: newMax});
+ },
+ [store, columnKey],
+ );
+
+ return (
+ <div {...stylex.props(filterStyles.numberRangeRow)}>
+ <XDSNumberInput
+ label={`Min ${header}`}
+ isLabelHidden
+ value={rangeValue?.min ?? null}
+ onChange={handleMinChange}
+ placeholder={filterConfig.minPlaceholder ?? 'Min'}
+ min={filterConfig.min ?? null}
+ max={filterConfig.max ?? null}
+ step={filterConfig.step ?? null}
+ size={size}
+ />
+ <XDSNumberInput
+ label={`Max ${header}`}
+ isLabelHidden
+ value={rangeValue?.max ?? null}
+ onChange={handleMaxChange}
+ placeholder={filterConfig.maxPlaceholder ?? 'Max'}
+ min={filterConfig.min ?? null}
+ max={filterConfig.max ?? null}
+ step={filterConfig.step ?? null}
+ size={size}
+ />
+ </div>
+ );
+}
+
+function SelectorFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeSelector;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const config = store.getConfig();
+ const value = config.filters[columnKey];
+ const strValue = typeof value === 'string' ? value : '';
+
+ const options = filterConfig.options.map(opt => ({
+ value: opt.value,
+ label: opt.label,
+ }));
+
+ return (
+ <XDSSelector
+ label={`Filter ${header}`}
+ isLabelHidden
+ options={options}
+ value={strValue}
+ onChange={(newValue: string) => {
+ store
+ .getConfig()
+ .onFilterChange(columnKey, newValue === '' ? null : newValue);
+ }}
+ placeholder={filterConfig.placeholder ?? 'All'}
+ size={size}
+ />
+ );
+}
+
+function MultiSelectorFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeMultiSelector;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const config = store.getConfig();
+ const value = config.filters[columnKey];
+ const arrValue = Array.isArray(value) ? value : [];
+
+ const options = filterConfig.options.map(opt => ({
+ value: opt.value,
+ label: opt.label,
+ }));
+
+ return (
+ <XDSMultiSelector
+ label={`Filter ${header}`}
+ isLabelHidden
+ options={options}
+ value={arrValue}
+ onChange={(newValue: string[]) => {
+ store
+ .getConfig()
+ .onFilterChange(columnKey, newValue.length === 0 ? null : newValue);
+ }}
+ placeholder={filterConfig.placeholder ?? 'All'}
+ size={size}
+ hasSelectAll={filterConfig.hasSelectAll ?? true}
+ hasSearch={filterConfig.isSearchable ?? false}
+ />
+ );
+}
+
+function DateFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeDate;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const value = store.getConfig().filters[columnKey] as string | undefined;
+
+ return (
+ <XDSDateInput
+ label={`Filter ${header}`}
+ isLabelHidden
+ value={(value as ISODateString | undefined) ?? undefined}
+ onChange={newValue => {
+ store.getConfig().onFilterChange(columnKey, newValue ?? null);
+ }}
+ min={filterConfig.min as ISODateString | undefined}
+ max={filterConfig.max as ISODateString | undefined}
+ size={size}
+ />
+ );
+}
+
+function TimeFilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterTypeTime;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const value = store.getConfig().filters[columnKey] as string | undefined;
+
+ return (
+ <XDSTimeInput
+ label={`Filter ${header}`}
+ isLabelHidden
+ value={(value as ISOTimeString | undefined) ?? undefined}
+ onChange={newValue => {
+ store.getConfig().onFilterChange(columnKey, newValue ?? null);
+ }}
+ min={filterConfig.min as ISOTimeString | undefined}
+ max={filterConfig.max as ISOTimeString | undefined}
+ size={size}
+ />
+ );
+}
+
+function StringListFilterControl({
+ columnKey,
+ header,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ size: 'sm' | 'md';
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const value =
+ (store.getConfig().filters[columnKey] as string[] | undefined) ?? [];
+
+ // Simple static search source that accepts any typed text as a new tag
+ const searchSource = useMemo(
+ () => ({
+ search: async (query: string) =>
+ query.trim() ? [{id: query.trim(), label: query.trim()}] : [],
+ bootstrap: () => [] as {id: string; label: string}[],
+ }),
+ [],
+ );
+
+ return (
+ <XDSTokenizer
+ label={`Filter ${header}`}
+ isLabelHidden
+ searchSource={searchSource}
+ value={value.map(v => ({id: v, label: v}))}
+ onChange={items => {
+ const newValues = items.map(item => item.id);
+ store
+ .getConfig()
+ .onFilterChange(columnKey, newValues.length > 0 ? newValues : null);
+ }}
+ size={size}
+ />
+ );
+}
+
+/** Renders the appropriate filter control for a column's filter type. */
+function FilterControl({
+ columnKey,
+ header,
+ filterConfig,
+ size,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterType;
+ size: 'sm' | 'md';
+}) {
+ switch (filterConfig.type) {
+ case 'text':
+ return (
+ <TextFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'number':
+ return (
+ <NumberFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'number-range':
+ return (
+ <NumberRangeFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'selector':
+ return (
+ <SelectorFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'multi-selector':
+ return (
+ <MultiSelectorFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'date':
+ return (
+ <DateFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'time':
+ return (
+ <TimeFilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ );
+ case 'string-list':
+ return (
+ <StringListFilterControl
+ columnKey={columnKey}
+ header={header}
+ size={size}
+ />
+ );
+ }
+}
+
+// =============================================================================
+// Popover Filter Trigger
+// =============================================================================
+
+function PopoverFilterTrigger({
+ columnKey,
+ header,
+ filterConfig,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterType;
+}) {
+ const store = useContext(FilterStoreContext)!;
+ const config = store.getConfig();
+ const value = config.filters[columnKey];
+ const hasValue = value != null;
+ const [isOpen, setIsOpen] = useState(false);
+
+ // Buffer the filter value locally while the popover is open.
+ // Only commit to the consumer's state on explicit "Apply".
+ const [draft, setDraft] = useState<XDSTableFilterValue | null>(null);
+
+ const handleOpen = useCallback(
+ (open: boolean) => {
+ if (open) {
+ // Seed draft from current value when opening
+ setDraft(value ?? null);
+ }
+ setIsOpen(open);
+ },
+ [value],
+ );
+
+ const handleApply = useCallback(() => {
+ store.getConfig().onFilterChange(columnKey, draft);
+ setIsOpen(false);
+ }, [store, columnKey, draft]);
+
+ const handleClear = useCallback(() => {
+ store.getConfig().onFilterChange(columnKey, null);
+ setIsOpen(false);
+ }, [store, columnKey]);
+
+ // Build a local store override so FilterControl writes to the draft
+ // instead of the consumer's state.
+ const draftStore: FilterStore = {
+ getConfig() {
+ return {
+ ...store.getConfig(),
+ filters: {
+ ...store.getConfig().filters,
+ [columnKey]: draft ?? undefined,
+ },
+ onFilterChange: (_key: string, val: XDSTableFilterValue | null) => {
+ setDraft(val);
+ },
+ };
+ },
+ };
+
+ return (
+ <XDSPopover
+ isOpen={isOpen}
+ onOpenChange={handleOpen}
+ label={`Filter ${header}`}
+ placement="below"
+ alignment="start"
+ content={
+ <FilterStoreContext.Provider value={draftStore}>
+ <div {...stylex.props(filterStyles.popoverContent)}>
+ <FilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size="sm"
+ />
+ <div {...stylex.props(filterStyles.popoverActions)}>
+ <XDSButton
+ label="Clear"
+ variant="secondary"
+ size="sm"
+ onClick={handleClear}
+ />
+ <XDSButton
+ label="Apply"
+ variant="primary"
+ size="sm"
+ onClick={handleApply}
+ />
+ </div>
+ </div>
+ </FilterStoreContext.Provider>
+ }>
+ <button
+ type="button"
+ aria-label={`Filter ${header}`}
+ aria-haspopup="dialog"
+ {...stylex.props(
+ filterStyles.triggerButton,
+ hasValue ? filterStyles.triggerActive : filterStyles.triggerInactive,
+ )}>
+ <XDSIcon
+ icon="funnel"
+ size="xsm"
+ color={hasValue ? 'accent' : 'secondary'}
+ />
+ </button>
+ </XDSPopover>
+ );
+}
+
+// =============================================================================
+// Helper
+// =============================================================================
+
+function getHeaderString(
+ column: XDSTableColumn<Record<string, unknown>>,
+): string {
+ if (typeof column.header === 'string') return column.header;
+ return column.key;
+}
+
+// =============================================================================
+// Filter Slot Components
+//
+// These are stable components rendered by transformHeaderCell. Because the
+// component *type* (`FilterSlot` / `InlineFilterSlot`) never changes across
+// renders, React keeps the same fiber and no remount occurs when filter state
+// updates. All dynamic data (filters, onFilterChange, filterConfig) is read
+// from FilterStoreContext at render time — not passed as props.
+// =============================================================================
+
+/**
+ * Popover variant slot — renders the funnel trigger button for one column.
+ * Reads filter state and column config from context.
+ */
+function FilterSlot({
+ columnKey,
+ header,
+ filterConfig,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterType;
+}) {
+ return (
+ <div {...stylex.props(filterStyles.afterPopover)}>
+ <PopoverFilterTrigger
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ />
+ </div>
+ );
+}
+
+/**
+ * Inline variant slot — renders the filter control (or placeholder) for one
+ * column. Reads variant and filter config from context.
+ */
+function InlineFilterSlot({
+ columnKey,
+ header,
+ filterConfig,
+}: {
+ columnKey: string;
+ header: string;
+ filterConfig: XDSTableFilterType | undefined;
+}) {
+ const variant = useContext(FilterVariantContext);
+ const size = variant === 'inline-compact' ? 'sm' : 'md';
+ const placeholderStyle =
+ variant === 'inline-compact'
+ ? filterStyles.placeholderCompact
+ : filterStyles.placeholder;
+
+ return (
+ <div {...stylex.props(filterStyles.afterInline)}>
+ {filterConfig != null ? (
+ <FilterControl
+ columnKey={columnKey}
+ header={header}
+ filterConfig={filterConfig}
+ size={size}
+ />
+ ) : (
+ <div aria-hidden="true" {...stylex.props(placeholderStyle)} />
+ )}
+ </div>
+ );
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * useXDSTableFiltering — table plugin for column filtering.
+ *
+ * Returns a stable TablePlugin that transforms header cells to add
+ * filter controls. Follows the headless pattern: consumer owns filter state,
+ * plugin provides UI and interaction.
+ *
+ * Filter types are configured per-column via the `filter` field on
+ * XDSTableColumn. The plugin reads filter config from columns and
+ * renders the appropriate control (text input, selector, etc.).
+ *
+ * @template T - Row data type
+ *
+ * @example
+ * ```
+ * const [filters, setFilters] = useState<XDSTableFilterState>({});
+ *
+ * const filterPlugin = useXDSTableFiltering({
+ * filters,
+ * onFilterChange: (key, value) => {
+ * setFilters(prev => ({
+ * ...prev,
+ * [key]: value ?? undefined,
+ * }));
+ * },
+ * variant: 'popover',
+ * });
+ *
+ * <XDSTable
+ * data={users}
+ * columns={[
+ * { key: 'name', header: 'Name', filter: { type: 'text' } },
+ * { key: 'status', header: 'Status', filter: {
+ * type: 'selector',
+ * options: [{ value: 'active' }, { value: 'inactive' }],
+ * }},
+ * { key: 'age', header: 'Age', filter: { type: 'number-range', min: 0 } },
+ * ]}
+ * plugins={[filterPlugin]}
+ * />
+ * ```
+ */
+export function useXDSTableFiltering<T extends Record<string, unknown>>(
+ config: UseXDSTableFilteringConfig,
+): TablePlugin<T> {
+ const configRef = useRef(config);
+ configRef.current = config;
+
+ const storeRef = useRef<FilterStore | null>(null);
+ if (storeRef.current == null) {
+ storeRef.current = {
+ getConfig() {
+ return configRef.current;
+ },
+ };
+ }
+ const store = storeRef.current;
+
+ const variant = config.variant ?? 'popover';
+
+ return useMemo(
+ (): TablePlugin<T> => ({
+ transformTableContext(children: ReactNode) {
+ return (
+ <FilterStoreContext.Provider value={store}>
+ <FilterVariantContext.Provider value={variant}>
+ {children}
+ </FilterVariantContext.Provider>
+ </FilterStoreContext.Provider>
+ );
+ },
+
+ transformHeaderCell(
+ props: HeaderCellRenderProps,
+ column: XDSTableColumn<T>,
+ ): HeaderCellRenderProps {
+ const rawFilter = column.filter;
+ const header = getHeaderString(
+ column as XDSTableColumn<Record<string, unknown>>,
+ );
+
+ // Resolve field references to concrete filter types
+ const filterConfig = rawFilter
+ ? resolveFilterConfig(rawFilter, store.getConfig().searchConfig)
+ : undefined;
+
+ if (variant === 'popover') {
+ // No filter config on this column — nothing to render.
+ if (!filterConfig) return props;
+
+ return {
+ ...props,
+ after: (
+ <>
+ {props.after}
+ <FilterSlot
+ columnKey={column.key}
+ header={header}
+ filterConfig={filterConfig}
+ />
+ </>
+ ),
+ };
+ }
+
+ // Inline or inline-compact: render filter controls below the header
+ // label row. Uses the `below` slot so controls sit underneath the
+ // header content rather than inline after it.
+ return {
+ ...props,
+ below: (
+ <>
+ {props.below}
+ <InlineFilterSlot
+ columnKey={column.key}
+ header={header}
+ filterConfig={filterConfig}
+ />
+ </>
+ ),
+ };
+ },
+ }),
+ [store, variant],
+ );
+}
diff --git a/packages/core/src/Table/types.ts b/packages/core/src/Table/types.ts
index cf84c1e566..1e4b50098f 100644
--- a/packages/core/src/Table/types.ts
+++ b/packages/core/src/Table/types.ts
@@ -18,6 +18,7 @@ import type {
ReactNode,
} from 'react';
import type {StyleXStyles} from '../theme/types';
+import type {XDSTableFilterFieldRef} from './plugins/filtering/useXDSTableFiltering';
// =============================================================================
// Column Width
@@ -108,6 +109,27 @@ export interface XDSTableColumn<T extends Record<string, unknown>> {
*/
resizable?: boolean;
sortable?: boolean | XDSTableSortableColumnConfig;
+ /**
+ * Filter configuration for this column.
+ *
+ * References a field in the shared `PowerSearchConfig` passed to
+ * `useXDSTableFiltering`. The plugin resolves the operator's value
+ * type and renders the matching control.
+ *
+ * Accepts:
+ * - **Field key** — `'status'` — uses the field's `defaultOperator`
+ * - **Field ref** — `{ field: 'status', operator: 'is_not' }` — explicit operator
+ *
+ * @example
+ * ```
+ * // Field key (uses defaultOperator)
+ * { key: 'status', header: 'Status', filter: 'status' }
+ *
+ * // Field + explicit operator
+ * { key: 'status', header: 'Status', filter: { field: 'status', operator: 'is_not' } }
+ * ```
+ */
+ filter?: XDSTableFilterFieldRef | string;
/**
* Custom cell renderer. Receives the row item and returns rich JSX content.
* Defaults to `String(item[key])` — use renderCell for rich content like
@@ -156,13 +178,14 @@ export interface HeaderRowRenderProps {
* Uses named slots so multiple plugins can contribute content without
* conflicts. Each plugin writes to its own slot; XDSBaseTable renders
* them in order: `before | content | after`, with `overlay` positioned
- * absolutely on top.
+ * absolutely on top and `below` underneath the header row.
*
* Slot semantics:
* - **before** — content before the label (e.g. selection checkbox)
* - **content** — the header label; plugins may wrap (e.g. sort button)
* - **after** — content after the label (e.g. sort icon, filter icon)
* - **overlay** — absolutely positioned layer (e.g. resize handle)
+ * - **below** — content below the header label row (e.g. inline filter controls)
*/
export interface HeaderCellRenderProps {
htmlProps: ThHTMLAttributes<HTMLTableCellElement>;
@@ -175,6 +198,8 @@ export interface HeaderCellRenderProps {
after?: ReactNode;
/** Absolutely positioned overlay content (e.g. resize handle). */
overlay?: ReactNode;
+ /** Content rendered below the header label row (e.g. inline filter controls). */
+ below?: ReactNode;
}
/** Props passed through the plugin pipeline for each body `<tr>` */