Floating control panel

Overview

The floating control panel is the editor's Quick Edit Panel — a 20rem wide property panel that mounts next to the currently selected element instead of being docked in the right sidebar. It exposes the full set of element controls across 21 lazy-loaded sections (layout, text, background, media, spacing, position, attributes, events, dialog block settings, and more), plus quick-action buttons for Duplicate, Delete, Copy Style, Paste Style, and Create Block.

The panel is opt-in. By default the editor uses the docked right sidebar; switching the panelMode preference to quick-edit activates the floating panel and hides the Configuration toggle in the top toolbar. Once active, the panel auto-positions to the right of your selection, but the moment you grab its header it becomes a free floating window — its position is persisted per session, survives selection changes, and clamps back into the viewport on resize.

How it works

The mode toggle lives in useEditorPreferencesStore (persisted to localStorage under the editor-preferences-store key). It exposes two settings: panelMode ('right-sidebar' or 'quick-edit') and quickEditTrigger ('right-click' or 'double-click'). When panelMode === 'quick-edit', the canvas gesture chosen by quickEditTrigger writes the focused element's id into useCommmerceEditorSetupStore.quickEditElementId, which is the single gate that decides whether the panel is allowed to render.

Single-element selections render QuickEditPanel via React Portal from inside each ElementRenderer instance (rendered at three layout branches in drag-drop/ElementRenderer.tsx). Multi-selections render QuickEditMultiPanel instead, which positions itself against the bounding box of the selected set. Both panels share useDraggablePanel — the hook that owns auto-positioning, pointer-down drag, viewport clamping, and sessionStorage persistence under commmerce-editor:quick-edit-panel:position.

The body of the panel — header, quick-action rows, and 21 lazy-loaded section components — lives in QuickEditSections.tsx so the same UI can be reused by the docked right sidebar. Each section is dynamically imported via React.lazy and rendered only when relevant to the selected element's tag and parent layout mode; the panel shows a "Loading…" fallback while the section bundle fetches.

Drag math is handled by useDraggablePanel: on pointer-down it records the cursor's offset from the panel's top-left so the panel moves relative to the grab point (not jumping to the cursor). Pointer-move clamps the new position so at least HANDLE_VISIBLE = 40 px of the header remains in the viewport — even if the rest of the panel falls off-screen. Pointer-up writes the final position to sessionStorage so the next mount lands at the same spot. A resize listener re-clamps the persisted position so a spot saved on a wider window doesn't strand the panel after the user shrinks the editor.

Key features

• Auto-anchors to selection — on first appear, the panel computes autoPosition based on the selected element's bounding box. USE CASE: clicking a hero button puts the panel right next to it so you don't have to move your eye across the screen.
• Flips left if it would overflow right — if rect.right + 20rem + 12px exceeds the viewport, the panel re-anchors to the left of the element. USE CASE: selecting an element near the right edge still leaves the panel fully visible.
• Drag with relative offset — pointer-down records the cursor's offset inside the header so the panel doesn't snap to the cursor when dragging starts. USE CASE: grabbing the bottom-right of the header keeps the panel in the same spot until you actually move the mouse.
• Position persists across selections — sessionStorage keeps the user-chosen spot for the lifetime of the tab. USE CASE: parking the panel in a fixed corner while authoring a long page; clicking different elements doesn't snap it back.
• Viewport reclamp on resize — a resize listener clamps the persisted position to the new window size if it now falls out of bounds. USE CASE: closing a docked DevTools panel doesn't leave the Quick Edit panel stranded off-screen.
• Ctrl/Cmd to hide — useIsModifierKeyPressed unmounts the panel while the modifier is held. USE CASE: peeking at the layer underneath without dismissing the selection.
• Auto-hide during gestures — when interactionMode becomes 'drag' | 'resize' | 'rotate' | 'grid-cell-resize', the panel unmounts. USE CASE: dragging an element doesn't leave the panel floating over the drop target.
• Mounted-but-hidden during media upload — when isUploadMediaOpen is true the panel keeps its React tree alive but hides via inline style. USE CASE: BannerSlider's active-slide index survives an image upload round-trip.
• Multi-selection mode — QuickEditMultiPanel snaps to the bounding box of every selected element and edits fan out across the set via the batch slice. USE CASE: aligning six product cards in one go.
• Portal escape — the panel is rendered via createPortal to document.body, escaping any ancestor's z-index or overflow context. USE CASE: a clipped canvas container can't crop the panel.
• Shared body with docked sidebar — when panelMode === 'right-sidebar' the same QuickEditSections component renders inside the docked sidebar with chromeless set and drag handle props omitted. USE CASE: switching panel modes doesn't change which controls are available.
• Header badge shows parent layout — a blue pill in the header names the parent's layout mode (free-flow / stack / grid). USE CASE: instantly knowing why the Reorder section shows up/down vs left/right arrows.

