@octane-xplat/table 0.0.1 → 0.11.0

package/src/table.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest'
+import { createTable } from './table'
+
+const DATA = [
+	{ name: 'Charlie', n: 3 },
+	{ name: 'Alice', n: 1 },
+	{ name: 'Bob', n: 2 },
+]
+
+const columns = [
+	{ accessorKey: 'name', header: 'Name' },
+	{ accessorKey: 'n', header: 'N' },
+]
+
+const names = (table: any) => table.getRowModel().rows.map((r: any) => r.original.name)
+
+describe('createTable', () => {
+	it('builds the core row model in data order', () => {
+		const table = createTable({ data: DATA, columns })
+		expect(names(table)).toEqual(['Charlie', 'Alice', 'Bob'])
+		expect(table.getHeaderGroups().map((g: any) => g.headers.map((h: any) => h.column.id))).toEqual(
+			[['name', 'n']],
+		)
+	})
+
+	it('sorts through the sorting state slice', () => {
+		const table = createTable({ data: DATA, columns })
+		table.setSorting([{ id: 'name', desc: false }])
+		expect(names(table)).toEqual(['Alice', 'Bob', 'Charlie'])
+		table.setSorting([{ id: 'name', desc: true }])
+		expect(names(table)).toEqual(['Charlie', 'Bob', 'Alice'])
+		table.setSorting([])
+		expect(names(table)).toEqual(['Charlie', 'Alice', 'Bob'])
+	})
+
+	it('notifies subscribers through table.store and memoizes the row model', () => {
+		const table = createTable({ data: DATA, columns })
+		const seen: unknown[] = []
+		const sub = table.store.subscribe((s: any) => seen.push(s.sorting))
+		const before = table.getRowModel()
+		table.setSorting([{ id: 'name', desc: false }])
+		expect(seen.at(-1)).toEqual([{ id: 'name', desc: false }])
+		expect(table.getRowModel() === before).toBe(false)
+		sub.unsubscribe()
+	})
+
+	it('filters via global filter', () => {
+		const table = createTable({ data: DATA, columns })
+		table.setGlobalFilter('ali')
+		expect(names(table)).toEqual(['Alice'])
+		table.setGlobalFilter('a')
+		expect(names(table)).toEqual(['Charlie', 'Alice'])
+	})
+
+	it('paginates', () => {
+		const table = createTable({
+			data: DATA,
+			columns,
+			initialState: { pagination: { pageIndex: 0, pageSize: 2 } },
+		})
+
+		expect(names(table)).toEqual(['Charlie', 'Alice'])
+		table.nextPage()
+		expect(names(table)).toEqual(['Bob'])
+	})
+
+	it('syncs option updates through setOptions', () => {
+		const table = createTable({ data: DATA, columns })
+		table.setOptions((prev: any) => ({ ...prev, data: [{ name: 'Zed', n: 9 }] }))
+		expect(names(table)).toEqual(['Zed'])
+	})
+
+	it('honors controlled state slices via options.state', () => {
+		const table = createTable({
+			data: DATA,
+			columns,
+			state: { sorting: [{ id: 'n', desc: true }] },
+		})
+
+		expect(names(table)).toEqual(['Charlie', 'Bob', 'Alice'])
+	})
+})
+
+describe('stable selection ownership', () => {
+	it('selects only eligible filtered page IDs and keeps missing IDs until the owner clears', () => {
+		const data = [
+			{ id: 'a', name: 'Alice' },
+			{ id: 'b', name: 'Bob' },
+			{ id: 'c', name: 'Charlie' },
+		]
+
+		const table = createTable({
+			data,
+			columns: [{ accessorKey: 'name' }],
+			getRowId: (row) => row.id,
+			enableRowSelection: (row) => row.id !== 'b',
+			initialState: { rowSelection: { absent: true }, pagination: { pageIndex: 0, pageSize: 2 } },
+		})
+
+		table.toggleAllPageRowsSelected(true)
+		expect(table.store.get().rowSelection).toEqual({ absent: true, a: true })
+		table.setGlobalFilter('char')
+		table.toggleAllPageRowsSelected(true)
+		expect(table.store.get().rowSelection).toEqual({ absent: true, a: true, c: true })
+		table.toggleAllPageRowsSelected(false)
+		expect(table.store.get().rowSelection).toEqual({ absent: true, a: true })
+		table.setOptions((prev) => ({ ...prev, data: [{ id: 'a', name: 'Updated Alice' }] }))
+		table.setGlobalFilter('')
+		expect(table.getRowModel().rows[0].getIsSelected()).toBe(true)
+		expect(table.getSelectedRowModel().rows.map((row) => row.id)).toEqual(['a'])
+		table.resetRowSelection(true)
+		expect(table.store.get().rowSelection).toEqual({})
+	})
+})

