@humanspeak/svelte-headless-table/dist/plugins/addColumnFilters.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 { RenderConfig } from '@humanspeak/svelte-render';
import { type Readable, type Writable } from 'svelte/store';
import type { BodyRow } from '../bodyRows.js';
import type { PluginInitTableState } from '../createViewModel.js';
import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
/**
 * Configuration options for the addColumnFilters plugin.
 */
export interface ColumnFiltersConfig {
    /** If true, filtering is handled server-side and all rows are returned. */
    serverSide?: boolean;
}
/**
 * State exposed by the addColumnFilters plugin.
 *
 * @template Item - The type of data items in the table.
 */
export interface ColumnFiltersState<Item> {
    /** Writable store containing filter values keyed by column ID. */
    filterValues: Writable<Record<string, unknown>>;
    /** Readable store containing rows before filtering was applied. */
    preFilteredRows: Readable<BodyRow<Item>[]>;
}
/**
 * Per-column configuration options for column filters.
 *
 * @template Item - The type of data items in the table.
 * @template FilterValue - The type of the filter value.
 */
export interface ColumnFiltersColumnOptions<Item, FilterValue = any> {
    /** The filter function to use for this column. */
    fn: ColumnFilterFn<FilterValue>;
    /** Initial filter value for this column. */
    initialFilterValue?: FilterValue;
    /** Optional render function for custom filter UI. */
    render?: (props: ColumnRenderConfigPropArgs<Item, FilterValue>) => RenderConfig;
}
/**
 * Props passed to the column filter render function.
 *
 * @template Item - The type of data items.
 * @template FilterValue - The type of the filter value.
 * @template Value - The type of cell values.
 */
interface ColumnRenderConfigPropArgs<Item, FilterValue = any, Value = any> extends PluginInitTableState<Item> {
    /** The column ID. */
    id: string;
    /** Writable store for the filter value. */
    filterValue: Writable<FilterValue>;
    /** Readable store of all current column values (after filtering). */
    values: Readable<Value[]>;
    /** Readable store of rows before filtering. */
    preFilteredRows: Readable<BodyRow<Item>[]>;
    /** Readable store of all column values before filtering. */
    preFilteredValues: Readable<Value[]>;
}
/**
 * Function type for column filter implementations.
 *
 * @template FilterValue - The type of the filter value.
 * @template Value - The type of cell values.
 */
export type ColumnFilterFn<FilterValue = any, Value = any> = (props: ColumnFilterFnProps<FilterValue, Value>) => boolean;
/**
 * Props passed to a ColumnFilterFn.
 *
 * @template FilterValue - The type of the filter value.
 * @template Value - The type of cell values.
 */
export type ColumnFilterFnProps<FilterValue = any, Value = any> = {
    /** The current filter value for this column. */
    filterValue: FilterValue;
    /** The cell value being tested. */
    value: Value;
};
/**
 * Props added to header cells by the column filters plugin.
 */
export type ColumnFiltersPropSet = NewTablePropSet<{
    'thead.tr.th': {
        /** The rendered filter component. */
        render?: RenderConfig;
    } | undefined;
}>;
/**
 * Creates a column filters plugin that enables per-column filtering with custom filter functions.
 *
 * @template Item - The type of data items in the table.
 * @param config - Configuration options.
 * @returns A TablePlugin that provides column filtering functionality.
 * @example
 * ```typescript
 * const table = createTable(data, {
 *   colFilter: addColumnFilters()
 * })
 *
 * // Configure per-column in column definitions:
 * table.column({
 *   accessor: 'status',
 *   header: 'Status',
 *   plugins: {
 *     colFilter: {
 *       fn: matchFilter,
 *       initialFilterValue: undefined
 *     }
 *   }
 * })
 * ```
 */
export declare const addColumnFilters: <Item>({ serverSide }?: ColumnFiltersConfig) => TablePlugin<Item, ColumnFiltersState<Item>, ColumnFiltersColumnOptions<Item>, ColumnFiltersPropSet>;
/**
 * A filter function that matches exact values.
 * Returns true if filterValue is undefined or equals the cell value.
 *
 * @param props - The filter props containing filterValue and value.
 * @returns True if the value matches the filter.
 */
export declare const matchFilter: ColumnFilterFn<unknown, unknown>;
/**
 * A filter function that matches text by prefix (case-insensitive).
 * Returns true if filterValue is empty or value starts with filterValue.
 *
 * @param props - The filter props containing filterValue and value.
 * @returns True if the value starts with the filter text.
 */
export declare const textPrefixFilter: ColumnFilterFn<string, string>;
/**
 * A filter function that matches numbers within a range.
 * The range is [min, max] inclusive. Use null for unbounded.
 *
 * @param props - The filter props with a [min, max] filterValue and numeric value.
 * @returns True if the value is within the specified range.
 * @example
 * ```typescript
 * numberRangeFilter({ filterValue: [10, 50], value: 25 }) // true
 * numberRangeFilter({ filterValue: [null, 100], value: 50 }) // true (no min)
 * ```
 */
export declare const numberRangeFilter: ColumnFilterFn<[number | null, number | null], number>;
export {};