@mohasinac/appkit 4.42.18 → 4.44.0

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

@@ -1,13 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit";
-import { sortBy } from "../../../constants/sort";
-import { CATEGORY_FIELDS } from "../../../constants/field-names";
-import { categoriesRepository } from "../../../repositories";
 import { Container, Heading, Main, Section } from "../../../ui";
 import { AdSlot } from "../../homepage/components/AdSlot";
 import { CategoriesIndexListing } from "./CategoriesIndexListing";
-import { safeRead } from "../../../errors/safe-read";
-import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility";
 function sp(params, key) {
     const v = params[key];
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
@@ -39,32 +34,28 @@ function buildCategoryFilters(params) {
     }
     return parts.join(",");
 }
-export async function CategoriesIndexPageView({ searchParams = {} }) {
-    /*
-     * 🛑 MUST MATCH CategoriesIndexListing's DEFAULT_SORT.
-     *
-     * This defaulted to "name" while the client listing defaulted to the same,
-     * and both were wrong: the roots fell off page 1. Now both default to tier
-     * ascending — and they have to agree, because this view hands its result to
-     * the listing as initialData and every public listing hook sets
-     * `staleTime: Infinity` when given it. A disagreement here is not a
-     * transient wrong first paint; it is frozen for that query key
-     * (Root Cause #30).
-     */
-    const sort = sp(searchParams, "sort") || sortBy(CATEGORY_FIELDS.TIER, "ASC");
-    const page = Number(sp(searchParams, "page")) || 1;
-    const filters = buildCategoryFilters(searchParams);
-    const result = await safeRead(() => categoriesRepository.list({
-        page,
-        pageSize: 200,
-        sorts: sort,
-        ...(filters ? { filters } : {}),
-    }), { route: "/categories", key: "categories.list", fallback: null });
-    /*
-     * This one page carries THREE entity kinds — categories, brands and bundles
-     * are all `CategoryDocument` rows discriminated by `categoryType` — so a
-     * single unfiltered read published sandbox fixtures of all three.
-     */
-    const initialData = hidePublicTestData((result?.items ?? []));
-    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Categories" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(CategoriesIndexListing, { initialData: initialData }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
+/**
+ * The categories index.
+ *
+ * 🛑 This view deliberately performs NO Firestore read.
+ *
+ * It used to fetch `pageSize: 200` and hand the result to
+ * `CategoriesIndexListing` as `initialData` — which destructured it as
+ * `initialData: _` and threw it away, then fetched `/api/categories?flat=true`
+ * regardless. So the read was 200 documents per render, on a route that
+ * regenerated every 300s, rendering nothing. Measured 2026-10-09 while tracing
+ * 2.1M Firestore reads/week against a 50K/day free tier.
+ *
+ * Deleting it also removes this page from Root Cause #30's blast radius
+ * entirely: you cannot freeze the wrong data under a `staleTime: Infinity` key
+ * you never seeded. The long "MUST MATCH CategoriesIndexListing's DEFAULT_SORT"
+ * warning that used to live here is now moot for the same reason — there is no
+ * second parser to keep in sync.
+ *
+ * Unlike the other listing pages, making this one static costs no SEO: its grid
+ * was already client-rendered, so there was never a server-rendered grid to
+ * lose (contrast `/products`, where the grid IS in the SSR HTML and must stay).
+ */
+export async function CategoriesIndexPageView(_props = {}) {
+    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Categories" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(CategoriesIndexListing, {}), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
 }

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

@@ -21,6 +21,16 @@ const __O = {
     hidden: "overflow-hidden",
     xAuto: "overflow-x-auto",
 };
+/**
+ * Read and display bounds for this page. Every one of these replaced an
+ * unbounded read — see the comments at each use site for what each one cost.
+ */
+/** Tiles rendered in "Related Categories". A sample, not an index. */
+const RELATED_CATEGORY_LIMIT = 24;
+/** Documents read to fill those tiles. Headroom for the non-listing filter. */
+const RELATED_CATEGORY_FETCH = 60;
+/** Descendant slugs the Stores tab will match on → at most 4 chunked queries. */
+const STORE_CATEGORY_SLUG_MAX = 120;
 export async function CategoryDetailPageView({ slug }) {
     // The category IS this page's subject — a read failure must surface rather
     // than render an anonymous, empty category page. `undefined` still means
@@ -75,8 +85,18 @@ export async function CategoryDetailPageView({ slug }) {
         // Related categories — every other category sharing this category's root
         // (siblings + cousins across the tree, up to the tier-0/1/2 depth the
         // catalog actually uses), not just direct children.
+        //
+        // 🛑 BOUNDED. This read is a display grid, and it used to be an unbounded
+        // `.get()` over the whole root subtree — ~9% of a 50K/day Firestore budget
+        // for one page render once the forest reaches ~330 nodes, and it rendered
+        // every one of those as a tile. The section is a SAMPLE of nearby
+        // categories; the tier-grouped children grid above it is the real index.
+        // Fetch headroom is larger than the display cap because the filter below
+        // drops this category plus every brand/bundle/sublisting row.
+        // `buildTree` still passes no limit — a truncated node list there would
+        // silently drop whole branches.
         category?.rootId
-            ? safeRead(() => categoriesRepository.getCategoriesByRootId(category.rootId), {
+            ? safeRead(() => categoriesRepository.getCategoriesByRootId(category.rootId, { limit: RELATED_CATEGORY_FETCH }), {
                 route: "/categories/[slug]",
                 key: "category.rootSiblings",
                 fallback: [],
@@ -98,7 +118,9 @@ export async function CategoryDetailPageView({ slug }) {
             fallback: null,
         }),
     ]);
-    const relatedCategories = rootSiblingCategories.filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"));
+    const relatedCategories = rootSiblingCategories
+        .filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"))
+        .slice(0, RELATED_CATEGORY_LIMIT);
     // Stores tab — stores whose storeCategory is this category or ANY descendant.
     //
     // `storeCategory` is a single slug with no ancestor chain (unlike a product's
@@ -108,14 +130,25 @@ export async function CategoryDetailPageView({ slug }) {
     // an unbounded N+1. Both are fixed by pipe-joining the slugs into OR-groups:
     // the enhanced Sieve adapter turns a same-field OR into a Firestore `in`,
     // which caps at 30 values, hence the chunking.
-    const storeCategorySlugs = [
-        slug,
-        ...(await safeRead(() => categoriesRepository.getDescendantIds(category?.id ?? ""), {
-            route: "/categories/[slug]",
-            key: "category.descendantIds",
-            fallback: [],
-        })),
-    ].filter(Boolean);
+    //
+    // 🛑 The descendant ids are REUSED from `childCategories` above, not fetched
+    // again. `getDescendantIds` is literally `getDescendants().map(d => d.id)`,
+    // so calling it here ran the identical paginated subtree query a second time
+    // and threw the documents away — on a ~330-node root that is ~330 wasted
+    // reads per page view, and the two answers could disagree if one read failed
+    // while the other succeeded.
+    //
+    // 🛑 And the fan-out is CAPPED, nearest-first. One `listStores` query per 30
+    // slugs is 11 queries at ~330 nodes and 51 at ~1,500; sorting by tier takes
+    // the closest descendants, which is what someone browsing a root cares
+    // about. `storeCount` was already a floor (each chunk caps at pageSize 50),
+    // so this tightens a floor rather than making an exact number wrong.
+    const descendantIdsByProximity = [...childCategories]
+        .sort((a, b) => (a.tier ?? 0) - (b.tier ?? 0))
+        .map((c) => c.id);
+    const storeCategorySlugs = [slug, ...descendantIdsByProximity]
+        .filter(Boolean)
+        .slice(0, STORE_CATEGORY_SLUG_MAX);
     const SLUG_CHUNK = 30;
     const slugChunks = [];
     for (let i = 0; i < storeCategorySlugs.length; i += SLUG_CHUNK) {

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

@@ -0,0 +1,65 @@
+/**
+ * The seller form's category description-template picker — C2c.
+ *
+ * Fills `SellerProductShell`'s `renderTemplateSelector` slot, which existed
+ * with zero consumers until C2b widened it (Root Cause #8's shape: a slot
+ * shell rendered with no render props shows a layout skeleton and no content).
+ *
+ * ## What it is for
+ *
+ * Our sellers write every description from scratch because no
+ * category→description mechanism has ever existed. The competitor crawl shows
+ * the model: worldhobbyshop reuses TWO bodies across 1,195 listings — a
+ * pre-owned disclosure and a new-in-box spec block — and tcgindia generates
+ * five templated FAQs per product. The bodies live on the CATEGORY, so fixing
+ * the copy fixes every future listing at once.
+ *
+ * ## 🛑 The clobber rule is the whole design
+ *
+ * `isDescriptionDirty` arrives from the shell: non-empty after trim AND not
+ * byte-identical to a body applied this session. When it is false the picker
+ * may fill silently — the seller is looking at either an empty box or our own
+ * text. When it is TRUE it must not overwrite; it offers **Replace
+ * description** instead, which is destructive and therefore carries a
+ * `confirmation` on its ActionDef (Rule #7), not a `window.confirm`.
+ *
+ * ## 🛑 "No template" must never blank the field
+ *
+ * A category with no body at any ancestor renders "No template yet" and leaves
+ * whatever is in the box alone. Blanking a field to signal absence is how a
+ * seller loses work to a feature that was trying to help.
+ */
+import React from "react";
+import type { CategoryTemplateVariant } from "../schemas/category-content";
+/** What the picker may apply to the draft. Deliberately narrow. */
+export interface CategoryTemplateApply {
+    description?: string;
+    appliedTemplateId?: string;
+    appliedTemplateBody?: string;
+}
+export interface CategoryTemplatePickerProps {
+    /** The leaf the seller has chosen. Empty until they pick one. */
+    categoryId: string;
+    /** The raw `condition` enum from the draft — mapped to a variant below. */
+    condition: string;
+    /** Resolved `{{slot}}` values, supplied by the shell. */
+    context: Record<string, string>;
+    /** True when the seller has authored text we must not overwrite. */
+    isDescriptionDirty: boolean;
+    onApply: (partial: CategoryTemplateApply) => void;
+}
+/**
+ * Which body a condition wants.
+ *
+ * 🛑 The variants are the conditions that change what the copy must SAY, not
+ * every `CONDITION_OPTIONS` value — a "pre-owned" and a "used" listing want
+ * the same disclosure paragraph, which is why `CategoryTemplateVariant` has
+ * five members against the form's six conditions.
+ *
+ * `refurbished` maps to `pre_owned` rather than `default`: it has been owned
+ * and worked on, so the disclosure applies. Mapping it to `default` would hand
+ * a refurbished item a brand-new-item body, which is the one wrong answer
+ * available here.
+ */
+export declare function variantForCondition(condition: string): CategoryTemplateVariant;
+export declare function CategoryTemplatePicker({ categoryId, condition, context, isDescriptionDirty, onApply, }: CategoryTemplatePickerProps): React.JSX.Element | null;

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

@@ -0,0 +1,170 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The seller form's category description-template picker — C2c.
+ *
+ * Fills `SellerProductShell`'s `renderTemplateSelector` slot, which existed
+ * with zero consumers until C2b widened it (Root Cause #8's shape: a slot
+ * shell rendered with no render props shows a layout skeleton and no content).
+ *
+ * ## What it is for
+ *
+ * Our sellers write every description from scratch because no
+ * category→description mechanism has ever existed. The competitor crawl shows
+ * the model: worldhobbyshop reuses TWO bodies across 1,195 listings — a
+ * pre-owned disclosure and a new-in-box spec block — and tcgindia generates
+ * five templated FAQs per product. The bodies live on the CATEGORY, so fixing
+ * the copy fixes every future listing at once.
+ *
+ * ## 🛑 The clobber rule is the whole design
+ *
+ * `isDescriptionDirty` arrives from the shell: non-empty after trim AND not
+ * byte-identical to a body applied this session. When it is false the picker
+ * may fill silently — the seller is looking at either an empty box or our own
+ * text. When it is TRUE it must not overwrite; it offers **Replace
+ * description** instead, which is destructive and therefore carries a
+ * `confirmation` on its ActionDef (Rule #7), not a `window.confirm`.
+ *
+ * ## 🛑 "No template" must never blank the field
+ *
+ * A category with no body at any ancestor renders "No template yet" and leaves
+ * whatever is in the box alone. Blanking a field to signal absence is how a
+ * seller loses work to a feature that was trying to help.
+ */
+import React from "react";
+import { useQuery } from "@tanstack/react-query";
+import { Button, Div, Row, Stack, Text } from "../../../ui";
+import { apiClient } from "../../../http";
+import { CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
+import { interpolate } from "../../../_internal/shared/templating/placeholders";
+const PANEL_CLASS = "rounded-lg border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-3)] py-[var(--appkit-space-3)]";
+/**
+ * Which body a condition wants.
+ *
+ * 🛑 The variants are the conditions that change what the copy must SAY, not
+ * every `CONDITION_OPTIONS` value — a "pre-owned" and a "used" listing want
+ * the same disclosure paragraph, which is why `CategoryTemplateVariant` has
+ * five members against the form's six conditions.
+ *
+ * `refurbished` maps to `pre_owned` rather than `default`: it has been owned
+ * and worked on, so the disclosure applies. Mapping it to `default` would hand
+ * a refurbished item a brand-new-item body, which is the one wrong answer
+ * available here.
+ */
+export function variantForCondition(condition) {
+    switch (condition) {
+        case "new":
+            return "new_in_box";
+        case "like_new":
+        case "good":
+        case "fair":
+        case "used":
+        case "refurbished":
+            return "pre_owned";
+        default:
+            return "default";
+    }
+}
+function unwrap(res) {
+    const body = res?.data ?? res;
+    return body && typeof body === "object" && "template" in body ? body : null;
+}
+/** "2 of 9 slots could not be filled: {{year}}, {{type}}" */
+function unresolvedNote(unresolved, total) {
+    if (unresolved.length === 0)
+        return null;
+    const named = unresolved.map((n) => `{{${n}}}`).join(", ");
+    return `${unresolved.length} of ${total} slots could not be filled: ${named}`;
+}
+/** "adds 2 specification rows · sets condition to Used" */
+function describeDefaults(defaults) {
+    const parts = [];
+    const specs = defaults.specifications?.length ?? 0;
+    if (specs > 0)
+        parts.push(`${specs} specification row${specs === 1 ? "" : "s"}`);
+    const box = defaults.inTheBox?.length ?? 0;
+    if (box > 0)
+        parts.push(`a "what's in the box" list of ${box}`);
+    const kw = defaults.seoKeywords?.length ?? 0;
+    if (kw > 0)
+        parts.push(`${kw} SEO keyword${kw === 1 ? "" : "s"}`);
+    const faqs = defaults.faqTemplates?.length ?? 0;
+    if (faqs > 0)
+        parts.push(`${faqs} listing FAQ${faqs === 1 ? "" : "s"}`);
+    return parts;
+}
+export function CategoryTemplatePicker({ categoryId, condition, context, isDescriptionDirty, onApply, }) {
+    const variant = variantForCondition(condition);
+    /*
+     * Keyed on (category, variant) — the same pair the endpoint's edge cache is
+     * keyed on, so switching back to a condition the seller already looked at
+     * costs nothing at all. Fired on change, never per keystroke: `condition` is
+     * a select and `categoryId` comes from a picker.
+     */
+    const query = useQuery({
+        queryKey: ["category-description-template", categoryId, variant],
+        enabled: categoryId.length > 0,
+        staleTime: 60 * 60 * 1000,
+        queryFn: async () => unwrap(await apiClient.get(CATEGORY_ENDPOINTS.DESCRIPTION_TEMPLATE(categoryId, variant))),
+    });
+    const data = query.data ?? null;
+    const template = data?.template ?? null;
+    /*
+     * Interpolated here rather than on apply, so the unresolved-slot note is
+     * accurate BEFORE the seller commits. A note that appears only after the
+     * text lands is a report on something they can no longer choose about.
+     */
+    const filled = React.useMemo(() => (template ? interpolate(template.body, context) : null), [template, context]);
+    /*
+     * Auto-fill when the seller owns nothing. Deliberately an effect rather than
+     * a render-time write: the body has to reach the draft, which is the
+     * shell's state.
+     *
+     * 🛑 Guarded on `isDescriptionDirty` reading FALSE, which covers all three
+     * silent cases the plan specifies — never touched, cleared, or still showing
+     * a body we applied. The seller who typed one character gets the button
+     * instead.
+     *
+     * `filled.text` is in the dependency list, so changing the category or the
+     * condition refreshes a body we own. That is the "Updated for Burst Dual
+     * Layer" case, and it is the reason this is not a one-shot.
+     */
+    const applied = data && template && filled;
+    React.useEffect(() => {
+        if (!applied || isDescriptionDirty)
+            return;
+        onApply({
+            description: filled.text,
+            appliedTemplateId: template.id,
+            appliedTemplateBody: filled.text,
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [applied, isDescriptionDirty, filled?.text, template?.id]);
+    if (categoryId.length === 0)
+        return null;
+    if (query.isLoading) {
+        return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "Looking for a description template for this category\u2026" }) }));
+    }
+    /*
+     * 🛑 A failed fetch says so, and does NOT fall through to "No template yet".
+     * Those are different facts, and conflating them is Root Cause #72's rule
+     * one level out: absence must never be reported as a measured zero.
+     */
+    if (query.isError) {
+        return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "Could not load the category's description template. Your description is untouched \u2014 write your own, or try again in a moment." }) }));
+    }
+    if (!data || !template || !filled) {
+        return (_jsx(Div, { className: PANEL_CLASS, children: _jsx(Text, { size: "xs", color: "muted", children: "No description template for this category yet \u2014 write your own, and an admin can add one so the next listing starts from it." }) }));
+    }
+    const note = unresolvedNote(filled.unresolved, template.placeholders?.length ?? filled.unresolved.length);
+    const extras = describeDefaults(data.defaults);
+    const source = data.inheritedFromName
+        ? `Inherited from ${data.inheritedFromName}`
+        : "From this category";
+    return (_jsx(Div, { className: PANEL_CLASS, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { gap: "sm", align: "center", justify: "between", wrap: true, children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", children: template.label }), _jsxs(Text, { size: "xs", color: "muted", children: [source, isDescriptionDirty ? "" : " · applied"] })] }), isDescriptionDirty ? (_jsx(Button, { action: ACTIONS.STORE["replace-description"], size: "sm", onClick: () => onApply({
+                                description: filled.text,
+                                appliedTemplateId: template.id,
+                                appliedTemplateBody: filled.text,
+                            }) })) : null] }), note ? (_jsx(Text, { size: "xs", color: "muted", children: note })) : null, extras.length > 0 ? (_jsxs(Text, { size: "xs", color: "muted", children: ["This category also supplies ", extras.join(", "), " when you save."] })) : null, isDescriptionDirty ? (_jsx(Text, { size: "xs", color: "muted", children: "Your own description is kept \u2014 nothing was overwritten." })) : null] }) }));
+}

