@mui/internal-docs-infra 0.7.1-canary.4 → 0.8.1-canary.0

package/CodeHighlighter/CodeHighlighter.mjs

@@ -109,7 +109,7 @@ async function CodeSourceLoader(props) {
         }
       }
     }
-    let output = 'hastGzip';
+    let output = 'hastCompressed';
     if (props.deferParsing === 'json') {
       output = 'hastJson';
     } else if (props.deferParsing === 'none') {
@@ -248,7 +248,7 @@ async function CodeInitialSourceLoader(props) {
   if (!url) {
     throw new Errors.ErrorCodeHighlighterServerMissingUrl();
   }
-  let output = 'hastGzip';
+  let output = 'hastCompressed';
   if (props.deferParsing === 'json') {
     output = 'hastJson';
   } else if (props.deferParsing === 'none') {

package/CodeHighlighter/types.d.mts

@@ -29,7 +29,7 @@ export interface HastRoot extends Root {
 export type VariantSource = string | HastRoot | {
   hastJson: string;
 } | {
-  hastGzip: string;
+  hastCompressed: string;
 };
 /**
  * Additional files associated with a code variant.
@@ -182,7 +182,7 @@ export interface LoadFileOptions {
   /** Output format for the loaded file
    * @default 'hast'
    */
-  output?: 'hast' | 'hastJson' | 'hastGzip';
+  output?: 'hast' | 'hastJson' | 'hastCompressed';
 }
 /**
  * Options for the loadCodeVariant function, extending LoadFileOptions with required function dependencies

package/abstractCreateTypes/TypeCode.d.mts

@@ -0,0 +1,43 @@
+import * as React from 'react';
+import type { FallbackNode } from "../pipeline/hastUtils/fallbackFormat.mjs";
+type HighlightAt = 'hydration' | 'idle' | 'visible';
+interface TypeCodeProps {
+  /** JSON-serialized HAST tree (root > pre > code > children). */
+  hastJson?: string;
+  /** DEFLATE-compressed, base64-encoded HAST tree. */
+  hastCompressed?: string;
+  /** When to replace the fallback with the fully-highlighted version. */
+  highlightAt: HighlightAt;
+  /**
+   * Links-only fallback (code children with highlighting spans stripped),
+   * in compact `FallbackNode[]` format.
+   * Serves two purposes:
+   * 1. Rendered as the initial display until the full highlight is ready.
+   * 2. Its text content is used as a DEFLATE dictionary for decompression
+   *    when `hastCompressed` was compressed with that same text dictionary.
+   */
+  fallback?: FallbackNode[];
+  /** Props for the `<code>` element wrapper (className, etc.). */
+  codeProps?: Record<string, unknown>;
+}
+/**
+ * Renders a links-only fallback on the server and replaces it with the
+ * fully syntax-highlighted version on the client at the configured time.
+ *
+ * When `fallback` is provided, it is converted to HAST and rendered for the
+ * initial display. Its text content is derived (via `fallbackToText`) to serve
+ * as the DEFLATE dictionary for decompressing `hastCompressed`.
+ *
+ * - `'hydration'`: parse immediately on mount.
+ * - `'idle'`: defer to `requestIdleCallback` regardless of visibility.
+ * - `'visible'`: wait until the element enters the viewport (IntersectionObserver),
+ *   then defer to `requestIdleCallback` to avoid blocking scroll or paint.
+ */
+export declare function TypeCode({
+  hastJson,
+  hastCompressed,
+  highlightAt,
+  fallback,
+  codeProps
+}: TypeCodeProps): React.DetailedReactHTMLElement<React.HTMLAttributes<HTMLElement>, HTMLElement> | React.DetailedReactHTMLElement<Record<string, unknown>, HTMLElement>;
+export {};

package/abstractCreateTypes/TypeCode.mjs

@@ -0,0 +1,166 @@
+'use client';
+
+import * as React from 'react';
+import { decompressHast, hastToJsx } from "../pipeline/hastUtils/index.mjs";
+import { useCodeComponents } from "../useCode/CodeComponentsContext.mjs";
+import { fallbackToHast, fallbackToText } from "../pipeline/hastUtils/fallbackFormat.mjs";
+/**
+ * Find the children of the first `<code>` element in a parsed HAST tree.
+ */
+function findCodeChildren(node) {
+  if (node.type === 'element' && node.tagName === 'code') {
+    return node.children;
+  }
+  for (const child of node.children) {
+    if (child.type === 'element') {
+      const found = findCodeChildren(child);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Renders a links-only fallback on the server and replaces it with the
+ * fully syntax-highlighted version on the client at the configured time.
+ *
+ * When `fallback` is provided, it is converted to HAST and rendered for the
+ * initial display. Its text content is derived (via `fallbackToText`) to serve
+ * as the DEFLATE dictionary for decompressing `hastCompressed`.
+ *
+ * - `'hydration'`: parse immediately on mount.
+ * - `'idle'`: defer to `requestIdleCallback` regardless of visibility.
+ * - `'visible'`: wait until the element enters the viewport (IntersectionObserver),
+ *   then defer to `requestIdleCallback` to avoid blocking scroll or paint.
+ */
+export function TypeCode({
+  hastJson,
+  hastCompressed,
+  highlightAt,
+  fallback,
+  codeProps
+}) {
+  const components = useCodeComponents();
+  // Determine the effective mode: fall back to 'idle' when IntersectionObserver
+  // is unavailable (progressive enhancement for older browsers/runtimes).
+  const effectiveMode = highlightAt === 'visible' && (typeof IntersectionObserver === 'undefined' || typeof ResizeObserver === 'undefined') ? 'idle' : highlightAt;
+  const [hast, setHast] = React.useState(null);
+  const [isVisible, setIsVisible] = React.useState(effectiveMode !== 'visible');
+  const [codeElement, setCodeElement] = React.useState(null);
+
+  // Synchronize visibility state when the effective mode changes.
+  React.useEffect(() => {
+    setIsVisible(effectiveMode !== 'visible');
+  }, [effectiveMode]);
+
+  // Convert compact fallback to HAST for rendering.
+  const fallbackHastRoot = React.useMemo(() => fallback ? fallbackToHast(fallback) : undefined, [fallback]);
+
+  // Derive text dictionary from fallback for decompression.
+  const textDictionary = React.useMemo(() => fallback ? fallbackToText(fallback) : undefined, [fallback]);
+
+  // Render fallback HAST as JSX for initial display.
+  const fallbackJsx = React.useMemo(() => fallbackHastRoot ? hastToJsx(fallbackHastRoot, components) : null, [fallbackHastRoot, components]);
+
+  // Observe visibility for 'visible' mode: decompress when scrolled into view,
+  // release expanded HAST when scrolled away to reduce memory pressure.
+  //
+  // Three complementary observers cover different visibility triggers:
+  // - IntersectionObserver: scroll-based viewport entry/exit.
+  // - ResizeObserver: ancestor layout changes (CSS-based tabs, accordions)
+  //   that resize the element without necessarily triggering IO.
+  // - Document 'toggle' listener (capture phase): native <details> elements
+  //   whose toggle event does not bubble and may not trigger IO or RO.
+  React.useEffect(() => {
+    if (effectiveMode !== 'visible' || !codeElement) {
+      return undefined;
+    }
+    const updateVisibility = inViewport => {
+      if (inViewport) {
+        setIsVisible(true);
+      } else {
+        setIsVisible(false);
+        setHast(null);
+      }
+    };
+    const io = new IntersectionObserver(([entry]) => {
+      updateVisibility(entry.isIntersecting);
+    });
+    io.observe(codeElement);
+
+    // Force IO to re-evaluate without a synchronous getBoundingClientRect call.
+    const nudgeObserver = () => {
+      io.unobserve(codeElement);
+      io.observe(codeElement);
+    };
+    const ro = new ResizeObserver(nudgeObserver);
+    ro.observe(codeElement);
+
+    // Native <details> toggle events don't bubble, but capture-phase
+    // listeners on the document still intercept them. Re-check visibility
+    // whenever any <details> on the page opens or closes.
+    document.addEventListener('toggle', nudgeObserver, true);
+    return () => {
+      io.disconnect();
+      ro.disconnect();
+      document.removeEventListener('toggle', nudgeObserver, true);
+    };
+  }, [effectiveMode, codeElement]);
+
+  // Parse and decompress once visible.
+  React.useEffect(() => {
+    if (!isVisible) {
+      return undefined;
+    }
+    const parse = () => {
+      if (hastCompressed == null && hastJson == null) {
+        return;
+      }
+      try {
+        const raw = hastCompressed ? decompressHast(hastCompressed, textDictionary) : hastJson;
+        const parsed = JSON.parse(raw);
+
+        // Extract code element's children from the full tree.
+        const root = parsed.type === 'root' ? parsed : {
+          type: 'root',
+          children: Array.isArray(parsed) ? parsed : [parsed]
+        };
+        const codeChildren = findCodeChildren(root);
+        const hastRoot = {
+          type: 'root',
+          children: codeChildren ?? root.children
+        };
+        setHast(hastRoot);
+      } catch (error) {
+        console.warn('Failed to parse highlighted code HAST; rendering fallback instead.', error);
+      }
+    };
+    if (effectiveMode === 'hydration') {
+      parse();
+      return undefined;
+    }
+
+    // 'idle' and 'visible' both defer to idle time to avoid blocking the main thread.
+    if (typeof requestIdleCallback !== 'undefined') {
+      const id = requestIdleCallback(parse, {
+        timeout: 2000
+      });
+      return () => cancelIdleCallback(id);
+    }
+    const id = setTimeout(parse, 0);
+    return () => clearTimeout(id);
+  }, [isVisible, hastJson, hastCompressed, effectiveMode, textDictionary]);
+  const highlighted = React.useMemo(() => hast !== null ? hastToJsx(hast, components) : null, [hast, components]);
+  const content = highlighted ?? fallbackJsx;
+
+  // 'hydration' and 'idle' parse without visibility gating — no observer needed.
+  if (effectiveMode !== 'visible') {
+    return /*#__PURE__*/React.createElement('code', codeProps, content);
+  }
+  return /*#__PURE__*/React.createElement('code', {
+    ...codeProps,
+    ref: setCodeElement
+  }, content);
+}

package/abstractCreateTypes/abstractCreateTypes.d.mts

@@ -97,6 +97,12 @@ export type TypesTableMeta = {
    * Pass an empty array to disable all inline enhancers.
    */
   enhancersInline?: PluggableList;
+  /**
+   * Controls when expensive detailedType and formattedCode HAST fields are
+   * converted to fully-highlighted JSX.
+   * When set, overrides the factory-level highlightAt.
+   */
+  highlightAt?: TypesJsxOptions['highlightAt'];
   /**
    * Custom component tag name to use instead of `<a>` for type reference links.
    * When set, enhanceCodeTypes emits elements with this tag name,
@@ -243,6 +249,12 @@ export type AbstractCreateTypesOptions<T extends {} = {}> = {
    * Can be overridden by TypesTableMeta.defaultImportSlug.
    */
   defaultImportSlug?: string;
+  /**
+   * Controls when expensive detailedType and formattedCode HAST fields are
+   * converted to fully-highlighted JSX.
+   * Can be overridden by TypesTableMeta.highlightAt.
+   */
+  highlightAt?: TypesJsxOptions['highlightAt'];
 };
 export declare function abstractCreateTypes<T extends {}>(options: AbstractCreateTypesOptions<T>, url: string, meta: TypesTableMeta | undefined, exportName?: string): React.ComponentType<T>;
 export declare function createTypesFactory<T extends {}>(options: AbstractCreateTypesOptions<T>): (url: string, typeDef: object, meta?: TypesTableMeta | undefined) => React.ComponentType<T>;

package/abstractCreateTypes/abstractCreateTypes.mjs

@@ -42,6 +42,7 @@ export function abstractCreateTypes(options, url, meta, exportName) {
   const ShortTypeCode = meta.ShortTypeCode ?? options.ShortTypeCode;
   const DefaultCode = meta.DefaultCode ?? options.DefaultCode;
   const RawTypePre = meta.RawTypePre ?? options.RawTypePre;
+  const highlightAt = meta.highlightAt ?? options.highlightAt;
 
   // Enhancers from meta completely override options.enhancers if set
   // Use DEFAULT_ENHANCERS if neither meta nor options specify enhancers
@@ -126,7 +127,8 @@ export function abstractCreateTypes(options, url, meta, exportName) {
       DefaultCode,
       RawTypePre,
       enhancers,
-      enhancersInline
+      enhancersInline,
+      highlightAt
     },
     // Include additionalTypes for:
     // 1. Single component mode (createTypes)
@@ -213,6 +215,7 @@ function createAdditionalTypesComponent(options, url, meta) {
   const ShortTypeCode = meta.ShortTypeCode ?? options.ShortTypeCode;
   const DefaultCode = meta.DefaultCode ?? options.DefaultCode;
   const RawTypePre = meta.RawTypePre ?? options.RawTypePre;
+  const highlightAt = meta.highlightAt ?? options.highlightAt;
 
   // Enhancers from meta completely override options.enhancers if set
   // Use DEFAULT_ENHANCERS if neither meta nor options specify enhancers
@@ -273,7 +276,8 @@ function createAdditionalTypesComponent(options, url, meta) {
       DefaultCode,
       RawTypePre,
       enhancers,
-      enhancersInline
+      enhancersInline,
+      highlightAt
     }), []);
     return /*#__PURE__*/_jsx(options.TypesTable, {
       ...props,

package/abstractCreateTypes/typesToJsx.d.mts

@@ -1,3 +1,4 @@
+import * as React from 'react';
 import type { PluggableList } from 'unified';
 import type { HighlightedComponentTypeMeta, HighlightedHookTypeMeta, HighlightedFunctionTypeMeta, HighlightedClassTypeMeta, HighlightedRawTypeMeta, HighlightedEnumMemberMeta, HighlightedTypesMeta, HighlightedProperty, HighlightedParameter, HighlightedMethod, HighlightedClassProperty } from "../pipeline/loadServerTypes/index.mjs";
 import type { FormattedEnumMember } from "../pipeline/loadServerTypesMeta/index.mjs";
@@ -56,6 +57,15 @@ export type TypesJsxOptions = {
    * Applied instead of the full enhancers for these compact fields.
    */
   enhancersInline?: PluggableList;
+  /**
+   * Controls when expensive detailedType and formattedCode HAST fields are
+   * converted to fully-highlighted JSX.
+   * - `'init'`: convert immediately during SSG
+   * - `'hydration'`: server-render a links-only fallback, highlight on client mount
+   * - `'idle'`: server-render a links-only fallback, highlight when browser is idle
+   * - `'visible'`: server-render a links-only fallback, highlight when scrolled into view (default)
+   */
+  highlightAt?: 'init' | 'hydration' | 'idle' | 'visible';
 };
 /**
  * An enhanced property with HAST fields converted to React nodes.