@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/ui-tailwind/chrome/tw-command-palette-mount.tsx

@@ -0,0 +1,96 @@
+/**
+ * TwCommandPaletteMount — ready-to-use mount adapter that wires
+ * `TwCommandPalette` + `isCommandPaletteOpenShortcut` together so a
+ * host only needs to supply the command graph.
+ *
+ * design-close-chrome Phase 3 / designsystem §6.25.
+ *
+ * Why a separate mount component:
+ *   - `TwCommandPalette` is intentionally pure — no global state, no
+ *     key subscription.  That keeps it testable and composable.
+ *   - Most hosts want the Ctrl+K / Cmd+K binding, open-state
+ *     management, and click-off-to-close plumbing out of the box.
+ *   - This adapter pairs them with a single `groups` prop.  Opt-out
+ *     is trivial: use `TwCommandPalette` directly with your own open
+ *     state + key handler.
+ *
+ * The adapter:
+ *   - Subscribes to window keydown with `isCommandPaletteOpenShortcut`
+ *     (only when not already open, to let the palette own Escape/Enter).
+ *   - Calls `event.preventDefault()` so Ctrl+K does not bubble to the
+ *     browser (avoids the URL-bar focus on macOS Chrome).
+ *   - Honors a `disabled` flag so hosts can suppress the binding while
+ *     another modal captures input.
+ */
+
+import React, { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+
+import {
+  TwCommandPalette,
+  isCommandPaletteOpenShortcut,
+  type CommandPaletteGroup,
+  type TwCommandPaletteProps,
+} from "./tw-command-palette";
+
+export interface TwCommandPaletteMountProps
+  extends Omit<TwCommandPaletteProps, "open" | "onOpenChange"> {
+  /** Command graph supplied by the host. */
+  groups: readonly CommandPaletteGroup[];
+  /**
+   * When `true`, the global Ctrl+K / Cmd+K listener is suppressed so
+   * a higher-priority modal keeps keyboard focus.  Defaults to `false`.
+   */
+  disabled?: boolean;
+  /**
+   * Optional: fires when the palette's open state transitions.  Callers
+   * can use this to emit analytics or to coordinate focus with other
+   * chrome surfaces.
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Optional: the initial open state.  Defaults to `false`.  Primarily
+   * useful for Storybook / tests.
+   */
+  defaultOpen?: boolean;
+}
+
+export function TwCommandPaletteMount(props: TwCommandPaletteMountProps): ReactNode {
+  const { disabled = false, defaultOpen = false, onOpenChange, ...paletteProps } = props;
+  const [open, setOpen] = useState(defaultOpen);
+  // Ref mirrors `open` so the keydown handler can toggle without reading
+  // React state (which React 18 strict mode double-invokes inside
+  // `setState` updaters).  Fire `onOpenChange` exactly once per Ctrl+K.
+  const openRef = useRef(defaultOpen);
+
+  const handleOpenChange = useCallback(
+    (next: boolean) => {
+      openRef.current = next;
+      setOpen(next);
+      onOpenChange?.(next);
+    },
+    [onOpenChange],
+  );
+
+  useEffect(() => {
+    if (disabled) return;
+    if (typeof window === "undefined") return;
+    const handler = (event: KeyboardEvent): void => {
+      if (!isCommandPaletteOpenShortcut(event)) return;
+      event.preventDefault();
+      // Toggle: Ctrl+K with palette open dismisses it.  That matches
+      // VSCode / most IDE palettes.  Side effect (onOpenChange) lives
+      // here — NOT inside a setState updater — so React 18 strict mode
+      // cannot fire it twice for a single keypress.
+      const next = !openRef.current;
+      openRef.current = next;
+      setOpen(next);
+      onOpenChange?.(next);
+    };
+    window.addEventListener("keydown", handler);
+    return () => {
+      window.removeEventListener("keydown", handler);
+    };
+  }, [disabled, onOpenChange]);
+
+  return <TwCommandPalette {...paletteProps} open={open} onOpenChange={handleOpenChange} />;
+}

package/src/ui-tailwind/chrome/tw-context-menu.tsx

@@ -11,6 +11,7 @@
 import * as React from "react";
 
 import { TwShortcutHint, type ShortcutKey } from "./tw-shortcut-hint";
+import { FOCUS_RING_CLASSES } from "../theme/tokens";
 
 // ---------------------------------------------------------------------------
 // Dedupe context
@@ -222,7 +223,7 @@ function ContextMenuRow({ item, platform }: ContextMenuRowProps): React.JSX.Elem
         "text-[13px] text-[var(--color-text-primary)] text-left",
         "hover:bg-[var(--color-bg-hover)]",
         "disabled:opacity-40 disabled:cursor-not-allowed",
-        "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--color-accent)]",
+        FOCUS_RING_CLASSES,
       ].join(" ")}
     >
       <span className="flex items-center gap-2 min-w-0">

