@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -42,9 +42,11 @@ import {
   createCommandBridgePlugins,
   type CommandBridgeCallbacks,
 } from "./pm-command-bridge";
-import { createCollabPlugins } from "./pm-collab-plugins";
-import { prosemirrorToYXmlFragment } from "y-prosemirror";
 import { buildDecorations } from "./pm-decorations";
+import { buildPageBreakDecorations } from "./pm-page-break-decorations";
+import { DecorationSet } from "prosemirror-view";
+import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+import { buildPagePreviewMaps } from "../../runtime/layout/resolve-page-previews";
 import { createContextualInteractionPlugin } from "./pm-contextual-ui";
 import {
   finishPerfProbe,
@@ -65,6 +67,7 @@ import {
   performSearch,
   searchPluginKey,
 } from "./search-plugin";
+import { createRemoteCursorPlugin } from "./remote-cursor-plugin.ts";
 import {
   createSurfaceDecorationKey,
   createSurfaceDocumentBuildKey,
@@ -73,12 +76,90 @@ import { tableNodeViews } from "./tw-table-node-view";
 import type { SelectionToolbarAnchor } from "../../ui/headless/selection-toolbar-model";
 import type { MediaPreviewDescriptor } from "./pm-state-from-snapshot";
 
+/**
+ * Build page-break widget decorations from the layout facet's current page
+ * graph. Returns `[]` when the facet is unavailable, the active story is
+ * not the main body, or there is only one page.
+ *
+ * The widget DOM renders the full inter-page chrome (footer band of prev
+ * page, visible gap, header band of next page) INLINE in the PM flow.
+ * Because it lives inside the flow, no absolute-positioned overlay is
+ * required — PM paints the chrome at exactly the right Y coordinate
+ * between adjacent blocks.
+ */
+function buildPageBreakDecorationsFromProps(
+  facet: WordReviewEditorLayoutFacet | undefined,
+  isMainStory: boolean,
+  positionMap: PositionMap,
+  posture: "canvas" | "page",
+  canonicalDocument: import("../../core/state/editor-state.ts").CanonicalDocumentEnvelope,
+  dimensions: {
+    headerBandPx?: number;
+    footerBandPx?: number;
+    interGapPx?: number;
+  } = {},
+): ReturnType<typeof buildPageBreakDecorations> {
+  if (!facet || !isMainStory) return [];
+  if (typeof facet.getRenderFrame !== "function") return [];
+  const frame = facet.getRenderFrame();
+  if (!frame || frame.pages.length < 2) return [];
+  const fakeGraph = {
+    revision: frame.revision,
+    contentPageCount: frame.pages.filter((p) => !p.page.isBlankFiller).length,
+    pages: frame.pages.map((p) => ({
+      pageId: p.page.pageId,
+      pageIndex: p.page.pageIndex,
+      startOffset: p.page.startOffset,
+      isBlankFiller: p.page.isBlankFiller,
+      stories: {
+        displayPageNumber: p.page.stories.displayPageNumber,
+        header: p.page.stories.header,
+        footer: p.page.stories.footer,
+      },
+    })),
+  };
+
+  // Build per-page header/footer preview maps so the bands show live
+  // content (with PAGE/NUMPAGES resolved) instead of generic labels.
+  // We pass a graph-shape compatible adapter — `buildPagePreviewMaps`
+  // reads only `pages[].pageId / stories / isBlankFiller`, which the
+  // render-frame projection above already provides.
+  const subParts = canonicalDocument.subParts;
+  const previews =
+    subParts && (subParts.headers?.length || subParts.footers?.length)
+      ? buildPagePreviewMaps(fakeGraph as never, {
+          headers: subParts.headers,
+          footers: subParts.footers,
+        })
+      : undefined;
+
+  return buildPageBreakDecorations({
+    graph: fakeGraph as never,
+    posture,
+    headerBandPx: dimensions.headerBandPx,
+    footerBandPx: dimensions.footerBandPx,
+    interGapPx: dimensions.interGapPx,
+    runtimeToPmOffset: (offset) => positionMap.runtimeToPm(offset),
+    headerPreviewByPageId: previews?.headerPreviewByPageId,
+    footerPreviewByPageId: previews?.footerPreviewByPageId,
+  });
+}
+
+function extractDecorations(
+  set: DecorationSet,
+  _doc: unknown,
+): ReturnType<typeof buildPageBreakDecorations> {
+  // PM's DecorationSet doesn't expose its decorations directly; `find` with
+  // no range returns every decoration. This is the standard pattern when we
+  // need to merge sets.
+  return set.find() as unknown as ReturnType<typeof buildPageBreakDecorations>;
+}
+
 /**
  * Same props interface as the legacy TwEditorSurface — drop-in replacement.
  */
 export interface TwProseMirrorSurfaceProps {
   currentUser: EditorUser;
-  ydoc?: import("yjs").Doc;
   awareness?: import("y-protocols/awareness").Awareness;
   snapshot: RuntimeRenderSnapshot;
   canonicalDocument: CanonicalDocumentEnvelope;
@@ -100,6 +181,8 @@ export interface TwProseMirrorSurfaceProps {
   onDeleteForward?: () => void;
   onInsertTab?: () => void;
   onOutdentTab?: () => void;
+  onListIndent?: () => void;
+  onListOutdent?: () => void;
   onInsertHardBreak?: () => void;
   onSplitParagraph?: () => void;
   onUndo?: () => void;
@@ -125,6 +208,31 @@ export interface TwProseMirrorSurfaceProps {
   dispatchRuntimeCommand?: (
     command: import("./fast-text-edit-lane").LaneRuntimeCommand,
   ) => import("../../api/public-types").TextCommandAck;
+  /**
+   * Optional layout facet. When supplied and the active story is `main`,
+   * the surface injects widget decorations at every page boundary.  The
+   * widget DOM renders full inter-page chrome (page-N footer band +
+   * visible gap + page-N+1 header band) INLINE, so chrome stays aligned
+   * with PM content without any absolute overlay.
+   */
+  layoutFacet?: WordReviewEditorLayoutFacet;
+  /** Height in px of each page's header band. Default 32. */
+  pageChromeHeaderBandPx?: number;
+  /** Height in px of each page's footer band. Default 32. */
+  pageChromeFooterBandPx?: number;
+  /** Visible vertical gap between adjacent pages. Default 24 for page mode. */
+  pageChromeInterGapPx?: number;
+  /**
+   * Revision counter; incremented by the host to trigger a decoration
+   * rebuild when the render frame changes (zoom, incremental relayout).
+   */
+  pageBreakRevision?: number;
+  /**
+   * Called when the user double-clicks a per-page header band.
+   * Receives the pageIndex of the band the user clicked.
+   */
+  onOpenHeaderStoryForPage?: (pageIndex: number) => void;
+  onOpenFooterStoryForPage?: (pageIndex: number) => void;
 }
 
 export interface TwProseMirrorSurfaceRef {
@@ -162,6 +270,10 @@ export const TwProseMirrorSurface = forwardRef<
   );
 
   const mountRef = useRef<HTMLDivElement>(null);
+  const openHeaderForPageRef = useRef(props.onOpenHeaderStoryForPage);
+  const openFooterForPageRef = useRef(props.onOpenFooterStoryForPage);
+  openHeaderForPageRef.current = props.onOpenHeaderStoryForPage;
+  openFooterForPageRef.current = props.onOpenFooterStoryForPage;
   const viewRef = useRef<EditorView | null>(null);
   const positionMapRef = useRef<PositionMap | null>(null);
   const callbacksRef = useRef<CommandBridgeCallbacks | null>(null);
@@ -202,6 +314,8 @@ export const TwProseMirrorSurface = forwardRef<
     onInsertHardBreak: () => props.onInsertHardBreak?.(),
     onInsertTab: () => props.onInsertTab?.(),
     onOutdentTab: () => props.onOutdentTab?.(),
+    onListIndent: () => props.onListIndent?.(),
+    onListOutdent: () => props.onListOutdent?.(),
     onUndo: () => props.onUndo?.(),
     onRedo: () => props.onRedo?.(),
     onBlockedInput: (command, message) => {
@@ -276,8 +390,6 @@ export const TwProseMirrorSurface = forwardRef<
     ],
   );
 
-  const isCollabMode = Boolean(props.ydoc);
-
   // Create PM plugins (stable across renders — callbacks accessed via ref)
   const plugins = useMemo(() => {
     const selectionCallbacks = {
@@ -291,73 +403,79 @@ export const TwProseMirrorSurface = forwardRef<
       isPredicted: (opId) => sessionRef.current?.isPredicted(opId) ?? false,
     });
 
-    const corePlugins = props.ydoc
-      ? createCollabPlugins({
-          ydoc: props.ydoc,
-          awareness: props.awareness,
-          selectionCallbacks,
-        })
-      : createCommandBridgePlugins({
-          ...selectionCallbacks,
-          gate,
-          onInsertText: (text) => {
-            if (laneRef.current) {
-              laneRef.current.onInsertText(text);
-            } else {
-              callbacksRef.current?.onInsertText(text);
-            }
-          },
-          onDeleteBackward: () => {
-            if (laneRef.current) {
-              laneRef.current.onDeleteBackward();
-            } else {
-              callbacksRef.current?.onDeleteBackward();
-            }
-          },
-          onDeleteForward: () => {
-            if (laneRef.current) {
-              laneRef.current.onDeleteForward();
-            } else {
-              callbacksRef.current?.onDeleteForward();
-            }
-          },
-          onSplitParagraph: () => {
-            if (laneRef.current) {
-              laneRef.current.onSplitParagraph();
-            } else {
-              callbacksRef.current?.onSplitParagraph();
-            }
-          },
-          onInsertHardBreak: () => {
-            if (laneRef.current) {
-              laneRef.current.onInsertHardBreak();
-            } else {
-              callbacksRef.current?.onInsertHardBreak();
-            }
-          },
-          onInsertTab: () => callbacksRef.current?.onInsertTab(),
-          onOutdentTab: () => callbacksRef.current?.onOutdentTab?.(),
-          onUndo: () => callbacksRef.current?.onUndo(),
-          onRedo: () => callbacksRef.current?.onRedo(),
-          onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
-          onCompositionChange: (composing) => {
-            sessionRef.current?.setComposing(composing);
-          },
-        });
+    const corePlugins = createCommandBridgePlugins({
+      ...selectionCallbacks,
+      gate,
+      onInsertText: (text) => {
+        if (laneRef.current) {
+          laneRef.current.onInsertText(text);
+        } else {
+          callbacksRef.current?.onInsertText(text);
+        }
+      },
+      onDeleteBackward: () => {
+        if (laneRef.current) {
+          laneRef.current.onDeleteBackward();
+        } else {
+          callbacksRef.current?.onDeleteBackward();
+        }
+      },
+      onDeleteForward: () => {
+        if (laneRef.current) {
+          laneRef.current.onDeleteForward();
+        } else {
+          callbacksRef.current?.onDeleteForward();
+        }
+      },
+      onSplitParagraph: () => {
+        if (laneRef.current) {
+          laneRef.current.onSplitParagraph();
+        } else {
+          callbacksRef.current?.onSplitParagraph();
+        }
+      },
+      onInsertHardBreak: () => {
+        if (laneRef.current) {
+          laneRef.current.onInsertHardBreak();
+        } else {
+          callbacksRef.current?.onInsertHardBreak();
+        }
+      },
+      onInsertTab: () => callbacksRef.current?.onInsertTab(),
+      onOutdentTab: () => callbacksRef.current?.onOutdentTab?.(),
+      onListIndent: () => callbacksRef.current?.onListIndent?.(),
+      onListOutdent: () => callbacksRef.current?.onListOutdent?.(),
+      onUndo: () => callbacksRef.current?.onUndo(),
+      onRedo: () => callbacksRef.current?.onRedo(),
+      onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
+      onCompositionChange: (composing) => {
+        sessionRef.current?.setComposing(composing);
+      },
+    });
 
     return [
       ...corePlugins,
+      ...(props.awareness
+        ? [
+            createRemoteCursorPlugin({
+              awareness: props.awareness,
+              localClientId: props.awareness.clientID,
+              getPositionMap: () => positionMapRef.current,
+              getActiveStory: () => snapshotRef.current.activeStory,
+            }),
+          ]
+        : []),
       createContextualInteractionPlugin({
         onCommentActivated: (commentId) => props.onCommentActivated?.(commentId),
         onRevisionActivated: (revisionId) => props.onRevisionActivated?.(revisionId),
       }),
       createSearchPlugin(),
     ];
-  }, [props.onCommentActivated, props.onRevisionActivated, props.ydoc, props.awareness]);
+  }, [props.awareness, props.onCommentActivated, props.onRevisionActivated]);
 
   const applyDecorationProps = useCallback(
     (view: EditorView, positionMap: PositionMap): void => {
-      const decorations = buildDecorations(
+      const baseDecorations = buildDecorations(
         view.state.doc,
         positionMap,
         commentModel,
@@ -374,6 +492,24 @@ export const TwProseMirrorSurface = forwardRef<
         props.activeWorkflowScopeIds,
         props.workflowMetadata,
       );
+      const pageBreakDecos = buildPageBreakDecorationsFromProps(
+        props.layoutFacet,
+        snapshot.activeStory.kind === "main",
+        positionMap,
+        props.isPageWorkspace ? "page" : "canvas",
+        props.canonicalDocument,
+        {
+          headerBandPx: props.pageChromeHeaderBandPx,
+          footerBandPx: props.pageChromeFooterBandPx,
+          interGapPx: props.pageChromeInterGapPx,
+        },
+      );
+      const decorations = pageBreakDecos.length > 0
+        ? DecorationSet.create(view.state.doc, [
+            ...pageBreakDecos,
+            ...extractDecorations(baseDecorations, view.state.doc),
+          ])
+        : baseDecorations;
       view.setProps({
         editable: () => canEdit,
         decorations: () => decorations,
@@ -414,6 +550,33 @@ export const TwProseMirrorSurface = forwardRef<
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Listen for the custom events dispatched by the page-chrome widget
+  // decorations (`wre-open-header-story-for-page` /
+  // `wre-open-footer-story-for-page`).  The widget DOM lives inside the
+  // mount element, so bubbling events reach us here.
+  useEffect(() => {
+    const mount = mountRef.current;
+    if (!mount) return;
+    const handleHeader = (event: Event) => {
+      const detail = (event as CustomEvent<{ pageIndex: number }>).detail;
+      if (typeof detail?.pageIndex === "number") {
+        openHeaderForPageRef.current?.(detail.pageIndex);
+      }
+    };
+    const handleFooter = (event: Event) => {
+      const detail = (event as CustomEvent<{ pageIndex: number }>).detail;
+      if (typeof detail?.pageIndex === "number") {
+        openFooterForPageRef.current?.(detail.pageIndex);
+      }
+    };
+    mount.addEventListener("wre-open-header-story-for-page", handleHeader);
+    mount.addEventListener("wre-open-footer-story-for-page", handleFooter);
+    return () => {
+      mount.removeEventListener("wre-open-header-story-for-page", handleHeader);
+      mount.removeEventListener("wre-open-footer-story-for-page", handleFooter);
+    };
+  }, []);
+
   // Build the FastTextEditLane whenever `dispatchRuntimeCommand` changes.
   // The lane is consulted via `laneRef.current` inside PM plugin callbacks,
   // so the plugins memo does not need to depend on this effect.
@@ -469,11 +632,6 @@ export const TwProseMirrorSurface = forwardRef<
   useEffect(() => {
     if (!mountRef.current || !surface) return;
 
-    // Collab mode: y-prosemirror owns the doc after initial mount
-    if (isCollabMode && viewRef.current) {
-      return;
-    }
-
     if (viewRef.current && documentBuildKeyRef.current === documentBuildKey) {
       return;
     }
@@ -543,15 +701,6 @@ export const TwProseMirrorSurface = forwardRef<
       });
       viewRef.current = view;
       recordPerfSample("pm.mount");
-
-      if (isCollabMode && props.ydoc) {
-        const yXmlFragment = props.ydoc.getXmlFragment("prosemirror");
-        if (yXmlFragment.length === 0) {
-          props.ydoc.transact(() => {
-            prosemirrorToYXmlFragment(view.state.doc, yXmlFragment);
-          });
-        }
-      }
     } else {
       suppressSelectionEchoRef.current = true;
       viewRef.current.updateState(state);
@@ -575,12 +724,10 @@ export const TwProseMirrorSurface = forwardRef<
   }, [
     applyDecorationProps,
     documentBuildKey,
-    isCollabMode,
     surface,
     snapshot.selection,
     plugins,
     props.mediaPreviews,
-    props.ydoc,
   ]);
 
   // Update decorations and editability without rebuilding the PM document.
@@ -613,7 +760,6 @@ export const TwProseMirrorSurface = forwardRef<
   ]);
 
   useEffect(() => {
-    if (isCollabMode) return;
     const view = viewRef.current;
     const positionMap = positionMapRef.current;
     if (!view || !surface || !positionMap) {
@@ -649,7 +795,7 @@ export const TwProseMirrorSurface = forwardRef<
     queueMicrotask(() => {
       suppressSelectionEchoRef.current = false;
     });
-  }, [isCollabMode, snapshot.selection, surface]);
+  }, [snapshot.selection, surface]);
 
   useEffect(() => {
     if (!pendingSelectionProbeRef.current) {

package/src/ui-tailwind/editor-surface/tw-table-bands.css

@@ -0,0 +1,61 @@
+/*
+ * R2c: table-style conditional-region band classes.
+ *
+ * These classes are applied to <td> elements by TwTableNodeView.applyCellAttrs
+ * whenever the surface snapshot's SurfaceTableCellSnapshot.bandClasses is set.
+ * The class set comes from `resolveTableStyleResolution().cells[*].activeConditionalRegions`
+ * mapped through the `band-<region>` convention.
+ *
+ * Band styling uses @apply against theme variables so light↔dark toggle repaints
+ * cell colors via the cascade instead of forcing a surface rebuild.
+ *
+ * Consumer integration: import this stylesheet alongside editor-theme.css in
+ * the app's build pipeline, e.g.:
+ *   @import "@beyondwork/docx-react-component/ui-tailwind/editor-surface/tw-table-bands.css";
+ *
+ * Direct overrides: when a cell has a direct `shading.fill`, applyCellAttrs
+ * writes an inline `background-color` that wins over the band default.
+ */
+
+.band-firstRow {
+  @apply font-semibold bg-surface-raised;
+}
+
+.band-lastRow {
+  @apply font-semibold bg-surface-raised;
+}
+
+.band-firstColumn {
+  @apply font-semibold;
+}
+
+.band-lastColumn {
+  @apply font-semibold;
+}
+
+.band-band1Horz {
+  @apply bg-surface-secondary;
+}
+
+.band-band2Horz {
+  @apply bg-surface-tertiary;
+}
+
+.band-band1Vert {
+  @apply bg-surface-secondary/50;
+}
+
+.band-band2Vert {
+  @apply bg-surface-tertiary/50;
+}
+
+/* Corner cells — reserved for table styles that define them explicitly. */
+.band-nwCell { /* top-left */ }
+.band-neCell { /* top-right */ }
+.band-swCell { /* bottom-left */ }
+.band-seCell { /* bottom-right */ }
+
+/* R3e: virtual header repeated on continuation pages. Visual parity with firstRow. */
+.band-virtual-header {
+  @apply font-semibold bg-surface-raised;
+}

package/src/ui-tailwind/editor-surface/tw-table-node-view.tsx

@@ -11,6 +11,11 @@
 import type { Node as PMNode } from "prosemirror-model";
 import type { NodeViewConstructor, ViewMutationRecord } from "prosemirror-view";
 
+// R2c: band class styles live in ./tw-table-bands.module.css. Consumers import
+// that stylesheet through their build pipeline (same pattern as editor-theme.css).
+// Importing .css directly from a .tsx breaks the node:test runner and the npm
+// library build — keep CSS as a consumer-side concern.
+
 const TABLE_LAYOUT_SYNC_EVENT = "pm-table-layout-sync";
 
 interface TableCellLayout {
@@ -318,6 +323,7 @@ function applyCellAttrs(cell: HTMLTableCellElement, node: PMNode, isHeader: bool
   const borderRight = node.attrs.borderRight as string | null | undefined;
   const borderBottom = node.attrs.borderBottom as string | null | undefined;
   const borderLeft = node.attrs.borderLeft as string | null | undefined;
+  const bandClasses = node.attrs.bandClasses as string | null | undefined;
 
   if (backgroundColor) cell.setAttribute("data-cell-background", backgroundColor);
   else cell.removeAttribute("data-cell-background");
@@ -332,6 +338,19 @@ function applyCellAttrs(cell: HTMLTableCellElement, node: PMNode, isHeader: bool
   if (borderLeft) cell.setAttribute("data-border-left", borderLeft);
   else cell.removeAttribute("data-border-left");
 
+  // R2b: band classes come from the resolved style cascade. They layer on top
+  // of the base Tailwind classes so theme vars (bg-surface-*, text-secondary,
+  // etc.) repaint on light↔dark toggle without a surface rebuild. Direct
+  // `backgroundColor` overrides still win via the inline-style block below.
+  if (bandClasses) {
+    cell.setAttribute("data-band-classes", bandClasses);
+    for (const token of bandClasses.split(/\s+/).filter(Boolean)) {
+      cell.classList.add(token);
+    }
+  } else {
+    cell.removeAttribute("data-band-classes");
+  }
+
   cell.style.backgroundColor = backgroundColor ?? "";
   cell.style.verticalAlign = verticalAlign === "center" ? "middle" : (verticalAlign ?? "");
   cell.style.borderTop = borderTop ?? "";

package/src/ui-tailwind/index.ts

@@ -47,17 +47,18 @@ export { TwStatusBar } from "./status/tw-status-bar";
 // Chrome
 export { TwAlertBanner } from "./chrome/tw-alert-banner";
 export { TwSelectionToolbar } from "./chrome/tw-selection-toolbar";
+export {
+  TwModeDock,
+  type TwModeDockAction,
+  type TwModeDockProps,
+} from "./chrome/tw-mode-dock";
 
-// Chrome overlay plane (R3a — scope rail, workspace dock)
+// Chrome overlay plane (R3a — scope rail layer)
 export {
   TwChromeOverlay,
   type TwChromeOverlayProps,
   TwScopeRailLayer,
   type TwScopeRailLayerProps,
-  TwWorkspaceViewSwitcher,
-  type TwWorkspaceViewSwitcherProps,
-  type WorkspaceView,
-  type WorkspaceViewAction,
 } from "./chrome-overlay";
 
 // Session capabilities