@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/model/canonical-document.ts

@@ -8,6 +8,7 @@ import {
   expectExactString,
   expectIso8601UtcTimestamp,
   expectString,
+  expectStringAllowEmpty,
   expectUuid,
   stableStringify,
 } from "./cds-1.0.0.ts";
@@ -27,7 +28,7 @@ const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
   "diagnostics",
 ] as const;
 
-const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts"] as const;
+const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts", "fieldRegistry"] as const;
 
 const ID_PATTERNS = {
   styleId: /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/,
@@ -61,6 +62,8 @@ export interface CanonicalDocument {
   preservation: PreservationStore;
   diagnostics: DiagnosticStore;
   subParts?: SubPartsCatalog;
+  /** Package-backed field registry for supported field families. */
+  fieldRegistry?: FieldRegistry;
 }
 
 export interface DocumentMetadata {
@@ -79,12 +82,14 @@ export interface StylesCatalog {
   characters: Record<string, CharacterStyleDefinition>;
   tables: Record<string, TableStyleDefinition>;
   latentStyles?: Record<string, LatentStyleDefinition>;
+  fromPackage?: boolean;
 }
 
 export interface ParagraphStyleDefinition {
   styleId: string;
   basedOn?: string;
   nextStyle?: string;
+  outlineLevel?: number;
   displayName: string;
   kind: "paragraph";
   isDefault: boolean;
@@ -131,6 +136,8 @@ export interface NumberingLevelDefinition {
   text: string;
   startAt?: number;
   paragraphStyleId?: string;
+  isLegalNumbering?: boolean;
+  suffix?: "tab" | "space" | "nothing";
 }
 
 export interface NumberingInstance {
@@ -155,6 +162,9 @@ export interface MediaItem {
   relationshipId?: string;
   packagePartName: string;
   altText?: string;
+  display?: "inline" | "floating";
+  widthEmu?: number;
+  heightEmu?: number;
 }
 
 // ---- Sub-part canonical types ----
@@ -166,6 +176,7 @@ export interface HeaderDocument {
   partPath: string;
   relationshipId: string;
   blocks: BlockNode[];
+  sectionIndex?: number;
 }
 
 export interface FooterDocument {
@@ -173,6 +184,7 @@ export interface FooterDocument {
   partPath: string;
   relationshipId: string;
   blocks: BlockNode[];
+  sectionIndex?: number;
 }
 
 export interface FootnoteDefinition {
@@ -203,11 +215,25 @@ export interface ThemeDefinition {
   fontScheme?: ThemeFontScheme;
 }
 
+export interface DocumentSettings {
+  evenAndOddHeaders?: boolean;
+  zoomLevel?: "pageWidth" | "onePage" | number;
+}
+
 export interface SubPartsCatalog {
   headers: HeaderDocument[];
   footers: FooterDocument[];
   footnoteCollection?: FootnoteCollection;
   theme?: ThemeDefinition;
+  finalSectionProperties?: SectionProperties;
+  resolvedTheme?: ResolvedTheme;
+  settings?: DocumentSettings;
+}
+
+export interface ResolvedTheme {
+  colors: Record<string, string>;
+  majorFont?: string;
+  minorFont?: string;
 }
 
 // ---- Inline footnote reference node ----
@@ -305,6 +331,7 @@ export interface ParagraphNode {
   };
   alignment?: "left" | "center" | "right" | "both" | "distribute";
   spacing?: ParagraphSpacing;
+  contextualSpacing?: boolean;
   indentation?: ParagraphIndentation;
   tabStops?: TabStop[];
   keepNext?: boolean;
@@ -407,6 +434,23 @@ export interface TableCellNode {
   verticalAlign?: "top" | "center" | "bottom";
 }
 
+export interface SdtCheckboxState {
+  checked: boolean;
+  checkedChar?: string;
+  uncheckedChar?: string;
+}
+
+export interface SdtDatePickerState {
+  fullDate?: string;
+  dateFormat?: string;
+  lid?: string;
+}
+
+export interface SdtDropdownListItem {
+  displayText?: string;
+  value: string;
+}
+
 export interface SdtNode {
   type: "sdt";
   properties: {
@@ -415,6 +459,11 @@ export interface SdtNode {
     tag?: string;
     lock?: string;
     propertiesXml?: string;
+    checkbox?: SdtCheckboxState;
+    datePicker?: SdtDatePickerState;
+    dropdownList?: SdtDropdownListItem[];
+    comboBox?: SdtDropdownListItem[];
+    showingPlcHdr?: boolean;
   };
   children: BlockNode[];
 }
@@ -431,11 +480,119 @@ export interface AltChunkNode {
   relationshipId: string;
 }
 
+/**
+ * Supported field families that receive first-class canonical treatment.
+ * These families have stable registry IDs, dependency metadata, and
+ * runtime-owned refresh behavior.
+ */
+export type SupportedFieldFamily = "REF" | "PAGEREF" | "NOTEREF" | "TOC";
+
+/**
+ * Unsupported field families that remain preserve-only.
+ * They survive round-trip but do not participate in runtime refresh.
+ */
+export type PreserveOnlyFieldFamily =
+  | "PAGE"
+  | "NUMPAGES"
+  | "DATE"
+  | "TIME"
+  | "AUTHOR"
+  | "FILENAME"
+  | "MERGEFIELD"
+  | "IF"
+  | "SEQ"
+  | "INDEX"
+  | "TC"
+  | "STYLEREF"
+  | "FORMULA"
+  | "UNKNOWN";
+
+export type FieldFamily = SupportedFieldFamily | PreserveOnlyFieldFamily;
+
+/** Runtime refresh status for a field instance. */
+export type FieldRefreshStatus =
+  | "current"
+  | "stale"
+  | "unresolvable"
+  | "preserve-only";
+
 export interface FieldNode {
   type: "field";
   fieldType: "simple" | "complex";
   instruction: string;
   children: InlineNode[];
+  /** Classified field family. Undefined for legacy snapshots. */
+  fieldFamily?: FieldFamily;
+  /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Runtime refresh status. Undefined for legacy or preserve-only fields. */
+  refreshStatus?: FieldRefreshStatus;
+}
+
+// ─── Field registry ─────────────────────────────────────────────────────────
+
+/**
+ * Package-backed field registry that catalogs every field instance in the
+ * document, grouped by supported vs preserve-only families.
+ *
+ * Supported field entries carry dependency metadata (bookmark targets) and
+ * participate in deterministic refresh.  Preserve-only entries survive
+ * round-trip but are not refreshable.
+ */
+export interface FieldRegistry {
+  /** Supported field instances that participate in refresh. */
+  supported: FieldRegistryEntry[];
+  /** Preserve-only field instances cataloged for round-trip safety. */
+  preserveOnly: FieldRegistryEntry[];
+  /** Generated TOC structure extracted from heading-driven TOC fields. */
+  tocStructure?: TocStructure;
+}
+
+export interface FieldRegistryEntry {
+  /** Stable document-order index of this field (0-based). */
+  fieldIndex: number;
+  /** Classified field family. */
+  fieldFamily: FieldFamily;
+  /** Whether the field is in the supported refresh slice. */
+  supported: boolean;
+  /** Field instruction text. */
+  instruction: string;
+  /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Current display text extracted from field content. */
+  displayText: string;
+  /** Paragraph index in document order where this field appears. */
+  paragraphIndex: number;
+  /** Runtime refresh status. */
+  refreshStatus: FieldRefreshStatus;
+}
+
+/**
+ * Generated table-of-contents structure extracted from TOC fields and
+ * heading-styled paragraphs in the document.
+ */
+export interface TocStructure {
+  /** The raw TOC field instruction (e.g. "TOC \\o \"1-3\" \\h"). */
+  instruction: string;
+  /** Heading level range the TOC covers. */
+  levelRange: { from: number; to: number };
+  /** Ordered TOC entries derived from heading paragraphs. */
+  entries: TocEntry[];
+  /** Whether the TOC content is current with the heading structure. */
+  status: "current" | "stale";
+}
+
+export interface TocEntry {
+  /** Heading text. */
+  text: string;
+  /** Heading outline level (1-9). */
+  level: number;
+  /** Paragraph index of the heading in document order. */
+  paragraphIndex: number;
+  /** Style ID of the heading paragraph, if available. */
+  styleId?: string;
+  /** Bookmark name anchoring this heading, if present. */
+  bookmarkName?: string;
 }
 
 export interface BookmarkStartNode {
@@ -451,7 +608,86 @@ export interface BookmarkEndNode {
 
 export interface SectionBreakNode {
   type: "section_break";
+  sectionPropertiesXml?: string;
+  /**
+   * @deprecated Legacy field from older snapshots. New exports should use
+   * sectionPropertiesXml and only contain raw <w:sectPr> content.
+   */
   propertiesXml?: string;
+  sectionProperties?: SectionProperties;
+}
+
+export interface SectionProperties {
+  pageSize?: PageSize;
+  pageMargins?: PageMargins;
+  columns?: ColumnProperties;
+  pageNumbering?: PageNumbering;
+  lineNumbering?: SectionLineNumbering;
+  pageBorders?: SectionPageBorders;
+  documentGrid?: SectionDocumentGrid;
+  headerReferences?: HeaderFooterReference[];
+  footerReferences?: HeaderFooterReference[];
+  sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
+  titlePage?: boolean;
+}
+
+export interface PageSize {
+  width: number;
+  height: number;
+  orientation?: "portrait" | "landscape";
+}
+
+export interface PageMargins {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  header?: number;
+  footer?: number;
+  gutter?: number;
+}
+
+export interface ColumnProperties {
+  count?: number;
+  space?: number;
+  equalWidth?: boolean;
+  columns?: Array<{ width: number; space?: number }>;
+  separator?: boolean;
+}
+
+export interface PageNumbering {
+  format?: string;
+  start?: number;
+  chapStyle?: string;
+  chapSep?: string;
+}
+
+export interface SectionLineNumbering {
+  countBy?: number;
+  start?: number;
+  distance?: number;
+  restart?: "newPage" | "newSection" | "continuous";
+}
+
+export interface SectionPageBorders {
+  top?: BorderSpec;
+  left?: BorderSpec;
+  bottom?: BorderSpec;
+  right?: BorderSpec;
+  offsetFrom?: "page" | "text";
+  display?: "allPages" | "firstPage" | "notFirstPage";
+  zOrder?: "front" | "back";
+}
+
+export interface SectionDocumentGrid {
+  type?: "default" | "lines" | "linesAndChars" | "snapToChars";
+  linePitch?: number;
+  charSpace?: number;
+}
+
+export interface HeaderFooterReference {
+  variant: HeaderFooterVariant;
+  relationshipId: string;
 }
 
 export type InlineNode =
@@ -487,6 +723,7 @@ export type TextMark =
   | { type: "doubleStrikethrough" }
   | { type: "vanish" }
   | { type: "lang"; val: string }
+  | { type: "highlight"; color: string; val: string }
   | { type: "backgroundColor"; color: string }
   | { type: "charSpacing"; val: number }
   | { type: "kerning"; val: number }
@@ -587,6 +824,7 @@ export interface ShapeNode {
   type: "shape";
   text?: string;
   geometry?: string;
+  isTextBox?: boolean;
   rawXml: string;
 }
 
@@ -617,6 +855,7 @@ export interface OpaqueBlockNode {
   type: "opaque_block";
   fragmentId: string;
   warningId: string;
+  rawXml?: string;
 }
 
 export interface DocRange {
@@ -781,7 +1020,7 @@ export interface DiagnosticErrorEntry {
     | "internal_invariant";
   message: string;
   isFatal: boolean;
-  source: "import" | "runtime" | "validation" | "datastore" | "export";
+  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
   details?: unknown;
 }
 
@@ -1146,6 +1385,9 @@ function validateDocumentNode(
     case "opaque_block":
       expectDomainString(record.fragmentId, "fragmentId", `${path}.fragmentId`, issues);
       expectDomainString(record.warningId, "warningId", `${path}.warningId`, issues);
+      if (record.rawXml !== undefined) {
+        expectString(record.rawXml, `${path}.rawXml`, issues);
+      }
       return;
     case "table":
       if (!Array.isArray(record.gridColumns)) {
@@ -1343,7 +1585,11 @@ function validateReviewStore(
         );
       }
       if (threadRecord.body !== undefined) {
-        expectString(threadRecord.body, `${path}.comments.${commentId}.body`, issues);
+        expectStringAllowEmpty(
+          threadRecord.body,
+          `${path}.comments.${commentId}.body`,
+          issues,
+        );
       }
       if (!Array.isArray(threadRecord.warningIds)) {
         issues.push({
@@ -1489,7 +1735,7 @@ function validateCommentEntries(
     }
     expectString(record.entryId, `${path}[${index}].entryId`, issues);
     expectString(record.authorId, `${path}[${index}].authorId`, issues);
-    expectString(record.body, `${path}[${index}].body`, issues);
+    expectStringAllowEmpty(record.body, `${path}[${index}].body`, issues);
     expectIso8601UtcTimestamp(record.createdAt, `${path}[${index}].createdAt`, issues);
     if (record.metadata !== undefined) {
       validateCommentEntryMetadata(record.metadata, `${path}[${index}].metadata`, issues);

package/src/model/cds-1.0.0.ts

@@ -98,6 +98,19 @@ export function expectString(
   return value;
 }
 
+export function expectStringAllowEmpty(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): string | null {
+  if (typeof value !== "string") {
+    issues.push({ path, message: "Expected a string." });
+    return null;
+  }
+
+  return value;
+}
+
 export function expectExactString<T extends string>(
   value: unknown,
   expected: T,

package/src/model/snapshot.ts

@@ -62,7 +62,7 @@ export interface EditorError {
   code: EditorErrorCode;
   message: string;
   isFatal: boolean;
-  source: "import" | "runtime" | "validation" | "datastore" | "export";
+  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
   details?: Record<string, unknown>;
 }
 
@@ -110,6 +110,7 @@ export interface PersistedEditorSnapshot {
   canonicalDocument: CanonicalDocument;
   compatibility: CompatibilityReport;
   warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshotRecord;
   sourcePackage?: PersistedSourcePackage;
 }
 
@@ -127,7 +128,26 @@ const SNAPSHOT_REQUIRED_TOP_LEVEL_KEYS = [
   "warningLog",
 ] as const;
 
-const SNAPSHOT_OPTIONAL_TOP_LEVEL_KEYS = ["sourcePackage"] as const;
+const SNAPSHOT_OPTIONAL_TOP_LEVEL_KEYS = ["sourcePackage", "protectionSnapshot"] as const;
+
+export interface ProtectionRangeRecord {
+  rangeId: string;
+  start?: number;
+  end?: number;
+  editorGroup?: string;
+  editor?: string;
+  enforced: boolean;
+  enforcementReason: string;
+}
+
+export interface ProtectionSnapshotRecord {
+  hasDocumentProtection: boolean;
+  editType?: string;
+  enforcementActive: boolean;
+  ranges: ProtectionRangeRecord[];
+  enforcedRangeCount: number;
+  preservedRangeCount: number;
+}
 
 const PERSISTED_EDITOR_SNAPSHOT_VERSIONS = new Set<PersistedEditorSnapshotVersion>([
   LEGACY_PERSISTED_EDITOR_SNAPSHOT_VERSION,
@@ -174,6 +194,7 @@ const EDITOR_ERROR_SOURCES = new Set<EditorError["source"]>([
   "runtime",
   "validation",
   "datastore",
+  "host",
   "export",
 ]);
 
@@ -259,6 +280,9 @@ export function validatePersistedEditorSnapshot(
   if (record.sourcePackage !== undefined) {
     validatePersistedSourcePackage(record.sourcePackage, "$.sourcePackage", issues);
   }
+  if (record.protectionSnapshot !== undefined) {
+    validateProtectionSnapshot(record.protectionSnapshot, "$.protectionSnapshot", issues);
+  }
 
   return issues;
 }
@@ -536,6 +560,7 @@ export function createPersistedEditorSnapshot(params: {
   canonicalDocument: CanonicalDocument;
   compatibility: CompatibilityReport;
   warningLog?: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshotRecord;
   sourcePackage?: PersistedSourcePackage;
 }): PersistedEditorSnapshot {
   assertCanonicalDocument(params.canonicalDocument);
@@ -553,10 +578,70 @@ export function createPersistedEditorSnapshot(params: {
     canonicalDocument: params.canonicalDocument,
     compatibility: params.compatibility,
     warningLog: params.warningLog ?? params.compatibility.warnings,
+    protectionSnapshot: params.protectionSnapshot,
     sourcePackage: params.sourcePackage,
   };
 }
 
+function validateProtectionSnapshot(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+  if (typeof record.hasDocumentProtection !== "boolean") {
+    issues.push({ path: `${path}.hasDocumentProtection`, message: "hasDocumentProtection must be a boolean." });
+  }
+  if (record.editType !== undefined) {
+    expectString(record.editType, `${path}.editType`, issues);
+  }
+  if (typeof record.enforcementActive !== "boolean") {
+    issues.push({ path: `${path}.enforcementActive`, message: "enforcementActive must be a boolean." });
+  }
+  if (!Array.isArray(record.ranges)) {
+    issues.push({ path: `${path}.ranges`, message: "ranges must be an array." });
+  } else {
+    record.ranges.forEach((range, index) => validateProtectionRange(range, `${path}.ranges[${index}]`, issues));
+  }
+  if (!Number.isInteger(record.enforcedRangeCount)) {
+    issues.push({ path: `${path}.enforcedRangeCount`, message: "enforcedRangeCount must be an integer." });
+  }
+  if (!Number.isInteger(record.preservedRangeCount)) {
+    issues.push({ path: `${path}.preservedRangeCount`, message: "preservedRangeCount must be an integer." });
+  }
+}
+
+function validateProtectionRange(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+  expectString(record.rangeId, `${path}.rangeId`, issues);
+  if (record.start !== undefined && !Number.isInteger(record.start)) {
+    issues.push({ path: `${path}.start`, message: "start must be an integer." });
+  }
+  if (record.end !== undefined && !Number.isInteger(record.end)) {
+    issues.push({ path: `${path}.end`, message: "end must be an integer." });
+  }
+  if (record.editorGroup !== undefined) {
+    expectString(record.editorGroup, `${path}.editorGroup`, issues);
+  }
+  if (record.editor !== undefined) {
+    expectString(record.editor, `${path}.editor`, issues);
+  }
+  if (typeof record.enforced !== "boolean") {
+    issues.push({ path: `${path}.enforced`, message: "enforced must be a boolean." });
+  }
+  expectString(record.enforcementReason, `${path}.enforcementReason`, issues);
+}
+
 export function projectAnchorToSnapshot(
   anchor: Record<string, unknown>,
 ): Record<string, unknown> {

package/src/review/store/revision-store.ts

@@ -44,6 +44,8 @@ export interface RevisionSidebarEntry {
   canAccept: boolean;
   canReject: boolean;
   preserveOnlyReason?: string;
+  linkedMoveRevisionId?: string;
+  moveDirection?: "from" | "to";
 }
 
 export interface RevisionSidebarProjection {
@@ -212,6 +214,8 @@ function toSidebarEntry(revision: RevisionRecord): RevisionSidebarEntry {
   const anchorSummary = summarizeRevisionAnchor(revision.anchor);
   const actionability = getRevisionActionability(revision);
 
+  const moveData = revision.metadata.moveData;
+
   return {
     revisionId: revision.revisionId,
     kind: revision.kind,
@@ -228,6 +232,8 @@ function toSidebarEntry(revision: RevisionRecord): RevisionSidebarEntry {
     canAccept: isRevisionActionable(revision),
     canReject: isRevisionActionable(revision),
     preserveOnlyReason: revision.metadata.preserveOnlyReason,
+    linkedMoveRevisionId: moveData?.linkedRevisionId,
+    moveDirection: moveData?.direction,
   };
 }
 

package/src/review/store/revision-types.ts

@@ -28,6 +28,7 @@ export interface PropertyChangeData {
 export interface MoveData {
   moveId: string;
   direction: "from" | "to";
+  linkedRevisionId?: string;
 }
 
 export interface RevisionMetadataEnvelope {