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

package/useStream/useStream.mjs

@@ -0,0 +1,119 @@
+'use client';
+
+import * as React from 'react';
+import { streamChunks } from "./streamChunks.mjs";
+import { useStreamController } from "./useStreamController.mjs";
+import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
+
+/** Options for {@link useStream}. */
+
+/** Result of {@link useStream}. */
+
+/**
+ * Stream a list of chunks on the client and own a `StreamController` that scopes
+ * their coordination. Render the returned `chunks` as chunk components inside
+ * the returned `Controller`; each chunk registers its swap with the controller,
+ * and the list's completion (`markLast`) plus those swaps drive `loading`.
+ *
+ * The controller runs in `streaming` mode, so it stays `loading` until the list
+ * finishes streaming - at which point the chunks present can settle it.
+ *
+ * `refresh()` (and the opt-in `revalidateOnIdle`) re-stream the list in the
+ * background and swap the result in atomically when it completes, without a
+ * loading flash — the current list stays visible the whole time.
+ */
+export function useStream(options) {
+  const {
+    source,
+    loaderOptions,
+    channelKey,
+    revalidateOnIdle
+  } = options;
+  const {
+    Controller,
+    loading: controllerLoading,
+    markLast
+  } = useStreamController({
+    streaming: true,
+    channelKey
+  });
+  const [chunks, setChunks] = React.useState([]);
+  const [streamComplete, setStreamComplete] = React.useState(false);
+  const [revalidating, setRevalidating] = React.useState(false);
+  const [refreshToken, setRefreshToken] = React.useState(0);
+
+  // Set by `refresh()` so the stream effect can tell a background revalidation
+  // (keep the current list, swap on complete) from an initial / source-change
+  // stream (reveal progressively). Read-and-cleared at the start of the effect.
+  const refreshRef = React.useRef(false);
+  const refresh = React.useCallback(() => {
+    refreshRef.current = true;
+    setRefreshToken(token => token + 1);
+  }, []);
+  React.useEffect(() => {
+    const controller = new AbortController();
+    const isRefresh = refreshRef.current;
+    refreshRef.current = false;
+    if (isRefresh) {
+      setRevalidating(true);
+    }
+    (async () => {
+      try {
+        const stream = streamChunks(source, loaderOptions, controller.signal);
+        // Snapshots accumulate and reveal in order as the source streams.
+        let latest = [];
+        for await (const snapshot of stream) {
+          if (controller.signal.aborted) {
+            return;
+          }
+          latest = snapshot.chunks;
+          // Initial / source-change: reveal progressively. A background refresh
+          // holds the current list and swaps once below (stale-while-revalidate).
+          if (!isRefresh) {
+            setChunks(snapshot.chunks);
+            if (snapshot.lastChunk) {
+              setStreamComplete(true);
+              markLast();
+            }
+          }
+        }
+        if (isRefresh && !controller.signal.aborted) {
+          setChunks(latest);
+          setRevalidating(false);
+        }
+      } catch {
+        // Stream aborted by a newer run, or the loader failed.
+        if (isRefresh && !controller.signal.aborted) {
+          setRevalidating(false);
+        }
+      }
+    })();
+    return () => controller.abort();
+    // Re-stream when the source identity changes or a refresh is requested;
+    // options are read once at stream start, and `markLast` is stable.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [source, refreshToken]);
+
+  // Opt-in stale-while-revalidate: once the list has finished streaming,
+  // revalidate in the background on the first idle period. Browser-only.
+  React.useEffect(() => {
+    if (!revalidateOnIdle || !streamComplete || typeof window === 'undefined') {
+      return undefined;
+    }
+    return requestIdle(() => refresh());
+  }, [revalidateOnIdle, streamComplete, refresh]);
+
+  // Loading until the list has finished streaming AND every rendered chunk has
+  // settled. The controller's `loading` only reflects chunk swaps (it settles
+  // immediately when no chunks have registered yet), so combine it with the
+  // list-streaming state.
+  const loading = !streamComplete || controllerLoading;
+  return {
+    chunks,
+    Controller,
+    loading,
+    streamComplete,
+    revalidating,
+    refresh
+  };
+}

package/useStream/useStreamController.d.mts

@@ -0,0 +1,15 @@
+import type { UseStreamControllerOptions, UseStreamControllerResult } from "./types.mjs";
+/**
+ * Scope a group of chunks so the page can tell when they have all loaded.
+ *
+ * Returns a `Controller` provider to wrap the chunks in - it supplies the
+ * controller's gate as the ambient gate (via `CoordinatedGateContext`), so
+ * chunks rendered inside register their swap with it through `CoordinatedLazy`
+ * without a `gate` prop - and a reactive `loading` flag that stays `true` until
+ * every registered chunk settles. Completion resolves via the gate's
+ * **known-count** (`knownCount`) or **last-chunk** (`streaming` + `markLast`)
+ * signals; with neither, it opens as soon as the chunks present in the initial
+ * commit all settle. Each chunk also registers with the page-global gate (via
+ * `CoordinatedLazy`), so a page-wide coordinated commit waits for them too.
+ */
+export declare function useStreamController(options?: UseStreamControllerOptions): UseStreamControllerResult;

package/useStream/useStreamController.mjs

@@ -0,0 +1,90 @@
+'use client';
+
+import * as React from 'react';
+import { createSettleGate } from "../useCoordinated/createSettleGate.mjs";
+import { CoordinatedGateContext } from "../CoordinatedLazy/CoordinatedGateContext.mjs";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Scope a group of chunks so the page can tell when they have all loaded.
+ *
+ * Returns a `Controller` provider to wrap the chunks in - it supplies the
+ * controller's gate as the ambient gate (via `CoordinatedGateContext`), so
+ * chunks rendered inside register their swap with it through `CoordinatedLazy`
+ * without a `gate` prop - and a reactive `loading` flag that stays `true` until
+ * every registered chunk settles. Completion resolves via the gate's
+ * **known-count** (`knownCount`) or **last-chunk** (`streaming` + `markLast`)
+ * signals; with neither, it opens as soon as the chunks present in the initial
+ * commit all settle. Each chunk also registers with the page-global gate (via
+ * `CoordinatedLazy`), so a page-wide coordinated commit waits for them too.
+ */
+export function useStreamController(options = {}) {
+  const {
+    knownCount,
+    streaming = false,
+    safetyTimeoutMs
+  } = options;
+
+  // One gate per controller instance, configured once with its completion mode.
+  const [gate] = React.useState(() => {
+    const instance = createSettleGate(safetyTimeoutMs != null ? {
+      safetyTimeoutMs
+    } : undefined);
+    if (knownCount != null) {
+      instance.expect(knownCount);
+    } else if (streaming) {
+      // Hold open for an unknown-count stream until markLast.
+      instance.expect(Number.POSITIVE_INFINITY);
+    }
+    return instance;
+  });
+
+  // Stable provider that hands this instance's gate down as the ambient gate
+  // (created once; `gate` is stable for the controller's lifetime).
+  const [Controller] = React.useState(() => function StreamControllerProvider({
+    children
+  }) {
+    return /*#__PURE__*/_jsx(CoordinatedGateContext.Provider, {
+      value: gate,
+      children: children
+    });
+  });
+  const [loading, setLoading] = React.useState(() => knownCount !== 0);
+  React.useEffect(() => {
+    // Chunks register in their own (child) effects, which run before this
+    // (parent) effect - so by now the gate reflects every chunk present in the
+    // initial commit. These setState calls cannot move to render: at render
+    // time the gate is still unarmed, so `gate.isSettled()` returns `true` and a
+    // render-time derivation would wrongly report 'done' immediately. Only after
+    // the child effects register does the gate reflect the initial-commit chunks.
+    /* eslint-disable react-hooks/set-state-in-effect -- gate.isSettled() only reflects child chunks after their (child) effects register them; this parent effect runs after, so the value is unavailable during render */
+    if (gate.isSettled()) {
+      setLoading(false);
+      return undefined;
+    }
+    setLoading(true);
+    let cancelled = false;
+    const wait = gate.whenSettled();
+    if (wait) {
+      wait.then(() => {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }).catch(() => {});
+    } else {
+      setLoading(false);
+    }
+    /* eslint-enable react-hooks/set-state-in-effect */
+    return () => {
+      cancelled = true;
+    };
+  }, [gate]);
+  const markLast = React.useCallback(() => gate.markLast(), [gate]);
+  const setKnownCount = React.useCallback(count => gate.expect(count), [gate]);
+  return {
+    Controller,
+    loading,
+    gate,
+    markLast,
+    setKnownCount
+  };
+}

package/withDocsInfra/withDocsInfra.d.mts

@@ -71,6 +71,17 @@ export interface WithDocsInfraOptions {
    * Existing `client.ts` files are never overwritten.
    */
   requireDemoClient?: string;
+  /**
+   * When `true`, `pnpm docs-infra validate` ensures every demo `index.ts` matched by a
+   * `loadPrecomputedCodeHighlighter` demo rule has a sibling `page.tsx` that renders
+   * the demo as the route's default export, so each demo is browsable on its own page.
+   *
+   * The demo's export name is read from the `create*` factory call in `index.ts`, so the
+   * generated page imports the exact export (e.g. `import { DemoButton } from '.';`).
+   *
+   * Existing `page.tsx`/`page.ts` files are never overwritten.
+   */
+  requireDemoPage?: boolean;
   /**
    * Performance logging options
    */
@@ -111,6 +122,14 @@ export interface WithDocsInfraOptions {
    * Passed to `transformHtmlCodeBlock` through the types loader pipeline.
    */
   codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
+  /**
+   * When `true`, the demo loaders register the `TypescriptToJavascriptTransformer`
+   * so that TypeScript variants also produce a JavaScript counterpart at build time.
+   *
+   * Defaults to `false` because the transform is comparatively expensive;
+   * enable it when the rendered demos should expose both TS and JS sources.
+   */
+  transformTypescriptToJavascript?: boolean;
   /**
    * Name of the index file to update when syncing types metadata to parent indexes.
    * The types loader will call syncPageIndex to update the parent directory's index

package/withDocsInfra/withDocsInfra.mjs

@@ -76,7 +76,9 @@ export function withDocsInfra(options = {}) {
     notableCommentsPrefix,
     typesIndexFileName = 'page.mdx',
     errorIfTypesIndexOutOfDate = Boolean(process.env.CI),
-    requireDemoClient
+    requireDemoClient,
+    requireDemoPage = false,
+    transformTypescriptToJavascript = false
   } = options;
 
   // Only include ordering in loader options if explicitly provided
@@ -116,16 +118,22 @@ export function withDocsInfra(options = {}) {
       }),
       ...(demoEmphasisOptions && {
         emphasisOptions: demoEmphasisOptions
-      })
+      }),
+      ...(transformTypescriptToJavascript ? {
+        transformTypescriptToJavascript: true
+      } : {})
     };
 
-    // The demo highlighter options carry `requireClient` so the validate CLI can
-    // discover both the import specifier and the patterns it should ensure clients for.
-    // The loader itself ignores this option.
+    // The demo highlighter options carry `requireClient`/`requirePage` so the validate
+    // CLI can discover both the import specifier and the patterns it should ensure
+    // clients/pages for. The loader itself ignores these options.
     const demoCodeHighlighterOptions = {
       ...codeHighlighterOptions,
       ...(requireDemoClient ? {
         requireClient: requireDemoClient
+      } : {}),
+      ...(requireDemoPage ? {
+        requirePage: true
       } : {})
     };
     const turbopackRules = {

package/pipeline/loaderUtils/convertCommentsToOneIndexed.d.mts

@@ -1,8 +0,0 @@
-import type { SourceComments } from "../../CodeHighlighter/types.mjs";
-/**
- * Convert comments from 0-based to 1-based line numbers.
- *
- * `parseImportsAndComments` emits 0-based line numbers, but the rest of the
- * pipeline (HAST `dataLn`, source enhancers) uses 1-based lines.
- */
-export declare function convertCommentsToOneIndexed(comments: SourceComments | undefined): SourceComments | undefined;

package/pipeline/loaderUtils/convertCommentsToOneIndexed.mjs

@@ -1,16 +0,0 @@
-/**
- * Convert comments from 0-based to 1-based line numbers.
- *
- * `parseImportsAndComments` emits 0-based line numbers, but the rest of the
- * pipeline (HAST `dataLn`, source enhancers) uses 1-based lines.
- */
-export function convertCommentsToOneIndexed(comments) {
-  if (!comments) {
-    return undefined;
-  }
-  const converted = {};
-  for (const [lineStr, commentArray] of Object.entries(comments)) {
-    converted[parseInt(lineStr, 10) + 1] = commentArray;
-  }
-  return converted;
-}