@mohasinac/appkit 4.71.0 → 4.71.2

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

@@ -0,0 +1,434 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { z } from "zod";
+import { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { FormGroup } from "../../../ui/components/Form.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { IconButton } from "../../../ui/components/IconButton.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { MediaImage } from "../../../ui/components/MediaImage.js";
+import { QuickFormDrawer } from "../../shell/QuickFormDrawer.js";
+import { RichTextEditor } from "../../../ui/components/RichTextEditor.js";
+import { RichTextRenderer } from "../../../ui/rich-text/RichTextRenderer.js";
+import { Select } from "../../../ui/components/Select.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
+import { SURFACE_MAP } from "../../../ui/components/surface-tokens.js";
+import { Span, Text } from "../../../ui/components/Typography.js";
+import { TextLink } from "../../../ui/components/TextLink.js";
+import { Toggle } from "../../../ui/components/Toggle.js";
+import { useToastSafe } from "../../../ui/components/toast-context.js";
+import { FUNCTIONAL_SLOT_LABELS, NAV_SLOT_LABELS } from "../../../_internal/shared/features/dashboard/recent-entry.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { ADMIN_ROW_HREF_BY_RESOURCE } from "../../../_internal/shared/features/admin/row-widget-resources.js";
+import { ADMIN_ENDPOINTS, SUPPORT_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { apiClient } from "../../../http/index.js";
+import { FAQ_CATEGORY_LABELS } from "../../faq/schemas/firestore.js";
+import { TicketCategoryValues } from "../../support/schemas/firestore.js";
+import { supportTicketCreateSchema } from "../../support/schemas/ticket-create-form.js";
+import { ImageUpload } from "../../media/upload/ImageUpload.js";
+import { useMediaUpload } from "../../media/hooks/useMedia.js";
+import { ROW_COLUMNS, packBySpan } from "../../../utils/pack-by-span.js";
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
+import { humaniseFieldName } from "../../shell/entity-form.js";
+import { normalizeError } from "../../../errors/normalize.js";
+/**
+ * 9H's color picker — a small, curated subset of `SURFACE_MAP`, never a raw
+ * hex. The full map also has structural variants (`glass`, `interactive`,
+ * `elevated`, …) that don't mean anything as a card ACCENT.
+ */
+const CARD_COLOR_OPTIONS = [
+    "default",
+    "muted",
+    "success-surface",
+    "warning-surface",
+    "danger-surface",
+    "info-surface",
+];
+function resolveCardColor(color) {
+    return color && CARD_COLOR_OPTIONS.includes(color) ? color : undefined;
+}
+/**
+ * The real, closed `UI_BUTTON.variants` keys (`Button.tsx`) — hand-listed
+ * rather than imported, since that map is module-private inside a `"use
+ * client"` component this shared card-rendering module already imports
+ * `Button` from directly (so the KEYS are a safe hand-copy, not a new
+ * dependency).
+ *
+ * 🛑 THREE copies exist, not two — found by review 2026-11-03. Both
+ * `page-regions/[pageId]/route.ts` AND `user/profile/route.ts` spell the
+ * same 7 values out again in their own `cardElementSchema`'s `cta.variant`
+ * enum (neither can import `Button.tsx`). If a variant is ever added to
+ * `Button.tsx`, update all THREE, not "the other place."
+ */
+const CTA_VARIANT_OPTIONS = [
+    { value: "primary", label: "Primary" },
+    { value: "secondary", label: "Secondary" },
+    { value: "outline", label: "Outline" },
+    { value: "ghost", label: "Ghost" },
+    { value: "danger", label: "Danger" },
+    { value: "warning", label: "Warning" },
+    { value: "inverse", label: "Inverse (on dark/branded background)" },
+];
+/**
+ * The discrete, breakpoint-driven resize control — owner's instruction:
+ * "the resize should be in breakpoints not on stretching as per needs".
+ * Same 4 values `field-ui-meta.ts`'s `FieldRow` uses for form fields, picked
+ * from a `<Select>`, never a drag handle or a continuous slider.
+ */
+const SPAN_OPTIONS = [
+    { value: "full", label: "Full width" },
+    { value: "pair", label: "Half (2 per row)" },
+    { value: "third", label: "Third (3 per row)" },
+    { value: "quarter", label: "Quarter (4 per row)" },
+];
+/**
+ * Whole-card content-tag gate — first cut covers `governs: "listingType"`
+ * only (the common case: "hide this widget when collector-drop is
+ * disabled"). `categoryType`/`browsePage` tags are real, valid
+ * `ContentTag.governs` values too (the server schema accepts all three,
+ * `isContentVisible` handles all three) — just not reachable from this
+ * picker yet. A card can still be tagged with either via direct API use;
+ * widening this `<Select>` to a kind+value pair is a follow-up, not a
+ * blocker for the listing-type case this was built for.
+ */
+const CONTENT_TAG_OPTIONS = [
+    { value: "", label: "No tag — always visible" },
+    ...ALL_LISTING_TYPES.map((t) => ({ value: t, label: humaniseFieldName(t) })),
+];
+/** `<Select>` options for `functionalSlot.slotId`, derived from the closed `FunctionalSlotId` vocabulary — never hand-typed, so a new slot id can't silently go missing here. */
+const FUNCTIONAL_SLOT_OPTIONS = Object.entries(FUNCTIONAL_SLOT_LABELS).map(([value, label]) => ({ value, label }));
+/** `<Select>` options for `navSlot.slotId`, derived from the closed `NavSlotId` vocabulary — same reasoning as `FUNCTIONAL_SLOT_OPTIONS`. */
+const NAV_SLOT_OPTIONS = Object.entries(NAV_SLOT_LABELS).map(([value, label]) => ({ value, label }));
+const FAQ_CATEGORY_OPTIONS = Object.entries(FAQ_CATEGORY_LABELS).map(([value, label]) => ({ value, label }));
+/**
+ * No pre-built label map exists for `TicketCategoryValues` (unlike FAQ's own
+ * `FAQ_CATEGORY_LABELS`) — `/user/support/new` derives its labels from the
+ * schema's `annotate()` metadata via `buildSectionsFromSchema`, which this
+ * flat `QuickFieldDef[]` shape doesn't go through. `humaniseFieldName` turns
+ * each snake_case value into the same reading a human would pick by hand
+ * (`"order_issue"` → "Order issue").
+ */
+const TICKET_CATEGORY_OPTIONS = Object.values(TicketCategoryValues).map((value) => ({
+    value,
+    label: humaniseFieldName(value),
+}));
+const quickFaqSchema = z.object({
+    question: z.string().min(5, "Question must be at least 5 characters"),
+    answer: z.string().min(20, "Answer must be at least 20 characters"),
+    category: z.string().min(1, "Category is required"),
+});
+const FORM_WIDGET_REGISTRY = {
+    "quick-add-faq": {
+        title: "Quick add FAQ",
+        fields: [
+            { name: "question", label: "Question", type: "text", required: true },
+            { name: "answer", label: "Answer", type: "textarea", required: true },
+            { name: "category", label: "Category", type: "select", required: true, options: FAQ_CATEGORY_OPTIONS },
+        ],
+        schema: quickFaqSchema,
+        // `context` unused — FAQ creation has no owning store/record. Kept on
+        // the signature so every registry entry has the same shape.
+        submit: async (values) => {
+            await apiClient.post(ADMIN_ENDPOINTS.FAQS, values);
+        },
+    },
+    "quick-open-support-ticket": {
+        title: "Quick open support ticket",
+        fields: [
+            { name: "category", label: "Category", type: "select", required: true, options: TICKET_CATEGORY_OPTIONS },
+            { name: "subject", label: "Subject", type: "text", required: true },
+            { name: "description", label: "Description", type: "textarea", required: true },
+            {
+                name: "orderId",
+                label: "Order ID",
+                type: "text",
+                helperText: "Required when the category is an order issue.",
+            },
+        ],
+        schema: supportTicketCreateSchema,
+        // `context` unused — the route scopes the ticket to the signed-in
+        // caller (`auth: true`), not to any record this card could be on.
+        submit: async (values) => {
+            await apiClient.post(SUPPORT_ENDPOINTS.TICKETS, values);
+        },
+    },
+};
+/** `<Select>` options for `form.formId`, derived from the registry itself — never hand-typed, so a renamed/removed entry can't silently go missing here. */
+const FORM_WIDGET_OPTIONS = Object.entries(FORM_WIDGET_REGISTRY).map(([value, def]) => ({ value, label: def.title }));
+/**
+ * The `form` CardElement's render target — a button that opens a
+ * `QuickFormDrawer` built from the resolved registry entry. Unknown
+ * `formId`s (a stale pin from a removed registry entry) render the same
+ * honest "not editable here" text the placeholder used, rather than a
+ * broken button.
+ */
+function FormWidgetButton({ formId, label, context }) {
+    const [open, setOpen] = useState(false);
+    const [submitting, setSubmitting] = useState(false);
+    const toast = useToastSafe();
+    const widget = FORM_WIDGET_REGISTRY[formId];
+    if (!widget) {
+        return _jsxs(Text, { size: "sm", color: "muted", children: [label, " (form \u2014 unknown formId \u201C", formId, "\u201D)"] });
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "secondary", size: "sm", type: "button", onClick: () => setOpen(true), children: label }), _jsx(QuickFormDrawer, { isOpen: open, onClose: () => setOpen(false), title: widget.title, fields: widget.fields, schema: widget.schema, onSubmit: async (values) => {
+                    setSubmitting(true);
+                    try {
+                        await widget.submit(values, context);
+                        toast?.showToast(`${widget.title} — saved.`, "success");
+                        setOpen(false);
+                    }
+                    catch (err) {
+                        void normalizeError(err);
+                        toast?.showToast(`Couldn't save "${widget.title}" — please try again.`, "error");
+                    }
+                    finally {
+                        setSubmitting(false);
+                    }
+                }, isLoading: submitting })] }));
+}
+/**
+ * `text`/`image`/`richText` carry no REQUIRED label (free prose, and a
+ * media/rich-text block whose label is purely decorative) — falls back to
+ * "card" rather than rendering `undefined` in an aria-label.
+ */
+function elementDisplayLabel(el) {
+    if (!el)
+        return "card";
+    if (el.kind === "text" || el.kind === "image" || el.kind === "richText") {
+        return ("label" in el ? el.label : undefined) || "card";
+    }
+    return el.label;
+}
+export function DashboardCardView({ card, toggles, charts, settingsPreviews, onToggle, onRemove, onUpdate, editable = true, functionalSlots = {}, }) {
+    const [editing, setEditing] = useState(false);
+    const baseClass = "border border-[var(--appkit-color-border)] hover:border-[var(--appkit-color-primary)] transition-all";
+    const colorKey = resolveCardColor(card.color);
+    // 9H's composition UI builds elements one at a time (add text, remove any
+    // element) — no drag-and-drop, matching the plan's own stated constraint
+    // ("no drag-and-drop") for this whole card system.
+    const first = card.elements[0];
+    const isEditing = editable && editing;
+    return (_jsxs(Div, { rounded: "xl", paddingX: "x-lg", paddingY: "y-lg", shadow: "sm", surface: colorKey, className: `relative ${baseClass} ${colorKey ? "" : "bg-[var(--appkit-color-surface)]"}`, children: [card.title && !isEditing && (_jsx(Text, { size: "xs", weight: "semibold", className: "uppercase tracking-widest text-[var(--appkit-color-text-muted)] mb-2", children: card.title })), isEditing ? (_jsx(DashboardCardEditPanel, { card: card, onUpdate: onUpdate, onDone: () => setEditing(false) })) : card.elements.length <= 1 && first ? (_jsx(DashboardCardElementBody, { element: first, toggles: toggles, charts: charts, settingsPreviews: settingsPreviews, onToggle: onToggle, functionalSlots: functionalSlots })) : (
+            // Packed by span, breakpoint-driven — full width on mobile, N-up
+            // from `sm`/`lg` via `<FormGroup columns>` (the exact mechanism
+            // `build-sections.tsx`'s `packRows` already uses for form fields;
+            // see `pack-by-span.ts`'s own doc comment for why this is a
+            // deliberate, flagged second copy rather than a shared import).
+            // Elements with no stored span default to `"full"` — identical to
+            // the single vertical stack every card rendered before spans
+            // existed.
+            _jsx(Stack, { gap: "xs", children: packBySpan(card.elements.map((el, i) => ({ el, i })), ({ i }) => card.spans?.[String(i)]).map((row, rowIndex) => (_jsx(FormGroup, { columns: ROW_COLUMNS[card.spans?.[String(row[0].i)] ?? "full"], gap: "sm", children: row.map(({ el, i }) => (_jsx(DashboardCardElementBody, { element: el, toggles: toggles, charts: charts, settingsPreviews: settingsPreviews, onToggle: onToggle, functionalSlots: functionalSlots }, `${el.kind}-${i}`))) }, `row-${rowIndex}`))) })), editable && (_jsxs(Row, { gap: "xs", className: "absolute right-2 top-2 z-10", children: [_jsx(IconButton, { "aria-label": isEditing ? "Stop editing this card" : `Edit "${card.title ?? elementDisplayLabel(first)}"`, icon: _jsx(Icon, { name: isEditing ? "confirm" : "edit", size: "sm" }), size: "sm", variant: "ghost", rounded: "full", onClick: () => setEditing((e) => !e) }), _jsx(IconButton, { "aria-label": `Remove "${card.title ?? elementDisplayLabel(first)}"`, icon: _jsx(Icon, { name: "close", size: "sm" }), size: "sm", variant: "ghost", rounded: "full", onClick: onRemove })] }))] }));
+}
+function DashboardCardEditPanel({ card, onUpdate, onDone, }) {
+    const toast = useToastSafe();
+    const { upload } = useMediaUpload();
+    // Tracks which element indices have an upload in flight — NOT local-only
+    // state that would be lost on unmount: `onUpdate`/`onDone` both close over
+    // the parent's own `setCards`, which stays mounted while only this panel
+    // unmounts, so an upload that resolves after "Done" is clicked still
+    // lands correctly. This exists purely so "Done" can be disabled with
+    // visible feedback while an upload is running, rather than for
+    // correctness.
+    const [uploadingIndices, setUploadingIndices] = useState(new Set());
+    const isUploading = uploadingIndices.size > 0;
+    function updateElement(index, patch) {
+        const next = card.elements.map((el, i) => (i === index ? { ...el, ...patch } : el));
+        onUpdate({ elements: next });
+    }
+    /*
+     * 🛑 A card's `elements` array is server-validated `.min(1)` (the route's
+     * own Zod schema — confirmed by negative control when that schema was
+     * built). Letting the last element go to 0 here isn't caught until the
+     * debounced PATCH 400s 600ms later, with no rollback and no specific
+     * error — the edit just silently reverts on next load. Refusing the
+     * client-side action is the correct fix, not a server-side message.
+     */
+    function removeElement(index) {
+        if (card.elements.length <= 1) {
+            toast?.showToast("A card needs at least one element — add another before removing this one.", "info");
+            return;
+        }
+        onUpdate({ elements: card.elements.filter((_, i) => i !== index) });
+        // Reindexing: a span keyed to an index above the removed one would now
+        // point at the wrong element. Simplest correct fix is to drop every
+        // stored span and let elements fall back to "full" — a card composed
+        // by hand rarely has more than a few elements, so re-picking spans
+        // after a removal is a small cost for never silently mis-sizing an
+        // unrelated element.
+        if (card.spans)
+            onUpdate({ spans: {} });
+    }
+    function setElementSpan(index, span) {
+        const next = { ...(card.spans ?? {}) };
+        if (span === "full")
+            delete next[String(index)];
+        else
+            next[String(index)] = span;
+        onUpdate({ spans: next });
+    }
+    function addTextElement() {
+        onUpdate({ elements: [...card.elements, { kind: "text", body: "" }] });
+    }
+    function addRichTextElement() {
+        onUpdate({ elements: [...card.elements, { kind: "richText", html: "" }] });
+    }
+    function addCtaElement() {
+        onUpdate({ elements: [...card.elements, { kind: "cta", href: "", label: "" }] });
+    }
+    function addImageElement() {
+        // Empty placeholder first — the admin picks the file from the
+        // `ImageUpload` control that appears once this element exists, rather
+        // than a file picker opening as a side effect of this click.
+        onUpdate({ elements: [...card.elements, { kind: "image", mediaUrl: "", alt: "" }] });
+    }
+    function addFormElement() {
+        // A second registry entry now exists (2026-11-05) — widened from a
+        // direct add to picking the first option, with the real `<Select>`
+        // (FORM_WIDGET_OPTIONS below) shown in the per-element editor so the
+        // admin can change it after adding, same pattern `functionalSlot`
+        // already uses.
+        const firstId = Object.keys(FORM_WIDGET_REGISTRY)[0];
+        onUpdate({
+            elements: [
+                ...card.elements,
+                { kind: "form", formId: firstId, label: FORM_WIDGET_REGISTRY[firstId].title },
+            ],
+        });
+    }
+    function addFunctionalSlotElement() {
+        // A second `FunctionalSlotId` now exists (2026-11-05) — widened from a
+        // direct add to picking the first option, with the real `<Select>`
+        // (FUNCTIONAL_SLOT_OPTIONS below) shown in the per-element editor so the
+        // admin can change it after adding, same pattern `form`'s own "widen
+        // when a second entry exists" comment anticipated.
+        onUpdate({
+            elements: [
+                ...card.elements,
+                { kind: "functionalSlot", slotId: "pdp-offer-action", label: FUNCTIONAL_SLOT_LABELS["pdp-offer-action"] },
+            ],
+        });
+    }
+    function addNavSlotElement() {
+        onUpdate({
+            elements: [
+                ...card.elements,
+                { kind: "navSlot", slotId: "sidebar-admin", href: "", label: "" },
+            ],
+        });
+    }
+    return (_jsxs(Stack, { gap: "sm", padding: "r-xl", children: [_jsx(FieldInput, { name: `card-title-${card.id}`, label: "Title", value: card.title ?? "", onChange: (value) => onUpdate({ title: value || undefined }) }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "mb-1", children: "Color" }), _jsx(Row, { gap: "xs", children: CARD_COLOR_OPTIONS.map((key) => (_jsx(IconButton, { "aria-label": `Set card color to ${key}`, "aria-pressed": card.color === key, onClick: () => onUpdate({ color: card.color === key ? undefined : key }), rounded: "full", className: `h-6 w-6 min-h-0 min-w-0 border-2 ${SURFACE_MAP[key] || "bg-[var(--appkit-color-surface)]"} ${card.color === key ? "border-[var(--appkit-color-primary)]" : "border-[var(--appkit-color-border)]"}` }, key))) })] }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "mb-1", children: "Visible when listing type is on" }), _jsx(Select, { "aria-label": "Gate this card by listing type", options: CONTENT_TAG_OPTIONS, value: card.contentTags?.[0]?.value ?? "", onValueChange: (value) => onUpdate({ contentTags: value ? [{ governs: "listingType", value }] : undefined }) })] }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "mb-1", children: "Elements" }), _jsx(Stack, { gap: "sm", children: card.elements.map((el, i) => (_jsx(Div, { rounded: "md", border: "default", padding: "sm", children: _jsxs(Row, { gap: "xs", align: "start", justify: "between", children: [_jsxs(Div, { className: "flex-1", children: [el.kind === "text" ? (_jsx(FieldTextarea, { name: `card-element-${card.id}-${i}`, value: el.body, onChange: (value) => updateElement(i, { body: value }), rows: 2 })) : el.kind === "richText" ? (_jsx(RichTextEditor, { value: el.html, onChange: (value) => updateElement(i, { html: value }), placeholder: "Rich text\u2026", minHeightClassName: "min-h-[80px]" })) : el.kind === "image" ? (_jsxs(Stack, { gap: "xs", children: [_jsx(ImageUpload, { currentImage: el.mediaUrl, label: "Image", onUpload: async (file) => {
+                                                            setUploadingIndices((prev) => new Set(prev).add(i));
+                                                            try {
+                                                                return await upload(file, "dashboard-cards");
+                                                            }
+                                                            finally {
+                                                                setUploadingIndices((prev) => {
+                                                                    const next = new Set(prev);
+                                                                    next.delete(i);
+                                                                    return next;
+                                                                });
+                                                            }
+                                                        }, onChange: (url) => updateElement(i, { mediaUrl: url }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-alt`, label: "Alt text", value: el.alt, onChange: (value) => updateElement(i, { alt: value }) })] })) : el.kind === "cta" ? (_jsxs(Stack, { gap: "xs", children: [_jsx(FieldInput, { name: `card-element-${card.id}-${i}-label`, label: "Button label", value: el.label, onChange: (value) => updateElement(i, { label: value }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-href`, label: "Link", value: el.href, onChange: (value) => updateElement(i, { href: value }) }), _jsx(Select, { "aria-label": "Button style", options: CTA_VARIANT_OPTIONS, value: el.variant ?? "primary", onValueChange: (value) => updateElement(i, { variant: value }) })] })) : el.kind === "form" ? (
+                                            // The admin picks WHICH closed, pre-registered
+                                            // quick-create target and a label — never a submit
+                                            // target outside `FORM_WIDGET_REGISTRY`.
+                                            _jsxs(Stack, { gap: "xs", children: [_jsx(Select, { "aria-label": "Quick form", options: FORM_WIDGET_OPTIONS, value: el.formId, onValueChange: (value) => updateElement(i, {
+                                                            formId: value,
+                                                            label: FORM_WIDGET_REGISTRY[value]?.title ?? el.label,
+                                                        }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-label`, label: "Button label", value: el.label, onChange: (value) => updateElement(i, { label: value }) })] })) : el.kind === "functionalSlot" ? (
+                                            // The admin picks WHICH closed, pre-vetted slot and a
+                                            // label — never what it renders. What actually renders
+                                            // is entirely developer-wired (see `recent-entry.ts`'s
+                                            // `functionalSlot` doc comment); this panel has no way
+                                            // to point it at anything outside `FUNCTIONAL_SLOT_OPTIONS`.
+                                            _jsxs(Stack, { gap: "xs", children: [_jsx(Select, { "aria-label": "Functional slot", options: FUNCTIONAL_SLOT_OPTIONS, value: el.slotId, onValueChange: (value) => updateElement(i, {
+                                                            slotId: value,
+                                                            label: FUNCTIONAL_SLOT_LABELS[value],
+                                                        }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-label`, label: "Label", value: el.label, onChange: (value) => updateElement(i, { label: value }) })] })) : el.kind === "navSlot" ? (
+                                            // Inline-authored, same free-text fields as `cta` above
+                                            // (not a closed registry the way `functionalSlot`'s
+                                            // picker is) — `slotId` only picks WHICH chrome a
+                                            // bridge should go looking for this in; it never
+                                            // constrains `href`/`label`/`icon`.
+                                            _jsxs(Stack, { gap: "xs", children: [_jsx(Select, { "aria-label": "Nav slot", options: NAV_SLOT_OPTIONS, value: el.slotId, onValueChange: (value) => updateElement(i, { slotId: value }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-label`, label: "Label", value: el.label, onChange: (value) => updateElement(i, { label: value }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-href`, label: "Link", value: el.href, onChange: (value) => updateElement(i, { href: value }) }), _jsx(FieldInput, { name: `card-element-${card.id}-${i}-icon`, label: "Icon (optional emoji/glyph)", value: el.icon ?? "", onChange: (value) => updateElement(i, { icon: value || undefined }) })] })) : (_jsxs(Text, { size: "sm", color: "muted", children: [el.label, " (", el.kind, ")"] })), _jsxs(Row, { gap: "xs", align: "center", className: "mt-2", children: [_jsx(Text, { size: "xs", color: "muted", children: "Width:" }), _jsx(Select, { "aria-label": "Element width", options: SPAN_OPTIONS, value: card.spans?.[String(i)] ?? "full", onValueChange: (value) => setElementSpan(i, value) })] })] }), _jsx(IconButton, { "aria-label": "Remove this element", icon: _jsx(Icon, { name: "close", size: "sm" }), size: "sm", variant: "ghost", disabled: card.elements.length <= 1, onClick: () => removeElement(i) })] }) }, i))) }), _jsxs(Row, { gap: "xs", wrap: true, padding: "t-xs", children: [_jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addTextElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Text"] }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addRichTextElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Rich text"] }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addImageElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Image"] }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addCtaElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Button"] }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addFormElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Quick form"] }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addFunctionalSlotElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Functional slot"] }), _jsxs(Button, { variant: "ghost", size: "sm", type: "button", onClick: addNavSlotElement, children: [_jsx(Icon, { name: "create", size: "sm" }), " Nav slot"] })] })] }), isUploading && (_jsx(Text, { size: "xs", color: "muted", children: "Uploading image\u2026 this card will keep saving once it finishes." })), _jsx(Button, { variant: "primary", size: "sm", type: "button", onClick: onDone, disabled: isUploading, children: "Done" })] }));
+}
+function DashboardCardElementBody({ element, toggles, charts, settingsPreviews, onToggle, functionalSlots = {}, }) {
+    if (element.kind === "toggle") {
+        const live = toggles.find((t) => t.toggleId === element.toggleId);
+        return (_jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { weight: "semibold", className: "text-[var(--appkit-color-text)]", children: element.label }), _jsx(Toggle, { checked: live?.isOn ?? false, disabled: !live, ariaLabel: element.label, onChange: () => void onToggle(element.toggleId, element.label) })] }));
+    }
+    if (element.kind === "chart") {
+        const live = charts.find((c) => c.chartId === element.chartId);
+        return (_jsxs(Div, { children: [_jsx(Text, { size: "xs", color: "muted", children: element.label }), _jsx(Text, { size: "2xl", weight: "bold", numeric: true, className: "leading-none", children: live ? live.value : "—" })] }));
+    }
+    if (element.kind === "settingPreview") {
+        const live = settingsPreviews.find((s) => s.settingId === element.settingId);
+        return (_jsxs(TextLink, { variant: "bare", href: live?.href ?? "#", children: [_jsx(Text, { size: "xs", color: "muted", children: element.label }), _jsx(Text, { weight: "semibold", children: live ? live.value : "—" })] }));
+    }
+    if (element.kind === "text") {
+        return _jsx(Text, { size: "sm", children: element.body });
+    }
+    if (element.kind === "link" || element.kind === "page") {
+        return (_jsx(TextLink, { variant: "bare", href: element.href, children: _jsx(Text, { weight: "semibold", children: element.label }) }));
+    }
+    if (element.kind === "adminRow") {
+        const href = ADMIN_ROW_HREF_BY_RESOURCE[element.resource]?.(element.rowId);
+        return href ? (_jsx(TextLink, { variant: "bare", href: href, children: _jsx(Text, { weight: "semibold", children: element.label }) })) : (_jsx(Text, { weight: "semibold", children: element.label }));
+    }
+    if (element.kind === "functionalSlot") {
+        const live = functionalSlots[element.slotId];
+        return live ? (_jsx(_Fragment, { children: live })) : (_jsxs(Text, { size: "sm", color: "muted", children: [element.label, " (not available on this page)"] }));
+    }
+    if (element.kind === "productCard") {
+        return (_jsx(TextLink, { variant: "bare", href: element.href, children: _jsx(Text, { weight: "semibold", children: element.label }) }));
+    }
+    if (element.kind === "pdpSection") {
+        const href = `${String(ROUTES.PUBLIC.PRODUCT_DETAIL(element.productId))}#section-${element.sectionId}`;
+        return (_jsx(TextLink, { variant: "bare", href: href, children: _jsx(Text, { weight: "semibold", children: element.label }) }));
+    }
+    if (element.kind === "image") {
+        const img = (_jsx(MediaImage, { src: element.mediaUrl, alt: element.alt, size: "card", className: "w-full" }));
+        return element.href ? _jsx(TextLink, { variant: "bare", href: element.href, children: img }) : img;
+    }
+    if (element.kind === "richText") {
+        // `charts={false}` deliberately — this renderer has no chart data
+        // source wired in, so the chart-block feature must not be silently
+        // inherited from the shared `RichTextRenderer`.
+        return _jsx(RichTextRenderer, { html: element.html, charts: false });
+    }
+    if (element.kind === "cta") {
+        return (_jsx(Button, { variant: element.variant ?? "primary", asChild: true, children: _jsx(TextLink, { variant: "bare", href: element.href, children: element.label }) }));
+    }
+    if (element.kind === "navSlot") {
+        /*
+         * Inline render is identical in SHAPE to `cta` just above — `navSlot` is
+         * inline-authored content (`href`/`label`/`icon` carried on the element
+         * itself), not a live page-supplied slot like `functionalSlot` below.
+         * `slotId` has no bearing on how this renders HERE; it only tells a
+         * separate chrome-side bridge (see `recent-entry.ts`'s `NavSlotId` doc
+         * comment) which navbar/sidebar to also pin this into. A card holding a
+         * `navSlot` element still renders it right here in the page's own
+         * body-grid too — pinning is additive, not a replacement for the inline
+         * render.
+         *
+         * `icon` rendered the same way `AdminSidebar.tsx`'s own `NavLink`
+         * renders `item.icon` — a plain, admin-typed glyph/emoji `<Span>`, not
+         * `<Icon name=...>`: that component's `name` is a closed, compile-time
+         * `IconKey` registry, which an arbitrary admin-typed string can never
+         * safely satisfy.
+         */
+        return (_jsx(Button, { variant: "secondary", asChild: true, children: _jsxs(TextLink, { variant: "bare", href: element.href, children: [element.icon && _jsx(Span, { size: "base", className: "shrink-0 opacity-60", children: element.icon }), element.label] }) }));
+    }
+    /*
+     * 🛑 2026-11-04 — the gap this comment used to describe is closed.
+     * `FormWidgetButton` resolves `formId` against `FORM_WIDGET_REGISTRY`;
+     * the `context` field the old comment named as the missing piece was
+     * added to the `CardElement` `form` variant (`recent-entry.ts`) the same
+     * pass. See `FORM_WIDGET_REGISTRY`'s own doc comment for why it still
+     * has exactly one entry.
+     */
+    return _jsx(FormWidgetButton, { formId: element.formId, label: element.label, context: element.context });
+}

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

