@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/layout/NavbarLayout.js

@@ -3,9 +3,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef, useState, useEffect, useCallback } from "react";
 import Link from "next/link.js";
 import { ChevronDown } from "lucide-react";
-import { Div, Li, Nav, Row, Span, Ul } from "../../ui/index.js";
+import { Div, IconButton, Li, Nav, Row, Span, Ul } from "../../ui/index.js";
 import { NavbarChevron } from "../../ui/components/NavbarChevron.js";
 import { findActiveNavItem } from "../../_internal/client/features/layout/navActive.js";
+import { useHoldToOpen } from "./useHoldToOpen.js";
 const __O = {
     hidden: "overflow-hidden",
 };
@@ -15,8 +16,64 @@ function DefaultNavItem({ item, isActive, }) {
         : isActive
             ? "bg-primary-50 dark:bg-[var(--appkit-color-surface-elevated)] text-primary-800 dark:text-white font-semibold px-[var(--appkit-space-3)] border-b-2 border-primary-500 dark:border-secondary-400 rounded-none pb-[6px] transition-colors duration-150"
             : "text-[var(--appkit-color-text-muted)] hover:bg-surface-hover hover:text-zinc-950 dark:hover:text-white transition-colors duration-150 px-[var(--appkit-space-3)]";
-    const trigger = (_jsxs(Link, { href: item.href, "aria-current": isActive ? "page" : undefined, className: `flex items-center gap-[var(--appkit-space-1-5)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] rounded-lg font-medium transition-colors duration-150 whitespace-nowrap ${activeClasses}`, children: [item.icon, _jsx(Span, { children: item.label }), item.children && item.children.length > 0 && (_jsx(ChevronDown, { className: "w-3.5 h-3.5 shrink-0 opacity-70", "aria-hidden": "true" }))] }));
-    if (!item.children || item.children.length === 0)
+    const hasChildren = Boolean(item.children && item.children.length > 0);
+    /*
+     * Click-to-open state, which exists ONLY for the caret.
+     *
+     * 🛑 Hover and focus stay pure CSS below, and this does not replace them. The
+     * panel opens on `group-hover` / `group-focus-within` with no JS at all, which
+     * is what keeps it usable for a keyboard user on Tab and before hydration.
+     * This adds the third affordance that was genuinely missing: a pointer user
+     * who CLICKS the caret expecting a menu got a navigation instead, because the
+     * caret was inside the parent `<Link>`.
+     */
+    const [open, setOpen] = useState(false);
+    const wrapRef = useRef(null);
+    const panelId = `nav-panel-${item.href.replace(/[^a-z0-9]+/gi, "-")}`;
+    /*
+     * Close on outside click, on Escape, and whenever the route changes.
+     *
+     * The route-change close is the one that is easy to miss and the most
+     * annoying to live with: the panel's own links navigate, and without this the
+     * menu stays open over the page it just took you to. `isActive` is derived
+     * from `pathname` upstream, so the effect re-runs on every navigation.
+     */
+    useEffect(() => {
+        if (!open)
+            return;
+        const onDown = (e) => {
+            if (!wrapRef.current?.contains(e.target))
+                setOpen(false);
+        };
+        const onKey = (e) => {
+            if (e.key === "Escape")
+                setOpen(false);
+        };
+        document.addEventListener("mousedown", onDown);
+        document.addEventListener("keydown", onKey);
+        return () => {
+            document.removeEventListener("mousedown", onDown);
+            document.removeEventListener("keydown", onKey);
+        };
+    }, [open]);
+    useEffect(() => {
+        setOpen(false);
+    }, [item.href, isActive]);
+    /*
+     * Hold-to-open — the touch affordance, shared with the mobile bottom nav so
+     * one gesture is defined once. See `useHoldToOpen` for why the "did we hold"
+     * flag has to be a ref.
+     */
+    const holdHandlers = useHoldToOpen(() => setOpen(true), hasChildren);
+    const trigger = (_jsxs(Link, { href: item.href, "aria-current": isActive ? "page" : undefined, className: `flex items-center gap-[var(--appkit-space-1-5)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] rounded-lg font-medium transition-colors duration-150 whitespace-nowrap ${activeClasses}${hasChildren ? " select-none touch-manipulation" : ""}`, ...holdHandlers, children: [item.icon, _jsx(Span, { children: item.label })] }));
+    /*
+     * The explicit narrow, not just `hasChildren`. A boolean derived from
+     * `item.children` does not narrow the field itself, so the `.map` below
+     * cannot see that it is defined — this keeps both the readable guard above
+     * and a non-optional array to iterate.
+     */
+    const children = item.children ?? [];
+    if (!hasChildren || children.length === 0)
         return trigger;
     /*
      * 🛑 Hover/focus-within CSS, not React state, and the trigger is still a real
@@ -24,16 +81,24 @@ function DefaultNavItem({ item, isActive, }) {
      *
      * Two things this buys. The group stays usable without JS and without a
      * pointer — `focus-within` opens it on Tab, so a keyboard user reaches the
-     * children; and `aria-haspopup`/`aria-expanded` are deliberately NOT faked,
-     * because nothing here manages expanded state and announcing a state we do
-     * not track is worse than announcing none. The parent is a link whose
-     * children are also reachable from the page it leads to, which is the
-     * progressive-enhancement shape rather than a menu that traps people.
+     * children. And the parent is a real link whose children are also reachable
+     * from the page it leads to, which is the progressive-enhancement shape
+     * rather than a menu that traps people.
+     *
+     * 🛑 The CARET is now a separate button, and `aria-expanded` is real rather
+     * than faked. It used to live INSIDE the parent `<Link>`, so clicking the one
+     * control that looks like a disclosure navigated away instead of disclosing —
+     * the caret was announcing an affordance the markup did not have. It is the
+     * button that owns `aria-expanded`/`aria-controls`, because it is the only
+     * part that tracks state; the hover and focus paths still open the panel
+     * without touching it, which is why the attribute can be false while the
+     * panel is visible. That asymmetry is honest: the button reports what the
+     * BUTTON did, and a hover is not a disclosure a screen reader user performed.
      *
      * The `pt` on the panel is a hover bridge: without it the gap between the
      * trigger and the panel closes the menu as the pointer crosses it.
      */
-    return (_jsxs(Div, { className: "relative group", children: [trigger, _jsx(Div, { className: "absolute left-0 top-full z-20 hidden pt-[var(--appkit-space-1)] group-hover:block group-focus-within:block", children: _jsx(Div, { surface: "elevated", border: "default", rounded: "lg", shadow: "lg", padding: "xs", children: _jsx(Ul, { className: "min-w-[15rem] list-none", children: item.children.map((child) => (_jsx(Li, { children: _jsxs(Link, { href: child.href, className: "block rounded-md px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] hover:bg-surface-hover transition-colors duration-150", children: [_jsx(Span, { weight: "medium", children: child.label }), child.description && (_jsx(Span, { size: "xs", color: "muted", className: "block mt-[var(--appkit-space-0-5)] whitespace-normal", children: child.description }))] }) }, child.href))) }) }) })] }));
+    return (_jsxs(Div, { ref: wrapRef, className: "relative group", children: [_jsxs(Row, { align: "center", gap: "none", children: [trigger, _jsx(IconButton, { type: "button", size: "sm", variant: "ghost", rounded: "md", "aria-expanded": open, "aria-haspopup": "true", "aria-controls": panelId, "aria-label": `${item.label} menu`, onClick: () => setOpen((v) => !v), icon: _jsx(ChevronDown, { className: `w-3.5 h-3.5 shrink-0 opacity-70 transition-transform duration-150 ${open ? "rotate-180" : ""}`, "aria-hidden": "true" }) })] }), _jsx(Div, { id: panelId, className: `absolute left-0 top-full z-20 pt-[var(--appkit-space-1)] group-hover:block group-focus-within:block ${open ? "block" : "hidden"}`, children: _jsx(Div, { surface: "elevated", border: "default", rounded: "lg", shadow: "lg", padding: "xs", children: _jsx(Ul, { className: "min-w-[15rem] list-none", children: children.map((child) => (_jsx(Li, { children: _jsxs(Link, { href: child.href, className: "flex items-start gap-[var(--appkit-space-2)] rounded-md px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] hover:bg-surface-hover transition-colors duration-150", children: [child.icon && (_jsx(Span, { className: "flex-shrink-0 mt-[var(--appkit-space-0-5)]", "aria-hidden": "true", children: child.icon })), _jsxs(Span, { className: "block", children: [_jsx(Span, { weight: "medium", className: "block", children: child.label }), child.description && (_jsx(Span, { size: "xs", color: "muted", className: "block mt-[var(--appkit-space-0-5)] whitespace-normal", children: child.description }))] })] }) }, child.href))) }) }) })] }));
 }
 /**
  * NavbarLayout — generic horizontal navigation bar shell.
@@ -86,8 +151,20 @@ export function NavbarLayout({ items, activeHref, id = "main-navbar", ariaLabel
     // `findActiveNavItem` prefix-matches (`activeHref.startsWith(`${href}/`)`) and
     // resolves ties by LONGEST href, so a root entry like "/" cannot light up on
     // every page and a more specific entry always beats a shorter one.
-    const activeItem = findActiveNavItem(items, activeHref);
-    const isItemActive = (item) => activeItem?.href === item.href;
+    //
+    // 🛑 CHILDREN COUNT. A dropdown parent links to one page and stands for
+    // several — "Products" owns /auctions, /bundles and the rest — so resolving
+    // against top-level hrefs alone would mark NOTHING on four of the six pages
+    // the parent represents, which is the same lost-your-place bug described
+    // above, just one level down. Each child is resolved as a candidate carrying
+    // its parent's href, so the longest-match rule still decides and a child
+    // always beats its own shorter parent.
+    const candidates = items.flatMap((item) => [
+        { href: item.href, ownerHref: item.href },
+        ...(item.children ?? []).map((child) => ({ href: child.href, ownerHref: item.href })),
+    ]);
+    const activeItem = findActiveNavItem(candidates, activeHref);
+    const isItemActive = (item) => activeItem?.ownerHref === item.href;
     if (inline) {
         return (_jsx(Ul, { "aria-label": ariaLabel, className: "hidden xl:flex items-center justify-center gap-[var(--appkit-space-0-5)] xl:gap-[var(--appkit-space-1)] w-full", children: items.map((item) => (_jsx(Li, { children: renderItem ? (renderItem(item, isItemActive(item))) : (_jsx(DefaultNavItem, { item: item, isActive: isItemActive(item) })) }, item.href))) }));
     }

package/dist/features/layout/SideActionDock.d.ts

@@ -0,0 +1 @@
+export default function SideActionDock(): import("react").JSX.Element | null;

package/dist/features/layout/SideActionDock.js

@@ -0,0 +1,219 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * SideActionDock — the floating action dock that replaced the bottom bar.
+ *
+ * Reads the SAME `BottomActionsContext` the bar read, so all ~30 publishers
+ * (`useBottomActions`, `useFormBottomActions`, every `DataListingView` bulk
+ * bar) are untouched: only the presentation changed.
+ *
+ * ── Why a side dock and not a bar ──────────────────────────────────────────
+ *
+ * A full-width bar welded to an edge covers content the whole time it is up —
+ * the last row of a listing on mobile, and on desktop it either reads as a
+ * browser download bar at the bottom or steals the header's space at the top.
+ * A dock is a 56px button at rest and a panel only while it is being used.
+ *
+ * ── Three rules this encodes ───────────────────────────────────────────────
+ *
+ * 1. **It docks OPPOSITE the sidebar.** `SidebarLayout` docks to the hand-mode
+ *    side (`hand === "left" ? left-0 : right-0`), so the dock takes the other
+ *    edge and the two can never overlap — including while the sidebar is open,
+ *    which is exactly when a CTA hidden underneath it would be unreachable.
+ *
+ * 2. **It reveals only after the inline CTA has been seen and passed** — see
+ *    `useCtaReveal`. A page with no CTA anchor shows it at once, which is what
+ *    every bulk-action screen needs.
+ *
+ * 3. **Bulk mode ignores the reveal gate.** A selection is a state the user
+ *    just entered deliberately; making them scroll to act on it would be a
+ *    puzzle, not an affordance.
+ *
+ * 🛑 It is NOT part of the `BottomChrome` tier any more and must not be put
+ * back into it. The tier exists so bars can stack without overlapping and
+ * publish one height; a dock that floats beside the content reserves no height
+ * and belongs to no tier. Rendering it inside `BottomChrome` would re-add its
+ * height to `--bottom-chrome-height` and push the footer down by a phantom bar.
+ */
+import { useEffect, useId, useRef, useState } from "react";
+import { ChevronDown, ChevronUp, Check, X } from "lucide-react";
+import { useBottomActionsContext } from "./BottomActionsContext.js";
+import { useClickOutside } from "../../react/index.js";
+import { useHandMode } from "../../_internal/client/hand-mode/index.js";
+import { useCtaReveal } from "./useCtaReveal.js";
+import { ActionRow, Div, IconButton, Row, Span, Stack, Text, Button } from "../../ui/index.js";
+const PANEL_SURFACE = "bg-[color-mix(in_srgb,var(--appkit-color-bg)_94%,transparent)] backdrop-blur-md border border-[var(--appkit-color-border)]";
+const FLEX_CENTER = "flex items-center justify-center";
+const CLS_COUNT_BADGE = "bg-error-solid text-error-on-solid";
+/**
+ * How many actions fit on one line before the row splits in two.
+ *
+ * 🛑 ROW COUNT is a function of `pageActions.length` and NOTHING else — never
+ * of validation state, and never of measured width. In this app LABELS ARE
+ * STATE ("Add to Cart" → "Adding…", "Buy Now" → "Out of Stock"), so a layout
+ * that re-flowed on width would shift the controls under the user's thumb at
+ * the exact moment they committed to a tap.
+ */
+const SINGLE_ROW_MAX_ACTIONS = 2;
+function ActionButtons({ actions, dispatchAction, }) {
+    return (_jsx(_Fragment, { children: actions.map((action) => {
+            const isIconOnly = !action.label;
+            /*
+             * Width is ActionRow's job, not this component's — every action is
+             * sized from its own label by `.appkit-action-row__group > *`.
+             *
+             * 🛑 Never add `flex-1`, `flex-shrink-0`, `basis-*`, `w-*`, `h-*`,
+             * `truncate` or `leading-none` below. Both tailwind configs set
+             * `important: true`, so any of them beats ActionRow's CSS and silently
+             * reverts this to the squeezed behaviour with no visible error — a
+             * 44px stub reading "Ba" beside a full-width "Continue to payment".
+             */
+            return (_jsxs(Button, { type: "button", variant: action.variant ?? "primary", size: "sm", isLoading: action.loading, disabled: action.disabled, onClick: () => dispatchAction(action.id), className: [
+                    "relative",
+                    isIconOnly ? "appkit-action-row__icon-only justify-center" : "",
+                ]
+                    .filter(Boolean)
+                    .join(" "), children: [action.icon && (_jsx(Span, { className: ["flex-shrink-0", action.label ? "mr-1.5" : ""].join(" "), "aria-hidden": "true", children: action.icon })), action.label && _jsx(Span, { children: action.label }), action.badge !== undefined && (_jsx(Span, { className: `absolute -top-1.5 -right-1.5 min-w-[18px] h-[18px] ${CLS_COUNT_BADGE} text-[10px] ${FLEX_CENTER} px-[var(--appkit-space-1)] pointer-events-none select-none`, rounded: "full", weight: "bold", "aria-hidden": "true", children: action.badge }))] }, action.id));
+        }) }));
+}
+/**
+ * Lays a page's actions out across one or two lines. The LAST action is the
+ * primary — `useFormBottomActions` appends submit last and the checkout bars
+ * build `[back, primary]`, so this holds for every producer.
+ */
+function PageActionsRow({ pageActions, dispatchAction, }) {
+    if (pageActions.length === 0)
+        return null;
+    if (pageActions.length <= SINGLE_ROW_MAX_ACTIONS) {
+        return (_jsx(ActionRow, { children: _jsx(ActionButtons, { actions: pageActions, dispatchAction: dispatchAction }) }));
+    }
+    const secondaries = pageActions.slice(0, -1);
+    const primary = pageActions[pageActions.length - 1];
+    return (_jsxs(Div, { className: "flex w-full flex-col gap-[var(--appkit-space-2)]", children: [_jsx(ActionRow, { children: _jsx(ActionButtons, { actions: secondaries, dispatchAction: dispatchAction }) }), _jsx(ActionRow, { children: _jsx(ActionButtons, { actions: [primary], dispatchAction: dispatchAction }) })] }));
+}
+/** The bulk-mode action list — one tap picks AND runs. */
+function BulkActionList({ bulkActions, selectedActionId, onSelect, }) {
+    return (_jsx(Div, { role: "listbox", "aria-label": "Bulk actions", className: "w-full", children: bulkActions.map((action, i) => {
+            const isSelected = action.id === selectedActionId;
+            return (_jsxs(Button, { role: "option", "aria-selected": isSelected, type: "button", variant: "ghost", disabled: action.disabled || action.loading, onClick: () => onSelect(action.id), className: [
+                    "w-full flex items-center gap-[var(--appkit-space-3)] px-[var(--appkit-space-3)] py-[var(--appkit-space-2-5)] text-left text-[length:var(--appkit-text-sm)] font-medium transition-colors rounded-md",
+                    i > 0 ? "border-t border-[var(--appkit-color-border-subtle)]" : "",
+                    isSelected ? "bg-[var(--appkit-color-surface-input)]" : "",
+                    action.variant === "danger"
+                        ? "text-error hover:bg-error-surface"
+                        : "text-[var(--appkit-color-text)] hover:bg-surface-hover",
+                    action.disabled || action.loading ? "opacity-50 cursor-not-allowed" : "",
+                ]
+                    .filter(Boolean)
+                    .join(" "), children: [action.icon && (_jsx(Span, { className: `flex-shrink-0 w-5 h-5 ${FLEX_CENTER}`, "aria-hidden": "true", children: action.icon })), _jsx(Span, { className: "flex-1 truncate", children: action.label }), isSelected && (_jsx(Check, { className: "w-4 h-4 flex-shrink-0 text-primary-600 dark:text-primary-400", "aria-hidden": "true" }))] }, action.id));
+        }) }));
+}
+export default function SideActionDock() {
+    const { state, actionCallbacksRef, bulkCallbacksRef, bulkClearRef } = useBottomActionsContext();
+    const { hand } = useHandMode();
+    const [expanded, setExpanded] = useState(false);
+    const [infoOpen, setInfoOpen] = useState(false);
+    const [selectedActionId, setSelectedActionId] = useState(null);
+    const containerRef = useRef(null);
+    const infoPanelId = useId();
+    useClickOutside(containerRef, () => {
+        setExpanded(false);
+        setInfoOpen(false);
+    });
+    const { actions, bulk, infoLabel, secondaryLabel, infoPanel, infoOpenSignal, ctaAnchorId } = state;
+    const isBulkMode = !!(bulk && bulk.selectedCount > 0);
+    const hasInfoPanel = infoPanel != null && !isBulkMode;
+    const bulkActions = bulk?.actions ?? [];
+    const pageActions = actions;
+    const hasContent = (isBulkMode ? bulkActions.length > 0 || !!bulk : pageActions.length > 0) ||
+        !!infoLabel ||
+        !!secondaryLabel;
+    // Rule 3 — a selection is its own reveal.
+    const revealed = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId) || isBulkMode;
+    const isVisible = hasContent && revealed;
+    // Rule 1 — opposite the sidebar, which docks to the hand-mode side.
+    const dockSideClass = hand === "left" ? "right-0" : "left-0";
+    const panelAlignClass = hand === "left" ? "items-end" : "items-start";
+    // Collapse when the dock goes away, or the next page inherits an open panel.
+    useEffect(() => {
+        if (!isVisible) {
+            setExpanded(false);
+            setInfoOpen(false);
+        }
+    }, [isVisible]);
+    useEffect(() => {
+        if (!hasInfoPanel)
+            setInfoOpen(false);
+    }, [hasInfoPanel]);
+    /*
+     * Force-open on a bumped signal — a failed form submit, today. Depends on
+     * the counter alone, so a re-render with the same value never re-opens what
+     * the user has since collapsed. The dock must EXPAND as well: a failed save
+     * whose error sheet opens inside a collapsed dock is a message nobody sees.
+     */
+    const lastSignalRef = useRef(undefined);
+    useEffect(() => {
+        if (infoOpenSignal == null)
+            return;
+        if (lastSignalRef.current === infoOpenSignal)
+            return;
+        lastSignalRef.current = infoOpenSignal;
+        setExpanded(true);
+        setInfoOpen(true);
+    }, [infoOpenSignal]);
+    useEffect(() => {
+        if (!isBulkMode) {
+            setSelectedActionId(null);
+            return;
+        }
+        setSelectedActionId((prev) => {
+            const ids = bulkActions.map((a) => a.id);
+            if (prev && ids.includes(prev))
+                return prev;
+            return ids[0] ?? null;
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isBulkMode, bulkActions.map((a) => a.id).join(",")]);
+    const selectedAction = bulkActions.find((a) => a.id === selectedActionId);
+    const dispatchAction = (id) => {
+        actionCallbacksRef.current.get(id)?.();
+        setExpanded(false);
+    };
+    const dispatchBulkClear = () => {
+        bulkClearRef.current?.();
+        setExpanded(false);
+    };
+    const handleApply = () => {
+        if (!selectedActionId)
+            return;
+        bulkCallbacksRef.current.get(selectedActionId)?.();
+        setExpanded(false);
+    };
+    if (!isVisible)
+        return null;
+    /*
+     * The resting affordance. In bulk mode it counts the selection, which is the
+     * one number a user in that state is tracking; otherwise it carries the
+     * PRIMARY action's icon, so the dock looks like what it does rather than like
+     * a generic "more" button.
+     */
+    const primaryAction = pageActions[pageActions.length - 1];
+    const fabBadge = isBulkMode ? bulk?.selectedCount : undefined;
+    const fabLabel = isBulkMode
+        ? `${bulk?.selectedCount ?? 0} selected — bulk actions`
+        : (primaryAction?.label ?? infoLabel ?? "Page actions");
+    return (_jsxs(Div, { ref: containerRef, role: "toolbar", "aria-label": isBulkMode ? "Bulk actions" : "Page actions", className: [
+            "fixed z-[var(--appkit-z-overlay)] pointer-events-auto flex flex-col",
+            panelAlignClass,
+            dockSideClass,
+            // Clears the whole bottom tier, so it never lands on the mobile tab bar
+            // or on a pagination bar — the same sum every other floating control
+            // reads (see CSS Variable Reference → "The bottom edge is three tiers").
+            "bottom-[calc(var(--keyboard-inset-height,0px)+var(--bottom-nav-height,4rem)+var(--bottom-chrome-height,0px)+var(--appkit-space-4))]",
+            "px-[var(--appkit-space-3)] gap-[var(--appkit-space-2)]",
+        ].join(" "), "data-section": "side-action-dock", children: [expanded && (_jsx(Div, { surface: "elevated", rounded: "xl", shadow: "lg", padding: "sm", className: `${PANEL_SURFACE} w-[min(20rem,calc(100vw-2rem))] max-h-[70vh] overflow-y-auto`, children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "truncate", children: isBulkMode
+                                        ? bulk?.noun
+                                            ? `${bulk.selectedCount} ${bulk.noun}`
+                                            : `${bulk?.selectedCount ?? 0} selected`
+                                        : (secondaryLabel ?? infoLabel ?? "Actions") }), _jsx(IconButton, { size: "sm", variant: "ghost", "aria-label": "Close actions", onClick: () => setExpanded(false), icon: _jsx(X, { className: "w-4 h-4", "aria-hidden": "true" }) })] }), !isBulkMode && secondaryLabel && infoLabel && (_jsx(Text, { size: "xs", color: "muted", className: "leading-5", children: infoLabel })), hasInfoPanel && (_jsxs(_Fragment, { children: [_jsxs(Button, { type: "button", variant: "ghost", onClick: () => setInfoOpen((o) => !o), "aria-expanded": infoOpen, "aria-controls": infoPanelId, className: "w-full flex items-center justify-between gap-[var(--appkit-space-2)] rounded-md px-[var(--appkit-space-2)] py-[var(--appkit-space-1)] min-h-0", children: [_jsx(Text, { as: "span", size: "xs", color: "muted", children: infoOpen ? "Hide details" : "Details" }), infoOpen ? (_jsx(ChevronDown, { className: "w-4 h-4 text-zinc-400", "aria-hidden": "true" })) : (_jsx(ChevronUp, { className: "w-4 h-4 text-zinc-400", "aria-hidden": "true" }))] }), infoOpen && (_jsx(Div, { id: infoPanelId, className: "max-h-[40vh]", overflow: "y-auto", children: infoPanel }))] })), isBulkMode && bulk ? (_jsxs(Stack, { gap: "sm", children: [_jsx(BulkActionList, { bulkActions: bulkActions, selectedActionId: selectedActionId, onSelect: setSelectedActionId }), _jsxs(ActionRow, { children: [_jsxs(Button, { type: "button", variant: "ghost", size: "sm", onClick: dispatchBulkClear, children: [_jsx(X, { className: "w-3.5 h-3.5 mr-1.5 flex-shrink-0", "aria-hidden": "true" }), _jsx(Span, { children: "Clear" })] }), _jsx(Button, { type: "button", variant: selectedAction?.variant ?? "primary", size: "sm", isLoading: selectedAction?.loading, disabled: !selectedActionId || selectedAction?.disabled || selectedAction?.loading, onClick: handleApply, children: _jsx(Span, { children: "Apply" }) })] })] })) : (_jsx(PageActionsRow, { pageActions: pageActions, dispatchAction: dispatchAction }))] }) })), _jsxs(Button, { type: "button", variant: isBulkMode ? "primary" : (primaryAction?.variant ?? "primary"), rounded: "full", "aria-expanded": expanded, "aria-label": fabLabel, onClick: () => setExpanded((o) => !o), className: "relative shadow-lg h-14 min-h-0 px-[var(--appkit-space-5)]", children: [primaryAction?.icon && !isBulkMode && (_jsx(Span, { className: "flex-shrink-0 mr-1.5", "aria-hidden": "true", children: primaryAction.icon })), _jsx(Span, { className: "truncate max-w-[9rem]", children: isBulkMode ? "Bulk actions" : (primaryAction?.label ?? "Actions") }), fabBadge !== undefined && fabBadge > 0 && (_jsx(Span, { className: `absolute -top-1.5 -right-1.5 min-w-[20px] h-[20px] ${CLS_COUNT_BADGE} text-[10px] ${FLEX_CENTER} px-[var(--appkit-space-1)] pointer-events-none select-none`, rounded: "full", weight: "bold", "aria-hidden": "true", children: fabBadge }))] })] }));
+}

