@mohasinac/appkit 4.53.2 → 4.54.0-next.0

package/dist/features/layout/BottomActions.js

@@ -0,0 +1,330 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * BottomActions — the PHONE half of the page-action control.
+ *
+ * 🛑 Mobile only, unconditionally. `SideActionDock` is the desktop half, and
+ * `useIsDesktop` is the single line that chooses between them; both read the
+ * same `BottomActionsContext`, so every publisher (`useBottomActions`,
+ * `useFormBottomActions`, every `DataListingView` bulk bar) feeds whichever
+ * one is mounted without knowing which that is.
+ *
+ * Why a bar here and a dock there: a phone has a thumb zone and a bottom edge
+ * that already means something, and this bar stacks correctly above the tab
+ * bar inside `BottomChrome`. A floating puck on a phone takes content space on
+ * the screen with the least of it. At 1440px the argument reverses — see
+ * `SideActionDock`.
+ *
+ * 🛑 THE `desktop` OPTION IS GONE FROM THIS COMPONENT. It used to carry an
+ * `"always" | "after-scroll"` opt-in with its own `scrollY > 400` gate. That
+ * threshold is a guess about where a page's CTA sits — wrong on a short page
+ * and wrong on a long gallery — and the dock now owns desktop outright, so a
+ * page opting the BAR onto desktop would put two toolbars on one screen.
+ * `BottomActionsState.desktop` still exists for callers; this component no
+ * longer reads it.
+ *
+ * A fixed-bottom mobile action bar rendered **above** BottomNavbar (bottom-14).
+ * Reads from `BottomActionsContext` — features register their actions via the
+ * `useBottomActions` hook; this component just renders whatever is registered.
+ *
+ * Two modes:
+ *  - **Page mode** — shows registered page-level actions inline (Add to Cart,
+ *    Buy Now, Place Bid, Proceed to Checkout, etc.) with an optional info label.
+ *  - **Bulk mode** — activates when sieveFilter("bulk.selectedCount", SIEVE_OP.GT, "0"); shows:
+ *      • Selection count pill on the left (tap to deselect all)
+ *      • An upward-opening type-picker dropdown (middle, flex-1) — tap to
+ *        choose WHICH action to run; the chosen label is always visible.
+ *      • An "Apply" submit button on the right — executes the selected action,
+ *        styled with the selected action's variant (danger = red, etc.).
+ *
+ * Layout rules:
+ *  - Not mounted at all on lg+ screens.
+ *  - It reveals only once the page's own inline CTA has been SEEN and scrolled
+ *    past (`useCtaReveal`), and hides again when that CTA comes back into view.
+ *    A bar duplicating a button the user is already looking at is noise.
+ *  - The bar collapses rather than translating when hidden, so the height it
+ *    publishes through `BottomChrome` is honest at every frame.
+ *
+ * @component
+ * @example
+ * // Automatically rendered by LayoutClient — no manual usage required.
+ * // Features use `useBottomActions` to register their actions.
+ */
+import { useState, useRef, useEffect, useId } from "react";
+import { X, ChevronUp, ChevronDown, Check } from "lucide-react";
+import { useBottomActionsContext } from "./BottomActionsContext.js";
+import { useClickOutside } from "../../react/index.js";
+import { useCtaReveal } from "./useCtaReveal.js";
+import { useIsDesktop } from "./useIsDesktop.js";
+import { ActionRow, Div, Row, Span, Text, Button } from "../../ui/index.js";
+// Token values inlined from @mohasinac/appkit/tokens
+const BOTTOM_NAV_BG = "bg-[color-mix(in_srgb,var(--appkit-color-bg)_90%,transparent)] backdrop-blur-md border-t border-[var(--appkit-color-border)]";
+const BOTTOM_NAV_HEIGHT = "h-14";
+const FLEX_CENTER = "flex items-center justify-center";
+const CLS_COUNT_BADGE = "bg-error-solid text-error-on-solid";
+// ─── Sub-components ───────────────────────────────────────────────────────────
+function BulkPickerPanel({ bulkActions, selectedActionId, pickerOpen, onSelect, }) {
+    return (_jsx(Div, { role: "listbox", "aria-label": "Bulk actions", className: [
+            // Flips with the tier — see InfoPanel for why.
+            "absolute left-0 right-0 overflow-hidden",
+            "bottom-full lg:bottom-auto lg:top-full",
+            BOTTOM_NAV_BG,
+            "border-t lg:border-t-0 lg:border-b border-[var(--appkit-color-border)]/80",
+            "shadow-[0_-8px_24px_rgba(0,0,0,0.10)] dark:shadow-[0_-8px_24px_rgba(0,0,0,0.35)]",
+            "lg:shadow-[0_8px_24px_rgba(0,0,0,0.10)] dark:lg:shadow-[0_8px_24px_rgba(0,0,0,0.35)]",
+            "transition-[max-height,opacity] duration-200 ease-out",
+            pickerOpen ? "max-h-64 opacity-100" : "max-h-0 opacity-0 pointer-events-none",
+        ]
+            .filter(Boolean)
+            .join(" "), 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-5)] py-[var(--appkit-space-3-5)] text-left text-[length:var(--appkit-text-sm)] font-medium transition-colors rounded-none",
+                    i > 0 ? "border-t border-zinc-100/80 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));
+        }) }));
+}
+/**
+ * Expandable detail that opens UPWARD from the bar.
+ *
+ * Same recipe as BulkPickerPanel above — absolutely positioned at `bottom-full`
+ * so it grows into the space above the bar rather than pushing the page, and
+ * animated on max-height/opacity so it can't be tabbed into while closed.
+ * Scrolls internally, since a many-store cart's breakdown can outgrow the
+ * screen.
+ */
+function InfoPanel({ id, open, children, }) {
+    return (_jsx(Div, { id: id, className: [
+            // Opens UPWARD from a bottom-edge bar, DOWNWARD from a desktop bar
+            // hanging under the header — a panel must always expand into the
+            // screen, never off it. Border and shadow flip with it, or the sheet
+            // is lit from the wrong side and reads as detached from its bar.
+            "absolute left-0 right-0 overflow-hidden",
+            "bottom-full lg:bottom-auto lg:top-full",
+            BOTTOM_NAV_BG,
+            "border-t lg:border-t-0 lg:border-b border-[var(--appkit-color-border)]/80",
+            "shadow-[0_-8px_24px_rgba(0,0,0,0.10)] dark:shadow-[0_-8px_24px_rgba(0,0,0,0.35)]",
+            "lg:shadow-[0_8px_24px_rgba(0,0,0,0.10)] dark:lg:shadow-[0_8px_24px_rgba(0,0,0,0.35)]",
+            "transition-[max-height,opacity] duration-200 ease-out",
+            open ? "max-h-[60vh] opacity-100" : "max-h-0 opacity-0 pointer-events-none",
+        ]
+            .filter(Boolean)
+            .join(" "), "aria-hidden": !open, children: _jsx(Div, { className: "max-h-[60vh]", overflow: "y-auto", padding: "md", children: children }) }));
+}
+/**
+ * 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. `BottomChrome`'s
+ * ResizeObserver faithfully republishes `--bottom-chrome-height` on any height
+ * change, and every consumer (BackToTop, the pagination bar, the footer's
+ * clearance) reflows with it. A bar that grew a row when an error appeared
+ * would shift the whole page while the user was typing. The error count lives
+ * in `infoLabel`, which sits in the absolutely-positioned panel and is excluded
+ * from the published height by construction.
+ *
+ * The invariant is about ROW COUNT, not pixel height. `ActionRow` lets a long
+ * label wrap to a second line, which changes the bar's height by ~16px,
+ * monotonically, and the observer handles that correctly. What must never
+ * happen is a row count that FLIPS: that is a ~48px step and it is reversible
+ * mid-interaction.
+ *
+ * Which is exactly why the count split stays primary and `flex-wrap` is only an
+ * overflow net. In this app LABELS ARE STATE — "Add to Cart" becomes "Adding…",
+ * "Buy Now" becomes "Out of Stock", "Apply" becomes "Apply (3)". If width alone
+ * decided rows, tapping Add to Cart would shorten the label, free ~40px,
+ * un-wrap a row and shift the page under the user's thumb at the exact moment
+ * they committed to the tap.
+ *
+ * 🛑 This constant is COUPLED to `--appkit-size-action-min` (tokens.css).
+ * Two actions per line is safe only while `2 × action-min + gap` fits the
+ * narrowest supported viewport (280px). Raising either without re-checking that
+ * sum reintroduces device-dependent row flipping.
+ */
+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 now, not this component's — every action is
+             * sized from its own label by `.appkit-action-row__group > *`, and only
+             * the leftover is shared out. There is deliberately NO per-action width
+             * class here: the old `grow` ternary is what produced a 44px stub
+             * reading "Ba" next to a full-width "Continue to payment".
+             *
+             * The one thing a stylesheet cannot infer is that a child has no label,
+             * so icon-only opts into its square tap target explicitly.
+             *
+             * 🛑 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 bar to the squeezed behaviour with no visible error.
+             */
+            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 form's or a page's actions out across one or two lines.
+ *
+ * | n    | layout                                                          |
+ * |------|-----------------------------------------------------------------|
+ * | 1    | one row, full-width primary                                     |
+ * | 2    | one row, each sized from its own label                          |
+ * | 3+   | two rows — secondaries above, primary full-width below           |
+ *
+ * The LAST action is treated as the primary. That holds for every producer:
+ * `useFormBottomActions` appends submit last, and the checkout/cart bars build
+ * `[back, primary]`. Putting it on its own line keeps the thumb target the same
+ * size no matter how many secondary actions a screen has, which is the whole
+ * reason a 5-action form (3 forms + soft-ban + hard-ban on the admin user
+ * editor) was unrepresentable before.
+ *
+ * Secondaries WRAP rather than overflowing into a menu. Wrapping keeps the
+ * height a pure function of the action count — the invariant above — whereas a
+ * popover would add a second interaction to reach an action that is already
+ * only one line away. No current caller exceeds five.
+ */
+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 }) })] }));
+}
+export default function BottomActions() {
+    const { state, actionCallbacksRef, bulkCallbacksRef, bulkClearRef } = useBottomActionsContext();
+    const isDesktop = useIsDesktop();
+    const [pickerOpen, setPickerOpen] = useState(false);
+    const [infoOpen, setInfoOpen] = useState(false);
+    const [selectedActionId, setSelectedActionId] = useState(null);
+    const containerRef = useRef(null);
+    const infoPanelId = useId();
+    useClickOutside(containerRef, () => {
+        setPickerOpen(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;
+    /*
+     * The same reveal rule the dock uses, for the same reason: while the page's
+     * own Add-to-Cart is on screen, a second copy of it welded to the bottom
+     * edge is a duplicate covering the last row of the page. A selection is its
+     * own reveal — bulk mode is a state the user just entered deliberately, and
+     * making them scroll to act on it would be a puzzle.
+     */
+    const revealed = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId) || isBulkMode;
+    const isVisible = hasContent && revealed;
+    // A panel left open after its content is withdrawn (bulk mode taking over, or
+    // the page clearing it) would sit there as an empty sheet.
+    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. `hasInfoPanel` is read but deliberately NOT
+     * a dependency: publishing the panel and bumping the signal are two separate
+     * setState calls, so re-running on `hasInfoPanel` would open the panel again
+     * one render after the user closed it.
+     */
+    const lastSignalRef = useRef(undefined);
+    useEffect(() => {
+        if (infoOpenSignal == null)
+            return;
+        if (lastSignalRef.current === infoOpenSignal)
+            return;
+        lastSignalRef.current = infoOpenSignal;
+        setInfoOpen(true);
+    }, [infoOpenSignal]);
+    // Keep selectedActionId in sync with available bulk actions
+    useEffect(() => {
+        if (!isBulkMode) {
+            setPickerOpen(false);
+            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)?.();
+    const dispatchBulkClear = () => {
+        bulkClearRef.current?.();
+        setPickerOpen(false);
+    };
+    const handleApply = () => {
+        if (!selectedActionId)
+            return;
+        bulkCallbacksRef.current.get(selectedActionId)?.();
+        setPickerOpen(false);
+    };
+    // 🛑 AFTER every hook, never before — this flips on resize, and an early
+    // return above a `useState` would change the hook order mid-session.
+    // `return null`, not `lg:hidden`: see `useIsDesktop` for why the class form
+    // cannot be trusted here, and because a display:none bar still mounts,
+    // still observes, and can still take focus.
+    if (isDesktop)
+        return null;
+    return (_jsxs(Div, { ref: containerRef, role: "toolbar", "aria-label": isBulkMode ? "Bulk actions" : "Page actions", "aria-hidden": !isVisible, className: [
+            // Position, z-index and the offset above the nav all belong to
+            // <BottomChrome>, the tier container this renders inside. `relative` is
+            // kept because the two panels below are `absolute bottom-full` against it.
+            "relative pointer-events-auto",
+        ]
+            .filter(Boolean)
+            .join(" "), "data-section": "bottomactions-div-401", children: [isBulkMode && (_jsx(BulkPickerPanel, { bulkActions: bulkActions, selectedActionId: selectedActionId, pickerOpen: pickerOpen, onSelect: (id) => { setSelectedActionId(id); setPickerOpen(false); } })), hasInfoPanel && !isBulkMode && (_jsx(InfoPanel, { id: infoPanelId, open: infoOpen, children: infoPanel })), _jsx(Div, { className: `grid transition-[grid-template-rows] duration-300 ease-out ${isVisible ? "grid-rows-[1fr]" : "grid-rows-[0fr]"}`, children: _jsx(Div, { overflow: "hidden", className: "min-h-0", children: _jsxs(Div, { className: [
+                            BOTTOM_NAV_BG,
+                            // Cast away from the edge the bar is welded to: upward from the
+                            // bottom edge, downward from under the header.
+                            "shadow-[0_-4px_20px_rgba(0,0,0,0.08)] dark:shadow-[0_-4px_20px_rgba(0,0,0,0.30)]",
+                            "lg:shadow-[0_4px_20px_rgba(0,0,0,0.08)] dark:lg:shadow-[0_4px_20px_rgba(0,0,0,0.30)]",
+                            // A hairline on the side facing the page, so the bar reads as
+                            // chrome rather than as a floating slab.
+                            "lg:border-b lg:border-[var(--appkit-color-border)]/80",
+                            isVisible ? "" : "pointer-events-none",
+                        ]
+                            .filter(Boolean)
+                            .join(" "), children: [isBulkMode && (_jsx(Div, { className: "h-[3px] w-full bg-[image:var(--appkit-gradient-brand-tri)]" })), secondaryLabel && !isBulkMode && (_jsx(Div, { className: "pt-[var(--appkit-space-2)] pb-0 border-b border-[var(--appkit-color-border-subtle)]", padding: "x-md", children: _jsx(Text, { className: "leading-5 truncate", color: "muted", size: "xs", weight: "semibold", children: secondaryLabel }) })), infoLabel && !isBulkMode && !hasInfoPanel && (_jsx(Div, { className: "pt-[var(--appkit-space-2)] pb-0 border-b border-[var(--appkit-color-border-subtle)]", padding: "x-md", children: _jsx(Text, { className: "leading-5 truncate", color: "muted", size: "xs", weight: "semibold", children: infoLabel }) })), infoLabel && !isBulkMode && hasInfoPanel && (_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-none border-b border-[var(--appkit-color-border)]/80 px-[var(--appkit-space-4)] pt-[var(--appkit-space-2)] pb-[var(--appkit-space-1)] min-h-0", children: [_jsx(Text, { className: "leading-5 truncate", color: "muted", size: "xs", weight: "semibold", children: infoLabel }), _jsxs(Span, { className: "flex-shrink-0 flex items-center gap-[var(--appkit-space-1)]", children: [_jsx(Text, { as: "span", size: "xs", color: "muted", children: infoOpen ? "Hide" : "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" }))] })] })), _jsx(Row, { className: `min-${BOTTOM_NAV_HEIGHT} py-[var(--appkit-space-2)]`, gap: "sm", padding: "x-sm", children: isBulkMode && bulk ? (_jsxs(_Fragment, { children: [_jsxs(Button, { rounded: "full", gap: "xs", type: "button", variant: "ghost", onClick: dispatchBulkClear, className: "flex-shrink-0 bg-primary-50 hover:bg-primary-surface active:bg-primary-200 dark:bg-primary-950/30 text-primary-700 dark:text-primary-300 pl-2 pr-3 h-8 border border-primary-200/70 dark:border-primary-800/50 transition-colors min-h-0", "aria-label": "Clear selection", children: [_jsx(X, { className: "w-3.5 h-3.5 flex-shrink-0", "aria-hidden": "true" }), _jsx(Span, { size: "xs", weight: "semibold", className: "tabular-nums whitespace-nowrap leading-none", children: bulk.noun
+                                                        ? `${bulk.selectedCount} ${bulk.noun}`
+                                                        : `${bulk.selectedCount} selected` })] }), bulkActions.length > 0 && (_jsxs(Button, { type: "button", variant: "ghost", onClick: () => setPickerOpen((o) => !o), "aria-haspopup": "listbox", "aria-expanded": pickerOpen, className: [
+                                                "flex-1 min-w-0 h-10 flex items-center gap-[var(--appkit-space-2)] px-[var(--appkit-space-3)] rounded-lg border text-[length:var(--appkit-text-sm)] font-medium transition-colors",
+                                                " hover:bg-[var(--appkit-color-surface)] active:bg-zinc-200 bg-[var(--appkit-color-surface-input)] dark:hover:bg-slate-700/60",
+                                                "border-[var(--appkit-color-border)]",
+                                                selectedAction?.variant === "danger"
+                                                    ? "text-error"
+                                                    : "text-[var(--appkit-color-text)]",
+                                            ]
+                                                .filter(Boolean)
+                                                .join(" "), children: [selectedAction?.icon && (_jsx(Span, { className: `flex-shrink-0 w-4 h-4 ${FLEX_CENTER}`, "aria-hidden": "true", children: selectedAction.icon })), _jsx(Span, { className: "flex-1 truncate leading-none", align: "start", children: selectedAction?.label ?? "Bulk actions" }), pickerOpen ? (_jsx(ChevronDown, { className: "w-4 h-4 flex-shrink-0 text-zinc-400", "aria-hidden": "true" })) : (_jsx(ChevronUp, { className: "w-4 h-4 flex-shrink-0 text-zinc-400", "aria-hidden": "true" }))] })), bulkActions.length > 0 && (_jsx(Button, { type: "button", variant: selectedAction?.variant ?? "primary", size: "sm", isLoading: selectedAction?.loading, disabled: !selectedActionId ||
+                                                selectedAction?.disabled ||
+                                                selectedAction?.loading, onClick: handleApply, className: "h-10 flex-shrink-0", children: _jsx(Span, { className: "leading-none", children: "Apply" }) }))] })) : (
+                                /* Page mode — action buttons inline ------------------------------ */
+                                _jsx(PageActionsRow, { pageActions: pageActions, dispatchAction: dispatchAction })) })] }) }) })] }));
+}

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

