@jmruthers/pace-core 0.5.121 → 0.5.123

package/docs/api/modules.md

@@ -1,6 +1,6 @@
-[@jmruthers/pace-core - v0.5.121](README.md) / Exports
+[@jmruthers/pace-core - v0.5.123](README.md) / Exports
 
-# @jmruthers/pace-core - v0.5.121
+# @jmruthers/pace-core - v0.5.123
 
 **`File`**
 
@@ -359,6 +359,7 @@ import { Dialog, NavigationMenu } from '@jmruthers/pace-core/components';
 - [fromSupabaseClient](modules.md#fromsupabaseclient)
 - [getStylePath](modules.md#getstylepath)
 - [getAllStylePaths](modules.md#getallstylepaths)
+- [parseAndNormalizeEventColours](modules.md#parseandnormalizeeventcolours)
 - [applyPalette](modules.md#applypalette)
 - [clearPalette](modules.md#clearpalette)
 - [generateSSRThemeCSS](modules.md#generatessrthemecss)
@@ -2612,7 +2613,7 @@ Useful for components that need to know if they're inside an error boundary
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx:216](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx#L216)
+[packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx:220](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx#L220)
 
 ___
 
@@ -2634,7 +2635,7 @@ Default error fallback component
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx:238](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx#L238)
+[packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx:242](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicErrorBoundary.tsx#L242)
 
 ___
 
@@ -2661,7 +2662,7 @@ React element with loading spinner
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx:75](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx#L75)
+[packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx:76](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx#L76)
 
 ___
 
@@ -2683,7 +2684,7 @@ Full page loading spinner with event branding
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx:135](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx#L135)
+[packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx:139](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx#L139)
 
 ___
 
@@ -2707,7 +2708,7 @@ Skeleton loading component for content placeholders
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx:189](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx#L189)
+[packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx:196](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicLoadingSpinner.tsx#L196)
 
 ___
 
@@ -2822,6 +2823,15 @@ Header component for public pages with event-specific branding
 This component displays the app logo, event logo, and event information
 in a clean, accessible layout suitable for public pages.
 
+Logo handling follows a priority order:
+1. customAppLogo prop (if provided) - highest priority
+2. logoUrl prop (if provided) - direct URL override
+3. Auto-generated path from appName via useAppConfig() - convention-based
+4. Default SVG fallback - lowest priority
+
+The logo can be made clickable by providing the logoHref prop, which will
+wrap the logo in a Link component for navigation.
+
 #### Parameters
 
 | Name | Type | Description |
@@ -2836,7 +2846,7 @@ React element with public page header
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicPageHeader.tsx:86](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicPageHeader.tsx#L86)
+[packages/core/src/components/PublicLayout/PublicPageHeader.tsx:124](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicPageHeader.tsx#L124)
 
 ___
 
@@ -2849,6 +2859,9 @@ Layout component for public pages that don't require authentication
 This component provides a consistent structure for public event pages
 with event-specific branding, error handling, and loading states.
 
+Automatically applies event colors from the event's event_colours field
+when an event is provided, ensuring consistent theming across public pages.
+
 #### Parameters
 
 | Name | Type | Description |
@@ -2863,7 +2876,7 @@ React element with complete public page layout
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicPageLayout.tsx:101](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicPageLayout.tsx#L101)
+[packages/core/src/components/PublicLayout/PublicPageLayout.tsx:119](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicPageLayout.tsx#L119)
 
 ___
 
@@ -2894,7 +2907,7 @@ directly in your components instead.
 
 #### Defined in
 
-[packages/core/src/components/PublicLayout/PublicPageLayout.tsx:221](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicPageLayout.tsx#L221)
+[packages/core/src/components/PublicLayout/PublicPageLayout.tsx:224](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PublicLayout/PublicPageLayout.tsx#L224)
 
 ___
 
@@ -3894,7 +3907,7 @@ Object containing route parameters, event data, loading state, error, and refetc
 
 #### Defined in
 
-[packages/core/src/hooks/public/usePublicRouteParams.ts:121](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L121)
+[packages/core/src/hooks/public/usePublicRouteParams.ts:129](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L129)
 
 ___
 
@@ -3922,7 +3935,7 @@ Useful when you only need the event code and will fetch data separately
 
 #### Defined in
 
-[packages/core/src/hooks/public/usePublicRouteParams.ts:216](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L216)
+[packages/core/src/hooks/public/usePublicRouteParams.ts:224](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L224)
 
 ___
 
@@ -3945,7 +3958,7 @@ Utility function to generate public route paths
 
 #### Defined in
 
-[packages/core/src/hooks/public/usePublicRouteParams.ts:252](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L252)
+[packages/core/src/hooks/public/usePublicRouteParams.ts:260](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L260)
 
 ___
 
@@ -3954,6 +3967,7 @@ ___
 ▸ **extractEventCodeFromPath**(`path`): `string` \| ``null``
 
 Utility function to extract event code from a public route path
+Supports 2-50 character event codes
 
 #### Parameters
 
@@ -3967,7 +3981,7 @@ Utility function to extract event code from a public route path
 
 #### Defined in
 
-[packages/core/src/hooks/public/usePublicRouteParams.ts:266](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L266)
+[packages/core/src/hooks/public/usePublicRouteParams.ts:275](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/public/usePublicRouteParams.ts#L275)
 
 ___
 
@@ -4048,16 +4062,33 @@ ___
 
 ### useEventTheme
 
-▸ **useEventTheme**(): `void`
+▸ **useEventTheme**(`event?`): `void`
 
 Hook that automatically applies event-specific theming
 
-This hook watches the selected event and applies its colors using the theming system.
-It will:
-- Apply event colors when an event with `event_colours` is selected
-- Clear theming when no event is selected
-- Skip theme application when on the login route to prevent login screen styling
-- Handle cleanup when the component unmounts
+This hook applies event colors using the theming system. It works in two modes:
+
+**Authenticated Mode (default):**
+- Uses EventProvider context via useEvents() hook
+- Automatically watches selectedEvent changes
+- Used in authenticated pages with EventProvider
+
+**Public Page Mode:**
+- Accepts event prop directly
+- No EventProvider required
+- Used in public pages without authentication context
+
+Behavior:
+- Applies event colors when an event with `event_colours` is provided
+- Clears theming when no event is provided
+- Skips theme application when on the login route to prevent login screen styling
+- Handles cleanup and error cases gracefully
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `event?` | ``null`` \| `Event` | Optional event object. If provided, uses this event directly (public page mode). If not provided, uses EventProvider context via useEvents() (authenticated mode). |
 
 #### Returns
 
@@ -4065,9 +4096,29 @@ It will:
 
 void - This is an effect hook with no return value
 
+**`Example`**
+
+```tsx
+// Authenticated mode - uses EventProvider
+function MyApp() {
+  useEventTheme(); // Watches selectedEvent from EventProvider
+  return <div>App content</div>;
+}
+```
+
+**`Example`**
+
+```tsx
+// Public page mode - uses event prop
+function PublicPageLayout({ event }) {
+  useEventTheme(event); // Uses event prop directly
+  return <div>Public content</div>;
+}
+```
+
 #### Defined in
 
-[packages/core/src/hooks/useEventTheme.ts:85](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventTheme.ts#L85)
+[packages/core/src/hooks/useEventTheme.ts:92](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/hooks/useEventTheme.ts#L92)
 
 ___
 
@@ -6297,7 +6348,7 @@ const client = createSecureClient(
 
 #### Defined in
 
-[packages/core/src/rbac/secureClient.ts:216](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/secureClient.ts#L216)
+[packages/core/src/rbac/secureClient.ts:218](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/secureClient.ts#L218)
 
 ___
 
@@ -6324,7 +6375,7 @@ SecureSupabaseClient instance
 
 #### Defined in
 
-[packages/core/src/rbac/secureClient.ts:235](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/secureClient.ts#L235)
+[packages/core/src/rbac/secureClient.ts:237](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/secureClient.ts#L237)
 
 ___
 
@@ -6362,6 +6413,65 @@ ___
 
 ___
 
+### parseAndNormalizeEventColours
+
+▸ **parseAndNormalizeEventColours**(`input`): \{ `main`: `any` ; `sec`: `any` ; `acc`: `any`  } \| ``null``
+
+Parse and normalize event_colours to PaletteData
+
+Supports multiple input formats:
+- Object with 'main', 'sec', 'acc' keys
+- Object with 'ev-main', 'ev-sec', 'ev-acc' keys (legacy)
+- JSON string that will be parsed
+
+Only includes explicitly defined color values. Does not fill
+missing shades - only shades that are present in the input will
+be included in the output.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `input` | `unknown` | Event colours from database (JSONB field) |
+
+#### Returns
+
+\{ `main`: `any` ; `sec`: `any` ; `acc`: `any`  } \| ``null``
+
+Normalized palette data with main, sec, acc palettes, or null if invalid
+
+**`Example`**
+
+```ts
+// Standard format
+const colours = {
+  main: { 500: { L: 0.5, C: 0.2, H: 0 }, raw: { L: 0.5, C: 0.2, H: 0 } },
+  sec: { 500: { L: 0.5, C: 0.2, H: 120 } },
+  acc: { 500: { L: 0.5, C: 0.2, H: 240 } }
+};
+const palette = parseAndNormalizeEventColours(colours);
+// Returns: { main: { 500: {...}, raw: {...} }, sec: { 500: {...} }, acc: { 500: {...} } }
+```
+
+**`Example`**
+
+```ts
+// Legacy format with ev-* keys
+const colours = {
+  "ev-main": { 500: { L: 0.5, C: 0.2, H: 0 } },
+  "ev-sec": { 500: { L: 0.5, C: 0.2, H: 120 } },
+  "ev-acc": { 500: { L: 0.5, C: 0.2, H: 240 } }
+};
+const palette = parseAndNormalizeEventColours(colours);
+// Returns normalized palette with only defined shades included
+```
+
+#### Defined in
+
+[packages/core/src/theming/parseEventColours.ts:68](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/theming/parseEventColours.ts#L68)
+
+___
+
 ### applyPalette
 
 ▸ **applyPalette**(`palette`): `void`
@@ -6552,7 +6662,7 @@ ___
 
 ▸ **formatDate**(`date`): `string`
 
-Format a date as a readable string
+Format a date as a readable string in "dd mmm yyyy" format (e.g., "15 Jun 2024")
 
 #### Parameters
 
@@ -6590,7 +6700,7 @@ Format a number as a currency
 
 #### Defined in
 
-[packages/core/src/utils/formatting.ts:23](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L23)
+[packages/core/src/utils/formatting.ts:24](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L24)
 
 ___
 
@@ -6614,7 +6724,7 @@ Format a number with custom options
 
 #### Defined in
 
-[packages/core/src/utils/formatting.ts:33](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L33)
+[packages/core/src/utils/formatting.ts:34](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L34)
 
 ___
 
@@ -6659,7 +6769,7 @@ formatPercent(0.8123, 'en-US', { preserveDecimals: true, maxDecimals: 2 }) // '0
 
 #### Defined in
 
-[packages/core/src/utils/formatting.ts:70](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L70)
+[packages/core/src/utils/formatting.ts:71](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L71)
 
 ___
 
@@ -6682,7 +6792,7 @@ Format a large number with abbreviations (K, M, B)
 
 #### Defined in
 
-[packages/core/src/utils/formatting.ts:114](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L114)
+[packages/core/src/utils/formatting.ts:115](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L115)
 
 ___
 
@@ -6704,7 +6814,7 @@ Format a file size in bytes to a human-readable string
 
 #### Defined in
 
-[packages/core/src/utils/formatting.ts:124](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L124)
+[packages/core/src/utils/formatting.ts:125](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/utils/formatting.ts#L125)
 
 ___
 

package/docs/best-practices/README.md

@@ -344,7 +344,7 @@ import { z } from 'zod';
 <button
   aria-label="Close dialog"
   onClick={onClose}
-  className="p-2 rounded-md hover:bg-gray-100"
+  className="p-2 rounded-md hover:bg-sec-100"
 >
   <XIcon className="h-4 w-4" />
 </button>

package/docs/implementation-guides/datatable-filtering.md

@@ -0,0 +1,313 @@
+# DataTable Filtering Guide
+
+## Overview
+
+The DataTable component supports multiple types of column filtering, including text, select dropdowns, number, and date filters. This guide explains how to configure each filter type and provides examples for common use cases.
+
+## Filter Types
+
+### 1. Text Filters (Default)
+Text filters allow users to type and search for values in a column.
+
+```typescript
+const columns = [
+  {
+    id: 'name',
+    accessorKey: 'name',
+    header: 'Name',
+    enableColumnFilter: true,
+    // No filterType specified - defaults to 'text'
+  }
+];
+```
+
+### 2. Select Filters
+Select filters provide dropdown menus with predefined options, perfect for categorical data.
+
+#### Method 1: Using `filterSelectOptions` (Recommended)
+```typescript
+const columns = [
+  {
+    id: 'meal_type',
+    accessorFn: (row) => row.mealtype?.mealtype_name || 'N/A',
+    header: 'Type',
+    enableColumnFilter: true,
+    filterType: 'select',
+    filterSelectOptions: [
+      { value: 'breakfast', label: 'Breakfast' },
+      { value: 'lunch', label: 'Lunch' },
+      { value: 'dinner', label: 'Dinner' },
+      { value: 'morning_tea', label: 'Morning Tea' },
+      { value: 'afternoon_tea', label: 'Afternoon Tea' },
+      { value: 'pantry', label: 'Pantry' }
+    ],
+    filterFn: (row, id, value) => {
+      return value.includes(row.original.mealtype?.mealtype_id);
+    }
+  }
+];
+```
+
+#### Method 2: Using `fieldOptions`
+```typescript
+const columns = [
+  {
+    id: 'status',
+    accessorKey: 'status',
+    header: 'Status',
+    enableColumnFilter: true,
+    filterType: 'select',
+    fieldOptions: [
+      { value: 'active', label: 'Active' },
+      { value: 'inactive', label: 'Inactive' },
+      { value: 'pending', label: 'Pending' }
+    ]
+  }
+];
+```
+
+#### Method 3: Auto-detection
+The DataTable automatically detects select filters when a column has limited unique values (≤10):
+
+```typescript
+const columns = [
+  {
+    id: 'priority',
+    accessorKey: 'priority',
+    header: 'Priority',
+    enableColumnFilter: true,
+    // No filterType specified - will auto-detect as 'select' if ≤10 unique values
+  }
+];
+```
+
+### 3. Number Filters
+Number filters provide numeric input with comparison operators.
+
+```typescript
+const columns = [
+  {
+    id: 'price',
+    accessorKey: 'price',
+    header: 'Price',
+    enableColumnFilter: true,
+    filterType: 'number'
+  }
+];
+```
+
+### 4. Date Filters
+Date filters provide date picker inputs.
+
+```typescript
+const columns = [
+  {
+    id: 'created_date',
+    accessorKey: 'created_date',
+    header: 'Created Date',
+    enableColumnFilter: true,
+    filterType: 'date'
+  }
+];
+```
+
+## Complete Example
+
+Here's a complete example showing different filter types:
+
+```typescript
+import { DataTable } from '@jmruthers/pace-core';
+
+function MealsTable() {
+  const meals = [
+    {
+      id: '1',
+      meal_code: '28py',
+      mealtype: { mealtype_id: 'breakfast', mealtype_name: 'Breakfast' },
+      meal_date: '2024-12-28',
+      price: 15.50
+    },
+    // ... more data
+  ];
+
+  const mealTypes = [
+    { mealtype_id: 'breakfast', mealtype_name: 'Breakfast' },
+    { mealtype_id: 'lunch', mealtype_name: 'Lunch' },
+    { mealtype_id: 'dinner', mealtype_name: 'Dinner' },
+    { mealtype_id: 'morning_tea', mealtype_name: 'Morning Tea' },
+    { mealtype_id: 'afternoon_tea', mealtype_name: 'Afternoon Tea' },
+    { mealtype_id: 'pantry', mealtype_name: 'Pantry' }
+  ];
+
+  const columns = [
+    {
+      id: 'meal_code',
+      accessorKey: 'meal_code',
+      header: 'Meal Code',
+      enableColumnFilter: true,
+      // Text filter (default)
+    },
+    {
+      id: 'meal_type',
+      accessorFn: (row) => row.mealtype?.mealtype_name || 'N/A',
+      header: 'Type',
+      enableColumnFilter: true,
+      filterType: 'select',
+      filterSelectOptions: mealTypes.map(mt => ({
+        value: mt.mealtype_id,
+        label: mt.mealtype_name
+      })),
+      filterFn: (row, id, value) => {
+        return value.includes(row.original.mealtype?.mealtype_id);
+      }
+    },
+    {
+      id: 'meal_date',
+      accessorKey: 'meal_date',
+      header: 'Date',
+      enableColumnFilter: true,
+      filterType: 'date'
+    },
+    {
+      id: 'price',
+      accessorKey: 'price',
+      header: 'Price',
+      enableColumnFilter: true,
+      filterType: 'number'
+    }
+  ];
+
+  return (
+    <DataTable
+      data={meals}
+      columns={columns}
+      features={{
+        filtering: true,  // Enable filtering
+        search: true,
+        pagination: true,
+        sorting: true
+      }}
+      rbac={{
+        pageName: 'meals'
+      }}
+    />
+  );
+}
+```
+
+## Filter Configuration Options
+
+### Column Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enableColumnFilter` | `boolean` | Enable filtering for this column |
+| `filterType` | `'text' \| 'select' \| 'number' \| 'date'` | Type of filter to render |
+| `filterSelectOptions` | `Array<{value: string\|number, label: string}>` | Options for select filters |
+| `fieldOptions` | `Array<{value: string\|number, label: string}>` | Alternative options for select filters |
+| `filterFn` | `(row, id, value) => boolean` | Custom filter function |
+
+### DataTable Features
+
+```typescript
+features={{
+  filtering: true,        // Enable column filtering
+  search: true,          // Enable global search
+  showFilterRow: true,   // Show filter row by default
+}}
+```
+
+## Advanced Filtering
+
+### Custom Filter Functions
+
+For complex filtering logic, you can provide a custom `filterFn`:
+
+```typescript
+{
+  id: 'meal_type',
+  accessorFn: (row) => row.mealtype?.mealtype_name || 'N/A',
+  header: 'Type',
+  enableColumnFilter: true,
+  filterType: 'select',
+  filterSelectOptions: mealTypes.map(mt => ({
+    value: mt.mealtype_id,
+    label: mt.mealtype_name
+  })),
+  filterFn: (row, id, value) => {
+    // Custom logic: filter by mealtype_id but display mealtype_name
+    const mealtypeId = row.original.mealtype?.mealtype_id;
+    return value.includes(mealtypeId);
+  }
+}
+```
+
+### Multiple Value Selection
+
+Select filters support multiple value selection by default:
+
+```typescript
+// Users can select multiple meal types
+filterSelectOptions: [
+  { value: 'breakfast', label: 'Breakfast' },
+  { value: 'lunch', label: 'Lunch' },
+  { value: 'dinner', label: 'Dinner' }
+]
+// When user selects "Breakfast" and "Lunch", 
+// filterFn receives: ['breakfast', 'lunch']
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Select filter not showing dropdown:**
+   - Ensure `filterType: 'select'` is set
+   - Verify `filterSelectOptions` or `fieldOptions` is provided
+   - Check that `enableColumnFilter: true` is set
+
+2. **Filter not working with foreign key data:**
+   - Use `accessorFn` to extract the display value
+   - Provide custom `filterFn` to match against the actual ID
+   - Ensure `filterSelectOptions` uses the ID values
+
+3. **Auto-detection not working:**
+   - Ensure column has ≤10 unique values
+   - Check that values are not null/undefined
+   - Verify `enableColumnFilter: true` is set
+
+### Debug Tips
+
+Enable debug logging to see filter behavior:
+
+```typescript
+// In your app setup
+<UnifiedAuthProvider 
+  supabaseClient={supabase}
+  appName="your-app"
+  enableRBAC={true}
+  debug={true}  // Enable debug logging
+>
+  <YourApp />
+</UnifiedAuthProvider>
+```
+
+## Best Practices
+
+1. **Use `filterSelectOptions` for predefined options** - More explicit and clear
+2. **Provide meaningful labels** - Use human-readable labels, not IDs
+3. **Use custom `filterFn` for foreign keys** - Match against IDs, display names
+4. **Limit select options** - Keep dropdowns manageable (≤20 options)
+5. **Test with real data** - Ensure filters work with actual data values
+6. **Consider performance** - Large datasets may need server-side filtering
+
+## Migration from Old Filtering
+
+If you're upgrading from an older version:
+
+1. **Replace `meta.filterOptions`** with `filterSelectOptions`
+2. **Add `filterType: 'select'`** for explicit select filters
+3. **Update `filterFn`** to work with new filter value format
+4. **Test all filter combinations** to ensure they work correctly
+
+This comprehensive filtering system provides a great user experience for data exploration and analysis.