@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/cart/repository/cart.repository.js

@@ -590,6 +590,53 @@ export class CartRepository extends BaseRepository {
             updatedAt: new Date(),
         }, { merge: true });
     }
+    /**
+     * Opt the cart in or out of paying with points (D46/D47, decision 24).
+     *
+     * 🛑 A BOOLEAN, and the schema deliberately has no numeric sibling. Opt in
+     * and the server applies as many points as the 50% cap allows; whatever
+     * cannot be applied stays in the balance for a later order. A client-supplied
+     * amount is a client-supplied discount, which is the whole reason
+     * `storeAddons` is the source of truth for add-on fees rather than a request
+     * body.
+     *
+     * Written with the same `set(..., { merge: true })` as its neighbours so a
+     * concurrent add-on or selection write is not clobbered.
+     *
+     * 🛑 Opting OUT deletes the field rather than writing `false` — absent and
+     * `false` mean the same thing to every reader (`cart.useAllPoints === true`),
+     * and keeping both shapes invites a reader that handles only one. Same
+     * reasoning as `setStoreAddons` directly above.
+     */
+    /**
+     * Set or clear the instalment plan.
+     *
+     * 🛑 `null` DELETES the field rather than storing `{ optIn: false }`. The
+     * schema's rule is that absent means "no instalments", so a second
+     * representation of the same state is one more thing every reader has to
+     * get right (Root Cause #42's shape). `tenureMonths` is stored verbatim and
+     * validated against the live `emi.tenureOptions` at order time — the admin
+     * can change those options after a cart was saved, so validating here would
+     * freeze a tenure that is no longer offered.
+     */
+    async setEmiPlan(userId, plan) {
+        await this.db
+            .collection(this.collection)
+            .doc(userId)
+            .set({
+            emiPlan: plan ? { tenureMonths: plan.tenureMonths } : FieldValue.delete(),
+            updatedAt: new Date(),
+        }, { merge: true });
+    }
+    async setUseAllPoints(userId, useAllPoints) {
+        await this.db
+            .collection(this.collection)
+            .doc(userId)
+            .set({
+            useAllPoints: useAllPoints ? true : FieldValue.delete(),
+            updatedAt: new Date(),
+        }, { merge: true });
+    }
     /*
      * `pruneStoreAddons(userId, keepStoreIds)` used to live here. It had zero
      * callers from the day it was written, and `pruneForItems` now does the same

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

@@ -6,6 +6,7 @@
  */
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ListingType } from "../../products/types/index";
+import type { CouponType } from "../../promotions/types/index";
 /**
  * What KIND of thing one cart line represents.
  *
@@ -57,6 +58,33 @@ export interface CartLineMember {
     gstRate?: 0 | 5 | 12 | 18 | 28;
     hsnCode?: string;
     listingType?: ListingType;
+    /**
+     * How the coordinator expressed this member's share of the line.
+     *
+     * Absent means `"amount"` — every line written before splits existed, so no
+     * migration and no behaviour change until a coordinator picks percentages.
+     *
+     * 🛑 The PERCENTAGE is the stored fact, not the resolved rupees. Percentages
+     * apply to the LANDED cost (goods + shipping + fees), so a member's figure
+     * MOVES when shipping is re-quoted — storing the computed amount instead
+     * would freeze a number that no longer matches the agreed share. The
+     * computed figures are snapshotted at COMMIT, which is where the
+     * coordinator's agreement actually becomes binding (D61).
+     *
+     * `resolveSplit` (`_internal/shared/checkout/split.ts`) is the only thing
+     * that turns these into money.
+     */
+    splitMode?: "amount" | "percent";
+    /** 0–100, read only when `splitMode === "percent"`. */
+    percent?: number;
+    /**
+     * The member's agreed contribution in decimal rupees, when typed directly.
+     *
+     * 🛑 NOT the same as `unitPrice`. `unitPrice` is what the ITEM costs;
+     * this is what this PERSON agreed to put in, and the two differ by design
+     * the moment a split is uneven or the total exceeds the landed cost.
+     */
+    contribution?: number;
 }
 export interface CartItemDocument {
     itemId: string;
@@ -183,6 +211,26 @@ export interface CartItemDocument {
     chosenShippingProviderId?: string;
     /** Fee in decimal rupees for the chosen provider, snapshotted at cart time. */
     chosenShippingFee?: number;
+    /**
+     * ── S5a: which address THIS line ships to ────────────────────────────────
+     *
+     * One payer, N destinations. Absent means "the order's own shipping
+     * address", which is every cart that predates this and every ordinary
+     * single-destination order — so nothing changes for them.
+     *
+     * 🛑 An `addresses/{id}` REFERENCE, never a copied address. Copying would
+     * put a name, a phone number and a street address onto the cart document,
+     * which is a PII store with no encryption, no `*_PII_FIELDS` entry and no
+     * retention story — and carts are swept by a TTL job that is not written to
+     * handle personal data. The id resolves server-side at checkout, where the
+     * address is already being read and decrypted.
+     *
+     * 🛑 It must belong to the BUYER. An arbitrary `addresses` id would let a
+     * caller address a parcel to any stored address on the platform, which is
+     * both a delivery hijack and a way to read whether an id exists. Checked
+     * server-side at the write, not trusted from the client.
+     */
+    destinationAddressId?: string;
     addedAt: Date;
     updatedAt: Date;
 }
@@ -196,6 +244,28 @@ export interface CartAppliedCoupon {
     storeId?: string;
     /** Item IDs (CartItemDocument.itemId) this coupon was calculated against */
     applicableItemIds?: string[];
+    /**
+     * The coupon's type, snapshotted at apply time (D51).
+     *
+     * 🛑 Needed because `detectCouponConflict` buckets on TYPE, not scope: a
+     * `points_earn` coupon is admin-scoped like every platform coupon but
+     * competes for its own slot, so without this field on the stored entry the
+     * detector could not tell a points coupon already in the cart from an
+     * ordinary platform one, and `RIPLI05` would block every other admin coupon
+     * — the exact defect the third bucket exists to prevent.
+     *
+     * Absent means "a discount coupon", which is what every cart written before
+     * this field holds, and is the reading that preserves the previous
+     * behaviour exactly.
+     *
+     * 🛑 Snapshotted deliberately, unlike the restrictions: a coupon's TYPE
+     * decides which slot it occupies, so re-reading it live would mean an admin
+     * editing a coupon's type could retroactively make a live cart's
+     * combination illegal. The money is still re-validated against the live
+     * coupon at placement (`revalidateAppliedCoupons`), which is where a changed
+     * discount has to be caught.
+     */
+    type?: CouponType;
 }
 /**
  * Paid add-ons the buyer opted into, for ONE store.
@@ -239,6 +309,52 @@ export interface CartDocument extends BaseDocument {
      * rather than a flag someone has to remember to check.
      */
     storeAddons?: Record<string, CartStoreAddons>;
+    /**
+     * The buyer has opted to spend points on this checkout.
+     *
+     * ## 🛑 A BOOLEAN, and the amount is never stored or sent
+     *
+     * Owner's rule: *"if use point it is all and then the balance is returned if
+     * excess"* — one opt-in, all-or-nothing. Ticked, the checkout applies as many
+     * points as the 50% cap allows; whatever cannot be applied stays in the
+     * balance. The buyer never types a number.
+     *
+     * So this is the ONLY thing the client may say about points. The amount is
+     * derived server-side from the live balance and
+     * `POINTS_MAX_REDEMPTION_PERCENT` at the moment the order is priced — the
+     * same rule that makes `storeAddons` above the source of truth rather than a
+     * request body, and for the same reason: a client-supplied money figure is a
+     * client-supplied discount.
+     *
+     * 🛑 This replaces a deleted `pointsToRedeem?: number` on the checkout input,
+     * whose handler debited the buyer AFTER the gateway had captured full price
+     * (D46). A number was the wrong shape as well as the wrong place.
+     */
+    useAllPoints?: boolean;
+    /**
+     * "Pay in instalments", with the chosen tenure — an opt-in ON THE ORDER,
+     * orthogonal to how the token is tendered.
+     *
+     * 🛑 It lives HERE, on the cart, for exactly the reason `storeAddons` does:
+     * the online path creates the gateway order in one request
+     * (`/api/payment/create-order`, which decides the CAPTURE amount) and the
+     * order document in a later one (`/api/payment/verify`). A choice carried in
+     * a request body cannot be read by both, so the two would be free to
+     * disagree about how much of the total is deferred — and the difference is
+     * money captured that the order does not record (the D37/D38/D40 class).
+     *
+     * `useAllPoints` is the precedent and the shape is deliberately the same: a
+     * durable selection the server re-reads, never a client-supplied amount.
+     *
+     * Absent means a plain full-price order, which is why it is written with
+     * `FieldValue.delete()` rather than `{ optIn: false }` — a stored false and
+     * an absent field must not be two ways of saying the same thing.
+     */
+    emiPlan?: CartEmiPlan;
+}
+/** The buyer's instalment selection. `tenureMonths` is validated against the live `emi.tenureOptions` at order time, never here. */
+export interface CartEmiPlan {
+    tenureMonths: number;
 }
 export declare const CART_COLLECTION: "carts";
 export declare const CART_INDEXED_FIELDS: string[];

