@kala-ui/react-app 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/components/charts/chart.js

@@ -4,8 +4,11 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
  * Base Chart Component
  * React component for ApexCharts with built-in loading and empty states
  */
+import { useSlotStyles } from "@kala-ui/react/kala-provider";
+import { applySlot } from "@kala-ui/react/lib/slot-styles";
 import { cn } from "@kala-ui/react/lib/utils";
 import { lazy, Suspense } from "react";
+import { chartStyles } from "../../config/charts.js";
 import { ChartSkeleton } from "./chart-skeleton.js";
 // apexcharts touches `window` at module scope, so importing it statically
 // crashes any SSR framework on the first render — and the root barrel
@@ -24,7 +27,10 @@ function getTooltipTheme() {
  * Base Chart Component - use this as the foundation for all charts
  * Provides consistent styling, loading skeleton, and empty state
  */
-export function Chart({ className, isLoading, isEmpty, emptyMessage = "No data available", skeletonConfig, skeleton, ...props }) {
+export function Chart({ className, isLoading, isEmpty, emptyMessage = "No data available", skeletonConfig, skeleton, slotStyles: slotStylesRaw, ...props }) {
+    const slotStyles = useSlotStyles("charts", slotStylesRaw);
+    const { "data-kala-component": _marker, ...chartProps } = props;
+    const markerProps = { "data-kala-component": _marker };
     // Render skeleton if loading
     if (isLoading) {
         if (skeleton) {
@@ -32,6 +38,9 @@ export function Chart({ className, isLoading, isEmpty, emptyMessage = "No data a
         }
         return (_jsx(ChartSkeleton, { "data-kala-component": "charts-chart", ...(skeletonConfig || {}), className: className }));
     }
+    const emptyPart = applySlot(chartStyles.empty, slotStyles?.empty);
+    const emptyIcon = applySlot(chartStyles.emptyIcon, slotStyles?.emptyIcon);
+    const emptyText = applySlot(chartStyles.emptyText, slotStyles?.emptyText);
     // Render empty state when no data
     if (isEmpty) {
         // Height may arrive as a number (px) or a CSS length string ("20rem",
@@ -40,9 +49,10 @@ export function Chart({ className, isLoading, isEmpty, emptyMessage = "No data a
         const height = typeof configuredHeight === "number"
             ? `${configuredHeight}px`
             : configuredHeight;
-        return (_jsxs("div", { "data-kala-component": "charts-chart", className: cn("w-full flex flex-col items-center justify-center text-center rounded-lg border bg-card text-muted-foreground", className), style: { height }, children: [_jsxs("svg", { className: "mb-3 h-10 w-10 opacity-40", fill: "none", role: "img", "aria-label": "Chart empty state", stroke: "currentColor", viewBox: "0 0 24 24", children: [_jsx("title", { children: "No chart data" }), _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 1.5, d: "M3 13h2v8H3zM9 9h2v12H9zM15 5h2v16h-2zM21 1h2v20h-2z" })] }), _jsx("p", { className: "text-sm", children: emptyMessage })] }));
+        return (_jsxs("div", { "data-kala-component": "charts-chart", className: cn(emptyPart.className, className), style: { height, ...emptyPart.style }, children: [_jsxs("svg", { className: emptyIcon.className, fill: "none", role: "img", "aria-label": "Chart empty state", stroke: "currentColor", viewBox: "0 0 24 24", children: [_jsx("title", { children: "No chart data" }), _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 1.5, d: "M3 13h2v8H3zM9 9h2v12H9zM15 5h2v16h-2zM21 1h2v20h-2z" })] }), _jsx("p", { className: emptyText.className, children: emptyMessage })] }));
     }
-    return (_jsx("div", { "data-kala-component": "charts-chart", className: cn("w-full", className), children: _jsx(Suspense, { fallback: skeleton ?? (_jsx(ChartSkeleton, { ...(skeletonConfig || {}), className: className })), children: _jsx(ReactApexChart, { ...props }) }) }));
+    const root = applySlot(cn(chartStyles.root, className), slotStyles?.root);
+    return (_jsx("div", { "data-kala-component": _marker ?? "charts-chart", className: root.className, style: root.style, children: _jsx(Suspense, { fallback: skeleton ?? (_jsx(ChartSkeleton, { ...(skeletonConfig || {}), className: className })), children: _jsx(ReactApexChart, { ...chartProps }) }) }));
 }
 export { ChartSkeleton } from "./chart-skeleton.js";
 export { getTooltipTheme };

package/dist/components/charts/chart.types.d.ts

@@ -2,6 +2,7 @@
  * Chart Component Types
  * Type definitions for ApexCharts-based chart components
  */
+import type { SlotStyles } from "@kala-ui/react/lib/slot-styles";
 import type { ApexOptions } from "apexcharts";
 /**
  * Base chart props shared across all chart types
@@ -27,6 +28,8 @@ export interface BaseChartProps {
     isLoading?: boolean;
     /** Message shown when data is empty (default: "No data available") */
     emptyMessage?: string;
+    /** Per-part overrides: root, empty, emptyIcon, emptyText, titleBlock, title, subtitle. */
+    slotStyles?: SlotStyles;
 }
 /**
  * Series data point for single value charts

package/dist/components/charts/donut-chart.d.ts

@@ -3,5 +3,5 @@
  * Circular charts for showing proportions and percentages
  */
 import type { DonutChartProps } from "./chart.types";
-export declare function DonutChart({ series, labels, colors, height, width, className, title, subtitle, animations, donut, donutSize, dataLabels, legend, isLoading, emptyMessage, options: customOptions, }: DonutChartProps): import("react").JSX.Element;
+export declare function DonutChart({ series, labels, colors, height, width, className, title, subtitle, animations, donut, donutSize, dataLabels, legend, slotStyles, isLoading, emptyMessage, options: customOptions, }: DonutChartProps): import("react").JSX.Element;
 export declare function PieChart(props: DonutChartProps): import("react").JSX.Element;

package/dist/components/charts/donut-chart.js

@@ -7,10 +7,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@kala-ui/react/lib/utils";
 import { useMemo } from "react";
+import { chartStyles } from "../../config/charts.js";
 import { Chart, getTooltipTheme } from "./chart.js";
 import { useThemeAwareChart } from "./use-theme-aware-chart.js";
-import { getDefaultChartOptions } from "./utils.js";
-export function DonutChart({ series, labels, colors, height = 350, width = "100%", className, title, subtitle, animations = true, donut = true, donutSize = 65, dataLabels = true, legend = true, isLoading, emptyMessage, options: customOptions, }) {
+import { getDefaultChartOptions } from "./chart-utils.js";
+export function DonutChart({ series, labels, colors, height = 350, width = "100%", className, title, subtitle, animations = true, donut = true, donutSize = 65, dataLabels = true, legend = true, slotStyles, isLoading, emptyMessage, options: customOptions, }) {
     const { colors: themeColors } = useThemeAwareChart();
     const isEmpty = !isLoading && (series.length === 0 || labels.length === 0);
     const chartOptions = useMemo(() => {
@@ -138,7 +139,7 @@ export function DonutChart({ series, labels, colors, height = 350, width = "100%
         subtitle,
         customOptions,
     ]);
-    return (_jsx(Chart, { "data-kala-component": "charts-donut-chart", className: cn("w-full", className), options: chartOptions, series: series, type: donut ? "donut" : "pie", height: height, width: width, isLoading: isLoading, isEmpty: isEmpty, emptyMessage: emptyMessage }));
+    return (_jsx(Chart, { "data-kala-component": "charts-donut-chart", className: cn(chartStyles.root, className), slotStyles: slotStyles, options: chartOptions, series: series, type: donut ? "donut" : "pie", height: height, width: width, isLoading: isLoading, isEmpty: isEmpty, emptyMessage: emptyMessage }));
 }
 // Convenience alias for Pie charts
 export function PieChart(props) {

package/dist/components/charts/index.d.ts

@@ -11,4 +11,4 @@ export { LineChart } from "./line-chart";
 export { RadialBarChart } from "./radial-bar-chart";
 export * from "./theme-utils";
 export { useThemeAwareChart } from "./use-theme-aware-chart";
-export * from "./utils";
+export * from "./chart-utils";

package/dist/components/charts/index.js

@@ -12,4 +12,4 @@ export { LineChart } from "./line-chart.js";
 export { RadialBarChart } from "./radial-bar-chart.js";
 export * from "./theme-utils.js";
 export { useThemeAwareChart } from "./use-theme-aware-chart.js";
-export * from "./utils.js";
+export * from "./chart-utils.js";

package/dist/components/charts/line-chart.d.ts

@@ -3,4 +3,4 @@
  * Clean line charts for trends and time series data
  */
 import type { LineChartProps } from "./chart.types";
-export declare function LineChart({ series, categories, colors, height, width, className, title, subtitle, toolbar, animations, curve, strokeWidth, markers, yAxisLabel, isLoading, emptyMessage, options: customOptions, }: LineChartProps): import("react").JSX.Element;
+export declare function LineChart({ series, categories, colors, height, width, className, title, subtitle, toolbar, animations, curve, strokeWidth, markers, yAxisLabel, slotStyles, isLoading, emptyMessage, options: customOptions, }: LineChartProps): import("react").JSX.Element;

package/dist/components/charts/line-chart.js

@@ -7,9 +7,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@kala-ui/react/lib/utils";
 import { useMemo } from "react";
+import { chartStyles } from "../../config/charts.js";
 import { Chart, getTooltipTheme } from "./chart.js";
 import { useThemeAwareChart } from "./use-theme-aware-chart.js";
-import { getDefaultChartOptions } from "./utils.js";
+import { getDefaultChartOptions } from "./chart-utils.js";
 /**
  * Check if series data is empty (no series or all series have empty data arrays)
  */
@@ -18,7 +19,7 @@ function isSeriesEmpty(series) {
         return true;
     return series.every((s) => !s.data || (Array.isArray(s.data) && s.data.length === 0));
 }
-export function LineChart({ series, categories, colors, height = 350, width = "100%", className, title, subtitle, toolbar = false, animations = true, curve = "smooth", strokeWidth = 2, markers = true, yAxisLabel, isLoading, emptyMessage, options: customOptions, }) {
+export function LineChart({ series, categories, colors, height = 350, width = "100%", className, title, subtitle, toolbar = false, animations = true, curve = "smooth", strokeWidth = 2, markers = true, yAxisLabel, slotStyles, isLoading, emptyMessage, options: customOptions, }) {
     const { colors: themeColors } = useThemeAwareChart();
     const isEmpty = !isLoading && isSeriesEmpty(series);
     const chartOptions = useMemo(() => {
@@ -154,5 +155,5 @@ export function LineChart({ series, categories, colors, height = 350, width = "1
         subtitle,
         customOptions,
     ]);
-    return (_jsx(Chart, { "data-kala-component": "charts-line-chart", className: cn("w-full", className), options: chartOptions, series: series, type: "line", height: height, width: width, isLoading: isLoading, isEmpty: isEmpty, emptyMessage: emptyMessage }));
+    return (_jsx(Chart, { "data-kala-component": "charts-line-chart", className: cn(chartStyles.root, className), slotStyles: slotStyles, options: chartOptions, series: series, type: "line", height: height, width: width, isLoading: isLoading, isEmpty: isEmpty, emptyMessage: emptyMessage }));
 }

package/dist/components/charts/radial-bar-chart.d.ts

@@ -3,4 +3,4 @@
  * Circular progress bars for showing percentages and completion rates
  */
 import type { RadialBarChartProps } from "./chart.types";
-export declare function RadialBarChart({ series, labels, colors, height, width, className, title, subtitle, animations, dataLabels, hollowSize, isLoading, emptyMessage, options: customOptions, }: RadialBarChartProps): import("react").JSX.Element;
+export declare function RadialBarChart({ series, labels, colors, height, width, className, title, subtitle, animations, dataLabels, hollowSize, slotStyles, isLoading, emptyMessage, options: customOptions, }: RadialBarChartProps): import("react").JSX.Element;

package/dist/components/charts/radial-bar-chart.js

@@ -7,10 +7,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@kala-ui/react/lib/utils";
 import { useMemo } from "react";
+import { chartStyles } from "../../config/charts.js";
 import { Chart, getTooltipTheme } from "./chart.js";
 import { useThemeAwareChart } from "./use-theme-aware-chart.js";
-import { getDefaultChartOptions } from "./utils.js";
-export function RadialBarChart({ series, labels, colors, height = 350, width = "100%", className, title, subtitle, animations = true, dataLabels = true, hollowSize = "50%", isLoading, emptyMessage, options: customOptions, }) {
+import { getDefaultChartOptions } from "./chart-utils.js";
+export function RadialBarChart({ series, labels, colors, height = 350, width = "100%", className, title, subtitle, animations = true, dataLabels = true, hollowSize = "50%", slotStyles, isLoading, emptyMessage, options: customOptions, }) {
     const { colors: themeColors } = useThemeAwareChart();
     const isEmpty = !isLoading && (series.length === 0 || labels.length === 0);
     const chartOptions = useMemo(() => {
@@ -111,5 +112,5 @@ export function RadialBarChart({ series, labels, colors, height = 350, width = "
         subtitle,
         customOptions,
     ]);
-    return (_jsx(Chart, { "data-kala-component": "charts-radial-bar-chart", className: cn("w-full", className), options: chartOptions, series: series, type: "radialBar", height: height, width: width, isLoading: isLoading, isEmpty: isEmpty, emptyMessage: emptyMessage }));
+    return (_jsx(Chart, { "data-kala-component": "charts-radial-bar-chart", className: cn(chartStyles.root, className), slotStyles: slotStyles, options: chartOptions, series: series, type: "radialBar", height: height, width: width, isLoading: isLoading, isEmpty: isEmpty, emptyMessage: emptyMessage }));
 }

package/dist/components/data-table/data-table.js

@@ -37,7 +37,7 @@ import { DataTableHeaderRow } from "./data-table-header-row.js";
 import { DataTableSkeleton } from "./data-table-skeleton.js";
 import { DataTableToolbar } from "./data-table-toolbar.js";
 import { PaginationNav } from "./pagination-nav.js";
-import { useTableState } from "./useTableState.js";
+import { useTableState } from "./use-table-state.js";
 /**
  * DataTable Component
  */
@@ -230,7 +230,9 @@ export function DataTable({ data, columns, searchable, pagination, defaultSort,
             : "There is no data to display at the moment.",
         ...emptyState,
     };
-    return (_jsxs(Stack, { "data-kala-component": "data-table", className: cn(stickyFooter ? "h-full min-h-0" : "", className), "aria-label": ariaLabel, role: ariaLabel ? "region" : undefined, gap: 0, children: [_jsx(DataTableToolbar, { searchConfig: searchConfig, searchQuery: searchQuery, onSearchChange: setSearchQuery, bulkActions: bulkActions, selectedRows: selectedRows, selectedIdsCount: selectedIds.size, toolbarContent: toolbarContent, hasData: data.length > 0, className: stickyFooter ? "shrink-0" : undefined }), filterableColumns && (_jsx("div", { className: stickyFooter ? "shrink-0" : undefined, children: _jsx(DataTableFilterChips, { filterConfigs: filterConfigs, filterableColumns: filterableColumns, onSetFilter: setFilter, onRemoveFilter: removeFilter, onClearFilters: clearFilters }) })), displayData.length === 0 && !filterConfigs.length && !searchQuery ? (_jsx(EmptyState, { title: emptyConfig.title, description: emptyConfig.description, ...(emptyState?.icon && { icon: emptyState.icon }), ...(emptyState?.action && { action: emptyState.action }) })) : (_jsxs(_Fragment, { children: [_jsxs(Box, { className: cn("border relative overflow-hidden kala-surface-card", stickyFooter && paginationConfig && displayData.length > 0
+    return (_jsxs(Stack, { "data-kala-component": "data-table", className: cn(stickyFooter ? "h-full min-h-0" : "", className), "aria-label": ariaLabel, role: ariaLabel ? "region" : undefined, gap: 0, children: [_jsx(DataTableToolbar, { searchConfig: searchConfig, searchQuery: searchQuery, onSearchChange: setSearchQuery, bulkActions: bulkActions, selectedRows: selectedRows, selectedIdsCount: selectedIds.size, toolbarContent: toolbarContent, hasData: data.length > 0, className: stickyFooter ? "shrink-0" : undefined }), filterableColumns && (_jsx("div", { className: stickyFooter ? "shrink-0" : undefined, children: _jsx(DataTableFilterChips, { filterConfigs: filterConfigs, filterableColumns: filterableColumns, onSetFilter: setFilter, onRemoveFilter: removeFilter, onClearFilters: clearFilters }) })), displayData.length === 0 && !filterConfigs.length && !searchQuery ? (_jsx(EmptyState, { title: emptyConfig.title, description: emptyConfig.description, ...(emptyState?.icon && { icon: emptyState.icon }), ...(emptyState?.action && { action: emptyState.action }), ...(emptyState?.slotStyles && {
+                    slotStyles: emptyState.slotStyles,
+                }) })) : (_jsxs(_Fragment, { children: [_jsxs(Box, { className: cn("border relative overflow-hidden kala-surface-card", stickyFooter && paginationConfig && displayData.length > 0
                             ? "flex-1 min-h-0"
                             : "", bordered && "border-2", paginationConfig && displayData.length > 0
                             ? "rounded-t-lg border-b-0"

package/dist/components/data-table/data-table.types.d.ts

@@ -121,6 +121,8 @@ export interface EmptyStateConfig {
         label: string;
         onClick: () => void;
     };
+    /** Per-part overrides forwarded to the embedded EmptyState */
+    slotStyles?: EmptyStateProps["slotStyles"];
 }
 /**
  * Loading state configuration - DEPRECATED: Use DataTableSkeletonConfig

package/dist/components/data-table/index.d.ts

@@ -3,4 +3,4 @@
  */
 export { DataTable, DataTableSkeleton } from "./data-table";
 export type { BulkAction, ColumnDef, DataTableProps, DataTableSkeletonConfig, EmptyStateConfig, FilterableColumn, FilterConfig, FilterOperator, LoadingConfig, PaginationConfig, SearchConfig, SelectionConfig, SortConfig, SortDirection, TableState, } from "./data-table.types";
-export { useTableState } from "./useTableState";
+export { useTableState } from "./use-table-state";

package/dist/components/data-table/index.js

@@ -3,4 +3,4 @@
  * DataTable Component Exports
  */
 export { DataTable, DataTableSkeleton } from "./data-table.js";
-export { useTableState } from "./useTableState.js";
+export { useTableState } from "./use-table-state.js";

package/dist/components/data-table/use-table-state.d.ts

@@ -0,0 +1,29 @@
+/**
+ * useTableState Hook
+ * Manages table state including sorting, filtering, pagination, and search
+ */
+import type { ColumnDef, FilterConfig, SearchConfig, SortConfig, TableState } from "./data-table.types";
+interface UseTableStateOptions<TData> {
+    data: TData[];
+    columns: ColumnDef<TData>[];
+    defaultSort?: SortConfig<TData>;
+    defaultFilters?: FilterConfig<TData>[];
+    searchConfig?: SearchConfig<TData> | boolean;
+    pageSize?: number;
+    total?: number;
+    /** Controlled page number (1-indexed); omitted = uncontrolled */
+    page?: number;
+    /** Callback when sort changes */
+    onSortChange?: (sort: SortConfig<TData> | null) => void;
+    /** Callback when filters change */
+    onFilterChange?: (filters: FilterConfig<TData>[]) => void;
+    /** Callback when search query changes */
+    onSearchChange?: (query: string) => void;
+    /** Callback when pagination changes */
+    onPaginationChange?: (page: number, pageSize: number) => void;
+}
+/**
+ * Hook to manage table state (sorting, filtering, search, pagination)
+ */
+export declare function useTableState<TData>({ data, columns, defaultSort, defaultFilters, searchConfig, pageSize: initialPageSize, total: manualTotal, page, onSortChange, onFilterChange, onSearchChange, onPaginationChange, }: UseTableStateOptions<TData>): TableState<TData>;
+export {};

package/dist/components/data-table/use-table-state.js

@@ -0,0 +1,312 @@
+"use client";
+/**
+ * useTableState Hook
+ * Manages table state including sorting, filtering, pagination, and search
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+/**
+ * Hook to manage table state (sorting, filtering, search, pagination)
+ */
+export function useTableState({ data, columns, defaultSort, defaultFilters = [], searchConfig, pageSize: initialPageSize = 10, total: manualTotal, page, onSortChange, onFilterChange, onSearchChange, onPaginationChange, }) {
+    // State
+    const [sortConfig, setSortConfig] = useState(defaultSort ?? null);
+    const [filterConfigs, setFilterConfigs] = useState(defaultFilters);
+    const [searchQuery, setSearchQuery] = useState("");
+    const [currentPage, setCurrentPage] = useState(1);
+    const [pageSize, setPageSize] = useState(initialPageSize);
+    // Controlled page: mirror prop changes into internal state during render
+    // (adjust-state-on-prop-change). The hook keeps working uncontrolled when
+    // no `page` is supplied.
+    const prevControlledPageRef = useRef(undefined);
+    if (page !== undefined &&
+        page !== prevControlledPageRef.current &&
+        page !== currentPage) {
+        prevControlledPageRef.current = page;
+        setCurrentPage(page);
+    }
+    else {
+        prevControlledPageRef.current = page;
+    }
+    // Sync pageSize when initialPageSize changes (e.g. data loads and pagination is false)
+    useEffect(() => {
+        setPageSize(initialPageSize);
+    }, [initialPageSize]);
+    // Get search keys
+    const searchKeys = useMemo(() => {
+        if (!searchConfig)
+            return [];
+        const defaultKeys = columns
+            .filter((col) => col.accessorKey)
+            .map((col) => col.accessorKey);
+        if (typeof searchConfig === "boolean") {
+            return defaultKeys;
+        }
+        return searchConfig.searchKeys ?? defaultKeys;
+    }, [searchConfig, columns]);
+    // Filter data based on search query
+    // When onSearchChange is provided, data is already server-filtered — skip client-side filtering
+    const searchedData = useMemo(() => {
+        if (onSearchChange)
+            return data;
+        if (!searchQuery.trim() || searchKeys.length === 0)
+            return data;
+        const query = searchQuery.toLowerCase();
+        return data.filter((row) => {
+            return searchKeys.some((key) => {
+                const value = row[key];
+                if (value === null || value === undefined)
+                    return false;
+                return String(value).toLowerCase().includes(query);
+            });
+        });
+    }, [data, searchQuery, searchKeys, onSearchChange]);
+    // Apply filters
+    const filteredData = useMemo(() => {
+        if (filterConfigs.length === 0)
+            return searchedData;
+        return searchedData.filter((row) => {
+            return filterConfigs.every((filter) => {
+                const value = row[filter.key];
+                const filterValue = filter.value;
+                switch (filter.operator) {
+                    case "equals":
+                        if (typeof value === "boolean") {
+                            return value === (filterValue === "true" || filterValue === true);
+                        }
+                        return value === filterValue;
+                    case "contains":
+                        return String(value)
+                            .toLowerCase()
+                            .includes(String(filterValue).toLowerCase());
+                    case "startsWith":
+                        return String(value)
+                            .toLowerCase()
+                            .startsWith(String(filterValue).toLowerCase());
+                    case "endsWith":
+                        return String(value)
+                            .toLowerCase()
+                            .endsWith(String(filterValue).toLowerCase());
+                    case "in":
+                        if (typeof value === "boolean") {
+                            const strVal = String(value);
+                            return (Array.isArray(filterValue) &&
+                                filterValue.some((v) => v === strVal || v === value));
+                        }
+                        return Array.isArray(filterValue) && filterValue.includes(value);
+                    default:
+                        return true;
+                }
+            });
+        });
+    }, [searchedData, filterConfigs]);
+    // Apply sorting
+    const sortedData = useMemo(() => {
+        if (!sortConfig)
+            return filteredData;
+        const { key, direction } = sortConfig;
+        const column = columns.find((col) => col.accessorKey === key);
+        return [...filteredData].sort((a, b) => {
+            // Use custom sort function if provided
+            if (column?.sortFn) {
+                return column.sortFn(a, b, direction);
+            }
+            // Default sort
+            const aValue = a[key];
+            const bValue = b[key];
+            if (aValue === bValue)
+                return 0;
+            if (aValue === null || aValue === undefined)
+                return 1;
+            if (bValue === null || bValue === undefined)
+                return -1;
+            // Handle different types
+            if (typeof aValue === "string" && typeof bValue === "string") {
+                const result = aValue.localeCompare(bValue);
+                return direction === "asc" ? result : -result;
+            }
+            if (typeof aValue === "number" && typeof bValue === "number") {
+                return direction === "asc" ? aValue - bValue : bValue - aValue;
+            }
+            if (aValue instanceof Date && bValue instanceof Date) {
+                return direction === "asc"
+                    ? aValue.getTime() - bValue.getTime()
+                    : bValue.getTime() - aValue.getTime();
+            }
+            // Fallback to string comparison
+            const result = String(aValue).localeCompare(String(bValue));
+            return direction === "asc" ? result : -result;
+        });
+    }, [filteredData, sortConfig, columns]);
+    // Pagination
+    const totalPages = Math.ceil((manualTotal ?? sortedData.length) / pageSize);
+    const hasNextPage = currentPage < totalPages;
+    const hasPreviousPage = currentPage > 1;
+    const pageData = useMemo(() => {
+        // If manualTotal AND onPaginationChange are provided, assume server-side pagination
+        // Otherwise, do client-side pagination
+        if (manualTotal !== undefined && onPaginationChange !== undefined) {
+            return sortedData;
+        }
+        const startIndex = (currentPage - 1) * pageSize;
+        const endIndex = startIndex + pageSize;
+        return sortedData.slice(startIndex, endIndex);
+    }, [sortedData, currentPage, pageSize, manualTotal, onPaginationChange]);
+    // Toggle sort
+    const toggleSort = useCallback((key) => {
+        setSortConfig((prev) => {
+            let newSort;
+            if (!prev || prev.key !== key) {
+                newSort = { key, direction: "asc" };
+            }
+            else if (prev.direction === "asc") {
+                newSort = { key, direction: "desc" };
+            }
+            else {
+                newSort = null; // Clear sort
+            }
+            return newSort;
+        });
+        setCurrentPage(1); // Reset to first page when sorting changes
+    }, []);
+    // Notify parent of sort changes after render. Calling the callback directly
+    // inside useEffect is safe — the setState that triggered this effect has
+    // already committed; the callback runs in the passive-effect phase, not
+    // during render. (The prior queueMicrotask deferral broke act() in tests:
+    // the microtask fired outside act()'s flush window, so sync assertions saw
+    // zero calls.)
+    const prevSortRef = useRef(defaultSort ?? null);
+    useEffect(() => {
+        if (sortConfig !== prevSortRef.current) {
+            prevSortRef.current = sortConfig;
+            onSortChange?.(sortConfig);
+        }
+    });
+    // Notify parent of filter changes after render.
+    const prevFilterRef = useRef(defaultFilters);
+    useEffect(() => {
+        if (filterConfigs !== prevFilterRef.current) {
+            prevFilterRef.current = filterConfigs;
+            onFilterChange?.(filterConfigs);
+        }
+    });
+    // Extract debounce ms from searchConfig
+    const debounceMs = useMemo(() => {
+        if (!searchConfig || typeof searchConfig === "boolean")
+            return 0;
+        return searchConfig.debounce ?? 0;
+    }, [searchConfig]);
+    // Notify parent of search changes after render. When a debounce is
+    // configured, the parent (server-side search) is notified only after the
+    // debounce window elapses — firing on every keystroke would hammer the
+    // server. The local searchQuery state updates immediately so the local
+    // (client-side) filtering stays responsive; only the parent callback waits.
+    // The effect depends on [searchQuery] only: re-running it on unrelated
+    // re-renders would clear the pending timer and silently swallow the
+    // callback, so the latest callback is read through a ref instead.
+    const prevSearchRef = useRef("");
+    const onSearchChangeRef = useRef(onSearchChange);
+    useEffect(() => {
+        onSearchChangeRef.current = onSearchChange;
+    });
+    useEffect(() => {
+        if (searchQuery === prevSearchRef.current)
+            return;
+        prevSearchRef.current = searchQuery;
+        const callback = onSearchChangeRef.current;
+        if (!callback)
+            return;
+        if (debounceMs <= 0) {
+            callback(searchQuery);
+            return;
+        }
+        const timer = setTimeout(() => callback(searchQuery), debounceMs);
+        return () => clearTimeout(timer);
+    }, [searchQuery, debounceMs]);
+    // Notify parent of pagination changes after render.
+    const prevPaginationRef = useRef({ page: 1, pageSize: initialPageSize });
+    useEffect(() => {
+        const prev = prevPaginationRef.current;
+        if (currentPage !== prev.page || pageSize !== prev.pageSize) {
+            prevPaginationRef.current = { page: currentPage, pageSize };
+            onPaginationChange?.(currentPage, pageSize);
+        }
+    });
+    // Filter management
+    const setFilter = useCallback((filter) => {
+        setFilterConfigs((prev) => {
+            const filtered = prev.filter((f) => f.key !== filter.key);
+            return [...filtered, filter];
+        });
+        setCurrentPage(1);
+    }, []);
+    const removeFilter = useCallback((key) => {
+        setFilterConfigs((prev) => prev.filter((f) => f.key !== key));
+        setCurrentPage(1);
+    }, []);
+    const clearFilters = useCallback(() => {
+        setFilterConfigs([]);
+        setCurrentPage(1);
+    }, []);
+    const searchDebounceRef = useRef(null);
+    // Search management
+    const handleSetSearchQuery = useCallback((query) => {
+        setSearchQuery(query);
+        if (searchDebounceRef.current)
+            clearTimeout(searchDebounceRef.current);
+        if (debounceMs > 0) {
+            searchDebounceRef.current = setTimeout(() => {
+                setCurrentPage(1);
+            }, debounceMs);
+        }
+        else {
+            setCurrentPage(1);
+        }
+    }, [debounceMs]);
+    // Set current page and notify server-side listener
+    const handleSetCurrentPage = useCallback((pageOrUpdater) => {
+        setCurrentPage((prev) => {
+            const newPage = typeof pageOrUpdater === "function"
+                ? pageOrUpdater(prev)
+                : pageOrUpdater;
+            return newPage;
+        });
+    }, []);
+    // Pagination navigation
+    const nextPage = useCallback(() => {
+        if (hasNextPage) {
+            handleSetCurrentPage((prev) => prev + 1);
+        }
+    }, [hasNextPage, handleSetCurrentPage]);
+    const previousPage = useCallback(() => {
+        if (hasPreviousPage) {
+            handleSetCurrentPage((prev) => prev - 1);
+        }
+    }, [hasPreviousPage, handleSetCurrentPage]);
+    // Page size change — reset page without direct callback
+    const handleSetPageSize = useCallback((size) => {
+        setPageSize(size);
+        setCurrentPage(1);
+    }, []);
+    return {
+        processedData: sortedData,
+        pageData,
+        sortConfig,
+        setSortConfig,
+        toggleSort,
+        filterConfigs,
+        setFilter,
+        removeFilter,
+        clearFilters,
+        searchQuery,
+        setSearchQuery: handleSetSearchQuery,
+        currentPage,
+        setCurrentPage: handleSetCurrentPage,
+        pageSize,
+        setPageSize: handleSetPageSize,
+        totalPages,
+        hasNextPage,
+        hasPreviousPage,
+        nextPage,
+        previousPage,
+    };
+}