@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/features/categories/components/CategoryDetailPageView.js

@@ -7,8 +7,8 @@ import { categoriesRepository, productRepository, storeRepository, } from "../..
 import { Container, Div, Heading, ImageMosaic, Main, MOSAIC_MIN, Section, Span, SplitTile, Stack, Text } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { RichTextRenderer } from "../../../ui/rich-text/RichTextRenderer.js";
-import { OverflowRow } from "../../../ui/index.js";
 import { resolveTaxonomyVisual } from "../utils/taxonomy-visual.js";
+import { SubcategoryCardRow } from "./SubcategoryCardRow.js";
 import { CategoryDetailTabs } from "./CategoryDetailTabs.js";
 import { CategoryGrid } from "./CategoryGrid.js";
 import { CategoryHighlightsAndFaqSection } from "./CategoryHighlightsAndFaqSection.js";
@@ -27,6 +27,7 @@ import { safeRead } from "../../../errors/safe-read.js";
 import { breadcrumbJsonLd, collectionPageJsonLd, faqJsonLd, } from "../../../seo/json-ld.js";
 import { toStoreListItem } from "../../../_internal/server/features/stores/adapters.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
+import { productImageUrls } from "../../products/schemas/firestore.js";
 const __O = {
     hidden: "overflow-hidden",
 };
@@ -49,17 +50,73 @@ const __W = "max-w-7xl mx-auto";
  * Admin surfaces that genuinely need both still show both —
  * `CategoryTableColumns` renders "own (total)" explicitly.
  */
-function toSubcategoryItems(children) {
+/*
+ * 🛑 products + auctions, SUMMED.
+ *
+ * `metrics.productCount` EXCLUDES auctions — `Tally` keeps `productIds` and
+ * `auctionIds` as separate arrays and writes `auctionCount` /
+ * `totalAuctionCount` alongside, so the comparable "how much is in here"
+ * figure is the sum of both. Reading only the product half understated every
+ * subcategory holding an auction, and understated it silently: the chip
+ * showed a plausible smaller number rather than anything that looked wrong.
+ *
+ * This page already derives its own header figures correctly that way
+ * (`productCount` and `auctionCount` resolved separately further down); this
+ * was the one place that took the product half for the whole.
+ *
+ * Prefer the rollup (`total*`) over the own-count for both halves, because a
+ * chip is a navigational promise about the whole subtree you are about to
+ * enter, not about what happens to be filed at that exact node. Shared by
+ * `toSubcategoryItems` (the chip's badge count) and the scroller's own
+ * filter below, so the two can't disagree about what "has listings" means.
+ */
+function listingCountFor(child) {
+    const products = child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0;
+    const auctions = child.metrics?.totalAuctionCount ?? child.metrics?.auctionCount ?? 0;
+    return products + auctions;
+}
+/**
+ * Direct children → the Subcategory card row's items.
+ *
+ * `descendants` is the SAME array the page already fetched, passed in so each
+ * card can carry its own direct children's names for the filter. One level
+ * only — see `SubcategoryCardRow`'s header for why matching the whole subtree
+ * would surface cards for names the visitor never sees.
+ */
+function toSubcategoryItems(children, descendants) {
+    /*
+     * Grandchildren indexed by parent in ONE pass. The alternative — filtering
+     * `descendants` inside the map — is O(children x descendants), and on the
+     * spinning-tops root that is 5 x ~1,200 per render for a list that never
+     * changes.
+     *
+     * 🛑 Keyed on `parentIds[last]`, the IMMEDIATE parent. `parentIds` holds the
+     * full ancestor chain, so testing `.includes(child.id)` would match every
+     * descendant at any depth and quietly turn the one-level rule into a
+     * whole-subtree match.
+     */
+    const childNamesByParent = new Map();
+    for (const d of descendants) {
+        const parent = d.parentIds?.[d.parentIds.length - 1];
+        if (!parent)
+            continue;
+        const list = childNamesByParent.get(parent);
+        if (list)
+            list.push(d.name);
+        else
+            childNamesByParent.set(parent, [d.name]);
+    }
     return children.map((child) => {
-        const count = child.metrics?.totalProductCount ?? child.metrics?.productCount ?? 0;
+        const count = listingCountFor(child);
         return {
             id: child.id,
-            label: child.name,
+            name: child.name,
             // Omitted rather than rendered as 0 — `count` is "not counted" when
-            // undefined, and a chip reading "0" invites a click that lands on an
+            // undefined, and a card reading "0" invites a click that lands on an
             // empty page.
             count: count > 0 ? count : undefined,
             href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(child.slug)),
+            childNames: childNamesByParent.get(child.id) ?? [],
             ...resolveTaxonomyVisual(child),
         };
     });
@@ -114,7 +171,7 @@ export async function CategoryDetailPageView({ slug }) {
         // Four of the ten tabs used to have no count at all and could never hide.
         categoriesIn
             ? listingTabCounts(CATEGORY_PAGE_TABS, { categoriesIn })
-            : Promise.resolve({}),
+            : Promise.resolve({ available: {}, total: {} }),
         // SB-UNI-D — bundles fetched from the categories collection. We pull
         // all active bundle rows; the carousel filters by category affinity.
         categoriesIn
@@ -216,9 +273,76 @@ export async function CategoryDetailPageView({ slug }) {
             })
             : Promise.resolve([]),
     ]);