package/dist/features/categories/constants/listing-categories.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `categoryType` values that are NOT browsable listing categories.
+ *
+ * - `brand`     — a manufacturer/publisher row, browsed at `/brands/{slug}`
+ * - `bundle`    — a priced bundle, browsed at `/bundles/{slug}`
+ * - `sublisting`— a grading/variant axis (`"PSA 10"`, `"105RF"`), never browsed
+ */
+export declare const NON_LISTING_CATEGORY_TYPES: ReadonlySet<string>;
+/**
+ * True when a category row is a real, browsable listing category.
+ *
+ * Structural parameter on purpose: callers hold `CategoryDocument` (server) or
+ * `CategoryItem` (client) and neither should have to be imported here.
+ */
+export declare function isListingCategory(cat: {
+    categoryType?: string | null;
+}): boolean;

package/dist/features/categories/constants/listing-categories.js

@@ -0,0 +1,53 @@
+/*
+ * WHY: four surfaces need to answer "is this row a browsable listing category,
+ *      or is it a brand / bundle / sublisting sharing the collection?" — the
+ *      sitemap, the filter-facet hook, the public categories route, and the
+ *      catalogue editor's picker. Three of them had already hand-written the
+ *      same Set, which is how the fourth got shipped without one.
+ *
+ * WHAT: one Set and one predicate. No imports, so it is safe in a client
+ *       bundle (Root Cause #6) and safe in a server-only metadata path
+ *       (Root Cause #76).
+ *
+ * 🛑 THE TEST CANNOT BE A FIRESTORE CLAUSE, and that is the whole reason this
+ * exists as a predicate rather than a query filter. A plain listing category
+ * **OMITS** `categoryType` entirely — that is the convention every seeded
+ * listing category follows — so there is no value to match on and
+ * `where("categoryType", "not-in", [...])` would exclude every real category
+ * (a Firestore inequality drops documents that lack the field). It has to be
+ * applied in memory, after the fetch.
+ *
+ * Measured cost of not doing this: the `/products` category facet offered 11
+ * options of which **9 were not categories** — "Takara-Tomy", "Hasbro",
+ * "Burst Battlers Pack", "X-Series Starter Set" — and the catalogue editor's
+ * category picker offered "Original Collector's Set" and "Metal Fusion Duo".
+ * It fails silently because a short list of plausible names is
+ * indistinguishable from a correct one.
+ *
+ * @tag domain:categories
+ * @tag layer:constants
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+/**
+ * `categoryType` values that are NOT browsable listing categories.
+ *
+ * - `brand`     — a manufacturer/publisher row, browsed at `/brands/{slug}`
+ * - `bundle`    — a priced bundle, browsed at `/bundles/{slug}`
+ * - `sublisting`— a grading/variant axis (`"PSA 10"`, `"105RF"`), never browsed
+ */
+export const NON_LISTING_CATEGORY_TYPES = new Set([
+    "brand",
+    "bundle",
+    "sublisting",
+]);
+/**
+ * True when a category row is a real, browsable listing category.
+ *
+ * Structural parameter on purpose: callers hold `CategoryDocument` (server) or
+ * `CategoryItem` (client) and neither should have to be imported here.
+ */
+export function isListingCategory(cat) {
+    const kind = cat.categoryType;
+    return typeof kind !== "string" || !NON_LISTING_CATEGORY_TYPES.has(kind);
+}

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

