pagamio-frontend-commons-lib/lib/shared/hooks/usePagamioTable.d.ts

Pagamio library for Frontend reusable components like the form engine and table container

import type { QueryParamConfig, ResponseMapping } from '../../api';
import type { BaseEntity, CoreTableColumnDef, SortConfig } from '../../pagamio-table/data-table/types';
/**
 * Props interface for usePagamioTable hook
 */
export interface UsePagamioTableProps<T extends BaseEntity> {
    /** Function to fetch data from the API */
    fetchData?: (query?: Record<string, string>, signal?: AbortSignal) => Promise<any>;
    /** Data for client-side operations */
    data?: T[];
    /** Table column definitions */
    columns: CoreTableColumnDef<T>[];
    /** Initial filter values */
    defaultFilters?: Record<string, string>;
    /** Configuration for response structure mapping */
    responseMapping?: ResponseMapping;
    /** Configuration for query parameter formatting */
    queryParamConfig?: QueryParamConfig;
    /** Pagination configuration */
    pagination?: {
        enabled: boolean;
        mode: 'client' | 'server';
        pageSize?: number;
        pageIndex?: number;
    };
    /** Filtering configuration */
    filtering?: {
        enabled: boolean;
        mode: 'client' | 'server';
        searchMode?: 'client' | 'server';
    };
    /** Sorting configuration */
    sorting?: {
        enabled: boolean;
        mode: 'client' | 'server';
    };
}
interface UsePagamioTableReturn<T extends BaseEntity> {
    data: T[];
    totalItems: number;
    loading: boolean;
    error: string | null;
    currentPage: number;
    itemsPerPage: number;
    searchQuery: string;
    selectedFilters: Record<string, string>;
    appliedFilters: Record<string, string>;
    sortConfig: SortConfig;
    columns: CoreTableColumnDef<T>[];
    handleApplyFilters: () => void;
    handlePageChange: (newPage: number) => void;
    handlePaginationChange: (newPageIndex: number, newPageSize: number) => void;
    setSearchQuery: (query: string) => void;
    setCurrentPage: (page: number) => void;
    setItemsPerPage: (size: number) => void;
    handleFilterChange: (columnKey: string, value: string) => void;
    handleSort: (sortBy: string, sortDir: 'asc' | 'desc') => void;
    handleClearFilters: () => void;
    refresh: () => void;
}
export declare const springBootMapping: ResponseMapping;
export declare const arrayResponseMapping: ResponseMapping;
/**
 * Custom hook for managing table data with pagination, sorting, and filtering.
 * Supports both client-side and server-side operations.
 *
 * @template T - The type of data items in the table. Must extend `BaseEntity`.
 *
 * @param {UsePagamioTableProps<T>} props - Configuration options for the hook.
 * @param {Function} [props.fetchData] - Function to fetch data from the API (required for server-side operations).
 * @param {T[]} [props.data] - Initial data for client-side operations.
 * @param {CoreTableColumnDef<T>[]} props.columns - Column definitions for the table.
 * @param {Record<string, string>} [props.defaultFilters] - Initial filter values.
 * @param {ResponseMapping} [props.responseMapping] - Configuration for mapping API response structure.
 * @param {QueryParamConfig} [props.queryParamConfig] - Configuration for query parameter formatting.
 * @param {Object} [props.pagination] - Pagination configuration.
 * @param {boolean} [props.pagination.enabled] - Whether pagination is enabled.
 * @param {'client' | 'server'} [props.pagination.mode] - Pagination mode ('client' or 'server').
 * @param {number} [props.pagination.pageSize] - Default page size.
 * @param {Object} [props.filtering] - Filtering configuration.
 * @param {boolean} [props.filtering.enabled] - Whether filtering is enabled.
 * @param {'client' | 'server'} [props.filtering.mode] - Filtering mode ('client' or 'server').
 * @param {Object} [props.sorting] - Sorting configuration.
 * @param {boolean} [props.sorting.enabled] - Whether sorting is enabled.
 * @param {'client' | 'server'} [props.sorting.mode] - Sorting mode ('client' or 'server').
 *
 * @returns {Object} - Table state and utility functions.
 * @returns {T[]} data - The processed and paginated data.
 * @returns {number} totalItems - Total number of items (for server-side pagination).
 * @returns {boolean} loading - Whether data is being fetched.
 * @returns {string | null} error - Error message, if any.
 * @returns {number} currentPage - Current page index.
 * @returns {number} itemsPerPage - Number of items per page.
 * @returns {string} searchQuery - Current search query.
 * @returns {Record<string, string>} appliedFilters - Currently applied filters.
 * @returns {Record<string, string>} selectedFilters - Currently selected filters.
 * @returns {SortConfig} sortConfig - Current sorting configuration.
 * @returns {CoreTableColumnDef<T>[]} columns - Column definitions.
 * @returns {Function} handleApplyFilters - Function to apply filters.
 * @returns {Function} handlePageChange - Function to change the current page.
 * @returns {Function} handlePaginationChange - Function to change pagination settings.
 * @returns {Function} setSearchQuery - Function to update the search query.
 * @returns {Function} setCurrentPage - Function to update the current page.
 * @returns {Function} setItemsPerPage - Function to update the items per page.
 * @returns {Function} handleFilterChange - Function to update filters.
 * @returns {Function} handleSort - Function to update sorting.
 * @returns {Function} handleClearFilters - Function to clear all filters.
 * @returns {Function} refresh - Function to manually refresh the table data.
 */
export declare const usePagamioTable: <T extends BaseEntity>({ fetchData, data: clientData, columns, defaultFilters, responseMapping, queryParamConfig, pagination, filtering, sorting, }: UsePagamioTableProps<T>) => UsePagamioTableReturn<T>;
export {};
/**
 * Example usage of the `usePagamioTable` hook.
 *
 * @example
 * const table = usePagamioTable<Product>({
 *   fetchData: fetchProducts,
 *   columns: columns as unknown as CoreTableColumnDef<Product>[],
 *   defaultFilters: initialFilters,
 *   pagination: { enabled: true, mode: "server" },
 *   filtering: { enabled: true, mode: "server" },
 *   queryParamConfig: {
 *     filtering: { searchParam: "name", filterFormat: "flat" },
 *   },
 * });
 *
 * // Render the table
 * return (
 *   <CoreTable
 *     columns={table.columns}
 *     data={table.data}
 *     pagination={{
 *       enabled: true,
 *       pageIndex: table.currentPage,
 *       pageSize: table.itemsPerPage,
 *       itemsPerPage: table.itemsPerPage,
 *       itemsPerPageOptions: [10, 25, 50],
 *       onPageChange: table.handlePageChange,
 *       onPaginationChange: table.handlePaginationChange,
 *     }}
 *     filtering={{
 *       filters: filters,
 *       appliedFilters: table.selectedFilters,
 *       onTableFilter: table.handleFilterChange,
 *     }}
 *     sorting={{
 *       sortConfig: table.sortConfig,
 *       onSort: table.handleSort,
 *     }}
 *     search={{
 *       enabled: true,
 *       searchQuery: table.searchQuery,
 *       onSearch: (e) => table.setSearchQuery(e.target.value),
 *     }}
 *     onClearFilters={table.handleClearFilters}
 *   />
 * );
 */