@pagamio/frontend-commons-lib 0.8.331 → 0.8.333

package/lib/components/ecommerce/ProductCard.js

@@ -5,8 +5,11 @@ import { formatPrice } from '../../helpers/utils';
 import ImageComponent from '../ui/ImageComponent';
 const LOW_STOCK_THRESHOLD = 5;
 export function ProductCard({ product, onAddToCart, isAddingToCart, storeId, basePath = '/shop', featured = false, linkSuffix, currency = 'ZAR', renderLink, onNavigate, }) {
-    const hasStock = product.totalStock > 0;
-    const isLowStock = hasStock && product.totalStock <= LOW_STOCK_THRESHOLD;
+    // Non-stock products (services / fees / digital goods) have no
+    // StockItem rows by design — they're always available
+    const isNonStock = product.isStockItem === false;
+    const hasStock = isNonStock || product.totalStock > 0;
+    const isLowStock = !isNonStock && hasStock && product.totalStock <= LOW_STOCK_THRESHOLD;
     const isBackorderable = product.allowBackorders === true;
     const canAddToCart = (hasStock || isBackorderable) && !!storeId;
     const hasVariants = product.variants && product.variants.length > 0;

package/lib/components/ecommerce/types.d.ts

@@ -33,6 +33,13 @@ export interface EcommerceProduct {
     totalStock: number;
     inStock?: boolean;
     allowBackorders?: boolean;
+    /**
+     * False for services / fees / digital goods that don't hold inventory.
+     * The card treats these as always available — no out-of-stock badge,
+     * no low-stock warning. Defaults to true (or undefined) for stock
+     * products which retain the existing behaviour.
+     */
+    isStockItem?: boolean;
     variants?: ProductVariant[];
 }
 export interface CartItemBundleItem {

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

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { UsePagamioComboboxReturn } from '../../shared/hooks/usePagamioCombobox';
+export interface PagamioSearchableComboboxProps<T extends {
+    id: string;
+}> {
+    /** State from usePagamioCombobox(). */
+    combobox: UsePagamioComboboxReturn<T>;
+    /** Controlled selected id, or null when nothing is selected. */
+    value: string | null;
+    onChange: (id: string | null) => void;
+    /**
+     * Optional pre-resolved selected option. When set, the trigger shows its
+     * label without needing to fetch via `restoreIds`. If both this and the
+     * hook's `restoredOptions` are available, this wins.
+     */
+    selectedOption?: T | null;
+    /** Trigger placeholder when nothing is selected. */
+    placeholder?: string;
+    /** Shown in dropdown when no results match. */
+    emptyMessage?: string;
+    /** Shown at the bottom of the list when the server returned a full page. */
+    cappedMessage?: string;
+    /** Shown while loading. */
+    loadingMessage?: string;
+    disabled?: boolean;
+    required?: boolean;
+    name?: string;
+    /** Allow clearing the selected value via an inline ✕. Default true. */
+    clearable?: boolean;
+    /** How to render an option as a string label. Default: `o.name` (must exist). */
+    getLabel?: (option: T) => string;
+    /** Optional custom row renderer inside the dropdown. */
+    renderOption?: (option: T, isSelected: boolean) => React.ReactNode;
+    /** Optional custom trigger label renderer. */
+    renderSelected?: (option: T) => React.ReactNode;
+    className?: string;
+    triggerClassName?: string;
+    contentClassName?: string;
+}
+export declare function PagamioSearchableCombobox<T extends {
+    id: string;
+}>({ combobox, value, onChange, selectedOption, placeholder, emptyMessage, cappedMessage, loadingMessage, disabled, required, name, clearable, getLabel, renderOption, renderSelected, className, triggerClassName, contentClassName, }: PagamioSearchableComboboxProps<T>): import("react/jsx-runtime").JSX.Element;

package/lib/components/ui/PagamioSearchableCombobox.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * PagamioSearchableCombobox — server-driven, debounced, single-select combobox.
+ *
+ * Built on top of the existing Command (cmdk) primitive + Popover.
+ * State is owned by `usePagamioCombobox` (created by the caller).
+ *
+ * See .agent/conventions/lookup-endpoints.md (backend) for the contract.
+ */
+import { CheckIcon, ChevronDownIcon, Cross2Icon } from '@radix-ui/react-icons';
+import * as React from 'react';
+import { cn } from '../../helpers';
+import { Command, CommandEmpty, CommandInput, CommandItem, CommandList } from './Command';
+import { Popover, PopoverContent, PopoverTrigger } from './Popover';
+function defaultGetLabel(option) {
+    // Assumes `name` exists. Override via `getLabel` for resources that use
+    // a different display field.
+    const o = option;
+    return o.name ?? option.id;
+}
+export function PagamioSearchableCombobox({ combobox, value, onChange, selectedOption, placeholder = 'Select…', emptyMessage = 'No results.', cappedMessage = 'Showing top results — refine your search.', loadingMessage = 'Loading…', disabled, required, name, clearable = true, getLabel = defaultGetLabel, renderOption, renderSelected, className, triggerClassName, contentClassName, }) {
+    const [open, setOpen] = React.useState(false);
+    // Resolve the option object for the current value: caller-supplied wins,
+    // then the hook's options (top-N), then restored.
+    const resolvedSelected = React.useMemo(() => {
+        if (selectedOption && selectedOption.id === value)
+            return selectedOption;
+        if (!value)
+            return null;
+        return combobox.options.find((o) => o.id === value) ?? combobox.restoredOptions.find((o) => o.id === value) ?? null;
+    }, [selectedOption, value, combobox.options, combobox.restoredOptions]);
+    const handleSelect = (id) => {
+        onChange(id === value ? null : id);
+        setOpen(false);
+    };
+    const handleClear = (e) => {
+        e.stopPropagation();
+        onChange(null);
+    };
+    return (_jsxs("div", { className: cn('w-full', className), children: [_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { type: "button", role: "combobox", "aria-expanded": open, "aria-haspopup": "listbox", "aria-required": required, disabled: disabled, name: name, className: cn('flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border bg-background text-foreground px-3 py-2 text-sm shadow-sm ring-offset-background placeholder:text-muted-foreground', 'focus:outline-none focus:ring-1 focus:ring-ring', 'disabled:cursor-not-allowed disabled:opacity-50', triggerClassName), children: [_jsx("span", { className: cn('line-clamp-1 text-left flex-1', !resolvedSelected && 'text-muted-foreground'), children: resolvedSelected
+                                        ? renderSelected
+                                            ? renderSelected(resolvedSelected)
+                                            : getLabel(resolvedSelected)
+                                        : placeholder }), clearable && resolvedSelected && !disabled ? (_jsx("span", { role: "button", tabIndex: -1, "aria-label": "Clear selection", onClick: handleClear, onMouseDown: (e) => e.preventDefault(), className: "ml-2 inline-flex h-4 w-4 items-center justify-center rounded-sm opacity-60 hover:opacity-100", children: _jsx(Cross2Icon, { className: "h-3 w-3" }) })) : (_jsx(ChevronDownIcon, { className: "ml-2 h-4 w-4 opacity-50 shrink-0" }))] }) }), _jsx(PopoverContent, { align: "start", sideOffset: 4, className: cn('p-0 w-[var(--radix-popover-trigger-width)] min-w-[240px]', contentClassName), children: _jsxs(Command, { shouldFilter: false, children: [_jsx(CommandInput, { placeholder: placeholder, value: combobox.search, onValueChange: combobox.setSearch }), _jsx(CommandList, { children: combobox.isLoading && combobox.options.length === 0 ? (_jsx("div", { className: "py-6 text-center text-sm text-muted-foreground", children: loadingMessage })) : combobox.error ? (_jsx("div", { className: "py-6 text-center text-sm text-destructive", children: combobox.error.message || 'Failed to load options.' })) : combobox.options.length === 0 ? (_jsx(CommandEmpty, { children: emptyMessage })) : (_jsxs(_Fragment, { children: [combobox.options.map((option) => {
+                                                const isSelected = option.id === value;
+                                                return (_jsx(CommandItem, { value: option.id, onSelect: () => handleSelect(option.id), children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "flex-1 line-clamp-1", children: getLabel(option) }), isSelected ? _jsx(CheckIcon, { className: "ml-2 h-4 w-4 opacity-100" }) : null] })) }, option.id));
+                                            }), combobox.isCapped ? (_jsx("div", { className: "border-t px-3 py-2 text-xs text-muted-foreground", children: cappedMessage })) : null] })) })] }) })] }), name ? _jsx("input", { type: "hidden", name: name, value: value ?? '' }) : null] }));
+}

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

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { UsePagamioComboboxReturn } from '../../shared/hooks/usePagamioCombobox';
+export interface PagamioSearchableMultiComboboxProps<T extends {
+    id: string;
+}> {
+    combobox: UsePagamioComboboxReturn<T>;
+    value: string[];
+    onChange: (ids: string[]) => void;
+    /**
+     * Pre-resolved selected options. Used to label chips for ids that aren't
+     * in the current top-N. If omitted, the component falls back to
+     * `combobox.restoredOptions` (configure `restoreIds` on the hook).
+     */
+    selectedOptions?: readonly T[];
+    placeholder?: string;
+    emptyMessage?: string;
+    cappedMessage?: string;
+    loadingMessage?: string;
+    disabled?: boolean;
+    required?: boolean;
+    name?: string;
+    getLabel?: (option: T) => string;
+    renderOption?: (option: T, isSelected: boolean) => React.ReactNode;
+    renderChip?: (option: T, onRemove: () => void) => React.ReactNode;
+    className?: string;
+    triggerClassName?: string;
+    contentClassName?: string;
+}
+export declare function PagamioSearchableMultiCombobox<T extends {
+    id: string;
+}>({ combobox, value, onChange, selectedOptions, placeholder, emptyMessage, cappedMessage, loadingMessage, disabled, required, name, getLabel, renderOption, renderChip, className, triggerClassName, contentClassName, }: PagamioSearchableMultiComboboxProps<T>): import("react/jsx-runtime").JSX.Element;

