@atlaskit/renderer 126.7.0 → 126.8.0

package/dist/es2019/ui/hooks/useScrollToBlock.js

@@ -0,0 +1,229 @@
+import { useEffect } from 'react';
+import { getDocument } from '@atlaskit/browser-apis';
+import { DEFAULT_BLOCK_LINK_HASH_PREFIX, expandAllParentsThenScroll, expandElement, isExpandCollapsed, findNodeWithExpandParents, getLocalIdSelector } from '@atlaskit/editor-common/block-menu';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
+import { useStableScroll } from './useStableScroll';
+
+/**
+ * useScrollToBlock - Handler for block link scrolling in the renderer with expand support
+ *
+ * This hook enables scroll-to-block functionality when blocks may be hidden inside collapsed expands.
+ * It searches the ADF document for the target block, identifies any parent expand nodes,
+ * expands them if needed, and waits for layout stability before scrolling to the block.
+ *
+ * This implementation waits for the container to stabilize (no layout shifts) before scrolling,
+ * which prevents issues with images loading, dynamic content, or other async operations that
+ * cause layout changes.
+ *
+ * This hook replaces useScrollToLocalId when the platform_editor_expand_on_scroll_to_block experiment is enabled.
+ *
+ * When platform_editor_expand_on_scroll_to_block experiment is cleaned up:
+ *       - Remove the experiment check
+ *       - Delete the deprecated useScrollToLocalId hook
+ *       - Make this the default scroll-to-block behavior
+ *
+ * @param containerRef - Optional ref to the renderer container (RendererStyleContainer)
+ * @param adfDoc - The ADF document to search for nodes and expand parents
+ */
+export const useScrollToBlock = (containerRef, adfDoc) => {
+  const {
+    waitForStability,
+    cleanup: cleanupStability
+  } = useStableScroll({
+    stabilityWaitTime: 750,
+    maxStabilityWaitTime: 10_000
+  });
+  useEffect(() => {
+    var _getDocument;
+    // Only run in browser environment.
+    if (typeof window === 'undefined' || !(containerRef !== null && containerRef !== void 0 && containerRef.current)) {
+      return;
+    }
+    if (!expValEquals('platform_editor_expand_on_scroll_to_block', 'isEnabled', true)) {
+      return;
+    }
+
+    // Parse hash fragment for block ID (format: #block-{localId}).
+    const hash = window.location.hash;
+    const defaultPrefixWithHash = `#${DEFAULT_BLOCK_LINK_HASH_PREFIX}`;
+    const blockId = hash.startsWith(defaultPrefixWithHash) ? hash.slice(defaultPrefixWithHash.length) : null;
+    if (!blockId) {
+      return;
+    }
+    let retryCount = 0;
+    const maxRetries = 40;
+    const retryInterval = 250;
+    let intervalId = null;
+    let hasScrolled = false;
+    let cancelExpandAndScroll = null;
+    const scrollToElement = () => {
+      // Step 1: Search the ADF document for the node with the given blockId.
+      // This works even if the node is hidden inside a collapsed expand.
+      if (!adfDoc || !(containerRef !== null && containerRef !== void 0 && containerRef.current)) {
+        return false;
+      }
+      const nodeWithExpandParents = findNodeWithExpandParents(adfDoc, blockId);
+      if (!nodeWithExpandParents) {
+        // Node not found in ADF document.
+        return false;
+      }
+      const {
+        expandParentLocalIds
+      } = nodeWithExpandParents;
+
+      // Step 2: If the node has expand parents, we need to expand them first.
+      if (expandParentLocalIds.length > 0) {
+        // Find the expand elements in the DOM using their localIds.
+        // Note: We need to expand from outermost to innermost.
+        let allExpandsFound = true;
+        let anyExpandsCollapsed = false;
+        for (const expandLocalId of expandParentLocalIds) {
+          const expandContainer = containerRef.current.querySelector(`[data-local-id="${expandLocalId}"]`);
+          if (!expandContainer) {
+            // Expand not found in DOM yet (shouldn't happen but handle it).
+            allExpandsFound = false;
+            break;
+          }
+
+          // Check if this expand is collapsed.
+          if (isExpandCollapsed(expandContainer)) {
+            anyExpandsCollapsed = true;
+            // Expand it.
+            expandElement(expandContainer);
+            // After expanding, we need to retry to handle nested expands.
+            // The DOM needs time to update.
+            return false; // Will retry after interval.
+          }
+        }
+        if (!allExpandsFound) {
+          // Retry later when expands are in DOM.
+          return false;
+        }
+
+        // All parent expands are now open (or we just expanded one and need to wait).
+        if (anyExpandsCollapsed) {
+          // Just expanded something, wait for DOM update.
+          return false;
+        }
+      }
+
+      // Step 3: Now the target element should be visible in the DOM, find it and scroll.
+      const element = getLocalIdSelector(blockId, containerRef.current);
+      if (!element) {
+        // Element still not in DOM, retry.
+        return false;
+      }
+
+      // Element found and all parent expands are open! Use the utility to scroll.
+      // (This will handle any final edge cases and do the actual scrolling).
+      // Capture cleanup function to cancel pending timeouts.
+      cancelExpandAndScroll = expandAllParentsThenScroll(element);
+      return true;
+    };
+    const performScroll = () => {
+      if (hasScrolled) {
+        return;
+      }
+
+      // Try to scroll to element.
+      if (scrollToElement()) {
+        hasScrolled = true;
+        cleanup();
+      }
+    };
+    const attemptScroll = () => {
+      retryCount++;
+
+      // Try to find the element first.
+      if (!adfDoc || !(containerRef !== null && containerRef !== void 0 && containerRef.current)) {
+        return false;
+      }
+      const nodeWithExpandParents = findNodeWithExpandParents(adfDoc, blockId);
+      if (!nodeWithExpandParents) {
+        return false;
+      }
+      const {
+        expandParentLocalIds
+      } = nodeWithExpandParents;
+
+      // Check if all expands are expanded and element exists.
+      let allReady = true;
+      if (expandParentLocalIds.length > 0) {
+        for (const expandLocalId of expandParentLocalIds) {
+          const expandContainer = containerRef.current.querySelector(`[data-local-id="${expandLocalId}"]`);
+          if (!expandContainer) {
+            allReady = false;
+            break;
+          }
+          if (isExpandCollapsed(expandContainer)) {
+            expandElement(expandContainer);
+            allReady = false;
+            break;
+          }
+        }
+      }
+      const element = getLocalIdSelector(blockId, containerRef.current);
+      if (!element) {
+        allReady = false;
+      }
+
+      // If everything is ready, start monitoring for stability.
+      if (allReady) {
+        if (intervalId) {
+          clearInterval(intervalId);
+          intervalId = null;
+        }
+        waitForStability(containerRef.current, performScroll);
+        return true;
+      }
+
+      // Stop retrying if we've exceeded max retries.
+      if (retryCount >= maxRetries) {
+        cleanup();
+        return false;
+      }
+      return false;
+    };
+    const cleanup = () => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      cleanupStability();
+      // Cancel any pending expand and scroll operations.
+      if (cancelExpandAndScroll) {
+        cancelExpandAndScroll();
+        cancelExpandAndScroll = null;
+      }
+    };
+
+    // Try to scroll immediately.
+    if (attemptScroll()) {
+      return cleanup;
+    }
+    if (((_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.readyState) === 'complete') {
+      // Document is already ready, try a few more times with delays.
+      // This handles cases where elements are added after document ready.
+      intervalId = setInterval(() => {
+        attemptScroll();
+      }, retryInterval);
+    } else {
+      // Document not ready yet, wait for it and then retry.
+      intervalId = setInterval(() => {
+        var _getDocument2;
+        if (((_getDocument2 = getDocument()) === null || _getDocument2 === void 0 ? void 0 : _getDocument2.readyState) === 'complete') {
+          attemptScroll();
+        } else if (retryCount >= maxRetries) {
+          cleanup();
+        } else {
+          retryCount++;
+        }
+      }, retryInterval);
+    }
+
+    // Cleanup function.
+    return cleanup;
+    // Intentionally not including adfDoc in the dependency array to avoid unnecessary re-renders.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef, waitForStability, cleanupStability]);
+};

package/dist/es2019/ui/hooks/useScrollToLocalId.js

@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 import { getDocument } from '@atlaskit/browser-apis';
 import { DEFAULT_BLOCK_LINK_HASH_PREFIX } from '@atlaskit/editor-common/block-menu';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 
 // Find editor node dom with localId - similar to confluence useScrollOnUrlChange.ts
 const getLocalIdSelector = (localId, container) => {
@@ -33,6 +34,16 @@ const getLocalIdSelector = (localId, container) => {
   }
   return null;
 };
+
+/**
+ * useScrollToLocalId - Handler for block link scrolling in the renderer (traditional pages)
+ *
+ * This hook is deprecated in favor of useScrollToBlock which supports expanding parent nodes.
+ * This hook will be removed when the platform_editor_expand_on_scroll_to_block experiment is cleaned up.
+ *
+ * @param containerRef - Optional ref to the renderer container (RendererStyleContainer).
+ * @param shouldScrollToLocalId - Whether scroll-to-block functionality should be enabled
+ */
 export const useScrollToLocalId = (containerRef, shouldScrollToLocalId) => {
   useEffect(() => {
     var _getDocument;
@@ -40,6 +51,9 @@ export const useScrollToLocalId = (containerRef, shouldScrollToLocalId) => {
     if (typeof window === 'undefined' || !(containerRef !== null && containerRef !== void 0 && containerRef.current) || !shouldScrollToLocalId) {
       return;
     }
+    if (expValEquals('platform_editor_expand_on_scroll_to_block', 'isEnabled', true)) {
+      return;
+    }
 
     // Parse hash fragment for block ID (format: #block-{localId})
     const hash = window.location.hash;

package/dist/es2019/ui/hooks/useStableScroll.js

@@ -0,0 +1,88 @@
+import { useRef, useCallback } from 'react';
+/**
+ * Hook that provides functionality to wait for layout stability before performing an action.
+ * Uses ResizeObserver to detect when a container has stopped resizing (e.g., images finished loading).
+ */
+export const useStableScroll = (options = {}) => {
+  const {
+    stabilityWaitTime = 200,
+    maxStabilityWaitTime = 10_000
+  } = options;
+  const stabilityTimeoutRef = useRef(null);
+  const resizeObserverRef = useRef(null);
+  const lastStableTimeRef = useRef(0);
+  const onStableCallbackRef = useRef(null);
+  const cleanup = useCallback(() => {
+    if (stabilityTimeoutRef.current) {
+      clearTimeout(stabilityTimeoutRef.current);
+      stabilityTimeoutRef.current = null;
+    }
+    if (resizeObserverRef.current) {
+      resizeObserverRef.current.disconnect();
+      resizeObserverRef.current = null;
+    }
+    onStableCallbackRef.current = null;
+    lastStableTimeRef.current = 0;
+  }, []);
+  const scheduleStabilityCheck = useCallback(() => {
+    // Clear any existing stability timeout.
+    if (stabilityTimeoutRef.current) {
+      clearTimeout(stabilityTimeoutRef.current);
+      stabilityTimeoutRef.current = null;
+    }
+
+    // Check if we've exceeded the maximum stability wait time.
+    const now = Date.now();
+    if (lastStableTimeRef.current === 0) {
+      lastStableTimeRef.current = now;
+    } else if (now - lastStableTimeRef.current > maxStabilityWaitTime) {
+      // We've waited too long for stability, call the callback now.
+      if (onStableCallbackRef.current) {
+        onStableCallbackRef.current();
+        cleanup();
+      }
+      return;
+    }
+
+    // Set a timeout to call the callback after the stability wait time.
+    stabilityTimeoutRef.current = setTimeout(() => {
+      if (onStableCallbackRef.current) {
+        onStableCallbackRef.current();
+        cleanup();
+      }
+    }, stabilityWaitTime);
+  }, [stabilityWaitTime, maxStabilityWaitTime, cleanup]);
+  const waitForStability = useCallback((container, onStable) => {
+    // Clean up any existing observer
+    cleanup();
+
+    // Store the callback
+    onStableCallbackRef.current = onStable;
+
+    // Check if ResizeObserver is available
+    if (typeof ResizeObserver === 'undefined') {
+      // Fallback: just call the callback after the stability wait time
+      stabilityTimeoutRef.current = setTimeout(() => {
+        if (onStableCallbackRef.current) {
+          onStableCallbackRef.current();
+          cleanup();
+        }
+      }, stabilityWaitTime);
+      return;
+    }
+
+    // Create a ResizeObserver to monitor the container for size changes.
+    resizeObserverRef.current = new ResizeObserver(() => {
+      // Container size changed, reset stability timer.
+      scheduleStabilityCheck();
+    });
+    resizeObserverRef.current.observe(container);
+
+    // Start the initial stability check
+    scheduleStabilityCheck();
+  }, [stabilityWaitTime, scheduleStabilityCheck, cleanup]);
+  return {
+    waitForStability,
+    cleanup
+  };
+};

package/dist/esm/ui/Renderer/index.js

@@ -20,6 +20,7 @@ import { browser as browserLegacy, getBrowserInfo } from '@atlaskit/editor-commo
 import { startMeasure, stopMeasure } from '@atlaskit/editor-common/performance-measures';
 import { getDistortedDurationMonitor } from '@atlaskit/editor-common/performance/measure-render';
 import { getResponseEndTime } from '@atlaskit/editor-common/performance/navigation';
+import { useScrollToBlock } from '../hooks/useScrollToBlock';
 import { getAnalyticsAppearance, getAnalyticsEventSeverity, shouldForceTracking } from '@atlaskit/editor-common/utils';
 import { fg } from '@atlaskit/platform-feature-flags';
 import { FabricChannel } from '@atlaskit/analytics-listeners/types';
@@ -61,7 +62,7 @@ export var DEGRADED_SEVERITY_THRESHOLD = 3000;
 var TABLE_INFO_TIMEOUT = 10000;
 var RENDER_EVENT_SAMPLE_RATE = 0.2;
 var packageName = "@atlaskit/renderer";
-var packageVersion = "0.0.0-development";
+var packageVersion = "126.7.1";
 var setAsQueryContainerStyles = css({
   containerName: 'ak-renderer-wrapper',
   containerType: 'inline-size'
@@ -183,7 +184,8 @@ export var RendererFunctionalComponent = function RendererFunctionalComponent(pr
     return props.dataProviders || new ProviderFactory();
   }, [props.dataProviders]);
   var _useRendererContext = useRendererContext(),
-    parentContextContentMode = _useRendererContext.contentMode;
+    parentContextContentMode = _useRendererContext.contentMode,
+    nestedRendererType = _useRendererContext.nestedRendererType;
   var createRendererContext = useMemo(function () {
     return function (featureFlags, isTopLevelRenderer, contentMode) {
       var normalizedFeatureFlags = normalizeFeatureFlags(featureFlags);
@@ -353,6 +355,7 @@ export var RendererFunctionalComponent = function RendererFunctionalComponent(pr
                 distortedDuration: renderedMeasurementDistortedDurationMonitor.distortedDuration,
                 ttfb: getResponseEndTime(),
                 nodes: countNodes(props.document),
+                nestedRendererType: editorExperiment('platform_synced_block', true) && fg('platform_synced_block_patch_1') ? nestedRendererType : undefined,
                 severity: severity
               },
               eventType: EVENT_TYPE.OPERATIONAL
@@ -428,6 +431,7 @@ export var RendererFunctionalComponent = function RendererFunctionalComponent(pr
   var rendererContext = useMemo(function () {
     return createRendererContext(props.featureFlags, props.isTopLevelRenderer, props.contentMode);
   }, [props.featureFlags, props.isTopLevelRenderer, createRendererContext, props.contentMode]);
+  useScrollToBlock(editorRef, props.document);
   try {
     var _rendererContext$feat, _props$media;
     var schema = getSchema(props.schema, props.adfStage);

package/dist/esm/ui/hooks/useScrollToBlock.js

@@ -0,0 +1,245 @@
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+import { useEffect } from 'react';
+import { getDocument } from '@atlaskit/browser-apis';
+import { DEFAULT_BLOCK_LINK_HASH_PREFIX, expandAllParentsThenScroll, expandElement, isExpandCollapsed, findNodeWithExpandParents, getLocalIdSelector } from '@atlaskit/editor-common/block-menu';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
+import { useStableScroll } from './useStableScroll';
+
+/**
+ * useScrollToBlock - Handler for block link scrolling in the renderer with expand support
+ *
+ * This hook enables scroll-to-block functionality when blocks may be hidden inside collapsed expands.
+ * It searches the ADF document for the target block, identifies any parent expand nodes,
+ * expands them if needed, and waits for layout stability before scrolling to the block.
+ *
+ * This implementation waits for the container to stabilize (no layout shifts) before scrolling,
+ * which prevents issues with images loading, dynamic content, or other async operations that
+ * cause layout changes.
+ *
+ * This hook replaces useScrollToLocalId when the platform_editor_expand_on_scroll_to_block experiment is enabled.
+ *
+ * When platform_editor_expand_on_scroll_to_block experiment is cleaned up:
+ *       - Remove the experiment check
+ *       - Delete the deprecated useScrollToLocalId hook
+ *       - Make this the default scroll-to-block behavior
+ *
+ * @param containerRef - Optional ref to the renderer container (RendererStyleContainer)
+ * @param adfDoc - The ADF document to search for nodes and expand parents
+ */
+export var useScrollToBlock = function useScrollToBlock(containerRef, adfDoc) {
+  var _useStableScroll = useStableScroll({
+      stabilityWaitTime: 750,
+      maxStabilityWaitTime: 10000
+    }),
+    waitForStability = _useStableScroll.waitForStability,
+    cleanupStability = _useStableScroll.cleanup;
+  useEffect(function () {
+    var _getDocument;
+    // Only run in browser environment.
+    if (typeof window === 'undefined' || !(containerRef !== null && containerRef !== void 0 && containerRef.current)) {
+      return;
+    }
+    if (!expValEquals('platform_editor_expand_on_scroll_to_block', 'isEnabled', true)) {
+      return;
+    }
+
+    // Parse hash fragment for block ID (format: #block-{localId}).
+    var hash = window.location.hash;
+    var defaultPrefixWithHash = "#".concat(DEFAULT_BLOCK_LINK_HASH_PREFIX);
+    var blockId = hash.startsWith(defaultPrefixWithHash) ? hash.slice(defaultPrefixWithHash.length) : null;
+    if (!blockId) {
+      return;
+    }
+    var retryCount = 0;
+    var maxRetries = 40;
+    var retryInterval = 250;
+    var intervalId = null;
+    var hasScrolled = false;
+    var cancelExpandAndScroll = null;
+    var scrollToElement = function scrollToElement() {
+      // Step 1: Search the ADF document for the node with the given blockId.
+      // This works even if the node is hidden inside a collapsed expand.
+      if (!adfDoc || !(containerRef !== null && containerRef !== void 0 && containerRef.current)) {
+        return false;
+      }
+      var nodeWithExpandParents = findNodeWithExpandParents(adfDoc, blockId);
+      if (!nodeWithExpandParents) {
+        // Node not found in ADF document.
+        return false;
+      }
+      var expandParentLocalIds = nodeWithExpandParents.expandParentLocalIds;
+
+      // Step 2: If the node has expand parents, we need to expand them first.
+      if (expandParentLocalIds.length > 0) {
+        // Find the expand elements in the DOM using their localIds.
+        // Note: We need to expand from outermost to innermost.
+        var allExpandsFound = true;
+        var anyExpandsCollapsed = false;
+        var _iterator = _createForOfIteratorHelper(expandParentLocalIds),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var expandLocalId = _step.value;
+            var expandContainer = containerRef.current.querySelector("[data-local-id=\"".concat(expandLocalId, "\"]"));
+            if (!expandContainer) {
+              // Expand not found in DOM yet (shouldn't happen but handle it).
+              allExpandsFound = false;
+              break;
+            }
+
+            // Check if this expand is collapsed.
+            if (isExpandCollapsed(expandContainer)) {
+              anyExpandsCollapsed = true;
+              // Expand it.
+              expandElement(expandContainer);
+              // After expanding, we need to retry to handle nested expands.
+              // The DOM needs time to update.
+              return false; // Will retry after interval.
+            }
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+        if (!allExpandsFound) {
+          // Retry later when expands are in DOM.
+          return false;
+        }
+
+        // All parent expands are now open (or we just expanded one and need to wait).
+        if (anyExpandsCollapsed) {
+          // Just expanded something, wait for DOM update.
+          return false;
+        }
+      }
+
+      // Step 3: Now the target element should be visible in the DOM, find it and scroll.
+      var element = getLocalIdSelector(blockId, containerRef.current);
+      if (!element) {
+        // Element still not in DOM, retry.
+        return false;
+      }
+
+      // Element found and all parent expands are open! Use the utility to scroll.
+      // (This will handle any final edge cases and do the actual scrolling).
+      // Capture cleanup function to cancel pending timeouts.
+      cancelExpandAndScroll = expandAllParentsThenScroll(element);
+      return true;
+    };
+    var performScroll = function performScroll() {
+      if (hasScrolled) {
+        return;
+      }
+
+      // Try to scroll to element.
+      if (scrollToElement()) {
+        hasScrolled = true;
+        cleanup();
+      }
+    };
+    var attemptScroll = function attemptScroll() {
+      retryCount++;
+
+      // Try to find the element first.
+      if (!adfDoc || !(containerRef !== null && containerRef !== void 0 && containerRef.current)) {
+        return false;
+      }
+      var nodeWithExpandParents = findNodeWithExpandParents(adfDoc, blockId);
+      if (!nodeWithExpandParents) {
+        return false;
+      }
+      var expandParentLocalIds = nodeWithExpandParents.expandParentLocalIds;
+
+      // Check if all expands are expanded and element exists.
+      var allReady = true;
+      if (expandParentLocalIds.length > 0) {
+        var _iterator2 = _createForOfIteratorHelper(expandParentLocalIds),
+          _step2;
+        try {
+          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+            var expandLocalId = _step2.value;
+            var expandContainer = containerRef.current.querySelector("[data-local-id=\"".concat(expandLocalId, "\"]"));
+            if (!expandContainer) {
+              allReady = false;
+              break;
+            }
+            if (isExpandCollapsed(expandContainer)) {
+              expandElement(expandContainer);
+              allReady = false;
+              break;
+            }
+          }
+        } catch (err) {
+          _iterator2.e(err);
+        } finally {
+          _iterator2.f();
+        }
+      }
+      var element = getLocalIdSelector(blockId, containerRef.current);
+      if (!element) {
+        allReady = false;
+      }
+
+      // If everything is ready, start monitoring for stability.
+      if (allReady) {
+        if (intervalId) {
+          clearInterval(intervalId);
+          intervalId = null;
+        }
+        waitForStability(containerRef.current, performScroll);
+        return true;
+      }
+
+      // Stop retrying if we've exceeded max retries.
+      if (retryCount >= maxRetries) {
+        cleanup();
+        return false;
+      }
+      return false;
+    };
+    var cleanup = function cleanup() {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      cleanupStability();
+      // Cancel any pending expand and scroll operations.
+      if (cancelExpandAndScroll) {
+        cancelExpandAndScroll();
+        cancelExpandAndScroll = null;
+      }
+    };
+
+    // Try to scroll immediately.
+    if (attemptScroll()) {
+      return cleanup;
+    }
+    if (((_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.readyState) === 'complete') {
+      // Document is already ready, try a few more times with delays.
+      // This handles cases where elements are added after document ready.
+      intervalId = setInterval(function () {
+        attemptScroll();
+      }, retryInterval);
+    } else {
+      // Document not ready yet, wait for it and then retry.
+      intervalId = setInterval(function () {
+        var _getDocument2;
+        if (((_getDocument2 = getDocument()) === null || _getDocument2 === void 0 ? void 0 : _getDocument2.readyState) === 'complete') {
+          attemptScroll();
+        } else if (retryCount >= maxRetries) {
+          cleanup();
+        } else {
+          retryCount++;
+        }
+      }, retryInterval);
+    }
+
+    // Cleanup function.
+    return cleanup;
+    // Intentionally not including adfDoc in the dependency array to avoid unnecessary re-renders.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef, waitForStability, cleanupStability]);
+};

package/dist/esm/ui/hooks/useScrollToLocalId.js

@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 import { getDocument } from '@atlaskit/browser-apis';
 import { DEFAULT_BLOCK_LINK_HASH_PREFIX } from '@atlaskit/editor-common/block-menu';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 
 // Find editor node dom with localId - similar to confluence useScrollOnUrlChange.ts
 var getLocalIdSelector = function getLocalIdSelector(localId, container) {
@@ -33,6 +34,16 @@ var getLocalIdSelector = function getLocalIdSelector(localId, container) {
   }
   return null;
 };
+
+/**
+ * useScrollToLocalId - Handler for block link scrolling in the renderer (traditional pages)
+ *
+ * This hook is deprecated in favor of useScrollToBlock which supports expanding parent nodes.
+ * This hook will be removed when the platform_editor_expand_on_scroll_to_block experiment is cleaned up.
+ *
+ * @param containerRef - Optional ref to the renderer container (RendererStyleContainer).
+ * @param shouldScrollToLocalId - Whether scroll-to-block functionality should be enabled
+ */
 export var useScrollToLocalId = function useScrollToLocalId(containerRef, shouldScrollToLocalId) {
   useEffect(function () {
     var _getDocument;
@@ -40,6 +51,9 @@ export var useScrollToLocalId = function useScrollToLocalId(containerRef, should
     if (typeof window === 'undefined' || !(containerRef !== null && containerRef !== void 0 && containerRef.current) || !shouldScrollToLocalId) {
       return;
     }
+    if (expValEquals('platform_editor_expand_on_scroll_to_block', 'isEnabled', true)) {
+      return;
+    }
 
     // Parse hash fragment for block ID (format: #block-{localId})
     var hash = window.location.hash;