@mohasinac/appkit 4.51.0 → 4.52.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.51.0",
-  "head": "8e22d42a3cf524b03f860462c5fe567bfbb621de",
+  "version": "4.52.0",
+  "head": "5e6e4777891284de76aa0d646e556f8aee0ff76e",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-14T12:00:13.325Z"
+  "builtAt": "2026-10-14T12:39:32.737Z"
 }

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

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useCallback, useMemo } from "react";
 import { useCategoriesFiltered } from "../hooks/useCategories.js";
+import { CATEGORY_TABS, DEFAULT_CATEGORY_TAB, matchesCategoryTab, } from "../constants/category-tabs.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { Button, Div, Grid, ListingFilterDrawer, ListingToolbar, Pagination, Row, Stack, Text, StickyToolbar } from "../../../ui/index.js";
 import { CategoryCard } from "./CategoryGrid.js";
@@ -20,11 +21,16 @@ const PAGE_SIZE = 24;
 function renderCategoryGrid(props) {
     const { isLoading, categories, view, activeSearch, activeTab, brandsOnly } = props;
     const isBrandView = activeTab === "brands" || brandsOnly;
+    /* The empty state names the tab the visitor is actually on. It said
+     * "categories" on all five, so an empty Parts tab reported the wrong thing. */
+    const noun = brandsOnly
+        ? "brands"
+        : (CATEGORY_TABS.find((t) => t.key === activeTab)?.label ?? "categories").toLowerCase();
     if (isLoading) {
         return (_jsx(Grid, { cols: "categoryCards", gap: "md", children: Array.from({ length: 10 }).map((_, i) => (_jsxs(Div, { className: `${__O.hidden} animate-pulse`, border: "subtle", rounded: "xl", children: [_jsx(Div, { className: "aspect-[4/3]", surface: "subtle" }), _jsxs(Stack, { className: `${__P.p3}.5`, gap: "sm", children: [_jsx(Div, { className: "h-3.5 w-3/4", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-full", surface: "subtle", rounded: "default" })] })] }, i))) }));
     }
     if (categories.length === 0) {
-        return (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: activeSearch ? `No ${isBrandView ? "brands" : "categories"} matching "${activeSearch}"` : isBrandView ? "No brands found" : "No categories found" }));
+        return (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: activeSearch ? `No ${noun} matching "${activeSearch}"` : `No ${noun} found` }));
     }
     if (view === "list") {
         return (_jsx(Stack, { className: "divide-y divide-zinc-100 divide-[var(--appkit-color-border-subtle)]", border: "subtle", rounded: "xl", children: categories.map((category) => _jsx(CategoryCard, { category: category, href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category.slug)) }, category.id)) }));
@@ -131,12 +137,21 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
     const commitSearch = useCallback(() => {
         table.set(TABLE_KEYS.QUERY, searchInput.trim());
     }, [searchInput, table]);
-    // Tab state — "all" | "categories" | "brands" (not used when brandsOnly=true)
-    const activeTab = brandsOnly ? "brands" : (table.get(TABLE_KEYS.TAB) || "all");
-    const isBrandParam = brandsOnly ? true :
-        activeTab === "brands" ? true :
-            activeTab === "categories" ? false :
-                undefined;
+    /*
+     * Tab state. Five tabs, no "All" — see `category-tabs.ts`: "All" was the
+     * default and it was what rendered 1,185 undifferentiated rows.
+     */
+    const rawTab = brandsOnly ? "brands" : table.get(TABLE_KEYS.TAB) || DEFAULT_CATEGORY_TAB;
+    const activeTab = (CATEGORY_TABS.some((t) => t.key === rawTab)
+        ? rawTab
+        : DEFAULT_CATEGORY_TAB);
+    /*
+     * 🛑 The fetch stays unfiltered (`?flat=true`) and the TABS partition that one
+     * cached response — a per-tab query would turn one request into five for the
+     * same data. `isBrand` is still sent for the brands tab because the API has a
+     * dedicated clause for it; everything else is partitioned below.
+     */
+    const isBrandParam = activeTab === "brands" ? true : undefined;
     const switchTab = (key) => {
         table.set(TABLE_KEYS.TAB, key);
     };
@@ -144,6 +159,8 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
         q: table.get(TABLE_KEYS.QUERY) || undefined,
         isFeatured: table.get(TABLE_KEYS.IS_FEATURED) === "true" || undefined,
         isBrand: isBrandParam,
+        // The tab partition — applied before pagination inside the hook.
+        predicate: (c) => matchesCategoryTab(c, activeTab),
         rootOnly: table.get("rootOnly") === "true" || undefined,
         tier: getNumericParam(table, "tier"),
         minProductCount: getNumericParam(table, "minItemCount"),
@@ -153,11 +170,7 @@ export function CategoriesIndexListing({ brandsOnly = false }) {
         pageSize: PAGE_SIZE,
     });
     const activeSearch = table.get(TABLE_KEYS.QUERY) || "";
-    const TABS = [
-        { key: "all", label: "All" },
-        { key: "categories", label: "Categories" },
-        { key: "brands", label: "Brands" },
-    ];
+    const TABS = CATEGORY_TABS;
     return (_jsxs(Div, { className: "min-h-screen", children: [!brandsOnly && (_jsx(Row, { gap: "xs", border: "default", className: "border-b mb-2", children: TABS.map((tab) => (_jsx(Button, { variant: "ghost", type: "button", onClick: () => switchTab(tab.key), paddingX: "md", paddingY: "y-xs-tall", textSize: "sm", weight: "medium", className: [
                         "transition-colors border-b-2 -mb-px rounded-none",
                         activeTab === tab.key

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

@@ -4,6 +4,7 @@ import { ArrowRight } from "lucide-react";
 import { Div, Grid, Row, Span, Stack, Text } from "../../../ui/index.js";
 import { DynamicBgDiv } from "../../../ui/components/DynamicBgDiv.js";
 import { MediaImage } from "../../media/MediaImage.js";
+import { ImageMosaic, MOSAIC_MIN } from "../../../ui/components/ImageMosaic.js";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
@@ -17,7 +18,7 @@ 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?.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" })] })] })] })] }));
+    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" })] })] })] })] }));
     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/constants/category-tabs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * How the categories index splits into tabs — ONE definition of each predicate.
+ *
+ * ## 🛑 The index shows ROOTS, not everything
+ *
+ * `/categories` used to render the whole flat forest: 1,185 rows, of which 752
+ * are part leaves and 220 are model leaves. A visitor met a wall of names with
+ * no sense of where they were. The Categories tab now shows the SIX roots and
+ * you walk down — parent to child to leaf — which is how every catalogue of
+ * this shape is browsed, and what the category detail page already supports
+ * (it fetches every descendant and renders them tier-grouped).
+ *
+ * ## 🛑 Parts cannot be matched on `categoryType`
+ *
+ * Brands, franchises and bundles each carry a discriminator. Parts deliberately
+ * DO NOT — `gen-category-parts.mjs` omits `categoryType` because 92 files read
+ * it and a new value opts a row out of every path that works. So a part is
+ * identified by its ANCESTRY: a leaf whose chain passes through one of the four
+ * `*-parts` nodes. That is a fact about where it lives, not a flag that can
+ * drift from it.
+ *
+ * ## Why the tabs partition ONE payload
+ *
+ * The listing already fetches `?flat=true` once. Deriving all five tabs from
+ * that single cached response costs no extra request — a per-tab query would
+ * turn one fetch into five for the same data.
+ *
+ * @tag domain:categories
+ * @tag layer:constants
+ * @tag pattern:shared-literal
+ * @tag sideEffects:none
+ */
+/** The tier-2 nodes every part leaf hangs beneath. */
+export declare const PART_PARENT_IDS: readonly string[];
+export type CategoryTabKey = "categories" | "brands" | "franchises" | "parts" | "bundles";
+export interface CategoryTabDef {
+    key: CategoryTabKey;
+    label: string;
+}
+/**
+ * 🛑 No "All" tab. It was the default and it was the problem — it is what
+ * rendered 1,185 undifferentiated rows. Every tab here answers a question
+ * ("which parts do you have?"); "all" answers none of them.
+ */
+export declare const CATEGORY_TABS: readonly CategoryTabDef[];
+export declare const DEFAULT_CATEGORY_TAB: CategoryTabKey;
+/** The minimum shape these predicates read. */
+interface TabbableCategory {
+    categoryType?: string | null;
+    tier?: number | null;
+    parentIds?: readonly string[] | null;
+    isLeaf?: boolean | null;
+}
+/** A leaf whose ancestry passes through a `*-parts` node. */
+export declare function isPartCategory(c: TabbableCategory): boolean;
+/**
+ * Does this row belong on the given tab?
+ *
+ * 🛑 The Categories tab is ROOTS ONLY (`tier === 0`). Brands, franchises and
+ * bundles are tier-0 too but carry a discriminator, so the type check has to
+ * come first or they would appear under Categories as well.
+ */
+export declare function matchesCategoryTab(c: TabbableCategory, tab: CategoryTabKey): boolean;
+export {};

package/dist/features/categories/constants/category-tabs.js

@@ -0,0 +1,88 @@
+/**
+ * How the categories index splits into tabs — ONE definition of each predicate.
+ *
+ * ## 🛑 The index shows ROOTS, not everything
+ *
+ * `/categories` used to render the whole flat forest: 1,185 rows, of which 752
+ * are part leaves and 220 are model leaves. A visitor met a wall of names with
+ * no sense of where they were. The Categories tab now shows the SIX roots and
+ * you walk down — parent to child to leaf — which is how every catalogue of
+ * this shape is browsed, and what the category detail page already supports
+ * (it fetches every descendant and renders them tier-grouped).
+ *
+ * ## 🛑 Parts cannot be matched on `categoryType`
+ *
+ * Brands, franchises and bundles each carry a discriminator. Parts deliberately
+ * DO NOT — `gen-category-parts.mjs` omits `categoryType` because 92 files read
+ * it and a new value opts a row out of every path that works. So a part is
+ * identified by its ANCESTRY: a leaf whose chain passes through one of the four
+ * `*-parts` nodes. That is a fact about where it lives, not a flag that can
+ * drift from it.
+ *
+ * ## Why the tabs partition ONE payload
+ *
+ * The listing already fetches `?flat=true` once. Deriving all five tabs from
+ * that single cached response costs no extra request — a per-tab query would
+ * turn one fetch into five for the same data.
+ *
+ * @tag domain:categories
+ * @tag layer:constants
+ * @tag pattern:shared-literal
+ * @tag sideEffects:none
+ */
+/** The tier-2 nodes every part leaf hangs beneath. */
+export const PART_PARENT_IDS = [
+    "category-original-parts",
+    "category-metal-parts",
+    "category-burst-parts",
+    "category-x-parts",
+];
+/**
+ * 🛑 No "All" tab. It was the default and it was the problem — it is what
+ * rendered 1,185 undifferentiated rows. Every tab here answers a question
+ * ("which parts do you have?"); "all" answers none of them.
+ */
+export const CATEGORY_TABS = [
+    { key: "categories", label: "Categories" },
+    { key: "brands", label: "Brands" },
+    { key: "franchises", label: "Franchises" },
+    { key: "parts", label: "Parts" },
+    { key: "bundles", label: "Bundles" },
+];
+export const DEFAULT_CATEGORY_TAB = "categories";
+const typeOf = (c) => String(c.categoryType ?? "");
+/** A leaf whose ancestry passes through a `*-parts` node. */
+export function isPartCategory(c) {
+    if (typeOf(c))
+        return false; // brand / bundle / franchise / sublisting
+    return (c.parentIds ?? []).some((p) => PART_PARENT_IDS.includes(String(p)));
+}
+/**
+ * Does this row belong on the given tab?
+ *
+ * 🛑 The Categories tab is ROOTS ONLY (`tier === 0`). Brands, franchises and
+ * bundles are tier-0 too but carry a discriminator, so the type check has to
+ * come first or they would appear under Categories as well.
+ */
+export function matchesCategoryTab(c, tab) {
+    const type = typeOf(c);
+    switch (tab) {
+        case "brands":
+            return type === "brand";
+        case "franchises":
+            return type === "franchise";
+        case "bundles":
+            return type === "bundle";
+        case "parts":
+            return isPartCategory(c);
+        case "categories":
+            /*
+             * A plain, top-level category. Parts are excluded by the type check
+             * being empty AND tier 0 — no part leaf is tier 0 — but a reader should
+             * not have to derive that, so the root test carries the meaning.
+             */
+            return type === "" && Number(c.tier ?? -1) === 0;
+        default:
+            return false;
+    }
+}

package/dist/features/categories/hooks/useCategories.d.ts

@@ -20,6 +20,20 @@ export interface CategoriesFilteredParams {
     sort?: string;
     page?: number;
     pageSize?: number;
+    /**
+     * Tab partition, applied BEFORE pagination.
+     *
+     * 🛑 Before, not after — the hook paginates internally, so filtering the
+     * returned page would show a short grid and a page count for a different,
+     * larger set. It is a predicate rather than another flag because the Parts
+     * tab cannot be expressed as one: a part carries no `categoryType` and is
+     * identified by its ancestry (`category-tabs.ts`).
+     *
+     * Not part of the react-query key, deliberately — the FETCH is the same
+     * unfiltered `?flat=true` for every tab, so keying on it would mint five
+     * cache entries for one response.
+     */
+    predicate?: (c: CategoryItem) => boolean;
 }
 /** API-driven for structured filters; text search + pagination done in hook (Firestore substring limitation). */
 export declare function useCategoriesFiltered(params?: CategoriesFilteredParams): {

package/dist/features/categories/hooks/useCategories.js

@@ -45,6 +45,8 @@ export function useCategoriesFiltered(params = {}) {
             items = items.filter((c) => c.name.toLowerCase().includes(lq) || (c.description ?? "").toLowerCase().includes(lq));
         if (params.isBrand === false)
             items = items.filter((c) => !c.isBrand);
+        if (params.predicate)
+            items = items.filter(params.predicate);
         if (minProductCount !== undefined)
             items = items.filter((c) => (c.productCount ?? 0) >= minProductCount);
         if (maxProductCount !== undefined)

package/dist/features/categories/types/index.d.ts

@@ -10,6 +10,18 @@ export interface CategoryDisplay {
     coverImage?: string;
     color?: string;
     showInMenu?: boolean;
+    /**
+     * Member images for a collage, most important first — what a BUNDLE actually
+     * looks like, which is its contents rather than one tile.
+     *
+     * 🛑 Derived at SEED time from the members' own `mainImage`, not fetched. A
+     * card cannot resolve `bundleProductIds` into images without one query per
+     * bundle per render, and a grid of five bundles would then be five extra
+     * reads for decoration. `<ImageMosaic>` renders nothing below `MOSAIC_MIN`
+     * (3), so a short list degrades to the cover image rather than a broken
+     * collage.
+     */
+    mosaicImages?: string[];
 }
 export interface CategoryMetrics {
     productCount: number;

package/dist/seed/categories-seed-data.js

@@ -247,6 +247,34 @@ function bundleCategorySlugsFor(productIds) {
     }
     return out;
 }
+/**
+ * Attach a bundle's member images so its card can render a collage.
+ *
+ * 🛑 A bundle IS its contents, so a single placeholder tile is the least
+ * informative thing a bundle card can show. Resolved here, at seed time, from
+ * the members' own `mainImage` — a card cannot do it at render time without one
+ * query per bundle, and a grid of five would be five reads for decoration.
+ *
+ * `<ImageMosaic>` renders nothing below `MOSAIC_MIN` (3), so a bundle with one
+ * or two resolvable members quietly falls back to its cover image rather than
+ * showing a broken collage. A member id that resolves to no product is dropped
+ * rather than defaulted — a wrong photo is worse than one fewer tile.
+ */
+function withBundleMosaic(row) {
+    const ids = row.bundleProductIds ?? [];
+    // `row.display` must already exist — `CategoryDocumentDisplay` requires
+    // `showInFooter`, so spreading onto `{}` would drop a required field. Every
+    // bundle row declares one; a row without is left untouched rather than
+    // half-built.
+    if (ids.length === 0 || !row.display)
+        return row;
+    const images = ids
+        .map((id) => productsStandardSeedData.find((p) => p.id === id)?.mainImage)
+        .filter((src) => typeof src === "string" && src.length > 0);
+    if (images.length === 0)
+        return row;
+    return { ...row, display: { ...row.display, mosaicImages: images } };
+}
 const bundleRows = [
     {
         id: "bundle-original-collectors-set",
@@ -514,7 +542,7 @@ const allCategoryRows = [
     ...sublistingRows.map((s) => ({ ancestors: [], ...s, createdByType: "admin" })),
     ...brandRows.map((b) => ({ ancestors: [], ...b, createdByType: "admin" })),
     ...franchiseRows.map((f) => ({ ancestors: [], ...f, createdByType: "admin" })),
-    ...bundleRows.map((b) => ({ ancestors: [], ...b })),
+    ...bundleRows.map((b) => ({ ancestors: [], ...withBundleMosaic(b) })),
 ]
     .map(withGeneratedContent)
     .map(withGeneratedCoverImage)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.51.0",
+  "version": "4.52.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"