@mui/internal-docs-infra 0.12.1-canary.34 → 0.12.1-canary.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.34",
+  "version": "0.12.1-canary.35",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -30,8 +30,8 @@
   "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.2",
-    "@csstools/postcss-relative-color-syntax": "^4.0.7",
+    "@csstools/postcss-light-dark-function": "^3.0.3",
+    "@csstools/postcss-relative-color-syntax": "^4.0.8",
     "@csstools/postcss-stepped-value-functions": "^5.0.4",
     "@orama/orama": "^3.1.18",
     "@orama/plugin-qps": "^3.1.18",
@@ -41,7 +41,7 @@
     "autoprefixer": "^10.5.4",
     "chalk": "^6.0.0",
     "clipboard-copy": "^4.0.1",
-    "es-toolkit": "^1.49.0",
+    "es-toolkit": "^1.51.0",
     "fflate": "^0.8.3",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "hast-util-to-text": "^4.0.2",
@@ -52,7 +52,7 @@
     "kebab-case": "^2.0.2",
     "lz-string": "^1.5.0",
     "path-module": "^0.1.2",
-    "postcss": "^8.5.22",
+    "postcss": "^8.5.26",
     "postcss-modules-extract-imports": "^3.1.0",
     "postcss-modules-local-by-default": "^4.2.0",
     "postcss-modules-scope": "^3.2.1",
@@ -62,14 +62,14 @@
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
-    "remark-typography": "^0.7.3",
+    "remark-typography": "^0.8.1",
     "sucrase": "^3.35.1",
     "typescript-api-extractor": "1.0.0-beta.6",
     "uint8-to-base64": "^0.2.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "vscode-oniguruma": "^2.0.1",
-    "yargs": "^18.0.0",
+    "yargs": "^18.1.0",
     "zx": "^8.8.5"
   },
   "peerDependencies": {
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "c7ecd7d0578f1fd06710d507fcd4e155afc8bde7"
+  "gitSha": "621d2be80da48abdbfaeb85f498580416be78c9a"
 }

package/pipeline/loadServerTypesMeta/format.mjs

