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

package/useCode/subscribeToggleNudge.mjs

@@ -0,0 +1,95 @@
+// Document-level subscriber registry for `<details>` toggle events. Each
+// `<Pre>` would otherwise install its own capture-phase listener; on docs
+// pages with many code blocks that's N listeners all firing on every
+// toggle anywhere in the document. A single shared listener fans out to
+// the relevant subscribers instead.
+//
+// Subscribers register their `<pre>` element so the dispatcher can do a
+// single `target.contains(pre)` ancestry check per subscriber and skip
+// the nudge entirely for unrelated toggles — no JS-side work runs in
+// `<Pre>` instances whose subtree the toggle didn't touch.
+//
+// The value is a Set rather than a single function so the registry
+// tolerates the (unlikely but possible) case where two `<Pre>` instances
+// transiently share the same DOM node — e.g. a fast unmount/remount
+// where the next mount's setup runs before the prior mount's cleanup.
+// Without the set the second subscribe would silently overwrite the
+// first nudge and a single unsubscribe would orphan the other instance.
+
+const toggleSubscribers = new Map();
+let toggleListenerAttached = false;
+let sharedToggleListener = null;
+
+// Reconcile the document-level capture listener with the current
+// subscriber set. Idempotent: callable from any code path (including
+// test teardowns that want to defensively assert no leaked listener)
+// without risk of leaving the document in a half-attached state.
+function syncToggleListener() {
+  if (typeof document === 'undefined') {
+    if (toggleSubscribers.size === 0) {
+      sharedToggleListener = null;
+      toggleListenerAttached = false;
+    }
+    return;
+  }
+  if (toggleSubscribers.size === 0) {
+    if (toggleListenerAttached && sharedToggleListener) {
+      document.removeEventListener('toggle', sharedToggleListener, true);
+    }
+    sharedToggleListener = null;
+    toggleListenerAttached = false;
+    return;
+  }
+  if (!toggleListenerAttached || !sharedToggleListener) {
+    sharedToggleListener = event => {
+      const target = event.target;
+      if (!(target instanceof Node)) {
+        return;
+      }
+      // Snapshot before iterating: a nudge may synchronously trigger an
+      // unmount that mutates `toggleSubscribers` mid-dispatch. Iterating
+      // a snapshot keeps dispatch order independent of subscriber
+      // mutations and matches the snapshot pattern used by
+      // `sweepDetachedFrames` / `nudgeFrameObserver`.
+      Array.from(toggleSubscribers).forEach(([preNode, nudges]) => {
+        // Centralized ancestry filter: only nudge subscribers whose `<pre>`
+        // is a descendant of the toggled element. Done here (rather than
+        // in each subscriber) so unrelated toggles short-circuit before
+        // any subscriber-side work runs.
+        if (!target.contains(preNode)) {
+          return;
+        }
+        Array.from(nudges).forEach(nudge => nudge());
+      });
+    };
+    document.addEventListener('toggle', sharedToggleListener, true);
+    toggleListenerAttached = true;
+  }
+}
+export function subscribeToggleNudge(preNode, nudge) {
+  // Defensive SSR no-op: there is no `document` to attach a listener to,
+  // and module state in Node persists across requests — leaking a
+  // subscriber here would also leak the closure it captures. `useEffect`
+  // already won't run on the server, but make the contract explicit so
+  // any future non-effect caller can't strand entries in the registry.
+  if (typeof document === 'undefined') {
+    return () => {};
+  }
+  let nudges = toggleSubscribers.get(preNode);
+  if (!nudges) {
+    nudges = new Set();
+    toggleSubscribers.set(preNode, nudges);
+  }
+  nudges.add(nudge);
+  syncToggleListener();
+  return () => {
+    const existing = toggleSubscribers.get(preNode);
+    if (existing) {
+      existing.delete(nudge);
+      if (existing.size === 0) {
+        toggleSubscribers.delete(preNode);
+      }
+    }
+    syncToggleListener();
+  };
+}

package/useCode/transformEngineCache.d.mts

