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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.50",
+  "version": "0.12.1-canary.51",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -65,7 +65,7 @@
     "remark-typography": "^0.8.6",
     "sucrase": "^3.35.1",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-api-extractor": "1.0.0-beta.6",
+    "typescript-api-extractor": "1.0.0-beta.7",
     "uint8-to-base64": "^0.2.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
@@ -814,5 +814,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "5aa500cdf1274a4ecc6674e3cab2ef7dc8a92aa9"
+  "gitSha": "9741b9d5e30ddcd5bccf4020dd59ec56ea4932cb"
 }

package/pipeline/loadServerTypesMeta/externalTypes.d.mts

@@ -48,12 +48,23 @@ export declare function formatFunctionSignature(type: tae.FunctionNode): string;
  * Attempts to collect a named union type as an external type during formatting.
  * Only collects if:
  * - The type has a name
- * - ALL members are literals or simple intrinsics (string, number, boolean)
+ * - ALL members are literals, simple intrinsics (string, number, boolean), or template literals
+ *   whose placeholders are simple intrinsics
  * - The type is not in allExports (not an own type)
  * - The type is not a built-in namespace
  * - The optional pattern filter matches
  */
 export declare function maybeCollectExternalUnion(type: tae.UnionNode, collector: ExternalTypesCollector): void;
+/**
+ * Attempts to collect a named template literal type as an external type during formatting.
+ * Only collects if:
+ * - The type has a name
+ * - ALL placeholders are simple intrinsics (string, number, boolean)
+ * - The type is not in allExports (not an own type)
+ * - The type is not a built-in namespace
+ * - The optional pattern filter matches
+ */
+export declare function maybeCollectExternalTemplateLiteral(type: tae.TemplateLiteralNode, collector: ExternalTypesCollector): void;
 /**
  * Attempts to collect a named function type as an external type during formatting.
  * Only collects named function types that aren't ComponentRenderFn, own types, or built-in.

package/pipeline/loadServerTypesMeta/externalTypes.mjs

@@ -1,7 +1,8 @@
 import { uniq } from 'es-toolkit';
-import { isExternalType, isIntrinsicType, isUnionType, isObjectType, isLiteralType, isTypeOperatorType, isTypeQueryType } from "./typeGuards.mjs";
+import { isExternalType, isIntrinsicType, isUnionType, isObjectType, isLiteralType, isTemplateLiteralType, isTypeOperatorType, isTypeQueryType } from "./typeGuards.mjs";
 import { isBuiltInTypeName } from "./builtInTypes.mjs";
 import { groupType, UNION_OR_INTERSECTION } from "./precedence.mjs";
+import { formatTemplateLiteral } from "./templateLiteral.mjs";
 
 /**
  * Metadata for an external type discovered during formatting.
@@ -93,6 +94,9 @@ export function formatExternalTypeDefinition(type) {
     }
     return String(value);
   }
+  if (isTemplateLiteralType(type)) {
+    return formatTemplateLiteral(type, formatExternalTypeDefinition);
+  }
   if (isIntrinsicType(type)) {
     return type.intrinsic;
   }
@@ -125,11 +129,23 @@ export function formatFunctionSignature(type) {
   return signatures.length > 1 ? signatures.map(sig => `(${sig})`).join(' | ') : signatures[0] || '() => void';
 }
 
+/**
+ * Whether a type is a literal, a simple intrinsic (string, number, boolean), or a template
+ * literal whose placeholders are all simple intrinsics.
+ */
+function isLiteralLike(type) {
+  if (isTemplateLiteralType(type)) {
+    return type.types.every(isLiteralLike);
+  }
+  return isLiteralType(type) || isIntrinsicType(type) && ['string', 'number', 'boolean'].includes(type.intrinsic);
+}
+
 /**
  * Attempts to collect a named union type as an external type during formatting.
  * Only collects if:
  * - The type has a name
- * - ALL members are literals or simple intrinsics (string, number, boolean)
+ * - ALL members are literals, simple intrinsics (string, number, boolean), or template literals
+ *   whose placeholders are simple intrinsics
  * - The type is not in allExports (not an own type)
  * - The type is not a built-in namespace
  * - The optional pattern filter matches
@@ -161,7 +177,7 @@ export function maybeCollectExternalUnion(type, collector) {
   }
 
   // Only collect if ALL members are literals
-  const allMembersAreLiterals = resolvedUnionMembers(type).every(t => isLiteralType(t) || isIntrinsicType(t) && ['string', 'number', 'boolean'].includes(t.intrinsic));
+  const allMembersAreLiterals = resolvedUnionMembers(type).every(isLiteralLike);
   if (allMembersAreLiterals) {
     collector.collected.set(typeName, {
       name: typeName,
@@ -170,6 +186,50 @@ export function maybeCollectExternalUnion(type, collector) {
   }
 }
 
+/**
+ * Attempts to collect a named template literal type as an external type during formatting.
+ * Only collects if:
+ * - The type has a name
+ * - ALL placeholders are simple intrinsics (string, number, boolean)
+ * - The type is not in allExports (not an own type)
+ * - The type is not a built-in namespace
+ * - The optional pattern filter matches
+ */
+export function maybeCollectExternalTemplateLiteral(type, collector) {
+  const typeName = type.typeName?.name;
+  if (!typeName) {
+    return;
+  }
+
+  // Already collected
+  if (collector.collected.has(typeName)) {
+    return;
+  }
+
+  // Pattern filter
+  if (collector.pattern && !collector.pattern.test(typeName)) {
+    return;
+  }
+
+  // Built-in type
+  if (isBuiltInTypeName(type.typeName)) {
+    return;
+  }
+
+  // Own type (in exports or typeNameMap)
+  if (isOwnTypeName(typeName, collector)) {
+    return;
+  }
+
+  // Only collect if ALL placeholders are simple intrinsics, as unions require of their members
+  if (isLiteralLike(type)) {
+    collector.collected.set(typeName, {
+      name: typeName,
+      definition: formatExternalTypeDefinition(type)
+    });
+  }
+}
+
 /**
  * Attempts to collect a named function type as an external type during formatting.
  * Only collects named function types that aren't ComponentRenderFn, own types, or built-in.

package/pipeline/loadServerTypesMeta/formatType.mjs

@@ -1,9 +1,10 @@
 import { uniq } from 'es-toolkit';
-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 { isExternalType, isIntrinsicType, isUnionType, isIntersectionType, isObjectType, isAnonymousObjectType, isArrayType, isFunctionType, isLiteralType, isTemplateLiteralType, isTupleType, isTypeParameterType, isTypeOperatorType, isTypeQueryType, isInternalTypeName } from "./typeGuards.mjs";
+import { isOwnTypeName, maybeCollectExternalUnion, maybeCollectExternalTemplateLiteral, maybeCollectExternalFunction, maybeCollectExternalReference } from "./externalTypes.mjs";
 import { isBuiltInTypeReference } from "./builtInTypes.mjs";
 import { prettyFormat } from "./format.mjs";
 import { groupType, UNION, UNION_OR_INTERSECTION } from "./precedence.mjs";
+import { formatTemplateLiteral } from "./templateLiteral.mjs";
 /**
  * The keys a preserved type operator stands for, or `undefined` when it should be shown as
  * the syntax it was written as.
@@ -329,6 +330,30 @@ export function formatType(type, options) {
   if (isLiteralType(type)) {
     return normalizeQuotes(String(type.value));
   }
+  if (isTemplateLiteralType(type)) {
+    // A reference to a template literal alias keeps its name, like the other named types.
+    // But skip if the type name matches selfName to avoid circular references like `type Foo = Foo`
+    if (type.typeName) {
+      const qualifiedName = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
+      if (!matchesSelfName(qualifiedName, type.typeName.name)) {
+        if (externalTypesCollector) {
+          // Only collect as external if the qualified name wasn't rewritten to an own type.
+          if (qualifiedName === type.typeName.name || !isOwnTypeName(qualifiedName, externalTypesCollector)) {
+            maybeCollectExternalTemplateLiteral(type, externalTypesCollector);
+          }
+        }
+        return qualifiedName;
+      }
+    }
+
+    // Use expandObjects=false for placeholders to prevent deep expansion (one level only)
+    return formatTemplateLiteral(type, placeholder => formatType(placeholder, {
+      exportNames,
+      typeNameMap,
+      externalTypesCollector,
+      preserveTypeParameters
+    }));
+  }
   if (isArrayType(type)) {
     // Use expandObjects=false for element types to prevent deep expansion (one level only)
     const formattedMemberType = formatType(type.elementType, {

package/pipeline/loadServerTypesMeta/templateLiteral.d.mts

@@ -0,0 +1,8 @@
+import type * as tae from 'typescript-api-extractor';
+/**
+ * Writes a template literal type as TypeScript source, such as `` `${number}px` ``.
+ *
+ * Placeholders are formatted by the caller, so each formatter keeps its own rules for the
+ * types inside them.
+ */
+export declare function formatTemplateLiteral(type: tae.TemplateLiteralNode, formatPlaceholder: (placeholder: tae.AnyType) => string): string;

