@beyondwork/docx-react-component 1.0.17 → 1.0.19

package/src/api/public-types.ts

@@ -6,12 +6,25 @@ export type ExternalDocumentSource =
       bytes: Uint8Array | ArrayBuffer;
       sourceLabel?: string;
     }
+  | {
+      kind: "session";
+      sessionState: EditorSessionState;
+      sourceLabel?: string;
+    }
   | {
       kind: "snapshot";
       snapshot: PersistedEditorSnapshot;
       sourceLabel?: string;
     };
 
+export type LoadSourcePolicy = "prefer-saved-state" | "prefer-source-package";
+
+export interface LoadRequest {
+  documentId: string;
+  loadRevision?: string;
+  loadSourcePolicy?: LoadSourcePolicy;
+}
+
 export interface EditorUser {
   userId: string;
   displayName: string;
@@ -43,11 +56,129 @@ export type EditorAnchorProjection =
       reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
     };
 
+export type EditorStoryTarget =
+  | { kind: "main" }
+  | {
+      kind: "header";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | {
+      kind: "footer";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | { kind: "footnote"; noteId: string }
+  | { kind: "endnote"; noteId: string };
+
 export interface SelectionSnapshot {
   anchor: number;
   head: number;
   isCollapsed: boolean;
   activeRange: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+}
+
+export interface PageLayoutSnapshot {
+  sectionIndex: number;
+  sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
+  pageWidth: number;
+  pageHeight: number;
+  marginTop: number;
+  marginBottom: number;
+  marginLeft: number;
+  marginRight: number;
+  headerMargin: number;
+  footerMargin: number;
+  gutter: number;
+  orientation: "portrait" | "landscape";
+  columns: number;
+  differentFirstPage: boolean;
+  differentOddEvenPages: boolean;
+  pageNumbering?: {
+    format?: string;
+    start?: number;
+    chapterStyle?: string;
+    chapterSeparator?: string;
+  };
+  lineNumbering?: {
+    countBy?: number;
+    start?: number;
+    distance?: number;
+    restart?: "newPage" | "newSection" | "continuous";
+  };
+  pageBorders?: {
+    top?: { value?: string; size?: number; space?: number; color?: string };
+    left?: { value?: string; size?: number; space?: number; color?: string };
+    bottom?: { value?: string; size?: number; space?: number; color?: string };
+    right?: { value?: string; size?: number; space?: number; color?: string };
+    offsetFrom?: "page" | "text";
+    display?: "allPages" | "firstPage" | "notFirstPage";
+    zOrder?: "front" | "back";
+  };
+  documentGrid?: {
+    type?: "default" | "lines" | "linesAndChars" | "snapToChars";
+    linePitch?: number;
+    charSpace?: number;
+  };
+  columnDefinitions: Array<{ width: number; space?: number }>;
+  equalWidthColumns: boolean;
+  columnSeparator: boolean;
+  headerVariants: Array<{ variant: "default" | "first" | "even"; relationshipId: string }>;
+  footerVariants: Array<{ variant: "default" | "first" | "even"; relationshipId: string }>;
+}
+
+export type WorkspaceMode = "canvas" | "page";
+
+export type ZoomLevel = "pageWidth" | "onePage" | number;
+
+export type SectionBreakType =
+  | "nextPage"
+  | "continuous"
+  | "evenPage"
+  | "oddPage"
+  | "nextColumn";
+
+export interface SectionLayoutPatch {
+  pageSize?: Partial<{
+    width: number;
+    height: number;
+    orientation: "portrait" | "landscape";
+  }>;
+  pageMargins?: Partial<{
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    header: number;
+    footer: number;
+    gutter: number;
+  }>;
+  columns?: Partial<{
+    count: number;
+    space: number;
+    equalWidth: boolean;
+    columns: Array<{ width: number; space?: number }>;
+    separator: boolean;
+  }>;
+  titlePage?: boolean;
+  sectionType?: SectionBreakType;
+}
+
+export interface SectionPageNumberingPatch {
+  format?: string | null;
+  start?: number | null;
+  chapterStyle?: string | null;
+  chapterSeparator?: string | null;
+}
+
+export interface HeaderFooterLinkPatch {
+  kind: "header" | "footer";
+  variant: "default" | "first" | "even";
+  linkToPrevious: boolean;
+  relationshipId?: string | null;
 }
 
 export interface DocumentStats {
@@ -144,6 +275,7 @@ export interface FormattingStateSnapshot {
   textColor?: string;
   highlightColor?: string | null;
   alignment?: FormattingAlignment;
+  paragraphStyleId?: string;
   breadcrumb: FormattingBreadcrumbItem[];
 }
 
@@ -158,6 +290,79 @@ export interface SearchResultSnapshot {
   anchor: EditorAnchorProjection;
   excerpt: string;
   isActive: boolean;
+  storyTarget?: EditorStoryTarget;
+  sectionIndex?: number;
+  pageIndex?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Document Navigation Model (Wave 37)
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime-owned snapshot of the document's page stack, heading outline, and
+ * navigation context.  Derived from canonical document state and section
+ * properties — never from DOM scroll position or CSS layout.
+ */
+export interface DocumentNavigationSnapshot {
+  /** Total estimated page count across all sections. */
+  pageCount: number;
+  /** Ordered page descriptors, one per logical page. */
+  pages: DocumentPageSnapshot[];
+  /** Ordered heading outline extracted from paragraph styles. */
+  headings: DocumentHeadingSnapshot[];
+  /** Index of the page containing the current selection head. */
+  activePageIndex: number;
+  /** Section index containing the current selection head. */
+  activeSectionIndex: number;
+}
+
+/** Runtime-derived descriptor for a single logical page. */
+export interface DocumentPageSnapshot {
+  /** Zero-based page index within the whole document. */
+  pageIndex: number;
+  /** Section that owns this page (zero-based). */
+  sectionIndex: number;
+  /** Zero-based page index within its owning section. */
+  pageInSection: number;
+  /** Estimated character offset where the page begins in the main story. */
+  startOffset: number;
+  /** Estimated character offset where the page ends in the main story. */
+  endOffset: number;
+  /** Page layout properties inherited from the section. */
+  layout: PageLayoutSnapshot;
+}
+
+/** A heading entry in the document outline. */
+export interface DocumentHeadingSnapshot {
+  /** Stable identifier for the heading (derived from block position). */
+  headingId: string;
+  /** Outline level (1 = Heading 1, 2 = Heading 2, etc.). */
+  level: number;
+  /** Plain-text content of the heading paragraph. */
+  text: string;
+  /** Character offset of the heading in the main story. */
+  offset: number;
+  /** Zero-based page index where the heading lives. */
+  pageIndex: number;
+  /** Section index where the heading lives. */
+  sectionIndex: number;
+}
+
+export interface StyleCatalogEntrySnapshot {
+  styleId: string;
+  displayName: string;
+  kind: "paragraph" | "character" | "table";
+  isDefault: boolean;
+  basedOn?: string;
+  nextStyle?: string;
+}
+
+export interface StyleCatalogSnapshot {
+  paragraphs: StyleCatalogEntrySnapshot[];
+  characters: StyleCatalogEntrySnapshot[];
+  tables: StyleCatalogEntrySnapshot[];
+  fromPackage: boolean;
 }
 
 export interface InsertTableOptions {
@@ -234,7 +439,17 @@ export type SurfaceInlineSegment =
       warningId: string;
       label: string;
       detail: string;
+      presentation?: "inline-chip" | "quiet-marker";
       state: "locked-preserve-only";
+    }
+  | {
+      segmentId: string;
+      kind: "note_ref";
+      from: number;
+      to: number;
+      noteKind: "footnote" | "endnote";
+      noteId: string;
+      label: string;
     };
 
 export interface SurfaceTableCellSnapshot {
@@ -243,11 +458,19 @@ export interface SurfaceTableCellSnapshot {
   colspan: number;
   rowspan: number;
   backgroundColor?: string | null;
+  verticalAlign?: "top" | "center" | "bottom" | null;
+  borderTop?: string | null;
+  borderRight?: string | null;
+  borderBottom?: string | null;
+  borderLeft?: string | null;
   content: SurfaceBlockSnapshot[];
 }
 
 export interface SurfaceTableRowSnapshot {
   cells: SurfaceTableCellSnapshot[];
+  height?: number;
+  heightRule?: "auto" | "atLeast" | "exact";
+  isHeader?: boolean;
 }
 
 export type SurfaceBlockSnapshot =
@@ -261,6 +484,8 @@ export type SurfaceBlockSnapshot =
         numberingInstanceId: string;
         level: number;
       };
+      numberingPrefix?: string;
+      numberingSuffix?: "tab" | "space" | "nothing";
       alignment?: "left" | "center" | "right" | "both" | "distribute";
       spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
       indentation?: { left?: number; right?: number; firstLine?: number; hanging?: number };
@@ -272,6 +497,7 @@ export type SurfaceBlockSnapshot =
       pageBreakBefore?: boolean;
       outlineLevel?: number;
       bidi?: boolean;
+      suppressLineNumbers?: boolean;
       segments: SurfaceInlineSegment[];
     }
   | {
@@ -281,6 +507,15 @@ export type SurfaceBlockSnapshot =
       to: number;
       styleId?: string;
       gridColumns: number[];
+      alignment?: "left" | "center" | "right";
+      tblLook?: {
+        firstRow?: boolean;
+        lastRow?: boolean;
+        firstColumn?: boolean;
+        lastColumn?: boolean;
+        noHBand?: boolean;
+        noVBand?: boolean;
+      };
       rows: SurfaceTableRowSnapshot[];
     }
   | {
@@ -292,6 +527,11 @@ export type SurfaceBlockSnapshot =
       alias?: string;
       tag?: string;
       lock?: string;
+      checkboxChecked?: boolean;
+      dateValue?: string;
+      dropdownItems?: Array<{ displayText?: string; value: string }>;
+      comboBoxItems?: Array<{ displayText?: string; value: string }>;
+      showingPlcHdr?: boolean;
       children: SurfaceBlockSnapshot[];
     }
   | {
@@ -306,11 +546,19 @@ export type SurfaceBlockSnapshot =
       state: "locked-preserve-only";
     };
 
+export interface SecondaryStorySurface {
+  target: EditorStoryTarget;
+  label: string;
+  storySize: number;
+  blocks: SurfaceBlockSnapshot[];
+}
+
 export interface EditorSurfaceSnapshot {
   storySize: number;
   plainText: string;
   blocks: SurfaceBlockSnapshot[];
   lockedFragmentIds: string[];
+  secondaryStories: SecondaryStorySurface[];
 }
 
 export type EditorWarningCode =
@@ -354,7 +602,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>;
 }
 
@@ -389,6 +637,52 @@ export interface CompatibilityPanelSnapshot {
   featureEntries: CompatibilityFeatureEntry[];
 }
 
+export type ViewMode = "editing" | "review" | "view";
+
+export type CaretAffinity = "forward" | "backward" | "none";
+
+export interface ActiveListContext {
+  numberingInstanceId: string;
+  level: number;
+  isOrdered: boolean;
+  markerText?: string;
+}
+
+export interface ActiveNoteContext {
+  noteKind: "footnote" | "endnote";
+  noteId: string;
+  referencePosition: number;
+}
+
+export interface PageRegionHitTest {
+  region: "body" | "header" | "footer" | "margin" | "gutter";
+  sectionIndex: number;
+  columnIndex: number;
+}
+
+export interface LayoutMeasurement {
+  pageRegions: PageRegionHitTest[];
+  caretAffinity: CaretAffinity;
+  tabStops: Array<{ pos: number; val?: string; leader?: string }>;
+  listMarkerLane?: { indent: number; markerWidth: number };
+  objectFrame?: { kind: "image" | "textbox" | "shape"; anchorPos: number; display: "inline" | "floating" };
+}
+
+export interface EditorViewStateSnapshot {
+  viewMode: ViewMode;
+  workspaceMode: WorkspaceMode;
+  zoomLevel: ZoomLevel;
+  activeStory: EditorStoryTarget;
+  selection: SelectionSnapshot;
+  caretAffinity: CaretAffinity;
+  activeListContext: ActiveListContext | null;
+  activeNoteContext: ActiveNoteContext | null;
+  activePageRegion: PageRegionHitTest | null;
+  activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
+  measurement: LayoutMeasurement;
+  isFocused: boolean;
+}
+
 export interface CommandStateSnapshot {
   canUndo: boolean;
   canRedo: boolean;
@@ -404,6 +698,8 @@ export interface RuntimeRenderSnapshot {
   isDirty: boolean;
   readOnly: boolean;
   selection: SelectionSnapshot;
+  activeStory: EditorStoryTarget;
+  pageLayout?: PageLayoutSnapshot;
   documentStats: DocumentStats;
   comments: CommentSidebarSnapshot;
   trackedChanges: TrackedChangesSnapshot;
@@ -414,6 +710,20 @@ export interface RuntimeRenderSnapshot {
   surface?: EditorSurfaceSnapshot;
 }
 
+export interface EditorSessionState {
+  sessionVersion: "editor-session-state/1";
+  schemaVersion: RuntimePersistedEditorSnapshot["schemaVersion"];
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  editorBuild: string;
+  canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+  sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
+}
+
 export interface PersistedEditorSnapshot {
   snapshotVersion: RuntimePersistedEditorSnapshot["snapshotVersion"];
   schemaVersion: RuntimePersistedEditorSnapshot["schemaVersion"];
@@ -440,10 +750,16 @@ export interface ExportDocxOptions {
   reason?: string;
 }
 
+export interface ExportDelivery {
+  mode: "downloaded" | "persisted-by-host" | "exported-bytes-only";
+  savedAt?: string;
+}
+
 export interface ExportResult {
   bytes: Uint8Array;
   mimeType: string;
   fileName: string;
+  delivery: ExportDelivery;
 }
 
 export type AutosaveState =
@@ -462,7 +778,7 @@ export type WordReviewEditorEvent =
       type: "ready";
       documentId: string;
       sessionId: string;
-      source: "docx" | "snapshot" | "datastore" | "canonical";
+      source: "docx" | "session" | "snapshot";
       stats: DocumentStats;
       compatibility: CompatibilityReport;
       comments: CommentSidebarSnapshot;
@@ -499,6 +815,11 @@ export type WordReviewEditorEvent =
       documentId: string;
       changeId: string;
     }
+  | {
+      type: "story_changed";
+      documentId: string;
+      activeStory: EditorStoryTarget;
+    }
   | {
       type: "warning_added";
       documentId: string;
@@ -526,6 +847,13 @@ export type WordReviewEditorEvent =
       snapshot: PersistedEditorSnapshot;
       isAutosave: boolean;
     }
+  | {
+      type: "session_saved";
+      documentId: string;
+      sessionState: EditorSessionState;
+      savedAt: string;
+      isAutosave: boolean;
+    }
   | {
       type: "export_completed";
       documentId: string;
@@ -546,6 +874,16 @@ export interface SaveSnapshotResult {
   savedAt: string;
 }
 
+export interface SaveSessionParams {
+  documentId: string;
+  sessionState: EditorSessionState;
+  isAutosave: boolean;
+}
+
+export interface SaveSessionResult {
+  savedAt: string;
+}
+
 export interface SaveExportParams {
   documentId: string;
   result: ExportResult;
@@ -561,10 +899,17 @@ export interface EditorTelemetryEvent {
   detail?: Record<string, unknown>;
 }
 
+export interface EditorHostAdapter {
+  load?(params: LoadRequest): Promise<LoadResult>;
+  saveSession?(params: SaveSessionParams): Promise<SaveSessionResult>;
+  saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
+  logEvent?(event: EditorTelemetryEvent): void;
+}
+
 export interface EditorDatastoreAdapter {
-  load(params: { documentId: string }): Promise<LoadResult>;
+  load(params: LoadRequest): Promise<LoadResult>;
   saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult>;
-  saveExport(params: SaveExportParams): Promise<SaveExportResult>;
+  saveExport?(params: SaveExportParams): Promise<SaveExportResult>;
   logEvent?(event: EditorTelemetryEvent): void;
 }
 
@@ -585,6 +930,7 @@ export interface WordReviewEditorRef {
   acceptAllChanges(): void;
   rejectAllChanges(): void;
   exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  getSessionState(): EditorSessionState;
   getSnapshot(): PersistedEditorSnapshot;
   getRenderSnapshot(): RuntimeRenderSnapshot;
   getCompatibilityReport(): CompatibilityReport;
@@ -595,6 +941,7 @@ export interface WordReviewEditorRef {
   getTrackedChanges(): TrackedChangesSnapshot;
   isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
+  getStyleCatalog(): StyleCatalogSnapshot;
   replaceText(text: string, target?: EditorAnchorProjection): void;
   toggleBold(): void;
   toggleItalic(): void;
@@ -607,6 +954,8 @@ export interface WordReviewEditorRef {
   setTextColor(color: string | null): void;
   setHighlightColor(color: string | null): void;
   setAlignment(alignment: FormattingAlignment): void;
+  setParagraphStyle(styleId: string | null): void;
+  setTableStyle(styleId: string | null): void;
   indent(): void;
   outdent(): void;
   insertPageBreak(): void;
@@ -627,20 +976,41 @@ export interface WordReviewEditorRef {
   setSelection(selection: SelectionSnapshot | null): void;
   scrollToRevision(revisionId: string): void;
   scrollToComment(commentId: string): void;
+  openStory(target: EditorStoryTarget): void;
+  closeStory(): void;
+  getPageLayoutSnapshot(): PageLayoutSnapshot | null;
+  getDocumentNavigationSnapshot(): DocumentNavigationSnapshot;
+  getViewState(): EditorViewStateSnapshot;
+  setWorkspaceMode(mode: WorkspaceMode): void;
+  setZoom(level: ZoomLevel): void;
+  insertSectionBreak(type: SectionBreakType, options?: { afterSectionIndex?: number }): void;
+  deleteSectionBreak(sectionIndex: number): void;
+  updateSectionLayout(sectionIndex: number, patch: SectionLayoutPatch): void;
+  setSectionPageNumbering(
+    sectionIndex: number,
+    patch: SectionPageNumberingPatch | null,
+  ): void;
+  setHeaderFooterLink(sectionIndex: number, params: HeaderFooterLinkPatch): void;
+  setImageLayout(mediaId: string, dimensions: { widthEmu: number; heightEmu: number }): void;
+  setImageFrame(mediaId: string, offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number }): void;
 }
 
 export interface WordReviewEditorProps {
   documentId: string;
   currentUser: EditorUser;
   initialDocx?: Uint8Array | ArrayBuffer;
+  initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;
   initialSourceLabel?: string;
   externalDocumentRevision?: string;
   externalDocSource?: ExternalDocumentSource;
+  loadRevision?: string;
+  loadSourcePolicy?: LoadSourcePolicy;
   readOnly?: boolean;
   reviewMode?: "editing" | "review";
   markupDisplay?: "clean" | "simple" | "all";
   showReviewPanel?: boolean;
+  hostAdapter?: EditorHostAdapter;
   datastore?: EditorDatastoreAdapter;
   autosave?: AutosaveConfig;
   onEvent?: (event: WordReviewEditorEvent) => void;

package/src/api/session-state.ts

@@ -0,0 +1,58 @@
+import type {
+  EditorSessionState,
+  PersistedEditorSnapshot,
+} from "./public-types.ts";
+
+export const EDITOR_SESSION_STATE_VERSION = "editor-session-state/1" as const;
+
+function cloneStructuredValue<T>(value: T): T {
+  return structuredClone(value);
+}
+
+export function createEditorSessionState(
+  input: Omit<EditorSessionState, "sessionVersion">,
+): EditorSessionState {
+  return cloneStructuredValue({
+    sessionVersion: EDITOR_SESSION_STATE_VERSION,
+    ...input,
+  });
+}
+
+export function editorSessionStateFromPersistedSnapshot(
+  snapshot: PersistedEditorSnapshot,
+): EditorSessionState {
+  return createEditorSessionState({
+    schemaVersion: snapshot.schemaVersion,
+    documentId: snapshot.documentId,
+    docId: snapshot.docId,
+    createdAt: snapshot.createdAt,
+    updatedAt: snapshot.updatedAt,
+    editorBuild: snapshot.editorBuild,
+    canonicalDocument: snapshot.canonicalDocument,
+    compatibility: snapshot.compatibility,
+    warningLog: snapshot.warningLog,
+    sourcePackage: snapshot.sourcePackage,
+  });
+}
+
+export function persistedSnapshotFromEditorSessionState(
+  sessionState: EditorSessionState,
+  options: {
+    savedAt: string;
+  },
+): PersistedEditorSnapshot {
+  return cloneStructuredValue({
+    snapshotVersion: "persisted-editor-snapshot/2",
+    schemaVersion: sessionState.schemaVersion,
+    documentId: sessionState.documentId,
+    docId: sessionState.docId,
+    createdAt: sessionState.createdAt,
+    updatedAt: sessionState.updatedAt,
+    savedAt: options.savedAt,
+    editorBuild: sessionState.editorBuild,
+    canonicalDocument: sessionState.canonicalDocument,
+    compatibility: sessionState.compatibility,
+    warningLog: sessionState.warningLog,
+    sourcePackage: sessionState.sourcePackage,
+  });
+}

package/src/core/commands/formatting-commands.ts

@@ -271,6 +271,7 @@ export function getFormattingStateFromRenderSnapshot(
     alignment: getConsistentValue(paragraphs, (paragraph) =>
       toPublicAlignment(paragraph.alignment),
     ),
+    paragraphStyleId: getConsistentValue(paragraphs, (paragraph) => paragraph.styleId),
     breadcrumb: getSelectionBreadcrumb(surface.blocks, snapshot.selection),
   };
 }