@beyondwork/docx-react-component 1.0.37 → 1.0.38

package/src/ui-tailwind/chrome/tw-detach-handle.tsx

@@ -0,0 +1,147 @@
+/**
+ * Shared detach/attach primitive for chrome surfaces that can float vs
+ * dock.  Extracted from the hand-rolled implementation in
+ * `tw-selection-tool-host.tsx` so the same UX works on the topnav, the
+ * selection tier, and any future overlay layer that opts in.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §6.3 every overlay child
+ * should consume this shape.  State is owned by `ViewState.chromePins`
+ * so pin offsets survive snapshot rebuilds within one session.
+ */
+
+import React, { useCallback, useEffect, useRef } from "react";
+import { GripHorizontal } from "lucide-react";
+
+import type {
+  ChromePinSurface,
+  PinState,
+} from "../../api/public-types";
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
+
+export interface TwDetachHandleProps {
+  /** Which chrome surface this handle controls; stored in ViewState. */
+  surface: ChromePinSurface;
+  /** Current pin state; `undefined` means docked-default. */
+  pin?: PinState;
+  /** Callback fired with the next pin state (null = clear). */
+  onChange: (surface: ChromePinSurface, pin: PinState | null) => void;
+  /** Human label rendered next to the status chip. */
+  label: string;
+  /** Optional test id override. */
+  "data-testid"?: string;
+  /** Optional className spliced onto the root. */
+  className?: string;
+}
+
+/**
+ * Compact grip + Float/Dock toggle row.  Consumers mount this inline
+ * above the surface's content; when `pin.detached === true` the consumer
+ * translates the surface by `pin.offset.x / y` itself (the handle does
+ * not wrap the payload).
+ */
+export function TwDetachHandle(props: TwDetachHandleProps): React.JSX.Element {
+  const { surface, pin, onChange, label } = props;
+  const isDetached = pin?.detached ?? false;
+  const offset = pin?.offset ?? { x: 0, y: 0 };
+  const dragState = useRef<
+    | {
+        startX: number;
+        startY: number;
+        originX: number;
+        originY: number;
+      }
+    | null
+  >(null);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return undefined;
+    }
+
+    const handleMove = (event: MouseEvent) => {
+      if (!dragState.current) return;
+      const nextX =
+        dragState.current.originX + (event.clientX - dragState.current.startX);
+      const nextY =
+        dragState.current.originY + (event.clientY - dragState.current.startY);
+      onChange(surface, { detached: true, offset: { x: nextX, y: nextY } });
+    };
+
+    const handleUp = () => {
+      dragState.current = null;
+    };
+
+    window.addEventListener("mousemove", handleMove);
+    window.addEventListener("mouseup", handleUp);
+    return () => {
+      window.removeEventListener("mousemove", handleMove);
+      window.removeEventListener("mouseup", handleUp);
+    };
+  }, [onChange, surface]);
+
+  const beginDrag = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      preserveEditorSelectionMouseDown(event);
+      dragState.current = {
+        startX: event.clientX,
+        startY: event.clientY,
+        originX: isDetached ? offset.x : 0,
+        originY: isDetached ? offset.y : 0,
+      };
+      if (!isDetached) {
+        onChange(surface, { detached: true, offset: { x: 0, y: 0 } });
+      }
+    },
+    [isDetached, offset.x, offset.y, onChange, surface],
+  );
+
+  const toggle = useCallback(() => {
+    if (isDetached) {
+      onChange(surface, null);
+    } else {
+      onChange(surface, { detached: true, offset: { x: 0, y: 0 } });
+    }
+  }, [isDetached, onChange, surface]);
+
+  return (
+    <div
+      className={[
+        "inline-flex items-center gap-1.5 self-center rounded-lg border border-border/70 bg-canvas/94 px-1.5 py-1 shadow-[0_8px_20px_-18px_var(--color-shadow-strong)]",
+        props.className ?? "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      data-testid={props["data-testid"] ?? `detach-handle-${surface}`}
+      data-surface={surface}
+    >
+      <button
+        type="button"
+        aria-label={isDetached ? "Drag floating menu" : "Drag to float menu"}
+        data-testid={`${surface}-detach-drag-handle`}
+        className="inline-flex h-6 items-center justify-center rounded-md border border-transparent px-1.5 text-tertiary transition-colors hover:border-border/60 hover:bg-surface hover:text-primary"
+        onMouseDown={beginDrag}
+      >
+        <GripHorizontal className="h-3 w-3" />
+      </button>
+      <span className="text-[9px] font-semibold uppercase tracking-[0.12em] text-tertiary">
+        {label}
+      </span>
+      <span className="rounded-full bg-surface px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-[0.08em] text-secondary">
+        {isDetached ? "Floating" : "Docked"}
+      </span>
+      <button
+        type="button"
+        aria-label={isDetached ? "Dock menu" : "Float menu"}
+        aria-pressed={isDetached}
+        data-testid={`${surface}-detach-toggle`}
+        className="inline-flex h-6 items-center rounded-md border border-border/60 px-2 text-[10px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary"
+        onMouseDown={preserveEditorSelectionMouseDown}
+        onClick={toggle}
+      >
+        {isDetached ? "Dock menu" : "Float menu"}
+      </button>
+    </div>
+  );
+}
+
+export default TwDetachHandle;

package/src/ui-tailwind/chrome/tw-selection-anchor-resolver.ts

@@ -0,0 +1,163 @@
+/**
+ * Selection anchor resolver — pure helper that turns a runtime selection
+ * into an overlay-space `RenderFrameRect` via the layout facet's render-
+ * kernel anchor index.
+ *
+ * Replaces the DOM-rect + zoomScale math that lived in
+ * `tw-review-workspace.tsx` (`resolveSelectionToolbarPlacement`, dropped
+ * in R2).  Per runtime-rendering-and-chrome-phase.md §6.2, every chrome
+ * surface reads anchors from the kernel — not DOM rects — so selection
+ * chrome stays glued to canonical positions through scroll, zoom, and
+ * predicted-text reconciliation.
+ *
+ * The resolver is intentionally pure: same facet + selection + tool kind
+ * returns the same rect.  Consumers compose it with the placement
+ * helper (`tw-selection-tool-placement.ts`) and the overlay projector.
+ */
+
+import type {
+  RenderFrameRect,
+  SelectionSnapshot,
+  TableStructureContextSnapshot,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types";
+import type {
+  ActiveImageContext,
+  ActiveObjectContext,
+  ActiveSelectionToolModel,
+} from "../../ui/headless/selection-tool-types";
+
+export interface ResolveSelectionAnchorInput {
+  facet: WordReviewEditorLayoutFacet;
+  selection: SelectionSnapshot;
+  tool: ActiveSelectionToolModel | null;
+}
+
+/**
+ * Resolve the anchor rect for the currently active selection tool.
+ *
+ * - formatting / suggestion / comment / workflow / blocked → bySelection
+ *   over the selection's from/to offsets (collapsed selections fall
+ *   through to byRuntimeOffset).
+ * - structure(image) → byBlockId when the image has a mediaId that the
+ *   engine can map back to a block; else falls through to selection.
+ * - structure(object) → same as image.
+ * - structure(table) → (byTableCell from sibling plan P4 when shipped;
+ *   today we fall back to bySelection against the selected cells' range).
+ * - structure(list) → bySelection.
+ *
+ * Returns `null` when the facet has no render kernel installed or the
+ * selection does not resolve to any anchor.
+ */
+export function resolveSelectionAnchor(
+  input: ResolveSelectionAnchorInput,
+): RenderFrameRect | null {
+  const { facet, selection, tool } = input;
+  // No kernel, no anchor — caller falls back to DOM rects in that case.
+  const frame =
+    typeof facet.getRenderFrame === "function"
+      ? facet.getRenderFrame() ?? null
+      : null;
+  if (!frame) return null;
+
+  if (!tool) {
+    return anchorForSelection(frame.anchorIndex, selection);
+  }
+
+  switch (tool.kind) {
+    case "structure-context": {
+      const structural = resolveStructuralAnchor(frame, tool);
+      if (structural) return structural;
+      return anchorForSelection(frame.anchorIndex, selection);
+    }
+    case "formatting-inline":
+    case "suggestion-review":
+    case "comment-thread":
+    case "workflow-task":
+    case "blocked-explainer":
+      return anchorForSelection(frame.anchorIndex, selection);
+    default: {
+      const _exhaustive: never = tool;
+      void _exhaustive;
+      return anchorForSelection(frame.anchorIndex, selection);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function anchorForSelection(
+  anchorIndex: import("../../api/public-types").RenderAnchorIndex,
+  selection: SelectionSnapshot,
+): RenderFrameRect | null {
+  if (selection.activeRange.kind === "node") {
+    // Node selection — snap to the node's runtime offset.
+    return anchorIndex.byRuntimeOffset(selection.activeRange.at);
+  }
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  if (from === to) {
+    return anchorIndex.byRuntimeOffset(from);
+  }
+  return anchorIndex.bySelection(from, to);
+}
+
+function resolveStructuralAnchor(
+  frame: import("../../api/public-types").RenderFrame,
+  tool: ActiveSelectionToolModel & { kind: "structure-context" },
+): RenderFrameRect | null {
+  const { anchorIndex } = frame;
+  switch (tool.structureKind) {
+    case "image":
+      return resolveImageAnchor(anchorIndex, tool.activeImage);
+    case "object":
+      return resolveObjectAnchor(anchorIndex, tool.activeObject);
+    case "table":
+      return resolveTableAnchor(frame, tool.activeTable ?? undefined);
+    case "list":
+      return null;
+  }
+}
+
+function resolveImageAnchor(
+  anchorIndex: import("../../api/public-types").RenderAnchorIndex,
+  image: ActiveImageContext | undefined,
+): RenderFrameRect | null {
+  if (!image) return null;
+  // Images are identified by mediaId; the engine emits block fragments
+  // whose blockId ties back to the image's anchor block.  When the
+  // chrome has no better handle, fall back to byBlockId(mediaId) — which
+  // may or may not match depending on the engine's mapping.  If it
+  // doesn't, the outer caller falls through to bySelection.
+  const rect = anchorIndex.byBlockId(image.mediaId);
+  return rect;
+}
+
+function resolveObjectAnchor(
+  anchorIndex: import("../../api/public-types").RenderAnchorIndex,
+  _object: ActiveObjectContext | undefined,
+): RenderFrameRect | null {
+  void anchorIndex;
+  void _object;
+  // Shape/textbox anchors don't have a stable id today; fall through to
+  // the selection path.  Sibling plan P4 adds `byTableCell` and similar
+  // precise accessors for structural objects; this lane will adopt them.
+  return null;
+}
+
+function resolveTableAnchor(
+  frame: import("../../api/public-types").RenderFrame,
+  table: TableStructureContextSnapshot | undefined,
+): RenderFrameRect | null {
+  if (!table) return null;
+  // Sibling plan P4 will expose `byTableCell(tableBlockId, row, col)`
+  // and `byTableColumnEdge` / `byTableRowEdge` on the anchor index.
+  // Today we have only `tableBlockIndex` (ordinal), so the best-effort
+  // fallback is the selection path — callers chain to `anchorForSelection`
+  // when this returns null.
+  void frame;
+  void table;
+  return null;
+}

package/src/ui-tailwind/chrome/tw-selection-tool-host.tsx

@@ -1,11 +1,14 @@
-import React, { useEffect, useRef, useState, type CSSProperties, type FocusEventHandler, type Ref } from "react";
+import React, { useCallback, type CSSProperties, type FocusEventHandler, type Ref } from "react";
 
-import { GripHorizontal } from "lucide-react";
-
-import type { RuntimeContextAnalyticsSnapshot } from "../../api/public-types";
+import type {
+  ChromePinsState,
+  ChromePinSurface,
+  PinState,
+  RuntimeContextAnalyticsSnapshot,
+} from "../../api/public-types";
 import type { ActiveSelectionToolModel } from "../../ui/headless/selection-tool-types";
-import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
 import { TwContextAnalyticsSummary } from "./tw-context-analytics-summary";
+import { TwDetachHandle } from "./tw-detach-handle";
 import { TwSelectionToolBlocked } from "./tw-selection-tool-blocked";
 import { TwSelectionToolComment } from "./tw-selection-tool-comment";
 import { TwSelectionToolFormatting } from "./tw-selection-tool-formatting";
@@ -22,6 +25,13 @@ export interface TwSelectionToolHostProps {
   tool: ActiveSelectionToolModel | null;
   contextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
   placement: SelectionToolPlacement | null;
+  /**
+   * Chrome pin state (R2.3) — selection-tier detach/float persistence
+   * rides ViewState.chromePins.selectionTier so pinned tools survive
+   * snapshot rebuilds.  When absent, the host renders non-pinnable.
+   */
+  chromePins?: ChromePinsState;
+  onChromePinChange?: (surface: ChromePinSurface, pin: PinState | null) => void;
   rootRef?: Ref<HTMLDivElement>;
   onFocusCapture?: FocusEventHandler<HTMLDivElement>;
   onBlurCapture?: FocusEventHandler<HTMLDivElement>;
@@ -62,48 +72,22 @@ export function TwSelectionToolHost(props: TwSelectionToolHostProps) {
     return null;
   }
 
-  const [isDetached, setIsDetached] = useState(false);
-  const [detachedOffset, setDetachedOffset] = useState({ x: 0, y: 0 });
-  const dragStateRef = useRef<{
-    startX: number;
-    startY: number;
-    originX: number;
-    originY: number;
-  } | null>(null);
-  const supportsTopMenuControls = isTopMenuKind(props.tool.kind);
-
-  useEffect(() => {
-    setIsDetached(false);
-    setDetachedOffset({ x: 0, y: 0 });
-    dragStateRef.current = null;
-  }, [props.tool.kind]);
-
-  useEffect(() => {
-    if (!supportsTopMenuControls || typeof window === "undefined") {
-      return;
-    }
-
-    const handleMouseMove = (event: MouseEvent) => {
-      if (!dragStateRef.current) {
-        return;
-      }
-      setDetachedOffset({
-        x: dragStateRef.current.originX + (event.clientX - dragStateRef.current.startX),
-        y: dragStateRef.current.originY + (event.clientY - dragStateRef.current.startY),
-      });
-    };
+  // R2.3: pin state now rides ViewState.chromePins.selectionTier so
+  // pinned tools survive snapshot rebuilds.  When the host doesn't pass
+  // chromePins/onChromePinChange, the detach handle is suppressed (same
+  // as the pre-R2 behavior for tool kinds without the handle).
+  const pin = props.chromePins?.selectionTier;
+  const isDetached = pin?.detached ?? false;
+  const detachedOffset = pin?.offset ?? { x: 0, y: 0 };
+  const supportsDetach =
+    supportsDetachForKind(props.tool.kind) && Boolean(props.onChromePinChange);
 
-    const handleMouseUp = () => {
-      dragStateRef.current = null;
-    };
-
-    window.addEventListener("mousemove", handleMouseMove);
-    window.addEventListener("mouseup", handleMouseUp);
-    return () => {
-      window.removeEventListener("mousemove", handleMouseMove);
-      window.removeEventListener("mouseup", handleMouseUp);
-    };
-  }, [supportsTopMenuControls]);
+  const handlePinChange = useCallback(
+    (surface: ChromePinSurface, next: PinState | null) => {
+      props.onChromePinChange?.(surface, next);
+    },
+    [props.onChromePinChange], // eslint-disable-line react-hooks/exhaustive-deps
+  );
 
   const overlayTestId = getOverlayTestId(props.tool.kind, Boolean(props.placement));
   const toolContent = renderTool(props, props.tool);
@@ -124,56 +108,25 @@ export function TwSelectionToolHost(props: TwSelectionToolHostProps) {
       {toolContent}
     </div>
   ) : null;
-  const wrappedContent = content && supportsTopMenuControls ? (
-    <div className="flex flex-col gap-1">
-      <div className="inline-flex items-center gap-1.5 self-center rounded-lg border border-border/70 bg-canvas/94 px-1.5 py-1 shadow-[0_8px_20px_-18px_var(--color-shadow-strong)]">
-        <button
-          type="button"
-          aria-label={isDetached ? "Drag floating menu" : "Drag to float menu"}
-          data-testid="selection-tool-drag-handle"
-          className="inline-flex h-6 items-center justify-center rounded-md border border-transparent px-1.5 text-tertiary transition-colors hover:border-border/60 hover:bg-surface hover:text-primary"
-          onMouseDown={(event) => {
-            preserveEditorSelectionMouseDown(event);
-            setIsDetached(true);
-            dragStateRef.current = {
-              startX: event.clientX,
-              startY: event.clientY,
-              originX: isDetached ? detachedOffset.x : 0,
-              originY: isDetached ? detachedOffset.y : 0,
-            };
-          }}
-        >
-          <GripHorizontal className="h-3 w-3" />
-        </button>
-        <span className="text-[9px] font-semibold uppercase tracking-[0.12em] text-tertiary">
-          {getTopMenuLabel(props.tool.kind)}
-        </span>
-        <span className="rounded-full bg-surface px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-[0.08em] text-secondary">
-          {isDetached ? "Floating" : "Docked"}
-        </span>
-        <button
-          type="button"
-          aria-label={isDetached ? "Dock menu" : "Float menu"}
-          aria-pressed={isDetached}
-          data-testid="selection-tool-attach-toggle"
-          className="inline-flex h-6 items-center rounded-md border border-border/60 px-2 text-[10px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary"
-          onMouseDown={preserveEditorSelectionMouseDown}
-          onClick={() => {
-            setIsDetached((current) => !current);
-          }}
-        >
-          {isDetached ? "Dock menu" : "Float menu"}
-        </button>
+  const wrappedContent =
+    content && supportsDetach ? (
+      <div className="flex flex-col gap-1">
+        <TwDetachHandle
+          surface="selectionTier"
+          pin={pin}
+          onChange={handlePinChange}
+          label={getTopMenuLabel(props.tool.kind)}
+          data-testid={`selection-tool-detach-${props.tool.kind}`}
+        />
+        {content}
       </div>
-      {content}
-    </div>
-  ) : content;
+    ) : content;
 
   if (!wrappedContent) {
     return null;
   }
 
-  if (isDetached) {
+  if (isDetached && supportsDetach) {
     return (
       <div className="pointer-events-none absolute inset-0 z-20" data-testid={overlayTestId}>
         <div
@@ -285,8 +238,14 @@ function getOverlayTestId(kind: ActiveSelectionToolModel["kind"], hasPlacement:
   }
 }
 
-function isTopMenuKind(kind: ActiveSelectionToolModel["kind"]): boolean {
-  return kind === "formatting-inline" || kind === "suggestion-review" || kind === "workflow-task";
+/**
+ * R2.3: the detach affordance lands on every selection tier that has
+ * interactive chrome.  `blocked-explainer` remains non-detachable —
+ * it's a status-only surface that should dismiss when the selection
+ * changes, not get pinned.
+ */
+function supportsDetachForKind(kind: ActiveSelectionToolModel["kind"]): boolean {
+  return kind !== "blocked-explainer";
 }
 
 function getTopMenuLabel(kind: ActiveSelectionToolModel["kind"]): string {
@@ -297,6 +256,12 @@ function getTopMenuLabel(kind: ActiveSelectionToolModel["kind"]): string {
       return "Suggestion";
     case "workflow-task":
       return "Workflow";
+    case "structure-context":
+      return "Structure";
+    case "comment-thread":
+      return "Comment";
+    case "blocked-explainer":
+      return "Menu";
     default:
       return "Menu";
   }

package/src/ui-tailwind/chrome/tw-selection-tool-placement.ts

@@ -0,0 +1,149 @@
+/**
+ * Selection-tool placement helper — pure function that decides where a
+ * selection-anchored floating chrome panel renders relative to its
+ * anchor rect.
+ *
+ * Extracts the right→left→above/below decision that lived in
+ * `tw-review-workspace.tsx::resolveSelectionToolbarPlacement` so
+ * consumers can feed it render-frame rects instead of DOM rects (R2.1
+ * owns the rect production; this helper is zoom-agnostic).
+ *
+ * The output is a `SelectionToolPlacement` compatible with
+ * `tw-selection-tool-host`'s existing contract so the rewire is
+ * additive — callers that already use `SelectionToolPlacement` keep
+ * working.
+ */
+
+import type { CSSProperties } from "react";
+
+import type { RenderFrameRect } from "../../api/public-types";
+
+export interface SelectionToolPlacementDecision {
+  placement: "right" | "left" | "above" | "below";
+  style: CSSProperties;
+}
+
+export interface ResolveSelectionToolPlacementInput {
+  /** Anchor rect in overlay coordinate space. */
+  anchor: RenderFrameRect;
+  /** Container size in overlay coordinate space. */
+  container: { widthPx: number; heightPx: number };
+  /**
+   * Estimated toolbar width in px.  Defaults to a reasonable bounded
+   * window (`clamp(168, 32% of container, 260)`) so the helper can run
+   * before the toolbar measures its own width.
+   */
+  estimatedToolbarWidthPx?: number;
+  /**
+   * Estimated toolbar height in px.  Defaults to 44 (matches the
+   * legacy DOM-based math).
+   */
+  estimatedToolbarHeightPx?: number;
+  /** Edge padding in px.  Defaults to 16. */
+  edgePaddingPx?: number;
+  /** Gap between anchor and toolbar in px.  Defaults to 12. */
+  gapPx?: number;
+}
+
+const DEFAULT_EDGE_PADDING = 16;
+const DEFAULT_GAP = 12;
+const DEFAULT_TOOLBAR_HEIGHT = 44;
+const TOOLBAR_WIDTH_MIN = 168;
+const TOOLBAR_WIDTH_MAX = 260;
+const TOOLBAR_WIDTH_CONTAINER_FRACTION = 0.32;
+
+/**
+ * Decide where to render the selection-tool panel relative to its
+ * anchor.  Prefers `right` when there is clearance, falls back to
+ * `left`, then `above` / `below` based on vertical room.
+ *
+ * Returns `null` when the container is zero-sized (the caller should
+ * then skip rendering entirely).
+ */
+export function resolveSelectionToolPlacement(
+  input: ResolveSelectionToolPlacementInput,
+): SelectionToolPlacementDecision | null {
+  const { anchor, container } = input;
+  if (container.widthPx <= 0 || container.heightPx <= 0) return null;
+
+  const edgePadding = input.edgePaddingPx ?? DEFAULT_EDGE_PADDING;
+  const gapPx = input.gapPx ?? DEFAULT_GAP;
+  const toolbarHeight = input.estimatedToolbarHeightPx ?? DEFAULT_TOOLBAR_HEIGHT;
+  const toolbarWidth =
+    input.estimatedToolbarWidthPx ??
+    Math.min(
+      TOOLBAR_WIDTH_MAX,
+      Math.max(
+        TOOLBAR_WIDTH_MIN,
+        container.widthPx * TOOLBAR_WIDTH_CONTAINER_FRACTION,
+      ),
+    );
+
+  const anchorLeft = anchor.leftPx;
+  const anchorRight = anchor.leftPx + anchor.widthPx;
+  const anchorTop = anchor.topPx;
+  const anchorBottom = anchor.topPx + anchor.heightPx;
+  const centerX = anchorLeft + anchor.widthPx / 2;
+  const centerY = anchorTop + anchor.heightPx / 2;
+
+  const rightClearance = container.widthPx - anchorRight - gapPx - edgePadding;
+  const leftClearance = anchorLeft - gapPx - edgePadding;
+
+  const clampedCenterX = Math.max(
+    edgePadding,
+    Math.min(
+      centerX,
+      Math.max(edgePadding, container.widthPx - edgePadding),
+    ),
+  );
+  const clampedCenterY = Math.max(
+    edgePadding + toolbarHeight / 2,
+    Math.min(
+      centerY,
+      Math.max(
+        edgePadding + toolbarHeight / 2,
+        container.heightPx - edgePadding - toolbarHeight / 2,
+      ),
+    ),
+  );
+  const maxWidthPx = Math.max(220, container.widthPx - edgePadding * 2);
+
+  if (rightClearance >= toolbarWidth) {
+    return {
+      placement: "right",
+      style: {
+        left: `${anchorRight}px`,
+        top: `${clampedCenterY}px`,
+        maxWidth: `${maxWidthPx}px`,
+        transform: `translate(${gapPx}px, -50%)`,
+      },
+    };
+  }
+
+  if (leftClearance >= toolbarWidth) {
+    return {
+      placement: "left",
+      style: {
+        left: `${anchorLeft}px`,
+        top: `${clampedCenterY}px`,
+        maxWidth: `${maxWidthPx}px`,
+        transform: `translate(calc(-100% - ${gapPx}px), -50%)`,
+      },
+    };
+  }
+
+  const placement: "above" | "below" =
+    anchorTop < toolbarHeight + gapPx + edgePadding ? "below" : "above";
+  return {
+    placement,
+    style: {
+      left: `${clampedCenterX}px`,
+      top: `${placement === "above" ? anchorTop : anchorBottom}px`,
+      maxWidth: `${maxWidthPx}px`,
+      transform:
+        placement === "above"
+          ? `translate(-50%, calc(-100% - ${gapPx}px))`
+          : `translate(-50%, ${gapPx}px)`,
+    },
+  };
+}