@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/ui-tailwind/editor-surface/search-plugin.ts

@@ -0,0 +1,168 @@
+/**
+ * ProseMirror search/highlight plugin for the editor surface.
+ *
+ * Provides in-document search with optional case sensitivity and regex support.
+ * Matched ranges are shown as inline decorations with a configurable highlight color.
+ *
+ * Usage:
+ *   1. Include createSearchPlugin() in the editor plugin list.
+ *   2. Call performSearch(state, query, options) to compute matches.
+ *   3. Dispatch the results into the plugin state via searchPluginKey meta.
+ *   4. Call clearSearch(state, dispatch) to remove all highlights.
+ */
+
+import { Plugin, PluginKey } from "prosemirror-state";
+import type { EditorState, Transaction } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+
+import type {
+  SearchOptions as PublicSearchOptions,
+} from "../../api/public-types";
+import {
+  buildSearchPattern,
+  createSearchExcerpt,
+  findSearchMatches,
+  searchSecondaryStories,
+  type SecondaryStorySearchResult,
+  type SearchTextOptions,
+} from "../../core/search/search-text.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SearchResult {
+  from: number;
+  to: number;
+  text: string;
+  index: number;
+}
+
+export interface SearchOptions extends PublicSearchOptions, SearchTextOptions {
+  regex?: boolean;
+  highlightColor?: string;
+}
+
+export const DEFAULT_SEARCH_HIGHLIGHT_COLOR = "#fde68a";
+
+// ---------------------------------------------------------------------------
+// Plugin state
+// ---------------------------------------------------------------------------
+
+interface SearchPluginState {
+  results: SearchResult[];
+  highlightColor: string | null;
+}
+
+export const searchPluginKey = new PluginKey<SearchPluginState>("search");
+
+// ---------------------------------------------------------------------------
+// Plugin factory
+// ---------------------------------------------------------------------------
+
+export function createSearchPlugin(): Plugin<SearchPluginState> {
+  return new Plugin<SearchPluginState>({
+    key: searchPluginKey,
+
+    state: {
+      init(): SearchPluginState {
+        return { results: [], highlightColor: null };
+      },
+
+      apply(tr: Transaction, pluginState: SearchPluginState): SearchPluginState {
+        const meta = tr.getMeta(searchPluginKey) as SearchPluginState | undefined;
+        if (meta) return meta;
+        return pluginState;
+      },
+    },
+
+    props: {
+      decorations(state: EditorState): DecorationSet {
+        const pluginState = searchPluginKey.getState(state);
+        if (
+          !pluginState ||
+          pluginState.results.length === 0 ||
+          !pluginState.highlightColor
+        ) {
+          return DecorationSet.empty;
+        }
+
+        const decos = pluginState.results.map((r) =>
+          Decoration.inline(r.from, r.to, {
+            style: `background-color: ${pluginState.highlightColor}; border-radius: 2px;`,
+            class: "search-highlight",
+          }),
+        );
+
+        return DecorationSet.create(state.doc, decos);
+      },
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Search computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan all text nodes in the document for matches of `query`.
+ * Returns an array of match ranges; does not dispatch anything.
+ * To apply highlights, set the results on the plugin via:
+ *   view.dispatch(view.state.tr.setMeta(searchPluginKey, { results, highlightColor }))
+ */
+export function performSearch(
+  state: EditorState,
+  query: string,
+  options: SearchOptions = {},
+): SearchResult[] {
+  const pattern = buildSearchPattern(query, options);
+  if (!pattern) return [];
+
+  const results: SearchResult[] = [];
+
+  state.doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return;
+
+    let match: RegExpExecArray | null;
+    pattern.lastIndex = 0;
+    while ((match = pattern.exec(node.text)) !== null) {
+      results.push({
+        from: pos + match.index,
+        to: pos + match.index + match[0].length,
+        text: match[0],
+        index: results.length,
+      });
+
+      if (match[0].length === 0) {
+        pattern.lastIndex += 1;
+      }
+    }
+  });
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Clear helper (ProseMirror Command signature)
+// ---------------------------------------------------------------------------
+
+/**
+ * ProseMirror command that clears all search highlights from the plugin state.
+ */
+export function clearSearch(
+  state: EditorState,
+  dispatch?: (tr: Transaction) => void,
+): boolean {
+  if (!dispatch) return true;
+  dispatch(
+    state.tr.setMeta(searchPluginKey, { results: [], highlightColor: null }),
+  );
+  return true;
+}
+
+export {
+  createSearchExcerpt,
+  findSearchMatches,
+  searchSecondaryStories,
+};
+export type { SecondaryStorySearchResult };

package/src/ui-tailwind/editor-surface/surface-build-keys.ts

@@ -0,0 +1,63 @@
+import type {
+  EditorStoryTarget,
+  EditorSurfaceSnapshot,
+} from "../../api/public-types.ts";
+
+const surfaceIdentityMap = new WeakMap<EditorSurfaceSnapshot, number>();
+let nextSurfaceIdentity = 0;
+
+function getSurfaceIdentity(surface: EditorSurfaceSnapshot): number {
+  const cached = surfaceIdentityMap.get(surface);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const identity = nextSurfaceIdentity;
+  nextSurfaceIdentity += 1;
+  surfaceIdentityMap.set(surface, identity);
+  return identity;
+}
+
+export function createSurfaceDocumentBuildKey(input: {
+  surface: EditorSurfaceSnapshot | null | undefined;
+  activeStory: EditorStoryTarget;
+  mediaPreviewKey: string;
+  showUnsupportedObjectPreviews?: boolean;
+}): string {
+  return JSON.stringify({
+    surfaceIdentity:
+      input.surface === undefined || input.surface === null
+        ? "loading"
+        : getSurfaceIdentity(input.surface),
+    activeStory: input.activeStory,
+    mediaPreviewKey: input.mediaPreviewKey,
+    showUnsupportedObjectPreviews: input.showUnsupportedObjectPreviews ?? false,
+  });
+}
+
+export function createSurfaceDecorationKey(input: {
+  markupDisplay: string;
+  showTrackedChanges: boolean;
+  canEdit: boolean;
+  activeCommentId?: string;
+  activeRevisionId?: string;
+  workflowScopeSignature?: string;
+  workflowCandidateSignature?: string;
+  workflowBlockedSignature?: string;
+  workflowMetadataSignature?: string;
+  activeWorkflowWorkItemId?: string | null;
+  activeWorkflowScopeIds?: readonly string[];
+}): string {
+  return JSON.stringify({
+    markupDisplay: input.markupDisplay,
+    showTrackedChanges: input.showTrackedChanges,
+    canEdit: input.canEdit,
+    activeCommentId: input.activeCommentId ?? null,
+    activeRevisionId: input.activeRevisionId ?? null,
+    workflowScopeSignature: input.workflowScopeSignature ?? null,
+    workflowCandidateSignature: input.workflowCandidateSignature ?? null,
+    workflowBlockedSignature: input.workflowBlockedSignature ?? null,
+    workflowMetadataSignature: input.workflowMetadataSignature ?? null,
+    activeWorkflowWorkItemId: input.activeWorkflowWorkItemId ?? null,
+    activeWorkflowScopeIds: input.activeWorkflowScopeIds ?? [],
+  });
+}

package/src/ui-tailwind/editor-surface/tw-caret.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+
+import type { SelectionSnapshot } from "../../api/public-types";
+
+export function renderTwCaret(selection: SelectionSnapshot, position: number) {
+  return selection.isCollapsed && selection.anchor === position ? (
+    <span
+      aria-hidden="true"
+      className="inline-block w-0.5 h-[1.2em] bg-accent rounded-full align-middle animate-wre-blink"
+    />
+  ) : null;
+}

package/src/ui-tailwind/editor-surface/tw-editor-surface.tsx

@@ -0,0 +1,150 @@
+import React, { type FocusEventHandler, useMemo } from "react";
+
+import type {
+  EditorUser,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+} from "../../api/public-types";
+import {
+  createCommentDecorationModel,
+  type MarkupDisplay,
+} from "../../ui/headless/comment-decoration-model";
+import { createRevisionDecorationModel } from "../../ui/headless/revision-decoration-model";
+import { createEditorKeyboardHandler } from "../../ui/headless/use-editor-keyboard";
+import { TwOpaqueBlock } from "./tw-opaque-block";
+import { TwParagraphBlock } from "./tw-paragraph-block";
+
+export interface TwEditorSurfaceProps {
+  currentUser: EditorUser;
+  snapshot: RuntimeRenderSnapshot;
+  reviewMode: "editing" | "review";
+  markupDisplay: MarkupDisplay;
+  activeRevisionId?: string;
+  /** When false, revision decorations are suppressed in the document surface. */
+  showTrackedChanges?: boolean;
+  onFocus: FocusEventHandler<HTMLDivElement>;
+  onBlur: FocusEventHandler<HTMLDivElement>;
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  onInsertText?: (text: string) => void;
+  onDeleteBackward?: () => void;
+  onDeleteForward?: () => void;
+  onInsertTab?: () => void;
+  onInsertHardBreak?: () => void;
+  onSplitParagraph?: () => void;
+  onCommentActivated?: (commentId: string) => void;
+  onRevisionActivated?: (revisionId: string) => void;
+}
+
+export function TwEditorSurface(props: TwEditorSurfaceProps) {
+  const { currentUser, markupDisplay, onBlur, onFocus, snapshot } = props;
+  const surface = snapshot.surface;
+
+  const canEdit = Boolean(
+    surface && snapshot.isReady && !snapshot.readOnly && !snapshot.fatalError,
+  );
+
+  const commentDecorations = useMemo(
+    () => createCommentDecorationModel(snapshot.comments),
+    [snapshot.comments],
+  );
+
+  const showTrackedChanges = props.showTrackedChanges !== false;
+  const revisionDecorations = useMemo(
+    () => showTrackedChanges
+      ? createRevisionDecorationModel(snapshot.trackedChanges, props.activeRevisionId)
+      : undefined,
+    [snapshot.trackedChanges, props.activeRevisionId, showTrackedChanges],
+  );
+
+  const handleKeyDown = useMemo(() => {
+    if (!surface) return undefined;
+    return createEditorKeyboardHandler(
+      {
+        selection: snapshot.selection,
+        storySize: surface.storySize,
+        canEdit,
+      },
+      {
+        onSelectionChange: props.onSelectionChange,
+        onInsertText: props.onInsertText,
+        onDeleteBackward: props.onDeleteBackward,
+        onDeleteForward: props.onDeleteForward,
+        onInsertTab: props.onInsertTab,
+        onInsertHardBreak: props.onInsertHardBreak,
+        onSplitParagraph: props.onSplitParagraph,
+      },
+    );
+  }, [surface, snapshot.selection, canEdit, props]);
+
+  const fontClass = markupDisplay === "clean"
+    ? "font-[family-name:var(--font-legal-sans)]"
+    : "font-[family-name:var(--font-legal-serif)]";
+
+  return (
+    <section aria-label="Document canvas" className="min-w-0">
+      <div
+        aria-label="Document surface"
+        aria-multiline="true"
+        role="textbox"
+        tabIndex={0}
+        onFocus={onFocus}
+        onBlur={onBlur}
+        onKeyDown={handleKeyDown}
+        className={`bg-transparent border-none px-12 py-10 outline-offset-1 ${fontClass}`}
+      >
+        {/* Document header */}
+        <div className="flex justify-between gap-4 items-start mb-5">
+          <div>
+            <h1 className="font-[family-name:var(--font-legal-serif)] text-2xl leading-tight text-primary">
+              {snapshot.sourceLabel ?? "Document draft"}
+            </h1>
+            <p className="text-xs text-secondary mt-2">
+              {snapshot.sessionId} · {snapshot.documentStats.storyLength} chars
+            </p>
+          </div>
+          <span className="text-xs text-secondary whitespace-nowrap">
+            Reviewer {currentUser.displayName}
+          </span>
+        </div>
+
+        {/* Document blocks */}
+        <div className="space-y-4 pl-10 relative">
+          {surface ? (
+            surface.blocks.map((block) =>
+              block.kind === "paragraph" ? (
+                <TwParagraphBlock
+                  key={block.blockId}
+                  block={block}
+                  selection={snapshot.selection}
+                  markupDisplay={markupDisplay}
+                  commentDecorations={commentDecorations}
+                  revisionDecorations={revisionDecorations}
+                  onSelectionChange={props.onSelectionChange}
+                  onCommentActivated={props.onCommentActivated}
+                  onRevisionActivated={props.onRevisionActivated}
+                />
+              ) : block.kind === "opaque_block" ? (
+                <TwOpaqueBlock
+                  key={block.blockId}
+                  block={block}
+                  selection={snapshot.selection}
+                  onSelectionChange={props.onSelectionChange}
+                />
+              ) : null,
+            )
+          ) : (
+            <p className="text-sm text-secondary leading-relaxed">
+              Loading the review surface. Compatibility cues and edit actions appear here once
+              the runtime snapshot is ready.
+            </p>
+          )}
+          {snapshot.fatalError ? (
+            <p className="text-sm text-danger">
+              Fatal runtime error: {snapshot.fatalError.message}
+            </p>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  );
+}

package/src/ui-tailwind/editor-surface/tw-inline-token.tsx

@@ -0,0 +1,129 @@
+import React from "react";
+
+import type { SelectionSnapshot, SurfaceInlineSegment } from "../../api/public-types";
+import type { CommentDecorationModel } from "../../ui/headless/comment-decoration-model";
+import { getCommentHighlightClass, type MarkupDisplay } from "../../ui/headless/comment-decoration-model";
+import { createSelectionSnapshot, selectionTouchesRange } from "../../ui/headless/selection-helpers";
+import { renderTwCaret } from "./tw-caret";
+
+export interface TwInlineTokenProps {
+  segment: SurfaceInlineSegment;
+  selection: SelectionSnapshot;
+  markupDisplay: MarkupDisplay;
+  commentDecorations?: CommentDecorationModel;
+  onSelectionChange?: (selection: SelectionSnapshot) => 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";
+
+export function TwInlineToken(props: TwInlineTokenProps) {
+  const { segment, selection } = props;
+  const selected = selectionTouchesRange(selection, segment.from, segment.to);
+  const commentClass = getCommentHighlightClass(
+    props.commentDecorations,
+    segment.from,
+    segment.to,
+    props.markupDisplay,
+  );
+
+  const showSymbols = props.markupDisplay !== "clean";
+
+  if (segment.kind === "tab") {
+    return (
+      <button
+        type="button"
+        tabIndex={-1}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          props.onSelectionChange?.(createSelectionSnapshot(segment.from, segment.to));
+        }}
+        className={`inline-flex items-center border-none bg-transparent cursor-text ${commentClass} ${selected ? "bg-surface-hover" : ""} ${focusRingClass} ${showSymbols ? "mx-0.5 text-tertiary/50" : "w-8"}`}
+        title="Tab character"
+      >
+        {renderTwCaret(selection, segment.from)}
+        {showSymbols ? <span className="text-xs">→</span> : <span className="w-8" />}
+        {renderTwCaret(selection, segment.to)}
+      </button>
+    );
+  }
+
+  if (segment.kind === "hard_break") {
+    return (
+      <>
+        <button
+          type="button"
+          tabIndex={-1}
+          onMouseDown={(e) => {
+            e.preventDefault();
+            props.onSelectionChange?.(createSelectionSnapshot(segment.from, segment.to));
+          }}
+          className={`inline-flex items-center border-none bg-transparent cursor-text ${commentClass} ${selected ? "bg-surface-hover" : ""} ${focusRingClass} ${showSymbols ? "mx-0.5 text-tertiary/40" : ""}`}
+          title="Line break"
+        >
+          {renderTwCaret(selection, segment.from)}
+          {showSymbols ? <span className="text-xs">↵</span> : null}
+          {renderTwCaret(selection, segment.to)}
+        </button>
+        <br />
+      </>
+    );
+  }
+
+  if (segment.kind === "image") {
+    const isMissing = segment.state === "missing";
+    return (
+      <button
+        type="button"
+        tabIndex={-1}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          props.onSelectionChange?.(createSelectionSnapshot(segment.from, segment.to));
+        }}
+        className={`inline-flex items-center gap-1 mx-0.5 px-1.5 py-0.5 rounded text-xs border-none cursor-pointer ${commentClass} ${
+          isMissing ? "text-danger bg-delete-soft" : "text-secondary bg-surface"
+        } ${selected ? "ring-1 ring-accent/30" : ""} ${focusRingClass}`}
+        title={segment.detail ?? segment.altText ?? "Inline image"}
+      >
+        {renderTwCaret(selection, segment.from)}
+        <span>📷</span>
+        {segment.altText ?? (isMissing ? "Missing image" : "Image")}
+        {renderTwCaret(selection, segment.to)}
+      </button>
+    );
+  }
+
+  // opaque_inline
+  if (segment.kind === "opaque_inline") {
+    if (segment.presentation === "quiet-marker") {
+      return (
+        <span
+          aria-label={segment.label}
+          title={segment.detail}
+          className="inline-block h-0 w-0 overflow-hidden align-baseline"
+          data-inline-presentation="quiet-marker"
+        />
+      );
+    }
+
+    return (
+      <button
+        type="button"
+        tabIndex={-1}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          props.onSelectionChange?.(createSelectionSnapshot(segment.from, segment.to));
+        }}
+        className={`inline-flex items-center gap-1 mx-0.5 px-1.5 py-0.5 rounded text-xs text-comment bg-warning-soft border-none cursor-pointer ${commentClass} ${selected ? "ring-1 ring-accent/30" : ""} ${focusRingClass}`}
+        title={segment.detail}
+      >
+        {renderTwCaret(selection, segment.from)}
+        <span>🔒</span>
+        {segment.label}
+        {renderTwCaret(selection, segment.to)}
+      </button>
+    );
+  }
+
+  return null;
+}

