@snowpact/react-tanstack-query-table 1.2.0 → 1.4.0

package/README.md

@@ -8,110 +8,188 @@ Ultra-light, registry-based data table for React + TanStack Table + TanStack Que
 - **Registry-based**: Inject your own i18n, Link component, confirmation dialogs
 - **TypeScript**: Full type support with generics
 - **Two modes**: Client-side and Server-side pagination/filtering/sorting
-- **Customizable**: Override styles via registry
+- **Customizable**: Override styles via CSS variables or registry
 
-## Installation
+## Quick Setup
+
+### 1. Install
 
 ```bash
+npm install @tanstack/react-query @tanstack/react-table
 npm install @snowpact/react-tanstack-query-table
-# or
-pnpm add @snowpact/react-tanstack-query-table
 ```
 
-### Peer Dependencies
+### 2. Import styles
 
-```bash
-npm install @tanstack/react-query @tanstack/react-table react react-dom
+```tsx
+// In your app entry point (main.tsx or App.tsx)
+import '@snowpact/react-tanstack-query-table/styles.css';
 ```
 
-### Tailwind CSS Configuration
+### 3. Setup once
 
-Tailwind CSS is required. You must configure Tailwind to scan the package's classes:
+```tsx
+import { setupSnowTable } from '@snowpact/react-tanstack-query-table';
+import { Link } from 'react-router-dom';
 
-**In your `tailwind.config.css` (Tailwind v4):**
+// Your translation function (or just return the key)
+const t = (key: string) => translations[key] || key;
 
-```css
-/* Include SnowTable classes for Tailwind scanning */
-@source "node_modules/@snowpact/react-tanstack-query-table/dist";
+setupSnowTable({
+  t,
+  LinkComponent: Link,
+  confirm: ({ title }) => window.confirm(title),
+});
 ```
 
-**Or in `tailwind.config.js` (Tailwind v3):**
+### 4. Use the table
 
-```js
-module.exports = {
-  content: [
-    // ... your app files
-    './node_modules/@snowpact/react-tanstack-query-table/dist/**/*.js',
-  ],
-};
+```tsx
+import { SnowClientDataTable, SnowColumnConfig } from '@snowpact/react-tanstack-query-table';
+
+type User = { id: string; name: string; email: string; status: string };
+
+const columns: SnowColumnConfig<User>[] = [
+  { key: 'name', label: 'Name' },
+  { key: 'email', label: 'Email' },
+  { key: 'status', label: 'Status' },
+];
+
+<SnowClientDataTable
+  queryKey={['users']}
+  fetchAllItemsEndpoint={() => fetchUsers()}
+  columnConfig={columns}
+  enableGlobalSearch
+  enablePagination
+/>
 ```
 
-> **Note**: The path may vary depending on your project structure. If using a monorepo or workspace, adjust the path accordingly (e.g., `../../node_modules/...`).
+That's it! You have a working data table.
+
+---
+
+## Advanced Configuration
+
+### Theme Customization
+
+Override CSS variables to match your design:
+
+```css
+:root {
+  --snow-background: #ffffff;
+  --snow-foreground: #0a0a0a;
+  --snow-secondary: #f5f5f5;
+  --snow-secondary-foreground: #737373;
+  --snow-border: #d4d4d4;
+  --snow-ring: #a3a3a3;
+  --snow-radius: 0.375rem;
+}
 
-## Quick Start
+/* Dark mode */
+.dark {
+  --snow-background: #1a1a2e;
+  --snow-foreground: #eaeaea;
+  --snow-secondary: #16213e;
+  --snow-secondary-foreground: #a0a0a0;
+  --snow-border: #0f3460;
+  --snow-ring: #3b82f6;
+}
+```
 
-### 1. Setup (once in your app)
+### Setup with i18n (react-i18next)
 
 ```tsx
-import { setupSnowTable } from '@snowpact/react-tanstack-query-table';
 import { useTranslation } from 'react-i18next';
