@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -13,6 +13,9 @@ import { ADMIN_USER_STATUS_TABS, ADMIN_USER_ROLE_TABS } from "../constants/filte
 import { toRecordArray, toRelativeDate, toStringValue, } from "../hooks/useAdminListingData.js";
 import { DataListingView } from "./DataListingView.js";
 import { apiClient } from "../../../http/index.js";
+import { QuickFormDrawer } from "../../shell/QuickFormDrawer.js";
+import { pointsAdjustFormSchema } from "../../points/schemas/adjust-form.js";
+import { POINTS_ADJUSTMENT_MAX, POINTS_ADJUSTMENT_REASON_MIN, } from "../../points/schemas/firestore.js";
 import { AdminUserEditorView } from "./AdminUserEditorView.js";
 import { useBulkAction } from "../../../react/index.js";
 import { useBulkEvent } from "../../events/hooks/useBulkEvent.js";
@@ -28,6 +31,7 @@ export function AdminUsersView({ children, ...props }) {
     const [banModalOpen, setBanModalOpen] = useState(false);
     const [banTargetId, setBanTargetId] = useState(null);
     const [banReason, setBanReason] = useState("");
+    const [pointsTargetId, setPointsTargetId] = useState(null);
     const [bulkConfirmTarget, setBulkConfirmTarget] = useState(null);
     // Hard-ban runs as a Firebase Function job (cascade across address/payment
     // clusters can exceed the Vercel Hobby 10s ceiling) — the route only
@@ -80,6 +84,25 @@ export function AdminUsersView({ children, ...props }) {
             void queryClient.invalidateQueries({ queryKey: ["admin", "users", "listing"] });
         },
     });
+    /*
+     * Points adjustment (D48). `useApiMutation` is the house idiom here — it owns
+     * the loading toast and the error toast, so this only has to say what success
+     * means and what to invalidate.
+     *
+     * 🛑 Invalidates the users listing because `pointsBalance` lives on the user
+     * document, so the row an admin is looking at is stale the moment this
+     * succeeds. Without it the operator applies a credit and sees the old number,
+     * which reads as the adjustment having failed.
+     */
+    const adjustPoints = useApiMutation({
+        errorMessage: "Failed to adjust points.",
+        mutationFn: (payload) => apiClient.post(ADMIN_ENDPOINTS.POINTS, payload),
+        onSuccess: (data) => {
+            toast.showToast(`Points adjusted. New balance: ${data.balance}.`, "success");
+            setPointsTargetId(null);
+            void queryClient.invalidateQueries({ queryKey: ["admin", "users", "listing"] });
+        },
+    });
     const handleManageBulkClick = (selection) => {
         const rowId = selection.selectedIds[0];
         const row = selection.rows.find((r) => r.id === rowId) ?? null;
@@ -221,6 +244,10 @@ export function AdminUsersView({ children, ...props }) {
                         onClick: () => unbanUser.mutate(row.id),
                         disabled: !isBanned || unbanUser.isPending,
                     },
+                    {
+                        label: ACTIONS.ADMIN["adjust-user-points"].label,
+                        onClick: () => setPointsTargetId(row.id),
+                    },
                 ] }));
         },
         renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(_Fragment, { children: [_jsx(FilterChipGroup, { label: "Status", tabs: ADMIN_USER_STATUS_TABS, value: pendingFilters.status ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, status: id })) }), _jsx(FilterChipGroup, { label: "Role", tabs: ADMIN_USER_ROLE_TABS, value: pendingFilters.role ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, role: id })) })] })),
@@ -282,5 +309,49 @@ export function AdminUsersView({ children, ...props }) {
                                         .finally(() => setBulkConfirmTarget(null));
                                 }, children: bulkConfirmTarget?.action === "suspend"
                                     ? ACTIONS.ADMIN["bulk-suspend-users"].confirmation.confirmLabel
-                                    : ACTIONS.ADMIN["bulk-delete-users"].confirmation.confirmLabel })] })] })] }));
+                                    : ACTIONS.ADMIN["bulk-delete-users"].confirmation.confirmLabel })] })] }), _jsx(QuickFormDrawer, { isOpen: Boolean(pointsTargetId), onClose: () => setPointsTargetId(null), title: ACTIONS.ADMIN["adjust-user-points"].label, schema: pointsAdjustFormSchema, submitLabel: "Apply adjustment", defaultValues: { userId: pointsTargetId ?? "" }, fields: [
+                    /*
+                     * `userId` is carried as a hidden-in-practice text field rather than
+                     * injected at submit time, so the schema validates the SAME object
+                     * the route will receive. Pre-filled from the row and not meant to be
+                     * retyped.
+                     */
+                    {
+                        name: "userId",
+                        label: "User ID",
+                        type: "text",
+                        required: true,
+                        helperText: "Pre-filled from the row you opened.",
+                    },
+                    {
+                        name: "amount",
+                        label: "Points (negative to debit)",
+                        type: "number",
+                        required: true,
+                        helperText: `1 point = ₹1 against a future order. Whole numbers, up to ${POINTS_ADJUSTMENT_MAX} per adjustment.`,
+                    },
+                    {
+                        name: "description",
+                        label: "What the buyer sees",
+                        type: "text",
+                        required: true,
+                        placeholder: "Goodwill credit for the delayed BX-53 order",
+                    },
+                    {
+                        name: "adminReason",
+                        label: "Internal reason",
+                        type: "textarea",
+                        required: true,
+                        helperText: `At least ${POINTS_ADJUSTMENT_REASON_MIN} characters. Never shown to the buyer — the reader is the next admin.`,
+                    },
+                ], isLoading: adjustPoints.isPending, onSubmit: (values) => {
+                    /*
+                     * 🛑 The cast is to the SCHEMA'S OWN inferred type, and it is safe
+                     * only because `schema={pointsAdjustFormSchema}` is passed above —
+                     * the drawer will not call this until that parse succeeds, so the
+                     * shape is already proven. `FormValues` is an index-signature bag,
+                     * which is why a cast is needed at all rather than a widening.
+                     */
+                    adjustPoints.mutate(values);
+                } })] }));
 }

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

