@mui/internal-docs-infra 0.12.1-canary.22 → 0.12.1-canary.24

package/cli/loadNextConfig.d.mts

@@ -1,4 +1,5 @@
 import type { DescriptionReplacement } from "../pipeline/loadServerTypesMeta/format.mjs";
+import type { InheritedExternalPropsConfig } from "../pipeline/loadServerTypesMeta/inheritedExternalProps.mjs";
 import type { OrderingConfig } from "../pipeline/loadServerTypesText/order.mjs";
 export interface DemoClientRequirement {
   /**
@@ -21,6 +22,8 @@ export interface DemoPageRequirement {
 export type ExtractedNextConfigOptions = {
   ordering?: OrderingConfig;
   descriptionReplacements?: DescriptionReplacement[];
+  /** Props to re-include when inherited from these externally declared types. */
+  inheritedExternalProps?: InheritedExternalPropsConfig;
   useVisibleDescription?: boolean;
   socketDir?: string;
   /** Page-index cache directory configured on the sitemap loader. */

package/cli/loadNextConfig.mjs

@@ -47,6 +47,9 @@ function extractOptionsFromLoaderEntries(loaders) {
     if (!result.descriptionReplacements && loader.loader === TYPES_LOADER && loader.options?.descriptionReplacements) {
       result.descriptionReplacements = loader.options.descriptionReplacements;
     }
+    if (!result.inheritedExternalProps && loader.loader === TYPES_LOADER && loader.options?.inheritedExternalProps) {
+      result.inheritedExternalProps = loader.options.inheritedExternalProps;
+    }
     if (!result.socketDir && loader.loader === TYPES_LOADER && typeof loader.options?.socketDir === 'string') {
       result.socketDir = loader.options.socketDir;
     }
@@ -83,6 +86,7 @@ export function extractOptionsFromTurbopack(config) {
     const extracted = extractOptionsFromLoaderEntries(loaders);
     merged.ordering ??= extracted.ordering;
     merged.descriptionReplacements ??= extracted.descriptionReplacements;
+    merged.inheritedExternalProps ??= extracted.inheritedExternalProps;
     merged.useVisibleDescription ??= extracted.useVisibleDescription;
     merged.socketDir ??= extracted.socketDir;
     merged.cacheDir ??= extracted.cacheDir;
@@ -171,6 +175,7 @@ function extractOptionsFromWebpackResult(result) {
     const extracted = extractOptionsFromLoaderEntries(useEntries);
     merged.ordering ??= extracted.ordering;
     merged.descriptionReplacements ??= extracted.descriptionReplacements;
+    merged.inheritedExternalProps ??= extracted.inheritedExternalProps;
     merged.useVisibleDescription ??= extracted.useVisibleDescription;
     merged.socketDir ??= extracted.socketDir;
     merged.cacheDir ??= extracted.cacheDir;
@@ -329,6 +334,7 @@ export async function extractDocsInfraOptionsFromNextConfig(dir) {
   return {
     ordering: turbopack.ordering ?? webpack.ordering,
     descriptionReplacements: turbopack.descriptionReplacements ?? webpack.descriptionReplacements,
+    inheritedExternalProps: turbopack.inheritedExternalProps ?? webpack.inheritedExternalProps,
     useVisibleDescription: turbopack.useVisibleDescription ?? webpack.useVisibleDescription,
     socketDir: turbopack.socketDir ?? webpack.socketDir,
     cacheDir: turbopack.cacheDir ?? webpack.cacheDir,

package/cli/runValidate.mjs

@@ -88,6 +88,7 @@ const runValidate = {
     const {
       ordering,
       descriptionReplacements,
+      inheritedExternalProps,
       useVisibleDescription = false,
       socketDir: configSocketDir,
       cacheDir: configCacheDir,
@@ -300,6 +301,7 @@ const runValidate = {
               },
               ordering,
               descriptionReplacements,
+              inheritedExternalProps,
               socketDir,
               cacheDir
             }

package/cli/validateWorker.mjs

@@ -74,6 +74,7 @@ if (parentPort) {
             updateParentIndex: excludeFromIndex ? undefined : task.syncTypesOptions.updateParentIndex,
             ordering: task.syncTypesOptions.ordering,
             descriptionReplacements: task.syncTypesOptions.descriptionReplacements,
+            inheritedExternalProps: task.syncTypesOptions.inheritedExternalProps,
             socketDir: task.syncTypesOptions.socketDir,
             cacheDir: task.syncTypesOptions.cacheDir
           });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.22",
+  "version": "0.12.1-canary.24",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -30,15 +30,15 @@
   "homepage": "https://github.com/mui/mui-public/tree/master/packages/docs-infra",
   "dependencies": {
     "@babel/runtime": "^7.29.7",
-    "@csstools/postcss-light-dark-function": "^3.0.1",
-    "@csstools/postcss-relative-color-syntax": "^4.0.5",
-    "@csstools/postcss-stepped-value-functions": "^5.0.3",
+    "@csstools/postcss-light-dark-function": "^3.0.2",
+    "@csstools/postcss-relative-color-syntax": "^4.0.7",
+    "@csstools/postcss-stepped-value-functions": "^5.0.4",
     "@orama/orama": "^3.1.18",
     "@orama/plugin-qps": "^3.1.18",
     "@orama/stemmers": "^3.1.18",
     "@orama/stopwords": "^3.1.18",
-    "@wooorm/starry-night": "^3.9.0",
-    "autoprefixer": "^10.5.0",
+    "@wooorm/starry-night": "^3.10.0",
+    "autoprefixer": "^10.5.4",
     "chalk": "^5.6.2",
     "clipboard-copy": "^4.0.1",
     "es-toolkit": "^1.49.0",
@@ -48,11 +48,11 @@
     "icss-utils": "^5.1.0",
     "import-meta-resolve": "^4.2.0",
     "jiti": "^2.7.0",
-    "jsondiffpatch": "^0.7.3",
+    "jsondiffpatch": "^0.7.6",
     "kebab-case": "^2.0.2",
     "lz-string": "^1.5.0",
     "path-module": "^0.1.2",
-    "postcss": "^8.5.15",
+    "postcss": "^8.5.22",
     "postcss-modules-extract-imports": "^3.1.0",
     "postcss-modules-local-by-default": "^4.2.0",
     "postcss-modules-scope": "^3.2.1",
@@ -64,7 +64,7 @@
     "remark-stringify": "^11.0.0",
     "remark-typography": "^0.7.3",
     "sucrase": "^3.35.1",
-    "typescript-api-extractor": "1.0.0-beta.3",
+    "typescript-api-extractor": "1.0.0-beta.4",
     "uint8-to-base64": "^0.2.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "5a40e5ed0fc8d5ff358463279c75f69b33062d9f"
+  "gitSha": "da1a18c9574a4a0c716b373ec6169e6ab47abc62"
 }

package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.d.mts

@@ -2,6 +2,7 @@ import type { LoaderContext } from 'webpack';
 import type { FormatInlineTypeOptions, DescriptionReplacement } from "../loadServerTypesMeta/format.mjs";
 import type { SyncPageIndexBaseOptions } from "../transformMarkdownMetadata/types.mjs";
 import type { OrderingConfig } from "../loadServerTypesText/order.mjs";
+import type { InheritedExternalPropsConfig } from "../loadServerTypesMeta/inheritedExternalProps.mjs";
 import type { TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
 export type LoaderOptions = {
   /** Performance tracking and logging options */
@@ -54,6 +55,11 @@ export type LoaderOptions = {
    * Each entry has a `pattern` (regex string) and `replacement` string.
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /**
+   * Props to re-include when inherited from these externally declared types,
+   * keyed by the declaring type's name.
+   */
+  inheritedExternalProps?: InheritedExternalPropsConfig;
   /** Options for code blocks highlighted inside generated type metadata */
   codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
   /**

package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.mjs

@@ -92,6 +92,7 @@ export async function loadPrecomputedTypes(source) {
       externalTypesPattern: options.externalTypesPattern,
       ordering: options.ordering,
       descriptionReplacements: options.descriptionReplacements,
+      inheritedExternalProps: options.inheritedExternalProps,
       codeBlockEmphasisOptions: options.codeBlockEmphasisOptions,
       cacheDir: options.cacheDir,
       sync: true,

package/pipeline/loadServerTypesMeta/inheritedExternalProps.d.mts

@@ -0,0 +1,34 @@
+import ts from 'typescript';
+import type { ExportNode } from 'typescript-api-extractor';
+/**
+ * Props to re-include for a single externally declared type. Either a list of
+ * prop names, or an object that additionally pins the package the type must be
+ * declared in — use the object form when another installed package could
+ * declare a type with the same name.
+ */
+export type InheritedExternalPropsEntry = string[] | {
+  /** Name of the package the type must be declared in (e.g. `@base-ui/react`). */
+  from: string;
+  props: string[];
+};
+/**
+ * Props to re-include when they are inherited from externally declared types,
+ * keyed by the name of the type (interface or type alias) that declares them.
+ *
+ * @example { BaseUIComponentProps: ['className', 'render', 'style'] }
+ * @example { BaseUIComponentProps: { from: '@base-ui/react', props: ['className'] } }
+ */
+export interface InheritedExternalPropsConfig {
+  [typeName: string]: InheritedExternalPropsEntry;
+}
+/**
+ * Re-adds configured props to parsed component exports when they are inherited
+ * from a type declared in an installed package. typescript-api-extractor skips
+ * properties that are only declared inside `node_modules` (which is what keeps
+ * native DOM attributes out of the docs), so shared props that a library
+ * inherits from another package's base props type silently disappear from its
+ * prop tables. The synthesized nodes are built from the checker's resolved
+ * types, so the output matches what the extractor produces when the same props
+ * are declared locally.
+ */
+export declare function augmentComponentsWithInheritedProps(exports: ExportNode[], program: ts.Program, sourceFile: ts.SourceFile, config: InheritedExternalPropsConfig | undefined): void;

package/pipeline/loadServerTypesMeta/inheritedExternalProps.mjs

@@ -0,0 +1,286 @@
+import ts from 'typescript';
+import { CallSignature, Documentation, ExternalTypeNode, FunctionNode, IntrinsicNode, LiteralNode, Parameter, PropertyNode, TypeName, UnionNode } from 'typescript-api-extractor';
+import { isComponentType, isObjectType } from "./typeGuards.mjs";
+
+/**
+ * Props to re-include for a single externally declared type. Either a list of
+ * prop names, or an object that additionally pins the package the type must be
+ * declared in — use the object form when another installed package could
+ * declare a type with the same name.
+ */
+
+/**
+ * Props to re-include when they are inherited from externally declared types,
+ * keyed by the name of the type (interface or type alias) that declares them.
+ *
+ * @example { BaseUIComponentProps: ['className', 'render', 'style'] }
+ * @example { BaseUIComponentProps: { from: '@base-ui/react', props: ['className'] } }
+ */
+
+function resolveConfig(config) {
+  return new Map(Object.entries(config).map(([typeName, entry]) => [typeName, Array.isArray(entry) ? {
+    props: entry
+  } : entry]));
+}
+
+/** Bail out of type conversion once nesting gets deeper than any expected prop shape. */
+const MAX_CONVERSION_DEPTH = 8;
+
+/**
+ * Re-adds configured props to parsed component exports when they are inherited
+ * from a type declared in an installed package. typescript-api-extractor skips
+ * properties that are only declared inside `node_modules` (which is what keeps
+ * native DOM attributes out of the docs), so shared props that a library
+ * inherits from another package's base props type silently disappear from its
+ * prop tables. The synthesized nodes are built from the checker's resolved
+ * types, so the output matches what the extractor produces when the same props
+ * are declared locally.
+ */
+export function augmentComponentsWithInheritedProps(exports, program, sourceFile, config) {
+  if (!config || Object.keys(config).length === 0) {
+    return;
+  }
+  const checker = program.getTypeChecker();
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+  if (!moduleSymbol) {
+    return;
+  }
+  const symbolsByExportName = new Map();
+  collectExportSymbols(checker, moduleSymbol, [], symbolsByExportName, new Set());
+  const exportNames = exports.map(exportNode => exportNode.name);
+  const resolvedConfig = resolveConfig(config);
+  const propNames = new Set(Array.from(resolvedConfig.values()).flatMap(entry => entry.props));
+  for (const exportNode of exports) {
+    if (!isComponentType(exportNode.type)) {
+      continue;
+    }
+    const symbol = symbolsByExportName.get(exportNode.name);
+    if (!symbol) {
+      continue;
+    }
+    const propsType = getComponentPropsType(checker, symbol);
+    if (!propsType) {
+      continue;
+    }
+    const component = exportNode.type;
+    const existingNames = new Set(component.props.map(prop => prop.name));
+    const addedProps = [];
+    for (const propName of propNames) {
+      if (existingNames.has(propName)) {
+        continue;
+      }
+      const propSymbol = propsType.getProperty(propName);
+      if (!propSymbol || !isInheritedExternalProp(propSymbol, propName, resolvedConfig)) {
+        continue;
+      }
+      const propNode = createPropNode(propSymbol, checker, exportNames);
+      if (propNode) {
+        addedProps.push(propNode);
+      }
+    }
+    if (addedProps.length === 0) {
+      continue;
+    }
+    component.props.push(...addedProps);
+    augmentPropsTypeExports(exports, exportNode, addedProps);
+  }
+}
+
+/**
+ * Mirrors the synthesized props onto the exported props type of the component
+ * (both the namespaced `Component.Props` alias and the flat interface export),
+ * so their rendered type definitions match the component's prop table.
+ */
+function augmentPropsTypeExports(exports, componentExport, addedProps) {
+  const componentName = componentExport.name;
+  const propsExportNames = new Set([`${componentName}.Props`, `${componentName.replaceAll('.', '')}Props`]);
+  if (componentExport.reexportedFrom) {
+    propsExportNames.add(`${componentExport.reexportedFrom}Props`);
+  }
+  for (const exportNode of exports) {
+    if (!propsExportNames.has(exportNode.name) || !isObjectType(exportNode.type)) {
+      continue;
+    }
+    const existingNames = new Set(exportNode.type.properties.map(prop => prop.name));
+    exportNode.type.properties.push(...addedProps.filter(prop => !existingNames.has(prop.name)));
+  }
+}
+
+/**
+ * Maps parsed export names to their TypeScript symbols, using the same naming
+ * scheme as typescript-api-extractor (namespace members become dotted names,
+ * e.g. `Menu.Root`).
+ */
+function collectExportSymbols(checker, moduleSymbol, namespaces, result, visited) {
+  if (namespaces.length > 2 || visited.has(moduleSymbol)) {
+    return;
+  }
+  visited.add(moduleSymbol);
+  for (const exportSymbol of checker.getExportsOfModule(moduleSymbol)) {
+    const name = [...namespaces, exportSymbol.name].join('.');
+    result.set(name, exportSymbol);
+
+    // Recurse into `export * as Namespace from '...'` re-exports.
+    const declaration = exportSymbol.declarations?.[0];
+    if (declaration && ts.isNamespaceExport(declaration)) {
+      const aliased = checker.getAliasedSymbol(exportSymbol);
+      if (aliased) {
+        collectExportSymbols(checker, aliased, [...namespaces, exportSymbol.name], result, visited);
+      }
+    }
+  }
+}
+
+/**
+ * Resolves the props type of a component export from its first call signature.
+ */
+function getComponentPropsType(checker, symbol) {
+  // eslint-disable-next-line no-bitwise
+  const isAlias = (symbol.flags & ts.SymbolFlags.Alias) !== 0;
+  const resolvedSymbol = isAlias ? checker.getAliasedSymbol(symbol) : symbol;
+  const componentType = checker.getTypeOfSymbol(resolvedSymbol);
+  for (const signature of componentType.getCallSignatures()) {
+    const propsParameter = signature.parameters[0];
+    const declaration = propsParameter?.valueDeclaration ?? propsParameter?.declarations?.[0];
+    if (declaration) {
+      return checker.getTypeOfSymbolAtLocation(propsParameter, declaration);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Checks that a prop is declared in an installed package on one of the
+ * configured types (and, when configured, in the expected package). Locally
+ * declared props are already handled by the extractor, and external props of
+ * any other origin (e.g. native DOM attributes) must stay excluded from the
+ * docs.
+ */
+function isInheritedExternalProp(propSymbol, propName, config) {
+  const declarations = propSymbol.declarations ?? [];
+  if (declarations.length === 0) {
+    return false;
+  }
+  return declarations.every(declaration => {
+    const fileName = declaration.getSourceFile().fileName;
+    if (!fileName.includes('node_modules')) {
+      return false;
+    }
+    const owner = ts.findAncestor(declaration, node => ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node));
+    const entry = owner && config.get(owner.name.text);
+    if (!entry || !entry.props.includes(propName)) {
+      return false;
+    }
+    return !entry.from || getPackageName(fileName) === entry.from;
+  });
+}
+
+/**
+ * Extracts the package name from a file path inside `node_modules`,
+ * e.g. `.../node_modules/@base-ui/react/types.d.ts` → `@base-ui/react`.
+ * Uses the last `node_modules` segment to handle nested installations.
+ */
+function getPackageName(fileName) {
+  const segments = fileName.split(/[\\/]/);
+  const index = segments.lastIndexOf('node_modules');
+  if (index === -1) {
+    return undefined;
+  }
+  const first = segments[index + 1];
+  if (!first) {
+    return undefined;
+  }
+  if (first.startsWith('@')) {
+    const second = segments[index + 2];
+    return second ? `${first}/${second}` : undefined;
+  }
+  return first;
+}
+function createPropNode(propSymbol, checker, exportNames) {
+  const declaration = propSymbol.valueDeclaration ?? propSymbol.declarations?.[0];
+  if (!declaration) {
+    return undefined;
+  }
+  const propType = checker.getTypeOfSymbolAtLocation(propSymbol, declaration);
+  const description = ts.displayPartsToString(propSymbol.getDocumentationComment(checker));
+  // eslint-disable-next-line no-bitwise
+  const optional = (propSymbol.flags & ts.SymbolFlags.Optional) !== 0;
+  return new PropertyNode(propSymbol.name, convertType(propType, checker, exportNames, 0), description ? new Documentation(description) : undefined, optional);
+}
+
+/**
+ * Converts a checker-resolved type into the extractor's type model, mirroring
+ * how typescript-api-extractor represents locally declared props: intrinsics
+ * and unions are expanded, anonymous function types are expanded into call
+ * signatures, and named types become references.
+ */
+function convertType(type, checker, exportNames, depth) {
+  if (depth > MAX_CONVERSION_DEPTH) {
+    return new ExternalTypeNode(new TypeName(checker.typeToString(type)));
+  }
+  const intrinsic = getIntrinsicName(type);
+  if (intrinsic) {
+    return new IntrinsicNode(intrinsic);
+  }
+
+  // eslint-disable-next-line no-bitwise
+  if ((type.flags & ts.TypeFlags.Literal) !== 0) {
+    return new LiteralNode(checker.typeToString(type));
+  }
+  if (type.isUnion()) {
+    return new UnionNode(undefined, type.types.map(member => convertType(member, checker, exportNames, depth + 1)));
+  }
+  const typeName = getNamedTypeReference(type, exportNames);
+  const callSignatures = type.getCallSignatures();
+  if (callSignatures.length > 0) {
+    return new FunctionNode(typeName, callSignatures.map(signature => convertSignature(signature, checker, exportNames, depth)));
+  }
+  if (typeName) {
+    return new ExternalTypeNode(typeName);
+  }
+  return new ExternalTypeNode(new TypeName(checker.typeToString(type)));
+}
+function convertSignature(signature, checker, exportNames, depth) {
+  const parameters = signature.parameters.map(parameter => {
+    const declaration = parameter.valueDeclaration ?? parameter.declarations?.[0];
+    const parameterType = declaration ? checker.getTypeOfSymbolAtLocation(parameter, declaration) : checker.getTypeOfSymbol(parameter);
+    const optional = Boolean(declaration && ts.isParameter(declaration) && (declaration.questionToken || declaration.initializer));
+    return new Parameter(convertType(parameterType, checker, exportNames, depth + 1), parameter.name, undefined, optional, undefined);
+  });
+  return new CallSignature(parameters, convertType(signature.getReturnType(), checker, exportNames, depth + 1));
+}
+const INTRINSIC_FLAGS = [[ts.TypeFlags.String, 'string'], [ts.TypeFlags.Number, 'number'], [ts.TypeFlags.Boolean, 'boolean'], [ts.TypeFlags.BigInt, 'bigint'], [ts.TypeFlags.Undefined, 'undefined'], [ts.TypeFlags.Null, 'null'], [ts.TypeFlags.Void, 'void'], [ts.TypeFlags.Any, 'any'], [ts.TypeFlags.Unknown, 'unknown'], [ts.TypeFlags.Never, 'never']];
+function getIntrinsicName(type) {
+  // `boolean` is represented as a union of literals, so check it before unions.
+  // eslint-disable-next-line no-bitwise
+  const match = INTRINSIC_FLAGS.find(([flag]) => (type.flags & flag) !== 0);
+  return match?.[1];
+}
+
+/**
+ * Builds a reference for a named type, preferring the module's dotted export
+ * name (e.g. `Menu.Root.State`) when one exists for the flat name.
+ */
+function getNamedTypeReference(type, exportNames) {
+  const symbol = type.aliasSymbol ?? type.getSymbol();
+  const name = symbol?.name;
+  if (!symbol || !name || name.startsWith('__')) {
+    return undefined;
+  }
+
+  // Collect enclosing namespaces (e.g. `React` for `React.CSSProperties`),
+  // stopping at module/source-file symbols whose names are quoted paths.
+  const namespaces = [];
+  let parent = symbol.parent;
+  while (parent && /^[A-Za-z_$][\w$]*$/.test(parent.name)) {
+    namespaces.unshift(parent.name);
+    parent = parent.parent;
+  }
+  const flatName = [...namespaces, name].join('');
+  const dottedName = exportNames.find(exportName => exportName.includes('.') && exportName.replaceAll('.', '') === flatName);
+  if (dottedName) {
+    const parts = dottedName.split('.');
+    return new TypeName(parts[parts.length - 1], parts.slice(0, -1));
+  }
+  return new TypeName(name, namespaces.length > 0 ? namespaces : undefined);
+}

package/pipeline/loadServerTypesMeta/loadServerTypesMeta.d.mts

@@ -4,6 +4,7 @@ import type { HookTypeMeta as HookType } from "./formatHook.mjs";
 import type { FunctionTypeMeta as FunctionType } from "./formatFunction.mjs";
 import type { RawTypeMeta as RawType, ReExportInfo } from "./formatRaw.mjs";
 import type { FormattedProperty, FormattedEnumMember, FormattedParameter, FormatInlineTypeOptions, DescriptionReplacement } from "./format.mjs";
+import type { InheritedExternalPropsConfig } from "./inheritedExternalProps.mjs";
 import type { OrderingConfig } from "../loadServerTypesText/order.mjs";
 import type { OrganizeTypesResult } from "../loadServerTypesText/organizeTypesByExport.mjs";
 export type ClassTypeMeta = ClassType;
@@ -93,6 +94,14 @@ export interface LoadServerTypesMetaOptions {
    * Each entry has a `pattern` (regex string) and `replacement` string.
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /**
+   * Props to re-include when inherited from these externally declared types,
+   * keyed by the declaring type's name. The parser normally drops props that are
+   * only declared inside `node_modules`; this re-adds the configured ones.
+   *
+   * @example { BaseUIComponentProps: ['className', 'render', 'style'] }
+   */
+  inheritedExternalProps?: InheritedExternalPropsConfig;
 }
 export interface LoadServerTypesMetaResult extends OrganizeTypesResult<TypesMeta> {
   /** All dependencies that should be watched for changes */

package/pipeline/loadServerTypesMeta/loadServerTypesMeta.mjs

@@ -166,7 +166,8 @@ export async function loadServerTypesMeta(options) {
     resolvedVariantMap: Array.from(resolvedVariantMap.entries()),
     dependencies: config.dependencies,
     rootContextDir,
-    relativePath
+    relativePath,
+    inheritedExternalProps: options.inheritedExternalProps
   });
   if (!workerResult.success) {
     throw new Error(workerResult.error || 'Worker failed to process types');

package/pipeline/loadServerTypesMeta/processTypes.d.mts

@@ -1,5 +1,6 @@
 import type { CompilerOptions } from 'typescript';
 import type { ExportNode } from 'typescript-api-extractor';
+import type { InheritedExternalPropsConfig } from "./inheritedExternalProps.mjs";
 import type { PerformanceLog } from "./performanceTracking.mjs";
 export interface VariantResult {
   exports: ExportNode[];
@@ -22,6 +23,11 @@ export interface WorkerRequest {
   /** Root context directory path (must end with /) */
   rootContextDir: string;
   relativePath: string;
+  /**
+   * Props to re-include when inherited from these externally declared types,
+   * keyed by the declaring type's name.
+   */
+  inheritedExternalProps?: InheritedExternalPropsConfig;
 }
 export interface WorkerResponse {
   requestId?: number;

package/pipeline/loadServerTypesMeta/processTypes.mjs

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'url';
 import { parseFromProgram } from 'typescript-api-extractor';
 import ts from 'typescript';
 import { createOptimizedProgram } from "./createOptimizedProgram.mjs";
+import { augmentComponentsWithInheritedProps } from "./inheritedExternalProps.mjs";
 import { extractJSDocText, isJSDocNodeArray } from "./extractJSDocText.mjs";
 import { PerformanceTracker } from "./performanceTracking.mjs";
 import { nameMark } from "../loadPrecomputedCodeHighlighter/performanceLogger.mjs";
@@ -299,6 +300,10 @@ export async function processTypes(request) {
           exports
         } = parseFromProgram(entrypoint, program, parserOptions);
 
+        // Re-add configured props that the parser dropped because they are
+        // inherited from an externally declared type in node_modules
+        augmentComponentsWithInheritedProps(exports, program, sourceFile, request.inheritedExternalProps);
+
         // Extract namespaces from the exports (e.g., "Menu" from "Menu.Root")
         const namespaces = extractNamespaces(exports);
 

package/pipeline/syncTypes/syncTypes.d.mts

@@ -1,3 +1,4 @@
+import type { InheritedExternalPropsConfig } from "../loadServerTypesMeta/inheritedExternalProps.mjs";
 import type { FormatInlineTypeOptions, DescriptionReplacement } from "../loadServerTypesMeta/format.mjs";
 import type { OrderingConfig } from "../loadServerTypesText/order.mjs";
 import type { SyncPageIndexBaseOptions } from "../transformMarkdownMetadata/types.mjs";
@@ -62,6 +63,11 @@ export interface SyncTypesOptions {
    * Each entry has a `pattern` (regex string) and `replacement` string.
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /**
+   * Props to re-include when inherited from these externally declared types,
+   * keyed by the declaring type's name.
+   */
+  inheritedExternalProps?: InheritedExternalPropsConfig;
   /**
    * Directory for the sha256-validated JSON cache of the types pipeline. When set, after
    * writing types.md syncTypes pre-populates `{cacheDir}/types-text/{route}.json` with the

package/pipeline/syncTypes/syncTypes.mjs

@@ -196,7 +196,8 @@ export async function syncTypes(options) {
     socketDir: options.socketDir,
     externalTypesPattern: options.externalTypesPattern,
     ordering: options.ordering,
-    descriptionReplacements: options.descriptionReplacements
+    descriptionReplacements: options.descriptionReplacements,
+    inheritedExternalProps: options.inheritedExternalProps
   });
   const {
     allDependencies,

package/useDemo/useDemo.d.mts

@@ -68,8 +68,8 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   expanded: boolean;
   expand: () => void;
   setExpanded: (expanded: boolean) => void;
-  copy: (event: React.MouseEvent<Element, MouseEvent>) => Promise<void>;
-  copyMarkdown: (event: React.MouseEvent<Element, MouseEvent>) => Promise<void>;
+  copy: (event: React.MouseEvent<Element>) => Promise<void>;
+  copyMarkdown: (event: React.MouseEvent<Element>) => Promise<void>;
   availableTransforms: string[];
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;

package/withDocsInfra/withDocsInfra.d.mts

@@ -2,6 +2,7 @@ import type { NextConfig } from 'next';
 import type { RuleSetRule } from 'webpack';
 import type { OrderingConfig } from "../pipeline/loadServerTypesText/order.mjs";
 import type { DescriptionReplacement } from "../pipeline/loadServerTypesMeta/format.mjs";
+import type { InheritedExternalPropsConfig } from "../pipeline/loadServerTypesMeta/inheritedExternalProps.mjs";
 import type { EnhanceCodeEmphasisOptions } from "../pipeline/parseSource/calculateFrameRanges.mjs";
 import type { TransformHtmlCodeBlockOptions } from "../pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
 export interface WebpackOptions {
@@ -165,6 +166,27 @@ export interface WithDocsInfraOptions {
    * ```
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /**
+   * Props to re-include in component docs when they are inherited from these
+   * externally declared types, keyed by the declaring type's name. Type
+   * extraction normally drops props that are only declared inside
+   * `node_modules` (which keeps native DOM attributes out of the docs); this
+   * option re-adds the configured props when a component's props type extends
+   * one of the listed types from an installed package.
+   *
+   * Entries can also pin the package the type must come from, to disambiguate
+   * same-named types from different packages.
+   *
+   * @example
+   * ```js
+   * { BaseUIComponentProps: ['className', 'render', 'style'] }
+   * ```
+   * @example
+   * ```js
+   * { BaseUIComponentProps: { from: '@base-ui/react', props: ['className', 'render', 'style'] } }
+   * ```
+   */
+  inheritedExternalProps?: InheritedExternalPropsConfig;
   /**
    * Directory rooting docs-infra's build caches and coordination state — relocate it (or point it
    * at a persistent cache) and everything under it moves together: the sha256-validated JSON caches

package/withDocsInfra/withDocsInfra.mjs

@@ -93,6 +93,7 @@ export function withDocsInfra(options = {}) {
   // Only include ordering in loader options if explicitly provided
   const ordering = options.ordering;
   const descriptionReplacements = options.descriptionReplacements;
+  const inheritedExternalProps = options.inheritedExternalProps;
   const demoEmphasisOptions = options.demoEmphasisOptions;
   const codeBlockEmphasisOptions = options.codeBlockEmphasisOptions;
 
@@ -183,6 +184,9 @@ export function withDocsInfra(options = {}) {
             } : {}),
             ...(descriptionReplacements ? {
               descriptionReplacements: descriptionReplacements
+            } : {}),
+            ...(inheritedExternalProps ? {
+              inheritedExternalProps: inheritedExternalProps
             } : {})
           }
         }]
@@ -313,6 +317,9 @@ export function withDocsInfra(options = {}) {
               } : {}),
               ...(descriptionReplacements ? {
                 descriptionReplacements
+              } : {}),
+              ...(inheritedExternalProps ? {
+                inheritedExternalProps
               } : {})
             }
           }]