@beyondwork/docx-react-component 1.0.38 → 1.0.40

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

@@ -15,9 +15,15 @@
 import * as React from "react";
 import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
 import type { ScopeRailSegment } from "../../runtime/layout";
-import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+import type {
+  ScopeIssueAction,
+  TableStructureContextSnapshot,
+  WordReviewEditorLayoutFacet,
+  WorkflowScopeMode,
+} from "../../api/public-types";
 import { TwScopeRailLayer } from "./tw-scope-rail-layer";
-import { TwWorkspaceViewSwitcher, type WorkspaceView } from "./tw-workspace-view-switcher";
+import { TwScopeCardLayer } from "./tw-scope-card-layer";
+import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
 
 export interface TwChromeOverlayProps {
   /** Layout facet the overlay layers read from. */
@@ -26,18 +32,54 @@ export interface TwChromeOverlayProps {
   space?: OverlayCoordinateSpace;
   /** Active scope id (for emphasis + rail tab sync). */
   activeScopeId?: string | null;
-  /** Click handler the rail layer forwards to consumers. */
+  /**
+   * Click handler fired when the user clicks a scope rail stripe.
+   * P0 wires this to open the scope card (P1 ships the card layer).
+   */
+  onScopeStripeClick?: (segment: ScopeRailSegment) => void;
+  /**
+   * Legacy click handler kept for compatibility with consumers that
+   * subscribed before the stripe affordance existed.  Called alongside
+   * `onScopeStripeClick` on a stripe click.
+   */
   onScopeSegmentClick?: (segment: ScopeRailSegment) => void;
-  /** Currently active workspace view preset (draft / layout / review / workflow). */
-  activeWorkspaceView?: WorkspaceView;
-  /** Handler that fires when the user picks a workspace view. */
-  onWorkspaceViewChange?: (view: WorkspaceView) => void;
-  /** Show the bottom workspace view-switcher dock.  Default: true. */
-  showWorkspaceDock?: boolean;
+  /**
+   * Fires when the scope card is dismissed (close button, Escape, or
+   * click-outside).  The owner uses this to clear `activeScopeId`.
+   */
+  onScopeCardClose?: () => void;
+  /**
+   * Fires when a mode button inside the scope card is clicked.  The
+   * owner relays this into a `scope-mode-change-requested` event for
+   * the host (which then drives the overlay-apply path).
+   */
+  onScopeCardModeChange?: (scopeId: string, mode: WorkflowScopeMode) => void;
+  /**
+   * Fires when an issue action button (Resolve/Waive/Escalate) inside
+   * the scope card is clicked.  The owner relays this into a
+   * `scope-issue-action-requested` event for the host.
+   */
+  onScopeCardIssueAction?: (
+    scopeId: string,
+    issueId: string,
+    action: ScopeIssueAction,
+  ) => void;
   /** Test id applied to the overlay root. */
   "data-testid"?: string;
   /** Optional extra children (e.g., future comment balloon layer). */
   children?: React.ReactNode;
+
+  // Table grip props (P6) -----------------------------------------------
+  /** Active table context — when present, column/row resize grips are shown. */
+  tableContext?: TableStructureContextSnapshot | null;
+  /** Fires when a column grip drag completes. */
+  onSetColumnWidth?: (columnIndex: number, twips: number) => void;
+  /** Fires when a row grip drag completes. */
+  onSetRowHeight?: (
+    rowIndex: number,
+    twips: number,
+    rule: "auto" | "atLeast" | "exact",
+  ) => void;
 }
 
 /**
@@ -53,12 +95,16 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   facet,
   space,
   activeScopeId,
+  onScopeStripeClick,
   onScopeSegmentClick,
-  activeWorkspaceView,
-  onWorkspaceViewChange,
-  showWorkspaceDock = true,
+  onScopeCardClose,
+  onScopeCardModeChange,
+  onScopeCardIssueAction,
   "data-testid": testId,
   children,
+  tableContext,
+  onSetColumnWidth,
+  onSetRowHeight,
 }) => {
   return (
     <div
@@ -70,17 +116,35 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
         facet={facet}
         space={space}
         activeScopeId={activeScopeId}
+        onStripeClick={onScopeStripeClick}
         onSegmentClick={onScopeSegmentClick}
       />
+      <TwScopeCardLayer
+        facet={facet}
+        activeScopeId={activeScopeId ?? null}
+        onClose={onScopeCardClose ?? noop}
+        onModeChange={onScopeCardModeChange ?? noopModeChange}
+        onIssueAction={onScopeCardIssueAction ?? noopIssueAction}
+        space={space}
+      />
+      <TwTableGripLayer
+        facet={facet}
+        tableContext={tableContext ?? null}
+        space={space}
+        onSetColumnWidth={onSetColumnWidth}
+        onSetRowHeight={onSetRowHeight}
+      />
       {children}
-      {showWorkspaceDock ? (
-        <TwWorkspaceViewSwitcher
-          activeView={activeWorkspaceView ?? "review"}
-          onViewChange={onWorkspaceViewChange}
-        />
-      ) : null}
     </div>
   );
 };
 
+const noop = () => undefined;
+const noopModeChange = (_scopeId: string, _mode: WorkflowScopeMode) => undefined;
+const noopIssueAction = (
+  _scopeId: string,
+  _issueId: string,
+  _action: ScopeIssueAction,
+) => undefined;
+
 export default TwChromeOverlay;

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

@@ -0,0 +1,133 @@
+/**
+ * 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`.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import * as React from "react";
+import {
+  projectRectToOverlay,
+  type OverlayCoordinateSpace,
+} from "./chrome-overlay-projector";
+import { TwScopeCard } from "./tw-scope-card";
+import type {
+  ScopeIssueAction,
+  WorkflowScopeMode,
+} from "../../api/public-types";
+import type { RenderFrameRect } from "../../runtime/render";
+import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TwScopeCardLayerProps {
+  facet: WordReviewEditorLayoutFacet;
+  activeScopeId: string | null;
+  onClose: () => void;
+  onModeChange: (scopeId: string, mode: WorkflowScopeMode) => void;
+  onIssueAction: (
+    scopeId: string,
+    issueId: string,
+    action: ScopeIssueAction,
+  ) => void;
+  space?: OverlayCoordinateSpace;
+  "data-testid"?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+const CARD_GAP_PX = 8;
+const CARD_ESTIMATED_HEIGHT_PX = 160;
+const CARD_FALLBACK_LEFT_PX = 16;
+const CARD_FALLBACK_TOP_PX = 16;
+
+export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
+  facet,
+  activeScopeId,
+  onClose,
+  onModeChange,
+  onIssueAction,
+  space,
+  "data-testid": testId,
+}) => {
+  if (!activeScopeId) return null;
+  const models =
+    typeof facet.getAllScopeCardModels === "function"
+      ? facet.getAllScopeCardModels()
+      : [];
+  const model = models.find((m) => m.scopeId === activeScopeId);
+  if (!model) return null;
+
+  const projectorSpace: OverlayCoordinateSpace =
+    space ?? { originLeftPx: 0, originTopPx: 0 };
+  const positioned = resolveCardPosition(
+    model.primaryAnchorRect,
+    projectorSpace,
+  );
+
+  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}
+    >
+      <div style={positioned} className="absolute">
+        <TwScopeCard
+          model={model}
+          onClose={onClose}
+          onModeChange={(mode) => onModeChange(model.scopeId, mode)}
+          onIssueAction={(action) => {
+            if (!model.issue) return;
+            onIssueAction(model.scopeId, model.issue.issueId, action);
+          }}
+        />
+      </div>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Positioning
+// ---------------------------------------------------------------------------
+
+function resolveCardPosition(
+  anchor: RenderFrameRect | null,
+  space: OverlayCoordinateSpace,
+): React.CSSProperties {
+  if (!anchor) {
+    return {
+      left: `${CARD_FALLBACK_LEFT_PX}px`,
+      top: `${CARD_FALLBACK_TOP_PX}px`,
+    };
+  }
+  // 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 targetRect: RenderFrameRect = {
+    leftPx: anchor.leftPx,
+    topPx: Math.max(0, anchor.topPx - CARD_ESTIMATED_HEIGHT_PX - CARD_GAP_PX),
+    widthPx: 1,
+    heightPx: 1,
+  };
+  const projected = projectRectToOverlay(targetRect, space);
+  return {
+    left: projected.left,
+    top: projected.top,
+  };
+}
+
+export default TwScopeCardLayer;

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

@@ -0,0 +1,386 @@
+/**
+ * TwScopeCard — inline floating card shown above a scoped region when
+ * the user activates the rail stripe.  Displays scope label + mode
+ * selector + (when an `IssueMetadataValue` is attached via
+ * `ScopeCardModel.issue`) the R2 issue severity, owner, title, and
+ * resolve/waive/escalate actions.
+ *
+ * Per docs/plans/scope-card-overlay.md P1, the card never mutates
+ * runtime state directly — it fires `onModeChange` / `onIssueAction`
+ * callbacks that bubble up to `scope-mode-change-requested` /
+ * `scope-issue-action-requested` events on WordReviewEditorEvent.
+ *
+ * A11y contract:
+ *   - role="dialog", aria-modal="false" (not a hard-focus capture; the
+ *     editor surface remains interactive while the card is open)
+ *   - aria-labelledby points at the header id
+ *   - Escape closes; focus-trap wraps Tab / Shift-Tab
+ *   - An aria-live="polite" region announces the attached issue's
+ *     severity when the card opens with an issue
+ */
+
+import * as React from "react";
+import type {
+  IssueMetadataValue,
+  IssueOwner,
+  IssueSeverity,
+  ScopeCardModel,
+  ScopeIssueAction,
+  WorkflowScopeMode,
+} from "../../api/public-types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TwScopeCardProps {
+  model: ScopeCardModel;
+  onClose: () => void;
+  onModeChange: (mode: WorkflowScopeMode) => void;
+  onIssueAction: (action: ScopeIssueAction) => void;
+  /** Test id applied to the root node. */
+  "data-testid"?: string;
+}
+
+const MODE_OPTIONS: ReadonlyArray<{ mode: WorkflowScopeMode; label: string }> = [
+  { mode: "edit", label: "Edit" },
+  { mode: "suggest", label: "Suggest" },
+  { mode: "comment", label: "Comment" },
+  { mode: "view", label: "View" },
+];
+
+const SEVERITY_COLOR: Record<IssueSeverity, string> = {
+  low: "var(--color-secondary)",
+  medium: "var(--color-warning)",
+  high: "var(--color-warning)",
+  blocker: "var(--color-danger)",
+};
+
+const SEVERITY_LABEL: Record<IssueSeverity, string> = {
+  low: "Low",
+  medium: "Medium",
+  high: "High",
+  blocker: "Blocker",
+};
+
+const OWNER_LABEL: Record<IssueOwner, string> = {
+  procurement: "Procurement",
+  legal: "Legal",
+  risk: "Risk",
+  finance: "Finance",
+  sustainability: "Sustainability",
+};
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export const TwScopeCard: React.FC<TwScopeCardProps> = ({
+  model,
+  onClose,
+  onModeChange,
+  onIssueAction,
+  "data-testid": testId,
+}) => {
+  const rootRef = React.useRef<HTMLDivElement | null>(null);
+  const headerId = React.useId();
+  const liveRegionId = React.useId();
+
+  // --- Focus management ----------------------------------------------------
+  React.useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return undefined;
+    const first = getFocusable(root)[0];
+    first?.focus();
+    return undefined;
+  }, []);
+
+  // --- Escape + click-outside ---------------------------------------------
+  React.useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        onClose();
+      }
+    };
+    const onPointerDown = (event: PointerEvent) => {
+      const root = rootRef.current;
+      if (!root) return;
+      if (event.target instanceof Node && root.contains(event.target)) return;
+      onClose();
+    };
+    window.addEventListener("keydown", onKey, true);
+    window.addEventListener("pointerdown", onPointerDown, true);
+    return () => {
+      window.removeEventListener("keydown", onKey, true);
+      window.removeEventListener("pointerdown", onPointerDown, true);
+    };
+  }, [onClose]);
+
+  // --- Focus trap ----------------------------------------------------------
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== "Tab") return;
+    const root = rootRef.current;
+    if (!root) return;
+    const focusables = getFocusable(root);
+    if (focusables.length === 0) return;
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = document.activeElement;
+    if (event.shiftKey) {
+      if (active === first || !root.contains(active)) {
+        event.preventDefault();
+        last.focus();
+      }
+    } else {
+      if (active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+  };
+
+  const issue = model.issue;
+  const postureLabel = posturePresentationLabel(model.posture);
+
+  return (
+    <div
+      ref={rootRef}
+      className="wre-scope-card pointer-events-auto absolute flex w-80 max-w-[22rem] flex-col gap-2 rounded-lg border border-border bg-canvas p-3 text-sm shadow-[var(--shadow-float)]"
+      role="dialog"
+      aria-modal="false"
+      aria-labelledby={headerId}
+      data-testid={testId ?? "scope-card"}
+      data-scope-id={model.scopeId}
+      data-posture={model.posture}
+      onKeyDown={onKeyDown}
+    >
+      {/* Header --------------------------------------------------------- */}
+      <div className="flex items-center justify-between gap-2">
+        <div
+          id={headerId}
+          className="flex min-w-0 flex-1 items-center gap-2 text-xs font-medium text-primary"
+        >
+          <span
+            className={`wre-scope-rail-icon wre-scope-rail-icon-${posturePresentationIcon(model.posture)}`}
+            aria-hidden="true"
+            style={{ color: postureTokenColor(model.posture) }}
+          />
+          <span className="truncate uppercase tracking-[0.06em]">
+            {postureLabel}
+          </span>
+          {model.label ? (
+            <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 (
+            <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>
+
+      {/* Issue row (R2) ------------------------------------------------- */}
+      {issue ? <IssueRow issue={issue} onAction={onIssueAction} /> : null}
+
+      {/* A11y live region ---------------------------------------------- */}
+      <span
+        id={liveRegionId}
+        role="status"
+        aria-live="polite"
+        className="sr-only"
+      >
+        {issue
+          ? `${postureLabel} scope, ${SEVERITY_LABEL[issue.severity]} severity issue attached: ${issue.title}`
+          : `${postureLabel} scope opened`}
+      </span>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Issue row
+// ---------------------------------------------------------------------------
+
+const IssueRow: React.FC<{
+  issue: IssueMetadataValue;
+  onAction: (action: ScopeIssueAction) => void;
+}> = ({ issue, onAction }) => {
+  const canResolve = issue.checklistState === "open" || issue.checklistState === "acknowledged";
+  const canWaive = issue.checklistState !== "waived";
+  const canEscalate = issue.escalationState !== "requested";
+
+  return (
+    <div
+      className="flex flex-col gap-1.5 rounded-md bg-surface p-2"
+      data-testid="scope-card-issue"
+    >
+      <div className="flex items-center gap-1.5 text-[11px]">
+        <span
+          aria-hidden="true"
+          className="inline-block h-2 w-2 rounded-full"
+          style={{ background: SEVERITY_COLOR[issue.severity] }}
+        />
+        <span className="font-semibold text-primary">
+          {SEVERITY_LABEL[issue.severity]}
+        </span>
+        {issue.owner ? (
+          <span
+            className="rounded-sm border border-border px-1 py-0.5 text-[10px] font-medium uppercase tracking-[0.06em] text-secondary"
+            data-testid="scope-card-issue-owner"
+          >
+            {OWNER_LABEL[issue.owner]}
+          </span>
+        ) : null}
+      </div>
+      <div
+        className="text-xs font-medium leading-snug text-primary"
+        data-testid="scope-card-issue-title"
+      >
+        {issue.title}
+      </div>
+      {issue.summary ? (
+        <div className="text-[11px] leading-snug text-secondary">{issue.summary}</div>
+      ) : null}
+      <div className="flex gap-1">
+        <IssueActionButton
+          label="Resolve"
+          testId="scope-card-issue-resolve"
+          disabled={!canResolve}
+          onClick={() => onAction("resolve")}
+        />
+        <IssueActionButton
+          label="Waive"
+          testId="scope-card-issue-waive"
+          disabled={!canWaive}
+          onClick={() => onAction("waive")}
+        />
+        <IssueActionButton
+          label="Escalate"
+          testId="scope-card-issue-escalate"
+          disabled={!canEscalate}
+          onClick={() => onAction("escalate")}
+        />
+      </div>
+    </div>
+  );
+};
+
+const IssueActionButton: React.FC<{
+  label: string;
+  testId: string;
+  disabled: boolean;
+  onClick: () => void;
+}> = ({ label, testId, disabled, onClick }) => (
+  <button
+    type="button"
+    disabled={disabled}
+    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={onClick}
+    data-testid={testId}
+  >
+    {label}
+  </button>
+);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+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,
+  );
+}
+
+function posturePresentationLabel(posture: ScopeCardModel["posture"]): string {
+  switch (posture) {
+    case "edit":
+      return "Edit";
+    case "suggest":
+      return "Suggest";
+    case "comment":
+      return "Comment";
+    case "view":
+      return "View";
+    case "candidate":
+      return "Proposed";
+    case "preserve-only":
+    case "blocked-import":
+      return "Blocked";
+    default:
+      return "Scope";
+  }
+}
+
+function posturePresentationIcon(posture: ScopeCardModel["posture"]): string {
+  switch (posture) {
+    case "edit":
+      return "pencil";
+    case "suggest":
+      return "sparkles";
+    case "comment":
+      return "message";
+    case "view":
+      return "eye";
+    case "candidate":
+      return "flag";
+    case "preserve-only":
+    case "blocked-import":
+      return "lock";
+    default:
+      return "eye";
+  }
+}
+
+function postureTokenColor(posture: ScopeCardModel["posture"]): string {
+  switch (posture) {
+    case "edit":
+      return "var(--color-accent)";
+    case "suggest":
+    case "candidate":
+      return "var(--color-warning)";
+    case "comment":
+      return "var(--color-insert)";
+    case "preserve-only":
+    case "blocked-import":
+      return "var(--color-danger)";
+    default:
+      return "var(--color-secondary)";
+  }
+}
+
+export default TwScopeCard;