@beyondwork/docx-react-component 1.0.41 → 1.0.42

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

@@ -1,18 +1,21 @@
 /**
- * TwScopeCardLayer — renders at most one scope card at a time, chosen
- * by `activeScopeId`.  Consumes `facet.getAllScopeCardModels()` to
- * look up the model, then positions the card 8px above the model's
- * `primaryAnchorRect`.
+ * TwScopeCardLayer — renders at most one scope card at a time.  The
+ * layer resolves which card is visible from two inputs:
  *
- * Per docs/plans/scope-card-overlay.md P1, the layer keeps
- * positioning pure: it never calls `getBoundingClientRect` or reads
- * DOM rects.  Coordinates come from the render kernel's anchor index
- * through `ScopeCardModel.primaryAnchorRect`, projected into the
- * overlay's own coordinate space via the shared projector.
+ *   1. `activeScopeId` — the currently opened scope, set by the
+ *      workspace when the user clicks a rail stripe.  Resets on
+ *      click-outside / Escape / close button.
+ *   2. internal `pinnedScopeId` — when the user clicks the pin button
+ *      on a card, that scope persists across `activeScopeId` changes
+ *      until explicitly unpinned or the scope disappears from the
+ *      card model list.
  *
- * Auto-flip, pin, and overlapping-scope stacking land in P3.  P1
- * renders a single card above the scope's first line and falls back
- * to a top-left overlay placement when no rect is resolvable.
+ * Per docs/plans/scope-card-overlay.md P1 the layer keeps positioning
+ * pure: coordinates come from the render kernel's anchor index via
+ * `ScopeCardModel.primaryAnchorRect`, projected into the overlay's
+ * coordinate space.  P3b adds auto-flip: when the anchor is within
+ * `CARD_ESTIMATED_HEIGHT_PX + CARD_GAP_PX` of the viewport top, the
+ * card flips below the scope's first line instead of above.
  */
 
 import * as React from "react";
@@ -22,6 +25,8 @@ import {
 } from "./chrome-overlay-projector";
 import { TwScopeCard } from "./tw-scope-card";
 import type {
+  EditorRole,
+  ScopeCardModel,
   ScopeIssueAction,
   WorkflowScopeMode,
 } from "../../api/public-types";
@@ -42,7 +47,22 @@ export interface TwScopeCardLayerProps {
     issueId: string,
     action: ScopeIssueAction,
   ) => void;
+  /** R3 — routed from chrome overlay; undefined hides the row. */
+  onAcceptSuggestionGroup?: (scopeId: string, groupId: string) => void;
+  onRejectSuggestionGroup?: (scopeId: string, groupId: string) => void;
+  /** K2 — routed from chrome overlay; undefined hides the button. */
+  onAskAgent?: (scopeId: string) => void;
+  /** P3 — active editor role threaded down to the card. */
+  editorRole?: EditorRole;
+  /** P3 — scope-tag editor slot (rendered only in workflow role). */
+  scopeTagEditor?: React.ReactNode;
   space?: OverlayCoordinateSpace;
+  /**
+   * P3b — top of the viewport in overlay-space pixels.  The layer
+   * uses this to decide whether the card should flip below the scope.
+   * Default: 0 (overlay origin is viewport top).
+   */
+  viewportTopPx?: number;
   "data-testid"?: string;
 }
 
@@ -61,15 +81,48 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   onClose,
   onModeChange,
   onIssueAction,
+  onAcceptSuggestionGroup,
+  onRejectSuggestionGroup,
+  onAskAgent,
+  editorRole,
+  scopeTagEditor,
   space,