package/dist/features/contact/email.d.ts

@@ -1,14 +1,9 @@
 import "server-only";
 import type { SendGuardContext } from "../../_internal/shared/features/messaging/config";
 import type { JsonValue } from "@mohasinac/appkit";
-type SendEmailOptions = Record<string, JsonValue> & {
-    to: string | string[];
-    subject: string;
+import type { EmailOptions } from "../../contracts/email";
+type SendEmailOptions = Omit<EmailOptions, "html"> & {
     html?: string;
-    text?: string;
-    from?: string;
-    cc?: string | string[];
-    replyTo?: string;
 };
 /**
  * Everything `sendEmail` needs beyond the message itself.
@@ -22,9 +17,9 @@ type SendEmailOptions = Record<string, JsonValue> & {
  * (CLAUDE.md Rule #22: make the wrong thing unrepresentable).
  *
  * Kept as a separate second parameter rather than a field on
- * `SendEmailOptions` because that type has a `Record<string, JsonValue>` index
- * signature — a structured object would not satisfy it, and widening the index
- * signature to accommodate one field would weaken every other field's typing.
+ * `SendEmailOptions`, which is now the provider's own `EmailOptions`. The
+ * guard is about who may send and why; it is not part of the message, and
+ * folding it in would put it on the wire to the provider.
  */
 export type SendEmailGuard = SendGuardContext;
 /**
@@ -59,6 +54,28 @@ export interface OrderConfirmationEmailParams {
         unitPrice: number;
         totalPrice: number;
     }>;
+    /**
+     * Phase 7 — the invoice PDF to attach, as STORED bytes.
+     *
+     * 🛑 Bytes, never a path and never a renderer. Two renders can disagree — a
+     * changed template, a different library version — and the buyer's copy must
+     * be byte-identical to ours. Letting this function render would be a second
+     * render by definition.
+     *
+     * 🛑 Optional, and absence must stay silent. The invoice is numbered on the
+     * PAID transition and its bytes are produced on first request, so a COD
+     * order confirmed before payment legitimately has none — and this email has
+     * always sent without an attachment. Failing or warning here would turn the
+     * normal case into a noisy one.
+     *
+     * Resend supports attachments already (`email-resend/provider.ts`), so this
+     * needs no new send, no new credential and no change to the 80/day ceiling.
+     * Only the payload is bigger.
+     */
+    invoicePdf?: {
+        filename: string;
+        content: Buffer;
+    };
 }
 export declare function sendOrderConfirmationEmail(params: OrderConfirmationEmailParams): Promise<{
     success: boolean;

package/dist/features/contact/email.js

@@ -124,9 +124,10 @@ export async function sendEmail(opts, guard) {
                 ? opts.cc
                 : undefined,
             replyTo: typeof opts.replyTo === "string" ? opts.replyTo : undefined,
-            headers: typeof opts.headers === "object" && opts.headers
-                ? opts.headers
-                : undefined,
+            headers: opts.headers,
+            // Forwarded, not dropped — the provider has mapped these to Resend's
+            // `attachments` all along; nothing here ever handed them over.
+            attachments: opts.attachments,
         });
         void recordSendAttempt({
             to: opts.to,
@@ -184,6 +185,22 @@ export async function sendOrderConfirmationEmail(params) {
             to,
             subject: `Order Confirmed — ${orderId}`,
             html,
+            /*
+             * Phase 7 — the invoice, when there is one. The STORED bytes, handed
+             * in by the caller: see `invoicePdf` on the params type for why this
+             * function must not render its own.
+             */
+            ...(params.invoicePdf
+                ? {
+                    attachments: [
+                        {
+                            filename: params.invoicePdf.filename,
+                            content: params.invoicePdf.content,
+                            contentType: "application/pdf",
+                        },
+                    ],
+                }
+                : {}),
             text: `Hi ${userName},\n\nYour order ${orderId} has been confirmed!\n\n${itemsText}\nTotal: ${formattedTotal}\nPayment: ${paymentLabel}\nShip to: ${shippingAddress ?? "-"}\n\nView your order: ${orderUrl}\n\n© ${currentYear()} ${siteName}`,
         }, {
             channel: "email",

package/dist/features/dashboard/components/DashboardHubView.d.ts

@@ -0,0 +1,83 @@
+import React from "react";
+import type { AttentionCounts } from "../../../_internal/server/features/dashboard/attention";
+import type { DashboardHubSection } from "../../../_internal/shared/features/dashboard/hub-sections";
+/**
+ * The dashboard hub — one component, two modes, zero copy of its own.
+ *
+ * ## Why one component and not two
+ *
+ * A landing page lists SECTIONS; a section hub lists SCREENS. Those read as
+ * two features and are one: a grid of link cards, each with a title, a
+ * sentence about what it is for, and an optional count of things waiting. Same
+ * prop surface, same renderer — which the Duplication Framework calls a
+ * consolidate-on-sight ("copies accept the same parameters and return the same
+ * shape"), not a Rule-of-Three wait.
+ *
+ * The thing it must not become is `AdminGuideHubView`, which is the visual
+ * pattern here and hand-writes its own 13-card list — so a guide added to the
+ * nav never appears on it. Every card below comes from a nav item's existing
+ * `label` and `description`.
+ *
+ * ## Not a client component
+ *
+ * It takes plain data and renders. No hook, no fetch, no `"use client"` — the
+ * page that mounts it is already per-request (its layout reads the session), so
+ * the counts arrive with the render rather than costing a second invocation
+ * after it. See `_internal/server/features/dashboard/data.ts`.
+ *
+ * ## No icons, on purpose
+ *
+ * A nav item carries no `iconKey`, so icons would mean a hand-written map of
+ * 22 sections or ~130 screens — a second list to drift from the first, which is
+ * the whole defect this feature exists to avoid (Root Cause #61). The section
+ * heading plus the card's own sentence is the distinction; `<Badge>` carries
+ * the only signal that needs to catch the eye.
+ */
+export interface DashboardHubViewProps {
+    /**
+     * Page heading. Omit when the grid is embedded in a page that already has
+     * one — `/store` renders it inside a `CollapsibleSection`, and a second
+     * `<h1>` mid-page breaks the heading outline for a screen reader.
+     */
+    title?: string;
+    /** One sentence under the heading. Only rendered alongside a `title`. */
+    description?: string;
+    /**
+     * What to render.
+     *
+     * - `"sections"` — one card per section, linking to its hub. The landing page.
+     * - `"screens"` — one card per screen in `sections[0]`. A section hub.
+     *
+     * 🛑 A hub is passed a ONE-section array rather than a section plus a mode
+     * flag, so the two modes cannot disagree about what they are rendering.
+     */
+    mode: "sections" | "screens";
+    sections: DashboardHubSection[];
+    /** Built by the caller from `ROUTES.{PORTAL}.SECTION(slug)`. */
+    sectionHrefs: Record<string, string>;
+    counts: AttentionCounts;
+    /**
+     * Rendered above the cards — the live stat tiles on `/store` and `/user`.
+     *
+     * Those are real data and stay: the plan's "bland tile walls" are the
+     * undifferentiated grids of ~19 nav shortcuts, not the figures beside them.
+     * Deleting a working panel while replacing its neighbour is Root Cause #60's
+     * shape, so the slot exists and the caller keeps passing them.
+     */
+    above?: React.ReactNode;
+    /** Shown when the viewer can see nothing at all. */
+    emptyMessage?: string;
+    /**
+     * Render "7 screens" on a section card. Default `true`.
+     *
+     * 🛑 Pass `false` whenever `sections` has NOT been through every filter that
+     * applies to the portal. `/store` is the live case: its entitlement filter
+     * (`filterStoreNavGroups`) runs in the layout and on the hub pages, but the
+     * client landing does not hold the store document, so its "Listings" card
+     * would claim nine screens where the seller can reach six. The section itself
+     * is still correct — it is the COUNT that would over-promise, so the count is
+     * withheld rather than guessed.
+     */
+    showScreenCount?: boolean;
+}
+export declare function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount, }: DashboardHubViewProps): React.JSX.Element;

package/dist/features/dashboard/components/DashboardHubView.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Badge, Div, Grid, Heading, Row, Section, Stack, Text, TextLink } from "../../../ui/index.js";
+/**
+ * Sum of the counts inside a section, or `null` when it has none.
+ *
+ * 🛑 `null` and `0` are different answers and a card renders only the first as
+ * "no badge". A section whose every count FAILED must not read as "nothing
+ * waiting" (Root Cause #72), so a failed read inside an otherwise-countless
+ * section stays `null` rather than collapsing to a sum of zero.
+ */
+function sectionTotal(section, counts) {
+    let total = null;
+    for (const item of section.items) {
+        const value = item.id ? counts[item.id] : undefined;
+        if (typeof value !== "number")
+            continue;
+        total = (total ?? 0) + value;
+    }
+    return total;
+}
+/** A count worth showing. Zero is not — a `0` badge is noise on every card. */
+function badgeFor(value) {
+    if (typeof value !== "number" || value <= 0)
+        return null;
+    return (_jsx(Badge, { variant: "warning", "aria-label": `${value} waiting`, children: value }));
+}
+function CardGrid({ cards }) {
+    return (_jsx(Grid, { cols: "cards", gap: "md", children: cards.map((card) => (_jsxs(TextLink, { variant: "bare", href: card.href, rounded: "xl", layout: "flex-col", gap: "sm", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: "group border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0 w-full", children: [_jsx(Text, { weight: "semibold", className: "min-w-0 text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", children: card.label }), badgeFor(card.count)] }), card.description && (_jsx(Text, { size: "sm", className: "text-[var(--appkit-color-text-muted)] leading-relaxed", children: card.description })), card.meta && (_jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-faint)] mt-auto", children: card.meta }))] }, card.key))) }));
+}
+export function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount = true, }) {
+    const hasAny = sections.some((section) => section.items.length > 0);
+    return (_jsxs(Stack, { gap: "lg", children: [title && (_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, size: "xl", weight: "semibold", color: "primary", children: title }), description && (_jsx(Text, { size: "sm", color: "muted", children: description }))] })), above, !hasAny && (_jsx(Alert, { variant: "info", title: "Nothing here yet", children: emptyMessage ??
+                    "Your permission set doesn't include access to any of these screens yet. Ask an admin for the permissions you need." })), hasAny && mode === "sections" && (_jsx(CardGrid, { cards: sections.map((section) => ({
+                    key: section.slug,
+                    href: sectionHrefs[section.slug] ?? "",
+                    label: section.title,
+                    /*
+                     * A section has no description of its own and must not invent one —
+                     * so it names what is inside it instead. `items.length` is the
+                     * post-filter count, which is what this viewer will actually find
+                     * PROVIDED every filter has run; see `showScreenCount`.
+                     */
+                    meta: showScreenCount
+                        ? `${section.items.length} ${section.items.length === 1 ? "screen" : "screens"}`
+                        : undefined,
+                    count: sectionTotal(section, counts),
+                })) })), hasAny &&
+                mode === "screens" &&
+                sections.map((section) => (_jsxs(Section, { children: [_jsx(Heading, { level: 2, size: "lg", weight: "semibold", className: "mb-4 text-[var(--appkit-color-text)]", children: section.title }), _jsx(CardGrid, { cards: section.items.map((item) => ({
+                                key: item.id ?? item.href,
+                                href: item.href,
+                                label: item.label,
+                                description: item.description,
+                                count: item.id ? (counts[item.id] ?? null) : null,
+                            })) })] }, section.slug))), hasAny && mode === "sections" && (_jsx(Div, { children: _jsx(Text, { size: "xs", color: "faint", children: "Every card above is a section of the sidebar. The screens inside one are the same screens, with a sentence each on what they are for." }) }))] }));
+}