@@ -0,0 +1,21 @@
+import type { CreateTransformedFiles } from "./TransformEngine.mjs";
+import type { TransformEngineLoader } from "../CodeProvider/CodeContext.mjs";
+/** Built-in loader, used when no provider supplies a `transformEngineLoader`. */
+export declare const defaultTransformEngineLoader: TransformEngineLoader;
+/** Synchronously reads the cached applier, or `undefined` if not yet resolved. */
+export declare function peekTransformEngine(): CreateTransformedFiles | undefined;
+/**
+ * Resolves the applier (from the warm cache, else via the loader) and caches it.
+ * Returns the cached value synchronously when warm. Rejects if the load fails;
+ * callers decide whether to surface or swallow that.
+ */
+export declare function loadTransformEngine(loader?: TransformEngineLoader): CreateTransformedFiles | Promise<CreateTransformedFiles>;
+/**
+ * Eagerly resolves and caches the applier so the next transform swap (and the
+ * first transform-bearing block's first render) build synchronously instead of
+ * flashing un-transformed files. Fire-and-forget — fails open. Pass the provider's
+ * `transformEngineLoader` to share its page-wide deduplication.
+ */
+export declare function preloadTransformEngine(loader?: TransformEngineLoader): Promise<void>;
+/** Clears the cache so the next resolve loads from scratch. For tests. */
+export declare function resetTransformEngineCache(): void;

package/useCode/transformEngineCache.mjs

@@ -0,0 +1,60 @@
+// Set DEBUG=true to log transform-engine load failures (e.g. a chunk-load error
+// after a rotated deploy, or offline). Off by default — a failed load fails open
+// (transforms simply don't apply) per convention 9.3.
+const DEBUG = false;
+
+// Module-level cache of the resolved transform applier (`createTransformedFiles`,
+// which pulls the `jsondiffpatch` chunk). Kept in this *light* module — which only
+// reaches the heavy chunk through the dynamic `import()` below — so it can be
+// primed by `CodeHighlighter`'s speculative preload (in the client chunk) AND read
+// by `useTransformManagement` (in the content chunk) without either statically
+// pulling the other in. The first transform-bearing block resolves it once; every
+// block after reads it synchronously, so the swap-commit build stays synchronous.
+let cached;
+
+/** Built-in loader, used when no provider supplies a `transformEngineLoader`. */
+export const defaultTransformEngineLoader = () => import("./TransformEngine.mjs").then(mod => mod.createTransformedFiles);
+
+/** Synchronously reads the cached applier, or `undefined` if not yet resolved. */
+export function peekTransformEngine() {
+  return cached;
+}
+
+/**
+ * Resolves the applier (from the warm cache, else via the loader) and caches it.
+ * Returns the cached value synchronously when warm. Rejects if the load fails;
+ * callers decide whether to surface or swallow that.
+ */
+export function loadTransformEngine(loader) {
+  if (cached) {
+    return cached;
+  }
+  return (loader ?? defaultTransformEngineLoader)().then(create => {
+    cached = create;
+    return create;
+  });
+}
+
+/**
+ * Eagerly resolves and caches the applier so the next transform swap (and the
+ * first transform-bearing block's first render) build synchronously instead of
+ * flashing un-transformed files. Fire-and-forget — fails open. Pass the provider's
+ * `transformEngineLoader` to share its page-wide deduplication.
+ */
+export async function preloadTransformEngine(loader) {
+  if (cached) {
+    return;
+  }
+  try {
+    await loadTransformEngine(loader);
+  } catch (error) {
+    if (DEBUG) {
+      console.error('[docs-infra] transform engine failed to preload', error);
+    }
+  }
+}
+
+/** Clears the cache so the next resolve loads from scratch. For tests. */
+export function resetTransformEngineCache() {
+  cached = undefined;
+}

package/useCode/useCode.d.mts