+  viewportTopPx = 0,
   "data-testid": testId,
 }) => {
-  if (!activeScopeId) return null;
+  const [pinnedScopeId, setPinnedScopeId] = React.useState<string | null>(null);
+
+  // If the layer's close handler fires, also clear any pin so the
+  // next stripe click starts from a clean state.
+  const handleClose = React.useCallback(() => {
+    setPinnedScopeId(null);
+    onClose();
+  }, [onClose]);
+
+  const handleTogglePin = React.useCallback((scopeId: string) => {
+    setPinnedScopeId((current) => (current === scopeId ? null : scopeId));
+  }, []);
+
+  // The effective scope is the pinned one if it still resolves to a
+  // model, else the active one.  When a pinned scope disappears
+  // (e.g. the host cleared the overlay), drop the pin.
   const models =
     typeof facet.getAllScopeCardModels === "function"
       ? facet.getAllScopeCardModels()
       : [];
-  const model = models.find((m) => m.scopeId === activeScopeId);
+
+  const pinnedModel = pinnedScopeId
+    ? models.find((m) => m.scopeId === pinnedScopeId) ?? null
+    : null;
+  if (pinnedScopeId && !pinnedModel) {
+    // Async cleanup via effect to avoid setState during render.
+    queueMicrotask(() => setPinnedScopeId(null));
+  }
+
+  const effectiveScopeId = pinnedModel ? pinnedScopeId : activeScopeId;
+  if (!effectiveScopeId) return null;
+  const model: ScopeCardModel | undefined =
+    pinnedModel ?? models.find((m) => m.scopeId === effectiveScopeId);
   if (!model) return null;
 
   const projectorSpace: OverlayCoordinateSpace =
@@ -77,23 +130,48 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   const positioned = resolveCardPosition(
     model.primaryAnchorRect,
     projectorSpace,
+    viewportTopPx,
   );
 
+  const isPinned = pinnedScopeId === model.scopeId;
+
   return (
     <div
       className="wre-scope-card-layer pointer-events-none absolute inset-0 z-30"
       data-testid={testId ?? "scope-card-layer"}
-      data-active-scope-id={activeScopeId}
+      data-active-scope-id={effectiveScopeId}
+      data-pinned-scope-id={isPinned ? model.scopeId : undefined}
     >
-      <div style={positioned} className="absolute">
+      <div
+        style={positioned}
+        className="absolute"
+        data-card-placement={positioned["--wre-card-placement"] as string | undefined}
+      >
         <TwScopeCard
           model={model}
-          onClose={onClose}
+          onClose={handleClose}
           onModeChange={(mode) => onModeChange(model.scopeId, mode)}
           onIssueAction={(action) => {
             if (!model.issue) return;
             onIssueAction(model.scopeId, model.issue.issueId, action);
           }}
+          onAcceptSuggestionGroup={
+            onAcceptSuggestionGroup
+              ? (groupId) => onAcceptSuggestionGroup(model.scopeId, groupId)
+              : undefined
+          }
+          onRejectSuggestionGroup={
+            onRejectSuggestionGroup
+              ? (groupId) => onRejectSuggestionGroup(model.scopeId, groupId)
+              : undefined
+          }
+          onAskAgent={
+            onAskAgent ? () => onAskAgent(model.scopeId) : undefined
+          }
+          editorRole={editorRole}
+          scopeTagEditor={scopeTagEditor}
+          pinned={isPinned}
+          onTogglePin={() => handleTogglePin(model.scopeId)}
         />
       </div>
     </div>
@@ -104,22 +182,41 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
 // Positioning
 // ---------------------------------------------------------------------------
 
+/**
+ * Decide where the card renders relative to the scope's anchor rect.
+ *
+ * Preferred placement: 8px above the anchor's first line.  When the
+ * resulting top would be within `CARD_ESTIMATED_HEIGHT_PX + CARD_GAP_PX`
+ * of the overlay-space viewport top, flip to 8px below the anchor's
+ * last line instead — that keeps the card visible even when the user
+ * is scrolled to the very first scope on the page.
+ *
+ * Returns a React.CSSProperties object with an extra
+ * `--wre-card-placement` custom property that tests (and the card's
+ * own shadow token tweaks) can key off to verify which placement the
+ * layer chose.
+ */
 function resolveCardPosition(
   anchor: RenderFrameRect | null,
   space: OverlayCoordinateSpace,
-): React.CSSProperties {
+  viewportTopPx: number,
+): React.CSSProperties & { "--wre-card-placement"?: string } {
   if (!anchor) {
     return {
       left: `${CARD_FALLBACK_LEFT_PX}px`,
       top: `${CARD_FALLBACK_TOP_PX}px`,
+      "--wre-card-placement": "fallback",
     };
   }
-  // Position the card above the anchor's first line, leaving
-  // `CARD_GAP_PX` between anchor top and card bottom.  P3 adds auto-
-  // flip based on viewport clipping.
+  const preferredTop = anchor.topPx - CARD_ESTIMATED_HEIGHT_PX - CARD_GAP_PX;
+  const willClipAtTop = preferredTop < viewportTopPx;
+  const placement: "above" | "below" = willClipAtTop ? "below" : "above";
+  const targetTop = placement === "below"
+    ? anchor.topPx + anchor.heightPx + CARD_GAP_PX
+    : preferredTop;
   const targetRect: RenderFrameRect = {
     leftPx: anchor.leftPx,
-    topPx: Math.max(0, anchor.topPx - CARD_ESTIMATED_HEIGHT_PX - CARD_GAP_PX),
+    topPx: targetTop,
     widthPx: 1,
     heightPx: 1,
   };
@@ -127,6 +224,7 @@ function resolveCardPosition(
   return {
     left: projected.left,
     top: projected.top,
+    "--wre-card-placement": placement,
   };
 }
 

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

@@ -21,13 +21,18 @@
 
 import * as React from "react";
 import type {
+  EditorRole,
   IssueMetadataValue,
   IssueOwner,
   IssueSeverity,
+  ReviewActionKind,
+  ReviewActionMetadataValue,
   ScopeCardModel,
   ScopeIssueAction,
+  SuggestionGroup,
   WorkflowScopeMode,
 } from "../../api/public-types";
+import { resolveScopeCardVisibility } from "./scope-card-role-model";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -38,6 +43,48 @@ export interface TwScopeCardProps {
   onClose: () => void;
   onModeChange: (mode: WorkflowScopeMode) => void;
   onIssueAction: (action: ScopeIssueAction) => void;
+  /**
+   * R3 — accept every member of a suggestion group.  Renders the
+   * suggestion row only when this handler is supplied and the model
+   * has at least one group attached.
+   */
+  onAcceptSuggestionGroup?: (groupId: string) => void;
+  /** R3 — reject every member of a suggestion group. */
+  onRejectSuggestionGroup?: (groupId: string) => void;
+  /**
+   * K2 — "Ask review agent" button is only rendered when this
+   * handler is supplied (matches the hidden-by-default pattern of
+   * other review-role chrome).  Fires once per click; the host
+   * resolves the selection text + surrounding context from the
+   * scope's anchor.
+   */
+  onAskAgent?: () => void;
+  /**
+   * P3 — active editor role.  Drives which card sections render:
+   * `editor` keeps mode + issue only, `review` renders the full
+   * surface, `workflow` additionally reserves a scope-tag editor
+   * slot.  Defaults to `review` if the host doesn't supply one —
+   * preserves the full card the P1/P2 tests exercised.
+   */
+  editorRole?: EditorRole;
+  /**
+   * P3 — slot the host may render in workflow role to expose a
+   * scope-tag editor (a chip picker, free-text input, etc.).  When
+   * present and role is workflow, the card renders it between the
+   * mode row and the issue row.
+   */
+  scopeTagEditor?: React.ReactNode;
+  /**
+   * P3b — whether the card is pinned.  A pinned card persists on
+   * the overlay across `activeScopeId` changes.  The card adds an
+   * `aria-pressed` toggle to the pin button based on this flag.
+   */
+  pinned?: boolean;
+  /**
+   * P3b — toggle pin state.  Omit to hide the pin button entirely
+   * (keeps the P1/P2 simple cards unchanged).
+   */
+  onTogglePin?: () => void;
   /** Test id applied to the root node. */
   "data-testid"?: string;
 }
@@ -80,8 +127,16 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
   onClose,
   onModeChange,
   onIssueAction,
+  onAcceptSuggestionGroup,
+  onRejectSuggestionGroup,
+  onAskAgent,
+  editorRole = "review",
+  scopeTagEditor,
+  pinned = false,
+  onTogglePin,
   "data-testid": testId,
 }) => {
+  const visibility = resolveScopeCardVisibility(editorRole);
   const rootRef = React.useRef<HTMLDivElement | null>(null);
   const headerId = React.useId();
   const liveRegionId = React.useId();
@@ -153,6 +208,7 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
       data-testid={testId ?? "scope-card"}
       data-scope-id={model.scopeId}
       data-posture={model.posture}
+      data-chrome-overlay="scope-card"
       onKeyDown={onKeyDown}
     >
       {/* Header --------------------------------------------------------- */}
@@ -173,46 +229,123 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
             <span className="truncate text-tertiary">· {model.label}</span>
           ) : null}
         </div>