-import { Link } from 'react-router-dom';
-import { useConfirm } from './your-confirm-dialog';
+
+// Get t function at module level or use a hook wrapper
+const { t } = i18n;
 
 setupSnowTable({
-  useTranslation: () => useTranslation(),
+  t: (key) => t(key),
   LinkComponent: Link,
-  useConfirm: () => useConfirm(),
+  confirm: ({ title, content }) => {
+    const message = typeof content === 'string' ? `${title}\n\n${content}` : title;
+    return window.confirm(message);
+  },
 });
 ```
 
-> **Full setup example**: See [examples/full-setup.md](./examples/full-setup.md) for a complete Shadcn/UI integration with custom `useConfirm` hook, tooltips, and translations.
+Required translation keys:
+- `dataTable.search` - Search placeholder
+- `dataTable.elements` - "elements" label
+- `dataTable.searchEmpty` - Empty state text
+- `dataTable.resetFilters` - Reset button tooltip
+- `dataTable.columns` - Columns button label
 
-### 2. Use a Client Table
+### Setup with custom confirm dialog
 
 ```tsx
-import { SnowClientDataTable, SnowColumnConfig } from '@snowpact/react-tanstack-query-table';
-import { Edit, Trash } from 'lucide-react';
+import { useConfirmDialog } from './your-confirm-hook';
 
-type User = { id: string; name: string; email: string };
+// If you have a hook-based confirm dialog
+const confirmDialog = useConfirmDialog();
 
-const columns: SnowColumnConfig<User>[] = [{ key: 'name' }, { key: 'email' }];
+setupSnowTable({
+  t,
+  LinkComponent: Link,
+  confirm: async ({ title, content, confirmText, cancelText }) => {
+    return confirmDialog.open({
+      title,
+      description: content,
+      confirmLabel: confirmText,
+      cancelLabel: cancelText,
+    });
+  },
+});
+```
 
-<SnowClientDataTable
-  queryKey={['users']}
-  fetchAllItemsEndpoint={() => fetchUsers()}
-  columnConfig={columns}
-  actions={[
-    { type: 'click', icon: Edit, label: 'Edit', onClick: user => editUser(user) },
-    { type: 'endpoint', icon: Trash, label: 'Delete', endpoint: user => deleteUser(user.id) },
-  ]}
-  enableGlobalSearch
-  enablePagination
-/>;
+### Override component styles (rare)
+
+For deep customization, override internal Tailwind classes:
+
+```tsx
+setupSnowTable({
+  t,
+  LinkComponent: Link,
+  confirm: ({ title }) => window.confirm(title),
+  styles: {
+    button: {
+      visual: 'rounded-full bg-primary text-primary-foreground',
+      hover: 'hover:bg-primary/90',
+    },
+    table: {
+      header: 'bg-slate-100 dark:bg-slate-800',
+      rowHover: 'hover:bg-slate-50',
+    },
+    input: 'rounded-full border-2 border-primary',
+  },
+});
 ```
 
+---
+
 ## Client vs Server Mode
 
-| Mode       | Component         | Use case      | Data handling                                   |
-| ---------- | ----------------- | ------------- | ----------------------------------------------- |
-| **Client** | `SnowClientDataTable` | < 5,000 items | All data loaded, filtered/sorted locally        |
-| **Server** | `SnowServerDataTable` | > 5,000 items | Paginated API, server handles filtering/sorting |
+| Mode       | Component             | Use case      | Data handling                            |
+| ---------- | --------------------- | ------------- | ---------------------------------------- |
+| **Client** | `SnowClientDataTable` | < 5,000 items | All data loaded, filtered/sorted locally |
+| **Server** | `SnowServerDataTable` | > 5,000 items | Server handles pagination/filtering      |
 
 ### SnowClientDataTable
 
-Best for small to medium datasets. Fetches all data once via React Query, then handles pagination, search, and sorting entirely in the browser.
+Fetches all data once, handles everything in the browser:
 
 ```tsx
 <SnowClientDataTable
   queryKey={['users']}