package/dist/features/dashboard/components/DashboardSectionsClient.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+import type { NavPortal, SidebarNavGroup } from "../../../_internal/shared/features/layout/types";
+export interface DashboardSectionsClientProps {
+    portal: NavPortal;
+    /**
+     * The portal's nav groups.
+     *
+     * 🛑 Pass the groups the SIDEBAR was given, already put through any
+     * portal-specific filter (`filterStoreNavGroups` for `/store`). This applies
+     * only the navConfig/permission filter; a section the store is not entitled
+     * to would otherwise appear here and nowhere else.
+     */
+    groups: readonly SidebarNavGroup[];
+    /** `null` means admin; `undefined` means "no permission gating applies". */
+    permissions?: string[] | null;
+    /** Omit when embedding in a page that already has a heading. */
+    title?: string;
+    description?: string;
+    /** Live stat tiles and anything else that belongs above the cards. */
+    above?: React.ReactNode;
+    emptyMessage?: string;
+}
+export declare function DashboardSectionsClient({ portal, groups, permissions, title, description, above, emptyMessage, }: DashboardSectionsClientProps): React.JSX.Element;

package/dist/features/dashboard/components/DashboardSectionsClient.js

@@ -0,0 +1,66 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useSiteSettings } from "../../../core/hooks/useSiteSettings.js";
+import { filterNavGroups } from "../../../_internal/client/features/layout/filterNavItems.js";
+import { hubSections } from "../../../_internal/shared/features/dashboard/hub-sections.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { DashboardHubView } from "./DashboardHubView.js";
+/**
+ * The sectioned index of a dashboard, for a landing page that is already a
+ * CLIENT component.
+ *
+ * ## Why a client variant exists at all
+ *
+ * `/store/page.tsx` and `/user/page.tsx` are `"use client"` and carry live stat
+ * tiles (`useStoreDashboard`, `useNotifications`, an avatar uploader). Turning
+ * either into a server component to fetch hub data would mean moving a working
+ * 250–360 line page into a sibling file for the sake of a card grid — a large
+ * diff over a working feature, which is the shape of Root Cause #60.
+ *
+ * So the DATA source differs and the RENDERER does not: this resolves sections
+ * from the same `useSiteSettings` navConfig the sidebar reads, and hands them to
+ * the same `<DashboardHubView>` the admin landing renders server-side. One card
+ * grid, two ways in — not two card grids.
+ *
+ * ## 🛑 No attention counts here, and that is honest rather than lazy
+ *
+ * Counts need Firestore, which a client component can only reach through an
+ * endpoint — a second billed invocation per landing visit for numbers the page
+ * did not previously show (Root Cause #94). The admin landing, which is a
+ * server component under a session-reading layout, gets them for free in its
+ * own render. A seller's one countable figure (pending orders) is already a
+ * live stat tile on `/store`, so the badge would be the second place for it.
+ *
+ * `counts={{}}` means every card renders without a badge — never with a `0`,
+ * which is the one answer that would wrongly read as "nothing waiting"
+ * (Root Cause #72).
+ */
+/**
+ * 🛑 `Record<NavPortal, …>` so a fourth portal is a COMPILE error here rather
+ * than a landing page whose section cards all link to `""`. An object keyed on
+ * `string` would accept the omission silently (Root Cause #61).
+ */
+const SECTION_ROUTE = {
+    admin: (slug) => String(ROUTES.ADMIN.SECTION(slug)),
+    store: (slug) => String(ROUTES.STORE.SECTION(slug)),
+    user: (slug) => String(ROUTES.USER.SECTION(slug)),
+};
+export function DashboardSectionsClient({ portal, groups, permissions, title, description, above, emptyMessage, }) {
+    const { data: settings } = useSiteSettings();
+    /*
+     * Derived, never copied into state — the settings query can resolve after
+     * first paint, and a `useState` seeded from it would freeze the pre-settings
+     * answer. Same reasoning as `AdminIntegrationsView`.
+     */
+    const sections = useMemo(() => hubSections(filterNavGroups([...groups], settings?.navConfig, permissions)), [groups, settings?.navConfig, permissions]);
+    const sectionHrefs = useMemo(() => Object.fromEntries(sections.map((s) => [s.slug, SECTION_ROUTE[portal](s.slug)])), [sections, portal]);
+    return (_jsx(DashboardHubView, { title: title, description: description, mode: "sections", sections: sections, sectionHrefs: sectionHrefs, counts: {}, above: above, emptyMessage: emptyMessage, 
+        /*
+         * 🛑 Withheld deliberately. `/store`'s entitlement filter lives in the
+         * layout and on the hub pages, not here, so a count rendered from these
+         * groups would over-promise on the Listings card. See the prop's own
+         * header — the section is right, the number would not be.
+         */
+        showScreenCount: false }));
+}

