Merge pull request #3562 from superdoc-dev/caio/sd-3310-scrollintoview

feat(ui): scroll a content control into view by id (SD-3310)

Author: caio-pizzol

apps/docs/editor/custom-ui/content-controls.mdx

@@ -39,14 +39,16 @@ The event tells you *what* is active; `getRect` tells you *where* to draw. `acti
 | Full live list and active stack | `ui.contentControls.observe()` / `getSnapshot()` |
 | Read one control | `ui.contentControls.get({ id })` |
 | Position your UI | `ui.contentControls.getRect({ id })` |
+| Scroll a control into view | `ui.contentControls.scrollIntoView({ id })` |
 | Hover and right-click hit-testing | `ui.viewport.entityAt()` / `contextAt()` |
 | Change content, tags, or locks | `editor.doc.contentControls.*` |
 
 `active` is the innermost control. For nested controls (an inline field inside a block clause), `activePath` carries the full stack, innermost first, so you don't also need `observe()` just to read the nesting.
 
+`scrollIntoView` resolves the control's position from the document, so it works even when the control is on a page that hasn't rendered yet (the page mounts, then scrolls). It scrolls only - it does not move the cursor into the control.
+
 ## Current limits
 
-- No built-in scroll-to-control. Read the position with `getRect()` and scroll your container.
 - No geometry-change subscription. Re-read `getRect()` on scroll, resize, and the `pagination-update` / `zoomChange` events.
 - No focus-by-id helper. Clicking a control in the document still drives selection.
 

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -3815,6 +3815,74 @@ export class PresentationEditor extends EventEmitter {
     return this.scrollToPosition(pos, options);
   }
 
+  /**
+   * Scroll a content control (SDT field/clause) into view by its id.
+   *
+   * Model-aware: the control's position is resolved from the document
+   * model, not the painted DOM, so this works even when the control sits
+   * on a not-yet-rendered (virtualized) page — `scrollToPositionAsync`
+   * mounts the page first, then scrolls. This is why it cannot reuse the
+   * paint-only `getEntityRects` rect path.
+   *
+   * Scroll-only: it does NOT move the selection or place the caret inside
+   * the control. Focusing/activating a control is a separate concern.
+   *
+   * v1 is body-only: it searches the body editor, and `scrollToPositionAsync`
+   * only scrolls in body mode, so a control inside a header/footer/note
+   * story does not resolve and returns `false`.
+   *
+   * @returns `true` once scrolled; `false` when the id is empty/unknown,
+   *   the control is in a non-body story, or no editor is available.
+   */
+  async scrollContentControlIntoView(
+    entityId: string,
+    options: { block?: 'start' | 'center' | 'end' | 'nearest'; behavior?: ScrollBehavior } = {},
+  ): Promise<boolean> {
+    const editor = this.#editor;
+    if (!editor || typeof entityId !== 'string' || entityId.length === 0) return false;
+
+    let found: { pos: number; node: ReturnType<typeof editor.state.doc.nodeAt> } | null = null;
+    editor.state.doc.descendants((node, pos) => {
+      if (found) return false;
+      const name = node.type?.name;
+      // Normalize the node id to a string before comparing. The id a
+      // consumer passes comes from the list / painted `data-sdt-id` (always
+      // a string), but the PM attr can be numeric, so a strict `===` would
+      // miss it. Matches the painted-DOM (`getRect`) id convention.
+      if ((name === 'structuredContent' || name === 'structuredContentBlock') && String(node.attrs?.id) === entityId) {
+        found = { pos, node };
+        return false;
+      }
+      return true;
+    });
+    if (!found) return false;
+
+    // Resolve the first *text* position inside the control. Only text
+    // positions reliably map to a layout fragment; wrapper boundaries
+    // (block, paragraph, run) sit between fragments and make
+    // `scrollToPositionAsync` fail. A deep `descendants` walk handles
+    // inline (`run > text`) and block (`paragraph > run > text`) nesting
+    // uniformly. `descendants` yields each child's position relative to
+    // the node's content, so the absolute position is `found.pos + 1 + rel`.
+    // Scroll-only: this does NOT move the selection or focus.
+    let contentPos = found.pos + 1;
+    let textFound = false;
+    found.node?.descendants((child, rel) => {
+      if (textFound) return false;
+      if (child.isText) {
+        contentPos = found.pos + 1 + rel;
+        textFound = true;
+        return false;
+      }
+      return true;
+    });
+
+    return this.scrollToPositionAsync(contentPos, {
+      behavior: options.behavior ?? 'smooth',
+      block: options.block ?? 'center',
+    });
+  }
+
   /**
    * Scrolls a specific page into view.
    *

packages/super-editor/src/ui/content-controls.test.ts

@@ -351,6 +351,51 @@ describe('ui.contentControls handle (SD-3157)', () => {
     ui.destroy();
   });
 
+  it('scrollIntoView({ id }) returns { success: false } for an empty or missing id without touching the presentation', async () => {
+    const { superdoc, editor } = makeStub({ items: [makeItem('sdt-1')] });
+    const ui = createSuperDocUI({ superdoc });
+    // Attach after construction: a `presentationEditor` present during the
+    // toolbar-snapshot build would need the full presentation interface.
+    const scroll = vi.fn().mockResolvedValue(true);
+    (editor as { presentationEditor?: unknown }).presentationEditor = { scrollContentControlIntoView: scroll };
+
+    expect(await ui.contentControls.scrollIntoView({ id: '' })).toEqual({ success: false });
+    // @ts-expect-error exercising the runtime guard for a missing id
+    expect(await ui.contentControls.scrollIntoView({})).toEqual({ success: false });
+    expect(scroll).not.toHaveBeenCalled();
+
+    ui.destroy();
+  });
+
+  it('scrollIntoView({ id }) returns { success: false } when the presentation layer is not ready', async () => {
+    // The stub editor has no `presentationEditor` (e.g. SSR / pre-mount).
+    const { superdoc } = makeStub({ items: [makeItem('sdt-1')] });
+    const ui = createSuperDocUI({ superdoc });
+
+    expect(await ui.contentControls.scrollIntoView({ id: 'sdt-1' })).toEqual({ success: false });
+
+    ui.destroy();
+  });
+
+  it('scrollIntoView({ id }) delegates to the presentation scroll with center/smooth defaults and maps the boolean to { success }', async () => {
+    const { superdoc, editor } = makeStub({ items: [makeItem('sdt-1')] });
+    const ui = createSuperDocUI({ superdoc });
+    const scroll = vi.fn().mockResolvedValue(true);
+    (editor as { presentationEditor?: unknown }).presentationEditor = { scrollContentControlIntoView: scroll };
+
+    expect(await ui.contentControls.scrollIntoView({ id: 'sdt-1' })).toEqual({ success: true });
+    expect(scroll).toHaveBeenCalledWith('sdt-1', { block: 'center', behavior: 'smooth' });
+
+    // Explicit options pass through; a falsy presentation result maps to failure.
+    scroll.mockResolvedValueOnce(false);
+    expect(await ui.contentControls.scrollIntoView({ id: 'sdt-1', block: 'start', behavior: 'auto' })).toEqual({
+      success: false,
+    });
+    expect(scroll).toHaveBeenLastCalledWith('sdt-1', { block: 'start', behavior: 'auto' });
+
+    ui.destroy();
+  });
+
   it('observe receives the snapshot value directly (parallel to comments/trackChanges)', async () => {
     // `observe` is the value-shaped alias of `subscribe`. The demo
     // (`field-chip.ts`) consumes it directly, so an explicit test

packages/super-editor/src/ui/create-super-doc-ui.ts

@@ -2250,6 +2250,43 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
         target: { kind: 'entity', entityType: 'contentControl', entityId: id },
       });
     },
+    async scrollIntoView({
+      id,
+      block,
+      behavior,
+    }: {
+      id: string;
+      block?: 'start' | 'center' | 'end' | 'nearest';
+      behavior?: 'auto' | 'smooth';
+    }): Promise<ScrollIntoViewOutput> {
+      if (typeof id !== 'string' || id.length === 0) return { success: false };
+      // Resolve through the host editor — `presentationEditor` lives on the
+      // body/host, not a routed child story editor. Same posture as
+      // `viewport.getRect` / `runScrollIntoView`. The model-aware scroll is
+      // body-only, so a control in a header/footer/note resolves to a no-op
+      // `{ success: false }`. We call the presentation method directly rather
+      // than routing a content-control target through `viewport.scrollIntoView`
+      // — content controls are UI-local and deliberately absent from the
+      // Document API `ScrollIntoViewInput` address union (mirrors `getRect`).
+      const editor = resolveHostEditor(superdoc);
+      const presentation = editor?.presentationEditor as
+        | {
+            scrollContentControlIntoView?: (
+              id: string,
+              opts: { block?: 'start' | 'center' | 'end' | 'nearest'; behavior?: 'auto' | 'smooth' },
+            ) => Promise<boolean>;
+          }
+        | null
+        | undefined;
+      if (!presentation || typeof presentation.scrollContentControlIntoView !== 'function') {
+        return { success: false };
+      }
+      const ok = await presentation.scrollContentControlIntoView(id, {
+        block: block ?? 'center',
+        behavior: behavior ?? 'smooth',
+      });
+      return { success: Boolean(ok) };
+    },
   };
 
   // Resolve a metadata id (= the SDT's w:tag) to the SDT's content-

packages/super-editor/src/ui/types.ts

@@ -462,9 +462,10 @@ export interface ContentControlsSlice {
  * directly, matching the architectural rule that this handle is a UI
  * surface, not a parallel mutation contract.
  *
- * The handle does not include `scrollIntoView` in v1: that path
- * widens `ui.viewport.scrollIntoView` and is a separate slice from
- * `ui.viewport.getRect` (SD-3156).
+ * The handle includes `scrollIntoView` via a dedicated model-aware
+ * path. It does NOT widen `ui.viewport.scrollIntoView`: content controls
+ * stay UI-local and out of the Document API address union, mirroring how
+ * `getRect` resolves a content control through a UI-local address.
  */
 export interface ContentControlsHandle {
   /** Snapshot the current content-controls slice synchronously. */
@@ -496,6 +497,28 @@ export interface ContentControlsHandle {
    * failure reason).
    */
   getRect(input: { id: string }): ViewportRectResult;
+  /**
+   * Scroll the content control identified by `id` into view. The
+   * control's position is resolved from the document model (not the
+   * painted DOM), so it works even when the control sits on a
+   * not-yet-rendered (virtualized) page — the page is mounted, then
+   * scrolled. Scroll-only: it does not move the selection or place the
+   * caret inside the control.
+   *
+   * Returns the same `ScrollIntoViewOutput` shape as
+   * `ui.viewport.scrollIntoView`: `{ success: true }` once scrolled, or
+   * `{ success: false }` when `id` is empty/unknown or the presentation
+   * layer isn't ready. `block` defaults to `'center'`, `behavior` to
+   * `'smooth'`.
+   *
+   * v1 is body-only: a control inside a header/footer/note story does
+   * not resolve and returns `{ success: false }`.
+   */
+  scrollIntoView(input: {
+    id: string;
+    block?: 'start' | 'center' | 'end' | 'nearest';
+    behavior?: 'auto' | 'smooth';
+  }): Promise<import('@superdoc/document-api').ScrollIntoViewOutput>;
 }
 
 /**

tests/behavior/tests/sdt/content-control-scroll-imported-docx.spec.ts

@@ -0,0 +1,97 @@
+/**
+ * SD-3310 regression for imported Word-authored content controls.
+ *
+ * `nda-template.docx` is the contract-templates demo's fixture: 13 real
+ * Word SDTs (7 inline smart fields + 6 block clauses). It is copied here
+ * (not loaded from demos/) so the behavior suite isn't coupled to demo
+ * paths.
+ *
+ * Confirms `ui.contentControls.scrollIntoView` resolves controls imported
+ * from a real .docx (not just programmatically-created ones) and scrolls
+ * them into view from an off-screen start.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test, expect } from '../../fixtures/superdoc.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const NDA = path.resolve(__dirname, 'fixtures/nda-template.docx');
+
+test.use({ viewport: { width: 1000, height: 360 } });
+
+type Item = { id: string; kind: string; text?: string };
+
+async function snapshotItems(page: import('@playwright/test').Page): Promise<Item[]> {
+  return page.evaluate(() => {
+    const ui = (window as any).__bootSuperDocUI?.();
+    if (!ui) return [];
+    return ui.contentControls.getSnapshot().items.map((it: any) => ({ id: it.id, kind: it.kind, text: it.text }));
+  });
+}
+
+async function probeVisible(page: import('@playwright/test').Page, id: string) {
+  return page.evaluate((sdtId) => {
+    const el = document.querySelector<HTMLElement>(`[data-sdt-id="${sdtId}"]`);
+    if (!el) return { painted: false, inViewport: false };
+    const r = el.getBoundingClientRect();
+    return { painted: true, inViewport: r.top >= 0 && r.top <= window.innerHeight };
+  }, id);
+}
+
+async function scrollTo(page: import('@playwright/test').Page, id: string): Promise<{ success: boolean }> {
+  return page.evaluate(async (sdtId) => {
+    const ui = (window as any).__bootSuperDocUI?.();
+    if (!ui) return { success: false };
+    return ui.contentControls.scrollIntoView({ id: sdtId, block: 'center', behavior: 'auto' });
+  }, id);
+}
+
+async function scrollContainerTo(page: import('@playwright/test').Page, edge: 'top' | 'bottom'): Promise<void> {
+  await page.evaluate((to) => {
+    let node: HTMLElement | null = document.querySelector<HTMLElement>('.presentation-editor__pages');
+    let scroller: HTMLElement | null = null;
+    while (node) {
+      if (node.scrollHeight > node.clientHeight + 4) {
+        scroller = node;
+        break;
+      }
+      node = node.parentElement;
+    }
+    const target = to === 'top' ? 0 : 1_000_000;
+    if (scroller) scroller.scrollTop = target;
+    else window.scrollTo(0, target);
+  }, edge);
+}
+
+test('@behavior SD-3310: scrolls real imported NDA-template controls (first field + last clause) into view', async ({
+  superdoc,
+}) => {
+  await superdoc.loadDocument(NDA);
+  await superdoc.waitForStable();
+
+  const items = await snapshotItems(superdoc.page);
+  // Sanity: the fixture's controls are visible to the handle.
+  expect(items.length).toBeGreaterThanOrEqual(6);
+
+  const first = items[0]; // top-most (an inline smart field)
+  const last = items[items.length - 1]; // bottom-most (a block clause)
+  expect(first.id).toBeTruthy();
+  expect(last.id).toBeTruthy();
+
+  // Bottom clause: scroll to top so it's off-screen, then scroll it in.
+  await scrollContainerTo(superdoc.page, 'top');
+  await superdoc.waitForStable();
+  expect((await probeVisible(superdoc.page, last.id)).inViewport).toBe(false);
+  expect((await scrollTo(superdoc.page, last.id)).success).toBe(true);
+  await superdoc.waitForStable();
+  expect(await probeVisible(superdoc.page, last.id)).toEqual({ painted: true, inViewport: true });
+
+  // Top field: scroll to bottom so it's off-screen, then scroll it in.
+  await scrollContainerTo(superdoc.page, 'bottom');
+  await superdoc.waitForStable();
+  expect((await probeVisible(superdoc.page, first.id)).inViewport).toBe(false);
+  expect((await scrollTo(superdoc.page, first.id)).success).toBe(true);
+  await superdoc.waitForStable();
+  expect(await probeVisible(superdoc.page, first.id)).toEqual({ painted: true, inViewport: true });
+});