@casinogate/ui 1.0.0 → 1.0.1

package/dist/components/data-table/README.md

@@ -0,0 +1,1285 @@
+# DataTable Component Guide
+
+A powerful, flexible, and feature-rich data table component built on top of `@tanstack/table-core` for Svelte 5 applications. The DataTable provides advanced functionality including sorting, pagination, resizing, infinite scrolling, and fully customizable rendering.
+
+## 🎨 [View Live Examples in Storybook](https://static.casinogate.dev/components/master/?path=/story/ui-kit-datatable--primitive)
+
+Explore interactive examples and experiment with all DataTable features in our live Storybook.
+
+---
+
+## 📚 Table of Contents
+
+- [DataTable Component Guide](#datatable-component-guide)
+  - [🎨 View Live Examples in Storybook](#-view-live-examples-in-storybook)
+  - [📚 Table of Contents](#-table-of-contents)
+  - [When to Use](#when-to-use)
+  - [Installation \& Import](#installation--import)
+    - [From Package](#from-package)
+    - [Import the Component](#import-the-component)
+    - [For Advanced Use Cases (Primitives)](#for-advanced-use-cases-primitives)
+  - [Basic Usage](#basic-usage)
+    - [Minimal Example](#minimal-example)
+    - [Key Concepts](#key-concepts)
+  - [Component Architecture](#component-architecture)
+    - [1. Preset Component (Recommended)](#1-preset-component-recommended)
+    - [2. Primitive Components (Advanced)](#2-primitive-components-advanced)
+  - [Advanced Features](#advanced-features)
+    - [Sorting](#sorting)
+    - [Pagination](#pagination)
+    - [Column Resizing](#column-resizing)
+    - [Infinite Scrolling](#infinite-scrolling)
+    - [Custom Cell Rendering](#custom-cell-rendering)
+      - [Simple String/HTML Rendering](#simple-stringhtml-rendering)
+      - [Using `renderComponent` for Svelte Components](#using-rendercomponent-for-svelte-components)
+      - [Using `renderSnippet` for Inline Templates](#using-rendersnippet-for-inline-templates)
+      - [Comparison: When to Use Each Approach](#comparison-when-to-use-each-approach)
+    - [Practical Examples with renderComponent](#practical-examples-with-rendercomponent)
+      - [Interactive Checkbox Column](#interactive-checkbox-column)
+      - [Avatar with Fallback](#avatar-with-fallback)
+      - [Dropdown Actions Menu](#dropdown-actions-menu)
+    - [Loading States](#loading-states)
+    - [Empty States](#empty-states)
+  - [API Reference](#api-reference)
+    - [DataTable Props](#datatable-props)
+    - [createTable Options](#createtable-options)
+    - [Column Definition](#column-definition)
+    - [Table Utilities](#table-utilities)
+  - [TypeScript Support](#typescript-support)
+    - [Typing Your Data](#typing-your-data)
+    - [Extend Column Meta](#extend-column-meta)
+  - [Styling \& Theming](#styling--theming)
+    - [Using Variants](#using-variants)
+    - [Custom Styling](#custom-styling)
+    - [Cell-Level Styling](#cell-level-styling)
+    - [Tailwind Integration](#tailwind-integration)
+  - [Common Patterns](#common-patterns)
+    - [Server-Side Pagination](#server-side-pagination)
+    - [Row Click Handling](#row-click-handling)
+    - [Conditional Row Styling](#conditional-row-styling)
+    - [Searchable Table](#searchable-table)
+  - [Troubleshooting](#troubleshooting)
+    - [Common Issues](#common-issues)
+      - [❌ Data not updating when changed](#-data-not-updating-when-changed)
+      - [❌ "Cannot read property 'getHeaderGroups' of undefined"](#-cannot-read-property-getheadergroups-of-undefined)
+      - [❌ Sorting not working](#-sorting-not-working)
+      - [❌ Column resize handles not visible](#-column-resize-handles-not-visible)
+      - [❌ Performance issues with large datasets](#-performance-issues-with-large-datasets)
+    - [Debugging Tips](#debugging-tips)
+  - [Accessibility](#accessibility)
+    - [Best Practices](#best-practices)
+  - [Further Resources](#further-resources)
+  - [Quick Reference](#quick-reference)
+    - [Minimal Setup](#minimal-setup)
+    - [With Pagination](#with-pagination)
+    - [With Sorting](#with-sorting)
+    - [With Resizing](#with-resizing)
+
+---
+
+## When to Use
+
+Use the DataTable component when you need to:
+
+- Display tabular data with consistent styling
+- Implement sorting, filtering, or pagination
+- Handle large datasets efficiently
+- Provide column resizing capabilities
+- Implement infinite scrolling for real-time data
+- Customize cell rendering with complex components
+- Maintain responsive table layouts
+
+---
+
+## Installation & Import
+
+### From Package
+
+If using the published package:
+
+```bash
+pnpm add @casinogate/ui
+```
+
+### Import the Component
+
+```typescript
+import { DataTable, createTable, rowModels } from '@casinogate/ui';
+import type { ColumnDef } from '@casinogate/ui';
+
+// Import styles (required)
+import '@casinogate/ui/styles.css';
+```
+
+### For Advanced Use Cases (Primitives)
+
+For complete control over table structure:
+
+```typescript
+import { DataTablePrimitive } from '@casinogate/ui';
+
+const { Root, Table, Header, Head, Body, Row, Cell, SortButton, ResizeHandler, FlexRender } = DataTablePrimitive;
+```
+
+---
+
+## Basic Usage
+
+### Minimal Example
+
+Here's the simplest way to create a functional data table:
+
+```svelte
+<script lang="ts">
+  import { DataTable, createTable, rowModels } from '@casinogate/ui';
+  import type { ColumnDef } from '@casinogate/ui';
+
+  type User = {
+    id: number;
+    name: string;
+    email: string;
+  };
+
+  const data: User[] = [
+    { id: 1, name: 'John Doe', email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
+  ];
+
+  const columns: ColumnDef<User>[] = [
+    {
+      accessorKey: 'id',
+      header: 'ID',
+    },
+    {
+      accessorKey: 'name',
+      header: 'Name',
+    },
+    {
+      accessorKey: 'email',
+      header: 'Email',
+    },
+  ];
+
+  const table = createTable({
+    get data() {
+      return data;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+  });
+</script>
+
+<DataTable {table} />
+```
+
+### Key Concepts
+
+1. **Define your data type** - Use TypeScript interfaces for type safety
+2. **Create column definitions** - Specify which fields to display and how
+3. **Initialize the table** - Use `createTable` with your data and columns
+4. **Render the component** - Pass the table instance to `<DataTable>`
+
+---
+
+## Component Architecture
+
+The DataTable is available in two forms:
+
+### 1. Preset Component (Recommended)
+
+The high-level `<DataTable>` component with built-in features:
+
+- Automatic header and body rendering
+- Built-in loading states with spinner
+- Empty state handling
+- Sorting button integration
+- Column resize handlers
+
+**Use when:** You want a fully-functional table quickly.
+
+### 2. Primitive Components (Advanced)
+
+Fine-grained control with individual components:
+
+- `DataTablePrimitive.Root` - Container with context
+- `DataTablePrimitive.Table` - Table wrapper
+- `DataTablePrimitive.Header` - Table header section
+- `DataTablePrimitive.Head` - Header cell
+- `DataTablePrimitive.Body` - Table body section
+- `DataTablePrimitive.Row` - Table row
+- `DataTablePrimitive.Cell` - Table cell
+- `DataTablePrimitive.SortButton` - Sorting control
+- `DataTablePrimitive.ResizeHandler` - Column resize handle
+- `DataTablePrimitive.FlexRender` - Content renderer
+
+**Use when:** You need complete control over markup and behavior.
+
+---
+
+## Advanced Features
+
+### Sorting
+
+Enable sorting on specific columns:
+
+```typescript
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    enableSorting: true, // Enable sorting for this column
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    enableSorting: true,
+  },
+];
+
+const table = createTable({
+  get data() {
+    return data;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(),
+  getSortedRowModel: rowModels.sortedRowModel(), // Add sorting model
+});
+```
+
+The sort button appears automatically when `enableSorting: true` and using the preset `<DataTable>` component.
+
+### Pagination
+
+Implement client-side pagination:
+
+```svelte
+<script lang="ts">
+  import { DataTable, createTable, rowModels, usePaginationState } from '@casinogate/ui';
+  import { Pagination } from '@casinogate/ui';
+
+  // Create pagination state manager
+  const paginationState = usePaginationState();
+
+  const table = createTable({
+    get data() {
+      return data;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+    getPaginationRowModel: rowModels.paginationRowModel(), // Add pagination
+
+    state: {
+      get pagination() {
+        return paginationState.value;
+      },
+    },
+
+    onPaginationChange: paginationState.updater,
+  });
+</script>
+
+<DataTable {table} />
+
+<Pagination.Basic
+  bind:page={() => table.getState().pagination.pageIndex + 1, (value) => table.setPageIndex(value - 1)}
+  count={data.length}
+  perPage={table.getState().pagination.pageSize}
+  siblingCount={1}
+/>
+```
+
+### Column Resizing
+
+Allow users to resize columns:
+
+```typescript
+import { useResizeState } from '@casinogate/ui';
+
+const resizeState = useResizeState();
+
+const table = createTable({
+  get data() {
+    return data;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(),
+
+  columnResizeMode: 'onChange', // Enable resize mode
+
+  state: {
+    get columnSizing() {
+      return resizeState.value;
+    },
+  },
+
+  onColumnSizingChange: resizeState.updater,
+});
+```
+
+```svelte
+<!-- Enable resizable prop on the component -->
+<DataTable {table} resizable />
+```
+
+### Infinite Scrolling
+
+Load more data as the user scrolls:
+
+```svelte
+<script lang="ts">
+  let data = $state<Item[]>([]);
+  let page = $state(1);
+  let isLoading = $state(false);
+
+  async function loadMore() {
+    isLoading = true;
+    const response = await fetch(`/api/data?page=${page}`);
+    const newData = await response.json();
+    data = [...data, ...newData];
+    page++;
+    isLoading = false;
+  }
+
+  const table = createTable({
+    get data() {
+      return data;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+
+    features: {
+      onLastRowReached: () => {
+        if (!isLoading) {
+          loadMore();
+        }
+      },
+      get isLoading() {
+        return isLoading;
+      },
+    },
+  });
+
+  $effect(() => {
+    loadMore(); // Initial load
+  });
+</script>
+
+<DataTable {table} class="h-[400px]" />
+```
+
+### Custom Cell Rendering
+
+Customize how cells display data using three different approaches:
+
+#### Simple String/HTML Rendering
+
+Return a string or HTML directly from cell/header functions:
+
+```typescript
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    cell: (info) => {
+      const value = info.getValue();
+      return `👤 ${value}`;
+    },
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: (info) => {
+      const status = info.getValue();
+      const color = status === 'active' ? 'green' : 'gray';
+      return `<span class="text-${color}-600">${status}</span>`;
+    },
+  },
+];
+```
+
+#### Using `renderComponent` for Svelte Components
+
+The `renderComponent` helper allows you to render full Svelte components in headers and cells:
+
+```typescript
+import { renderComponent } from '@casinogate/ui';
+import SortButton from './sort-button.svelte';
+import StatusBadge from './status-badge.svelte';
+import ActionMenu from './action-menu.svelte';
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: ({ column }) =>
+      renderComponent(SortButton, {
+        label: 'Name',
+        onclick: () => column.toggleSorting(),
+      }),
+    cell: (info) => info.getValue(),
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) =>
+      renderComponent(StatusBadge, {
+        status: row.original.status,
+        variant: row.original.isPremium ? 'premium' : 'default',
+      }),
+  },
+  {
+    id: 'actions',
+    header: 'Actions',
+    cell: ({ row }) =>
+      renderComponent(ActionMenu, {
+        userId: row.original.id,
+        onEdit: () => handleEdit(row.original),
+        onDelete: () => handleDelete(row.original),
+      }),
+    enableSorting: false,
+  },
+];
+```
+
+**Key Benefits:**
+
+- Pass reactive props to components
+- Full component lifecycle and state management
+- Event handlers work naturally
+- Type-safe props with TypeScript
+
+#### Using `renderSnippet` for Inline Templates
+
+The `renderSnippet` helper works with Svelte's `createRawSnippet` to render inline templates:
+
+```typescript
+<script lang="ts">
+  import { createRawSnippet } from 'svelte';
+  import { renderSnippet, createTable, rowModels } from '@casinogate/ui';
+  import type { ColumnDef } from '@casinogate/ui';
+
+  type Payment = {
+    id: string;
+    amount: number;
+    status: 'Pending' | 'Processing' | 'Success' | 'Failed';
+    email: string;
+  };
+
+  // Create a snippet for status cell
+  const statusSnippet = createRawSnippet<[{ status: string }]>((getStatus) => {
+    const { status } = getStatus();
+    return {
+      render: () => `<div class="capitalize">${status}</div>`,
+    };
+  });
+
+  // Create a snippet for amount with formatting
+  const amountSnippet = createRawSnippet<[{ amount: number }]>((getAmount) => {
+    const { amount } = getAmount();
+    const formatter = new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'USD',
+    });
+    const formatted = formatter.format(amount);
+    return {
+      render: () => `<div class="text-right font-medium">${formatted}</div>`,
+    };
+  });
+
+  const columns: ColumnDef<Payment>[] = [
+    {
+      accessorKey: 'status',
+      header: 'Status',
+      cell: ({ row }) =>
+        renderSnippet(statusSnippet, {
+          status: row.original.status,
+        }),
+    },
+    {
+      accessorKey: 'amount',
+      header: () => {
+        const headerSnippet = createRawSnippet(() => {
+          return {
+            render: () => `<div class="text-right">Amount</div>`,
+          };
+        });
+        return renderSnippet(headerSnippet);
+      },
+      cell: ({ row }) =>
+        renderSnippet(amountSnippet, {
+          amount: row.original.amount,
+        }),
+    },
+    {
+      accessorKey: 'email',
+      header: 'Email',
+      cell: ({ row }) => {
+        // Inline snippet creation
+        const emailSnippet = createRawSnippet<[{ email: string }]>((getEmail) => {
+          const { email } = getEmail();
+          return {
+            render: () => `<div class="lowercase">${email}</div>`,
+          };
+        });
+
+        return renderSnippet(emailSnippet, {
+          email: row.original.email,
+        });
+      },
+    },
+  ];
+
+  const table = createTable({
+    get data() {
+      return payments;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+  });
+</script>
+```
+
+**Key Benefits:**
+
+- Lightweight alternative to full components
+- Inline template rendering
+- Access to formatting logic
+- Can pass data parameters
+
+#### Comparison: When to Use Each Approach
+
+| Approach            | Best For                                              | Pros                                      | Cons                          |
+| ------------------- | ----------------------------------------------------- | ----------------------------------------- | ----------------------------- |
+| **String/HTML**     | Simple text, icons, basic styling                     | Fastest, simplest                         | No reactivity, no components  |
+| **renderComponent** | Interactive elements, complex UI, reusable components | Full Svelte features, type-safe, reusable | Slightly more overhead        |
+| **renderSnippet**   | Formatted text, inline templates, simple markup       | Lightweight, inline logic, type-safe      | Limited to template rendering |
+
+### Practical Examples with renderComponent
+
+#### Interactive Checkbox Column
+
+```typescript
+import { renderComponent } from '@casinogate/ui';
+import Checkbox from './checkbox.svelte';
+
+const columns: ColumnDef<User>[] = [
+  {
+    id: 'select',
+    header: ({ table }) =>
+      renderComponent(Checkbox, {
+        checked: table.getIsAllPageRowsSelected(),
+        indeterminate: table.getIsSomePageRowsSelected() && !table.getIsAllPageRowsSelected(),
+        onCheckedChange: (value) => table.toggleAllPageRowsSelected(!!value),
+        'aria-label': 'Select all',
+      }),
+    cell: ({ row }) =>
+      renderComponent(Checkbox, {
+        checked: row.getIsSelected(),
+        onCheckedChange: (value) => row.toggleSelected(!!value),
+        'aria-label': 'Select row',
+      }),
+    enableSorting: false,
+    enableHiding: false,
+  },
+  // ... other columns
+];
+```
+
+#### Avatar with Fallback
+
+```typescript
+// avatar-cell.svelte
+<script lang="ts">
+  let { src, name }: { src?: string; name: string } = $props();
+
+  const initials = $derived(
+    name
+      .split(' ')
+      .map((n) => n[0])
+      .join('')
+      .toUpperCase()
+  );
+</script>
+
+<div class="flex items-center gap-2">
+  {#if src}
+    <img src={src} alt={name} class="h-8 w-8 rounded-full" />
+  {:else}
+    <div class="flex h-8 w-8 items-center justify-center rounded-full bg-gray-200">
+      {initials}
+    </div>
+  {/if}
+  <span>{name}</span>
+</div>
+```
+
+```typescript
+// In your columns definition
+import { renderComponent } from '@casinogate/ui';
+import AvatarCell from './avatar-cell.svelte';
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'User',
+    cell: ({ row }) =>
+      renderComponent(AvatarCell, {
+        src: row.original.avatar,
+        name: row.original.name,
+      }),
+  },
+];
+```
+
+#### Dropdown Actions Menu
+
+```typescript
+// actions-menu.svelte
+<script lang="ts">
+  import * as DropdownMenu from '$lib/components/dropdown-menu';
+  import { MoreHorizontal, Edit, Trash, Copy } from 'lucide-svelte';
+
+  let {
+    userId,
+    onEdit,
+    onDelete,
+    onDuplicate
+  }: {
+    userId: string;
+    onEdit: () => void;
+    onDelete: () => void;
+    onDuplicate: () => void;
+  } = $props();
+</script>
+
+<DropdownMenu.Root>
+  <DropdownMenu.Trigger>
+    <button class="rounded p-2 hover:bg-gray-100">
+      <MoreHorizontal class="h-4 w-4" />
+    </button>
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content>
+    <DropdownMenu.Item onclick={onEdit}>
+      <Edit class="mr-2 h-4 w-4" />
+      Edit
+    </DropdownMenu.Item>
+    <DropdownMenu.Item onclick={onDuplicate}>
+      <Copy class="mr-2 h-4 w-4" />
+      Duplicate
+    </DropdownMenu.Item>
+    <DropdownMenu.Separator />
+    <DropdownMenu.Item onclick={onDelete} class="text-red-600">
+      <Trash class="mr-2 h-4 w-4" />
+      Delete
+    </DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu.Root>
+```
+
+```typescript
+import { renderComponent } from '@casinogate/ui';
+import ActionsMenu from './actions-menu.svelte';
+
+const columns: ColumnDef<User>[] = [
+  // ... other columns
+  {
+    id: 'actions',
+    header: 'Actions',
+    cell: ({ row }) =>
+      renderComponent(ActionsMenu, {
+        userId: row.original.id,
+        onEdit: () => openEditModal(row.original),
+        onDelete: () => confirmDelete(row.original.id),
+        onDuplicate: () => duplicateUser(row.original),
+      }),
+    enableHiding: false,
+  },
+];
+```
+
+### Loading States
+
+The preset DataTable automatically handles loading states:
+
+```typescript
+const table = createTable({
+  // ... other options
+  features: {
+    get isLoading() {
+      return isDataLoading;
+    },
+  },
+});
+```
+
+Loading indicators appear:
+
+- **Initial load**: Full spinner overlay
+- **Infinite scroll**: Spinner at bottom during data fetch
+
+### Empty States
+
+Customize the message when no data is available:
+
+```svelte
+<DataTable {table}>
+  {#snippet empty()}
+    <div class="py-8 text-center">
+      <p>No users found.</p>
+      <button onclick={loadData}>Retry</button>
+    </div>
+  {/snippet}
+</DataTable>
+```
+
+---
+
+## API Reference
+
+### DataTable Props
+
+| Prop        | Type                             | Default         | Description                               |
+| ----------- | -------------------------------- | --------------- | ----------------------------------------- |
+| `table`     | `CreateTableReturn<TData>`       | **Required**    | Table instance created with `createTable` |
+| `variant`   | `'primary' \| 'secondary'`       | `'primary'`     | Visual style variant                      |
+| `stripped`  | `boolean`                        | `true`          | Alternating row background colors         |
+| `align`     | `'start' \| 'center' \| 'end'`   | `'start'`       | Text alignment in cells                   |
+| `rounded`   | `'none' \| 'sm' \| 'md' \| 'lg'` | `'sm'`          | Border radius                             |
+| `resizable` | `boolean`                        | `false`         | Enable column resizing                    |
+| `class`     | `string`                         | `undefined`     | Additional CSS classes                    |
+| `empty`     | `Snippet`                        | Default message | Custom empty state content                |
+| `loading`   | `Snippet`                        | Default spinner | Custom loading indicator                  |
+
+### createTable Options
+
+Core configuration for table behavior:
+
+```typescript
+interface TableOptions<TData> {
+  // Required
+  data: TData[] | (() => TData[]);
+  columns: ColumnDef<TData>[];
+  getCoreRowModel: () => RowModel<TData>;
+
+  // Optional - Row Models
+  getSortedRowModel?: () => RowModel<TData>;
+  getPaginationRowModel?: () => RowModel<TData>;
+  getFilteredRowModel?: () => RowModel<TData>;
+
+  // Optional - State Management
+  state?: Partial<TableState>;
+  onStateChange?: (updater: Updater<TableState>) => void;
+  onPaginationChange?: (updater: Updater<PaginationState>) => void;
+  onSortingChange?: (updater: Updater<SortingState>) => void;
+  onColumnSizingChange?: (updater: Updater<ColumnSizingState>) => void;
+
+  // Optional - Column Sizing
+  columnResizeMode?: 'onChange' | 'onEnd';
+  defaultColumn?: Partial<ColumnDef<TData>>;
+
+  // Optional - Custom Features
+  features?: {
+    onLastRowReached?: () => void;
+    isLoading?: boolean;
+  };
+
+  // Optional - Meta Data
+  meta?: Record<string, any>;
+}
+```
+
+### Column Definition
+
+Define how each column behaves:
+
+```typescript
+interface ColumnDef<TData> {
+  // Identifier
+  accessorKey: keyof TData; // For simple property access
+  id?: string; // Custom identifier
+
+  // Display
+  header: string | ((props: HeaderContext) => any);
+  cell?: (props: CellContext) => any;
+  footer?: string | ((props: HeaderContext) => any);
+
+  // Behavior
+  enableSorting?: boolean; // Default: true
+  enableResizing?: boolean; // Default: true
+  enableHiding?: boolean; // Default: true
+
+  // Sizing
+  size?: number; // Default width
+  minSize?: number; // Minimum width
+  maxSize?: number; // Maximum width
+
+  // Metadata
+  meta?: Record<string, any>;
+}
+```
+
+### Table Utilities
+
+State management helpers:
+
+```typescript
+// Pagination State
+const paginationState = usePaginationState();
+// Returns: { value: PaginationState, updater: (updater) => void }
+
+// Resize State
+const resizeState = useResizeState();
+// Returns: { value: ColumnSizingState, updater: (updater) => void }
+
+// Row Selection State (if needed)
+const selectionState = useRowSelectionState();
+// Returns: { value: RowSelectionState, updater: (updater) => void }
+
+// Row Models
+rowModels.coreRowModel(); // Required base model
+rowModels.sortedRowModel(); // For sorting
+rowModels.paginationRowModel(); // For pagination
+rowModels.filteredRowModel(); // For filtering
+```
+
+---
+
+## TypeScript Support
+
+### Typing Your Data
+
+```typescript
+// Define your data structure
+interface User {
+  id: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+
+// Type your columns
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'firstName', // ✅ TypeScript validates this exists
+    header: 'First Name',
+  },
+  {
+    accessorKey: 'invalidKey', // ❌ TypeScript error!
+    header: 'Invalid',
+  },
+];
+
+// Type your table
+const table = createTable<User>({
+  get data() {
+    return users;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(),
+});
+```
+
+### Extend Column Meta
+
+Add custom metadata to columns:
+
+```typescript
+declare module '@tanstack/table-core' {
+  interface ColumnMeta<TData extends RowData, TValue> {
+    className?: string;
+    headerClassName?: string;
+    tooltip?: string;
+  }
+}
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    meta: {
+      className: 'font-mono',
+      tooltip: 'User email address',
+    },
+  },
+];
+```
+
+---
+
+## Styling & Theming
+
+### Using Variants
+
+Built-in style variants:
+
+```svelte
+<!-- Primary variant (default) -->
+<DataTable {table} variant="primary" />
+
+<!-- Secondary variant -->
+<DataTable {table} variant="secondary" />
+```
+
+### Custom Styling
+
+Apply custom classes:
+
+```svelte
+<DataTable {table} class="border-2 shadow-lg" rounded="lg" stripped={false} />
+```
+
+### Cell-Level Styling
+
+Style individual cells using column meta:
+
+```typescript
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: (info) => {
+      const status = info.getValue();
+      const className = status === 'active' ? 'text-green-600 font-semibold' : 'text-gray-400';
+      return `<span class="${className}">${status}</span>`;
+    },
+  },
+];
+```
+
+### Tailwind Integration
+
+The DataTable uses Tailwind CSS with the `cgui:` prefix:
+
+```css
+/* Custom styles in your global CSS */
+.cgui\\:custom-table-row:hover {
+  background-color: theme('colors.blue.50');
+}
+```
+
+---
+
+## Common Patterns
+
+### Server-Side Pagination
+
+```svelte
+<script lang="ts">
+  let data = $state<Item[]>([]);
+  let totalCount = $state(0);
+  let currentPage = $state(1);
+  const pageSize = 20;
+
+  async function fetchData(page: number) {
+    const response = await fetch(`/api/items?page=${page}&limit=${pageSize}`);
+    const result = await response.json();
+    data = result.items;
+    totalCount = result.total;
+  }
+
+  const paginationState = usePaginationState();
+
+  const table = createTable({
+    get data() {
+      return data;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+    manualPagination: true, // Disable client-side pagination
+    pageCount: Math.ceil(totalCount / pageSize),
+
+    state: {
+      get pagination() {
+        return paginationState.value;
+      },
+    },
+
+    onPaginationChange: (updater) => {
+      paginationState.updater(updater);
+      const newState = typeof updater === 'function' ? updater(paginationState.value) : updater;
+      fetchData(newState.pageIndex + 1);
+    },
+  });
+
+  $effect(() => {
+    fetchData(currentPage);
+  });
+</script>
+
+<DataTable {table} />
+```
+
+### Row Click Handling
+
+```svelte
+<script lang="ts">
+  import { DataTablePrimitive } from '@casinogate/ui';
+
+  function handleRowClick(row: any) {
+    console.log('Clicked row:', row.original);
+    // Navigate, open modal, etc.
+  }
+</script>
+
+<DataTablePrimitive.Root {table}>
+  <DataTablePrimitive.Table>
+    <DataTablePrimitive.Header>
+      <!-- Header rows -->
+    </DataTablePrimitive.Header>
+
+    <DataTablePrimitive.Body>
+      {#each table.getRowModel().rows as row}
+        <DataTablePrimitive.Row onclick={() => handleRowClick(row)} class="cursor-pointer hover:bg-gray-50">
+          {#each row.getVisibleCells() as cell}
+            <DataTablePrimitive.Cell {cell}>
+              <DataTablePrimitive.FlexRender content={cell.column.columnDef.cell} context={cell.getContext()} />
+            </DataTablePrimitive.Cell>
+          {/each}
+        </DataTablePrimitive.Row>
+      {/each}
+    </DataTablePrimitive.Body>
+  </DataTablePrimitive.Table>
+</DataTablePrimitive.Root>
+```
+
+### Conditional Row Styling
+
+```typescript
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    cell: (info) => {
+      const row = info.row.original;
+      if (row.isVIP) {
+        return `<span class="text-gold-600 font-bold">⭐ ${info.getValue()}</span>`;
+      }
+      return info.getValue();
+    },
+  },
+];
+```
+
+### Searchable Table
+
+```svelte
+<script lang="ts">
+  import { rowModels } from '@casinogate/ui';
+
+  let searchQuery = $state('');
+
+  const filteredData = $derived(
+    data.filter((item) =>
+      Object.values(item).some((value) => String(value).toLowerCase().includes(searchQuery.toLowerCase()))
+    )
+  );
+
+  const table = createTable({
+    get data() {
+      return filteredData;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+  });
+</script>
+
+<input type="search" bind:value={searchQuery} placeholder="Search..." />
+
+<DataTable {table} />
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### ❌ Data not updating when changed
+
+**Problem:** Table doesn't reflect data changes.
+
+**Solution:** Use a getter function for reactive data:
+
+```typescript
+// ❌ Wrong
+const table = createTable({
+  data: myData,
+  // ...
+});
+
+// ✅ Correct
+const table = createTable({
+  get data() {
+    return myData;
+  },
+  // ...
+});
+```
+
+#### ❌ "Cannot read property 'getHeaderGroups' of undefined"
+
+**Problem:** Table instance not properly initialized.
+
+**Solution:** Ensure `getCoreRowModel` is provided:
+
+```typescript
+const table = createTable({
+  get data() {
+    return data;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(), // Required!
+});
+```
+
+#### ❌ Sorting not working
+
+**Problem:** Sort button appears but doesn't sort.
+
+**Solution:** Add the sorted row model:
+
+```typescript
+const table = createTable({
+  // ... other options
+  getSortedRowModel: rowModels.sortedRowModel(), // Add this
+});
+```
+
+#### ❌ Column resize handles not visible
+
+**Problem:** Resize functionality enabled but handles don't appear.
+
+**Solution:** Ensure `resizable` prop is set:
+
+```svelte
+<DataTable {table} resizable />
+```
+
+#### ❌ Performance issues with large datasets
+
+**Problem:** Table is slow with 1000+ rows.
+
+**Solutions:**
+
+1. Implement pagination to limit visible rows
+2. Use virtualization for extremely large datasets
+3. Consider server-side pagination for very large datasets
+4. Memoize expensive cell renderers
+
+```typescript
+// Use pagination to improve performance
+const table = createTable({
+  get data() {
+    return largeDataset;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(),
+  getPaginationRowModel: rowModels.paginationRowModel(),
+  initialState: {
+    pagination: {
+      pageSize: 50, // Show 50 rows at a time
+    },
+  },
+});
+```
+
+### Debugging Tips
+
+Enable verbose logging:
+
+```typescript
+const table = createTable({
+  get data() {
+    return data;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(),
+  debugTable: true, // Log table state changes
+  debugHeaders: true, // Log header information
+  debugColumns: true, // Log column information
+});
+```
+
+---
+
+## Accessibility
+
+The DataTable component includes built-in accessibility features:
+
+- **Semantic HTML**: Uses proper `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>` elements
+- **Keyboard Navigation**: Sort buttons are keyboard-accessible
+- **ARIA Attributes**: Sort buttons include `aria-sort` attributes
+- **Screen Reader Support**: Table structure is properly announced
+
+### Best Practices
+
+1. **Always provide meaningful headers**:
+
+   ```typescript
+   const columns: ColumnDef<User>[] = [
+     { accessorKey: 'id', header: 'User ID' }, // ✅ Clear header
+     { accessorKey: 'id', header: '' }, // ❌ Empty header
+   ];
+   ```
+
+2. **Use descriptive labels for actions**:
+
+   ```svelte
+   <button aria-label="Edit user {user.name}">Edit</button>
+   ```
+
+3. **Ensure sufficient color contrast** for text and backgrounds
+
+---
+
+## Further Resources
+
+- **Live Examples**: [Storybook](https://static.casinogate.dev/components/master/?path=/story/ui-kit-datatable)
+- **TanStack Table Docs**: [tanstack.com/table](https://tanstack.com/table/latest)
+- **Component Source**: [GitHub](../../)
+- **Report Issues**: Contact your team lead or file an issue
+
+---
+
+## Quick Reference
+
+### Minimal Setup
+
+```typescript
+import { DataTable, createTable, rowModels } from '@casinogate/ui';
+const table = createTable({
+  get data() {
+    return data;
+  },
+  columns,
+  getCoreRowModel: rowModels.coreRowModel(),
+});
+```
+
+### With Pagination
+
+```typescript
+import { usePaginationState } from '@casinogate/ui';
+const paginationState = usePaginationState();
+// Add: getPaginationRowModel, state: { get pagination() { return paginationState.value; } }, onPaginationChange: paginationState.updater
+```
+
+### With Sorting
+
+```typescript
+// Add: getSortedRowModel: rowModels.sortedRowModel()
+// In columns: enableSorting: true
+```
+
+### With Resizing
+
+```typescript
+import { useResizeState } from '@casinogate/ui';
+const resizeState = useResizeState();
+// Add: columnResizeMode: 'onChange', state: { get columnSizing() { return resizeState.value; } }, onColumnSizingChange: resizeState.updater
+// Component: <DataTable {table} resizable />
+```
+
+---
+
+**Need help?** Check the [Storybook examples](https://static.casinogate.dev/components/master/?path=/story/ui-kit-datatable) or reach out to the UI team.