@beyondwork/docx-react-component 1.0.55 → 1.0.57

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

@@ -20,6 +20,7 @@
  */
 
 import * as React from "react";
+import { X } from "lucide-react";
 import type {
   EditorRole,
   IssueMetadataValue,
@@ -148,13 +149,25 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
   const headerId = React.useId();
   const liveRegionId = React.useId();
 
-  // --- Focus management ----------------------------------------------------
+  // Cached focusable list — populated on mount and on subtree mutations so
+  // Tab handler never calls getFocusable() per-keystroke (perf §7).
+  const focusablesRef = React.useRef<HTMLElement[]>([]);
+
+  // --- Focus management + focusable cache init ----------------------------
   React.useEffect(() => {
     const root = rootRef.current;
     if (!root) return undefined;
-    const first = getFocusable(root)[0];
+
+    const refresh = () => { focusablesRef.current = getFocusable(root); };
+    refresh();
+
+    const observer = new MutationObserver(refresh);
+    observer.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ["disabled", "hidden", "inert"] });
+
+    const first = focusablesRef.current[0];
     first?.focus();
-    return undefined;
+
+    return () => observer.disconnect();
   }, []);
 
   // --- Escape + click-outside ---------------------------------------------
@@ -183,18 +196,17 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
     };
   }, [onClose, pinned]);
 
-  // --- Focus trap ----------------------------------------------------------
+  // --- Focus trap (reads cached list — no DOM query per Tab) --------------
   const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
     if (event.key !== "Tab") return;
-    const root = rootRef.current;
-    if (!root) return;
-    const focusables = getFocusable(root);
+    const focusables = focusablesRef.current;
     if (focusables.length === 0) return;
     const first = focusables[0];
     const last = focusables[focusables.length - 1];
     const active = document.activeElement;
