@mui/internal-docs-infra 0.12.1-canary.40 → 0.12.1-canary.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.40",
+  "version": "0.12.1-canary.41",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "99c21315b55b03f58d832f7854e628da68343a10"
+  "gitSha": "96f05ba632fabe0c395fd6bf647b40c3bb717ee6"
 }

package/pipeline/loadServerTypesMeta/constants.d.mts

@@ -0,0 +1,10 @@
+import type { ParserOptions } from 'typescript-api-extractor';
+/**
+ * Extraction policy the pipeline hands to `typescript-api-extractor`.
+ *
+ * The depth and property-count caps decide whether the parser resolves a type or hands
+ * back a preserved reference, so anything parsing sources outside the pipeline — tests
+ * included — has to apply the same caps or it will resolve shapes the real build leaves
+ * alone.
+ */
+export declare const PARSER_OPTIONS: ParserOptions;

package/pipeline/loadServerTypesMeta/constants.mjs

@@ -0,0 +1,18 @@
+/**
+ * Extraction policy the pipeline hands to `typescript-api-extractor`.
+ *
+ * The depth and property-count caps decide whether the parser resolves a type or hands
+ * back a preserved reference, so anything parsing sources outside the pipeline — tests
+ * included — has to apply the same caps or it will resolve shapes the real build leaves
+ * alone.
+ */
+export const PARSER_OPTIONS = {
+  includeExternalTypes: false,
+  shouldInclude: ({
+    depth
+  }) => depth <= 15,
+  shouldResolveObject: ({
+    propertyCount,
+    depth
+  }) => propertyCount <= 50 && depth <= 15
+};

package/pipeline/loadServerTypesMeta/externalTypes.mjs

@@ -1,5 +1,6 @@
 import { uniq } from 'es-toolkit';
