@kala-ui/react-app 0.1.0-beta.0

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

@@ -0,0 +1,23 @@
+/**
+ * DataTable Component
+ * Fully-featured, accessible data table with sorting, filtering, search, and pagination
+ *
+ * Features:
+ * - Sorting (single column)
+ * - Filtering (multiple filters)
+ * - Global search
+ * - Pagination with configurable page sizes
+ * - Row selection (optional)
+ * - Bulk actions (optional)
+ * - Loading states
+ * - Empty states
+ * - Full keyboard navigation
+ * - WCAG 2.1 AA compliant
+ * - React 19 compatible
+ */
+import type { DataTableProps } from "./data-table.types";
+/**
+ * DataTable Component
+ */
+export declare function DataTable<TData>({ data, columns, searchable, pagination, defaultSort, defaultFilters, filterableColumns, emptyState, isLoading, loadingConfig, skeletonConfig, skeleton, selection, bulkActions, onRowClick, getRowClassName, getRowAttributes, stickyHeader, compact, striped, bordered, hoverable, caption, footer, className, ariaLabel, stickyFooter, headersBelow, onSortChange, onFilterChange, toolbarContent, }: DataTableProps<TData>): import("react").JSX.Element;
+export { DataTableSkeleton } from "./data-table-skeleton";

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

