@tanstack/svelte-table/dist/createTableHook.svelte.d.ts

Headless UI for building powerful tables & datagrids for Svelte.

import FlexRenderSvelte from './FlexRender.svelte';
import type { SvelteTable } from './createTable.svelte';
import type { Component, Snippet } from 'svelte';
import type { AccessorFn, AccessorFnColumnDef, AccessorKeyColumnDef, Cell, CellContext, CellData, Column, ColumnDef, DeepKeys, DeepValue, DisplayColumnDef, GroupColumnDef, Header, IdentifiedColumnDef, NoInfer, Row, RowData, Table, TableFeatures, TableOptions } from '@tanstack/table-core';
export type ComponentType<T extends Record<string, any>> = Component<T>;
/**
 * Enhanced CellContext with pre-bound cell components.
 * The `cell` property includes the registered cellComponents.
 */
export type AppCellContext<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, TCellComponents extends Record<string, ComponentType<any>>> = {
    cell: Cell<TFeatures, TData, TValue> & TCellComponents & {
        FlexRender: typeof FlexRenderSvelte;
    };
    column: Column<TFeatures, TData, TValue>;
    getValue: CellContext<TFeatures, TData, TValue>['getValue'];
    renderValue: CellContext<TFeatures, TData, TValue>['renderValue'];
    row: Row<TFeatures, TData>;
    table: Table<TFeatures, TData>;
};
/**
 * Enhanced HeaderContext with pre-bound header components.
 * The `header` property includes the registered headerComponents.
 */
export type AppHeaderContext<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, THeaderComponents extends Record<string, ComponentType<any>>> = {
    column: Column<TFeatures, TData, TValue>;
    header: Header<TFeatures, TData, TValue> & THeaderComponents & {
        FlexRender: typeof FlexRenderSvelte;
    };
    table: Table<TFeatures, TData>;
};
/**
 * Template type for column definitions that can be a string or a function.
 */
export type AppColumnDefTemplate<TProps extends object> = string | ((props: TProps) => any);
/**
 * Enhanced column definition base with pre-bound components in cell/header/footer contexts.
 */
export type AppColumnDefBase<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = Omit<IdentifiedColumnDef<TFeatures, TData, TValue>, 'cell' | 'header' | 'footer'> & {
    cell?: AppColumnDefTemplate<AppCellContext<TFeatures, TData, TValue, TCellComponents>>;
    header?: AppColumnDefTemplate<AppHeaderContext<TFeatures, TData, TValue, THeaderComponents>>;
    footer?: AppColumnDefTemplate<AppHeaderContext<TFeatures, TData, TValue, THeaderComponents>>;
};
/**
 * Enhanced display column definition with pre-bound components.
 */
export type AppDisplayColumnDef<TFeatures extends TableFeatures, TData extends RowData, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = Omit<DisplayColumnDef<TFeatures, TData, unknown>, 'cell' | 'header' | 'footer'> & {
    cell?: AppColumnDefTemplate<AppCellContext<TFeatures, TData, unknown, TCellComponents>>;
    header?: AppColumnDefTemplate<AppHeaderContext<TFeatures, TData, unknown, THeaderComponents>>;
    footer?: AppColumnDefTemplate<AppHeaderContext<TFeatures, TData, unknown, THeaderComponents>>;
};
/**
 * Enhanced group column definition with pre-bound components.
 */
export type AppGroupColumnDef<TFeatures extends TableFeatures, TData extends RowData, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = Omit<GroupColumnDef<TFeatures, TData, unknown>, 'cell' | 'header' | 'footer' | 'columns'> & {
    cell?: AppColumnDefTemplate<AppCellContext<TFeatures, TData, unknown, TCellComponents>>;
    header?: AppColumnDefTemplate<AppHeaderContext<TFeatures, TData, unknown, THeaderComponents>>;
    footer?: AppColumnDefTemplate<AppHeaderContext<TFeatures, TData, unknown, THeaderComponents>>;
    columns?: ReadonlyArray<ColumnDef<TFeatures, TData, unknown>>;
};
/**
 * Enhanced column helper with pre-bound components in cell/header/footer contexts.
 * This enables TypeScript to know about the registered components when defining columns.
 */