package/src/table.ts

@@ -0,0 +1,91 @@
+import {
+	aggregationFns,
+	columnFacetingFeature,
+	columnFilteringFeature,
+	columnGroupingFeature,
+	columnOrderingFeature,
+	columnPinningFeature,
+	columnSizingFeature,
+	columnVisibilityFeature,
+	constructTable,
+	createExpandedRowModel,
+	createFacetedMinMaxValues,
+	createFacetedRowModel,
+	createFacetedUniqueValues,
+	createFilteredRowModel,
+	createGroupedRowModel,
+	createPaginatedRowModel,
+	createSortedRowModel,
+	filterFns,
+	globalFilteringFeature,
+	rowAggregationFeature,
+	rowExpandingFeature,
+	rowPaginationFeature,
+	rowPinningFeature,
+	rowSelectionFeature,
+	rowSortingFeature,
+	sortFns,
+	tableFeatures,
+} from '@tanstack/table-core'
+
+import { storeReactivityBindings } from '@tanstack/table-core/store-reactivity-bindings'
+import type { RowData, Table, TableFeatures } from '@tanstack/table-core'
+import type { DataGridOptions } from './props'
+
+/** DataGrid's default feature slots: every stock feature whose machinery is
+ *  DOM-free — sorting, filtering, grouping, expanding, pagination, pinning,
+ *  selection, column ordering/visibility/sizing, faceting, global filtering,
+ *  aggregation — plus the row-model factories and builtin fn registries that
+ *  v9 keeps as separate slots. Omitted: `columnResizingFeature` (its drag
+ *  handler installs global event listeners — web-only; resize gesture UI
+ *  belongs to platform leaves) and `cellSelectionFeature`/`cellSpanningFeature`
+ *  (range-selection UX is web-spreadsheet-shaped, not a v1 xplat idiom). Pass
+ *  `features` to add them where a platform leaf supports them. */
+export const dataGridFeatures = tableFeatures({
+	columnFacetingFeature,
+	columnFilteringFeature,
+	columnGroupingFeature,
+	columnOrderingFeature,
+	columnPinningFeature,
+	columnSizingFeature,
+	columnVisibilityFeature,
+	globalFilteringFeature,
+	rowAggregationFeature,
+	rowExpandingFeature,
+	rowPaginationFeature,
+	rowPinningFeature,
+	rowSelectionFeature,
+	rowSortingFeature,
+	sortedRowModel: createSortedRowModel(),
+	filteredRowModel: createFilteredRowModel(),
+	groupedRowModel: createGroupedRowModel(),
+	expandedRowModel: createExpandedRowModel(),
+	paginatedRowModel: createPaginatedRowModel(),
+	facetedRowModel: createFacetedRowModel(),
+	facetedMinMaxValues: createFacetedMinMaxValues(),
+	facetedUniqueValues: createFacetedUniqueValues(),
+	sortFns,
+	filterFns,
+	aggregationFns,
+})
+
+export type DataGridFeatures = typeof dataGridFeatures
+
+/** Construct a table instance bound to TanStack Store reactivity — the
+ *  vanilla/non-framework binding (`table.optionsStore` subscribable, atoms
+ *  from `@tanstack/store`, `queueMicrotask` scheduling — all DOM-free). Wrap
+ *  with `useTable` inside a component; call directly for non-rendering
+ *  consumers (tests, headless row models). */
+export function createTable<
+	TData extends RowData,
+	TFeatures extends TableFeatures = DataGridFeatures,
+>(options: DataGridOptions<TFeatures, TData>): Table<TFeatures, TData> {
+	return constructTable({
+		...(options as object),
+		features: {
+			coreReactivityFeature: storeReactivityBindings(),
+			...dataGridFeatures,
+			...options.features,
+		},
+	} as never) as Table<TFeatures, TData>
+}

