@tanstack/angular-table 9.0.0-alpha.5 → 9.0.0-alpha.51

package/src/helpers/createTableHook.ts

@@ -0,0 +1,499 @@
+import { createColumnHelper as coreCreateColumnHelper } from '@tanstack/table-core'
+import { injectTable } from '../injectTable'
+import { injectFlexRenderContext } from '../flexRender'
+import { injectTableHeaderContext as _injectTableHeaderContext } from './header'
+import { injectTableContext as _injectTableContext } from './table'
+import { injectTableCellContext as _injectTableCellContext } from './cell'
+import type { FlexRenderContent } from '../flexRender'
+import type { AngularTable } from '../injectTable'
+import type {
+  AccessorFn,
+  AccessorFnColumnDef,
+  AccessorKeyColumnDef,
+  Cell,
+  CellContext,
+  CellData,
+  Column,
+  ColumnDef,
+  DeepKeys,
+  DeepValue,
+  DisplayColumnDef,
+  GroupColumnDef,
+  Header,
+  HeaderContext,
+  IdentifiedColumnDef,
+  Row,
+  RowData,
+  Table,
+  TableFeature,
+  TableFeatures,
+  TableOptions,
+  TableState,
+} from '@tanstack/table-core'
+import type { Signal, Type } from '@angular/core'
+
+export type RenderableComponent =
+  | Type<any>
+  | (<T extends NonNullable<unknown>>(props: T) => FlexRenderContent<T>)
+
+// =============================================================================
+// Enhanced Context Types with Pre-bound Components
+// =============================================================================
+
+/**
+ * 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, RenderableComponent>,
+> = {
+  cell: Cell<TFeatures, TData, TValue> &
+    TCellComponents & { FlexRender: () => unknown }
+  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, RenderableComponent>,
+> = {
+  column: Column<TFeatures, TData, TValue>
+  header: Header<TFeatures, TData, TValue> &
+    THeaderComponents & { FlexRender: () => unknown }
+  table: Table<TFeatures, TData>
+}
+
+// =============================================================================
+// Enhanced Column Definition Types
+// =============================================================================
+
+/**
+ * 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, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = 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, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = 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, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = 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 Type
+// =============================================================================
+
+/**
+ * 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, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = {
+  /**
+   * 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>
+}
+
+/**
+ * Extended table API returned by useAppTable with all App wrapper components
+ */
+export type AppAngularTable<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TTableComponents extends Record<string, RenderableComponent>,
+  TCellComponents extends Record<string, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = AngularTable<TFeatures, TData> &
+  NoInfer<TTableComponents> & {
+    appCell: <TValue>(
+      cell: Cell<TFeatures, TData, TValue>,
+    ) => Cell<TFeatures, TData, TValue> & NoInfer<TCellComponents>
+
+    appHeader: <TValue>(
+      header: Header<TFeatures, TData, TValue>,
+    ) => Header<TFeatures, TData, TValue> & NoInfer<THeaderComponents>
+
+    appFooter: <TValue>(
+      footer: Header<TFeatures, TData, TValue>,
+    ) => Header<TFeatures, TData, TValue> & NoInfer<THeaderComponents>
+  }
+
+// =============================================================================
+// CreateTableHook Options and Props
+// =============================================================================
+
+/**
+ * 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 CreateTableContextOptions<
+  TFeatures extends TableFeatures,
+  TTableComponents extends Record<string, RenderableComponent>,
+  TCellComponents extends Record<string, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = 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
+}
+
+export type CreateTableHookResult<
+  TFeatures extends TableFeatures,
+  TTableComponents extends Record<string, RenderableComponent>,
+  TCellComponents extends Record<string, RenderableComponent>,
+  THeaderComponents extends Record<string, RenderableComponent>,
+> = {
+  createAppColumnHelper: <TData extends RowData>() => AppColumnHelper<
+    TFeatures,
+    TData,
+    TCellComponents,
+    THeaderComponents
+  >
+  injectTableContext: <TData extends RowData = RowData>() => Signal<
+    AngularTable<TFeatures, TData>
+  >
+  injectTableHeaderContext: <
+    TValue extends CellData = CellData,
+    TRowData extends RowData = RowData,
+  >() => Signal<Header<TFeatures, TRowData, TValue>>
+  injectTableCellContext: <
+    TValue extends CellData = CellData,
+    TRowData extends RowData = RowData,
+  >() => Signal<Cell<TFeatures, TRowData, TValue>>
+  injectFlexRenderHeaderContext: <
+    TData extends RowData,
+    TValue extends CellData,
+  >() => HeaderContext<TFeatures, TData, TValue>
+  injectFlexRenderCellContext: <
+    TData extends RowData,
+    TValue extends CellData,
+  >() => CellContext<TFeatures, TData, TValue>
+  injectAppTable: <TData extends RowData>(
+    tableOptions: () => Omit<
+      TableOptions<TFeatures, TData>,
+      '_features' | '_rowModels'
+    >,
+  ) => AppAngularTable<
+    TFeatures,
+    TData,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
+  >
+}
+
+/**
+ * Creates app-scoped Angular table helpers with features, row models, and
+ * renderable component maps pre-bound.
+ *
+ * Use this when an app or design system wants typed `injectAppTable`,
+ * pre-bound column helpers, and typed table/cell/header context injection
+ * helpers without repeating the same feature and component generics.
+ *
+ * @example
+ * ```ts
+ * const { injectAppTable, createAppColumnHelper } = createTableHook({
+ *   _features,
+ *   _rowModels: {},
+ *   tableComponents: {},
+ *   cellComponents: {},
+ *   headerComponents: {},
+ * })
+ * ```
+ */
+export function createTableHook<
+  TFeatures extends TableFeatures,
+  const TTableComponents extends Record<string, RenderableComponent>,
+  const TCellComponents extends Record<string, RenderableComponent>,
+  const THeaderComponents extends Record<string, RenderableComponent>,
+>({
+  tableComponents,
+  cellComponents,
+  headerComponents,
+  ...defaultTableOptions
+}: CreateTableContextOptions<
+  TFeatures,
+  TTableComponents,
+  TCellComponents,
+  THeaderComponents
+>): CreateTableHookResult<
+  TFeatures,
+  TTableComponents,
+  TCellComponents,
+  THeaderComponents
+> {
+  function injectTableContext<TData extends RowData = RowData>(): Signal<
+    AngularTable<TFeatures, TData>
+  > {
+    return _injectTableContext<TFeatures, TData>()
+  }
+
+  function injectTableHeaderContext<
+    TValue extends CellData = CellData,
+    TRowData extends RowData = RowData,
+  >(): Signal<Header<TFeatures, TRowData, TValue>> {
+    return _injectTableHeaderContext<TFeatures, TRowData, TValue>()
+  }
+
+  function injectTableCellContext<
+    TValue extends CellData = CellData,
+    TRowData extends RowData = RowData,
+  >(): Signal<Cell<TFeatures, TRowData, TValue>> {
+    return _injectTableCellContext<TFeatures, TRowData, TValue>()
+  }
+
+  function injectFlexRenderHeaderContext<
+    TData extends RowData,
+    TValue extends CellData,
+  >(): HeaderContext<TFeatures, TData, TValue> {
+    return injectFlexRenderContext<HeaderContext<TFeatures, TData, TValue>>()
+  }
+
+  function injectFlexRenderCellContext<
+    TData extends RowData,
+    TValue extends CellData,
+  >(): CellContext<TFeatures, TData, TValue> {
+    return injectFlexRenderContext<CellContext<TFeatures, TData, TValue>>()
+  }
+
+  function injectAppTable<
+    TData extends RowData,
+    TSelected = TableState<TFeatures>,
+  >(
+    tableOptions: () => Omit<
+      TableOptions<TFeatures, TData>,
+      '_features' | '_rowModels'
+    >,
+  ): AppAngularTable<
+    TFeatures,
+    TData,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
+  > {
+    function appCell(cell: Cell<TFeatures, TData, any>) {
+      return cell as Cell<TFeatures, TData, any> & TCellComponents
+    }
+
+    function appHeader(header: Header<TFeatures, TData, any>) {
+      return header as Header<TFeatures, TData, any> & THeaderComponents
+    }
+
+    function appFooter(footer: Header<TFeatures, TData, any>) {
+      return footer as Header<TFeatures, TData, any> & THeaderComponents
+    }
+
+    const appTableFeatures: TableFeature<{}> = {
+      constructTableAPIs: (table) => {
+        Object.assign(table, tableComponents, { appCell, appHeader, appFooter })
+      },
+      assignCellPrototype(prototype) {
+        Object.assign(prototype, cellComponents)
+      },
+      assignHeaderPrototype(prototype) {
+        Object.assign(prototype, headerComponents)
+      },
+    }
+
+    return injectTable<TFeatures, TData>(() => {
+      return {
+        ...defaultTableOptions,
+        ...tableOptions(),
+        _features: {
+          ...defaultTableOptions._features,
+          appTableFeatures,
+        },
+      } as TableOptions<TFeatures, TData>
+    }) as AngularTable<any, any>
+  }
+
+  function createAppColumnHelper<TData extends RowData>(): AppColumnHelper<
+    TFeatures,
+    TData,
+    TCellComponents,
+    THeaderComponents
+  > {
+    // The runtime implementation is the same - components are attached at render time
+    // This cast provides the enhanced types for column definitions
+    return coreCreateColumnHelper<TFeatures, TData>() as AppColumnHelper<
+      TFeatures,
+      TData,
+      TCellComponents,
+      THeaderComponents
+    >
+  }
+
+  return {
+    createAppColumnHelper,
+    injectTableContext,
+    injectTableHeaderContext,
+    injectTableCellContext,
+    injectFlexRenderHeaderContext,
+    injectFlexRenderCellContext,
+    injectAppTable,
+  }
+}