@@ -5,6 +5,8 @@ interface AdminViewCardsProps {
     view: "grid" | "list";
     isLoading?: boolean;
     emptyLabel?: string;
+    /** Rendered beneath `emptyLabel` when there are no rows — see DataTable's note. */
+    emptyAction?: React.ReactNode;
     onRowClick?: (row: AdminListingScaffoldRow) => void;
     selectedIdSet?: Set<string>;
     onToggleSelect?: (id: string) => void;
@@ -13,5 +15,5 @@ interface AdminViewCardsProps {
     /** Resource-type emoji fallback for rows without their own `image` (e.g. 👤 for users, 🏪 for stores). */
     resourceIcon?: string;
 }
-export declare function AdminViewCards({ rows, view, isLoading, emptyLabel, onRowClick, selectedIdSet, onToggleSelect, renderRowActions, resourceIcon, }: AdminViewCardsProps): React.JSX.Element;
+export declare function AdminViewCards({ rows, view, isLoading, emptyLabel, emptyAction, onRowClick, selectedIdSet, onToggleSelect, renderRowActions, resourceIcon, }: AdminViewCardsProps): React.JSX.Element;
 export {};

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

@@ -58,7 +58,7 @@ function AdminCardItem({ row, view, selected, onToggleSelect, onRowClick, render
                         e.stopPropagation();
                         if (e.target === e.currentTarget)
                             onToggleSelect(row.id);
-                    }, children: _jsx(Checkbox, { bare: true, checked: selected, onChange: () => onToggleSelect(row.id), className: "h-4 w-4 rounded border-zinc-300 text-primary accent-primary cursor-pointer", "aria-label": `Select ${row.primary}` }) })), _jsx(RowAvatar, { image: row.image, alt: row.primary, icon: resourceIcon }), _jsxs(Stack, { gap: "none", className: "flex-1 min-w-0", children: [_jsx(Text, { size: "sm", weight: "semibold", className: "truncate", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", className: "truncate", children: row.secondary }), row.barcodeId && (_jsx(Text, { size: "xs", color: "faint", className: "truncate font-mono", children: row.barcodeId }))] }), flags.length > 0 && (_jsx(Row, { gap: "xs", className: "hidden sm:flex shrink-0", children: flags.map(({ key, label, tone }) => (_jsx(Span, { padding: "pill-2xs", weight: "medium", className: `inline-flex text-[10px] ${STATUS_TONE_CLASSES[tone]}`, rounded: "full", children: label }, key))) })), _jsx(StatusBadge, { status: row.status }), _jsx(Span, { size: "xs", color: "muted", className: "hidden sm:block shrink-0 w-24", align: "end", children: row.updatedAt }), renderRowActions && (_jsx(Div, { "data-no-row-click": true, className: "shrink-0", onClick: (e) => e.stopPropagation(), children: renderRowActions(row) }))] }));
+                    }, children: _jsx(Checkbox, { bare: true, checked: selected, onChange: () => onToggleSelect(row.id), className: "h-4 w-4 rounded border-zinc-300 text-primary accent-primary cursor-pointer", "aria-label": `Select ${row.primary}` }) })), _jsx(RowAvatar, { image: row.image, alt: row.primary, icon: resourceIcon }), _jsxs(Stack, { gap: "none", className: "flex-1 min-w-0", children: [_jsx(Text, { size: "sm", weight: "semibold", truncate: 2, color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", className: "truncate", children: row.secondary }), (row.barcodeId || row.boxCode) && (_jsx(Text, { size: "xs", color: "faint", className: "truncate font-mono", children: [row.barcodeId, row.boxCode].filter(Boolean).join(" · ") })), _jsx(Div, { className: "sm:hidden mt-1", children: _jsx(StatusBadge, { status: row.status }) })] }), flags.length > 0 && (_jsx(Row, { gap: "xs", className: "hidden sm:flex shrink-0", children: flags.map(({ key, label, tone }) => (_jsx(Span, { padding: "pill-2xs", weight: "medium", className: `inline-flex text-[10px] ${STATUS_TONE_CLASSES[tone]}`, rounded: "full", children: label }, key))) })), _jsx(Div, { className: "hidden sm:block shrink-0", children: _jsx(StatusBadge, { status: row.status }) }), _jsx(Span, { size: "xs", color: "muted", className: "hidden sm:block shrink-0 w-24", align: "end", children: row.updatedAt }), renderRowActions && (_jsx(Div, { "data-no-row-click": true, className: "shrink-0", onClick: (e) => e.stopPropagation(), children: renderRowActions(row) }))] }));
     }
     return (_jsxs(Div, { rounded: "xl", className: [
             "border overflow-hidden cursor-pointer transition-all hover:shadow-md hover:-translate-y-0.5",
@@ -71,9 +71,9 @@ function AdminCardItem({ row, view, selected, onToggleSelect, onRowClick, render
                     e.stopPropagation();
                     if (e.target === e.currentTarget)
                         onToggleSelect(row.id);
-                }, children: [_jsx(Checkbox, { bare: true, checked: selected, onChange: () => onToggleSelect(row.id), className: "h-4 w-4 rounded border-zinc-300 text-primary accent-primary cursor-pointer", "aria-label": `Select ${row.primary}` }), flags.length > 0 && (_jsx(Row, { gap: "xs", wrap: true, children: flags.map(({ key, label, tone }) => (_jsx(Span, { padding: "pill-2xs", weight: "medium", className: `inline-flex text-[10px] ${STATUS_TONE_CLASSES[tone]}`, rounded: "full", children: label }, key))) }))] })), _jsxs(Stack, { gap: "xs", className: `${__P.p3}.5`, children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(RowAvatar, { image: row.image, alt: row.primary, icon: resourceIcon, size: "12" }), _jsxs(Stack, { gap: "none", className: "min-w-0 flex-1", children: [_jsx(Text, { size: "sm", weight: "semibold", className: "line-clamp-2 leading-snug", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", className: "truncate", children: row.secondary })] })] }), row.barcodeId && (_jsx(Text, { size: "xs", color: "faint", className: "truncate font-mono", children: row.barcodeId })), _jsxs(Row, { justify: "between", gap: "xs", children: [_jsx(StatusBadge, { status: row.status }), _jsx(Span, { color: "muted", className: "text-[11px] shrink-0", children: row.updatedAt })] }), renderRowActions && (_jsx(Row, { "data-no-row-click": true, justify: "end", gap: "xs", className: "border-t border-[var(--appkit-color-border)] -mx-[var(--appkit-space-3)] -mb-[var(--appkit-space-3)] mt-[var(--appkit-space-1)] px-[var(--appkit-space-3)] py-[var(--appkit-space-2)]", onClick: (e) => e.stopPropagation(), children: renderRowActions(row) }))] })] }));
+                }, children: [_jsx(Checkbox, { bare: true, checked: selected, onChange: () => onToggleSelect(row.id), className: "h-4 w-4 rounded border-zinc-300 text-primary accent-primary cursor-pointer", "aria-label": `Select ${row.primary}` }), flags.length > 0 && (_jsx(Row, { gap: "xs", wrap: true, children: flags.map(({ key, label, tone }) => (_jsx(Span, { padding: "pill-2xs", weight: "medium", className: `inline-flex text-[10px] ${STATUS_TONE_CLASSES[tone]}`, rounded: "full", children: label }, key))) }))] })), _jsxs(Stack, { gap: "xs", className: `${__P.p3}.5`, children: [_jsxs(Row, { gap: "sm", align: "center", children: [_jsx(RowAvatar, { image: row.image, alt: row.primary, icon: resourceIcon, size: "12" }), _jsxs(Stack, { gap: "none", className: "min-w-0 flex-1", children: [_jsx(Text, { size: "sm", weight: "semibold", className: "line-clamp-2 leading-snug", color: "primary", children: row.primary }), _jsx(Text, { size: "xs", color: "muted", className: "truncate", children: row.secondary })] })] }), (row.barcodeId || row.boxCode) && (_jsx(Text, { size: "xs", color: "faint", className: "truncate font-mono", children: [row.barcodeId, row.boxCode].filter(Boolean).join(" · ") })), _jsxs(Row, { justify: "between", gap: "xs", children: [_jsx(StatusBadge, { status: row.status }), _jsx(Span, { color: "muted", className: "text-[11px] shrink-0", children: row.updatedAt })] }), renderRowActions && (_jsx(Row, { "data-no-row-click": true, justify: "end", gap: "xs", className: "border-t border-[var(--appkit-color-border)] -mx-[var(--appkit-space-3)] -mb-[var(--appkit-space-3)] mt-[var(--appkit-space-1)] px-[var(--appkit-space-3)] py-[var(--appkit-space-2)]", onClick: (e) => e.stopPropagation(), children: renderRowActions(row) }))] })] }));
 }
-export function AdminViewCards({ rows, view, isLoading, emptyLabel = "No items found", onRowClick, selectedIdSet, onToggleSelect, renderRowActions, resourceIcon, }) {
+export function AdminViewCards({ rows, view, isLoading, emptyLabel = "No items found", emptyAction, onRowClick, selectedIdSet, onToggleSelect, renderRowActions, resourceIcon, }) {
     if (isLoading) {
         const count = view === "grid" ? 12 : 8;
         if (view === "list") {
@@ -82,7 +82,7 @@ export function AdminViewCards({ rows, view, isLoading, emptyLabel = "No items f
         return (_jsx(Grid, { cols: "cards", gap: "md", children: Array.from({ length: count }).map((_, i) => _jsx(SkeletonCard, { view: "grid" }, i)) }));
     }
     if (rows.length === 0) {
-        return (_jsx(Text, { paddingY: "3xl", size: "sm", color: "muted", align: "center", children: emptyLabel }));
+        return (_jsxs(Stack, { paddingY: "y-3xl", gap: "md", align: "center", children: [_jsx(Text, { size: "sm", color: "muted", align: "center", children: emptyLabel }), emptyAction] }));
     }
     if (view === "list") {
         return (_jsx(Div, { rounded: "xl", border: "subtle", className: `${__O.hidden} divide-y divide-zinc-100 divide-[var(--appkit-color-border)]`, children: rows.map((row) => (_jsx(AdminCardItem, { row: row, view: "list", selected: selectedIdSet?.has(row.id) ?? false, onToggleSelect: onToggleSelect, onRowClick: onRowClick, renderRowActions: renderRowActions, resourceIcon: resourceIcon }, row.id))) }));

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

@@ -39,6 +39,26 @@ export interface AdminListingScaffoldRow {
     isOnSale?: boolean;
     isSold?: boolean;
     barcodeId?: string;
+    /**
+     * The storage box this row's item is in — `AC60-03`.
+     *
+     * 🛑 OPTIONAL, AND ONLY A ROW MAPPER THAT ACTUALLY HAS IT MAY SET IT. A
+     * placement lives in `inventoryPlacements`, keyed `{boxId}__{productId}`, so
+     * a listing query does not carry it for free: a mapper that wants this
+     * column has to join, and most should not — one placements read per row is
+     * an N+1 against Rule #6's ~3-round-trip budget.
+     *
+     * It is declared here rather than left to a bespoke column because "where
+     * is this thing" is the question a warehouse screen exists to answer, and
+     * the alternative was the free-text `physicalLocation` that was retired for
+     * being three uncontrolled inputs nothing could group.
+     *
+     * 🛑 A row with no placement renders NOTHING here, never "—" and never
+     * "Unknown". An item that has not been put in a box yet and an item whose
+     * placement we failed to read are different facts, and a dash asserts the
+     * first about both.
+     */
+    boxCode?: string;
     /** Row photo/thumbnail (avatar, product image, store logo, cover image, etc). Falls back to the table's resource icon when omitted. */
     image?: string;
 }
@@ -78,6 +98,14 @@ export interface ListingViewConfig<TResponse, TRow extends {
     portal: "admin" | "seller" | "user";
     title: string;
     subtitle?: string;
+    /**
+     * Suppress the `<h1>` this view renders from `title`.
+     *
+     * For the handful of pages that already author their own heading — a second
+     * `<h1>` is a worse outline than none, which is the defect this header was
+     * added to fix. Everything else leaves it unset and gets the heading.
+     */
+    hideHeader?: boolean;
     /**
      * Search box copy. OPTIONAL — declaring it is what makes the box exist.
      *

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

@@ -1,7 +1,30 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * DataListingView — config-driven listing scaffold for admin + seller dashboards.
+ *
+ * Replaces ~30 hand-wired admin/seller view components (AdminBrandsView, AdminCategoriesView,
+ * SellerCouponsView, etc.) by accepting a single `config` object describing:
+ *   - data layer (endpoint, queryKey, mapRows, buildFilters, sortOptions)
+ *   - presentation (title, subtitle, columns, searchPlaceholder, emptyLabel)
+ *   - actions (bulkActions, primaryAction, renderRowActions)
+ *   - filter panel (renderFilterPanel)
+ *   - editor side-drawer (renderEditor)
+ *
+ * Composes: useAdminListing (data + state) + ListingToolbar + BulkActionBar + Pagination
+ *         + DataTable | AdminViewCards + ListingFilterDrawer + SideDrawer
+ *         + useBottomActions (mobile bulk bar)
+ *
+ * Usage:
+ *   const ADMIN_BRANDS_CONFIG: ListingViewConfig<BrandsResponse, BrandRow> = { ... };
+ *   <DataListingView config={ADMIN_BRANDS_CONFIG} />
+ *
+ * Created 2026-05-23 as part of W6-12 (plan: read-this-files-and-modular-storm.md).
+ */
+import React from "react";
 import { Plus } from "lucide-react";
-import { BulkActionBar, Button, Div, ListingFilterDrawer, ListingToolbar, Pagination, Row, SideDrawer, StickyToolbar, TextLink } from "../../../ui/index.js";
+import { BulkActionBar, Button, Div, Heading, Icon, IconButton, ListingFilterDrawer, ListingToolbar, Pagination, Row, SideDrawer, Stack, StickyToolbar, Text, TextLink } from "../../../ui/index.js";
+import { ROW_ACTION_ID, ROW_ACTION_META } from "../../products/constants/action-defs.js";
 import { useBottomActions } from "../../layout/index.js";
 import { useAdminListing } from "../hooks/useAdminListing.js";
 import { getResourceIcon } from "../../../ui/columns/column-renderers.js";
@@ -44,6 +67,55 @@ export function DataListingView({ config, }) {
         openEditPanel: panel.openEditPanel,
     };
     const resourceIcon = getResourceIcon(typeof config.queryKey[1] === "string" ? config.queryKey[1] : undefined);
+    /**
+     * ONE renderer for `config.primaryAction`, used by the toolbar AND by the
+     * empty state.
+     *
+     * 🛑 WHY THIS EXISTS: the action was rendered in the toolbar and nowhere
+     * else, so an admin landing on an EMPTY list was told "No X found" with no
+     * way forward — while the button that creates the first record sat in a
+     * toolbar above an empty table. 27 of ~84 listing configs declare a
+     * `primaryAction`; all 27 had that hole.
+     *
+     * 🛑 And it is a FUNCTION rather than two copies, because the alternative is
+     * the shape Root Cause #75 is about: a rule spelled out twice, where the
+     * copy made first learns nothing when the other gains a branch. The `href`
+     * vs `onClick` split and the `asChild` anchor are exactly the sort of detail
+     * that would drift.
+     *
+     * `size` is the only difference between the two placements — a toolbar
+     * button is `sm`, and an empty state is the one thing on screen, so it gets
+     * the default.
+     */
+    /*
+     * 🛑 TWO DIFFERENT EMPTY STATES, and offering the wrong action is worse than
+     * offering none.
+     *
+     * "No products found" with a New Product button is right on a fresh install
+     * and actively misleading when the admin has just filtered to
+     * `status=archived` — there may be a thousand products, and the useful move
+     * is to clear the filter, not to create a thousand-and-first. `resetAll`
+     * and `hasActiveState` already exist for the toolbar's own Reset control,
+     * so this needs no new state and cannot disagree with it.
+     */
+    const emptyIsFiltered = hasActiveState;
+    const emptyLabel = config.emptyLabel ?? `No ${config.title.toLowerCase()} found`;
+    const resolvedEmptyLabel = emptyIsFiltered
+        ? `No ${config.title.toLowerCase()} match these filters`
+        : emptyLabel;
+    const renderPrimaryAction = (size) => {
+        const action = config.primaryAction;
+        if (!action)
+            return null;
+        const icon = action.icon ?? _jsx(Plus, { className: "h-4 w-4" });
+        return action.href ? (
+        // `asChild` so a create PAGE is a real anchor — middle-click and
+        // copy-link work, and it is not a button that happens to navigate (a
+        // Known-TS-Pattern this repo bans outright).
+        _jsx(Button, { gap: "sm", size: size, asChild: true, children: _jsxs(TextLink, { variant: "inherit", href: action.href, children: [icon, action.label] }) })) : (_jsxs(Button, { gap: "sm", size: size, onClick: () => action.onClick?.({ openCreatePanel: panel.openCreatePanel }), children: [icon, action.label] }));
+    };
+    /** What an empty list offers: clear the filters, or create the first record. */
+    const renderEmptyAction = () => emptyIsFiltered ? (_jsx(Button, { variant: "secondary", onClick: resetAll, children: "Clear filters" })) : (renderPrimaryAction());
     const bulkActionItems = config.buildBulkActions?.(selectionContext);
     // Mobile bulk bar
     useBottomActions(selection.selectedCount > 0 && bulkActionItems
@@ -85,20 +157,109 @@ export function DataListingView({ config, }) {
                     window.location.href = href;
                 }
                 : undefined;
+    /*
+     * ── A DIRECT EDIT AFFORDANCE ON EVERY ROW ─────────────────────────────────
+     *
+     * Measured across 16 admin and store listings: ZERO edit links in rows and
+     * zero pencils on admin. Editing meant opening a `⋯` menu first — two
+     * clicks and a hidden menu for the single most common action an admin
+     * performs. `/store/products` had 15 pencil-labelled buttons and admin had
+     * none, so the two halves of the product did not even agree.
+     *
+     * Composed here rather than added to each config because ~105 listing
+     * screens render through this one component, and both row renderers
+     * (`DataTable` and `AdminViewCards`) already drop `renderRowActions` into a
+     * click-stopped container — so one wrapper reaches every surface.
+     *
+     * 🛑 ONLY WHEN AN EDIT TARGET ACTUALLY RESOLVES. This file already carries a
+     * long note about `AdminViewCards` once wiring every card to
+     * `openEditPanel` whether or not the config had anywhere to go, so cards
+     * looked clickable and silently did nothing. A pencil that opens nothing is
+     * that same lie with a sharper point on it: the two real targets are a
+     * drawer (`renderEditor`) and a route (`rowHrefTemplate`), and a config with
+     * neither keeps exactly the actions it declared.
+     *
+     * 🛑 `onRowClick` is deliberately NOT a target. It is an arbitrary callback
+     * — several configs use it to open a *view* modal, toggle a selection, or
+     * navigate somewhere that is not an editor — so labelling it "Edit" would
+     * promise one thing and do another.
+     *
+     * Label and icon come from `ROW_ACTION_META[ROW_ACTION_ID.EDIT]` per Rule
+     * #7, so this shares one definition with every `⋯` menu's own Edit entry
+     * rather than hardcoding a second "Edit" string.
+     */
+    const rowEditHref = React.useCallback((row) => {
+        const t = config.rowHrefTemplate;
+        if (!t)
+            return null;
+        return typeof t === "function"
+            ? t(row)
+            : t.replace("{id}", encodeURIComponent(row.id));
+    }, [config.rowHrefTemplate]);
+    const hasEditTarget = Boolean(config.renderEditor ?? config.rowHrefTemplate);
+    /*
+     * The row's own name for the accessible label, falling back to its id.
+     *
+     * 🛑 A RUNTIME CHECK, not a cast. `TRow` is only `{ id: string }` here, but
+     * every config maps its rows through `mapRows` into `AdminDataRow`, so
+     * `primary` is present in practice — which is exactly the situation where
+     * `(row as AdminDataRow).primary` would compile and then read `undefined`
+     * on the one config that is shaped differently. `typeof` proves it instead.
+     *
+     * It matters because the alternative is ~50 buttons on a page all announcing
+     * "Edit product": a screen-reader user hears the control and not the record,
+     * which is the same as having no label at all.
+     */
+    const rowEditLabel = React.useCallback((row) => {
+        const primary = row.primary;
+        const name = typeof primary === "string" && primary.trim() ? primary.trim() : row.id;
+        return `${ROW_ACTION_META[ROW_ACTION_ID.EDIT].label} ${name}`;
+    }, []);
+    /*
+     * Hoisted so the memo below depends on plain identifiers.
+     * `react-hooks/exhaustive-deps` cannot track a property read inside the
+     * nested function the memo RETURNS, so reading `config.x` there asks for
+     * `config` itself as a dependency — and `config` is a fresh object on every
+     * render for every inline config, which would make the memo recompute each
+     * time and hand `DataTable` a new prop identity on every render.
+     */
+    const { renderEditor, renderRowActions } = config;
+    const { openEditPanel } = panel;
+    const renderRowActionsWithEdit = React.useMemo(() => {
+        if (!hasEditTarget)
+            return renderRowActions;
+        return (row) => {
+            const href = rowEditHref(row);
+            return (_jsxs(Row, { align: "center", justify: "end", gap: "xs", children: [renderEditor ? (_jsx(IconButton, { "aria-label": rowEditLabel(row), size: "sm", variant: "ghost", icon: _jsx(Icon, { name: "edit" }), onClick: () => openEditPanel(row.id) })) : href ? (
+                    /*
+                     * A real link, not a click handler calling `window.location`.
+                     * The row's own navigation still does that — changing it is the
+                     * Phase 3 chrome work — but a NEW affordance has no reason to
+                     * inherit a full page load, and a link is also middle-clickable,
+                     * which is how an admin opens three records to compare them.
+                     *
+                     * Conditional rather than falling back to `href="#"`: the branch
+                     * already guarantees a template exists, so a null here would mean
+                     * one returned nothing — and a pencil linking to the current page
+                     * is worse than no pencil.
+                     */
+                    _jsx(TextLink, { href: href, variant: "bare", "aria-label": rowEditLabel(row), children: _jsx(Icon, { name: "edit", size: "sm" }) })) : null, renderRowActions?.(row)] }));
+        };
+    }, [
+        hasEditTarget,
+        renderRowActions,
+        renderEditor,
+        rowEditHref,
+        rowEditLabel,
+        openEditPanel,
+    ]);
     // A box exists only when the config asks for one.
     const searchEnabled = Boolean(config.search ?? config.searchPlaceholder);
-    return (_jsxs(Div, { className: config.className ?? "min-h-screen", children: [_jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchInput, searchPlaceholder: config.search?.placeholder ?? config.searchPlaceholder, 
+    return (_jsxs(Div, { className: config.className ?? "min-h-screen", children: [!config.hideHeader && (_jsxs(Stack, { gap: "xs", className: "mb-[var(--appkit-space-4)]", children: [_jsx(Heading, { level: 1, size: "2xl", weight: "bold", children: config.title }), config.subtitle && (_jsx(Text, { size: "sm", color: "muted", children: config.subtitle }))] })), _jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchInput, searchPlaceholder: config.search?.placeholder ?? config.searchPlaceholder, 
                 // Passing this is what renders the box — ListingToolbar gates on it.
                 // Undefined when the config declares no search, so a view whose
                 // endpoint cannot search no longer shows an input that does nothing.
-                onSearchChange: searchEnabled ? setSearchInput : undefined, onSearchCommit: searchEnabled ? commitSearch : undefined, sortValue: table.get("sort") || config.defaultSort, sortOptions: config.sortOptions, onSortChange: (v) => table.set("sort", v), showTableView: !config.hideTableView, toggles: config.toggles, view: view, onViewChange: (v) => setView(v), onResetAll: resetAll, hasActiveState: hasActiveState, extra: config.primaryAction || config.toolbarExtra ? (_jsxs(Row, { align: "center", gap: "sm", children: [config.toolbarExtra, config.primaryAction &&
-                            (config.primaryAction.href ? (
-                            // `asChild` so the create PAGE is a real anchor — middle-click
-                            // and copy-link work, and it is not a button that happens to
-                            // navigate (a Known-TS-Pattern this repo bans outright).
-                            _jsx(Button, { gap: "sm", size: "sm", asChild: true, children: _jsxs(TextLink, { variant: "inherit", href: config.primaryAction.href, children: [config.primaryAction.icon ?? _jsx(Plus, { className: "h-4 w-4" }), config.primaryAction.label] }) })) : (_jsxs(Button, { gap: "sm", size: "sm", onClick: () => config.primaryAction.onClick?.({
-                                    openCreatePanel: panel.openCreatePanel,
-                                }), children: [config.primaryAction.icon ?? _jsx(Plus, { className: "h-4 w-4" }), config.primaryAction.label] })))] })) : undefined }), config.renderAboveContent?.(), bulkActionItems && (_jsx(BulkActionBar, { selectedCount: selection.selectedCount, onClearSelection: selection.clearSelection, actions: bulkActionItems })), totalPages > 1 && (_jsx(StickyToolbar, { offset: "header+pagination", tone: "translucent", border: true, padding: "toolbar", children: _jsx(Row, { justify: "center", children: _jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: (p) => table.setPage(p), pageSize: pageSize, onPageSizeChange: setPageSize, paginationConfig: { showPageSizeSelector: true, pageSizeOptions: [10, 25, 50, 100] } }) }) })), _jsxs(Div, { paddingX: "x-sm-md", padding: "y-md", children: [errorMessage && (_jsx(Div, { textSize: "sm", className: "mb-4 border border-error/20", color: "error", surface: "danger-surface", padding: "inline", rounded: "xl", children: errorMessage })), view === "table" && !config.hideTableView && !isMobile ? (_jsx(DataTable, { columns: config.columns, rows: rows, resourceIcon: resourceIcon, isLoading: isLoading, emptyLabel: config.emptyLabel ?? `No ${config.title.toLowerCase()} found`, selectedIds: selection.selectedIdSet, onToggleSelect: selection.toggle, onToggleSelectAll: (next) => next
+                onSearchChange: searchEnabled ? setSearchInput : undefined, onSearchCommit: searchEnabled ? commitSearch : undefined, sortValue: table.get("sort") || config.defaultSort, sortOptions: config.sortOptions, onSortChange: (v) => table.set("sort", v), showTableView: !config.hideTableView, toggles: config.toggles, view: view, onViewChange: (v) => setView(v), onResetAll: resetAll, hasActiveState: hasActiveState, extra: config.primaryAction || config.toolbarExtra ? (_jsxs(Row, { align: "center", gap: "sm", children: [config.toolbarExtra, renderPrimaryAction("sm")] })) : undefined }), config.renderAboveContent?.(), bulkActionItems && (_jsx(BulkActionBar, { selectedCount: selection.selectedCount, onClearSelection: selection.clearSelection, actions: bulkActionItems })), totalPages > 1 && (_jsx(StickyToolbar, { offset: "header+pagination", tone: "translucent", border: true, padding: "toolbar", children: _jsx(Row, { justify: "center", children: _jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: (p) => table.setPage(p), pageSize: pageSize, onPageSizeChange: setPageSize, paginationConfig: { showPageSizeSelector: true, pageSizeOptions: [10, 25, 50, 100] } }) }) })), _jsxs(Div, { paddingX: "x-sm-md", padding: "y-md", children: [errorMessage && (_jsx(Div, { textSize: "sm", className: "mb-4 border border-error/20", color: "error", surface: "danger-surface", padding: "inline", rounded: "xl", children: errorMessage })), view === "table" && !config.hideTableView && !isMobile ? (_jsx(DataTable, { columns: config.columns, rows: rows, resourceIcon: resourceIcon, isLoading: isLoading, emptyLabel: resolvedEmptyLabel, emptyAction: renderEmptyAction(), selectedIds: selection.selectedIdSet, onToggleSelect: selection.toggle, onToggleSelectAll: (next) => next
                             ? selection.setSelectedIds(rows.map((r) => r.id))
                             : selection.clearSelection(), rowHrefTemplate: config.rowHrefTemplate, onRowClick: config.onRowClick
                             ? (row) => config.onRowClick(row, {
@@ -106,14 +267,14 @@ export function DataListingView({ config, }) {
                             })
                             : config.renderEditor
                                 ? (row) => panel.openEditPanel(row.id)
-                                : undefined, renderRowActions: config.renderRowActions })) : config.renderCards ? (
+                                : undefined, renderRowActions: renderRowActionsWithEdit })) : config.renderCards ? (
                     // The persisted view-mode preference is global, so a "table"
                     // value can still reach here on a hideTableView-only view (see
                     // the DataTable branch's guard above) — fall back to "grid".
-                    config.renderCards(rows, view === "table" ? "grid" : view, selectionContext, isLoading)) : (_jsx(AdminViewCards, { rows: rows, view: view === "table" ? "grid" : view, resourceIcon: resourceIcon, isLoading: isLoading, emptyLabel: config.emptyLabel ?? `No ${config.title.toLowerCase()} found`, onRowClick: resolvedRowClick
+                    config.renderCards(rows, view === "table" ? "grid" : view, selectionContext, isLoading)) : (_jsx(AdminViewCards, { rows: rows, view: view === "table" ? "grid" : view, resourceIcon: resourceIcon, isLoading: isLoading, emptyLabel: resolvedEmptyLabel, emptyAction: renderEmptyAction(), onRowClick: resolvedRowClick
                             ? (row) => resolvedRowClick(row)
-                            : undefined, selectedIdSet: selection.selectedIdSet, onToggleSelect: selection.toggle, renderRowActions: config.renderRowActions
-                            ? (row) => config.renderRowActions(row)
+                            : undefined, selectedIdSet: selection.selectedIdSet, onToggleSelect: selection.toggle, renderRowActions: renderRowActionsWithEdit
+                            ? (row) => renderRowActionsWithEdit(row)
                             : undefined }))] }), config.renderFilterPanel && (_jsx(ListingFilterDrawer, { open: filterOpen, onClose: () => setFilterOpen(false), onApply: applyFilters, onClear: clearFilters, activeCount: activeFilterCount, children: config.renderFilterPanel({
                     pendingFilters,
                     setPendingFilters,

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

@@ -24,6 +24,17 @@ interface DataTableProps<T extends {
     currentPage?: number;
     onPageChange?: (page: number) => void;
     emptyLabel?: string;
+    /**
+     * Rendered beneath `emptyLabel` when there are no rows — normally the
+     * listing's own create button.
+     *
+     * 🛑 A ReactNode rather than `{label, href}`: the caller already owns a
+     * renderer for its primary action, and a second description of the same
+     * button here would be two things to keep in step. Optional, because a
+     * listing with nothing to offer should say so and stop — an empty state
+     * with a fabricated action is worse than a quiet one.
+     */
+    emptyAction?: React.ReactNode;
     /** When provided, renders a leading checkbox column + long-press to toggle. */
     selectedIds?: Set<string>;
     onToggleSelect?: (id: string, selected: boolean) => void;
@@ -33,5 +44,5 @@ interface DataTableProps<T extends {
 }
 export declare function DataTable<T extends {
     id: string;
-}>({ columns: columnsProp, rows, isLoading, sortKey, sortDir, onSort, totalPages, currentPage, onPageChange, emptyLabel, rowHrefTemplate, onRowClick, renderRowActions, selectedIds, onToggleSelect, onToggleSelectAll, resourceIcon, }: DataTableProps<T>): React.JSX.Element;
+}>({ columns: columnsProp, rows, isLoading, sortKey, sortDir, onSort, totalPages, currentPage, onPageChange, emptyLabel, emptyAction, rowHrefTemplate, onRowClick, renderRowActions, selectedIds, onToggleSelect, onToggleSelectAll, resourceIcon, }: DataTableProps<T>): React.JSX.Element;
 export {};

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

@@ -48,11 +48,11 @@ function SelectableRow({ row, columns, isSelected, onToggle, renderRowActions, o
                     ? col.render(row)
                     : String(row[col.key] ?? "") }, col.key))), renderRowActions && (_jsx(Td, { padding: "xs-3", onClick: (e) => e.stopPropagation(), children: renderRowActions(row) }))] }));
 }
-export function DataTable({ columns: columnsProp, rows, isLoading, sortKey, sortDir, onSort, totalPages = 1, currentPage = 1, onPageChange, emptyLabel = "No records found", rowHrefTemplate, onRowClick, renderRowActions, selectedIds, onToggleSelect, onToggleSelectAll, resourceIcon, }) {
+export function DataTable({ columns: columnsProp, rows, isLoading, sortKey, sortDir, onSort, totalPages = 1, currentPage = 1, onPageChange, emptyLabel = "No records found", emptyAction, rowHrefTemplate, onRowClick, renderRowActions, selectedIds, onToggleSelect, onToggleSelectAll, resourceIcon, }) {
     const columns = (columnsProp ?? buildDefaultColumns(resourceIcon));
     const selectionEnabled = Boolean(onToggleSelect);
     const allRowsSelected = selectionEnabled && rows.length > 0 && rows.every((r) => selectedIds?.has(r.id));
-    return (_jsxs(Div, { surface: "card", className: `${__O.hidden}`, children: [_jsx(Div, { className: `${__O.xAuto}`, children: _jsxs(Table, { "data-testid": "data-table", size: "sm", children: [_jsx(Thead, { children: _jsxs(Tr, { className: "bg-[var(--appkit-color-bg)] dark:bg-[var(--appkit-color-surface-elevated)]", border: "default", children: [selectionEnabled && (_jsx(Th, { padding: "xs-3", scope: "col", className: "w-10", children: onToggleSelectAll && (_jsx(Checkbox, { bare: true, "data-testid": "select-all-checkbox", "aria-label": allRowsSelected ? "Deselect all" : "Select all", checked: allRowsSelected, onChange: () => onToggleSelectAll(!allRowsSelected), className: "h-4 w-4 rounded border-[var(--appkit-color-border)] accent-zinc-900 dark:accent-zinc-100" })) })), columns.map((col) => (_jsxs(Th, { scope: "col", onClick: col.sortable && onSort ? () => onSort(col.key) : undefined, className: `text-left text-[var(--appkit-color-text)] ${col.sortable && onSort ? "cursor-pointer select-none hover:text-primary" : ""} ${COLUMN_PRIORITY_CLASS[resolveColumnPriority(col)]} ${col.className ?? ""}`, padding: "md", weight: "semibold", children: [col.header, col.sortable && sortKey === col.key && (_jsx(Span, { className: "ml-1", children: sortDir === "asc" ? "↑" : "↓" }))] }, col.key))), renderRowActions && _jsx(Th, { padding: "xs-3", scope: "col", className: "w-12" })] }) }), _jsx(Tbody, { children: isLoading ? (Array.from({ length: 5 }).map((_, i) => (_jsxs(Tr, { border: "default", children: [selectionEnabled && _jsx(Td, { padding: "xs-3", className: "w-10" }), columns.map((col) => (_jsx(Td, { padding: "md", className: COLUMN_PRIORITY_CLASS[resolveColumnPriority(col)], children: _jsx(Div, { className: "h-4 w-full animate-pulse bg-neutral-200", rounded: "default" }) }, col.key)))] }, i)))) : rows.length === 0 ? (_jsx(Tr, { children: _jsx(Td, { colSpan: columns.length + (selectionEnabled ? 1 : 0) + (renderRowActions ? 1 : 0), align: "center", color: "faint", paddingX: "md", paddingY: "md", children: emptyLabel }) })) : (rows.map((row) => (_jsx(SelectableRow, { row: row, columns: columns, isSelected: selectedIds?.has(row.id) ?? false, onToggle: onToggleSelect, renderRowActions: renderRowActions, onRowClick: onRowClick, rowHref: typeof rowHrefTemplate === "function"
+    return (_jsxs(Div, { surface: "card", className: `${__O.hidden}`, children: [_jsx(Div, { className: `${__O.xAuto}`, children: _jsxs(Table, { "data-testid": "data-table", size: "sm", children: [_jsx(Thead, { children: _jsxs(Tr, { className: "bg-[var(--appkit-color-bg)] dark:bg-[var(--appkit-color-surface-elevated)]", border: "default", children: [selectionEnabled && (_jsx(Th, { padding: "xs-3", scope: "col", className: "w-10", children: onToggleSelectAll && (_jsx(Checkbox, { bare: true, "data-testid": "select-all-checkbox", "aria-label": allRowsSelected ? "Deselect all" : "Select all", checked: allRowsSelected, onChange: () => onToggleSelectAll(!allRowsSelected), className: "h-4 w-4 rounded border-[var(--appkit-color-border)] accent-zinc-900 dark:accent-zinc-100" })) })), columns.map((col) => (_jsxs(Th, { scope: "col", onClick: col.sortable && onSort ? () => onSort(col.key) : undefined, className: `text-left text-[var(--appkit-color-text)] ${col.sortable && onSort ? "cursor-pointer select-none hover:text-primary" : ""} ${COLUMN_PRIORITY_CLASS[resolveColumnPriority(col)]} ${col.className ?? ""}`, padding: "md", weight: "semibold", children: [col.header, col.sortable && sortKey === col.key && (_jsx(Span, { className: "ml-1", children: sortDir === "asc" ? "↑" : "↓" }))] }, col.key))), renderRowActions && _jsx(Th, { padding: "xs-3", scope: "col", className: "w-12" })] }) }), _jsx(Tbody, { children: isLoading ? (Array.from({ length: 5 }).map((_, i) => (_jsxs(Tr, { border: "default", children: [selectionEnabled && _jsx(Td, { padding: "xs-3", className: "w-10" }), columns.map((col) => (_jsx(Td, { padding: "md", className: COLUMN_PRIORITY_CLASS[resolveColumnPriority(col)], children: _jsx(Div, { className: "h-4 w-full animate-pulse bg-neutral-200", rounded: "default" }) }, col.key)))] }, i)))) : rows.length === 0 ? (_jsx(Tr, { children: _jsx(Td, { colSpan: columns.length + (selectionEnabled ? 1 : 0) + (renderRowActions ? 1 : 0), align: "center", color: "faint", paddingX: "md", paddingY: "md", children: _jsxs(Stack, { paddingY: "y-xl", gap: "md", align: "center", children: [_jsx(Text, { size: "sm", color: "muted", children: emptyLabel }), emptyAction] }) }) })) : (rows.map((row) => (_jsx(SelectableRow, { row: row, columns: columns, isSelected: selectedIds?.has(row.id) ?? false, onToggle: onToggleSelect, renderRowActions: renderRowActions, onRowClick: onRowClick, rowHref: typeof rowHrefTemplate === "function"
                                     ? rowHrefTemplate(row)
-                                    : rowHrefTemplate?.replace("{id}", encodeURIComponent(row.id)), selectionEnabled: selectionEnabled }, row.id)))) })] }) }), totalPages > 1 && onPageChange && (_jsx(Row, { className: "border-t border-neutral-200", padding: "inline", align: "center", justify: "end", gap: "sm", children: Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (_jsx(Button, { onClick: () => onPageChange(p), variant: p === currentPage ? "primary" : "ghost", size: "sm", className: `h-8 w-8 rounded text-[length:var(--appkit-text-xs)] font-medium transition ${p === currentPage ? "bg-neutral-900 text-white" : "text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:bg-surface-hover"}`, children: p }, p))) }))] }));
+                                    : rowHrefTemplate?.replace("{id}", encodeURIComponent(row.id)), selectionEnabled: selectionEnabled }, row.id)))) })] }) }), totalPages > 1 && onPageChange && (_jsx(Row, { className: "border-t border-neutral-200", padding: "inline", align: "center", justify: "end", gap: "sm", children: Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => (_jsx(Button, { onClick: () => onPageChange(p), variant: p === currentPage ? "primary" : "ghost", size: "sm", className: `h-8 w-8 rounded text-[length:var(--appkit-text-xs)] font-medium transition ${p === currentPage ? "bg-neutral-900 text-white" : "text-[var(--appkit-color-text-muted)] hover:bg-surface-hover"}`, children: p }, p))) }))] }));
 }

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" | "FRANCHISE" | "PART" | "BEY" | "BUNDLE" | "GROUP" | "SUBLISTING" | "EVENT" | "BLOG" | "REVIEW" | "STORE" | "USER" | "CAROUSEL" | "SECTION";
+export type OwnerQuickActionsResource = "PRODUCT" | "CATEGORY" | "BRAND" | "FRANCHISE" | "PART" | "BEY" | "FAQ" | "BUNDLE" | "GROUP" | "SUBLISTING" | "EVENT" | "BLOG" | "REVIEW" | "STORE" | "USER" | "CAROUSEL" | "SECTION";
 export interface OwnerQuickActionsProps {
     resource: OwnerQuickActionsResource;
     /** Where the pencil goes — that record's dashboard editor. */

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

@@ -66,6 +66,12 @@ const RESOURCE_LEAVES = {
      */
     PART: { bucket: "PART", edit: "edit", remove: "delete" },
     BEY: { bucket: "BEY", edit: "edit", remove: "delete" },
+    /*
+     * No `duplicate`: two identical questions in a help centre is a defect, not
+     * a shortcut — and unlike a product there is no per-copy field (price,
+     * stock, barcode) that makes a near-duplicate useful.
+     */
+    FAQ: { bucket: "FAQ", 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" },
@@ -183,7 +189,18 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
      * 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;
+    /*
+     * 🛑 `onMedia` ALONE now — `placement === "card"` no longer implies a dark
+     * backdrop and including it would be actively wrong.
+     *
+     * It used to, because every card pinned this toolbar over its hero
+     * PHOTOGRAPH, so "card" and "on media" were the same thing. The card
+     * toolbars now sit in normal flow at the foot of the card, on the card's own
+     * surface — where a dark scrim with white icons is a black rectangle on a
+     * white card. A caller that genuinely still renders over artwork passes
+     * `onMedia` explicitly, which is what that prop is for.
+     */
+    const onDark = onMedia;
     const neutralVariant = onDark ? "scrim" : "ghost";
     /*
      * Danger ink is dropped on a dark backdrop for the same reason: `danger`
@@ -192,7 +209,48 @@ export function OwnerQuickActions({ resource, editHref, onDelete, onClone, owner
      * actually communicated — colour was never the safeguard.
      */
     const dangerVariant = onDark ? "scrim" : "danger";
-    return (_jsxs(_Fragment, { children: [_jsxs(Row, { gap: "xs", align: "center", className: className, 
+    /*
+     * ── THE BOX ───────────────────────────────────────────────────────────────
+     *
+     * 🛑 THE TOOLBAR NOW CARRIES ITS OWN CONTAINER, AND THAT IS THE FIX FOR
+     * "they appear at random places".
+     *
+     * This component used to render a BARE `<Row>` and leave every decision
+     * about where it sat — and whether it read as a group at all — to each
+     * caller's `className`. Measured, the callers disagreed completely: the
+     * product grid pinned it `absolute right-2 top-14`, i.e. ON the product
+     * photo; the pre-order card landed it over its own "Reserve now" CTA; the
+     * category hero put it ABOVE the `<h1>`, overlapping the title. Three
+     * surfaces, three positions, none of them legible as a toolbar.
+     *
+     * A shared control cluster needs a shared container, or the next surface
+     * invents a fourth position. So the box is here, once:
+     *
+     *   - a real surface and border, so it reads as a discrete group of
+     *     controls rather than three icons floating on artwork;
+     *   - `rounded` + padding, so the icons have breathing room and the hit
+     *     targets do not touch;
+     *   - a shadow, which is what separates it from whatever it sits on when
+     *     the backdrop happens to be a similar tone.
+     *
+     * 🛑 `inline-flex`, never `w-full`. In normal flow this must shrink to its
+     * own content — a full-width bar would read as a section divider and would
+     * stretch across a card body it is only a corner of.
+     */
+    const boxClass = onDark
+        ? /*
+           * On media: a translucent dark scrim rather than a theme surface. The
+           * `frost` reasoning from Root Cause #67 — a theme-relative surface is a
+           * LIGHT background in every light theme, so a themed box on a dark hero
+           * photo is a white rectangle over the artwork.
+           */
+            "inline-flex rounded-[var(--appkit-radius-lg)] bg-black/55 backdrop-blur-sm p-[var(--appkit-space-1)] shadow-md"
+        : /*
+           * Off media: the real surface tokens, so it inverts with the theme
+           * instead of being a fixed near-white that disappears in dark mode.
+           */
+            "inline-flex rounded-[var(--appkit-radius-lg)] bg-[var(--appkit-color-surface-elevated)] border border-[var(--appkit-color-border)] p-[var(--appkit-space-1)] shadow-sm";
+    return (_jsxs(_Fragment, { children: [_jsxs(Row, { gap: "xs", align: "center", className: `${boxClass} ${className}`.trim(), 
                 /*
                  * Stops the click reaching an ancestor `<Link>` or the card's own
                  * `onClick`. Without it, pressing Edit on a card both navigates to the

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

@@ -8,7 +8,7 @@
  * 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 type RecordQuickActionResource = "CATEGORY" | "BRAND" | "BUNDLE" | "GROUP" | "EVENT" | "BLOG" | "FRANCHISE" | "SUBLISTING" | "PART" | "BEY" | "FAQ" | "PRODUCT";
 export interface RecordOwnerQuickActionsProps {
     resource: RecordQuickActionResource;
     /** The record's document id — what the endpoint and the editor are keyed on. */