package/src/ui-tailwind/chrome/tw-image-context-toolbar.tsx

@@ -2,6 +2,7 @@ import React from "react";
 
 import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
 import type { ActiveImageContext } from "../../ui/headless/selection-tool-types";
+import { EMU_PER_INCH } from "../../runtime/units.ts";
 
 export interface TwImageContextToolbarProps {
   activeImage: ActiveImageContext;
@@ -17,10 +18,10 @@ export interface TwImageContextToolbarProps {
 }
 
 const IMAGE_SIZE_PRESETS = [
-  { label: "Small image", widthEmu: 1828800, heightEmu: 914400 },
-  { label: "Medium image", widthEmu: 2743200, heightEmu: 1371600 },
-  { label: "Large image", widthEmu: 3657600, heightEmu: 1828800 },
-] as const;
+  { label: "Small image", widthEmu: 2 * EMU_PER_INCH, heightEmu: 1 * EMU_PER_INCH },
+  { label: "Medium image", widthEmu: 3 * EMU_PER_INCH, heightEmu: 1.5 * EMU_PER_INCH },
+  { label: "Large image", widthEmu: 4 * EMU_PER_INCH, heightEmu: 2 * EMU_PER_INCH },
+];
 
 const NUDGE_EMU = 228600;
 

package/src/ui-tailwind/chrome/tw-mode-dock.tsx

@@ -1,5 +1,7 @@
 import React, { type ReactNode } from "react";
 
