@mohasinac/appkit 4.59.0 → 4.60.1

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. */

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

@@ -12,9 +12,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  *     Event handlers cannot be passed to Client Component props.
  *
- * at render. `ProductOwnerQuickActions` records that this exact mistake took
- * down every `/products/[slug]` page in production, with an opaque digest per
- * handler.
+ * at render. The now-deleted product-specific wrapper recorded that this exact
+ * mistake took down every `/products/[slug]` page in production, with an
+ * opaque digest per handler.
  *
  * That is why ten detail views were passing `editHref` and nothing else: the
  * bin and the clone are rendered behind `{showDelete && …}` / `{showClone && …}`,
@@ -23,20 +23,26 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * ## 🛑 Why ONE wrapper and not one per resource
  *
- * `ProductOwnerQuickActions` is resource-specific because products are the one
- * collection a SELLER can also own, so its endpoints live under
- * `SELLER_ENDPOINTS` and its clone has a bespoke redirect to the copy's editor.
- * Everything here is admin-owned and differs only by three strings, so eight
- * near-identical files would trip the Duplication Framework's Rule of Three
- * immediately. One table, one component.
+ * There used to be TWO wrappers — this one and `ProductOwnerQuickActions` —
+ * because a product is the only collection a SELLER can also own, so it needs
+ * `SELLER_ENDPOINTS`, a clone that lands on the copy's editor, and a
+ * post-delete target that is not an admin list.
+ *
+ * 🛑 THOSE THREE DIFFERENCES ARE NOW ROWS IN THE TABLE, NOT A SECOND FILE.
+ * Every one of them is real and every one survives — but none needed a
+ * separate component to express, and having two meant two places for the box,
+ * the placement and the visibility rule to drift. That drift is exactly what
+ * shipped: five card types pinned the toolbar to four different corners, one
+ * of them on top of its own CTA, and the category hero rendered it over the
+ * `<h1>`. One table, one component, one position everywhere.
  *
  * ## Why the redirect lands on the ADMIN list
  *
  * You deleted the record from its own public page, so that page is now a 404 —
  * staying is not an option and the public index tells you nothing about whether
  * the delete worked. The admin list is where the absence is verifiable.
- * `ProductOwnerQuickActions` differs deliberately: a seller may delete a
- * product and has no admin list to land on.
+ * PRODUCT differs deliberately, through its own `afterDelete`: a seller may
+ * delete a product and has no admin list to land on.
  *
  * @tag domain:admin
  * @tag layer:components
@@ -44,7 +50,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import { useCallback } from "react";
 import { OwnerQuickActions } from "./OwnerQuickActions.js";