@@ -190,7 +190,7 @@ export function extractTypeParameters(type, typeNameMap = {}) {
  * while preserving all markdown features and applying syntax highlighting to code blocks.
  */
 export async function parseMarkdownToHast(markdown) {
-  const processor = unified().use(remarkParse).use(remarkGfm).use(transformMarkdownCode).use(remarkTypography, []).use(remarkRehype).freeze();
+  const processor = unified().use(remarkParse).use(remarkGfm).use(transformMarkdownCode).use(remarkTypography).use(remarkRehype).freeze();
   const mdast = processor.parse(markdown);
   const result = await processor.run(mdast);
   return result;

package/pipeline/loadServerTypesMeta/processTypes.mjs

@@ -4,6 +4,7 @@ import { parseFromProgram } from 'typescript-api-extractor';
 import ts from 'typescript';
 import { createOptimizedProgram } from "./createOptimizedProgram.mjs";
 import { augmentComponentsWithInheritedProps } from "./inheritedExternalProps.mjs";
+import { transformConstantGroup } from "./transformConstantGroup.mjs";
 import { extractJSDocText, isJSDocNodeArray } from "./extractJSDocText.mjs";
 import { PerformanceTracker } from "./performanceTracking.mjs";
 import { nameMark } from "../loadPrecomputedCodeHighlighter/performanceLogger.mjs";
@@ -343,8 +344,12 @@ export async function processTypes(request) {
           const {
             exports: internalExport
           } = parseFromProgram(file, program, parserOptions);
-          internalTypesCache[file] = internalExport;
-          return internalExport;
+
+          // Metadata files may declare their members as an enum or as named constants;
+          // normalize both to a single constant group named after the file.
+          const groupExports = transformConstantGroup(file, internalExport);
+          internalTypesCache[file] = groupExports;
+          return groupExports;
         });
         const internalTypes = allInternalTypes.reduce((acc, cur) => {
           acc.push(...cur);

package/pipeline/loadServerTypesMeta/transformConstantGroup.d.mts

@@ -0,0 +1,14 @@
+import type * as tae from 'typescript-api-extractor';
+/**
+ * Normalizes a metadata file's exports into a single constant group named after the file.
+ *
+ * A constant group is a named, documented set of key/value constants belonging to one
+ * component — the data attributes it sets, or the CSS variables it reads. Authors may
+ * declare it as an enum named after the file, or as named literal constants; both end up
+ * as the same enum-shaped export so the rest of the pipeline sees one representation.
+ *
+ * Exports matching no known authoring style are returned unchanged. Once a group is formed
+ * it replaces the file's exports, so a metadata file that also exports something which is
+ * not a constant is a mistake: it throws rather than dropping those exports silently.
+ */
+export declare function transformConstantGroup(filePath: string, exports: tae.ExportNode[]): tae.ExportNode[];

package/pipeline/loadServerTypesMeta/transformConstantGroup.mjs

@@ -0,0 +1,80 @@
+import { EnumMember, EnumNode, ExportNode, TypeName } from 'typescript-api-extractor';
+import { fileUrlToPortablePath } from "../loaderUtils/fileUrlToPortablePath.mjs";
+import { getFileNameFromUrl } from "../loaderUtils/getFileNameFromUrl.mjs";
+import { isEnumType, isLiteralType } from "./typeGuards.mjs";
+
+/**
+ * Derives a constant group's name from its file path, e.g.
+ * `/src/accordion/panel/AccordionPanelCssVars.ts` becomes `AccordionPanelCssVars`.
+ */
+function getGroupName(filePath) {
+  const {
+    fileName,
+    extension
+  } = getFileNameFromUrl(fileUrlToPortablePath(filePath));
+  return extension ? fileName.slice(0, -extension.length) : fileName;
+}
+
+/**
+ * Reads a constant's value from its literal type.
+ *
+ * String literals arrive wrapped in quotes (`"data-open"`) while numeric literals do not,
+ * so both are normalized to the bare string an enum member would have carried. Anything
+ * else — objects, functions, booleans — is not a documentable constant.
+ */
+function readLiteralValue(value) {
+  if (typeof value === 'number') {
+    return String(value);
+  }
+  if (typeof value === 'string' && value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return undefined;
+}
+
+/**
+ * Normalizes a metadata file's exports into a single constant group named after the file.
+ *
+ * A constant group is a named, documented set of key/value constants belonging to one
+ * component — the data attributes it sets, or the CSS variables it reads. Authors may
+ * declare it as an enum named after the file, or as named literal constants; both end up
+ * as the same enum-shaped export so the rest of the pipeline sees one representation.
+ *
+ * Exports matching no known authoring style are returned unchanged. Once a group is formed
+ * it replaces the file's exports, so a metadata file that also exports something which is
+ * not a constant is a mistake: it throws rather than dropping those exports silently.
+ */
+export function transformConstantGroup(filePath, exports) {
+  const groupName = getGroupName(filePath);
+
+  // Already an enum declaration named after its file, so there is nothing to normalize.
+  if (exports.some(node => node.name === groupName && isEnumType(node.type))) {
+    return exports;
+  }
+
+  // Literal constants are folded into members of a single group rather than left alongside
+  // it: names this generic (`open`, `index`, `disabled`) would shadow real types when
+  // resolving `{@link}` references.
+  const members = [];
+  const discarded = [];
+  for (const node of exports) {
+    const value = isLiteralType(node.type) ? readLiteralValue(node.type.value) : undefined;
+    if (value === undefined) {
+      discarded.push(node.name);
+    } else {
+      members.push(new EnumMember(node.name, value, node.documentation));
+    }
+  }
+  if (members.length === 0) {
+    return exports;
+  }
+
+  // The group replaces the file's exports wholesale, so anything that is not a constant —
+  // a helper function, a type alias, an enum under another name, a constant widened off its
+  // literal type — would be documented nowhere. Metadata files are expected to hold
+  // constants only, so fail the build rather than drop these exports silently.
+  if (discarded.length > 0) {
+    throw new Error(`[transformConstantGroup] ${groupName} - metadata files must export only constants, but these are not: ${discarded.join(', ')}`);
+  }
+  return [new ExportNode(groupName, new EnumNode(new TypeName(groupName), members, undefined), undefined)];
+}

package/pipeline/loadServerTypesText/parseTypesMarkdown.mjs

@@ -144,7 +144,7 @@ function stripPositions(node) {
  * on mdast nodes that were already parsed, avoiding a redundant text → mdast re-parse.
  */
 async function convertDescriptions(targets) {
-  const processor = unified().use(transformMarkdownCode).use(remarkTypography, []).use(remarkRehype);
+  const processor = unified().use(transformMarkdownCode).use(remarkTypography).use(remarkRehype);
   await Promise.all(targets.map(async ([setter, children]) => {
     const root = {
       type: 'root',