import { type PaginationRangeItem } from "./use-pagination";
/** Text alignment for a DataTable column's header + cells. */
export type DataTableAlign = "start" | "center" | "end";
/** Row density preset. Controls cell padding + header height. */
export type DataTableDensity = "comfortable" | "compact";
/** Selection cardinality. `"none"` hides the leading checkbox column. */
export type DataTableSelectionMode = "none" | "single" | "multiple";
/**
 * Typed column definition. `T` is the row shape; `accessorKey` is constrained
 * to keys of `T` so the accessor is fully type-checked and IntelliSense-driven.
 *
 * @example
 * const columns: DataTableColumn<User>[] = [
 *   { accessorKey: "name", header: "Name", sortable: true },
 *   { id: "actions", header: "", cell: (row) => <RowMenu id={row.id} />, align: "end" },
 * ]
 */
export interface DataTableColumn<T> {
    /** Stable column id. Defaults to `String(accessorKey)` when omitted. Required if no `accessorKey` (e.g. an actions column). */
    id?: string;
    /** Key of the row object to read the value from. Omit for derived/action columns that only use `cell`. */
    accessorKey?: keyof T;
    /** Header content — string or node. */
    header: React.ReactNode;
    /** Custom cell renderer. Receives the full row + row index. Falls back to `String(row[accessorKey])`. */
    cell?: (row: T, rowIndex: number) => React.ReactNode;
    /** Enables click-to-sort on this column's header. Requires a sortable value (uses `sortFn` or default comparator). Default `false`. */
    sortable?: boolean;
    /** Custom comparator for sorting. Defaults to a locale-aware string / numeric compare on `row[accessorKey]`. */
    sortFn?: (a: T, b: T) => number;
    /** Header + cell alignment. Default `"start"`. */
    align?: DataTableAlign;
    /** CSS width applied to the column (`<col>` style), e.g. `"40%"` or `160`. */
    width?: number | string;
    /** Per-cell className for the `<td>`. */
    className?: string;
    /** Per-header className for the `<th>`. */
    headerClassName?: string;
    /** Accessible label for the header when `header` is a non-text node (icon-only / actions column). */
    ariaLabel?: string;
}
/** One sort instruction. `desc:false` = ascending. */
export interface DataTableSort {
    /** Column id this sort applies to. */
    id: string;
    /** `true` = descending, `false` = ascending. */
    desc: boolean;
}
/** Options for {@link useDataTable}. Mirrors the controllable DataTable props (sort/selection/pagination). */
export interface UseDataTableOptions<T> {
    /** Row data. */
    data: T[];
    /** Typed column definitions. */
    columns: DataTableColumn<T>[];
    /** Stable row key — string key of `T` or a function. Falls back to row index (logs a one-time dev warning). */
    getRowId?: keyof T | ((row: T, index: number) => string);
    /** Uncontrolled initial sort. */
    defaultSort?: DataTableSort[];
    /** Controlled sort state. Presence switches sorting to controlled. */
    sort?: DataTableSort[];
    /** Fires on header activation with the next sort array. */
    onSortChange?: (sort: DataTableSort[]) => void;
    /** Allow stacking multiple sort columns (additive activation appends/cycles). Default `false`. */
    multiSort?: boolean;
    /** Skip internal sorting (server/TanStack drives order). Header still emits `onSortChange`. Default `false`. */
    manualSort?: boolean;
    /** Selection cardinality. Default `"none"`. */
    selectionMode?: DataTableSelectionMode;
    /** Uncontrolled initial selected row-id set. */
    defaultSelectedKeys?: string[];
    /** Controlled selected row-id set. */
    selectedKeys?: string[];
    /** Fires with the next selected row-id array. */
    onSelectedKeysChange?: (keys: string[]) => void;
    /** Predicate to disable selection for specific rows. */
    isRowSelectable?: (row: T) => boolean;
    /** Rows per page. Omit / `0` disables pagination (all rows in one view). */
    pageSize?: number;
    /** Uncontrolled initial page (1-indexed). Default `1`. */
    defaultPage?: number;
    /** Controlled page (1-indexed). */
    page?: number;
    /** Fires on page change. */
    onPageChange?: (page: number) => void;
    /** Skip internal pagination/slicing (server drives the window). `data` is the current page. Default `false`. */
    manualPagination?: boolean;
    /** Total row count when `manualPagination` — drives the footer's page-count math. */
    rowCount?: number;
}
/** Resolved table state + actions returned by {@link useDataTable}. */
export interface UseDataTableReturn<T> {
    /** Rows for the current view (sorted + sliced unless manual*). */
    rows: T[];
    /** rowId for a given row. */
    rowId: (row: T, index: number) => string;
    /** Active sort instructions (first = primary). */
    sort: DataTableSort[];
    /** Cycle a column's sort asc → desc → none. `additive` keeps other sorted columns (multi-sort). */
    toggleSort: (columnId: string, additive: boolean) => void;
    /** Current sort direction for a column. */
    sortDirectionFor: (columnId: string) => "asc" | "desc" | "none";
    /** Selected row ids. */
    selectedKeys: Set<string>;
    /** Whether a row id is selected. */
    isSelected: (id: string) => boolean;
    /** Flip a single row's selection (respects `selectionMode`). */
    toggleRow: (id: string) => void;
    /** "all" | "some" | "none" across selectable rows on the current page. */
    selectAllState: "all" | "some" | "none";
    /** Select / clear exactly the current page's selectable ids (off-page selections preserved). */
    toggleSelectAll: () => void;
    /** Active 1-indexed page. */
    activePage: number;
    /** Total page count. */
    pageCount: number;
    /** Set the active page (clamped). */
    setPage: (page: number) => void;
    /** Pagination range (page numbers + `'dots'` markers). */
    range: PaginationRangeItem[];
    /** Total selectable row count across the whole data set (for the footer summary). */
    selectableCount: number;
}
/**
 * Headless sort/selection/pagination engine for {@link DataTable}. Controlled +
 * uncontrolled for all three axes. Pure — no markup, no design tokens.
 *
 * @example
 * const t = useDataTable({ data, columns, getRowId: "id", pageSize: 10 });
 */
export declare function useDataTable<T>(options: UseDataTableOptions<T>): UseDataTableReturn<T>;