@mohasinac/appkit 4.30.19 → 4.31.0

package/dist/features/auth/role-predicates.d.ts

@@ -13,22 +13,90 @@ type RoleCarrier = {
     role?: string | null;
 } | null | undefined;
 export declare const isAdminUser: (input: RoleCarrier) => boolean;
+/**
+ * True for sellers AND testers.
+ *
+ * A QA tester owns a real store — `becomeSeller`/`createStore` auto-approve it —
+ * so every seller-facing surface must admit them. Making `tester` a peer role
+ * of `seller` rather than a boolean is what removed the `isTester` flag; this
+ * predicate is where that peerage is expressed.
+ */
 export declare const isSellerUser: (input: RoleCarrier) => boolean;
+/** Strictly the `seller` role — for the rare case that must EXCLUDE testers. */
+export declare const isStrictSellerUser: (input: RoleCarrier) => boolean;
 export declare const isModeratorUser: (input: RoleCarrier) => boolean;
 export declare const isEmployeeUser: (input: RoleCarrier) => boolean;
 export declare const isBuyerUser: (input: RoleCarrier) => boolean;
 /**
- * True for real admins OR a tester explicitly flagged to test admin areas
- * (`isTester && canTestAdmin`). Used at the two RBAC chokepoints — the API route
- * guard (`createRouteHandler`) and the admin layout guard (`makeAdminSectionLayout`)
- * — so a flagged tester gets real read/write access to `/admin/**` without changing
- * their `role`. Callers must supply `isTester`/`canTestAdmin` from a live Firestore
- * read; these are never present in the session-cookie JWT claims (only `role` is).
+ * ── Tester identity: role first, legacy booleans second ──────────────────────
+ *
+ * `isTester` / `canTestAdmin` are being replaced by the `tester` role and the
+ * `tester:admin-surfaces` permission. Both predicates below read the NEW shape
+ * first and fall back to the OLD one, which is what makes the code safe to ship
+ * before the data migration: a tester whose document still says
+ * `{ role: "seller", isTester: true }` keeps working unchanged, and one already
+ * migrated to `{ role: "tester" }` works too.
+ *
+ * ⛔ Do NOT delete the fallbacks until the backfill has run and been verified.
+ * Removing them early locks every existing tester out of the Tester Hub and out
+ * of the auto-approved store the QA program depends on.
  */
