superdoc-dev · chittolinag · May 15, 2026 · May 15, 2026 · May 15, 2026 · luccas-harbour
@@ -1560,6 +1560,8 @@ export type ParagraphAttrs = {
   directionContext?: ParagraphDirectionContext;
   isTocEntry?: boolean;
   tocInstruction?: string;
+  /** Stable id shared by every paragraph in the same TOC (docPartObj uniqueId or parent sdBlockId). */
+  tocId?: string;
   /** Floating alignment for positioned paragraphs (from w:framePr/@w:xAlign). */
   floatAlignment?: 'left' | 'right' | 'center';
   /**

@@ -42,6 +42,12 @@ export const DOM_CLASS_NAMES = {
    */
   SDT_GROUP_HOVER: 'sdt-group-hover',
 
+  /** Paragraph fragment rendered as a Table of Contents entry. */
+  TOC_ENTRY: 'superdoc-toc-entry',
+
+  /** TOC analogue of `SDT_GROUP_HOVER`, applied to every fragment sharing a `data-toc-id`. */
+  TOC_GROUP_HOVER: 'toc-group-hover',
+
   /** Block-level image fragment (ImageBlock). */
   IMAGE_FRAGMENT: 'superdoc-image-fragment',
 

@@ -3093,6 +3093,10 @@ export class DomPainter {
       // Add TOC-specific styling class
       if (isTocEntry) {
         fragmentEl.classList.add('superdoc-toc-entry');
+        const tocId = block.attrs?.tocId;
+        if (typeof tocId === 'string' && tocId.length > 0) {
+          fragmentEl.dataset.tocId = tocId;
+        }
       }
 
       if (paraContinuesFromPrev) {
@@ -7322,8 +7326,7 @@ export class DomPainter {
     wrapper.dataset.layoutEpoch = String(this.layoutEpoch);
     this.applySdtDataset(wrapper, sdt);
 
-    const appearance =
-      sdt.type === 'structuredContent' ? (sdt as { appearance?: string }).appearance : undefined;
+    const appearance = sdt.type === 'structuredContent' ? (sdt as { appearance?: string }).appearance : undefined;
     if (appearance === 'hidden') {
       wrapper.dataset.appearance = 'hidden';
       // No alias label and no chrome: see CSS rule keyed off

@@ -241,6 +241,9 @@ const LINK_AND_TOC_STYLES = `
   color: inherit !important;
   text-decoration: none !important;
   cursor: default;
+  /* Disable native link drag so our pointer loop can run text-selection. */
+  -webkit-user-drag: none;
+  user-drag: none;
 }
 
 .superdoc-toc-entry .superdoc-link:hover {
@@ -252,6 +255,26 @@ const LINK_AND_TOC_STYLES = `
   outline: none;
 }
 
+/* TOC hover. .toc-group-hover is set by PresentationEditor on every entry
+   sharing a data-toc-id so the whole TOC greys out together. The ::after
+   stripe (height set via --toc-gap-below) fills the paragraph-spacing gap
+   between adjacent entries so the hover reads as one continuous block. */
+.superdoc-toc-entry:hover,
+.superdoc-toc-entry.toc-group-hover {
+  background-color: var(--sd-content-controls-block-hover-bg, #f2f2f2);
+}
+
+.superdoc-toc-entry.toc-group-hover::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: 100%;
+  height: var(--toc-gap-below, 0px);
+  background-color: var(--sd-content-controls-block-hover-bg, #f2f2f2);
+  pointer-events: none;
+}
+
 /* Remove focus outlines from layout engine elements */
 .superdoc-layout,
 .superdoc-page,

@@ -49,7 +49,13 @@ export function handleDocumentPartObjectNode(node: PMNode, context: NodeHandlerC
   if (docPartGallery === 'Table of Contents') {
     processTocChildren(
       Array.from(node.content),
-      { docPartGallery, docPartObjectId, tocInstruction, sdtMetadata: docPartSdtMetadata },
+      {
+        docPartGallery,
+        docPartObjectId,
+        tocInstruction,
+        sdtMetadata: docPartSdtMetadata,
+        tocId: docPartObjectId ?? undefined,
+      },
       {
         nextBlockId,
         positions,
@@ -100,6 +106,7 @@ export function handleDocumentPartObjectNode(node: PMNode, context: NodeHandlerC
           docPartObjectId,
           tocInstruction: getNodeInstruction(child) ?? tocInstruction,
           sdtMetadata: docPartSdtMetadata,
+          tocId: docPartObjectId ?? undefined,
         };
         const tocContext = {
           nextBlockId,

@@ -1199,6 +1199,7 @@ describe('document-section', () => {
             docPartObjectId: 'toc-123',
             tocInstruction: 'TOC \\o "1-3"',
             sdtMetadata: expect.objectContaining({ type: 'docPartObject' }),
+            tocId: 'toc-123',
           },
           expect.objectContaining({
             nextBlockId: mockBlockIdGenerator,

@@ -244,7 +244,13 @@ function processDocumentPartObject(
 
     processTocChildren(
       Array.from(child.content ?? []),
-      { docPartGallery, docPartObjectId, tocInstruction, sdtMetadata: docPartSdtMetadata },
+      {
+        docPartGallery,
+        docPartObjectId,
+        tocInstruction,
+        sdtMetadata: docPartSdtMetadata,
+        tocId: docPartObjectId ?? undefined,
+      },
       {
         nextBlockId: context.nextBlockId,
         positions: context.positions,

@@ -33,6 +33,7 @@ export function applyTocMetadata(
     gallery?: string | null;
     uniqueId?: string | null;
     instruction?: string | null;
+    tocId?: string | null;
   },
 ): void {
   blocks.forEach((block) => {
@@ -53,6 +54,9 @@ export function applyTocMetadata(
       if (metadata.instruction) {
         block.attrs.tocInstruction = metadata.instruction;
       }
+      if (metadata.tocId) {
+        block.attrs.tocId = metadata.tocId;
+      }
     }
   });
 }
@@ -95,6 +99,11 @@ export function processTocChildren(
     docPartObjectId?: string;
     tocInstruction?: string;
     sdtMetadata?: SdtMetadata;
+    /**
+     * Stable id shared by every paragraph in the TOC. Used by the
+     * painter/presentation editor to coordinate hover across all entries.
+     */
+    tocId?: string;
   },
   context: {
     nextBlockId: BlockIdGenerator;
@@ -114,7 +123,7 @@ export function processTocChildren(
   },
 ): void {
   const paragraphConverter = context.converters.paragraphToFlowBlocks;
-  const { docPartGallery, docPartObjectId, tocInstruction } = metadata;
+  const { docPartGallery, docPartObjectId, tocInstruction, tocId } = metadata;
   const { blocks, recordBlockKind } = outputArrays;
 
   children.forEach((child) => {
@@ -147,6 +156,7 @@ export function processTocChildren(
         gallery: docPartGallery,
         uniqueId: docPartObjectId,
         instruction: tocInstruction,
+        tocId,
       });
       applySdtMetadataToParagraphBlocks(
         paragraphBlocks.filter((b) => b.kind === 'paragraph') as ParagraphBlock[],
@@ -166,7 +176,13 @@ export function processTocChildren(
 
       processTocChildren(
         child.content,
-        { docPartGallery, docPartObjectId, tocInstruction: finalInstruction, sdtMetadata: metadata.sdtMetadata },
+        {
+          docPartGallery,
+          docPartObjectId,
+          tocInstruction: finalInstruction,
+          sdtMetadata: metadata.sdtMetadata,
+          tocId,
+        },
         context,
         outputArrays,
       );
@@ -189,12 +205,14 @@ export function processTocChildren(
 export function handleTableOfContentsNode(node: PMNode, context: NodeHandlerContext): void {
   if (!Array.isArray(node.content)) return;
 
+  // Direct tableOfContents nodes have no enclosing SDT — use sdBlockId as the
+  // hover group key, and omit gallery so applyTocMetadata doesn't fabricate one.
+  const sdBlockId = (node.attrs as { sdBlockId?: unknown } | undefined)?.sdBlockId;
   processTocChildren(
     node.content,
     {
-      // No enclosing SDT — omit gallery so applyTocMetadata does not fabricate
-      // a docPartObject sdt entry on each TOC paragraph.
       tocInstruction: getNodeInstruction(node),
+      tocId: typeof sdBlockId === 'string' ? sdBlockId : undefined,
     },
     {
       nextBlockId: context.nextBlockId,

@@ -564,6 +564,14 @@ export class PresentationEditor extends EventEmitter {
     id: string | null;
     elements: HTMLElement[];
   } | null = null;
+  /**
+   * TOC group hover state — mirror of #lastHoveredStructuredContentBlock
+   * for paragraph fragments sharing the same `data-toc-id`.
+   */
+  #lastHoveredTocGroup: {
+    id: string;
+    elements: HTMLElement[];
+  } | null = null;
 
   // Remote cursor/presence state management
   /** Manager for remote cursor rendering and awareness subscriptions */
@@ -671,9 +679,12 @@ export class PresentationEditor extends EventEmitter {
     ensureEditorFieldAnnotationInteractionStyles(doc);
     ensureEditorMovableObjectInteractionStyles(doc);
 
-    // Add event listeners for structured content hover coordination
+    // Hover coordination — structured-content blocks and TOC entries each
+    // group their fragments by id so the whole control greys out together.
     this.#painterHost.addEventListener('mouseover', this.#handleStructuredContentBlockMouseEnter);
     this.#painterHost.addEventListener('mouseout', this.#handleStructuredContentBlockMouseLeave);
+    this.#painterHost.addEventListener('mouseover', this.#handleTocEntryMouseEnter);
+    this.#painterHost.addEventListener('mouseout', this.#handleTocEntryMouseLeave);
 
     const win = this.#visibleHost?.ownerDocument?.defaultView ?? window;
     this.#domIndexObserverManager = new DomPositionIndexObserverManager({
@@ -6739,6 +6750,117 @@ export class PresentationEditor extends EventEmitter {
     this.#lastHoveredStructuredContentBlock = { id, elements };
   }
 
+  /** TOC analogue of {@link #handleStructuredContentBlockMouseEnter}, keyed by `data-toc-id`. */
+  #handleTocEntryMouseEnter = (event: MouseEvent) => {
+    const target = event.target as HTMLElement | null;
+    const entry = target?.closest?.(`.${DOM_CLASS_NAMES.TOC_ENTRY}`) as HTMLElement | null;
+    if (!entry) return;
+
+    const tocId = entry.dataset.tocId;
+    if (!tocId) return;
+
+    this.#setHoveredTocGroup(tocId);
+  };
+
+  #handleTocEntryMouseLeave = (event: MouseEvent) => {
+    const target = event.target as HTMLElement | null;
+    const entry = target?.closest?.(`.${DOM_CLASS_NAMES.TOC_ENTRY}`) as HTMLElement | null;
+    if (!entry) return;
+
+    const tocId = entry.dataset.tocId;
+    if (!tocId) return;
+
+    const relatedTarget = event.relatedTarget as HTMLElement | null;
+    if (relatedTarget) {
+      const nextEntry = relatedTarget.closest?.(`.${DOM_CLASS_NAMES.TOC_ENTRY}`) as HTMLElement | null;
+      if (nextEntry && nextEntry.dataset.tocId === tocId) {
+        return;
+      }
+    }
+
+    this.#clearHoveredTocGroup();
+  };
+
+  #clearHoveredTocGroup() {
+    if (!this.#lastHoveredTocGroup) return;
+    this.#lastHoveredTocGroup.elements.forEach((element) => {
+      element.classList.remove(DOM_CLASS_NAMES.TOC_GROUP_HOVER);
+      element.style.removeProperty('--toc-gap-below');
+    });
+    this.#lastHoveredTocGroup = null;
+  }
+
+  #setHoveredTocGroup(id: string) {
+    if (this.#lastHoveredTocGroup?.id === id) return;
+
+    this.#clearHoveredTocGroup();
+
+    const elements = this.#queryTocEntryElementsById(id);
+    if (elements.length === 0) return;
+
+    elements.forEach((element) => element.classList.add(DOM_CLASS_NAMES.TOC_GROUP_HOVER));
+    this.#applyTocGapFill(elements);
+    this.#lastHoveredTocGroup = { id, elements };
+  }
+
+  /**
+   * Each TOC entry is its own absolutely-positioned paragraph fragment, so
+   * paragraph spacing leaves an unbacked strip between them. Write the gap to
+   * `--toc-gap-below` and let the `::after` rule in styles.ts paint it.
+   * Cross-page gaps are skipped so the strip doesn't draw over page breaks.
+   */
+  #applyTocGapFill(elements: HTMLElement[]): void {
+    if (elements.length < 2) return;
+
+    const measured = elements
+      .map((element) => ({ element, rect: element.getBoundingClientRect() }))
+      .sort((a, b) => a.rect.top - b.rect.top);
+
+    for (let i = 0; i < measured.length - 1; i++) {
+      const current = measured[i];
+      const next = measured[i + 1];
+
+      const currentPage = current.element.closest('[data-page-index]');
+      if (!currentPage || currentPage !== next.element.closest('[data-page-index]')) continue;
+
+      // Divide by the painter's zoom transform so the strip matches the
+      // fragment's untransformed CSS-pixel height. Pad by 1px to cover
+      // sub-pixel rounding; the overlap falls on the next (also grey) entry.
+      const rawGap = next.rect.top - current.rect.bottom;
+      const scaleY =
+        current.rect.height && current.element.offsetHeight ? current.rect.height / current.element.offsetHeight : 1;
+      const gap = scaleY > 0 ? rawGap / scaleY : rawGap;
+      if (gap > 0) {
+        current.element.style.setProperty('--toc-gap-below', `${gap + 1}px`);
+      }
+    }
+  }
+
+  #queryTocEntryElementsById(id: string): HTMLElement[] {
+    if (!this.#painterHost) return [];
+    const escapedId = typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(id) : id.replace(/"/g, '\\"');
+    return Array.from(
+      this.#painterHost.querySelectorAll<HTMLElement>(`.${DOM_CLASS_NAMES.TOC_ENTRY}[data-toc-id="${escapedId}"]`),
+    );
+  }
+
+  /** Restore JS-driven `toc-group-hover` after a repaint, mirror of #reapplySdtGroupHover. */
+  #reapplyTocGroupHover(): void {
+    if (!this.#lastHoveredTocGroup) return;
+
+    const { id } = this.#lastHoveredTocGroup;
+    const elements = this.#queryTocEntryElementsById(id);
+
+    if (elements.length === 0) {
+      this.#lastHoveredTocGroup = null;
+      return;
+    }
+
+    elements.forEach((element) => element.classList.add(DOM_CLASS_NAMES.TOC_GROUP_HOVER));
+    this.#applyTocGapFill(elements);
+    this.#lastHoveredTocGroup = { id, elements };
+  }
+
   /**
    * Re-applies the sdt-group-hover class after a paint cycle.
    * DOM elements are rebuilt during repaint, so the hover class added by
@@ -6790,6 +6912,7 @@ export class PresentationEditor extends EventEmitter {
       proofingAnnotations: this.#buildProofingAnnotations(),
       rebuildDomPositionIndex: () => this.#rebuildDomPositionIndex(),
       reapplyStructuredContentHover: () => this.#reapplySdtGroupHover(),
+      reapplyTocGroupHover: () => this.#reapplyTocGroupHover(),
     });
   }
 

@@ -46,6 +46,7 @@ type RefreshAfterPaintOptions = {
   proofingAnnotations: ProofingAnnotation[] | null | undefined;
   rebuildDomPositionIndex: () => void;
   reapplyStructuredContentHover?: () => void;
+  reapplyTocGroupHover?: () => void;
 };
 
 /**
@@ -141,6 +142,7 @@ export class PresentationPostPaintPipeline {
     this.syncInlineStyleLayers(options.editorState, options.domPositionIndex);
     this.applyProofingAnnotations(options.proofingAnnotations, options.rebuildDomPositionIndex);
     options.reapplyStructuredContentHover?.();
+    options.reapplyTocGroupHover?.();
   }
 
   destroy(): void {