@beyondwork/docx-react-component 1.0.1 → 1.0.3

package/src/preservation/store.ts

@@ -0,0 +1,185 @@
+import type {
+  DocRange,
+  OpaqueFragmentRecord,
+  PreservationStore,
+  PreservedPackagePart,
+} from "../model/canonical-document.ts";
+
+export interface OpaqueFragmentDescriptor {
+  featureKey:
+    | "sections"
+    | "tables"
+    | "headers-footers"
+    | "fields"
+    | "content-controls"
+    | "custom-xml"
+    | "alt-chunk"
+    | "embedded-objects"
+    | "alternate-content"
+    | "unknown-ooxml";
+  label: string;
+  detail: string;
+}
+
+export function createPreservationStore(
+  seed?: Partial<PreservationStore>,
+): PreservationStore {
+  return {
+    opaqueFragments: { ...(seed?.opaqueFragments ?? {}) },
+    packageParts: { ...(seed?.packageParts ?? {}) },
+  };
+}
+
+export function getOpaqueFragment(
+  store: PreservationStore,
+  fragmentId: string,
+): OpaqueFragmentRecord | undefined {
+  return normalizeOpaqueFragmentMap(store)[fragmentId];
+}
+
+export function listOpaqueFragments(
+  store: PreservationStore,
+): OpaqueFragmentRecord[] {
+  return Object.values(normalizeOpaqueFragmentMap(store)).sort((left, right) => {
+    return (
+      left.lastKnownRange.from - right.lastKnownRange.from ||
+      left.fragmentId.localeCompare(right.fragmentId)
+    );
+  });
+}
+
+export function listPreservedPackageParts(
+  store: PreservationStore,
+): PreservedPackagePart[] {
+  return Object.values(normalizePackagePartMap(store)).sort((left, right) =>
+    left.packagePartName.localeCompare(right.packagePartName),
+  );
+}
+
+export function findOpaqueFragmentsIntersectingRange(
+  store: PreservationStore,
+  range: DocRange,
+): OpaqueFragmentRecord[] {
+  return listOpaqueFragments(store).filter((fragment) =>
+    rangesIntersect(fragment.lastKnownRange, range),
+  );
+}
+
+export function describeOpaqueFragment(
+  fragment: OpaqueFragmentRecord,
+): OpaqueFragmentDescriptor {
+  const xml = fragment.payloadReference;
+  const detail = createDetail(fragment);
+
+  if (/\b(?:w:)?sectPr\b/u.test(xml)) {
+    return {
+      featureKey: "sections",
+      label: "Section properties",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?tbl\b/u.test(xml)) {
+    return {
+      featureKey: "tables",
+      label: "Preserved table structure",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?hdr\b|\b(?:w:)?ftr\b/u.test(xml)) {
+    return {
+      featureKey: "headers-footers",
+      label: "Header or footer content",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?fldSimple\b|\b(?:w:)?fldChar\b|\b(?:w:)?instrText\b/u.test(xml)) {
+    return {
+      featureKey: "fields",
+      label: "Word field content",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?sdt\b/u.test(xml)) {
+    return {
+      featureKey: "content-controls",
+      label: "Content control",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?customXml\b/u.test(xml)) {
+    return {
+      featureKey: "custom-xml",
+      label: "Custom XML wrapper",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?altChunk\b/u.test(xml)) {
+    return {
+      featureKey: "alt-chunk",
+      label: "Alternate content import",
+      detail,
+    };
+  }
+
+  if (/\b(?:w:)?object\b|\b(?:o:)?OLEObject\b/u.test(xml)) {
+    return {
+      featureKey: "embedded-objects",
+      label: "Embedded object",
+      detail,
+    };
+  }
+
+  if (/\b(?:mc:)?AlternateContent\b/u.test(xml)) {
+    return {
+      featureKey: "alternate-content",
+      label: "Markup compatibility block",
+      detail,
+    };
+  }
+
+  return {
+    featureKey: "unknown-ooxml",
+    label: "Unsupported OOXML fragment",
+    detail,
+  };
+}
+
+function createDetail(fragment: OpaqueFragmentRecord): string {
+  const detail = [
+    `Preserved whole-unit from ${fragment.lastKnownRange.from}-${fragment.lastKnownRange.to}.`,
+    fragment.packagePartName ? `Part ${fragment.packagePartName}.` : null,
+    fragment.relationshipId ? `Relationship ${fragment.relationshipId}.` : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return detail.length > 0
+    ? detail
+    : "Preserved whole-unit to keep unsupported OOXML intact.";
+}
+
+function rangesIntersect(left: DocRange, right: DocRange): boolean {
+  return left.from < right.to && right.from < left.to;
+}
+
+function normalizeOpaqueFragmentMap(
+  store: PreservationStore,
+): Record<string, OpaqueFragmentRecord> {
+  return store && typeof store === "object" && store.opaqueFragments && typeof store.opaqueFragments === "object"
+    ? (store.opaqueFragments as Record<string, OpaqueFragmentRecord>)
+    : {};
+}
+
+function normalizePackagePartMap(
+  store: PreservationStore,
+): Record<string, PreservedPackagePart> {
+  return store && typeof store === "object" && store.packageParts && typeof store.packageParts === "object"
+    ? (store.packageParts as Record<string, PreservedPackagePart>)
+    : {};
+}

package/src/review/README.md

@@ -0,0 +1,16 @@
+# Review
+
+Comments, anchors, revisions, remap helpers, and accept/reject behavior belong here.
+
+Frozen Wave 1 contract:
+
+- comments and revisions live in the canonical `review` store, not in the content tree
+- review anchors use canonical position ranges or detached-anchor payloads, never DOM paths
+- all review mutations flow through runtime commands and transactions
+- detached comments or revisions remain addressable with reason metadata; they are not silently dropped
+- v1 authoring is limited to single-paragraph comments, thread replies, tracked insertions, tracked deletions, and accept/reject flows
+- preserve-only review structures such as multi-paragraph editable comment ranges, tracked moves, and structural list/table revisions stay locked and warning-backed
+
+Key subdirectories:
+
+- `store/`

package/src/review/store/README.md

@@ -0,0 +1,3 @@
+# Review Store
+
+Comment threads, revision records, review selectors, and accept/reject state belong here.

package/src/review/store/comment-anchors.ts

@@ -0,0 +1,70 @@
+import {
+  createNodeAnchor,
+  createRangeAnchor,
+  mapAnchor,
+  normalizeRange,
+  type Assoc,
+  type BoundaryAssoc,
+  type DocRange,
+  type EditorAnchorProjection,
+  type TransactionMapping,
+} from "../../core/selection/mapping.ts";
+
+export type CommentAnchor = EditorAnchorProjection;
+export type CommentAnchorState = "active" | "detached";
+
+export interface CommentAnchorSummary {
+  anchor: CommentAnchor;
+  state: CommentAnchorState;
+  range: DocRange;
+}
+
+export function createCommentRangeAnchor(
+  from: number,
+  to = from,
+  assoc?: BoundaryAssoc,
+): CommentAnchor {
+  return createRangeAnchor(from, to, assoc);
+}
+
+export function createCommentNodeAnchor(at: number, assoc?: Assoc): CommentAnchor {
+  return createNodeAnchor(at, assoc);
+}
+
+export function remapCommentAnchor(
+  anchor: CommentAnchor,
+  mapping: TransactionMapping,
+): CommentAnchor {
+  return mapAnchor(anchor, mapping);
+}
+
+export function isDetachedCommentAnchor(anchor: CommentAnchor): boolean {
+  return anchor.kind === "detached";
+}
+
+export function summarizeCommentAnchor(anchor: CommentAnchor): CommentAnchorSummary {
+  if (anchor.kind === "range") {
+    return {
+      anchor,
+      state: "active",
+      range: normalizeRange(anchor.range),
+    };
+  }
+
+  if (anchor.kind === "node") {
+    return {
+      anchor,
+      state: "active",
+      range: {
+        from: anchor.at,
+        to: anchor.at,
+      },
+    };
+  }
+
+  return {
+    anchor,
+    state: "detached",
+    range: normalizeRange(anchor.lastKnownRange),
+  };
+}

package/src/review/store/comment-remapping.ts

@@ -0,0 +1,154 @@
+import type { CommentThreadRecord, EditorWarning } from "../../core/state/editor-state.ts";
+import {
+  detachReviewAnchor,
+  getAnchorRange,
+  mapReviewAnchor,
+  mappingTouchesAnchorContent,
+  rangeStaysWithinSingleParagraph,
+  type ReviewAnchor,
+} from "../../core/selection/review-anchors.ts";
+import type { TransactionMapping } from "../../core/selection/mapping.ts";
+
+export interface RemapCommentThreadsOptions {
+  comments: Record<string, CommentThreadRecord>;
+  mapping: TransactionMapping;
+  nextContent: unknown;
+  existingWarnings?: EditorWarning[];
+}
+
+export interface RemapCommentThreadsResult {
+  comments: Record<string, CommentThreadRecord>;
+  warnings: EditorWarning[];
+  detachedCommentIds: string[];
+}
+
+export function remapCommentThreads(
+  options: RemapCommentThreadsOptions,
+): RemapCommentThreadsResult {
+  const comments = Object.fromEntries(
+    Object.entries(options.comments).map(([commentId, comment]) => [
+      commentId,
+      remapCommentThread(comment, options.mapping, options.nextContent),
+    ]),
+  );
+  const detachedCommentIds = Object.values(comments)
+    .filter((comment) => comment.anchor.kind === "detached")
+    .map((comment) => comment.commentId);
+
+  return {
+    comments,
+    warnings: mergeDetachedAnchorWarnings(comments, options.existingWarnings ?? []),
+    detachedCommentIds,
+  };
+}
+
+export function remapCommentThread(
+  comment: CommentThreadRecord,
+  mapping: TransactionMapping,
+  nextContent: unknown,
+): CommentThreadRecord {
+  if (comment.anchor.kind === "detached") {
+    return comment;
+  }
+
+  const mappedAnchor = mapReviewAnchor(comment.anchor, mapping);
+  const anchor = normalizeCommentAnchor(comment.anchor, mappedAnchor, mapping, nextContent);
+
+  return {
+    ...comment,
+    anchor,
+  };
+}
+
+function normalizeCommentAnchor(
+  previousAnchor: ReviewAnchor,
+  mappedAnchor: ReviewAnchor,
+  mapping: TransactionMapping,
+  nextContent: unknown,
+): ReviewAnchor {
+  if (mappedAnchor.kind === "detached") {
+    return mappedAnchor;
+  }
+
+  const previousRange = getAnchorRange(previousAnchor);
+  const mappedRange = getAnchorRange(mappedAnchor);
+
+  if (
+    previousAnchor.kind === "range" &&
+    previousRange.from < previousRange.to &&
+    mappedAnchor.kind === "range" &&
+    mappedRange.from === mappedRange.to &&
+    mappingTouchesAnchorContent(previousAnchor, mapping)
+  ) {
+    return detachReviewAnchor(previousRange, detachReason(mapping));
+  }
+
+  if (
+    mappedAnchor.kind === "range" &&
+    !rangeStaysWithinSingleParagraph(nextContent, mappedAnchor.range)
+  ) {
+    return detachReviewAnchor(previousRange, "invalidatedByStructureChange");
+  }
+
+  return mappedAnchor;
+}
+
+function detachReason(
+  mapping: TransactionMapping,
+): "deleted" | "invalidatedByStructureChange" {
+  return mapping.metadata?.invalidatesStructures
+    ? "invalidatedByStructureChange"
+    : "deleted";
+}
+
+function mergeDetachedAnchorWarnings(
+  comments: Record<string, CommentThreadRecord>,
+  existingWarnings: EditorWarning[],
+): EditorWarning[] {
+  const retainedWarnings = existingWarnings.filter(
+    (warning) =>
+      warning.code !== "comment_anchor_detached" ||
+      !warning.details ||
+      typeof warning.details.commentId !== "string" ||
+      comments[warning.details.commentId]?.anchor.kind === "detached",
+  );
+
+  const knownDetachedIds = new Set(
+    retainedWarnings
+      .filter((warning) => warning.code === "comment_anchor_detached")
+      .map((warning) =>
+        typeof warning.details?.commentId === "string"
+          ? warning.details.commentId
+          : undefined,
+      )
+      .filter((value): value is string => Boolean(value)),
+  );
+
+  const detachedWarnings = Object.values(comments)
+    .filter(
+      (comment) =>
+        comment.anchor.kind === "detached" && !knownDetachedIds.has(comment.commentId),
+    )
+    .map((comment) => createDetachedCommentWarning(comment));
+
+  return [...retainedWarnings, ...detachedWarnings];
+}
+
+function createDetachedCommentWarning(
+  comment: CommentThreadRecord,
+): EditorWarning {
+  const anchor = comment.anchor.kind === "detached" ? comment.anchor : undefined;
+
+  return {
+    warningId: `warning:comment-anchor-detached:${comment.commentId}`,
+    code: "comment_anchor_detached",
+    severity: "warning",
+    message: `Comment ${comment.commentId} detached after edit remapping.`,
+    source: "review",
+    affectedAnchor: anchor,
+    details: {
+      commentId: comment.commentId,
+      reason: anchor?.reason,
+    },
+  };
+}