@@ -1,6 +1,7 @@
 import React from "react";
 import type { AttentionCounts } from "../../../_internal/server/features/dashboard/attention";
 import type { DashboardHubSection } from "../../../_internal/shared/features/dashboard/hub-sections";
+import type { DashboardCard } from "../../../_internal/shared/features/dashboard/recent-entry";
 /**
  * The dashboard hub — one component, two modes, zero copy of its own.
  *
@@ -79,5 +80,22 @@ export interface DashboardHubViewProps {
      * withheld rather than guessed.
      */
     showScreenCount?: boolean;
+    /**
+     * `"{portal}:hub"` — opts every card into per-user hide/show (Phase 4A).
+     * Omit to keep this component fully server-safe with no interactivity at
+     * all, same as before this phase; passing it mounts `HiddenHubCardGate`
+     * client leaves around each card, which does not force this component
+     * itself to become a client component (RSC composition, not a hook here).
+     */
+    hideScope?: string;
+    /**
+     * Stable, hand-chosen page-region id (Phase 12) — this one view is shared
+     * by four distinct routes (`/admin`, and the three `{portal}/sections/[section]`
+     * hubs), so every caller computes its own route-template-derived id rather
+     * than this component guessing one.
+     */
+    pageId: string;
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
 }
-export declare function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount, }: DashboardHubViewProps): React.JSX.Element;
+export declare function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount, hideScope, pageId, pageRegionCards, }: DashboardHubViewProps): React.JSX.Element;

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

