@beyondwork/docx-react-component 1.0.37 → 1.0.38

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

@@ -0,0 +1,150 @@
+import React, { type ReactNode } from "react";
+
+/**
+ * TwRailCard — shared editorial card primitive consumed by the runtime review
+ * rail tabs (Workflow, Comments, Changes).
+ *
+ * The card is tone-aware: the tone drives a 3px left edge rule, the eyebrow
+ * color, and the optional progress-bar fill via CSS custom properties declared
+ * in `src/ui-tailwind/theme/editor-theme.css` under `.wre-rail-card`.
+ *
+ * This primitive deliberately stays host-agnostic — no workflow, comment, or
+ * revision coupling.  Consumers pass display fields and an optional footer
+ * slot so the card can host accept/reject, reply composer, or resolve actions
+ * without the primitive owning any domain logic.
+ */
+
+export type RailCardTone =
+  | "neutral"
+  | "inReview"
+  | "blocked"
+  | "scheduled"
+  | "resolved";
+
+export interface RailCardAvatar {
+  initials: string;
+  color?: string;
+  alt?: string;
+}
+
+export interface RailCardProgress {
+  value: number;
+  total?: number;
+}
+
+export interface RailCardCounter {
+  label: string;
+  value: string;
+}
+
+export interface TwRailCardProps {
+  tone: RailCardTone;
+  eyebrow: string;
+  title: string;
+  detail?: string;
+  leadingIcon?: ReactNode;
+  avatars?: readonly RailCardAvatar[];
+  avatarOverflowCount?: number;
+  counter?: RailCardCounter;
+  progress?: RailCardProgress;
+  footer?: ReactNode;
+  onClick?: () => void;
+  onSelect?: () => void;
+  isActive?: boolean;
+  dataTestId?: string;
+}
+
+export function TwRailCard(props: TwRailCardProps) {
+  const {
+    tone,
+    eyebrow,
+    title,
+    detail,
+    leadingIcon,
+    avatars,
+    avatarOverflowCount,
+    counter,
+    progress,
+    footer,
+    onClick,
+    onSelect,
+    isActive,
+    dataTestId,
+  } = props;
+
+  const handleClick = onClick || onSelect;
+  const tag: "article" | "button" = handleClick ? "button" : "article";
+
+  const clamped = progress
+    ? Math.max(0, Math.min(1, progress.total && progress.total > 0 ? progress.value / progress.total : progress.value))
+    : 0;
+
+  const commonProps: Record<string, unknown> = {
+    className: "wre-rail-card block w-full text-left",
+    "data-tone": tone,
+    "data-active": isActive ? "true" : "false",
+    "data-testid": dataTestId,
+  };
+
+  if (handleClick) {
+    commonProps.onClick = handleClick;
+    commonProps.type = "button";
+  }
+
+  return React.createElement(
+    tag,
+    commonProps,
+    <>
+      {counter ? (
+        <span className="wre-rail-card__counter" aria-label={counter.label} title={counter.label}>
+          {counter.value}
+        </span>
+      ) : null}
+
+      <span className="wre-rail-card__eyebrow">
+        {leadingIcon ? <span aria-hidden="true">{leadingIcon}</span> : null}
+        {eyebrow}
+      </span>
+
+      <p className="wre-rail-card__title">{title}</p>
+
+      {detail ? <p className="wre-rail-card__detail">{detail}</p> : null}
+
+      {avatars && avatars.length > 0 ? (
+        <span className="wre-rail-card__avatars" aria-hidden={avatars.every((a) => !a.alt) ? "true" : undefined}>
+          {avatars.map((avatar, index) => (
+            <span
+              key={`${avatar.initials}-${index}`}
+              className="wre-rail-card__avatar"
+              style={avatar.color ? { background: avatar.color } : undefined}
+              title={avatar.alt}
+              aria-label={avatar.alt}
+            >
+              {avatar.initials}
+            </span>
+          ))}
+          {avatarOverflowCount && avatarOverflowCount > 0 ? (
+            <span className="wre-rail-card__avatar-counter">+{avatarOverflowCount}</span>
+          ) : null}
+        </span>
+      ) : null}
+
+      {footer ? <div className="wre-rail-card__footer">{footer}</div> : null}
+
+      {progress ? (
+        <span
+          className="wre-rail-card__progress"
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={progress.total ?? 1}
+          aria-valuenow={progress.value}
+        >
+          <span
+            className="wre-rail-card__progress-fill"
+            style={{ width: `${Math.round(clamped * 100)}%` }}
+          />
+        </span>
+      ) : null}
+    </>,
+  );
+}

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