@@ -0,0 +1,250 @@
+"use client";
+/**
+ * DataTable Component
+ * Fully-featured, accessible data table with sorting, filtering, search, and pagination
+ *
+ * Features:
+ * - Sorting (single column)
+ * - Filtering (multiple filters)
+ * - Global search
+ * - Pagination with configurable page sizes
+ * - Row selection (optional)
+ * - Bulk actions (optional)
+ * - Loading states
+ * - Empty states
+ * - Full keyboard navigation
+ * - WCAG 2.1 AA compliant
+ * - React 19 compatible
+ */
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@kala-ui/react/box";
+import { Button } from "@kala-ui/react/button";
+import { Checkbox } from "@kala-ui/react/checkbox";
+import { EmptyState } from "@kala-ui/react/empty-state";
+import { Flex } from "@kala-ui/react/flex";
+import { cn } from "@kala-ui/react/lib/utils";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "@kala-ui/react/select";
+import { Stack } from "@kala-ui/react/stack";
+import { TableCell, TableFooter, TableHead, TableHeader, TableRow, } from "@kala-ui/react/table";
+import { Text } from "@kala-ui/react/text";
+import { useDisclosure } from "@kala-ui/react-hooks";
+import { ArrowDown, ArrowUp } from "lucide-react";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { DataTableBodyRows } from "./data-table-body-rows.js";
+import { DataTableFilterChips } from "./data-table-filter-chips.js";
+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";
+/**
+ * DataTable Component
+ */
+export function DataTable({ data, columns, searchable, pagination, defaultSort, defaultFilters, filterableColumns, emptyState, isLoading = false, loadingConfig, skeletonConfig, skeleton, selection, bulkActions, onRowClick, getRowClassName, getRowAttributes, stickyHeader = true, compact = false, striped = false, bordered = false, hoverable = true, caption, footer, className, ariaLabel, stickyFooter = false, headersBelow = false, onSortChange, onFilterChange, toolbarContent, }) {
+    // Determine page size
+    const pageSize = useMemo(() => {
+        if (!pagination)
+            return data.length;
+        if (typeof pagination === "boolean")
+            return 10;
+        return pagination.pageSize;
+    }, [pagination, data.length]);
+    // Extract callbacks from configs
+    const paginationCallback = useMemo(() => {
+        if (!pagination || typeof pagination === "boolean")
+            return undefined;
+        return pagination.onPageChange;
+    }, [pagination]);
+    const totalCount = useMemo(() => {
+        if (!pagination || typeof pagination === "boolean")
+            return undefined;
+        return pagination.total;
+    }, [pagination]);
+    const searchCallback = useMemo(() => {
+        if (!searchable || typeof searchable === "boolean")
+            return undefined;
+        return searchable.onChange;
+    }, [searchable]);
+    // Table state management
+    const controlledPage = useMemo(() => {
+        if (!pagination || typeof pagination === "boolean")
+            return undefined;
+        return pagination.page;
+    }, [pagination]);
+    const tableState = useTableState({
+        data,
+        columns,
+        searchConfig: searchable,
+        pageSize,
+        total: totalCount,
+        page: controlledPage,
+        defaultSort,
+        defaultFilters,
+        onSortChange,
+        onFilterChange,
+        onSearchChange: searchCallback,
+        onPaginationChange: paginationCallback,
+    });
+    const { pageData, sortConfig, toggleSort, searchQuery, setSearchQuery, currentPage, setCurrentPage, pageSize: currentPageSize, setPageSize, totalPages, hasNextPage, hasPreviousPage, nextPage, previousPage, processedData, filterConfigs, setFilter, removeFilter, clearFilters, } = tableState;
+    // Determine display data: use full data for server-side pagination, pageData for client-side
+    const displayData = paginationCallback ? data : pageData;
+    // Row selection state. When the caller controls selection via
+    // `selection.selectedIds`, mirror prop changes into state during render
+    // (React's "adjust state on prop change" pattern) — useState only seeds the
+    // initial value, so bulk-delete flows that update the prop would otherwise
+    // keep rendering a stale selection.
+    const [selectedIds, setSelectedIds] = useState(selection?.selectedIds ?? new Set());
+    const controlledSelectedIds = selection?.selectedIds;
+    const prevControlledSelectedIds = useRef(controlledSelectedIds);
+    if (controlledSelectedIds !== undefined &&
+        controlledSelectedIds !== prevControlledSelectedIds.current) {
+        prevControlledSelectedIds.current = controlledSelectedIds;
+        setSelectedIds(controlledSelectedIds);
+    }
+    // Scroll container ref for scroll-to-top/bottom buttons
+    const scrollContainerRef = useRef(null);
+    const [showScrollButtons, { set: setShowScrollButtons }] = useDisclosure(false);
+    const handleScroll = useCallback(() => {
+        if (scrollContainerRef.current) {
+            const { scrollTop, scrollHeight, clientHeight } = scrollContainerRef.current;
+            setShowScrollButtons(scrollHeight > clientHeight && scrollTop > 100);
+        }
+    }, [setShowScrollButtons]);
+    const scrollToTop = useCallback(() => {
+        scrollContainerRef.current?.scrollTo({ top: 0, behavior: "smooth" });
+    }, []);
+    const scrollToBottom = useCallback(() => {
+        if (scrollContainerRef.current) {
+            scrollContainerRef.current.scrollTo({
+                top: scrollContainerRef.current.scrollHeight,
+                behavior: "smooth",
+            });
+        }
+    }, []);
+    // Handle select all
+    const isAllSelected = useMemo(() => {
+        if (!selection || displayData.length === 0)
+            return false;
+        const selectableRows = displayData.filter((row) => !selection.isRowSelectable || selection.isRowSelectable(row));
+        return selectableRows.every((row) => selectedIds.has(selection.getRowId(row)));
+    }, [selection, displayData, selectedIds]);
+    const isSomeSelected = useMemo(() => {
+        if (!selection || displayData.length === 0)
+            return false;
+        const selectableRows = displayData.filter((row) => !selection.isRowSelectable || selection.isRowSelectable(row));
+        return (selectableRows.some((row) => selectedIds.has(selection.getRowId(row))) &&
+            !isAllSelected);
+    }, [selection, displayData, selectedIds, isAllSelected]);
+    const handleSelectAll = useCallback(() => {
+        if (!selection)
+            return;
+        const newSelectedIds = new Set(selectedIds);
+        const selectableRows = displayData.filter((row) => !selection.isRowSelectable || selection.isRowSelectable(row));
+        if (isAllSelected) {
+            selectableRows.forEach((row) => {
+                newSelectedIds.delete(selection.getRowId(row));
+            });
+        }
+        else {
+            selectableRows.forEach((row) => {
+                newSelectedIds.add(selection.getRowId(row));
+            });
+        }
+        setSelectedIds(newSelectedIds);
+        selection.onSelectionChange(newSelectedIds);
+    }, [selection, displayData, selectedIds, isAllSelected]);
+    const handleSelectRow = useCallback((row) => {
+        if (!selection)
+            return;
+        const rowId = selection.getRowId(row);
+        const newSelectedIds = new Set(selectedIds);
+        if (newSelectedIds.has(rowId)) {
+            newSelectedIds.delete(rowId);
+        }
+        else {
+            newSelectedIds.add(rowId);
+        }
+        setSelectedIds(newSelectedIds);
+        selection.onSelectionChange(newSelectedIds);
+    }, [selection, selectedIds]);
+    // Get selected rows for bulk actions
+    const selectedRows = useMemo(() => {
+        if (!selection)
+            return [];
+        return data.filter((row) => selectedIds.has(selection.getRowId(row)));
+    }, [data, selectedIds, selection]);
+    // Search config
+    const searchConfig = useMemo(() => {
+        if (!searchable)
+            return null;
+        if (typeof searchable === "boolean") {
+            return {
+                placeholder: "Search...",
+                ariaLabel: "Search table",
+            };
+        }
+        return {
+            placeholder: searchable.placeholder ?? "Search...",
+            ariaLabel: searchable.ariaLabel ?? "Search table",
+            ...searchable,
+        };
+    }, [searchable]);
+    // Pagination config
+    const paginationConfig = useMemo(() => {
+        if (!pagination)
+            return null;
+        if (typeof pagination === "boolean") {
+            return {
+                page: currentPage,
+                pageSize: currentPageSize,
+                total: processedData.length,
+                pageSizeOptions: [10, 20, 50, 100],
+            };
+        }
+        return {
+            ...pagination,
+            page: currentPage,
+            pageSize: currentPageSize,
+            total: pagination.total ?? processedData.length,
+        };
+    }, [pagination, currentPage, currentPageSize, processedData.length]);
+    // Render loading state
+    if (isLoading) {
+        if (skeleton) {
+            return (_jsx(Stack, { gap: 4, className: className, children: skeleton }));
+        }
+        const showSearch = !!searchConfig;
+        const showFilters = !!filterableColumns;
+        const showPagination = !!paginationConfig;
+        const showSelection = !!selection?.enabled;
+        const showBulkActions = !!bulkActions;
+        const skeletonRows = skeletonConfig?.rows ?? loadingConfig?.rows ?? 5;
+        return (_jsx(Stack, { gap: 4, className: className, children: _jsx(DataTableSkeleton, { rows: skeletonRows, columns: columns, showSearch: showSearch, showFilters: showFilters, showPagination: showPagination, showSelection: showSelection, showBulkActions: showBulkActions, stickyHeader: stickyHeader, stickyFooter: stickyFooter }) }));
+    }
+    // Compute empty state config
+    const emptyConfig = {
+        title: searchQuery ? "No results found" : "No data available",
+        description: searchQuery
+            ? `No results found for "${searchQuery}". Try adjusting your search.`
+            : "There is no data to display at the moment.",
+        ...emptyState,
+    };
+    return (_jsxs(Stack, { 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
+                            ? "flex-1 min-h-0"
+                            : "", bordered && "border-2", paginationConfig && displayData.length > 0
+                            ? "rounded-t-lg border-b-0"
+                            : "rounded-lg"), children: [_jsx(Box, { ref: scrollContainerRef, onScroll: handleScroll, className: cn("overflow-auto relative", paginationConfig && displayData.length > 0
+                                    ? "rounded-t-lg"
+                                    : "rounded-lg", stickyFooter ? "flex-1 min-h-0 max-h-[70vh]" : "max-h-[800px]"), children: _jsxs("table", { className: "w-full border-separate border-spacing-0 caption-bottom text-sm", children: [caption && _jsx("caption", { className: "sr-only", children: caption }), _jsx(DataTableHeaderRow, { columns: columns, selection: selection, sortConfig: sortConfig, onToggleSort: toggleSort, filterableColumns: filterableColumns, filterConfigs: filterConfigs, onSetFilter: setFilter, onRemoveFilter: removeFilter, isAllSelected: isAllSelected, isSomeSelected: isSomeSelected, onSelectAll: handleSelectAll, stickyHeader: stickyHeader }), displayData.length === 0 ? (_jsx("tbody", { children: _jsx("tr", { children: _jsx("td", { colSpan: columns.length + (selection?.enabled ? 1 : 0), className: "h-48 text-center", children: _jsxs("div", { className: "flex flex-col items-center gap-3", children: [_jsx(Text, { size: "sm", className: "text-muted-foreground", children: "No results match the current filters." }), clearFilters && (_jsx(Button, { variant: "outline", size: "sm", onClick: clearFilters, children: "Clear Filters" }))] }) }) }) })) : (_jsxs(_Fragment, { children: [_jsx(DataTableBodyRows, { displayData: displayData, columns: columns, selection: selection, selectedIds: selectedIds, onSelectRow: handleSelectRow, onRowClick: onRowClick, compact: compact, striped: striped, hoverable: hoverable, getRowClassName: getRowClassName, getRowAttributes: getRowAttributes, hasPagination: !!paginationConfig, hasFooter: !!footer }), headersBelow && displayData.length > 10 && (_jsx(TableHeader, { className: cn("bg-muted border-t", stickyFooter &&
+                                                        "sticky bottom-0 z-40 shadow-[0_-1px_0_0_var(--border)] backdrop-blur-sm bg-muted/95"), children: _jsxs(TableRow, { children: [selection?.enabled && (_jsx(TableHead, { className: "w-12", children: _jsx(Checkbox, { checked: isAllSelected
+                                                                        ? true
+                                                                        : isSomeSelected
+                                                                            ? "indeterminate"
+                                                                            : false, onCheckedChange: handleSelectAll, "aria-label": "Select all rows (bottom)" }) })), columns.map((column) => (_jsx(TableHead, { className: cn(column.className, column.align === "center" && "text-center", column.align === "right" && "text-right"), children: _jsx(Flex, { align: "center", gap: 2, className: cn(column.align === "center" && "justify-center", column.align === "right" && "justify-end"), children: column.enableSorting !== false ? (_jsxs(Button, { variant: "ghost", size: "sm", className: "h-auto p-0 -ml-2 justify-start font-medium hover:bg-transparent", onClick: () => toggleSort(column.accessorKey ||
+                                                                            column.id), "aria-label": `Sort by ${column.header}`, children: [column.header, sortConfig?.key ===
+                                                                                (column.accessorKey || column.id) &&
+                                                                                (sortConfig.direction === "asc" ? (_jsx(ArrowUp, { className: "ml-2 h-4 w-4 text-muted-foreground", "aria-hidden": "true" })) : (_jsx(ArrowDown, { className: "ml-2 h-4 w-4 text-muted-foreground", "aria-hidden": "true" })))] })) : (_jsx(Text, { weight: "medium", children: column.header })) }) }, column.id)))] }) })), footer && (_jsx(TableFooter, { className: cn("border-t", !!paginationConfig && "border-b"), children: _jsx(TableRow, { className: "border-0", children: _jsx(TableCell, { colSpan: columns.length + (selection?.enabled ? 1 : 0), className: "p-4", children: footer }) }) }))] }))] }) }), showScrollButtons && (_jsxs(Flex, { gap: 2, className: "absolute bottom-4 right-4 z-10", children: [_jsx(Button, { color: "secondary", size: "icon", onClick: scrollToTop, className: "rounded-full shadow-lg h-9 w-9 bg-background/80 backdrop-blur-sm border-border-strong/20", "aria-label": "Scroll to top", children: _jsx(ArrowUp, { className: "h-4 w-4" }) }), _jsx(Button, { color: "secondary", size: "icon", onClick: scrollToBottom, className: "rounded-full shadow-lg h-9 w-9 bg-background/80 backdrop-blur-sm border-border-strong/20", "aria-label": "Scroll to bottom", children: _jsx(ArrowDown, { className: "h-4 w-4" }) })] }))] }), paginationConfig && displayData.length > 0 && (_jsxs(Flex, { align: "center", justify: "between", className: cn("flex-col gap-3 sm:flex-row sm:gap-0 px-4 py-3 border rounded-b-lg bg-muted/30", stickyFooter && "shrink-0"), children: [_jsxs(Flex, { align: "center", justify: "between", gap: 4, className: "w-full sm:w-auto", wrap: "wrap", children: [_jsxs(Text, { as: "span", className: "text-foreground whitespace-nowrap", children: [Math.min((paginationConfig.page - 1) * paginationConfig.pageSize + 1, paginationConfig.total), " - ", Math.min(paginationConfig.page * paginationConfig.pageSize, paginationConfig.total), " / ", _jsx(Text, { as: "span", weight: "medium", className: "text-foreground", children: paginationConfig.total })] }), paginationConfig.pageSizeOptions && (_jsxs(Flex, { align: "center", gap: 2, children: [_jsx(Text, { size: "sm", className: "text-muted-foreground whitespace-nowrap", children: "Rows per page" }), _jsxs(Select, { value: String(paginationConfig.pageSize), onValueChange: (value) => setPageSize(Number(value)), children: [_jsx(SelectTrigger, { className: "h-8 w-[70px]", children: _jsx(SelectValue, { placeholder: String(paginationConfig.pageSize) }) }), _jsx(SelectContent, { side: "top", children: paginationConfig.pageSizeOptions.map((option) => (_jsx(SelectItem, { value: String(option), children: option }, option))) })] })] }))] }), _jsx(PaginationNav, { currentPage: paginationConfig.page, totalPages: totalPages, hasPreviousPage: hasPreviousPage, hasNextPage: hasNextPage, onPageChange: setCurrentPage, onPreviousPage: previousPage, onNextPage: nextPage })] }))] }))] }));
+}
+// Export skeleton for direct use
+export { DataTableSkeleton } from "./data-table-skeleton.js";

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