@@ -2,6 +2,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints";
+import { isListingCategory } from "../constants/listing-categories";
 /**
  * Returns all categories flattened in DFS tree order:
  * parent → its children → their children, etc.
@@ -11,11 +12,36 @@ export function useCategoryTree(opts) {
     const { data, isLoading } = useQuery({
         queryKey: ["categories", "tree"],
         queryFn: async () => {
-            const res = await apiClient.get(`${CATEGORY_ENDPOINTS.LIST}?pageSize=300&sort=tier,order,name`);
+            /*
+             * 🛑 `flat=true` is load-bearing, not a preference.
+             *
+             * `/api/categories` computes `isFiltered` from flat/parentId/featured/
+             * isBrand/showOnHomepage/tier/type. `pageSize` and `sort` are NOT in
+             * that set — so a request carrying only those falls through to TREE
+             * mode, which returns a NESTED payload with only roots at the top
+             * level. `flattenTree` below then builds its adjacency map from roots
+             * alone and `dfs(null)` emits tier-0 only.
+             *
+             * Measured against production data before this fix: the category
+             * facet on /products, /auctions, /pre-orders and /prize-draws showed
+             * **11 options instead of 47** — and 9 of those 11 were not categories
+             * at all. It listed "Takara-Tomy", "Hasbro", "Burst Battlers Pack" and
+             * "X-Series Starter Set", because brand and bundle rows live in the
+             * same collection with empty `parentIds`, so tree mode surfaced them
+             * as roots.
+             *
+             * It failed silently because a short list of plausible-looking names
+             * is indistinguishable from a correct one.
+             *
+             * `sort` was also dropped: BOTH branches hardcode `sort: "order"`, and
+             * this hook re-orders by DFS anyway, so passing it implied a control
+             * that never existed.
+             */
+            const res = await apiClient.get(`${CATEGORY_ENDPOINTS.LIST}?flat=true&pageSize=500`);
             const items = Array.isArray(res)
                 ? res
                 : res.items ?? res.data ?? [];
