@beyondwork/docx-react-component 1.0.0

package/src/model/cds-1.0.0.ts

@@ -0,0 +1,196 @@
+export const CDS_SCHEMA_VERSION = "cds/1.0.0" as const;
+export const PERSISTED_EDITOR_SNAPSHOT_VERSION =
+  "persisted-editor-snapshot/1" as const;
+export const COMPATIBILITY_REPORT_VERSION = "compatibility-report/1" as const;
+
+export type CDS_SchemaVersion = typeof CDS_SCHEMA_VERSION;
+export type PersistedEditorSnapshotVersion =
+  typeof PERSISTED_EDITOR_SNAPSHOT_VERSION;
+export type CompatibilityReportVersion = typeof COMPATIBILITY_REPORT_VERSION;
+
+export type Id = string;
+export type UUID = string;
+export type ISO8601DateTime = string;
+export type Base64 = string;
+export type PartName = string;
+export type RelationshipId = string;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+
+export interface JsonObject {
+  [key: string]: JsonValue | undefined;
+}
+
+export interface ModelValidationIssue {
+  path: string;
+  message: string;
+}
+
+export class ModelValidationError extends Error {
+  readonly issues: readonly ModelValidationIssue[];
+
+  constructor(message: string, issues: readonly ModelValidationIssue[]) {
+    super(message);
+    this.name = "ModelValidationError";
+    this.issues = issues;
+  }
+}
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const ISO_8601_UTC_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function isUuid(value: unknown): value is UUID {
+  return typeof value === "string" && UUID_PATTERN.test(value);
+}
+
+export function isIso8601UtcTimestamp(
+  value: unknown,
+): value is ISO8601DateTime {
+  return (
+    typeof value === "string" &&
+    ISO_8601_UTC_PATTERN.test(value) &&
+    !Number.isNaN(Date.parse(value))
+  );
+}
+
+export function asPlainObject(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): Record<string, unknown> | null {
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "Expected a plain object." });
+    return null;
+  }
+
+  return value;
+}
+
+export function expectString(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): string | null {
+  if (!isNonEmptyString(value)) {
+    issues.push({ path, message: "Expected a non-empty string." });
+    return null;
+  }
+
+  return value;
+}
+
+export function expectExactString<T extends string>(
+  value: unknown,
+  expected: T,
+  path: string,
+  issues: ModelValidationIssue[],
+): T | null {
+  if (value !== expected) {
+    issues.push({
+      path,
+      message: `Expected ${JSON.stringify(expected)}.`,
+    });
+    return null;
+  }
+
+  return expected;
+}
+
+export function expectIso8601UtcTimestamp(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): ISO8601DateTime | null {
+  if (!isIso8601UtcTimestamp(value)) {
+    issues.push({
+      path,
+      message: "Expected an ISO 8601 UTC timestamp string.",
+    });
+    return null;
+  }
+
+  return value;
+}
+
+export function expectUuid(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): UUID | null {
+  if (!isUuid(value)) {
+    issues.push({
+      path,
+      message: "Expected an RFC 4122 UUID string.",
+    });
+    return null;
+  }
+
+  return value;
+}
+
+export function sortRecordKeys<T>(
+  record: Record<string, T>,
+): Array<[string, T]> {
+  return Object.entries(record).sort(([left], [right]) =>
+    left.localeCompare(right),
+  );
+}
+
+export function assertValid(
+  issues: readonly ModelValidationIssue[],
+  message: string,
+): void {
+  if (issues.length > 0) {
+    throw new ModelValidationError(message, issues);
+  }
+}
+
+function toStableJsonValue(value: unknown): JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => toStableJsonValue(item));
+  }
+
+  if (!isPlainObject(value)) {
+    throw new TypeError("Cannot serialize non-JSON value.");
+  }
+
+  const sortedEntries = sortRecordKeys(value).filter(
+    ([, entryValue]) => entryValue !== undefined,
+  );
+  const result: JsonObject = {};
+
+  for (const [key, entryValue] of sortedEntries) {
+    result[key] = toStableJsonValue(entryValue);
+  }
+
+  return result;
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(toStableJsonValue(value));
+}

