@mohasinac/appkit 4.30.19 → 4.31.0

package/dist/features/account/components/UserSupportView.js

@@ -1,14 +1,18 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Li, useApiMutation } from "@mohasinac/appkit/client";
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { Button, Div, FormActions, Row, Select, SideDrawer, Span, Stack, Text, Ul, useToast } from "../../../ui";
-import { FieldInput } from "../../../ui/forms/FieldInput";
+import { Button, Div, Row, SideDrawer, Span, Stack, Text, Ul, useToast } from "../../../ui";
 import { FieldTextarea } from "../../../ui/forms/FieldTextarea";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
+import { FormShellContext, useFormShellState } from "../../../ui/forms/FormShell";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
+import { buildSectionsFromSchema, visibleValues } from "../../shell/build-sections";
+import { SectionForm, useSectionFormNav } from "../../shell/SectionForm";
 import { apiClient } from "../../../http";
 import { supportTicketCreateSchema } from "../../support/schemas/ticket-create-form";
-import { ValidationError } from "../../../errors/validation-error";
+import { TicketCategoryValues } from "../../support/schemas/firestore";
 import { SUPPORT_ENDPOINTS } from "../../../constants/api-endpoints";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
@@ -18,23 +22,44 @@ const __O = {
     yAuto: "overflow-y-auto",
 };
 // --- Constants ---------------------------------------------------------------
