import { FlexRender, LitRenderable } from "./flexRender.js"; import { LitTable } from "./TableController.js"; import { AccessorFn, AccessorFnColumnDef, AccessorKeyColumnDef, Cell, CellContext, CellData, Column, ColumnDef, DeepKeys, DeepValue, DisplayColumnDef, GroupColumnDef, Header, IdentifiedColumnDef, NoInfer, Row, RowData, Table, TableFeatures, TableOptions, TableState } from "@tanstack/table-core"; import { ReactiveControllerHost } from "lit"; import { Context, ContextConsumer } from "@lit/context"; //#region src/createTableHook.d.ts type ComponentType> = (props: T) => any; type BoundComponents>> = { [TKey in keyof TComponents]: () => ReturnType; }; /** * Enhanced CellContext with pre-bound cell components. * The `cell` property includes the registered cellComponents. */ type AppCellContext>> = { cell: Cell & BoundComponents & { FlexRender: () => LitRenderable; }; column: Column; getValue: CellContext['getValue']; renderValue: CellContext['renderValue']; row: Row; table: Table; }; /** * Enhanced HeaderContext with pre-bound header components. * The `header` property includes the registered headerComponents. */ type AppHeaderContext>> = { column: Column; header: Header & BoundComponents & { FlexRender: () => LitRenderable; }; table: Table; }; /** * Template type for column definitions that can be a string or a function. */ type AppColumnDefTemplate = string | ((props: TProps) => any); /** * Enhanced column definition base with pre-bound components in cell/header/footer contexts. */ type AppColumnDefBase>, THeaderComponents extends Record>> = Omit, 'cell' | 'header' | 'footer'> & { cell?: AppColumnDefTemplate>; header?: AppColumnDefTemplate>; footer?: AppColumnDefTemplate>; }; /** * Enhanced display column definition with pre-bound components. */ type AppDisplayColumnDef>, THeaderComponents extends Record>> = Omit, 'cell' | 'header' | 'footer'> & { cell?: AppColumnDefTemplate>; header?: AppColumnDefTemplate>; footer?: AppColumnDefTemplate>; }; /** * Enhanced group column definition with pre-bound components. */ type AppGroupColumnDef>, THeaderComponents extends Record>> = Omit, 'cell' | 'header' | 'footer' | 'columns'> & { cell?: AppColumnDefTemplate>; header?: AppColumnDefTemplate>; footer?: AppColumnDefTemplate>; columns?: ReadonlyArray>; }; /** * Enhanced column helper with pre-bound components in cell/header/footer contexts. * This enables TypeScript to know about the registered components when defining columns. */ type AppColumnHelper>, THeaderComponents extends Record>> = { /** * Creates a data column definition with an accessor key or function. * The cell, header, and footer contexts include pre-bound components. */ accessor: | DeepKeys, TValue extends (TAccessor extends AccessorFn ? TReturn : TAccessor extends DeepKeys ? DeepValue : never)>(accessor: TAccessor, column: TAccessor extends AccessorFn ? AppColumnDefBase & { id: string; } : AppColumnDefBase) => TAccessor extends AccessorFn ? AccessorFnColumnDef : AccessorKeyColumnDef; /** * Wraps an array of column definitions to preserve each column's individual TValue type. */ columns: >>(columns: [...TColumns]) => Array> & [...TColumns]; /** * Creates a display column definition for non-data columns. * The cell, header, and footer contexts include pre-bound components. */ display: (column: AppDisplayColumnDef) => DisplayColumnDef; /** * Creates a group column definition with nested child columns. * The cell, header, and footer contexts include pre-bound components. */ group: (column: AppGroupColumnDef) => GroupColumnDef; }; /** * Options for creating a table hook with pre-bound components and default table options. * Extends all TableOptions except 'columns' | 'data' | 'store' | 'state' | 'initialState'. */ type CreateTableHookOptions>, TCellComponents extends Record>, THeaderComponents extends Record>> = Omit, '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 useAppTable. * 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; }; /** * Extended table API returned by useAppTable with all App wrapper functions */ type AppLitTable>, TCellComponents extends Record>, THeaderComponents extends Record>> = LitTable & NoInfer & { /** * Wraps a cell and provides cell context with pre-bound cellComponents. * @example * ```ts * ${table.AppCell(cell, (c) => html`${c.FlexRender()}`)} * ``` */ AppCell: (cell: Cell, renderFn: (cell: Cell & BoundComponents & { FlexRender: () => LitRenderable; }) => LitRenderable) => LitRenderable; /** * Wraps a header and provides header context with pre-bound headerComponents. * @example * ```ts * ${table.AppHeader(header, (h) => html`${h.FlexRender()}`)} * ``` */ AppHeader: (header: Header, renderFn: (header: Header & BoundComponents & { FlexRender: () => LitRenderable; }) => LitRenderable) => LitRenderable; /** * Wraps a footer and provides header context with pre-bound headerComponents. * @example * ```ts * ${table.AppFooter(footer, (f) => html`${f.FlexRender()}`)} * ``` */ AppFooter: (header: Header, renderFn: (header: Header & BoundComponents & { FlexRender: () => LitRenderable; }) => LitRenderable) => LitRenderable; /** * Convenience FlexRender function attached to the table instance. * Renders cell, header, or footer content from column definitions. * @example * ```ts * ${table.FlexRender({ header })} * ${table.FlexRender({ cell })} * ${table.FlexRender({ footer: header })} * ``` */ FlexRender: typeof FlexRender; }; interface CreateTableHookResult>, TCellComponents extends Record>, THeaderComponents extends Record>> { /** 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: () => AppColumnHelper; /** * Creates a controller-like object whose `table()` method returns a table with * the `App*` wrapper functions, a bound `FlexRender`, and the registered * `tableComponents` attached. `TData` is inferred from the `data` option. */ useAppTable: >(host: ReactiveControllerHost & HTMLElement, tableOptions: Omit, 'features'>, selector?: (state: TableState) => TSelected) => { table: () => AppLitTable; }; /** * Reads the table provided by the nearest ancestor that called `useAppTable`, * via a `@lit/context` `ContextConsumer`. This is the BARE `LitTable` written * to the provider, not the extended `AppLitTable`. */ useTableContext: (host: ReactiveControllerHost & HTMLElement) => ContextConsumer>, ReactiveControllerHost & HTMLElement>; /** * Reads the cell instance from a `@lit/context` `ContextConsumer`. lit never * provides an extended cell through context, so this is a BARE `Cell`. */ useCellContext: (host: ReactiveControllerHost & HTMLElement) => ContextConsumer>, ReactiveControllerHost & HTMLElement>; /** * Reads the header instance from a `@lit/context` `ContextConsumer`. lit never * provides an extended header through context, so this is a BARE `Header`. */ useHeaderContext: (host: ReactiveControllerHost & HTMLElement) => ContextConsumer>, ReactiveControllerHost & HTMLElement>; } /** * 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 `@lit/context` in those components * - Get a `useAppTable` hook that returns an extended table with App wrapper functions * - Get a `createAppColumnHelper` function pre-bound to your features * * @example * ```ts * // hooks/table.ts * export const { * createAppColumnHelper, * useAppTable, * 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 }, * }) * * // Create column helper with TFeatures already bound * const columnHelper = createAppColumnHelper() * * // my-table.ts * @customElement('my-table') * class MyTable extends LitElement { * private appTable = useAppTable(this, { * columns, * data: this.data, * }) * * protected render() { * const table = this.appTable.table() * * return html` * * * ${repeat(table.getHeaderGroups(), (hg) => hg.id, (hg) => html` * * ${hg.headers.map((h) => table.AppHeader(h, (header) => html` * * `))} * * `)} * * * ${table.getRowModel().rows.map((row) => html` * * ${row.getAllCells().map((c) => table.AppCell(c, (cell) => html` * * `))} * * `)} * *
${header.FlexRender()}
${cell.FlexRender()}
* ` * } * } * ``` */ declare function createTableHook>, const TCellComponents extends Record>, const THeaderComponents extends Record>>({ tableComponents, cellComponents, headerComponents, ...defaultTableOptions }: CreateTableHookOptions): CreateTableHookResult; //#endregion export { AppCellContext, AppColumnDefBase, AppColumnDefTemplate, AppColumnHelper, AppDisplayColumnDef, AppGroupColumnDef, AppHeaderContext, AppLitTable, BoundComponents, ComponentType, CreateTableHookOptions, CreateTableHookResult, createTableHook };