@beyondwork/docx-react-component 1.0.0

package/src/ui/comments/README.md

@@ -0,0 +1,3 @@
+# Comments UI
+
+Comment markers, thread navigation, and sidebar thread views belong here.

package/src/ui/compatibility/README.md

@@ -0,0 +1,3 @@
+# Compatibility UI
+
+Compatibility reports, preserve-only warnings, and unsupported-content summaries belong here.

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/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/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/40 decoration-1 underline-offset-2${activeRing}`;
+      }
+      if (state.hasDeletions) {
+        return `text-secondary line-through decoration-1${activeRing}`;
+      }
+      return activeRing;
+    case "all":
+      if (state.hasInsertions) {
+        return `text-insert bg-insert-soft${activeRing}`;
+      }
+      if (state.hasDeletions) {
+        return `text-danger line-through decoration-1 bg-delete-soft${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,34 @@
+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 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/use-editor-keyboard.ts

@@ -0,0 +1,98 @@
+import type { KeyboardEvent } from "react";
+
+import type { SelectionSnapshot } from "../../api/public-types";
+import { createSelectionSnapshot } from "./selection-helpers";
+
+export interface EditorKeyboardCallbacks {
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  onInsertText?: (text: string) => void;
+  onDeleteBackward?: () => void;
+  onDeleteForward?: () => void;
+  onInsertTab?: () => void;
+  onInsertHardBreak?: () => void;
+  onSplitParagraph?: () => void;
+}
+
+export interface EditorKeyboardContext {
+  selection: SelectionSnapshot;
+  storySize: number;
+  canEdit: boolean;
+}
+
+export function createEditorKeyboardHandler(
+  context: EditorKeyboardContext,
+  callbacks: EditorKeyboardCallbacks,
+): (event: KeyboardEvent<HTMLDivElement>) => void {
+  return function handleKeyDown(event: KeyboardEvent<HTMLDivElement>): void {
+    const { selection, storySize, canEdit } = context;
+
+    if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      moveSelection(selection.anchor, selection.head - 1, event.shiftKey, storySize, callbacks);
+      return;
+    }
+
+    if (event.key === "ArrowRight") {
+      event.preventDefault();
+      moveSelection(selection.anchor, selection.head + 1, event.shiftKey, storySize, callbacks);
+      return;
+    }
+
+    if (event.key === "Home") {
+      event.preventDefault();
+      moveSelection(selection.anchor, 0, event.shiftKey, storySize, callbacks);
+      return;
+    }
+
+    if (event.key === "End") {
+      event.preventDefault();
+      moveSelection(selection.anchor, storySize, event.shiftKey, storySize, callbacks);
+      return;
+    }
+
+    if (!canEdit || event.metaKey || event.ctrlKey || event.altKey) {
+      return;
+    }
+
+    switch (event.key) {
+      case "Backspace":
+        event.preventDefault();
+        callbacks.onDeleteBackward?.();
+        return;
+      case "Delete":
+        event.preventDefault();
+        callbacks.onDeleteForward?.();
+        return;
+      case "Tab":
+        event.preventDefault();
+        callbacks.onInsertTab?.();
+        return;
+      case "Enter":
+        event.preventDefault();
+        if (event.shiftKey) {
+          callbacks.onInsertHardBreak?.();
+        } else {
+          callbacks.onSplitParagraph?.();
+        }
+        return;
+      default:
+        if (event.key.length === 1) {
+          event.preventDefault();
+          callbacks.onInsertText?.(event.key);
+        }
+    }
+  };
+}
+
+function moveSelection(
+  anchor: number,
+  nextHead: number,
+  extend: boolean,
+  storySize: number,
+  callbacks: EditorKeyboardCallbacks,
+): void {
+  const clampedHead = Math.max(0, Math.min(storySize, nextHead));
+  callbacks.onSelectionChange?.(
+    createSelectionSnapshot(extend ? anchor : clampedHead, clampedHead),
+  );
+}

