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

package/ChunkProvider/ChunkContext.d.mts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import type { ChunkContextValue } from "./types.mjs";
+/**
+ * Supplies the lazily-resolved client `StreamSource` to descendant chunks.
+ * `undefined` outside a `ChunkProvider` - a chunk then relies on its own config
+ * source (or stays in its loading/preloaded state).
+ */
+export declare const ChunkContext: React.Context<ChunkContextValue<unknown, unknown> | undefined>;
+/** Read the surrounding `ChunkProvider`, or `undefined` when there is none. */
+export declare function useChunkContext(): ChunkContextValue | undefined;

package/ChunkProvider/ChunkContext.mjs

@@ -0,0 +1,15 @@
+'use client';
+
+import * as React from 'react';
+/**
+ * Supplies the lazily-resolved client `StreamSource` to descendant chunks.
+ * `undefined` outside a `ChunkProvider` - a chunk then relies on its own config
+ * source (or stays in its loading/preloaded state).
+ */
+export const ChunkContext = /*#__PURE__*/React.createContext(undefined);
+
+/** Read the surrounding `ChunkProvider`, or `undefined` when there is none. */
+if (process.env.NODE_ENV !== "production") ChunkContext.displayName = "ChunkContext";
+export function useChunkContext() {
+  return React.useContext(ChunkContext);
+}

package/ChunkProvider/ChunkProvider.d.mts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { ChunkProviderProps } from "./types.mjs";
+/**
+ * Layout-level provider that supplies a client `StreamSource` to descendant
+ * chunks, dynamically importing the loader module only when a chunk first needs
+ * to load - so the loaders stay out of the initial bundle and are never
+ * imported when chunks are precomputed/preloaded. The import promise is cached,
+ * so many chunks share one fetch (mirrors how `CodeProvider` lazily provides
+ * its parser/loaders).
+ */
+export declare function ChunkProvider<P, O>({
+  children,
+  source
+}: ChunkProviderProps<P, O>): React.ReactElement;

package/ChunkProvider/ChunkProvider.mjs

@@ -0,0 +1,38 @@
+'use client';
+
+import * as React from 'react';
+import { ChunkContext } from "./ChunkContext.mjs";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Layout-level provider that supplies a client `StreamSource` to descendant
+ * chunks, dynamically importing the loader module only when a chunk first needs
+ * to load - so the loaders stay out of the initial bundle and are never
+ * imported when chunks are precomputed/preloaded. The import promise is cached,
+ * so many chunks share one fetch (mirrors how `CodeProvider` lazily provides
+ * its parser/loaders).
+ */
+export function ChunkProvider({
+  children,
+  source
+}) {
+  // Hold the in-flight/resolved import so the first caller triggers the import
+  // and the rest reuse its promise. Written only inside the callback (never
+  // during render).
+  const cacheRef = React.useRef(null);
+  const resolveSource = React.useCallback(() => {
+    if (!cacheRef.current) {
+      cacheRef.current = source().then(loaded => loaded.default);
+    }
+    return cacheRef.current;
+  }, [source]);
+  const value = React.useMemo(() => ({
+    resolveSource
+  }), [resolveSource]);
+
+  // The context is intentionally `unknown`-generic; consumers narrow at the use
+  // site. Casting here is the one untyped seam for the provider's generics.
+  return /*#__PURE__*/_jsx(ChunkContext.Provider, {
+    value: value,
+    children: children
+  });
+}

package/ChunkProvider/PreloadContext.d.mts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+/**
+ * Memoize a preload by key: the first call with a given `key` runs `factory`
+ * and caches its promise; later calls with the same key return that promise. So
+ * many instances that need the same helper share one dynamic `import()` (and
+ * one round of any work the factory does) instead of each kicking off their own.
+ */
+export type PreloadFn = <T>(key: string, factory: () => Promise<T>) => Promise<T>;
+/**
+ * Provides the cross-instance `PreloadFn`. `undefined` outside a
+ * `PreloadProvider` - `usePreload` then falls back to calling the factory
+ * directly (the browser's module cache still dedups identical `import()`s).
+ */
+export declare const PreloadContext: React.Context<PreloadFn | undefined>;

package/ChunkProvider/PreloadContext.mjs

