analytica-frontend-lib/dist/TableProvider/index.d.ts

Repositório público dos componentes utilizados nas plataformas da Analytica Ensino

import { ReactNode } from 'react';
import { type SortMode, type SortState } from '../Table/index';
import { type ColumnFilterConfig } from '../components/Table/useColumnFilters';
import { FilterConfig } from '../Filter/useTableFilter/index';
export type { ColumnFilterConfig, ColumnFilterOption, } from '../components/Table/useColumnFilters';
/**
 * Column configuration with flexible rendering options
 */
export interface ColumnConfig<T = Record<string, unknown>> {
    /** Column key (must match data object key) */
    key: string;
    /** Column label - can be string or JSX */
    label: string | ReactNode;
    /**
     * Enable sorting for this column. Overrides `sortableColumns`; when omitted,
     * `sortableColumns` decides.
     */
    sortable?: boolean;
    /**
     * Field to sort by, when it differs from the rendered one. A column showing
     * `totalTimeFormatted` ("2h 05min") must sort by `totalTime` — otherwise the
     * API gets a field it doesn't know, and a client-side sort would compare the
     * formatted strings. Defaults to `key`.
     */
    sortKey?: string;
    /** Turns this column's header into a filter dropdown. */
    filter?: ColumnFilterConfig;
    /** Custom render function for cell content */
    render?: (value: unknown, row: T, index: number) => ReactNode;
    /** Column width */
    width?: string;
    /** Additional CSS classes */
    className?: string;
    /** Text alignment */
    align?: 'left' | 'center' | 'right';
}
/**
 * Which columns can be sorted, when a column doesn't say so itself.
 *
 * Defaults to none: turning `enableTableSort` on must not silently make every
 * column clickable, since most tables here are paginated server-side and a
 * client-side sort would only reorder the page you're looking at.
 */
export declare function isColumnSortable<T>(header: ColumnConfig<T>, enableTableSort: boolean, sortableColumns: SortableColumns | undefined): boolean;
export type SortableColumns = 'all' | string[];
/**
 * Combined parameters sent via onParamsChange
 */
export interface TableParams {
    /** Current page number */
    page: number;
    /** Items per page */
    limit: number;
    /** Search query */
    search?: string;
    /** Active filters (dynamic keys based on filter configs) */
    [key: string]: unknown;
    /** Sort column */
    sortBy?: string;
    /** Sort direction */
    sortOrder?: 'asc' | 'desc';
}
/**
 * Pagination configuration
 */
export interface PaginationConfig {
    /** Label for items (e.g., "atividades") */
    itemLabel?: string;
    /** Items per page options */
    itemsPerPageOptions?: number[];
    /** Default items per page */
    defaultItemsPerPage?: number;
    /** Total items (for displaying pagination info) */
    totalItems?: number;
    /** Total pages (if known from backend) */
    totalPages?: number;
}
/**
 * Empty state configuration
 */
export interface EmptyStateConfig {
    /** Custom component to render when table is empty (no data and no search active) */
    component?: ReactNode;
    /** Image to display in empty state (path from project) */
    image?: string;
    /** Title text for empty state */
    title?: string;
    /** Description text for empty state */
    description?: string;
    /** Button text for empty state action (optional) */
    buttonText?: string;
    /** Icon to display on button (optional) */
    buttonIcon?: ReactNode;
    /** Callback when empty state button is clicked */
    onButtonClick?: () => void;
    /** Button variant (solid, outline, or link) */
    buttonVariant?: 'solid' | 'outline' | 'link';
    /** Button action color (primary, positive, or negative) */
    buttonAction?: 'primary' | 'positive' | 'negative';
}
/**
 * Loading state configuration
 */
export interface LoadingStateConfig {
    /** Custom component to render when table is loading */
    component?: ReactNode;
}
/**
 * No search result state configuration
 */
export interface NoSearchResultConfig {
    /** Custom component to render when search returns no results */
    component?: ReactNode;
    /** Title for no search result state */
    title?: string;
    /** Description for no search result state */
    description?: string;
    /** Image to display in no search result state */
    image?: string;
}
/**
 * Table components exposed via render prop
 */
export interface TableComponents {
    /** Search and filter controls */
    controls: ReactNode;
    /** Table with data */
    table: ReactNode;
    /** Pagination controls */
    pagination: ReactNode;
}
/**
 * TableProvider Props
 */
