@kitr/table 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+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,15 @@
-# Temporary Holding Version
+# @kitr/table
 
-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.
+**Tables.** Show rows of data with sorting, paging and filters that stay in the URL.
+
+```sh
+pnpm kitr add table
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/table`.
+
+Built on @tanstack/react-table.
+
+Read the guide at https://kitr.dev/packages/table.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { ColumnFiltersState, PaginationState, SortingState, Updater } from "@tanstack/react-table";
+export * from "@tanstack/react-table";
+/**
+ * The feature set kitr's DataTable and `useUrlTableState` assume: sorting,
+ * pagination, column filters and column visibility. TanStack Table v9 is feature-sliced, so a
+ * table only ships the code for the features you register. Extend with
+ * `tableFeatures({ ...dataTableFeatures, rowSelectionFeature })`.
+ */
+export declare const dataTableFeatures: {
+  rowSortingFeature: import("@tanstack/react-table").TableFeature;
+  rowPaginationFeature: import("@tanstack/react-table").TableFeature;
+  columnFilteringFeature: import("@tanstack/react-table").TableFeature;
+  columnVisibilityFeature: import("@tanstack/react-table").TableFeature;
+};
+/** The type of `dataTableFeatures`, for `ColumnDef<DataTableFeatures, Order>` and `useTable` generics. */
+export type DataTableFeatures = typeof dataTableFeatures;
+/**
+ * `dataTableFeatures` plus the browser-side row models: for a list that arrives in one response,
+ * the table sorts, filters and pages it itself. Turn the manual flags off with it
+ * (`useUrlTableState({ ..., manual: false })` does), or nothing changes when a header is clicked.
+ */
+export declare const clientTableFeatures: {
+  sortedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+  paginatedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+  filteredRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+  sortFns: {
+    alphanumeric: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    text: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    datetime: import("@tanstack/react-table").CreatedSortFn<any, any>;
+    basic: import("@tanstack/react-table").CreatedSortFn<any, any>;
+  };
+  filterFns: {
+    includesString: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    equalsString: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    equals: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    weakEquals: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    inNumberRange: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    arrIncludes: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    arrIncludesAll: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+    arrIncludesSome: import("@tanstack/react-table").CreatedFilterFn<any, any>;
+  };
+  rowSortingFeature: import("@tanstack/react-table").TableFeature;
+  rowPaginationFeature: import("@tanstack/react-table").TableFeature;
+  columnFilteringFeature: import("@tanstack/react-table").TableFeature;
+  columnVisibilityFeature: import("@tanstack/react-table").TableFeature;
+};
+/** The type of `clientTableFeatures`. */
+export type ClientTableFeatures = typeof clientTableFeatures;
+/** The search-param shape kitr tables use. Add it to your route's `validateSearch`. */
+export interface TableSearch {
+  /** One-based page number. Absent means page 1. */
+  page?: number;
+  /** Rows per page. Absent means the default page size. */
+  size?: number;
+  /** Sort columns, comma-separated, `-` for descending: `-total,customer`. */
+  sort?: string;
+  /** Column filters as column id to string value: `{ status: 'open' }`. */
+  filter?: Record<string, string>;
+}
+/** Options for `useUrlTableState`: the route's current search, a way to change it and the page size. */
+export interface UrlTableStateOptions {
+  /** The current table search params, usually `Route.useSearch()`. */
+  search: TableSearch;
+  /** Merge a patch into the URL, e.g. `(patch) => navigate({ search: (s) => ({ ...s, ...patch }) })`. */
+  setSearch: (patch: Partial<TableSearch>) => void;
+  /** Rows per page when the URL has no `size`, and the size left out of the URL. Default 20. */
+  defaultPageSize?: number;
+  /**
+   * `true` (default): the server sorts, filters and pages, the table shows what came back.
+   * `false`: the table does it in the browser; use it with `clientTableFeatures`.
+   */
+  manual?: boolean;
+}
+/**
+ * Bind sorting, pagination and column filters to URL search params so a
+ * filtered view is shareable by link. Router-agnostic; pass the route's search
+ * and a setter. Spread the result into `useTable` (with `dataTableFeatures` or a superset).
+ */
+export declare function useUrlTableState({ search, setSearch, defaultPageSize, manual }: UrlTableStateOptions): {
+  state: {
+    sorting: SortingState;
+    pagination: PaginationState;
+    columnFilters: ColumnFiltersState;
+  };
+  onSortingChange: (updater: Updater<SortingState>) => void;
+  onPaginationChange: (updater: Updater<PaginationState>) => void;
+  onColumnFiltersChange: (updater: Updater<ColumnFiltersState>) => void;
+  manualSorting: boolean;
+  manualPagination: boolean;
+  manualFiltering: boolean;
+};
+/** `-name,createdAt` ⇄ `[{ id: 'name', desc: true }, { id: 'createdAt', desc: false }]` */
+export declare function parseSort(sort?: string): SortingState;
+/** Turns TanStack's sorting state into the URL's `sort` string: `[{ id: 'total', desc: true }]` becomes `-total`. */
+export declare function formatSort(sorting: SortingState): string;
+/** Validate raw search params into `TableSearch`. Plug into `validateSearch` or wrap with zod. */
+export declare function parseTableSearch(raw: Record<string, unknown>): TableSearch;

