@pagamio/frontend-commons-lib 0.8.326 → 0.8.328

package/lib/pagamio-table/data-table/index.d.ts

@@ -1,3 +1,3 @@
 import type { PagamioTableProps } from './types';
-declare const PagamioTable: <T extends Record<string, any>>({ columns, data, isLoading, rowCount, sorting, pagination, filtering, search, onRowClick, rowClassName, expandable, renderDetailPanel, toolbar, toolbarMode, enableColumnResizing, enableColumnPinning, enableColumnOrdering, enableColumnFilters, enableHiding, enableRowSelection, enableRowActions, enableRowVirtualization, enableGrouping, enableEditing, enableDensityToggle, enableFullScreenToggle, enableClickToCopy, enableRowNumbers, enableMultiSort, enableStickyHeader, enableStickyFooter, editDisplayMode, onEditingRowSave, onEditingRowCancel, renderRowActions, renderRowActionMenuItems, positionActionsColumn, renderTopToolbarCustomActions, renderBottomToolbarCustomActions, layoutMode, defaultColumn, mantineTableOptions, }: PagamioTableProps<T>) => import("react/jsx-runtime").JSX.Element;
+declare const PagamioTable: <T extends Record<string, any>>({ columns, data, isLoading, isFetching, rowCount, sorting, pagination, filtering, search, onRowClick, rowClassName, expandable, renderDetailPanel, toolbar, toolbarMode, enableColumnResizing, enableColumnPinning, enableColumnOrdering, enableColumnFilters, enableHiding, enableRowSelection, enableRowActions, enableRowVirtualization, enableGrouping, enableEditing, enableDensityToggle, enableFullScreenToggle, enableClickToCopy, enableRowNumbers, enableMultiSort, enableStickyHeader, enableStickyFooter, editDisplayMode, onEditingRowSave, onEditingRowCancel, renderRowActions, renderRowActionMenuItems, positionActionsColumn, renderTopToolbarCustomActions, renderBottomToolbarCustomActions, layoutMode, defaultColumn, mantineTableOptions, }: PagamioTableProps<T>) => import("react/jsx-runtime").JSX.Element;
 export default PagamioTable;

package/lib/pagamio-table/data-table/index.js

@@ -101,7 +101,7 @@ function CustomToolbar({ filters, appliedFilters, onFilterChange, onApply, onCle
                     (typeof addButton === 'boolean' ? (_jsx(IconButton, { onClick: onAdd ?? (() => { }), icon: HiPlusSm, label: "add-new-entry", className: cn('items-center text-nowrap', isNarrow ? 'w-full' : undefined), children: addText ?? 'Add New Entry' })) : (addButton))] }) }));
 }
 // ─── PagamioTable Component ──────────────────────────────────────────