QuickEditSections (21 lazy-loaded)

Every section is imported via React.lazy and shown only when relevant to the selected element's tag, type, or parent layout. Sections render their own collapsed/expanded state locally so the floating panel and the docked sidebar remember independent expansion preferences.

Panel-action controls

Below the section header, two rows of quick-actions cover the most common element operations. The first row (Duplicate / Delete) is always enabled; the second row (Copy Style / Paste Style / Create Block) is conditionally gated.

useEditorPreferencesStore

All persistent UI preferences for the panel live in this Zustand store, persisted to localStorage under editor-preferences-store. Changes survive across sessions and tabs.

Workflows

Examples

import { useEditorPreferencesStore } from '../../common/store/useEditorPreferencesStore';

/*   Switch from the docked Right Sidebar to the floating Quick Edit panel.  */
useEditorPreferencesStore.getState().setPanelMode('quick-edit');

/*   Change the trigger gesture — double-click is friendlier when           */
/*   right-click is reserved for the browser DevTools context menu.         */
useEditorPreferencesStore.getState().setQuickEditTrigger('double-click');

/*   The same UI body that the floating panel uses can be embedded in any    */
/*   host container — drop the drag handle props and pass chromeless=true.   */
import QuickEditSections from '../../common/components/commmerce-editor/element-editor/QuickEditSections';

<QuickEditSections
    node={node}
    parentNode={parent}
    chromeless={true}
    onSaveAttribute={handleSaveAttribute}
    onSaveStyle={handleSaveStyle}
    onLayoutModeChange={handleLayoutModeChange}
    onCopyStyle={handleCopyStyle}
    onPasteStyle={handlePasteStyle}
    onCreateBlock={handleCreateBlock}
    /* no headerDragHandleProps -> static header, no drag affordance */
/>

/*   Two side-by-side panels can keep independent persisted positions by    */
/*   passing distinct storageKey strings to useDraggablePanel.               */
const { position, dragHandleProps, isDragging } = useDraggablePanel({
    autoPosition,
    panelRef,
    resetKey: node.id,
    storageKey: 'my-feature:secondary-panel:position'
});

/*   The hook persists to sessionStorage on every pointer-up. Read it       */
/*   without invoking the hook (e.g. in a debug overlay).                    */
const raw = sessionStorage.getItem('commmerce-editor:quick-edit-panel:position');
const pos = raw ? JSON.parse(raw) : null;
/*   pos => { top: 142, left: 980 } or null when never dragged.            */

Keyboard shortcuts

Tips & gotchas

• The panel is portaled to document.body via createPortal — it escapes any z-index or overflow context set by ancestors.
• Auto-position prefers placing the panel to the right of the selection. If that would overflow, it flips to the left. Vertically, it clamps to a 10 px viewport margin top and bottom.
• Position persistence uses sessionStorage, not localStorage — closing the tab resets the panel to auto-position on the next load. The panelMode preference itself, however, is in localStorage and survives across sessions.
• Single-click never opens the panel; it only selects. Clicking a different element closes the panel; clicking the same element again leaves it open.
• Sections are lazy-loaded via React.lazy. Opening the panel on a complex element shows the Loading… fallback while the section bundles fetch — first paint is intentionally fast.
• Quick-action buttons render with inline styles (not Tailwind utility classes) so the panel looks identical in both the floating and docked sidebar host contexts.
• When you've docked the right sidebar (the default right-sidebar mode), the same QuickEditSections body renders inside the sidebar with the drag handle props omitted — meaning a docked panel is the floating panel without its drag affordance.
• Grid-context selections gain extra sections automatically: GridSpanSection, GridLayoutTemplatesPanel, and GridActionsSection only appear when the parent container's layout mode is grid.
• The drag clamp uses HANDLE_VISIBLE = 40 px — at most the panel can be pushed so far off-screen that only 40 px of the header remains visible. Vertical clamp uses maxTop = window.innerHeight - 40; the rest of the panel may sit below the viewport because the panel can be up to 80vh tall.
• The hook's resetKey is intentionally a no-op now — persistence is the product rule. Earlier versions snapped back to auto-position when the selection changed; the new behavior leaves the panel where the user parked it.