@humanspeak/svelte-headless-table/dist/plugins/addTableFilter.d.ts

A powerful, headless table library for Svelte that provides complete control over table UI while handling complex data operations like sorting, filtering, pagination, grouping, and row expansion. Build custom, accessible data tables with zero styling opin

import { type Readable, type Writable } from 'svelte/store';
import type { BodyRow } from '../bodyRows.js';
import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
/**
 * Configuration options for the addTableFilter plugin.
 */
export interface TableFilterConfig {
    /** Custom filter function. Defaults to textPrefixFilter. */
    fn?: TableFilterFn;
    /** Initial filter value. Defaults to empty string. */
    initialFilterValue?: string;
    /** Whether to include hidden columns in the filter. Defaults to false. */
    includeHiddenColumns?: boolean;
    /** If true, filtering is handled server-side and all rows are returned. Defaults to false. */
    serverSide?: boolean;
}
/**
 * State exposed by the addTableFilter plugin.
 *
 * @template Item - The type of data items in the table.
 */
export interface TableFilterState<Item> {
    /** Writable store containing the current filter value. */
    filterValue: Writable<string>;
    /** Readable store containing the rows before filtering was applied. */
    preFilteredRows: Readable<BodyRow<Item>[]>;
}
/**
 * Per-column configuration options for the table filter.
 *
 * @template _Item - The type of data items (unused but required for type inference).
 */
export interface TableFilterColumnOptions<_Item> {
    /** If true, this column is excluded from filtering. */
    exclude?: boolean;
    /** Custom function to extract the filter value from the cell value. */
    getFilterValue?: (_value: any) => string;
}
/**
 * Function type for custom filter implementations.
 *
 * @param props - The filter function props containing the filter value and cell value.
 * @returns True if the value matches the filter.
 */
export type TableFilterFn = (_props: TableFilterFnProps) => boolean;
/**
 * Props passed to a TableFilterFn.
 */
export type TableFilterFnProps = {
    /** The current filter value entered by the user. */
    filterValue: string;
    /** The string value of the cell being tested. */
    value: string;
};
/**
 * Props added to tbody.tr.td elements by the table filter plugin.
 */
export type TableFilterPropSet = NewTablePropSet<{
    'tbody.tr.td': {
        /** True if this cell matches the current filter. */
        matches: boolean;
    };
}>;
/**
 * Options for the rowMatchesFilter function.
 *
 * @template Item - The type of data items in the table.
 */
export interface RowMatchesFilterOptions<Item> {
    /** Per-column filter configuration. */
    columnOptions: Record<string, TableFilterColumnOptions<Item>>;
    /** The current filter value. */
    filterValue: string;
    /** The filter function to use. */
    fn: TableFilterFn;
    /** Whether to include hidden columns in filtering. */
    includeHiddenColumns: boolean;
    /** Record to track which cells matched the filter. */
    tableCellMatches: Record<string, boolean>;
}
/**
 * Checks if a row matches the filter criteria.
 * Uses O(1) Set-based lookups for visibility checks instead of O(m) array searches.
 *
 * @template Item - The type of data items in the table.
 * @param row - The row to check.
 * @param options - The filter options.
 * @returns True if any cell in the row matches the filter, or if the row has subRows.
 */
export declare const rowMatchesFilter: <Item>(row: BodyRow<Item>, options: RowMatchesFilterOptions<Item>) => boolean;
/**
 * Creates a table filter plugin that enables filtering rows by text search across columns.
 *
 * @template Item - The type of data items in the table.
 * @param config - Configuration options for the filter.
 * @returns A TablePlugin that provides filtering functionality.
 * @example
 * ```typescript
 * const table = createTable(data, {
 *   filter: addTableFilter({
 *     fn: ({ filterValue, value }) => value.toLowerCase().includes(filterValue.toLowerCase()),
 *     initialFilterValue: '',
 *     includeHiddenColumns: false
 *   })
 * })
 *
 * // Access the filter state
 * const { filterValue } = table.pluginStates.filter
 * filterValue.set('search term')
 * ```
 */
export declare const addTableFilter: <Item>({ fn, initialFilterValue, includeHiddenColumns, serverSide }?: TableFilterConfig) => TablePlugin<Item, TableFilterState<Item>, TableFilterColumnOptions<Item>, TableFilterPropSet>;