@mui/internal-docs-infra 0.11.1-canary.8 → 0.11.1

package/useCodeWindow/useCodeWindow.d.mts

@@ -36,11 +36,28 @@ export type UseCodeWindowOptions = {
    */
   collapsibleProbeSelector?: string;
 };
-export type UseCodeWindowResult<ToggleElement extends HTMLElement = HTMLElement> = {
+export type UseCodeWindowResult<ToggleElement extends HTMLElement = HTMLElement, ScrollElement extends HTMLElement = HTMLElement> = {
   /**
    * Ref to attach to the collapsible container element.
    */
   containerRef: React.RefObject<HTMLDivElement | null>;
+  /**
+   * Optional ref to attach to a scrollable ancestor that should be
+   * compensated instead of the page. Attach it when the code block is
+   * rendered as a fixed-height "window" (its own `overflow: auto` region)
+   * so the anchor stays put against the panel's own scroll rather than the
+   * page. When left unattached, the page is compensated — the right default
+   * for code that grows the document flow. Forwarded from `useScrollAnchor`.
+   *
+   * When attached, this element is also treated as the horizontal scroll
+   * owner: the scrollbar-gutter swap (`data-scrollbar-gutter`) and the
+   * collapse scroll-back run on it instead of the inner `<pre>`. Use this when
+   * the window owns both scroll axes so the horizontal scrollbar sits at the
+   * window's edge (in view) rather than at the bottom of the inner `<pre>`,
+   * which can extend past the window's height and scroll out of view. Your
+   * gutter CSS must then key off this element's attribute.
+   */
+  scrollContainerRef: React.RefObject<ScrollElement | null>;
   /**
    * Ref to attach to the toggle element. Used as a fallback anchor
    * when the primary anchor is offscreen on collapse.
@@ -84,4 +101,4 @@ export type UseCodeWindowResult<ToggleElement extends HTMLElement = HTMLElement>
  * Anchor selection and the collapsible probe are configurable so it works
  * with any highlighter that marks frames with data attributes.
  */
-export declare function useCodeWindow<ToggleElement extends HTMLElement = HTMLElement>(options?: UseCodeWindowOptions): UseCodeWindowResult<ToggleElement>;
+export declare function useCodeWindow<ToggleElement extends HTMLElement = HTMLElement, ScrollElement extends HTMLElement = HTMLElement>(options?: UseCodeWindowOptions): UseCodeWindowResult<ToggleElement, ScrollElement>;

package/useCodeWindow/useCodeWindow.mjs

@@ -53,33 +53,38 @@ function cancelScheduled(handle) {
  * Smoothly slides the `<code>` element back to the left edge over `duration`
  * ms using an ease-out cubic via the Web Animations API.
  *
- * Used during collapse instead of tweening `pre.scrollLeft` because the
- * scrollbar-gutter animation forces `overflow-x: hidden` on the pre, which
+ * `scrollEl` is whichever element owns the horizontal scroll — the inner
+ * `<pre>` by default, or an attached scroll container (see `scrollContainerRef`)
+ * when the code block is rendered inside a fixed-size window. `code` is this
+ * code window's own `<code>` (scoped to its container by the caller) so a shared
+ * scroll container holding several blocks animates the right one.
+ *
+ * Used during collapse instead of tweening `scrollEl.scrollLeft` because the
+ * scrollbar-gutter animation forces `overflow-x: hidden` on `scrollEl`, which
  * snaps `scrollLeft` to 0 instantly. Animating a transform on the inner
  * `code` element produces the same visual effect, isn't reset by the overflow
- * change, and is naturally clipped by the pre's hidden overflow.
+ * change, and is naturally clipped by the scroll element's hidden overflow.
  *
  * Honors `prefers-reduced-motion` by snapping immediately.
  */
-function smoothCollapseScrollLeft(pre, duration) {
-  const startLeft = pre.scrollLeft;
+function smoothCollapseScrollLeft(scrollEl, code, duration) {
+  const startLeft = scrollEl.scrollLeft;
   if (startLeft <= 0) {
     return null;
   }
-  const code = pre.querySelector('code');
-  if (!code || typeof code.animate !== 'function') {
-    return null;
-  }
 
   // Cancel any leftover scroll-back animation from a previous toggle so we
   // don't end up with two transforms competing on the same element.
-  scrollbackAnimations.get(pre)?.cancel();
-  scrollbackAnimations.delete(pre);
+  scrollbackAnimations.get(scrollEl)?.cancel();
+  scrollbackAnimations.delete(scrollEl);
 
-  // Reset the actual scroll position now; the WAAPI animation visually
-  // compensates by translating the element from `-startLeft` back to `0`.
-  pre.scrollLeft = 0;
-  if (prefersReducedMotion() || duration <= 0) {
+  // Snap the actual scroll position back to the left edge now. When we can
+  // animate, the WAAPI transform below visually compensates by translating the
+  // element from `-startLeft` back to `0`; otherwise (no WAAPI, no `code`,
+  // reduced motion, or zero duration) this stands as an instant snap — still
+  // the correct collapsed end state.
+  scrollEl.scrollLeft = 0;
+  if (!code || typeof code.animate !== 'function' || prefersReducedMotion() || duration <= 0) {
     return null;
   }
   const anim = code.animate([{
@@ -91,10 +96,10 @@ function smoothCollapseScrollLeft(pre, duration) {
     easing: 'cubic-bezier(0, 0, 0.2, 1)',
     fill: 'none'
   });
-  scrollbackAnimations.set(pre, anim);
+  scrollbackAnimations.set(scrollEl, anim);
   const onSettle = () => {
-    if (scrollbackAnimations.get(pre) === anim) {
-      scrollbackAnimations.delete(pre);
+    if (scrollbackAnimations.get(scrollEl) === anim) {
+      scrollbackAnimations.delete(scrollEl);
     }
   };
   anim.finished.then(onSettle, onSettle);
@@ -106,74 +111,84 @@ function isElementInViewport(element) {
 }
 
 /**
- * Measures the horizontal scrollbar height of a `<pre>` element by
+ * Measures the horizontal scrollbar height of the scroll element by
  * temporarily forcing `overflow-x: scroll`.
  */
-function measureScrollbarHeight(pre) {
-  const prevOverflow = pre.style.overflowX;
-  pre.style.overflowX = 'scroll';
-  const scrollbarHeight = pre.offsetHeight - pre.clientHeight;
-  pre.style.overflowX = prevOverflow;
+function measureScrollbarHeight(scrollEl) {
+  const prevOverflow = scrollEl.style.overflowX;
+  scrollEl.style.overflowX = 'scroll';
+  const scrollbarHeight = scrollEl.offsetHeight - scrollEl.clientHeight;
+  scrollEl.style.overflowX = prevOverflow;
   return scrollbarHeight;
 }
-function clearGutterState(pre) {
-  cancelScheduled(gutterCleanupTimers.get(pre));
-  gutterCleanupTimers.delete(pre);
-  const flipTimer = gutterFlipTimers.get(pre);
+function clearGutterState(scrollEl) {
+  cancelScheduled(gutterCleanupTimers.get(scrollEl));
+  gutterCleanupTimers.delete(scrollEl);
+  const flipTimer = gutterFlipTimers.get(scrollEl);
   if (flipTimer !== undefined) {
     clearTimeout(flipTimer);
-    gutterFlipTimers.delete(pre);
+    gutterFlipTimers.delete(scrollEl);
   }
-  pre.removeAttribute(GUTTER_STATE_ATTRIBUTE);
+  scrollEl.removeAttribute(GUTTER_STATE_ATTRIBUTE);
 }
-function cancelAllForPre(pre) {
-  scrollbackAnimations.get(pre)?.cancel();
-  scrollbackAnimations.delete(pre);
-  clearGutterState(pre);
+function cancelAllForScrollEl(scrollEl) {
+  scrollbackAnimations.get(scrollEl)?.cancel();
+  scrollbackAnimations.delete(scrollEl);
+  clearGutterState(scrollEl);
 }
 
 /**
  * Drives a from→to transition on the `data-scrollbar-gutter` attribute of
- * `pre`, which the consumer's CSS hooks into to animate the swap between
- * a real scrollbar and equivalent padding-bottom.
+ * the scroll element, which the consumer's CSS hooks into to animate the swap
+ * between a real scrollbar and equivalent padding-bottom.
+ *
+ * `scrollEl` is whichever element owns the horizontal scroll — the inner
+ * `<pre>` by default, or the attached `scrollContainerRef` when the code block
+ * is rendered inside a fixed-size window. `code` is this code window's own
+ * `<code>` (scoped to its container by the caller).
  *
  * Skips the animation when content doesn't overflow (no scrollbar exists)
  * or when the browser uses overlay scrollbars (zero height).
  */
-function animateScrollbarGutter(pre, from, to, durationMs) {
-  const scrollbarHeight = measureScrollbarHeight(pre);
+function animateScrollbarGutter(scrollEl, code, from, to, durationMs) {
+  const scrollbarHeight = measureScrollbarHeight(scrollEl);
   if (scrollbarHeight === 0) {
     return; // Overlay scrollbars, nothing to do
   }
 
-  // For expand, check the inner code's scrollWidth (since `min-width:
-  // fit-content` reflects hidden frames). For collapse, the pre's own
-  // scrollWidth is enough.
-  if (from === 'expand-from') {
-    const code = pre.querySelector('code');
-    if (code && code.scrollWidth <= pre.clientWidth) {
-      return;
-    }
-  } else if (pre.scrollWidth <= pre.clientWidth) {
+  // Decide from this code window's own `<code>`, not from `scrollEl` — the
+  // scroll owner may be a shared container wrapping other content. `code`'s
+  // `scrollWidth` reflects hidden frames (via `min-width: fit-content`), so it
+  // predicts the post-expand width and still reflects the wide source during
+  // collapse; compare it against the scroll owner's visible width.
+  //
+  // Exception: a collapse-to-empty block (`data-focused-lines="0"`) shows
+  // nothing while collapsed, so its `scrollWidth` can't predict the post-expand
+  // width that way. On expand, run the swap anyway so `overflow-x` stays hidden
+  // through the reveal instead of flashing a scrollbar; if the expanded source
+  // turns out to fit, the swap simply ends without one. On collapse the current
+  // width is real, so the normal skip still applies.
+  const widthUnknownOnExpand = from === 'expand-from' && code?.getAttribute('data-focused-lines') === '0';
+  if (!code || !widthUnknownOnExpand && code.scrollWidth <= scrollEl.clientWidth) {
     return;
   }
-  clearGutterState(pre);
-  pre.setAttribute(GUTTER_STATE_ATTRIBUTE, from);
+  clearGutterState(scrollEl);
+  scrollEl.setAttribute(GUTTER_STATE_ATTRIBUTE, from);
 
   // Move into the transition state on the next macrotask. Tracked so the
   // flip can be cancelled if the component unmounts before it fires.
   const flipTimer = setTimeout(() => {
-    gutterFlipTimers.delete(pre);
-    pre.setAttribute(GUTTER_STATE_ATTRIBUTE, to);
+    gutterFlipTimers.delete(scrollEl);
+    scrollEl.setAttribute(GUTTER_STATE_ATTRIBUTE, to);
   }, 0);
-  gutterFlipTimers.set(pre, flipTimer);
+  gutterFlipTimers.set(scrollEl, flipTimer);
 
   // Schedule cleanup on the animation timeline so DevTools throttling
   // scales it together with the CSS transition.
-  const cleanup = scheduleOnAnimationTimeline(pre, durationMs + 30, () => {
-    clearGutterState(pre);
+  const cleanup = scheduleOnAnimationTimeline(scrollEl, durationMs + 30, () => {
+    clearGutterState(scrollEl);
   });
-  gutterCleanupTimers.set(pre, cleanup);
+  gutterCleanupTimers.set(scrollEl, cleanup);
 }
 const DEFAULT_ANCHOR_SELECTOR = '[data-frame-type="highlighted"], [data-frame-type="focus"]';
 const DEFAULT_COLLAPSIBLE_SELECTOR = '[data-collapsible]';
@@ -218,17 +233,18 @@ export function useCodeWindow(options = {}) {
     collapsibleProbeSelector = DEFAULT_COLLAPSIBLE_SELECTOR
   } = options;
   const toggleRef = React.useRef(null);
-  const lastPreRef = React.useRef(null);
+  const lastScrollElRef = React.useRef(null);
   const {
     containerRef,
+    scrollContainerRef,
     anchorScroll: rawAnchorScroll
   } = useScrollAnchor();
   React.useEffect(() => {
     return () => {
-      const pre = lastPreRef.current;
-      if (pre) {
-        cancelAllForPre(pre);
-        lastPreRef.current = null;
+      const scrollEl = lastScrollElRef.current;
+      if (scrollEl) {
+        cancelAllForScrollEl(scrollEl);
+        lastScrollElRef.current = null;
       }
     };
   }, []);
@@ -246,34 +262,45 @@ export function useCodeWindow(options = {}) {
     if (!anchor) {
       return;
     }
-    const pre = container.querySelector('pre');
-    if (pre) {
-      lastPreRef.current = pre;
+
+    // The element whose horizontal scrollbar we smooth: the attached scroll
+    // container when one is provided (the code block lives inside a
+    // fixed-size window that owns both scroll axes), otherwise the inner
+    // `<pre>`, which scrolls horizontally on its own.
+    const scrollEl = scrollContainerRef.current ?? container.querySelector('pre');
+    // Scope content lookups to *this* code window's `container`, never to
+    // `scrollEl`: an attached scroll container may wrap several code blocks or
+    // unrelated content, so `scrollEl.querySelector('code')` could match the
+    // wrong block. The overflow decision and scroll-back both use this code.
+    const code = container.querySelector('code');
+    if (scrollEl) {
+      lastScrollElRef.current = scrollEl;
       if (direction === 'collapse') {
         // Smoothly return horizontal scroll to the left edge. We animate
         // via a transform on the inner `code` element rather than
-        // tweening `pre.scrollLeft`, because the gutter animation below
+        // tweening `scrollEl.scrollLeft`, because the gutter animation below
         // sets `overflow-x: hidden` which would snap `scrollLeft` to 0
         // instantly. Both animations start in the same frame: the
         // scroll-back resets `scrollLeft` to 0 up front, so the gutter
         // swap's `overflow-x` change has nothing left to snap.
-        smoothCollapseScrollLeft(pre, scrollBackDuration);
-        animateScrollbarGutter(pre, 'collapse-from', 'collapse-to', collapseDuration);
+        smoothCollapseScrollLeft(scrollEl, code, scrollBackDuration);
+        animateScrollbarGutter(scrollEl, code, 'collapse-from', 'collapse-to', collapseDuration);
       }
       if (direction === 'expand') {
         // Cancel any in-flight collapse scroll-back so its leftover
         // transform can't drift the code horizontally during expand.
-        scrollbackAnimations.get(pre)?.cancel();
-        scrollbackAnimations.delete(pre);
-        if (collapsibleProbeSelector && pre.querySelector(collapsibleProbeSelector)) {
-          animateScrollbarGutter(pre, 'expand-from', 'expand-to', expandDuration);
+        scrollbackAnimations.get(scrollEl)?.cancel();
+        scrollbackAnimations.delete(scrollEl);
+        if (collapsibleProbeSelector && container.querySelector(collapsibleProbeSelector)) {
+          animateScrollbarGutter(scrollEl, code, 'expand-from', 'expand-to', expandDuration);
         }
       }
     }
     rawAnchorScroll(anchor, direction === 'collapse' ? collapseDuration : expandDuration);
-  }, [containerRef, rawAnchorScroll, anchorSelector, collapsibleProbeSelector, collapseDuration, expandDuration, scrollBackDuration]);
+  }, [containerRef, scrollContainerRef, rawAnchorScroll, anchorSelector, collapsibleProbeSelector, collapseDuration, expandDuration, scrollBackDuration]);
   return {
     containerRef,
+    scrollContainerRef,
     toggleRef,
     anchorScroll
   };