@colspec/tanstack 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Om Prakash Das
+
+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

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @colspec/tanstack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turns a [colspec](https://github.com/Om1938/colspec) contract into native
+TanStack Table v9 column definitions and table options. Framework-independent:
+use it with any TanStack Table adapter.
+
+```sh
+npm install @colspec/tanstack @colspec/core @tanstack/table-core
+```
+
+## Usage
+
+Register the functions contracts may refer to, once:
+
+```ts
+import { createTableRegistry } from "@colspec/tanstack";
+
+const registry = createTableRegistry<Product>({
+  accessorFns: { "inventory.brandModel": (row) => `${row.brand} ${row.model}` },
+  cells: { "inventory.statusBadge": ({ getValue }) => renderBadge(getValue()) },
+  formatters: {
+    "inventory.date": (value: string) => new Date(value).toLocaleDateString(),
+  },
+});
+```
+
+Then hydrate a validated contract:
+
+```ts
+import { hydrateContract } from "@colspec/tanstack";
+
+const result = hydrateContract<typeof features, Product>(contract, registry);
+
+if (result.ok) {
+  const { columns, options } = result.value;
+  // columns: ColumnDef[]
+  // options: { initialState, manualSorting, manualFiltering, manualPagination }
+}
+```
+
+## How names resolve
+
+| In the contract                              | Resolves to                               |
+| -------------------------------------------- | ----------------------------------------- |
+| `"sortFn": "alphanumeric"`                   | TanStack's built-in function of that name |
+| `"sortFn": "auto"`                           | Passed through; TanStack chooses          |
+| `"cell": { "ref": "inventory.statusBadge" }` | Your registered function                  |
+| `"header": "Name"`                           | Literal text                              |
+
+A name that can't be found produces a `missing-reference` or `unknown-builtin`
+diagnostic. colspec never substitutes a different function, and never executes
+anything stored in a contract.
+
+Results are memoized by contract and registry identity, so `columns` stays
+stable between renders as long as you keep the same contract object.
+
+## Registry categories
+
+`sortFns`, `filterFns`, `aggregationFns`, `accessorFns`, `cells`, `headers`
+(also used for footers), `formatters`, `actions`.
+
+## Features
+
+`defaultFeatures` is a ready-made TanStack feature set covering sorting,
+filtering, pagination, visibility and sizing. Pass your own `tableFeatures()`
+to add grouping or pinning, or to ship less.
+
+Requires `@tanstack/table-core` 9.
+
+[Documentation](https://github.com/Om1938/colspec/tree/main/apps/docs/guide) · MIT

package/dist/index.d.mts

@@ -0,0 +1,87 @@
+import { AccessorFn, AggregationFnDef, CellContext, ColumnDef, FilterFn, HeaderContext, RowData, SortFn, TableFeatures } from "@tanstack/table-core";
+import { ContractDefaults, Registry, RegistryInput, Result, TableContract } from "@colspec/core";
+//#region src/features.d.ts
+/**
+ * A ready-made feature set covering everything a contract can configure.
+ * Pass your own `tableFeatures(...)` instead to ship only what a table uses.
+ */
+export declare const defaultFeatures: {
+  rowSortingFeature: import("@tanstack/table-core").TableFeature;
+  columnFilteringFeature: import("@tanstack/table-core").TableFeature;
+  rowPaginationFeature: import("@tanstack/table-core").TableFeature;
+  columnVisibilityFeature: import("@tanstack/table-core").TableFeature;
+  columnSizingFeature: import("@tanstack/table-core").TableFeature;
+  sortedRowModel: (table: import("@tanstack/table-core").Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  filteredRowModel: (table: import("@tanstack/table-core").Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  paginatedRowModel: (table: import("@tanstack/table-core").Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  sortFns: {
+    alphanumeric: import("@tanstack/table-core").CreatedSortFn<any, any>;
+    alphanumericCaseSensitive: import("@tanstack/table-core").CreatedSortFn<any, any>;
+    basic: import("@tanstack/table-core").CreatedSortFn<any, any>;
+    datetime: import("@tanstack/table-core").CreatedSortFn<any, any>;
+    text: import("@tanstack/table-core").CreatedSortFn<any, any>;
+    textCaseSensitive: import("@tanstack/table-core").CreatedSortFn<any, any>;
+  };
+  filterFns: {
+    arrIncludes: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    arrIncludesAll: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    arrHas: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    arrIncludesSome: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    between: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    betweenInclusive: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    empty: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    endsWith: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    equals: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    equalsString: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    equalsStringSensitive: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    inDateRange: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    inNumberRange: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    includesString: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    includesStringSensitive: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    notEmpty: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    startsWith: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+    weakEquals: import("@tanstack/table-core").CreatedFilterFn<any, any>;
+  };
+};
+export type DefaultFeatures = typeof defaultFeatures;
+//#endregion
+//#region src/registry.d.ts
+/** The function types each registry category holds for TanStack Table. */
+export interface TableRegistryEntries<TData extends RowData = any> {
+  sortFns: SortFn<any, TData>;
+  filterFns: FilterFn<any, TData>;
+  accessorFns: AccessorFn<TData>;
+  cells: (context: CellContext<any, TData, any>) => unknown;
+  /** Used for both `header` and `footer`. */
+  headers: (context: HeaderContext<any, TData, any>) => unknown;
+  formatters: (value: any) => unknown;
+  actions: (row: TData) => unknown;
+  aggregationFns: AggregationFnDef<any, TData, any, any>;
+}
+export type TableRegistry<TData extends RowData = any> = Registry<TableRegistryEntries<TData>>;
+/** `createRegistry` typed for TanStack Table functions over `TData` rows. */
+export declare function createTableRegistry<TData extends RowData>(input?: RegistryInput<TableRegistryEntries<TData>>): TableRegistry<TData>;
+//#endregion
+//#region src/table-options.d.ts
+/** Table options a contract controls besides its columns. */
+export interface ContractTableOptions {
+  initialState: ContractDefaults;
+  manualSorting: boolean;
+  manualFiltering: boolean;
+  manualPagination: boolean;
+}
+/** Maps contract defaults and execution modes onto TanStack table options. */
+export declare function toTableOptions(contract: TableContract): ContractTableOptions;
+//#endregion
+//#region src/hydrate.d.ts
+export interface HydratedContract<TFeatures extends TableFeatures, TData extends RowData> {
+  columns: Array<ColumnDef<TFeatures, TData>>;
+  options: ContractTableOptions;
+}
+/**
+ * Converts a validated contract into TanStack column definitions and table
+ * options. The result is memoized per registry and contract object, so the
+ * columns keep a stable identity between renders.
+ */
+export declare function hydrateContract<TFeatures extends TableFeatures = any, TData extends RowData = any>(contract: TableContract, registry: TableRegistry<TData>): Result<HydratedContract<TFeatures, TData>>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,143 @@
+import { aggregationFns, columnFilteringFeature, columnSizingFeature, columnVisibilityFeature, createFilteredRowModel, createPaginatedRowModel, createSortedRowModel, filterFns, rowPaginationFeature, rowSortingFeature, sortFns, tableFeatures } from "@tanstack/table-core";
+import { createRegistry, getMode, isRef, toResult } from "@colspec/core";
+//#region src/features.ts
+/**
+* A ready-made feature set covering everything a contract can configure.
+* Pass your own `tableFeatures(...)` instead to ship only what a table uses.
+*/
+const defaultFeatures = tableFeatures({
+	rowSortingFeature,
+	columnFilteringFeature,
+	rowPaginationFeature,
+	columnVisibilityFeature,
+	columnSizingFeature,
+	sortedRowModel: createSortedRowModel(),
+	filteredRowModel: createFilteredRowModel(),
+	paginatedRowModel: createPaginatedRowModel(),
+	sortFns,
+	filterFns
+});
+//#endregion
+//#region src/hydrate-columns.ts
+/** Drops unset keys so they cannot shadow TanStack's column defaults. */
+function defined(values) {
+	return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== void 0));
+}
+function hydrateColumn(column, index, resolve) {
+	const { accessorFn, header, footer, cell, formatter, actions, sortFn, filterFn, aggregationFn, meta, server: _server, ...serializable } = column;
+	const at = (key, ...rest) => [
+		"columns",
+		index,
+		key,
+		...rest
+	];
+	const format = resolve.ref("formatters", formatter, at("formatter"));
+	const handlers = actions?.map((action, actionIndex) => [action.ref, resolve.ref("actions", action, at("actions", actionIndex))]);
+	return {
+		...serializable,
+		...defined({
+			accessorFn: resolve.ref("accessorFns", accessorFn, at("accessorFn")),
+			header: resolve.template("headers", header, at("header")),
+			footer: resolve.template("headers", footer, at("footer")),
+			cell: resolve.ref("cells", cell, at("cell")) ?? (format && ((context) => format(context.getValue()))),
+			sortFn: resolve.named("sortFns", sortFn, at("sortFn")),
+			filterFn: resolve.named("filterFns", filterFn, at("filterFn")),
+			aggregationFn: resolve.named("aggregationFns", aggregationFn, at("aggregationFn")),
+			meta: meta || handlers ? {
+				...meta,
+				...handlers && { actions: Object.fromEntries(handlers) }
+			} : void 0
+		})
+	};
+}
+/** Converts contract columns into native TanStack column definitions. */
+function hydrateColumns(columns, resolve) {
+	return columns.map((column, index) => hydrateColumn(column, index, resolve));
+}
+//#endregion
+//#region src/resolve.ts
+/** Functions TanStack ships, addressable from a contract by plain name. */
+const BUILTINS = {
+	sortFns,
+	filterFns,
+	aggregationFns
+};
+/** Lets TanStack pick a function from the column's data. */
+const AUTO = "auto";
+/**
+* Looks names up in the registry or TanStack's built-ins. A name that cannot
+* be found is reported and never replaced with another function.
+*/
+function createResolver(registry, diagnostics) {
+	function lookup(source, category, name, path, code) {
+		if (Object.hasOwn(source, name)) return source[name];
+		diagnostics.push({
+			code,
+			severity: "error",
+			path,
+			message: `"${name}" was not found in ${category}.`
+		});
+	}
+	/** Resolves a reference to an application-registered function. */
+	function ref(category, value, path) {
+		return value && lookup(registry[category], category, value.ref, path, "missing-reference");
+	}
+	/** Resolves a built-in name, `"auto"`, or a reference. */
+	function named(category, value, path) {
+		if (value === void 0 || value === AUTO) return value;
+		if (isRef(value)) return ref(category, value, path);
+		return lookup(BUILTINS[category] ?? {}, category, value, path, "unknown-builtin");
+	}
+	/** Resolves a renderer reference, passing literal text through. */
+	function template(category, value, path) {
+		return typeof value === "string" ? value : ref(category, value, path);
+	}
+	return {
+		ref,
+		named,
+		template
+	};
+}
+//#endregion
+//#region src/table-options.ts
+/** Maps contract defaults and execution modes onto TanStack table options. */
+function toTableOptions(contract) {
+	const mode = getMode(contract);
+	return {
+		initialState: contract.defaults ?? {},
+		manualSorting: mode.sorting === "server",
+		manualFiltering: mode.filtering === "server",
+		manualPagination: mode.pagination === "server"
+	};
+}
+//#endregion
+//#region src/hydrate.ts
+const cache = /* @__PURE__ */ new WeakMap();
+/**
+* Converts a validated contract into TanStack column definitions and table
+* options. The result is memoized per registry and contract object, so the
+* columns keep a stable identity between renders.
+*/
+function hydrateContract(contract, registry) {
+	let byContract = cache.get(registry);
+	if (!byContract) cache.set(registry, byContract = /* @__PURE__ */ new WeakMap());
+	let result = byContract.get(contract);
+	if (!result) {
+		const diagnostics = [];
+		const columns = hydrateColumns(contract.columns, createResolver(registry, diagnostics));
+		result = toResult({
+			columns,
+			options: toTableOptions(contract)
+		}, diagnostics);
+		byContract.set(contract, result);
+	}
+	return result;
+}
+//#endregion
+//#region src/registry.ts
+/** `createRegistry` typed for TanStack Table functions over `TData` rows. */
+function createTableRegistry(input = {}) {
+	return createRegistry(input);
+}
+//#endregion
+export { createTableRegistry, defaultFeatures, hydrateContract, toTableOptions };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@colspec/tanstack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "peerDependencies": {
+    "@tanstack/table-core": "^9.2.6"
+  },
+  "dependencies": {
+    "@colspec/core": "0.1.1"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0",
+    "@tanstack/table-core": "^9.2.6"
+  },
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "description": "Hydrate colspec JSON contracts into native TanStack Table v9 column definitions and table options.",
+  "author": "Om Prakash Das",
+  "homepage": "https://github.com/Om1938/colspec/tree/main/packages/tanstack#readme",
+  "bugs": {
+    "url": "https://github.com/Om1938/colspec/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Om1938/colspec.git",
+    "directory": "packages/tanstack"
+  },
+  "keywords": [
+    "tanstack-table",
+    "tanstack",
+    "table",
+    "datagrid",
+    "dynamic-columns",
+    "colspec",
+    "column-def hydration"
+  ],
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "build": "tsdown",
+    "test": "vitest run",
+    "check-types": "tsc --noEmit"
+  }
 }