-import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { ADMIN_ENDPOINTS, SELLER_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
 const WIRING = {
     CATEGORY: {
@@ -97,6 +103,18 @@ const WIRING = {
         editHref: (id) => String(ROUTES.ADMIN.CATEGORIES_EDIT(id)),
         afterDelete: String(ROUTES.ADMIN.CATEGORIES),
     },
+    PRODUCT: {
+        endpoint: SELLER_ENDPOINTS.PRODUCT_BY_ID,
+        editHref: (id) => String(ROUTES.STORE.PRODUCTS_EDIT(id)),
+        afterDelete: String(ROUTES.STORE.PRODUCTS),
+        clone: SELLER_ENDPOINTS.PRODUCT_DUPLICATE,
+        afterClone: (newId) => String(ROUTES.STORE.PRODUCTS_EDIT(newId)),
+    },
+    FAQ: {
+        endpoint: ADMIN_ENDPOINTS.FAQ_BY_ID,
+        editHref: (id) => String(ROUTES.ADMIN.FAQS_EDIT(id)),
+        afterDelete: String(ROUTES.ADMIN.FAQS),
+    },
     SUBLISTING: {
         endpoint: ADMIN_ENDPOINTS.SUBLISTING_CATEGORY_BY_ID,
         editHref: (id) => String(ROUTES.ADMIN.SUBLISTING_CATEGORIES_EDIT(id)),
@@ -112,7 +130,7 @@ export function RecordOwnerQuickActions({ resource, recordId, recordLabel, owner
      * navigates away — so a swallowed failure is indistinguishable from "it
      * worked but the page did not move", and the obvious user response is to
      * press the button again. Returning early on `!res.ok` is the bug
-     * `ProductOwnerQuickActions` documents having had.
+     * the deleted product wrapper documented having had.
      */
     const handleDelete = useCallback(async () => {
         const res = await fetch(wiring.endpoint(recordId), { method: "DELETE" });
@@ -124,5 +142,34 @@ export function RecordOwnerQuickActions({ resource, recordId, recordLabel, owner
             window.location.assign(wiring.afterDelete);
         }
     }, [wiring, recordId]);
-    return (_jsx(OwnerQuickActions, { resource: resource, placement: placement, onMedia: onMedia, className: className, recordLabel: recordLabel, ownerId: ownerId, storeId: storeId, editHref: wiring.editHref(recordId), onDelete: handleDelete }));
+    /*
+     * Clone, for the resources whose table entry declares one.
+     *
+     * 🛑 Built UNCONDITIONALLY — the hook cannot be called behind an `if` — but
+     * passed to `OwnerQuickActions` only when `wiring.clone` exists, which is
+     * what makes the button absent rather than present-and-broken for the
+     * resources that cannot be copied.
+     *
+     * 🛑 THROWS on failure, like `handleDelete` above and for the same reason:
+     * `OwnerQuickActions` catches and toasts, so returning quietly is
+     * indistinguishable from "it worked but the page did not move", and the
+     * obvious user response is to press it again. The previous product-specific
+     * implementation returned early after showing its own toast, which is the
+     * double-toast path this avoids.
+     */
+    const handleClone = useCallback(async () => {
+        if (!wiring.clone)
+            return;
+        const res = await fetch(wiring.clone(recordId), { method: "POST" });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => null));
+            throw Object.assign(new Error("Clone failed"), { code: body?.code });
+        }
+        const json = (await res.json().catch(() => null));
+        const newId = json?.data?.id;
+        if (newId && wiring.afterClone && typeof window !== "undefined") {
+            window.location.assign(wiring.afterClone(newId));
+        }
+    }, [wiring, recordId]);
+    return (_jsx(OwnerQuickActions, { resource: resource, placement: placement, onMedia: onMedia, className: className, recordLabel: recordLabel, ownerId: ownerId, storeId: storeId, editHref: wiring.editHref(recordId), onDelete: handleDelete, onClone: wiring.clone ? handleClone : undefined }));
 }

package/dist/features/admin/components/analytics/AdminStatCard.d.ts

@@ -9,6 +9,40 @@ export interface AdminStatCardProps {
     /** Named preset or raw CSS gradient string */
     gradient?: keyof typeof GRADIENTS | string;
     className?: string;
+    /**
+     * Change against the previous comparable period, as a SIGNED percentage.
+     * `12.4` renders "▲ 12.4%", `-3` renders "▼ 3%", `0` renders "no change".
+     *
+     * 🛑 OMIT IT WHEN THERE IS NO COMPARISON, and never pass `0` to mean "we
+     * did not measure". A number here is a factual claim about a previous
+     * period; `0` claims the figure held steady, which is a different and
+     * stronger statement than silence. The whole reason a trend is worth adding
+     * is that it is trusted, and a fabricated flat line is the cheapest way to
+     * lose that.
+     */
+    trendPercent?: number;
+    /**
+     * What `trendPercent` is measured against — "vs last week", "vs yesterday".
+     *
+     * 🛑 REQUIRED WHENEVER `trendPercent` IS PASSED, enforced by the discriminated
+     * shape below rather than by a comment. "▲ 12.4%" alone is unreadable: up
+     * on what? The same number is excellent against last month and alarming
+     * against last hour.
+     */
+    trendLabel?: string;
+    /**
+     * 🛑 DOES A HIGHER NUMBER MEAN BETTER? Defaults to `true`, and the exception
+     * is the reason this prop exists: refunds, cancellations, failed payments
+     * and error counts all go UP when things go WRONG. Colouring those green
+     * because the arrow points up is a dashboard actively misinforming the
+     * person reading it.
+     */
+    higherIsBetter?: boolean;
+    /**
+     * Recent values, oldest first, for the sparkline. Needs at least two points
+     * to draw a line; fewer renders nothing rather than a dot or a flat stub.
+     */
+    series?: readonly number[];
 }
-export declare function AdminStatCard({ label, value, sub, icon, gradient, className, }: AdminStatCardProps): React.JSX.Element;
+export declare function AdminStatCard({ label, value, sub, icon, gradient, className, trendPercent, trendLabel, higherIsBetter, series, }: AdminStatCardProps): React.JSX.Element;
 export {};