@mohasinac/appkit 4.55.0-next.0 → 4.56.0

package/dist/features/layout/NavbarLayout.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef, useState, useEffect, useCallback } from "react";
+import { createPortal } from "react-dom";
 import Link from "next/link.js";
 import { ChevronDown } from "lucide-react";
 import { Div, IconButton, Li, Nav, Row, Span, Ul } from "../../ui/index.js";
@@ -10,6 +11,20 @@ import { useHoldToOpen } from "./useHoldToOpen.js";
 const __O = {
     hidden: "overflow-hidden",
 };
+/**
+ * How long the panel survives the pointer leaving the trigger.
+ *
+ * It is a hover BRIDGE, and it replaces the `pt` padding the in-flow panel used
+ * to carry for the same job: the panel is portalled to `<body>` now, so there is
+ * no shared box the pointer can cross and no padding that would help. 150ms is
+ * long enough for a diagonal flick from the trigger to the first menu row and
+ * short enough that it never reads as a stuck menu.
+ */
+const CLOSE_GRACE_MS = 150;
+/** `min-w-[15rem]` on the panel — the width estimate used before it has mounted. */
+const PANEL_MIN_WIDTH_PX = 240;
+/** Keeps a right-aligned panel off the viewport edge. */
+const VIEWPORT_MARGIN_PX = 8;
 function DefaultNavItem({ item, isActive, }) {
     const activeClasses = item.highlighted
         ? "border border-primary-400/40 dark:border-secondary-400/30 text-primary-700 dark:text-secondary-400 bg-primary-50/80 dark:bg-secondary-900/30 px-[var(--appkit-space-3)] transition-colors duration-150"
@@ -18,21 +33,105 @@ function DefaultNavItem({ item, isActive, }) {
             : "text-[var(--appkit-color-text-muted)] hover:bg-surface-hover hover:text-zinc-950 dark:hover:text-white transition-colors duration-150 px-[var(--appkit-space-3)]";
     const hasChildren = Boolean(item.children && item.children.length > 0);
     /*
-     * Click-to-open state, which exists ONLY for the caret.
+     * 🛑 OPEN STATE IS JS, AND THE PANEL IS PORTALLED. Neither is a preference.
+     *
+     * This used to open on `group-hover` / `group-focus-within` with the panel
+     * `position: absolute` inside the item — and the panel was INVISIBLE on every
+     * surface that renders this navbar, because `NavbarLayout` wraps the items in
+     * `relative flex-1 overflow-hidden` and a `overflow-x-auto` scroller for its
+     * scroll arrows. An absolutely-positioned descendant cannot escape an
+     * ancestor's overflow, and `overflow-x: auto` forces `overflow-y` to `auto`
+     * as well, so the 346px panel was clipped to the 40px nav strip.
+     *
+     * That is also why it was previously measured as working: the computed style
+     * really is `display: block` with a 346px height. Clipping does not show up
+     * in a computed style — only in what you can see.
      *
-     * 🛑 Hover and focus stay pure CSS below, and this does not replace them. The
-     * panel opens on `group-hover` / `group-focus-within` with no JS at all, which
-     * is what keeps it usable for a keyboard user on Tab and before hydration.
-     * This adds the third affordance that was genuinely missing: a pointer user
-     * who CLICKS the caret expecting a menu got a navigation instead, because the
-     * caret was inside the parent `<Link>`.
+     * The only fix is to take the panel out of the clipping ancestor entirely, so
+     * it renders into `<body>` as `position: fixed` at coordinates read off the
+     * trigger. Hover and focus therefore cannot be CSS any more: there is no
+     * shared ancestor left for `:hover` to descend through. All four affordances
+     * survive — hover, focusing the trigger, the caret button, and hold-to-open
+     * on touch — and what is given up is the pre-hydration open, which was never
+     * real here: a clipped panel is not a working no-JS fallback.
+     *
+     * 🛑 Known limit, deliberately accepted rather than papered over: the panel
+     * is at the END of `<body>`, so TABBING off the caret moves to the next nav
+     * item (closing the menu) instead of into the children. The children stay
+     * reachable because the parent is a real link to a page that lists them all
+     * — the same argument the CSS version made — and Escape returns focus to the
+     * caret. Closing that properly means roving-tabindex menu semantics, which is
+     * its own change and should not ride along with a clipping fix.
      */
     const [open, setOpen] = useState(false);
+    const [coords, setCoords] = useState(null);
+    const [mounted, setMounted] = useState(false);
     const wrapRef = useRef(null);
+    const panelRef = useRef(null);
+    const closeTimerRef = useRef(null);
     const panelId = `nav-panel-${item.href.replace(/[^a-z0-9]+/gi, "-")}`;
+    // `createPortal` needs a DOM node, which does not exist during SSR.
+    useEffect(() => setMounted(true), []);
+    const cancelClose = useCallback(() => {
+        if (closeTimerRef.current) {
+            clearTimeout(closeTimerRef.current);
+            closeTimerRef.current = null;
+        }
+    }, []);
+    const openNow = useCallback(() => {
+        cancelClose();
+        setOpen(true);
+    }, [cancelClose]);
+    const scheduleClose = useCallback(() => {
+        cancelClose();
+        closeTimerRef.current = setTimeout(() => setOpen(false), CLOSE_GRACE_MS);
+    }, [cancelClose]);
+    // A pending timer outliving the item would call `setOpen` after unmount; the
+    // nav re-renders its item list whenever the listing-type flags or the session
+    // resolve.
+    useEffect(() => cancelClose, [cancelClose]);
+    /*
+     * Re-read the trigger's position whenever anything can move it.
+     *
+     * 🛑 The scroll listener is CAPTURING. The nav items live in their own
+     * horizontal scroller, so the scroll that slides the trigger sideways is that
+     * element's, not the window's — a bubbling listener on `window` never sees
+     * it, and the panel would hang over wherever the trigger used to be.
+     */
+    const measure = useCallback(() => {
+        const el = wrapRef.current;
+        if (!el)
+            return;
+        const rect = el.getBoundingClientRect();
+        const width = panelRef.current?.offsetWidth || PANEL_MIN_WIDTH_PX;
+        const maxLeft = Math.max(VIEWPORT_MARGIN_PX, window.innerWidth - width - VIEWPORT_MARGIN_PX);
+        setCoords({
+            top: rect.bottom,
+            left: Math.min(Math.max(rect.left, VIEWPORT_MARGIN_PX), maxLeft),
+        });
+    }, []);
+    useEffect(() => {
+        if (!open) {
+            setCoords(null);
+            return;
+        }
+        measure();
+        window.addEventListener("resize", measure);
+        window.addEventListener("scroll", measure, true);
+        return () => {
+            window.removeEventListener("resize", measure);
+            window.removeEventListener("scroll", measure, true);
+        };
+    }, [open, measure]);
     /*
      * Close on outside click, on Escape, and whenever the route changes.
      *
+     * 🛑 The outside test has to accept the PANEL too. It is portalled, so it is
+     * not inside `wrapRef` any more — testing the wrapper alone would treat a
+     * click on a menu link as "outside", unmount the link on `mousedown`, and the
+     * `click` that follows would land on nothing. Every menu item would silently
+     * fail to navigate.
+     *
      * The route-change close is the one that is easy to miss and the most
      * annoying to live with: the panel's own links navigate, and without this the
      * menu stays open over the page it just took you to. `isActive` is derived
@@ -42,12 +141,20 @@ function DefaultNavItem({ item, isActive, }) {
         if (!open)
             return;
         const onDown = (e) => {
-            if (!wrapRef.current?.contains(e.target))
-                setOpen(false);
+            const target = e.target;
+            if (wrapRef.current?.contains(target))
+                return;
+            if (panelRef.current?.contains(target))
+                return;
+            setOpen(false);
         };
         const onKey = (e) => {
-            if (e.key === "Escape")
-                setOpen(false);
+            if (e.key !== "Escape")
+                return;
+            setOpen(false);
+            // Escape has to return the caret focus, or the user is left tabbing from
+            // wherever inside a menu that no longer exists.
+            wrapRef.current?.querySelector("button")?.focus();
         };
         document.addEventListener("mousedown", onDown);
         document.addEventListener("keydown", onKey);
@@ -64,7 +171,7 @@ function DefaultNavItem({ item, isActive, }) {
      * one gesture is defined once. See `useHoldToOpen` for why the "did we hold"
      * flag has to be a ref.
      */
-    const holdHandlers = useHoldToOpen(() => setOpen(true), hasChildren);
+    const holdHandlers = useHoldToOpen(openNow, hasChildren);
     const trigger = (_jsxs(Link, { href: item.href, "aria-current": isActive ? "page" : undefined, className: `flex items-center gap-[var(--appkit-space-1-5)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] rounded-lg font-medium transition-colors duration-150 whitespace-nowrap ${activeClasses}${hasChildren ? " select-none touch-manipulation" : ""}`, ...holdHandlers, children: [item.icon, _jsx(Span, { children: item.label })] }));
     /*
      * The explicit narrow, not just `hasChildren`. A boolean derived from
@@ -76,29 +183,29 @@ function DefaultNavItem({ item, isActive, }) {
     if (!hasChildren || children.length === 0)
         return trigger;
     /*
-     * 🛑 Hover/focus-within CSS, not React state, and the trigger is still a real
-     * link.
-     *
-     * Two things this buys. The group stays usable without JS and without a
-     * pointer — `focus-within` opens it on Tab, so a keyboard user reaches the
-     * children. And the parent is a real link whose children are also reachable
-     * from the page it leads to, which is the progressive-enhancement shape
-     * rather than a menu that traps people.
-     *
-     * 🛑 The CARET is now a separate button, and `aria-expanded` is real rather
-     * than faked. It used to live INSIDE the parent `<Link>`, so clicking the one
+     * 🛑 The CARET is a separate button, and `aria-expanded` is real rather than
+     * faked. It used to live INSIDE the parent `<Link>`, so clicking the one
      * control that looks like a disclosure navigated away instead of disclosing —
-     * the caret was announcing an affordance the markup did not have. It is the
-     * button that owns `aria-expanded`/`aria-controls`, because it is the only
-     * part that tracks state; the hover and focus paths still open the panel
-     * without touching it, which is why the attribute can be false while the
-     * panel is visible. That asymmetry is honest: the button reports what the
-     * BUTTON did, and a hover is not a disclosure a screen reader user performed.
+     * the caret was announcing an affordance the markup did not have.
      *
-     * The `pt` on the panel is a hover bridge: without it the gap between the
-     * trigger and the panel closes the menu as the pointer crosses it.
+     * The trigger stays a real link, so a tap still follows it and a crawler
+     * still gets a destination; the menu is the affordance on top, never a
+     * replacement for it.
      */
-    return (_jsxs(Div, { ref: wrapRef, className: "relative group", children: [_jsxs(Row, { align: "center", gap: "none", children: [trigger, _jsx(IconButton, { type: "button", size: "sm", variant: "ghost", rounded: "md", "aria-expanded": open, "aria-haspopup": "true", "aria-controls": panelId, "aria-label": `${item.label} menu`, onClick: () => setOpen((v) => !v), icon: _jsx(ChevronDown, { className: `w-3.5 h-3.5 shrink-0 opacity-70 transition-transform duration-150 ${open ? "rotate-180" : ""}`, "aria-hidden": "true" }) })] }), _jsx(Div, { id: panelId, className: `absolute left-0 top-full z-20 pt-[var(--appkit-space-1)] group-hover:block group-focus-within:block ${open ? "block" : "hidden"}`, children: _jsx(Div, { surface: "elevated", border: "default", rounded: "lg", shadow: "lg", padding: "xs", children: _jsx(Ul, { className: "min-w-[15rem] list-none", children: children.map((child) => (_jsx(Li, { children: _jsxs(Link, { href: child.href, className: "flex items-start gap-[var(--appkit-space-2)] rounded-md px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] hover:bg-surface-hover transition-colors duration-150", children: [child.icon && (_jsx(Span, { className: "flex-shrink-0 mt-[var(--appkit-space-0-5)]", "aria-hidden": "true", children: child.icon })), _jsxs(Span, { className: "block", children: [_jsx(Span, { weight: "medium", className: "block", children: child.label }), child.description && (_jsx(Span, { size: "xs", color: "muted", className: "block mt-[var(--appkit-space-0-5)] whitespace-normal", children: child.description }))] })] }) }, child.href))) }) }) })] }));
+    const panel = (_jsx(Div, { ref: panelRef, id: panelId, 
+        // Positioning only — the exception the inline-style rule names, since
+        // these are runtime measurements with no representable class.
+        style: {
+            position: "fixed",
+            top: coords?.top ?? 0,
+            left: coords?.left ?? 0,
+            zIndex: "var(--appkit-z-dropdown)",
+            // Rendered-but-hidden for exactly one frame: the panel has to be in the
+            // DOM for `measure` to read its real width, and `visibility` keeps it
+            // measurable without painting it at the placeholder position.
+            visibility: coords ? "visible" : "hidden",
+        }, onPointerEnter: cancelClose, onPointerLeave: scheduleClose, onFocusCapture: cancelClose, onBlurCapture: scheduleClose, children: _jsx(Div, { surface: "elevated", border: "default", rounded: "lg", shadow: "lg", padding: "xs", children: _jsx(Ul, { className: "min-w-[15rem] list-none", children: children.map((child) => (_jsx(Li, { children: _jsxs(Link, { href: child.href, onClick: () => setOpen(false), className: "flex items-start gap-[var(--appkit-space-2)] rounded-md px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] hover:bg-surface-hover transition-colors duration-150", children: [child.icon && (_jsx(Span, { className: "flex-shrink-0 mt-[var(--appkit-space-0-5)]", "aria-hidden": "true", children: child.icon })), _jsxs(Span, { className: "block", children: [_jsx(Span, { weight: "medium", className: "block", children: child.label }), child.description && (_jsx(Span, { size: "xs", color: "muted", className: "block mt-[var(--appkit-space-0-5)] whitespace-normal", children: child.description }))] })] }) }, child.href))) }) }) }));
+    return (_jsxs(Div, { ref: wrapRef, className: "relative", onPointerEnter: openNow, onPointerLeave: scheduleClose, onFocusCapture: openNow, onBlurCapture: scheduleClose, children: [_jsxs(Row, { align: "center", gap: "none", children: [trigger, _jsx(IconButton, { type: "button", size: "sm", variant: "ghost", rounded: "md", "aria-expanded": open, "aria-haspopup": "true", "aria-controls": panelId, "aria-label": `${item.label} menu`, onClick: () => (open ? setOpen(false) : openNow()), icon: _jsx(ChevronDown, { className: `w-3.5 h-3.5 shrink-0 opacity-70 transition-transform duration-150 ${open ? "rotate-180" : ""}`, "aria-hidden": "true" }) })] }), open && mounted ? createPortal(panel, document.body) : null] }));
 }
 /**
  * NavbarLayout — generic horizontal navigation bar shell.

package/dist/features/live/components/LiveItemDetailPageView.js

@@ -26,6 +26,7 @@ import { getGroupsWithItemsForProduct } from "../../../_internal/server/features
 import { ReviewsListingPanel } from "../../reviews/components/ReviewsListingPanel.js";
 import { ListingBottomActions } from "../../products/components/ListingBottomActions.js";
 import { productImageUrls } from "../../products/schemas/firestore.js";
+import { PurchaseReviewAffordance } from "../../reviews/components/PurchaseReviewAffordance.js";
 function toDescriptionHtml(raw) {
     if (!raw)
         return "";
@@ -79,5 +80,5 @@ export async function LiveItemDetailPageView({ slug, initialProduct, renderActio
                     price: price ?? undefined,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: storeName ?? undefined,
-                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.LIVE), className: CLS_BREADCRUMB_LINK, children: "Live" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_ITEM_BADGE, children: "Live Item" }), meta?.vendorVerified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Verified Seller" })), meta?.cites && (_jsxs(Span, { color: "warning", surface: "warning-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: ["CITES: ", meta.cites] }))] }), _jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: String(p.title ?? p.slug ?? p.id), storeId: p.storeId ? String(p.storeId) : undefined, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(String(p.id))) }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), meta?.species && (_jsxs(Text, { className: "italic mt-1", color: "muted", size: "sm", children: [meta.species, meta.sex && meta.sex !== "n/a" && ` · ${meta.sex}`, meta.ageMonths !== undefined && ` · ${meta.ageMonths}mo`] }))] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), jurisdictions.length > 0 && (_jsxs(Div, { className: CLS_WARN_BOX, children: [_jsx(Text, { className: CLS_WARN_TITLE, children: "Delivery restrictions" }), _jsxs(Text, { className: CLS_WARN_BODY, children: ["This item can only be shipped to: ", jurisdictions.join(", ")] })] })), transport && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Transport" }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", children: ["Method: ", transport.method, transport.handlingFee !== undefined && (_jsx(PricesOnly, { children: ` · Handling: ${formatCurrency(transport.handlingFee, "INR")}` })), transport.insuranceIncluded && " · Insurance included"] })] })), meta?.careInfo && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Care information" }), _jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", children: meta.careInfo })] })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: toCustomSectionTabs(p.customSections) })), renderBuyBar: () => _jsx(Div, { id: "live-item-buy-bar", children: renderActions?.(product) }), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName || category || undefined, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(ListingBottomActions, { listingType: "live", anchorId: "live-item-buy-bar", price: price, currency: currency })] })] }));
+                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.LIVE), className: CLS_BREADCRUMB_LINK, children: "Live" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_ITEM_BADGE, children: "Live Item" }), meta?.vendorVerified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Verified Seller" })), meta?.cites && (_jsxs(Span, { color: "warning", surface: "warning-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: ["CITES: ", meta.cites] }))] }), _jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: String(p.title ?? p.slug ?? p.id), storeId: p.storeId ? String(p.storeId) : undefined, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(String(p.id))) }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), meta?.species && (_jsxs(Text, { className: "italic mt-1", color: "muted", size: "sm", children: [meta.species, meta.sex && meta.sex !== "n/a" && ` · ${meta.sex}`, meta.ageMonths !== undefined && ` · ${meta.ageMonths}mo`] }))] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), jurisdictions.length > 0 && (_jsxs(Div, { className: CLS_WARN_BOX, children: [_jsx(Text, { className: CLS_WARN_TITLE, children: "Delivery restrictions" }), _jsxs(Text, { className: CLS_WARN_BODY, children: ["This item can only be shipped to: ", jurisdictions.join(", ")] })] })), transport && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Transport" }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", children: ["Method: ", transport.method, transport.handlingFee !== undefined && (_jsx(PricesOnly, { children: ` · Handling: ${formatCurrency(transport.handlingFee, "INR")}` })), transport.insuranceIncluded && " · Insurance included"] })] })), meta?.careInfo && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Care information" }), _jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", children: meta.careInfo })] })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: toCustomSectionTabs(p.customSections) })), renderBuyBar: () => _jsx(Div, { id: "live-item-buy-bar", children: renderActions?.(product) }), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(PurchaseReviewAffordance, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined }), _jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName || category || undefined, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(ListingBottomActions, { listingType: "live", anchorId: "live-item-buy-bar", price: price, currency: currency })] })] }));
 }

package/dist/features/media/MediaAvatar.js

@@ -8,6 +8,6 @@ const sizeClasses = {
     xl: "w-20 h-20",
 };
 export function MediaAvatar({ src, alt, size = "md", className = "", }) {
-    return (_jsx(Div, { className: `relative ${sizeClasses[size]} overflow-hidden flex-shrink-0 ${className}`, rounded: "full", children: _jsx(MediaImage, { src: src, alt: alt, size: "avatar" }) }));
+    return (_jsx(Div, { className: `relative ${sizeClasses[size]} overflow-hidden flex-shrink-0 ${className}`, rounded: "full", children: _jsx(MediaImage, { src: src, alt: alt, size: "avatar", objectFit: "cover" }) }));
 }
 export default MediaAvatar;

package/dist/features/media/MediaImage.d.ts

@@ -24,7 +24,24 @@ export interface MediaImageProps {
      * one slide the visitor can actually see.
      */
     fetchPriority?: "high" | "low" | "auto";
-    /** CSS object-fit applied to the underlying img element. Defaults to `'cover'`. */
+    /**
+     * CSS object-fit applied to the underlying img element. Defaults to
+     * `'contain'`.
+     *
+     * 🛑 THE DEFAULT CHANGED on 2026-10-20, from `'cover'`. `cover` fills the
+     * box by cropping whatever does not fit, which is right for a photograph
+     * that continues past its frame and wrong for this catalogue: most of its
+     * imagery is a product shot centred on white, where the crop takes the
+     * product and leaves the background. `contain` fits the whole subject
+     * inside the shape and letterboxes the remainder against the tile's own
+     * surface colour.
+     *
+     * Pass `'cover'` explicitly where a FILLED box is the component's contract
+     * rather than a preference — a full-bleed backdrop with text over it, or a
+     * circular avatar. Three call sites do: `MediaAvatar`, and the slide and
+     * card backgrounds in `HeroCarousel`. A letterboxed backdrop there would put
+     * the dim overlay and the headline on bare surface.
+     */
     objectFit?: "cover" | "contain";
     /**
      * Emoji or text to show when `src` is undefined.

package/dist/features/media/MediaImage.js

@@ -67,7 +67,7 @@ function resolveSrcSet(input) {
         .filter(Boolean)
         .join(", ");
 }
-export function MediaImage({ src, alt, size = "card", priority = false, loading, fetchPriority, objectFit = "cover", fallback, className, rounded, shadow, style, sources, onError, }) {
+export function MediaImage({ src, alt, size = "card", priority = false, loading, fetchPriority, objectFit = "contain", fallback, className, rounded, shadow, style, sources, onError, }) {
     const [hasError, setHasError] = useState(false);
     const [isLoaded, setIsLoaded] = useState(false);
     const [retryCount, setRetryCount] = useState(0);

package/dist/features/media/messages/en.json

@@ -1,67 +1,67 @@
-{
-  "mediaEditor": {
-    "cropTitle": "Crop Image",
-    "cropInstruction": "Drag to reposition. Use the zoom slider or +/- keys to zoom.",
-    "cropPreviewAlt": "Preview",
-    "cropZoom": "Zoom",
-    "cropZoomIn": "Zoom in",
-    "cropZoomOut": "Zoom out",
-    "cropRotateLeft": "Rotate left 90°",
-    "cropRotateRight": "Rotate right 90°",
-    "cropFlipH": "Flip horizontally",
-    "cropFlipV": "Flip vertically",
-    "cropWarningTitle": "Low zoom",
-    "cropWarningMessage": "Zoom in for better quality.",
-    "cropPosition": "Position",
-    "cropReset": "Reset",
-    "cropSave": "Save Crop",
-    "cropCancel": "Cancel",
-    "trimTitle": "Trim Video",
-    "trimInstruction": "Set the start and end times, then click Trim.",
-    "trimStart": "Start",
-    "trimEnd": "End",
-    "trimDuration": "Duration: {duration}s",
-    "trimQuality": "Quality",
-    "trimQualityLow": "Low",
-    "trimQualityMedium": "Medium",
-    "trimQualityHigh": "High",
-    "trimSave": "Trim Video",
-    "trimSkip": "Skip",
-    "trimming": "Trimming…",
-    "thumbnailTitle": "Select Thumbnail",
-    "thumbnailInstruction": "Seek to the frame you want to use as the thumbnail.",
-    "thumbnailCapture": "Use This Frame",
-    "thumbnailSkip": "Skip",
-    "thumbnailCapturing": "Capturing…",
-    "thumbnailUploading": "Uploading…",
-    "cropSuccess": "Image cropped",
-    "trimSuccess": "Video trimmed",
-    "thumbnailSuccess": "Thumbnail saved",
-    "cropError": "Failed to crop image",
-    "trimError": "Failed to trim video",
-    "thumbnailError": "Failed to capture thumbnail",
-    "editImage": "Edit / Crop",
-    "editVideo": "Trim / Thumbnail"
-  },
-  "camera": {
-    "takePhoto": "Take Photo",
-    "startRecording": "Start Recording",
-    "stopRecording": "Stop Recording",
-    "flipCamera": "Flip Camera",
-    "switchToCamera": "Use Camera",
-    "switchToUpload": "Upload File",
-    "cameraError": "Camera unavailable",
-    "permissionDenied": "Camera permission denied. Please allow access in your browser settings.",
-    "notSupported": "Camera is not supported on this device",
-    "starting": "Starting camera..."
-  },
-  "upload": {
-    "change": "Change",
-    "remove": "Remove",
-    "clickToUpload": "Click to upload",
-    "uploading": "Uploading…",
-    "uploadingProgress": "Uploading {progress}%…",
-    "replaceFile": "Replace file",
-    "chooseFile": "Choose file to upload"
-  }
-}
+{
+  "mediaEditor": {
+    "cropTitle": "Crop Image",
+    "cropInstruction": "Drag to reposition. Use the zoom slider or +/- keys to zoom.",
+    "cropPreviewAlt": "Preview",
+    "cropZoom": "Zoom",
+    "cropZoomIn": "Zoom in",
+    "cropZoomOut": "Zoom out",
+    "cropRotateLeft": "Rotate left 90°",
+    "cropRotateRight": "Rotate right 90°",
+    "cropFlipH": "Flip horizontally",
+    "cropFlipV": "Flip vertically",
+    "cropWarningTitle": "Low zoom",
+    "cropWarningMessage": "Zoom in for better quality.",
+    "cropPosition": "Position",
+    "cropReset": "Reset",
+    "cropSave": "Save Crop",
+    "cropCancel": "Cancel",
+    "trimTitle": "Trim Video",
+    "trimInstruction": "Set the start and end times, then click Trim.",
+    "trimStart": "Start",
+    "trimEnd": "End",
+    "trimDuration": "Duration: {duration}s",
+    "trimQuality": "Quality",
+    "trimQualityLow": "Low",
+    "trimQualityMedium": "Medium",
+    "trimQualityHigh": "High",
+    "trimSave": "Trim Video",
+    "trimSkip": "Skip",
+    "trimming": "Trimming…",
+    "thumbnailTitle": "Select Thumbnail",
+    "thumbnailInstruction": "Seek to the frame you want to use as the thumbnail.",
+    "thumbnailCapture": "Use This Frame",
+    "thumbnailSkip": "Skip",
+    "thumbnailCapturing": "Capturing…",
+    "thumbnailUploading": "Uploading…",
+    "cropSuccess": "Image cropped",
+    "trimSuccess": "Video trimmed",
+    "thumbnailSuccess": "Thumbnail saved",
+    "cropError": "Failed to crop image",
+    "trimError": "Failed to trim video",
+    "thumbnailError": "Failed to capture thumbnail",
+    "editImage": "Edit / Crop",
+    "editVideo": "Trim / Thumbnail"
+  },
+  "camera": {
+    "takePhoto": "Take Photo",
+    "startRecording": "Start Recording",
+    "stopRecording": "Stop Recording",
+    "flipCamera": "Flip Camera",
+    "switchToCamera": "Use Camera",
+    "switchToUpload": "Upload File",
+    "cameraError": "Camera unavailable",
+    "permissionDenied": "Camera permission denied. Please allow access in your browser settings.",
+    "notSupported": "Camera is not supported on this device",
+    "starting": "Starting camera..."
+  },
+  "upload": {
+    "change": "Change",
+    "remove": "Remove",
+    "clickToUpload": "Click to upload",
+    "uploading": "Uploading…",
+    "uploadingProgress": "Uploading {progress}%…",
+    "replaceFile": "Replace file",
+    "chooseFile": "Choose file to upload"
+  }
+}

package/dist/features/orders/schemas/firestore.d.ts

@@ -8,6 +8,7 @@ import type { ListingType } from "../../products/types";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 import type { ReturnReason } from "../../../_internal/shared/features/orders/return-reasons";
 import type { ReturnCustodyState } from "../../../_internal/shared/features/returns/custody";
+import type { ActualShipmentCost, SelectedShippingQuote, ShippingReconciliation } from "../../../_internal/shared/shipping/quote";
 import type { Encrypted, Plaintext } from "../../../security/encrypted";
 export interface OrderSourceStandard {
     path: "standard";
@@ -449,7 +450,7 @@ export interface OrderDocument extends BaseDocument {
     platformFee?: number;
     depositAmount?: number;
     codRemainingAmount?: number;
-    /** COD handling fee charged to the buyer: max(codHandlingFeeMin, subtotal × codHandlingFeePercent / 100). Only set when paymentMethod === "cod". */
+    /** COD handling fee charged to the buyer: min(subtotal × codHandlingFeePercent / 100, codHandlingFeeCap). Only set when paymentMethod === "cod". */
     codHandlingFee?: number;
     /** Buyer opted into gift wrapping at checkout (unchecked by default). */
     giftWrapAddon?: boolean;
@@ -550,6 +551,43 @@ export interface OrderDocument extends BaseDocument {
     shippingMethod?: ShippingMethod;
     shippingCarrier?: string;
     trackingUrl?: string;
+    /**
+     * The courier the BUYER picked at checkout, and what they were charged for
+     * it, frozen at order creation.
+     *
+     * 🛑 Stored, never recomputed. Carrier rates move hourly, so re-quoting at
+     * reconciliation time would compare the seller's real spend against a price
+     * nobody was ever charged, and the buyer's refund would depend on when a job
+     * happened to run. Same reasoning as `sourceContext`.
+     *
+     * `chargedRate` is the ₹50-rounded figure and is the ONLY one that is
+     * billed; `rawRate` is kept for the audit trail and is never rendered.
+     * Absent on orders placed before the picker shipped, and on any order whose
+     * seller ships manually — so every reader must treat absence as "no quote
+     * was taken", never as zero.
+     */
+    selectedShippingQuote?: SelectedShippingQuote;
+    /**
+     * What the seller actually spent on postage, recorded at dispatch.
+     *
+     * Written by the seller's ship action. Its presence is what makes an order
+     * eligible for reconciliation; its absence means the parcel has not been
+     * dispatched or the seller has not told us what it cost.
+     */
+    actualShipmentCost?: ActualShipmentCost;
+    /**
+     * The outcome of comparing the two above — computed ONCE, when the seller
+     * dispatches, and then left alone.
+     *
+     * 🛑 Its presence is the idempotency key for the points credit. Crediting is
+     * an append to a ledger, so a job that ran twice would pay the buyer twice
+     * and nothing downstream could tell the difference between that and two
+     * genuine savings. Every writer must check this field is unset before
+     * writing a `shipping_saving` entry.
+     */
+    shippingReconciliation?: ShippingReconciliation & {
+        reconciledAt: Date;
+    };
     /**
      * The carrier's label PDF, once a shipment has been booked.
      *

package/dist/features/points/repository/points.repository.d.ts

@@ -0,0 +1,81 @@
+import { type PointsEntryKind, type PointsLedgerEntry } from "../schemas/firestore";
+/**
+ * The points ledger: append-only entries, and a balance that is their sum.
+ *
+ * ## 🛑 Every mutation is a TRANSACTION over the ledger and the mirror
+ *
+ * `users/{uid}.pointsBalance` is a denormalised mirror of the ledger, kept so
+ * a page can show a balance in one read instead of scanning an unbounded
+ * collection. Root Cause #42 is explicit about what happens to a mirror the
+ * moment one write path forgets it, and this mirror guards MONEY-SHAPED value:
+ * drift here either hands a buyer points nobody credited, or swallows points
+ * they earned.
+ *
+ * So the entry and the mirror move together or not at all, and the mirror is
+ * incremented from the value read INSIDE the transaction rather than from a
+ * figure the caller passed in — two concurrent credits that each read "53" and
+ * each wrote "106" would lose one of them.
+ *
+ * `redeem()` additionally re-checks the balance inside the transaction. A
+ * caller that validated the balance a moment earlier is working from a read
+ * that may already be stale, and the failure mode is a negative balance — the
+ * one state this ledger must never reach.
+ */
+export declare class PointsRepository {
+    /**
+     * Current balance, from the mirror.
+     *
+     * 🛑 Falls back to summing the ledger when the mirror is absent, rather than
+     * returning 0. An unseeded or pre-feature user document has no
+     * `pointsBalance`, and answering "0" for someone with real credits would
+     * silently deny them money they are owed. Absence means "not computed yet",
+     * never "nothing".
+     */
+    getBalance(userId: string): Promise<number>;
+    /**
+     * The authoritative balance, computed from the entries themselves.
+     *
+     * Unbounded by nature, so it is NOT the read path — it exists to repair the
+     * mirror and to let a reconciliation job prove the two agree.
+     */
+    sumLedger(userId: string): Promise<number>;
+    /**
+     * Append an entry and move the mirror, atomically.
+     *
+     * Returns the new balance so a caller can report it without a second read.
+     */
+    append(input: {
+        userId: string;
+        kind: PointsEntryKind;
+        amount: number;
+        description: string;
+        orderId?: string;
+        adminReason?: string;
+        actorUid?: string;
+    }): Promise<{
+        entryId: string;
+        balance: number;
+    }>;
+    /**
+     * Spend points against an order.
+     *
+     * 🛑 `points` is given POSITIVE and stored NEGATIVE. The caller is saying
+     * "spend 53", and making them pass `-53` is an invitation to pass `53` by
+     * mistake and credit somebody instead of charging them.
+     *
+     * Re-reads the balance inside the transaction and refuses rather than going
+     * negative — see the class header.
+     */
+    redeem(input: {
+        userId: string;
+        points: number;
+        orderId: string;
+        description: string;
+    }): Promise<{
+        entryId: string;
+        balance: number;
+    }>;
+    /** Most recent entries first, for the buyer's own points page. */
+    listForUser(userId: string, limit?: number): Promise<PointsLedgerEntry[]>;
+}
+export declare const pointsRepository: PointsRepository;