-            return flattenTree(items);
+            return flattenTree(items.filter(isListingCategory));
         },
         enabled: opts?.enabled ?? true,
         staleTime: 5 * 60 * 1000, // 5 min

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

@@ -1,25 +1,87 @@
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
 import { type CategoryCreateInput, type CategoryDocument, type CategoryMoveInput, type CategoryTreeNode } from "../schemas";
-import type { FirestoreDocument } from "@mohasinac/appkit";
+import type { FirestoreDocument, JsonValue } from "@mohasinac/appkit";
 export declare class CategoriesRepository extends BaseRepository<CategoryDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    list(model: SieveModel): Promise<FirebaseSieveResult<CategoryDocument>>;
+    /** Derived on every write path via `applyWriteHooks`. */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    list(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<CategoryDocument>>;
     createWithHierarchy(input: CategoryCreateInput): Promise<CategoryDocument>;
     getCategoryBySlug(slug: string): Promise<CategoryDocument | null>;
     getRootCategories(): Promise<CategoryDocument[]>;
     getLeafCategories(): Promise<CategoryDocument[]>;
-    getCategoriesByTier(tier: number): Promise<CategoryDocument[]>;
-    getCategoriesByRootId(rootId: string): Promise<CategoryDocument[]>;
-    getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**
-     * IDs of every descendant category at any depth (not just direct
-     * children) — `parentIds` stores the full ancestor chain, so a single
-     * array-contains query on that field already returns the whole subtree
-     * with no recursion needed. Used to expand a parent category's product
-     * listing/count to include products filed under any of its children.
+     * @param limit 0 = unbounded (the historical behaviour). When > 0 the bound is
+     *   pushed into Firestore instead of slicing after the read.
+     *
+     * 🛑 The limit is applied with HEADROOM, not exactly, because `!isBrand` is a
+     * post-fetch filter: brand rows live in this same collection (they are
+     * `CategoryDocument`s discriminated by `isBrand`), so a bare `.limit(n)` could
+     * return n brand rows, filter all of them out, and yield an empty tier. The
+     * caller still slices to its own limit.
+     */
+    getCategoriesByTier(tier: number, limit?: number): Promise<CategoryDocument[]>;
+    /**
+     * Every category sharing a root, tier-then-order.
+     *
+     * 🛑 `limit` is for DISPLAY callers only, and it is a real truncation.
+     * `buildTree(rootId)` must pass nothing: a tree built from a truncated node
+     * list silently drops whole branches, which is the exact failure
+     * `getDescendants`'s docstring was rewritten to avoid. A display grid of
+     * sibling categories, by contrast, renders ~20 tiles and has no reason to
+     * read 1,500 documents to do it.
+     *
+     * Paginated rather than one unbounded `.get()`: the previous form read the
+     * whole root subtree into memory on every category page render, which at the
+     * ~330-node forest this plan seeds is ~9% of a 50K/day Firestore budget for
+     * ONE page view.
+     */
+    /**
+     * Several categories by id, in ONE round trip, in the order asked for.
+     *
+     * The ancestor-walk primitive. A five-tier tree means a leaf has up to four
+     * ancestors, and resolving an inherited description template or an inherited
+     * `productDefaults` means reading them nearest-first until the answer is
+     * found — which as four sequential `findById` calls is four round trips, on
+     * a route the seller form hits on every category change. Rule #6 budgets
+     * about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled. Callers
+     * walk the result looking for the first document that declares a thing, so
+     * "nearest first" has to survive the round trip — Firestore's `getAll`
+     * already answers in argument order, and this keeps that guarantee explicit
+     * rather than incidental. A caller needing to know WHICH id was missing
+     * should compare lengths; none does, because an ancestor that no longer
+     * exists is a data problem for the reconcile job, not a reason to fail a
+     * form.
+     *
+     * Bounded at 30 to match `array-contains-any`'s cap, so this cannot become
+     * the unbounded read that `getCategoriesByRootId` had to be rewritten to
+     * avoid being.
+     */
+    findByIds(ids: string[]): Promise<CategoryDocument[]>;
+    getCategoriesByRootId(rootId: string, opts?: {
+        limit?: number;
+    }): Promise<CategoryDocument[]>;
+    /**
+     * Categories whose `productDefaults.taxCodeId` points at `taxCodeId`.
+     *
+     * 🛑 Exists so DELETE on a tax code can REFUSE while it is referenced.
+     * `taxCodeId` is a plain string with no referential integrity, and a
+     * dangling reference does not error — `findResolvable` answers `null`,
+     * whose correct handling is "leave the product's gstRate alone", so every
+     * subsequent listing under that category silently derives NO TAX. It does
+     * not fail; it under-charges, until someone reads an invoice.
+     *
+     * One equality on a dot-path — served by the automatic index, no composite
+     * to declare. Bounded at 200: the answer is used to NAME referrers in a 409
+     * message, and the first five are what the admin reads.
      */
-    getDescendantIds(categoryId: string): Promise<string[]>;
+    findByTaxCodeId(taxCodeId: string): Promise<CategoryDocument[]>;
+    getChildren(parentId: string): Promise<CategoryDocument[]>;
     /**
      * Every descendant DOCUMENT at any depth.
      *
@@ -159,7 +221,6 @@ export declare class CategoriesRepository extends BaseRepository<CategoryDocumen
      * SB-UNI-B — derive the canonical `sublisting-{slug}` ID from a
      * human-entered category name.
      */
-    incrementViewCount(categoryId: string): Promise<void>;
     generateSublistingId(name: string): string;
 }
 export declare const categoriesRepository: CategoriesRepository;