+    // 🛑 SAME TIER ONLY. `rootSiblingCategories` spans the whole root subtree —
+    // siblings AND cousins across every depth — so without a tier check this
+    // rendered deeper descendants (children, grandchildren) as "related",
+    // which reads as a second, redundant Subcategories row rather than a set
+    // of actual peers. A category with no siblings at its own tier correctly
+    // shows nothing here; the tier-grouped descendant tabs above already cover
+    // "what's below this category".
     const relatedCategories = rootSiblingCategories
-        .filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"))
+        .filter((c) => c.id !== category?.id &&
+        (!c.categoryType || c.categoryType === "category") &&
+        c.tier === category?.tier)
         .slice(0, RELATED_CATEGORY_LIMIT);
+    // 🛑 ONLY children that actually have something in them. A direct child
+    // with zero listings anywhere in its own subtree is a dead end — clicking
+    // it opens an empty category page — so it's dropped from the chip row
+    // rather than rendered with no count badge. `listingCountFor` reads the
+    // ROLLUP (own + descendants), so a child that merely has no listings of
+    // its OWN but does further down is correctly kept.
+    const directChildrenWithListings = childCategories
+        .filter((c) => c.tier === (category?.tier ?? 0) + 1)
+        .filter((c) => listingCountFor(c) > 0);
+    /*
+     * The ancestor chain as cards, root first.
+     *
+     * 🛑 `ancestor.id` is used as the slug, which is correct HERE and is not a
+     * general licence: categories are one of this codebase's "pure slug"
+     * collections (`id === slug`), so the two are interchangeable for a category
+     * row. `CategoryAncestor` carries only `{id, name, tier}` — no slug field —
+     * so the alternative would be a lookup per ancestor for a value already in
+     * hand.
+     *
+     * `tier` comes from the stored ancestor rather than the array index: the
+     * index is only the depth if the chain is complete, and a chain that skipped
+     * a tier would silently relabel every level below it (the closure-skip case
+     * CLAUDE.md records under the counters invariant).
+     */
+    /*
+     * `CategoryAncestor` is `{id, name, tier}` and carries no display block, so
+     * the artwork is looked up in rows this page ALREADY fetched —
+     * `rootSiblingCategories` spans the whole root subtree, which is where an
+     * ancestor lives. A miss simply yields no visual and the card falls back,
+     * which is why this is a plain lookup and not another read.
+     */
+    const rowsById = new Map();
+    for (const c of [...rootSiblingCategories, ...childCategories]) {
+        if (c?.id)
+            rowsById.set(c.id, c);
+    }
+    /*
+     * 🛑 The IMMEDIATE parent only — one card, never the chain.
+     *
+     * `ancestors` is ordered root-first, so the last entry is the direct parent
+     * and everything before it is a grandparent. Rendering the whole ladder put
+     * four cards on a tier-4 page for a path the breadcrumb at the top of the
+     * page already spells out in full, and the uncles/grandparents are not
+     * places you step to from here — the one move this row needs to afford is
+     * "up one".
+     */
+    const immediateParent = (category?.ancestors ?? []).at(-1);
+    const parentLadder = immediateParent
+        ? [
+            {
+                id: immediateParent.id,
+                name: immediateParent.name,
+                href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(immediateParent.id)),
+                level: immediateParent.tier,
+                ...resolveTaxonomyVisual(rowsById.get(immediateParent.id) ?? null),
+            },
+        ]
+        : [];
     // Stores tab — stores whose storeCategory is this category or ANY descendant.
     //
     // `storeCategory` is a single slug with no ancestor chain (unlike a product's