package/src/model/snapshot.ts

@@ -0,0 +1,393 @@
+import {
+  CDS_SCHEMA_VERSION,
+  COMPATIBILITY_REPORT_VERSION,
+  PERSISTED_EDITOR_SNAPSHOT_VERSION,
+  type CompatibilityReportVersion,
+  type ISO8601DateTime,
+  type ModelValidationIssue,
+  type PersistedEditorSnapshotVersion,
+  asPlainObject,
+  assertValid,
+  expectExactString,
+  expectIso8601UtcTimestamp,
+  expectString,
+  stableStringify,
+} from "./cds-1.0.0.ts";
+import {
+  type CanonicalDocument,
+  assertCanonicalDocument,
+  validateCanonicalDocument,
+} from "./canonical-document.ts";
+
+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?: Record<string, unknown>;
+  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?: Record<string, unknown>;
+  details?: Record<string, unknown>;
+}
+
+export interface CompatibilityReport {
+  reportVersion: CompatibilityReportVersion;
+  generatedAt: ISO8601DateTime;
+  blockExport: boolean;
+  featureEntries: CompatibilityFeatureEntry[];
+  warnings: EditorWarning[];
+  errors: EditorError[];
+}
+
+export interface PersistedEditorSnapshot {
+  snapshotVersion: PersistedEditorSnapshotVersion;
+  schemaVersion: typeof CDS_SCHEMA_VERSION;
+  documentId: string;
+  docId: string;
+  createdAt: ISO8601DateTime;
+  updatedAt: ISO8601DateTime;
+  savedAt: ISO8601DateTime;
+  editorBuild: string;
+  canonicalDocument: CanonicalDocument;
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+}
+
+const SNAPSHOT_TOP_LEVEL_KEYS = [
+  "snapshotVersion",
+  "schemaVersion",
+  "documentId",
+  "docId",
+  "createdAt",
+  "updatedAt",
+  "savedAt",
+  "editorBuild",
+  "canonicalDocument",
+  "compatibility",
+  "warningLog",
+] as const;
+
+export function serializePersistedEditorSnapshot(
+  snapshot: PersistedEditorSnapshot,
+): string {
+  assertPersistedEditorSnapshot(snapshot);
+  return stableStringify(snapshot);
+}
+
+export function parsePersistedEditorSnapshot(
+  json: string,
+): PersistedEditorSnapshot {
+  const parsed = JSON.parse(json) as unknown;
+  assertPersistedEditorSnapshot(parsed);
+  return parsed;
+}
+
+export function assertPersistedEditorSnapshot(
+  snapshot: unknown,
+): asserts snapshot is PersistedEditorSnapshot {
+  const issues = validatePersistedEditorSnapshot(snapshot);
+  assertValid(issues, "Invalid persisted editor snapshot.");
+}
+
+export function validatePersistedEditorSnapshot(
+  snapshot: unknown,
+): ModelValidationIssue[] {
+  const issues: ModelValidationIssue[] = [];
+  const record = asPlainObject(snapshot, "$", issues);
+  if (!record) {
+    return issues;
+  }
+
+  validateExactObjectKeys(record, SNAPSHOT_TOP_LEVEL_KEYS, "$", issues);
+
+  expectExactString(
+    record.snapshotVersion,
+    PERSISTED_EDITOR_SNAPSHOT_VERSION,
+    "$.snapshotVersion",
+    issues,
+  );
+  expectExactString(
+    record.schemaVersion,
+    CDS_SCHEMA_VERSION,
+    "$.schemaVersion",
+    issues,
+  );
+  expectString(record.documentId, "$.documentId", issues);
+  expectString(record.docId, "$.docId", issues);
+  expectIso8601UtcTimestamp(record.createdAt, "$.createdAt", issues);
+  expectIso8601UtcTimestamp(record.updatedAt, "$.updatedAt", issues);
+  expectIso8601UtcTimestamp(record.savedAt, "$.savedAt", issues);
+  expectString(record.editorBuild, "$.editorBuild", issues);
+
+  const canonicalDocumentIssues = validateCanonicalDocument(record.canonicalDocument);
+  issues.push(...canonicalDocumentIssues.map(prefixIssue("$.canonicalDocument")));
+
+  if (
+    asPlainObject(record.canonicalDocument, "$.canonicalDocument", [])?.docId !==
+    record.docId
+  ) {
+    issues.push({
+      path: "$.docId",
+      message: "Snapshot docId must match canonicalDocument.docId.",
+    });
+  }
+
+  validateCompatibilityReport(record.compatibility, "$.compatibility", issues);
+
+  if (!Array.isArray(record.warningLog)) {
+    issues.push({
+      path: "$.warningLog",
+      message: "warningLog must be an array.",
+    });
+  } else {
+    record.warningLog.forEach((warning, index) => {
+      validateEditorWarning(warning, `$.warningLog[${index}]`, issues);
+    });
+  }
+
+  return issues;
+}
+
+export function assertCompatibilityReport(
+  report: unknown,
+): asserts report is CompatibilityReport {
+  const issues = validateCompatibilityReport(report);
+  assertValid(issues, "Invalid compatibility report.");
+}
+
+export function validateCompatibilityReport(
+  report: unknown,
+  path = "$",
+  issues: ModelValidationIssue[] = [],
+): ModelValidationIssue[] {
+  const record = asPlainObject(report, path, issues);
+  if (!record) {
+    return issues;
+  }
+
+  expectExactString(
+    record.reportVersion,
+    COMPATIBILITY_REPORT_VERSION,
+    `${path}.reportVersion`,
+    issues,
+  );
+  expectIso8601UtcTimestamp(record.generatedAt, `${path}.generatedAt`, issues);
+
+  if (typeof record.blockExport !== "boolean") {
+    issues.push({
+      path: `${path}.blockExport`,
+      message: "blockExport must be a boolean.",
+    });
+  }
+
+  if (!Array.isArray(record.featureEntries)) {
+    issues.push({
+      path: `${path}.featureEntries`,
+      message: "featureEntries must be an array.",
+    });
+  } else {
+    record.featureEntries.forEach((featureEntry, index) => {
+      validateCompatibilityFeatureEntry(
+        featureEntry,
+        `${path}.featureEntries[${index}]`,
+        issues,
+      );
+    });
+  }
+
+  if (!Array.isArray(record.warnings)) {
+    issues.push({
+      path: `${path}.warnings`,
+      message: "warnings must be an array.",
+    });
+  } else {
+    record.warnings.forEach((warning, index) => {
+      validateEditorWarning(warning, `${path}.warnings[${index}]`, issues);
+    });
+  }
+
+  if (!Array.isArray(record.errors)) {
+    issues.push({
+      path: `${path}.errors`,
+      message: "errors must be an array.",
+    });
+  } else {
+    record.errors.forEach((error, index) => {
+      validateEditorError(error, `${path}.errors[${index}]`, issues);
+    });
+  }
+
+  return issues;
+}
+
+function validateCompatibilityFeatureEntry(
+  featureEntry: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(featureEntry, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectString(record.featureEntryId, `${path}.featureEntryId`, issues);
+  expectString(record.featureKey, `${path}.featureKey`, issues);
+  expectString(record.featureClass, `${path}.featureClass`, issues);
+  expectString(record.message, `${path}.message`, issues);
+}
+
+function validateEditorWarning(
+  warning: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(warning, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectString(record.warningId, `${path}.warningId`, issues);
+  expectString(record.code, `${path}.code`, issues);
+  expectString(record.severity, `${path}.severity`, issues);
+  expectString(record.message, `${path}.message`, issues);
+  expectString(record.source, `${path}.source`, issues);
+}
+
+function validateEditorError(
+  error: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(error, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectString(record.errorId, `${path}.errorId`, issues);
+  expectString(record.code, `${path}.code`, issues);
+  expectString(record.message, `${path}.message`, issues);
+  expectString(record.source, `${path}.source`, issues);
+
+  if (typeof record.isFatal !== "boolean") {
+    issues.push({
+      path: `${path}.isFatal`,
+      message: "isFatal must be a boolean.",
+    });
+  }
+}
+
+function validateExactObjectKeys(
+  record: Record<string, unknown>,
+  expectedKeys: readonly string[],
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const actualKeys = new Set(Object.keys(record));
+  const expected = new Set(expectedKeys);
+
+  for (const expectedKey of expectedKeys) {
+    if (!actualKeys.has(expectedKey)) {
+      issues.push({
+        path,
+        message: `Missing required key ${JSON.stringify(expectedKey)}.`,
+      });
+    }
+  }
+
+  for (const actualKey of actualKeys) {
+    if (!expected.has(actualKey)) {
+      issues.push({
+        path: `${path}.${actualKey}`,
+        message:
+          "Unexpected persisted snapshot key. Render/UI state is not part of the persistence contract.",
+      });
+    }
+  }
+}
+
+function prefixIssue(basePath: string) {
+  return (issue: ModelValidationIssue): ModelValidationIssue => ({
+    path: `${basePath}${issue.path === "$" ? "" : issue.path.slice(1)}`,
+    message: issue.message,
+  });
+}
+
+export function createPersistedEditorSnapshot(params: {
+  documentId: string;
+  savedAt: ISO8601DateTime;
+  editorBuild: string;
+  canonicalDocument: CanonicalDocument;
+  compatibility: CompatibilityReport;
+  warningLog?: EditorWarning[];
+}): PersistedEditorSnapshot {
+  assertCanonicalDocument(params.canonicalDocument);
+  assertCompatibilityReport(params.compatibility);
+
+  return {
+    snapshotVersion: PERSISTED_EDITOR_SNAPSHOT_VERSION,
+    schemaVersion: CDS_SCHEMA_VERSION,
+    documentId: params.documentId,
+    docId: params.canonicalDocument.docId,
+    createdAt: params.canonicalDocument.createdAt,
+    updatedAt: params.canonicalDocument.updatedAt,
+    savedAt: params.savedAt,
+    editorBuild: params.editorBuild,
+    canonicalDocument: params.canonicalDocument,
+    compatibility: params.compatibility,
+    warningLog: params.warningLog ?? params.compatibility.warnings,
+  };
+}
+
+export function projectAnchorToSnapshot(
+  anchor: Record<string, unknown>,
+): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(anchor)) as Record<string, unknown>;
+}

package/src/preservation/README.md

@@ -0,0 +1,3 @@
+# Preservation
+
+Unsupported OOXML capture, retention, untouched package-part preservation, and export reattachment logic belong here.

package/src/preservation/markup-compatibility.ts

@@ -0,0 +1,48 @@
+export function extractDocumentRootAttributes(documentXml: string): Record<string, string> {
+  const match = documentXml.match(
+    /<(?:[A-Za-z_][A-Za-z0-9:._-]*:)?document\b([^>]*)>/u,
+  );
+  if (!match) {
+    return {};
+  }
+
+  const attributes: Record<string, string> = {};
+  const pattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  for (const attributeMatch of (match[1] ?? "").matchAll(pattern)) {
+    const name = attributeMatch[1];
+    const value = attributeMatch[3] ?? attributeMatch[4] ?? "";
+    if (!name) {
+      continue;
+    }
+
+    attributes[name] = value;
+  }
+
+  return attributes;
+}
+
+export function extractMarkupCompatibilityAttributes(
+  documentXml: string,
+): Record<string, string> {
+  return filterMarkupCompatibilityAttributes(extractDocumentRootAttributes(documentXml));
+}
+
+export function filterMarkupCompatibilityAttributes(
+  attributes: Record<string, string>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(attributes).filter(([name]) =>
+      name.startsWith("xmlns:mc") ||
+      name === "mc:Ignorable" ||
+      name === "mc:ProcessContent" ||
+      name === "mc:PreserveAttributes" ||
+      name === "mc:PreserveElements" ||
+      name.startsWith("xmlns:w1") ||
+      name.startsWith("xmlns:wsp") ||
+      name.startsWith("xmlns:wpg") ||
+      name.startsWith("xmlns:wpi") ||
+      name.startsWith("xmlns:wne") ||
+      name.startsWith("xmlns:wps"),
+    ),
+  );
+}