package/lib/components/ui/PagamioSearchableMultiCombobox.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * PagamioSearchableMultiCombobox — server-driven, debounced, multi-select combobox.
+ *
+ * Sibling of PagamioSearchableCombobox. Differences:
+ *   - `value` is `string[]`, `onChange` toggles ids.
+ *   - The trigger shows chips for each selected option (resolved via the
+ *     hook's `restoredOptions` OR `selectedOptions` prop).
+ *   - The dropdown stays open while toggling — supports multi-pick flow.
+ *
+ * See .agent/conventions/lookup-endpoints.md (backend) for the contract.
+ */
+import { ChevronDownIcon, Cross2Icon } from '@radix-ui/react-icons';
+import * as React from 'react';
+import { cn } from '../../helpers';
+import { Command, CommandEmpty, CommandInput, CommandItem, CommandList } from './Command';
+import { Popover, PopoverContent, PopoverTrigger } from './Popover';
+function defaultGetLabel(option) {
+    const o = option;
+    return o.name ?? option.id;
+}
+export function PagamioSearchableMultiCombobox({ combobox, value, onChange, selectedOptions, placeholder = 'Select…', emptyMessage = 'No results.', cappedMessage = 'Showing top results — refine your search.', loadingMessage = 'Loading…', disabled, required, name, getLabel = defaultGetLabel, renderOption, renderChip, className, triggerClassName, contentClassName, }) {
+    const [open, setOpen] = React.useState(false);
+    // Resolve labels for currently-selected ids. Caller's `selectedOptions`
+    // wins; otherwise look in the hook's options + restoredOptions.
+    const selectedById = React.useMemo(() => {
+        const map = new Map();
+        const sources = [selectedOptions ?? [], combobox.options, combobox.restoredOptions];
+        for (const source of sources) {
+            for (const option of source) {
+                if (!map.has(option.id))
+                    map.set(option.id, option);
+            }
+        }
+        return map;
+    }, [selectedOptions, combobox.options, combobox.restoredOptions]);
+    const chips = React.useMemo(() => value.map((id) => selectedById.get(id)).filter((o) => o !== undefined), [value, selectedById]);
+    // Ids in `value` that we couldn't resolve to a label — render as raw id.
+    const unresolvedIds = React.useMemo(() => value.filter((id) => !selectedById.has(id)), [value, selectedById]);
+    const toggle = (id) => {
+        onChange(value.includes(id) ? value.filter((v) => v !== id) : [...value, id]);
+    };
+    const remove = (id) => onChange(value.filter((v) => v !== id));
+    const clearAll = (e) => {
+        e.stopPropagation();
+        onChange([]);
+    };
+    const hasSelection = value.length > 0;
+    return (_jsxs("div", { className: cn('w-full', className), children: [_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { type: "button", role: "combobox", "aria-expanded": open, "aria-haspopup": "listbox", "aria-required": required, disabled: disabled, className: cn('flex min-h-9 w-full items-center justify-between whitespace-normal rounded-md border bg-background text-foreground px-2 py-1 text-sm shadow-sm ring-offset-background', 'focus:outline-none focus:ring-1 focus:ring-ring', 'disabled:cursor-not-allowed disabled:opacity-50', triggerClassName), children: [_jsx("div", { className: "flex flex-wrap gap-1 items-center flex-1 min-w-0", children: hasSelection ? (_jsxs(_Fragment, { children: [chips.map((option) => renderChip ? (_jsx(React.Fragment, { children: renderChip(option, () => remove(option.id)) }, option.id)) : (_jsxs("span", { className: "inline-flex items-center gap-1 rounded-sm bg-muted px-1.5 py-0.5 text-xs text-foreground", children: [_jsx("span", { className: "line-clamp-1 max-w-[160px]", children: getLabel(option) }), _jsx("span", { role: "button", tabIndex: -1, "aria-label": `Remove ${getLabel(option)}`, onClick: (e) => {
+                                                            e.stopPropagation();
+                                                            remove(option.id);
+                                                        }, onMouseDown: (e) => e.preventDefault(), className: "inline-flex h-3 w-3 items-center justify-center opacity-60 hover:opacity-100", children: _jsx(Cross2Icon, { className: "h-3 w-3" }) })] }, option.id))), unresolvedIds.map((id) => (_jsxs("span", { className: "inline-flex items-center gap-1 rounded-sm bg-muted px-1.5 py-0.5 text-xs text-muted-foreground italic", children: [_jsx("span", { className: "line-clamp-1 max-w-[140px]", children: id }), _jsx("span", { role: "button", tabIndex: -1, "aria-label": "Remove", onClick: (e) => {
+                                                            e.stopPropagation();
+                                                            remove(id);
+                                                        }, onMouseDown: (e) => e.preventDefault(), className: "inline-flex h-3 w-3 items-center justify-center opacity-60 hover:opacity-100", children: _jsx(Cross2Icon, { className: "h-3 w-3" }) })] }, id)))] })) : (_jsx("span", { className: "text-muted-foreground px-1", children: placeholder })) }), _jsxs("div", { className: "flex items-center", children: [hasSelection && !disabled ? (_jsx("span", { role: "button", tabIndex: -1, "aria-label": "Clear all", onClick: clearAll, onMouseDown: (e) => e.preventDefault(), className: "ml-2 inline-flex h-4 w-4 items-center justify-center rounded-sm opacity-60 hover:opacity-100", children: _jsx(Cross2Icon, { className: "h-3 w-3" }) })) : null, _jsx(ChevronDownIcon, { className: "ml-2 h-4 w-4 opacity-50 shrink-0" })] })] }) }), _jsx(PopoverContent, { align: "start", sideOffset: 4, className: cn('p-0 w-[var(--radix-popover-trigger-width)] min-w-[240px]', contentClassName), children: _jsxs(Command, { shouldFilter: false, children: [_jsx(CommandInput, { placeholder: placeholder, value: combobox.search, onValueChange: combobox.setSearch }), _jsx(CommandList, { children: combobox.isLoading && combobox.options.length === 0 ? (_jsx("div", { className: "py-6 text-center text-sm text-muted-foreground", children: loadingMessage })) : combobox.error ? (_jsx("div", { className: "py-6 text-center text-sm text-destructive", children: combobox.error.message || 'Failed to load options.' })) : combobox.options.length === 0 ? (_jsx(CommandEmpty, { children: emptyMessage })) : (_jsxs(_Fragment, { children: [combobox.options.map((option) => {
+                                                const isSelected = value.includes(option.id);
+                                                return (_jsx(CommandItem, { value: option.id, onSelect: () => toggle(option.id), children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [_jsx("span", { className: cn('mr-2 inline-flex h-4 w-4 items-center justify-center rounded-sm border', isSelected ? 'bg-primary text-primary-foreground border-primary' : 'border-input'), children: isSelected ? '✓' : null }), _jsx("span", { className: "flex-1 line-clamp-1", children: getLabel(option) })] })) }, option.id));
+                                            }), combobox.isCapped ? (_jsx("div", { className: "border-t px-3 py-2 text-xs text-muted-foreground", children: cappedMessage })) : null] })) })] }) })] }), name ? value.map((id) => _jsx("input", { type: "hidden", name: name, value: id }, id)) : null] }));
+}

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