-import { isExternalType, isIntrinsicType, isUnionType, isObjectType, isLiteralType } from "./typeGuards.mjs";
+import { isExternalType, isIntrinsicType, isUnionType, isObjectType, isLiteralType, isTypeOperatorType, isTypeQueryType } from "./typeGuards.mjs";
+import { groupType, UNION_OR_INTERSECTION } from "./precedence.mjs";
 
 /**
  * Metadata for an external type discovered during formatting.
@@ -52,6 +53,25 @@ export function isOwnTypeName(typeName, collector) {
   return false;
 }
 
+/**
+ * Members of a union, with preserved type operators replaced by the keys they resolve to.
+ *
+ * `'muted' | keyof Config` reads as a plain literal union to someone reading the docs, and
+ * it reached this module as one until the parser started preserving the operator.
+ *
+ * `maybeCollectExternalUnion` needs this to decide whether every member is a literal. When
+ * formatting, the operator branch below would produce the same text on its own; flattening
+ * first is what lets `uniq` dedupe a key against a sibling listed next to the operator.
+ */
+function resolvedUnionMembers(type) {
+  return type.types.flatMap(member => {
+    if (!isTypeOperatorType(member) || member.resolvedType === undefined) {
+      return member;
+    }
+    return isUnionType(member.resolvedType) ? member.resolvedType.types : member.resolvedType;
+  });
+}
+
 /**
  * Formats an external type definition as a simple type string.
  * This produces a concise representation suitable for documentation.
@@ -61,9 +81,21 @@ export function isOwnTypeName(typeName, collector) {
 export function formatExternalTypeDefinition(type) {
   if (isUnionType(type)) {
     // Always expand union types - don't use typeName since we want the full definition
-    const members = type.types.map(t => formatExternalTypeDefinition(t));
+    const members = resolvedUnionMembers(type).map(t => formatExternalTypeDefinition(t));
     return uniq(members).join(' | ');
   }
+  if (isTypeOperatorType(type)) {
+    // This section shows full definitions, so an operator is worth more as the keys it
+    // stands for than as its authored syntax.
+    if (type.resolvedType !== undefined) {
+      return formatExternalTypeDefinition(type.resolvedType);
+    }
+    // `keyof` binds tighter than both composers, so a composite operand has to be grouped.
+    return `${type.operator} ${groupType(formatExternalTypeDefinition(type.type), UNION_OR_INTERSECTION)}`;
+  }
+  if (isTypeQueryType(type)) {
+    return `typeof ${type.expressionName}`;
+  }
   if (isLiteralType(type)) {
     const value = type.value;
     // Ensure string literals are quoted with single quotes
@@ -142,7 +174,7 @@ export function maybeCollectExternalUnion(type, collector) {
   }
 
   // Only collect if ALL members are literals
-  const allMembersAreLiterals = type.types.every(t => isLiteralType(t) || isIntrinsicType(t) && ['string', 'number', 'boolean'].includes(t.intrinsic));
+  const allMembersAreLiterals = resolvedUnionMembers(type).every(t => isLiteralType(t) || isIntrinsicType(t) && ['string', 'number', 'boolean'].includes(t.intrinsic));
   if (allMembersAreLiterals) {
     collector.collected.set(typeName, {
       name: typeName,

package/pipeline/loadServerTypesMeta/formatType.mjs

@@ -1,7 +1,27 @@
 import { uniq } from 'es-toolkit';
-import { isExternalType, isIntrinsicType, isUnionType, isIntersectionType, isObjectType, isAnonymousObjectType, isArrayType, isFunctionType, isLiteralType, isTupleType, isTypeParameterType, isInternalTypeName } from "./typeGuards.mjs";
+import { isExternalType, isIntrinsicType, isUnionType, isIntersectionType, isObjectType, isAnonymousObjectType, isArrayType, isFunctionType, isLiteralType, isTupleType, isTypeParameterType, isTypeOperatorType, isTypeQueryType, isInternalTypeName } from "./typeGuards.mjs";
 import { isOwnTypeName, maybeCollectExternalUnion, maybeCollectExternalFunction, maybeCollectExternalReference } from "./externalTypes.mjs";
 import { prettyFormat } from "./format.mjs";
+import { groupType, UNION, UNION_OR_INTERSECTION } from "./precedence.mjs";
+/**
+ * The keys a preserved type operator stands for, or `undefined` when it should be shown as
+ * the syntax it was written as.
+ *
+ * A type parameter operand is kept by name in raw declarations: the checker resolves
+ * `keyof T` to its base constraint, which holds no type parameter to recover `T` from.
+ * Both the union branch and the operator branch ask this, so they cannot disagree about
+ * which operators expand. `formatExternalTypeDefinition` takes no options and always
+ * expands, so it deliberately does not share this rule.
+ */
+function resolvedOperatorKeys(type, preserveTypeParameters) {
+  if (!isTypeOperatorType(type) || type.resolvedType === undefined) {
+    return undefined;
+  }
+  if (preserveTypeParameters && isTypeParameterType(type.type)) {
+    return undefined;
+  }
+  return type.resolvedType;
+}
 export function formatType(type, options) {
   const {
     removeUndefined = false,
@@ -93,6 +113,13 @@ export function formatType(type, options) {
       if (isTypeParameterType(t) && isUnionType(t.constraint)) {
         return t.constraint.types;
       }
+
+      // A `keyof` member stands for its keys, so flatten them in to be deduped and
+      // ordered with their siblings rather than joined in as one opaque string.
+      const operatorKeys = resolvedOperatorKeys(t, preserveTypeParameters);
+      if (operatorKeys !== undefined) {
+        return isUnionType(operatorKeys) ? operatorKeys.types : operatorKeys;
+      }
       return t;
     });
 
@@ -199,7 +226,9 @@ export function formatType(type, options) {
     if (formattedMembers.length === 1) {
       return formattedMembers[0];
     }
-    return formattedMembers.join(' & ');
+
+    // `&` binds tighter than `|`, so a union member has to be grouped to survive the join.
+    return formattedMembers.map(member => groupType(member, UNION)).join(' & ');
   }
   if (isObjectType(type)) {
     // Check if the object has an index signature
@@ -428,6 +457,44 @@ export function formatType(type, options) {
       externalTypesCollector
     }) : type.name;
   }
