@mohasinac/appkit 4.46.0 → 4.47.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.46.0",
-  "head": "34ce98d7f80659ca1052873c7444d69dde36c07b",
+  "version": "4.47.0",
+  "head": "f72c5f183b70c66b626c7809ffb1a4b0112e7cb1",
   "branch": "main",
   "dirty": true,
-  "builtAt": "2026-10-13T00:19:07.494Z"
+  "builtAt": "2026-10-13T05:22:53.600Z"
 }

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

@@ -28,6 +28,29 @@ export interface BreadcrumbTrailProps {
      */
     showCurrent?: boolean;
     className?: string;
+    /**
+     * I5b — collapse the middle of a long trail behind a dropdown.
+     *
+     * 🛑 Needed independently of multi-assignment: a tier-4 part leaf is SEVEN
+     * crumbs (`All Categories > Spinning Tops > Beyblade Metal > Metal Parts >
+     * Performance Tips > Rubber Flat`) and 390px cannot hold it. D4b measured
+     * that depth and never addressed how it wraps.
+     *
+     * Defaults ON, because the only trails long enough to collapse are the ones
+     * that already overflow.
+     */
+    collapse?: boolean;
+    /**
+     * I5b — the OTHER categories this listing is filed under, as one extra crumb.
+     *
+     * Pass `categoryIds`/`categoryIdNames` straight through from the product;
+     * `alternateAssignments` decides inline-vs-dropdown and returns nothing at
+     * all for a single assignment, which is the overwhelming majority.
+     */
+    alternates?: {
+        ids?: readonly string[] | null;
+        names?: readonly string[] | null;
+    };
 }
 /**
  * BreadcrumbTrail — a category-aware breadcrumb component.
@@ -45,4 +68,4 @@ export interface BreadcrumbTrailProps {
  * />
  * ```
  */
-export declare function BreadcrumbTrail({ category, rootLabel, rootHref, basePath, showCurrent, className, }: BreadcrumbTrailProps): React.JSX.Element;
+export declare function BreadcrumbTrail({ category, rootLabel, rootHref, basePath, showCurrent, className, collapse, alternates, }: BreadcrumbTrailProps): React.JSX.Element;

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

@@ -1,6 +1,10 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React from "react";
 import { Breadcrumb } from "../../../ui/index.js";
+import { Text } from "../../../ui/components/Typography.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
+import { alternateAssignments, collapseTrail } from "../utils/breadcrumb-chain.js";
 /**
  * BreadcrumbTrail — a category-aware breadcrumb component.
  *
@@ -17,8 +21,8 @@ import { ROUTES } from "../../../next/routing/route-map.js";
  * />
  * ```
  */
