@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/ui/editor-shell-view.tsx

@@ -0,0 +1,144 @@
+import React, { type CSSProperties, type ReactNode } from "react";
+
+import type {
+  ActiveListContext,
+  DocumentNavigationSnapshot,
+  EditorError,
+  FormattingStateSnapshot,
+  InteractionGuardSnapshot,
+  ReviewQueueSnapshot,
+  RuntimeContextAnalyticsSnapshot,
+  RuntimeRenderSnapshot,
+  StyleCatalogSnapshot,
+  WordReviewEditorChromeOptions,
+  WordReviewEditorChromePreset,
+  WordReviewEditorChromeVisibility,
+  WorkflowScopeSnapshot,
+  WorkspaceMode,
+  ZoomLevel,
+} from "../api/public-types.ts";
+import type { SessionCapabilities } from "../runtime/session-capabilities.ts";
+import type { MarkupDisplay } from "./headless/comment-decoration-model.ts";
+import type {
+  ActiveSelectionToolModel,
+  SelectionToolAnchor,
+} from "./headless/selection-tool-types.ts";
+import type { EditorCommandBag } from "./editor-command-bag.ts";
+import type { ReviewRailTab } from "../ui-tailwind/review/tw-review-rail.tsx";
+import { TwReviewWorkspace } from "../ui-tailwind/tw-review-workspace.tsx";
+import type { EditorViewStateSnapshot } from "../api/public-types.ts";
+
+export interface EditorShellViewProps {
+  shellRef: React.RefObject<HTMLDivElement | null>;
+  documentId: string;
+  snapshot: RuntimeRenderSnapshot;
+  loadError: EditorError | null;
+  diagnosticsModeMessage: string | null;
+  accessibilityInstructionsId: string;
+  accessibilityStatusId: string;
+  accessibilityAlertId: string;
+  accessibilityStatusMessage: string;
+  visuallyHiddenStyles: CSSProperties;
+  onShellKeyDownCapture: React.KeyboardEventHandler<HTMLDivElement>;
+  viewState: EditorViewStateSnapshot;
+  markupDisplay: MarkupDisplay;
+  currentUserId: string;
+  capabilities: SessionCapabilities;
+  reviewMode: "editing" | "review";
+  workspaceMode: WorkspaceMode;
+  zoomLevel?: ZoomLevel;
+  formattingState?: FormattingStateSnapshot;
+  activeListContext?: ActiveListContext | null;
+  styleCatalog?: StyleCatalogSnapshot;
+  activeRailTab: ReviewRailTab;
+  activeCommentId?: string;
+  activeRevisionId?: string;
+  showTrackedChanges: boolean;
+  workflowScopeSnapshot?: WorkflowScopeSnapshot | null;
+  interactionGuardSnapshot?: InteractionGuardSnapshot;
+  chromePreset?: WordReviewEditorChromePreset;
+  chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  reviewQueue?: ReviewQueueSnapshot;
+  documentContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
+  selectionContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
+  currentScopeContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
+  activeSelectionTool?: ActiveSelectionToolModel | null;
+  selectionToolAnchor?: SelectionToolAnchor | null;
+  documentNavigation?: DocumentNavigationSnapshot;
+  commands: EditorCommandBag;
+  document: ReactNode;
+  onAddCommentFromSelection?: () => void;
+  onAddCommentFromSuggestion?: () => void;
+  onAcceptSuggestion?: () => void;
+  onRejectSuggestion?: () => void;
+  onEditSuggestion?: () => void;
+  onDismissSelectionToolbar?: () => void;
+  onSelectionToolbarFocusCapture?: React.FocusEventHandler<HTMLDivElement>;
+  onSelectionToolbarBlurCapture?: React.FocusEventHandler<HTMLDivElement>;
+  selectionToolbarRef?: React.Ref<HTMLDivElement>;
+  chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
+}
+
+export function EditorShellView(props: EditorShellViewProps) {
+  const {
+    shellRef,
+    documentId,
+    snapshot,
+    loadError,
+    diagnosticsModeMessage,
+    accessibilityInstructionsId,
+    accessibilityStatusId,
+    accessibilityAlertId,
+    accessibilityStatusMessage,
+    visuallyHiddenStyles,
+    onShellKeyDownCapture,
+    document,
+    commands,
+    ...workspaceProps
+  } = props;
+
+  return (
+    <div
+      ref={shellRef}
+      role="region"
+      aria-label={`Word review editor for ${snapshot.sourceLabel ?? documentId}`}
+      aria-describedby={`${accessibilityInstructionsId} ${accessibilityStatusId}${
+        diagnosticsModeMessage ? ` ${accessibilityAlertId}` : ""
+      }`}
+      className="relative h-full"
+      onKeyDownCapture={onShellKeyDownCapture}
+    >
+      <p id={accessibilityInstructionsId} style={visuallyHiddenStyles}>
+        Press F6 to move focus between the toolbar, document surface, review rail, and status bar.
+      </p>
+      <div
+        id={accessibilityStatusId}
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        style={visuallyHiddenStyles}
+      >
+        {accessibilityStatusMessage}
+      </div>
+      {diagnosticsModeMessage ? (
+        <div
+          id={accessibilityAlertId}
+          data-wre-alert="true"
+          role="alert"
+          aria-live="assertive"
+          aria-atomic="true"
+          tabIndex={-1}
+          className="border-b border-danger/30 bg-danger/5 px-4 py-3 text-sm text-danger"
+        >
+          {diagnosticsModeMessage}
+        </div>
+      ) : null}
+      <TwReviewWorkspace
+        snapshot={snapshot}
+        commands={commands}
+        document={document}
+        {...workspaceProps}
+      />
+    </div>
+  );
+}