-        <button
-          type="button"
-          aria-label="Close scope card"
-          className="flex h-6 w-6 items-center justify-center rounded-sm text-tertiary transition-colors hover:bg-surface hover:text-primary"
-          onClick={onClose}
-          data-testid="scope-card-close"
-        >
-          ×
-        </button>
-      </div>
-
-      {/* Mode row ------------------------------------------------------- */}
-      <div
-        role="group"
-        aria-label="Scope mode"
-        className="flex gap-1 rounded-md border border-border bg-surface p-0.5"
-      >
-        {MODE_OPTIONS.map(({ mode, label }) => {
-          const active = model.posture === mode;
-          return (
+        <div className="flex items-center gap-1">
+          {onTogglePin ? (
             <button
-              key={mode}
               type="button"
-              aria-pressed={active ? "true" : "false"}
-              className={`flex-1 rounded-sm px-2 py-1 text-xs font-medium transition-colors ${
-                active
-                  ? "bg-canvas text-primary shadow-sm"
-                  : "text-secondary hover:bg-canvas hover:text-primary"
+              aria-label={pinned ? "Unpin scope card" : "Pin scope card"}
+              aria-pressed={pinned ? "true" : "false"}
+              className={`flex h-6 w-6 items-center justify-center rounded-sm text-[10px] font-semibold uppercase tracking-[0.06em] transition-colors ${
+                pinned
+                  ? "bg-surface text-accent"
+                  : "text-tertiary hover:bg-surface hover:text-primary"
               }`}
-              onClick={() => onModeChange(mode)}
-              data-testid={`scope-card-mode-${mode}`}
+              onClick={onTogglePin}
+              data-testid="scope-card-pin"
+              title={pinned ? "Unpin" : "Pin"}
             >
-              {label}
+              {pinned ? "ON" : "PIN"}
             </button>
-          );
-        })}
+          ) : null}
+          <button
+            type="button"
+            aria-label="Close scope card"
+            className="flex h-6 w-6 items-center justify-center rounded-sm text-tertiary transition-colors hover:bg-surface hover:text-primary"
+            onClick={onClose}
+            data-testid="scope-card-close"
+          >
+            ×
+          </button>
+        </div>
       </div>
 
+      {/* Mode row ------------------------------------------------------- */}
+      {visibility.modeRow ? (
+        <div
+          role="group"
+          aria-label="Scope mode"
+          className="flex gap-1 rounded-md border border-border bg-surface p-0.5"
+        >
+          {MODE_OPTIONS.map(({ mode, label }) => {
+            const active = model.posture === mode;
+            return (
+              <button
+                key={mode}
+                type="button"
+                aria-pressed={active ? "true" : "false"}
+                className={`flex-1 rounded-sm px-2 py-1 text-xs font-medium transition-colors ${
+                  active
+                    ? "bg-canvas text-primary shadow-sm"
+                    : "text-secondary hover:bg-canvas hover:text-primary"
+                }`}
+                onClick={() => onModeChange(mode)}
+                data-testid={`scope-card-mode-${mode}`}
+              >
+                {label}
+              </button>
+            );
+          })}
+        </div>
+      ) : null}
+
+      {/* Scope tag editor slot (P3 workflow role) ---------------------- */}
+      {visibility.scopeTagEditor && scopeTagEditor ? (
+        <div
+          className="flex flex-col gap-1 rounded-md bg-surface p-2"
+          data-testid="scope-card-scope-tag-editor"
+        >
+          {scopeTagEditor}
+        </div>
+      ) : null}
+
       {/* Issue row (R2) ------------------------------------------------- */}
-      {issue ? <IssueRow issue={issue} onAction={onIssueAction} /> : null}
+      {visibility.issueRow && issue ? (
+        <IssueRow issue={issue} onAction={onIssueAction} />
+      ) : null}
+
+      {/* Suggestion group rows (R3) ------------------------------------ */}
+      {visibility.suggestionRows &&
+      model.suggestionGroups.length > 0 &&
+      (onAcceptSuggestionGroup || onRejectSuggestionGroup) ? (
+        <div className="flex flex-col gap-1.5">
+          {model.suggestionGroups.map((group) => (
+            <SuggestionGroupRow
+              key={group.groupId}
+              group={group}
+              onAccept={
+                onAcceptSuggestionGroup
+                  ? () => onAcceptSuggestionGroup(group.groupId)
+                  : undefined
+              }
+              onReject={
+                onRejectSuggestionGroup
+                  ? () => onRejectSuggestionGroup(group.groupId)
+                  : undefined
+              }
+            />
+          ))}
+        </div>
+      ) : null}
+
+      {/* Review-action timeline (K1) ----------------------------------- */}
+      {visibility.timeline && model.reviewActions.length > 0 ? (
+        <ReviewActionTimeline
+          actions={model.reviewActions}
+          totalCount={model.reviewActionCount}
+        />
+      ) : null}
+
+      {/* Ask review agent button (K2) ---------------------------------- */}
+      {visibility.agentButton && onAskAgent ? (
+        <button
+          type="button"
+          className="rounded-md border border-border bg-canvas px-2 py-1.5 text-xs font-medium text-primary transition-colors hover:bg-surface"
+          onClick={onAskAgent}
+          data-testid="scope-card-ask-agent"
+        >
+          Ask review agent
+        </button>
+      ) : null}
 
       {/* A11y live region ---------------------------------------------- */}
       <span
@@ -314,6 +447,151 @@ const IssueActionButton: React.FC<{
   </button>
 );
 
+// ---------------------------------------------------------------------------
+// Suggestion group row (R3)
+// ---------------------------------------------------------------------------
+
+const TIER_LABEL: Record<NonNullable<SuggestionGroup["tier"]>, string> = {
+  preferred: "Preferred",
+  fallback_1: "Fallback 1",
+  fallback_2: "Fallback 2",
+  escalate_only: "Escalate only",
+};
+
+const SuggestionGroupRow: React.FC<{
+  group: SuggestionGroup;
+  onAccept?: () => void;
+  onReject?: () => void;
+}> = ({ group, onAccept, onReject }) => (
+  <div
+    className="flex flex-col gap-1 rounded-md border border-border bg-surface p-2"
+    data-testid="scope-card-suggestion-group"
+    data-group-id={group.groupId}
+  >
+    <div className="flex items-center justify-between gap-2">
+      <div className="flex items-center gap-1.5 text-[11px] text-primary">
+        <span className="font-semibold">Suggestion group</span>
+        {group.tier ? (
+          <span className="rounded-sm border border-border px-1 py-0.5 text-[10px] font-medium uppercase tracking-[0.06em] text-secondary">
+            {TIER_LABEL[group.tier]}
+          </span>
+        ) : null}
+      </div>
+      <span className="text-[10px] text-tertiary">
+        {group.suggestionIds.length} redline
+        {group.suggestionIds.length === 1 ? "" : "s"}
+      </span>
+    </div>
+    {group.rationale ? (
+      <div className="text-[11px] leading-snug text-secondary">{group.rationale}</div>
+    ) : null}
+    <div className="flex gap-1">
+      <button
+        type="button"
+        disabled={!onAccept}
+        className="flex-1 rounded-sm border border-border bg-canvas px-1.5 py-1 text-[11px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary disabled:cursor-not-allowed disabled:opacity-40"
+        onClick={onAccept}
+        data-testid="scope-card-suggestion-accept"
+      >
+        Accept
+      </button>
+      <button
+        type="button"
+        disabled={!onReject}
+        className="flex-1 rounded-sm border border-border bg-canvas px-1.5 py-1 text-[11px] font-medium text-secondary transition-colors hover:bg-surface hover:text-primary disabled:cursor-not-allowed disabled:opacity-40"
+        onClick={onReject}
+        data-testid="scope-card-suggestion-reject"
+      >
+        Reject
+      </button>
+    </div>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Review-action timeline (K1)
+// ---------------------------------------------------------------------------
+
+const ACTION_LABEL: Record<ReviewActionKind, string> = {
+  include: "Included",
+  edit: "Edited",
+  discard: "Discarded",
+  escalate: "Escalated",
+  acknowledge: "Acknowledged",
+  resolve: "Resolved",
+  waive: "Waived",
+};
+
+const TIMELINE_DEFAULT_VISIBLE = 8;
+
+const ReviewActionTimeline: React.FC<{
+  actions: readonly ReviewActionMetadataValue[];
+  totalCount: number;
+}> = ({ actions, totalCount }) => {
+  const [expanded, setExpanded] = React.useState(false);
+  const visible = expanded ? actions : actions.slice(0, TIMELINE_DEFAULT_VISIBLE);
+  const canExpand = actions.length > TIMELINE_DEFAULT_VISIBLE;
+
+  return (
+    <div
+      className="flex flex-col gap-1 rounded-md bg-surface p-2"
+      data-testid="scope-card-timeline"
+    >
+      <div className="flex items-center justify-between gap-2">
+        <span className="text-[10px] font-semibold uppercase tracking-[0.06em] text-tertiary">
+          Activity ({totalCount})
+        </span>
+        {canExpand ? (
+          <button
+            type="button"
+            className="rounded-sm border border-border bg-canvas px-1.5 py-0.5 text-[10px] font-medium text-secondary transition-colors hover:text-primary"
+            onClick={() => setExpanded((prev) => !prev)}
+            data-testid="scope-card-timeline-toggle"
+          >
+            {expanded ? "Show less" : "Show all"}
+          </button>
+        ) : null}
+      </div>
+      <div
+        className={`flex flex-col gap-1 ${
+          expanded && canExpand ? "max-h-60 overflow-y-auto" : ""
+        }`}
+      >
+        {visible.map((entry) => (
+          <div
+            key={entry.reviewActionId}
+            className="flex items-center gap-1.5 text-[11px] leading-tight text-primary"
+            data-testid="scope-card-timeline-entry"
+          >
+            <span
+              aria-hidden="true"
+              className="inline-block h-1.5 w-1.5 rounded-full bg-accent"
+            />
+            <span className="font-medium">{entry.actor}</span>
+            <span className="text-tertiary">· {entry.actorRole}</span>
+            <span className="text-secondary">· {ACTION_LABEL[entry.action]}</span>
+            <span className="text-tertiary">· {formatRelative(entry.createdAt)}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+function formatRelative(isoString: string): string {
+  const now = Date.now();
+  const then = new Date(isoString).getTime();
+  if (Number.isNaN(then)) return isoString;
+  const diffSeconds = Math.round((then - now) / 1000);
+  const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+  const abs = Math.abs(diffSeconds);
+  if (abs < 60) return rtf.format(diffSeconds, "second");
+  if (abs < 3600) return rtf.format(Math.round(diffSeconds / 60), "minute");
+  if (abs < 86400) return rtf.format(Math.round(diffSeconds / 3600), "hour");
+  if (abs < 604800) return rtf.format(Math.round(diffSeconds / 86400), "day");
+  return rtf.format(Math.round(diffSeconds / 604800), "week");
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------