@beyondwork/docx-react-component 1.0.58 → 1.0.59

package/src/ui-tailwind/review/tw-comment-sidebar.tsx

@@ -157,6 +157,16 @@ function CommentThreadCard(props: {
   const canEdit = isOwnComment && thread.status === "open" && props.onEditBody != null;
   const hasNoBody = isEmptyCommentBody(leadEntry?.body);
   const showExcerpt = Boolean(thread.excerpt) && !isDraftThread && thread.excerpt !== "Empty thread";
+  const threadCardClassName = [
+    "rounded-lg bg-surface/90 transition-colors ring-1 ring-border",
+    isActive
+      ? "bg-accent-soft/40 ring-accent/25 shadow-[var(--shadow-soft)]"
+      : "hover:bg-surface",
+    thread.status === "detached"
+      ? "border-l-[3px] border-[var(--color-semantic-warning)] opacity-70"
+      : "",
+  ].join(" ");
+  const threadContentPaddingClass = thread.status === "detached" ? "pl-2.5 pr-3" : "px-3";
 
   const scrollRef = useCallback(
     (node: HTMLButtonElement | null) => {
@@ -168,130 +178,123 @@ function CommentThreadCard(props: {
   );
 
   return (
-    <button
-      type="button"
-      ref={scrollRef}
-      data-comment-thread-id={thread.commentId}
-      data-comment-thread-status={thread.status}
-      className={[
-        "w-full text-left cursor-pointer rounded-lg bg-surface/90 px-3 py-2.5 transition-colors ring-1 ring-border",
-        focusRingClass,
-        isActive
-          ? "bg-accent-soft/40 ring-accent/25 shadow-[var(--shadow-soft)]"
-          : "hover:bg-surface",
-        thread.status === "detached"
-          ? "border-l-[3px] border-[var(--color-semantic-warning)] opacity-70 pl-2.5"
-          : "",
-      ].join(" ")}
-      onClick={() => props.onOpenComment?.(thread)}
-    >
-      {/* Header row: avatar + author + date + status */}
-      <div className="mb-1.5 flex items-center gap-1.5">
-        <span className="inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-full bg-subtle text-[8px] font-semibold text-secondary">
-          {thread.createdBy.charAt(0).toUpperCase()}
-        </span>
-        <span className="truncate text-[10px] font-medium text-primary">{thread.createdBy}</span>
-        {thread.status === "detached" && (
-          <span
-            data-comment-thread-detached-chip="true"
-            className="inline-flex items-center rounded-full bg-[var(--color-semantic-warning-soft)] text-[var(--color-semantic-warning)] text-[9px] font-semibold uppercase tracking-[0.08em] px-1.5 py-0.5 ml-1.5"
-          >
-            Detached
+    <div data-comment-thread-card={thread.commentId} className={threadCardClassName}>
+      <button
+        type="button"
+        ref={scrollRef}
+        data-comment-thread-id={thread.commentId}
+        data-comment-thread-status={thread.status}
+        className={["w-full cursor-pointer pb-1 pt-2.5 text-left", threadContentPaddingClass, focusRingClass].join(" ")}
+        onClick={() => props.onOpenComment?.(thread)}
+      >
+        {/* Header row: avatar + author + date + status */}
+        <div className="mb-1.5 flex items-center gap-1.5">
+          <span className="inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-full bg-subtle text-[8px] font-semibold text-secondary">
+            {thread.createdBy.charAt(0).toUpperCase()}
           </span>
-        )}
-        <span data-comment-thread-created-at="true" className="text-[9px] text-tertiary">
-          {formatCommentDate(thread.createdAt)}
-        </span>
-        <span className="flex-1" />
-        {isDraftThread ? <StatusBadge label="draft" tone="draft" /> : null}
-        {thread.status === "resolved" ? <StatusBadge label="resolved" tone="resolved" /> : null}
-      </div>
+          <span className="truncate text-[10px] font-medium text-primary">{thread.createdBy}</span>
+          {thread.status === "detached" && (
+            <span
+              data-comment-thread-detached-chip="true"
+              className="ml-1.5 inline-flex items-center rounded-full bg-[var(--color-semantic-warning-soft)] px-1.5 py-0.5 text-[9px] font-semibold uppercase tracking-[0.08em] text-[var(--color-semantic-warning)]"
+            >
+              Detached
+            </span>
+          )}
+          <span data-comment-thread-created-at="true" className="text-[9px] text-tertiary">
+            {formatCommentDate(thread.createdAt)}
+          </span>
+          <span className="flex-1" />
+          {isDraftThread ? <StatusBadge label="draft" tone="draft" /> : null}
+          {thread.status === "resolved" ? <StatusBadge label="resolved" tone="resolved" /> : null}
+        </div>
 
-      {/* Excerpt — anchored text from document */}
-      {showExcerpt ? (
-        <p className="mb-1.5 rounded-md bg-comment-soft px-2 py-1 text-[9px] leading-4 text-secondary italic whitespace-pre-wrap break-words line-clamp-2">
-          {thread.excerpt}
-        </p>
-      ) : null}
+        {/* Excerpt — anchored text from document */}
+        {showExcerpt ? (
+          <p className="mb-1.5 rounded-md bg-comment-soft px-2 py-1 text-[9px] italic leading-4 text-secondary whitespace-pre-wrap break-words line-clamp-2">
+            {thread.excerpt}
+          </p>
+        ) : null}
 
-      {/* Comment body */}
-      {canEdit && (isActive || hasNoBody) ? (
-        <InlineEditableBody
-          body={leadEntry?.body ?? ""}
-          autoFocus={isActive && hasNoBody}
-          onSave={(newBody) => props.onEditBody?.(thread.commentId, newBody)}
-          label={isDraftThread ? "New comment" : undefined}
-        />
-      ) : presentation ? (
-        <CommentMarkdownRenderer
-          body={presentation.body}
-          mentions={presentation.mentions}
-          attachments={presentation.attachments}
-          resolveAttachmentHref={resolveAttachmentHref}
-          className="text-[10px] leading-[1.1rem] text-secondary break-words"
-        />
-      ) : leadEntry?.body ? (
-        <p
-          className="text-[10px] leading-[1.1rem] text-secondary whitespace-pre-wrap break-words line-clamp-4"
-          data-comment-thread-body="true"
-        >
-          {leadEntry.body}
-        </p>
-      ) : canEdit ? (
-        <p
-          className="cursor-text text-[10px] italic text-tertiary"
-          onClick={(e) => {
-            e.stopPropagation();
-            props.onOpenComment?.(thread);
-          }}
-        >
-          New comment
-        </p>
-      ) : null}
+        {/* Comment body */}
+        {canEdit && (isActive || hasNoBody) ? (
+          <InlineEditableBody
+            body={leadEntry?.body ?? ""}
+            autoFocus={isActive && hasNoBody}
+            onSave={(newBody) => props.onEditBody?.(thread.commentId, newBody)}
+            label={isDraftThread ? "New comment" : undefined}
+          />
+        ) : presentation ? (
+          <CommentMarkdownRenderer
+            body={presentation.body}
+            mentions={presentation.mentions}
+            attachments={presentation.attachments}
+            resolveAttachmentHref={resolveAttachmentHref}
+            className="text-[10px] leading-[1.1rem] text-secondary break-words"
+          />
+        ) : leadEntry?.body ? (
+          <p
+            className="text-[10px] leading-[1.1rem] text-secondary whitespace-pre-wrap break-words line-clamp-4"
+            data-comment-thread-body="true"
+          >
+            {leadEntry.body}
+          </p>
+        ) : canEdit ? (
+          <p
+            className="cursor-text text-[10px] italic text-tertiary"
+            onClick={(e) => {
+              e.stopPropagation();
+              props.onOpenComment?.(thread);
+            }}
+          >
+            New comment
+          </p>
+        ) : null}
 
-      {/* Reply entries (compact) */}
-      {thread.entries.slice(1).map((entry) => {
-        const replyPresentation = replyPresentationByEntryId.get(entry.entryId);
-        return (
-          <div key={entry.entryId} className="mt-2 ml-4 border-l border-border pl-2.5">
-            <div className="mb-0.5 flex items-center gap-1">
-              <span className="text-[9px] font-medium text-secondary">{entry.authorId}</span>
-              <span className="text-[9px] text-tertiary">{formatCommentDate(entry.createdAt)}</span>
+        {/* Reply entries (compact) */}
+        {thread.entries.slice(1).map((entry) => {
+          const replyPresentation = replyPresentationByEntryId.get(entry.entryId);
+          return (
+            <div key={entry.entryId} className="mt-2 ml-4 border-l border-border pl-2.5">
+              <div className="mb-0.5 flex items-center gap-1">
+                <span className="text-[9px] font-medium text-secondary">{entry.authorId}</span>
+                <span className="text-[9px] text-tertiary">{formatCommentDate(entry.createdAt)}</span>
+              </div>
+              {replyPresentation ? (
+                <CommentMarkdownRenderer
+                  body={replyPresentation.body}
+                  mentions={presentation?.mentions}
+                  attachments={presentation?.attachments}
+                  resolveAttachmentHref={resolveAttachmentHref}
+                  className="text-[10px] leading-4 text-secondary break-words"
+                />
+              ) : (
+                <p
+                  className="text-[10px] leading-4 text-secondary whitespace-pre-wrap break-words line-clamp-3"
+                  data-comment-reply-body="true"
+                >
+                  {entry.body}
+                </p>
+              )}
             </div>
-            {replyPresentation ? (
-              <CommentMarkdownRenderer
-                body={replyPresentation.body}
-                mentions={presentation?.mentions}
-                attachments={presentation?.attachments}
-                resolveAttachmentHref={resolveAttachmentHref}
-                className="text-[10px] leading-4 text-secondary break-words"
-              />
-            ) : (
-              <p
-                className="text-[10px] leading-4 text-secondary whitespace-pre-wrap break-words line-clamp-3"
-                data-comment-reply-body="true"
-              >
-                {entry.body}
-              </p>
-            )}
-          </div>
-        );
-      })}
+          );
+        })}
 
-      {thread.entryCount > thread.entries.length ? (
-        <p className="mt-1 text-[9px] text-tertiary">
-          +{thread.entryCount - thread.entries.length} more
-        </p>
-      ) : null}
+        {thread.entryCount > thread.entries.length ? (
+          <p className="mt-1 text-[9px] text-tertiary">
+            +{thread.entryCount - thread.entries.length} more
+          </p>
+        ) : null}
+      </button>
 
       {/* Inline actions — compact, horizontal */}
-      <div className="mt-2 flex items-center gap-1">
+      <div className={["mt-2 flex items-center gap-1 pb-2.5", threadContentPaddingClass].join(" ")}>
         {thread.status === "open" && (
           <>
             <button
               type="button"
               className="inline-flex items-center gap-0.5 rounded px-1 py-0.5 text-[9px] font-medium text-accent hover:bg-accent-soft transition-colors"
-              onClick={(e) => { e.stopPropagation(); props.onResolveComment?.(thread.commentId); }}
+              onClick={() => props.onResolveComment?.(thread.commentId)}
             >
               <Check className="h-2 w-2" /> Resolve
             </button>
@@ -305,7 +308,7 @@ function CommentThreadCard(props: {
             type="button"
             className="inline-flex items-center gap-0.5 rounded px-1 py-0.5 text-[9px] font-medium text-secondary hover:bg-surface-hover transition-colors"
             data-comment-thread-action="reopen"
-            onClick={(e) => { e.stopPropagation(); props.onReopenComment?.(thread.commentId); }}
+            onClick={() => props.onReopenComment?.(thread.commentId)}
           >
             <RotateCcw className="h-2 w-2" /> Reopen
           </button>
@@ -314,7 +317,7 @@ function CommentThreadCard(props: {
           <span className="text-[9px] text-comment">Detached</span>
         )}
       </div>
-    </button>
+    </div>
   );
 }
 

package/src/ui-tailwind/review/tw-review-rail-footer.tsx

@@ -1,5 +1,6 @@
 import React from "react";
 import { HelpCircle, Search } from "lucide-react";
+import { FOCUS_RING_CLASSES } from "../theme/tokens";
 
 /**
  * Thin pinned footer rendered at the bottom of the review rail.  The footer
@@ -14,8 +15,7 @@ export interface TwReviewRailFooterProps {
   searchLabel?: 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";
+const focusRingClass = FOCUS_RING_CLASSES;
 
 /**
  * Accept only http(s) and mailto help links.  Rejects javascript:, data:,

package/src/ui-tailwind/theme/tokens.ts

@@ -273,6 +273,20 @@ export const HOST_LOCKED_TOKENS = [
 export type HostOverridableToken = (typeof HOST_OVERRIDABLE_TOKENS)[number];
 export type HostLockedToken = (typeof HOST_LOCKED_TOKENS)[number];
 
+/**
+ * Canonical focus-visible ring class string (designsystem §4.7 / §7.2).
+ *
+ * Every interactive chrome surface that renders a custom focus indicator
+ * MUST import this constant rather than inline the Tailwind utilities.
+ * The invariant is enforced by `test/ui-tailwind/focus-ring-canonical.test.ts`.
+ *
+ * Exceptions: input / textarea elements that use a 1-px border ring as the
+ * idle-state affordance (e.g. `tw-comment-sidebar` reply composer) are
+ * a distinct pattern and not covered by this utility.
+ */
+export const FOCUS_RING_CLASSES =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
+
 /** Returns true if `path` is in the locked set (must not be overridden by hosts). */
 export function isTokenPathLocked(path: string): boolean {
   return (HOST_LOCKED_TOKENS as readonly string[]).includes(path);

package/src/ui-tailwind/toolbar/tw-shell-header.tsx

@@ -131,6 +131,11 @@ export function TwShellHeader(props: TwShellHeaderProps): React.ReactElement {
                 key={mode.id}
                 value={mode.id}
                 disabled={mode.disabled}
+                onClick={() => {
+                  if (!mode.disabled) {
+                    props.onModeChange?.(mode.id);
+                  }
+                }}
                 className={`wre-rail-tab ${focusRingClass}`}
                 data-testid={`tw-shell-header__mode-${mode.id}`}
               >

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -17,6 +17,7 @@ import type {
   ActiveListContext,
   CommentSidebarThreadSnapshot,
   DocumentNavigationSnapshot,
+  EditorAnchorProjection,
   EditorStoryTarget,
   EditorViewStateSnapshot,
   FormattingStateSnapshot,
@@ -39,15 +40,8 @@ import type {
   WorkspaceMode,
   ZoomLevel,
 } from "../api/public-types";
-import { findPageForOffset } from "../runtime/document-navigation.ts";
 import { createCanvasBackend } from "../runtime/layout/index.ts";
-import {
-  DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP,
-  estimateBlockHeight,
-  estimateParagraphLineCount,
-  estimateParagraphLineHeight,
-  getUsableColumnWidth,
-} from "../runtime/page-layout-estimation.ts";
+import { DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP } from "../runtime/page-layout-estimation.ts";
 import {
   incrementInvalidationCounter,
   recordPerfSample,
@@ -96,7 +90,7 @@ import { resolveSelectionToolPlacement } from "./chrome/tw-selection-tool-placem
 import { TwReviewRail, type ReviewRailTab } from "./review/tw-review-rail";
 import { TwStatusBar } from "./status/tw-status-bar";
 import { type ToolbarInteractionPolicy } from "./toolbar/tw-toolbar";
-import { TwChromeOverlay } from "./chrome-overlay";
+import { TwChromeOverlay, TwPageStackOverlayLayer } from "./chrome-overlay";
 import {
   cycleScopeIndex,
   shouldHandleScopeNavKey,
@@ -423,6 +417,7 @@ export interface TwReviewWorkspaceProps {
    */
   onScopeAskAgent?: (payload: {
     scopeId: string;
+    anchor?: EditorAnchorProjection;
   }) => void;
   /**
    * P3 — optional scope-tag editor slot rendered inside the scope
@@ -538,9 +533,12 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   const onScopeAskAgent = props.onScopeAskAgent;
   const handleScopeCardAskAgent = useCallback(
     (scopeId: string) => {
-      onScopeAskAgent?.({ scopeId });
+      const cardModel = props.layoutFacet
+        ?.getAllScopeCardModels?.()
+        ?.find((m) => m.scopeId === scopeId);
+      onScopeAskAgent?.({ scopeId, anchor: cardModel?.anchor });
     },
-    [onScopeAskAgent],
+    [onScopeAskAgent, props.layoutFacet],
   );
   const zoomLevel = props.zoomLevel ?? 100;
   // Numeric zooms resolve immediately; "pageWidth" / "onePage" need the
@@ -548,7 +546,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
   // `pageShellMetrics` has been computed (P2.c).
   const numericZoomScale = typeof zoomLevel === "number" ? zoomLevel / 100 : 1;
   const chromePreset = resolveChromePreset(props.chromePreset, props.reviewMode);
-  const chromeOptions = resolveChromePresetOptions(chromePreset, props.chromeOptions);
+  const chromeOptions = resolveChromePresetOptions(chromePreset, props.chromeOptions, viewState.editorRole);
   const preserveOnlyCount = caps?.preserveOnlyCount ??
     snapshot.compatibility.featureEntries.filter(
       (entry) => entry.featureClass === "preserve-only",
@@ -1606,12 +1604,12 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                   style={
                     isPageWorkspace
                       ? {
-                          // Phase A (L8 page-native layout): the paper frame
-                          // owns paper width/height + browser-native CSS
-                          // `zoom` so layout measurement stays truthful
-                          // inside the card.  `pageShellMetrics.pageFrameStyle`
-                          // carries the paper chrome (bg + shadow + rounded +
-                          // border) — painted exactly once.
+                          // N1 (L8 Phase D): paper chrome (bg/border/shadow)
+                          // now lives on per-page overlay cards (z-0) painted
+                          // by TwPageStackOverlayLayer below.  This wrapper
+                          // keeps width/height/zoom so layout measurement stays
+                          // truthful but is visually transparent so the canvas
+                          // background shows through inter-page gaps.
                           ...(pageShellMetrics.frameWidthPx
                             ? { width: `${pageShellMetrics.frameWidthPx}px` }
                             : {}),
@@ -1619,11 +1617,23 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             ? { minHeight: `${pageShellMetrics.frameHeightPx}px` }
                             : {}),
                           ...(zoomScale !== 1 ? { zoom: zoomScale } : {}),
-                          ...pageShellMetrics.pageFrameStyle,
                         }
                       : undefined
                   }
                 >
+                  {/* N1 (L8 Phase D): per-page paper card backgrounds at z-0,
+                      painted before the z-10 PM wrapper so white card areas
+                      sit behind PM text.  Gaps between cards expose the gray
+                      workspace-canvas background, giving N discrete papers. */}
+                  {isPageWorkspace && chromeVisibility.pageChrome && props.layoutFacet ? (
+                    <TwPageStackOverlayLayer
+                      facet={props.layoutFacet}
+                      scrollRoot={pageStackScrollRoot}
+                      renderFrameRevision={renderFrameRevision}
+                      visiblePageIndexRange={visiblePageIndexRange}
+                      data-layer="page-card-backgrounds"
+                    />
+                  ) : null}
                   {isPageWorkspace && chromeVisibility.pageChrome && pageChromeModel.lineNumberingEnabled ? (
                     <div
                       aria-hidden="true"
@@ -1990,7 +2000,6 @@ const EMPTY_PAGE_CHROME_MODEL: PageChromeModel = {
   documentGridStyle: undefined,
 };
 
-const DOCUMENT_CONTENT_TOP_PADDING_PX = 40;
 
 // P2.a — real-dimension page frame.  Page frame width/height are
 // `pageLayout.pageWidth/pageHeight × FRAME_PX_PER_TWIP_AT_96DPI` so
@@ -2024,7 +2033,6 @@ function buildPageChromeModel(
     pageLayout,
     surfaceBlocks: surface.blocks,
     pages: navigation.pages,
-    buildLineNumberMarkers,
   });
   const lineNumberingEnabled =
     Boolean(pageLayout.lineNumbering) && lineMarkers.length > 0;
@@ -2124,72 +2132,6 @@ export function resolveZoomMultiplier(
   );
 }
 
-function buildLineNumberMarkers(
-  blocks: readonly SurfaceBlockSnapshot[],
-  pages: ReadonlyArray<DocumentNavigationSnapshot["pages"][number]>,
-): Array<{ id: string; label: string; topPx: number }> {
-  const markers: Array<{ id: string; label: string; topPx: number }> = [];
-  if (pages.length === 0) {
-    return markers;
-  }
-
-  let currentTopTwips = 0;
-  let lineNumber = 1;
-  let lastPageIndex = -1;
-  let lastSectionIndex = -1;
-
-  for (const block of blocks) {
-    const pageIndex = findPageForOffset(pages, block.from);
-    const page = pages[pageIndex];
-    if (!page) {
-      continue;
-    }
-
-    const lineNumbering = page.layout.lineNumbering;
-    const restartMode = lineNumbering?.restart ?? "newPage";
-    const restartStart = lineNumbering?.start ?? 1;
-    const countBy = Math.max(1, lineNumbering?.countBy ?? 1);
-    const columnWidth = getUsableColumnWidth(page.layout);
-
-    if (pageIndex !== lastPageIndex) {
-      if (restartMode === "newPage" || lastPageIndex === -1) {
-        lineNumber = restartStart;
-      }
-      lastPageIndex = pageIndex;
-    }
-    if (page.sectionIndex !== lastSectionIndex) {
-      if (restartMode === "newSection" || lastSectionIndex === -1) {
-        lineNumber = restartStart;
-      }
-      lastSectionIndex = page.sectionIndex;
-    }
-
-    if (block.kind === "paragraph" && lineNumbering) {
-      const lineCount = estimateParagraphLineCount(block, columnWidth);
-      const lineHeight = estimateParagraphLineHeight(block);
-      const suppress = block.suppressLineNumbers === true;
-      for (let lineIndex = 0; lineIndex < lineCount; lineIndex += 1) {
-        if (!suppress && (lineNumber - restartStart) % countBy === 0) {
-          markers.push({
-            id: `${block.blockId}-${lineIndex}`,
-            label: String(lineNumber),
-            topPx:
-              DOCUMENT_CONTENT_TOP_PADDING_PX +
-              (currentTopTwips + lineIndex * lineHeight) * DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP,
-          });
-        }
-        if (!suppress) {
-          lineNumber += 1;
-        }
-      }
-    }
-
-    currentTopTwips += estimateBlockHeight(block, columnWidth);
-  }
-
-  return markers;
-}
-
 function shouldRenderPageBorder(
   pageLayout: RuntimeRenderSnapshot["pageLayout"],
   pages: ReadonlyArray<DocumentNavigationSnapshot["pages"][number]>,

package/src/validation/diagnostics.ts

@@ -17,6 +17,7 @@ export const EDITOR_WARNING_CODES = [
   "large_document_degraded",
   "font_substitution",
   "image_missing",
+  "review_target_not_found",
 ] as const;
 
 export type EditorWarningCode = (typeof EDITOR_WARNING_CODES)[number];