@mui/internal-docs-infra 0.11.1-canary.16 → 0.11.1-canary.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.11.1-canary.16",
+  "version": "0.11.1-canary.17",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -768,5 +768,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "4c7e314cf1f7d63fe80e86d6e3c84fc7d15a053e"
+  "gitSha": "5f0871264ec4d7c78d5fd7e62888de0f7bf61cda"
 }

package/useCode/EditableEngine.mjs

@@ -1146,12 +1146,19 @@ export const createEditableEngine = ctx => {
           state.repeatFlushId = null;
           // The user may have moved focus or cleared the selection in the
           // 100ms since the last repeat keydown (e.g. clicked elsewhere,
-          // unmounted, blurred). The debounced flush is best-effort; if
-          // there's no live selection inside the editable any more, skip
-          // — the next real event will pick up state. Without this guard
-          // `getPosition` throws from a stray timer after teardown.
+          // unmounted, blurred). The debounced flush is best-effort; if the
+          // engine is gone or there's no live selection inside the editable
+          // any more, skip — the next real event will pick up state.
+          //
+          // Bail out before touching `window`: a stray timer can fire after
+          // teardown, and in a test environment the `window` global may already
+          // be removed, so `window.getSelection()` would throw a `ReferenceError`
+          // (an unhandled rejection that can mask real failures).
+          if (state.disconnected || typeof window === 'undefined') {
+            return;
+          }
           const selection = window.getSelection();
-          if (state.disconnected || !selection || selection.rangeCount === 0 || !element.contains(selection.getRangeAt(0).startContainer)) {
+          if (!selection || selection.rangeCount === 0 || !element.contains(selection.getRangeAt(0).startContainer)) {
             return;
           }
           flushChanges();

package/useCodeWindow/useCodeWindow.d.mts

@@ -48,6 +48,14 @@ export type UseCodeWindowResult<ToggleElement extends HTMLElement = HTMLElement,
    * 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>;
   /**

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,76 @@ 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.
+  if (!code || 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,7 +225,7 @@ 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,
@@ -226,10 +233,10 @@ export function useCodeWindow(options = {}) {
   } = 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;
       }
     };
   }, []);
@@ -247,32 +254,42 @@ 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,

package/useScrollAnchor/useScrollAnchor.mjs

@@ -42,10 +42,16 @@ export function useScrollAnchor() {
     activeSessionCleanupRef.current = null;
 
     // Snapshot the scroll target at session start so a later ref change
-    // doesn't redirect compensation mid-flight.
-    const scrollTarget = scrollContainerRef.current ?? window;
+    // doesn't redirect compensation mid-flight. `scrollElement` is the attached
+    // container (if any); `scrollTarget` is what receives the user-interaction
+    // listeners (the container or the window).
+    const scrollElement = scrollContainerRef.current;
+    const scrollTarget = scrollElement ?? window;
     const interactionTarget = scrollTarget;
-    const initialTop = anchor.getBoundingClientRect().top;
+
+    // Mutable so it can be re-baselined when an attached container can't yet
+    // absorb a delta (see below).
+    let initialTop = anchor.getBoundingClientRect().top;
     let active = true;
     let cleanupTimer;
 
@@ -58,8 +64,25 @@ export function useScrollAnchor() {
         return;
       }
       const delta = anchor.getBoundingClientRect().top - initialTop;
-      if (Math.abs(delta) > 0.5) {
-        scrollTarget.scrollBy(0, delta);
+      if (Math.abs(delta) <= 0.5) {
+        return;
+      }
+      if (!scrollElement) {
+        window.scrollBy(0, delta);
+        return;
+      }
+      const before = scrollElement.scrollTop;
+      scrollElement.scrollBy(0, delta);
+      const remainder = delta - (scrollElement.scrollTop - before);
+      if (Math.abs(remainder) > 0.5) {
+        // The container couldn't absorb this part — it isn't scrollable yet
+        // (its content hasn't exceeded its `max-height`). Re-baseline instead
+        // of forcing the difference elsewhere: scrolling the page would shift
+        // the surrounding layout, and carrying the delta forward would snap the
+        // anchor back the instant the container becomes scrollable. Accepting
+        // the small drift now keeps the surrounding layout still and lets the
+        // container hold the anchor smoothly from here on.
+        initialTop += remainder;
       }
     });
     function cleanup() {