package/src/ui/editor-surface/README.md

@@ -0,0 +1,3 @@
+# Editor Surface
+
+The editable document canvas, overlays, and selection-aware rendering belong here.

package/src/ui/editor-surface-controller.tsx

@@ -0,0 +1,66 @@
+import React, { forwardRef } from "react";
+
+import type {
+  DocumentNavigationSnapshot,
+  EditorUser,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowMetadataMarkup,
+  WorkflowScope,
+} from "../api/public-types.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import type { MarkupDisplay } from "./headless/comment-decoration-model.ts";
+import type { SelectionToolbarAnchor } from "./headless/selection-toolbar-model.ts";
+import type { ActiveSelectionToolModel } from "./headless/selection-tool-types.ts";
+import {
+  TwProseMirrorSurface,
+  type TwProseMirrorSurfaceRef,
+} from "../ui-tailwind/editor-surface/tw-prosemirror-surface.tsx";
+import type { MediaPreviewDescriptor } from "../ui-tailwind/editor-surface/pm-state-from-snapshot.ts";
+
+export interface EditorSurfaceControllerProps {
+  currentUser: EditorUser;
+  snapshot: RuntimeRenderSnapshot;
+  canonicalDocument: CanonicalDocumentEnvelope;
+  documentNavigation: DocumentNavigationSnapshot;
+  reviewMode: "editing" | "review";
+  markupDisplay: MarkupDisplay;
+  showUnsupportedObjectPreviews?: boolean;
+  activeRevisionId?: string;
+  activeSelectionToolKind?: ActiveSelectionToolModel["kind"] | null;
+  showTrackedChanges?: boolean;
+  suggestionsEnabled?: boolean;
+  mediaPreviews?: Record<string, MediaPreviewDescriptor>;
+  isPageWorkspace?: boolean;
+  onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;
+  onFocus: React.FocusEventHandler<HTMLDivElement>;
+  onBlur: React.FocusEventHandler<HTMLDivElement>;
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  onInsertText?: (text: string) => void;
+  onDeleteBackward?: () => void;
+  onDeleteForward?: () => void;
+  onInsertTab?: () => void;
+  onOutdentTab?: () => void;
+  onInsertHardBreak?: () => void;
+  onSplitParagraph?: () => void;
+  onUndo?: () => void;
+  onRedo?: () => void;
+  onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  onCommentActivated?: (commentId: string) => void;
+  onRevisionActivated?: (revisionId: string) => void;
+  workflowScopes?: readonly WorkflowScope[];
+  workflowCandidates?: readonly WorkflowCandidateRange[];
+  workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[];
+  activeWorkflowWorkItemId?: string | null;
+  activeWorkflowScopeIds?: readonly string[];
+  workflowMetadata?: readonly WorkflowMetadataMarkup[];
+}
+
+export const EditorSurfaceController = forwardRef<
+  TwProseMirrorSurfaceRef,
+  EditorSurfaceControllerProps
+>(function EditorSurfaceController(props, ref) {
+  return <TwProseMirrorSurface ref={ref} {...props} />;
+});