-export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHref = String(ROUTES.PUBLIC.CATEGORIES), basePath = String(ROUTES.PUBLIC.CATEGORIES), showCurrent = true, className, }) {
-    const items = [
+export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHref = String(ROUTES.PUBLIC.CATEGORIES), basePath = String(ROUTES.PUBLIC.CATEGORIES), showCurrent = true, className, collapse = true, alternates, }) {
+    const full = [
         // Root
         { label: rootLabel, href: rootHref },
         // Ancestors (sorted by tier ascending so root → leaf order)
@@ -32,5 +36,42 @@ export function BreadcrumbTrail({ category, rootLabel = "All Categories", rootHr
         // Current category (no href so it renders as the active item)
         ...(showCurrent ? [{ label: category.name }] : []),
     ];
-    return _jsx(Breadcrumb, { items: items, className: className });
+    /*
+     * I5b — the alternates become ONE extra crumb, never a second row. Two rows
+     * of crumbs above a title is a pattern no competitor in the crawl uses and it
+     * costs vertical space above the fold on a phone.
+     */
+    const alt = alternateAssignments({
+        categoryIds: alternates?.ids ?? null,
+        categoryIdNames: alternates?.names ?? null,
+        hrefFor: (slug) => `${basePath}/${slug}`,
+    });
+    /*
+     * 🛑 Collapsing is PRESENTATION. The JSON-LD is emitted elsewhere, from the
+     * full chain, and must stay that way — a crawler never receives a truncated
+     * hierarchy because a phone could not show it.
+     */
+    const split = collapse ? collapseTrail(toCrumbs(full)) : null;
+    const items = split && split.collapsed.length > 0
+        ? [
+            ...split.lead.map(fromCrumb),
+            /*
+             * The collapsed group as ONE crumb whose label names what it hides.
+             * 🛑 Rendered as a real crumb with no href rather than a menu,
+             * because `Breadcrumb` is a plain list primitive — and the hidden
+             * ancestors are still reachable: every one of them is an ancestor of
+             * the crumbs either side, so no path is lost, only shortened.
+             */
+            { label: `… ${split.collapsed.length} more` },
+            ...split.tail.map(fromCrumb),
+        ]
+        : full;
+    return (_jsxs(_Fragment, { children: [_jsx(Breadcrumb, { items: items, className: className }), alt.mode !== "none" && (_jsxs(Text, { size: "xs", color: "muted", children: ["Also in", " ", alt.items.map((a, i) => (_jsxs(React.Fragment, { children: [i > 0 && " · ", _jsx(TextLink, { href: a.url ?? "#", children: a.name })] }, a.url ?? a.name)))] }))] }));
+}
+/** `BreadcrumbItem` ⇄ `BreadcrumbCrumb` — two names for one shape. */
+function toCrumbs(items) {
+    return items.map((i) => ({ name: i.label, url: i.href }));
+}
+function fromCrumb(c) {
+    return c.url ? { label: c.name, href: c.url } : { label: c.name };
 }

package/dist/features/seller/components/CategoryInlineSelect.d.ts

@@ -6,5 +6,21 @@ export interface CategoryInlineSelectProps {
     disabled?: boolean;
     /** Show the "+ Create new category" option. Defaults to true — sellers can create categories inline. */
     allowCreate?: boolean;
+    /**
+     * I2 — the ADDITIONAL assignments, beyond `value`.
+     *
+     * 🛑 Omitting this pair keeps the component exactly single-select, which is
+     * what every existing call site gets. Multi-assignment is opt-in per surface
+     * rather than switched on globally, because `value`/`onChange` is a `string`
+     * contract that five call sites rely on and changing it under them is Root
+     * Cause #20 (a public prop change without its consumers in the same commit).
+     */
+    extraValues?: string[];
+    onExtraValuesChange?: (ids: string[]) => void;
+    /**
+     * How many assignments are allowed in total, `value` included. Defaults to
+     * `MAX_CATEGORY_ASSIGNMENTS`, which is what the repository refuses above.
+     */
+    maxAssignments?: number;
 }
-export declare function CategoryInlineSelect({ value, onChange, placeholder, disabled, allowCreate, }: CategoryInlineSelectProps): React.JSX.Element;
+export declare function CategoryInlineSelect({ value, onChange, placeholder, disabled, allowCreate, extraValues, onExtraValuesChange, maxAssignments, }: CategoryInlineSelectProps): React.JSX.Element;

package/dist/features/seller/components/CategoryInlineSelect.js

@@ -1,9 +1,12 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { PaginatedSelect } from "../../../ui/components/PaginatedSelect.js";
 import { CategoryQuickCreateForm } from "../../admin/components/CategoryQuickCreateForm.js";
 import { apiClient } from "../../../http/index.js";
 import { ADMIN_ENDPOINTS, CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { Stack } from "../../../ui/components/Layout.js";
+import { Text } from "../../../ui/components/Typography.js";
+import { MAX_CATEGORY_ASSIGNMENTS } from "../../products/repository/category-assignment.js";
 // Admin: paginated + server-side search via /api/admin/categories (admin/mod only).
 // Response via successResponse({ data: items, total }) → apiClient unwraps to { data, total, ... }.
 async function loadAdminCategoryOptions(query, page) {
@@ -35,9 +38,17 @@ async function loadPublicCategoryOptions(query, _page) {
     const items = q ? all.filter((c) => c.label.toLowerCase().includes(q)) : all;
     return { items, hasMore: false, nextPage: 2 };
 }
-export function CategoryInlineSelect({ value, onChange, placeholder = "Search categories…", disabled, allowCreate = true, }) {
+export function CategoryInlineSelect({ value, onChange, placeholder = "Search categories…", disabled, allowCreate = true, extraValues, onExtraValuesChange, maxAssignments = MAX_CATEGORY_ASSIGNMENTS, }) {
     const loadOptions = allowCreate ? loadAdminCategoryOptions : loadPublicCategoryOptions;
-    return (_jsx(PaginatedSelect, { value: value || null, onChange: (v) => onChange(v ?? ""), loadOptions: loadOptions, placeholder: placeholder, disabled: disabled, createLabel: "category", drawerTitle: "Create Category", renderCreateForm: allowCreate
+    const primary = (_jsx(PaginatedSelect, { value: value || null, onChange: (v) => onChange(v ?? ""), loadOptions: loadOptions, placeholder: placeholder, disabled: disabled, createLabel: "category", drawerTitle: "Create Category", renderCreateForm: allowCreate
             ? ({ onCreated, onCancel }) => (_jsx(CategoryQuickCreateForm, { onSaved: (id, name) => onCreated({ value: id, label: name }), onCancel: onCancel }))
             : undefined }));
+    // Single-select unless the caller opted in — byte-identical to before.
+    if (!onExtraValuesChange)
+        return primary;
+    const extras = extraValues ?? [];
+    const remaining = Math.max(0, maxAssignments - 1 - extras.length);
+    return (_jsxs(Stack, { gap: "sm", children: [primary, _jsx(PaginatedSelect, { multiple: true, value: extras, onChange: (v) => onExtraValuesChange(Array.isArray(v) ? v : []), loadOptions: loadOptions, placeholder: remaining > 0
+                    ? `Also list under… (up to ${remaining} more)`
+                    : "No more categories can be added", disabled: disabled || remaining <= 0 }), _jsx(Text, { size: "xs", color: "muted", children: "Optional. Add a category from a DIFFERENT tree \u2014 a franchise, for example. Two categories from the same tree will be refused, because the broader one is already implied by the narrower." })] }));
 }

package/dist/features/seller/components/SellerProductShell.d.ts

@@ -6,6 +6,16 @@ export interface SellerProductDraft {
     slug?: string;
     description?: string;
     category?: string;
+    /**
+     * I2 — the assignment list, DEFAULT FIRST, with `category` mirroring `[0]`.
+     *
+     * 🛑 Declared on the TYPE as well as the Zod schema. The schema is
+     * `.passthrough()`, so an undeclared key survives at runtime — and stays
+     * untyped, so the picker could not read `values.categoryIds` at all. Both
+     * halves are needed, which is the same trap as a field missing from
+     * `PRODUCT_UPDATABLE_FIELDS` (Root Cause #101) one layer out.
+     */
+    categoryIds?: string[];
     brand?: string;
     condition?: string;
     tags?: string[];
@@ -134,10 +144,25 @@ export interface SellerProductShellProps {
     onDiscard?: () => void;
     isLoading?: boolean;
     storeSlug?: string;
-    /** Render a custom category selector (e.g. PaginatedSelect with createLabel). */
+    /**
+     * Render a custom category selector (e.g. PaginatedSelect with createLabel).
+     *
+     * I2 — `extraValues`/`onExtraValuesChange` carry the ADDITIONAL assignments.
+     * A selector that ignores them stays exactly single-select, which is what
+     * every surface except this one does.
+     */
     renderCategorySelector?: (props: {
         value: string;
         onChange: (v: string) => void;
+        /**
+         * 🛑 OPTIONAL, and that is the whole point. `QuickProductForm` is a second
+         * consumer of this slot and making these required broke it immediately —
+         * Root Cause #20, a public prop change without its consumers, which the
+         * comment above literally warns about. A selector that ignores them stays
+         * exactly single-select.
+         */
+        extraValues?: string[];
+        onExtraValuesChange?: (ids: string[]) => void;
     }) => React.ReactNode;
     /** Render a custom brand selector. */
     renderBrandSelector?: (props: {

package/dist/features/seller/components/SellerProductShell.js

@@ -46,6 +46,15 @@ const sellerProductSchema = z.object({
     description: z.string().max(10000).optional().or(z.literal("")),
     price: z.number().min(0).optional(),
     category: z.string().optional(),
+    /**
+     * I2 — the assignment list, DEFAULT FIRST. `category` mirrors `[0]`.
+     *
+     * Declared even though this schema is `.passthrough()`, because the draft's
+     * TYPE is what the render site reads `values.categoryIds` off — passthrough
+     * keeps an undeclared key at runtime and still leaves it untyped, so the
+     * picker could not see it.
+     */
+    categoryIds: z.array(z.string()).max(4).optional(),
     brand: z.string().optional(),
     isActive: z.boolean().optional(),
     images: z
@@ -106,7 +115,27 @@ function StepBasic({ values, onChange, renderCategorySelector, renderBrandSelect
         condition: CONDITION_OPTIONS.find((o) => o.value === (values.condition ?? "new"))?.label ?? "",
         siteName: "LetItRip",
     };
-    return (_jsxs(Stack, { gap: "md", children: [_jsx(FormField, { name: "title", label: "Title", type: "text", value: values.title ?? "", onChange: (v) => onChange({ title: v }), placeholder: "e.g. Charizard Base Set PSA 9" }), _jsxs(FormGroup, { columns: 2, children: [renderCategorySelector ? (_jsxs(_Fragment, { children: [_jsx(Text, { className: "text-[var(--appkit-color-text)] mb-1", size: "sm", weight: "medium", children: "Category" }), renderCategorySelector({ value: values.category ?? "", onChange: (v) => onChange({ category: v }) })] })) : (_jsx(FormField, { name: "category", label: "Category", type: "text", value: values.category ?? "", onChange: (v) => onChange({ category: v }), placeholder: "e.g. Trading Cards" })), _jsx(FormField, { name: "condition", label: "Condition", type: "select", value: values.condition ?? "new", onChange: (v) => onChange({ condition: v }), options: CONDITION_OPTIONS })] }), renderTemplateSelector?.({
+    return (_jsxs(Stack, { gap: "md", children: [_jsx(FormField, { name: "title", label: "Title", type: "text", value: values.title ?? "", onChange: (v) => onChange({ title: v }), placeholder: "e.g. Charizard Base Set PSA 9" }), _jsxs(FormGroup, { columns: 2, children: [renderCategorySelector ? (_jsxs(_Fragment, { children: [_jsx(Text, { className: "text-[var(--appkit-color-text)] mb-1", size: "sm", weight: "medium", children: "Category" }), renderCategorySelector({
+                                value: values.category ?? "",
+                                onChange: (v) => onChange({ category: v }),
+                                /*
+                                 * 🛑 `categoryIds[0]` is the DEFAULT assignment and is already
+                                 * rendered by the primary picker above, so the extras list is
+                                 * everything AFTER it. Passing the whole array would show the
+                                 * primary twice and let a seller "remove" it from a control that
+                                 * does not own it.
+                                 */
+                                extraValues: (values.categoryIds ?? []).slice(1),
+                                onExtraValuesChange: (ids) => onChange({
+                                    /*
+                                     * Rebuilt primary-first on every change, because the server
+                                     * derives the default by DEPTH and reorders the stored array
+                                     * anyway — sending it in a different order would make the
+                                     * form and the saved document disagree until the next load.
+                                     */
+                                    categoryIds: [values.category ?? "", ...ids].filter(Boolean),
+                                }),
+                            })] })) : (_jsx(FormField, { name: "category", label: "Category", type: "text", value: values.category ?? "", onChange: (v) => onChange({ category: v }), placeholder: "e.g. Trading Cards" })), _jsx(FormField, { name: "condition", label: "Condition", type: "select", value: values.condition ?? "new", onChange: (v) => onChange({ condition: v }), options: CONDITION_OPTIONS })] }), renderTemplateSelector?.({
                 categoryId: values.category ?? "",
                 condition: values.condition ?? "new",
                 context: templateContext,

package/dist/seed/_helpers/category-content-generated.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GENERATED by scripts/gen-category-content.mjs — do not edit by hand.
+ *
+ * `contentBody` per category, composed from FACTS ONLY (I7). Every clause
+ * traces to a committed source: canonical-beys.json for a model leaf,
+ * part-glossary.json for a part leaf, the forest's own child lists above them.
+ *
+ * 🛑 A node with nothing factual to say is ABSENT from this map rather than
+ * carrying an empty body — `CategoryHighlightsAndFaqSection` renders nothing
+ * when its inputs are empty, and an empty paragraph reads as a defect.
+ *
+ * 🛑 No price band appears here. `MARKET_BANDS` omits a band rather than
+ * guessing one, and a body that stated an unmeasured "typical price" would be
+ * the same guess with better typography.
+ *
+ * 🛑 No listing COUNT appears here either. Counts live in `categoryCounts` and
+ * move; a sentence saying "48 listings" is wrong the next day and nothing
+ * reports it.
+ *
+ * Model leaves with a body: 213 of 216
+ * Part leaves with a body:  532 of 752
+ */
+export declare const GENERATED_CATEGORY_CONTENT: Record<string, string>;
+export declare const GENERATED_CATEGORY_CONTENT_COUNT = 745;