@@ -2,4 +2,49 @@ import React from "react";
 export interface BottomChromeProps {
     children: React.ReactNode;
 }
+/**
+ * BottomChrome — the middle tier of the bottom edge.
+ *
+ * The bottom edge is three tiers: the nav bar is the floor, `BackToTop` is the
+ * ceiling, and *everything else* lives in here. This container is what makes
+ * that middle tier a single thing with a single height:
+ *
+ *   --keyboard-inset-height   useVisualViewportInset  (the on-screen keyboard)
+ *   --bottom-nav-height       BottomNavLayout         (the tab bar)
+ *   --bottom-chrome-height    THIS COMPONENT          (CTA row, pagination, …)
+ *      ↑ BackToTop floats above the sum of all three
+ *
+ * Because it is a flex column, its own `offsetHeight` IS the sum of whatever is
+ * inside it — a bar changing height, revealing on scroll, entering bulk mode,
+ * or being added years from now all just resize this box, and the one
+ * ResizeObserver below picks every case up. Consumers read one variable and
+ * never have to learn about individual bars. Publishing a separate var per bar
+ * was the alternative, and it fails the moment someone adds bar number three
+ * without also editing every consumer's `calc()`.
+ *
+ * Two constraints this container places on its children:
+ *   - A child must hide by COLLAPSING, not by transforming. `translate-y-full`
+ *     leaves layout height behind, so a hidden bar would still be reserved here
+ *     on every page that has no CTA. See BottomActions' grid-rows collapse.
+ *   - No `overflow: hidden` here, ever. BottomActions' bulk-picker and info
+ *     panels are `absolute bottom-full` on mobile / `top-full` on desktop —
+ *     deliberately outside the flow (they are transient tap-to-open overlays,
+ *     not persistent bands, so they are excluded from the published height) —
+ *     and clipping would erase them.
+ *
+ * ── The tier CHANGES ENDS at `lg` ──────────────────────────────────────────
+ *
+ * Below `lg` it is the bottom edge, as described above. At `lg` and up it hangs
+ * from under the sticky header instead, and publishes its height as
+ * `--top-chrome-height` rather than `--bottom-chrome-height`.
+ *
+ * A full-width action bar welded to the bottom of a desktop window is a mobile
+ * pattern on a screen that has neither a thumb zone nor a tab bar to stack
+ * above — it reads as a browser download bar, and it is the furthest point on
+ * screen from the content it acts on. Under the header it sits where the eye
+ * already is and where the page's own chrome lives.
+ *
+ * Consumers therefore read whichever end they care about, and the two are
+ * mutually exclusive by construction (see `write()`).
+ */
 export declare function BottomChrome({ children }: BottomChromeProps): React.JSX.Element;

