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.tsxnew file mode 100644index 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.tsxindex 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}</>) : (resolvedContentdiff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.tsindex 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsindex 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>` */