@@ -0,0 +1,18 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Memoize a preload by key: the first call with a given `key` runs `factory`
+ * and caches its promise; later calls with the same key return that promise. So
+ * many instances that need the same helper share one dynamic `import()` (and
+ * one round of any work the factory does) instead of each kicking off their own.
+ */
+
+/**
+ * Provides the cross-instance `PreloadFn`. `undefined` outside a
+ * `PreloadProvider` - `usePreload` then falls back to calling the factory
+ * directly (the browser's module cache still dedups identical `import()`s).
+ */
+export const PreloadContext = /*#__PURE__*/React.createContext(undefined);
+if (process.env.NODE_ENV !== "production") PreloadContext.displayName = "PreloadContext";

package/ChunkProvider/PreloadProvider.d.mts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+/**
+ * Scopes a cross-instance preload cache (typically at a layout). Descendants
+ * call `usePreload` to start dynamic imports of shared helpers keyed by a
+ * stable string; the first call per key runs the factory and every other
+ * instance reuses its promise - so a helper a chunk's data implies (a transform
+ * fn, say) is fetched once, in parallel with the content, across the page.
+ */
+export declare function PreloadProvider({
+  children
+}: {
+  children: React.ReactNode;
+}): React.ReactElement;

package/ChunkProvider/PreloadProvider.mjs

@@ -0,0 +1,33 @@
+'use client';
+
+import * as React from 'react';
+import { PreloadContext } from "./PreloadContext.mjs";
+
+/**
+ * Scopes a cross-instance preload cache (typically at a layout). Descendants
+ * call `usePreload` to start dynamic imports of shared helpers keyed by a
+ * stable string; the first call per key runs the factory and every other
+ * instance reuses its promise - so a helper a chunk's data implies (a transform
+ * fn, say) is fetched once, in parallel with the content, across the page.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export function PreloadProvider({
+  children
+}) {
+  // One cache per provider instance, stable across renders.
+  const [cache] = React.useState(() => new Map());
+  const preload = React.useCallback((key, factory) => {
+    const existing = cache.get(key);
+    if (existing) {
+      // Same key -> same factory type by contract; the consumer owns the keying.
+      return existing;
+    }
+    const promise = factory();
+    cache.set(key, promise);
+    return promise;
+  }, [cache]);
+  return /*#__PURE__*/_jsx(PreloadContext.Provider, {
+    value: preload,
+    children: children
+  });
+}

package/ChunkProvider/index.d.mts

@@ -0,0 +1,7 @@
+export { ChunkProvider } from "./ChunkProvider.mjs";
+export { ChunkContext, useChunkContext } from "./ChunkContext.mjs";
+export { usePreload } from "./usePreload.mjs";
+export { PreloadProvider } from "./PreloadProvider.mjs";
+export { PreloadContext } from "./PreloadContext.mjs";
+export type { ChunkContextValue, ChunkProviderProps } from "./types.mjs";
+export type { PreloadFn } from "./PreloadContext.mjs";

package/ChunkProvider/index.mjs

@@ -0,0 +1,7 @@
+export { ChunkProvider } from "./ChunkProvider.mjs";
+export { ChunkContext, useChunkContext } from "./ChunkContext.mjs";
+
+// Cross-instance preload dedup ships with the provider surface.
+export { usePreload } from "./usePreload.mjs";
+export { PreloadProvider } from "./PreloadProvider.mjs";
+export { PreloadContext } from "./PreloadContext.mjs";

package/ChunkProvider/types.d.mts

@@ -0,0 +1,23 @@
+import type * as React from 'react';
+import type { StreamSource } from "../CoordinatedLazy/types.mjs";
+/**
+ * Provided by a `ChunkProvider`: lazily resolve the client `StreamSource` for
+ * descendant chunks. Called only when a chunk actually needs to load (i.e. it
+ * was not preloaded), so the loader module stays out of the initial bundle and
+ * is never imported when everything is precomputed.
+ */
+export interface ChunkContextValue<P = unknown, O = unknown> {
+  resolveSource: () => Promise<StreamSource<P, O>>;
+}
+/** Props for {@link ChunkProvider}. */
+export interface ChunkProviderProps<P = unknown, O = unknown> {
+  children: React.ReactNode;
+  /**
+   * Dynamic import of the client source module - its `default` export is the
+   * {@link StreamSource}. Imported once, lazily, on the first chunk that needs
+   * to load; the resolved promise is shared across descendants.
+   */
+  source: () => Promise<{
+    default: StreamSource<P, O>;
+  }>;
+}