-  fetchAllItemsEndpoint={() => api.getUsers()} // Returns User[]
+  fetchAllItemsEndpoint={() => api.getUsers()}
   columnConfig={columns}
 />
 ```
 
 ### SnowServerDataTable
 
-Best for large datasets. The server handles pagination, search, filtering, and sorting. Returns paginated results with a total count.
+Server handles pagination, search, filtering, and sorting:
 
 ```tsx
 import { SnowServerDataTable, ServerFetchParams } from '@snowpact/react-tanstack-query-table';
@@ -125,21 +203,25 @@ const fetchUsers = async (params: ServerFetchParams) => {
   };
 };
 
-<SnowServerDataTable queryKey={['users']} fetchServerEndpoint={fetchUsers} columnConfig={columns} />;
+<SnowServerDataTable
+  queryKey={['users']}
+  fetchServerEndpoint={fetchUsers}
+  columnConfig={columns}
+/>
 ```
 
+---
+
 ## Actions
 
-Actions appear as buttons in each row. Three types are available:
+Actions appear as buttons in each row:
 
 ### Click Action
 
-Simple callback when clicked.
-
 ```tsx
 {
   type: 'click',
-  icon: Edit,
+  icon: EditIcon,
   label: 'Edit',
   onClick: (item) => openEditModal(item),
 }
@@ -147,12 +229,10 @@ Simple callback when clicked.
 
 ### Link Action
 
-Navigates to a URL. Uses your registered `LinkComponent`.
-
 ```tsx
 {
   type: 'link',
-  icon: Eye,
+  icon: EyeIcon,
   label: 'View',
   href: (item) => `/users/${item.id}`,
   external: false,  // true for target="_blank"
@@ -161,123 +241,57 @@ Navigates to a URL. Uses your registered `LinkComponent`.
 
 ### Endpoint Action
 
-Calls an async endpoint (API mutation). Integrates with React Query invalidation.
-
-```tsx
-{
-  type: 'endpoint',
-  icon: Trash,
-  label: 'Delete',
-  endpoint: (item) => api.deleteUser(item.id),
-  onSuccess: () => queryClient.invalidateQueries(['users']),
-  onError: (error) => toast.error(error.message),
-}
-```
-
-### Confirmation Dialog
-
-Any action can require confirmation before executing:
-
 ```tsx
 {
   type: 'endpoint',
-  icon: Trash,
+  icon: TrashIcon,
   label: 'Delete',
   variant: 'danger',
   endpoint: (item) => api.deleteUser(item.id),
+  onSuccess: () => queryClient.invalidateQueries(['users']),
   confirm: {
     title: 'Delete user?',
     content: 'This action cannot be undone.',
-    confirmText: 'Delete',
-    cancelText: 'Cancel',
   },
 }
 ```
 
-For forms inside confirm dialogs, use a function to access the `close` helper:
-
-```tsx
-{
-  type: 'click',
-  icon: Edit,
-  label: 'Change Status',
-  onClick: () => {},
-  confirm: {
-    title: 'Change Status',
-    hideButtons: true,  // Form handles its own buttons
-    content: ({ close }) => (
-      <StatusForm
-        onSuccess={() => {
-          queryClient.invalidateQueries(['users']);
-          close();
-        }}
-      />
-    ),
-  },
-}
-```
-
-### Action Options
-
-| Option      | Type                                                        | Description                              |
-| ----------- | ----------------------------------------------------------- | ---------------------------------------- |
-| `icon`      | `ComponentType<SVGProps>`                                   | Icon component (lucide-react or any SVG) |
-| `label`     | `string`                                                    | Button label (used for tooltip)          |
-| `variant`   | `'default' \| 'danger' \| 'warning' \| 'info' \| 'success'` | Button color variant                     |
-| `display`   | `'button' \| 'dropdown'`                                    | Show as button or in dropdown menu       |
-| `hidden`    | `boolean`                                                   | Conditionally hide the action            |
-| `disabled`  | `boolean`                                                   | Disable the action                       |
-| `showLabel` | `boolean`                                                   | Show label text next to icon             |
-
 ### Dynamic Actions
 
-Actions can be functions that return the action config, allowing per-row customization:
-
 ```tsx
 actions={[
   (item) => ({
     type: 'click',
-    icon: item.isActive ? Pause : Play,
+    icon: item.isActive ? PauseIcon : PlayIcon,
     label: item.isActive ? 'Deactivate' : 'Activate',
     onClick: () => toggleStatus(item),
-    hidden: item.role === 'admin',  // Hide for admins
+    hidden: item.role === 'admin',
   }),
 ]}
 ```
 
-## Search & Filtering
+---
 
-### Global Search
-
-Enable fuzzy search across all columns:
-
-```tsx
-<SnowClientDataTable enableGlobalSearch texts={{ searchPlaceholder: 'Search users...' }} />
-```
+## Filters
 
-For custom search values (computed columns):
+### Global Search
 
 ```tsx