@@ -3,7 +3,6 @@ import type { ContentProps, SourceEnhancers } from "../CodeHighlighter/types.mjs
 import { type UseCopierOpts } from "../useCopier/index.mjs";
 export type UseCodeOpts = {
   preClassName?: string;
-  defaultOpen?: boolean;
   copy?: UseCopierOpts;
   githubUrlPrefix?: string;
   initialVariant?: string;
@@ -31,6 +30,116 @@ export type UseCodeOpts = {
    * Disables editing of the code block even when a CodeControllerContext is present.
    */
   disabled?: boolean;
+  /**
+   * Called when the code block is asked to expand its collapsed window — most
+   * importantly from the editor itself, when the caret navigates past the
+   * visible region (e.g. `ArrowUp` at the top of a collapsed block). Fires
+   * synchronously, *before* the expansion re-renders, so a host can capture the
+   * still-collapsed layout and engage a scroll anchor (e.g. `useCodeWindow`'s
+   * `anchorScroll('expand')`) — matching the timing of a click on the expand
+   * toggle. Without this, keyboard-driven expansion would jump the viewport
+   * instead of smoothly anchoring it.
+   */
+  onExpand?: () => void;
+  /**
+   * Delay in milliseconds between a transform change and the actual swap
+   * of the rendered file tree to the new transform. `selectedTransform`
+   * still updates synchronously so UI controls reflect the change
+   * immediately — whether triggered by a user click in this demo or
+   * received as an external broadcast from a peer demo. While the swap
+   * is pending the rendered `<pre>` element receives a `data-transforming`
+   * attribute so consumer CSS can run an exit animation — most notably
+   * expanding `.collapse` placeholders back to their original height —
+   * before the new tree replaces them. When omitted or `0`, the new
+   * transform commits synchronously (default behavior).
+   */
+  transformDelay?: number;
+  /**
+   * Delay in milliseconds between a variant change and the actual
+   * swap of the rendered file tree to the new variant. `selectedVariant`
+   * still updates synchronously so UI controls (tabs, dropdowns)
+   * reflect the change immediately — whether triggered by a user
+   * click in this demo or received as an external broadcast from a
+   * peer demo. While the swap is pending the rendered `<pre>` element
+   * receives a `data-transforming` attribute, and `<Pre>` appends a
+   * bridge `<span class="collapse">` to the shorter of the two
+   * variants' rendered tree so consumer CSS can animate between the
+   * two heights before the swap commits. When omitted or `0`, the
+   * new variant commits synchronously (default behavior).
+   */
+  variantSwapDelay?: number;
+  /**
+   * Controls which transforms are treated as layout-affecting (phase 1,
+   * coordinated barrier) versus non-layout (phase 2, deferred). All
+   * options consult the precomputed `hasCollapse` /
+   * `hasCollapseInFocus` flags on each transform manifest entry — no
+   * tree walking happens at runtime.
+   *
+   *   - `'all'` — Phase 1 if *any* file (main or `extraFiles`) in the
+   *     selected variant has `hasCollapse: true`. Most conservative;
+   *     matches the historical pre-`transformLayoutShift` behavior.
+   *   - `'selected'` (default) — Phase 1 only when the currently
+   *     rendered file's transform has `hasCollapse: true`. Avoids
+   *     coordinating swaps that wouldn't visibly shift the rendered
+   *     pre.
+   *   - `'focus'` — Like `'selected'`, but while the surrounding code
+   *     block is *collapsed* (un-expanded), use `hasCollapseInFocus`
+   *     instead of `hasCollapse`. A `.collapse` placeholder outside
+   *     the initially-visible region (the lines covered by
+   *     `data-frame-type` ∈ `'highlighted' | 'focus' | 'padding-top' |
+   *     'padding-bottom'`) won't trigger the coordinated barrier
+   *     because the user can't see the resulting layout shift. Falls
+   *     back to `'selected'`-style behavior when expanded.
+   */
+  transformLayoutShift?: 'all' | 'selected' | 'focus';
+  /**
+   * When `true`, throws synchronously during render if any transform
+   * on any variant has `hasCollapseInFocus: true` — i.e. its
+   * `.collapse` placeholder lands inside the focus region that is
+   * visible while the surrounding code block is un-expanded. The
+   * thrown error names the offending variant/file/transform so the
+   * demo author can narrow the `@focus` (or `@padding`) markers, or
+   * shrink the transform's edit range, until the placeholder lands
+   * outside the initially-visible window. Pair with
+   * `transformLayoutShift: 'focus'` to guarantee no coordinated
+   * barrier swaps fire while the block is collapsed.
+   */
+  strictCollapseInFocus?: boolean;
+  /**
+   * Controls which variant swaps are treated as layout-affecting
+   * (phase 1, coordinated barrier) versus non-layout (phase 2,
+   * deferred). The check consults `totalLines` / `focusedLines`
+   * metadata precomputed by the pipeline — no tree walking happens
+   * at runtime.
+   *
+   *   - `'all'` — Phase 1 when the sum of `totalLines` across every
+   *     file (main + `extraFiles`) differs between the from-variant
+   *     and the to-variant. Useful when the rendering surface shows
+   *     all files simultaneously.
+   *   - `'selected'` (default) — Phase 1 when the currently selected
+   *     file's `totalLines` differs between the two variants (or
+   *     the file is missing from one side). Avoids coordinating
+   *     swaps that wouldn't visibly shift the rendered pre.
+   *   - `'focus'` — Like `'selected'`, but while the surrounding
+   *     code block is *collapsed* (un-expanded), compare
+   *     `focusedLines` (the size of the visible window when
+   *     collapsed) instead of `totalLines`. Recommended for demos
+   *     that use `@focus` / `@padding` markers to collapse to a
+   *     specific region.
+   */
+  variantLayoutShift?: 'all' | 'selected' | 'focus';
+  /**
+   * When `true`, throws synchronously during render if any two
+   * variants declare a file with the same name but a different
+   * `focusedLines` count. Pair with `variantLayoutShift: 'focus'`
+   * to guarantee no coordinated barrier swaps fire while the block
+   * is collapsed: when every shared file's focused window matches
+   * across variants, switching variants can never shift the
+   * collapsed pre's height. The thrown error names the offending
+   * variants / file so the demo author can align the
+   * `@focus` / `@padding` markers.
+   */
+  strictMatchingVariantFocusedLines?: boolean;
 };
 type UserProps<T extends {} = {}> = T & {
   name?: string;
@@ -54,6 +163,13 @@ export interface UseCodeResult<T extends {} = {}> {
    * the variant has no `url` or the URL cannot be resolved.
    */
   selectedFileUrl: string | undefined;
+  /**
+   * Slug for the currently selected file. Always derived from the canonical
+   * (original) file name — transforms are a view preference and do not
+   * produce separate slugs. Useful for building permalinks (e.g. `#${slug}`)
+   * that survive transform changes.
+   */
+  selectedFileSlug: string | undefined;
   selectFileName: (fileName: string) => void;
   allFilesSlugs: Array<{
     fileName: string;
@@ -72,6 +188,21 @@ export interface UseCodeResult<T extends {} = {}> {
   availableTransforms: string[];
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;
+  /**
+   * Target of an in-flight transform swap that is still waiting on
+   * slow peers to catch up. `undefined` when no swap is pending or
+   * shortly after one commits. Otherwise mirrors the shape of
+   * `selectedTransform`: `null` for a pending swap back to the
+   * un-transformed original, or the transform name for a pending
+   * swap to that transform. Consumers can check
+   * `pendingTransform !== undefined` to render a generic loading
+   * indicator, or read the value to render something like
+   * `` `Switching to ${pendingTransform ?? 'original'}…` ``. Only
+   * populated on the demo that originated the change — peer demos
+   * receiving the broadcast keep this `undefined` so the indicator
+   * stays anchored to the demo the user interacted with.
+   */
+  pendingTransform: string | null | undefined;
   /**
    * Replace the source of the currently selected file (or `fileName` when
    * provided) in the controlled code. Internal hooks may pass additional
@@ -87,6 +218,14 @@ export interface UseCodeResult<T extends {} = {}> {
    * is in scope and editing is not disabled.
    */
   reset?: () => void;
+  /**
+   * Re-fetches the block's data on the client by re-running the full variant
+   * loader, then swaps in the fresh result while keeping the current highlighted
+   * output visible until the new tree lands (stale-while-revalidate). Invalidates
+   * the pre-parsed HAST cache. `undefined` (or a no-op) for a block with no `url`
+   * to re-fetch from, or with no `CodeProvider` in scope.
+   */
+  refresh?: () => void;
   userProps: UserProps<T>;
 }
 export declare function useCode<T extends {} = {}>(contentProps: ContentProps<T>, opts?: UseCodeOpts): UseCodeResult<T>;