-const PagamioTable = ({ columns, data, isLoading = false, rowCount, sorting, pagination, filtering, search, onRowClick, rowClassName, expandable = false, renderDetailPanel, toolbar, toolbarMode = 'custom', enableColumnResizing, enableColumnPinning, enableColumnOrdering, enableColumnFilters, enableHiding, enableRowSelection, enableRowActions, enableRowVirtualization, enableGrouping, enableEditing, enableDensityToggle, enableFullScreenToggle, enableClickToCopy, enableRowNumbers, enableMultiSort, enableStickyHeader, enableStickyFooter, editDisplayMode, onEditingRowSave, onEditingRowCancel, renderRowActions, renderRowActionMenuItems, positionActionsColumn, renderTopToolbarCustomActions, renderBottomToolbarCustomActions, layoutMode, defaultColumn, mantineTableOptions, }) => {
+const PagamioTable = ({ columns, data, isLoading = false, isFetching = false, rowCount, sorting, pagination, filtering, search, onRowClick, rowClassName, expandable = false, renderDetailPanel, toolbar, toolbarMode = 'custom', enableColumnResizing, enableColumnPinning, enableColumnOrdering, enableColumnFilters, enableHiding, enableRowSelection, enableRowActions, enableRowVirtualization, enableGrouping, enableEditing, enableDensityToggle, enableFullScreenToggle, enableClickToCopy, enableRowNumbers, enableMultiSort, enableStickyHeader, enableStickyFooter, editDisplayMode, onEditingRowSave, onEditingRowCancel, renderRowActions, renderRowActionMenuItems, positionActionsColumn, renderTopToolbarCustomActions, renderBottomToolbarCustomActions, layoutMode, defaultColumn, mantineTableOptions, }) => {
     const [expanded, setExpanded] = useState({});
     const tableRef = useRef(null);
     // ── Internal max-height ─────────────────────────────────────────────
@@ -233,6 +233,7 @@ const PagamioTable = ({ columns, data, isLoading = false, rowCount, sorting, pag
         // State
         state: {
             isLoading,
+            showProgressBars: isFetching,
             pagination: paginationState,
             sorting: sortingState,
             expanded,

package/lib/pagamio-table/data-table/types.d.ts

@@ -103,6 +103,13 @@ export interface PagamioTableProps<T extends Record<string, any>> {
     columns: CoreTableColumnDef<T>[];
     data: T[];
     isLoading?: boolean;
+    /**
+     * Background-refetch indicator (e.g. paginating with `keepPreviousData`).
+     * When true, MRT shows a top progress bar without replacing rows with
+     * skeletons. `isLoading` should remain reserved for the first-load case
+     * where there are no rows yet.
+     */
+    isFetching?: boolean;
     rowCount?: number;
     sorting?: {
         sortConfig: SortConfig;
@@ -170,6 +177,12 @@ export interface UsePagamioTableConfig<T extends BaseEntity> {
     enabled?: boolean;
     staleTime?: number;
     gcTime?: number;
+    /**
+     * Keep the previous page's rows visible while the next page fetches
+     * (TanStack `placeholderData: keepPreviousData`). Defaults to true so
+     * pagination/sort/filter no longer flash an empty table.
+     */
+    keepPreviousData?: boolean;
     data?: T[];
     columns: CoreTableColumnDef<T>[];
     defaultFilters?: Record<string, string>;
@@ -202,6 +215,7 @@ export interface UsePagamioTableReturn<T extends BaseEntity> {
     data: T[];
     totalItems: number;
     isLoading: boolean;
+    isFetching: boolean;
     error: string | null;
     currentPage: number;
     pageSize: number;

package/lib/shared/hooks/usePagamioTable.d.ts

@@ -1,5 +1,20 @@
-import type { ResponseMapping } from '../../api';
+import type { QueryParamConfig, ResponseMapping } from '../../api';
 import type { BaseEntity, UsePagamioTableConfig, UsePagamioTableReturn } from '../../pagamio-table/data-table/types';
 export declare const springBootMapping: ResponseMapping;
 export declare const arrayResponseMapping: ResponseMapping;
-export declare const usePagamioTable: <T extends BaseEntity>({ queryKey, queryFn, enabled: queryEnabled, staleTime, gcTime, data: clientData, columns, defaultFilters, responseMapping, queryParamConfig, pagination: paginationConfig, filtering: filteringConfig, sorting: sortingConfig, toolbar, searchPlaceholder, onRowClick, rowClassName, expandable, renderDetailPanel, }: UsePagamioTableConfig<T>) => UsePagamioTableReturn<T>;
+/**
+ * Response mapping for Pagamio NestJS backends (commerce-os-core,
+ * nestjs-api-commons). Matches `PaginatedResponseDto<T>`:
+ *   { data: T[], meta: { page, limit, total, totalPages, hasNextPage, hasPreviousPage } }
+ *
+ * Pair with `pagamioQueryConfig` so request params line up too.
+ */
+export declare const pagamioMapping: ResponseMapping;
+/**
+ * Query-param config for Pagamio NestJS backends. Matches `PaginationDto`:
+ *   page (1-based), limit, search, sortBy, sortOrder ('asc'|'desc')
+ *
+ * The hook tracks `page` zero-indexed internally; we bump on the way out.
+ */
+export declare const pagamioQueryConfig: QueryParamConfig;
+export declare const usePagamioTable: <T extends BaseEntity>({ queryKey, queryFn, enabled: queryEnabled, staleTime, gcTime, keepPreviousData: keepPrev, data: clientData, columns, defaultFilters, responseMapping, queryParamConfig, pagination: paginationConfig, filtering: filteringConfig, sorting: sortingConfig, toolbar, searchPlaceholder, onRowClick, rowClassName, expandable, renderDetailPanel, }: UsePagamioTableConfig<T>) => UsePagamioTableReturn<T>;

package/lib/shared/hooks/usePagamioTable.js

@@ -10,7 +10,7 @@
  * Returns `tableProps` (spread-ready for <PagamioTable {...tableProps} />)
  * plus direct state/action access for custom logic.
  */
-import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { keepPreviousData, useQuery, useQueryClient } from '@tanstack/react-query';
 import { useCallback, useMemo, useState } from 'react';
 import { getNestedValue } from '../utils';
 // ─── Default Mappings ────────────────────────────────────────────────
@@ -30,6 +30,37 @@ export const arrayResponseMapping = {
     pageSize: '',
     defaultValues: { data: [], total: 0, page: 0, pageSize: 10 },
 };
+/**
+ * Response mapping for Pagamio NestJS backends (commerce-os-core,
+ * nestjs-api-commons). Matches `PaginatedResponseDto<T>`:
+ *   { data: T[], meta: { page, limit, total, totalPages, hasNextPage, hasPreviousPage } }
+ *
+ * Pair with `pagamioQueryConfig` so request params line up too.
+ */
+export const pagamioMapping = {
+    responseType: 'default',
+    data: 'data',
+    total: 'meta.total',
+    page: 'meta.page',
+    pageSize: 'meta.limit',
+    defaultValues: { data: [], total: 0, page: 1, pageSize: 10 },
+};
+/**
+ * Query-param config for Pagamio NestJS backends. Matches `PaginationDto`:
+ *   page (1-based), limit, search, sortBy, sortOrder ('asc'|'desc')
+ *
+ * The hook tracks `page` zero-indexed internally; we bump on the way out.
+ */
+export const pagamioQueryConfig = {
+    pagination: {
+        transform: (page, size) => ({
+            page: (page + 1).toString(),
+            limit: size.toString(),
+        }),
+    },
+    sorting: { sortByParam: 'sortBy', sortDirParam: 'sortOrder' },
+    filtering: { searchParam: 'search', filterFormat: 'flat' },
+};
 const defaultQueryConfig = {
     pagination: {
         transform: (page, size) => ({ page: page.toString(), size: size.toString() }),
@@ -123,7 +154,7 @@ function clientSort(items, sortConfig) {
     return sorted;
 }
 // ─── Hook ────────────────────────────────────────────────────────────
-export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = true, staleTime, gcTime, data: clientData, columns, defaultFilters = {}, responseMapping = springBootMapping, queryParamConfig = defaultQueryConfig, pagination: paginationConfig = { enabled: true, mode: 'client' }, filtering: filteringConfig = { enabled: true, mode: 'client', searchMode: 'server' }, sorting: sortingConfig = { enabled: true, mode: 'client' }, toolbar, searchPlaceholder, onRowClick, rowClassName, expandable, renderDetailPanel, }) => {
+export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = true, staleTime, gcTime, keepPreviousData: keepPrev = true, data: clientData, columns, defaultFilters = {}, responseMapping = springBootMapping, queryParamConfig = defaultQueryConfig, pagination: paginationConfig = { enabled: true, mode: 'client' }, filtering: filteringConfig = { enabled: true, mode: 'client', searchMode: 'server' }, sorting: sortingConfig = { enabled: true, mode: 'client' }, toolbar, searchPlaceholder, onRowClick, rowClassName, expandable, renderDetailPanel, }) => {
     // ── Local state ──────────────────────────────────────────────────
     const [currentPage, setCurrentPage] = useState(paginationConfig.pageIndex ?? 0);
     const [pageSize, setPageSize] = useState(paginationConfig.pageSize ?? 10);
@@ -148,12 +179,13 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
     ]);
     // ── TanStack Query — replaces manual fetch + AbortController ─────
     const fullQueryKey = useMemo(() => (queryKey ? [...queryKey, queryParams] : ['pagamio-table-noop']), [queryKey, queryParams]);
-    const { data: rawResponse, isLoading: queryLoading, error: queryError, } = useQuery({
+    const { data: rawResponse, isLoading: queryLoading, isFetching: queryFetching, error: queryError, } = useQuery({
         queryKey: fullQueryKey,
         queryFn: () => queryFn(queryParams),
         enabled: isServerMode && queryEnabled,
         staleTime,
         gcTime,
+        placeholderData: keepPrev ? keepPreviousData : undefined,
     });
     // ── Process server response ──────────────────────────────────────
     const { serverData, serverTotal } = useMemo(() => {
@@ -186,6 +218,7 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
         return processedData;
     }, [processedData, currentPage, pageSize, paginationConfig.mode, paginationConfig.enabled]);
     const isLoading = isServerMode ? queryLoading : false;
+    const isFetching = isServerMode ? queryFetching : false;
     const error = queryError ? queryError.message : null;
     // ── Actions ──────────────────────────────────────────────────────
     const handleFilterChange = useCallback((key, value) => {
@@ -224,6 +257,7 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
         columns,
         data: paginatedData,
         isLoading,
+        isFetching,
         rowCount: totalItems,
         ...(paginationConfig.enabled && {
             pagination: {
@@ -267,6 +301,7 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
         columns,
         paginatedData,
         isLoading,
+        isFetching,
         totalItems,
         paginationConfig.enabled,
         currentPage,
@@ -295,6 +330,7 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
         data: paginatedData,
         totalItems,
         isLoading,
+        isFetching,
         error,
         currentPage,
         pageSize,
@@ -316,6 +352,7 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
         paginatedData,
         totalItems,
         isLoading,
+        isFetching,
         error,
         currentPage,
         pageSize,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pagamio/frontend-commons-lib",
   "description": "Pagamio library for Frontend reusable components like the form engine and table container",
-  "version": "0.8.326",
+  "version": "0.8.328",
   "publishConfig": {
     "access": "public",
     "provenance": false