package/dist/features/layout/TitleBarLayout.js

@@ -64,7 +64,7 @@ export function TitleBarLayout({ onToggleSidebar, sidebarOpen, onSearchToggle, s
     _jsxs(Row, { gap: "xs", reverse: "hand", className: "hidden lg:flex", children: [loginHref && (_jsx(Link, { href: loginHref, className: "px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium text-[var(--appkit-color-text-muted)] hover:text-primary-700 dark:hover:text-secondary-400 transition-colors rounded-lg hover:bg-primary-surface", children: "Sign in" })), registerHref && (_jsx(Link, { href: registerHref, className: "px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-semibold rounded-lg bg-primary text-white hover:bg-primary/90 transition-colors btn-glow shadow-sm", children: "Register" }))] })) : null;
     const hasTb2 = !!(notificationsEl || messagesEl || wishlistEl || cartEl || profileEl);
     // ── Render ───────────────────────────────────────────────────────────────────
-    return (_jsxs(BlockHeader, { id: id, className: `sticky top-0 z-50 bg-[var(--appkit-color-bg)]/95 backdrop-blur-md border-b border-[var(--appkit-color-border-subtle)] shadow-sm ${className}`, children: [promoStripText && (_jsx(Section, { color: "inverse", tone: "accent-banner", className: "text-[length:var(--appkit-text-xs)] text-center font-medium", padding: "y-2xs", children: promoStripText })), _jsxs(Div, { paddingX: "x-page", className: "container mx-auto max-w-[1920px]", children: [_jsxs(Row, { justify: "between", gap: "none", reverse: "hand", className: "relative h-14", children: [_jsx(Row, { gap: "3", children: _jsxs(Link, { href: logoHref, "aria-label": brandName, className: "flex items-center gap-[var(--appkit-space-2)] transition-opacity hover:opacity-80", children: [_jsx(Div, { className: "flex md:hidden", children: _jsx(SiteMark, { title: brandShortName ?? brandName, size: "sm" }) }), _jsx(SiteLogo, { title: brandName, size: "md" })] }) }), _jsx(Row, { className: "hidden md:flex absolute inset-y-0 left-1/2 -translate-x-1/2", align: "center", children: _jsx(Link, { href: logoHref, "aria-label": brandName, className: "flex items-center transition-opacity hover:opacity-80", children: _jsx(SiteMark, { src: siteLogoUrl, title: brandName, size: "lg" }) }) }), _jsxs(Row, { gap: "xs", reverse: "hand", children: [devSlot, navSlot, compareEl, notificationSlot, notificationsEl && _jsx(Div, { className: "hidden lg:flex", children: notificationsEl }), messagesEl && _jsx(Div, { className: "hidden lg:flex", children: messagesEl }), wishlistEl && _jsx(Div, { className: "hidden lg:flex", children: wishlistEl }), cartEl && _jsx(Div, { className: "hidden lg:flex", children: cartEl }), user
+    return (_jsxs(BlockHeader, { id: id, className: `sticky top-0 z-50 bg-[var(--appkit-color-bg)]/95 backdrop-blur-md border-b border-[var(--appkit-color-border-subtle)] shadow-sm ${className}`, children: [promoStripText && (_jsx(Section, { color: "inverse", tone: "accent-banner", className: "text-[length:var(--appkit-text-xs)] text-center font-medium", padding: "y-2xs", children: promoStripText })), _jsxs(Div, { paddingX: "x-page", className: "container mx-auto max-w-[1920px]", children: [_jsxs(Row, { gap: "none", reverse: "hand", className: "relative h-14", children: [_jsx(Row, { gap: "3", reverse: "hand", className: "flex-1", children: _jsx(Link, { href: logoHref, "aria-label": brandName, className: "flex items-center gap-[var(--appkit-space-2)] transition-opacity hover:opacity-80", children: _jsx(SiteLogo, { title: brandName, size: "md" }) }) }), _jsx(Row, { className: "flex flex-none", align: "center", children: _jsx(Link, { href: logoHref, "aria-label": brandName, className: "flex items-center transition-opacity hover:opacity-80", children: _jsx(SiteMark, { src: siteLogoUrl, title: brandShortName ?? brandName, size: "lg" }) }) }), _jsxs(Row, { gap: "xs", reverse: "hand", justify: "end", className: "flex-1", children: [devSlot, navSlot, compareEl, notificationSlot, notificationsEl && _jsx(Div, { className: "hidden lg:flex", children: notificationsEl }), messagesEl && _jsx(Div, { className: "hidden lg:flex", children: messagesEl }), wishlistEl && _jsx(Div, { className: "hidden lg:flex", children: wishlistEl }), cartEl && _jsx(Div, { className: "hidden lg:flex", children: cartEl }), user
                                         ? profileEl && _jsx(Div, { className: "hidden lg:flex", children: profileEl })
                                         : authButtonsEl ?? (profileEl && _jsx(Div, { className: "hidden lg:flex", children: profileEl })), searchBtn, _jsx(Div, { className: "hidden sm:flex", children: promotionsEl }), themeBtn, hamburgerBtn] })] }), hasTb2 && (
                     // `justify="end"` is CORRECT alongside `reverse="hand"` — do not

package/dist/features/layout/cta-anchor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CTA anchor — the inline Buy button a floating action dock hides behind.
+ *
+ * A page marks its own primary CTA with `ctaAnchorProps()`; `SideActionDock`
+ * finds it by attribute and reveals itself only once that element has been
+ * SEEN and then scrolled out of view.
+ *
+ * 🛑 An ATTRIBUTE, not a ref passed through the context, on purpose. The dock
+ * is mounted once by `AppLayoutShell`, several levels above every page that
+ * registers actions, and ~30 call sites publish into that context — threading a
+ * ref through all of them to reach a gate that only a handful of detail pages
+ * need would make the common case pay for the rare one. An attribute lets a
+ * page opt in with one prop spread and lets every other page say nothing.
+ *
+ * A page with NO anchor reveals the dock immediately. That is the honest
+ * default: an admin bulk bar has no Buy button to scroll past, and a dock that
+ * waited for an element that will never exist would never appear at all.
+ */
+export declare const CTA_ANCHOR_ATTR = "data-cta-anchor";
+/**
+ * Spread onto the element wrapping a page's inline primary CTA.
+ *
+ * @example
+ * <Stack gap="sm" {...ctaAnchorProps()}>
+ *   <Button>Buy Now</Button>
+ *   <Button>Add to Cart</Button>
+ * </Stack>
+ */
+export declare function ctaAnchorProps(): {
+    [CTA_ANCHOR_ATTR]: "true";
+};

package/dist/features/layout/cta-anchor.js

@@ -0,0 +1,31 @@
+/**
+ * CTA anchor — the inline Buy button a floating action dock hides behind.
+ *
+ * A page marks its own primary CTA with `ctaAnchorProps()`; `SideActionDock`
+ * finds it by attribute and reveals itself only once that element has been
+ * SEEN and then scrolled out of view.
+ *
+ * 🛑 An ATTRIBUTE, not a ref passed through the context, on purpose. The dock
+ * is mounted once by `AppLayoutShell`, several levels above every page that
+ * registers actions, and ~30 call sites publish into that context — threading a
+ * ref through all of them to reach a gate that only a handful of detail pages
+ * need would make the common case pay for the rare one. An attribute lets a
+ * page opt in with one prop spread and lets every other page say nothing.
+ *
+ * A page with NO anchor reveals the dock immediately. That is the honest
+ * default: an admin bulk bar has no Buy button to scroll past, and a dock that
+ * waited for an element that will never exist would never appear at all.
+ */
+export const CTA_ANCHOR_ATTR = "data-cta-anchor";
+/**
+ * Spread onto the element wrapping a page's inline primary CTA.
+ *
+ * @example
+ * <Stack gap="sm" {...ctaAnchorProps()}>
+ *   <Button>Buy Now</Button>
+ *   <Button>Add to Cart</Button>
+ * </Stack>
+ */
+export function ctaAnchorProps() {
+    return { [CTA_ANCHOR_ATTR]: "true" };
+}

package/dist/features/layout/hooks/useBottomActions.d.ts

@@ -18,6 +18,13 @@ export interface UseBottomActionsOptions {
      * so pages that don't opt in behave exactly as before.
      */
     desktop?: BottomActionsDesktopMode;
+    /**
+     * `id` of this page's inline primary CTA. The floating action dock stays
+     * hidden until that element has been seen and scrolled out of view. Omit it
+     * and the dock appears as soon as there is something to show — which is what
+     * every bulk-selection screen wants.
+     */
+    ctaAnchorId?: string;
     /**
      * Set false to opt out entirely — no claim is taken, so this consumer is
      * invisible to the stack and cannot displace whoever currently owns the

package/dist/features/layout/hooks/useBottomActions.js

@@ -2,7 +2,7 @@
 import { useEffect, useId, useRef } from "react";
 import { useBottomActionsContext, } from "../BottomActionsContext.js";
 export function useBottomActions(options = {}) {
-    const { setActions, setBulkConfig, setInfoLabel, setSecondaryLabel, setInfoPanel, setInfoOpenSignal, setDesktopMode, claim, release, topClaimId, } = useBottomActionsContext();
+    const { setActions, setBulkConfig, setInfoLabel, setSecondaryLabel, setInfoPanel, setInfoOpenSignal, setDesktopMode, setCtaAnchorId, claim, release, topClaimId, } = useBottomActionsContext();
     /*
      * One bar, many potential claimants. `DataListingView` already holds it on
      * ~70 admin screens, so a form opened in a drawer over a listing used to
@@ -75,6 +75,11 @@ export function useBottomActions(options = {}) {
             return;
         setDesktopMode(options.desktop);
     }, [setDesktopMode, options.desktop, isTop]);
+    useEffect(() => {
+        if (!isTop)
+            return;
+        setCtaAnchorId(options.ctaAnchorId);
+    }, [setCtaAnchorId, options.ctaAnchorId, isTop]);
     // NOTE: no clearAll() on unmount any more — `release()` above owns that, and
     // only blanks the bar when the stack empties. Clearing here would flash an
     // empty bar between a drawer closing and the listing behind it republishing.

package/dist/features/layout/index.d.ts

@@ -32,7 +32,15 @@ export { useBottomActions } from "./hooks/useBottomActions";
 export type { UseBottomActionsOptions } from "./hooks/useBottomActions";
 export { useFormBottomActions } from "./hooks/useFormBottomActions";
 export type { UseFormBottomActionsOptions } from "./hooks/useFormBottomActions";
-export { default as BottomActions } from "./BottomActions";
+export { default as SideActionDock } from "./SideActionDock";
+/**
+ * @deprecated The bottom action bar is now a floating side dock. Kept as an
+ * alias so a consumer that mounts it by name keeps compiling and keeps
+ * rendering the same actions — the component it resolves to is
+ * `SideActionDock`.
+ */
+export { default as BottomActions } from "./SideActionDock";
+export { ctaAnchorProps, CTA_ANCHOR_ATTR } from "./cta-anchor";
 export { BottomChrome } from "./BottomChrome";
 export type { BottomChromeProps } from "./BottomChrome";
 export { BottomNavbar } from "./BottomNavbar";

package/dist/features/layout/index.js

@@ -17,7 +17,15 @@ export { AppLayoutShell } from "./AppLayoutShell.js";
 export { BottomActionsProvider, useBottomActionsContext, } from "./BottomActionsContext.js";
 export { useBottomActions } from "./hooks/useBottomActions.js";
 export { useFormBottomActions } from "./hooks/useFormBottomActions.js";
-export { default as BottomActions } from "./BottomActions.js";
+export { default as SideActionDock } from "./SideActionDock.js";
+/**
+ * @deprecated The bottom action bar is now a floating side dock. Kept as an
+ * alias so a consumer that mounts it by name keeps compiling and keeps
+ * rendering the same actions — the component it resolves to is
+ * `SideActionDock`.
+ */
+export { default as BottomActions } from "./SideActionDock.js";
+export { ctaAnchorProps, CTA_ANCHOR_ATTR } from "./cta-anchor.js";
 export { BottomChrome } from "./BottomChrome.js";
 export { BottomNavbar } from "./BottomNavbar.js";
 export { MainNavbar } from "./MainNavbar.js";

package/dist/features/layout/useCtaReveal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * useCtaReveal — "has the user met the Buy button and scrolled past it?"
+ *
+ * Returns true when the floating action dock should be on screen:
+ *
+ *  - the page marks NO CTA anchor          → true immediately (nothing to wait
+ *    for; an admin bulk bar has no Buy button)
+ *  - the page marks one, not yet seen      → false (the inline CTA is doing the
+ *    job; a second copy of it beside itself is noise)
+ *  - seen, and now out of view             → true
+ *  - seen, and scrolled back into view      → false again
+ *
+ * 🛑 `IntersectionObserver`, never a scroll-position threshold. The bar this
+ * replaces used `window.scrollY > 400`, which is a guess about where a CTA sits
+ * — wrong on a short page (the dock appears while the real button is still on
+ * screen) and wrong on a long gallery (it appears before the CTA is reached).
+ * Observing the element itself is the same rule stated exactly, and it costs no
+ * scroll handler.
+ *
+ * The anchor is looked up on an interval-free `MutationObserver` because the
+ * page that owns it mounts AFTER this dock — the dock lives in the app shell
+ * and the CTA arrives with the route.
+ */
+export declare function useCtaReveal(enabled?: boolean, anchorId?: string): boolean;

package/dist/features/layout/useCtaReveal.js

@@ -0,0 +1,82 @@
+"use client";
+import { useEffect, useState } from "react";
+import { CTA_ANCHOR_ATTR } from "./cta-anchor.js";
+/**
+ * useCtaReveal — "has the user met the Buy button and scrolled past it?"
+ *
+ * Returns true when the floating action dock should be on screen:
+ *
+ *  - the page marks NO CTA anchor          → true immediately (nothing to wait
+ *    for; an admin bulk bar has no Buy button)
+ *  - the page marks one, not yet seen      → false (the inline CTA is doing the
+ *    job; a second copy of it beside itself is noise)
+ *  - seen, and now out of view             → true
+ *  - seen, and scrolled back into view      → false again
+ *
+ * 🛑 `IntersectionObserver`, never a scroll-position threshold. The bar this
+ * replaces used `window.scrollY > 400`, which is a guess about where a CTA sits
+ * — wrong on a short page (the dock appears while the real button is still on
+ * screen) and wrong on a long gallery (it appears before the CTA is reached).
+ * Observing the element itself is the same rule stated exactly, and it costs no
+ * scroll handler.
+ *
+ * The anchor is looked up on an interval-free `MutationObserver` because the
+ * page that owns it mounts AFTER this dock — the dock lives in the app shell
+ * and the CTA arrives with the route.
+ */
+export function useCtaReveal(enabled = true, anchorId) {
+    const [anchor, setAnchor] = useState(null);
+    const [anchorExists, setAnchorExists] = useState(false);
+    const [seen, setSeen] = useState(false);
+    const [inView, setInView] = useState(false);
+    // Find the anchor, and keep looking — a client-side navigation swaps the
+    // page under a dock that never unmounts.
+    useEffect(() => {
+        if (!enabled || typeof document === "undefined")
+            return;
+        const read = () => {
+            // An id published through the context wins over the attribute: a page
+            // that names its anchor explicitly is making a more specific statement
+            // than "somewhere on this page there is a CTA".
+            const el = anchorId
+                ? document.getElementById(anchorId)
+                : document.querySelector(`[${CTA_ANCHOR_ATTR}]`);
+            setAnchor((prev) => (prev === el ? prev : el));
+            setAnchorExists(!!el);
+            // A new page means a fresh question. Without this reset, navigating from
+            // a product page (seen, scrolled past) to another one would reveal the
+            // dock at the top of the new page, over its own inline CTA.
+            if (!el) {
+                setSeen(false);
+                setInView(false);
+            }
+        };
+        read();
+        const mo = new MutationObserver(read);
+        mo.observe(document.body, { childList: true, subtree: true });
+        return () => mo.disconnect();
+    }, [enabled, anchorId]);
+    useEffect(() => {
+        if (!anchor || typeof IntersectionObserver === "undefined")
+            return;
+        setSeen(false);
+        const io = new IntersectionObserver(([entry]) => {
+            if (!entry)
+                return;
+            setInView(entry.isIntersecting);
+            if (entry.isIntersecting)
+                setSeen(true);
+        }, 
+        // Any sliver counts as "met it" — a CTA half-cut by the fold has been
+        // encountered, and requiring full visibility would leave the dock hidden
+        // on a short viewport where it is needed most.
+        { threshold: 0 });
+        io.observe(anchor);
+        return () => io.disconnect();
+    }, [anchor]);
+    if (!enabled)
+        return false;
+    if (!anchorExists)
+        return true;
+    return seen && !inView;
+}