export interface TableProviderProps<T = Record<string, unknown>> {
    /** Data to display in the table */
    readonly data: T[];
    /** Column configurations */
    readonly headers: ColumnConfig<T>[];
    /** Loading state */
    readonly loading?: boolean;
    /** Table variant */
    readonly variant?: 'default' | 'borderless';
    /** Enable search functionality */
    readonly enableSearch?: boolean;
    /** Enable filters functionality */
    readonly enableFilters?: boolean;
    /** Enable table sorting */
    readonly enableTableSort?: boolean;
    /**
     * Which columns are sortable: `'all'`, or an explicit list of column keys.
     * A column's own `sortable` flag wins over this. Defaults to none.
     */
    readonly sortableColumns?: SortableColumns;
    /**
     * `'client'` (default) sorts the rows it was handed. `'server'` leaves them
     * in the order they arrived and just reports `sortBy`/`sortOrder` through
     * `onParamsChange`, for the API to sort.
     */
    readonly sortMode?: SortMode;
    /** Sort applied when the URL doesn't specify one. */
    readonly defaultSort?: SortState;
    /**
     * Namespaces this table's URL params (`vendas_sortBy` instead of `sortBy`).
     * Required whenever two tables can share a URL — otherwise one reads the
     * other's sort column, which the API will reject.
     */
    readonly tableId?: string;
    /** Enable pagination */
    readonly enablePagination?: boolean;
    /** Enable row click functionality */
    readonly enableRowClick?: boolean;
    /** Initial filter configurations */
    readonly initialFilters?: FilterConfig[];
    /** Pagination configuration */
    readonly paginationConfig?: PaginationConfig;
    /** Search placeholder text */
    readonly searchPlaceholder?: string;
    /** Additional CSS classes for the search container */
    readonly searchContainerClassName?: string;
    /** Empty state configuration (when table is empty with no search) */
    readonly emptyState?: EmptyStateConfig;
    /** Loading state configuration (when table is loading) */
    readonly loadingState?: LoadingStateConfig;
    /** No search result state configuration (when search returns no results) */
    readonly noSearchResultState?: NoSearchResultConfig;
    /** Key field name to use for unique row identification (recommended for better performance) */
    readonly rowKey?: keyof T;
    /** Callback when any parameter changes */
    readonly onParamsChange?: (params: TableParams) => void;
    /** Callback when row is clicked */
    readonly onRowClick?: (row: T, index: number) => void;
    /**
     * Content to display in the header area (e.g., action buttons)
     * Rendered above the search/filter controls
     */
    readonly headerContent?: ReactNode;
    /**
     * Additional CSS classes for the container wrapper
     */
    readonly containerClassName?: string;
    /**
     * Render prop for custom layout control
     * When provided, gives full control over component positioning
     * @param components - Table components (controls, table, pagination)
     * @returns Custom layout JSX
     *
     * @example
     * ```tsx
     * <TableProvider {...props}>
     *   {({ controls, table, pagination }) => (
     *     <>
     *       <div className="mb-4">{controls}</div>
     *       <div className="bg-white p-6">
     *         {table}
     *         {pagination}
     *       </div>
     *     </>
     *   )}
     * </TableProvider>
     * ```
     */
    readonly children?: (components: TableComponents) => ReactNode;
}
/**
 * TableProvider - Self-contained table component with search, filters, sorting, and pagination
 *
 * @example
 * ```tsx
 * <TableProvider
 *   data={activities}
 *   headers={[
 *     { key: 'title', label: 'Título', sortable: true },
 *     { key: 'status', label: 'Status', render: (value) => <Badge>{value}</Badge> }
 *   ]}
 *   loading={loading}
 *   variant="borderless"
 *   enableSearch
 *   enableFilters
 *   enableTableSort
 *   enablePagination
 *   enableRowClick
 *   initialFilters={filterConfigs}
 *   paginationConfig={{ itemLabel: 'atividades' }}
 *   onParamsChange={handleParamsChange}
 *   onRowClick={handleRowClick}
 * />
 * ```
 */
export declare function TableProvider<T extends Record<string, unknown>>({ data, headers, loading, variant, enableSearch, enableFilters, enableTableSort, sortableColumns, sortMode, defaultSort, tableId, enablePagination, enableRowClick, initialFilters, paginationConfig, searchPlaceholder, searchContainerClassName, emptyState, loadingState, noSearchResultState, rowKey, onParamsChange, onRowClick, headerContent, containerClassName, children, }: TableProviderProps<T>): import("react/jsx-runtime").JSX.Element;
export default TableProvider;
//# sourceMappingURL=TableProvider.d.ts.map