export type AppColumnHelper<TFeatures extends TableFeatures, TData extends RowData, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = {
    /**
     * Creates a data column definition with an accessor key or function.
     * The cell, header, and footer contexts include pre-bound components.
     */
    accessor: <TAccessor extends AccessorFn<TData> | DeepKeys<TData>, TValue extends (TAccessor extends AccessorFn<TData, infer TReturn> ? TReturn : TAccessor extends DeepKeys<TData> ? DeepValue<TData, TAccessor> : never)>(accessor: TAccessor, column: TAccessor extends AccessorFn<TData> ? AppColumnDefBase<TFeatures, TData, TValue, TCellComponents, THeaderComponents> & {
        id: string;
    } : AppColumnDefBase<TFeatures, TData, TValue, TCellComponents, THeaderComponents>) => TAccessor extends AccessorFn<TData> ? AccessorFnColumnDef<TFeatures, TData, TValue> : AccessorKeyColumnDef<TFeatures, TData, TValue>;
    /**
     * Wraps an array of column definitions to preserve each column's individual TValue type.
     */
    columns: <TColumns extends ReadonlyArray<ColumnDef<TFeatures, TData, any>>>(columns: [...TColumns]) => Array<ColumnDef<TFeatures, TData, any>> & [...TColumns];
    /**
     * Creates a display column definition for non-data columns.
     * The cell, header, and footer contexts include pre-bound components.
     */
    display: (column: AppDisplayColumnDef<TFeatures, TData, TCellComponents, THeaderComponents>) => DisplayColumnDef<TFeatures, TData, unknown>;
    /**
     * Creates a group column definition with nested child columns.
     * The cell, header, and footer contexts include pre-bound components.
     */
    group: (column: AppGroupColumnDef<TFeatures, TData, TCellComponents, THeaderComponents>) => GroupColumnDef<TFeatures, TData, unknown>;
};
/**
 * Options for creating a table hook with pre-bound components and default table options.
 * Extends all TableOptions except 'columns' | 'data' | 'store' | 'state' | 'initialState'.
 */
export type CreateTableHookOptions<TFeatures extends TableFeatures, TTableComponents extends Record<string, ComponentType<any>>, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = Omit<TableOptions<TFeatures, any>, 'columns' | 'data' | 'store' | 'state' | 'initialState'> & {
    /**
     * Table-level components that need access to the table instance.
     * These are available directly on the table object returned by createAppTable.
     * Use `useTableContext()` inside these components.
     * @example { PaginationControls, GlobalFilter, RowCount }
     */
    tableComponents?: TTableComponents;
    /**
     * Cell-level components that need access to the cell instance.
     * These are available on the cell object passed to AppCell's children.
     * Use `useCellContext()` inside these components.
     * @example { TextCell, NumberCell, DateCell, CurrencyCell }
     */
    cellComponents?: TCellComponents;
    /**
     * Header-level components that need access to the header instance.
     * These are available on the header object passed to AppHeader/AppFooter's children.
     * Use `useHeaderContext()` inside these components.
     * @example { SortIndicator, ColumnFilter, ResizeHandle }
     */
    headerComponents?: THeaderComponents;
};
/**
 * Svelte-aware table returned by `createAppTable`, extended with the registered
 * table components and the `App*` context wrappers.
 */