package/src/helpers/flexRenderCell.ts

@@ -0,0 +1,136 @@
+import {
+  DestroyRef,
+  Directive,
+  Injector,
+  TemplateRef,
+  ViewContainerRef,
+  computed,
+  inject,
+  input,
+} from '@angular/core'
+import {
+  Cell,
+  CellData,
+  Header,
+  RowData,
+  TableFeatures,
+} from '@tanstack/table-core'
+import { FlexViewRenderer } from '../flex-render/renderer'
+import type { FlexRenderInputContent } from '../flex-render/renderer'
+import type { CellContext, HeaderContext } from '@tanstack/table-core'
+
+/**
+ * Simplified directive wrapper of `*flexRender`.
+ *
+ * Use this utility component to render headers, cells, or footers with custom markup.
+ *
+ * Only one prop (`cell`, `header`, or `footer`) may be passed based on the used selector.
+ *
+ * @example
+ * ```html
+ * <td *flexRenderCell="cell; let cell">{{cell}}</td>
+ * <th *flexRenderHeader="header; let header">{{header}}</th>
+ * <th *flexRenderFooter="footer; let footer">{{footer}}</th>
+ * ```
+ *
+ * This replaces calling `*flexRender` directly like this:
+ * ```html
+ * <td *flexRender="cell.column.columnDef.cell; props: cell.getContext(); let cell">{{cell}}</td>
+ * <td *flexRender="header.column.columnDef.header; props: header.getContext(); let header">{{header}}</td>
+ * <td *flexRender="footer.column.columnDef.footer; props: footer.getContext(); let footer">{{footer}}</td>
+ * ```
+ *
+ * Can be imported through {@link FlexRenderCell} or {@link FlexRender} import,
+ * which the latter is preferred.
+ *
+ * @example
+ * ```ts
+ * import {FlexRender} from '@tanstack/angular-table
+ *
+ * @Component({
+ *  // ...
+ *  imports: [
+ *    FlexRender
+ *  ]
+ * })
+ * ```
+ */
+@Directive({
+  selector:
+    'ng-template[flexRenderCell], ng-template[flexRenderFooter], ng-template[flexRenderHeader]',
+})
+export class FlexRenderCell<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData,
+> {
+  readonly cell = input<Cell<TFeatures, TData, TValue>>(undefined, {
+    alias: 'flexRenderCell',
+  })
+
+  readonly header = input<Header<TFeatures, TData, TValue>>(undefined, {
+    alias: 'flexRenderHeader',
+  })
+
+  readonly footer = input<Header<TFeatures, TData, TValue>>(undefined, {
+    alias: 'flexRenderFooter',
+  })
+
+  readonly #renderData = computed<
+    | [
+        content: FlexRenderInputContent<CellContext<TFeatures, TData, TValue>>,
+        props: CellContext<TFeatures, TData, TValue>,
+      ]
+    | [
+        content: FlexRenderInputContent<
+          HeaderContext<TFeatures, TData, TValue>
+        >,
+        props: HeaderContext<TFeatures, TData, TValue>,
+      ]
+    | [content: null, props: null]
+  >(
+    () => {
+      const cell = this.cell()
+      const header = this.header()
+      const footer = this.footer()
+      if (cell) {
+        return [cell.column.columnDef.cell, cell.getContext()]
+      }
+      if (header) {
+        return [header.column.columnDef.header, header.getContext()]
+      }
+      if (footer) {
+        return [footer.column.columnDef.footer, footer.getContext()]
+      }
+      return [null, null]
+    },
+    {
+      equal: (a, b) => {
+        return a[0] === b[0] && a[1] === b[1]
+      },
+    },
+  )
+
+  readonly #injector = inject(Injector)
+  readonly #templateRef = inject(TemplateRef)
+  readonly #viewContainerRef = inject(ViewContainerRef)
+
+  constructor() {
+    const content = computed(() => this.#renderData()[0])
+    const props = computed(() => this.#renderData()[1])
+
+    const renderer = new FlexViewRenderer<TFeatures, TData, TValue, any>({
+      content: content,
+      props: props,
+      injector: () => this.#injector,
+      templateRef: this.#templateRef,
+      viewContainerRef: this.#viewContainerRef,
+    })
+
+    renderer.mount()
+
+    inject(DestroyRef).onDestroy(() => {
+      renderer.destroy()
+    })
+  }
+}