@mohasinac/appkit 4.56.0 → 4.58.0

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

@@ -51,6 +51,27 @@ const ORDER_LANE_TABS = [
     { id: "auction", label: "Auction wins" },
     { id: "offer", label: "Offer wins" },
 ];
+/**
+ * Payment-method tabs — a THIRD axis, independent of the lane tabs above and
+ * the lifecycle scope beside them.
+ *
+ * 🛑 EMI is not a lane and not a status, which is why it could not join
+ * either existing control: `orderType` records how the order was WON
+ * (standard / auction / offer) and the scope records where it IS. How it is
+ * being PAID is orthogonal to both — an auction win can be on an EMI plan.
+ *
+ * Every id is exactly a stored `OrderDocument.paymentMethod` value, and
+ * `paymentMethod` is `canFilter: true` in the orders SIEVE_FIELDS — checked
+ * before wiring this, because an unallowlisted field does not raise: the
+ * clause is silently dropped and the chip returns the ENTIRE order list while
+ * looking like a filter (Root Cause #62).
+ */
+const PAYMENT_METHOD_TABS = [
+    { id: "", label: "Any" },
+    { id: "emi", label: "EMI plans" },
+    { id: "cod", label: "Cash on delivery" },
+    { id: "online", label: "Paid online" },
+];
 const STATUS_OPTIONS = [
     { value: "pending", label: "Pending" },
     { value: "processing", label: "Processing" },
@@ -85,7 +106,7 @@ export function UserOrdersView({ onOrderClick }) {
      * (CLAUDE.md, Root Cause #35).
      */
     const searchParams = useSearchParams();
-    const hasNarrowingFilter = ["q", "search", "status", "orderType", "filters"].some((k) => Boolean(searchParams.get(k)));
+    const hasNarrowingFilter = ["q", "search", "status", "orderType", "paymentMethod", "filters"].some((k) => Boolean(searchParams.get(k)));
     const emptyMessage = hasNarrowingFilter
         ? "No orders match your search or filters."
         : "You haven't placed any orders yet.";
@@ -104,7 +125,7 @@ export function UserOrdersView({ onOrderClick }) {
             fields: ["id", "productTitle"],
         },
         emptyLabel: emptyMessage,
-        filterKeys: ["status", "orderType"],
+        filterKeys: ["status", "orderType", "paymentMethod"],
         defaultSort: sortBy("createdAt", "DESC"),
         queryKey: ["user", "orders", "listing"],
         endpoint: ACCOUNT_ENDPOINTS.ORDERS,
@@ -115,6 +136,7 @@ export function UserOrdersView({ onOrderClick }) {
         buildFilters: (state) => [
             state.status ? sieveFilter("status", SIEVE_OP.EQ, state.status) : null,
             state.orderType ? sieveFilter("orderType", SIEVE_OP.EQ, state.orderType) : null,
+            state.paymentMethod ? sieveFilter("paymentMethod", SIEVE_OP.EQ, state.paymentMethod) : null,
         ]
             .filter(Boolean)
             .join(",") || undefined,
@@ -123,7 +145,7 @@ export function UserOrdersView({ onOrderClick }) {
         // in flight" without those two questions fighting over one control.
         buildExtraParams: () => orderScope.extraParams,
         renderAboveContent: orderScope.renderAboveContent,
-        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FilterChipGroup, { label: "Type", tabs: ORDER_LANE_TABS, value: pendingFilters.orderType ?? "", onChange: (id) => setPendingFilters((prev) => ({ ...prev, orderType: id })) }), _jsx(Div, { children: _jsx(PaginatedSelect, { value: pendingFilters.status || null, onChange: (v) => setPendingFilters((p) => ({ ...p, status: v ?? "" })), options: STATUS_OPTIONS, placeholder: "All statuses", ariaLabel: "Filter by order status" }) })] })),
+        renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FilterChipGroup, { label: "Type", tabs: ORDER_LANE_TABS, value: pendingFilters.orderType ?? "", onChange: (id) => setPendingFilters((prev) => ({ ...prev, orderType: id })) }), _jsx(FilterChipGroup, { label: "Payment", tabs: PAYMENT_METHOD_TABS, value: pendingFilters.paymentMethod ?? "", onChange: (id) => setPendingFilters((prev) => ({ ...prev, paymentMethod: id })) }), _jsx(Div, { children: _jsx(PaginatedSelect, { value: pendingFilters.status || null, onChange: (v) => setPendingFilters((p) => ({ ...p, status: v ?? "" })), options: STATUS_OPTIONS, placeholder: "All statuses", ariaLabel: "Filter by order status" }) })] })),
         renderCards: (rows, _view, _selection, isLoading) => {
             if (isLoading) {
                 return (_jsx(Stack, { gap: "md", children: Array.from({ length: 3 }).map((_, i) => (_jsx(Div, { className: "h-24 animate-pulse border border-[var(--appkit-color-border)]", rounded: "xl" }, i))) }));

package/dist/features/admin/components/AdminBeysView.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AdminBeysView — browse and correct the generated Beyblade database.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `beys` is 1,988 rows built by committed generators from a crawled corpus. So
+ * there is no "Add Beyblade" button: a row authored here would have no source,
+ * would vanish on the next regeneration, and would make the claim "this dataset
+ * rebuilds from `appkit/src/seed/` alone" false. Adding one is a change to the
+ * generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:beys
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/beys/page.tsx
+ */
+import React from "react";
+import type { ListingLayoutProps } from "../../../ui";
+export type AdminBeysViewProps = ListingLayoutProps;
+export declare function AdminBeysView({ children, ...props }: AdminBeysViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminBeysView.js

@@ -0,0 +1,178 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AdminBeysView — browse and correct the generated Beyblade database.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `beys` is 1,988 rows built by committed generators from a crawled corpus. So
+ * there is no "Add Beyblade" button: a row authored here would have no source,
+ * would vanish on the next regeneration, and would make the claim "this dataset
+ * rebuilds from `appkit/src/seed/` alone" false. Adding one is a change to the
+ * generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:beys
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/beys/page.tsx
+ */
+import React from "react";
+import { Heading, ListingLayout, Stack, Text } from "../../../ui/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { BEY_FIELDS } from "../../../constants/field-names.js";
+import { sortBy } from "../../../constants/sort.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { DataListingView } from "./DataListingView.js";
+/**
+ * 🛑 Rows are read from WHICHEVER envelope shape arrives.
+ *
+ * `apiClient.get()` unwraps `{success, data}` and returns `data` itself, so an
+ * endpoint that puts rows directly in `data` hands `mapRows` an ARRAY while one
+ * that nests them hands it an object. Reading `.data` off an array yields
+ * undefined — which is exactly how the categories listing rendered "No
+ * categories found" against a 200 carrying 58 rows. This route returns the
+ * object shape, and tolerating both is what keeps that from mattering.
+ */
+function extractRows(response) {
+    if (Array.isArray(response))
+        return response;
+    if (!response || typeof response !== "object")
+        return [];
+    const obj = response;
+    if (Array.isArray(obj.data))
+        return obj.data;
+    return Array.isArray(obj.items) ? obj.items : [];
+}
+function extractTotal(response) {
+    if (Array.isArray(response) || !response || typeof response !== "object")
+        return undefined;
+    const total = response.total;
+    return typeof total === "number" ? total : undefined;
+}
+/*
+ * audit-create-affordance-ok: this listing is deliberately inbound-only.
+ * The 1,988 rows are produced by committed generators from a crawled
+ * corpus, so there is no POST endpoint and no create route key to point a
+ * button at — a Beyblade authored by hand would have no source, would vanish
+ * on the next regeneration, and would make "this dataset rebuilds from
+ * appkit/src/seed/ alone" false. Adding one is a change to the generator.
+ * The surface exists to CORRECT a wrong extraction and to REMOVE a row that
+ * should not exist, which are the two operations the data actually needs.
+ */
+const COLUMNS = [
+    {
+        key: "primary",
+        header: "Beyblade",
+        sortable: true,
+        render: (row) => (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { weight: "semibold", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", children: row.secondary })] })),
+    },
+    {
+        key: "weight",
+        header: "Mass",
+        className: "w-28",
+        render: (row) => (_jsx(Text, { size: "sm", color: "muted", children: row.weight })),
+    },
+    {
+        key: "edited",
+        header: "Corrected",
+        className: "w-28",
+        /*
+         * 🛑 Shown as a COLUMN, because a hand-corrected row behaves differently
+         * from its neighbours — the generator no longer owns the fields somebody
+         * fixed. Leaving that invisible is how a later maintainer concludes the
+         * generator is producing a value it is actually being prevented from
+         * writing. Text, not a colour-only dot (colour is never the only signal).
+         */
+        render: (row) => row.edited ? (_jsx(Text, { size: "xs", weight: "medium", children: "By hand" })) : (_jsx(Text, { size: "xs", color: "faint", children: "Generated" })),
+    },
+];
+const ADMIN_BEYS_CONFIG = {
+    portal: "admin",
+    title: "Beyblades",
+    subtitle: "The generated Beyblade database. Corrections made here are kept when the database is regenerated.",
+    searchPlaceholder: "Search Beyblades by name — Dranzer F, Variares…",
+    /*
+     * 🛑 `searchCommit: "enter"`, not debounce. The route's search is an indexed
+     * PREFIX range, so a partial word is a different query rather than a
+     * narrowing one — debouncing would fire a range query per pause and show
+     * confusing intermediate results. Enter also makes the prefix-only behaviour
+     * legible: you typed a prefix and asked for it.
+     */
+    searchCommit: "enter",
+    /*
+     * 🛑 DECLARED, so the placeholder can be CHECKED rather than trusted.
+     * The route matches exactly one field — an indexed prefix range on
+     * `name` — and the placeholder must not imply more. It is a prefix and
+     * it is case-sensitive; `mode` says so where a reader will see it.
+     */
+    search: {
+        placeholder: "Search Beyblades by name — a prefix, case-sensitive",
+        fields: ["name"],
+    },
+    emptyLabel: "No Beyblade matches that name",
+    filterKeys: [],
+    /*
+     * 🛑 Through `sortBy`, not a bare "name". The route currently ALWAYS
+     * orders by name and ignores the `sorts` param, so this is the only
+     * option — but writing it as a literal is what lets a field rename
+     * leave a sort string that silently sorts nothing.
+     */
+    defaultSort: sortBy(BEY_FIELDS.NAME, "ASC"),
+    pageSize: 25,
+    queryKey: ["admin", "beys"],
+    endpoint: ADMIN_ENDPOINTS.BEYS,
+    sortOptions: [{ value: sortBy(BEY_FIELDS.NAME, "ASC"), label: "Name A-Z" }],
+    columns: COLUMNS,
+    buildFilters: () => undefined,
+    getTotal: (response, rows) => extractTotal(response) ?? rows.length,
+    mapRows: (response) => extractRows(response).map((raw) => {
+        const r = raw;
+        /*
+         * 🛑 `≈` when the mass was SUMMED from the parts rather than stated by
+         * the source. 93% of beys have a mass but only 248 state it, and a
+         * derived figure shown as an exact one is the easiest way for this
+         * dataset to start lying — the same marking the detail page and the OG
+         * card use.
+         */
+        const summed = typeof r.weightGFromParts === "number" ? r.weightGFromParts : null;
+        const weight = typeof r.weightG === "number"
+            ? `${r.weightG} g`
+            : summed !== null
+                ? `≈ ${Math.round(summed * 10) / 10} g`
+                : "—";
+        return {
+            id: String(r.id ?? ""),
+            primary: String(r.name ?? r.id ?? "Unnamed Beyblade"),
+            /*
+             * System first: it is the one line a collector uses to place a bey in
+             * time, and it is present on 94% of them. The product code follows
+             * because two vendor releases of one model differ by little else.
+             */
+            secondary: [r.system, Array.isArray(r.productCodes) ? r.productCodes[0] : null]
+                .filter(Boolean)
+                .join(" · ") || "—",
+            weight,
+            edited: r.adminEdited === true,
+        };
+    }),
+    /*
+     * 🛑 `rowHrefTemplate`, not `rowHref`. Verified against the interface
+     * rather than guessed — there is no `rowHref` field, and an unknown key on
+     * an object literal typed by an interface is a compile error I could not
+     * have seen under this session's no-build cap.
+     */
+    rowHrefTemplate: (row) => String(ROUTES.ADMIN.BEYS_EDIT(row.id)),
+};
+export function AdminBeysView({ children, ...props }) {
+    if (React.Children.count(children) > 0) {
+        return (_jsxs(ListingLayout, { portal: "admin", ...props, children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Beyblades" }), children] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Beyblades" }), _jsx(DataListingView, { config: ADMIN_BEYS_CONFIG })] }));
+}

package/dist/features/admin/components/AdminPartsView.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AdminPartsView — browse and correct the generated part glossary.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `partGlossary` is 2,488 rows built by committed generators from a crawled
+ * corpus. So there is no "Add part" button: a row authored here would have no
+ * source, would vanish on the next regeneration, and would make the claim
+ * "this dataset rebuilds from `appkit/src/seed/` alone" false. Adding a part is
+ * a change to the generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:parts
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/parts/page.tsx
+ */
+import React from "react";
+import type { ListingLayoutProps } from "../../../ui";
+export type AdminPartsViewProps = ListingLayoutProps;
+export declare function AdminPartsView({ children, ...props }: AdminPartsViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminPartsView.js

@@ -0,0 +1,160 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AdminPartsView — browse and correct the generated part glossary.
+ *
+ * ── 🛑 WHY THIS IS A CORRECTION SURFACE, NOT A CRUD SCREEN ────────────────
+ *
+ * `partGlossary` is 2,488 rows built by committed generators from a crawled
+ * corpus. So there is no "Add part" button: a row authored here would have no
+ * source, would vanish on the next regeneration, and would make the claim
+ * "this dataset rebuilds from `appkit/src/seed/` alone" false. Adding a part is
+ * a change to the generator.
+ *
+ * What this surface IS for is the thing the corpus demonstrably needs — fixing
+ * a wrong extraction. On mode data alone the source was wrong five times in one
+ * session: an inverted tip transition, a mechanism attributed to the wrong
+ * part, a part with no modes at all, and two misexpanded abbreviations. A
+ * correction made here survives the next reseed, field by field
+ * (`adminEditedFields`).
+ *
+ * @tag domain:parts
+ * @tag layer:feature
+ * @tag access:client
+ * @tag consumers:app/[locale]/admin/parts/page.tsx
+ */
+import React from "react";
+import { Heading, ListingLayout, Stack, Text } from "../../../ui/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { PART_GLOSSARY_FIELDS } from "../../../constants/field-names.js";
+import { sortBy } from "../../../constants/sort.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { DataListingView } from "./DataListingView.js";
+/**
+ * 🛑 Rows are read from WHICHEVER envelope shape arrives.
+ *
+ * `apiClient.get()` unwraps `{success, data}` and returns `data` itself, so an
+ * endpoint that puts rows directly in `data` hands `mapRows` an ARRAY while one
+ * that nests them hands it an object. Reading `.data` off an array yields
+ * undefined — which is exactly how the categories listing rendered "No
+ * categories found" against a 200 carrying 58 rows. This route returns the
+ * object shape, and tolerating both is what keeps that from mattering.
+ */
+function extractRows(response) {
+    if (Array.isArray(response))
+        return response;
+    if (!response || typeof response !== "object")
+        return [];
+    const obj = response;
+    if (Array.isArray(obj.data))
+        return obj.data;
+    return Array.isArray(obj.items) ? obj.items : [];
+}
+function extractTotal(response) {
+    if (Array.isArray(response) || !response || typeof response !== "object")
+        return undefined;
+    const total = response.total;
+    return typeof total === "number" ? total : undefined;
+}
+/*
+ * audit-create-affordance-ok: this listing is deliberately inbound-only.
+ * The 2,488 rows are produced by committed generators from a crawled
+ * corpus, so there is no POST endpoint and no create route key to point a
+ * button at — a part authored by hand would have no source, would vanish
+ * on the next regeneration, and would make "this dataset rebuilds from
+ * appkit/src/seed/ alone" false. Adding one is a change to the generator.
+ * The surface exists to CORRECT a wrong extraction and to REMOVE a row that
+ * should not exist, which are the two operations the data actually needs.
+ */
+const COLUMNS = [
+    {
+        key: "primary",
+        header: "Part",
+        sortable: true,
+        render: (row) => (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { weight: "semibold", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", children: row.secondary })] })),
+    },
+    {
+        key: "weight",
+        header: "Weight",
+        className: "w-24",
+        render: (row) => (_jsx(Text, { size: "sm", color: "muted", children: row.weight })),
+    },
+    {
+        key: "edited",
+        header: "Corrected",
+        className: "w-28",
+        /*
+         * 🛑 Shown as a COLUMN, because a hand-corrected row behaves differently
+         * from its neighbours — the generator no longer owns the fields somebody
+         * fixed. Leaving that invisible is how a later maintainer concludes the
+         * generator is producing a value it is actually being prevented from
+         * writing. Text, not a colour-only dot (colour is never the only signal).
+         */
+        render: (row) => row.edited ? (_jsx(Text, { size: "xs", weight: "medium", children: "By hand" })) : (_jsx(Text, { size: "xs", color: "faint", children: "Generated" })),
+    },
+];
+const ADMIN_PARTS_CONFIG = {
+    portal: "admin",
+    title: "Parts",
+    subtitle: "The generated part glossary. Corrections made here are kept when the database is regenerated.",
+    searchPlaceholder: "Search parts by name — Rubber Flat, Dranzer…",
+    /*
+     * 🛑 `searchCommit: "enter"`, not debounce. The route's search is an indexed
+     * PREFIX range, so a partial word is a different query rather than a
+     * narrowing one — debouncing would fire a range query per pause and show
+     * confusing intermediate results. Enter also makes the prefix-only behaviour
+     * legible: you typed a prefix and asked for it.
+     */
+    searchCommit: "enter",
+    /*
+     * 🛑 DECLARED, so the placeholder can be CHECKED rather than trusted.
+     * The route matches exactly one field — an indexed prefix range on
+     * `name` — and the placeholder must not imply more. It is a prefix and
+     * it is case-sensitive; `mode` says so where a reader will see it.
+     */
+    search: {
+        placeholder: "Search parts by name — a prefix, case-sensitive",
+        fields: ["name"],
+    },
+    emptyLabel: "No part matches that name",
+    filterKeys: [],
+    /*
+     * 🛑 Through `sortBy`, not a bare "name". The route currently ALWAYS
+     * orders by name and ignores the `sorts` param, so this is the only
+     * option — but writing it as a literal is what lets a field rename
+     * leave a sort string that silently sorts nothing.
+     */
+    defaultSort: sortBy(PART_GLOSSARY_FIELDS.NAME, "ASC"),
+    pageSize: 25,
+    queryKey: ["admin", "parts"],
+    endpoint: ADMIN_ENDPOINTS.PARTS,
+    sortOptions: [{ value: sortBy(PART_GLOSSARY_FIELDS.NAME, "ASC"), label: "Name A-Z" }],
+    columns: COLUMNS,
+    buildFilters: () => undefined,
+    getTotal: (response, rows) => extractTotal(response) ?? rows.length,
+    mapRows: (response) => extractRows(response).map((raw) => {
+        const r = raw;
+        const weight = typeof r.weightG === "number" ? `${r.weightG} g` : "—";
+        return {
+            id: String(r.id ?? ""),
+            primary: String(r.name ?? r.id ?? "Unnamed part"),
+            /* The classification is what disambiguates a bare code like "105". */
+            secondary: [r.classification, r.code].filter(Boolean).join(" · ") || "—",
+            weight,
+            edited: r.adminEdited === true,
+        };
+    }),
+    /*
+     * 🛑 `rowHrefTemplate`, not `rowHref`. Verified against the interface
+     * rather than guessed — there is no `rowHref` field, and an unknown key on
+     * an object literal typed by an interface is a compile error I could not
+     * have seen under this session's no-build cap.
+     */
+    rowHrefTemplate: (row) => String(ROUTES.ADMIN.PARTS_EDIT(row.id)),
+};
+export function AdminPartsView({ children, ...props }) {
+    if (React.Children.count(children) > 0) {
+        return (_jsxs(ListingLayout, { portal: "admin", ...props, children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Parts" }), children] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Heading, { level: 1, className: "sr-only", children: "Parts" }), _jsx(DataListingView, { config: ADMIN_PARTS_CONFIG })] }));
+}

package/dist/features/admin/components/OwnerQuickActions.d.ts

@@ -1,5 +1,5 @@
 /** Which registry bucket supplies the labels and the confirm copy. */
-export type OwnerQuickActionsResource = "PRODUCT" | "CATEGORY" | "BRAND" | "BUNDLE" | "GROUP" | "SUBLISTING" | "EVENT" | "BLOG" | "REVIEW";
+export type OwnerQuickActionsResource = "PRODUCT" | "CATEGORY" | "BRAND" | "FRANCHISE" | "PART" | "BEY" | "BUNDLE" | "GROUP" | "SUBLISTING" | "EVENT" | "BLOG" | "REVIEW" | "STORE" | "USER" | "CAROUSEL" | "SECTION";
 export interface OwnerQuickActionsProps {
     resource: OwnerQuickActionsResource;
     /** Where the pencil goes — that record's dashboard editor. */
@@ -24,6 +24,23 @@ export interface OwnerQuickActionsProps {
      * `detail` sits in a header row beside the title.
      */
     placement?: "card" | "detail";
+    /**
+     * 🛑 Set this whenever `placement="detail"` sits on a DARK cover hero.
+     *
+     * `detail` otherwise renders the `ghost` variant, which is
+     * `color: var(--appkit-color-zinc-600)` — a dark grey that is correct on a
+     * page-surface header row and invisible on a cover photo. Every detail view
+     * that has a hero already computes a `hasCover` flag and flips each of its
+     * siblings to `color="inverse"`; this toolbar was the one element in that
+     * block that did not, so the pencil rendered near-black on near-black and
+     * read as "admins get no edit button" (Root Cause #67 — a theme-relative ink
+     * on a theme-invariant dark surface).
+     *
+     * Pass the SAME flag the rest of the hero branches on, not a literal `true`:
+     * a coverless hero falls back to the page surface, where the scrim's white
+     * ink would be invisible in the mirror-image way.
+     */
+    onMedia?: boolean;
     className?: string;
 }
-export declare function OwnerQuickActions({ resource, editHref, onDelete, onClone, ownerId, storeId, recordLabel, placement, className, }: OwnerQuickActionsProps): import("react").JSX.Element | null;
+export declare function OwnerQuickActions({ resource, editHref, onDelete, onClone, ownerId, storeId, recordLabel, placement, onMedia, className, }: OwnerQuickActionsProps): import("react").JSX.Element | null;

package/dist/features/admin/components/OwnerQuickActions.js

@@ -54,14 +54,63 @@ import { IconButton } from "../../../ui/components/IconButton.js";
 import { Row, useToast } from "../../../ui/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
-export function OwnerQuickActions({ resource, editHref, onDelete, onClone, ownerId, storeId, recordLabel, placement = "card", className = "", }) {
+const RESOURCE_LEAVES = {
+    PRODUCT: { bucket: "PRODUCT", edit: "edit", remove: "delete", duplicate: "duplicate" },
+    CATEGORY: { bucket: "CATEGORY", edit: "edit", remove: "delete" },
+    /*
+     * Both get a bin. Unlike the three pencil-only resources below, the blast
+     * radius of removing one reference row is SMALL and bounded: a bey keeps
+     * its parts list (`partName` sits beside `partId` for exactly this), a
+     * boxed set keeps its contents, and a category page keeps its listings.
+     * Nothing cascades, and the committed seed can put the row back.
+     */
+    PART: { bucket: "PART", edit: "edit", remove: "delete" },
+    BEY: { bucket: "BEY", edit: "edit", remove: "delete" },
+    BRAND: { bucket: "BRAND", edit: "edit", remove: "delete" },
+    BUNDLE: { bucket: "BUNDLE", edit: "edit", remove: "delete" },
+    GROUP: { bucket: "GROUP", edit: "edit", remove: "delete" },
+    SUBLISTING: { bucket: "SUBLISTING", edit: "edit", remove: "delete" },
+    EVENT: { bucket: "EVENT", edit: "edit", remove: "delete", duplicate: "duplicate" },
+    REVIEW: { bucket: "REVIEW", edit: "edit", remove: "delete" },
+    /** 🛑 `edit-post` / `delete-post`, not `edit` / `delete`. See the note above. */
+    BLOG: { bucket: "BLOG", edit: "edit-post", remove: "delete-post", duplicate: "duplicate-post" },
+    /**
+     * A franchise row IS a category (`categoryType: "franchise"`), so it reuses
+     * the category leaves rather than duplicating copy that would drift.
+     */
+    FRANCHISE: { bucket: "CATEGORY", edit: "edit", remove: "delete" },
+    /** Carousel slides have no bucket of their own; the leaves live under ADMIN. */
+    CAROUSEL: { bucket: "ADMIN", edit: "edit-carousel", remove: "delete-carousel" },
+    /*
+     * ── The three PENCIL-ONLY resources ─────────────────────────────────────
+     *
+     * `remove` is omitted on purpose for all three. Each is a delete whose blast
+     * radius is far larger than the page the bin would sit on, and a public
+     * surface is the worst possible place to offer it:
+     *
+     * STORE   — deleting a store orphans its products, orders and payouts. The
+     *           dashboard offers `suspend-store` / `verify-store`, which are the
+     *           operations an admin actually wants from a store page.
+     * USER    — deleting a user cascades across orders, reviews, bids and
+     *           addresses. `ADMIN.ban-user` is the reversible tool, and it has
+     *           its own flow with a reason.
+     * SECTION — homepage section `order` is POSITIONAL, so removing one silently
+     *           renumbers its neighbours. There is also no per-section public
+     *           page; the pencil goes to the list that owns them.
+     */
+    STORE: { bucket: "ADMIN", edit: "manage-store" },
+    USER: { bucket: "ADMIN", edit: "manage-user" },
+    SECTION: { bucket: "ADMIN", edit: "edit-section" },
+};
+export function OwnerQuickActions({ resource, editHref, onDelete, onClone, ownerId, storeId, recordLabel, placement = "card", onMedia = false, className = "", }) {
     const session = useOptionalSession();
     const isOwnerOrAdmin = useIsOwner(ownerId);
     const isAdmin = useIsAdmin();
     const { showToast } = useToast();
     const [confirmOpen, setConfirmOpen] = useState(false);
     const [deleting, setDeleting] = useState(false);
-    const bucket = ACTIONS[resource];
+    const leaves = RESOURCE_LEAVES[resource];
+    const bucket = ACTIONS[leaves.bucket];
     const handleConfirmedDelete = useCallback(async () => {
         if (!onDelete)
             return;
@@ -113,10 +162,36 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
      */
     if (!isAdmin && !isOwnerOrAdmin && !ownsStore)
         return null;
-    const editDef = bucket.edit;
-    const deleteDef = bucket.delete;
+    const editDef = bucket[leaves.edit];
+    const deleteDef = leaves.remove ? bucket[leaves.remove] : undefined;
     const confirmation = deleteDef?.confirmation;
-    const showClone = Boolean(onClone) && isAdmin;
+    const showClone = Boolean(onClone) && isAdmin && Boolean(leaves.duplicate);
+    /*
+     * 🛑 `leaves.remove` gates the bin, not just `onDelete`. A resource whose
+     * mapping omits a delete leaf (store, user, homepage section) must render no
+     * bin even if a caller passes `onDelete` — the safety decision belongs to the
+     * resource, not to each of its call sites, or the next call site re-opens it.
+     */
+    const showDelete = Boolean(onDelete) && Boolean(leaves.remove);
+    /*
+     * 🛑 The scrim is for ANY dark backdrop, not only a card.
+     *
+     * `detail` used to hard-map to `ghost` (`color: var(--appkit-color-zinc-600)`),
+     * which is right on a page-surface header row and invisible on a cover photo
+     * — and every detail view with a hero puts this toolbar inside that hero,
+     * beside siblings it has already flipped to `color="inverse"`. The pencil
+     * therefore rendered near-black on near-black and read as "admins get no
+     * edit button at all". See `onMedia` above and Root Cause #67.
+     */
+    const onDark = placement === "card" || onMedia;
+    const neutralVariant = onDark ? "scrim" : "ghost";
+    /*
+     * Danger ink is dropped on a dark backdrop for the same reason: `danger`
+     * resolves to a theme-relative red that disappears against the hero. The bin
+     * keeps its confirm dialog, which is where the destructive intent is
+     * actually communicated — colour was never the safeguard.
+     */
+    const dangerVariant = onDark ? "scrim" : "danger";
     return (_jsxs(_Fragment, { children: [_jsxs(Row, { gap: "xs", align: "center", className: className, 
                 /*
                  * Stops the click reaching an ancestor `<Link>` or the card's own
@@ -125,7 +200,7 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
                  */
                 onClick: (e) => {
                     e.stopPropagation();
-                }, children: [_jsx(IconButton, { "aria-label": editDef?.ariaLabel ?? editDef?.label ?? "Edit", size: "touch", variant: placement === "card" ? "scrim" : "ghost", icon: _jsx(Icon, { name: "edit" }), onClick: () => {
+                }, children: [_jsx(IconButton, { "aria-label": editDef?.ariaLabel ?? editDef?.label ?? "Edit", size: "touch", variant: neutralVariant, icon: _jsx(Icon, { name: "edit" }), onClick: () => {
                             /*
                              * `window.location`, not `next/link`. This component is rendered
                              * inside cards whose whole body is already an anchor, and nesting
@@ -135,8 +210,8 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
                              */
                             if (typeof window !== "undefined")
                                 window.location.assign(editHref);
-                        } }), showClone && (_jsx(IconButton, { "aria-label": (bucket.duplicate?.ariaLabel ?? bucket.duplicate?.label) ||
-                            "Duplicate", size: "touch", variant: placement === "card" ? "scrim" : "ghost", icon: _jsx(Icon, { name: "duplicate" }), onClick: () => void onClone?.() })), onDelete && (_jsx(IconButton, { "aria-label": deleteDef?.ariaLabel ?? deleteDef?.label ?? "Delete", size: "touch", variant: placement === "card" ? "scrim" : "danger", icon: _jsx(Icon, { name: "delete" }), onClick: () => setConfirmOpen(true) }))] }), onDelete && (_jsx(ConfirmDeleteModal, { isOpen: confirmOpen, onClose: () => setConfirmOpen(false), onConfirm: handleConfirmedDelete, isDeleting: deleting, title: confirmation?.title ?? "Delete this record?", message: recordLabel && confirmation
+                        } }), showClone && (_jsx(IconButton, { "aria-label": (leaves.duplicate ? bucket[leaves.duplicate]?.ariaLabel ?? bucket[leaves.duplicate]?.label : undefined) ||
+                            "Duplicate", size: "touch", variant: neutralVariant, icon: _jsx(Icon, { name: "duplicate" }), onClick: () => void onClone?.() })), showDelete && (_jsx(IconButton, { "aria-label": deleteDef?.ariaLabel ?? deleteDef?.label ?? "Delete", size: "touch", variant: dangerVariant, icon: _jsx(Icon, { name: "delete" }), onClick: () => setConfirmOpen(true) }))] }), showDelete && (_jsx(ConfirmDeleteModal, { isOpen: confirmOpen, onClose: () => setConfirmOpen(false), onConfirm: handleConfirmedDelete, isDeleting: deleting, title: confirmation?.title ?? "Delete this record?", message: recordLabel && confirmation
                     ? `${confirmation.body}\n\nDeleting: ${recordLabel}`
                     : confirmation?.body, confirmText: confirmation?.confirmLabel ?? deleteDef?.label ?? "Delete", variant: "danger" }))] }));
 }

package/dist/features/admin/components/RecordOwnerQuickActions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The admin-owned resources this wrapper can delete.
+ *
+ * 🛑 Deliberately NOT every `OwnerQuickActionsResource`. `STORE`, `USER` and
+ * `SECTION` omit a `remove` leaf in `RESOURCE_LEAVES` because their blast
+ * radius is far wider than the page a bin would sit on, and `REVIEW` has no
+ * admin edit route to send the pencil to. Adding one here without adding its
+ * leaf there still renders no bin — the resource owns that decision, which is
+ * the point of gating it in two places.
+ */
+export type RecordQuickActionResource = "CATEGORY" | "BRAND" | "BUNDLE" | "GROUP" | "EVENT" | "BLOG" | "FRANCHISE" | "SUBLISTING" | "PART" | "BEY";
+export interface RecordOwnerQuickActionsProps {
+    resource: RecordQuickActionResource;
+    /** The record's document id — what the endpoint and the editor are keyed on. */
+    recordId: string;
+    /** Names the record in the delete confirmation. */
+    recordLabel?: string;
+    /**
+     * Forwarded to `OwnerQuickActions` so a store-owned record (a grouped
+     * listing, a store-authored bundle) stays visible to the seller who owns it
+     * and not only to an admin. `SessionUser.storeId` holds the store SLUG, not
+     * the Auth UID — two different id spaces, hence two props.
+     */
+    ownerId?: string;
+    storeId?: string;
+    placement?: "card" | "detail";
+    /** Pass the hero's own `hasCover` flag. See `OwnerQuickActions.onMedia`. */
+    onMedia?: boolean;
+    className?: string;
+}
+export declare function RecordOwnerQuickActions({ resource, recordId, recordLabel, ownerId, storeId, placement, onMedia, className, }: RecordOwnerQuickActionsProps): import("react").JSX.Element;