@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/features/collector-drops/components/PlaceBidFormClient.d.ts

@@ -0,0 +1,65 @@
+import React from "react";
+import { type BidIncrementTier } from "../../../_internal/shared/features/collector-drops/config";
+export interface PlaceBidInput {
+    productId: string;
+    bidAmount: number;
+    autoMaxBid?: number;
+}
+/**
+ * The `ActionResult` envelope every server action in this app returns.
+ *
+ * 🛑 Exactly ONE level. `onPlaceBid`/`onBuyNow` used to be typed
+ * `Promise<unknown>`, and the consumer's actions returned a *doubly*-wrapped
+ * `{ ok: true, data: { ok: false, error } }`. Reading the outer `ok` therefore
+ * saw `true` for every possible outcome — including every failure — so Buy Now
+ * placed a real bid and a real locked cart line and then silently
+ * `router.refresh()`ed a page that renders nothing from the cart. Typing these
+ * props is what makes a re-introduced second envelope a compile error rather
+ * than a silent no-op button.
+ */
+export type BidActionEnvelope<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+    issues?: unknown[];
+};
+/** The subset of `BuyNowCollectorDropResult` this component actually consumes. */
+export interface BuyNowSuccess {
+    checkoutUrl?: string;
+}
+export interface PlaceBidFormClientProps {
+    productId: string;
+    currentBid: number;
+    startingBid: number;
+    tiers: BidIncrementTier[];
+    minBidIncrementOverride?: number;
+    currency: string;
+    isEnded: boolean;
+    collectorDropEndDate: Date | null;
+    buyNowPrice: number | null;
+    /**
+     * The seller's floor (D53). Threaded so the Buy-Now control is not offered
+     * for a buyout the server will refuse — `isBuyNowAvailable` now rejects
+     * `buyNowPrice < reservePrice`, and without this prop the button would
+     * render and then error on click.
+     */
+    reservePrice?: number | null;
+    bidCount: number;
+    tags?: string[];
+    onPlaceBid: (input: PlaceBidInput) => Promise<BidActionEnvelope<unknown>>;
+    onBuyNow?: () => Promise<BidActionEnvelope<BuyNowSuccess>>;
+}
+export declare function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, tiers, minBidIncrementOverride, currency, isEnded: ssrIsEnded, collectorDropEndDate, buyNowPrice, reservePrice, bidCount: ssrBidCount, tags, onPlaceBid, onBuyNow, }: PlaceBidFormClientProps): React.JSX.Element;
+/**
+ * `PlaceBidModalButton` — opens a modal that hosts the same PlaceBidFormClient.
+ *
+ * Use this on listing-detail pages so buyers explicitly opt-in to the bid
+ * surface instead of always seeing the card inline.
+ */
+export declare function PlaceBidModalButton(props: PlaceBidFormClientProps & {
+    triggerLabel?: string;
+    triggerClassName?: string;
+}): React.JSX.Element;

package/dist/features/collector-drops/components/PlaceBidFormClient.js