export type AppSvelteTable<TFeatures extends TableFeatures, TData extends RowData, TTableComponents extends Record<string, ComponentType<any>>, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = SvelteTable<TFeatures, TData> & NoInfer<TTableComponents> & {
    /**
     * Root wrapper component that provides table context.
     * @example
     * ```svelte
     * <table.AppTable>
     *   <table>...</table>
     * </table.AppTable>
     * ```
     */
    AppTable: Component<{
        children: Snippet;
    }>;
    /**
     * Wraps a cell and provides cell context with pre-bound cellComponents.
     * @example
     * ```svelte
     * <table.AppCell cell={cell}>
     *   {#snippet children(c)}
     *     <td><c.TextCell /></td>
     *   {/snippet}
     * </table.AppCell>
     * ```
     */
    AppCell: Component<{
        cell: Cell<TFeatures, TData, any>;
        children: Snippet<[
            Cell<TFeatures, TData, any> & NoInfer<TCellComponents> & {
                FlexRender: typeof FlexRenderSvelte;
            }
        ]>;
    }>;
    /**
     * Wraps a header and provides header context with pre-bound headerComponents.
     * @example
     * ```svelte
     * <table.AppHeader header={header}>
     *   {#snippet children(h)}
     *     <th><h.SortIndicator /></th>
     *   {/snippet}
     * </table.AppHeader>
     * ```
     */
    AppHeader: Component<{
        header: Header<TFeatures, TData, any>;
        children: Snippet<[
            Header<TFeatures, TData, any> & NoInfer<THeaderComponents> & {
                FlexRender: typeof FlexRenderSvelte;
            }
        ]>;
    }>;
    /**
     * Wraps a footer and provides header context with pre-bound headerComponents.
     * @example
     * ```svelte
     * <table.AppFooter header={footer}>
     *   {#snippet children(f)}
     *     <td><f.FlexRender /></td>
     *   {/snippet}
     * </table.AppFooter>
     * ```
     */
    AppFooter: Component<{
        header: Header<TFeatures, TData, any>;
        children: Snippet<[
            Header<TFeatures, TData, any> & NoInfer<THeaderComponents> & {
                FlexRender: typeof FlexRenderSvelte;
            }
        ]>;
    }>;
    /**
     * Convenience FlexRender component attached to the table instance.
     */
    FlexRender: typeof FlexRenderSvelte;
};
export interface CreateTableHookResult<TFeatures extends TableFeatures, TTableComponents extends Record<string, ComponentType<any>>, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> {
    /** The features object that was passed to `createTableHook`. */
    appFeatures: TFeatures;
    /**
     * A column helper pre-bound to `TFeatures` and the registered components, so
     * the cell/header/footer render props expose the bound components.
     */
    createAppColumnHelper: <TData extends RowData>() => AppColumnHelper<TFeatures, TData, TCellComponents, THeaderComponents>;
    /**
     * Creates a table with the `App*` wrapper components and registered
     * `tableComponents` attached. `TData` is inferred from the `data` option.
     *
     * Read table state with `table.atoms.<slice>.get()` or `table.store.get()`.
     * These reads participate in Svelte dependency tracking inside templates,
     * `$derived`, and `$effect`.
     */
    createAppTable: <TData extends RowData>(tableOptions: Omit<TableOptions<TFeatures, TData>, 'features'>) => AppSvelteTable<TFeatures, TData, TTableComponents, TCellComponents, THeaderComponents>;
    /**
     * Reads the table provided by the nearest `<table.AppTable>`. This is the same
     * extended instance `createAppTable` returns, so the `App*` components and your
     * `tableComponents` are available on it.
     */
    useTableContext: <TData extends RowData = RowData>() => AppSvelteTable<TFeatures, TData, TTableComponents, TCellComponents, THeaderComponents>;
    /**
     * Reads the cell provided by the nearest `<table.AppCell>`, extended with your
     * `cellComponents` and a context-bound `FlexRender`.
     */
    useCellContext: <TValue extends CellData = CellData>() => Cell<TFeatures, any, TValue> & TCellComponents & {
        FlexRender: typeof FlexRenderSvelte;
    };
    /**
     * Reads the header provided by the nearest `<table.AppHeader>` /
     * `<table.AppFooter>`, extended with your `headerComponents` and a
     * context-bound `FlexRender`.
     */
    useHeaderContext: <TValue extends CellData = CellData>() => Header<TFeatures, any, TValue> & THeaderComponents & {
        FlexRender: typeof FlexRenderSvelte;
    };
}
/**
 * Creates a custom table hook with pre-bound components for composition.
 *
 * This is the table equivalent of TanStack Form's `createFormHook`. It allows you to:
 * - Define features, row models, and default options once, shared across all tables
 * - Register reusable table, cell, and header components
 * - Access table/cell/header instances via context in those components
 * - Get a `createAppTable` hook that returns an extended table with App wrapper components
 * - Get a `createAppColumnHelper` function pre-bound to your features
 *
 * @example
 * ```ts
 * // hooks/table.ts
 * export const {
 *   createAppTable,
 *   createAppColumnHelper,
 *   useTableContext,
 *   useCellContext,
 *   useHeaderContext,
 * } = createTableHook({
 *   features: tableFeatures({
 *     rowPaginationFeature,
 *     rowSortingFeature,
 *     columnFilteringFeature,
 *     paginatedRowModel: createPaginatedRowModel(),
 *     sortedRowModel: createSortedRowModel(),
 *     filteredRowModel: createFilteredRowModel(),
 *     sortFns,
 *     filterFns,
 *   }),
 *   tableComponents: { PaginationControls, RowCount },
 *   cellComponents: { TextCell, NumberCell },
 *   headerComponents: { SortIndicator, ColumnFilter },
 * })
 * ```
 */
export declare function createTableHook<TFeatures extends TableFeatures, const TTableComponents extends Record<string, ComponentType<any>>, const TCellComponents extends Record<string, ComponentType<any>>, const THeaderComponents extends Record<string, ComponentType<any>>>({ tableComponents, cellComponents, headerComponents, ...defaultTableOptions }: CreateTableHookOptions<TFeatures, TTableComponents, TCellComponents, THeaderComponents>): CreateTableHookResult<TFeatures, TTableComponents, TCellComponents, THeaderComponents>;