package/src/ui-tailwind/editor-surface/tw-opaque-block.tsx

@@ -0,0 +1,58 @@
+import React from "react";
+
+import type { SelectionSnapshot, SurfaceBlockSnapshot } from "../../api/public-types";
+import { selectionTouchesRange, createSelectionSnapshot } from "../../ui/headless/selection-helpers";
+
+export interface TwOpaqueBlockProps {
+  block: Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>;
+  selection: SelectionSnapshot;
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  workflowTargeted?: boolean;
+}
+
+const focusRingClass =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
+
+export function TwOpaqueBlock(props: TwOpaqueBlockProps) {
+  const { block, selection, workflowTargeted } = props;
+  const selected = selectionTouchesRange(selection, block.from, block.to);
+
+  return (
+    <div className="group relative">
+      <div className="absolute -left-10 top-1 flex flex-col items-end gap-0 select-none w-8 text-right">
+        <div className="flex items-center gap-0.5">
+          <span className="text-[10px] text-tertiary/60 font-medium">Lock</span>
+          <span className="inline-block h-1 w-1 rounded-full" style={{ backgroundColor: "var(--color-comment)" }} />
+        </div>
+      </div>
+      <button
+        type="button"
+        tabIndex={-1}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          props.onSelectionChange?.(createSelectionSnapshot(block.from, block.to));
+        }}
+        className={[
+          "w-full text-left border-l-2 border-dashed border-warning/30 pl-4 py-2 rounded-r bg-warning-soft/20",
+          "cursor-pointer transition-colors",
+          selected ? "ring-1 ring-accent/30 bg-warning-soft/40" : "hover:bg-warning-soft/30",
+          focusRingClass,
+        ].join(" ")}
+      >
+        <div className="flex items-center gap-1.5 text-xs text-tertiary mb-1">
+          <span>🔒</span>
+          <span>{block.label}</span>
+          <span className="inline-flex items-center px-1.5 py-0.5 rounded-full text-[10px] font-semibold text-comment bg-warning-soft">
+            preserve-only
+          </span>
+          {workflowTargeted && (
+            <span className="inline-flex items-center px-1.5 py-0.5 rounded-full text-[10px] font-semibold text-amber-700 bg-amber-100">
+              workflow-targeted
+            </span>
+          )}
+        </div>
+        <p className="text-sm text-secondary">{block.detail}</p>
+      </button>
+    </div>
+  );
+}