@snowpact/react-tanstack-query-table 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+import { Column } from '@tanstack/react-table';
+import { ColumnDef } from '@tanstack/react-table';
+import { ColumnMeta } from '@tanstack/react-table';
+import { ComponentType } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { MouseEvent as MouseEvent_2 } from 'react';
+import { OnChangeFn } from '@tanstack/react-table';
+import { PaginationState } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+import { SortingState } from '@tanstack/react-table';
+import { SVGProps } from 'react';
+import { Table } from '@tanstack/react-table';
+import { VisibilityState } from '@tanstack/react-table';
+
+/**
+ * Button variants supported by actions
+ */
+export declare type ActionButtonVariant = 'default' | 'warning' | 'danger' | 'info' | 'success';
+
+export declare function ActionCell<T, K>({ item, actions, onAction }: ActionCellProps<T, K>): JSX.Element;
+
+declare interface ActionCellProps<T, K> {
+    item: T;
+    actions: TableAction<T, K>[];
+    onAction: (action: TableAction<T, K>, item: T) => void;
+}
+
+/**
+ * Confirm content can be static or a function receiving close helper
+ */
+export declare type ActionConfirmContent = ReactNode | ((helpers: ConfirmCloseHelper) => ReactNode);
+
+/**
+ * Action Hover Registry
+ *
+ * Allows consumers to provide custom tooltip behavior for action buttons.
+ * The consumer handles all tooltip UI - SnowTable just notifies on hover/unhover.
+ */
+export declare interface ActionHoverInfo {
+    label: string;
+    element: HTMLElement;
+}
+
+export declare type BaseAction = {
+    icon: IconComponent;
+    label: string;
+    variant?: ActionButtonVariant;
+    display?: 'button' | 'dropdown';
+    hidden?: boolean;
+    disabled?: boolean;
+    showLabel?: boolean;
+    confirm?: {
+        title: string;
+        content: ActionConfirmContent;
+        subtitle?: string;
+        confirmText?: string;
+        cancelText?: string;
+        hideButtons?: boolean;
+    };
+};
+
+/**
+ * Base props shared between SnowClientTable and SnowServerTable
+ */
+export declare interface BaseSnowTableProps<T extends Record<string, unknown>, K> extends DataTableUIOptions<T> {
+    queryKey: string[];
+    columnConfig: SnowColumnConfig<T>[];
+    actions?: TableAction<T, K>[];
+    filters?: FilterConfig<T>[];
+    prefilters?: PreFilter[];
+    defaultSortBy?: string;
+    defaultSortOrder?: 'asc' | 'desc';
+    defaultPageSize?: number;
+    /**
+     * Persist table state (prefilter, pagination, search, filters, sorting) in URL query params.
+     */
+    persistState?: boolean;
+}
+
+/**
+ * Styles Registry
+ *
+ * ONLY visual styles are customizable (colors, borders, shadows, rounded).
+ * Structural styles (layout, sizing, positioning) are fixed in the components.
+ */
+declare interface ButtonStyles {
+    visual: string;
+    hover: string;
+    disabled: string;
+    danger: string;
+    warning: string;
+    info: string;
+    success: string;
+}
+
+export declare type ClickAction<T> = BaseAction & {
+    type: 'click';
+    onClick: (item: T) => void;
+};
+
+export declare function ColumnConfiguration<T extends object>({ table }: ColumnConfigurationProps<T>): JSX.Element;
+
+export declare type ColumnConfigurationProps<T extends object> = {
+    table: Table<T>;
+};
+
+export declare interface ConfirmCloseHelper {
+    close: () => void;
+}
+
+export declare type ConfirmContent = ReactNode | ((helpers: ConfirmCloseHelper) => ReactNode);
+
+declare interface ConfirmOptions {
+    title: string;
+    subtitle?: string;
+    content: ConfirmContent;
+    confirmText?: string;
+    cancelText?: string;
+    hideButtons?: boolean;
+}
+
+export declare function DataTable<Data extends object>({ data, columns, isLoading, isFetching, mode, pagination: externalPagination, onPaginationChange: externalOnPaginationChange, totalCount: externalTotalCount, globalFilter: externalGlobalFilter, onGlobalFilterChange: externalOnGlobalFilterChange, enableGlobalSearch, filters, columnFilters: externalColumnFilters, onColumnFiltersChange: externalOnColumnFiltersChange, prefilters, activePrefilter, onPrefilterChange, sorting: externalSorting, onSortingChange: externalOnSortingChange, enableSorting, columnVisibility: externalColumnVisibility, onColumnVisibilityChange: externalOnColumnVisibilityChange, enableColumnConfiguration, onRowClick, activeRowId, displayTotalNumber, enableElementLabel, enablePagination, enableResponsive, texts, onResetFilters, enableResetFilters, }: DataTableProps<Data>): JSX.Element;
+
+export declare type DataTableProps<T extends object> = {
+    data: T[];
+    columns: ColumnDef<T, any>[];
+    isLoading?: boolean;
+    isFetching?: boolean;
+    mode?: 'client' | 'server';
+    pagination?: PaginationState;
+    onPaginationChange?: OnChangeFn<PaginationState>;
+    totalCount?: number;
+    globalFilter?: string;
+    onGlobalFilterChange?: (value: string) => void;
+    enableGlobalSearch?: boolean;
+    filters?: FilterConfig<T>[];
+    columnFilters?: Record<string, string[]>;
+    onColumnFiltersChange?: (filters: Record<string, string[]>) => void;
+    prefilters?: PreFilter[];
+    activePrefilter?: string;
+    onPrefilterChange?: (key: string) => void;
+    sorting?: SortingState;
+    onSortingChange?: OnChangeFn<SortingState>;
+    enableSorting?: boolean;
+    columnVisibility?: VisibilityState;
+    onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
+    enableColumnConfiguration?: boolean;
+    onRowClick?: (data: T) => void;
+    activeRowId?: string | number;
+    displayTotalNumber?: boolean;
+    enableElementLabel?: boolean;
+    enablePagination?: boolean;
+    enableResponsive?: boolean;
+    texts?: {
+        searchPlaceholder?: string;
+        emptyTitle?: string;
+    };
+    onResetFilters?: () => void;
+    enableResetFilters?: boolean;
+};
+
+declare interface DataTableStyles {
+    container: string;
+    header: string;
+    headerCell: string;
+    row: string;
+    rowHover: string;
+    rowAlternate: string;
+    rowActive: string;
+    divider: string;
+    empty: string;
+    loadingOverlay: string;
+}
+
+/**
+ * UI options that can be passed through to the underlying DataTable
+ */
+export declare interface DataTableUIOptions<T extends object> {
+    onRowClick?: (data: T) => void;
+    activeRowId?: string | number;
+    displayTotalNumber?: boolean;
+    enableElementLabel?: boolean;
+    enableGlobalSearch?: boolean;
+    enableSorting?: boolean;
+    enableColumnConfiguration?: boolean;
+    enablePagination?: boolean;
+    enableResetFilters?: boolean;
+    texts?: {
+        searchPlaceholder?: string;
+        emptyTitle?: string;
+    };
+}
+
+declare type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? Partial<T[P]> : T[P];
+};
+
+export declare const DEFAULT_PAGE_SIZES: number[];
+
+declare interface DropdownStyles {
+    content: string;
+    item: string;
+    checkboxItem: string;
+    separator: string;
+}
+
+export declare type EndpointAction<T, K> = BaseAction & {
+    type: 'endpoint';
+    endpoint: (item: T) => Promise<K>;
+    onSuccess?: (data: K, variables: T, context: unknown) => void;
+    onError?: (error: ErrorResponse, variables: T, context: unknown) => void;
+};
+
+export declare type ErrorResponse = {
+    message: string;
+    status: number;
+};
+
+export declare type FilterConfig<T extends object> = {
+    key: keyof T;
+    label: string;
+    options: FilterOption[];
+    multipleSelection?: boolean;
+};
+
+/**
+ * Single filter dropdown with multi-select support
+ */
+export declare type FilterOption = {
+    label: string;
+    value: string;
+};
+
+/**
+ * Icon component type - compatible with IconComponent
+ * Users can use lucide-react icons or any SVG component with this signature
+ */
+export declare type IconComponent = ComponentType<SVGProps<SVGSVGElement>>;
+
+export declare const isSnowTableSetup: () => boolean;
+
+export declare type LinkAction<T> = BaseAction & {
+    type: 'link';
+    href: (item: T) => string;
+    external?: boolean;
+};
+
+declare interface LinkProps {
+    to: string;
+    children: ReactNode;
+    className?: string;
+    target?: string;
+    rel?: string;
+    'aria-disabled'?: boolean;
+    onMouseEnter?: (e: MouseEvent_2<HTMLAnchorElement>) => void;
+    onMouseLeave?: () => void;
+}
+
+export declare function PageSizeSelector<Data extends object>({ table, paginationSizes, enableElementLabel, }: PageSizeSelectorProps<Data>): JSX.Element;
+
+export declare type PageSizeSelectorProps<Data extends object> = {
+    table: Table<Data>;
+    paginationSizes?: number[];
+    enableElementLabel?: boolean;
+};
+
+export declare function Pagination<Data extends object>({ table, isLoading }: PaginationProps<Data>): JSX.Element;
+
+export declare type PaginationProps<Data extends object> = {
+    table: Table<Data>;
+    isLoading?: boolean;
+};
+
+/**
+ * Prefilter tabs component (tabs or select based on viewport/count)
+ */
+export declare type PreFilter = {
+    id: string;
+    label: string;
+};
+
+export declare function PrefilterTabs({ prefilters, activePrefilter, onPrefilterChange }: PrefilterTabsProps): JSX.Element;
+
+export declare interface PrefilterTabsProps {
+    prefilters: PreFilter[];
+    activePrefilter: string;
+    onPrefilterChange: (id: string) => void;
+}
+
+export declare function SearchBar({ value, onDebouncedChange, placeholder }: SearchBarProps): JSX.Element;
+
+/**
+ * Search bar component with debounce
+ */
+export declare interface SearchBarProps {
+    /** Current value (controlled from parent) */
+    value?: string;
+    /** Callback with debounced value */
+    onDebouncedChange?: (value: string) => void;
+    /** Placeholder text */
+    placeholder?: string;
+}
+
+declare interface SelectStyles {
+    trigger: string;
+    content: string;
+    item: string;
+    itemSelected: string;
+}
+
+/**
+ * Parameters sent to the server for pagination, search, and filtering
+ */
+export declare interface ServerFetchParams {
+    limit: number;
+    offset: number;
+    search?: string;
+    prefilter?: string;
+    filters?: Record<string, string[]>;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+}
+
+/**
+ * Response structure for server-side paginated endpoints
+ */
+export declare interface ServerPaginatedResponse<T> {
+    items: T[];
+    totalItemCount: number;
+}
+
+export declare const setupSnowTable: (options: SetupSnowTableOptions) => void;
+
+export declare interface SetupSnowTableOptions {
+    useTranslation: () => {
+        t: (key: string, options?: Record<string, unknown>) => string;
+    };
+    LinkComponent: ComponentType<LinkProps>;
+    useConfirm: () => UseConfirmReturn;
+    styles?: DeepPartial<SnowTableStyles>;
+    onActionHover?: (info: ActionHoverInfo) => void;
+    onActionUnhover?: () => void;
+}
+
+export declare function SingleFilterDropdown<T extends object>({ filter, selectedValues, onFilterChange, }: SingleFilterDropdownProps<T>): JSX.Element | null;
+
+export declare interface SingleFilterDropdownProps<T extends object> {
+    filter: FilterConfig<T>;
+    selectedValues?: string[];
+    onFilterChange: (key: keyof T, selectedValues: string[]) => void;
+}
+
+export declare const SnowClientTable: <T extends Record<string, unknown>, K>({ queryKey, columnConfig, actions, filters, prefilters, prefilterFn, defaultSortBy, defaultSortOrder, defaultPageSize, persistState, fetchAllItemsEndpoint, ...restProps }: SnowClientTableProps<T, K>) => JSX.Element;
+
+/**
+ * Props for SnowClientTable component (client-side filtering/sorting)
+ */
+export declare interface SnowClientTableProps<T extends Record<string, unknown>, K> extends BaseSnowTableProps<T, K> {
+    fetchAllItemsEndpoint: () => Promise<T[]>;
+    /** Optional function to filter items based on active prefilter */
+    prefilterFn?: (item: T, prefilterId: string) => boolean;
+}
+
+export declare type SnowColumnConfig<T extends object> = {
+    key: keyof T | '_extra' | '_extra_' | `_extra_${string}`;
+    label?: string;
+    hidden?: boolean;
+    sortable?: boolean;
+    render?: (item: T) => ReactNode;
+    searchableValue?: (item: T) => string;
+    meta?: ColumnMeta<T, unknown>;
+};
+
+export declare const SnowServerTable: <T extends Record<string, unknown>, K>({ queryKey, columnConfig, actions, filters, prefilters, defaultSortBy, defaultSortOrder, defaultPageSize, persistState, fetchServerEndpoint, ...restProps }: SnowServerTableProps<T, K>) => JSX.Element;
+
+/**
+ * Props for SnowServerTable component (server-side pagination/filtering/sorting)
+ */
+export declare interface SnowServerTableProps<T extends Record<string, unknown>, K> extends BaseSnowTableProps<T, K> {
+    fetchServerEndpoint: (params: ServerFetchParams) => Promise<ServerPaginatedResponse<T>>;
+    filters?: FilterConfig<Record<string, unknown>>[];
+}
+
+declare interface SnowTableStyles {
+    state: StateStyles;
+    button: ButtonStyles;
+    input: string;
+    skeleton: string;
+    dropdown: DropdownStyles;
+    select: SelectStyles;
+    tabs: TabsStyles;
+    table: DataTableStyles;
+}
+
+export declare function SortButton({ column }: SortButtonProps): JSX.Element | null;
+
+export declare interface SortButtonProps {
+    column: Column<any, any>;
+}
+
+declare interface StateStyles {
+    active: string;
+    activeText: string;
+    focus: string;
+}
+
+export declare type TableAction<T, K> = EndpointAction<T, K> | ClickAction<T> | LinkAction<T> | ((item: T) => EndpointAction<T, K>) | ((item: T) => ClickAction<T>) | ((item: T) => LinkAction<T>);
+
+declare interface TabsStyles {
+    list: string;
+    trigger: string;
+    triggerActive: string;
+}
+
+declare interface UseConfirmReturn {
+    confirm: (options: ConfirmOptions) => Promise<boolean>;
+}
+
+/**
+ * Shared hook for building columns and handling actions in SnowClientTable and SnowServerTable.
+ *
+ * Extracts the common logic for:
+ * - Transforming SnowColumnConfig into TanStack Table ColumnDef
+ * - Adding action column with ActionCell
+ * - Handling action execution with confirmation dialogs and mutations
+ */
+export declare const useSnowColumns: <T extends Record<string, unknown>, K>({ columnConfig, actions, filters, mode, }: UseSnowColumnsOptions<T, K>) => UseSnowColumnsReturn<T, K>;
+
+export declare interface UseSnowColumnsOptions<T extends Record<string, unknown>, K> {
+    columnConfig: SnowColumnConfig<T>[];
+    actions?: TableAction<T, K>[];
+    filters?: FilterConfig<T>[];
+    /**
+     * Mode determines how global filter behaves:
+     * - 'client': enableGlobalFilter based on searchableValue
+     * - 'server': enableGlobalFilter always false (server handles search)
+     */
+    mode: 'client' | 'server';
+}
+
+export declare interface UseSnowColumnsReturn<T extends Record<string, unknown>, K> {
+    columns: ColumnDef<T, unknown>[];
+    handleAction: (action: TableAction<T, K>, item: T) => Promise<void>;
+}
+
+export declare const useTableStatePersist: ({ enabled, defaultPrefilter, defaultPageSize, defaultSortBy, defaultSortOrder, }: UseTableStatePersistOptions) => {
+    activePrefilter: string | undefined;
+    setActivePrefilter: (value: string | undefined) => void;
+    globalFilter: string;
+    setGlobalFilter: (value: string) => void;
+    pagination: PaginationState;
+    setPagination: (value: PaginationState | ((prev: PaginationState) => PaginationState)) => void;
+    columnFilters: Record<string, string[]>;
+    setColumnFilters: (value: Record<string, string[]>) => void;
+    sorting: SortingState;
+    setSorting: (value: SortingState | ((prev: SortingState) => SortingState)) => void;
+    resetToDefaults: () => void;
+    hasActiveFilters: boolean;
+};
+
+declare interface UseTableStatePersistOptions {
+    enabled: boolean;
+    defaultPrefilter?: string;
+    defaultPageSize: number;
+    defaultSortBy?: string;
+    defaultSortOrder?: 'asc' | 'desc';
+}
+
+export { }