package/src/useTable.tsrx

@@ -0,0 +1,34 @@
+import { useCallback, useState, useSyncExternalStore } from 'octane'
+import type { RowData, TableFeatures } from '@tanstack/table-core'
+import { createTable, type DataGridFeatures } from './table'
+import type { DataGridOptions, UseTable } from './props'
+
+/**
+ * Create a table instance bound to component rendering. The instance is
+ * constructed once; each render syncs `data`/`columns`/`state`/etc. into the
+ * options store (feature slots and `initialState` are first-render only).
+ *
+ * Re-render triggers: any `TableState` slice change (sorting, selection,
+ * filters, pagination, ...) through `table.store`, plus ordinary prop-driven
+ * renders for `data`/`columns` changes. Read rows via `table.getRowModel()`
+ * — memoized per revision, so snapshot reads stay Object.is-stable.
+ *
+ * Controlled slices: pass `state` + `atoms` (external `@tanstack/store`
+ * atoms own the slice) or subscribe `table.atoms.<slice>` yourself.
+ */
+export function useTable<TData extends RowData, TFeatures extends TableFeatures = DataGridFeatures>(
+	options: DataGridOptions<TFeatures, TData>,
+): UseTable<TFeatures, TData> {
+	const [{ table }] = useState(() => ({ table: createTable<TData, TFeatures>(options) }))
+	table.setOptions((prev) => ({ ...prev, ...options }) as never)
+	const subscribe = useCallback(
+		(notify: () => void) => {
+			const sub = table.store.subscribe(() => notify())
+			return () => sub.unsubscribe()
+		},
+		[table],
+	)
+
+	const state = useSyncExternalStore(subscribe, () => table.store.get())
+	return { table, state }
+}

package/types/index.d.ts

@@ -0,0 +1,20 @@
+import type { RowData, TableFeatures } from '@tanstack/table-core'
+import type { DataGridFeatures } from './table.js'
+import type { DataGridOptions, DataGridProps, UseTable } from './props.js'
+
+/** Headless data grid — table-core row model rendered through shared
+ *  VirtualList. */
+export declare function DataGrid<TData extends RowData = any>(props: DataGridProps<TData>): unknown
+
+/** Create a table instance bound to component rendering — re-renders on any
+ *  TableState slice change; sync this render's `data`/`columns`/`state` into
+ *  the options store each render. */
+export declare function useTable<
+	TData extends RowData,
+	TFeatures extends TableFeatures = DataGridFeatures,
+>(options: DataGridOptions<TFeatures, TData>): UseTable<TFeatures, TData>
+
+export { createTable, dataGridFeatures } from './table.js'
+export type { DataGridFeatures } from './table.js'
+export type { DataGridOptions, DataGridProps, UseTable } from './props.js'
+export type { Cell, ColumnDef, Header, Row, Table, TableState } from '@tanstack/table-core'

package/types/index.macos.d.ts

@@ -0,0 +1,17 @@
+import type { RowData, TableFeatures } from '@tanstack/table-core'
+import type { DataGridFeatures } from './table.js'
+import type { DataGridOptions, DataGridProps, UseTable } from './props.js'
+
+/** Headless data grid — table-core row model rendered through shared
+ *  VirtualList. */
+export declare function DataGrid<TData extends RowData = any>(props: DataGridProps<TData>): unknown
+
+export declare function useTable<
+	TData extends RowData,
+	TFeatures extends TableFeatures = DataGridFeatures,
+>(options: DataGridOptions<TFeatures, TData>): UseTable<TFeatures, TData>
+
+export { createTable, dataGridFeatures } from './table.js'
+export type { DataGridFeatures } from './table.js'
+export type { DataGridOptions, DataGridProps, UseTable } from './props.js'
+export type { Cell, ColumnDef, Header, Row, Table, TableState } from '@tanstack/table-core'

package/types/props.d.ts

