@mui/internal-docs-infra 0.12.1-canary.5 → 0.12.1-canary.50

package/CodeControllerContext/CodeControllerContext.d.mts

@@ -18,7 +18,7 @@ export interface CodeControllerContext {
    * code is always a string to simplify use. It will be highlighted when it is passed as `code`.
    * This behavior depends on client-side highlighting and the CodeProvider component.
    */
-  code?: ControlledCode;
+  code?: ControlledCode | null;
   /**
    * Controls the state for displaying the given code. This works with build-time and client-side
    * loading. If using server loading, the selection won't work for fallback loading and would
@@ -30,7 +30,7 @@ export interface CodeControllerContext {
    * called when the user interacts with the code highlighting. It's recommended to only set `code`
    * after the first `setCode` event fires to benefit from server or build-time rendering.
    */
-  setCode?: React.Dispatch<React.SetStateAction<ControlledCode | undefined>>;
+  setCode?: React.Dispatch<React.SetStateAction<ControlledCode | null>>;
   /**
    * Setter function for updating the selection state. When provided in the context, this function
    * will be called when the user interacts with the code highlighting interface.
@@ -43,6 +43,12 @@ export interface CodeControllerContext {
    * e.g. `{ variantA: {}, variantB: {} }`.
    */
   components?: Record<string, React.ReactNode> | undefined;
+  /**
+   * Current runtime error message per variant key (or `null` when the variant
+   * rendered cleanly), as reported by the preview components. Demos surface the
+   * selected variant's error via `useDemo().error`.
+   */
+  errors?: Record<string, string | null> | undefined;
   /**
    * Additional source enhancers to apply to parsed HAST sources.
    * These are merged with enhancers from CodeProvider and useCode opts.
@@ -52,13 +58,38 @@ export interface CodeControllerContext {
    * 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.
+   * has begun" (e.g. fetch the editable source, light up UI, or preload its live
+   * runtime). `deps` reports which file kinds the block spans — `js` when it has any
+   * JS/TS/JSX/TSX/MJS file, `css` when it has any CSS file — so the host can warm only
+   * the engine chunks it will need. `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;
+  onActivate?: (deps: {
+    js: boolean;
+    css: boolean;
+  }) => void;
 }
+/**
+ * Props a code-controller component receives: `children` to wrap and the optional
+ * `url` identifying the demo, plus any custom props `T` (typically a specific
+ * controller's options). Mirrors `ContentProps` — a small base extended by `T`.
+ */
+export type CodeControllerProps<T extends {} = {}> = {
+  children: React.ReactNode;
+  /**
+   * The demo's URL, supplied by the demo factory or passed explicitly so custom
+   * controllers can identify the demo they wrap.
+   */
+  url?: string;
+} & T;
+/**
+ * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
+ * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
+ * such as `useDemoController`. Parameterize with `T` for the controller's own props
+ * (e.g. `CodeController<UseDemoControllerOptions>`).
+ */
+export type CodeController<T extends {} = {}> = React.ComponentType<CodeControllerProps<T>>;
 export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
 /**
  * Hook to access controlled code state and setters. This is useful for custom
@@ -76,11 +107,15 @@ export declare const CodeControllerContext: React.Context<CodeControllerContext
  *   - components: Override components for the preview
  */
 export declare function useControlledCode(): {
-  code: ControlledCode | undefined;
+  code: ControlledCode | null;
   selection: Selection | undefined;
-  setCode: React.Dispatch<React.SetStateAction<ControlledCode | undefined>> | undefined;
+  setCode: React.Dispatch<React.SetStateAction<ControlledCode | null>> | undefined;
   setSelection: React.Dispatch<React.SetStateAction<Selection>> | undefined;
   components: Record<string, React.ReactNode> | undefined;
+  errors: Record<string, string | null> | undefined;
   sourceEnhancers: SourceEnhancers | undefined;
-  onActivate: (() => void) | undefined;
+  onActivate: ((deps: {
+    js: boolean;
+    css: boolean;
+  }) => void) | undefined;
 };

package/CodeControllerContext/CodeControllerContext.mjs

@@ -10,6 +10,19 @@ import * as React from 'react';
  * event fires.
  */
 
+/**
+ * Props a code-controller component receives: `children` to wrap and the optional
+ * `url` identifying the demo, plus any custom props `T` (typically a specific
+ * controller's options). Mirrors `ContentProps` — a small base extended by `T`.
+ */
+
+/**
+ * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
+ * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
+ * such as `useDemoController`. Parameterize with `T` for the controller's own props
+ * (e.g. `CodeController<UseDemoControllerOptions>`).
+ */
+
 export const CodeControllerContext = /*#__PURE__*/React.createContext(undefined);
 
 /**
@@ -31,11 +44,12 @@ if (process.env.NODE_ENV !== "production") CodeControllerContext.displayName = "
 export function useControlledCode() {
   const context = React.useContext(CodeControllerContext);
   return {
-    code: context?.code,
+    code: context?.code ?? null,
     selection: context?.selection,
     setCode: context?.setCode,
     setSelection: context?.setSelection,
     components: context?.components,
+    errors: context?.errors,
     sourceEnhancers: context?.sourceEnhancers,
     onActivate: context?.onActivate
   };

package/CodeHighlighter/CodeHighlighter.mjs

@@ -79,7 +79,8 @@ export function CodeHighlighter(props) {
   const renderChunk = options => {
     const userProps = {
       ...props,
-      code: options.preloaded,
+      code: props.loadPrecompute ? undefined : options.preloaded,
+      precompute: props.loadPrecompute ? options.preloaded : props.precompute,
       ContentLoading,
       initialVariant: initialKey,
       fallback: options.fallback,

package/CodeHighlighter/CodeHighlighterChunk.mjs

@@ -28,7 +28,8 @@ function CodeHighlighterChunkContent(props) {
   } = props;
   const clientProps = createClientProps({
     ...userProps,
-    code: data ?? userProps.code
+    code: userProps.loadPrecompute ? undefined : data ?? userProps.code,
+    precompute: userProps.loadPrecompute ? data ?? userProps.precompute : userProps.precompute
   });
   return /*#__PURE__*/_jsx(CodeHighlighterClient, {
     ...clientProps

package/CodeHighlighter/CodeHighlighterClient.d.mts

@@ -1,2 +1,3 @@
+import * as React from 'react';
 import type { CodeHighlighterClientProps } from "./types.mjs";
-export declare function CodeHighlighterClient(props: CodeHighlighterClientProps): import("react/jsx-runtime").JSX.Element;
+export declare function CodeHighlighterClient(props: CodeHighlighterClientProps): React.JSX.Element;