package/dist/features/dispute-reasons/components/AdminDisputeReasonsView.d.ts

@@ -0,0 +1,55 @@
+import React from "react";
+import { type DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+/**
+ * Admin → Trust & Safety → Dispute reasons.
+ *
+ * ## Why a management page exists at all
+ *
+ * Inline create in the triage drawer was the cheaper half and was rejected on
+ * its own, for a reason worth keeping: **with no management page nothing can
+ * ever retire a reason**, so the list only grows and a typo'd row is permanent.
+ * Both shipped — the drawer so an agent never leaves a ticket to add a missing
+ * reason, this page so the eleven seeded rows are reviewable and retire has a
+ * home.
+ *
+ * ## 🛑 A row is OPENABLE, not just actionable
+ *
+ * `audit-listing-detail-affordance` requires it and the reason is Root Cause
+ * #56: a menu of pure mutations lets staff act on a record they were never able
+ * to read. Here that would mean retiring a reason without seeing its KIND — and
+ * the kind is the only field that decides which gate the reason inherits, so
+ * retiring the wrong one silently narrows the wrong form.
+ *
+ * `RecordDetailModal` is the shared primitive for exactly this; a bespoke modal
+ * would have tripped the Duplication Framework's Rule of Three on sight.
+ */
+export interface AdminDisputeReasonsViewProps {
+    /**
+     * The staff list endpoint, supplied by the consumer.
+     *
+     * 🛑 A PROP rather than a literal in here, for the same reason
+     * `RaiseDisputeForm` takes `reasonsEndpoint`: appkit holds no consumer
+     * routes. The path belongs in `API_ROUTES`, which is the one registry, and a
+     * literal here would be a second place it is written — exactly what
+     * `audit-hardcoded-api-routes` blocks.
+     */
+    endpoint: string;
+    /** `PATCH /api/admin/dispute-reasons/{id}` with `{ isActive }`. */
+    onSetActive: (id: string, isActive: boolean) => Promise<void>;
+    /** `POST /api/dispute-reasons` — the same endpoint the triage drawer uses. */
+    onCreate: (input: {
+        label: string;
+        kind: DisputeKind;
+    }) => Promise<void>;
+}
+/**
+ * The two fields, exported so the triage drawer's inline create and this page
+ * cannot drift on the label bound or the kind vocabulary.
+ */
+export declare function DisputeReasonFields({ label, kind, onLabel, onKind, }: {
+    label: string;
+    kind: DisputeKind;
+    onLabel: (v: string) => void;
+    onKind: (v: DisputeKind) => void;
+}): React.JSX.Element;
+export declare function AdminDisputeReasonsView({ endpoint, onSetActive, onCreate, }: AdminDisputeReasonsViewProps): React.JSX.Element;