package/src/ui/headless/comment-decoration-model.ts

@@ -0,0 +1,124 @@
+import type { CommentSidebarSnapshot } from "../../api/public-types";
+
+export interface CommentDecorationModel {
+  threads: CommentDecorationThread[];
+  activeCommentId?: string;
+}
+
+export interface CommentDecorationThread {
+  commentId: string;
+  from: number;
+  to: number;
+  status: CommentSidebarSnapshot["threads"][number]["status"];
+  isActive: boolean;
+}
+
+export interface CommentRangeState {
+  hasComments: boolean;
+  hasOpen: boolean;
+  hasResolved: boolean;
+  hasActive: boolean;
+  count: number;
+  overlapping: CommentDecorationThread[];
+}
+
+export function createCommentDecorationModel(
+  snapshot?: CommentSidebarSnapshot,
+): CommentDecorationModel | undefined {
+  if (!snapshot) {
+    return undefined;
+  }
+
+  return {
+    activeCommentId: snapshot.activeCommentId,
+    threads: snapshot.threads
+      .filter((thread) => thread.anchor.kind !== "detached")
+      .map((thread) => {
+        const anchor = thread.anchor;
+        const from = anchor.kind === "range" ? anchor.from : anchor.kind === "node" ? anchor.at : 0;
+        const to = anchor.kind === "range" ? anchor.to : anchor.kind === "node" ? anchor.at : 0;
+        return {
+          commentId: thread.commentId,
+          from,
+          to,
+          status: thread.status,
+          isActive: thread.isActive,
+        };
+      }),
+  };
+}
+
+export function getCommentRangeState(
+  model: CommentDecorationModel | undefined,
+  from: number,
+  to: number,
+): CommentRangeState {
+  if (!model) {
+    return {
+      hasComments: false,
+      hasOpen: false,
+      hasResolved: false,
+      hasActive: false,
+      count: 0,
+      overlapping: [],
+    };
+  }
+
+  const overlapping = model.threads.filter((thread) =>
+    rangesOverlap(thread.from, thread.to, from, to),
+  );
+  return {
+    hasComments: overlapping.length > 0,
+    hasOpen: overlapping.some((thread) => thread.status === "open"),
+    hasResolved: overlapping.some((thread) => thread.status === "resolved"),
+    hasActive: overlapping.some((thread) => thread.isActive),
+    count: overlapping.length,
+    overlapping,
+  };
+}
+
+export type MarkupDisplay = "clean" | "simple" | "all";
+
+export function getCommentHighlightClass(
+  model: CommentDecorationModel | undefined,
+  from: number,
+  to: number,
+  markupDisplay: MarkupDisplay = "all",
+): string {
+  const state = getCommentRangeState(model, from, to);
+  if (!state.hasComments) {
+    return "";
+  }
+
+  switch (markupDisplay) {
+    case "clean":
+      return state.hasActive ? "bg-comment-soft" : "";
+    case "simple":
+      if (state.hasActive) {
+        return "underline decoration-comment decoration-2 underline-offset-4";
+      }
+      if (state.hasOpen) {
+        return "underline decoration-comment/60 decoration-1 underline-offset-4";
+      }
+      return "underline decoration-comment/40 decoration-1 underline-offset-4";
+    case "all":
+      if (state.hasActive) {
+        return "bg-comment-strong";
+      }
+      if (state.hasOpen) {
+        return "bg-comment-soft";
+      }
+      return "bg-comment-soft opacity-60";
+  }
+}
+
+export function rangesOverlap(
+  leftFrom: number,
+  leftTo: number,
+  rightFrom: number,
+  rightTo: number,
+): boolean {
+  const leftEnd = Math.max(leftFrom, leftTo);
+  const rightEnd = Math.max(rightFrom, rightTo);
+  return leftFrom < rightEnd && rightFrom < leftEnd;
+}