-const CATEGORY_OPTIONS = [
-    { label: "Order Issue", value: "order_issue" },
-    { label: "Billing / Payment", value: "billing_payment" },
-    { label: "Account", value: "account" },
-    { label: "Listing Dispute", value: "listing_dispute" },
-    { label: "Refund Request", value: "refund_request" },
-    { label: "Auction Dispute", value: "auction_dispute" },
+/**
+ * Category labels.
+ *
+ * Keyed off `TicketCategoryValues` rather than written as a parallel array, so
+ * a twelfth category cannot be added to the schema and silently omitted here —
+ * Root Cause #61, which the schema itself already guards on its own side.
+ *
+ * There are ten, so the generator renders this as a `PaginatedSelect`: it was
+ * a native `<Select>` with no `name`, which is over the five-option threshold
+ * AND unreachable by `applyZodIssues`.
+ */
+const CATEGORY_LABELS = {
+    [TicketCategoryValues.ORDER_ISSUE]: "Order issue",
+    [TicketCategoryValues.BILLING_PAYMENT]: "Billing / payment",
+    [TicketCategoryValues.ACCOUNT]: "Account",
+    [TicketCategoryValues.LISTING_DISPUTE]: "Listing dispute",
+    /*
+     * The hand-written array this replaced had TEN entries and the schema has
+     * ELEVEN — `scam_report` was simply missing, so a user could never file one
+     * from this drawer even though the route accepts it.
+     */
+    [TicketCategoryValues.SCAM_REPORT]: "Report a scam",
+    [TicketCategoryValues.REFUND_REQUEST]: "Refund request",
+    [TicketCategoryValues.AUCTION_DISPUTE]: "Auction dispute",
     // ST-4 — sellers use this to request changes to admin-controlled
     // store fields (status, capabilities, verification badge).
-    { label: "Store Change Request (sellers)", value: "store_change_request" },
+    [TicketCategoryValues.STORE_CHANGE_REQUEST]: "Store change request (sellers)",
     // ST-3 — buyers/sellers request mutation of order line items
-    { label: "Order Modification Request", value: "order_modification_request" },
+    [TicketCategoryValues.ORDER_MODIFICATION_REQUEST]: "Order modification request",
     // ST-5 — appeal a soft or hard ban; bypasses the create_support_tickets
     // soft-ban guard server-side.
-    { label: "Appeal a ban (unban request)", value: "unban_request" },
-    { label: "General", value: "general" },
-];
+    [TicketCategoryValues.UNBAN_REQUEST]: "Appeal a ban (unban request)",
+    [TicketCategoryValues.GENERAL]: "General",
+};
+const CATEGORY_OPTIONS = Object.values(TicketCategoryValues).map((value) => ({
+    value,
+    label: CATEGORY_LABELS[value] ?? value.replace(/_/g, " "),
+}));
 const CLS_MSG_USER = "border bg-[var(--appkit-color-surface)]/40 border-[var(--appkit-color-border)]";
 const CLS_MSG_STAFF = "bg-info-surface border border-info dark:bg-info-surface dark:border-info";
 const STATUS_BADGE = {
@@ -49,17 +74,20 @@ const ROLE_LABEL = {
     support: "Support",
     admin: "Admin",
 };
+const EMPTY_TICKET = {
+    category: TicketCategoryValues.GENERAL,
+    subject: "",
+    description: "",
+    orderId: "",
+};
 export function UserSupportView(_props) {
     const queryClient = useQueryClient();
     const { showToast } = useToast();
     const [detailOpen, setDetailOpen] = useState(false);
     const [selectedTicket, setSelectedTicket] = useState(null);
     const [newTicketOpen, setNewTicketOpen] = useState(false);
-    // New ticket form state
-    const [newSubject, setNewSubject] = useState("");
-    const [newCategory, setNewCategory] = useState("general");
-    const [newDescription, setNewDescription] = useState("");
-    const [newOrderId, setNewOrderId] = useState("");
+    const [newTicket, setNewTicket] = useState(EMPTY_TICKET);
+    const patchTicket = (partial) => setNewTicket((prev) => Object.assign({}, prev, partial));
     // Reply state
     const [replyBody, setReplyBody] = useState("");
     const { data, isLoading, error } = useQuery({
@@ -70,44 +98,45 @@ export function UserSupportView(_props) {
     const invalidate = () => queryClient.invalidateQueries({ queryKey: ["user", "support-tickets"] });
     const createMutation = useApiMutation({
         errorMessage: "Failed to create ticket.",
-        mutationFn: async () => {
-            /*
-             * This drawer validated NOTHING. Its sibling page
-             * (`/user/support/new`) hand-rolled a `canSubmit` boolean that required
-             * an order id for an `order_issue` ticket — a real rule, since an order
-             * complaint with no order is unactionable — and the route did not
-             * enforce it either. So the same ticket was acceptable or not purely
-             * depending on which surface the user happened to open.
-             *
-             * One schema now, across both surfaces and the route.
-             */
-            const parsed = supportTicketCreateSchema.safeParse({
-                subject: newSubject.trim(),
-                category: newCategory,
-                description: newDescription.trim(),
-                orderId: newOrderId.trim() || undefined,
-            });
-            if (!parsed.success) {
-                /*
-                 * ValidationError, not a bare Error — it carries the issue LIST, so
-                 * the failure keeps which field caused it. A plain Error flattens the
-                 * whole thing to one string, which is what `audit-unvalidated-safeparse`
-                 * exists to stop. It caught this in my own code.
-                 */
-                throw new ValidationError(parsed.error.issues[0]?.message ?? "Check the ticket details.", parsed.error.issues);
-            }
-            await apiClient.post(SUPPORT_ENDPOINTS.TICKETS, parsed.data);
-        },
+        mutationFn: async (values) => apiClient.post(SUPPORT_ENDPOINTS.TICKETS, values),
         onSuccess: () => {
             showToast("Support ticket created.", "success");
             setNewTicketOpen(false);
-            setNewSubject("");
-            setNewCategory("general");
-            setNewDescription("");
-            setNewOrderId("");
+            setNewTicket(EMPTY_TICKET);
             invalidate();
         },
     });
+    /*
+     * This drawer validated NOTHING before the schema landed, and its sibling
+     * page (`/user/support/new`) hand-rolled a `canSubmit` that required an
+     * order id for an `order_issue` ticket — a real rule the route did not
+     * enforce either, so the same ticket was acceptable or not depending purely
+     * on which surface the user opened. One schema now covers both and the
+     * route; the parse below is what reports it, per field.
+     */
+    const sections = useMemo(() => buildSectionsFromSchema(supportTicketCreateSchema, {
+        options: { category: CATEGORY_OPTIONS },
+    }), []);
+    const nav = useSectionFormNav(sections, newTicket, { scope: "user:support-ticket" });
+    const { shellCtx, setFieldError, clearErrors } = useFormShellState(supportTicketCreateSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
+    const submitTicket = () => {
+        clearErrors();
+        /*
+         * `visibleValues` is what keeps an order id typed before switching
+         * category out of a ticket that has nothing to do with an order — the
+         * `when` on that field hides the control and never clears it.
+         */
+        const parsed = supportTicketCreateSchema.safeParse(visibleValues(supportTicketCreateSchema, newTicket));
+        if (!parsed.success) {
+            applyZodIssues(parsed.error.issues, setFieldError);
+            return;
+        }
+        createMutation.mutate(parsed.data);
+    };
     const replyMutation = useApiMutation({
         errorMessage: "Failed to send reply.",
         mutationFn: async () => {
@@ -119,16 +148,18 @@ export function UserSupportView(_props) {
             invalidate();
         },
     });
-    return (_jsxs(_Fragment, { children: [_jsxs(Div, { className: "mx-auto max-w-2xl", paddingY: "y-lg", paddingX: "x-md", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", children: [_jsx(Text, { size: "xl", weight: "semibold", color: "primary", children: "Support Tickets" }), _jsx(Button, { type: "button", variant: "primary", size: "sm", onClick: () => setNewTicketOpen(true), children: "New ticket" })] }), renderTicketListArea({ isLoading, error, tickets, setSelectedTicket, setDetailOpen })] }), renderNewTicketDrawer({ newTicketOpen, setNewTicketOpen, newCategory, setNewCategory, newSubject, setNewSubject, newOrderId, setNewOrderId, newDescription, setNewDescription, createMutation }), renderTicketDetailDrawer({ detailOpen, setDetailOpen, selectedTicket, replyBody, setReplyBody, replyMutation })] }));
+    return (_jsxs(_Fragment, { children: [_jsxs(Div, { className: "mx-auto max-w-2xl", paddingY: "y-lg", paddingX: "x-md", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", children: [_jsx(Text, { size: "xl", weight: "semibold", color: "primary", children: "Support Tickets" }), _jsx(Button, { type: "button", variant: "primary", size: "sm", onClick: () => setNewTicketOpen(true), children: "New ticket" })] }), renderTicketListArea({ isLoading, error, tickets, setSelectedTicket, setDetailOpen })] }), _jsx(SideDrawer, { isOpen: newTicketOpen, onClose: () => setNewTicketOpen(false), title: "Open a support ticket", children: _jsx(Stack, { className: `${__P.p4}`, gap: "md", children: _jsxs(FormShellContext.Provider, { value: shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: newTicket, onChange: patchTicket, onSubmit: submitTicket, schema: supportTicketCreateSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, isLoading: createMutation.isPending, submitLabel: "Submit ticket", onCancel: () => setNewTicketOpen(false), 
+                                /*
+                                 * A drawer owns its own footer — `useIsInsideOverlay` already
+                                 * suppresses the viewport-fixed bar, which would otherwise
+                                 * render BEHIND the backdrop. Stated rather than relied on.
+                                 */
+                                bottomBar: false })] }) }) }), renderTicketDetailDrawer({ detailOpen, setDetailOpen, selectedTicket, replyBody, setReplyBody, replyMutation })] }));
 }
 function renderTicketListArea(props) {
     const { isLoading, error, tickets, setSelectedTicket, setDetailOpen } = props;
     return (_jsxs(_Fragment, { children: [isLoading && (_jsx(Stack, { gap: "3", children: [1, 2, 3].map((i) => _jsx(Div, { className: "h-16 animate-pulse", surface: "subtle", rounded: "lg" }, i)) })), error && (_jsx(Div, { textSize: "sm", className: "border border-error/20", color: "error", surface: "danger-surface", padding: "inline", rounded: "xl", children: "Failed to load support tickets." })), !isLoading && tickets.length === 0 && (_jsx(Div, { className: "text-left", surface: "muted", paddingY: "y-2xl", paddingX: "x-lg", rounded: "xl", border: "default", children: _jsx(Text, { size: "sm", color: "muted", children: "You haven't opened any support tickets yet." }) })), _jsx(Ul, { spacing: "loose", children: tickets.map((ticket) => (_jsx(Li, { children: _jsx(Button, { rounded: "xl", variant: "ghost", type: "button", shadow: "sm", border: "default", paddingX: "md", paddingY: "md", className: "w-full bg-[var(--appkit-color-surface)] text-left hover:border-[var(--appkit-color-primary-300)] transition-colors", onClick: () => { setSelectedTicket(ticket); setDetailOpen(true); }, children: _jsxs(Row, { align: "start", justify: "between", gap: "sm", children: [_jsxs(Div, { className: "min-w-0 flex-1", children: [_jsx(Text, { className: "truncate", color: "primary", weight: "medium", children: ticket.subject }), _jsxs(Text, { size: "xs", color: "muted", children: [ticket.category.replace(/_/g, " "), ticket.orderId ? ` · Order: ${ticket.orderId}` : ""] })] }), _jsx(Span, { size: "xs", weight: "medium", className: `shrink-0 inline-flex ${STATUS_BADGE[ticket.status] ?? STATUS_BADGE.open}`, padding: "pill-sm", rounded: "full", children: ticket.status.replace(/_/g, " ") })] }) }) }, ticket.id))) })] }));
 }
-function renderNewTicketDrawer(props) {
-    const { newTicketOpen, setNewTicketOpen, newCategory, setNewCategory, newSubject, setNewSubject, newOrderId, setNewOrderId, newDescription, setNewDescription, createMutation } = props;
-    return (_jsx(SideDrawer, { isOpen: newTicketOpen, onClose: () => setNewTicketOpen(false), title: "Open a support ticket", children: _jsxs(Stack, { className: `${__P.p4}`, gap: "md", children: [_jsx(Select, { label: "Category", options: CATEGORY_OPTIONS, value: newCategory, onValueChange: setNewCategory }), _jsx(FieldInput, { name: "subject", label: "Subject", type: "text", value: newSubject, onChange: setNewSubject, placeholder: "Brief description of the issue" }), newCategory === "order_issue" && (_jsx(FieldInput, { name: "orderId", label: "Order ID", type: "text", value: newOrderId, onChange: setNewOrderId, placeholder: "e.g. order-3-20260508-a1b2c3" })), _jsx(FieldTextarea, { name: "description", label: "Description", value: newDescription, onChange: setNewDescription, rows: 4, placeholder: "Describe the issue in detail\u2026" }), _jsxs(FormActions, { align: "right", children: [_jsx(Button, { type: "button", variant: "secondary", onClick: () => setNewTicketOpen(false), children: "Cancel" }), _jsx(Button, { type: "button", isLoading: createMutation.isPending, disabled: !newSubject.trim() || !newDescription.trim() || createMutation.isPending, onClick: () => createMutation.mutate(), children: "Submit ticket" })] })] }) }));
-}
 function renderTicketDetailDrawer(props) {
     const { detailOpen, setDetailOpen, selectedTicket, replyBody, setReplyBody, replyMutation } = props;
     return (_jsx(SideDrawer, { isOpen: detailOpen, onClose: () => setDetailOpen(false), title: selectedTicket?.subject ?? "Ticket", children: selectedTicket && (_jsxs(Stack, { className: `${__P.p4}`, gap: "md", children: [_jsxs(Row, { wrap: true, gap: "sm", children: [_jsx(Span, { size: "xs", weight: "medium", className: `inline-flex ${STATUS_BADGE[selectedTicket.status] ?? STATUS_BADGE.open}`, rounded: "full", padding: "pill-sm-tall", children: selectedTicket.status.replace(/_/g, " ") }), _jsx(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: selectedTicket.category.replace(/_/g, " ") }), selectedTicket.orderId && _jsxs(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: ["Order: ", selectedTicket.orderId] })] }), selectedTicket.description && (_jsxs(Div, { className: `${__P.p3}`, rounded: "lg", surface: "muted", border: "default", children: [_jsx(Text, { className: "mb-1 tracking-wide", size: "xs", weight: "semibold", color: "muted", transform: "uppercase", children: "Your description" }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", size: "sm", children: selectedTicket.description })] })), (selectedTicket.messages ?? []).length > 0 && (_jsxs(Stack, { gap: "sm", children: [_jsx(Text, { className: "tracking-wide", color: "muted", size: "xs", weight: "semibold", transform: "uppercase", children: "Messages" }), _jsx(Stack, { className: `max-h-72 ${__O.yAuto}`, gap: "sm", children: (selectedTicket.messages ?? []).map((msg, i) => (_jsxs(Div, { textSize: "sm", className: `${__P.p3} ${msg.authorRole === "user" ? CLS_MSG_USER : CLS_MSG_STAFF}`, rounded: "lg", children: [_jsxs(Row, { color: "muted", textSize: "xs", className: "mb-1", align: "center", gap: "sm", children: [_jsx(Span, { weight: "medium", color: "muted", children: ROLE_LABEL[msg.authorRole ?? "user"] ?? msg.authorRole }), msg.createdAt && _jsx(Span, { children: new Date(msg.createdAt).toLocaleString() })] }), _jsx(Text, { className: "whitespace-pre-wrap", color: "primary", children: msg.body })] }, msg.id ?? i))) })] })), selectedTicket.status !== "closed" && selectedTicket.status !== "resolved" && (_jsxs(Stack, { gap: "sm", children: [_jsx(FieldTextarea, { name: "reply", label: "Reply", value: replyBody, onChange: setReplyBody, rows: 3, placeholder: "Add a message to your ticket\u2026" }), _jsx(Button, { type: "button", variant: "primary", size: "sm", isLoading: replyMutation.isPending, disabled: !replyBody.trim() || replyMutation.isPending, onClick: () => replyMutation.mutate(), children: "Send reply" })] }))] })) }));

package/dist/features/account/components/index.d.ts

@@ -3,7 +3,7 @@ export type { UserSidebarProps, UserNavItem } from "./UserSidebar";
 export { AddressCard, AddressBook } from "./AddressBook";
 export type { AddressCardAddress, AddressCardProps } from "./AddressBook";
 export { AddressForm } from "./AddressForm";
-export type { AddressFormLabels, AddressFormPlaceholders } from "./AddressForm";
+export type { AddressFormLabels } from "./AddressForm";
 export { AddressSelectorCreate } from "./AddressSelectorCreate";
 export { NotificationBell } from "./NotificationBell";
 export type { NotificationBellLabels, NotificationBellProps, NotificationBellRenderLinkProps, } from "./NotificationBell";
@@ -27,12 +27,6 @@ export { UserNotificationsView } from "./UserNotificationsView";
 export type { UserNotificationsViewProps, UserNotificationsViewLabels, } from "./UserNotificationsView";
 export { UserOffersPanel } from "./UserOffersPanel";
 export type { UserOffersPanelProps } from "./UserOffersPanel";
-export { MessagesView } from "./MessagesView";
-export type { MessagesViewProps, MessagesViewLabels } from "./MessagesView";
-export { ChatList } from "./ChatList";
-export type { ChatListProps, ChatListLabels } from "./ChatList";
-export { ChatWindow } from "./ChatWindow";
-export type { ChatWindowProps, ChatWindowLabels } from "./ChatWindow";
 export { BecomeSellerView } from "./BecomeSellerView";
 export type { BecomeSellerViewProps, BecomeSellerViewLabels, } from "./BecomeSellerView";
 export { UserOrderTrackView } from "./UserOrderTrackView";

package/dist/features/account/components/index.js

@@ -13,9 +13,6 @@ export { OrderDetailView } from "./OrderDetailView";
 export { UserAddressesView } from "./UserAddressesView";
 export { UserNotificationsView } from "./UserNotificationsView";
 export { UserOffersPanel } from "./UserOffersPanel";
-export { MessagesView } from "./MessagesView";
-export { ChatList } from "./ChatList";
-export { ChatWindow } from "./ChatWindow";
 export { BecomeSellerView } from "./BecomeSellerView";
 export { UserOrderTrackView } from "./UserOrderTrackView";
 export { UserReturnsView } from "./UserReturnsView";

package/dist/features/account/hooks/useAddresses.d.ts

@@ -42,9 +42,10 @@ interface SetDefaultAddressData {
 }
 export interface AddressFilterParams {
     q?: string;
-    addressType?: string;
-    verified?: boolean;
-    activeOnly?: boolean;
+    /** Only the owner's default address. */
+    defaultOnly?: boolean;
+    /** Pipe-joined `AddressBanStatus` values. */
+    banStatus?: string;
 }
 export declare function useAddresses(options?: {
     enabled?: boolean;

package/dist/features/account/hooks/useAddresses.js

@@ -10,12 +10,10 @@ export function useAddresses(options) {
     const sp = new URLSearchParams();
     if (options?.filters?.q)
         sp.set("q", options.filters.q);
-    if (options?.filters?.addressType)
-        sp.set("addressType", options.filters.addressType);
-    if (options?.filters?.verified)
-        sp.set("verified", "true");
-    if (options?.filters?.activeOnly)
-        sp.set("activeOnly", "true");
+    if (options?.filters?.defaultOnly)
+        sp.set("defaultOnly", "true");
+    if (options?.filters?.banStatus)
+        sp.set("banStatus", options.filters.banStatus);
     const qs = sp.toString();
     const base = options?.listEndpoint ?? DEFAULT_ENDPOINTS.list;
     const endpoint = qs ? `${base}?${qs}` : base;

package/dist/features/account/hooks/useCollapsedSections.d.ts

@@ -1,11 +1,47 @@
+export type SectionExpandMode = "multi" | "single";
+export interface UseSectionStateOptions {
+    /**
+     * `"{portal}:{surface}"`, e.g. `"admin:dashboard"` or `"store:product-form"`.
+     *
+     * **The empty string means EPHEMERAL** — in-memory only, no profile read, no
+     * profile write, no localStorage. It exists so a surface can adopt this hook
+     * before it has chosen a durable scope name, without every such surface
+     * writing junk under `sectionState[""]` and without the legacy-derivation
+     * branch below reading another page's `collapsedSections` into it.
+     */
+    scope: string;
+    /** Every section id this surface manages, in display order. */
+    sectionIds: string[];
+    /**
+     * Which sections are open for a user who has never touched this surface.
+     * Defaults to the FIRST section — "required first, everything else
+     * collapsed". Pass `[]` for all-collapsed.
+     */
+    defaultOpen?: string[];
+    /** `"multi"` (default) lets several sections be open at once. `"single"` is
+     * accordion: opening one closes its siblings. */
+    mode?: SectionExpandMode;
+}
+export interface UseSectionStateResult {
+    isOpen: (id: string) => boolean;
+    toggle: (id: string) => void;
+    /** Force a section open without closing anything — what a validation error
+     * needs. Never collapses, even under `mode: "single"`. */
+    open: (id: string) => void;
+    /** Replace the whole open set. For a caller that already computes the next
+     * array itself (`SectionForm`'s controlled/uncontrolled `setOpenIds`
+     * contract) rather than expressing the change as a per-id toggle. */
+    setOpenIds: (ids: string[]) => void;
+    openIds: string[];
+}
+export declare function useSectionState({ scope, sectionIds, defaultOpen, mode, }: UseSectionStateOptions): UseSectionStateResult;
 export interface UseCollapsedSectionsOptions {
-    /** Every section ID this page manages, in display order. IDs must be
-     * globally unique across pages (prefix with a page key, e.g.
-     * "admin-dashboard:alerts") — uiPreferences.collapsedSections is a single
-     * flat list shared by the whole user document, not namespaced server-side.
-     * A section ID absent from the saved list defaults to collapsed, which is
-     * also the state for a user who has never touched this page. */
+    /** Every section ID this page manages, in display order. */
     sectionIds: string[];
+    /** Scope key. Optional only so the pre-existing call sites keep compiling;
+     * they share `"legacy:collapsed-sections"`, which reproduces the old global
+     * behaviour exactly. New code should call `useSectionState` directly. */
+    scope?: string;
 }
 export interface UseCollapsedSectionsResult {
     isCollapsed: (id: string) => boolean;
@@ -14,7 +50,12 @@ export interface UseCollapsedSectionsResult {
      * everything collapsed. */
     toggle: (id: string) => void;
 }
-/** Persisted, per-user, accordion-scoped collapse state for a page's
- * dashboard sections. Debounces writes to PATCH /api/user/profile so rapid
- * toggling doesn't fire a request per click. */
-export declare function useCollapsedSections({ sectionIds, }: UseCollapsedSectionsOptions): UseCollapsedSectionsResult;
+/**
+ * @deprecated Prefer `useSectionState`, which is namespaced per surface,
+ * supports several sections open at once, and defaults to section 1 open.
+ *
+ * Kept so the existing dashboard call sites need no edit. Semantics are
+ * byte-identical to the original: default all-collapsed (`defaultOpen: []`)
+ * and accordion (`mode: "single"`).
+ */
+export declare function useCollapsedSections({ sectionIds, scope, }: UseCollapsedSectionsOptions): UseCollapsedSectionsResult;

package/dist/features/account/hooks/useCollapsedSections.js

@@ -1,63 +1,236 @@
 "use client";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { normalizeError } from "../../../errors/normalize";
 import { useCurrentProfile, useUpdateCurrentProfile } from "./useProfile";
 const PERSIST_DEBOUNCE_MS = 600;
-/** Persisted, per-user, accordion-scoped collapse state for a page's
- * dashboard sections. Debounces writes to PATCH /api/user/profile so rapid
- * toggling doesn't fire a request per click. */
-export function useCollapsedSections({ sectionIds, }) {
+const LOCAL_KEY = "letitrip:section-state";
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Persisted, per-user, per-surface open/closed state for collapsible sections.
+ *
+ * `useSectionState` is the implementation; `useCollapsedSections` below is a
+ * thin adapter preserving the older hook's exact semantics for its existing
+ * call sites.
+ *
+ * 🛑 THE STORED VALUE IS WHAT IS **OPEN**, NOT WHAT IS COLLAPSED.
+ *
+ * The predecessor stored `uiPreferences.collapsedSections`: one flat, global,
+ * un-namespaced array of collapsed ids, shared by every page and kept apart
+ * only by a naming convention. Two consequences, both of which the polarity
+ * flip removes rather than patches:
+ *
+ *   - a never-seen surface had to DEFAULT to collapsed, because "absent" and
+ *     "deliberately collapsed" were the same value. Storing what is open makes
+ *     a never-seen scope resolve to `defaultOpen` by absence, so "section 1
+ *     open, the rest collapsed" needs no sentinel;
+ *   - one page's ids could collide with another's.
+ *
+ * The scope key is `"{portal}:{surface}"` and is supplied by the caller. It is
+ * deliberately NOT derived from the section ids — a hash would change the
+ * moment a section is added, silently resetting every user's layout.
+ *
+ * ── localStorage mirror ─────────────────────────────────────────────────────
+ * The profile arrives over the network, so a server-only read paints every
+ * section in its default state and then snaps to the user's real layout a
+ * moment later. Writes go to localStorage synchronously (instant, and it
+ * survives for signed-out users) and to the user document debounced (durable,
+ * and it follows the user to another device). localStorage seeds first paint;
+ * the profile is authoritative once it lands.
+ *
+ * ── Migration ───────────────────────────────────────────────────────────────
+ * One-way and lossless: the first time a scope is read with no `sectionState`
+ * entry, its open set is derived from the legacy `collapsedSections`
+ * (`sectionIds − collapsed`) and persisted under the new key. `collapsedSections`
+ * keeps being written for one release so a rollback loses nothing.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// localStorage mirror
+// ─────────────────────────────────────────────────────────────────────────────
+function readLocalScopes() {
+    if (typeof window === "undefined")
+        return {};
+    try {
+        const raw = window.localStorage.getItem(LOCAL_KEY);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        // Validate rather than trust: this value survives across releases and a
+        // shape written by an older version must degrade to "no preference", not
+        // to a render crash. Every entry is checked, so the cast above is a claim
+        // this loop then makes true.
+        const out = {};
+        for (const [scope, ids] of Object.entries(parsed)) {
+            if (Array.isArray(ids))
+                out[scope] = ids.filter((id) => typeof id === "string");
+        }
+        return out;
+        // localStorage throws on access in private mode, and JSON.parse throws on a
+        // value some other version wrote. Neither is reportable — the user document
+        // is the durable copy and this is only a first-paint cache — but the throw
+        // is still normalized rather than swallowed raw.
+    }
+    catch (err) {
+        void normalizeError(err);
+        return {};
+    }
+}
+function writeLocalScope(scope, openIds) {
+    if (typeof window === "undefined")
+        return;
+    try {
+        const all = readLocalScopes();
+        all[scope] = openIds;
+        window.localStorage.setItem(LOCAL_KEY, JSON.stringify(all));
+        // setItem throws on quota exhaustion and in private mode. Same reasoning as
+        // readLocalScopes — the debounced profile PATCH is the durable write, so
+        // losing the mirror costs one frame of default layout and nothing else.
+    }
+    catch (err) {
+        void normalizeError(err);
+    }
+}
+export function useSectionState({ scope, sectionIds, defaultOpen, mode = "multi", }) {
     const { data: profile } = useCurrentProfile();
     const updateProfile = useUpdateCurrentProfile();
-    // Full server-side list, including other pages' entries this hook must
-    // never clobber when it persists its own page's next state.
-    const savedFullListRef = useRef([]);
-    const [localCollapsed, setLocalCollapsed] = useState(null);
-    const debounceRef = useRef(null);
     const sectionIdsRef = useRef(sectionIds);
     sectionIdsRef.current = sectionIds;
+    const fallbackOpen = useMemo(() => defaultOpen ?? (sectionIds.length > 0 ? [sectionIds[0]] : []), 
+    // Only the first id matters for the default, so this does not need to
+    // re-run every time the array identity changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [defaultOpen, sectionIds[0], sectionIds.length]);
+    const fallbackOpenRef = useRef(fallbackOpen);
+    fallbackOpenRef.current = fallbackOpen;
+    // Server copy of EVERY scope, so persisting this surface never clobbers
+    // another's entry.
+    const savedScopesRef = useRef({});
+    const legacyCollapsedRef = useRef(undefined);
+    const debounceRef = useRef(null);
+    /** `scope: ""` opts out of every durable store — see the option's docstring. */
+    const persistent = scope !== "";
+    // Seeded synchronously from localStorage so first paint is already correct.
+    const [localOpen, setLocalOpen] = useState(() => {
+        if (!persistent)
+            return null;
+        const cached = readLocalScopes()[scope];
+        return cached ? new Set(cached) : null;
+    });
     useEffect(() => {
-        if (!profile)
+        if (!persistent || !profile)
             return;
-        const serverList = profile.uiPreferences?.collapsedSections;
-        savedFullListRef.current = serverList ?? [];
-        setLocalCollapsed((prev) => {
-            if (prev !== null)
-                return prev; // local interaction already in progress — don't clobber it
-            const known = new Set(serverList ?? []);
-            const initial = new Set();
-            for (const id of sectionIdsRef.current) {
-                // Never-set user (serverList undefined) → default every section collapsed.
-                if (serverList === undefined || known.has(id))
-                    initial.add(id);
-            }
-            return initial;
-        });
-    }, [profile]);
+        const prefs = profile.uiPreferences;
+        savedScopesRef.current = prefs?.sectionState ?? {};
+        legacyCollapsedRef.current = prefs?.collapsedSections;
+        const stored = savedScopesRef.current[scope];
+        if (stored) {
+            setLocalOpen(new Set(stored));
+            return;
+        }
+        // No entry for this scope yet — derive one from the legacy flat list if the
+        // user has one, otherwise fall back to the default. Persisting is left to
+        // the first real toggle: writing on mere page view would fire a profile
+        // PATCH for every visitor on every dashboard.
+        const legacy = legacyCollapsedRef.current;
+        if (legacy !== undefined) {
+            const collapsed = new Set(legacy);
+            setLocalOpen(new Set(sectionIdsRef.current.filter((id) => !collapsed.has(id))));
+        }
+        else {
+            setLocalOpen(new Set(fallbackOpenRef.current));
+        }
+    }, [profile, scope, persistent]);
     useEffect(() => () => {
         if (debounceRef.current)
             clearTimeout(debounceRef.current);
     }, []);
-    const persist = useCallback((nextForThisPage) => {
+    const persist = useCallback((next) => {
+        if (!persistent)
+            return;
+        const openIds = sectionIdsRef.current.filter((id) => next.has(id));
+        writeLocalScope(scope, openIds);
+        savedScopesRef.current = { ...savedScopesRef.current, [scope]: openIds };
         if (debounceRef.current)
             clearTimeout(debounceRef.current);
         debounceRef.current = setTimeout(() => {
+            // Keep writing the legacy list for one release: derived from this
+            // surface's ids only, merged over whatever other pages recorded, so a
+            // rollback finds the same state it would have written itself.
             const ids = sectionIdsRef.current;
-            const others = savedFullListRef.current.filter((id) => !ids.includes(id));
-            const merged = [...others, ...nextForThisPage];
-            savedFullListRef.current = merged;
-            updateProfile.mutate({ uiPreferences: { collapsedSections: merged } });
+            const others = (legacyCollapsedRef.current ?? []).filter((id) => !ids.includes(id));
+            const collapsedHere = ids.filter((id) => !next.has(id));
+            const mergedLegacy = [...others, ...collapsedHere];
+            legacyCollapsedRef.current = mergedLegacy;
+            updateProfile.mutate({
+                uiPreferences: {
+                    sectionState: { [scope]: openIds },
+                    collapsedSections: mergedLegacy,
+                },
+            });
         }, PERSIST_DEBOUNCE_MS);
-    }, [updateProfile]);
-    const isCollapsed = useCallback((id) => localCollapsed?.has(id) ?? true, [localCollapsed]);
+    }, [scope, persistent, updateProfile]);
+    const effectiveOpen = localOpen ?? new Set(fallbackOpen);
+    const isOpen = useCallback((id) => (localOpen ?? new Set(fallbackOpenRef.current)).has(id), [localOpen]);
     const toggle = useCallback((id) => {
-        setLocalCollapsed((prev) => {
-            const wasCollapsed = prev?.has(id) ?? true;
-            const next = wasCollapsed
-                ? new Set(sectionIdsRef.current.filter((s) => s !== id)) // opening id collapses every sibling
-                : new Set(sectionIdsRef.current); // closing the open one — back to all-collapsed
+        setLocalOpen((prev) => {
+            const current = prev ?? new Set(fallbackOpenRef.current);
+            const next = new Set(current);
+            if (next.has(id))
+                next.delete(id);
+            else if (mode === "single") {
+                next.clear();
+                next.add(id);
+            }
+            else
+                next.add(id);
+            persist(next);
+            return next;
+        });
+    }, [mode, persist]);
+    const open = useCallback((id) => {
+        setLocalOpen((prev) => {
+            const current = prev ?? new Set(fallbackOpenRef.current);
+            if (current.has(id))
+                return current;
+            // Deliberately additive even under `mode: "single"`: this exists for
+            // error recovery, and collapsing the section the user was just editing
+            // in order to reveal the one that failed loses their place.
+            const next = new Set(current);
+            next.add(id);
+            persist(next);
+            return next;
+        });
+    }, [persist]);
+    const setOpenIds = useCallback((ids) => {
+        setLocalOpen(() => {
+            const next = new Set(ids);
             persist(next);
             return next;
         });
     }, [persist]);
+    const openIds = useMemo(() => sectionIds.filter((id) => effectiveOpen.has(id)), 
+    // effectiveOpen is derived from localOpen; depending on the Set identity
+    // directly would recompute on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sectionIds, localOpen, fallbackOpen]);
+    return { isOpen, toggle, open, setOpenIds, openIds };
+}
+/**
+ * @deprecated Prefer `useSectionState`, which is namespaced per surface,
+ * supports several sections open at once, and defaults to section 1 open.
+ *
+ * Kept so the existing dashboard call sites need no edit. Semantics are
+ * byte-identical to the original: default all-collapsed (`defaultOpen: []`)
+ * and accordion (`mode: "single"`).
+ */
+export function useCollapsedSections({ sectionIds, scope = "legacy:collapsed-sections", }) {
+    const { isOpen, toggle } = useSectionState({
+        scope,
+        sectionIds,
+        defaultOpen: [],
+        mode: "single",
+    });
+    const isCollapsed = useCallback((id) => !isOpen(id), [isOpen]);
     return { isCollapsed, toggle };
 }