@@ -0,0 +1,52 @@
+import React from "react";
+import { HelpCircle, Search } from "lucide-react";
+
+/**
+ * Thin pinned footer rendered at the bottom of the review rail.  The footer
+ * auto-hides when neither `onSearch` nor `helpHref` is supplied, so existing
+ * hosts that do not opt in see no change (progressive disclosure, DESIGN.md
+ * §5.4).
+ */
+export interface TwReviewRailFooterProps {
+  onSearch?: () => void;
+  helpHref?: string;
+  helpLabel?: string;
+  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";
+
+export function TwReviewRailFooter(props: TwReviewRailFooterProps) {
+  const searchLabel = props.searchLabel ?? "SEARCH";
+  const helpLabel = props.helpLabel ?? "HELP";
+
+  if (!props.onSearch && !props.helpHref) {
+    return null;
+  }
+
+  return (
+    <footer className="flex h-10 shrink-0 items-center gap-2 border-t border-border/60 px-3">
+      {props.onSearch ? (
+        <button
+          type="button"
+          onClick={props.onSearch}
+          className={`inline-flex items-center gap-1.5 rounded-sm px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.14em] text-tertiary transition-colors hover:text-secondary ${focusRingClass}`}
+        >
+          <Search aria-hidden="true" className="h-3 w-3" />
+          <span>{searchLabel}</span>
+        </button>
+      ) : null}
+
+      {props.helpHref ? (
+        <a
+          href={props.helpHref}
+          className={`inline-flex items-center gap-1.5 rounded-sm px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.14em] text-tertiary transition-colors hover:text-secondary ${focusRingClass}`}
+        >
+          <HelpCircle aria-hidden="true" className="h-3 w-3" />
+          <span>{helpLabel}</span>
+        </a>
+      ) : null}
+    </footer>
+  );
+}

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

@@ -1,4 +1,4 @@
-import React from "react";
+import React, { type ReactNode } from "react";
 
 import * as Tabs from "@radix-ui/react-tabs";
 import * as ScrollArea from "@radix-ui/react-scroll-area";
@@ -12,11 +12,35 @@ import type {
   TrackedChangesSnapshot,
   TrackedChangeEntrySnapshot,
 } from "../../api/public-types";
+import type { ScopeRailSegment } from "../../runtime/layout";
 import type { MarkupDisplay } from "../../ui/headless/comment-decoration-model";
 import { TwCommentSidebar } from "./tw-comment-sidebar";
 import { TwRevisionSidebar } from "./tw-revision-sidebar";
+import { TwWorkflowTab } from "./tw-workflow-tab";
+import {
+  TwReviewRailFooter,
+  type TwReviewRailFooterProps,
+} from "./tw-review-rail-footer";
 
-export type ReviewRailTab = "comments" | "changes";
+/**
+ * Review rail with three tabs (Comments / Changes / Workflow) that matches
+ * the editorial reference mock while preserving the shipped R3a surface.
+ *
+ * The Workflow tab reads `scopeRailSegments` from the runtime facet — that
+ * stays the default path.  For hosts that need to override the Workflow card
+ * content (CLM, BW, agent integrations that derive their own model), pass
+ * `workflowTab` as a ReactNode and it will replace the built-in projection.
+ * Either way policy stays host-side; the runtime rail remains projection-only.
+ *
+ * Optional editorial surface (harness-pass §4.5):
+ *   - `intelligenceHeader={true}` turns on the DOCUMENT INTELLIGENCE header +
+ *     underline-active chip style.  Off by default so existing pill-tab
+ *     consumers see no change.
+ *   - `workflowScopesTitle?: string` overrides the header title.
+ *   - `railFooter?: TwReviewRailFooterProps` mounts the SEARCH / HELP footer.
+ */
+
+export type ReviewRailTab = "comments" | "changes" | "workflow";
 
 export interface TwReviewRailProps {
   activeTab: ReviewRailTab;
@@ -30,6 +54,34 @@ export interface TwReviewRailProps {
   contextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
   activeCommentId?: string;
   activeRevisionId?: string;
+  /**
+   * Scope rail segments used by the Workflow tab.  Consumers typically
+   * pass `ref.layout.getAllScopeRailSegments()` here.  When omitted the
+   * Workflow tab renders an empty state (unless `workflowTab` is set).
+   */
+  scopeRailSegments?: readonly ScopeRailSegment[];
+  activeScopeId?: string | null;
+  /**
+   * Optional host-provided Workflow-tab override.  When supplied this
+   * ReactNode replaces the default TwWorkflowTab content while still using
+   * the same tab chrome.  Hosts retain ownership of workflow/CLM policy.
+   */
+  workflowTab?: ReactNode;
+  /** Count badge shown next to the Workflow trigger. Defaults to segment count. */
+  workflowCount?: number;
+  /** Editorial header title — defaults to "Review" or tab-aware copy. */
+  workflowScopesTitle?: string;
+  /** Editorial header eyebrow — defaults to "DOCUMENT INTELLIGENCE". */
+  intelligenceEyebrow?: string;
+  /**
+   * Turn on the editorial DOCUMENT INTELLIGENCE header + underline-active
+   * tab chip.  Defaults to `false` so existing pill-tab callers see no
+   * change.
+   */
+  intelligenceHeader?: boolean;
+  /** Utility footer with SEARCH / HELP links.  Hides when unset. */
+  railFooter?: TwReviewRailFooterProps;
+
   onActiveTabChange: (tab: ReviewRailTab) => void;
   onOpenComment?: (thread: CommentSidebarThreadSnapshot) => void;
   onResolveComment?: (commentId: string) => void;
@@ -41,22 +93,38 @@ export interface TwReviewRailProps {
   onRejectRevision?: (revisionId: string) => void;
   onAcceptAllChanges?: () => void;
   onRejectAllChanges?: () => void;
+  onOpenScope?: (segment: ScopeRailSegment) => void;
 }
 
 const focusRingClass =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
 
+const PILL_TRIGGER_CLASS = `flex-1 rounded-lg px-3 py-1.5 text-xs font-medium text-tertiary transition-colors data-[state=active]:bg-surface data-[state=active]:text-primary data-[state=active]:shadow-[0_1px_0_var(--color-shadow)] outline-none ${focusRingClass}`;
+
 export function TwReviewRail(props: TwReviewRailProps) {
   const variant = props.variant ?? "docked";
+  const editorial = props.intelligenceHeader ?? false;
+  const intelligenceEyebrow =
+    props.intelligenceEyebrow ?? "DOCUMENT INTELLIGENCE";
+  const headerTitle = resolveHeaderTitle(props);
+  const workflowSegments = props.scopeRailSegments ?? [];
+  const workflowCount =
+    props.workflowCount ?? (props.workflowTab ? undefined : workflowSegments.length);
+  const widthClass = editorial ? "w-[360px]" : "w-[336px]";
+  const drawerWidthClass = editorial
+    ? "w-[min(360px,calc(100vw-1rem))]"
+    : "w-[min(336px,calc(100vw-1rem))]";
+
   return (
     <aside
       aria-label="Review rail"
       data-wre-drawer={variant === "drawer" ? "true" : "false"}
+      data-editorial-header={editorial ? "true" : "false"}
       className={[
         "flex flex-col border-l border-border/60 bg-[var(--color-sidebar-tint)]",
         variant === "drawer"
-          ? "h-full w-[min(336px,calc(100vw-1rem))] max-w-full shrink-0 shadow-[0_18px_40px_-22px_var(--color-shadow-strong)]"
-          : "w-[336px] shrink-0",
+          ? `h-full ${drawerWidthClass} max-w-full shrink-0 shadow-[var(--shadow-float)]`
+          : `${widthClass} shrink-0`,
       ].join(" ")}
     >
       <Tabs.Root
@@ -64,25 +132,84 @@ export function TwReviewRail(props: TwReviewRailProps) {
         onValueChange={(v: string) => props.onActiveTabChange(v as ReviewRailTab)}
         className="flex flex-1 flex-col min-h-0"
       >
-        <Tabs.List className="flex shrink-0 border-b border-border/60 px-3 py-2">
+        {editorial ? (
+          <header className="shrink-0 px-4 pt-[18px] pb-3">
+            <p className="text-[10px] font-semibold uppercase tracking-[0.18em] text-tertiary">
+              {intelligenceEyebrow}
+            </p>
+            <p className="mt-1 text-[16px] font-semibold text-primary">
+              {headerTitle}
+            </p>
+          </header>
+        ) : null}
+
+        <Tabs.List
+          className={
+            editorial
+              ? "flex shrink-0 items-center gap-2 border-b border-border/60 px-2"
+              : "flex shrink-0 border-b border-border/60 px-3 py-2"
+          }
+          aria-label="Review rail sections"
+        >
+          <Tabs.Trigger
+            value="workflow"
+            className={
+              editorial
+                ? `wre-rail-tab outline-none ${focusRingClass}`
+                : PILL_TRIGGER_CLASS
+            }
+          >
+            {editorial ? "Workflow" : "Workflow "}
+            {workflowCount !== undefined && workflowCount > 0 ? (
+              <span
+                className={
+                  editorial
+                    ? "wre-rail-tab__count"
+                    : "ml-1 inline-flex min-w-[14px] items-center justify-center rounded-full bg-subtle px-1.5 py-px text-[10px] font-medium text-tertiary"
+                }
+              >
+                {workflowCount}
+              </span>
+            ) : null}
+          </Tabs.Trigger>
           <Tabs.Trigger
             value="comments"
-            className={`flex-1 rounded-lg px-3 py-1.5 text-xs font-medium text-tertiary transition-colors data-[state=active]:bg-surface data-[state=active]:text-primary data-[state=active]:shadow-[0_1px_0_var(--color-shadow)] outline-none ${focusRingClass}`}
+            className={
+              editorial
+                ? `wre-rail-tab outline-none ${focusRingClass}`
+                : PILL_TRIGGER_CLASS
+            }
           >
-            Comments{" "}
+            {editorial ? "Comments" : "Comments "}
             {props.comments.totalCount > 0 ? (
-              <span className="ml-1 inline-flex min-w-[14px] items-center justify-center rounded-full bg-subtle px-1.5 py-px text-[10px] font-medium text-tertiary">
+              <span
+                className={
+                  editorial
+                    ? "wre-rail-tab__count"
+                    : "ml-1 inline-flex min-w-[14px] items-center justify-center rounded-full bg-subtle px-1.5 py-px text-[10px] font-medium text-tertiary"
+                }
+              >
                 {props.comments.totalCount}
               </span>
             ) : null}
           </Tabs.Trigger>
           <Tabs.Trigger
             value="changes"
-            className={`flex-1 rounded-lg px-3 py-1.5 text-xs font-medium text-tertiary transition-colors data-[state=active]:bg-surface data-[state=active]:text-primary data-[state=active]:shadow-[0_1px_0_var(--color-shadow)] outline-none ${focusRingClass}`}
+            className={
+              editorial
+                ? `wre-rail-tab outline-none ${focusRingClass}`
+                : PILL_TRIGGER_CLASS
+            }
           >
-            Changes{" "}
+            {editorial ? "Changes" : "Changes "}
             {props.trackedChanges.totalCount > 0 ? (
-              <span className="ml-1 inline-flex min-w-[14px] items-center justify-center rounded-full bg-subtle px-1.5 py-px text-[10px] font-medium text-tertiary">
+              <span
+                className={
+                  editorial
+                    ? "wre-rail-tab__count"
+                    : "ml-1 inline-flex min-w-[14px] items-center justify-center rounded-full bg-subtle px-1.5 py-px text-[10px] font-medium text-tertiary"
+                }
+              >
                 {props.trackedChanges.totalCount}
               </span>
             ) : null}
@@ -91,6 +218,16 @@ export function TwReviewRail(props: TwReviewRailProps) {
 
         <ScrollArea.Root className="flex-1 min-h-0">
           <ScrollArea.Viewport className="h-full w-full">
+            <Tabs.Content value="workflow" className="p-3 outline-none">
+              {props.workflowTab ?? (
+                <TwWorkflowTab
+                  segments={workflowSegments}
+                  activeScopeId={props.activeScopeId ?? null}
+                  onOpenScope={props.onOpenScope}
+                />
+              )}
+            </Tabs.Content>
+
             <Tabs.Content value="comments" className="p-3 outline-none">
               <TwCommentSidebar
                 currentUserId={props.currentUserId}
@@ -125,6 +262,24 @@ export function TwReviewRail(props: TwReviewRailProps) {
           </ScrollArea.Scrollbar>
         </ScrollArea.Root>
       </Tabs.Root>
+
+      {props.railFooter ? <TwReviewRailFooter {...props.railFooter} /> : null}
     </aside>
   );
 }
+
+function resolveHeaderTitle(props: TwReviewRailProps): string {
+  if (props.workflowScopesTitle) {
+    return props.workflowScopesTitle;
+  }
+  if (props.activeTab === "workflow") {
+    return "Workflow Scopes";
+  }
+  if (props.activeTab === "comments") {
+    return "Comments";
+  }
+  if (props.activeTab === "changes") {
+    return "Tracked Changes";
+  }
+  return "Review";
+}

package/src/ui-tailwind/review/tw-workflow-tab.tsx

@@ -0,0 +1,108 @@
+/**
+ * Workflow tab content for the review rail.
+ *
+ * Renders scope cards sourced from `ref.layout.getAllScopeRailSegments()`.
+ * Cards mirror the right-sidebar "Document Intelligence / Workflow Scopes"
+ * panel in image copy.png with state chips + labels.  Clicking a card
+ * forwards to `onOpenScope(segment)` so consumers can scroll to the scope
+ * and focus the rail label.
+ */
+
+import React from "react";
+import type { ScopeRailSegment, ScopeRailPosture } from "../../runtime/layout";
+
+export interface TwWorkflowTabProps {
+  segments: readonly ScopeRailSegment[];
+  activeScopeId?: string | null;
+  onOpenScope?: (segment: ScopeRailSegment) => void;
+}
+
+const POSTURE_META: Record<
+  ScopeRailPosture,
+  { chip: string; kind: "accent" | "warning" | "insert" | "secondary" | "danger" }
+> = {
+  edit: { chip: "EDIT", kind: "accent" },
+  suggest: { chip: "SUGGEST", kind: "warning" },
+  comment: { chip: "COMMENT", kind: "insert" },
+  view: { chip: "IN REVIEW", kind: "secondary" },
+  candidate: { chip: "SCHEDULED", kind: "warning" },
+  "preserve-only": { chip: "BLOCKED REGION", kind: "danger" },
+  "blocked-import": { chip: "BLOCKED REGION", kind: "danger" },
+};
+
+export const TwWorkflowTab: React.FC<TwWorkflowTabProps> = ({
+  segments,
+  activeScopeId,
+  onOpenScope,
+}) => {
+  // Dedupe by scopeId so a scope spanning multiple pages shows once.
+  const byScopeId = new Map<string, ScopeRailSegment>();
+  for (const segment of segments) {
+    if (!byScopeId.has(segment.scopeId)) {
+      byScopeId.set(segment.scopeId, segment);
+    }
+  }
+  const uniqueSegments = Array.from(byScopeId.values());
+
+  if (uniqueSegments.length === 0) {
+    return (
+      <div
+        className="wre-workflow-tab-empty rounded-md border border-dashed border-border/60 bg-canvas/50 p-4 text-[11px] text-tertiary"
+        data-testid="workflow-tab-empty"
+      >
+        <div className="font-semibold uppercase tracking-[0.1em] text-secondary">
+          Document Intelligence
+        </div>
+        <div className="mt-1 text-[11px] text-tertiary">
+          No workflow scopes on this document yet.
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="wre-workflow-tab flex flex-col gap-2" data-testid="workflow-tab">
+      <div className="mb-1">
+        <div className="text-[10px] font-semibold uppercase tracking-[0.14em] text-accent">
+          Document Intelligence
+        </div>
+        <div className="text-[15px] font-semibold text-primary">Workflow Scopes</div>
+      </div>
+      {uniqueSegments.map((segment) => {
+        const meta = POSTURE_META[segment.posture];
+        const isActive = activeScopeId === segment.scopeId || segment.isActiveWorkItem;
+        return (
+          <button
+            key={segment.scopeId}
+            type="button"
+            className={`wre-workflow-card flex flex-col gap-1 rounded-md border border-border/50 bg-canvas p-3 text-left transition-shadow hover:shadow-md ${
+              isActive ? "ring-1 ring-accent/60" : ""
+            }`}
+            onClick={onOpenScope ? () => onOpenScope(segment) : undefined}
+            data-scope-id={segment.scopeId}
+            data-posture={segment.posture}
+          >
+            <div className="flex items-center gap-2 text-[10px] font-semibold uppercase tracking-[0.12em]">
+              <span
+                className={`wre-workflow-card-chip wre-workflow-card-chip-${meta.kind} inline-flex items-center gap-1 rounded-full px-2 py-0.5`}
+                data-kind={meta.kind}
+              >
+                {meta.chip}
+              </span>
+              <span className="text-tertiary">Page {segment.pageIndex + 1}</span>
+            </div>
+            <div className="text-[13px] font-semibold text-primary">
+              {segment.label || segment.scopeId}
+            </div>
+            <div className="text-[11px] text-tertiary">
+              Section {segment.sectionIndex + 1}
+              {segment.isActiveWorkItem ? " • Active work item" : ""}
+            </div>
+          </button>
+        );
+      })}
+    </div>
+  );
+};
+
+export default TwWorkflowTab;