@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/ui/runtime-snapshot-selectors.ts

@@ -0,0 +1,197 @@
+import { useRef, useSyncExternalStore } from "react";
+import type {
+  DocumentNavigationSnapshot,
+  RuntimeRenderSnapshot,
+} from "../api/public-types.ts";
+
+export interface RuntimeSnapshotSource {
+  subscribe(listener: () => void): () => void;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+}
+
+export interface RuntimeValueSource<T> {
+  subscribe(listener: () => void): () => void;
+  getValue(): T;
+}
+
+export interface ToolbarSlice {
+  commandState: RuntimeRenderSnapshot["commandState"];
+  isDirty: RuntimeRenderSnapshot["isDirty"];
+  isReady: RuntimeRenderSnapshot["isReady"];
+  readOnly: RuntimeRenderSnapshot["readOnly"];
+  fatalError: RuntimeRenderSnapshot["fatalError"];
+}
+
+export interface SurfaceSlice {
+  revisionToken: RuntimeRenderSnapshot["revisionToken"];
+  selection: RuntimeRenderSnapshot["selection"];
+  activeStory: RuntimeRenderSnapshot["activeStory"];
+  surface: RuntimeRenderSnapshot["surface"];
+}
+
+export interface ReviewSlice {
+  comments: RuntimeRenderSnapshot["comments"];
+  trackedChanges: RuntimeRenderSnapshot["trackedChanges"];
+  compatibility: RuntimeRenderSnapshot["compatibility"];
+}
+
+export interface ViewSlice {
+  documentMode: RuntimeRenderSnapshot["documentMode"];
+  activeStory: RuntimeRenderSnapshot["activeStory"];
+  pageLayout: RuntimeRenderSnapshot["pageLayout"];
+}
+
+export interface StatusSlice {
+  warnings: RuntimeRenderSnapshot["warnings"];
+  fatalError: RuntimeRenderSnapshot["fatalError"];
+  isDirty: RuntimeRenderSnapshot["isDirty"];
+  documentStats: RuntimeRenderSnapshot["documentStats"];
+  protectionSnapshot: RuntimeRenderSnapshot["protectionSnapshot"];
+}
+
+export interface NavigationSlice {
+  documentNavigation: DocumentNavigationSnapshot | undefined;
+}
+
+export interface MetaSlice {
+  documentId: RuntimeRenderSnapshot["documentId"];
+  sessionId: RuntimeRenderSnapshot["sessionId"];
+  sourceLabel: RuntimeRenderSnapshot["sourceLabel"];
+}
+
+export function selectToolbarSlice(snapshot: RuntimeRenderSnapshot): ToolbarSlice {
+  return {
+    commandState: snapshot.commandState,
+    isDirty: snapshot.isDirty,
+    isReady: snapshot.isReady,
+    readOnly: snapshot.readOnly,
+    fatalError: snapshot.fatalError,
+  };
+}
+
+export function selectSurfaceSlice(snapshot: RuntimeRenderSnapshot): SurfaceSlice {
+  return {
+    revisionToken: snapshot.revisionToken,
+    selection: snapshot.selection,
+    activeStory: snapshot.activeStory,
+    surface: snapshot.surface,
+  };
+}
+
+export function selectReviewSlice(snapshot: RuntimeRenderSnapshot): ReviewSlice {
+  return {
+    comments: snapshot.comments,
+    trackedChanges: snapshot.trackedChanges,
+    compatibility: snapshot.compatibility,
+  };
+}
+
+export function selectViewSlice(snapshot: RuntimeRenderSnapshot): ViewSlice {
+  return {
+    documentMode: snapshot.documentMode,
+    activeStory: snapshot.activeStory,
+    pageLayout: snapshot.pageLayout,
+  };
+}
+
+export function selectStatusSlice(snapshot: RuntimeRenderSnapshot): StatusSlice {
+  return {
+    warnings: snapshot.warnings,
+    fatalError: snapshot.fatalError,
+    isDirty: snapshot.isDirty,
+    documentStats: snapshot.documentStats,
+    protectionSnapshot: snapshot.protectionSnapshot,
+  };
+}
+
+export function selectNavigationSlice(
+  documentNavigation?: DocumentNavigationSnapshot,
+): NavigationSlice {
+  return {
+    documentNavigation,
+  };
+}
+
+export function selectMetaSlice(snapshot: RuntimeRenderSnapshot): MetaSlice {
+  return {
+    documentId: snapshot.documentId,
+    sessionId: snapshot.sessionId,
+    sourceLabel: snapshot.sourceLabel,
+  };
+}
+
+export function shallowEqualRecord<T extends object>(
+  left: T,
+  right: T,
+): boolean {
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) {
+    return false;
+  }
+
+  for (const key of leftKeys) {
+    if (leftRecord[key] !== rightRecord[key]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function useRuntimeSnapshotSlice<T>(
+  runtime: RuntimeSnapshotSource | null,
+  fallbackSnapshot: RuntimeRenderSnapshot,
+  selector: (snapshot: RuntimeRenderSnapshot) => T,
+  isEqual: (left: T, right: T) => boolean = Object.is,
+): T {
+  const cachedSelectionRef = useRef<T>(selector(fallbackSnapshot));
+  return useSyncExternalStore(
+    (listener) => runtime?.subscribe(listener) ?? (() => undefined),
+    () => {
+      const next = selector(runtime?.getRenderSnapshot() ?? fallbackSnapshot);
+      if (isEqual(cachedSelectionRef.current, next)) {
+        return cachedSelectionRef.current;
+      }
+      cachedSelectionRef.current = next;
+      return next;
+    },
+    () => {
+      const next = selector(runtime?.getRenderSnapshot() ?? fallbackSnapshot);
+      if (isEqual(cachedSelectionRef.current, next)) {
+        return cachedSelectionRef.current;
+      }
+      cachedSelectionRef.current = next;
+      return next;
+    },
+  );
+}
+
+export function useRuntimeValue<T>(
+  source: RuntimeValueSource<T> | null,
+  fallbackValue: T,
+  isEqual: (left: T, right: T) => boolean = Object.is,
+): T {
+  const cachedValueRef = useRef<T>(fallbackValue);
+  return useSyncExternalStore(
+    (listener) => source?.subscribe(listener) ?? (() => undefined),
+    () => {
+      const next = source?.getValue() ?? fallbackValue;
+      if (isEqual(cachedValueRef.current, next)) {
+        return cachedValueRef.current;
+      }
+      cachedValueRef.current = next;
+      return next;
+    },
+    () => {
+      const next = source?.getValue() ?? fallbackValue;
+      if (isEqual(cachedValueRef.current, next)) {
+        return cachedValueRef.current;
+      }
+      cachedValueRef.current = next;
+      return next;
+    },
+  );
+}

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/workflow-surface-blocked-rails.ts

@@ -0,0 +1,94 @@
+import type {
+  EditorStoryTarget,
+  RuntimeRenderSnapshot,
+  SurfaceBlockSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowMarkupSnapshot,
+} from "../api/public-types";
+
+export function deriveVisibleWorkflowBlockedRails(
+  surface: RuntimeRenderSnapshot["surface"] | undefined,
+  markupSnapshot: WorkflowMarkupSnapshot | null,
+): WorkflowBlockedCommandReason[] {
+  if (!surface || !markupSnapshot) {
+    return [];
+  }
+
+  const visibleFragments = collectVisibleOpaqueFragmentStoryKeys(surface);
+  return markupSnapshot.opaqueFragments
+    .filter((fragment) =>
+      visibleFragments.has(
+        createOpaqueFragmentStoryKey(fragment.fragmentId, fragment.storyTarget ?? { kind: "main" }),
+      ),
+    )
+    .map((fragment) => ({
+      code: fragment.blockedReasonCode,
+      message: fragment.detail,
+      anchor: fragment.anchor,
+      storyTarget: fragment.storyTarget,
+    }));
+}
+
+function collectVisibleOpaqueFragmentStoryKeys(
+  surface: NonNullable<RuntimeRenderSnapshot["surface"]>,
+): Set<string> {
+  const keys = new Set<string>();
+  collectVisibleOpaqueFragmentStoryKeysInBlocks(surface.blocks, { kind: "main" }, keys);
+  for (const story of surface.secondaryStories) {
+    collectVisibleOpaqueFragmentStoryKeysInBlocks(story.blocks, story.target, keys);
+  }
+  return keys;
+}
+
+function collectVisibleOpaqueFragmentStoryKeysInBlocks(
+  blocks: readonly SurfaceBlockSnapshot[],
+  storyTarget: EditorStoryTarget,
+  keys: Set<string>,
+): void {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        if (segment.kind === "opaque_inline") {
+          keys.add(createOpaqueFragmentStoryKey(segment.fragmentId, storyTarget));
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectVisibleOpaqueFragmentStoryKeysInBlocks(cell.content, storyTarget, keys);
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      collectVisibleOpaqueFragmentStoryKeysInBlocks(block.children, storyTarget, keys);
+      continue;
+    }
+
+    keys.add(createOpaqueFragmentStoryKey(block.fragmentId, storyTarget));
+  }
+}
+
+function createOpaqueFragmentStoryKey(
+  fragmentId: string,
+  storyTarget: EditorStoryTarget,
+): string {
+  return `${fragmentId}:${serializeStoryTargetKey(storyTarget)}`;
+}
+
+function serializeStoryTargetKey(storyTarget: EditorStoryTarget): string {
+  switch (storyTarget.kind) {
+    case "main":
+      return "main";
+    case "header":
+    case "footer":
+      return `${storyTarget.kind}:${storyTarget.relationshipId}:${storyTarget.variant}:${storyTarget.sectionIndex ?? "none"}`;
+    case "footnote":
+    case "endnote":
+      return `${storyTarget.kind}:${storyTarget.noteId}`;
+  }
+}

package/src/ui-tailwind/chrome/chrome-preset-model.ts

@@ -0,0 +1,107 @@
+import type {
+  WordReviewEditorChromeOptions,
+  WordReviewEditorChromePreset,
+  WordReviewEditorChromeVisibility,
+  WordReviewEditorProps,
+} from "../../api/public-types";
+
+export function resolveChromePreset(
+  chromePreset: WordReviewEditorProps["chromePreset"],
+  _reviewMode: WordReviewEditorProps["reviewMode"] = "review",
+): WordReviewEditorChromePreset {
+  if (chromePreset) {
+    return chromePreset;
+  }
+  return "advanced";
+}
+
+export function resolveChromePresetOptions(
+  chromePreset: WordReviewEditorChromePreset,
+  overrides?: Partial<WordReviewEditorChromeOptions>,
+): WordReviewEditorChromeOptions {
+  const defaults: Record<WordReviewEditorChromePreset, WordReviewEditorChromeOptions> = {
+    selection: {
+      showReviewQueueBar: false,
+      showSectionTagAction: false,
+      showReviewRail: false,
+    },
+    simple: {
+      showReviewQueueBar: false,
+      showSectionTagAction: false,
+      showReviewRail: false,
+    },
+    advanced: {
+      showReviewQueueBar: false,
+      showSectionTagAction: false,
+      showReviewRail: true,
+    },
+    review: {
+      showReviewQueueBar: true,
+      showSectionTagAction: true,
+      showReviewRail: true,
+    },
+  };
+
+  return {
+    ...defaults[chromePreset],
+    ...overrides,
+  };
+}
+
+export function resolveChromeVisibilityForPreset(input: {
+  chromePreset: WordReviewEditorChromePreset;
+  chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
+}): WordReviewEditorChromeVisibility {
+  const options = resolveChromePresetOptions(input.chromePreset, input.chromeOptions);
+  const defaults: Record<WordReviewEditorChromePreset, WordReviewEditorChromeVisibility> = {
+    selection: {
+      toolbar: false,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: false,
+    },
+    simple: {
+      toolbar: true,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: false,
+    },
+    advanced: {
+      toolbar: true,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: true,
+    },
+    review: {
+      toolbar: true,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: options.showReviewRail,
+    },
+  };
+
+  return {
+    ...defaults[input.chromePreset],
+    ...(input.chromeOptions?.showReviewRail === undefined
+      ? {}
+      : { reviewRail: input.chromeOptions.showReviewRail }),
+    ...input.chromeVisibility,
+  };
+}

package/src/ui-tailwind/chrome/chrome-preset-toolbar.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+
+import type { WordReviewEditorChromePreset } from "../../api/public-types";
+import {
+  TwToolbar,
+  type TwToolbarProps,
+} from "../toolbar/tw-toolbar";
+
+export interface ChromePresetToolbarProps extends TwToolbarProps {
+  chromePreset: WordReviewEditorChromePreset;
+}
+
+export function ChromePresetToolbar(props: ChromePresetToolbarProps) {
+  return <TwToolbar {...props} preset={props.chromePreset} />;
+}

package/src/ui-tailwind/chrome/responsive-chrome.ts

@@ -0,0 +1,46 @@
+export const NARROW_CHROME_MAX_WIDTH = 1023;
+
+export interface ResponsiveChromeStateInput {
+  viewportWidth?: number;
+  reviewRailAvailable: boolean;
+  reviewRailOpen: boolean;
+}
+
+export interface ResponsiveChromeState {
+  isNarrow: boolean;
+  showSidebarToggle: boolean;
+  showDockedReviewRail: boolean;
+  showDrawerReviewRail: boolean;
+}
+
+export function isNarrowChromeViewport(viewportWidth?: number): boolean {
+  return typeof viewportWidth === "number" && viewportWidth <= NARROW_CHROME_MAX_WIDTH;
+}
+
+export function getInitialReviewRailOpen(input: {
+  viewportWidth?: number;
+  reviewRailAvailable: boolean;
+}): boolean {
+  return input.reviewRailAvailable && !isNarrowChromeViewport(input.viewportWidth);
+}
+
+export function resolveResponsiveChromeState(
+  input: ResponsiveChromeStateInput,
+): ResponsiveChromeState {
+  const isNarrow = isNarrowChromeViewport(input.viewportWidth);
+  if (!input.reviewRailAvailable) {
+    return {
+      isNarrow,
+      showSidebarToggle: false,
+      showDockedReviewRail: false,
+      showDrawerReviewRail: false,
+    };
+  }
+
+  return {
+    isNarrow,
+    showSidebarToggle: true,
+    showDockedReviewRail: !isNarrow && input.reviewRailOpen,
+    showDrawerReviewRail: isNarrow && input.reviewRailOpen,
+  };
+}

package/src/ui-tailwind/chrome/review-queue-bar.tsx

@@ -0,0 +1,97 @@
+import React from "react";
+
+import { BookmarkPlus, ChevronLeft, ChevronRight, MessageSquareText, Rows3 } from "lucide-react";
+
+import type { ReviewQueueSnapshot } from "../../api/public-types";
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
+
+export interface TwReviewQueueBarProps {
+  queue: ReviewQueueSnapshot;
+  onPrevious?: () => void;
+  onNext?: () => void;
+  onMarkSection?: () => void;
+}
+
+const buttonClass =
+  "inline-flex h-8 items-center gap-1 rounded-lg border border-border/80 bg-canvas px-2.5 text-xs font-medium text-secondary transition-colors hover:bg-surface-raised focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas disabled:cursor-not-allowed disabled:opacity-40";
+
+export function TwReviewQueueBar(props: TwReviewQueueBarProps) {
+  const activeItem = props.queue.items[props.queue.activeIndex] ?? null;
+  const activeLabel =
+    activeItem?.label ??
+    (props.queue.totalCount > 0 ? "Review queue" : "No review items");
+  const activeKindLabel = activeItem ? formatReviewQueueItemKind(activeItem.kind) : null;
+
+  return (
+    <div className="border-b border-border/80 bg-surface/80 px-3 py-2.5 backdrop-blur-sm">
+      <div className="flex flex-wrap items-center gap-2">
+        <button
+          type="button"
+          aria-label="Previous review item"
+          className={buttonClass}
+          disabled={props.queue.totalCount === 0}
+          onMouseDown={preserveEditorSelectionMouseDown}
+          onClick={props.onPrevious}
+        >
+          <ChevronLeft className="h-3.5 w-3.5" />
+          Prev
+        </button>
+        <button
+          type="button"
+          aria-label="Next review item"
+          className={buttonClass}
+          disabled={props.queue.totalCount === 0}
+          onMouseDown={preserveEditorSelectionMouseDown}
+          onClick={props.onNext}
+        >
+          Next
+          <ChevronRight className="h-3.5 w-3.5" />
+        </button>
+        {props.onMarkSection ? (
+          <button
+            type="button"
+            aria-label="Mark section for review"
+            className={buttonClass}
+            onMouseDown={preserveEditorSelectionMouseDown}
+            onClick={props.onMarkSection}
+          >
+            <BookmarkPlus className="h-3.5 w-3.5" />
+            Mark section
+          </button>
+        ) : null}
+        <div className="ml-auto flex flex-wrap items-center gap-2 text-xs text-secondary">
+          <span className="inline-flex items-center gap-1 rounded-full bg-canvas px-2.5 py-1 font-medium text-primary">
+            <MessageSquareText className="h-3.5 w-3.5 text-comment" />
+            {props.queue.openCount} open
+          </span>
+          <span className="inline-flex items-center gap-1 rounded-full bg-canvas px-2.5 py-1 font-medium text-primary">
+            <Rows3 className="h-3.5 w-3.5 text-accent" />
+            {props.queue.totalCount} total
+          </span>
+        </div>
+      </div>
+      <div className="mt-2 flex items-center gap-2 min-w-0">
+        {activeKindLabel ? (
+          <span
+            className="inline-flex shrink-0 rounded-full bg-canvas px-2 py-0.5 text-[11px] font-medium text-secondary"
+            data-testid="review-queue-item-kind"
+          >
+            {activeKindLabel}
+          </span>
+        ) : null}
+        <div className="min-w-0 truncate text-sm font-medium text-primary">{activeLabel}</div>
+      </div>
+    </div>
+  );
+}
+
+function formatReviewQueueItemKind(kind: ReviewQueueSnapshot["items"][number]["kind"]): string {
+  switch (kind) {
+    case "comment":
+      return "Comment";
+    case "change":
+      return "Redline";
+    case "section_mark":
+      return "Tag";
+  }
+}

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

@@ -0,0 +1,64 @@
+import React from "react";
+import { AlertTriangle, XCircle } from "lucide-react";
+
+import type { RuntimeRenderSnapshot, WorkflowBlockedCommandReason } from "../../api/public-types";
+
+export interface TwAlertBannerProps {
+  snapshot: RuntimeRenderSnapshot;
+  preserveOnlyCount: number;
+  workflowBlockedReasons?: WorkflowBlockedCommandReason[];
+}
+
+export function TwAlertBanner(props: TwAlertBannerProps) {
+  const { snapshot, preserveOnlyCount, workflowBlockedReasons = [] } = 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>
+    );
+  }
+
+  if (workflowBlockedReasons.length > 0) {
+    const firstReason = workflowBlockedReasons[0];
+    return (
+      <div className="flex items-center gap-2 px-3 py-1.5 bg-amber-50 text-amber-700 text-xs">
+        <AlertTriangle className="h-3.5 w-3.5 shrink-0" />
+        <span>
+          {firstReason.message}
+          {workflowBlockedReasons.length > 1
+            ? ` (+${workflowBlockedReasons.length - 1} more)`
+            : ""}
+        </span>
+      </div>
+    );
+  }
+
+  return null;
+}