From 76dad3dd1ac08732b838dc8b76186b0e3d3d6e06 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Wed, 23 Sep 2026 01:26:22 -0400
Subject: [PATCH] Check each column's Cell and options, and keep the cell args
 of declared lists

- A column list with a declared type keeps its cell args, like it keeps
  its column meta. A shared component that takes
  `ColumnConfig<Row, unknown, unknown, CellArgs>[]` from its caller can
  build the table (johanrd/table#6).
- Each column written in place is checked on its own: its Cell takes the
  row type, the column's meta and the table meta, and when the Cell asks
  for `@options`, the column's `options` returns them.
- A table `meta` together with a callback that has parameters no longer
  loses the inferred cell args and column meta. The Cell check read the
  column list while TypeScript was still inferring it.
- `CellOptions` and `CellOptionsOf` are exported (johanrd/table#5).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../typing-meta-and-cells.gjs.md              |  35 +++++-
 .../-private/-type-tests/cell-args.test.ts    |  23 ++++
 .../-type-tests/declared-cell-args.test.ts    |  68 +++++++++++
 .../-type-tests/options-check.test.ts         | 109 ++++++++++++++++++
 table/src/-private/interfaces/column.ts       |  12 ++
 table/src/-private/interfaces/table.ts        |  26 ++---
 table/src/-private/js-helper.ts               |   2 +-
 table/src/-private/meta.ts                    |  57 ++++++++-
 table/src/index.ts                            |   2 +
 9 files changed, 312 insertions(+), 22 deletions(-)
 create mode 100644 table/src/-private/-type-tests/declared-cell-args.test.ts
 create mode 100644 table/src/-private/-type-tests/options-check.test.ts

diff --git a/docs-app/src/templates/1-get-started/typing-meta-and-cells.gjs.md b/docs-app/src/templates/1-get-started/typing-meta-and-cells.gjs.md
index f086ec3..302ed89 100644
--- a/docs-app/src/templates/1-get-started/typing-meta-and-cells.gjs.md
+++ b/docs-app/src/templates/1-get-started/typing-meta-and-cells.gjs.md
@@ -224,6 +224,20 @@ columns: () => [
 
 `column.getOptionsForRow` has the type of the `@options` that the Cells ask for, and the `defaultValue`.
 
+TypeScript checks each column that you write in place:
+a column whose Cell asks for `@options` must have an `options` that returns them.
+
+```ts
+columns: () => [
+  // error: `unit` is not a number
+  { key: "age", Cell: UnitCell, options: () => ({ unit: 3 }) },
+  // error: the Cell asks for `@options`, and this column has no `options`
+  { key: "height", Cell: UnitCell },
+],
+```
+
+To name the types of options in your own code, import `CellOptions` (what `options` returns) and `CellOptionsOf` (the `@options` of a Cell's args).
+
 ## Code that takes any table
 
 A function that accepts `Column<Person>` or `Table<Person>` accepts columns and tables with any meta and any cell args.
@@ -237,6 +251,24 @@ function exportWidthOf(column: Column<Person, { exportWidth?: number }>) {
 }
 ```
 
+## Shared table components
+
+A component that takes a column list from its caller and builds the table itself
+can pass its type arguments through.
+The table keeps the cell args, and the column metas, that the list declares:
+
+```ts
+import type { ColumnConfig } from "@universal-ember/table";
+
+function makeTable<Row, CellArgs>(
+  parent: object,
+  columns: ColumnConfig<Row, unknown, unknown, CellArgs>[],
+  data: Row[],
+) {
+  return headlessTable(parent, { columns: () => columns, data: () => data });
+}
+```
+
 ## Limits
 
 - In `value` and `options`, `column.meta` is `unknown`, because TypeScript cannot give it the inferred type there.
@@ -244,5 +276,4 @@ function exportWidthOf(column: Column<Person, { exportWidth?: number }>) {
 - An inline `<template>` Cell has no types for its args.
   To use `@row` or other args in it, move it into a constant with a `TOC` type, as in the examples above.
 - A function inside a `meta` needs types on its parameters.
-- TypeScript does not check that a column's `options` returns the `@options` its Cell asks for.
-  The return type of `options` is only known after the Cell types are fixed.
+- In a list with a declared type, `options` is not checked against the `@options` of the Cells.
diff --git a/table/src/-private/-type-tests/cell-args.test.ts b/table/src/-private/-type-tests/cell-args.test.ts
index 31e9c5c..28879e2 100644
--- a/table/src/-private/-type-tests/cell-args.test.ts
+++ b/table/src/-private/-type-tests/cell-args.test.ts
@@ -237,3 +237,26 @@ expectTypeOf(options.defaultValue).toEqualTypeOf<string>();
 expectTypeOf(plain.columns[0]!.getOptionsForRow(optionsRow)).toEqualTypeOf<{
   defaultValue: string;
 }>();
+
+/////////////////////////////////////////////
+// A table meta and a callback with parameters do not stop the inference
+const withMetaAndCallback = headlessTable(
+  {},
+  {
+    columns: () => [
+      { key: 'name', meta: { align: 'left' }, Cell: GroupedCell },
+      { key: 'age', value: ({ row }) => row.data.age },
+    ],
+    data: () => people,
+    meta: { currency: 'EUR' },
+  },
+);
+
+type MetaAndCallbackArgs = CellArgsOf<
+  (typeof withMetaAndCallback.columns)[0]['Cell']
+>;
+
+expectTypeOf<MetaAndCallbackArgs['groupBy']>().toEqualTypeOf<'day' | 'week'>();
+expectTypeOf(withMetaAndCallback.columns[0]!.meta?.align).toEqualTypeOf<
+  'left' | undefined
+>();
diff --git a/table/src/-private/-type-tests/declared-cell-args.test.ts b/table/src/-private/-type-tests/declared-cell-args.test.ts
new file mode 100644
index 0000000..0a09a86
--- /dev/null
+++ b/table/src/-private/-type-tests/declared-cell-args.test.ts
@@ -0,0 +1,68 @@
+import { expectTypeOf } from 'expect-type';
+
+import { headlessTable } from '../../index.ts';
+
+import type { CellContext, ColumnConfig } from '../../index.ts';
+import type { ComponentLike } from '@glint/template';
+
+interface Person {
+  name: string;
+}
+declare const people: Person[];
+
+interface GroupArgs {
+  groupBy: 'day' | 'week';
+}
+
+type CellArgsOf<Cell> =
+  NonNullable<Cell> extends ComponentLike<infer Args> ? Args : never;
+
+/////////////////////////////////////////////
+// A shared component takes a column list from its caller.
+// The cell args are a type parameter there, with no Cell to read them from.
+function makeTable<T, CellArgs>(
+  columns: ColumnConfig<T, unknown, unknown, CellArgs>[],
+  data: T[],
+) {
+  return headlessTable({}, { columns: () => columns, data: () => data });
+}
+
+declare const groupColumns: ColumnConfig<Person, unknown, unknown, GroupArgs>[];
+
+const shared = makeTable(groupColumns, people);
+
+expectTypeOf<
+  CellArgsOf<(typeof shared.columns)[0]['Cell']>['groupBy']
+>().toEqualTypeOf<'day' | 'week'>();
+
+/////////////////////////////////////////////
+// A declared list keeps its args, even when no Cell in it asks for them
+declare const PlainCell: ComponentLike<CellContext<Person>>;
+
+const declared: ColumnConfig<Person, unknown, unknown, GroupArgs>[] = [
+  { key: 'name', Cell: PlainCell },
+];
+const fromDeclared = headlessTable(
+  {},
+  { columns: () => declared, data: () => people },
+);
+
+expectTypeOf<
+  CellArgsOf<(typeof fromDeclared.columns)[0]['Cell']>['groupBy']
+>().toEqualTypeOf<'day' | 'week'>();
+
+/////////////////////////////////////////////
+// A list written in place still reads its Cells
+declare const GroupedCell: ComponentLike<CellContext<Person> & GroupArgs>;
+
+const inPlace = headlessTable(
+  {},
+  {
+    columns: () => [{ key: 'name', Cell: GroupedCell }, { key: 'plain' }],
+    data: () => people,
+  },
+);
+
+expectTypeOf<
+  CellArgsOf<(typeof inPlace.columns)[0]['Cell']>['groupBy']
+>().toEqualTypeOf<'day' | 'week'>();
diff --git a/table/src/-private/-type-tests/options-check.test.ts b/table/src/-private/-type-tests/options-check.test.ts
new file mode 100644
index 0000000..f090dd8
--- /dev/null
+++ b/table/src/-private/-type-tests/options-check.test.ts
@@ -0,0 +1,109 @@
+import { expectTypeOf } from 'expect-type';
+
+import { headlessTable } from '../../index.ts';
+
+import type {
+  CellContext,
+  CellOptions,
+  CellOptionsOf,
+  ColumnConfig,
+} from '../../index.ts';
+import type { ComponentLike } from '@glint/template';
+
+interface Person {
+  name: string;
+  age: number;
+}
+declare const people: Person[];
+
+interface Unit {
+  unit: string;
+}
+
+declare const UnitCell: ComponentLike<CellContext<Person> & { options: Unit }>;
+declare const PlainCell: ComponentLike<CellContext<Person>>;
+
+/////////////////////////////////////////////
+// A column whose Cell asks for `@options` gives them through its `options`
+headlessTable(
+  {},
+  {
+    columns: () => [
+      { key: 'age', Cell: UnitCell, options: () => ({ unit: 'years' }) },
+      { key: 'name', Cell: PlainCell },
+    ],
+    data: () => people,
+  },
+);
+
+headlessTable(
+  {},
+  {
+    columns: () => [
+      {
+        key: 'age',
+        Cell: UnitCell,
+        // @ts-expect-error `unit` is not a number
+        options: () => ({ unit: 3 }),
+      },
+    ],
+    data: () => people,
+  },
+);
+
+headlessTable(
+  {},
+  {
+    columns: () => [
+      // @ts-expect-error the Cell asks for `@options`, and the column has no `options`
+      { key: 'age', Cell: UnitCell },
+    ],
+    data: () => people,
+  },
+);
+
+headlessTable(
+  {},
+  {
+    columns: () => [
+      // @ts-expect-error the `options` of another column do not count
+      { key: 'age', Cell: UnitCell },
+      { key: 'name', options: () => ({ unit: 'years' }) },
+    ],
+    data: () => people,
+  },
+);
+
+// The callbacks still see the row, and the column metas are still inferred
+const withMeta = headlessTable(
+  {},
+  {
+    columns: () => [
+      {
+        key: 'age',
+        meta: { align: 'right' },
+        Cell: UnitCell,
+        options: ({ row }) => ({ unit: row.data.age > 1 ? 'years' : 'year' }),
+      },
+    ],
+    data: () => people,
+    meta: { currency: 'EUR' },
+  },
+);
+
+expectTypeOf(withMeta.columns[0]!.meta?.align).toEqualTypeOf<
+  'right' | undefined
+>();
+
+/////////////////////////////////////////////
+// The option types can be named
+const unitOptions = (context: CellContext<Person>): CellOptions => ({
+  unit: context.row.data.age > 1 ? 'years' : 'year',
+});
+
+const declared: ColumnConfig<Person>[] = [{ key: 'age', options: unitOptions }];
+
+expectTypeOf<CellOptionsOf<{ options: Unit }>>().toEqualTypeOf<Unit>();
+expectTypeOf<CellOptionsOf<{ groupBy: 'day' }>>().toEqualTypeOf<unknown>();
+
+void declared;
diff --git a/table/src/-private/interfaces/column.ts b/table/src/-private/interfaces/column.ts
index 0fee553..225ed64 100644
--- a/table/src/-private/interfaces/column.ts
+++ b/table/src/-private/interfaces/column.ts
@@ -7,6 +7,9 @@ import type { Constructor } from '../private-types';
 import type { ComponentLike, ContentValue } from '@glint/template';
 
 declare const rowType: unique symbol;
+declare const cellArgsType: unique symbol;
+
+export type { cellArgsType };
 
 /**
  * What `value`, `options`, and a `Cell` receive.
@@ -113,6 +116,15 @@ export interface ColumnConfig<
    * gives `headlessTable` a row type that depends on the order TypeScript checks the program in.
    */
   readonly [rowType]?: T;
+
+  /**
+   * Type-only, never set.
+   *
+   * A column list with a declared type has no Cells to read the args from,
+   * for example a list that a shared component takes as an argument.
+   * The args it declares are read from here.
+   */
+  readonly [cellArgsType]?: CellArgs;
 }
 
 export type ColumnKey<T> = NonNullable<ColumnConfig<T>['key']>;
diff --git a/table/src/-private/interfaces/table.ts b/table/src/-private/interfaces/table.ts
index 70f6b0d..2af7ddb 100644
--- a/table/src/-private/interfaces/table.ts
+++ b/table/src/-private/interfaces/table.ts
@@ -1,6 +1,6 @@
 import type { Plugins } from '../../plugins/-private/utils';
 import type { ColumnConfig } from './column';
-import type { CellArgsOf } from '../meta.ts';
+import type { ColumnCheck } from '../meta.ts';
 import type { Pagination } from './pagination';
 import type { PreferencesAdapter } from './preferences';
 import type { Selection } from './selection';
@@ -154,15 +154,13 @@ export interface TableConfig<DataType, Meta = unknown> {
  *
  * `Columns` is the column list as written.
  * The extra args of its Cells are read from it,
- * and every Cell is checked against all of them.
+ * and each column of it is checked on its own, see `ColumnCheck`.
  *
  * `TableConfig` stays a plain interface,
  * for code that annotates a config or reads `table.config`.
  *
- * The plain list next to the mapped one lets TypeScript infer `DataType`
- * from the columns too, which the mapped list alone does not.
- * Its column meta is `any`, so that Cells that read a meta fit it.
- * The mapped list checks each column's meta.
+ * The plain list lets TypeScript infer `DataType` from the columns too,
+ * which the mapped list alone does not.
  */
 export type HeadlessTableConfig<
   DataType,
@@ -176,12 +174,12 @@ export type HeadlessTableConfig<
    * to set the behavior of columns when rendered
    */
   columns: () => {
-    [K in keyof ColumnMetas]: ColumnConfig<
-      DataType,
-      ColumnMetas[K],
-      Meta,
-      NoInfer<CellArgsOf<Columns>>
-    >;
-  } & Columns &
-    readonly ColumnConfig<DataType, any, Meta, any>[];
+    [K in keyof ColumnMetas]: ColumnConfig<DataType, ColumnMetas[K], Meta, any>;
+  } & Columns & {
+      [K in Extract<keyof Columns, `${number}`>]: ColumnCheck<
+        DataType,
+        Meta,
+        Columns[K]
+      >;
+    } & readonly ColumnConfig<DataType, any, Meta, any>[];
 };
diff --git a/table/src/-private/js-helper.ts b/table/src/-private/js-helper.ts
index ac66473..536ec21 100644
--- a/table/src/-private/js-helper.ts
+++ b/table/src/-private/js-helper.ts
@@ -29,7 +29,7 @@ export function headlessTable<
   T = unknown,
   const ColumnMetas extends unknown[] = unknown[],
   Meta = unknown,
-  Columns extends readonly unknown[] = readonly unknown[],
+  const Columns extends readonly unknown[] = readonly unknown[],
 >(
   parent: object,
   options: HeadlessTableConfig<T, ColumnMetas, Meta, Columns>,
diff --git a/table/src/-private/meta.ts b/table/src/-private/meta.ts
index 0c43e16..3604505 100644
--- a/table/src/-private/meta.ts
+++ b/table/src/-private/meta.ts
@@ -4,6 +4,8 @@ import type {
   UnwrapNamedArgs,
 } from '@glint/template/-private/integration';
 import type { ComponentSignatureArgs } from '@glint/template/-private/signature';
+import type { CellContext, cellArgsType } from './interfaces/column.ts';
+import type { ComponentLike } from '@glint/template';
 
 /**
  * The metas of columns that set one.
@@ -94,11 +96,22 @@ type UnionToIntersection<U> = (
  *   [{ Cell: GroupByCell }, { Cell: UpdateCell }]
  *   → { groupBy: ... } & { onUpdate: ... }
  */
-export type CellArgsOf<Columns extends readonly unknown[]> = [
-  ProvidedCells<Columns>,
-] extends [never]
-  ? unknown
-  : UnionToIntersection<ExtraArgsOf<ProvidedCells<Columns>>>;
+export type CellArgsOf<Columns extends readonly unknown[]> =
+  typeof cellArgsType extends keyof Columns[number]
+    ? DeclaredCellArgs<Columns[number]>
+    : [ProvidedCells<Columns>] extends [never]
+      ? unknown
+      : UnionToIntersection<ExtraArgsOf<ProvidedCells<Columns>>>;
+
+/**
+ * The cell args of a column list with a declared type.
+ * Object literals do not have the key, so a list written in place reads its Cells.
+ */
+type DeclaredCellArgs<Column> = Column extends {
+  readonly [cellArgsType]?: infer CellArgs;
+}
+  ? CellArgs
+  : unknown;
 
 /**
  * The `@options` the Cells of a table ask for, from their args.
@@ -109,3 +122,37 @@ export type CellOptionsOf<CellArgs> = CellArgs extends {
 }
   ? Options
   : unknown;
+
+/**
+ * What a column written in place must fit, given its own `Cell`:
+ *
+ * - the Cell takes the row type, this column's `meta`, and the table's `meta`
+ * - when the Cell asks for `@options`, the column's `options` returns them
+ *
+ * Each column is checked on its own, once the column list is inferred.
+ * A check that reads the whole list while it is being inferred would see it empty.
+ */
+export type ColumnCheck<DataType, Meta, Column> = Column extends {
+  Cell?: infer Cell;
+}
+  ? unknown extends Cell
+    ? unknown
+    : CellCheck<DataType, Meta, Column, NonNullable<Cell>> &
+        OptionsCheck<NonNullable<Cell>>
+  : unknown;
+
+type CellCheck<DataType, Meta, Column, Cell> = {
+  Cell?: ComponentLike<
+    CellContext<
+      DataType,
+      Column extends { meta: infer ColumnMeta } ? ColumnMeta : unknown,
+      Meta
+    > &
+      ExtraArgsOf<Cell>
+  >;
+};
+
+type OptionsCheck<Cell> =
+  NamedArgsOf<Cell> extends { options: infer Options }
+    ? { options: (...args: any[]) => Omit<Options, 'defaultValue'> }
+    : unknown;
diff --git a/table/src/index.ts b/table/src/index.ts
index af8b79b..7d8a971 100644
--- a/table/src/index.ts
+++ b/table/src/index.ts
@@ -13,6 +13,7 @@ export { deserializeSorts, serializeSorts } from './utils.ts';
 export type { Column } from './-private/column.ts';
 export type {
   CellContext,
+  CellOptions,
   ColumnConfig,
   ColumnKey,
   HeadlessTableConfig,
@@ -23,5 +24,6 @@ export type {
   TableConfig,
   TableMeta,
 } from './-private/interfaces/index.ts';
+export type { CellOptionsOf } from './-private/meta.ts';
 export type { Row } from './-private/row.ts';
 export type { Table } from './-private/table.ts';