+    const root = rootRef.current;
     if (event.shiftKey) {
-      if (active === first || !root.contains(active)) {
+      if (active === first || !root?.contains(active)) {
         event.preventDefault();
         last.focus();
       }
@@ -266,7 +278,7 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
             onClick={onClose}
             data-testid="scope-card-close"
           >
-            ×
+            <X className="h-3.5 w-3.5" aria-hidden="true" />
           </button>
         </div>
       </div>
@@ -614,9 +626,17 @@ function formatRelative(isoString: string): string {
 function getFocusable(root: HTMLElement): HTMLElement[] {
   const selector =
     'button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])';
-  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter(
-    (el) => !el.hasAttribute("inert") && el.offsetParent !== null,
-  );
+  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter((el) => {
+    if (el.hasAttribute("inert")) return false;
+    // Walk the ancestor chain for visibility/display — tolerates display:contents.
+    let node: HTMLElement | null = el;
+    while (node && node !== root) {
+      const s = getComputedStyle(node);
+      if (s.display === "none" || s.visibility === "hidden") return false;
+      node = node.parentElement;
+    }
+    return true;
+  });
 }
 
 function posturePresentationLabel(posture: ScopeCardModel["posture"]): string {

package/src/ui-tailwind/chrome-overlay/tw-toc-outline-sidebar.tsx

@@ -0,0 +1,133 @@
+/**
+ * Lane 6d — Slice N8: TOC outline sidebar (P11.8).
+ *
+ * Renders the formal TOC field entries from `getTocSnapshot()` as a
+ * collapsible left panel.  Unlike the heading-based nav panel (which
+ * uses `DocumentNavigationSnapshot.headings`), this sidebar reflects the
+ * actual `<w:sdt>` / `TOC` field content — complete with the document
+ * author's chosen heading levels, custom styles, and page numbers.
+ *
+ * Navigation: clicking an entry calls `onNavigate(entry)`.  The host
+ * is responsible for resolving `entry.anchor` or `entry.bookmarkName`
+ * into a runtime scroll (typically via `runtime.setSelection` or
+ * `onNavigateHeading(entry.headingId)`).
+ *
+ * `status === "stale"` shows a banner so the reviewer knows the TOC
+ * needs a refresh before page numbers are reliable.
+ */
+
+import React from "react";
+import type { TocSnapshot, TocEntrySnapshot } from "../../api/public-types";
+
+export interface TwTocOutlineSidebarProps {
+  /** `null` when the document has no TOC field. */
+  tocSnapshot: TocSnapshot | null;
+  /** Called when the user clicks a TOC entry. */
+  onNavigate: (entry: TocEntrySnapshot) => void;
+  /** Whether the sidebar is currently open. */
+  open: boolean;
+  /** Called when the close button is pressed. */
+  onClose: () => void;
+}
+
+/**
+ * Indentation step per outline level (px).  Levels start at 1 so
+ * level-1 gets 0 extra indentation; level-2 gets 12 px, etc.
+ */
+const INDENT_PX_PER_LEVEL = 12;
+
+export function TwTocOutlineSidebar({
+  tocSnapshot,
+  onNavigate,
+  open,
+  onClose,
+}: TwTocOutlineSidebarProps): React.ReactElement | null {
+  if (!open) return null;
+
+  const entries = tocSnapshot?.entries ?? [];
+  const isStale = tocSnapshot?.status === "stale";
+
+  return (
+    <aside
+      aria-label="Table of contents"
+      data-toc-sidebar=""
+      className="flex h-full w-56 shrink-0 flex-col border-r border-border bg-surface"
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between border-b border-border px-3 py-2">
+        <span className="text-xs font-medium uppercase tracking-wider text-secondary">
+          Table of Contents
+        </span>
+        <button
+          type="button"
+          aria-label="Close table of contents"
+          data-toc-close=""
+          onClick={onClose}
+          className="inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface-hover"
+        >
+          {/* ×  */}
+          <svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+            <path d="M1 1l10 10M11 1L1 11" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+          </svg>
+        </button>
+      </div>
+
+      {/* Stale banner */}
+      {isStale ? (
+        <div
+          role="status"
+          data-toc-stale=""
+          className="border-b border-border bg-[var(--color-warning-soft,theme(colors.amber.50))] px-3 py-1.5 text-[11px] text-[var(--color-warning,theme(colors.amber.700))]"
+        >
+          Table of contents may be out of date.
+        </div>
+      ) : null}
+
+      {/* Entry list */}
+      <nav
+        className="flex-1 overflow-y-auto px-2 py-2"
+        aria-label="Document outline"
+      >
+        {entries.length > 0 ? (
+          <ul className="space-y-px">
+            {entries.map((entry) => {
+              const indent = (entry.level - 1) * INDENT_PX_PER_LEVEL;
+              return (
+                <li key={entry.tocEntryId}>
+                  <button
+                    type="button"
+                    data-toc-entry-id={entry.tocEntryId}
+                    data-toc-level={entry.level}
+                    className="flex w-full items-baseline gap-1 rounded-md px-2 py-1 text-left text-xs text-primary transition-colors hover:bg-surface-hover"
+                    style={{ paddingLeft: `${8 + indent}px` }}
+                    onClick={() => onNavigate(entry)}
+                  >
+                    <span className="flex-1 truncate">{entry.text}</span>
+                    {entry.pageIndex != null ? (
+                      <span
+                        aria-label={`page ${entry.pageIndex + 1}`}
+                        className="shrink-0 tabular-nums text-tertiary"
+                      >
+                        {entry.pageIndex + 1}
+                      </span>
+                    ) : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        ) : tocSnapshot === null ? (
+          <p className="px-2 py-4 text-xs text-tertiary">
+            No table of contents found in this document.
+          </p>
+        ) : (
+          <p className="px-2 py-4 text-xs text-tertiary">
+            The table of contents is empty.
+          </p>
+        )}
+      </nav>
+    </aside>
+  );
+}
+
+export default TwTocOutlineSidebar;

package/src/ui-tailwind/editor-surface/chart-node-view.tsx

@@ -12,6 +12,7 @@
  */
 
 import React from "react";
+import { flushSync } from "react-dom";
 import { createRoot, type Root } from "react-dom/client";
 import type { Node as PMNode } from "prosemirror-model";
 import type { NodeViewConstructor } from "prosemirror-view";
@@ -24,6 +25,7 @@ const DEFAULT_HEIGHT = 336;
 class ChartNodeViewInstance {
   readonly dom: HTMLElement;
   private _root: Root | null = null;
+  private _mountedChartId: string | null = null;
 
   constructor(node: PMNode) {
     this.dom = document.createElement("span");
@@ -33,41 +35,78 @@ class ChartNodeViewInstance {
     this._mount(node);
   }
 
+  /**
+   * Mount or update the React root to render the chart whose id lives in
+   * `node.attrs.parsedChartId`. Transitions handled explicitly:
+   *
+   *   - id present, entry in store → create/reuse root, render ChartSurface.
+   *   - id present, entry missing  → unmount any prior root (don't leave a
+   *                                  stale chart from a previous id mounted).
+   *   - id null / undefined        → unmount any prior root (no chart).
+   *
+   * The previous implementation handled only the first case and silently
+   * left the prior React tree mounted on null / missing-entry transitions.
+   */
   private _mount(node: PMNode): void {
-    const parsedChartId = node.attrs.parsedChartId as string | null;
-    if (!parsedChartId) return;
+    const parsedChartId = (node.attrs.parsedChartId as string | null) ?? null;
+
+    if (!parsedChartId) {
+      this._unmountRoot();
+      return;
+    }
 
     const entry = chartModelStore.get(parsedChartId);
-    if (!entry) return;
+    if (!entry) {
+      this._unmountRoot();
+      return;
+    }
 
     const width = (node.attrs.widthPx as number | null) ?? entry.widthPx ?? DEFAULT_WIDTH;
     const height = (node.attrs.heightPx as number | null) ?? entry.heightPx ?? DEFAULT_HEIGHT;
+    const previewMediaId = node.attrs.previewMediaId as string | null;
+    const previewSrc = node.attrs.previewSrc as string | null;
 
     const el = React.createElement(ChartSurface, {
       model: entry.model,
       width,
       height,
       theme: entry.theme,
+      ...(previewMediaId ? { previewMediaId } : {}),
+      ...(previewMediaId && previewSrc
+        ? {
+            resolveMediaUrl: (mediaId: string) =>
+              mediaId === previewMediaId ? previewSrc : undefined,
+          }
+        : {}),
     });
 
     if (!this._root) {
       this._root = createRoot(this.dom);
     }
-    this._root.render(el);
+    flushSync(() => {
+      this._root?.render(el);
+    });
+    this._mountedChartId = parsedChartId;
+  }
+
+  private _unmountRoot(): void {
+    if (this._root) {
+      this._root.unmount();
+      this._root = null;
+    }
+    this._mountedChartId = null;
   }
 
   update(node: PMNode): boolean {
-    const parsedChartId = node.attrs.parsedChartId as string | null;
-    if (!parsedChartId) return false;
+    // Handle every `parsedChartId` transition in-place so PM doesn't
+    // destroy/recreate this NodeView on attr-only changes. Returning true
+    // tells PM "I handled this update."
     this._mount(node);
     return true;
   }
 
   destroy(): void {
-    if (this._root) {
-      this._root.unmount();
-      this._root = null;
-    }
+    this._unmountRoot();
   }
 
   stopEvent(): boolean {

package/src/ui-tailwind/editor-surface/float-wrap-resolver.ts

@@ -0,0 +1,119 @@
+/**
+ * Lane 6d — Slice N9 (P7.1 + P7.3): pure float-wrap resolver.
+ *
+ * Maps `SurfaceDrawingAnchor` (the V2c.4-projected DrawingFrame anchor) to
+ * a CSS-style descriptor that the `image_atom` / `shape_atom` toDOM can
+ * stamp onto the wrapper span.  Pure — no DOM access, no React, no schema
+ * dependency.
+ *
+ * v1 coverage (per the lane-6d MVP plan):
+ *   - `square`        → CSS float + `shape-outside: margin-box`
+ *   - `topAndBottom`  → block-level `clear: both`
+ *   - `none` + `behindDoc` → absolute-positioned, `z-index: -1` (behind text)
+ *   - `tight` / `through` → fall back to `square` and emit a one-shot
+ *     warn so telemetry can flag uncovered shapes.  v2 will consume
+ *     `wrapPolygon` data once Lane 3b V2c.x extends `AnchorGeometry`.
+ *
+ * EMU constant: 9525 EMU = 1 px at 96 dpi (OOXML standard).
+ */
+
+import type { SurfaceDrawingAnchor } from "../../api/public-types";
+import { EMU_PER_PX } from "../../runtime/units";
+
+export interface FloatWrapStyle {
+  /** CSS `float` value when the anchor wraps inline text. */
+  float?: "left" | "right";
+  /** CSS `shape-outside` for `square` wrap so adjacent text honors the
+   * picture's margin box. */
+  shapeOutside?: string;
+  /** CSS `clear` — set on `topAndBottom` so the picture renders on its
+   * own line. */
+  clear?: "both";
+  /** Block-level signal for `topAndBottom` so the wrapper switches from
+   * inline-block to block. */
+  display?: "block";
+  /** Absolute positioning — used for `behindDoc` shapes that sit beneath
+   * content. */
+  positionAbsolute?: { topPx: number; leftPx: number; zIndex: number };
+  /** When the resolver fell back to a default for an unsupported wrap
+   * mode, this carries the original mode for telemetry. */
+  fallbackFromMode?: "tight" | "through";
+}
+
+const warnedFallbacks = new Set<string>();
+
+/**
+ * Emit a one-shot console warning per wrap mode so noisy CCEP corpora
+ * don't flood the console but coverage gaps still surface.  Skips SSR
+ * (no `window`) so server-render passes don't spam logs.
+ */
+function warnFallbackOnce(mode: "tight" | "through"): void {
+  if (warnedFallbacks.has(mode)) return;
+  warnedFallbacks.add(mode);
+  if (typeof window === "undefined") return;
+  // Quiet by default — only fires once per mode per session.
+  console.warn(
+    `[lane-6d/N9] wrapMode="${mode}" rendered as "square" v1 fallback (polygon clipping pending Lane 3b V2c.x).`,
+  );
+}
+
+/**
+ * Reset the fallback warn dedup map.  Test-only helper — production code
+ * never calls this.
+ */
+export function _resetFloatWrapWarnings(): void {
+  warnedFallbacks.clear();
+}
+
+/**
+ * Pure resolver: anchor → CSS-style descriptor.  Returns `null` when
+ * the anchor is inline (no float treatment needed) or has no wrapMode.
+ */
+export function resolveFloatStyle(
+  anchor: SurfaceDrawingAnchor | undefined,
+): FloatWrapStyle | null {
+  if (!anchor) return null;
+  if (anchor.display !== "floating") return null;
+
+  switch (anchor.wrapMode) {
+    case "square": {
+      const float = anchor.positionH?.align === "right" ? "right" : "left";
+      return { float, shapeOutside: "margin-box" };
+    }
+    case "topAndBottom":
+      return { clear: "both", display: "block" };
+    case "tight":
+      warnFallbackOnce("tight");
+      return {
+        float: anchor.positionH?.align === "right" ? "right" : "left",
+        shapeOutside: "margin-box",
+        fallbackFromMode: "tight",
+      };
+    case "through":
+      warnFallbackOnce("through");
+      return {
+        float: anchor.positionH?.align === "right" ? "right" : "left",
+        shapeOutside: "margin-box",
+        fallbackFromMode: "through",
+      };
+    case "none": {
+      // `none` + behindDoc → absolute positioned underneath the text.
+      // `none` + !behindDoc → above text (in front).  Either way we use
+      // absolute positioning when offsets are present.
+      if (
+        anchor.positionH?.offset !== undefined ||
+        anchor.positionV?.offset !== undefined
+      ) {
+        return {
+          positionAbsolute: {
+            topPx: Math.round((anchor.positionV?.offset ?? 0) / EMU_PER_PX),
+            leftPx: Math.round((anchor.positionH?.offset ?? 0) / EMU_PER_PX),
+            zIndex: anchor.behindDoc ? -1 : 1,
+          },
+        };
+      }
+      // `none` with no offsets is rare — treat as inline-overlap.
+      return null;
+    }
+  }
+}