@@ -6,6 +6,8 @@ export * from './Avatar';
 export * from './Command';
 export * from './Dialog';
 export * from './Form';
+export * from './PagamioSearchableCombobox';
+export * from './PagamioSearchableMultiCombobox';
 export * from './Popover';
 export * from './Radio';
 export * from './Select';

package/lib/components/ui/index.js

@@ -5,6 +5,8 @@ export * from './Avatar';
 export * from './Command';
 export * from './Dialog';
 export * from './Form';
+export * from './PagamioSearchableCombobox';
+export * from './PagamioSearchableMultiCombobox';
 export * from './Popover';
 export * from './Radio';
 export * from './Select';

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

@@ -0,0 +1,13 @@
+import type { Field } from '../../../types';
+interface SearchableComboboxInputProps {
+    field: Field;
+    error?: {
+        message?: string;
+    };
+    value?: string | null;
+    onChange?: (value: string | null) => void;
+    onBlur?: () => void;
+    name?: string;
+}
+declare const SearchableComboboxInput: import("react").ForwardRefExoticComponent<SearchableComboboxInputProps & import("react").RefAttributes<HTMLDivElement>>;
+export default SearchableComboboxInput;

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

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Form-engine input that wires `usePagamioCombobox` + `PagamioSearchableCombobox`
+ * into the form-engine's field declaration shape.
+ *
+ * Field declaration:
+ *
+ *   {
+ *     name: "storeId",
+ *     label: "Store",
+ *     type: "searchable-combobox",
+ *     source: {
+ *       fetcher: (params) => getStoresLookup({ businessUnitId, ...params }),
+ *       queryKey: ["stores", "lookup", businessUnitId],
+ *     },
+ *     placeholder: "Search stores…",
+ *   }
+ */
+import { forwardRef, useMemo } from 'react';
+import { PagamioSearchableCombobox } from '../../../../components/ui/PagamioSearchableCombobox';
+import { usePagamioCombobox } from '../../../../shared/hooks/usePagamioCombobox';
+const SearchableComboboxInput = forwardRef(({ field, value, onChange }, ref) => {
+    const source = field.source;
+    if (!source) {
+        // Misconfigured field. Render a stable no-op so the form doesn't crash.
+        // The convention requires `source` for searchable-combobox.
+        return (_jsxs("div", { ref: ref, className: "rounded-md border border-destructive bg-destructive/10 px-3 py-2 text-sm text-destructive", children: ["Field ", _jsx("code", { children: field.name }), " of type ", _jsx("code", { children: "searchable-combobox" }), " is missing the ", _jsx("code", { children: "source" }), ' ', "spec."] }));
+    }
+    const restoreIds = useMemo(() => (value ? [value] : undefined), [value]);
+    const combobox = usePagamioCombobox({
+        queryKey: source.queryKey,
+        queryFn: source.fetcher,
+        pageSize: source.pageSize,
+        debounceMs: source.debounceMs,
+        restoreIds,
+    });
+    return (_jsx("div", { ref: ref, children: _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 }) }));
+});
+SearchableComboboxInput.displayName = 'SearchableComboboxInput';
+export default SearchableComboboxInput;