-type EffectiveAdminCarrier = {
+type TesterCarrier = {
     role?: string | null;
     isTester?: boolean;
     canTestAdmin?: boolean;
+    permissions?: readonly string[] | null;
 } | null | undefined;
+/** The `tester` role, or the legacy `isTester` flag. */
+export declare const isTesterUser: (input: TesterCarrier) => boolean;
+/**
+ * May this tester reach `/admin/**`?
+ *
+ * The `tester:admin-surfaces` permission, or the legacy `canTestAdmin` flag.
+ * Granted through the same `permissions[]` array employees already use, so it
+ * is one grant mechanism rather than a bespoke boolean — and revoking it is a
+ * permission change, which the admin audit log already records.
+ */
+export declare const canTestAdminSurfaces: (input: TesterCarrier) => boolean;
+/**
+ * True for real admins OR a tester cleared for admin surfaces. Used at the two
+ * RBAC chokepoints — the API route guard (`createRouteHandler`) and the admin
+ * layout guard (`makeAdminSectionLayout`) — so a cleared tester gets real
+ * read/write access to `/admin/**` without holding the admin role.
+ *
+ * Callers must supply the role/permissions from a live Firestore read; none of
+ * these are present in the session-cookie JWT claims (only `role` is).
+ */
+type EffectiveAdminCarrier = TesterCarrier;
 export declare const isEffectiveAdminUser: (input: EffectiveAdminCarrier) => boolean;
+/**
+ * ── Is this account blocked? ─────────────────────────────────────────────────
+ *
+ * 🛑 There are TWO ban fields on `UserDocument` and, until 2026-08-29, no ban
+ * path wrote the one every guard reads.
+ *
+ *   `disabled`   — required, and read by EVERY server-side guard:
+ *                  auth-server, api-handler, authorization.requireActiveUser,
+ *                  Guards.requireActiveAccount, SessionContext.
+ *                  Its only writers, `userRepository.disable()/enable()`, had
+ *                  ZERO callers.
+ *   `isDisabled` — optional, and what `hardBanCascade` and the bulk-suspend
+ *                  route actually set, alongside the Firebase Auth record.
+ *
+ * The consequence was that **no ban terminated an existing session.** A hard
+ * ban set Firebase Auth `disabled: true`, which blocks a fresh login — and
+ * nothing else. Every authenticated request from a session cookie the user
+ * already held kept passing, because each guard consulted a Firestore field
+ * the ban never touched. Silent, and invisible to anyone testing a ban by
+ * logging out first.
+ *
+ * This predicate reads BOTH so already-banned accounts are enforced from the
+ * moment it ships, without waiting on a backfill. Every write path now sets
+ * both fields too; `isDisabled` is removed once the data is reconciled.
+ */
+type BanCarrier = {
+    disabled?: boolean | null;
+    isDisabled?: boolean | null;
+} | null | undefined;
+export declare const isAccountDisabled: (input: BanCarrier) => boolean;
 export {};

package/dist/features/auth/role-predicates.js

@@ -2,8 +2,34 @@ function normalizeRole(input) {
     return (input?.role ?? "user");
 }
 export const isAdminUser = (input) => normalizeRole(input) === "admin";
-export const isSellerUser = (input) => normalizeRole(input) === "seller";
+/**
+ * True for sellers AND testers.
+ *
+ * A QA tester owns a real store — `becomeSeller`/`createStore` auto-approve it —
+ * so every seller-facing surface must admit them. Making `tester` a peer role
+ * of `seller` rather than a boolean is what removed the `isTester` flag; this
+ * predicate is where that peerage is expressed.
+ */
+export const isSellerUser = (input) => {
+    const role = normalizeRole(input);
+    return role === "seller" || role === "tester";
+};
+/** Strictly the `seller` role — for the rare case that must EXCLUDE testers. */
+export const isStrictSellerUser = (input) => normalizeRole(input) === "seller";
 export const isModeratorUser = (input) => normalizeRole(input) === "moderator";
 export const isEmployeeUser = (input) => normalizeRole(input) === "employee";
 export const isBuyerUser = (input) => normalizeRole(input) === "user";
-export const isEffectiveAdminUser = (input) => isAdminUser(input) || Boolean(input?.isTester && input?.canTestAdmin);
+/** The `tester` role, or the legacy `isTester` flag. */
+export const isTesterUser = (input) => normalizeRole(input) === "tester" || input?.isTester === true;
+/**
+ * May this tester reach `/admin/**`?
+ *
+ * The `tester:admin-surfaces` permission, or the legacy `canTestAdmin` flag.
+ * Granted through the same `permissions[]` array employees already use, so it
+ * is one grant mechanism rather than a bespoke boolean — and revoking it is a
+ * permission change, which the admin audit log already records.
+ */
+export const canTestAdminSurfaces = (input) => Boolean(input?.permissions?.includes("tester:admin-surfaces")) ||
+    input?.canTestAdmin === true;
+export const isEffectiveAdminUser = (input) => isAdminUser(input) || (isTesterUser(input) && canTestAdminSurfaces(input));
+export const isAccountDisabled = (input) => input?.disabled === true || input?.isDisabled === true;

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

@@ -140,6 +140,28 @@ export interface UserDocument extends BaseDocument {
          * stay unique). Absent/missing IDs default to collapsed for a section the
          * user has never interacted with. See useCollapsedSections. */
         collapsedSections?: string[];
+        /**
+         * Which sections are OPEN, namespaced per surface: `scope -> openIds[]`.
+         *
+         * Supersedes `collapsedSections`, and the polarity flip is the point.
+         * Storing what is COLLAPSED cannot express "section 1 open by default"
+         * without a sentinel, and an unseen scope has to be guessed at; storing
+         * what is OPEN makes a never-seen scope default correctly *by absence*.
+         *
+         * Namespaced because the flat list was global: every page's ids shared one
+         * array and were kept apart only by a naming convention. The scope key is
+         * `"{portal}:{surface}"` — deliberately NOT a hash of the section ids,
+         * which would change the moment a section is added and silently reset
+         * every user's layout.
+         *
+         * `collapsedSections` is still written during the migration window; see
+         * `useSectionState`'s one-way dual-read.
+         */
+        sectionState?: Record<string, string[]>;
+        /** Preferred density for list surfaces that offer a view switch.
+         * Was written by the route, the API type and useDataViewMode while being
+         * absent from this interface — declared 2026-08-29. */
+        dataViewMode?: "table" | "grid" | "list";
         /** Which side CTA panels/drawers/sidebars dock to and where close buttons
          * sit. Absent/"right" = default (right-docked). "left" = left-hand mode. */
         handMode?: "left" | "right";

package/dist/features/auth/schemas/index.d.ts

@@ -26,9 +26,9 @@ export declare const loginSchema: z.ZodObject<{
  */
 export declare const registerPasswordSchema: z.ZodString;
 export declare const registerSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
     email: z.ZodString;
     password: z.ZodString;
-    displayName: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     email: string;
     password: string;

package/dist/features/auth/schemas/index.js

@@ -1,7 +1,20 @@
 export * from "./firestore";
 import { z } from "zod";
 import { ERROR_MESSAGES } from "../../../errors/messages";
+import { annotate } from "../../shell/field-ui-meta";
 // --- Form schemas -------------------------------------------------------------
+/*
+ * The `annotate()` calls below add UI metadata to a WeakMap keyed on the schema
+ * object; they return the same schema and change nothing about parsing. That is
+ * what makes them safe on `registerSchema`, which the register ROUTE also
+ * parses — the server never reads the registry.
+ *
+ * Every auth form is a single required section. That is not a section in any
+ * interesting sense, and it is not meant to be: `sectionRequired` renders the
+ * panel open and non-collapsible, so the page looks exactly as it does today
+ * and gains the pinned mobile action bar, which is the whole reason to put a
+ * short form through <SectionForm> at all.
+ */
 /**
  * Login form schema — use with react-hook-form + zodResolver.
  *
@@ -10,8 +23,13 @@ import { ERROR_MESSAGES } from "../../../errors/messages";
  * const form = useForm({ resolver: zodResolver(loginSchema) });
  */
 export const loginSchema = z.object({
-    email: z.string().email(),
-    password: z.string().min(6),
+    email: annotate(z.string().email(), {
+        section: "basics", sectionLabel: "Sign in", sectionRequired: true,
+        order: 1, row: "full", inputType: "email", label: "Email",
+    }),
+    password: annotate(z.string().min(6), {
+        section: "basics", order: 2, row: "full", inputType: "password", label: "Password",
+    }),
 });
 /**
  * Matches the server-side complexity rule enforced in
@@ -27,16 +45,34 @@ export const registerPasswordSchema = z
     .regex(/[a-z]/, ERROR_MESSAGES.PASSWORD.NO_LOWERCASE)
     .regex(/[0-9]/, ERROR_MESSAGES.PASSWORD.NO_NUMBER);
 export const registerSchema = z.object({
-    email: z.string().email(),
-    password: registerPasswordSchema,
-    displayName: z.string().min(1).optional(),
+    displayName: annotate(z.string().min(1).optional(), {
+        section: "basics", sectionLabel: "Create your account", sectionRequired: true,
+        order: 1, row: "full", label: "Display name",
+    }),
+    email: annotate(z.string().email(), {
+        section: "basics", order: 2, row: "full", inputType: "email", label: "Email",
+    }),
+    password: annotate(registerPasswordSchema, {
+        section: "basics", order: 3, row: "full", inputType: "password", label: "Password",
+        help: "At least 8 characters, with an uppercase letter, a lowercase letter and a number.",
+    }),
 });
 export const forgotPasswordSchema = z.object({
-    email: z.string().email(),
+    email: annotate(z.string().email(), {
+        section: "basics", sectionLabel: "Reset your password", sectionRequired: true,
+        order: 1, row: "full", inputType: "email", label: "Email",
+    }),
 });
 export const resetPasswordSchema = z.object({
-    token: z.string().min(1),
-    password: z.string().min(6),
+    // Carried in the reset link, never typed. `derived` keeps it out of the
+    // rendered form; the schema still requires it, because the SUBMIT needs it.
+    token: annotate(z.string().min(1), {
+        section: "basics", order: 1, derived: true, tier: "t2-server",
+    }),
+    password: annotate(z.string().min(6), {
+        section: "basics", sectionLabel: "Choose a new password", sectionRequired: true,
+        order: 2, row: "full", inputType: "password", label: "New password",
+    }),
 });
 // --- Auth user schema ---------------------------------------------------------
 export const userRoleSchema = z.enum([

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

@@ -1,4 +1,17 @@
-export type UserRole = "user" | "seller" | "moderator" | "employee" | "admin";
+/**
+ * `tester` sits at the SAME level as `seller` (see ROLE_HIERARCHY in
+ * security/authorization.ts) because a QA tester owns a real store and must
+ * pass every seller gate — the Tester QA Program depends on it.
+ *
+ * It replaces the `isTester` boolean. The companion `canTestAdmin` boolean
+ * became the `tester:admin-surfaces` permission rather than a second role,
+ * because this hierarchy is LINEAR: there is no level that means
+ * "seller-level, plus read admin" without also meaning admin.
+ *
+ * Both booleans are still read during the migration window — see
+ * `isTesterUser` / `canTestAdminSurfaces` in ./role-predicates.
+ */
+export type UserRole = "user" | "seller" | "tester" | "moderator" | "employee" | "admin";
 export interface AuthUser {
     id: string;
     email?: string;

package/dist/features/blog/api/route.js

@@ -25,7 +25,15 @@ export async function GET(request) {
     try {
         const url = new URL(request.url);
         const page = numParam(url, "page", 1);
-        const perPage = numParam(url, "perPage", 20);
+        /*
+         * `pageSize` is canonical; `perPage` is still read because this is a public
+         * GET and a link built before 2026-08-31 carries the old spelling. Ignoring
+         * it would silently serve the default page size with a 200 — the shape of
+         * failure this codebase keeps paying for.
+         */
+        const pageSize = url.searchParams.has("perPage")
+            ? numParam(url, "perPage", 20)
+            : numParam(url, "pageSize", 20);
         const sort = param(url, "sort") ?? "-publishedAt";
         const parts = [];
         const category = param(url, "category");
@@ -52,7 +60,7 @@ export async function GET(request) {
         // `blogRepository.listAll` rather than the generic `db.getRepository(...)`:
         // only the feature repository knows how to push a searchTxt clause down and
         // AND-refine the remaining terms.
-        const result = await blogRepository.listAll({ filters, sorts: sort, page, pageSize: perPage }, q ? { search: q } : undefined);
+        const result = await blogRepository.listAll({ filters, sorts: sort, page, pageSize }, q ? { search: q } : undefined);
         const meta = {
             total: result.total,
             page: result.page,

package/dist/features/blog/components/BlogIndexListing.js

@@ -106,7 +106,7 @@ export function BlogIndexListing({ initialData }) {
         tags: table.get(TABLE_KEYS.TAGS) || undefined,
         sort: table.get(TABLE_KEYS.SORT) || DEFAULT_SORT,
         page: table.getNumber(TABLE_KEYS.PAGE, 1),
-        perPage: table.getNumber(TABLE_KEYS.PAGE_SIZE, PAGE_SIZE),
+        pageSize: table.getNumber(TABLE_KEYS.PAGE_SIZE, PAGE_SIZE),
     };
     const { posts, totalPages, isLoading } = useBlogPosts(params, { initialData });
     const currentPage = table.getNumber("page", 1);

package/dist/features/blog/hooks/useBlog.js

@@ -11,8 +11,8 @@ export function useBlogPosts(params = {}, opts) {
         searchParams.set("tags", params.tags);
     if (params.page)
         searchParams.set("page", String(params.page));
-    if (params.perPage)
-        searchParams.set("perPage", String(params.perPage));
+    if (params.pageSize)
+        searchParams.set("pageSize", String(params.pageSize));
     if (params.sort)
         searchParams.set("sort", params.sort);
     if (params.featured !== undefined)

package/dist/features/blog/schemas/index.d.ts

@@ -458,6 +458,8 @@ export declare const blogListParamsSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodString>;
     q: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    /** Accepted, never emitted — a link built before the 2026-08-31 rename. */
     perPage: z.ZodOptional<z.ZodNumber>;
     sort: z.ZodOptional<z.ZodString>;
     featured: z.ZodOptional<z.ZodBoolean>;
@@ -466,6 +468,7 @@ export declare const blogListParamsSchema: z.ZodObject<{
     page?: number | undefined;
     q?: string | undefined;
     perPage?: number | undefined;
+    pageSize?: number | undefined;
     category?: "news" | "tips" | "guides" | "updates" | "community" | undefined;
     featured?: boolean | undefined;
     tags?: string | undefined;
@@ -474,6 +477,7 @@ export declare const blogListParamsSchema: z.ZodObject<{
     page?: number | undefined;
     q?: string | undefined;
     perPage?: number | undefined;
+    pageSize?: number | undefined;
     category?: "news" | "tips" | "guides" | "updates" | "community" | undefined;
     featured?: boolean | undefined;
     tags?: string | undefined;

package/dist/features/blog/schemas/index.js

@@ -90,6 +90,8 @@ export const blogListParamsSchema = z.object({
     tags: z.string().optional(),
     q: z.string().optional(),
     page: z.coerce.number().optional(),
+    pageSize: z.coerce.number().optional(),
+    /** Accepted, never emitted — a link built before the 2026-08-31 rename. */
     perPage: z.coerce.number().optional(),
     sort: z.string().optional(),
     featured: z.coerce.boolean().optional(),

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

@@ -43,7 +43,7 @@ export interface BlogListParams {
     tags?: string;
     q?: string;
     page?: number;
-    perPage?: number;
+    pageSize?: number;
     sort?: string;
     featured?: boolean;
 }

package/dist/features/catalogue/components/CatalogueItemEditorView.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Add or edit an item in a user's personal catalogue.
+ *
+ * Fields come from `createCatalogueItemSchema`'s annotations. Three need a
+ * `renderers` entry: the photo list (a real uploader, not the generator's
+ * disabled placeholder), and the two taxonomy selects, which are searchable
+ * because 47 categories is well past the 5-option threshold.
+ *
+ * ## `categorySlugs` and `brandSlug` were declared, read, and never collected
+ *
+ * Both are inherited from `ProductDraftFields` and both are read by
+ * `product-from-item.ts`, which builds the marketplace listing when an item is
+ * promoted. The hand-rolled form had no control for either, so every promoted
+ * listing carried `categorySlugs: []` — and per the Category Tree rules a
+ * product with an empty chain is invisible on every category and brand page it
+ * should appear under. A schema field with a reader and no control is the
+ * inverse of a dead control, and just as silent.
+ *
+ * `mainImage` is `t1-derive` — the first photo, not a field anyone types. It
+ * renders as a read-only preview rather than a text box that could be desynced
+ * from the gallery it is supposed to mirror.
+ */
 import React from "react";
 import type { CatalogueItemDocument } from "../schemas/firestore";
 export interface CatalogueItemEditorViewProps {

package/dist/features/catalogue/components/CatalogueItemEditorView.js

@@ -1,60 +1,120 @@
 "use client";
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Add or edit an item in a user's personal catalogue.
+ *
+ * Fields come from `createCatalogueItemSchema`'s annotations. Three need a
+ * `renderers` entry: the photo list (a real uploader, not the generator's
+ * disabled placeholder), and the two taxonomy selects, which are searchable
+ * because 47 categories is well past the 5-option threshold.
+ *
+ * ## `categorySlugs` and `brandSlug` were declared, read, and never collected
+ *
+ * Both are inherited from `ProductDraftFields` and both are read by
+ * `product-from-item.ts`, which builds the marketplace listing when an item is
+ * promoted. The hand-rolled form had no control for either, so every promoted
+ * listing carried `categorySlugs: []` — and per the Category Tree rules a
+ * product with an empty chain is invisible on every category and brand page it
+ * should appear under. A schema field with a reader and no control is the
+ * inverse of a dead control, and just as silent.
+ *
+ * `mainImage` is `t1-derive` — the first photo, not a field anyone types. It
+ * renders as a read-only preview rather than a text box that could be desynced
+ * from the gallery it is supposed to mirror.
+ */
 import React from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { useApiMutation } from "@mohasinac/appkit/client";
-import { Alert, Button, FieldInput, FieldSelect, FieldTextarea, Form, Grid, Row, Span, Stack, Toggle } from "../../../ui";
-import { FormErrorSummary } from "../../../ui/forms";
-import { MediaUploadList } from "../../media/upload/MediaUploadList";
-import { useMediaUpload } from "../../media";
+import { ACCOUNT_ENDPOINTS, BRAND_ENDPOINTS, CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints";
 import { apiClient } from "../../../http";
-import { ACCOUNT_ENDPOINTS } from "../../../constants/api-endpoints";
+import { Alert, PaginatedSelect, Stack } from "../../../ui";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
+import { FormShellContext, useFormShellState } from "../../../ui/forms/FormShell";
+import { buildSectionsFromSchema } from "../../shell/build-sections";
+import { SectionForm, useSectionFormNav } from "../../shell/SectionForm";
+import { useMediaUpload } from "../../media";
+import { MediaUploadList } from "../../media/upload/MediaUploadList";
 import { createCatalogueItemSchema } from "../schemas/validation";
-const CONDITION_OPTIONS = [
-    { label: "New", value: "new" },
-    { label: "Like new", value: "like_new" },
-    { label: "Good", value: "good" },
-    { label: "Fair", value: "fair" },
-    { label: "Poor", value: "poor" },
-    { label: "Used", value: "used" },
-    { label: "Refurbished", value: "refurbished" },
-];
+/** PUBLIC endpoints — this is a buyer surface; the admin ones would 403. */
+async function loadOptionsFrom(endpoint, query, page) {
+    const params = new URLSearchParams({ page: String(page), pageSize: "25" });
+    if (query)
+        params.set("q", query);
+    const res = await apiClient.get(`${endpoint}?${params.toString()}`);
+    const data = res ?? {};
+    return {
+        items: (data.items ?? []).map((c) => ({ value: c.id, label: c.name })),
+        hasMore: data.hasMore ?? false,
+    };
+}
+const loadCategoryOptions = (q, p) => loadOptionsFrom(CATEGORY_ENDPOINTS.LIST, q, p);
+const loadBrandOptions = (q, p) => loadOptionsFrom(BRAND_ENDPOINTS.LIST, q, p);
 export function CatalogueItemEditorView({ item, onSaved }) {
     const isCreate = !item;
     const queryClient = useQueryClient();
     const { upload } = useMediaUpload();
     const uploadIndexRef = React.useRef(0);
-    const [title, setTitle] = React.useState(item?.title ?? "");
-    const [description, setDescription] = React.useState(item?.description ?? "");
-    const [condition, setCondition] = React.useState(item?.condition ?? "");
-    const [price, setPrice] = React.useState(item?.price ? String(item.price) : "0");
-    const [quantity, setQuantity] = React.useState(String(item?.quantity ?? 1));
-    const [visibility, setVisibility] = React.useState(item?.visibility ?? "public");
-    const [images, setImages] = React.useState(item?.images ?? []);
-    const galleryFields = images.map((url) => ({ url, type: "image" }));
-    const handleUpload = async (file) => {
+    const [form, setForm] = React.useState({
+        title: item?.title ?? "",
+        description: item?.description ?? "",
+        condition: item?.condition ?? "",
+        quantity: item?.quantity ?? 1,
+        price: item?.price ?? 0,
+        images: item?.images ?? [],
+        mainImage: item?.mainImage ?? item?.images?.[0] ?? "",
+        categorySlugs: item?.categorySlugs ?? [],
+        brandSlug: item?.brandSlug ?? "",
+        visibility: item?.visibility ?? "public",
+    });
+    const handleUpload = React.useCallback(async (file) => {
         uploadIndexRef.current += 1;
         return upload(file, "catalogue", true, {
             type: "catalogue-image",
-            item: title || "item",
+            item: form.title || "item",
             index: uploadIndexRef.current,
         });
-    };
+    }, [upload, form.title]);
+    const sections = React.useMemo(() => buildSectionsFromSchema(createCatalogueItemSchema, {
+        renderers: {
+            images: ({ values, onChange }) => (_jsx(MediaUploadList, { label: "Photos", value: values.images.map((url) => ({ url, type: "image" })), onChange: (fields) => {
+                    const urls = fields.map((f) => f.url);
+                    // `mainImage` is derived, so it moves with the gallery rather
+                    // than pointing at a photo the user has since removed.
+                    onChange({ images: urls, mainImage: urls[0] ?? "" });
+                }, onUpload: handleUpload, accept: "image/*", maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." })),
+            categorySlugs: ({ values, onChange }) => (
+            // Explicit `<string>`: with `multiple`, `value` is `V[]`, so an
+            // inferred V reads the array itself as the option type.
+            _jsx(PaginatedSelect, { multiple: true, value: values.categorySlugs, onChange: (v) => onChange({ categorySlugs: v ?? [] }), loadOptions: loadCategoryOptions, placeholder: "Search categories\u2026", searchPlaceholder: "Type a category name\u2026", noResultsText: "No categories found", ariaLabel: "Categories" })),
+            brandSlug: ({ values, onChange }) => (_jsx(PaginatedSelect, { value: values.brandSlug || null, onChange: (v) => onChange({ brandSlug: v ?? "" }), loadOptions: loadBrandOptions, placeholder: "Search brands\u2026", searchPlaceholder: "Type a brand name\u2026", noResultsText: "No brands found", ariaLabel: "Brand" })),
+        },
+    }), [handleUpload]);
+    const nav = useSectionFormNav(sections, form, { scope: "user:catalogue-item" });
+    const { shellCtx, setFieldError, clearErrors } = useFormShellState(createCatalogueItemSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
     const saveMutation = useApiMutation({
         successMessage: isCreate ? "Added to your catalogue" : "Catalogue item updated",
+        errorMessage: isCreate ? "Could not add this item." : "Could not save your changes.",
         mutationFn: async () => {
             const payload = {
-                title,
-                description: description || undefined,
-                condition: condition || undefined,
-                price: Math.round(Number(price) * 100) / 100,
-                quantity: Number(quantity),
-                visibility,
-                images,
-                mainImage: images[0],
+                title: form.title,
+                description: form.description || undefined,
+                condition: form.condition || undefined,
+                price: Math.round(Number(form.price) * 100) / 100,
+                quantity: Number(form.quantity),
+                visibility: form.visibility,
+                images: form.images,
+                mainImage: form.images[0],
+                categorySlugs: form.categorySlugs,
+                brandSlug: form.brandSlug || undefined,
             };
-            if (isCreate)
+            if (isCreate) {
                 return apiClient.post(ACCOUNT_ENDPOINTS.CATALOGUE, payload);
+            }
             return apiClient.patch(ACCOUNT_ENDPOINTS.CATALOGUE_BY_ID(item.id), payload);
         },
         onSuccess: (saved) => {
@@ -62,21 +122,21 @@ export function CatalogueItemEditorView({ item, onSaved }) {
             onSaved?.(saved.id);
         },
     });
-    return (_jsx(Form, { schema: createCatalogueItemSchema, spacing: "md", children: ({ setFieldError, markSubmitAttempted }) => (_jsxs(Stack, { gap: "md", children: [item?.listingStatus && item.listingStatus !== "not_listed" && (_jsxs(Alert, { variant: "info", children: ["This item is ", item.listingStatus.replace(/_/g, " "), item.listingStatus === "rejected" && item.rejectionReason ? `: ${item.rejectionReason}` : "."] })), _jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "title", label: "Title", required: true, value: title, onChange: setTitle }), _jsx(FieldSelect, { name: "condition", label: "Condition", value: condition, onChange: setCondition, options: CONDITION_OPTIONS }), _jsx(FieldInput, { name: "price", label: "Estimated resale price (\u20B9)", type: "number", min: "0", value: price, onChange: setPrice }), _jsx(FieldInput, { name: "quantity", label: "Quantity", type: "number", min: "1", value: quantity, onChange: setQuantity })] }), _jsx(FieldTextarea, { name: "description", label: "Description", value: description, onChange: setDescription, rows: 3 }), _jsx(MediaUploadList, { label: "Photos", value: galleryFields, onChange: (fields) => setImages(fields.map((f) => f.url)), onUpload: handleUpload, accept: "image/*", maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." }), _jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Toggle, { checked: visibility === "public", onChange: (checked) => setVisibility(checked ? "public" : "private"), size: "sm" }), _jsx(Span, { children: visibility === "public" ? "Public — visible on your profile" : "Private — only you can see it" })] }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
-                        // type="button" — no native submit, so unhide the summary here.
-                        markSubmitAttempted();
-                        const parsed = createCatalogueItemSchema.safeParse({
-                            title,
-                            images,
-                            price: Math.round(Number(price) * 100) / 100,
-                            quantity: Number(quantity),
-                            visibility,
-                        });
-                        if (!parsed.success) {
-                            for (const issue of parsed.error.issues)
-                                setFieldError(String(issue.path[0]), issue.message);
-                            return;
-                        }
-                        saveMutation.mutate();
-                    }, children: isCreate ? "Add to Catalogue" : "Save Changes" })] })) }));
+    const onSubmit = () => {
+        clearErrors();
+        const parsed = createCatalogueItemSchema.safeParse({
+            ...form,
+            price: Math.round(Number(form.price) * 100) / 100,
+            quantity: Number(form.quantity),
+            brandSlug: form.brandSlug || undefined,
+        });
+        if (!parsed.success) {
+            applyZodIssues(parsed.error.issues, setFieldError);
+            return;
+        }
+        saveMutation.mutate();
+    };
+    return (_jsxs(Stack, { gap: "md", children: [item?.listingStatus && item.listingStatus !== "not_listed" && (_jsxs(Alert, { variant: "info", children: ["This item is ", item.listingStatus.replace(/_/g, " "), item.listingStatus === "rejected" && item.rejectionReason
+                        ? `: ${item.rejectionReason}`
+                        : "."] })), _jsxs(FormShellContext.Provider, { value: shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: form, onChange: (partial) => setForm((prev) => Object.assign({}, prev, partial)), onSubmit: onSubmit, schema: createCatalogueItemSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, isLoading: saveMutation.isPending, submitLabel: isCreate ? "Add to Catalogue" : "Save Changes" })] })] }));
 }

package/dist/features/catalogue/schemas/validation.d.ts

@@ -2,13 +2,13 @@ import { z } from "zod";
 export declare const createCatalogueItemSchema: z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
+    quantity: z.ZodDefault<z.ZodNumber>;
     images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     mainImage: z.ZodOptional<z.ZodString>;
-    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
     categorySlugs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     brandSlug: z.ZodOptional<z.ZodString>;
     price: z.ZodOptional<z.ZodNumber>;
-    quantity: z.ZodDefault<z.ZodNumber>;
     visibility: z.ZodDefault<z.ZodEnum<["public", "private"]>>;
 }, "strip", z.ZodTypeAny, {
     title: string;
@@ -36,13 +36,13 @@ export declare const createCatalogueItemSchema: z.ZodObject<{
 export declare const updateCatalogueItemSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    condition: z.ZodOptional<z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>>;
+    quantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     images: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     mainImage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-    condition: z.ZodOptional<z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>>;
     categorySlugs: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
     brandSlug: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     price: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
-    quantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     visibility: z.ZodOptional<z.ZodDefault<z.ZodEnum<["public", "private"]>>>;
 }, "strip", z.ZodTypeAny, {
     title?: string | undefined;