@mui/internal-docs-infra 0.6.1-canary.3 → 0.7.1-canary.1

package/CodeControllerContext/CodeControllerContext.d.mts

@@ -46,9 +46,10 @@ export interface CodeControllerContext {
 }
 export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
 /**
- * Hook for accessing the controlled code context.
- *
- * This hook provides access to the controlled code, selection state, and setter functions
+ * Hook to access controlled code state and setters. This is useful for custom
+ * components that need to interact with the controlled code state. Use useCode
+ * instead when you need access to the code data along with control functions.
+ * Use this hook when you need direct access to the setCode and setSelection functions
  * from the CodeControllerContext. It's worth noting that useCode and useDemo handle
  * controlling selection in typical cases.
  *
@@ -59,4 +60,10 @@ export declare const CodeControllerContext: React.Context<CodeControllerContext
  *   - setSelection: Function to update the selection
  *   - components: Override components for the preview
  */
-export declare function useControlledCode(): CodeControllerContext | undefined;
+export declare function useControlledCode(): {
+  code: ControlledCode | undefined;
+  selection: Selection | undefined;
+  setCode: React.Dispatch<React.SetStateAction<ControlledCode | undefined>> | undefined;
+  setSelection: React.Dispatch<React.SetStateAction<Selection>> | undefined;
+  components: Record<string, React.ReactNode> | undefined;
+};

package/CodeControllerContext/CodeControllerContext.mjs

@@ -13,9 +13,10 @@ import * as React from 'react';
 export const CodeControllerContext = /*#__PURE__*/React.createContext(undefined);
 
 /**
- * Hook for accessing the controlled code context.
- *
- * This hook provides access to the controlled code, selection state, and setter functions
+ * Hook to access controlled code state and setters. This is useful for custom
+ * components that need to interact with the controlled code state. Use useCode
+ * instead when you need access to the code data along with control functions.
+ * Use this hook when you need direct access to the setCode and setSelection functions
  * from the CodeControllerContext. It's worth noting that useCode and useDemo handle
  * controlling selection in typical cases.
  *
@@ -29,5 +30,11 @@ export const CodeControllerContext = /*#__PURE__*/React.createContext(undefined)
 if (process.env.NODE_ENV !== "production") CodeControllerContext.displayName = "CodeControllerContext";
 export function useControlledCode() {
   const context = React.useContext(CodeControllerContext);
-  return context;
+  return {
+    code: context?.code,
+    selection: context?.selection,
+    setCode: context?.setCode,
+    setSelection: context?.setSelection,
+    components: context?.components
+  };
 }

package/CodeExternalsContext/CodeExternalsContext.d.mts

@@ -1,8 +1,22 @@
 import * as React from 'react';
+/** Represents any imported module or object that can be provided as an external dependency */
 type Module = NonNullable<unknown>;
+/**
+ * Context interface for providing external dependencies to demo components.
+ * Used by demo client providers to make precomputed externals available to child components.
+ */
 export interface CodeExternalsContext {
+  /** Map of module specifiers to their imported values (e.g., { 'react': React, '@mui/material': { Button } }) */
   externals?: Record<string, Module>;
 }
+/**
+ * React context for managing external dependencies in demo components.
+ * Primarily used internally by demo client providers created with abstractCreateDemoClient.
+ */
 export declare const CodeExternalsContext: React.Context<CodeExternalsContext | undefined>;
+/**
+ * Hook to access external dependencies from the CodeExternalsContext.
+ * Returns undefined if used outside of a provider.
+ */
 export declare function useCodeExternals(): CodeExternalsContext | undefined;
 export {};

package/CodeExternalsContext/CodeExternalsContext.mjs

@@ -1,7 +1,24 @@
 'use client';
 
 import * as React from 'react';
+
+/** Represents any imported module or object that can be provided as an external dependency */
+
+/**
+ * Context interface for providing external dependencies to demo components.
+ * Used by demo client providers to make precomputed externals available to child components.
+ */
+
+/**
+ * React context for managing external dependencies in demo components.
+ * Primarily used internally by demo client providers created with abstractCreateDemoClient.
+ */
 export const CodeExternalsContext = /*#__PURE__*/React.createContext(undefined);
