@mohasinac/appkit 4.52.5 → 4.53.0

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: _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 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: 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;
+}

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

@@ -0,0 +1,41 @@
+import React from "react";
+/**
+ * How long a press has to last before it counts as "hold to open" rather than
+ * "tap to follow the link". 400ms is the usual long-press threshold — short
+ * enough not to feel like a stall, long enough that an ordinary tap never
+ * trips it.
+ */
+export declare const HOLD_TO_OPEN_MS = 400;
+/**
+ * useHoldToOpen — press-and-hold a navigation link to open its sub-menu
+ * instead of following it.
+ *
+ * The shared half of the same affordance on two surfaces: the desktop navbar's
+ * dropdown and the mobile bottom nav's sheet. Both wrap a REAL link whose tap
+ * must still navigate, and both need the `click` that a long press still fires
+ * to be swallowed — otherwise the menu opens and the browser immediately
+ * navigates away from it, which reads as the gesture doing nothing.
+ *
+ * 🛑 `held` is a ref, not state. The click handler reads it in the same tick
+ * the timer wrote it, and a state update would not have landed yet — the link
+ * would follow through on every hold.
+ *
+ * @param onHold   called once the press passes the threshold (open the menu)
+ * @param enabled  false for a link with no children — then every handler is a
+ *                 no-op and the link behaves exactly as it did before
+ */
+export declare function useHoldToOpen(onHold: () => void, enabled?: boolean): {
+    onPointerDown: () => void;
+    onPointerUp: () => void;
+    onPointerLeave: () => void;
+    onPointerCancel: () => void;
+    onClickCapture: (e: React.MouseEvent) => void;
+    onContextMenu: (e: React.MouseEvent) => void;
+} | {
+    onPointerDown?: undefined;
+    onPointerUp?: undefined;
+    onPointerLeave?: undefined;
+    onPointerCancel?: undefined;
+    onClickCapture?: undefined;
+    onContextMenu?: undefined;
+};

package/dist/features/layout/useHoldToOpen.js

@@ -0,0 +1,84 @@
+"use client";
+import { useCallback, useEffect, useRef } from "react";
+/**
+ * How long a press has to last before it counts as "hold to open" rather than
+ * "tap to follow the link". 400ms is the usual long-press threshold — short
+ * enough not to feel like a stall, long enough that an ordinary tap never
+ * trips it.
+ */
+export const HOLD_TO_OPEN_MS = 400;
+/**
+ * useHoldToOpen — press-and-hold a navigation link to open its sub-menu
+ * instead of following it.
+ *
+ * The shared half of the same affordance on two surfaces: the desktop navbar's
+ * dropdown and the mobile bottom nav's sheet. Both wrap a REAL link whose tap
+ * must still navigate, and both need the `click` that a long press still fires
+ * to be swallowed — otherwise the menu opens and the browser immediately
+ * navigates away from it, which reads as the gesture doing nothing.
+ *
+ * 🛑 `held` is a ref, not state. The click handler reads it in the same tick
+ * the timer wrote it, and a state update would not have landed yet — the link
+ * would follow through on every hold.
+ *
+ * @param onHold   called once the press passes the threshold (open the menu)
+ * @param enabled  false for a link with no children — then every handler is a
+ *                 no-op and the link behaves exactly as it did before
+ */
+export function useHoldToOpen(onHold, enabled = true) {
+    const timerRef = useRef(null);
+    const heldRef = useRef(false);
+    const onHoldRef = useRef(onHold);
+    // Keep the callback current without re-creating the handlers (and therefore
+    // without restarting a press in progress on every parent re-render).
+    useEffect(() => {
+        onHoldRef.current = onHold;
+    }, [onHold]);
+    const cancel = useCallback(() => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+    }, []);
+    // Clear a pending timer if the item unmounts mid-press — the nav re-renders
+    // its item list whenever the listing-type flags or the session resolve.
+    useEffect(() => cancel, [cancel]);
+    const start = useCallback(() => {
+        heldRef.current = false;
+        cancel();
+        timerRef.current = setTimeout(() => {
+            heldRef.current = true;
+            onHoldRef.current();
+        }, HOLD_TO_OPEN_MS);
+    }, [cancel]);
+    /**
+     * Spread onto the element that wraps (or is) the link. `onClickCapture` is
+     * deliberate rather than `onClick`: on the bottom nav the handlers sit on a
+     * wrapper around `<NavItem>`, and by the time a bubbled click arrives the
+     * anchor's own default is already queued — capture runs before the anchor
+     * sees it, so one set of handlers works whether it is spread onto the link
+     * itself or onto a container.
+     */
+    const handlers = enabled
+        ? {
+            onPointerDown: start,
+            onPointerUp: cancel,
+            onPointerLeave: cancel,
+            onPointerCancel: cancel,
+            onClickCapture: (e) => {
+                if (!heldRef.current)
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                heldRef.current = false;
+            },
+            // A long press on touch otherwise raises the OS link callout over the
+            // menu the same gesture just opened.
+            onContextMenu: (e) => {
+                if (heldRef.current)
+                    e.preventDefault();
+            },
+        }
+        : {};
+    return handlers;
+}