+import { FOCUS_RING_CLASSES } from "../theme/tokens";
+
 export interface TwModeDockAction {
   id: string;
   label: string;
@@ -15,8 +17,10 @@ export interface TwModeDockProps {
   className?: string;
 }
 
-const focusRingClass =
-  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-canvas";
+// TwModeDock is a deprecated harness-only surface per designsystem §6.26,
+// but its focus ring still participates in the canonical §4.7 contract —
+// import the shared token constant so a future ring update cascades here.
+const focusRingClass = FOCUS_RING_CLASSES;
 
 export function TwModeDock(props: TwModeDockProps) {
   const actions = (props.actions ?? []).slice(0, 3);

package/src/ui-tailwind/chrome/use-container-breakpoint.ts

@@ -0,0 +1,111 @@
+/**
+ * useContainerBreakpoint — rAF-coalesced ResizeObserver hook that
+ * resolves to a named breakpoint based on a monitored element's
+ * `contentRect.width`.
+ *
+ * Motivation: the shipped `responsive-chrome.ts` compact-mode hook is
+ * viewport-driven (single threshold), so a toolbar inside a narrow
+ * split-pane renders at full width even when its container is small.
+ * Container-driven breakpoints fix this — the toolbar responds to its
+ * own box, not the page.
+ *
+ * Perf discipline (CLAUDE.md §Performance Invariants #1 + #7):
+ *   - The ResizeObserver callback MUST NOT call getBoundingClientRect
+ *     or any offset/client read.  It only reads `entry.contentRect.width`
+ *     (which is already laid-out and cached by the browser's observer
+ *     implementation).
+ *   - State updates are coalesced inside `requestAnimationFrame` so
+ *     multiple rapid resizes collapse into one render, and the new
+ *     measurement never drives a synchronous paint.
+ *
+ * Usage:
+ *
+ *   const ref = useRef<HTMLDivElement | null>(null);
+ *   const bp = useContainerBreakpoint(ref, { compact: 0, wide: 720 });
+ *   return <div ref={ref} data-breakpoint={bp}>...</div>;
+ *
+ * Thresholds map `width` to the highest-named breakpoint whose
+ * threshold is ≤ width.  Every map MUST include `0` as one of its
+ * thresholds so every width resolves to some name.
+ */
+
+import { useEffect, useMemo, useRef, useState } from "react";
+
+export type BreakpointMap = Readonly<Record<string, number>>;
+
+/**
+ * Resolve a width to the highest-named breakpoint whose threshold is
+ * ≤ width.  Exported for unit testing and for callers that already own
+ * the width and just want the mapping logic.
+ */
+export function resolveBreakpoint<T extends BreakpointMap>(
+  width: number,
+  thresholds: T,
+): keyof T | null {
+  let best: keyof T | null = null;
+  let bestThreshold = -Infinity;
+  for (const name of Object.keys(thresholds) as (keyof T)[]) {
+    const t = thresholds[name] as number;
+    if (width >= t && t > bestThreshold) {
+      best = name;
+      bestThreshold = t;
+    }
+  }
+  return best;
+}
+
+export function useContainerBreakpoint<T extends BreakpointMap>(
+  ref: React.RefObject<HTMLElement | null>,
+  thresholds: T,
+  initial: keyof T | null = null,
+): keyof T | null {
+  const [breakpoint, setBreakpoint] = useState<keyof T | null>(initial);
+  const rafRef = useRef<number | null>(null);
+  const latestWidthRef = useRef<number | null>(null);
+
+  // R8 — stringify thresholds into a stable deps key so inline
+  // literals (e.g. `{ compact: 0, wide: 720 }` declared in JSX) do
+  // not destroy + recreate the ResizeObserver on every render.  The
+  // stringify cost is a single pass over a ~3-key object when the
+  // caller's identity changes, which is what we want.
+  const depsKey = useMemo(() => JSON.stringify(thresholds), [thresholds]);
+  // Thresholds snapshot that the effect reads — captured at subscription
+  // time so the observer callback uses the values that corresponded to
+  // the current subscription.
+  const thresholdsRef = useRef(thresholds);
+  thresholdsRef.current = thresholds;
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+
+    const observer = new ResizeObserver((entries) => {
+      // Read-only access to contentRect; no layout-triggering calls.
+      const entry = entries[entries.length - 1];
+      if (!entry) return;
+      latestWidthRef.current = entry.contentRect.width;
+      if (rafRef.current !== null) return;
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = null;
+        const w = latestWidthRef.current;
+        if (w === null) return;
+        const next = resolveBreakpoint(w, thresholdsRef.current);
+        setBreakpoint((prev) => (prev === next ? prev : next));
+      });
+    });
+
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    };
+    // depsKey is the stable projection of `thresholds`; `ref` is an
+    // object reference that callers typically hold stable via useRef.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ref, depsKey]);
+
+  return breakpoint;
+}

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -25,9 +25,9 @@ import type {
 } from "../../api/public-types";
 import { TwScopeRailLayer } from "./tw-scope-rail-layer";
 import { TwScopeCardLayer } from "./tw-scope-card-layer";
-import { TwPageStackOverlayLayer } from "./tw-page-stack-overlay-layer";
 import { TwPageStackChromeLayer, type PmPortalView } from "../page-stack/tw-page-stack-chrome-layer";
 import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
