@tanstack/preact-table 9.0.0-alpha.21 → 9.0.0-alpha.23

package/dist/createTableHook.d.cts

@@ -0,0 +1,358 @@
+import { PreactTable } from "./useTable.cjs";
+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 { ComponentChildren, ComponentType } from "preact";
+
+//#region src/createTableHook.d.ts
+/**
+ * Enhanced CellContext with pre-bound cell components.
+ * The `cell` property includes the registered cellComponents.
+ */
+type AppCellContext<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, TCellComponents extends Record<string, ComponentType<any>>> = {
+  cell: Cell<TFeatures, TData, TValue> & TCellComponents & {
+    FlexRender: () => ComponentChildren;
+  };
+  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.
+ */
+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: () => ComponentChildren;
+  };
+  table: Table<TFeatures, TData>;
+};
+/**
+ * Template type for column definitions that can be a string or a function.
+ */
+type AppColumnDefTemplate<TProps extends object> = string | ((props: TProps) => any);
+/**
+ * Enhanced column definition base with pre-bound components in cell/header/footer contexts.
+ */
+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.
+ */
+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.
+ */
+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?: Array<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.
+ */
+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'.
+ */
+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 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;
+};
+/**
+ * Props for AppTable component - without selector
+ */
+interface AppTablePropsWithoutSelector {
+  children: ComponentChildren;
+  selector?: never;
+}
+/**
+ * Props for AppTable component - with selector
+ */
+interface AppTablePropsWithSelector<TFeatures extends TableFeatures, TSelected> {
+  children: (state: TSelected) => ComponentChildren;
+  selector: (state: TableState<TFeatures>) => TSelected;
+}
+/**
+ * Props for AppCell component - without selector
+ */
+interface AppCellPropsWithoutSelector<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, TCellComponents extends Record<string, ComponentType<any>>> {
+  cell: Cell<TFeatures, TData, TValue>;
+  children: (cell: Cell<TFeatures, TData, TValue> & TCellComponents & {
+    FlexRender: () => ComponentChildren;
+  }) => ComponentChildren;
+  selector?: never;
+}
+/**
+ * Props for AppCell component - with selector
+ */
+interface AppCellPropsWithSelector<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, TCellComponents extends Record<string, ComponentType<any>>, TSelected> {
+  cell: Cell<TFeatures, TData, TValue>;
+  children: (cell: Cell<TFeatures, TData, TValue> & TCellComponents & {
+    FlexRender: () => ComponentChildren;
+  }, state: TSelected) => ComponentChildren;
+  selector: (state: TableState<TFeatures>) => TSelected;
+}
+/**
+ * Props for AppHeader/AppFooter component - without selector
+ */
+interface AppHeaderPropsWithoutSelector<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, THeaderComponents extends Record<string, ComponentType<any>>> {
+  header: Header<TFeatures, TData, TValue>;
+  children: (header: Header<TFeatures, TData, TValue> & THeaderComponents & {
+    FlexRender: () => ComponentChildren;
+  }) => ComponentChildren;
+  selector?: never;
+}
+/**
+ * Props for AppHeader/AppFooter component - with selector
+ */
+interface AppHeaderPropsWithSelector<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData, THeaderComponents extends Record<string, ComponentType<any>>, TSelected> {
+  header: Header<TFeatures, TData, TValue>;
+  children: (header: Header<TFeatures, TData, TValue> & THeaderComponents & {
+    FlexRender: () => ComponentChildren;
+  }, state: TSelected) => ComponentChildren;
+  selector: (state: TableState<TFeatures>) => TSelected;
+}
+/**
+ * Component type for AppCell - wraps a cell and provides cell context with optional Subscribe
+ */
+interface AppCellComponent<TFeatures extends TableFeatures, TData extends RowData, TCellComponents extends Record<string, ComponentType<any>>> {
+  <TValue extends CellData = CellData>(props: AppCellPropsWithoutSelector<TFeatures, TData, TValue, TCellComponents>): ComponentChildren;
+  <TValue extends CellData = CellData, TSelected = unknown>(props: AppCellPropsWithSelector<TFeatures, TData, TValue, TCellComponents, TSelected>): ComponentChildren;
+}
+/**
+ * Component type for AppHeader/AppFooter - wraps a header and provides header context with optional Subscribe
+ */
+interface AppHeaderComponent<TFeatures extends TableFeatures, TData extends RowData, THeaderComponents extends Record<string, ComponentType<any>>> {
+  <TValue extends CellData = CellData>(props: AppHeaderPropsWithoutSelector<TFeatures, TData, TValue, THeaderComponents>): ComponentChildren;
+  <TValue extends CellData = CellData, TSelected = unknown>(props: AppHeaderPropsWithSelector<TFeatures, TData, TValue, THeaderComponents, TSelected>): ComponentChildren;
+}
+/**
+ * Component type for AppTable - root wrapper with optional Subscribe
+ */
+interface AppTableComponent<TFeatures extends TableFeatures> {
+  (props: AppTablePropsWithoutSelector): ComponentChildren;
+  <TSelected>(props: AppTablePropsWithSelector<TFeatures, TSelected>): ComponentChildren;
+}
+/**
+ * Extended table API returned by useAppTable with all App wrapper components
+ */
+type AppPreactTable<TFeatures extends TableFeatures, TData extends RowData, TSelected, TTableComponents extends Record<string, ComponentType<any>>, TCellComponents extends Record<string, ComponentType<any>>, THeaderComponents extends Record<string, ComponentType<any>>> = PreactTable<TFeatures, TData, TSelected> & NoInfer<TTableComponents> & {
+  /**
+   * Root wrapper component that provides table context with optional Subscribe.
+   * @example
+   * ```tsx
+   * // Without selector - children is ComponentChildren
+   * <table.AppTable>
+   *   <table>...</table>
+   * </table.AppTable>
+   *
+   * // With selector - children receives selected state
+   * <table.AppTable selector={(s) => s.pagination}>
+   *   {(pagination) => <div>Page {pagination.pageIndex}</div>}
+   * </table.AppTable>
+   * ```
+   */
+  AppTable: AppTableComponent<TFeatures>;
+  /**
+   * Wraps a cell and provides cell context with pre-bound cellComponents.
+   * Optionally accepts a selector for Subscribe functionality.
+   * @example
+   * ```tsx
+   * // Without selector
+   * <table.AppCell cell={cell}>
+   *   {(c) => <td><c.TextCell /></td>}
+   * </table.AppCell>
+   *
+   * // With selector - children receives cell and selected state
+   * <table.AppCell cell={cell} selector={(s) => s.columnFilters}>
+   *   {(c, filters) => <td>{filters.length}</td>}
+   * </table.AppCell>
+   * ```
+   */
+  AppCell: AppCellComponent<TFeatures, TData, NoInfer<TCellComponents>>;
+  /**
+   * Wraps a header and provides header context with pre-bound headerComponents.
+   * Optionally accepts a selector for Subscribe functionality.
+   * @example
+   * ```tsx
+   * // Without selector
+   * <table.AppHeader header={header}>
+   *   {(h) => <th><h.SortIndicator /></th>}
+   * </table.AppHeader>
+   *
+   * // With selector
+   * <table.AppHeader header={header} selector={(s) => s.sorting}>
+   *   {(h, sorting) => <th>{sorting.length} sorted</th>}
+   * </table.AppHeader>
+   * ```
+   */
+  AppHeader: AppHeaderComponent<TFeatures, TData, NoInfer<THeaderComponents>>;
+  /**
+   * Wraps a footer and provides header context with pre-bound headerComponents.
+   * Optionally accepts a selector for Subscribe functionality.
+   * @example
+   * ```tsx
+   * <table.AppFooter header={footer}>
+   *   {(f) => <td><table.FlexRender footer={footer} /></td>}
+   * </table.AppFooter>
+   * ```
+   */
+  AppFooter: AppHeaderComponent<TFeatures, TData, NoInfer<THeaderComponents>>;
+};
+/**
+ * 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 `useAppTable` hook that returns an extended table with App wrapper components
+ * - Get a `createAppColumnHelper` function pre-bound to your features
+ *
+ * @example
+ * ```tsx
+ * // hooks/table.ts
+ * export const {
+ *   useAppTable,
+ *   createAppColumnHelper,
+ *   useTableContext,
+ *   useCellContext,
+ *   useHeaderContext,
+ * } = createTableHook({
+ *   _features: tableFeatures({
+ *     rowPaginationFeature,
+ *     rowSortingFeature,
+ *     columnFilteringFeature,
+ *   }),
+ *   _rowModels: {
+ *     paginatedRowModel: createPaginatedRowModel(),
+ *     sortedRowModel: createSortedRowModel(sortFns),
+ *     filteredRowModel: createFilteredRowModel(filterFns),
+ *   },
+ *   tableComponents: { PaginationControls, RowCount },
+ *   cellComponents: { TextCell, NumberCell },
+ *   headerComponents: { SortIndicator, ColumnFilter },
+ * })
+ *
+ * // Create column helper with TFeatures already bound
+ * const columnHelper = createAppColumnHelper<Person>()
+ *
+ * // components/table-components.tsx
+ * function PaginationControls() {
+ *   const table = useTableContext() // TFeatures already known!
+ *   return <table.Subscribe selector={(s) => s.pagination}>...</table.Subscribe>
+ * }
+ *
+ * // features/users.tsx
+ * function UsersTable({ data }: { data: Person[] }) {
+ *   const table = useAppTable({
+ *     columns,
+ *     data, // TData inferred from Person[]
+ *   })
+ *
+ *   return (
+ *     <table.AppTable>
+ *       <table>
+ *         <thead>
+ *           {table.getHeaderGroups().map(headerGroup => (
+ *             <tr key={headerGroup.id}>
+ *               {headerGroup.headers.map(h => (
+ *                 <table.AppHeader header={h} key={h.id}>
+ *                   {(header) => (
+ *                     <th>
+ *                       <table.FlexRender header={h} />
+ *                       <header.SortIndicator />
+ *                     </th>
+ *                   )}
+ *                 </table.AppHeader>
+ *               ))}
+ *             </tr>
+ *           ))}
+ *         </thead>
+ *         <tbody>
+ *           {table.getRowModel().rows.map(row => (
+ *             <tr key={row.id}>
+ *               {row.getAllCells().map(c => (
+ *                 <table.AppCell cell={c} key={c.id}>
+ *                   {(cell) => <td><cell.TextCell /></td>}
+ *                 </table.AppCell>
+ *               ))}
+ *             </tr>
+ *           ))}
+ *         </tbody>
+ *       </table>
+ *       <table.PaginationControls />
+ *     </table.AppTable>
+ *   )
+ * }
+ * ```
+ */
+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>): {
+  appFeatures: TFeatures;
+  createAppColumnHelper: <TData extends RowData>() => AppColumnHelper<TFeatures, TData, TCellComponents, THeaderComponents>;
+  useAppTable: <TData extends RowData, TSelected = {}>(tableOptions: Omit<TableOptions<TFeatures, TData>, "_features" | "_rowModels">, selector?: (state: TableState<TFeatures>) => TSelected) => AppPreactTable<TFeatures, TData, TSelected, TTableComponents, TCellComponents, THeaderComponents>;
+  useTableContext: <TData extends RowData = RowData>() => PreactTable<TFeatures, TData>;
+  useCellContext: <TValue extends CellData = unknown>() => Cell<TFeatures, any, TValue>;
+  useHeaderContext: <TValue extends CellData = unknown>() => Header<TFeatures, any, TValue>;
+};
+//#endregion
+export { AppCellComponent, AppCellContext, AppCellPropsWithSelector, AppCellPropsWithoutSelector, AppColumnHelper, AppHeaderComponent, AppHeaderContext, AppHeaderPropsWithSelector, AppHeaderPropsWithoutSelector, AppPreactTable, AppTableComponent, AppTablePropsWithSelector, AppTablePropsWithoutSelector, CreateTableHookOptions, createTableHook };
+//# sourceMappingURL=createTableHook.d.cts.map