@pagamio/frontend-commons-lib 0.8.350 → 0.8.352

package/lib/components/ui/PagamioSearchableCombobox.d.ts

@@ -1,5 +1,19 @@
 import * as React from 'react';
 import type { UsePagamioComboboxReturn } from '../../shared/hooks/usePagamioCombobox';
+/**
+ * Optional in-popover action — replaces the old "+ Create New X" sentinel
+ * option pattern that some `<Select>` callers used to inline a "create a
+ * new item" affordance. Rendered as a button row pinned to the top of the
+ * popover, above the options list. Clicking it closes the popover and
+ * fires `onClick` (typically opening a quick-create modal). The handler
+ * is responsible for the side effect; the combobox does NOT update its
+ * `value` automatically.
+ */
+export interface SearchableComboboxActionButton {
+    /** Label shown on the action button (e.g. "+ New category"). */
+    label: React.ReactNode;
+    onClick: () => void;
+}
 export interface PagamioSearchableComboboxProps<T extends {
     id: string;
 }> {
@@ -8,6 +22,12 @@ export interface PagamioSearchableComboboxProps<T extends {
     /** Controlled selected id, or null when nothing is selected. */
     value: string | null;
     onChange: (id: string | null) => void;
+    /**
+     * Optional action button rendered at the top of the popover. Used to
+     * surface a "+ Create new …" affordance inside the picker itself,
+     * matching where the old static-select sentinel option lived.
+     */
+    actionButton?: SearchableComboboxActionButton;
     /**
      * Optional pre-resolved selected option. When set, the trigger shows its
      * label without needing to fetch via `restoreIds`. If both this and the
@@ -39,4 +59,4 @@ export interface PagamioSearchableComboboxProps<T extends {
 }
 export declare function PagamioSearchableCombobox<T extends {
     id: string;
-}>({ combobox, value, onChange, selectedOption, placeholder, searchPlaceholder, emptyMessage, cappedMessage, loadingMessage, disabled, required, name, getLabel, renderOption, renderSelected, className, triggerClassName, contentClassName, }: PagamioSearchableComboboxProps<T>): import("react/jsx-runtime").JSX.Element;
+}>({ combobox, value, onChange, actionButton, selectedOption, placeholder, searchPlaceholder, emptyMessage, cappedMessage, loadingMessage, disabled, required, name, getLabel, renderOption, renderSelected, className, triggerClassName, contentClassName, }: PagamioSearchableComboboxProps<T>): import("react/jsx-runtime").JSX.Element;

package/lib/components/ui/PagamioSearchableCombobox.js

@@ -19,7 +19,7 @@ function defaultGetLabel(option) {
     const o = option;
     return o.name ?? option.id;
 }
-export function PagamioSearchableCombobox({ combobox, value, onChange, selectedOption, placeholder = 'Select…', searchPlaceholder = 'Search...', emptyMessage = 'No options found', cappedMessage = 'Showing top results — refine your search.', loadingMessage = 'Loading…', disabled, required, name, getLabel = defaultGetLabel, renderOption, renderSelected, className, triggerClassName, contentClassName, }) {
+export function PagamioSearchableCombobox({ combobox, value, onChange, actionButton, selectedOption, placeholder = 'Select…', searchPlaceholder = 'Search...', emptyMessage = 'No options found', cappedMessage = 'Showing top results — refine your search.', loadingMessage = 'Loading…', disabled, required, name, getLabel = defaultGetLabel, renderOption, renderSelected, className, triggerClassName, contentClassName, }) {
     const [open, setOpen] = React.useState(false);
     const inputRef = React.useRef(null);
     // Focus the search input when the popover opens — matches the Select's
@@ -52,11 +52,18 @@ export function PagamioSearchableCombobox({ combobox, value, onChange, selectedO
                                         : placeholder }), _jsx(ChevronDownIcon, { className: "ml-2 h-4 w-4 opacity-50 shrink-0" })] }) }), _jsxs(PopoverContent, { align: "start", sideOffset: 4, 
                         // Mirrors SelectContent: same shadow + animation classes, popover
                         // background, popover-foreground text. Width matches trigger.
-                        className: cn('p-0 w-[var(--radix-popover-trigger-width)] min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md', contentClassName), children: [_jsx("div", { className: "p-2 border-b border-border", children: _jsx("input", { ref: inputRef, type: "text", placeholder: searchPlaceholder, value: combobox.search, onChange: (e) => combobox.setSearch(e.target.value), onKeyDown: (e) => e.stopPropagation(), className: "w-full px-2 py-1 text-sm border border-input rounded bg-background text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring" }) }), _jsx("div", { className: "p-1 max-h-[200px] overflow-y-auto", children: combobox.isLoading && combobox.options.length === 0 ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-muted-foreground", children: loadingMessage })) : combobox.error ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-destructive", children: combobox.error.message || 'Failed to load options.' })) : combobox.options.length === 0 ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-muted-foreground", children: emptyMessage })) : (_jsxs(_Fragment, { children: [combobox.options.map((option) => {
-                                            const isSelected = option.id === value;
-                                            return (_jsx("button", { type: "button", role: "option", "aria-selected": isSelected, onClick: () => handleSelect(option.id), className: cn(
-                                                // Mirrors SelectItem styling: padding, hover via
-                                                // focus:bg-muted, selected via bg-accent.
-                                                'relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm outline-none text-left', 'hover:bg-muted focus:bg-muted focus:text-foreground', isSelected && 'bg-accent text-foreground'), children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "line-clamp-1", children: getLabel(option) }), isSelected ? (_jsx("span", { className: "absolute right-2 flex h-3.5 w-3.5 items-center justify-center", children: _jsx(CheckIcon, { className: "h-4 w-4" }) })) : null] })) }, option.id));
-                                        }), combobox.isCapped ? (_jsx("div", { className: "mt-1 border-t px-2 py-1.5 text-xs text-muted-foreground", children: cappedMessage })) : null] })) })] })] }), name ? _jsx("input", { type: "hidden", name: name, value: value ?? '' }) : null] }));
+                        className: cn('p-0 w-[var(--radix-popover-trigger-width)] min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md', contentClassName), children: [_jsx("div", { className: "p-2 border-b border-border", children: _jsx("input", { ref: inputRef, type: "text", placeholder: searchPlaceholder, value: combobox.search, onChange: (e) => combobox.setSearch(e.target.value), onKeyDown: (e) => e.stopPropagation(), className: "w-full px-2 py-1 text-sm border border-input rounded bg-background text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring" }) }), _jsxs("div", { className: "p-1 max-h-[200px] overflow-y-auto", children: [actionButton ? (_jsx("button", { type: "button", onClick: () => {
+                                            setOpen(false);
+                                            actionButton.onClick();
+                                        }, className: cn(
+                                        // Same row geometry as an option row so the picker reads
+                                        // as one consistent list. Primary-coloured label keeps it
+                                        // visually distinct from real options.
+                                        'relative flex w-full cursor-pointer select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm outline-none text-left font-medium text-primary', 'hover:bg-muted focus:bg-muted'), children: actionButton.label }, "__action__")) : null, combobox.isLoading && combobox.options.length === 0 ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-muted-foreground", children: loadingMessage })) : combobox.error ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-destructive", children: combobox.error.message || 'Failed to load options.' })) : combobox.options.length === 0 ? (_jsx("div", { className: "px-2 py-1.5 text-sm text-muted-foreground", children: emptyMessage })) : (_jsxs(_Fragment, { children: [combobox.options.map((option) => {
+                                                const isSelected = option.id === value;
+                                                return (_jsx("button", { type: "button", role: "option", "aria-selected": isSelected, onClick: () => handleSelect(option.id), className: cn(
+                                                    // Mirrors SelectItem styling: padding, hover via
+                                                    // focus:bg-muted, selected via bg-accent.
+                                                    'relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-2 pr-8 text-sm outline-none text-left', 'hover:bg-muted focus:bg-muted focus:text-foreground', isSelected && 'bg-accent text-foreground'), children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "line-clamp-1", children: getLabel(option) }), isSelected ? (_jsx("span", { className: "absolute right-2 flex h-3.5 w-3.5 items-center justify-center", children: _jsx(CheckIcon, { className: "h-4 w-4" }) })) : null] })) }, option.id));
+                                            }), combobox.isCapped ? (_jsx("div", { className: "mt-1 border-t px-2 py-1.5 text-xs text-muted-foreground", children: cappedMessage })) : null] }))] })] })] }), name ? _jsx("input", { type: "hidden", name: name, value: value ?? '' }) : null] }));
 }

package/lib/form-engine/components/inputs/searchable-combobox/SearchableComboboxInput.js

@@ -34,7 +34,7 @@ const SearchableComboboxInput = forwardRef(({ field, value, onChange }, ref) =>
         debounceMs: source.debounceMs,
         restoreIds,
     });
-    return (_jsxs("div", { ref: ref, children: [field.label && (_jsx("label", { htmlFor: field.name, className: "block text-sm font-medium text-foreground mb-1", children: field.label })), _jsx(PagamioSearchableCombobox, { combobox: combobox, value: value ?? null, onChange: (id) => onChange?.(id), placeholder: field.placeholder, disabled: field.disabled, required: field.validation?.required ? true : undefined, name: field.name, getLabel: source.getLabel })] }));
+    return (_jsxs("div", { ref: ref, children: [field.label && (_jsx("label", { htmlFor: field.name, className: "block text-sm font-medium text-foreground mb-1", children: field.label })), _jsx(PagamioSearchableCombobox, { combobox: combobox, value: value ?? null, onChange: (id) => onChange?.(id), actionButton: field.actionButton, placeholder: field.placeholder, disabled: field.disabled, required: field.validation?.required ? true : undefined, name: field.name, getLabel: source.getLabel })] }));
 });
 SearchableComboboxInput.displayName = 'SearchableComboboxInput';
 export default SearchableComboboxInput;

package/lib/form-engine/types/index.d.ts

@@ -215,6 +215,17 @@ export interface Field {
      * Tells the form engine how to fetch lookup results.
      */
     source?: ComboboxSourceSpec;
+    /**
+     * Optional in-picker action for `searchable-combobox`. Renders as the
+     * first row of the popover (above the options) — the same place a
+     * "+ Create new …" sentinel option used to live in the old static
+     * `<Select>`. Clicking it closes the popover and fires `onClick`; the
+     * handler owns the side effect (e.g. opens a quick-create modal).
+     */
+    actionButton?: {
+        label: string;
+        onClick: () => void;
+    };
 }
 export interface DependentFieldUpdate {
     field: string;

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

@@ -1,4 +1,3 @@
-import 'jspdf-autotable';
 import { type MRT_ColumnDef } from 'mantine-react-table';
 interface ThemeColors {
     primary: {
@@ -36,9 +35,9 @@ interface CsvExportOptions {
     delimiter?: string;
     filename?: string;
 }
-export declare const exportToCsv: <T extends Record<string, any>>(data: T[], columns: MRT_ColumnDef<T>[], options?: CsvExportOptions) => void;
-export declare const exportToXlsx: <T extends Record<string, any>>(data: T[], columns: MRT_ColumnDef<T>[], options?: XlsxExportOptions) => void;
-export declare const exportToPdf: <T extends Record<string, any>>(data: T[], columns: MRT_ColumnDef<T>[], options?: PdfExportOptions) => Promise<void>;
+export declare const exportToCsv: <T extends Record<string, any>>(data: T[], allColumns: MRT_ColumnDef<T>[], options?: CsvExportOptions) => void;
+export declare const exportToXlsx: <T extends Record<string, any>>(data: T[], allColumns: MRT_ColumnDef<T>[], options?: XlsxExportOptions) => void;
+export declare const exportToPdf: <T extends Record<string, any>>(data: T[], allColumns: MRT_ColumnDef<T>[], options?: PdfExportOptions) => Promise<void>;
 /**
  * Sends an export file to the user via email using multipart/form-data
  * Automatically includes Authorization header from cookies if available

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

@@ -1,7 +1,10 @@
-import jsPDF from 'jspdf';
-import 'jspdf-autotable';
+import { jsPDF } from 'jspdf';
+import { applyPlugin } from 'jspdf-autotable';
 import Papa from 'papaparse';
 import * as XLSX from 'xlsx';
+// jspdf-autotable v5 no longer auto-attaches `autoTable` to jsPDF instances.
+// applyPlugin restores the `doc.autoTable(...)` call style used below.
+applyPlugin(jsPDF);
 // Helper function to convert RGB string to RGB values
 const parseRgbString = (rgbString) => {
     // Handle rgb(r, g, b) format
@@ -42,6 +45,50 @@ const loadImageAsBase64 = async (url) => {
         return null;
     }
 };
+/**
+ * jsPDF's addImage only embeds raster formats (PNG/JPEG/WEBP), not SVG. Many
+ * logos are SVGs, so rasterise any SVG data URL onto a canvas and return a PNG
+ * data URL. Raster inputs pass through unchanged.
+ */
+const ensureRasterImage = async (dataUrl, 
+// High render width so SVG logos stay crisp once scaled down into the PDF
+// (the logo prints at ~30mm; rendering at 600px gives ample DPI headroom).
+targetWidthPx = 600) => {
+    const isSvg = dataUrl.startsWith('data:image/svg');
+    if (!isSvg) {
+        const match = /^data:image\/(png|jpeg|jpg|webp)/i.exec(dataUrl);
+        if (!match)
+            return null;
+        const fmt = match[1].toUpperCase();
+        return {
+            dataUrl,
+            format: fmt === 'JPG' ? 'JPEG' : fmt,
+        };
+    }
+    return new Promise((resolve) => {
+        const img = new Image();
+        img.onload = () => {
+            // SVGs may report 0 intrinsic size; fall back to a 2:1 logo ratio so the
+            // canvas is never degenerate (which would yield a blank/blurry raster).
+            const ratio = img.naturalWidth > 0 ? img.naturalHeight / img.naturalWidth : 0.5;
+            const canvas = document.createElement('canvas');
+            canvas.width = targetWidthPx;
+            canvas.height = Math.max(1, Math.round(targetWidthPx * ratio));
+            const ctx = canvas.getContext('2d');
+            if (!ctx)
+                return resolve(null);
+            ctx.imageSmoothingEnabled = true;
+            ctx.imageSmoothingQuality = 'high';
+            ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+            resolve({ dataUrl: canvas.toDataURL('image/png'), format: 'PNG' });
+        };
+        img.onerror = () => resolve(null);
+        // Force the SVG to rasterise at the target size rather than its (often
+        // missing) intrinsic size.
+        img.width = targetWidthPx;
+        img.src = dataUrl;
+    });
+};
 // Helper functions for formatting different data types
 const formatStatusObject = (value) => {
     if ('label' in value && typeof value.label === 'string') {
@@ -224,8 +271,10 @@ const formatCellContentForExcel = (value, columnKey) => {
     return String(value);
 };
 // CSV Export
-export const exportToCsv = (data, columns, options = {}) => {
+export const exportToCsv = (data, allColumns, options = {}) => {
     const { title = 'Data Export', includeTimestamp = true, includeHeaders = true, delimiter = ',', filename } = options;
+    // Drop display-only columns (no accessorKey) so keys/headers stay aligned.
+    const columns = allColumns.filter((col) => Boolean(col.accessorKey));
     const columnKeys = columns.map((col) => col.accessorKey);
     const headers = columns.map((col) => formatHeaderText(col.header || ''));
     // Prepare data with proper formatting
@@ -471,7 +520,9 @@ const addMergedCells = (worksheet, title, hasSubtitle, headers) => {
     }
 };
 // XLSX Export
-export const exportToXlsx = (data, columns, options = {}) => {
+export const exportToXlsx = (data, allColumns, options = {}) => {
+    // Drop display-only columns (no accessorKey) so keys/headers stay aligned.
+    const columns = allColumns.filter((col) => Boolean(col.accessorKey));
     const { title = 'Data Export', subtitle, colors, sheetName = 'Data', includeTimestamp = true, autoFitColumns = true, } = options;
     const columnKeys = columns.map((col) => col.accessorKey);
     const headers = columns.map((col) => formatHeaderText(col.header || ''));
@@ -509,6 +560,11 @@ export const exportToXlsx = (data, columns, options = {}) => {
 };
 // Helper function to check if a column likely contains images
 const isImageColumn = (columnKey, data) => {
+    // Display-only columns (e.g. an "actions" column) have no accessorKey, so
+    // columnKey can be undefined here. They hold no exportable data.
+    if (!columnKey) {
+        return false;
+    }
     const imageKeywords = ['image', 'photo', 'picture', 'avatar', 'logo'];
     const keyLower = columnKey.toLowerCase();
     // Check if column key suggests images
@@ -579,7 +635,11 @@ const prepareTableDataForPdf = async (data, columns, doc) => {
     return { tableData, imageInfo };
 };
 // PDF Export
-export const exportToPdf = async (data, columns, options = {}) => {
+export const exportToPdf = async (data, allColumns, options = {}) => {
+    // Only data-bound columns are exportable; display-only columns (e.g. an
+    // "actions" column) have no accessorKey and would otherwise produce
+    // undefined keys/headers that crash downstream formatting.
+    const columns = allColumns.filter((col) => Boolean(col.accessorKey));
     const { title = 'Data Export', subtitle = `Generated on ${new Date().toLocaleDateString('en-US', {
         year: 'numeric',
         month: 'long',
@@ -606,10 +666,11 @@ export const exportToPdf = async (data, columns, options = {}) => {
     if (logo?.url) {
         try {
             const logoBase64 = await loadImageAsBase64(logo.url);
-            if (logoBase64) {
+            const raster = logoBase64 ? await ensureRasterImage(logoBase64) : null;
+            if (raster) {
                 const logoWidth = logo.width || 30;
                 const logoHeight = logo.height || 15;
-                doc.addImage(logoBase64, 'PNG', margin, currentY, logoWidth, logoHeight);
+                doc.addImage(raster.dataUrl, raster.format, margin, currentY, logoWidth, logoHeight);
                 currentY += logoHeight + 5;
             }
         }
@@ -638,7 +699,6 @@ export const exportToPdf = async (data, columns, options = {}) => {
     const columnHeaders = columns.map((col) => formatHeaderText(col.header || String(col.accessorKey)));
     // Format table data with enhanced handling for images, status, etc.
     const { tableData, imageInfo } = await prepareTableDataForPdf(data, columns, doc);
-    console.log(`PDF export: Processing ${tableData.length} rows with ${imageInfo.size} images`);
     // Calculate optimal column widths
     const availableWidth = pageWidth - 2 * margin;
     const numColumns = columnHeaders.length;

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

@@ -20,11 +20,23 @@ export const createPdfExportOptions = (config, title) => {
             primary: config.theme.colors.primary,
             core: config.theme.colors.core,
         },
-        logo: {
-            url: config.branding.navbarLogo?.path || config.branding.logo.path,
-            width: config.branding.navbarLogo?.width || config.branding.logo.width,
-            height: config.branding.navbarLogo?.height || config.branding.logo.height,
-        },
+        logo: scalePdfLogo(config.branding.navbarLogo?.path || config.branding.logo.path, config.branding.navbarLogo?.width || config.branding.logo.width, config.branding.navbarLogo?.height || config.branding.logo.height),
+    };
+};
+/**
+ * Branding logo dimensions in `config` are CSS pixels (sized for the navbar).
+ * `exportToPdf` interprets logo width/height as millimetres, so passing the raw
+ * pixel values renders a giant logo that fills the page. Scale to a fixed print
+ * width (mm) while preserving the source aspect ratio.
+ */
+const PDF_LOGO_WIDTH_MM = 32;
+const PDF_LOGO_FALLBACK_HEIGHT_MM = 12;
+const scalePdfLogo = (url, pxWidth, pxHeight) => {
+    const aspect = pxWidth && pxHeight && pxWidth > 0 ? pxHeight / pxWidth : undefined;
+    return {
+        url,
+        width: PDF_LOGO_WIDTH_MM,
+        height: aspect ? Math.round(PDF_LOGO_WIDTH_MM * aspect) : PDF_LOGO_FALLBACK_HEIGHT_MM,
     };
 };
 /**

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

@@ -3,3 +3,4 @@ export * from './useMediaQueries';
 export * from './useSessionTimer';
 export * from './usePagamioTable';
 export * from './usePagamioCombobox';
+export * from './useInfiniteCursor';

package/lib/shared/hooks/index.js

@@ -3,3 +3,4 @@ export * from './useMediaQueries';
 export * from './useSessionTimer';
 export * from './usePagamioTable';
 export * from './usePagamioCombobox';
+export * from './useInfiniteCursor';

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

@@ -0,0 +1,104 @@
+/**
+ * useInfiniteCursor — TanStack `useInfiniteQuery` wrapper for cursor-paginated
+ * Pagamio endpoints.
+ *
+ * Matches the backend cursor contract from `pagamio-nestjs-api-commons`:
+ *   `GET /<resource>/feed` → CursorPaginatedResponseDto<T> =
+ *     { data: T[], meta: { nextCursor, previousCursor, hasNextPage,
+ *                          hasPreviousPage, count, total? } }
+ *
+ * The hook treats `nextCursor` as an opaque base64 string — never parse or
+ * construct cursors on the client. If the backend changes its cursor encoding,
+ * the frontend doesn't need to know.
+ *
+ * For tables and any page-numbered UI, use `usePagamioTable` (offset paging)
+ * instead. Cursor pagination is for infinite-scroll surfaces (storefront,
+ * mobile feeds) where "Page X of Y" UX isn't shown.
+ *
+ * SRP: Wires `useInfiniteQuery` to the cursor contract. Callers own:
+ *   - flattening `data.pages` into a single list
+ *   - intersection-observer / "load more" wiring
+ *   - reading `data.pages[0]?.meta.total` for header counts (only present
+ *     when the caller passed `withTotal=true` on the first page).
+ */
+import { type QueryKey, type UseInfiniteQueryResult } from '@tanstack/react-query';
+/**
+ * Wire shape for one page of a cursor-paginated Pagamio response.
+ *
+ * Mirrors `CursorPaginatedResponseDto<T>` from `@pagamio/nestjs-api-commons`.
+ * `total` is optional and only set when the caller passes `withTotal=true`
+ * (conventionally first page only — see backend `.agent/conventions/pagination.md`).
+ */
+export type CursorResponse<T> = {
+    data: T[];
+    meta: {
+        nextCursor: string | null;
+        previousCursor: string | null;
+        hasNextPage: boolean;
+        hasPreviousPage: boolean;
+        count: number;
+        total?: number;
+    };
+};
+/**
+ * Documentation-as-code marker for the cursor meta shape. Mirrors the role
+ * of `pagamioMapping` for offset pagination — gives consumers a single named
+ * export to reference. Not consumed by `useInfiniteCursor` itself (TanStack
+ * handles the wiring); useful for grep / IDE jump-to-definition.
+ */
+export declare const cursorMapping: {
+    responseType: "cursor";
+    data: string;
+    nextCursor: string;
+    hasNextPage: string;
+    total: string;
+};
+export interface UseInfiniteCursorConfig<T> {
+    /** TanStack query key. Include scope params (orgId, BU id, filters) so
+     *  changes invalidate correctly. */
+    queryKey: QueryKey;
+    /** Fetches one page. Receives the cursor for the next page (undefined on
+     *  first page) and an AbortSignal forwarded from TanStack. */
+    queryFn: (args: {
+        cursor: string | undefined;
+        signal: AbortSignal;
+    }) => Promise<CursorResponse<T>>;
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+    /**
+     * When true, the previous page set stays visible while the query refetches
+     * after a key change (filter swap, sort change). Prevents the consumer's
+     * grid from flashing to a skeleton between filter changes. Maps to
+     * TanStack's `placeholderData: keepPreviousData`.
+     */
+    keepPreviousResults?: boolean;
+}
+/**
+ * Cursor-paginated infinite query for Pagamio `/feed` endpoints.
+ *
+ * Returns the raw TanStack `useInfiniteQueryResult` — no custom shape — so
+ * callers keep full access to `fetchNextPage`, `hasNextPage`, `isFetchingNextPage`,
+ * `data.pages`, etc.
+ *
+ * Example:
+ * ```ts
+ * const query = useInfiniteCursor<Product>({
+ *   queryKey: ['catalog', 'products', { businessUnitId, search }],
+ *   queryFn: ({ cursor, signal }) =>
+ *     apiClient
+ *       .get('/ecommerce/catalog/products/feed', {
+ *         params: { businessUnitId, cursor, limit: 30, withTotal: cursor === undefined },
+ *         signal,
+ *       })
+ *       .then((r) => r.data),
+ * });
+ *
+ * const items = query.data?.pages.flatMap((p) => p.data) ?? [];
+ * const total = query.data?.pages[0]?.meta.total;
+ * ```
+ */
+export declare function useInfiniteCursor<T>({ queryKey, queryFn, enabled, staleTime, gcTime, keepPreviousResults, }: UseInfiniteCursorConfig<T>): UseInfiniteQueryResult<{
+    pages: Array<CursorResponse<T>>;
+    pageParams: Array<string | undefined>;
+}, Error>;

package/lib/shared/hooks/useInfiniteCursor.js

@@ -0,0 +1,73 @@
+/**
+ * useInfiniteCursor — TanStack `useInfiniteQuery` wrapper for cursor-paginated
+ * Pagamio endpoints.
+ *
+ * Matches the backend cursor contract from `pagamio-nestjs-api-commons`:
+ *   `GET /<resource>/feed` → CursorPaginatedResponseDto<T> =
+ *     { data: T[], meta: { nextCursor, previousCursor, hasNextPage,
+ *                          hasPreviousPage, count, total? } }
+ *
+ * The hook treats `nextCursor` as an opaque base64 string — never parse or
+ * construct cursors on the client. If the backend changes its cursor encoding,
+ * the frontend doesn't need to know.
+ *
+ * For tables and any page-numbered UI, use `usePagamioTable` (offset paging)
+ * instead. Cursor pagination is for infinite-scroll surfaces (storefront,
+ * mobile feeds) where "Page X of Y" UX isn't shown.
+ *
+ * SRP: Wires `useInfiniteQuery` to the cursor contract. Callers own:
+ *   - flattening `data.pages` into a single list
+ *   - intersection-observer / "load more" wiring
+ *   - reading `data.pages[0]?.meta.total` for header counts (only present
+ *     when the caller passed `withTotal=true` on the first page).
+ */
+import { keepPreviousData, useInfiniteQuery } from '@tanstack/react-query';
+/**
+ * Documentation-as-code marker for the cursor meta shape. Mirrors the role
+ * of `pagamioMapping` for offset pagination — gives consumers a single named
+ * export to reference. Not consumed by `useInfiniteCursor` itself (TanStack
+ * handles the wiring); useful for grep / IDE jump-to-definition.
+ */
+export const cursorMapping = {
+    responseType: 'cursor',
+    data: 'data',
+    nextCursor: 'meta.nextCursor',
+    hasNextPage: 'meta.hasNextPage',
+    total: 'meta.total',
+};
+/**
+ * Cursor-paginated infinite query for Pagamio `/feed` endpoints.
+ *
+ * Returns the raw TanStack `useInfiniteQueryResult` — no custom shape — so
+ * callers keep full access to `fetchNextPage`, `hasNextPage`, `isFetchingNextPage`,
+ * `data.pages`, etc.
+ *
+ * Example:
+ * ```ts
+ * const query = useInfiniteCursor<Product>({
+ *   queryKey: ['catalog', 'products', { businessUnitId, search }],
+ *   queryFn: ({ cursor, signal }) =>
+ *     apiClient
+ *       .get('/ecommerce/catalog/products/feed', {
+ *         params: { businessUnitId, cursor, limit: 30, withTotal: cursor === undefined },
+ *         signal,
+ *       })
+ *       .then((r) => r.data),
+ * });
+ *
+ * const items = query.data?.pages.flatMap((p) => p.data) ?? [];
+ * const total = query.data?.pages[0]?.meta.total;
+ * ```
+ */
+export function useInfiniteCursor({ queryKey, queryFn, enabled, staleTime, gcTime, keepPreviousResults, }) {
+    return useInfiniteQuery({
+        queryKey,
+        queryFn: ({ pageParam, signal }) => queryFn({ cursor: pageParam, signal }),
+        initialPageParam: undefined,
+        getNextPageParam: (lastPage) => lastPage.meta.hasNextPage && lastPage.meta.nextCursor ? lastPage.meta.nextCursor : undefined,
+        enabled,
+        staleTime,
+        gcTime,
+        ...(keepPreviousResults ? { placeholderData: keepPreviousData } : {}),
+    });
+}

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.350",
+  "version": "0.8.352",
   "publishConfig": {
     "access": "public",
     "provenance": false
@@ -100,8 +100,8 @@
     "dayjs": "^1.11.13",
     "file-saver": "^2.0.5",
     "js-cookie": "^3.0.5",
-    "jspdf": "^2.5.2",
-    "jspdf-autotable": "^3.8.4",
+    "jspdf": "^4.2.1",
+    "jspdf-autotable": "^5.0.8",
     "jwt-decode": "^4.0.0",
     "lodash": "^4.17.21",
     "papaparse": "^5.4.1",