@beyondwork/docx-react-component 1.0.1 → 1.0.2

package/src/api/public-types.ts

@@ -0,0 +1,525 @@
+import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
+
+export type ExternalDocumentSource =
+  | {
+      kind: "docx";
+      bytes: Uint8Array | ArrayBuffer;
+      sourceLabel?: string;
+    }
+  | {
+      kind: "snapshot";
+      snapshot: PersistedEditorSnapshot;
+      sourceLabel?: string;
+    };
+
+export interface EditorUser {
+  userId: string;
+  displayName: string;
+  email?: string;
+  avatarUrl?: string;
+}
+
+export type EditorAnchorProjection =
+  | {
+      kind: "range";
+      from: number;
+      to: number;
+      assoc: {
+        start: -1 | 1;
+        end: -1 | 1;
+      };
+    }
+  | {
+      kind: "node";
+      at: number;
+      assoc: -1 | 1;
+    }
+  | {
+      kind: "detached";
+      lastKnownRange: {
+        from: number;
+        to: number;
+      };
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+    };
+
+export interface SelectionSnapshot {
+  anchor: number;
+  head: number;
+  isCollapsed: boolean;
+  activeRange: EditorAnchorProjection;
+}
+
+export interface DocumentStats {
+  storyLength: number;
+  commentCount: number;
+  revisionCount: number;
+  opaqueFragmentCount: number;
+}
+
+export interface CommentSidebarSnapshot {
+  activeCommentId?: string;
+  openCommentIds: string[];
+  resolvedCommentIds: string[];
+  detachedCommentIds: string[];
+  totalCount: number;
+  threads: CommentSidebarThreadSnapshot[];
+}
+
+export interface CommentSidebarThreadEntrySnapshot {
+  entryId: string;
+  authorId: string;
+  body: string;
+  createdAt: string;
+}
+
+export interface CommentSidebarThreadSnapshot {
+  commentId: string;
+  status: "open" | "resolved" | "detached";
+  anchor: EditorAnchorProjection;
+  excerpt: string;
+  entryCount: number;
+  entries: CommentSidebarThreadEntrySnapshot[];
+  createdAt: string;
+  createdBy: string;
+  warningCount: number;
+  anchorLabel: string;
+  isActive: boolean;
+  resolvedAt?: string;
+  resolvedBy?: string;
+}
+
+export interface TrackedChangeEntrySnapshot {
+  revisionId: string;
+  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
+  label: string;
+  status: "active" | "accepted" | "rejected" | "detached";
+  actionability: "actionable" | "preserve-only";
+  importedRevisionForm?:
+    | "run-insertion"
+    | "run-deletion"
+    | "paragraph-insertion"
+    | "paragraph-deletion";
+  anchor: EditorAnchorProjection;
+  anchorLabel: string;
+  createdAt: string;
+  authorId: string;
+  warningCount: number;
+  canAccept: boolean;
+  canReject: boolean;
+  preserveOnlyReason?: string;
+  excerpt?: string;
+  detail?: string;
+}
+
+export interface TrackedChangesSnapshot {
+  pendingChangeIds: string[];
+  acceptedChangeIds: string[];
+  rejectedChangeIds: string[];
+  detachedChangeIds: string[];
+  actionableChangeIds: string[];
+  preserveOnlyChangeIds: string[];
+  totalCount: number;
+  revisions: TrackedChangeEntrySnapshot[];
+}
+
+export type SurfaceTextMark =
+  | "bold"
+  | "italic"
+  | "underline"
+  | "strikethrough";
+
+export type SurfaceInlineSegment =
+  | {
+      segmentId: string;
+      kind: "text";
+      from: number;
+      to: number;
+      text: string;
+      marks?: SurfaceTextMark[];
+      hyperlinkHref?: string;
+    }
+  | {
+      segmentId: string;
+      kind: "tab" | "hard_break";
+      from: number;
+      to: number;
+      hyperlinkHref?: string;
+    }
+  | {
+      segmentId: string;
+      kind: "image";
+      from: number;
+      to: number;
+      mediaId: string;
+      altText?: string;
+      state: "editable" | "missing";
+      display?: "inline" | "floating";
+      detail?: string;
+    }
+  | {
+      segmentId: string;
+      kind: "opaque_inline";
+      from: number;
+      to: number;
+      fragmentId: string;
+      warningId: string;
+      label: string;
+      detail: string;
+      state: "locked-preserve-only";
+    };
+
+export interface SurfaceTableCellSnapshot {
+  gridSpan: number;
+  verticalMerge: "restart" | "continue" | null;
+  colspan: number;
+  rowspan: number;
+  content: SurfaceBlockSnapshot[];
+}
+
+export interface SurfaceTableRowSnapshot {
+  cells: SurfaceTableCellSnapshot[];
+}
+
+export type SurfaceBlockSnapshot =
+  | {
+      blockId: string;
+      kind: "paragraph";
+      from: number;
+      to: number;
+      styleId?: string;
+      numbering?: {
+        numberingInstanceId: string;
+        level: number;
+      };
+      segments: SurfaceInlineSegment[];
+    }
+  | {
+      blockId: string;
+      kind: "table";
+      from: number;
+      to: number;
+      styleId?: string;
+      gridColumns: number[];
+      rows: SurfaceTableRowSnapshot[];
+    }
+  | {
+      blockId: string;
+      kind: "sdt_block";
+      from: number;
+      to: number;
+      sdtType?: string;
+      alias?: string;
+      tag?: string;
+      lock?: string;
+      children: SurfaceBlockSnapshot[];
+    }
+  | {
+      blockId: string;
+      kind: "opaque_block";
+      from: number;
+      to: number;
+      fragmentId: string;
+      warningId: string;
+      label: string;
+      detail: string;
+      state: "locked-preserve-only";
+    };
+
+export interface EditorSurfaceSnapshot {
+  storySize: number;
+  plainText: string;
+  blocks: SurfaceBlockSnapshot[];
+  lockedFragmentIds: string[];
+}
+
+export type EditorWarningCode =
+  | "unsupported_ooxml_preserved"
+  | "unsupported_ooxml_locked"
+  | "import_normalized"
+  | "export_roundtrip_risk"
+  | "comment_anchor_detached"
+  | "revision_anchor_detached"
+  | "large_document_degraded"
+  | "font_substitution"
+  | "image_missing";
+
+export interface EditorWarning {
+  warningId: string;
+  code: EditorWarningCode;
+  severity: "info" | "warning";
+  message: string;
+  source:
+    | "import"
+    | "runtime"
+    | "review"
+    | "preservation"
+    | "validation"
+    | "export";
+  affectedAnchor?: EditorAnchorProjection;
+  featureEntryId?: string;
+  details?: Record<string, unknown>;
+}
+
+export type EditorErrorCode =
+  | "import_failed"
+  | "export_failed"
+  | "package_corrupt"
+  | "validation_failed"
+  | "datastore_failed"
+  | "internal_invariant";
+
+export interface EditorError {
+  errorId: string;
+  code: EditorErrorCode;
+  message: string;
+  isFatal: boolean;
+  source: "import" | "runtime" | "validation" | "datastore" | "export";
+  details?: Record<string, unknown>;
+}
+
+export type CompatibilityFeatureClass =
+  | "supported-roundtrip"
+  | "preserve-only"
+  | "unsupported-fatal";
+
+export interface CompatibilityFeatureEntry {
+  featureEntryId: string;
+  featureKey: string;
+  featureClass: CompatibilityFeatureClass;
+  message: string;
+  affectedAnchor?: EditorAnchorProjection;
+  details?: Record<string, unknown>;
+}
+
+export interface CompatibilityReport {
+  reportVersion: "compatibility-report/1";
+  generatedAt: string;
+  blockExport: boolean;
+  featureEntries: CompatibilityFeatureEntry[];
+  warnings: EditorWarning[];
+  errors: EditorError[];
+}
+
+export interface CompatibilityPanelSnapshot {
+  blockExport: boolean;
+  blockExportReasons: string[];
+  warningCount: number;
+  errorCount: number;
+  featureEntries: CompatibilityFeatureEntry[];
+}
+
+export interface CommandStateSnapshot {
+  canUndo: boolean;
+  canRedo: boolean;
+  readOnly: boolean;
+}
+
+export interface RuntimeRenderSnapshot {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  revisionToken: string;
+  isReady: boolean;
+  isDirty: boolean;
+  readOnly: boolean;
+  selection: SelectionSnapshot;
+  documentStats: DocumentStats;
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+  compatibility: CompatibilityPanelSnapshot;
+  warnings: EditorWarning[];
+  fatalError?: EditorError;
+  commandState: CommandStateSnapshot;
+  surface?: EditorSurfaceSnapshot;
+}
+
+export interface PersistedEditorSnapshot {
+  snapshotVersion: RuntimePersistedEditorSnapshot["snapshotVersion"];
+  schemaVersion: RuntimePersistedEditorSnapshot["schemaVersion"];
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  savedAt: string;
+  editorBuild: string;
+  canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+}
+
+export interface AddCommentParams {
+  anchor?: EditorAnchorProjection;
+  body?: string;
+  authorId?: string;
+}
+
+export interface ExportDocxOptions {
+  fileName?: string;
+  reason?: string;
+}
+
+export interface ExportResult {
+  bytes: Uint8Array;
+  mimeType: string;
+  fileName: string;
+}
+
+export type AutosaveState =
+  | { status: "idle" }
+  | { status: "saving" }
+  | { status: "saved"; savedAt: string }
+  | { status: "error"; error: EditorError };
+
+export interface AutosaveConfig {
+  enabled?: boolean;
+  debounceMs?: number;
+}
+
+export type WordReviewEditorEvent =
+  | {
+      type: "ready";
+      documentId: string;
+      sessionId: string;
+      source: "docx" | "snapshot" | "datastore" | "canonical";
+      stats: DocumentStats;
+      compatibility: CompatibilityReport;
+    }
+  | {
+      type: "dirty_changed";
+      documentId: string;
+      isDirty: boolean;
+    }
+  | {
+      type: "selection_changed";
+      documentId: string;
+      selection: SelectionSnapshot;
+    }
+  | {
+      type: "comment_added";
+      documentId: string;
+      commentId: string;
+      anchor: EditorAnchorProjection;
+    }
+  | {
+      type: "comment_resolved";
+      documentId: string;
+      commentId: string;
+    }
+  | {
+      type: "change_accepted";
+      documentId: string;
+      changeId: string;
+    }
+  | {
+      type: "change_rejected";
+      documentId: string;
+      changeId: string;
+    }
+  | {
+      type: "warning_added";
+      documentId: string;
+      warning: EditorWarning;
+    }
+  | {
+      type: "warning_cleared";
+      documentId: string;
+      warningId: string;
+      code: EditorWarningCode;
+    }
+  | {
+      type: "error";
+      documentId: string;
+      error: EditorError;
+    }
+  | {
+      type: "autosave_state";
+      documentId: string;
+      state: AutosaveState;
+    }
+  | {
+      type: "snapshot_saved";
+      documentId: string;
+      snapshot: PersistedEditorSnapshot;
+      isAutosave: boolean;
+    }
+  | {
+      type: "export_completed";
+      documentId: string;
+      result: ExportResult;
+    };
+
+export interface LoadResult {
+  source?: ExternalDocumentSource;
+}
+
+export interface SaveSnapshotParams {
+  documentId: string;
+  snapshot: PersistedEditorSnapshot;
+  isAutosave: boolean;
+}
+
+export interface SaveSnapshotResult {
+  savedAt: string;
+}
+
+export interface SaveExportParams {
+  documentId: string;
+  result: ExportResult;
+}
+
+export interface SaveExportResult {
+  savedAt: string;
+}
+
+export interface EditorTelemetryEvent {
+  type: string;
+  documentId: string;
+  detail?: Record<string, unknown>;
+}
+
+export interface EditorDatastoreAdapter {
+  load(params: { documentId: string }): Promise<LoadResult>;
+  saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult>;
+  saveExport(params: SaveExportParams): Promise<SaveExportResult>;
+  logEvent?(event: EditorTelemetryEvent): void;
+}
+
+export interface WordReviewEditorRef {
+  focus(): void;
+  blur(): void;
+  undo(): void;
+  redo(): void;
+  addComment(params: AddCommentParams): string;
+  openComment(commentId: string): void;
+  resolveComment(commentId: string): void;
+  reopenComment(commentId: string): void;
+  addCommentReply(commentId: string, body: string): void;
+  editCommentBody(commentId: string, body: string): void;
+  acceptChange(changeId: string): void;
+  rejectChange(changeId: string): void;
+  acceptAllChanges(): void;
+  rejectAllChanges(): void;
+  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  getSnapshot(): PersistedEditorSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+}
+
+export interface WordReviewEditorProps {
+  documentId: string;
+  currentUser: EditorUser;
+  initialDocx?: Uint8Array | ArrayBuffer;
+  initialSnapshot?: PersistedEditorSnapshot;
+  initialSourceLabel?: string;
+  externalDocumentRevision?: string;
+  externalDocSource?: ExternalDocumentSource;
+  readOnly?: boolean;
+  reviewMode?: "editing" | "review";
+  markupDisplay?: "clean" | "simple" | "all";
+  datastore?: EditorDatastoreAdapter;
+  autosave?: AutosaveConfig;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}