fix(data-table): a11y improvements, store hardening, and server hook race condition

- Replace use() with useContext() for DataTableRenderKeyContext to fix
  SSR context subscription bug where use() fails to register subscriptions
  after React Router SSR hydration, causing sort/pagination/page-size
  changes to not re-render components
- Add _version monotonic counter to store state, incremented on every
  setState, powering DataTableRenderKeyContext for table-dependent hooks
- Wrap providers (client + server) with DataTableRenderKeyContext
- Rewrite useDataTableSelection, useDataTablePagination, useDataTableRows
  to use useRenderKey() + direct table reads instead of useSliceSelector
- Fix pagination active button using disabled styling instead of full
  opacity (aria-disabled + pointer-events-none instead of disabled prop)

Author: yahyafakhroji

packages/datum-ui/src/components/features/data-table/__tests__/server-provider.test.tsx

@@ -1,8 +1,8 @@
 /// <reference types="@testing-library/jest-dom/vitest" />
 import { render, screen } from '@testing-library/react'
 import { describe, expect, it, vi } from 'vitest'
-import { ServerProvider } from '../core/server-provider'
 import { useDataTableStore } from '../core/data-table-context'
+import { ServerProvider } from '../core/server-provider'
 import { useDataTableLoading } from '../hooks/use-selectors'
 
 interface TestRow {

packages/datum-ui/src/components/features/data-table/__tests__/use-selectors.test.tsx

@@ -104,4 +104,3 @@ describe('useDataTableLoading', () => {
     expect(renderCount.current).toBe(countBefore)
   })
 })
-

packages/datum-ui/src/components/features/data-table/components/pagination.tsx

