@beyondwork/docx-react-component 1.0.0

package/src/core/state/editor-state.ts

@@ -0,0 +1,580 @@
+import {
+  DEFAULT_BOUNDARY_ASSOC,
+  createDetachedAnchor,
+  createRangeAnchor,
+  type EditorAnchorProjection,
+} from "../selection/mapping.ts";
+import {
+  assertPersistedEditorSnapshot as assertModelPersistedEditorSnapshot,
+  createPersistedEditorSnapshot as createModelPersistedEditorSnapshot,
+  type PersistedEditorSnapshot as ModelPersistedEditorSnapshot,
+} from "../../model/snapshot.ts";
+import {
+  assertCanonicalDocument,
+  type CanonicalDocument,
+  type CommentEntry as ModelCommentEntry,
+  type CommentResolution as ModelCommentResolution,
+  type CommentThread as ModelCommentThread,
+  type RevisionMetadataRecord as ModelRevisionMetadataRecord,
+  type RevisionRecord as ModelRevisionRecord,
+} from "../../model/canonical-document.ts";
+
+export type RuntimePhase = "loading" | "ready" | "error";
+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 interface EditorError {
+  errorId: string;
+  code:
+    | "import_failed"
+    | "export_failed"
+    | "package_corrupt"
+    | "validation_failed"
+    | "datastore_failed"
+    | "internal_invariant";
+  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 CommentEntryRecord = ModelCommentEntry;
+export type CommentResolutionRecord = ModelCommentResolution;
+export type CommentThreadRecord = ModelCommentThread;
+export type RevisionMetadataRecord = ModelRevisionMetadataRecord;
+export type RevisionRecord = ModelRevisionRecord;
+export type ReviewStore = CanonicalDocument["review"];
+export type CanonicalDocumentEnvelope = CanonicalDocument;
+
+export interface SelectionSnapshot {
+  anchor: number;
+  head: number;
+  isCollapsed: boolean;
+  activeRange: EditorAnchorProjection;
+}
+
+export interface DocumentStats {
+  paragraphCount: number;
+  wordCount: number;
+  characterCount: number;
+  commentCount: number;
+  revisionCount: number;
+}
+
+export interface CommentSidebarSnapshot {
+  activeCommentId?: string;
+  openThreadCount: number;
+  resolvedThreadCount: number;
+  threads: CommentThreadRecord[];
+}
+
+export interface TrackedChangesSnapshot {
+  totalCount: number;
+  pendingCount: number;
+  acceptedCount: number;
+  rejectedCount: number;
+}
+
+export interface CompatibilityPanelSnapshot {
+  report: CompatibilityReport;
+  blockExport: boolean;
+  totalEntries: number;
+}
+
+export interface CommandStateSnapshot {
+  canUndo: boolean;
+  canRedo: boolean;
+  canAddComment: boolean;
+  canAcceptAllChanges: boolean;
+  canRejectAllChanges: 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;
+}
+
+export interface PersistedEditorSnapshot
+  extends Omit<
+    ModelPersistedEditorSnapshot,
+    "canonicalDocument" | "compatibility" | "warningLog"
+  > {
+  canonicalDocument: CanonicalDocumentEnvelope;
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+}
+
+export interface EditorRuntimeState {
+  hasFocus: boolean;
+  activeCommentId?: string;
+}
+
+export interface EditorState {
+  phase: RuntimePhase;
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  revision: number;
+  revisionToken: string;
+  isDirty: boolean;
+  readOnly: boolean;
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  warnings: EditorWarning[];
+  compatibility: CompatibilityReport;
+  fatalError?: EditorError;
+  runtime: EditorRuntimeState;
+}
+
+export interface CreateEditorStateOptions {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  readOnly?: boolean;
+  canonicalDocument?: CanonicalDocumentEnvelope;
+  persistedSnapshot?: PersistedEditorSnapshot;
+  compatibility?: CompatibilityReport;
+  warnings?: EditorWarning[];
+  fatalError?: EditorError;
+}
+
+export function createEmptyReviewStore(): ReviewStore {
+  return {
+    comments: {},
+    revisions: {},
+  };
+}
+
+export function createDefaultCanonicalDocument(
+  documentId: string,
+  timestamp: string,
+): CanonicalDocumentEnvelope {
+  return {
+    schemaVersion: "cds/1.0.0",
+    docId: createCanonicalDocumentId(documentId),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    metadata: {
+      customProperties: {},
+    },
+    styles: {
+      paragraphs: {},
+      characters: {},
+      tables: {},
+    },
+    numbering: {
+      abstractDefinitions: {},
+      instances: {},
+    },
+    media: {
+      items: {},
+    },
+    content: {
+      type: "doc",
+      children: [{ type: "paragraph", children: [] }],
+    },
+    review: createEmptyReviewStore(),
+    preservation: {
+      opaqueFragments: {},
+      packageParts: {},
+    },
+    diagnostics: {
+      warnings: [],
+      errors: [],
+    },
+  };
+}
+
+export function createSelectionSnapshot(anchor = 0, head = anchor): SelectionSnapshot {
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: createRangeAnchor(anchor, head, DEFAULT_BOUNDARY_ASSOC),
+  };
+}
+
+export function createEmptyCompatibilityReport(generatedAt: string): CompatibilityReport {
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt,
+    blockExport: false,
+    featureEntries: [],
+    warnings: [],
+    errors: [],
+  };
+}
+
+export function createEditorState(options: CreateEditorStateOptions): EditorState {
+  const timestamp = new Date(0).toISOString();
+  if (options.persistedSnapshot) {
+    assertModelPersistedEditorSnapshot(options.persistedSnapshot as unknown);
+  }
+  if (options.canonicalDocument) {
+    assertCanonicalDocument(options.canonicalDocument as unknown);
+  }
+
+  const normalizedDocument = options.persistedSnapshot
+    ? structuredClone(options.persistedSnapshot.canonicalDocument)
+    : options.canonicalDocument
+      ? structuredClone(options.canonicalDocument)
+      : createDefaultCanonicalDocument(options.documentId, timestamp);
+  const warnings = options.persistedSnapshot?.warningLog ?? options.warnings ?? [];
+  const compatibility =
+    options.persistedSnapshot?.compatibility ??
+    options.compatibility ??
+    createEmptyCompatibilityReport(normalizedDocument.updatedAt);
+
+  return {
+    phase: options.fatalError ? "error" : "ready",
+    documentId: options.documentId,
+    sessionId: options.sessionId,
+    sourceLabel: options.sourceLabel,
+    revision: 0,
+    revisionToken: `${options.sessionId}:0`,
+    isDirty: false,
+    readOnly: options.readOnly ?? false,
+    document: normalizedDocument,
+    selection: createSelectionSnapshot(),
+    warnings,
+    compatibility,
+    fatalError: options.fatalError,
+    runtime: {
+      hasFocus: false,
+    },
+  };
+}
+
+export function deriveDocumentStats(state: Pick<EditorState, "document">): DocumentStats {
+  const serializedContent = extractText(state.document.content);
+
+  return {
+    paragraphCount: estimateParagraphCount(state.document.content),
+    wordCount: serializedContent.trim().length === 0 ? 0 : serializedContent.trim().split(/\s+/u).length,
+    characterCount: Array.from(serializedContent).length,
+    commentCount: Object.keys(state.document.review.comments).length,
+    revisionCount: Object.keys(state.document.review.revisions).length,
+  };
+}
+
+export function deriveRenderSnapshot(
+  state: EditorState,
+  history: { canUndo: boolean; canRedo: boolean },
+): RuntimeRenderSnapshot {
+  const comments = Object.values(state.document.review.comments).sort((left, right) =>
+    left.createdAt.localeCompare(right.createdAt),
+  );
+  const revisions = Object.values(state.document.review.revisions);
+
+  return {
+    documentId: state.documentId,
+    sessionId: state.sessionId,
+    sourceLabel: state.sourceLabel,
+    revisionToken: state.revisionToken,
+    isReady: state.phase === "ready",
+    isDirty: state.isDirty,
+    readOnly: state.readOnly,
+    selection: state.selection,
+    documentStats: deriveDocumentStats(state),
+    comments: {
+      activeCommentId: state.runtime.activeCommentId,
+      openThreadCount: comments.filter((comment) => comment.status === "open").length,
+      resolvedThreadCount: comments.filter((comment) => comment.status === "resolved").length,
+      threads: comments,
+    },
+    trackedChanges: {
+      totalCount: revisions.length,
+      pendingCount: revisions.filter((revision) => revision.status === "open").length,
+      acceptedCount: revisions.filter((revision) => revision.status === "accepted").length,
+      rejectedCount: revisions.filter((revision) => revision.status === "rejected").length,
+    },
+    compatibility: {
+      report: state.compatibility,
+      blockExport: state.compatibility.blockExport,
+      totalEntries: state.compatibility.featureEntries.length,
+    },
+    warnings: state.warnings,
+    fatalError: state.fatalError,
+    commandState: {
+      canUndo: history.canUndo,
+      canRedo: history.canRedo,
+      canAddComment: !state.readOnly,
+      canAcceptAllChanges: revisions.some((revision) => revision.status === "open"),
+      canRejectAllChanges: revisions.some((revision) => revision.status === "open"),
+    },
+  };
+}
+
+export function createPersistedEditorSnapshot(
+  state: EditorState,
+  options: {
+    editorBuild: string;
+    savedAt: string;
+    compatibility?: CompatibilityReport;
+  },
+): PersistedEditorSnapshot {
+  const snapshot = createModelPersistedEditorSnapshot({
+    documentId: state.documentId,
+    savedAt: options.savedAt,
+    editorBuild: options.editorBuild,
+    canonicalDocument: state.document,
+    compatibility: (options.compatibility ?? state.compatibility) as never,
+    warningLog: state.warnings,
+  });
+  return snapshot as PersistedEditorSnapshot;
+}
+
+function estimateParagraphCount(content: unknown): number {
+  if (Array.isArray(content)) {
+    return content.length;
+  }
+
+  if (content && typeof content === "object" && Array.isArray((content as { blocks?: unknown[] }).blocks)) {
+    return ((content as { blocks: unknown[] }).blocks).length;
+  }
+
+  return extractText(content).length > 0 ? 1 : 0;
+}
+
+function extractText(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => extractText(item)).join(" ");
+  }
+
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+
+  return Object.values(value as Record<string, unknown>)
+    .map((item) => extractText(item))
+    .filter(Boolean)
+    .join(" ");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function createCanonicalDocumentId(documentId: string): string {
+  const hashWord = (seed: string): string => {
+    let hash = 0x811c9dc5;
+    for (const char of seed) {
+      hash ^= char.charCodeAt(0);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+  };
+
+  const raw =
+    hashWord(`${documentId}:0`) +
+    hashWord(`${documentId}:1`) +
+    hashWord(`${documentId}:2`) +
+    hashWord(`${documentId}:3`);
+
+  return [
+    raw.slice(0, 8),
+    raw.slice(8, 12),
+    `4${raw.slice(13, 16)}`,
+    `8${raw.slice(17, 20)}`,
+    raw.slice(20, 32),
+  ].join("-");
+}
+
+export function normalizeCommentThreadRecord(value: unknown): CommentThreadRecord {
+  const record = isRecord(value) ? value : {};
+  const authorId =
+    typeof record.createdBy === "string" && record.createdBy.length > 0
+      ? record.createdBy
+      : typeof record.authorId === "string" && record.authorId.length > 0
+        ? record.authorId
+        : "unknown";
+  const createdAt =
+    typeof record.createdAt === "string" && record.createdAt.length > 0
+      ? record.createdAt
+      : new Date(0).toISOString();
+  const entries = Array.isArray(record.entries)
+    ? record.entries
+        .filter((entry): entry is Record<string, unknown> => isRecord(entry))
+        .map((entry, index) => ({
+          entryId:
+            typeof entry.entryId === "string" && entry.entryId.length > 0
+              ? entry.entryId
+              : `${String(record.commentId ?? "comment")}-entry-${index + 1}`,
+          authorId:
+            typeof entry.authorId === "string" && entry.authorId.length > 0
+              ? entry.authorId
+              : authorId,
+          body: typeof entry.body === "string" ? entry.body : "",
+          createdAt:
+            typeof entry.createdAt === "string" && entry.createdAt.length > 0
+              ? entry.createdAt
+              : createdAt,
+          metadata: isRecord(entry.metadata)
+            ? {
+                ooxmlCommentId:
+                  typeof entry.metadata.ooxmlCommentId === "string"
+                    ? entry.metadata.ooxmlCommentId
+                    : undefined,
+                paraId:
+                  typeof entry.metadata.paraId === "string"
+                    ? entry.metadata.paraId
+                    : undefined,
+                parentParaId:
+                  typeof entry.metadata.parentParaId === "string"
+                    ? entry.metadata.parentParaId
+                    : undefined,
+                durableId:
+                  typeof entry.metadata.durableId === "string"
+                    ? entry.metadata.durableId
+                    : undefined,
+                initials:
+                  typeof entry.metadata.initials === "string"
+                    ? entry.metadata.initials
+                    : undefined,
+              }
+            : undefined,
+        }))
+    : [
+        {
+          entryId: `${String(record.commentId ?? "comment")}-entry-1`,
+          authorId,
+          body: typeof record.body === "string" ? record.body : "",
+          createdAt,
+        },
+      ];
+  const resolution = isRecord(record.resolution)
+    ? {
+        resolvedAt:
+          typeof record.resolution.resolvedAt === "string"
+            ? record.resolution.resolvedAt
+            : typeof record.resolvedAt === "string"
+              ? record.resolvedAt
+              : createdAt,
+        resolvedBy:
+          typeof record.resolution.resolvedBy === "string" &&
+          record.resolution.resolvedBy.length > 0
+            ? record.resolution.resolvedBy
+            : authorId,
+      }
+    : typeof record.resolvedAt === "string"
+      ? {
+          resolvedAt: record.resolvedAt,
+          resolvedBy: authorId,
+        }
+      : undefined;
+  const normalizedStatus =
+    typeof record.status === "string"
+      ? record.status
+      : record.anchor && isRecord(record.anchor) && record.anchor.kind === "detached"
+        ? "detached"
+        : resolution || record.isResolved
+          ? "resolved"
+          : "open";
+
+  return {
+    commentId:
+      typeof record.commentId === "string" && record.commentId.length > 0
+        ? record.commentId
+        : "comment-generated",
+    anchor:
+      isRecord(record.anchor) && typeof record.anchor.kind === "string"
+        ? (record.anchor as EditorAnchorProjection)
+        : createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+    createdAt,
+    createdBy: authorId,
+    authorId,
+    body: entries.map((entry) => entry.body).join("\n"),
+    entries,
+    status:
+      normalizedStatus === "resolved" || normalizedStatus === "detached"
+        ? normalizedStatus
+        : "open",
+    resolution,
+    resolvedAt: resolution?.resolvedAt,
+    warningIds: Array.isArray(record.warningIds)
+      ? record.warningIds.filter((warningId): warningId is string => typeof warningId === "string")
+      : [],
+    isResolved: normalizedStatus === "resolved",
+    metadata: isRecord(record.metadata)
+      ? {
+          source:
+            record.metadata.source === "import" || record.metadata.source === "runtime"
+              ? record.metadata.source
+              : undefined,
+          rootOoxmlCommentId:
+            typeof record.metadata.rootOoxmlCommentId === "string"
+              ? record.metadata.rootOoxmlCommentId
+              : undefined,
+          rootParaId:
+            typeof record.metadata.rootParaId === "string"
+              ? record.metadata.rootParaId
+              : undefined,
+        }
+      : undefined,
+  };
+}