+import { TwObjectSelectionOverlay } from "./tw-object-selection-overlay";
 
 export interface TwChromeOverlayProps {
   /** Layout facet the overlay layers read from. */
@@ -93,6 +93,16 @@ export interface TwChromeOverlayProps {
   /** Optional extra children (e.g., future comment balloon layer). */
   children?: React.ReactNode;
 
+  // Object selection overlay (N6) ----------------------------------------
+  /** R.3 — grabbed image/shape id, or null. When set, the selection overlay renders. */
+  grabbedObjectId?: string | null;
+  /** Document `from` offset of the grabbed segment (for anchor-index lookup). */
+  grabbedObjectFromOffset?: number | null;
+  /** Document `to` offset of the grabbed segment. */
+  grabbedObjectToOffset?: number | null;
+  /** Called when the user clicks outside the selection box to deselect. */
+  onDeselectObject?: () => void;
+
   // Table grip props (P6) -----------------------------------------------
   /** Active table context — when present, column/row resize grips are shown. */
   tableContext?: TableStructureContextSnapshot | null;
@@ -187,6 +197,10 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   scopeCardScopeTagEditor,
   "data-testid": testId,
   children,
+  grabbedObjectId,
+  grabbedObjectFromOffset,
+  grabbedObjectToOffset,
+  onDeselectObject,
   tableContext,
   onSetColumnWidth,
   onSetRowHeight,
@@ -204,14 +218,6 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
       data-testid={testId ?? "chrome-overlay"}
       role="presentation"
     >
-      {pageStackScrollRoot !== undefined ? (
-        <TwPageStackOverlayLayer
-          facet={facet}
-          scrollRoot={pageStackScrollRoot}
-          renderFrameRevision={renderFrameRevision ?? 0}
-          visiblePageIndexRange={visiblePageIndexRange ?? null}
-        />
-      ) : null}
       {pageStackScrollRoot !== undefined ? (
         <TwPageStackChromeLayer
           facet={facet}
@@ -251,6 +257,14 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
         onSetColumnWidth={onSetColumnWidth}
         onSetRowHeight={onSetRowHeight}
       />
+      <TwObjectSelectionOverlay
+        grabbedObjectId={grabbedObjectId ?? null}
+        grabbedObjectFromOffset={grabbedObjectFromOffset ?? null}
+        grabbedObjectToOffset={grabbedObjectToOffset ?? null}
+        facet={facet}
+        space={space}
+        onDeselect={onDeselectObject}
+      />
       {children}
     </div>
   );

package/src/ui-tailwind/chrome-overlay/tw-object-selection-overlay.tsx

@@ -0,0 +1,158 @@
+/**
+ * Lane 6d — N6 P11.1–P11.5: object selection chrome overlay.
+ *
+ * Renders a selection box with 8 resize handles and a rotate grip around the
+ * grabbed image or shape.  Purely visual chrome — no resize/rotate mutations
+ * in this slice; handle interaction is deferred to the follow-up N6.b slice.
+ *
+ * Positioning: uses `RenderAnchorIndex.byRuntimeOffset(from)` + `bySelection`
+ * to compute the object rect in overlay-coordinate space, then paints over it.
+ *
+ * Dismissal: clicking outside the overlay calls `onDeselect()` which routes
+ * to `runtime.deselectObject()` in the workspace.
+ *
+ * v1 scope:
+ *   - rect, ellipse, roundRect shapes and inline/floating images.
+ *   - Resize handles are visual only (pointer-events-none on each handle).
+ *   - Rotate grip is visual only.
+ *   - Anchor drag indicator omitted until N6.b.
+ */
+
+import * as React from "react";
+import { useEffect, useRef } from "react";
+import type { WordReviewEditorLayoutFacet } from "../../api/public-types";
+import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
+import { projectRectToOverlay } from "./chrome-overlay-projector";
+
+/** The 8 corner/edge handle positions. */
+const HANDLE_POSITIONS = [
+  "nw", "n", "ne",
+  "w",        "e",
+  "sw", "s", "se",
+] as const;
+type HandlePosition = typeof HANDLE_POSITIONS[number];
+
+const CURSOR_MAP: Record<HandlePosition, string> = {
+  nw: "nw-resize", n: "n-resize", ne: "ne-resize",
+  w: "w-resize",               e: "e-resize",
+  sw: "sw-resize", s: "s-resize", se: "se-resize",
+};
+
+export interface TwObjectSelectionOverlayProps {
+  /** Stable id of the grabbed image/shape (mediaId or shapeId), or null. */
+  grabbedObjectId: string | null;
+  /** Document offset (`from`) of the grabbed object's inline segment. Null when no object grabbed. */
+  grabbedObjectFromOffset: number | null;
+  /** Document offset (`to`) of the grabbed object's inline segment. Null when no object grabbed. */
+  grabbedObjectToOffset: number | null;
+  /** Layout facet for render-frame + anchor-index access. */
+  facet: WordReviewEditorLayoutFacet;
+  /** Optional overlay coordinate-space override. */
+  space?: OverlayCoordinateSpace;
+  /** Called when the user clicks outside the selection box. */
+  onDeselect?: () => void;
+}
+
+export function TwObjectSelectionOverlay({
+  grabbedObjectId,
+  grabbedObjectFromOffset,
+  grabbedObjectToOffset,
+  facet,
+  space,
+  onDeselect,
+}: TwObjectSelectionOverlayProps) {
+  const overlayRef = useRef<HTMLDivElement>(null);
+
+  // Click-outside to deselect.
+  useEffect(() => {
+    if (!grabbedObjectId || !onDeselect) return;
+    function handlePointerDown(e: PointerEvent) {
+      if (overlayRef.current && !overlayRef.current.contains(e.target as Node)) {
+        onDeselect!();
+      }
+    }
+    document.addEventListener("pointerdown", handlePointerDown, { capture: true });
+    return () => document.removeEventListener("pointerdown", handlePointerDown, { capture: true });
+  }, [grabbedObjectId, onDeselect]);
+
+  if (!grabbedObjectId || grabbedObjectFromOffset == null) return null;
+
+  const frame = typeof facet.getRenderFrame === "function" ? facet.getRenderFrame() : null;
+  if (!frame) return null;
+
+  const rawRect = grabbedObjectToOffset != null
+    ? frame.anchorIndex.bySelection(grabbedObjectFromOffset, grabbedObjectToOffset)
+    : frame.anchorIndex.byRuntimeOffset(grabbedObjectFromOffset);
+  if (!rawRect) return null;
+
+  const rect = projectRectToOverlay(rawRect, space);
+
+  const boxStyle: React.CSSProperties = {
+    position: "absolute",
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+    height: rect.height,
+    outline: "2px solid var(--color-accent-primary)",
+    boxSizing: "border-box",
+    pointerEvents: "auto",
+  };
+
+  return (
+    <div
+      ref={overlayRef}
+      style={boxStyle}
+      data-chrome-overlay=""
+      data-object-selection=""
+      data-object-id={grabbedObjectId}
+      aria-label="Selected object"
+    >
+      {HANDLE_POSITIONS.map((pos) => (
+        <ObjectHandle key={pos} position={pos} />
+      ))}
+      <RotateGrip />
+    </div>
+  );
+}
+
+function ObjectHandle({ position }: { position: HandlePosition }) {
+  const HANDLE_PX = 8;
+  const half = HANDLE_PX / 2;
+  const pos = position;
+
+  const style: React.CSSProperties = {
+    position: "absolute",
+    width: HANDLE_PX,
+    height: HANDLE_PX,
+    background: "white",
+    border: "1.5px solid var(--color-accent-primary)",
+    borderRadius: 1,
+    boxSizing: "border-box",
+    cursor: CURSOR_MAP[pos],
+    // Visual only in v1 — pointer events disabled so clicks fall through to
+    // the click-outside listener which deselectObjects.
+    pointerEvents: "none",
+    ...(pos.includes("w") ? { left: -half } : pos.includes("e") ? { right: -half } : { left: "50%", transform: "translateX(-50%)" }),
+    ...(pos.includes("n") ? { top: -half } : pos.includes("s") ? { bottom: -half } : { top: "50%", transform: `${pos === "w" || pos === "e" ? "translateY(-50%)" : "translateX(-50%) translateY(-50%)"}` }),
+  };
+
+  return <div style={style} data-handle={pos} aria-hidden="true" />;
+}
+
+function RotateGrip() {
+  const style: React.CSSProperties = {
+    position: "absolute",
+    width: 10,
+    height: 10,
+    borderRadius: "50%",
+    background: "white",
+    border: "1.5px solid var(--color-accent-primary)",
+    top: -24,
+    left: "50%",
+    transform: "translateX(-50%)",
+    cursor: "grab",
+    pointerEvents: "none",
+    boxSizing: "border-box",
+  };
+  return <div style={style} data-handle="rotate" aria-hidden="true" />;
+}

package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx

@@ -628,13 +628,12 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
             height: `${rect.heightPx}px`,
             left: 0,
             right: 0,
-            // The overlay paints decorative paper-edge treatment (border
-            // + soft shadow) around each page's vertical slice.  It sits
-            // ABOVE the PM surface in stacking order so we deliberately
-            // leave `backgroundColor` unset — a filled overlay would
-            // occlude PM text.  Border + box-shadow alone give the
-            // 'distinct paper' perception without covering content.
-            backgroundColor: "transparent",
+            // N1 (L8 Phase D): this component is placed at z-0 BEFORE
+            // the z-10 PM wrapper inside `wre-page-surface`, so an opaque
+            // page background here sits behind PM text rather than on top
+            // of it.  White card + border + shadow gives the 'N distinct
+            // papers on a gray canvas' appearance.
+            backgroundColor: "var(--color-page-bg, white)",
             border: "1px solid var(--color-page-border, rgba(148,163,184,0.2))",
             borderRadius: "var(--radius-page, 4px)",
             boxShadow: