@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/.tmp-a4/src/api/public-types.ts

@@ -0,0 +1,318 @@
+export type ExternalDocumentSource =
+  | {
+      kind: "docx";
+      bytes: Uint8Array | ArrayBuffer;
+      sourceLabel?: string;
+    }
+  | {
+      kind: "snapshot";
+      snapshot: PersistedEditorSnapshot;
+      sourceLabel?: string;
+    };
+
+export interface EditorUser {
+  userId: string;
+  displayName: string;
+  initials?: 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 {
+  wordCount: number;
+  paragraphCount: number;
+  commentCount: number;
+  changeCount: number;
+}
+
+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 type CanonicalDocument = Record<string, unknown> & {
+  schemaVersion: "cds/1.0.0";
+  docId: string;
+};
+
+export interface PersistedEditorSnapshot {
+  snapshotVersion: "persisted-editor-snapshot/1";
+  schemaVersion: "cds/1.0.0";
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  savedAt: string;
+  editorBuild: string;
+  canonicalDocument: CanonicalDocument;
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+}
+
+export interface AddCommentParams {
+  anchor: EditorAnchorProjection;
+  body: string;
+}
+
+export interface ExportDocxOptions {
+  includeCompatibilityReport?: boolean;
+}
+
+export interface ExportResult {
+  docx: Uint8Array<ArrayBufferLike>;
+  compatibilityReport: CompatibilityReport;
+  warnings: EditorWarning[];
+}
+
+export interface AutosaveConfig {
+  enabled: boolean;
+  debounceMs: number;
+  maxIntervalMs: number;
+  idleOnly?: boolean;
+}
+
+export type AutosaveState =
+  | "idle"
+  | "scheduled"
+  | "saving"
+  | "saved"
+  | "error";
+
+export interface SaveSnapshotParams {
+  documentId: string;
+  snapshot: PersistedEditorSnapshot;
+  isAutosave: boolean;
+}
+
+export interface SaveSnapshotResult {
+  savedAt: string;
+}
+
+export interface SaveExportParams {
+  documentId: string;
+  docx: Uint8Array<ArrayBufferLike>;
+  compatibilityReport: CompatibilityReport;
+}
+
+export interface SaveExportResult {
+  savedAt: string;
+  artifactId?: string;
+}
+
+export interface LoadResult {
+  source?: ExternalDocumentSource;
+}
+
+export interface EditorTelemetryEvent {
+  type: string;
+  documentId: string;
+  details?: 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 type WordReviewEditorEvent =
+  | {
+      type: "ready";
+      documentId: string;
+      sessionId: string;
+      source: "docx" | "snapshot" | "datastore";
+      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 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;
+}
+
+export interface WordReviewEditorRef {
+  focus(): void;
+  blur(): void;
+  undo(): void;
+  redo(): void;
+  addComment(params: AddCommentParams): string;
+  openComment(commentId: string): void;
+  resolveComment(commentId: 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[];
+}