package/dist/index.js

@@ -0,0 +1,135 @@
+import { columnFilteringFeature, columnVisibilityFeature, createFilteredRowModel, createPaginatedRowModel, createSortedRowModel, filterFn_arrIncludes, filterFn_arrIncludesAll, filterFn_arrIncludesSome, filterFn_equals, filterFn_equalsString, filterFn_inNumberRange, filterFn_includesString, filterFn_weakEquals, rowPaginationFeature, rowSortingFeature, sortFn_alphanumeric, sortFn_basic, sortFn_datetime, sortFn_text, tableFeatures } from "@tanstack/react-table";
+import { useCallback, useMemo } from "react";
+export * from "@tanstack/react-table";
+// src/features.ts
+/**
+* The feature set kitr's DataTable and `useUrlTableState` assume: sorting,
+* pagination, column filters and column visibility. TanStack Table v9 is feature-sliced, so a
+* table only ships the code for the features you register. Extend with
+* `tableFeatures({ ...dataTableFeatures, rowSelectionFeature })`.
+*/
+const dataTableFeatures = tableFeatures({
+	rowSortingFeature,
+	rowPaginationFeature,
+	columnFilteringFeature,
+	columnVisibilityFeature
+});
+/**
+* `dataTableFeatures` plus the browser-side row models: for a list that arrives in one response,
+* the table sorts, filters and pages it itself. Turn the manual flags off with it
+* (`useUrlTableState({ ..., manual: false })` does), or nothing changes when a header is clicked.
+*/
+const clientTableFeatures = tableFeatures({
+	...dataTableFeatures,
+	sortedRowModel: createSortedRowModel(),
+	paginatedRowModel: createPaginatedRowModel(),
+	filteredRowModel: createFilteredRowModel(),
+	sortFns: {
+		alphanumeric: sortFn_alphanumeric,
+		text: sortFn_text,
+		datetime: sortFn_datetime,
+		basic: sortFn_basic
+	},
+	filterFns: {
+		includesString: filterFn_includesString,
+		equalsString: filterFn_equalsString,
+		equals: filterFn_equals,
+		weakEquals: filterFn_weakEquals,
+		inNumberRange: filterFn_inNumberRange,
+		arrIncludes: filterFn_arrIncludes,
+		arrIncludesAll: filterFn_arrIncludesAll,
+		arrIncludesSome: filterFn_arrIncludesSome
+	}
+});
+// src/url-state.ts
+/**
+* Bind sorting, pagination and column filters to URL search params so a
+* filtered view is shareable by link. Router-agnostic; pass the route's search
+* and a setter. Spread the result into `useTable` (with `dataTableFeatures` or a superset).
+*/
+function useUrlTableState({ search, setSearch, defaultPageSize = 20, manual = true }) {
+	const sorting = useMemo(() => parseSort(search.sort), [search.sort]);
+	const pagination = useMemo(() => ({
+		pageIndex: Math.max(0, (search.page ?? 1) - 1),
+		pageSize: search.size ?? defaultPageSize
+	}), [
+		search.page,
+		search.size,
+		defaultPageSize
+	]);
+	const columnFilters = useMemo(() => Object.entries(search.filter ?? {}).map(([id, value]) => ({
+		id,
+		value
+	})), [search.filter]);
+	const onSortingChange = useCallback((updater) => {
+		const next = typeof updater === "function" ? updater(sorting) : updater;
+		setSearch({
+			sort: next.length ? formatSort(next) : void 0,
+			page: void 0
+		});
+	}, [sorting, setSearch]);
+	const onPaginationChange = useCallback((updater) => {
+		const next = typeof updater === "function" ? updater(pagination) : updater;
+		setSearch({
+			page: next.pageIndex === 0 ? void 0 : next.pageIndex + 1,
+			size: next.pageSize === defaultPageSize ? void 0 : next.pageSize
+		});
+	}, [
+		pagination,
+		setSearch,
+		defaultPageSize
+	]);
+	const onColumnFiltersChange = useCallback((updater) => {
+		const next = typeof updater === "function" ? updater(columnFilters) : updater;
+		const filter = {};
+		for (const f of next) if (f.value !== void 0 && f.value !== "") filter[f.id] = String(f.value);
+		setSearch({
+			filter: Object.keys(filter).length ? filter : void 0,
+			page: void 0
+		});
+	}, [columnFilters, setSearch]);
+	return {
+		state: {
+			sorting,
+			pagination,
+			columnFilters
+		},
+		onSortingChange,
+		onPaginationChange,
+		onColumnFiltersChange,
+		manualSorting: manual,
+		manualPagination: manual,
+		manualFiltering: manual
+	};
+}
+/** `-name,createdAt` ⇄ `[{ id: 'name', desc: true }, { id: 'createdAt', desc: false }]` */
+function parseSort(sort) {
+	if (!sort) return [];
+	return sort.split(",").filter(Boolean).map((part) => part.startsWith("-") ? {
+		id: part.slice(1),
+		desc: true
+	} : {
+		id: part,
+		desc: false
+	});
+}
+/** Turns TanStack's sorting state into the URL's `sort` string: `[{ id: 'total', desc: true }]` becomes `-total`. */
+function formatSort(sorting) {
+	return sorting.map((s) => s.desc ? `-${s.id}` : s.id).join(",");
+}
+/** Validate raw search params into `TableSearch`. Plug into `validateSearch` or wrap with zod. */
+function parseTableSearch(raw) {
+	const out = {};
+	const page = Number(raw.page);
+	if (Number.isInteger(page) && page > 0) out.page = page;
+	const size = Number(raw.size);
+	if (Number.isInteger(size) && size > 0 && size <= 500) out.size = size;
+	if (typeof raw.sort === "string" && /^-?[\w.]+(,-?[\w.]+)*$/.test(raw.sort)) out.sort = raw.sort;
+	if (raw.filter && typeof raw.filter === "object") {
+		const filter = {};
+		for (const [k, v] of Object.entries(raw.filter)) if (typeof v === "string") filter[k] = v;
+		if (Object.keys(filter).length) out.filter = filter;
+	}
+	return out;
+}
+export { clientTableFeatures, dataTableFeatures, formatSort, parseSort, parseTableSearch, useUrlTableState };