@@ -282,18 +406,36 @@ export async function CategoryDetailPageView({ slug }) {
          * and it cast `createdAt` through `as unknown as string` where the adapter
          * converts a Timestamp properly.
          */
-        .map((s) => toStoreListItem(s));
+        .map((s) => toStoreListItem(s))
+        // 🛑 `storeCategory` is a one-time "primarily sells this" tag, not proof
+        // of current stock — a store can match the category and still have
+        // nothing listed right now (the exact shape of the empty-store report
+        // this filter closes). Listing it here sends a visitor into a store page
+        // with nothing to buy, so only stores that actually have products are
+        // kept. `totalProducts` is the denormalised `stats.totalProducts`
+        // counter, incremented atomically on create/delete — cheap to read here,
+        // unlike a per-store query.
+        .filter((s) => (s.totalProducts ?? 0) > 0);
     const storeCount = categoryStores.length;
     // `tabCounts` is keyed by tabSlug and already covers every listing type plus
     // bundles; `stores` is added here because this page resolves its store list
     // eagerly to render the tab body anyway.
-    const counts = { ...tabCounts, stores: storeCount };
+    // Two maps, not one: the BADGE is what the default (available) scope will
+    // render, while HIDING must stay keyed on the total — a tab whose rows have
+    // all ended still has a browsable archive behind the Ended/All scopes.
+    // `stores` is added to both because this page resolves its store list
+    // eagerly to render the tab body anyway, and a store has no availability
+    // scope of its own.
+    const counts = { ...tabCounts.available, stores: storeCount };
+    const totals = { ...tabCounts.total, stores: storeCount };
     // Header pills read the same numbers the tabs do. `?? 0` is safe here (a pill
     // simply doesn't render) — unlike the tab bar, where an unknown count must
     // stay visible rather than collapse to "hide me".
-    const productCount = counts.products ?? category?.metrics?.totalProductCount ?? category?.metrics?.productCount ?? 0;
-    const auctionCount = counts.auctions ?? category?.metrics?.totalAuctionCount ?? category?.metrics?.auctionCount ?? 0;
-    const preOrderCount = counts["pre-orders"] ?? 0;
+    // Header pills read TOTALS, deliberately: "47 products" is a statement about
+    // what this category holds, not about what one scope is currently showing.
+    const productCount = totals.products ?? category?.metrics?.totalProductCount ?? category?.metrics?.productCount ?? 0;
+    const auctionCount = totals.auctions ?? category?.metrics?.totalAuctionCount ?? category?.metrics?.auctionCount ?? 0;
+    const preOrderCount = totals["pre-orders"] ?? 0;
     /*
      * G3b — OWN vs CHILDREN, so one number stops answering two questions.
      *
@@ -333,7 +475,7 @@ export async function CategoryDetailPageView({ slug }) {
     const mosaicImages = hasCover
         ? []
         : (productsResult?.items ?? [])
-            .map((row) => row.mainImage ?? row.images?.[0] ?? null)
+            .map((row) => row.mainImage || productImageUrls(row.images)[0] || null)
             .filter((src) => !!src)
             .slice(0, 5);
     const hasMosaic = mosaicImages.length >= MOSAIC_MIN;
@@ -430,7 +572,7 @@ export async function CategoryDetailPageView({ slug }) {
     const ldFaq = category?.faqs && category.faqs.length > 0
         ? faqJsonLd(category.faqs.map((f) => ({ question: f.question, answer: f.answer })))
         : null;
-    return (_jsxs(Main, { children: [_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldBreadcrumb) } }), _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldCollection) } }), ldFaq && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldFaq) } })), _jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), !hasCover && hasMosaic && (_jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", padding: "x-md", children: _jsx(Div, { padding: "t-lg", children: _jsx(ImageMosaic, { images: mosaicImages, alt: `${category?.name ?? slug} on LetItRip` }) }) })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsx(BreadcrumbTrail, { crumbs: trail, className: "mb-4", tone: hasCover ? "on-media" : "default" }), category?.id && _jsx(LastCategoryBeacon, { categoryId: category.id }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), showCountSplit && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "muted", size: "xs", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [ownHere.toLocaleString(), " here \u00B7 ", inSubcategories.toLocaleString(), " in subcategories"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), contentBody && contentBody.trim().length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(RichTextRenderer, { html: contentBody }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), compositions.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "section", children: _jsxs(Stack, { gap: "md", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "What it is made of" }), _jsx(ModelCompositionPanel, { compositions: compositions, hrefForPart: (slot, tail) => String(ROUTES.PUBLIC.PART_DETAIL(slot, tail)) })] }) }) })), (() => {
+    return (_jsxs(Main, { children: [_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldBreadcrumb) } }), _jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldCollection) } }), ldFaq && (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(ldFaq) } })), _jsxs(Section, { className: `relative ${__O.hidden} ${hasCover ? "min-h-[220px] md:min-h-[280px]" : "bg-[var(--appkit-color-bg)]"}`, children: [hasCover && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "absolute inset-0", children: _jsx(MediaImage, { src: coverImage, alt: "", size: "banner" }) }), _jsx(Div, { surface: "overlay-md", className: "absolute inset-0" })] })), !hasCover && hasMosaic && (_jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", padding: "x-md", children: _jsx(Div, { padding: "t-lg", children: _jsx(ImageMosaic, { images: mosaicImages, alt: `${category?.name ?? slug} on LetItRip` }) }) })), _jsxs(Div, { className: "relative z-10 max-w-7xl mx-auto", paddingY: hasCover ? "y-3xl" : "y-xl", padding: "x-md", children: [_jsx(BreadcrumbTrail, { crumbs: trail, className: "mb-4", tone: hasCover ? "on-media" : "default" }), category?.id && _jsx(LastCategoryBeacon, { categoryId: category.id }), _jsx(Heading, { color: "inverse", level: 1, className: `mb-2 ${hasCover ? "" : "text-[var(--appkit-color-text)]"}`, size: "3xl", mdSize: "4xl", weight: "bold", children: category?.name ?? slug }), category?.description && typeof category.description === "string" && !category.description.startsWith("{") && (_jsx(Text, { color: hasCover ? "inverse" : "muted", className: `max-w-2xl mb-4 ${hasCover ? "/80" : ""}`, size: "base", children: category.description })), _jsxs(Row, { wrap: true, gap: "sm", children: [productCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: "inverse", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "bg-primary/10 text-primary-700 dark:text-primary-400", rounded: "full", padding: "pill-sm-tall", children: [productCount.toLocaleString(), " ", productCount === 1 ? "product" : "products"] })), showCountSplit && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "muted", size: "xs", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [ownHere.toLocaleString(), " here \u00B7 ", inSubcategories.toLocaleString(), " in subcategories"] })), auctionCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "warning", surface: hasCover ? undefined : "warning-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [auctionCount.toLocaleString(), " ", auctionCount === 1 ? "auction" : "auctions"] })), preOrderCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "info", surface: hasCover ? undefined : "info-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [preOrderCount.toLocaleString(), " ", preOrderCount === 1 ? "pre-order" : "pre-orders"] })), storeCount > 0 && (_jsxs(Span, { layout: "inline-flex", gap: "xs", color: hasCover ? "inverse" : "success", surface: hasCover ? undefined : "success-surface", size: "xs", weight: "medium", className: hasCover ? "bg-[rgba(255,255,255,0.2)] backdrop-blur-sm" : "", rounded: "full", padding: "pill-sm-tall", children: [storeCount.toLocaleString(), " ", storeCount === 1 ? "store" : "stores"] }))] })] })] }), category?.hasbroName && (_jsx(Section, { padding: "y-md", children: _jsx(Container, { size: "xl", children: _jsxs(Row, { gap: "md", align: "center", wrap: true, children: [category.hasbroCoverImage && (_jsx(MediaImage, { src: category.hasbroCoverImage, alt: `${category.hasbroName} logo`, size: "thumbnail", className: "h-12 w-auto flex-shrink-0" })), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", weight: "medium", children: "Also known as" }), _jsx(Text, { weight: "semibold", children: category.hasbroName }), _jsxs(Text, { size: "xs", color: "muted", children: ["The same wave, named differently outside Japan \u2014 Takara-Tomy releases it as ", category.name, ", Hasbro as ", category.hasbroName, ". Both names find these listings."] })] })] }) }) })), contentBody && contentBody.trim().length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(RichTextRenderer, { html: contentBody }) }) })), _jsx(CategoryHighlightsAndFaqSection, { highlights: category?.highlights, faqs: category?.faqs }), compositions.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "section", children: _jsxs(Stack, { gap: "md", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "What it is made of" }), _jsx(ModelCompositionPanel, { compositions: compositions, hrefForPart: (slot, tail) => String(ROUTES.PUBLIC.PART_DETAIL(slot, tail)) })] }) }) })), (() => {
                 if (category?.tier !== 0)
                     return null;
                 const branches = childCategories.filter((c) => c.tier === 1);
@@ -455,10 +597,5 @@ export async function CategoryDetailPageView({ slug }) {
                                 imageUrl: coverOf(b),
                                 countLabel: countOf(b),
                             } }) }) }));
-            })(), childCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "inline", children: (() => {
-                        const directChildren = childCategories.filter((c) => c.tier === (category?.tier ?? 0) + 1);
-                        if (directChildren.length === 0)
-                            return null;
-                        return (_jsxs(Div, { padding: "b-2xs", children: [_jsx(Text, { size: "xs", color: "muted", weight: "medium", className: "mb-[var(--appkit-space-1-5)]", children: "Subcategories" }), _jsx(OverflowRow, { items: toSubcategoryItems(directChildren), ariaLabel: "Subcategories", variant: "nav", placeholder: "Browse subcategories", searchPlaceholder: "Search subcategories\u2026", noResultsText: "No matching subcategory" })] }));
-                    })() }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
+            })(), directChildrenWithListings.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-b", children: _jsx(Div, { className: __W, padding: "inline", children: _jsxs(Div, { padding: "b-2xs", children: [parentLadder.length > 0 && (_jsx(Div, { padding: "b-2xs", children: _jsx(SubcategoryCardRow, { items: parentLadder, label: "Parent category" }) })), _jsx(SubcategoryCardRow, { items: toSubcategoryItems(directChildrenWithListings, childCategories) })] }) }) })), _jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(CategoryDetailTabs, { categorySlug: slug, categoryId: category?.id, initialProductsData: productsResult ?? undefined, initialBundles: bundlesResult ?? [], initialStores: categoryStores, counts: counts, totals: totals, enabledListingTypes: enabledListingTypes(settings), enabledCategoryTypes: enabledCategoryTypes(settings) }) }) }), groupedListings.length > 0 && (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "xl", children: _jsx(GroupedListingsCarousel, { groups: groupedListings }) }) })), relatedCategories.length > 0 && (_jsx(Section, { border: "subtle", surface: "default", className: "border-t", padding: "y-lg", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 2, className: "mb-4", size: "xl", weight: "semibold", children: "Related Categories" }), _jsx(CategoryGrid, { categories: relatedCategories, getHref: (c) => String(ROUTES.PUBLIC.CATEGORY_DETAIL(c.slug)) })] }) }))] }));
 }

package/dist/features/categories/components/CategoryDetailTabs.d.ts

@@ -17,9 +17,15 @@ export interface CategoryDetailTabsProps {
      * were structurally uncountable and could never hide (Root Cause #61).
      */
     counts?: Record<string, number | undefined>;
+    /**
+     * Every published row per tab, all availability scopes. Drives hide-at-zero
+     * and the "N ended — show all" hint; see `ListingTabCountResult`. Omitted,
+     * it falls back to `counts`, i.e. the pre-split behaviour.
+     */
+    totals?: Record<string, number | undefined>;
     /** Enabled listing types (e.g. ["standard","auction","pre-order"]). When omitted, all tabs shown. */
     enabledListingTypes?: string[];
     /** Enabled category types (e.g. ["category","brand","bundle"]). When omitted, all tabs shown. */
     enabledCategoryTypes?: string[];
 }