package/pipeline/loadServerTypesMeta/templateLiteral.mjs

@@ -0,0 +1,18 @@
+/**
+ * Writes a template literal type as TypeScript source, such as `` `${number}px` ``.
+ *
+ * Placeholders are formatted by the caller, so each formatter keeps its own rules for the
+ * types inside them.
+ */
+export function formatTemplateLiteral(type, formatPlaceholder) {
+  const placeholders = type.types.map((placeholder, index) => `\${${formatPlaceholder(placeholder)}}${escapeTemplateText(type.texts[index + 1])}`);
+  return `\`${escapeTemplateText(type.texts[0])}${placeholders.join('')}\``;
+}
+
+/**
+ * Escapes the characters that would otherwise end the template, start a placeholder or an
+ * escape, or be read back as a line feed.
+ */
+function escapeTemplateText(text) {
+  return text.replace(/\\|`|\$\{|\r/g, match => match === '\r' ? '\\r' : `\\${match}`);
+}

package/pipeline/loadServerTypesMeta/typeGuards.d.mts

@@ -45,6 +45,10 @@ export declare function isFunctionType(type: unknown): type is tae.FunctionNode;
  * Type guard to check if a type node is a literal type.
  */
 export declare function isLiteralType(type: unknown): type is tae.LiteralNode;
+/**
+ * Type guard to check if a type node is a template literal.
+ */
+export declare function isTemplateLiteralType(type: unknown): type is tae.TemplateLiteralNode;
 /**
  * Type guard to check if a type node is an enum type.
  */

package/pipeline/loadServerTypesMeta/typeGuards.mjs

@@ -80,6 +80,13 @@ export function isLiteralType(type) {
   return hasKind(type, 'literal');
 }
 
+/**
+ * Type guard to check if a type node is a template literal.
+ */
+export function isTemplateLiteralType(type) {
+  return hasKind(type, 'templateLiteral');
+}
+
 /**
  * Type guard to check if a type node is an enum type.
  */