package/lib/form-engine/components/inputs/searchable-multi-combobox/SearchableMultiComboboxInput.d.ts

@@ -0,0 +1,13 @@
+import type { Field } from '../../../types';
+interface SearchableMultiComboboxInputProps {
+    field: Field;
+    error?: {
+        message?: string;
+    };
+    value?: string[];
+    onChange?: (value: string[]) => void;
+    onBlur?: () => void;
+    name?: string;
+}
+declare const SearchableMultiComboboxInput: import("react").ForwardRefExoticComponent<SearchableMultiComboboxInputProps & import("react").RefAttributes<HTMLDivElement>>;
+export default SearchableMultiComboboxInput;

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

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Form-engine input that wires `usePagamioCombobox` +
+ * `PagamioSearchableMultiCombobox` into the form-engine's field declaration shape.
+ *
+ * Field declaration:
+ *
+ *   {
+ *     name: "productIds",
+ *     label: "Products",
+ *     type: "searchable-multi-combobox",
+ *     source: {
+ *       fetcher: (params) => getProductsLookup({ organizationId, ...params }),
+ *       queryKey: ["products", "lookup", organizationId],
+ *     },
+ *     placeholder: "Add products…",
+ *   }
+ */
+import { forwardRef, useMemo } from 'react';
+import { PagamioSearchableMultiCombobox } from '../../../../components/ui/PagamioSearchableMultiCombobox';
+import { usePagamioCombobox } from '../../../../shared/hooks/usePagamioCombobox';
+const SearchableMultiComboboxInput = forwardRef(({ field, value, onChange }, ref) => {
+    const source = field.source;
+    if (!source) {
+        return (_jsxs("div", { ref: ref, className: "rounded-md border border-destructive bg-destructive/10 px-3 py-2 text-sm text-destructive", children: ["Field ", _jsx("code", { children: field.name }), " of type ", _jsx("code", { children: "searchable-multi-combobox" }), " is missing the", ' ', _jsx("code", { children: "source" }), " spec."] }));
+    }
+    const restoreIds = useMemo(() => (value && value.length > 0 ? value : undefined), [value]);
+    const combobox = usePagamioCombobox({
+        queryKey: source.queryKey,
+        queryFn: source.fetcher,
+        pageSize: source.pageSize,
+        debounceMs: source.debounceMs,
+        restoreIds,
+    });
+    return (_jsx("div", { ref: ref, children: _jsx(PagamioSearchableMultiCombobox, { combobox: combobox, value: value ?? [], onChange: (ids) => onChange?.(ids), placeholder: field.placeholder, disabled: field.disabled, required: field.validation?.required ? true : undefined, name: field.name, getLabel: source.getLabel }) }));
+});
+SearchableMultiComboboxInput.displayName = 'SearchableMultiComboboxInput';
+export default SearchableMultiComboboxInput;