package/ChunkProvider/types.mjs

@@ -0,0 +1 @@
+export {};

package/ChunkProvider/usePreload.d.mts

@@ -0,0 +1,8 @@
+import { type PreloadFn } from "./PreloadContext.mjs";
+/**
+ * Returns the cross-instance `PreloadFn` from the surrounding
+ * `PreloadProvider`, or a direct-call fallback when there is none. Use it inside
+ * a `CoordinatedLazy` `preload(hoisted)` callback to start importing helpers the
+ * hoisted data implies, deduped across every instance on the page.
+ */
+export declare function usePreload(): PreloadFn;

package/ChunkProvider/usePreload.mjs

@@ -0,0 +1,21 @@
+'use client';
+
+import * as React from 'react';
+import { PreloadContext } from "./PreloadContext.mjs";
+
+/**
+ * Calls the factory directly when there is no `PreloadProvider`. The browser's
+ * module cache still dedups identical `import()`s, so this only loses the
+ * cross-instance memo of the factory's own work.
+ */
+const fallbackPreload = (_key, factory) => factory();
+
+/**
+ * Returns the cross-instance `PreloadFn` from the surrounding
+ * `PreloadProvider`, or a direct-call fallback when there is none. Use it inside
+ * a `CoordinatedLazy` `preload(hoisted)` callback to start importing helpers the
+ * hoisted data implies, deduped across every instance on the page.
+ */
+export function usePreload() {
+  return React.useContext(PreloadContext) ?? fallbackPreload;
+}

package/CodeControllerContext/CodeControllerContext.d.mts

@@ -48,6 +48,16 @@ export interface CodeControllerContext {
    * These are merged with enhancers from CodeProvider and useCode opts.
    */
   sourceEnhancers?: SourceEnhancers;
+  /**
+   * Called once when a block in this controller's scope first activates for
+   * editing — immediately for `editActivation: 'eager'`, or on first engagement
+   * (hover / focus / click) for `'interaction'`. Lets the host react to "editing
+   * has begun" (e.g. fetch the editable source, light up UI). `CodeHighlighter`
+   * separately warms its own live-editing dependencies (engine, grammars, worker)
+   * at the same moment, so a host that only wants the default behavior can leave
+   * this unset.
+   */
+  onActivate?: () => void;
 }
 export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
 /**
@@ -72,4 +82,5 @@ export declare function useControlledCode(): {
   setSelection: React.Dispatch<React.SetStateAction<Selection>> | undefined;
   components: Record<string, React.ReactNode> | undefined;
   sourceEnhancers: SourceEnhancers | undefined;
+  onActivate: (() => void) | undefined;
 };

package/CodeControllerContext/CodeControllerContext.mjs

@@ -36,6 +36,7 @@ export function useControlledCode() {
     setCode: context?.setCode,
     setSelection: context?.setSelection,
     components: context?.components,
-    sourceEnhancers: context?.sourceEnhancers
+    sourceEnhancers: context?.sourceEnhancers,
+    onActivate: context?.onActivate
   };
 }

package/CodeHighlighter/CodeHighlighter.d.mts

@@ -1,2 +1,16 @@
+import * as React from 'react';
 import type { CodeHighlighterProps } from "./types.mjs";
-export declare function CodeHighlighter<T extends {}>(props: CodeHighlighterProps<T>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Isomorphic entry for a code block. Validates and normalizes props, then maps them
+ * onto the generic {@link CodeHighlighterChunk} (a `createCoordinatedLazy` chunk):
+ * the decision inputs (`controlled`/`isInitial`/`forceClient`) computed by
+ * {@link buildCodeHighlighterChunkProps} route between rendering the client directly
+ * (precomputed content), dynamically importing the server `Loader` (load all
+ * variants), or the server `InitialLoader` (load a quick initial first). When a
+ * `ContentLoading` and an initial paint are available, the loading fallback +
+ * compressed residual are prepared up front via {@link prepareInitialSource}.
+ *
+ * The heavy load/parse pipeline lives behind the dynamically-imported loaders, so it
+ * never reaches the path that renders precomputed content.
+ */
+export declare function CodeHighlighter<T extends {}>(props: CodeHighlighterProps<T>): React.ReactElement;