+  if (isTypeOperatorType(type)) {
+    // The operator carries the checker result alongside the authored syntax. Format the
+    // result so `keyof X` keeps documenting the keys it stands for, whether that result is
+    // exact, a generic base constraint, or a fallback.
+    const operatorKeys = resolvedOperatorKeys(type, preserveTypeParameters);
+    if (operatorKeys !== undefined) {
+      return formatType(operatorKeys, {
+        expandObjects,
+        exportNames,
+        typeNameMap,
+        externalTypesCollector,
+        selfName,
+        preserveTypeParameters
+      });
+    }
+
+    // Either the operand is kept by name, or syntax-only output omitted the resolved
+    // result; the authored operand is all there is to show. `keyof` binds tighter than
+    // both composers, so a composite operand has to be grouped.
+    const operand = formatType(type.type, {
+      exportNames,
+      typeNameMap,
+      externalTypesCollector,
+      selfName,
+      preserveTypeParameters
+    });
+    return `${type.operator} ${groupType(operand, UNION_OR_INTERSECTION)}`;
+  }
+  if (isTypeQueryType(type)) {
+    return `typeof ${type.expressionName}`;
+  }
+
+  // Export-level nodes reach the page through formatClass/formatComponent/formatEnum, so
+  // they are the only kinds expected to fall through here. Asserting that keeps a node kind
+  // the parser gains later from silently documenting itself as the word `unknown`, which is
+  // how preserved `keyof` operators went unnoticed through a parser upgrade.
+  // Parenthesized so this reads as an expression rather than a `type` alias declaration.
+  type;
   return 'unknown';
 }
 

package/pipeline/loadServerTypesMeta/parseTestSources.d.mts

@@ -0,0 +1,24 @@
+import type * as tae from 'typescript-api-extractor';
+export interface ParseTestSourcesOptions {
+  /**
+   * Declarations placed in the virtual default library. Types declared here are external
+   * to the parsed sources, which is what makes the parser preserve constructs such as
+   * `keyof` rather than expanding them away — a locally declared operand is expanded.
+   * Omit to parse without a standard library at all.
+   */
+  lib?: string;
+  /** Overrides merged over the pipeline's own extraction policy. */
+  parserOptions?: tae.ParserOptions;
+}
+/**
+ * Parses TypeScript sources the way the pipeline does, without touching the filesystem.
+ *
+ * Tests that assert on parsed exports should start from source rather than hand-built
+ * nodes, so they stay honest about what `typescript-api-extractor` actually emits. The
+ * extraction policy is the pipeline's own, so a shape the real build declines to resolve
+ * is left unresolved here too.
+ *
+ * Sources are keyed by file name (e.g. `ComponentRootDataAttributes.ts`) and may import
+ * each other by relative path. The first entry is the entrypoint.
+ */
+export declare function parseTestSources(sources: Record<string, string>, options?: ParseTestSourcesOptions): tae.ExportNode[];

package/pipeline/loadServerTypesMeta/parseTestSources.mjs

