@pagamio/frontend-commons-lib 0.8.339 → 0.8.341

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

@@ -0,0 +1,48 @@
+import * as React from 'react';
+export interface ReservedBreakdownItem {
+    id: string;
+    /** Short label rendered for this row, e.g. "Cart #1234 (active)" */
+    label: string;
+    /** Optional secondary line, e.g. "expires in 14m" or "Transfer → Store B" */
+    detail?: string;
+    quantity: number;
+}
+export interface ReservedBreakdownBucket {
+    /** Total quantity for this bucket. */
+    quantity: number;
+    /** Individual contributing records. May be empty even when quantity > 0
+     *  if the source only exposes aggregate data. */
+    items: ReservedBreakdownItem[];
+    /** When true, the bucket's `quantity` is informational and is NOT part
+     *  of the parent `Reserved` total (e.g. pending stock transfers). */
+    informational?: boolean;
+}
+export interface ReservedBreakdownData {
+    total: number;
+    orders: ReservedBreakdownBucket;
+    transfers: ReservedBreakdownBucket;
+    allocations: ReservedBreakdownBucket;
+}
+export interface ReservedBreakdownPopoverProps {
+    /** Quantity value to render as the clickable trigger. */
+    reservedQuantity: number;
+    /** Lazy-load: fetcher invoked when the popover opens for the first time. */
+    fetch: () => Promise<ReservedBreakdownData>;
+    /** Optional className for the trigger button. */
+    className?: string;
+    /** Render variant — default styles the trigger as a link-like underlined
+     *  number, matching the dense layouts in inventory tables. */
+    variant?: 'link' | 'plain';
+}
+/**
+ * Clickable Reserved-quantity cell that opens a popover breaking down the
+ * value by source (Orders, Transfers, Allocations). Data-agnostic — the
+ * consumer provides a `fetch` callback that resolves the breakdown for the
+ * specific stock-item or station-allocation row.
+ *
+ * The trigger only renders an interactive control when `reservedQuantity > 0`.
+ * At zero, it renders the plain quantity text so the table cell stays
+ * visually consistent without offering an interaction with nothing to show.
+ */
+export declare const ReservedBreakdownPopover: React.FC<ReservedBreakdownPopoverProps>;
+export default ReservedBreakdownPopover;