package/src/ui/headless/preserve-editor-selection.ts

@@ -0,0 +1,5 @@
+import type { MouseEvent } from "react";
+
+export function preserveEditorSelectionMouseDown(event: MouseEvent<HTMLElement>): void {
+  event.preventDefault();
+}

package/src/ui/headless/revision-decoration-model.ts

@@ -0,0 +1,128 @@
+import type { TrackedChangesSnapshot, TrackedChangeEntrySnapshot } from "../../api/public-types";
+import { rangesOverlap, type MarkupDisplay } from "./comment-decoration-model";
+
+export interface RevisionDecorationModel {
+  revisions: RevisionDecorationEntry[];
+}
+
+export interface RevisionDecorationEntry {
+  revisionId: string;
+  from: number;
+  to: number;
+  kind: TrackedChangeEntrySnapshot["kind"];
+  status: TrackedChangeEntrySnapshot["status"];
+  actionability: TrackedChangeEntrySnapshot["actionability"];
+  isActive: boolean;
+}
+
+export interface RevisionRangeState {
+  hasChanges: boolean;
+  hasInsertions: boolean;
+  hasDeletions: boolean;
+  hasActive: boolean;
+  count: number;
+  overlapping: RevisionDecorationEntry[];
+}
+
+export function createRevisionDecorationModel(
+  snapshot?: TrackedChangesSnapshot,
+  activeRevisionId?: string,
+): RevisionDecorationModel | undefined {
+  if (!snapshot) {
+    return undefined;
+  }
+
+  return {
+    revisions: snapshot.revisions
+      .filter((rev) => rev.anchor.kind !== "detached" && rev.status === "active")
+      .map((rev) => {
+        const anchor = rev.anchor;
+        const from = anchor.kind === "range" ? anchor.from : anchor.kind === "node" ? anchor.at : 0;
+        const to = anchor.kind === "range" ? anchor.to : anchor.kind === "node" ? anchor.at : 0;
+        return {
+        revisionId: rev.revisionId,
+        from,
+        to,
+        kind: rev.kind,
+        status: rev.status,
+        actionability: rev.actionability,
+        isActive: rev.revisionId === activeRevisionId,
+      };
+      }),
+  };
+}
+
+export function getRevisionRangeState(
+  model: RevisionDecorationModel | undefined,
+  from: number,
+  to: number,
+): RevisionRangeState {
+  if (!model) {
+    return {
+      hasChanges: false,
+      hasInsertions: false,
+      hasDeletions: false,
+      hasActive: false,
+      count: 0,
+      overlapping: [],
+    };
+  }
+
+  const overlapping = model.revisions.filter((rev) =>
+    rangesOverlap(rev.from, rev.to, from, to),
+  );
+  return {
+    hasChanges: overlapping.length > 0,
+    hasInsertions: overlapping.some((rev) => rev.kind === "insertion"),
+    hasDeletions: overlapping.some((rev) => rev.kind === "deletion"),
+    hasActive: overlapping.some((rev) => rev.isActive),
+    count: overlapping.length,
+    overlapping,
+  };
+}
+
+export function getRevisionHighlightClass(
+  model: RevisionDecorationModel | undefined,
+  from: number,
+  to: number,
+  markupDisplay: MarkupDisplay = "all",
+): string {
+  const state = getRevisionRangeState(model, from, to);
+  if (!state.hasChanges) {
+    return "";
+  }
+
+  const activeRing = state.hasActive ? " ring-1 ring-accent/30" : "";
+
+  switch (markupDisplay) {
+    case "clean":
+      // In clean mode, deletions are hidden entirely (caller should not render).
+      // Insertions render as normal text with no decoration.
+      return "";
+    case "simple":
+      if (state.hasInsertions) {
+        return `underline decoration-insert/60 decoration-1 underline-offset-2 text-primary${activeRing}`;
+      }
+      if (state.hasDeletions) {
+        return `text-secondary line-through decoration-danger/70 decoration-1${activeRing}`;
+      }
+      return activeRing;
+    case "all":
+      if (state.hasInsertions) {
+        return `text-primary bg-insert-soft/80 ring-1 ring-insert/20${activeRing}`;
+      }
+      if (state.hasDeletions) {
+        return `text-danger line-through decoration-danger/80 decoration-1 bg-delete-soft/70${activeRing}`;
+      }
+      return activeRing;
+  }
+}
+
+export function shouldHideInCleanMode(
+  model: RevisionDecorationModel | undefined,
+  from: number,
+  to: number,
+): boolean {
+  const state = getRevisionRangeState(model, from, to);
+  return state.hasDeletions;
+}