@@ -0,0 +1,96 @@
+import type { Cell, ColumnDef, Header, Row, RowData, Table, TableFeatures, TableOptions, TableState } from '@tanstack/table-core';
+import type { DataGridFeatures } from './table';
+export interface LayoutChildProps {
+    row?: number;
+    col?: number;
+    rowSpan?: number;
+    colSpan?: number;
+    dock?: 'left' | 'top' | 'right' | 'bottom';
+    left?: number;
+    top?: number;
+    flexGrow?: number;
+    flexShrink?: number;
+    alignSelf?: string;
+    order?: number;
+}
+export interface AccessibilityProps {
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+    accessibilityRole?: string;
+    accessibilityState?: Record<string, any>;
+    testID?: string;
+}
+/** Options shared by `createTable`/`useTable`/`DataGrid`. Extends the
+ *  table-core options for the enabled feature set minus its reactivity slot
+ *  (owned by the adapter). */
+export type DataGridOptions<TFeatures extends TableFeatures, TData extends RowData> = Omit<TableOptions<TFeatures, TData>, 'features' | 'coreReactivityFeature'> & {
+    /** Feature slots beyond the defaults — pass `tableFeatures({...})`
+     *  output or merge onto `dataGridFeatures`. */
+    features?: Partial<TableFeatures>;
+};
+/** `useTable` return — the live table instance plus the flat reactive state.
+ *  `state` re-reads on every slice change; row models come from
+ *  `table.getRowModel()` (memoized per state/option revision). */
+export interface UseTable<TFeatures extends TableFeatures, TData extends RowData> {
+    table: Table<TFeatures, TData>;
+    state: TableState<TFeatures>;
+}
+export interface DataGridProps<TData extends RowData = any, TFeatures extends TableFeatures = DataGridFeatures> extends LayoutChildProps, AccessibilityProps {
+    id?: string;
+    className?: any;
+    style?: any;
+    /** Row data — pass a new array reference when data changes. */
+    data: TData[];
+    columns: ColumnDef<TFeatures, TData, any>[];
+    /** Feature overrides merged onto the defaults (see `dataGridFeatures`). */
+    features?: Partial<TableFeatures>;
+    /** Core options (atoms, change callbacks, manual row models, selection
+     * predicates). Data/columns and the explicit props below take precedence. */
+    options?: Omit<DataGridOptions<TFeatures, TData>, 'data' | 'columns' | 'features' | 'state' | 'initialState' | 'getRowId'>;
+    /** Partial controlled state. Pair with options.atoms or per-slice
+     * options callbacks; a state snapshot alone is read-only. */
+    state?: Partial<TableState<TFeatures>>;
+    initialState?: Partial<TableState<TFeatures>>;
+    getRowId?: (row: TData, index: number) => string;
+    /** Per-cell content override. Defaults to the column's `cell` template,
+     *  then `cell.getValue()`. */
+    renderCell?: (cell: Cell<TFeatures, TData, any>) => any;
+    /** Per-header content override. Defaults to the column's `header`
+     *  template plus a sort affordance when the column can sort. */
+    renderHeader?: (header: Header<TFeatures, TData, any>) => any;
+    /** Row tap — marks rows pressable. */
+    onRowPress?: (row: Row<TFeatures, TData>) => void;
+    renderEmpty?: () => any;
+    /** Show a text query across globally filterable columns. */
+    showGlobalFilter?: boolean;
+    /** Show text filters beneath filterable leaf-column headings. */
+    showColumnFilters?: boolean;
+    /** Show previous/next and page-size controls. Client-side by default;
+     * use options.manualPagination with pageCount/rowCount for server data. */
+    showPagination?: boolean;
+    /** Positive integer page sizes offered by the pager. Defaults to [10, 25, 50]. */
+    pageSizeOptions?: readonly number[];
+    /** Show row checkboxes and a current-page select-all checkbox. Selection
+     * survives filtering/pagination by ID; provide getRowId for mutable data. */
+    showRowSelection?: boolean;
+    /** Optional label for each selection checkbox. */
+    getRowLabel?: (row: Row<TFeatures, TData>) => string;
+    /** Show a column visibility/order panel, reset to initial state, and
+     * keyboard/touch move buttons. Non-hideable columns stay visible. */
+    showColumnSettings?: boolean;
+    /** Fixed-width columns with pan resize handles and accessible +/- actions.
+     * Widths use column minSize/maxSize; cancellation restores prior state. */
+    resizableColumns?: boolean;
+    /** Separate pan handles reorder leaf columns on release. Cancel preserves
+     * order; settings move buttons provide a non-drag alternative. */
+    reorderableColumns?: boolean;
+    /** Horizontal gesture direction. Defaults to ltr; use rtl for mirrored layouts. */
+    direction?: 'ltr' | 'rtl';
+    /** Caller-owned bulk actions; selected IDs include off-page selections. */
+    renderSelectionActions?: (table: Table<TFeatures, TData>) => any;
+    /** Platform escape bags — applied after shared props on the root view. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}

package/types/table.d.ts

@@ -0,0 +1,83 @@
+import type { RowData, Table, TableFeatures } from '@tanstack/table-core';
+import type { DataGridOptions } from './props';
+/** DataGrid's default feature slots: every stock feature whose machinery is
+ *  DOM-free — sorting, filtering, grouping, expanding, pagination, pinning,
+ *  selection, column ordering/visibility/sizing, faceting, global filtering,
+ *  aggregation — plus the row-model factories and builtin fn registries that
+ *  v9 keeps as separate slots. Omitted: `columnResizingFeature` (its drag
+ *  handler installs global event listeners — web-only; resize gesture UI
+ *  belongs to platform leaves) and `cellSelectionFeature`/`cellSpanningFeature`
+ *  (range-selection UX is web-spreadsheet-shaped, not a v1 xplat idiom). Pass
+ *  `features` to add them where a platform leaf supports them. */
+export declare const dataGridFeatures: {
+    columnFacetingFeature: import("@tanstack/table-core").TableFeature;
+    columnFilteringFeature: import("@tanstack/table-core").TableFeature;
+    columnGroupingFeature: import("@tanstack/table-core").TableFeature;
+    columnOrderingFeature: import("@tanstack/table-core").TableFeature;
+    columnPinningFeature: import("@tanstack/table-core").TableFeature;
+    columnSizingFeature: import("@tanstack/table-core").TableFeature;
+    columnVisibilityFeature: import("@tanstack/table-core").TableFeature;
+    globalFilteringFeature: import("@tanstack/table-core").TableFeature;
+    rowAggregationFeature: import("@tanstack/table-core").TableFeature;
+    rowExpandingFeature: import("@tanstack/table-core").TableFeature;
+    rowPaginationFeature: import("@tanstack/table-core").TableFeature;
+    rowPinningFeature: import("@tanstack/table-core").TableFeature;
+    rowSelectionFeature: import("@tanstack/table-core").TableFeature;
+    rowSortingFeature: import("@tanstack/table-core").TableFeature;
+    sortedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+    filteredRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+    groupedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+    expandedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+    paginatedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+    facetedRowModel: (table: Table<any, any>, columnId: string) => () => import("@tanstack/table-core").RowModel<any, any>;
+    facetedMinMaxValues: (table: Table<TableFeatures, any>, columnId: string) => () => undefined | [number, number];
+    facetedUniqueValues: (table: Table<TableFeatures, any>, columnId: string) => () => Map<any, number>;
+    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>;
+    };
+    aggregationFns: {
+        sum: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, number>;
+        min: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, (number | Date) | undefined>;
+        max: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, (number | Date) | undefined>;
+        extent: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, [(number | Date) | undefined, (number | Date) | undefined]>;
+        mean: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, number | undefined>;
+        median: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, number | undefined>;
+        unique: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, unknown[]>;
+        uniqueCount: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, number>;
+        count: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, number>;
+        first: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, unknown>;
+        last: import("@tanstack/table-core").AggregationFnDef<any, any, unknown, unknown>;
+    };
+};
+export type DataGridFeatures = typeof dataGridFeatures;
+/** Construct a table instance bound to TanStack Store reactivity — the
+ *  vanilla/non-framework binding (`table.optionsStore` subscribable, atoms
+ *  from `@tanstack/store`, `queueMicrotask` scheduling — all DOM-free). Wrap
+ *  with `useTable` inside a component; call directly for non-rendering
+ *  consumers (tests, headless row models). */
+export declare function createTable<TData extends RowData, TFeatures extends TableFeatures = DataGridFeatures>(options: DataGridOptions<TFeatures, TData>): Table<TFeatures, TData>;