package/lib/components/ui/ReservedBreakdownPopover.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { cn } from '../../helpers/utils';
+import { Popover, PopoverContent, PopoverTrigger } from './Popover';
+const formatQty = (q) => (Number.isInteger(q) ? String(q) : q.toFixed(2));
+/**
+ * Clickable Reserved-quantity cell that opens a popover breaking down the
+ * value by source (Orders, Transfers, Allocations). Data-agnostic — the
+ * consumer provides a `fetch` callback that resolves the breakdown for the
+ * specific stock-item or station-allocation row.
+ *
+ * The trigger only renders an interactive control when `reservedQuantity > 0`.
+ * At zero, it renders the plain quantity text so the table cell stays
+ * visually consistent without offering an interaction with nothing to show.
+ */
+export const ReservedBreakdownPopover = ({ reservedQuantity, fetch, className, variant = 'link', }) => {
+    const [state, setState] = React.useState({
+        loading: false,
+        data: undefined,
+        error: undefined,
+    });
+    const hasFetchedRef = React.useRef(false);
+    if (reservedQuantity <= 0) {
+        return _jsx("span", { className: className, children: formatQty(reservedQuantity) });
+    }
+    const handleOpenChange = (open) => {
+        if (!open || hasFetchedRef.current)
+            return;
+        hasFetchedRef.current = true;
+        setState({ loading: true, data: undefined, error: undefined });
+        fetch()
+            .then((data) => setState({ loading: false, data, error: undefined }))
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : 'Failed to load reserved breakdown';
+            setState({ loading: false, data: undefined, error: message });
+            hasFetchedRef.current = false;
+        });
+    };
+    const triggerClasses = variant === 'link'
+        ? 'underline decoration-dotted underline-offset-4 hover:decoration-solid focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded'
+        : 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded';
+    return (_jsxs(Popover, { onOpenChange: handleOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { type: "button", className: cn(triggerClasses, className), "aria-label": `View reserved breakdown (${formatQty(reservedQuantity)})`, children: formatQty(reservedQuantity) }) }), _jsx(PopoverContent, { align: "end", className: "w-80", children: _jsx(BreakdownBody, { state: state, reservedQuantity: reservedQuantity }) })] }));
+};
+const BreakdownBody = ({ state, reservedQuantity }) => {
+    if (state.loading) {
+        return _jsx("div", { className: "text-sm text-muted-foreground", children: "Loading breakdown\u2026" });
+    }
+    if (state.error) {
+        return _jsx("div", { className: "text-sm text-destructive", children: state.error });
+    }
+    if (!state.data) {
+        return _jsx("div", { className: "text-sm text-muted-foreground", children: "No data available" });
+    }
+    const { orders, transfers, allocations, total } = state.data;
+    return (_jsxs("div", { className: "space-y-3", children: [_jsxs("div", { className: "flex items-baseline justify-between", children: [_jsx("h4", { className: "text-sm font-semibold", children: "Reserved breakdown" }), _jsx("span", { className: "text-sm font-mono", children: formatQty(total) })] }), _jsx(BucketSection, { title: "Orders", bucket: orders }), _jsx(BucketSection, { title: "Transfers", bucket: transfers }), _jsx(BucketSection, { title: "Allocations", bucket: allocations }), Math.abs(total - reservedQuantity) > 0.001 ? (_jsxs("p", { className: "text-xs text-muted-foreground italic", children: ["Breakdown total (", formatQty(total), ") differs from the row value (", formatQty(reservedQuantity), "). Data may have changed since the row was last loaded."] })) : null] }));
+};
+const BucketSection = ({ title, bucket }) => {
+    const isInformational = bucket.informational === true;
+    return (_jsxs("section", { children: [_jsxs("div", { className: "flex items-baseline justify-between", children: [_jsxs("span", { className: "text-xs font-medium uppercase tracking-wide text-muted-foreground", children: [title, isInformational ? (_jsx("span", { className: "ml-1 normal-case font-normal italic text-muted-foreground/80", children: "(informational)" })) : null] }), _jsx("span", { className: "text-sm font-mono", children: formatQty(bucket.quantity) })] }), bucket.items.length > 0 ? (_jsx("ul", { className: "mt-1 space-y-0.5", children: bucket.items.map((item) => (_jsxs("li", { className: "flex items-baseline justify-between gap-2 text-xs", children: [_jsxs("span", { className: "truncate", children: [_jsx("span", { children: item.label }), item.detail ? _jsxs("span", { className: "text-muted-foreground", children: [" \u00B7 ", item.detail] }) : null] }), _jsx("span", { className: "font-mono", children: formatQty(item.quantity) })] }, item.id))) })) : null, isInformational && bucket.items.length === 0 && bucket.quantity > 0 ? (_jsx("p", { className: "mt-1 text-xs text-muted-foreground", children: "Pending records exist but no detail is available." })) : null, bucket.quantity === 0 && bucket.items.length === 0 ? (_jsx("p", { className: "mt-0.5 text-xs text-muted-foreground", children: "None" })) : null] }));
+};
+export default ReservedBreakdownPopover;

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

@@ -0,0 +1,13 @@
+import * as React from 'react';
+export type StockLabelKind = 'onHand' | 'reserved' | 'availableToSell';
+export interface StockLabelProps {
+    kind: StockLabelKind;
+    className?: string;
+}
+/**
+ * Inventory column label paired with a help-icon tooltip. Single source of
+ * truth for the three stock-quantity labels (On Hand / Reserved / Available
+ * to Sell) and their help text. Update copy here, not at the call site.
+ */
+export declare const StockLabel: React.FC<StockLabelProps>;
+export default StockLabel;