package/src/ui/review/README.md

@@ -0,0 +1,3 @@
+# Review UI
+
+Tracked-change display modes, review navigation, and accept/reject surfaces belong here.

package/src/ui/shared/revision-filters.ts

@@ -0,0 +1,31 @@
+import type { RuntimeRenderSnapshot } from "../../api/public-types";
+
+type Revision = RuntimeRenderSnapshot["trackedChanges"]["revisions"][number];
+type MarkupDisplay = "clean" | "simple" | "all";
+
+export function selectVisibleRevisions(
+  revisions: readonly Revision[],
+  markupDisplay: MarkupDisplay,
+): Revision[] {
+  switch (markupDisplay) {
+    case "clean":
+    case "simple":
+      return revisions.filter(
+        (revision) =>
+          revision.status === "active" && revision.actionability === "actionable",
+      );
+    case "all":
+      return [...revisions];
+  }
+}
+
+export function describeEmptyRevisionState(
+  markupDisplay: MarkupDisplay,
+  totalCount: number,
+): string {
+  if ((markupDisplay === "clean" || markupDisplay === "simple") && totalCount > 0) {
+    return "Simple markup keeps the rail focused on actionable live changes. Switch to All to inspect preserve-only or historical revision records.";
+  }
+
+  return "Runtime-backed change cards will appear here when tracked changes are present.";
+}

package/src/ui/status/README.md

@@ -0,0 +1,3 @@
+# Status UI
+
+Dirty state, autosave state, import/export progress, and validation status surfaces belong here.

package/src/ui/theme/README.md

@@ -0,0 +1,3 @@
+# Theme
+
+Design tokens, CSS variable mapping, and host-theme integration belong here.

package/src/ui/toolbar/README.md

@@ -0,0 +1,3 @@
+# Toolbar
+
+The compact command toolbar and contextual editor controls belong here.

package/src/ui-tailwind/chrome/tw-alert-banner.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { AlertTriangle, XCircle } from "lucide-react";
+
+import type { RuntimeRenderSnapshot } from "../../api/public-types";
+
+export interface TwAlertBannerProps {
+  snapshot: RuntimeRenderSnapshot;
+  preserveOnlyCount: number;
+}
+
+export function TwAlertBanner(props: TwAlertBannerProps) {
+  const { snapshot, preserveOnlyCount } = props;
+
+  if (snapshot.fatalError) {
+    return (
+      <div className="flex items-center gap-2 px-3 py-1.5 bg-danger-soft text-danger text-xs">
+        <XCircle className="h-3.5 w-3.5 shrink-0" />
+        <span>{snapshot.fatalError.message}</span>
+      </div>
+    );
+  }
+
+  if (snapshot.compatibility.blockExport) {
+    return (
+      <div className="flex items-center gap-2 px-3 py-1.5 bg-danger-soft text-danger text-xs">
+        <XCircle className="h-3.5 w-3.5 shrink-0" />
+        <span>
+          Export blocked &mdash;{" "}
+          {snapshot.compatibility.blockExportReasons[0] ?? "unsupported content"}
+        </span>
+      </div>
+    );
+  }
+
+  if (preserveOnlyCount > 0) {
+    return (
+      <div className="flex items-center gap-2 px-3 py-1.5 bg-warning-soft text-comment text-xs">
+        <AlertTriangle className="h-3.5 w-3.5 shrink-0" />
+        <span>
+          {preserveOnlyCount} preserve-only feature
+          {preserveOnlyCount !== 1 ? "s" : ""} detected
+        </span>
+      </div>
+    );
+  }
+
+  return null;
+}