@@ -148,9 +148,9 @@ export function DataTablePagination({
                   key={page}
                   theme={isActive ? 'solid' : 'outline'}
                   size="small"
-                  className={cn('h-8 min-w-8 px-2', isActive && 'font-semibold')}
+                  className={cn('h-8 min-w-8 px-2', isActive && 'pointer-events-none font-semibold')}
                   onClick={() => setPageIndex(page - 1)}
-                  disabled={isActive}
+                  aria-disabled={isActive || undefined}
                   aria-label={`Page ${page}`}
                   aria-current={isActive ? 'page' : undefined}
                 >

packages/datum-ui/src/components/features/data-table/core/client-provider.tsx

@@ -4,7 +4,7 @@ import type { ReactNode } from 'react'
 import type { UseDataTableClientOptions } from '../hooks/use-data-table-client'
 import { useDataTableClient } from '../hooks/use-data-table-client'
 import { useIsClient } from '../hooks/use-is-client'
-import { DataTableStoreContext, TableInstanceContext } from './data-table-context'
+import { DataTableRenderKeyContext, DataTableStoreContext, TableInstanceContext } from './data-table-context'
 
 export type DataTableClientProviderProps<TData> = UseDataTableClientOptions<TData> & {
   readonly className?: string
@@ -27,7 +27,9 @@ function ClientProviderInner<TData>({
   return (
     <DataTableStoreContext value={store}>
       <TableInstanceContext value={table}>
-        <div className={className}>{children}</div>
+        <DataTableRenderKeyContext value={store.getSnapshot()._version}>
+          <div className={className}>{children}</div>
+        </DataTableRenderKeyContext>
       </TableInstanceContext>
     </DataTableStoreContext>
   )

packages/datum-ui/src/components/features/data-table/core/data-table-context.tsx

@@ -2,11 +2,30 @@
 
 import type { Table } from '@tanstack/react-table'
 import type { DataTableContextValue, DataTableStore } from '../types'
-import { createContext, use } from 'react'
+import { createContext, use, useContext } from 'react' // eslint-disable-line react/no-use-context -- useContext needed: use() breaks context subscriptions after SSR hydration
 
 export const DataTableStoreContext = createContext<DataTableStore<any> | null>(null)
 export const TableInstanceContext = createContext<Table<any> | null>(null)
 
+/**
+ * Monotonic counter that increments on every store mutation.
+ * Table-dependent hooks consume this context to force re-renders
+ * through React's {children} composition boundary, since the
+ * mutable table singleton (stable ref) cannot trigger context updates.
+ */
+export const DataTableRenderKeyContext = createContext<number>(0)
+
+/**
+ * Forces a re-render when the store changes. Used by table-dependent hooks.
+ * Uses useContext (not use()) because use() does not reliably register
+ * context subscriptions in SSR/hydration scenarios (React Router SSR),
+ * preventing re-renders when the context value changes.
+ */
+export function useRenderKey(): number {
+  // eslint-disable-next-line react/no-use-context -- use() does not register context subscriptions after SSR hydration
+  return useContext(DataTableRenderKeyContext)
+}
+
 // Legacy context — retained for backward compat until providers are migrated (Task 4)
 export const DataTableContext = createContext<DataTableContextValue<any> | null>(null)
 

packages/datum-ui/src/components/features/data-table/core/server-provider.tsx

@@ -4,7 +4,7 @@ import type { ReactNode } from 'react'
 import type { UseDataTableServerOptions } from '../hooks/use-data-table-server'
 import { useDataTableServer } from '../hooks/use-data-table-server'
 import { useIsClient } from '../hooks/use-is-client'
-import { DataTableStoreContext, TableInstanceContext } from './data-table-context'
+import { DataTableRenderKeyContext, DataTableStoreContext, TableInstanceContext } from './data-table-context'
 
 export type DataTableServerProviderProps<TResponse, TData> = UseDataTableServerOptions<TResponse, TData> & {
   readonly className?: string
@@ -27,7 +27,9 @@ function ServerProviderInner<TResponse, TData>({
   return (
     <DataTableStoreContext value={store}>
       <TableInstanceContext value={table}>
-        <div className={className}>{children}</div>
+        <DataTableRenderKeyContext value={store.getSnapshot()._version}>
+          <div className={className}>{children}</div>
+        </DataTableRenderKeyContext>
       </TableInstanceContext>
     </DataTableStoreContext>
   )

packages/datum-ui/src/components/features/data-table/core/store.ts

@@ -43,6 +43,7 @@ export function createDataTableStore<TData>(
     isLoading: false,
     error: null,
     inlineContents: [],
+    _version: 0,
   }
 
   // Apply default filters on init if any exist (pageIndex already 0)
@@ -55,7 +56,7 @@ export function createDataTableStore<TData>(
   }
 
   function setState(next: DataTableStoreState<TData>) {
-    state = next
+    state = { ...next, _version: state._version + 1 }
     notify()
   }
 

packages/datum-ui/src/components/features/data-table/hooks/use-selectors.ts

@@ -1,9 +1,8 @@
 'use client'
 
-import type { HeaderGroup, Row, RowSelectionState } from '@tanstack/react-table'
 import type { DataTableStoreState, InlineContentEntry } from '../types'
 import { useCallback, useRef, useSyncExternalStore } from 'react'
-import { useDataTableStore, useTableInstance } from '../core/data-table-context'
+import { useDataTableStore, useRenderKey, useTableInstance } from '../core/data-table-context'
 
 function shallowEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
   const keysA = Object.keys(a)
@@ -84,58 +83,49 @@ export function useDataTableSorting() {
 }
 
 export function useDataTableSelection<TData>() {
+  useRenderKey() // re-render when store changes (table is mutable singleton)
   const store = useDataTableStore<TData>()
   const table = useTableInstance<TData>()
-  return useSliceSelector<TData, {
-    rowSelection: RowSelectionState
-    setRowSelection: (selection: RowSelectionState) => void
-    selectedRows: TData[]
-  }>(
-    useCallback((state: DataTableStoreState<TData>) => ({
-      rowSelection: state.rowSelection,
-      setRowSelection: store.setRowSelection,
-      selectedRows: table.getFilteredSelectedRowModel().rows.map(r => r.original),
-    }), [store, table]),
-  )
+  const state = store.getSnapshot()
+  return {
+    rowSelection: state.rowSelection,
+    setRowSelection: store.setRowSelection,
+    selectedRows: table.getFilteredSelectedRowModel().rows.map(r => r.original),
+  }
 }
 
 export function useDataTablePagination() {
+  useRenderKey() // re-render when store changes (table is mutable singleton)
   const store = useDataTableStore()
   const table = useTableInstance()
+  const state = store.getSnapshot()
 
-  // Stable function references — do not recreate on every snapshot call
+  // Stable function references (table ref is stable from useReactTable)
   const nextPage = useCallback(() => table.nextPage(), [table])
   const prevPage = useCallback(() => table.previousPage(), [table])
 
-  return useSliceSelector(
-    useCallback((state: DataTableStoreState<any>) => ({
-      canNextPage: table.getCanNextPage(),
-      canPrevPage: table.getCanPreviousPage(),
-      nextPage,
-      prevPage,
-      pageIndex: state.pageIndex,
-      pageCount: table.getPageCount(),
-      setPageIndex: store.setPageIndex,
-      pageSize: state.pageSize,
-      setPageSize: store.setPageSize,
-      totalRows: state.filteredData.length,
-    }), [store, table, nextPage, prevPage]),
-  )
+  return {
+    canNextPage: table.getCanNextPage(),
+    canPrevPage: table.getCanPreviousPage(),
+    nextPage,
+    prevPage,
+    pageIndex: state.pageIndex,
+    pageCount: table.getPageCount(),
+    setPageIndex: store.setPageIndex,
+    pageSize: state.pageSize,
+    setPageSize: store.setPageSize,
+    totalRows: state.filteredData.length,
+  }
 }
 
 export function useDataTableRows<TData>() {
+  useRenderKey() // re-render when store changes (table is mutable singleton)
   const table = useTableInstance<TData>()
-  return useSliceSelector<TData, {
-    rows: Row<TData>[]
-    headerGroups: HeaderGroup<TData>[]
-    totalColumns: number
-  }>(
-    useCallback((_state: DataTableStoreState<TData>) => ({
-      rows: table.getRowModel().rows,
-      headerGroups: table.getHeaderGroups(),
-      totalColumns: table.getAllColumns().length,
-    }), [table]),
-  )
+  return {
+    rows: table.getRowModel().rows,
+    headerGroups: table.getHeaderGroups(),
+    totalColumns: table.getAllColumns().length,
+  }
 }
 
 export function useDataTableLoading() {
@@ -161,4 +151,3 @@ export function useDataTableInlineContents<TData>() {
     }), [store]),
   )
 }
-

packages/datum-ui/src/components/features/data-table/types.ts

@@ -337,6 +337,8 @@ export interface DataTableStoreState<TData> {
   readonly isLoading: boolean
   readonly error: Error | null
   readonly inlineContents: readonly InlineContentEntry<TData>[]
+  /** Monotonic counter incremented on every state change. Used by table-dependent selectors to detect updates. */
+  readonly _version: number
 }
 
 export interface DataTableStore<TData> {