@octanejs/tanstack-table 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @octanejs/tanstack-table
+
+[TanStack Table](https://tanstack.com/table) for the [octane](https://github.com/octanejs/octane) UI framework.
+
+TanStack Table separates a framework-agnostic core (`@tanstack/table-core`:
+`createTable` plus every feature row model — sorting, filtering, pagination,
+selection, visibility, expanding, grouping, faceting, …) from a ~100-line React
+adapter (`useReactTable` + `flexRender`). This package reuses the core
+unchanged (re-exported verbatim) and transcribes only the adapter onto octane's
+hooks, preserving upstream's exact `useState`-based state wiring. The public
+surface matches `@tanstack/react-table` 1:1 — existing code works by changing
+the import.
+
+```tsx
+// before
+import { useReactTable, flexRender, getCoreRowModel } from '@tanstack/react-table';
+// after
+import { useReactTable, flexRender, getCoreRowModel } from '@octanejs/tanstack-table';
+
+function People() @{
+  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+  <table>
+    <thead>
+      @for (const hg of table.getHeaderGroups(); key hg.id) {
+        <tr>
+          @for (const header of hg.headers; key header.id) {
+            <th onClick={header.column.getToggleSortingHandler()}>
+              {header.isPlaceholder
+                ? null
+                : flexRender(header.column.columnDef.header, header.getContext())}
+            </th>
+          }
+        </tr>
+      }
+    </thead>
+    <tbody>
+      @for (const row of table.getRowModel().rows; key row.id) {
+        <tr>
+          @for (const cell of row.getVisibleCells(); key cell.id) {
+            <td>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
+          }
+        </tr>
+      }
+    </tbody>
+  </table>
+}
+```
+
+## Entry points
+
+| import | what you get | notes |
+| --- | --- | --- |
+| `@octanejs/tanstack-table` | everything `@tanstack/table-core` exports + `useReactTable`, `flexRender`, `Renderable` | core verbatim + the octane-bound adapter (single entry, mirroring upstream) |
+
+## How it works
+
+`useReactTable` is a line-for-line transcription of the upstream adapter: the
+table instance is created once, its state lives in a `useState` whose setter is
+wired into `onStateChange`, and options are re-composed into the instance
+during every render — so partially-controlled state (`state.sorting` +
+`onSortingChange`), full `onStateChange` passthrough, and table-core's
+functional `Updater<T>` contract behave exactly as on React.
+
+`flexRender` triages a columnDef renderer: components render through octane's
+`createElement` descriptor at value position; strings, numbers, and pre-created
+elements pass through as-is. Upstream's class-component and
+`react.memo`/`forwardRef` exotic-object branches are dropped — octane has no
+class components or `forwardRef`, and octane's `memo()` returns a plain
+function, so `typeof === 'function'` covers every component.
+
+octane keys hooks by a compiler-injected per-call-site `Symbol`, appended as
+the last argument of every `use*` call. `useReactTable` forwards that slot into
+its composed hooks, so two tables in one component stay independent, exactly
+like in React.
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@octanejs/tanstack-table",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "TanStack Table bindings for the octane renderer — reuses the framework-agnostic @tanstack/table-core and swaps the ~100-line React adapter (useReactTable, flexRender) for an octane port.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-table"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/table-core": "8.21.3",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "@tanstack/react-table": "8.21.3",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+// @octanejs/tanstack-table — TanStack Table for the octane renderer.
+//
+// TanStack Table separates a framework-agnostic core (`@tanstack/table-core`:
+// createTable + every feature row model) from a ~100-line React adapter
+// (`useReactTable` + `flexRender`). This package reuses the core UNCHANGED
+// (re-exported verbatim) and transcribes only the adapter onto octane's hooks,
+// preserving upstream's exact useState-based shape — the table instance is
+// created once, state lives in a useState whose setter is wired into the
+// instance's onStateChange, and options are re-composed into the instance
+// during every render. The public surface matches @tanstack/react-table 1:1:
+// existing code works by changing the import.
+//
+// The one octane-specific detail is hook slots: octane keys hooks by a
+// compiler-injected per-call-site Symbol, appended as the LAST argument of
+// every `use*` call. `useReactTable` forwards that slot into its two useState
+// calls (deriving a stable sub-slot for each), so two tables in one component
+// stay independent, just like in React.
+import { createElement, useState } from 'octane';
+import type { ComponentBody, ElementDescriptor } from 'octane';
+import { createTable } from '@tanstack/table-core';
+import type { RowData, TableOptions, TableOptionsResolved } from '@tanstack/table-core';
+import { splitSlot, subSlot } from './internal';
+
+export * from '@tanstack/table-core';
+
+export type Renderable<TProps> =
+	| ComponentBody<TProps>
+	| ElementDescriptor<any>
+	| string
+	| number
+	| boolean
+	| null
+	| undefined;
+
+/**
+ * If rendering headers, cells, or footers with custom markup, use flexRender
+ * instead of `cell.getValue()` or `cell.renderValue()`.
+ *
+ * Port note: upstream additionally detects class components and
+ * `react.memo`/`react.forward_ref` exotic objects. Both branches are dead in
+ * octane — there are no class components or forwardRef, and octane's `memo()`
+ * returns a plain function — so a component is exactly `typeof === 'function'`.
+ * The descriptor `createElement` returns renders at value position (a `.tsrx`
+ * hole); non-component values (strings, numbers, pre-created descriptors)
+ * pass through as-is.
+ */
+export function flexRender<TProps extends object>(Comp: Renderable<TProps>, props: TProps) {
+	return !Comp
+		? null
+		: typeof Comp === 'function'
+			? createElement(Comp as ComponentBody<TProps>, props)
+			: Comp;
+}
+
+export function useReactTable<TData extends RowData>(
+	options: TableOptions<TData>,
+	...rest: unknown[]
+) {
+	const [, slot] = splitSlot(rest);
+
+	// Compose in the generic options to the user options
+	const resolvedOptions: TableOptionsResolved<TData> = {
+		state: {}, // Dummy state
+		onStateChange: () => {}, // noop
+		renderFallbackValue: null,
+		...options,
+	};
+
+	// Create a new table and store it in state
+	const [tableRef] = useState(
+		() => ({
+			current: createTable<TData>(resolvedOptions),
+		}),
+		subSlot(slot, 'urt:t'),
+	);
+
+	// By default, manage table state here using the table's initial state
+	const [state, setState] = useState(() => tableRef.current.initialState, subSlot(slot, 'urt:s'));
+
+	// Compose the default state above with any user state. This will allow the user
+	// to only control a subset of the state if desired.
+	tableRef.current.setOptions((prev) => ({
+		...prev,
+		...options,
+		state: {
+			...state,
+			...options.state,
+		},
+		// Similarly, we'll maintain both our internal state and any user-provided
+		// state.
+		onStateChange: (updater) => {
+			setState(updater);
+			options.onStateChange?.(updater);
+		},
+	}));
+
+	return tableRef.current;
+}

package/src/internal.ts

@@ -0,0 +1,37 @@
+// Slot mechanics shared by the binding's plain-`.ts` hooks (same helper as
+// @octanejs/tanstack-query). The octane compiler injects a per-call-site Symbol slot into
+// every hook call in compiled files; these binding files are NOT compiled, so a
+// hook here receives the caller's slot as its trailing argument and derives a
+// distinct sub-slot for each base hook it composes.
+
+// Memoized: subSlot runs on EVERY hook call every render; the cache returns the
+// identical Symbol.for-interned value without the concat + registry lookup.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+// Tag-only symbols for the slotless-caller case (see below).
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	// No inherited slot (the caller was NOT compiled — e.g. a vendored wrapper
+	// hook): return a stable TAG-ONLY symbol rather than undefined. The runtime
+	// combines it with the ambient withSlot path, so sibling base hooks inside
+	// one composed hook stay DISTINCT per tag. Returning undefined here made
+	// them all resolve to the bare path — one shared slot, state collision.
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(':' + tag)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) byTag.set(tag, (sym = Symbol.for((slot.description ?? '') + ':' + tag)));
+	return sym;
+}
+
+// Split the compiler-injected trailing slot off a hook's runtime args, returning
+// the user args (everything before it) and the slot.
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}