package/src/ui/headless/selection-helpers.ts

@@ -0,0 +1,54 @@
+import type { SelectionSnapshot } from "../../api/public-types";
+
+export function createSelectionSnapshot(anchor: number, head = anchor): SelectionSnapshot {
+  const from = Math.min(anchor, head);
+  const to = Math.max(anchor, head);
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: {
+      kind: "range",
+      from,
+      to,
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+  };
+}
+
+export function createNodeSelectionSnapshot(at: number, assoc: -1 | 1 = 1): SelectionSnapshot {
+  return {
+    anchor: at,
+    head: at,
+    isCollapsed: true,
+    activeRange: {
+      kind: "node",
+      at,
+      assoc,
+    },
+  };
+}
+
+export function isCollapsedAtBlockStart(
+  selection: SelectionSnapshot,
+  blockFrom: number,
+): boolean {
+  return selection.isCollapsed && selection.head === blockFrom;
+}
+
+export function selectionTouchesRange(
+  selection: SelectionSnapshot,
+  from: number,
+  to: number,
+): boolean {
+  if (selection.isCollapsed) {
+    return false;
+  }
+
+  const selectionFrom = Math.min(selection.anchor, selection.head);
+  const selectionTo = Math.max(selection.anchor, selection.head);
+  return selectionFrom < to && from < selectionTo;
+}

package/src/ui/headless/selection-tool-context.ts

@@ -0,0 +1,19 @@
+import type {
+  DocumentNavigationSnapshot,
+  EditorViewStateSnapshot,
+  RuntimeRenderSnapshot,
+  StyleCatalogSnapshot,
+} from "../../api/public-types";
+import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import type { SelectionToolResolverContext } from "./selection-tool-types";
+
+export interface SelectionToolResolverInput extends SelectionToolResolverContext {
+  snapshot: RuntimeRenderSnapshot;
+  viewState: EditorViewStateSnapshot;
+  capabilities: SessionCapabilities;
+  documentNavigation: DocumentNavigationSnapshot;
+  styleCatalog: StyleCatalogSnapshot;
+  preferListStructureContext?: boolean;
+  addCommentDisabledReason?: string;
+  suppressedSuggestionRevisionId?: string | null;
+}