+
+/**
+ * Hook to access external dependencies from the CodeExternalsContext.
+ * Returns undefined if used outside of a provider.
+ */
 if (process.env.NODE_ENV !== "production") CodeExternalsContext.displayName = "CodeExternalsContext";
 export function useCodeExternals() {
   return React.useContext(CodeExternalsContext);

package/CodeHighlighter/types.d.mts

@@ -133,6 +133,13 @@ export type TransformSource = (source: string, fileName: string) => Promise<Reco
   source: string;
   fileName?: string;
 }> | undefined>;
+/**
+ * Parses source code into a HAST tree with syntax highlighting.
+ *
+ * @param source - The source code to parse and highlight
+ * @param fileName - File name used to detect language via file extension
+ * @param language - Optional explicit language override (e.g., 'tsx', 'css', 'typescript')
+ */
 export type ParseSource = (source: string, fileName: string, language?: string) => HastRoot;
 export type SourceTransformer = {
   extensions: string[];

package/CodeProvider/CodeContext.d.mts

@@ -13,19 +13,36 @@ export type ParseCodeFn = (code: Code, parseSource: ParseSource) => Code;
 export type ParseControlledCodeFn = (controlledCode: ControlledCode, parseSource: ParseSource) => Code;
 export type ComputeHastDeltasFn = (parsedCode: Code, parseSource: ParseSource) => Promise<Code>;
 export type GetAvailableTransformsFn = (parsedCode: Code | undefined, variantName: string) => string[];
+/**
+ * Context interface for code processing functions.
+ * Provides heavy functions via context that can't be serialized across the server-client boundary.
+ */
 export interface CodeContext {
+  /** Async parser promise for initial loading */
   sourceParser?: Promise<ParseSource>;
+  /** Sync parser available after initial load completes */
   parseSource?: ParseSource;
+  /** Source transformers for code transformation (e.g., TypeScript to JavaScript) */
   sourceTransformers?: SourceTransformers;
+  /** Source enhancers for modifying parsed HAST */
   sourceEnhancers?: SourceEnhancers;
+  /** Function to load raw source code and dependencies */
   loadSource?: LoadSource;
+  /** Function to load specific variant metadata */
   loadVariantMeta?: LoadVariantMeta;
+  /** Function to load code metadata from a URL */
   loadCodeMeta?: LoadCodeMeta;
+  /** Heavy function: Loads fallback code with all variants and files */
   loadCodeFallback?: LoadFallbackCodeFn;
+  /** Heavy function: Loads a specific code variant with its dependencies */
   loadCodeVariant?: LoadVariantFn;
+  /** Heavy function: Parses code strings into HAST nodes */
   parseCode?: ParseCodeFn;
+  /** Heavy function: Parses controlled code for editable demos */
   parseControlledCode?: ParseControlledCodeFn;
+  /** Heavy function: Computes HAST deltas for code transformations */
   computeHastDeltas?: ComputeHastDeltasFn;
+  /** Heavy function: Gets available transform keys for a variant */
   getAvailableTransforms?: GetAvailableTransformsFn;
 }
 export declare const CodeContext: React.Context<CodeContext>;

package/CodeProvider/CodeContext.mjs

@@ -4,6 +4,11 @@ import * as React from 'react';
 
 // Type definitions for the heavy functions we're moving to context
 
+/**
+ * Context interface for code processing functions.
+ * Provides heavy functions via context that can't be serialized across the server-client boundary.
+ */
+
 export const CodeContext = /*#__PURE__*/React.createContext({});
 if (process.env.NODE_ENV !== "production") CodeContext.displayName = "CodeContext";
 export const useCodeContext = () => {

package/CodeProvider/CodeProvider.d.mts

@@ -1,5 +1,13 @@
 import * as React from 'react';
 import type { LoadCodeMeta, LoadSource, LoadVariantMeta, SourceEnhancers } from "../CodeHighlighter/types.mjs";
+/**
+ * Provides client-side functions for fetching source code and highlighting it.
+ * Designed for cases where you need to render code blocks or demos based on
+ * client-side state or dynamic content loading.
+ *
+ * Implements the Props Context Layering pattern by providing heavy functions
+ * via context that can't be serialized across the server-client boundary.
+ */
 export declare function CodeProvider({
   children,
   loadCodeMeta,
@@ -7,9 +15,13 @@ export declare function CodeProvider({
   loadSource,
   sourceEnhancers
 }: {
+  /** Child components that will have access to the code handling context */
   children: React.ReactNode;
+  /** Function to load code metadata from a URL */
   loadCodeMeta?: LoadCodeMeta;
+  /** Function to load specific variant metadata */
   loadVariantMeta?: LoadVariantMeta;
+  /** Function to load raw source code and dependencies */
   loadSource?: LoadSource;
   sourceEnhancers?: SourceEnhancers;
 }): import("react/jsx-runtime").JSX.Element;

package/CodeProvider/CodeProvider.mjs

@@ -11,6 +11,15 @@ import { loadCodeVariant } from "../pipeline/loadCodeVariant/loadCodeVariant.mjs
 import { parseCode } from "../pipeline/loadCodeVariant/parseCode.mjs";
 import { parseControlledCode } from "../CodeHighlighter/parseControlledCode.mjs";
 import { computeHastDeltas, getAvailableTransforms } from "../pipeline/loadCodeVariant/computeHastDeltas.mjs";
+
+/**
+ * Provides client-side functions for fetching source code and highlighting it.
+ * Designed for cases where you need to render code blocks or demos based on
+ * client-side state or dynamic content loading.
+ *
+ * Implements the Props Context Layering pattern by providing heavy functions
+ * via context that can't be serialized across the server-client boundary.
+ */
 import { jsx as _jsx } from "react/jsx-runtime";
 export function CodeProvider({
   children,

package/abstractCreateDemoClient/abstractCreateDemoClient.d.mts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { Externals } from "../CodeHighlighter/types.mjs";
-type CreateDemoClientMeta = {
+export type CreateDemoClientMeta = {
   name?: string;
   slug?: string;
   displayName?: string;

package/abstractCreateTypes/abstractCreateTypes.d.mts

@@ -0,0 +1,252 @@
+import * as React from 'react';
+import type { PluggableList } from 'unified';
+import type { HighlightedTypesMeta } from '@mui/internal-docs-infra/pipeline/loadServerTypes';
+import type { ModuleLinkMapEntry } from "../pipeline/enhanceCodeTypes/scanState.mjs";
+import { type TypesJsxOptions } from "./typesToJsx.mjs";
+import type { TypesTableProps } from "../useTypes/useTypes.mjs";
+/**
+ * Export data structure containing a main type and its related additional types.
+ * Used in the precompute field for structured type data.
+ */
+export interface ExportData {
+  /** The main component/hook/function type for this export */
+  type: HighlightedTypesMeta;
+  /** Related types like .Props, .State, .ChangeEventDetails for this export */
+  additionalTypes: HighlightedTypesMeta[];
+}
+export type TypesTableMeta = {
+  precompute?: {
+    /**
+     * Structured export data where each export has a main type and related additional types.
+     * Keys are export names like "Root", "Trigger", etc.
+     */
+    exports: Record<string, ExportData>;
+    /**
+     * Top-level types that are not namespaced under any component part
+     * and not claimed by any variant-only group.
+     */
+    additionalTypes: HighlightedTypesMeta[];
+    /**
+     * Types belonging to variant-only groups (variants with no main export).
+     * Keyed by variant name, containing the types from that variant.
+     * Separated from `additionalTypes` to avoid duplication.
+     */
+    variantOnlyAdditionalTypes?: Record<string, HighlightedTypesMeta[]>;
+    /**
+     * Maps variant names to the type names that originated from that variant.
+     * Used for namespace imports (e.g., `* as Types`) to filter additionalTypes
+     * to only show types from that specific module.
+     */
+    variantTypeNames?: Record<string, string[]>;
+    singleComponentName?: string;
+    /**
+     * Platform-scoped anchor maps for linking type references in code.
+     * Used by enhanceCodeTypes to create links to type documentation.
+     */
+    anchorMap?: {
+      js?: Record<string, string>;
+      css?: Record<string, string>;
+    };
+  };
+  name?: string;
+  displayName?: string;
+  disableOptimization?: boolean;
+  watchSourceDirectly?: boolean;
+  /**
+   * When true, excludes this component from the parent index page.
+   * The component types will still be processed, but won't be added to the index.
+   */
+  excludeFromIndex?: boolean;
+  components?: TypesJsxOptions['components'];
+  /**
+   * Override pre component for type code blocks.
+   * When set, overrides the factory-level TypePre.
+   */
+  TypePre?: TypesJsxOptions['TypePre'];
+  /**
+   * Override pre component for detailed type blocks.
+   * When set, overrides the factory-level DetailedTypePre.
+   */
+  DetailedTypePre?: TypesJsxOptions['DetailedTypePre'];
+  /**
+   * Override code component for shortType fields.
+   * When set, overrides the factory-level ShortTypeCode.
+   */
+  ShortTypeCode?: TypesJsxOptions['ShortTypeCode'];
+  /**
+   * Override code component for default value fields.
+   * When set, overrides the factory-level DefaultCode.
+   */
+  DefaultCode?: TypesJsxOptions['DefaultCode'];
+  /**
+   * Override pre component for raw type formatted code blocks.
+   * When set, overrides the factory-level RawTypePre.
+   */
+  RawTypePre?: TypesJsxOptions['RawTypePre'];
+  /**
+   * Rehype plugins to run on HAST before converting to JSX.
+   * If set, completely overrides enhancers from AbstractCreateTypesOptions.
+   * Defaults to `[enhanceCodeInline]` when undefined.
+   * Pass an empty array to disable all enhancers.
+   */
+  enhancers?: PluggableList;
+  /**
+   * Rehype plugins to run on inline HAST fields (shortType and default).
+   * If set, completely overrides enhancersInline from AbstractCreateTypesOptions.
+   * Defaults to `[enhanceCodeInline]` when undefined.
+   * Pass an empty array to disable all inline enhancers.
+   */
+  enhancersInline?: PluggableList;
+  /**
+   * Custom component tag name to use instead of `<a>` for type reference links.
+   * When set, enhanceCodeTypes emits elements with this tag name,
+   * adding a `name` property (the matched identifier) alongside `href`.
+   * This enables interactive type popovers via a `TypeRef` component.
+   */
+  typeRefComponent?: string;
+  /**
+   * Custom component tag name to use instead of a plain HTML element
+   * for property references within type definitions, object literals, function calls, and JSX.
+   * For definitions the element receives `id`, for references it receives `href`.
+   * Both also receive `name` (owner) and `prop` (kebab-case property path).
+   */
+  typePropRefComponent?: string;
+  /**
+   * Custom component tag name to use instead of a plain HTML element
+   * for function parameter references.
+   * For definitions the element receives `id`, for references it receives `href`.
+   * Both also receive `name` (owner) and `param` (parameter name).
+   */
+  typeParamRefComponent?: string;
+  /**
+   * Opt-in property linking mode for enhanceCodeTypes.
+   * - `'shallow'`: Link only top-level properties of known owners.
+   * - `'deep'`: Link nested properties with dotted paths (e.g., `address.street-name`).
+   * - `undefined` (default): No property linking.
+   */
+  linkProps?: 'shallow' | 'deep';
+  /**
+   * Opt-in function parameter linking for enhanceCodeTypes.
+   * When `true`, links function parameter names to documentation anchors.
+   */
+  linkParams?: boolean;
+  /**
+   * Opt-in scope-based variable linking for enhanceCodeTypes.
+   * When `true`, links variable references to the type from their declaration
+   * using single-pass scope tracking.
+   */
+  linkScope?: boolean;
+  /**
+   * Module import linking map for enhanceCodeTypes.
+   * Maps module specifiers to their documentation page and exports.
+   */
+  moduleLinkMap?: {
+    js?: Record<string, ModuleLinkMapEntry>;
+    css?: Record<string, ModuleLinkMapEntry>;
+  };
+  /**
+   * Default anchor slug for default/namespace imports when the module entry
+   * in `moduleLinkMap` does not specify a `defaultSlug`.
+   */
+  defaultImportSlug?: string;
+};
+export type AbstractCreateTypesOptions<T extends {} = {}> = {
+  TypesTable: React.ComponentType<TypesTableProps<T>>;
+  components?: TypesJsxOptions['components'];
+  /**
+   * Required pre component for type code blocks.
+   * Type signatures are not precomputed, so this has a different
+   * contract from `components.pre`.
+   * Can be overridden by TypesTableMeta.TypePre.
+   */
+  TypePre: TypesJsxOptions['TypePre'];
+  /**
+   * Optional pre component for detailed type blocks.
+   * Falls back to `TypePre` when not provided.
+   * Can be overridden by TypesTableMeta.DetailedTypePre.
+   */
+  DetailedTypePre?: TypesJsxOptions['DetailedTypePre'];
+  /**
+   * Optional code component for shortType fields.
+   * Falls back to `components.code` when not provided.
+   * Can be overridden by TypesTableMeta.ShortTypeCode.
+   */
+  ShortTypeCode?: TypesJsxOptions['ShortTypeCode'];
+  /**
+   * Optional code component for default value fields.
+   * Falls back to `components.code` when not provided.
+   * Can be overridden by TypesTableMeta.DefaultCode.
+   */
+  DefaultCode?: TypesJsxOptions['DefaultCode'];
+  /**
+   * Optional pre component for raw type formatted code blocks.
+   * Falls back to `DetailedTypePre`, then `TypePre` when not provided.
+   * Can be overridden by TypesTableMeta.RawTypePre.
+   */
+  RawTypePre?: TypesJsxOptions['RawTypePre'];
+  /**
+   * Rehype plugins to run on HAST before converting to JSX.
+   * Can be overridden by TypesTableMeta.enhancers.
+   * Defaults to `[enhanceCodeInline]` when undefined.
+   * Pass an empty array to disable all enhancers.
+   */
+  enhancers?: PluggableList;
+  /**
+   * Rehype plugins to run on inline HAST fields (shortType and default).
+   * Can be overridden by TypesTableMeta.enhancersInline.
+   * Defaults to `[enhanceCodeInline]` when undefined.
+   * Pass an empty array to disable all inline enhancers.
+   */
+  enhancersInline?: PluggableList;
+  /**
+   * Custom component tag name to use instead of `<a>` for type reference links.
+   * When set, enhanceCodeTypes emits elements with this tag name,
+   * adding a `name` property (the matched identifier) alongside `href`.
+   * Can be overridden by TypesTableMeta.typeRefComponent.
+   */
+  typeRefComponent?: string;
+  /**
+   * Custom component tag name for property reference elements.
+   * Can be overridden by TypesTableMeta.typePropRefComponent.
+   */
+  typePropRefComponent?: string;
+  /**
+   * Custom component tag name for function parameter reference elements.
+   * Can be overridden by TypesTableMeta.typeParamRefComponent.
+   */
+  typeParamRefComponent?: string;
+  /**
+   * Opt-in property linking mode for enhanceCodeTypes.
+   * Can be overridden by TypesTableMeta.linkProps.
+   */
+  linkProps?: 'shallow' | 'deep';
+  /**
+   * Opt-in function parameter linking for enhanceCodeTypes.
+   * Can be overridden by TypesTableMeta.linkParams.
+   */
+  linkParams?: boolean;
+  /**
+   * Opt-in scope-based variable linking for enhanceCodeTypes.
+   * Can be overridden by TypesTableMeta.linkScope.
+   */
+  linkScope?: boolean;
+  /**
+   * Module import linking map for enhanceCodeTypes.
+   * Can be overridden by TypesTableMeta.moduleLinkMap.
+   */
+  moduleLinkMap?: {
+    js?: Record<string, ModuleLinkMapEntry>;
+    css?: Record<string, ModuleLinkMapEntry>;
+  };
+  /**
+   * Default anchor slug for default/namespace imports.
+   * Can be overridden by TypesTableMeta.defaultImportSlug.
+   */
+  defaultImportSlug?: string;
+};
+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>;
+export declare function createMultipleTypesFactory<T extends {}>(options: AbstractCreateTypesOptions<T>): <K extends Record<string, any>>(url: string, typeDef: K, meta?: TypesTableMeta | undefined) => {
+  types: Record<keyof K, React.ComponentType<T>>;
+  AdditionalTypes: React.ComponentType<T>;
+};