fix(data-table): SSR fallback removal, loading prop, and formatFilterValue API

Remove the SSR hydration gate (useIsClient) and make the store always
available during SSR. Table instance is deferred to after hydration via
a tableReady state gate, with null-safe selector hooks throughout.

- Remove useIsClient hook and SSR fallback rendering
- Add useTableInstanceOrNull for null-safe table access during SSR
- Refactor ClientProvider into outer (store) + inner (table) components
- Extract useClientTable and useServerTable hooks from providers
- Add loading prop to DataTable.Client for consumer-controlled skeleton state
- Add columnCount to store so Content derives skeleton columns from columns.length
- Fix loading effect ordering to prevent empty-message flash
- Refactor formatFilterValue from function to Record<string, (value) => string>
  with dot-notation support
- Remove dead setTable from store interface
- Deprecate useTableInstance with accurate hydration error message
- Update docs, storybook, and tests for all changes

Author: yahyafakhroji

apps/docs/content/docs/components/features/data-table.mdx

@@ -115,16 +115,13 @@ function UsersPage({ users }: { users: User[] }) {
 For paginated API data (e.g., Kubernetes resources with continuation tokens). Like the client mode, pass all options as props directly to `DataTable.Server`:
 
 ```tsx
-import { DataTable, useDataTableLoading } from '@datum-cloud/datum-ui/data-table'
+import { DataTable } from '@datum-cloud/datum-ui/data-table'
 
 function ServerContent() {
-  const { isLoading } = useDataTableLoading()
   return (
     <div className="flex flex-col gap-4">
       <DataTable.Search placeholder="Search..." />
-      {isLoading
-        ? <DataTable.Loading rows={5} columns={4} />
-        : <DataTable.Content emptyMessage="No results." />}
+      <DataTable.Content emptyMessage="No results." />
       <DataTable.Pagination />
     </div>
   )
@@ -324,12 +321,15 @@ Display currently active filters as removable badges, grouped by category. Suppo
   filterLabels={{ status: 'Status' }}
 />
 
-{/* Custom value formatting */}
+{/* Custom value formatting — per-column record, consumer-typed values */}
 <DataTable.ActiveFilters
-  filterLabels={{ status: 'Status' }}
-  formatFilterValue={(column, value) => {
-    if (column === 'status') return String(value).toUpperCase()
-    return undefined // fallback to default
+  filterLabels={{ status: 'Status', 'status.approval': 'Approval' }}
+  formatFilterValue={{
+    status: (value: string) => value.toUpperCase(),
+    'status.approval': (value: string) => {
+      const labels = { Approved: 'Approved', Rejected: 'Rejected', Pending: 'Pending' }
+      return labels[value] ?? value
+    },
   }}
 />
 ```
@@ -365,7 +365,7 @@ All filter and search components accept a `disabled` prop. Use this to prevent i
 ```tsx
 const { data, isLoading } = useFetchData()
 
-<DataTable.Client data={data} columns={columns}>
+<DataTable.Client data={data} columns={columns} loading={isLoading}>
   <DataTable.Search placeholder="Search..." disabled={isLoading} />
   <DataTable.SelectFilter
     column="status"
@@ -384,7 +384,7 @@ const { data, isLoading } = useFetchData()
     label="Created"
     disabled={isLoading}
   />
-  {isLoading ? <DataTable.Loading /> : <DataTable.Content />}
+  <DataTable.Content emptyMessage="No results." />
 </DataTable.Client>
 ```
 
@@ -395,7 +395,7 @@ const { data, isLoading } = useFetchData()
 | `label` | `string \| null` | `"Selected Filters"` | Label text before filter groups. Set to `null` to hide |
 | `excludeFilters` | `string[]` | -- | Keys to hide from display. Use column data paths for filters, `'search'` for the search badge |
 | `filterLabels` | `Record<string, string>` | `{}` | Maps column keys to display names |
-| `formatFilterValue` | `(column, value) => string \| undefined` | -- | Custom value formatter |
+| `formatFilterValue` | `Record<string, (value) => string>` | -- | Per-column value formatters. Keys support dot notation. |
 | `clearAll` | `'icon' \| 'button' \| 'text'` | `'icon'` | Clear-all action style |
 | `clearAllLabel` | `string` | `"Clear all"` | Label for the clear-all action |
 | `className` | `string` | -- | Root container class |
@@ -552,9 +552,9 @@ All options are passed as props directly to the provider component. The provider
 | `searchableColumns` | `string[]` | -- | Data paths to search in. Supports dot notation (e.g. `['metadata.name', 'spec.email']`) |
 | `searchFn` | `(row, search) => boolean` | -- | Custom search function |
 | `filterFns` | `Record<string, (cellValue, filterValue) => boolean>` | -- | Custom filter functions per column. Keys are data paths |
+| `loading` | `boolean` | -- | Consumer-controlled loading state. When `true`, `DataTable.Content` shows skeleton rows instead of the empty message |
 | `stateAdapter` | `StateAdapter` | -- | URL state sync adapter |
 | `className` | `string` | -- | Class for the provider wrapper div |
-| `ssrFallback` | `ReactNode \| null` | `<DataTable.Loading>` | Rendered during SSR and first client paint. Defaults to a skeleton table matching column count. Set to `null` to render nothing |
 | `children` | `ReactNode` | -- | Table content |
 
 ### `DataTable.Server` Props
@@ -571,22 +571,21 @@ All options are passed as props directly to the provider component. The provider
 | `defaultFilters` | `FilterValue` | `{}` | Initial filter state |
 | `stateAdapter` | `StateAdapter` | -- | URL state sync adapter |
 | `className` | `string` | -- | Class for the provider wrapper div |
-| `ssrFallback` | `ReactNode \| null` | `<DataTable.Loading>` | Rendered during SSR and first client paint. Defaults to a skeleton table matching column count. Set to `null` to render nothing |
 | `children` | `ReactNode` | -- | Table content |
 
 ### `DataTable` Namespace
 
 | Component | Description |
 |-----------|-------------|
-| `DataTable.Client` | Client-mode provider — pass `data`, `columns`, and all options as props. SSR-safe with automatic skeleton fallback |
-| `DataTable.Server` | Server-mode provider — pass `columns`, `fetchFn`, `transform`, and all options as props. SSR-safe with automatic skeleton fallback |
-| `DataTable.Content` | Table rendering with header, body, and empty state. Accepts sub-element className props (`tableClassName`, `headerClassName`, `headerRowClassName`, `headerCellClassName`, `bodyClassName`, `rowClassName`, `cellClassName`) |
+| `DataTable.Client` | Client-mode provider — pass `data`, `columns`, and all options as props. Accepts `loading` prop for consumer-controlled skeleton state |
+| `DataTable.Server` | Server-mode provider — pass `columns`, `fetchFn`, `transform`, and all options as props. Manages loading state internally via fetch lifecycle |
+| `DataTable.Content` | Table rendering with header, body, empty state, and skeleton loading. Shows skeleton rows (matching `pageSize` and column count) when loading. Accepts sub-element className props (`tableClassName`, `headerClassName`, `headerRowClassName`, `headerCellClassName`, `bodyClassName`, `rowClassName`, `cellClassName`) |
 | `DataTable.ColumnHeader` | Click-to-sort column header |
 | `DataTable.Pagination` | Page navigation with page size selector |
 | `DataTable.Search` | Debounced search input. Accepts `disabled` prop |
 | `DataTable.RowActions` | Per-row action dropdown from `ActionItem[]` |
 | `DataTable.BulkActions` | Render prop for selected rows |
-| `DataTable.Loading` | Skeleton loading state |
+| `DataTable.Loading` | Standalone skeleton table. Use for custom loading layouts outside `DataTable.Content` |
 | `DataTable.InlineContent` | Render custom content inline within the table body. Supports `position` (`"top"` or `"row"`), `open`, `onClose`, and `rowId` props |
 | `DataTable.SelectFilter` | Combobox popover filter with single-select. Accepts `searchable` and `disabled` props |
 | `DataTable.CheckboxFilter` | Multi-value checkbox popover filter with badges and clear button. Accepts `disabled` prop |

apps/storybook/stories/features/data-table.stories.tsx

@@ -1,9 +1,6 @@
 import type { ColumnDef } from '@tanstack/react-table'
 import type { Meta, StoryObj } from 'storybook-react-rsbuild'
-import {
-  DataTable,
-  useDataTableLoading,
-} from '@datum-cloud/datum-ui/data-table'
+import { DataTable } from '@datum-cloud/datum-ui/data-table'
 import { useState } from 'react'
 
 const meta: Meta = {
@@ -219,14 +216,11 @@ const postColumns: ColumnDef<Post>[] = [
 ]
 
 function ServerTableContent() {
-  const { isLoading } = useDataTableLoading()
   return (
     <div className="flex flex-col gap-4">
       <DataTable.Search placeholder="Search posts..." />
       <DataTable.ActiveFilters />
-      {isLoading
-        ? <DataTable.Loading rows={5} columns={4} />
-        : <DataTable.Content emptyMessage="No posts found." />}
+      <DataTable.Content emptyMessage="No posts found." />
       <DataTable.Pagination />
     </div>
   )
@@ -690,15 +684,19 @@ function ActiveFiltersDemo() {
         </DataTable.Client>
       </div>
 
-      {/* Custom label + button clear */}
+      {/* Custom label + button clear + formatFilterValue */}
       <div>
-        <h3 className="mb-2 text-sm font-medium text-muted-foreground">Custom label with button clear</h3>
+        <h3 className="mb-2 text-sm font-medium text-muted-foreground">Custom label with button clear + formatted values</h3>
         <DataTable.Client {...sharedFilterOptions}>
           <div className="flex flex-col gap-4">
             {filterControls}
             <DataTable.ActiveFilters
               label="Filters Applied"
               filterLabels={filterLabels}
+              formatFilterValue={{
+                status: (value: string) => value === 'active' ? 'Active' : 'Inactive',
+                role: (value: string) => `Role: ${value}`,
+              }}
               clearAll="button"
               clearAllLabel="Reset"
             />

packages/datum-ui/src/components/features/data-table/__tests__/active-filters.test.tsx

@@ -142,11 +142,42 @@ describe('dataTableActiveFilters', () => {
       filters: { status: 'active' },
       props: {
         filterLabels: { status: 'Status' },
-        formatFilterValue: (_col, val) => String(val).toUpperCase(),
+        formatFilterValue: {
+          status: (value: string) => value.toUpperCase(),
+        },
+      },
+    })
+
+    expect(screen.getByText('ACTIVE')).toBeInTheDocument()
+  })
+
+  it('falls back to String(value) for columns without a formatter', () => {
+    renderActiveFilters({
+      filters: { status: 'active', department: 'engineering' },
+      props: {
+        filterLabels: { status: 'Status', department: 'Department' },
+        formatFilterValue: {
+          status: (value: string) => value.toUpperCase(),
+        },
       },
     })
 
     expect(screen.getByText('ACTIVE')).toBeInTheDocument()
+    expect(screen.getByText('engineering')).toBeInTheDocument()
+  })
+
+  it('supports dot-notation keys in formatFilterValue', () => {
+    renderActiveFilters({
+      filters: { 'status.approval': 'Pending' },
+      props: {
+        filterLabels: { 'status.approval': 'Approval' },
+        formatFilterValue: {
+          'status.approval': (value: string) => `[${value}]`,
+        },
+      },
+    })
+
+    expect(screen.getByText('[Pending]')).toBeInTheDocument()
   })
 
   it('falls back to column key when filterLabels not provided', () => {

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

@@ -1,9 +1,10 @@
 /// <reference types="@testing-library/jest-dom/vitest" />
 import { render, screen } from '@testing-library/react'
-import { describe, expect, it } from 'vitest'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
 import { ClientProvider } from '../core/client-provider'
 import { useDataTableStore } from '../core/data-table-context'
-import { useDataTablePagination, useDataTableSearch } from '../hooks/use-selectors'
+import { useDataTableFilters, useDataTableLoading, useDataTablePagination, useDataTableSearch } from '../hooks/use-selectors'
 
 interface TestRow {
   readonly id: string
@@ -43,4 +44,82 @@ describe('clientProvider', () => {
     expect(screen.getByTestId('search')).toHaveTextContent('')
     expect(screen.getByTestId('page-size')).toHaveTextContent('20')
   })
+
+  it('always renders children (no SSR gate)', () => {
+    render(
+      <ClientProvider data={testData} columns={testColumns}>
+        <span data-testid="child">visible</span>
+      </ClientProvider>,
+    )
+    expect(screen.getByTestId('child')).toBeInTheDocument()
+  })
+
+  it('accepts filters set before table is ready', async () => {
+    function FilterReader() {
+      const { filters, setFilter } = useDataTableFilters()
+      return (
+        <div>
+          <span data-testid="filter-count">{Object.keys(filters).length}</span>
+          <button type="button" onClick={() => setFilter('status', 'active')}>Set Filter</button>
+        </div>
+      )
+    }
+
+    render(
+      <ClientProvider data={testData} columns={testColumns}>
+        <FilterReader />
+      </ClientProvider>,
+    )
+
+    expect(screen.getByTestId('filter-count')).toHaveTextContent('0')
+    await userEvent.click(screen.getByText('Set Filter'))
+    expect(screen.getByTestId('filter-count')).toHaveTextContent('1')
+  })
+
+  it('syncs loading prop into store', async () => {
+    function LoadingReader() {
+      const { isLoading } = useDataTableLoading()
+      return <span data-testid="loading">{String(isLoading)}</span>
+    }
+
+    const { rerender } = render(
+      <ClientProvider data={[]} columns={testColumns} loading>
+        <LoadingReader />
+      </ClientProvider>,
+    )
+
+    // After hydration, loading=true should be synced to store
+    await vi.waitFor(() => {
+      expect(screen.getByTestId('loading')).toHaveTextContent('true')
+    })
+
+    // When loading changes to false, store updates
+    rerender(
+      <ClientProvider data={testData} columns={testColumns} loading={false}>
+        <LoadingReader />
+      </ClientProvider>,
+    )
+
+    await vi.waitFor(() => {
+      expect(screen.getByTestId('loading')).toHaveTextContent('false')
+    })
+  })
+
+  it('defaults isLoading to false when loading prop is omitted', async () => {
+    function LoadingReader() {
+      const { isLoading } = useDataTableLoading()
+      return <span data-testid="loading">{String(isLoading)}</span>
+    }
+
+    render(
+      <ClientProvider data={testData} columns={testColumns}>
+        <LoadingReader />
+      </ClientProvider>,
+    )
+
+    // Without loading prop, store should eventually settle to false
+    await vi.waitFor(() => {
+      expect(screen.getByTestId('loading')).toHaveTextContent('false')
+    })
+  })
 })