@humanspeak/svelte-headless-table/dist/plugins/addSortBy.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 addSortBy plugin.
 */
export interface SortByConfig {
    /** Initial sort keys to apply on mount. */
    initialSortKeys?: SortKey[];
    /** If true, prevents sorting by multiple columns. Defaults to false. */
    disableMultiSort?: boolean;
    /** Function to detect multi-sort events (e.g., shift+click). Defaults to isShiftClick. */
    isMultiSortEvent?: (_event: Event) => boolean;
    /** Custom toggle order cycle. Defaults to ['asc', 'desc', undefined]. */
    toggleOrder?: ('asc' | 'desc' | undefined)[];
    /** If true, sorting is handled server-side and rows are returned as-is. */
    serverSide?: boolean;
}
/**
 * State exposed by the addSortBy plugin.
 *
 * @template Item - The type of data items in the table.
 */
export interface SortByState<Item> {
    /** Writable store containing the current sort keys. */
    sortKeys: WritableSortKeys;
    /** Readable store containing the rows before sorting was applied. */
    preSortedRows: Readable<BodyRow<Item>[]>;
}
/**
 * Per-column configuration options for sorting.
 */
export interface SortByColumnOptions {
    /** If true, this column cannot be sorted. */
    disable?: boolean;
    /** Custom function to extract the sortable value from the cell value. */
    getSortValue?: (_value: any) => string | number | (string | number)[];
    /** Custom comparison function for sorting. */
    compareFn?: (_left: any, _right: any) => number;
    /** If true, inverts the sort order for this column. */
    invert?: boolean;
}
/**
 * Props added to table elements by the sort plugin.
 */
export type SortByPropSet = NewTablePropSet<{
    'thead.tr.th': {
        /** Current sort order for this column. */
        order: 'asc' | 'desc' | undefined;
        /** Function to toggle sorting on this column. */
        toggle: (_event: Event) => void;
        /** Function to clear sorting on this column. */
        clear: () => void;
        /** Whether sorting is disabled for this column. */
        disabled: boolean;
    };
    'tbody.tr.td': {
        /** Current sort order for this column. */
        order: 'asc' | 'desc' | undefined;
    };
}>;
/**
 * Represents a single sort key with column ID and direction.
 */
export interface SortKey {
    /** The column ID to sort by. */
    id: string;
    /** The sort direction. */
    order: 'asc' | 'desc';
}
/**
 * Creates a writable store for managing sort keys with toggle and clear methods.
 *
 * @param initKeys - Initial sort keys.
 * @returns A WritableSortKeys store with toggle and clear functionality.
 * @example
 * ```typescript
 * const sortKeys = createSortKeysStore([{ id: 'name', order: 'asc' }])
 * sortKeys.toggleId('age') // Adds ascending sort by age
 * sortKeys.clearId('name') // Removes sort by name
 * ```
 */
export declare const createSortKeysStore: (initKeys: SortKey[]) => WritableSortKeys;
/**
 * Options for the toggleId method.
 */
interface ToggleOptions {
    /** Whether to allow multiple sort keys. */
    multiSort?: boolean;
    /** Custom toggle order cycle. */
    toggleOrder?: ('asc' | 'desc' | undefined)[];
}
/**
 * A writable store for sort keys with additional toggle and clear methods.
 */
export type WritableSortKeys = Writable<SortKey[]> & {
    /** Toggles the sort state for a column ID. */
    toggleId: (_id: string, _options: ToggleOptions) => void;
    /** Clears the sort state for a column ID. */
    clearId: (_id: string) => void;
};
/**
 * Creates a sort plugin that enables sorting table rows by one or more columns.
 * Supports ascending, descending, and unsorted states with customizable toggle order.
 *
 * @template Item - The type of data items in the table.
 * @param config - Configuration options for sorting behavior.
 * @returns A TablePlugin that provides sorting functionality.
 * @example
 * ```typescript
 * const table = createTable(data, {
 *   sort: addSortBy({
 *     initialSortKeys: [{ id: 'name', order: 'asc' }],
 *     disableMultiSort: false
 *   })
 * })
 *
 * // Access sort state in your component
 * const { sortKeys } = table.pluginStates.sort
 * ```
 */
export declare const addSortBy: <Item>({ initialSortKeys, disableMultiSort, isMultiSortEvent, toggleOrder, serverSide }?: SortByConfig) => TablePlugin<Item, SortByState<Item>, SortByColumnOptions, SortByPropSet>;
export {};