package/lib/form-engine/registry/RegisterComponents.js

@@ -31,7 +31,7 @@ export const setupInputRegistry = async () => {
     return getRegistryPromise();
 };
 const doSetup = async () => {
-    const [{ default: CardExpiryInput }, { default: CheckboxInput }, { default: ColorInput }, { default: CreditCardInput }, { default: DateInput }, { default: EmailInput }, { default: LabelInput }, { default: MultiSelectInputComponent }, { default: NumberInput }, { default: PasswordInput }, { default: RadioInput }, { default: SelectInput }, { default: TextareaInputFW }, { default: TimeInput }, { default: ToggleSwitchInput }, { default: UploadFieldForm }, { default: PhoneInput }, { default: SearchableMultiSelectInput },] = await Promise.all([
+    const [{ default: CardExpiryInput }, { default: CheckboxInput }, { default: ColorInput }, { default: CreditCardInput }, { default: DateInput }, { default: EmailInput }, { default: LabelInput }, { default: MultiSelectInputComponent }, { default: NumberInput }, { default: PasswordInput }, { default: RadioInput }, { default: SelectInput }, { default: TextareaInputFW }, { default: TimeInput }, { default: ToggleSwitchInput }, { default: UploadFieldForm }, { default: PhoneInput }, { default: SearchableMultiSelectInput }, { default: SearchableComboboxInput }, { default: SearchableMultiComboboxInput },] = await Promise.all([
         import('../components/inputs/card-expiry-input/CardExpiryInput'),
         import('../components/inputs/checkbox-input/CheckboxInput'),
         import('../components/inputs/color-input/ColorInput'),
@@ -50,6 +50,8 @@ const doSetup = async () => {
         import('../components/inputs/upload-field/UploadFieldForm'),
         import('../../components/ui/PhoneInput'),
         import('../components/inputs/searchable-multi-select/SearchableMultiSelectInput'),
+        import('../components/inputs/searchable-combobox/SearchableComboboxInput'),
+        import('../components/inputs/searchable-multi-combobox/SearchableMultiComboboxInput'),
     ]);
     registerInput('card-expiry-input', CardExpiryInput);
     registerInput('checkbox', CheckboxInput);
@@ -69,5 +71,7 @@ const doSetup = async () => {
     registerInput('textarea', TextareaInputFW);
     registerInput('time', TimeInput);
     registerInput('searchable-multi-select', SearchableMultiSelectInput);
+    registerInput('searchable-combobox', SearchableComboboxInput);
+    registerInput('searchable-multi-combobox', SearchableMultiComboboxInput);
     registryDone = true;
 };

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

@@ -130,7 +130,45 @@ export interface DependencyValidation {
 /**
  * Available field types supported by the form engine
  */
-export type FieldType = 'card-expiry-input' | 'checkbox' | 'color' | 'credit-card' | 'date' | 'email' | 'file' | 'multi-select' | 'number' | 'password' | 'radio' | 'searchable-multi-select' | 'select' | 'switch' | 'tel' | 'text' | 'textarea' | 'time';
+export type FieldType = 'card-expiry-input' | 'checkbox' | 'color' | 'credit-card' | 'date' | 'email' | 'file' | 'multi-select' | 'number' | 'password' | 'radio' | 'searchable-combobox' | 'searchable-multi-combobox' | 'searchable-multi-select' | 'select' | 'switch' | 'tel' | 'text' | 'textarea' | 'time';
+/**
+ * Source contract for server-driven combobox field types
+ * (`searchable-combobox`, `searchable-multi-combobox`).
+ *
+ * The form engine builds a `queryFn` from this spec and feeds it to
+ * `usePagamioCombobox`. See `.agent/conventions/lookup-endpoints.md`
+ * (backend) for the endpoint contract.
+ */
+export interface ComboboxOption {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+export interface ComboboxSourceSpec {
+    /**
+     * Function that fetches lookup results. The form engine calls this with
+     * `{ search, limit, ids }` per the lookup contract.
+     * Returns `{ data: T[] }` or `null`.
+     */
+    fetcher: (params: {
+        search?: string;
+        limit?: number;
+        ids?: string[];
+    }) => Promise<{
+        data: ComboboxOption[];
+    } | null | undefined>;
+    /**
+     * Query key prefix. Combined with the fetched-search and ids inside
+     * `usePagamioCombobox`. Should include scope (organizationId, etc.).
+     */
+    queryKey: readonly unknown[];
+    /** Optional: how to render the option label. Default: `option.name`. */
+    getLabel?: (option: ComboboxOption) => string;
+    /** Optional: per-field page size override. Default 20. */
+    pageSize?: number;
+    /** Optional: per-field debounce override (ms). Default 300. */
+    debounceMs?: number;
+}
 /**
  * Defines the structure of a form field
  */
@@ -172,6 +210,11 @@ export interface Field {
     /** callback for onChange event */
     onChange?: (value: string) => void;
     isHidden?: boolean;
+    /**
+     * Source spec for `searchable-combobox` / `searchable-multi-combobox` types.
+     * Tells the form engine how to fetch lookup results.
+     */
+    source?: ComboboxSourceSpec;
 }
 export interface DependentFieldUpdate {
     field: string;

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

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

package/lib/shared/hooks/index.js

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

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

@@ -0,0 +1,83 @@
+/**
+ * usePagamioCombobox — state hook for server-driven searchable combobox UIs.
+ *
+ * Mirrors the shape of `usePagamioTable`. The hook owns:
+ *   - The raw + debounced search string
+ *   - Top-N options fetched from the server (one query)
+ *   - Optional restoration of full records for a known set of ids (second query)
+ *   - `isCapped` (true when the server returned a full page; user should refine)
+ *
+ * Rendering is the caller's concern (see PagamioSearchableCombobox).
+ *
+ * Frontend contract (`/<resource>/lookup` endpoint):
+ *   GET /api/v1/<resource>/lookup?search=&limit=&ids=&<scope>
+ *   → { success, data: T[], timestamp }
+ * Slim payload (`{ id, name, ...minimal extras }`), no `meta`, no pagination.
+ * See `.agent/conventions/lookup-endpoints.md` (backend repo).
+ */
+import { type QueryKey } from '@tanstack/react-query';
+export interface ComboboxQueryParams {
+    search?: string;
+    limit?: number;
+    ids?: string[];
+}
+export interface ComboboxFetchResult<T> {
+    data: T[];
+}
+export interface UsePagamioComboboxConfig<T extends {
+    id: string;
+}> {
+    /** TanStack Query key. Should include scope params (orgId, buId). */
+    queryKey: QueryKey;
+    /**
+     * The fetcher. Called with `{ search, limit }` for top-N lookups and
+     * separately with `{ ids }` for restoring selected-state labels.
+     * Should return `{ data: T[] }` or `null`. The hook unwraps `data`.
+     */
+    queryFn: (params: ComboboxQueryParams) => Promise<ComboboxFetchResult<T> | null | undefined>;
+    /**
+     * Whether the underlying queries are allowed to run. Same semantics as
+     * TanStack Query's `enabled`. Use for dependent pickers (e.g. store
+     * picker needs business unit selected first).
+     */
+    enabled?: boolean;
+    /** Debounce ms for the search input. Default 300. */
+    debounceMs?: number;
+    /**
+     * How many rows to request per top-N fetch. Default 20. Should be ≤ the
+     * backend's hard cap (e.g. 50). When the server returns exactly this
+     * many rows, `isCapped` flips true to encourage the user to refine.
+     */
+    pageSize?: number;
+    /** TanStack Query stale time (ms). Default 60_000. */
+    staleTime?: number;
+    /**
+     * Ids whose full records to fetch even if they aren't in the current
+     * search results. Used to render chips/labels for pre-selected values.
+     */
+    restoreIds?: readonly string[];
+}
+export interface UsePagamioComboboxReturn<T extends {
+    id: string;
+}> {
+    /** Raw input value (updates on every keystroke). */
+    search: string;
+    setSearch: (value: string) => void;
+    /** Debounced input — drives the actual server query. */
+    debouncedSearch: string;
+    /** Top-N options for the current debounced search. */
+    options: T[];
+    /** Records resolved via `restoreIds`. Empty array when no ids passed. */
+    restoredOptions: T[];
+    /** First-fetch loading. */
+    isLoading: boolean;
+    /** Any background refetch in flight. */
+    isFetching: boolean;
+    /** True iff the server returned `pageSize` rows — there may be more. */
+    isCapped: boolean;
+    /** Underlying error, if any. */
+    error: Error | null;
+}
+export declare function usePagamioCombobox<T extends {
+    id: string;
+}>({ queryKey, queryFn, enabled, debounceMs, pageSize, staleTime, restoreIds, }: UsePagamioComboboxConfig<T>): UsePagamioComboboxReturn<T>;

package/lib/shared/hooks/usePagamioCombobox.js

@@ -0,0 +1,72 @@
+/**
+ * usePagamioCombobox — state hook for server-driven searchable combobox UIs.
+ *
+ * Mirrors the shape of `usePagamioTable`. The hook owns:
+ *   - The raw + debounced search string
+ *   - Top-N options fetched from the server (one query)
+ *   - Optional restoration of full records for a known set of ids (second query)
+ *   - `isCapped` (true when the server returned a full page; user should refine)
+ *
+ * Rendering is the caller's concern (see PagamioSearchableCombobox).
+ *
+ * Frontend contract (`/<resource>/lookup` endpoint):
+ *   GET /api/v1/<resource>/lookup?search=&limit=&ids=&<scope>
+ *   → { success, data: T[], timestamp }
+ * Slim payload (`{ id, name, ...minimal extras }`), no `meta`, no pagination.
+ * See `.agent/conventions/lookup-endpoints.md` (backend repo).
+ */
+import { keepPreviousData, useQuery } from '@tanstack/react-query';
+import { useEffect, useMemo, useState } from 'react';
+// ─── Hook ───────────────────────────────────────────────────────────────
+const DEFAULT_DEBOUNCE_MS = 300;
+const DEFAULT_PAGE_SIZE = 20;
+const DEFAULT_STALE_TIME = 60_000;
+export function usePagamioCombobox({ queryKey, queryFn, enabled = true, debounceMs = DEFAULT_DEBOUNCE_MS, pageSize = DEFAULT_PAGE_SIZE, staleTime = DEFAULT_STALE_TIME, restoreIds, }) {
+    const [search, setSearch] = useState('');
+    const [debouncedSearch, setDebouncedSearch] = useState('');
+    // Debounce raw input -> debounced value.
+    useEffect(() => {
+        if (search === debouncedSearch)
+            return;
+        const timer = setTimeout(() => setDebouncedSearch(search), debounceMs);
+        return () => clearTimeout(timer);
+    }, [search, debouncedSearch, debounceMs]);
+    // ── Primary query: top-N for current debounced search ────────────────
+    const topNQuery = useQuery({
+        queryKey: [...queryKey, 'lookup', { search: debouncedSearch, limit: pageSize }],
+        queryFn: () => queryFn({
+            search: debouncedSearch || undefined,
+            limit: pageSize,
+        }),
+        enabled,
+        staleTime,
+        placeholderData: keepPreviousData,
+    });
+    const options = useMemo(() => topNQuery.data?.data ?? [], [topNQuery.data]);
+    const isCapped = options.length >= pageSize;
+    // ── Secondary query: resolve labels for known ids ────────────────────
+    // Sorted to keep the cache key stable.
+    const stableRestoreIds = useMemo(() => {
+        if (!restoreIds || restoreIds.length === 0)
+            return undefined;
+        return [...restoreIds].sort();
+    }, [restoreIds]);
+    const restoreQuery = useQuery({
+        queryKey: [...queryKey, 'lookup', 'restore', stableRestoreIds],
+        queryFn: () => queryFn({ ids: stableRestoreIds }),
+        enabled: enabled && !!stableRestoreIds && stableRestoreIds.length > 0,
+        staleTime,
+    });
+    const restoredOptions = useMemo(() => restoreQuery.data?.data ?? [], [restoreQuery.data]);
+    return {
+        search,
+        setSearch,
+        debouncedSearch,
+        options,
+        restoredOptions,
+        isLoading: topNQuery.isLoading || restoreQuery.isLoading,
+        isFetching: topNQuery.isFetching || restoreQuery.isFetching,
+        isCapped,
+        error: topNQuery.error ?? restoreQuery.error ?? null,
+    };
+}

package/lib/styles.css

@@ -1450,6 +1450,9 @@ video {
 .w-\[52px\] {
   width: 52px;
 }
+.w-\[var\(--radix-popover-trigger-width\)\] {
+  width: var(--radix-popover-trigger-width);
+}
 .w-auto {
   width: auto;
 }
@@ -1485,6 +1488,9 @@ video {
 .min-w-\[20px\] {
   min-width: 20px;
 }
+.min-w-\[240px\] {
+  min-width: 240px;
+}
 .min-w-\[52px\] {
   min-width: 52px;
 }
@@ -1518,6 +1524,9 @@ video {
 .max-w-\[100vw\] {
   max-width: 100vw;
 }
+.max-w-\[140px\] {
+  max-width: 140px;
+}
 .max-w-\[160px\] {
   max-width: 160px;
 }
@@ -1981,6 +1990,9 @@ video {
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+.whitespace-normal {
+  white-space: normal;
+}
 .whitespace-nowrap {
   white-space: nowrap;
 }
@@ -2839,6 +2851,10 @@ video {
   padding-left: 0px;
   padding-right: 0px;
 }
+.px-1 {
+  padding-left: 0.25rem;
+  padding-right: 0.25rem;
+}
 .px-1\.5 {
   padding-left: 0.375rem;
   padding-right: 0.375rem;

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