package/dist/kitr.d.ts

@@ -0,0 +1,17 @@
+/** `kitr add table`: TanStack Table with sorting, pagination and filters bound to URL search params. */
+declare const _default: {
+  readonly name: "table";
+  readonly client: true;
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly wraps: {
+    readonly '@tanstack/react-table': "@kitr/table";
+  };
+  readonly eject: {
+    readonly '@kitr/table': "@tanstack/react-table";
+  };
+  readonly vite: {
+    readonly optimizeDeps: ["@tanstack/react-table"];
+  };
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,19 @@
+import { definePackage } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add table`: TanStack Table with sorting, pagination and filters bound to URL search params. */
+var kitr_default = definePackage({
+	name: "table",
+	client: true,
+	add(ctx) {
+		ctx.deps.add("@tanstack/react-table");
+		ctx.agents.add("table", `- Tables: \`validateSearch: parseTableSearch\` on the route, \`useUrlTableState({ search, setSearch })\` spread into \`useReactTable\` or the registry \`<DataTable>\`. Sorting/paging live in the URL, so views are shareable.`);
+	},
+	remove(ctx) {
+		ctx.deps.remove("@tanstack/react-table");
+		ctx.agents.remove("table");
+	},
+	wraps: { "@tanstack/react-table": "@kitr/table" },
+	eject: { "@kitr/table": "@tanstack/react-table" },
+	vite: { optimizeDeps: ["@tanstack/react-table"] }
+});
+export { kitr_default as default };

package/docs/api.md

@@ -0,0 +1,68 @@
+---
+title: API reference
+description: Every export of @kitr/table.
+order: 2
+---
+
+# API reference
+
+`@kitr/table` re-exports everything from `@tanstack/react-table` v9 and adds the following.
+
+## useUrlTableState
+
+```ts
+function useUrlTableState(options: {
+  search: TableSearch
+  setSearch: (patch: Partial<TableSearch>) => void
+  defaultPageSize?: number // default 20
+}): {
+  state: { sorting; pagination; columnFilters }
+  onSortingChange
+  onPaginationChange
+  onColumnFiltersChange
+  manualSorting: true
+  manualPagination: true
+  manualFiltering: true
+}
+```
+
+Spread the result into `useTable` or `<DataTable>`. Router-agnostic: any router that can read and patch search params works.
+
+## TableSearch
+
+```ts
+interface TableSearch {
+  page?: number                   // one-based
+  size?: number
+  sort?: string                   // "name,-createdAt"
+  filter?: Record<string, string>
+}
+```
+
+## parseTableSearch
+
+```ts
+function parseTableSearch(raw: Record<string, unknown>): TableSearch
+```
+
+For a route's `validateSearch`. Keeps positive integer pages, sizes up to 500, well-formed sort strings and string filters; drops everything else.
+
+## parseSort and formatSort
+
+```ts
+parseSort('-name,createdAt') // [{ id: 'name', desc: true }, { id: 'createdAt', desc: false }]
+formatSort([{ id: 'name', desc: true }]) // '-name'
+```
+
+## dataTableFeatures
+
+```ts
+const dataTableFeatures = tableFeatures({
+  rowSortingFeature,
+  rowPaginationFeature,
+  columnFilteringFeature,
+  columnVisibilityFeature,
+})
+```
+
+The features `<DataTable>` and `useUrlTableState` assume. TanStack Table v9 only bundles the features you register. Add more with `tableFeatures({ ...dataTableFeatures, rowSelectionFeature })`.