@@ -0,0 +1,305 @@
+/**
+ * DataTable Types
+ * Type definitions for the DataTable component with full TypeScript support
+ */
+import type { EmptyStateProps } from "@kala-ui/react/empty-state";
+import type { HTMLAttributes, ReactNode } from "react";
+/**
+ * Sort direction
+ */
+export type SortDirection = "asc" | "desc";
+/**
+ * Sort configuration
+ */
+export interface SortConfig<TData> {
+    key: keyof TData;
+    direction: SortDirection;
+}
+/**
+ * Filter operator types
+ */
+export type FilterOperator = "equals" | "contains" | "startsWith" | "endsWith" | "in";
+/**
+ * Filter configuration
+ */
+export interface FilterConfig<TData> {
+    key: keyof TData;
+    operator: FilterOperator;
+    value: unknown;
+}
+/**
+ * Filterable column configuration
+ */
+export interface FilterableColumn<TData> {
+    /** Key of the column to filter */
+    key: keyof TData;
+    /** Label to display for the filter */
+    label: string;
+    /** Type of filter input */
+    type: "select" | "text";
+    /** Options for select filter */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    /** Placeholder for text filter */
+    placeholder?: string;
+    /** Filter operator to use (default: 'equals' for select, 'contains' for text) */
+    operator?: FilterOperator;
+}
+/**
+ * Column definition for DataTable
+ */
+export interface ColumnDef<TData> {
+    /** Unique identifier for the column */
+    id: string;
+    /** Column header label */
+    header: string;
+    /** Key to access data from row object */
+    accessorKey?: keyof TData;
+    /** Custom cell renderer */
+    cell?: (row: TData) => ReactNode;
+    /** Enable sorting for this column */
+    enableSorting?: boolean;
+    /** Custom CSS class for the column */
+    className?: string;
+    /** Enable filtering for this column */
+    enableFiltering?: boolean;
+    /** Custom sort function */
+    sortFn?: (a: TData, b: TData, direction: SortDirection) => number;
+    /** Column width (CSS value) */
+    width?: string;
+    /** Column alignment */
+    align?: "left" | "center" | "right";
+    /** Hide column on mobile */
+    hideOnMobile?: boolean;
+    /** ARIA label for column header */
+    ariaLabel?: string;
+}
+/**
+ * Pagination configuration
+ */
+export interface PaginationConfig {
+    /** Current page number (1-indexed) */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of items */
+    total: number;
+    /** Page size options */
+    pageSizeOptions?: number[];
+    /** Callback when pagination changes (for server-side pagination) */
+    onPageChange?: (page: number, pageSize: number) => void;
+}
+/**
+ * Search configuration
+ */
+export interface SearchConfig<TData> {
+    /** Placeholder text for search input */
+    placeholder?: string;
+    /** Keys to search in */
+    searchKeys?: (keyof TData)[];
+    /** Debounce delay in ms */
+    debounce?: number;
+    /** ARIA label for search input */
+    ariaLabel?: string;
+    /** Callback when search query changes (for server-side search) */
+    onChange?: (query: string) => void;
+}
+/**
+ * Empty state configuration
+ */
+export interface EmptyStateConfig {
+    /** Title text */
+    title?: string;
+    /** Description text */
+    description?: string;
+    /** Icon component */
+    icon?: EmptyStateProps["icon"];
+    /** Action button */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+/**
+ * Loading state configuration - DEPRECATED: Use DataTableSkeletonConfig
+ */
+export interface LoadingConfig {
+    /** Number of skeleton rows to show */
+    rows?: number;
+    /** Show loading overlay */
+    overlay?: boolean;
+}
+/**
+ * DataTable Skeleton Configuration
+ * Full-featured skeleton configuration for DataTable
+ */
+export interface DataTableSkeletonConfig<_TData = unknown> {
+    /** Number of skeleton rows to show (default: 5) */
+    rows?: number;
+    /** Show search bar skeleton */
+    showSearch?: boolean;
+    /** Show filter pills skeleton */
+    showFilters?: boolean;
+    /** Number of filter pills to show (default: 3) */
+    filterCount?: number;
+    /** Show pagination skeleton */
+    showPagination?: boolean;
+    /** Show selection checkboxes */
+    showSelection?: boolean;
+    /** Show bulk actions bar */
+    showBulkActions?: boolean;
+    /** Enable sticky header */
+    stickyHeader?: boolean;
+    /** Enable sticky footer (for pagination) */
+    stickyFooter?: boolean;
+}
+/**
+ * Row selection configuration
+ */
+export interface SelectionConfig<TData> {
+    /** Enable row selection */
+    enabled: boolean;
+    /** Selected row IDs */
+    selectedIds: Set<string>;
+    /** Get unique ID from row */
+    getRowId: (row: TData) => string;
+    /** Selection change handler */
+    onSelectionChange: (selectedIds: Set<string>) => void;
+    /** Disable selection for specific rows */
+    isRowSelectable?: (row: TData) => boolean;
+}
+/**
+ * Bulk action definition
+ */
+export interface BulkAction<TData> {
+    /** Action identifier */
+    id: string;
+    /** Action label */
+    label: string;
+    /** Action icon */
+    icon?: ReactNode;
+    /** Action handler */
+    onClick: (selectedRows: TData[]) => void | Promise<void>;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Variant (default, destructive, etc.) */
+    variant?: "solid" | "ghost" | "outline" | "subtle" | "link" | "destructive";
+    /** Requires confirmation */
+    requireConfirmation?: boolean;
+    /** Confirmation message */
+    confirmationMessage?: string;
+}
+/**
+ * DataTable Props
+ */
+export interface DataTableProps<TData> {
+    /** Table data */
+    data: TData[];
+    /** Column definitions */
+    columns: ColumnDef<TData>[];
+    /** Enable global search */
+    searchable?: SearchConfig<TData> | boolean;
+    /** Enable pagination */
+    pagination?: PaginationConfig | boolean;
+    /** Initial sort configuration */
+    defaultSort?: SortConfig<TData>;
+    /** Initial filter configuration */
+    defaultFilters?: FilterConfig<TData>[];
+    /** Filterable columns configuration */
+    filterableColumns?: FilterableColumn<TData>[];
+    /** Callback when sort changes (for server-side sorting) */
+    onSortChange?: (sort: SortConfig<TData> | null) => void;
+    /** Callback when filters change (for server-side filtering) */
+    onFilterChange?: (filters: FilterConfig<TData>[]) => void;
+    /** Empty state configuration */
+    emptyState?: EmptyStateConfig;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Loading configuration - DEPRECATED: Use loadingConfig or skeletonConfig */
+    loadingConfig?: LoadingConfig;
+    /** Skeleton configuration for advanced control */
+    skeletonConfig?: DataTableSkeletonConfig;
+    /** Custom skeleton override */
+    skeleton?: React.ReactNode;
+    /** Row selection */
+    selection?: SelectionConfig<TData>;
+    /** Bulk actions */
+    bulkActions?: BulkAction<TData>[];
+    /** Row click handler */
+    onRowClick?: (row: TData) => void;
+    /** Custom row class name function */
+    getRowClassName?: (row: TData) => string;
+    /** Custom row attributes function */
+    getRowAttributes?: (row: TData) => HTMLAttributes<HTMLTableRowElement>;
+    /** Sticky header */
+    stickyHeader?: boolean;
+    /** Compact mode (reduced padding) */
+    compact?: boolean;
+    /** Striped rows */
+    striped?: boolean;
+    /** Bordered */
+    bordered?: boolean;
+    /** Hoverable rows */
+    hoverable?: boolean;
+    /** Custom table caption for a11y */
+    caption?: string;
+    /** Table footer content */
+    footer?: ReactNode;
+    /** Extra content rendered in the toolbar row, next to the search input */
+    toolbarContent?: ReactNode;
+    /** Custom CSS class for table container */
+    className?: string;
+    /** ARIA label for the table */
+    ariaLabel?: string;
+    /** Sticky footer (keeps pagination visible when scrolling) */
+    stickyFooter?: boolean;
+    /** Show duplicate column headers below data rows */
+    headersBelow?: boolean;
+}
+/**
+ * Table state hook return type
+ */
+export interface TableState<TData> {
+    /** Current filtered and sorted data */
+    processedData: TData[];
+    /** Current page data (if pagination enabled) */
+    pageData: TData[];
+    /** Current sort configuration */
+    sortConfig: SortConfig<TData> | null;
+    /** Set sort configuration */
+    setSortConfig: (config: SortConfig<TData> | null) => void;
+    /** Toggle sort for a column */
+    toggleSort: (key: keyof TData) => void;
+    /** Current filter configurations */
+    filterConfigs: FilterConfig<TData>[];
+    /** Add or update filter */
+    setFilter: (filter: FilterConfig<TData>) => void;
+    /** Remove filter */
+    removeFilter: (key: keyof TData) => void;
+    /** Clear all filters */
+    clearFilters: () => void;
+    /** Search query */
+    searchQuery: string;
+    /** Set search query */
+    setSearchQuery: (query: string) => void;
+    /** Current page (1-indexed) */
+    currentPage: number;
+    /** Set current page */
+    setCurrentPage: (page: number) => void;
+    /** Page size */
+    pageSize: number;
+    /** Set page size */
+    setPageSize: (size: number) => void;
+    /** Total pages */
+    totalPages: number;
+    /** Has next page */
+    hasNextPage: boolean;
+    /** Has previous page */
+    hasPreviousPage: boolean;
+    /** Go to next page */
+    nextPage: () => void;
+    /** Go to previous page */
+    previousPage: () => void;
+}

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

@@ -0,0 +1,6 @@
+"use client";
+/**
+ * DataTable Types
+ * Type definitions for the DataTable component with full TypeScript support
+ */
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * DataTable Component Exports
+ */
+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";

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

@@ -0,0 +1,6 @@
+"use client";
+/**
+ * DataTable Component Exports
+ */
+export { DataTable, DataTableSkeleton } from "./data-table.js";
+export { useTableState } from "./useTableState.js";

package/dist/components/data-table/pagination-nav.d.ts

@@ -0,0 +1,15 @@
+/**
+ * PaginationNav Component
+ * Numbered page buttons with ellipsis for DataTable pagination
+ */
+interface PaginationNavProps {
+    currentPage: number;
+    totalPages: number;
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+    onPageChange: (page: number) => void;
+    onPreviousPage: () => void;
+    onNextPage: () => void;
+}
+export declare function PaginationNav({ currentPage, totalPages, hasPreviousPage, hasNextPage, onPageChange, onPreviousPage, onNextPage, }: PaginationNavProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,23 @@
+"use client";
+/**
+ * PaginationNav Component
+ * Numbered page buttons with ellipsis for DataTable pagination
+ */
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@kala-ui/react/box";
+import { Button } from "@kala-ui/react/button";
+import { Flex } from "@kala-ui/react/flex";
+import { DOTS, usePagination } from "@kala-ui/react-hooks";
+import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";
+export function PaginationNav({ currentPage, totalPages, hasPreviousPage, hasNextPage, onPageChange, onPreviousPage, onNextPage, }) {
+    // Use fewer siblings on small screens to reduce button count
+    const { range } = usePagination({
+        total: totalPages,
+        page: currentPage,
+        siblings: 0,
+        boundaries: 1,
+        onPageChange,
+    });
+    return (_jsxs(Flex, { align: "center", justify: "center", wrap: "wrap", gap: 1, children: [_jsxs(Button, { variant: "outline", size: "sm", onClick: onPreviousPage, disabled: !hasPreviousPage, className: "h-8 w-8 p-0", children: [_jsx(ChevronLeft, { className: "h-4 w-4" }), _jsx(Box, { as: "span", className: "sr-only", children: "Previous page" })] }), range.map((item, index) => item === DOTS ? (_jsx(Flex, { align: "center", justify: "center", className: "h-8 w-8", "aria-hidden": true, children: _jsx(MoreHorizontal, { className: "h-4 w-4 text-muted-foreground" }) }, `dots-${index}`)) : (_jsx(Button, { variant: item === currentPage ? "solid" : "outline", size: "sm", onClick: () => onPageChange(item), className: "h-8 w-8 p-0 text-xs", "aria-label": `Page ${item}`, "aria-current": item === currentPage ? "page" : undefined, children: item }, item))), _jsxs(Button, { variant: "outline", size: "sm", onClick: onNextPage, disabled: !hasNextPage, className: "h-8 w-8 p-0", children: [_jsx(ChevronRight, { className: "h-4 w-4" }), _jsx(Box, { as: "span", className: "sr-only", children: "Next page" })] })] }));
+}