@@ -6,6 +6,8 @@ import { Grid, Row, Stack } from "../../../ui/components/Layout.js";
 import { Heading, Text } from "../../../ui/components/Typography.js";
 import { Section } from "../../../ui/components/Semantic.js";
 import { TextLink } from "../../../ui/components/TextLink.js";
+import { HiddenHubCardGate, HiddenHubCardsRestoreBar } from "./HiddenHubCardGate.js";
+import { AdminComposableRegion } from "./AdminComposableRegion.js";
 /**
  * Sum of the counts inside a section, or `null` when it has none.
  *
@@ -30,12 +32,15 @@ function badgeFor(value) {
         return null;
     return (_jsx(Badge, { variant: "warning", "aria-label": `${value} waiting`, children: value }));
 }
-function CardGrid({ cards }) {
-    return (_jsx(Grid, { cols: "cards", gap: "md", children: cards.map((card) => (_jsxs(TextLink, { variant: "bare", href: card.href, rounded: "xl", layout: "flex-col", gap: "sm", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: "group border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0 w-full", children: [_jsx(Text, { weight: "semibold", className: "min-w-0 text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", children: card.label }), badgeFor(card.count)] }), card.description && (_jsx(Text, { size: "sm", className: "text-[var(--appkit-color-text-muted)] leading-relaxed", children: card.description })), card.meta && (_jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-faint)] mt-auto", children: card.meta }))] }, card.key))) }));
+function CardLink({ card }) {
+    return (_jsxs(TextLink, { variant: "bare", href: card.href, rounded: "xl", layout: "flex-col", gap: "sm", paddingX: "lg", paddingY: "lg", shadow: "hover-md", className: "group border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] hover:border-[var(--appkit-color-primary)] transition-all", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0 w-full", children: [_jsx(Text, { weight: "semibold", className: "min-w-0 text-[var(--appkit-color-text)] group-hover:text-[var(--appkit-color-primary)] transition-colors", children: card.label }), badgeFor(card.count)] }), card.description && (_jsx(Text, { size: "sm", className: "text-[var(--appkit-color-text-muted)] leading-relaxed", children: card.description })), card.meta && (_jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-faint)] mt-auto", children: card.meta }))] }));
 }
-export function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount = true, }) {
+function CardGrid({ cards, hideScope }) {
+    return (_jsxs(Stack, { gap: "sm", children: [hideScope && _jsx(HiddenHubCardsRestoreBar, { scope: hideScope, allCardKeys: cards.map((c) => c.key) }), _jsx(Grid, { cols: "cards", gap: "md", children: cards.map((card) => hideScope ? (_jsx(HiddenHubCardGate, { scope: hideScope, cardKey: card.key, children: _jsx(CardLink, { card: card }) }, card.key)) : (_jsx(CardLink, { card: card }, card.key))) })] }));
+}
+export function DashboardHubView({ title, description, mode, sections, sectionHrefs, counts, above, emptyMessage, showScreenCount = true, hideScope, pageId, pageRegionCards = [], }) {
     const hasAny = sections.some((section) => section.items.length > 0);
-    return (_jsxs(Stack, { gap: "lg", children: [title && (_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, size: "xl", weight: "semibold", color: "primary", children: title }), description && (_jsx(Text, { size: "sm", color: "muted", children: description }))] })), above, !hasAny && (_jsx(Alert, { variant: "info", title: "Nothing here yet", children: emptyMessage ??
+    return (_jsxs(Stack, { gap: "lg", children: [title && (_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, size: "xl", weight: "semibold", color: "primary", children: title }), description && (_jsx(Text, { size: "sm", color: "muted", children: description }))] })), above, _jsx(AdminComposableRegion, { pageId: pageId, initialCards: pageRegionCards }), !hasAny && (_jsx(Alert, { variant: "info", title: "Nothing here yet", children: emptyMessage ??
                     "Your permission set doesn't include access to any of these screens yet. Ask an admin for the permissions you need." })), hasAny && mode === "sections" && (_jsx(CardGrid, { cards: sections.map((section) => ({
                     key: section.slug,
                     href: sectionHrefs[section.slug] ?? "",
@@ -50,7 +55,7 @@ export function DashboardHubView({ title, description, mode, sections, sectionHr
                         ? `${section.items.length} ${section.items.length === 1 ? "screen" : "screens"}`
                         : undefined,
                     count: sectionTotal(section, counts),
-                })) })), hasAny &&
+                })), hideScope: hideScope ? `${hideScope}:sections` : undefined })), hasAny &&
                 mode === "screens" &&
                 sections.map((section) => (_jsxs(Section, { children: [_jsx(Heading, { level: 2, size: "lg", weight: "semibold", className: "mb-4 text-[var(--appkit-color-text)]", children: section.title }), _jsx(CardGrid, { cards: section.items.map((item) => ({
                                 key: item.id ?? item.href,
@@ -58,5 +63,5 @@ export function DashboardHubView({ title, description, mode, sections, sectionHr
                                 label: item.label,
                                 description: item.description,
                                 count: item.id ? (counts[item.id] ?? null) : null,
-                            })) })] }, section.slug))), hasAny && mode === "sections" && (_jsx(Div, { children: _jsx(Text, { size: "xs", color: "faint", children: "Every card above is a section of the sidebar. The screens inside one are the same screens, with a sentence each on what they are for." }) }))] }));
+                            })), hideScope: hideScope ? `${hideScope}:screens:${section.slug}` : undefined })] }, section.slug))), hasAny && mode === "sections" && (_jsx(Div, { children: _jsx(Text, { size: "xs", color: "faint", children: "Every card above is a section of the sidebar. The screens inside one are the same screens, with a sentence each on what they are for." }) }))] }));
 }

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

@@ -0,0 +1,90 @@
+import type { ActionConfirmation } from "../../../_internal/shared/actions/action-registry";
+import type { RecentEntryInput } from "../../../_internal/shared/features/dashboard/recent-entry";
+/**
+ * DashboardQuickJump — the dashboard-landing search + recent/default cards
+ * (Phase 9, overhaul brief). The owner's own example: reaching Maintenance
+ * mode took four clicks through Site Settings; this is a search box that
+ * finds it by what it DOES ("maintenance", "down", "closed") and a card that
+ * remembers it was used, with a live switch right on the card.
+ *
+ * 🛑 This is additive to the sidebar, never a replacement for it — the full,
+ * exhaustive nav tree is untouched (see CommandPalette, AdminSidebar,
+ * SellerSidebar, UserSidebar). This component is the fast, personalized path
+ * for when a user doesn't want to dig through the tree.
+ *
+ * Search ranks via the SAME `rankNavSearchResults` the ⌘K palette uses, so
+ * "maintenance" finds the same thing in both places — no second, drifting
+ * copy of what counts as a good match.
+ */
+export type QuickJumpDefaultCard = RecentEntryInput;
+export interface DashboardQuickJumpToggle {
+    /** Stable id — becomes `RecentEntry.toggleId` and the search result's dedupe key. */
+    toggleId: string;
+    label: string;
+    /** Live current state. Always read at render time by the caller — never cached here. */
+    isOn: boolean;
+    keywords?: string[];
+    /** Resolves once the toggle has actually been saved — mirrors CommandPalette's own toggle contract. */
+    onToggle: () => Promise<void>;
+    /** Search ranking tiebreaker — see `rankNavSearchResults`'s own doc comment. Absent means 0. */
+    priority?: number;
+    /**
+     * 9K — when set, flipping this toggle from a card/search result shows this
+     * confirm dialog first; `onToggle` only fires on confirm. Same
+     * `ActionConfirmation` shape Rule #7 requires for destructive `ActionDef`s.
+     */
+    confirmation?: ActionConfirmation;
+}
+export interface DashboardQuickJumpChart {
+    /** Stable id — becomes `RecentEntry.chartId`. */
+    chartId: string;
+    label: string;
+    /** Live current value. The caller computes this on every render from data it already holds — never cached here. */
+    value: string | number;
+    keywords?: string[];
+}
+export interface DashboardQuickJumpGroup {
+    title: string;
+    items: {
+        href: string;
+        label: string;
+        description?: string;
+        keywords?: string[];
+    }[];
+}
+/**
+ * Phase 10 ("widget descriptors") — a `settingPreview` search/card source.
+ * READ-ONLY by construction: there is no `onToggle`/write callback here at
+ * all, unlike `DashboardQuickJumpToggle`. See `recent-entry.ts`'s doc
+ * comment for why this stays separate from the write-capable toggle kind.
+ */
+export interface DashboardQuickJumpSettingPreview {
+    settingId: string;
+    label: string;
+    /** Live current value, read by the caller — never cached here. */
+    value: string;
+    href: string;
+    keywords?: string[];
+    /** Search ranking tiebreaker — see `rankNavSearchResults`'s own doc comment. Absent means 0. */
+    priority?: number;
+}
+export interface DashboardQuickJumpProps {
+    /** `"{portal}:hub"` — same scope convention as `useHiddenHubCards`. */
+    scope: string;
+    /** The portal's full nav — same groups the sidebar search and ⌘K palette already use. */
+    groups: DashboardQuickJumpGroup[];
+    /** Shown, up to 10, when there is no visit history yet for this scope. A curated per-portal starting point, never guessed from usage. */
+    defaultCards: QuickJumpDefaultCard[];
+    /** Common toggles this portal makes searchable + cardable. Omit on portals with none named (store/user, for now). */
+    toggles?: DashboardQuickJumpToggle[];
+    /** Live chart/stat values this portal makes searchable + cardable. */
+    charts?: DashboardQuickJumpChart[];
+    /**
+     * Phase 10 — read-only site-settings previews outside `TOGGLE_CATALOG`,
+     * searchable the same way toggles/charts are (small, static candidate
+     * set). Admin-only in practice; omit elsewhere.
+     */
+    settingsPreviews?: DashboardQuickJumpSettingPreview[];
+    placeholder?: string;
+}
+export declare function DashboardQuickJump({ scope, groups, defaultCards, toggles, charts, settingsPreviews, placeholder, }: DashboardQuickJumpProps): import("react").JSX.Element;