-export declare function CategoryDetailTabs({ categorySlug, categoryId, initialProductsData, initialBundles, initialStores, counts, enabledListingTypes, enabledCategoryTypes, }: CategoryDetailTabsProps): React.JSX.Element;
+export declare function CategoryDetailTabs({ categorySlug, categoryId, initialProductsData, initialBundles, initialStores, counts, totals, enabledListingTypes, enabledCategoryTypes, }: CategoryDetailTabsProps): React.JSX.Element;

package/dist/features/categories/components/CategoryDetailTabs.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { EmptyState, Tabs, TabsList, TabsTrigger } from "../../../ui/index.js";
+import { AvailabilityScopeHint } from "../../products/components/AvailabilityScopeHint.js";
 import { CategoryProductsListing } from "./CategoryProductsListing.js";
 import { AuctionsIndexListing } from "../../products/components/AuctionsIndexListing.js";
 import { PreOrdersIndexListing } from "../../pre-orders/components/PreOrdersIndexListing.js";
@@ -29,6 +30,21 @@ const TAB_TYPE_MAP = {
     bundles: { kind: "category", type: "bundle" },
     stores: { kind: "entity", type: "stores" },
 };
+/**
+ * The listing types a tab spans, for the availability-scope hint.
+ *
+ * Derived from `TAB_TYPE_MAP` rather than hand-written: that map is already
+ * built from `ALL_LISTING_TYPES`, so a tenth type is covered without a second
+ * enumeration (Root Cause #61). The combined Art & Stickers tab is the one
+ * entry that spans two, and `GENERIC_TAB_LISTING_TYPES` already says so.
+ */
+function typesForTab(id) {
+    const generic = GENERIC_TAB_LISTING_TYPES[id];
+    if (generic)
+        return generic;
+    const mapping = TAB_TYPE_MAP[id];
+    return mapping?.kind === "listing" ? [mapping.type] : [];
+}
 /** Listing types rendered by the shared products listing rather than a dedicated one. */
 const GENERIC_TAB_LISTING_TYPES = {
     [pluginFor("standard").tabSlug]: ["standard"],
@@ -37,9 +53,25 @@ const GENERIC_TAB_LISTING_TYPES = {
     [pluginFor("live").tabSlug]: ["live"],
     // The combined Art & Stickers tab spans both types under the `art` slug.
     [pluginFor("art").tabSlug]: ART_STICKERS_LISTING_TYPES,
+    /*
+     * Spares render generically — there is nothing type-specific to show beyond
+     * a product grid, unlike an auction (countdown, bid history) or a prize draw
+     * (entries remaining).
+     *
+     * 🛑 This map is hand-written and a missing entry is a tab you can CLICK that
+     * renders an empty panel. It is covered — `audit-tab-body-coverage` exists
+     * for precisely this, after `CategoryDetailTabs` showed a blank panel for
+     * four types while `BrandDetailTabs` silently dropped the same four — so the
+     * eleventh type will be caught rather than discovered.
+     */
+    [pluginFor("spares").tabSlug]: ["spares"],
 };
-export function CategoryDetailTabs({ categorySlug, categoryId, initialProductsData, initialBundles = [], initialStores = [], counts, enabledListingTypes, enabledCategoryTypes, }) {
+export function CategoryDetailTabs({ categorySlug, categoryId, initialProductsData, initialBundles = [], initialStores = [], counts, totals, enabledListingTypes, enabledCategoryTypes, }) {
     const countFor = (id) => counts?.[id];
+    // Falls back to the badge when no totals map is supplied, so a caller that
+    // has not been migrated keeps today's hide behaviour rather than hiding
+    // everything.
+    const totalFor = (id) => totals?.[id] ?? counts?.[id];
     const visibleTabs = CATEGORY_PAGE_TABS.filter((t) => {
         const mapping = TAB_TYPE_MAP[t.id];
         if (mapping) {
@@ -52,11 +84,13 @@ export function CategoryDetailTabs({ categorySlug, categoryId, initialProductsDa
                     return false;
             }
         }
-        // Hide a tab only when its count is known and explicitly zero. `undefined`
-        // now means the count query FAILED (every tab is counted), so keeping it
-        // visible is the fail-open choice: an empty tab is a far smaller error than
-        // hiding a tab that holds real listings.
-        const count = countFor(t.id);
+        // 🛑 TOTAL, not the badge. The badge counts what the default (available)
+        // scope renders, and a tab whose rows have all ended badges 0 while still
+        // holding a browsable archive behind the Ended/All scopes — hiding it
+        // would strand that archive. `undefined` still means the count query
+        // FAILED, so the tab stays visible: an empty tab is a far smaller error
+        // than hiding a tab that holds real listings (Root Cause #59).
+        const count = totalFor(t.id);
         return count === undefined || count > 0;
     });
     const firstTabId = (visibleTabs[0]?.id ?? "products");
@@ -66,5 +100,5 @@ export function CategoryDetailTabs({ categorySlug, categoryId, initialProductsDa
     if (visibleTabs.length === 0) {
         return (_jsx(EmptyState, { title: "Nothing listed here yet", description: "This category has no active listings right now. Check back soon." }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(Tabs, { value: activeTab, onChange: (v) => setActiveTab(v), className: "mb-6", children: _jsx(TabsList, { children: visibleTabs.map((t) => (_jsx(TabsTrigger, { value: t.id, badge: countFor(t.id), children: t.label }, t.id))) }) }), GENERIC_TAB_LISTING_TYPES[activeTab] && (_jsx(CategoryProductsListing, { categorySlug: categorySlug, categoryId: categoryId, listingTypes: GENERIC_TAB_LISTING_TYPES[activeTab], initialData: activeTab === pluginFor("standard").tabSlug ? initialProductsData : undefined })), activeTab === pluginFor("auction").tabSlug && (_jsx(AuctionsIndexListing, { categorySlug: categorySlug })), activeTab === pluginFor("pre-order").tabSlug && (_jsx(PreOrdersIndexListing, { categorySlug: categorySlug })), activeTab === pluginFor("prize-draw").tabSlug && (_jsx(PrizeDrawsIndexListing, { categorySlug: categorySlug })), activeTab === "bundles" && (_jsx(CategoryBundlesListing, { initialBundles: initialBundles })), activeTab === "stores" && (_jsx(CategoryStoresListing, { stores: initialStores }))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(Tabs, { value: activeTab, onChange: (v) => setActiveTab(v), className: "mb-6", children: _jsx(TabsList, { children: visibleTabs.map((t) => (_jsx(TabsTrigger, { value: t.id, badge: countFor(t.id), children: t.label }, t.id))) }) }), _jsx(AvailabilityScopeHint, { total: totalFor(activeTab), available: countFor(activeTab), types: typesForTab(activeTab) }), GENERIC_TAB_LISTING_TYPES[activeTab] && (_jsx(CategoryProductsListing, { categorySlug: categorySlug, categoryId: categoryId, listingTypes: GENERIC_TAB_LISTING_TYPES[activeTab], initialData: activeTab === pluginFor("standard").tabSlug ? initialProductsData : undefined })), activeTab === pluginFor("auction").tabSlug && (_jsx(AuctionsIndexListing, { categorySlug: categorySlug })), activeTab === pluginFor("pre-order").tabSlug && (_jsx(PreOrdersIndexListing, { categorySlug: categorySlug })), activeTab === pluginFor("prize-draw").tabSlug && (_jsx(PrizeDrawsIndexListing, { categorySlug: categorySlug })), activeTab === "bundles" && (_jsx(CategoryBundlesListing, { initialBundles: initialBundles })), activeTab === "stores" && (_jsx(CategoryStoresListing, { stores: initialStores }))] }));
 }

package/dist/features/categories/components/CategoryGrid.js

@@ -18,7 +18,16 @@ export function CategoryCard({ category, href, onClick, className = "", }) {
     // own-node-only productCount so a parent category's card shows the same
     // "N products" a visitor actually sees once they open the page.
     const productCount = category.metrics?.totalProductCount ?? category.metrics?.productCount ?? category.productCount ?? 0;
-    const inner = (_jsxs(Stack, { className: "h-full", children: [_jsxs(Div, { surface: "muted", className: `relative aspect-[4/3] w-full ${__O.hidden} flex-shrink-0`, children: [(category.display?.mosaicImages?.length ?? 0) >= MOSAIC_MIN ? (_jsx(ImageMosaic, { images: category.display.mosaicImages, alt: category.name, className: "h-full w-full" })) : category.display?.coverImage ? (_jsx(MediaImage, { src: category.display.coverImage, alt: category.name, size: "card", className: "transition-transform duration-300 group-hover:scale-105" })) : category.display?.color ? (_jsx(DynamicBgDiv, { color: category.display.color, className: "h-full w-full opacity-80" })) : null, category.display?.icon && (_jsx(Row, { textSize: "4xl", className: "absolute inset-0", align: "center", justify: "center", children: category.display.icon })), category.isFeatured && (_jsx(Span, { size: "xs", className: CLS_FEATURED_DOT, children: "\u2605" }))] }), _jsxs(Stack, { className: `flex-1 ${__P.p3}.5`, children: [_jsx(Text, { color: "inverse", className: `leading-snug text-[var(--appkit-color-text)] dark:`, truncate: 2, size: "sm", weight: "semibold", children: category.name }), category.description && (_jsx(Text, { className: `mt-1 flex-1`, color: "muted", truncate: 2, size: "xs", children: category.description })), _jsxs(Row, { className: "mt-2", align: "center", justify: "between", gap: "sm", children: [_jsxs(Text, { size: "xs", color: "faint", children: [productCount.toLocaleString(), " ", productCount === 1 ? "item" : "items"] }), _jsxs(Span, { layout: "inline-flex", gap: "xs", size: "xs", weight: "medium", border: "default", className: "group-hover:bg-primary group-hover:border-primary group-hover:text-white transition-colors", rounded: "md", padding: "pill-sm-tall", color: "muted", children: ["Browse ", _jsx(ArrowRight, { className: "h-3 w-3" })] })] })] })] }));
+    /*
+     * Is a real picture going to render in the image area? Drives the emoji
+     * overlay below, which must not paint over artwork. Deliberately mirrors the
+     * first two branches of the chain rather than being derived from it — the
+     * `color` branch is a flat tint, which an emoji on top of is still the
+     * intended look.
+     */
+    const hasArtwork = (category.display?.mosaicImages?.length ?? 0) >= MOSAIC_MIN ||
+        Boolean(category.display?.coverImage);
+    const inner = (_jsxs(Stack, { className: "h-full", children: [_jsxs(Div, { surface: "muted", className: `relative aspect-[4/3] w-full ${__O.hidden} flex-shrink-0`, children: [(category.display?.mosaicImages?.length ?? 0) >= MOSAIC_MIN ? (_jsx(ImageMosaic, { images: category.display.mosaicImages, alt: category.name, className: "h-full w-full" })) : category.display?.coverImage ? (_jsx(MediaImage, { src: category.display.coverImage, alt: category.name, size: "card", className: "transition-transform duration-300 group-hover:scale-105" })) : category.display?.color ? (_jsx(DynamicBgDiv, { color: category.display.color, className: "h-full w-full opacity-80" })) : null, category.display?.icon && !hasArtwork && (_jsx(Row, { textSize: "4xl", className: "absolute inset-0", align: "center", justify: "center", children: category.display.icon })), category.isFeatured && (_jsx(Span, { size: "xs", className: CLS_FEATURED_DOT, children: "\u2605" }))] }), _jsxs(Stack, { className: `flex-1 ${__P.p3}.5`, children: [_jsx(Text, { color: "inverse", className: `leading-snug text-[var(--appkit-color-text)] dark:`, truncate: 2, size: "sm", weight: "semibold", children: category.name }), category.description && (_jsx(Text, { className: `mt-1 flex-1`, color: "muted", truncate: 2, size: "xs", children: category.description })), _jsxs(Row, { className: "mt-2", align: "center", justify: "between", gap: "sm", children: [_jsxs(Text, { size: "xs", color: "faint", children: [productCount.toLocaleString(), " ", productCount === 1 ? "item" : "items"] }), _jsxs(Span, { layout: "inline-flex", gap: "xs", size: "xs", weight: "medium", border: "default", className: "group-hover:bg-primary group-hover:border-primary group-hover:text-white transition-colors", rounded: "md", padding: "pill-sm-tall", color: "muted", children: ["Browse ", _jsx(ArrowRight, { className: "h-3 w-3" })] })] })] })] }));
     const cardClass = `group relative flex flex-col overflow-hidden rounded-xl border border-neutral-200 bg-[var(--appkit-color-surface)] border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] shadow-sm transition hover:shadow-md h-full ${className}`;
     if (href) {
         return (_jsx(Link, { href: href, className: cardClass, children: inner }));

package/dist/features/categories/components/PriceGuidanceHint.d.ts

@@ -0,0 +1,29 @@
+import React from "react";
+export interface PriceGuidanceHintProps {
+    /** Leaf category id/slug the listing is filed under. */
+    categoryId: string;
+    currency?: string;
+    className?: string;
+}
+/**
+ * The seller-facing price hint `description-template/route.ts`'s own
+ * docstring names as "C1's job, from a surface that knows who is asking" —
+ * renders the inherited competitor-derived market band beside the price
+ * field, on the SELLER'S own tax basis (the `/price-guidance` endpoint does
+ * that conversion server-side; this component only formats what it returns).
+ *
+ * Mounted via `ProductForm`'s `renderPriceGuidance` slot rather than fetched
+ * unconditionally inside the form — `ProductForm` has no data-fetching of its
+ * own (every app-specific concern is a render-prop), and this component is
+ * seller/admin-only, not something the form itself should assume a caller
+ * wants.
+ *
+ * 🛑 NEVER mount this on a public page (category/brand detail). A
+ * competitor-derived market band is exactly the "a neighbouring surface
+ * publishes the range" leak the guest price gate exists to close (CLAUDE.md
+ * § "Guest price gating"), even though the figure is advisory rather than a
+ * real listing price — which is also why `/price-guidance` itself is
+ * seller/admin/moderator-gated, not a public, edge-cached endpoint like its
+ * `description-template` sibling.
+ */
+export declare function PriceGuidanceHint({ categoryId, currency, className, }: PriceGuidanceHintProps): React.JSX.Element | null;

package/dist/features/categories/components/PriceGuidanceHint.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useQuery } from "@tanstack/react-query";
+import { PricesOnly, Stack, Text } from "../../../ui/index.js";
+import { apiClient } from "../../../http/index.js";
+import { CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+function unwrap(res) {
+    const body = res?.data ?? res;
+    return body && typeof body === "object" && "guidance" in body ? body : null;
+}
+/**
+ * The seller-facing price hint `description-template/route.ts`'s own
+ * docstring names as "C1's job, from a surface that knows who is asking" —
+ * renders the inherited competitor-derived market band beside the price
+ * field, on the SELLER'S own tax basis (the `/price-guidance` endpoint does
+ * that conversion server-side; this component only formats what it returns).
+ *
+ * Mounted via `ProductForm`'s `renderPriceGuidance` slot rather than fetched
+ * unconditionally inside the form — `ProductForm` has no data-fetching of its
+ * own (every app-specific concern is a render-prop), and this component is
+ * seller/admin-only, not something the form itself should assume a caller
+ * wants.
+ *
+ * 🛑 NEVER mount this on a public page (category/brand detail). A
+ * competitor-derived market band is exactly the "a neighbouring surface
+ * publishes the range" leak the guest price gate exists to close (CLAUDE.md
+ * § "Guest price gating"), even though the figure is advisory rather than a
+ * real listing price — which is also why `/price-guidance` itself is
+ * seller/admin/moderator-gated, not a public, edge-cached endpoint like its
+ * `description-template` sibling.
+ */
+export function PriceGuidanceHint({ categoryId, currency = "INR", className = "", }) {
+    const query = useQuery({
+        queryKey: ["category-price-guidance", categoryId],
+        enabled: categoryId.length > 0,
+        staleTime: 60 * 60 * 1000,
+        queryFn: async () => unwrap(await apiClient.get(CATEGORY_ENDPOINTS.PRICE_GUIDANCE(categoryId))),
+    });
+    const guidance = query.data?.guidance;
+    const basisNote = query.data?.basisNote;
+    if (!guidance?.market)
+        return null;
+    const { median, p25, p75 } = guidance.market;
+    const fmt = (n) => formatCurrency(n, currency);
+    // p25/p75 are independently optional (see CategoryPriceGuidance's own
+    // docstring) — a range renders only when BOTH are present, never a
+    // half-range that would misreport the band's shape.
+    const range = p25 !== undefined && p75 !== undefined ? ` (${fmt(p25)}–${fmt(p75)})` : "";
+    /*
+     * `<PricesOnly>` rather than `<GatedPrice>`: this is advisory guidance
+     * BESIDE the seller's own price input, not a listing's primary price, so a
+     * viewer who may not see prices should get nothing here — a "Sign in to see
+     * price" prompt inside a seller form would be nonsense. In practice it
+     * never renders for a guest anyway, because the data source
+     * (`/api/categories/[id]/price-guidance`) is seller/admin/moderator-gated
+     * and 403s before there is a number to format; the wrapper makes that
+     * guarantee visible at the render site instead of implied by the route.
+     */
+    return (_jsx(PricesOnly, { children: _jsxs(Stack, { gap: "xs", className: className, children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Market median:", " ", _jsx(Text, { as: "span", weight: "medium", color: "primary", children: fmt(median) }), range, basisNote?.suffix ? ` ${basisNote.suffix}` : ""] }), basisNote?.note && _jsx(Text, { size: "xs", color: "faint", children: basisNote.note })] }) }));
+}

package/dist/features/categories/components/SubcategoryCardRow.d.ts

@@ -0,0 +1,27 @@
+import React from "react";
+export interface SubcategoryCardItem {
+    id: string;
+    name: string;
+    href: string;
+    /** Rollup listing count. Omitted when zero — a card reading "0" invites a dead click. */
+    count?: number;
+    /** A real picture, when the row resolved one. */
+    imageUrl?: string;
+    /** An emoji, when that is all the row has. Never passed to an `<img>`. */
+    emoji?: string;
+    /** Direct children's names — searched, never rendered. */
+    childNames?: readonly string[];
+    /**
+     * Depth in the forest: 0 is a root, 1 its child, and so on.
+     *
+     * Rendered as a small "L0 / L1 / L2" marker so a row of ancestors reads as a
+     * LADDER rather than as five unrelated cards. Omitted on the subcategory row
+     * itself, where every card is the same depth by construction and the marker
+     * would be noise repeated N times.
+     */
+    level?: number;
+}
+export declare function SubcategoryCardRow({ items, label, }: {
+    items: readonly SubcategoryCardItem[];
+    label?: string;
+}): React.JSX.Element | null;