@beyondwork/docx-react-component 1.0.36 → 1.0.38

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)`,
+    },
+  };
+}

package/src/ui-tailwind/chrome/tw-selection-toolbar.tsx

@@ -22,6 +22,15 @@ export interface TwSelectionToolbarProps {
 const focusRingClass =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
 
+/**
+ * Fallback colors for the selection-toolbar one-click apply buttons.
+ * The model can override via `textColorDefault` / `highlightColorDefault`
+ * which R2.5 plumbs through from `formattingState` so the apply button
+ * reflects the user's recent color pick.
+ */
+const DEFAULT_TEXT_COLOR = "#1660a8";
+const DEFAULT_HIGHLIGHT_COLOR = "#ffff00";
+
 export const TwSelectionToolbar = forwardRef<HTMLDivElement, TwSelectionToolbarProps>(function TwSelectionToolbar(props, ref) {
   const { model } = props;
   const addCommentDisabled = !model.canAddComment;
@@ -64,17 +73,19 @@ export const TwSelectionToolbar = forwardRef<HTMLDivElement, TwSelectionToolbarP
       />
       <ToolbarActionButton
         icon={<Baseline className="h-3.5 w-3.5" />}
-        label="Text color blue"
+        label={`Apply ${model.textColorDefault ?? DEFAULT_TEXT_COLOR}`}
         pressed={false}
         disabled={formattingDisabled}
-        onClick={() => props.onSetTextColor?.("#1660a8")}
+        onClick={() => props.onSetTextColor?.(model.textColorDefault ?? DEFAULT_TEXT_COLOR)}
       />
       <ToolbarActionButton
         icon={<Highlighter className="h-3.5 w-3.5" />}
-        label="Highlight yellow"
+        label={`Apply ${model.highlightColorDefault ?? DEFAULT_HIGHLIGHT_COLOR} highlight`}
         pressed={false}
         disabled={formattingDisabled}
-        onClick={() => props.onSetHighlightColor?.("#ffff00")}
+        onClick={() =>
+          props.onSetHighlightColor?.(model.highlightColorDefault ?? DEFAULT_HIGHLIGHT_COLOR)
+        }
       />
 
       <div className="mx-0.5 h-4 w-px bg-border" />