package/lib/components/ui/StockLabel.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HiInformationCircle } from 'react-icons/hi';
+import { cn } from '../../helpers/utils';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './Tooltip';
+const STOCK_LABEL_CONFIG = {
+    onHand: {
+        label: 'On Hand',
+        helpText: 'Total stock physically in this location',
+    },
+    reserved: {
+        label: 'Reserved',
+        helpText: 'Stock already committed to orders, transfers, or allocations',
+    },
+    availableToSell: {
+        label: 'Available to Sell',
+        helpText: 'Stock currently available for sale',
+    },
+};
+/**
+ * Inventory column label paired with a help-icon tooltip. Single source of
+ * truth for the three stock-quantity labels (On Hand / Reserved / Available
+ * to Sell) and their help text. Update copy here, not at the call site.
+ */
+export const StockLabel = ({ kind, className }) => {
+    const { label, helpText } = STOCK_LABEL_CONFIG[kind];
+    return (_jsx(TooltipProvider, { delayDuration: 150, children: _jsxs("span", { className: cn('inline-flex items-center gap-1', className), children: [_jsx("span", { children: label }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": `${label} help`, className: "text-muted-foreground hover:text-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-full", children: _jsx(HiInformationCircle, { className: "h-4 w-4", "aria-hidden": "true" }) }) }), _jsx(TooltipContent, { className: "max-w-xs", children: helpText })] })] }) }));
+};
+export default StockLabel;

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

@@ -63,6 +63,10 @@ export type { ImageUploaderProps } from './ImageUploader';
 export { default as NotificationModal } from './NotificationModal';
 export type { NotificationModalProps } from './NotificationModal';
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from './Tooltip';
+export { StockLabel, default as StockLabelDefault } from './StockLabel';
+export type { StockLabelKind, StockLabelProps } from './StockLabel';
+export { ReservedBreakdownPopover, default as ReservedBreakdownPopoverDefault } from './ReservedBreakdownPopover';
+export type { ReservedBreakdownData, ReservedBreakdownBucket, ReservedBreakdownItem, ReservedBreakdownPopoverProps, } from './ReservedBreakdownPopover';
 export { default as TimerBadge } from './TimerBadge';
 export type { TimerBadgeProps } from './TimerBadge';
 export { Badge, default as BadgeDefault } from './Badge';

package/lib/components/ui/index.js

@@ -62,6 +62,10 @@ export { default as ImageUploader } from './ImageUploader';
 export { default as NotificationModal } from './NotificationModal';
 // Tooltip - v2 shadcn-style tooltip with Radix
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from './Tooltip';
+// StockLabel - inventory column label + help-icon tooltip
+export { StockLabel, default as StockLabelDefault } from './StockLabel';
+// ReservedBreakdownPopover - click-to-view breakdown of reserved stock
+export { ReservedBreakdownPopover, default as ReservedBreakdownPopoverDefault } from './ReservedBreakdownPopover';
 // TimerBadge - elapsed time with urgency coloring (green → amber → red)
 export { default as TimerBadge } from './TimerBadge';
 // Badge - styled pill/tag component

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

@@ -177,6 +177,15 @@ export interface UsePagamioTableConfig<T extends BaseEntity> {
     enabled?: boolean;
     staleTime?: number;
     gcTime?: number;
+    /**
+     * Auto-refetch interval (ms) for tables backed by long-running jobs
+     * (exports, imports, async report generation). Pass a fixed number to
+     * always poll, `false` to disable, or a predicate `(rows) => number | false`
+     * that returns the interval only while any row is still in flight — the
+     * predicate runs on every fetch settle so polling stops automatically
+     * once everything is terminal.
+     */
+    refetchInterval?: number | false | ((rows: T[]) => number | false);
     /**
      * Keep the previous page's rows visible while the next page fetches
      * (TanStack `placeholderData: keepPreviousData`). Defaults to true so

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

@@ -17,4 +17,4 @@ export declare const pagamioMapping: ResponseMapping;
  * 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>;
+export declare const usePagamioTable: <T extends BaseEntity>({ queryKey, queryFn, enabled: queryEnabled, staleTime, gcTime, refetchInterval, 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

@@ -158,7 +158,7 @@ function clientSort(items, sortConfig) {
     return sorted;
 }
 // ─── Hook ────────────────────────────────────────────────────────────
-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, }) => {
+export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = true, staleTime, gcTime, refetchInterval, 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);
@@ -190,6 +190,18 @@ export const usePagamioTable = ({ queryKey, queryFn, enabled: queryEnabled = tru
         staleTime,
         gcTime,
         placeholderData: keepPrev ? keepPreviousData : undefined,
+        // Predicate form re-extracts rows from the raw response so callers can
+        // gate polling on row state (e.g. "any pending export") without needing
+        // to know the responseMapping shape.
+        refetchInterval: typeof refetchInterval === 'function'
+            ? (query) => {
+                const raw = query.state.data;
+                if (!raw)
+                    return false;
+                const { data: rows } = processResponse(raw, responseMapping);
+                return refetchInterval(rows);
+            }
+            : refetchInterval,
     });
     // ── Process server response ──────────────────────────────────────
     const { serverData, serverTotal } = useMemo(() => {

package/lib/styles.css

@@ -3117,6 +3117,9 @@ video {
 .capitalize {
   text-transform: capitalize;
 }
+.normal-case {
+  text-transform: none;
+}
 .italic {
   font-style: italic;
 }
@@ -3487,6 +3490,9 @@ video {
 .line-through {
   text-decoration-line: line-through;
 }
+.decoration-dotted {
+  text-decoration-style: dotted;
+}
 .underline-offset-2 {
   text-underline-offset: 2px;
 }
@@ -4475,6 +4481,9 @@ video {
 .hover\:underline:hover {
   text-decoration-line: underline;
 }
+.hover\:decoration-solid:hover {
+  text-decoration-style: solid;
+}
 .hover\:opacity-100:hover {
   opacity: 1;
 }

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.339",
+  "version": "0.8.341",
   "publishConfig": {
     "access": "public",
     "provenance": false