@@ -0,0 +1,55 @@
+import ts from 'typescript';
+import { parseFromProgram } from 'typescript-api-extractor';
+import { PARSER_OPTIONS } from "./constants.mjs";
+const ROOT = '/virtual';
+const LIB_PATH = `${ROOT}/lib.d.ts`;
+/**
+ * Parses TypeScript sources the way the pipeline does, without touching the filesystem.
+ *
+ * Tests that assert on parsed exports should start from source rather than hand-built
+ * nodes, so they stay honest about what `typescript-api-extractor` actually emits. The
+ * extraction policy is the pipeline's own, so a shape the real build declines to resolve
+ * is left unresolved here too.
+ *
+ * Sources are keyed by file name (e.g. `ComponentRootDataAttributes.ts`) and may import
+ * each other by relative path. The first entry is the entrypoint.
+ */
+export function parseTestSources(sources, options = {}) {
+  const {
+    lib,
+    parserOptions
+  } = options;
+  const sourceFiles = new Map();
+  if (lib !== undefined) {
+    sourceFiles.set(LIB_PATH, ts.createSourceFile(LIB_PATH, lib, ts.ScriptTarget.ESNext, true));
+  }
+  const entryPaths = [];
+  for (const [name, text] of Object.entries(sources)) {
+    const filePath = `${ROOT}/${name}`;
+    sourceFiles.set(filePath, ts.createSourceFile(filePath, text, ts.ScriptTarget.ESNext, true));
+    entryPaths.push(filePath);
+  }
+  const host = {
+    getSourceFile: fileName => sourceFiles.get(fileName),
+    getDefaultLibFileName: () => LIB_PATH,
+    writeFile: () => {},
+    getCurrentDirectory: () => ROOT,
+    getCanonicalFileName: fileName => fileName,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => '\n',
+    fileExists: fileName => sourceFiles.has(fileName),
+    readFile: fileName => sourceFiles.get(fileName)?.text
+  };
+  const program = ts.createProgram(entryPaths, {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    rootDir: ROOT,
+    noLib: lib === undefined
+  }, host);
+  return parseFromProgram(entryPaths[0], program, {
+    ...PARSER_OPTIONS,
+    ...parserOptions
+  }).exports;
+}

package/pipeline/loadServerTypesMeta/precedence.d.mts

@@ -0,0 +1,13 @@
+/** Composers that bind looser than `keyof`, and than each other in this order. */
+export declare const UNION = "|";
+export declare const UNION_OR_INTERSECTION = "|&";
+/**
+ * Whether a formatted type composes at its top level with one of `operators`, so it needs
+ * grouping before being placed somewhere that binds tighter.
+ *
+ * Operators nested inside the type — an object's property type, a type argument, a function
+ * signature — are already grouped by their own brackets and are left alone.
+ */
+export declare function hasTopLevelOperator(formatted: string, operators: string): boolean;
+/** Wraps a formatted type in parentheses when it would otherwise re-associate. */
+export declare function groupType(formatted: string, operators: string): string;

package/pipeline/loadServerTypesMeta/precedence.mjs