-const columns: SnowColumnConfig<User>[] = [
-  {
-    key: '_extra_fullName',
-    label: 'Full Name',
-    render: item => `${item.firstName} ${item.lastName}`,
-    searchableValue: item => `${item.firstName} ${item.lastName}`,
-  },
-];
+<SnowClientDataTable
+  enableGlobalSearch
+  texts={{ searchPlaceholder: 'Search users...' }}
+/>
 ```
 
 ### Column Filters
 
-Multi-select dropdown filters:
-
 ```tsx
 <SnowClientDataTable
   filters={[
     {
       key: 'status',
       label: 'Status',
+      multipleSelection: true,  // Allow multiple values
       options: [
         { value: 'active', label: 'Active' },
         { value: 'inactive', label: 'Inactive' },
@@ -297,14 +311,11 @@ Multi-select dropdown filters:
 
 ### Prefilters (Tabs)
 
-Quick segmentation via tabs:
-
 ```tsx
 <SnowClientDataTable
   prefilters={[
     { id: 'all', label: 'All' },
     { id: 'active', label: 'Active' },
-    { id: 'archived', label: 'Archived' },
   ]}
   prefilterFn={(item, prefilterId) => {
     if (prefilterId === 'all') return true;
@@ -313,72 +324,37 @@ Quick segmentation via tabs:
 />
 ```
 
-For server mode, the `prefilter` value is sent to your endpoint.
+---
 
-## Advanced Configuration
+## Other Features
 
-### Column Configuration
-
-Users can show/hide columns via a settings button. Configuration is saved in cookies.
+### URL State Persistence
 
 ```tsx
-<SnowClientDataTable
-  enableColumnConfiguration
-  columnConfig={[
-    { key: 'name' }, // Always visible
-    { key: 'email' },
-    { key: 'details', meta: { defaultHidden: true } }, // Hidden by default
-  ]}
-/>
+<SnowClientDataTable persistState />
 ```
 
-### URL State Persistence
+Saves pagination, search, filters, and sorting in URL params.
 
-Persist table state (pagination, search, filters, sorting) in URL query params:
+### Column Configuration
 
 ```tsx
 <SnowClientDataTable
-  persistState // State saved in URL
+  enableColumnConfiguration
+  columnConfig={[
+    { key: 'name' },
+    { key: 'details', meta: { defaultHidden: true } },
+  ]}
 />
 ```
 
-URL params used:
-
-- `dt_page`, `dt_pageSize` - Pagination
-- `dt_search` - Search query
-- `dt_prefilter` - Active prefilter
-- `dt_filters` - Column filters
-- `dt_sortBy`, `dt_sortDesc` - Sorting
-
-### Column Meta Properties
-
-```tsx
-{
-  key: 'actions',
-  meta: {
-    width: '100px',           // Fixed width
-    minWidth: '80px',         // Minimum width
-    center: true,             // Center content
-    defaultHidden: true,      // Hidden by default
-    disableColumnClick: true, // Disable row click for this column
-  },
-}
-```
-
 ### Sorting
 
-```tsx
-<SnowClientDataTable enableSorting defaultSortBy="createdAt" defaultSortOrder="desc" />
-```
-
-### Pagination
-
 ```tsx
 <SnowClientDataTable
-  enablePagination
-  defaultPageSize={25}
-  displayTotalNumber // Show "X elements"
-  enableElementLabel // Show element label
+  enableSorting
+  defaultSortBy="createdAt"
+  defaultSortOrder="desc"
 />
 ```
 
@@ -386,43 +362,35 @@ URL params used:
 
 ```tsx
 <SnowClientDataTable
-  onRowClick={item => navigate(`/users/${item.id}`)}
-  activeRowId={selectedUserId} // Highlight active row
+  onRowClick={(item) => navigate(`/users/${item.id}`)}
+  activeRowId={selectedUserId}
 />
 ```
 
-### Custom Styles
-
-Override default Tailwind classes via the registry:
+### Custom Column Rendering
 
 ```tsx
-setupSnowTable({
-  // ... other options
-  styles: {
-    table: {
-      wrapper: 'border border-gray-200 rounded-lg',
-      header: 'bg-gray-50',
-      row: 'hover:bg-gray-100',
-    },
-    button: {
-      visual: 'bg-blue-500 text-white',
-      hover: 'hover:bg-blue-600',
-    },
+const columns: SnowColumnConfig<User>[] = [
+  { key: 'name', label: 'Name' },
+  {
+    key: 'status',
+    label: 'Status',
+    render: (item) => (
+      <span className={item.status === 'active' ? 'text-green-500' : 'text-red-500'}>
+        {item.status}
+      </span>
+    ),
   },
-});
+  {
+    key: '_extra_fullName',  // Use _extra_ prefix for computed columns
+    label: 'Full Name',
+    render: (item) => `${item.firstName} ${item.lastName}`,
+    searchableValue: (item) => `${item.firstName} ${item.lastName}`,
+  },
+];
 ```
 
-### Action Hover (Tooltips)
-
-Integrate with your tooltip system:
-
-```tsx
-setupSnowTable({
-  // ... other options
-  onActionHover: ({ label, element }) => showTooltip(label, element),
-  onActionUnhover: () => hideTooltip(),
-});
-```
+---
 
 ## API Reference
 
@@ -433,23 +401,22 @@ setupSnowTable({
 | `queryKey`                  | `string[]`              | Required | React Query cache key           |
 | `fetchAllItemsEndpoint`     | `() => Promise<T[]>`    | Required | Data fetching function          |
 | `columnConfig`              | `SnowColumnConfig<T>[]` | Required | Column definitions              |
-| `actions`                   | `TableAction<T>[]`      | `[]`     | Row actions                     |
-| `filters`                   | `FilterConfig<T>[]`     | `[]`     | Column filters                  |
-| `prefilters`                | `PreFilter[]`           | `[]`     | Tab filters                     |
+| `actions`                   | `TableAction<T>[]`      | -        | Row actions                     |
+| `filters`                   | `FilterConfig<T>[]`     | -        | Column filters                  |
+| `prefilters`                | `PreFilter[]`           | -        | Tab filters                     |
 | `prefilterFn`               | `(item, id) => boolean` | -        | Client-side prefilter logic     |
 | `persistState`              | `boolean`               | `false`  | Persist state in URL            |
 | `enableGlobalSearch`        | `boolean`               | `false`  | Enable search bar               |
-| `enablePagination`          | `boolean`               | `false`  | Enable pagination               |
-| `enableSorting`             | `boolean`               | `false`  | Enable column sorting           |
+| `enablePagination`          | `boolean`               | `true`   | Enable pagination               |
+| `enableSorting`             | `boolean`               | `true`   | Enable column sorting           |
 | `enableColumnConfiguration` | `boolean`               | `false`  | Enable column visibility toggle |
-| `enableResetFilters`        | `boolean`               | `false`  | Show reset filters button       |
 | `defaultPageSize`           | `number`                | `10`     | Initial page size               |
 | `defaultSortBy`             | `string`                | -        | Initial sort column             |
 | `defaultSortOrder`          | `'asc' \| 'desc'`       | `'asc'`  | Initial sort direction          |
 
 ### SnowServerDataTable Props
 
-Same as `SnowClientDataTable`, except:
+Same as `SnowClientDataTable`, plus:
 
 | Prop                  | Type                                                                 | Description              |
 | --------------------- | -------------------------------------------------------------------- | ------------------------ |