@@ -0,0 +1,306 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState, useTransition } from "react";
+import { useRouter } from "next/navigation.js";
+import { useTranslations } from "next-intl";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { isAuthError } from "../../../utils/auth-error.js";
+import { Button } from "../../../ui/components/Button.js";
+import { CountdownDisplay } from "../../../ui/components/CountdownDisplay.js";
+import { Div } from "../../../ui/components/Div.js";
+import { LoginRequiredModal } from "../../../ui/components/LoginRequiredModal.js";
+import { Modal } from "../../../ui/components/Modal.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Span, Text } from "../../../ui/components/Typography.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { useCanSeePrices } from "../../../react/hooks/useCanSeePrices.js";
+import { Form } from "../../../ui/components/Form.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues.js";
+import { placeBidSchema } from "../schemas/bid-input.js";
+import { useLiveCollectorDropBid } from "../hooks/useLiveCollectorDropBid.js";
+import { useIsCollectorDropEnded } from "../hooks/useIsCollectorDropEnded.js";
+import { COLLECTOR_DROP_BUYOUT_WINDOW_MINUTES } from "../../../_internal/shared/checkout/lanes.js";
+import { BID_PRESET_MULTIPLIERS, isBuyNowAvailable, resolveMinBid, resolveMinBidIncrement, } from "../../../_internal/shared/features/collector-drops/config.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
+const __P = {
+    p5: "p-[var(--appkit-space-5)]",
+};
+// The local `BID_ERROR_DISPLAY` map that used to live here is gone.
+//
+// It covered 5 of the ~78 codes the server can emit, and — the actual defect —
+// fell back to `result.error`, the server's own message. `result.error` is
+// always a string, so the safe literal after it was unreachable, and a 500
+// therefore printed its raw internals into the bid field: this component is
+// where `Cannot find module '../providers/db-firebase' Require stack: -
+// /var/task/.next/server/chunks/...` was shown to users.
+//
+// Its five strings already existed as `errors.codes.BID_*` in messages/en.json,
+// so nothing was lost by deleting it. `toUserMessage` resolves every code and
+// terminates in `errors.codes.UNKNOWN` — never in server text.
+/** Feature-specific last resort. Authored copy, never derived from an error. */
+const BID_FALLBACK = "Failed to place bid. Please try again.";
+const BUY_NOW_FALLBACK = "Buy Now failed. Please try again.";
+export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, tiers, minBidIncrementOverride, currency, isEnded: ssrIsEnded, collectorDropEndDate, buyNowPrice, reservePrice, bidCount: ssrBidCount, tags = [], onPlaceBid, onBuyNow, }) {
+    /*
+     * 🛑 Derived here, not trusted from the server.
+     *
+     * `isEnded` arrives baked into cached HTML. On a page cached while the collector drop
+     * was live it says "still open" indefinitely, so every gate below it — the
+     * amount field, the presets, the submit button, Buy Now — stayed enabled on a
+     * closed lot. The server prop is the INITIAL value only; `collectorDropEndDate` was
+     * already being passed in and used for display, and it is the real answer.
+     *
+     * The bid itself was never at risk: `placeBid` re-reads the product and
+     * rejects on an expired `collectorDropEndDate`. This fixes the affordance.
+     */
+    const isEnded = useIsCollectorDropEnded(collectorDropEndDate, ssrIsEnded);
+    const router = useRouter();
+    // Declared with the other hooks, never inside the early return below — a
+    // conditional hook is a render-order violation, and this component early-
+    // returns for signed-out viewers.
+    const { canSeePrices } = useCanSeePrices();
+    // Live-updates while the bid card is open — reflects other bidders'
+    // activity on this collector drop, not just the bidder's own submission.
+    const live = useLiveCollectorDropBid(productId, ssrCurrentBid, ssrBidCount, { enabled: !isEnded });
+    const currentBid = live.currentBid;
+    const bidCount = live.bidCount;
+    // Tiered, floor-raising: resolves fresh whenever the live current bid
+    // crosses a tier boundary while this modal is open.
+    const minBidIncrement = resolveMinBidIncrement(currentBid, tiers, minBidIncrementOverride);
+    // Mirrors `placeBid`'s own `hasBids`. The `currentBid` prop already falls
+    // back to `startingBid` when the collector drop has no bids, so it can't be tested
+    // for `> 0` the way the server tests the raw document field — `bidCount`, or
+    // a price that has moved past the opening one, is the equivalent signal.
+    const hasBids = bidCount > 0 || currentBid > startingBid;
+    // Same helper `placeBid` uses server-side, so the seeded amount below can
+    // never be one the server rejects.
+    const minBid = resolveMinBid(currentBid, tiers, minBidIncrementOverride, { hasBids });
+    const [bidAmount, setBidAmount] = useState(String(minBid));
+    const [stepMul, setStepMul] = useState(BID_PRESET_MULTIPLIERS[0]);
+    const [isPending, startTransition] = useTransition();
+    const [isBuyNowPending, startBuyNowTransition] = useTransition();
+    const [success, setSuccess] = useState(false);
+    // Root translator (no namespace) — `toUserMessage` passes fully-qualified
+    // `errors.codes.*` keys, and resolves them itself, so a missing key degrades
+    // to generic copy rather than throwing MISSING_MESSAGE at render time.
+    const t = useTranslations();
+    const [showLoginModal, setShowLoginModal] = useState(false);
+    /**
+     * Buy Now has no field to hang an error off — it is a standalone button, not
+     * a form input — so it needs its own slot. Without one, every domain failure
+     * (`COLLECTOR_DROP_ENDED`, `BUY_NOW_UNAVAILABLE`, rate-limit) was silent.
+     */
+    const [buyNowError, setBuyNowError] = useState(null);
+    /** Last amount the form itself wrote — see `seedAmount` below. */
+    const lastSeeded = useRef(minBid);
+    /**
+     * The bid a given preset multiplier resolves to at the live price.
+     *
+     * Anchored on `minBid` rather than `currentBid` so the first preset is always
+     * exactly the minimum acceptable bid. With bids present that is identical to
+     * the old `currentBid + increment * n`; with none it makes the opening preset
+     * the starting bid itself instead of an amount the seller never asked for.
+     */
+    function presetAmount(n) {
+        return minBid + minBidIncrement * (n - 1);
+    }
+    /**
+     * Write an amount the FORM chose (not the buyer). Tracking these separately
+     * from buyer keystrokes is what lets the live-price effect below tell "this
+     * value is still ours to update" from "the buyer typed this".
+     */
+    function seedAmount(value) {
+        lastSeeded.current = value;
+        setBidAmount(String(value));
+    }
+    function applyPreset(n) {
+        setStepMul(n);
+        seedAmount(presetAmount(n));
+    }
+    // Re-seed the amount whenever the live price moves under a preset selection.
+    //
+    // `bidAmount` was previously only ever written on mount or on click, but
+    // `currentBid` keeps updating from the `/collector-drop-bids/{id}` SSE channel while
+    // this form is open. A buyer who opened the modal, sat on it while another
+    // bidder moved the price, then hit "Place Bid" was submitting an amount now
+    // below the minimum — a guaranteed BID_AMOUNT_TOO_LOW rejection, with the
+    // preset buttons above already relabelled to the new tier so the number in
+    // the field visibly disagreed with the button that was highlighted.
+    //
+    // Custom is deliberately left alone: a typed amount is the buyer's own, and
+    // the schema + `min` attribute already surface it if the price outran them.
+    useEffect(() => {
+        if (stepMul === "custom")
+            return;
+        const next = presetAmount(stepMul);
+        if (String(next) === bidAmount)
+            return;
+        // Only follow the live price, never fight the buyer's own edits.
+        if (bidAmount !== String(lastSeeded.current))
+            return;
+        seedAmount(next);
+        // presetAmount is derived from currentBid/minBidIncrement, both in deps.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentBid, minBidIncrement, stepMul]);
+    // `currentBid` here is the LIVE SSE price, so the button hides itself the
+    // moment another bidder passes the buyout price — without a page reload, and
+    // without this component owning a second copy of the rule.
+    const buyNowAvailable = isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, reservePrice }) && !!onBuyNow;
+    const schema = placeBidSchema(minBid, formatCurrency(minBid, currency));
+    async function submitBid(amount, setFieldError) {
+        try {
+            const result = await onPlaceBid({ productId, bidAmount: amount });
+            const errorMsg = bidErrorMessage(result);
+            if (errorMsg) {
+                setFieldError("bidAmount", errorMsg);
+                return;
+            }
+            setSuccess(true);
+            // Provisional next-bid seed, corrected by the live-price effect above as
+            // soon as the SSE tick for this bid lands. It is only provisional because
+            // under proxy-bid semantics `placeBid` treats the submission as a MAXIMUM
+            // — the resulting visible price is usually lower than `amount`, and if the
+            // bid lost to a higher standing proxy cap it is higher. The old
+            // `amount + increment` was therefore rarely the next valid bid; taking the
+            // max against the live price keeps this from ever seeding below minimum.
+            setStepMul(BID_PRESET_MULTIPLIERS[0]);
+            seedAmount(resolveMinBid(Math.max(currentBid, amount), tiers, minBidIncrementOverride));
+            // The bid history list and any duplicated static current-bid/bid-count
+            // text elsewhere on this SSR'd page (info panel, page-level summary
+            // cards) are frozen server props — refresh so they reflect this bid
+            // immediately instead of waiting for the page's ISR window to roll
+            // over. The live price shown above already updated via SSE regardless.
+            router.refresh();
+        }
+        catch (err) {
+            void normalizeError(err);
+            if (isAuthError(err)) {
+                setShowLoginModal(true);
+            }
+            else {
+                // `err.message` deliberately NOT used — a thrown error here can carry
+                // server internals just as an envelope can.
+                setFieldError("bidAmount", BID_FALLBACK);
+            }
+        }
+    }
+    function bidErrorMessage(result) {
+        if (result.ok)
+            return null;
+        // No `?? result.error` tail. That is what leaked the require stack.
+        return toUserMessage(result.code, t, { fallback: BID_FALLBACK });
+    }
+    /**
+     * Show a Buy Now failure.
+     *
+     * Every failure used to be indistinguishable from success and was discarded.
+     * An auth failure never THROWS across a server-action boundary — it arrives
+     * as a code — so `isAuthError` in the catch below could never fire for it.
+     *
+     * ONLY `UNAUTHENTICATED` (401) means "sign in". `FORBIDDEN` (403) is "signed
+     * in, but not allowed" — bidding on your own collector drop, or an active
+     * `place_bids` soft ban. A login prompt for those tells the buyer to fix
+     * something that is not the problem.
+     */
+    function reportBuyNowFailure(code, _message) {
+        if (code === "UNAUTHENTICATED") {
+            setShowLoginModal(true);
+            return;
+        }
+        // `_message` is the SERVER's message and is intentionally ignored — it was
+        // the `?? message` tail here, same defect as bidErrorMessage above. Kept in
+        // the signature so callers need no change and the omission is visible.
+        void _message;
+        setBuyNowError(toUserMessage(code, t, { fallback: BUY_NOW_FALLBACK }));
+    }
+    function handleBuyNow() {
+        if (!onBuyNow)
+            return;
+        setSuccess(false);
+        setBuyNowError(null);
+        startBuyNowTransition(async () => {
+            try {
+                const result = await onBuyNow();
+                if (!result.ok) {
+                    reportBuyNowFailure(result.code, result.error);
+                    return;
+                }
+                setSuccess(true);
+                // Buy-Now writes a locked cart line, so send the buyer straight to the
+                // collector drop checkout lane to pay for it. `buyNowCollectorDrop` deliberately
+                // never touches the product document, so falling through to
+                // `router.refresh()` re-renders a byte-identical page — which is
+                // exactly what "the button does nothing" looked like.
+                if (result.data.checkoutUrl)
+                    router.push(result.data.checkoutUrl);
+                else
+                    router.refresh();
+            }
+            catch (err) {
+                void normalizeError(err);
+                reportBuyNowFailure(isAuthError(err) ? "UNAUTHENTICATED" : undefined, err instanceof Error ? err.message : undefined);
+            }
+        });
+    }
+    // A signed-out visitor cannot place a bid — `useAuthGate` already stops the
+    // submit — and this panel is the single densest money surface on the site:
+    // current bid, starting bid, minimum, increment, the +N preset chips and the
+    // Buy Now price, twelve amounts in all. Replacing the whole panel is both the
+    // honest affordance (the form was never usable) and the only version that
+    // cannot leak one of the twelve through a string prop.
+    if (!canSeePrices) {
+        return (_jsxs(Stack, { className: `${__P.p5}`, border: "subtle", gap: "sm", rounded: "xl", surface: "muted", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Bidding is for members" }), _jsx(Text, { size: "xs", color: "muted", children: "Sign in to see the current bid and place your own." }), _jsx(TextLink, { href: String(ROUTES.AUTH.LOGIN), weight: "semibold", size: "sm", children: "Sign in to bid" })] }));
+    }
+    return (_jsxs(Stack, { className: `${__P.p5}`, border: "subtle", gap: "md", rounded: "xl", surface: "muted", children: [_jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { size: "xs", color: "muted", children: hasBids ? "Current bid" : "Starting bid" }), _jsx(Text, { size: "xs", color: "muted", children: hasBids ? "Starting bid" : "Minimum bid" })] }), _jsxs(Row, { justify: "between", align: "baseline", children: [_jsx(Span, { size: "xl", weight: "bold", className: "text-primary-600 dark:text-primary-400", children: formatCurrency(currentBid, currency) }), _jsx(Span, { size: "sm", color: "muted", children: formatCurrency(hasBids ? startingBid : minBid, currency) })] }), _jsxs(Text, { size: "xs", color: "faint", children: [bidCount, " ", bidCount === 1 ? "bid" : "bids", " \u00B7 min increment", " ", formatCurrency(minBidIncrement, currency)] })] }), _jsx(LoginRequiredModal, { isOpen: showLoginModal, onClose: () => setShowLoginModal(false), message: "You need to be signed in to place a bid. Please log in or create an account to continue." }), _jsx(Form, { schema: schema, onSubmit: (e) => {
+                    // handler wired through render-prop below — keeps setFieldError in scope
+                    e.preventDefault();
+                }, children: ({ setFieldError, clearErrors, markSubmitAttempted }) => (_jsxs(Stack, { gap: "sm", children: [_jsx(FormErrorSummary, {}), _jsxs(Row, { gap: "xs", wrap: true, role: "radiogroup", "aria-label": "Bid amount preset", children: [BID_PRESET_MULTIPLIERS.map((n) => {
+                                    const amount = presetAmount(n);
+                                    const delta = amount - currentBid;
+                                    // `delta` is 0 only for the opening preset on a bid-free
+                                    // collector drop, where the minimum IS the starting bid — "+₹0" would
+                                    // read as a broken button, so name what it actually is.
+                                    const stepLabel = delta > 0 ? `+${formatCurrency(delta, currency)}` : "Minimum";
+                                    return (_jsx(Button, { type: "button", variant: stepMul === n ? "primary" : "secondary", size: "sm", role: "radio", "aria-checked": stepMul === n, disabled: isEnded || isPending, "aria-label": delta > 0
+                                            ? `Bid ${formatCurrency(amount, currency)} — ${formatCurrency(delta, currency)} above the current bid`
+                                            : `Bid ${formatCurrency(amount, currency)} — the minimum accepted bid`, onClick: () => {
+                                            clearErrors();
+                                            applyPreset(n);
+                                        }, children: _jsxs(Stack, { gap: "none", align: "center", children: [_jsx(Span, { size: "xs", weight: "semibold", children: stepLabel }), _jsx(Span, { size: "xs", color: "muted", children: formatCurrency(amount, currency) })] }) }, n));
+                                }), _jsx(Button, { type: "button", variant: stepMul === "custom" ? "primary" : "ghost", size: "sm", role: "radio", "aria-checked": stepMul === "custom", disabled: isEnded || isPending, onClick: () => setStepMul("custom"), children: "Custom" })] }), _jsx(FieldInput, { name: "bidAmount", type: "number", value: bidAmount, readOnly: stepMul !== "custom", onChange: (value) => {
+                                setBidAmount(value);
+                                clearErrors();
+                            }, placeholder: `At least ${formatCurrency(minBid, currency)}`, min: minBid, "aria-label": "Your bid amount", disabled: isEnded || isPending }), _jsx(Text, { size: "xs", color: "muted", "aria-live": "polite", children: stepMul === "custom"
+                                ? `Any amount from ${formatCurrency(minBid, currency)} up is accepted — it need not be an exact multiple of the increment.`
+                                : hasBids
+                                    ? `Minimum next bid ${formatCurrency(minBid, currency)} (current bid + ${formatCurrency(minBidIncrement, currency)} increment).`
+                                    : `Minimum opening bid ${formatCurrency(minBid, currency)} — the seller's starting bid. The ${formatCurrency(minBidIncrement, currency)} increment applies from the second bid on.` }), success && (_jsx(Text, { className: "text-success", size: "xs", children: "\u2713 Bid placed successfully!" })), !isEnded && collectorDropEndDate && (_jsxs(Text, { align: "center", size: "xs", color: "muted", children: ["Ends in ", _jsx(CountdownDisplay, { targetDate: collectorDropEndDate, format: "auto", expiredLabel: "Ended" })] })), _jsx(Button, { variant: "primary", size: "md", className: "w-full", disabled: isEnded || isPending, isLoading: isPending, type: "button", onClick: () => {
+                                // type="button" — no native submit, so unhide the summary here.
+                                markSubmitAttempted();
+                                clearErrors();
+                                const parsed = schema.safeParse({ bidAmount });
+                                if (!parsed.success)
+                                    return applyZodIssues(parsed.error.issues, setFieldError);
+                                setSuccess(false);
+                                startTransition(() => submitBid(parsed.data.bidAmount, setFieldError));
+                            }, children: isEnded ? "Collector Drop Ended" : "Place Bid" }), buyNowAvailable && (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "secondary", size: "md", className: "w-full", type: "button", disabled: isBuyNowPending || isPending, isLoading: isBuyNowPending, onClick: handleBuyNow, children: `Buy Now — ${formatCurrency(buyNowPrice, currency)}` }), buyNowError && (_jsx(Text, { align: "center", size: "xs", variant: "error", role: "alert", children: buyNowError })), _jsxs(Text, { align: "center", size: "xs", color: "muted", children: ["Skips the bidding. The collector drop stays live until you pay \u2014 complete checkout within ", COLLECTOR_DROP_BUYOUT_WINDOW_MINUTES, " minutes."] })] }))] })) }), tags.length > 0 && (_jsx(Div, { border: "default", className: "border-t", padding: "t-md", children: _jsx(Row, { wrap: true, gap: "xs", children: tags.map((tag) => (_jsx(Span, { rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", size: "xs", children: tag }, tag))) }) }))] }));
+}
+/**
+ * `PlaceBidModalButton` — opens a modal that hosts the same PlaceBidFormClient.
+ *
+ * Use this on listing-detail pages so buyers explicitly opt-in to the bid
+ * surface instead of always seeing the card inline.
+ */
+export function PlaceBidModalButton(props) {
+    const { triggerLabel = "Place a bid", triggerClassName = "", ...formProps } = props;
+    const [open, setOpen] = useState(false);
+    // Same reason as inside the form: this trigger is THE affordance a buyer sees
+    // on a cached collector drop page, so it must decide for itself rather than trust a
+    // boolean that was true whenever the HTML happened to be generated.
+    const isEnded = useIsCollectorDropEnded(props.collectorDropEndDate, props.isEnded);
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "primary", size: "md", className: triggerClassName, disabled: isEnded, onClick: () => setOpen(true), children: isEnded ? "Collector Drop Ended" : triggerLabel }), _jsx(Modal, { isOpen: open, onClose: () => setOpen(false), size: "md", title: "Place your bid", children: _jsx(PlaceBidFormClient, { ...formProps }) })] }));
+}

package/dist/features/collector-drops/components/bid-detail-fields.js

@@ -0,0 +1,103 @@
+/*
+ * WHY: All three bid listings — buyer, seller and admin — were dead ends. A
+ *      bid could be SEEN in a list and never opened, so the amount, the
+ *      collector drop it belongs to, when it was placed and whether it was outbid,
+ *      won or forfeited were only ever visible as a table row. `bid` is also
+ *      one of the three `relatedType` values with no per-record page in ANY
+ *      role, so a bid notification had nowhere to link.
+ * WHAT: The `<RecordDetailModal>` field list for a bid, built once.
+ *
+ * ## One builder, three portals
+ *
+ * The three views differ only in whether they may show the bidder's identity:
+ * a buyer sees their own bid, a seller sees who bid on their collector drop, and an
+ * admin sees everything. Writing the field list three times would be three
+ * chances to leak a bidder's name into the buyer view or to forget a field in
+ * one portal — the shape of Root Cause #38, one layer up.
+ *
+ * `maskPublicBid` already exists for the PUBLIC bid history and is unchanged;
+ * this is the dashboard equivalent, where the viewer is authenticated and the
+ * question is which role they hold.
+ *
+ * EXPORTS:
+ *   buildBidDetailFields, bidStatusBadge, type BidDetailViewer
+ *
+ * @tag domain:collector drops
+ * @tag layer:feature-util
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:UserBidsView,SellerBidsView,AdminBidsView
+ * @tag sideEffects:none
+ */
+const money = (amount, currency = "INR") => amount == null
+    ? "—"
+    : new Intl.NumberFormat("en-IN", { style: "currency", currency, maximumFractionDigits: 2 }).format(amount);
+const when = (value) => {
+    if (!value)
+        return "—";
+    const d = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(d.getTime()) ? "—" : d.toLocaleString();
+};
+/**
+ * A bid's status as a badge.
+ *
+ * `forfeited` is deliberately distinguished from `cancelled`: a forfeited bid
+ * WON and then let the payment window lapse, which is the seller's problem and
+ * the buyer's fault; a cancelled one never won anything. Collapsing them would
+ * hide exactly the distinction a support query is about.
+ */
+export function bidStatusBadge(status) {
+    switch (status) {
+        case "won":
+            return { label: "Won", tone: "success" };
+        case "active":
+            return { label: "Leading", tone: "info" };
+        case "outbid":
+            return { label: "Outbid", tone: "warning" };
+        case "forfeited":
+            return { label: "Forfeited — payment window lapsed", tone: "danger" };
+        case "cancelled":
+            return { label: "Cancelled", tone: "default" };
+        case "lost":
+            return { label: "Lost", tone: "default" };
+        default:
+            return { label: status ?? "Unknown", tone: "default" };
+    }
+}
+/**
+ * The scalar rows for a bid's detail modal.
+ *
+ * `bidderName` appears only for seller and admin. A buyer opening their OWN
+ * bid does not need to be told their own name, and the same component is used
+ * by all three, so gating here rather than at each call site is what stops a
+ * future copy-paste showing one buyer another's identity.
+ */
+export function buildBidDetailFields(bid, viewer) {
+    const rows = [
+        { label: "Collector Drop", value: bid.productTitle || bid.productId },
+        { label: "Bid amount", value: money(bid.bidAmount, bid.currency) },
+    ];
+    // Only meaningful when the bid raised a previous one.
+    if (bid.previousBidAmount != null) {
+        rows.push({ label: "Previous high bid", value: money(bid.previousBidAmount, bid.currency) });
+    }
+    if (bid.autoMaxBid != null) {
+        rows.push({ label: "Auto-bid limit", value: money(bid.autoMaxBid, bid.currency) });
+    }
+    rows.push({ label: "Placed", value: when(bid.bidDate ?? bid.createdAt) });
+    if (viewer !== "buyer") {
+        rows.push({ label: "Bidder", value: bid.userName || bid.userId });
+    }
+    // A buyout is a real bid, not a bid-free purchase — surfacing it here is
+    // what makes "why is there no ladder on this collector drop" answerable.
+    if (bid.isBuyout) {
+        rows.push({ label: "Placed via", value: "Buy Now" });
+    }
+    // The order this bid became. Present only once the win was actually paid,
+    // which is exactly the question "did they ever pay?" asks.
+    if (bid.orderId) {
+        rows.push({ label: "Order", value: bid.orderId });
+    }
+    rows.push({ label: "Bid ID", value: bid.id });
+    return rows;
+}

package/dist/features/collector-drops/components/index.d.ts

@@ -0,0 +1,7 @@
+export { MarketplaceCollectorDropCard, type MarketplaceCollectorDropCardData, type MarketplaceCollectorDropCardLabels, type MarketplaceCollectorDropCardProps, } from "./MarketplaceCollectorDropCard";
+export { MarketplaceCollectorDropGrid, type MarketplaceCollectorDropGridLabels, type MarketplaceCollectorDropGridProps, } from "./MarketplaceCollectorDropGrid";
+export { CollectorDropsListView } from "./CollectorDropsListView";
+export { CollectorDropDetailPageView } from "./CollectorDropDetailPageView";
+export type { CollectorDropDetailPageViewProps } from "./CollectorDropDetailPageView";
+export { CollectorDropBidsTable } from "./CollectorDropBidsTable";
+export type { CollectorDropBidsTableProps, CollectorDropWithBids } from "./CollectorDropBidsTable";

package/dist/features/collector-drops/components/index.js

@@ -0,0 +1,5 @@
+export { MarketplaceCollectorDropCard, } from "./MarketplaceCollectorDropCard.js";
+export { MarketplaceCollectorDropGrid, } from "./MarketplaceCollectorDropGrid.js";
+export { CollectorDropsListView } from "./CollectorDropsListView.js";
+export { CollectorDropDetailPageView } from "./CollectorDropDetailPageView.js";
+export { CollectorDropBidsTable } from "./CollectorDropBidsTable.js";

package/dist/features/collector-drops/hooks/useBids.d.ts

@@ -0,0 +1,33 @@
+import type { BidDocument } from "../schemas/firestore";
+export interface BidListResponse {
+    items: Omit<BidDocument, "userEmail">[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+export interface UseBidsParams {
+    productId: string;
+    page?: number;
+    pageSize?: number;
+}
+export interface UseBidsOptions {
+    initialData?: BidListResponse;
+    enabled?: boolean;
+}
+/**
+ * useBids
+ *
+ * Paginated, newest-first bid history for a single collector drop — backs the
+ * collector drop detail page's "Bid History" section. `/api/bids` already sorts
+ * `bidDate DESC` server-side (see `listBidsByProduct`), so no client sort
+ * is needed here.
+ */
+export declare function useBids(params: UseBidsParams, opts?: UseBidsOptions): {
+    bids: Omit<BidDocument, "userEmail">[];
+    total: number;
+    totalPages: number;
+    isLoading: boolean;
+    error: Error | null;
+};

package/dist/features/collector-drops/hooks/useBids.js

@@ -0,0 +1,32 @@
+import { useQuery } from "@tanstack/react-query";
+import { apiClient } from "../../../http/index.js";
+import { BID_ENDPOINTS } from "../../../constants/api-endpoints.js";
+/**
+ * useBids
+ *
+ * Paginated, newest-first bid history for a single collector drop — backs the
+ * collector drop detail page's "Bid History" section. `/api/bids` already sorts
+ * `bidDate DESC` server-side (see `listBidsByProduct`), so no client sort
+ * is needed here.
+ */
+export function useBids(params, opts) {
+    const { productId, page = 1, pageSize = 5 } = params;
+    const sp = new URLSearchParams();
+    sp.set("productId", productId);
+    sp.set("page", String(page));
+    sp.set("pageSize", String(pageSize));
+    const endpoint = `${BID_ENDPOINTS.LIST}?${sp.toString()}`;
+    const query = useQuery({
+        queryKey: ["bids", productId, page, pageSize],
+        queryFn: () => apiClient.get(endpoint),
+        initialData: page === 1 ? opts?.initialData : undefined,
+        enabled: opts?.enabled !== false && !!productId,
+    });
+    return {
+        bids: query.data?.items ?? [],
+        total: query.data?.total ?? 0,
+        totalPages: query.data?.totalPages ?? 1,
+        isLoading: query.isLoading,
+        error: query.error,
+    };
+}

package/dist/features/collector-drops/hooks/useCollectorDrops.d.ts

@@ -0,0 +1,51 @@
+import type { CollectorDropListResponse, CollectorDropListParams, CollectorDropItem, PublicBid } from "../types";
+import type { ProductItem } from "../../products/types";
+type CollectorDropListQuery = CollectorDropListParams | URLSearchParams | string;
+interface UseCollectorDropsOptions {
+    enabled?: boolean;
+    endpoint?: string;
+    initialData?: CollectorDropListResponse;
+    queryKeyPrefix?: string;
+    staleTime?: number;
+}
+interface UseCollectorDropDetailOptions {
+    enabled?: boolean;
+    productEndpoint?: string;
+    bidsEndpoint?: string;
+    refetchIntervalMs?: number;
+    productQueryKeyPrefix?: string;
+    bidsQueryKeyPrefix?: string;
+}
+export declare function useCollectorDrops(params?: CollectorDropListQuery, opts?: UseCollectorDropsOptions): {
+    data: CollectorDropListResponse | undefined;
+    collectorDrops: CollectorDropItem[];
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+    isLoading: boolean;
+    error: string | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<CollectorDropListResponse, Error>>;
+};
+export declare function useCollectorDrop(slug: string, opts?: {
+    enabled?: boolean;
+}): {
+    collectorDrop: CollectorDropItem | null;
+    isLoading: boolean;
+    error: string | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<CollectorDropItem | null, Error>>;
+};
+export declare function useCollectorDropBids(collectorDropSlug: string, limit?: number, opts?: {
+    enabled?: boolean;
+}): {
+    bids: import("..").BidRecord[];
+    total: number;
+    isLoading: boolean;
+    error: string | null;
+};
+export declare function useCollectorDropDetail(id: string, opts?: UseCollectorDropDetailOptions): {
+    productQuery: import("@tanstack/react-query").UseQueryResult<ProductItem | null, Error>;
+    product: ProductItem | null;
+    bidsQuery: import("@tanstack/react-query").UseQueryResult<PublicBid[], Error>;
+    bids: PublicBid[];
+};
+export {};