@@ -0,0 +1,40 @@
+/** Composers that bind looser than `keyof`, and than each other in this order. */
+export const UNION = '|';
+export const UNION_OR_INTERSECTION = '|&';
+
+/**
+ * Whether a formatted type composes at its top level with one of `operators`, so it needs
+ * grouping before being placed somewhere that binds tighter.
+ *
+ * Operators nested inside the type — an object's property type, a type argument, a function
+ * signature — are already grouped by their own brackets and are left alone.
+ */
+export function hasTopLevelOperator(formatted, operators) {
+  let depth = 0;
+  let quote = '';
+  for (let index = 0; index < formatted.length; index += 1) {
+    const char = formatted[index];
+    if (quote) {
+      if (char === quote) {
+        quote = '';
+      }
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === '(' || char === '[' || char === '{' || char === '<') {
+      depth += 1;
+    } else if (char === ')' || char === ']' || char === '}') {
+      depth -= 1;
+    } else if (char === '>' && formatted[index - 1] !== '=') {
+      // `=>` is an arrow, not the end of a type argument list.
+      depth -= 1;
+    } else if (depth === 0 && operators.includes(char)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Wraps a formatted type in parentheses when it would otherwise re-associate. */
+export function groupType(formatted, operators) {
+  return hasTopLevelOperator(formatted, operators) ? `(${formatted})` : formatted;
+}

package/pipeline/loadServerTypesMeta/processTypes.mjs

@@ -5,6 +5,7 @@ import ts from 'typescript';
 import { createOptimizedProgram } from "./createOptimizedProgram.mjs";
 import { augmentComponentsWithInheritedProps } from "./inheritedExternalProps.mjs";
 import { transformConstantGroup } from "./transformConstantGroup.mjs";
+import { PARSER_OPTIONS } from "./constants.mjs";
 import { extractJSDocText, isJSDocNodeArray } from "./extractJSDocText.mjs";
 import { PerformanceTracker } from "./performanceTracking.mjs";
 import { nameMark } from "../loadPrecomputedCodeHighlighter/performanceLogger.mjs";
@@ -269,16 +270,6 @@ export async function processTypes(request) {
     const programWrapperEnd = tracker.mark(nameMark(functionName, 'Program Creation End', [request.relativePath], true));
     tracker.measure(nameMark(functionName, 'Program Creation', [request.relativePath], true), programWrapperStart, programWrapperEnd);
     const internalTypesCache = {};
-    const parserOptions = {
-      includeExternalTypes: false,
-      shouldInclude: ({
-        depth
-      }) => depth <= 15,
-      shouldResolveObject: ({
-        propertyCount,
-        depth
-      }) => propertyCount <= 50 && depth <= 15
-    };
 
     // Process variants in parallel
     const resolvedVariantMap = new Map(request.resolvedVariantMap);
@@ -299,7 +290,7 @@ export async function processTypes(request) {
         // type aliases, and re-exports properly
         const {
           exports
-        } = parseFromProgram(entrypoint, program, parserOptions);
+        } = parseFromProgram(entrypoint, program, PARSER_OPTIONS);
 
         // Re-add configured props that the parser dropped because they are
         // inherited from an externally declared type in node_modules
@@ -343,7 +334,7 @@ export async function processTypes(request) {
           }
           const {
             exports: internalExport
-          } = parseFromProgram(file, program, parserOptions);
+          } = parseFromProgram(file, program, PARSER_OPTIONS);
 
           // Metadata files may declare their members as an enum or as named constants;
           // normalize both to a single constant group named after the file.

package/pipeline/loadServerTypesMeta/typeGuards.d.mts

@@ -61,6 +61,16 @@ export declare function isTypeParameterType(type: unknown): type is tae.TypePara
  * Type guard to check if a type node is a component type.
  */
 export declare function isComponentType(type: unknown): type is tae.ComponentNode;
+/**
+ * Type guard to check if a type node is a preserved type operator, such as `keyof T`.
+ * The operand is carried in `type` and the checker result in `resolvedType`.
+ */
+export declare function isTypeOperatorType(type: unknown): type is tae.TypeOperatorNode;
+/**
+ * Type guard to check if a type node is a preserved type query, such as `typeof value`.
+ * Type queries carry only the authored expression, never a resolved value shape.
+ */
+export declare function isTypeQueryType(type: unknown): type is tae.TypeQueryNode;
 /**
  * Checks if a type name is a TypeScript internal symbol name.
  * Internal names like __object, __type, __function are used by TypeScript

package/pipeline/loadServerTypesMeta/typeGuards.mjs

@@ -108,6 +108,22 @@ export function isComponentType(type) {
   return hasKind(type, 'component');
 }
 
+/**
+ * Type guard to check if a type node is a preserved type operator, such as `keyof T`.
+ * The operand is carried in `type` and the checker result in `resolvedType`.
+ */
+export function isTypeOperatorType(type) {
+  return hasKind(type, 'typeOperator');
+}
+
+/**
+ * Type guard to check if a type node is a preserved type query, such as `typeof value`.
+ * Type queries carry only the authored expression, never a resolved value shape.
+ */
+export function isTypeQueryType(type) {
+  return hasKind(type, 'typeQuery');
+}
+
 /**
  * Checks if a type name is a TypeScript internal symbol name.
  * Internal names like __object, __type, __function are used by TypeScript