package/dist/features/layout/BottomChrome.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useRef } from "react";
 import { Div } from "../../ui/index.js";
 import { BOTTOM_CHROME_SLOT_ID } from "../../ui/components/bottom-chrome-slot.js";
+import { useIsDesktop } from "./useIsDesktop.js";
 /**
  * BottomChrome — the middle tier of the bottom edge.
  *
@@ -48,26 +49,13 @@ import { BOTTOM_CHROME_SLOT_ID } from "../../ui/components/bottom-chrome-slot.js
  * Consumers therefore read whichever end they care about, and the two are
  * mutually exclusive by construction (see `write()`).
  */
-/**
- * The breakpoint at which the tier moves from the bottom edge to under the
- * header. 64rem is Tailwind's `lg` — the same line `BottomNavbar` disappears
- * at, so the tier changes ends exactly when the thing it was stacking above
- * stops existing.
- */
-const DESKTOP_QUERY = "(min-width: 64rem)";
 export function BottomChrome({ children }) {
     const ref = useRef(null);
-    const [isDesktop, setIsDesktop] = useState(false);
     // Matched in JS as well as in CSS because the MEASUREMENT has to know which
     // variable to publish — a media query alone can move the box but cannot tell
-    // the ResizeObserver which end of the screen it ended up at.
-    useEffect(() => {
-        const mq = window.matchMedia(DESKTOP_QUERY);
-        const sync = () => setIsDesktop(mq.matches);
-        sync();
-        mq.addEventListener("change", sync);
-        return () => mq.removeEventListener("change", sync);
-    }, []);
+    // the ResizeObserver which end of the screen it ended up at. Shared with
+    // SideActionDock/BottomActions so one line decides the whole layout flip.
+    const isDesktop = useIsDesktop();
     useEffect(() => {
         const root = document.documentElement;
         const el = ref.current;

package/dist/features/layout/SideActionDock.js

@@ -7,19 +7,31 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * (`useBottomActions`, `useFormBottomActions`, every `DataListingView` bulk
  * bar) are untouched: only the presentation changed.
  *
- * ── Why a side dock and not a bar ──────────────────────────────────────────
+ * ── 🛑 DESKTOP ONLY. The phone gets `BottomActions`. ───────────────────────
  *
- * 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.
+ * This used to render at every width, and on a phone that was the wrong trade
+ * twice over: a floating puck sits in the middle of the content on the screen
+ * with the least of it, and it replaced a bar that was already in the thumb
+ * zone and already stacked correctly above the tab bar. A phone has a thumb
+ * zone and a bottom edge that means something; a 1440px window has neither,
+ * which is the entire argument for each half.
+ *
+ * The two are mutually exclusive by construction — `useIsDesktop` decides, and
+ * both halves read the SAME `BottomActionsContext`, so all ~30 publishers are
+ * untouched and nothing can register with only one of them.
  *
  * ── 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,
+ * 1. **It docks OPPOSITE the sidebar, at the vertical MIDDLE.** `SidebarLayout`
+ *    docks to the hand-mode side (`hand === "left" ? left-0 : right-0`), so the
+ *    dock takes the other edge — left, in the default right-hand configuration
+ *    — and the two can never overlap, including while the sidebar is open,
  *    which is exactly when a CTA hidden underneath it would be unreachable.
+ *    Vertically it is centred rather than bottom-anchored: at the bottom of a
+ *    desktop window it reads as a browser download bar and sits as far from
+ *    the content as the viewport allows. Centred, it is beside the content,
+ *    and it needs no bottom-tier clearance at all — there is no tab bar at
+ *    this width and the pagination bar is at the other end of the screen.
  *
  * 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
@@ -41,6 +53,7 @@ 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 { useIsDesktop } from "./useIsDesktop.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";
@@ -111,6 +124,7 @@ function BulkActionList({ bulkActions, selectedActionId, onSelect, }) {
 export default function SideActionDock() {
     const { state, actionCallbacksRef, bulkCallbacksRef, bulkClearRef } = useBottomActionsContext();
     const { hand } = useHandMode();
+    const isDesktop = useIsDesktop();
     const [expanded, setExpanded] = useState(false);
     const [infoOpen, setInfoOpen] = useState(false);
     const [selectedActionId, setSelectedActionId] = useState(null);
@@ -130,7 +144,7 @@ export default function SideActionDock() {
         !!secondaryLabel;
     // Rule 3 — a selection is its own reveal.
     const revealed = useCtaReveal(hasContent && !isBulkMode, ctaAnchorId) || isBulkMode;
-    const isVisible = hasContent && revealed;
+    const isVisible = isDesktop && 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";
@@ -206,10 +220,19 @@ export default function SideActionDock() {
             "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))]",
+            /*
+             * Vertically centred — see rule 1. This is a desktop-only control, so
+             * it deliberately reads NONE of the three bottom-tier variables: there
+             * is no tab bar at this width, the keyboard inset is a phone concern,
+             * and the pagination bar is at the opposite end of the viewport. An
+             * unused `calc()` over variables that are 0 here is just a claim about
+             * a relationship that no longer exists.
+             *
+             * `max-h` + `justify-center` so a tall expanded panel grows about the
+             * midpoint and is clipped by the viewport rather than running off both
+             * ends of it; the panel scrolls internally.
+             */
+            "top-1/2 -translate-y-1/2 max-h-[90vh] justify-center",
             "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

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

@@ -33,13 +33,8 @@ export type { UseBottomActionsOptions } from "./hooks/useBottomActions";
 export { useFormBottomActions } from "./hooks/useFormBottomActions";
 export type { UseFormBottomActionsOptions } from "./hooks/useFormBottomActions";
 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 { default as BottomActions } from "./BottomActions";
+export { useIsDesktop, DESKTOP_QUERY } from "./useIsDesktop";
 export { ctaAnchorProps, CTA_ANCHOR_ATTR } from "./cta-anchor";
 export { BottomChrome } from "./BottomChrome";
 export type { BottomChromeProps } from "./BottomChrome";

package/dist/features/layout/index.js

@@ -17,14 +17,14 @@ 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 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`.
+/*
+ * The two presentations of one control. `AppLayoutShell` mounts both and
+ * `useIsDesktop` lets exactly one render — do not mount either directly, or a
+ * page gets two toolbars publishing into the same context.
  */
-export { default as BottomActions } from "./SideActionDock.js";
+export { default as SideActionDock } from "./SideActionDock.js";
+export { default as BottomActions } from "./BottomActions.js";
+export { useIsDesktop, DESKTOP_QUERY } from "./useIsDesktop.js";
 export { ctaAnchorProps, CTA_ANCHOR_ATTR } from "./cta-anchor.js";
 export { BottomChrome } from "./BottomChrome.js";
 export { BottomNavbar } from "./BottomNavbar.js";

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

@@ -0,0 +1,36 @@
+/**
+ * The line at which the layout stops being a phone.
+ *
+ * 64rem is Tailwind's `lg` — deliberately the same breakpoint `BottomNavbar`
+ * disappears at, so every decision that depends on "is there a tab bar at the
+ * bottom of this screen" flips at one place.
+ */
+export declare const DESKTOP_QUERY = "(min-width: 64rem)";
+/**
+ * `true` at `lg` and up.
+ *
+ * ── 🛑 WHY A HOOK AND NOT A `lg:` CLASS ────────────────────────────────────
+ *
+ * Three callers need the breakpoint as a VALUE, not as styling:
+ *
+ *   - `BottomChrome` must know which CSS variable to publish — a media query
+ *     can move the box but cannot tell a `ResizeObserver` which end of the
+ *     screen it landed at.
+ *   - `SideActionDock` and `BottomActions` are the two halves of one control
+ *     and must never both be mounted: two toolbars reading the same context,
+ *     both `fixed`, both dispatching the same callbacks. Hiding one with
+ *     `display:none` would still mount it, still run its observers, and still
+ *     let a stray `:focus` land inside an invisible bar.
+ *
+ * And the class form is actively unsafe here. Both Tailwind configs set
+ * `important: true`, so a `lg:` override and its unprefixed base tie on
+ * specificity AND on `!important` — a media query adds no specificity — and
+ * the winner is decided by EMISSION ORDER in the built CSS, which is invisible
+ * from the call site. That is exactly how `BottomChrome` ended up anchored to
+ * both edges at once and published an 801px phantom bar (see its header).
+ *
+ * SSR renders the mobile branch, because that is the branch that is correct
+ * when nothing is known: a phone that briefly gets the dock has lost its only
+ * CTA, while a desktop that briefly gets the bar has a bar.
+ */
+export declare function useIsDesktop(): boolean;