package/src/ui-tailwind/chrome/tw-selection-toolbar.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+import * as Tooltip from "@radix-ui/react-tooltip";
+import { MessageSquare } from "lucide-react";
+
+export interface TwSelectionToolbarProps {
+  selectionPreview: string;
+  readOnly: boolean;
+  onAddComment?: () => 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 TwSelectionToolbar(props: TwSelectionToolbarProps) {
+  return (
+    <div className="mb-6 inline-flex items-center gap-1 rounded-lg bg-canvas shadow-lg ring-1 ring-border p-1">
+      <Tooltip.Root>
+        <Tooltip.Trigger asChild>
+          <button
+            type="button"
+            aria-label="Comment"
+            disabled={props.readOnly}
+            onClick={props.onAddComment}
+            className={`inline-flex h-7 w-7 items-center justify-center rounded-md transition-colors text-accent hover:bg-accent-soft disabled:opacity-30 disabled:cursor-not-allowed ${focusRingClass}`}
+          >
+            <MessageSquare className="h-3.5 w-3.5" />
+          </button>
+        </Tooltip.Trigger>
+        <Tooltip.Portal>
+          <Tooltip.Content
+            className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
+            sideOffset={6}
+          >
+            Add comment
+          </Tooltip.Content>
+        </Tooltip.Portal>
+      </Tooltip.Root>
+      <div className="h-4 w-px bg-border mx-0.5" />
+      <span className="text-xs text-tertiary px-2 max-w-[200px] truncate">
+        {props.selectionPreview}
+      </span>
+    </div>
+  );
+}

package/src/ui-tailwind/chrome/tw-unsaved-modal.tsx

@@ -0,0 +1,58 @@
+import React from "react";
+import { AlertTriangle } from "lucide-react";
+
+export interface TwUnsavedModalProps {
+  open: boolean;
+  message?: string;
+  onDiscard: () => void;
+  onCancel: () => void;
+}
+
+export function TwUnsavedModal(props: TwUnsavedModalProps) {
+  if (!props.open) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0 bg-black/30 backdrop-blur-sm"
+        onClick={props.onCancel}
+      />
+
+      {/* Modal */}
+      <div className="relative mx-4 w-full max-w-md rounded-xl bg-canvas p-6 shadow-lg ring-1 ring-border">
+        <div className="flex items-start gap-3">
+          <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-warning-soft">
+            <AlertTriangle className="h-5 w-5 text-warning" />
+          </div>
+          <div className="flex-1">
+            <h3 className="text-base font-semibold text-primary">
+              Unsaved changes
+            </h3>
+            <p className="mt-1.5 text-sm text-secondary leading-relaxed">
+              {props.message ??
+                "You have unsaved changes that will be lost. Your work is being autosaved, but the latest edits may not be saved yet."}
+            </p>
+          </div>
+        </div>
+
+        <div className="mt-5 flex justify-end gap-2">
+          <button
+            type="button"
+            onClick={props.onCancel}
+            className="rounded-lg px-4 py-2 text-sm font-medium text-secondary hover:bg-surface transition-colors"
+          >
+            Keep editing
+          </button>
+          <button
+            type="button"
+            onClick={props.onDiscard}
+            className="rounded-lg bg-danger px-4 py-2 text-sm font-medium text-white hover:bg-danger/90 transition-colors"
+          >
+            Discard changes
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/ui-tailwind/chrome/use-before-unload.ts

@@ -0,0 +1,20 @@
+import { useEffect } from "react";
+
+/**
+ * Prompts the browser's native "unsaved changes" dialog when the user
+ * tries to close the tab or navigate away while `shouldWarn` is true.
+ */
+export function useBeforeUnload(shouldWarn: boolean): void {
+  useEffect(() => {
+    if (!shouldWarn) return;
+
+    function handleBeforeUnload(event: BeforeUnloadEvent) {
+      event.preventDefault();
+      // Modern browsers ignore custom messages and show their own.
+      event.returnValue = "";
+    }
+
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => window.removeEventListener("beforeunload", handleBeforeUnload);
+  }, [shouldWarn]);
+}