@mui/internal-docs-infra 0.13.1-canary.0 → 0.13.1-canary.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.13.1-canary.0",
+  "version": "0.13.1-canary.1",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -814,5 +814,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "764e3b3cfc14293e74e93f3413609025f502bab9"
+  "gitSha": "41611dd904d88de9bbc8dce94594452c144fd2ea"
 }

package/pipeline/loadServerTypesMeta/constantGroups.d.mts

@@ -0,0 +1,48 @@
+import ts from 'typescript';
+import type * as tae from 'typescript-api-extractor';
+/** Which of a component's tables a constant group holds. */
+export type ConstantGroupKind = 'dataAttributes' | 'cssVariables';
+export interface ConstantGroupTarget {
+  /** The component's name as the entrypoint exports it, e.g. `Toolbar.Button` */
+  component: string;
+  kind: ConstantGroupKind;
+}
+/** The constant groups holding one component's tables. */
+export type ComponentConstantGroups = Partial<Record<ConstantGroupKind, tae.EnumNode>>;
+/** The value of a constant in a constant group. */
+type ConstantValue = string | number;
+/**
+ * Finds the entrypoint's namespace exports whose module holds nothing but literal constants,
+ * e.g. `export * as ButtonDataAttributes from './ButtonDataAttributes'`, with their values.
+ * Namespaces nested in other namespace exports are found too, under their dotted path
+ * (`Toolbar.ButtonDataAttributes`).
+ *
+ * The parser flattens such a namespace into one export per member and cannot tell a constant
+ * from a type alias of the same literal, so the checker is asked instead.
+ *
+ * @returns Member values keyed by namespace path, then member name
+ */
+export declare function findConstantNamespaces(entrypoint: string, program: ts.Program): Map<string, Map<string, ConstantValue>>;
+/**
+ * Collapses the flattened members of each constant namespace (`ButtonDataAttributes.open`)
+ * into a single enum-shaped export named after the namespace, in place of its first member.
+ */
+export declare function foldConstantNamespaces(exports: tae.ExportNode[], namespaces: Map<string, Map<string, ConstantValue>>): tae.ExportNode[];
+/**
+ * Writes the declaration of a constant group as it is exported: a namespace of constants
+ * for a namespace export, an enum otherwise.
+ */
+export declare function formatConstantGroupDeclaration(name: string, group: tae.EnumNode, asNamespace: boolean): string;
+/**
+ * Resolves which component each constant group documents from its name: the component's
+ * name with its dots removed, followed by `DataAttributes` or `CssVariables`.
+ *
+ * Throws when the name before the suffix is not exactly one of the exported components.
+ *
+ * @returns Targets keyed by the group's export name, and each component's groups
+ */
+export declare function matchConstantGroups(exports: tae.ExportNode[]): {
+  targets: Map<string, ConstantGroupTarget>;
+  byComponent: Map<string, ComponentConstantGroups>;
+};
+export {};

package/pipeline/loadServerTypesMeta/constantGroups.mjs

@@ -0,0 +1,202 @@
+import ts from 'typescript';
+import { EnumMember, EnumNode, ExportNode, TypeName } from 'typescript-api-extractor';
+import { formatPropertyComment } from "./formatType.mjs";
+import { isComponentType, isEnumType } from "./typeGuards.mjs";
+
+/** Which of a component's tables a constant group holds. */
+
+/**
+ * A constant group is a named set of constant values an entrypoint publishes, either as an
+ * enum or as a namespace of constants (`export * as ButtonDataAttributes from './…'`); both
+ * are represented as an enum-shaped export. Its name tells which component table it holds:
+ * the component's name with its dots removed, followed by one of these suffixes, e.g.
+ * `ToolbarButtonDataAttributes` holds the data attributes of `Toolbar.Button`.
+ */
+const KIND_SUFFIXES = {
+  dataAttributes: 'DataAttributes',
+  cssVariables: 'CssVariables'
+};
+
+/** The constant groups holding one component's tables. */
+
+function resolveAlias(symbol, checker) {
+  // eslint-disable-next-line no-bitwise -- TypeScript symbol flags are a bitmask
+  return symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+}
+
+/** The value of a constant in a constant group. */
+
+/**
+ * Reads the value of a `const` holding a string or number literal.
+ */
+function readLiteralConstant(symbol, checker) {
+  const declaration = symbol.valueDeclaration;
+  if (!declaration || !ts.isVariableDeclaration(declaration) ||
+  // eslint-disable-next-line no-bitwise -- TypeScript node flags are a bitmask
+  !(ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const)) {
+    return undefined;
+  }
+  const type = checker.getTypeOfSymbol(symbol);
+  return type.isStringLiteral() || type.isNumberLiteral() ? type.value : undefined;
+}
+
+/**
+ * Reads a module's exports as constant values, when it exports nothing but literal constants.
+ */
+function readConstantModule(moduleSymbol, checker) {
+  const values = new Map();
+  const members = checker.getExportsOfModule(moduleSymbol);
+  const isConstantModule = members.length > 0 && members.every(member => {
+    const value = readLiteralConstant(resolveAlias(member, checker), checker);
+    if (value === undefined) {
+      return false;
+    }
+    values.set(member.name, value);
+    return true;
+  });
+  return isConstantModule ? values : undefined;
+}
+
+/**
+ * Finds the entrypoint's namespace exports whose module holds nothing but literal constants,
+ * e.g. `export * as ButtonDataAttributes from './ButtonDataAttributes'`, with their values.
+ * Namespaces nested in other namespace exports are found too, under their dotted path
+ * (`Toolbar.ButtonDataAttributes`).
+ *
+ * The parser flattens such a namespace into one export per member and cannot tell a constant
+ * from a type alias of the same literal, so the checker is asked instead.
+ *
+ * @returns Member values keyed by namespace path, then member name
+ */
+export function findConstantNamespaces(entrypoint, program) {
+  const namespaces = new Map();
+  const sourceFile = program.getSourceFile(entrypoint);
+  const checker = program.getTypeChecker();
+  const entrypointSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
+  const visited = new Set();
+  const visit = (moduleSymbol, prefix) => {
+    for (const exportSymbol of checker.getExportsOfModule(moduleSymbol)) {
+      if (exportSymbol.declarations?.some(ts.isNamespaceExport)) {
+        const target = checker.getAliasedSymbol(exportSymbol);
+        const path = `${prefix}${exportSymbol.name}`;
+        const values = readConstantModule(target, checker);
+        if (values) {
+          namespaces.set(path, values);
+        } else if (!visited.has(target)) {
+          visited.add(target);
+          visit(target, `${path}.`);
+        }
+      }
+    }
+  };
+  if (entrypointSymbol) {
+    visit(entrypointSymbol, '');
+  }
+  return namespaces;
+}
+
+/**
+ * Collapses the flattened members of each constant namespace (`ButtonDataAttributes.open`)
+ * into a single enum-shaped export named after the namespace, in place of its first member.
+ */
+export function foldConstantNamespaces(exports, namespaces) {
+  if (namespaces.size === 0) {
+    return exports;
+  }
+  const groups = new Map();
+  const folded = [];
+  for (const node of exports) {
+    // Members sit directly under their namespace, which may itself be nested
+    // (`Toolbar.ButtonDataAttributes.pressed`).
+    const dot = node.name.lastIndexOf('.');
+    const namespace = dot === -1 ? undefined : node.name.slice(0, dot);
+    const memberName = node.name.slice(dot + 1);
+    const value = namespace === undefined ? undefined : namespaces.get(namespace)?.get(memberName);
+    if (namespace === undefined || value === undefined) {
+      folded.push(node);
+    } else {
+      let members = groups.get(namespace);
+      if (!members) {
+        members = [];
+        groups.set(namespace, members);
+        folded.push(new ExportNode(namespace, new EnumNode(new TypeName(namespace), members, undefined), undefined));
+      }
+      // Typed as a string, but the parser stores numeric enum values as numbers too; do
+      // the same so both forms render alike.
+      members.push(new EnumMember(memberName, value, node.documentation));
+    }
+  }
+  return folded;
+}
+
+/**
+ * Writes the declaration of a constant group as it is exported: a namespace of constants
+ * for a namespace export, an enum otherwise.
+ */
+export function formatConstantGroupDeclaration(name, group, asNamespace) {
+  const members = group.members.map(member => {
+    // Enum members hold the literal's value, numbers included; a computed member has none.
+    const value = member.value;
+    const literal = typeof value === 'number' ? String(value) : JSON.stringify(value);
+    const comment = member.documentation ? formatPropertyComment(member.documentation) : undefined;
+    let declaration = `${member.name} = ${literal},`;
+    if (asNamespace) {
+      declaration = `const ${member.name}: ${literal};`;
+    } else if (value === undefined) {
+      declaration = `${member.name},`;
+    }
+    return comment ? `${comment}\n${declaration}` : declaration;
+  });
+  return asNamespace ? `declare namespace ${name} {\n${members.join('\n')}\n}` : `enum ${name} {\n${members.join('\n')}\n}`;
+}
+
+/**
+ * Resolves which component each constant group documents from its name: the component's
+ * name with its dots removed, followed by `DataAttributes` or `CssVariables`.
+ *
+ * Throws when the name before the suffix is not exactly one of the exported components.
+ *
+ * @returns Targets keyed by the group's export name, and each component's groups
+ */
+export function matchConstantGroups(exports) {
+  const targets = new Map();
+  const byComponent = new Map();
+  const componentsByFlatName = new Map();
+  for (const node of exports) {
+    if (isComponentType(node.type)) {
+      const flatName = node.name.replaceAll('.', '');
+      const names = componentsByFlatName.get(flatName);
+      if (names) {
+        names.push(node.name);
+      } else {
+        componentsByFlatName.set(flatName, [node.name]);
+      }
+    }
+  }
+  const kinds = Object.keys(KIND_SUFFIXES);
+  for (const node of exports) {
+    // Names are compared without dots, like the component names they stand for, so a group
+    // exported inside a namespace (`Toolbar.ButtonDataAttributes`) matches too.
+    const groupName = node.name.replaceAll('.', '');
+    const kind = kinds.find(candidate => groupName.endsWith(KIND_SUFFIXES[candidate]) && groupName.length > KIND_SUFFIXES[candidate].length);
+    if (kind && isEnumType(node.type)) {
+      const flatName = groupName.slice(0, -KIND_SUFFIXES[kind].length);
+      const components = componentsByFlatName.get(flatName) ?? [];
+      if (components.length !== 1) {
+        throw new Error(components.length === 0 ? `[constantGroups] ${node.name} - no exported component is named ${flatName}` : `[constantGroups] ${node.name} - ${components.join(', ')} are all named ${flatName}`);
+      }
+      const [component] = components;
+      targets.set(node.name, {
+        component,
+        kind
+      });
+      const groups = byComponent.get(component) ?? {};
+      groups[kind] ??= node.type;
+      byComponent.set(component, groups);
+    }
+  }
+  return {
+    targets,
+    byComponent
+  };
+}

package/pipeline/loadServerTypesMeta/formatComponent.d.mts

@@ -1,5 +1,6 @@
 import type * as tae from 'typescript-api-extractor';
 import type { FormattedProperty, FormattedEnumMember, FormatInlineTypeOptions, DescriptionReplacement } from "./format.mjs";
+import type { ComponentConstantGroups } from "./constantGroups.mjs";
 import type { TypeRewriteContext } from "./rewriteTypes.mjs";
 import type { ExternalTypesCollector } from "./externalTypes.mjs";
 import type { HastRoot } from "../../CodeHighlighter/types.mjs";
@@ -20,10 +21,8 @@ export type ComponentTypeMeta = {
  * Options for customizing component data formatting.
  */
 export interface FormatComponentOptions {
-  /** Suffix for data attributes enum name (default: 'DataAttributes') */
-  dataAttributesSuffix?: string;
-  /** Suffix for CSS variables enum name (default: 'CssVars') */
-  cssVariablesSuffix?: string;
+  /** The constant groups holding this component's tables (see `matchConstantGroups`) */
+  constantGroups?: ComponentConstantGroups;
   /** Pattern/replacement pairs to apply to descriptions */
   descriptionReplacements?: DescriptionReplacement[];
   /** Options for inline type formatting (e.g., unionPrintWidth) */
@@ -44,7 +43,7 @@ export interface FormatComponentOptions {
  */
 export declare function formatComponentData(component: tae.ExportNode & {
   type: tae.ComponentNode;
-}, allExports: tae.ExportNode[], typeNameMap: Record<string, string>, rewriteContext: TypeRewriteContext, options?: FormatComponentOptions): Promise<ComponentTypeMeta>;
+}, typeNameMap: Record<string, string>, rewriteContext: TypeRewriteContext, options?: FormatComponentOptions): Promise<ComponentTypeMeta>;
 /**
  * Type guard to check if an export is a public component that should be documented.
  *

package/pipeline/loadServerTypesMeta/formatComponent.mjs

@@ -20,10 +20,8 @@ import * as memberOrder from "../loadServerTypesText/order.mjs";
  *
  * The component must be validated with `isPublicComponent()` before calling this function.
  */
-export async function formatComponentData(component, allExports, typeNameMap, rewriteContext, options = {}) {
+export async function formatComponentData(component, typeNameMap, rewriteContext, options = {}) {
   const {
-    dataAttributesSuffix = 'DataAttributes',
-    cssVariablesSuffix = 'CssVars',
     descriptionReplacements,
     formatting,
     externalTypes
@@ -34,91 +32,11 @@ export async function formatComponentData(component, allExports, typeNameMap, re
   const descriptionText = component.documentation?.description ? applyDescriptionReplacements(component.documentation.description, descriptionReplacements) : undefined;
   const description = descriptionText ? await parseMarkdownToHast(descriptionText) : undefined;
 
-  // Find data attributes and CSS variables in a single loop
-  let dataAttributes;
-  let cssVariables;
-
-  // For DataAttributes/CssVars lookup, use the originalName (before transformations).
-  // Example for re-exported component:
-  //   - Component: ContextMenu.Backdrop (transformed from MenuBackdrop)
-  //   - originalName: MenuBackdrop
-  //   - We look for: MenuBackdropDataAttributes (using originalName + suffix)
-  //   - That export's originalName will also be MenuBackdropDataAttributes
-  const originalName = component.originalName;
-  const componentNameForLookup = originalName || component.name.replace(/\./g, '');
-  const dataAttributesName = `${componentNameForLookup}${dataAttributesSuffix}`;
-  const cssVariablesName = `${componentNameForLookup}${cssVariablesSuffix}`;
-
-  // Get the component's short name (e.g., "Trigger" from "AlertDialog.Trigger")
-  const componentShortName = component.name.split('.').pop() || component.name;
-  const dataAttributesSuffixWithShortName = `${componentShortName}${dataAttributesSuffix}`;
-  const cssVariablesSuffixWithShortName = `${componentShortName}${cssVariablesSuffix}`;
-
-  // Look for DataAttributes/CssVars by checking originalName on each export
-  // First pass: exact match
-  for (const node of allExports) {
-    const nodeOriginalName = node.originalName;
-    const nodeName = nodeOriginalName || node.name;
-    if (nodeName === dataAttributesName) {
-      dataAttributes = node;
-    } else if (nodeName === cssVariablesName) {
-      cssVariables = node;
-    }
-
-    // Early exit if we found both
-    if (dataAttributes && cssVariables) {
-      break;
-    }
-  }
-
-  // Fallback: For re-exported components (like AlertDialog.Trigger which re-exports DialogTrigger),
-  // the DataAttributes file uses the original component name (DialogTriggerDataAttributes).
-  // If we didn't find an exact match, look for any DataAttributes ending with the component's
-  // short name (e.g., "TriggerDataAttributes").
-  // Priority: prefer DataAttributes whose prefix is contained in the component's namespace
-  // (e.g., for AlertDialog.Trigger, prefer DialogTriggerDataAttributes over MenuTriggerDataAttributes)
-  if (!dataAttributes || !cssVariables) {
-    // Get the component's namespace (e.g., "AlertDialog" from "AlertDialog.Trigger")
-    const componentNamespace = component.name.includes('.') ? component.name.substring(0, component.name.lastIndexOf('.')) : '';
-
-    // Collect all matching candidates
-    const dataAttributesCandidates = [];
-    const cssVariablesCandidates = [];
-    for (const node of allExports) {
-      const nodeOriginalName = node.originalName;
-      const nodeName = nodeOriginalName || node.name;
-
-      // Check if this export ends with the component's short name + suffix
-      if (!dataAttributes && nodeName.endsWith(dataAttributesSuffixWithShortName)) {
-        // Extract the prefix (e.g., "Dialog" from "DialogTriggerDataAttributes")
-        const prefix = nodeName.slice(0, -dataAttributesSuffixWithShortName.length);
-        // Priority: 2 if prefix is contained in namespace (related component), 1 otherwise
-        const priority = componentNamespace.includes(prefix) ? 2 : 1;
-        dataAttributesCandidates.push({
-          node,
-          priority
-        });
-      }
-      if (!cssVariables && nodeName.endsWith(cssVariablesSuffixWithShortName)) {
-        const prefix = nodeName.slice(0, -cssVariablesSuffixWithShortName.length);
-        const priority = componentNamespace.includes(prefix) ? 2 : 1;
-        cssVariablesCandidates.push({
-          node,
-          priority
-        });
-      }
-    }
-
-    // Select the highest priority candidate
-    if (!dataAttributes && dataAttributesCandidates.length > 0) {
-      dataAttributesCandidates.sort((a, b) => b.priority - a.priority);
-      dataAttributes = dataAttributesCandidates[0].node;
-    }
-    if (!cssVariables && cssVariablesCandidates.length > 0) {
-      cssVariablesCandidates.sort((a, b) => b.priority - a.priority);
-      cssVariables = cssVariablesCandidates[0].node;
-    }
-  }
+  // The component's data attributes and CSS variables are the constant groups matched to it.
+  const {
+    dataAttributes,
+    cssVariables
+  } = options.constantGroups ?? {};
   const raw = {
     name: component.name,
     description,
@@ -131,8 +49,8 @@ export async function formatComponentData(component, allExports, typeNameMap, re
       externalTypes,
       descriptionReplacements
     }), options.ordering?.props ?? memberOrder.props),
-    dataAttributes: dataAttributes && dataAttributes.type.kind === 'enum' ? sortObjectByKeys(await formatEnum(dataAttributes.type, descriptionReplacements), options.ordering?.dataAttributes ?? memberOrder.dataAttributes) : {},
-    cssVariables: cssVariables && cssVariables.type.kind === 'enum' ? sortObjectByKeys(await formatEnum(cssVariables.type, descriptionReplacements), options.ordering?.cssVariables ?? memberOrder.cssVariables) : {}
+    dataAttributes: dataAttributes ? sortObjectByKeys(await formatEnum(dataAttributes, descriptionReplacements), options.ordering?.dataAttributes ?? memberOrder.dataAttributes) : {},
+    cssVariables: cssVariables ? sortObjectByKeys(await formatEnum(cssVariables, descriptionReplacements), options.ordering?.cssVariables ?? memberOrder.cssVariables) : {}
   };
 
   // Post-process type strings to align naming across re-exports and hide internal suffixes.

package/pipeline/loadServerTypesMeta/formatRaw.d.mts

@@ -1,5 +1,6 @@
 import type * as tae from 'typescript-api-extractor';
 import type { FormattedProperty, FormatInlineTypeOptions, DescriptionReplacement } from "./format.mjs";
+import type { ConstantGroupTarget } from "./constantGroups.mjs";
 import type { TypeRewriteContext } from "./rewriteTypes.mjs";
 import type { ExternalTypesCollector } from "./externalTypes.mjs";
 import type { HastRoot } from "../../CodeHighlighter/types.mjs";
@@ -12,7 +13,7 @@ export interface ReExportInfo {
   /** Anchor slug for linking (e.g., "#trigger") */
   slug: string;
   /** What kind of type this re-exports */
-  suffix: 'props' | 'css-variables' | 'data-attributes';
+  suffix: 'props';
 }
 /**
  * Formatted raw type metadata with the type declaration as a formatted code string.
@@ -46,11 +47,11 @@ export type RawTypeMeta = {
    */
   reExportOf?: ReExportInfo;
   /**
-   * For DataAttributes types, the component name this type belongs to.
+   * For constant groups holding a component's data attributes, that component's name.
    */
   dataAttributesOf?: string;
   /**
-   * For CssVars types, the component name this type belongs to.
+   * For constant groups holding a component's CSS variables, that component's name.
    */
   cssVarsOf?: string;
   /**
@@ -75,6 +76,10 @@ export interface FormatRawOptions {
   externalTypes?: ExternalTypesCollector;
   /** Pattern/replacement pairs to apply to descriptions */
   descriptionReplacements?: DescriptionReplacement[];
+  /** The component table this constant group holds (see `matchConstantGroups`) */
+  constantGroup?: ConstantGroupTarget;
+  /** Whether the constant group was exported as a namespace of constants rather than an enum */
+  constantNamespace?: boolean;
 }
 /**
  * Formats a raw type export into a structured metadata object with formatted code.

package/pipeline/loadServerTypesMeta/formatRaw.mjs

@@ -1,6 +1,7 @@
 import { prettyFormat, parseMarkdownToHast, applyDescriptionReplacements, formatProperties, extractTypeParameters } from "./format.mjs";
 import { formatType } from "./formatType.mjs";
 import { isEnumType, isObjectType } from "./typeGuards.mjs";
+import { formatConstantGroupDeclaration } from "./constantGroups.mjs";
 import { rewriteTypeStringsDeep } from "./rewriteTypes.mjs";
 
 /**
@@ -33,7 +34,9 @@ import { rewriteTypeStringsDeep } from "./rewriteTypes.mjs";
  */
 export async function formatRawData(exportNode, displayName, typeNameMap, rewriteContext, _options = {}) {
   const {
-    descriptionReplacements
+    descriptionReplacements,
+    constantGroup,
+    constantNamespace
   } = _options;
   const descriptionText = exportNode.documentation?.description ? applyDescriptionReplacements(exportNode.documentation.description, descriptionReplacements) : undefined;
   const description = descriptionText ? await parseMarkdownToHast(descriptionText) : undefined;
@@ -50,8 +53,9 @@ export async function formatRawData(exportNode, displayName, typeNameMap, rewrit
       };
     }));
 
-    // For enums, still generate the code block but also include members
-    const formattedCode = await generateFormattedCode(exportNode, displayName, typeNameMap);
+    // For enums, still generate the code block but also include members. The declaration
+    // follows how the group is exported: an enum, or a namespace of constants.
+    const formattedCode = await prettyFormat(formatConstantGroupDeclaration(displayName.replace(/\./g, ''), exportNode.type, Boolean(constantNamespace)), null);
 
     // Rewrite type names in descriptions (but NOT in formattedCode which is valid TypeScript syntax)
     const rewrittenDescriptionText = descriptionText ? rewriteTypeStringsDeep(descriptionText, rewriteContext) : undefined;
@@ -62,36 +66,11 @@ export async function formatRawData(exportNode, displayName, typeNameMap, rewrit
       formattedCode,
       enumMembers
     };
-    return raw;
-  }
-
-  // Handle DataAttributes types
-  if (displayName.endsWith('.DataAttributes')) {
-    const componentName = displayName.replace('.DataAttributes', '');
-    const formattedCode = await generateFormattedCode(exportNode, displayName, typeNameMap);
-    const rewrittenDescriptionText = descriptionText ? rewriteTypeStringsDeep(descriptionText, rewriteContext) : undefined;
-    const raw = {
-      name: displayName,
-      description,
-      descriptionText: rewrittenDescriptionText,
-      formattedCode,
-      dataAttributesOf: componentName
-    };
-    return raw;
-  }
-
-  // Handle CssVars types
-  if (displayName.endsWith('.CssVars')) {
-    const componentName = displayName.replace('.CssVars', '');
-    const formattedCode = await generateFormattedCode(exportNode, displayName, typeNameMap);
-    const rewrittenDescriptionText = descriptionText ? rewriteTypeStringsDeep(descriptionText, rewriteContext) : undefined;
-    const raw = {
-      name: displayName,
-      description,
-      descriptionText: rewrittenDescriptionText,
-      formattedCode,
-      cssVarsOf: componentName
-    };
+    if (constantGroup?.kind === 'dataAttributes') {
+      raw.dataAttributesOf = constantGroup.component;
+    } else if (constantGroup?.kind === 'cssVariables') {
+      raw.cssVarsOf = constantGroup.component;
+    }
     return raw;
   }
 

package/pipeline/loadServerTypesMeta/formatType.d.mts

@@ -20,4 +20,9 @@ export declare function formatType(type: tae.AnyType, options: FormatTypeOptions
  * processing, then runs the output through `prettyFormat()` for consistent styling.
  */
 export declare function prettyFormatType(type: tae.AnyType, options: FormatTypeOptions): Promise<string>;
-export declare function getFullyQualifiedName(typeName: tae.TypeName, exportNames: string[], typeNameMap: Record<string, string>, preserveTypeParameters?: boolean): string;
+export declare function getFullyQualifiedName(typeName: tae.TypeName, exportNames: string[], typeNameMap: Record<string, string>, preserveTypeParameters?: boolean): string;
+/**
+ * Formats a JSDoc comment block from property documentation.
+ * Returns undefined if no meaningful content to document.
+ */
+export declare function formatPropertyComment(documentation: tae.Documentation): string | undefined;

package/pipeline/loadServerTypesMeta/formatType.mjs

@@ -818,7 +818,7 @@ function normalizeQuotes(str) {
  * Formats a JSDoc comment block from property documentation.
  * Returns undefined if no meaningful content to document.
  */
-function formatPropertyComment(documentation) {
+export function formatPropertyComment(documentation) {
   const lines = [];
   if (documentation.description) {
     lines.push(...documentation.description.split('\n'));

package/pipeline/loadServerTypesMeta/loadServerTypesMeta.d.mts

@@ -119,7 +119,6 @@ export interface LoadServerTypesMetaResult extends OrganizeTypesResult<TypesMeta
  * This function handles:
  * - Loading TypeScript configuration
  * - Resolving library source files and variants
- * - Finding meta files (DataAttributes, CssVars)
  * - Processing types via worker thread
  * - Formatting component, hook, function, and raw types
  * - Collecting external types referenced in props/params

package/pipeline/loadServerTypesMeta/loadServerTypesMeta.mjs

@@ -1,8 +1,7 @@
 // Can use node: imports here since this is server-only code
 import path from 'node:path';
-import { readFile, stat } from 'node:fs/promises';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { parseImportsAndComments, extractNameAndSlugFromUrl } from "../loaderUtils/index.mjs";
+import { pathToFileURL } from 'node:url';
+import { extractNameAndSlugFromUrl } from "../loaderUtils/index.mjs";
 import { nameMark, performanceMeasure } from "../loadPrecomputedCodeHighlighter/performanceLogger.mjs";
 import { loadTypescriptConfig } from "./loadTypescriptConfig.mjs";
 import { resolveLibrarySourceFiles } from "./resolveLibrarySourceFiles.mjs";
@@ -13,7 +12,7 @@ import { formatFunctionData, isPublicFunction } from "./formatFunction.mjs";
 import { formatRawData } from "./formatRaw.mjs";
 import { prettyFormat } from "./format.mjs";
 import { buildTypeCompatibilityMap } from "./rewriteTypes.mjs";
-import { findMetaFiles } from "./findMetaFiles.mjs";
+import { matchConstantGroups } from "./constantGroups.mjs";
 import { getWorkerManager } from "./workerManager.mjs";
 import { reconstructPerformanceLogs } from "./performanceTracking.mjs";
 import { typeSuffixes as defaultTypeSuffixes } from "../loadServerTypesText/order.mjs";
@@ -25,7 +24,6 @@ const functionName = 'Load Server Types Meta';
  * This function handles:
  * - Loading TypeScript configuration
  * - Resolving library source files and variants
- * - Finding meta files (DataAttributes, CssVars)
  * - Processing types via worker thread
  * - Formatting component, hook, function, and raw types
  * - Collecting external types referenced in props/params
@@ -74,94 +72,12 @@ export async function loadServerTypesMeta(options) {
     }, [functionName, relativePath]);
   }
 
-  // Collect all entrypoints for optimized program creation
-  // Include both the component entrypoints and their meta files (DataAttributes, CssVars)
-  // These are file:// URLs from resolveLibrarySourceFiles
-  const resolvedEntrypointUrls = Array.from(resolvedVariantMap.values());
-
-  // Parse exports from library source files to find re-exported directories
-  // This helps us discover DataAttributes/CssVars files from re-exported components
-  const reExportedDirUrls = new Set();
-  await Promise.all(resolvedEntrypointUrls.map(async entrypointUrl => {
-    try {
-      // Convert file:// URL to filesystem path for Node.js fs APIs
-      const fsEntrypoint = fileURLToPath(entrypointUrl);
-      const sourceCode = await readFile(fsEntrypoint, 'utf-8');
-      const parsed = parseImportsAndComments(sourceCode, entrypointUrl);
-
-      // Look for relative exports (e.g., '../menu/', './Button', etc.)
-      await Promise.all(Object.keys(parsed.relative || {}).map(async exportPath => {
-        if (exportPath.startsWith('..') || exportPath.startsWith('.')) {
-          // Resolve to absolute filesystem path
-          const absoluteFsPath = path.resolve(path.dirname(fsEntrypoint), exportPath);
-
-          // Check if this path exists as a directory
-          // If not, it might be a module reference (e.g., '../menu/backdrop/MenuBackdrop' -> MenuBackdrop.tsx)
-          // In that case, we want to add the parent directory
-          try {
-            const stats = await stat(absoluteFsPath);
-            if (stats.isDirectory()) {
-              // It's a directory, add it with trailing slash so path.dirname returns this directory
-              reExportedDirUrls.add(pathToFileURL(`${absoluteFsPath}/`).href);
-            }
-          } catch {
-            // Path doesn't exist as-is. Check if it exists with common extensions
-            const extensions = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
-            for (const ext of extensions) {
-              try {
-                // eslint-disable-next-line no-await-in-loop
-                const fileStats = await stat(absoluteFsPath + ext);
-                if (fileStats.isFile()) {
-                  // It's a file reference, add the parent directory as file:// URL
-                  // Add trailing slash so path.dirname returns this directory, not its parent
-                  const parentDir = path.dirname(absoluteFsPath);
-                  reExportedDirUrls.add(pathToFileURL(`${parentDir}/`).href);
-                  break;
-                }
-              } catch {
-                // Continue checking other extensions
-              }
-            }
-
-            // If not found as file or directory, it might be a bare module reference - skip it
-          }
-        }
-      }));
-    } catch (error) {
-      // If we can't parse a file, just skip it
-      console.warn(`[Main] Failed to parse exports from ${entrypointUrl}:`, error instanceof Error ? error.message : error);
-    }
-  }));
-
-  // Find meta files from the library source directories and re-exported directories
-  // Convert file:// URLs to filesystem paths for findMetaFiles
-  const entrypointFiles = resolvedEntrypointUrls.map(url => fileURLToPath(url));
-  const reExportedDirs = Array.from(reExportedDirUrls).map(url => fileURLToPath(url));
-
-  // findMetaFiles accepts filesystem paths and returns filesystem paths
-  // We search both entrypoint files and re-exported directories for meta files,
-  // but only include actual files (entrypoints + found meta files), not directories
-  const metaFilesFromEntrypoints = await Promise.all(entrypointFiles.map(fsPath => findMetaFiles(fsPath))).then(results => results.flat());
-  const metaFilesFromReExports = await Promise.all(reExportedDirs.map(fsPath => findMetaFiles(fsPath))).then(results => results.flat());
-
-  // Meta files are DataAttributes/CssVars files that aren't imported but contain type info
-  const metaFiles = [...metaFilesFromEntrypoints, ...metaFilesFromReExports];
-
-  // All files needed for the TypeScript program (entrypoints + meta files)
-  const allEntrypoints = [...entrypointFiles, ...metaFiles];
-  currentMark = performanceMeasure(currentMark, {
-    mark: 'Meta Files Resolved',
-    measure: 'Meta Files Resolution'
-  }, [functionName, relativePath]);
-
   // Process types — use the worker manager singleton (which adapts to main vs worker thread)
   const workerManager = getWorkerManager();
   const workerStartTime = performance.now();
   const workerResult = await workerManager.processTypes({
     projectPath: config.projectPath,
     compilerOptions: config.options,
-    allEntrypoints,
-    metaFiles,
     resolvedVariantMap: Array.from(resolvedVariantMap.entries()),
     dependencies: config.dependencies,
     rootContextDir,
@@ -199,7 +115,7 @@ export async function loadServerTypesMeta(options) {
 
   // Build type compatibility map once from all exports across all variants
   // This map is used to rewrite type references (e.g., Dialog.Trigger.State -> AlertDialog.Trigger.State)
-  const allRawExports = Object.values(rawVariantData).flatMap(v => v.allTypes);
+  const allRawExports = Object.values(rawVariantData).flatMap(v => v.exports);
   const allExportNames = Array.from(new Set(allRawExports.map(exp => exp.name)));
   const typeCompatibilityMap = buildTypeCompatibilityMap(allRawExports, allExportNames);
 
@@ -223,18 +139,21 @@ export async function loadServerTypesMeta(options) {
     // Each variant shares the same collected map so types are deduplicated automatically.
     const externalTypesCollector = {
       collected: collectedExternalTypes,
-      allExports: variantResult.allTypes,
+      allExports: variantResult.exports,
       pattern: externalTypesPatternRegex,
       typeNameMap: variantResult.typeNameMap
     };
+    const constantGroups = matchConstantGroups(variantResult.exports);
+    const constantNamespaces = new Set(variantResult.constantNamespaces);
 
     // Process all exports in parallel within each variant
     const types = await Promise.all(variantResult.exports.map(async exportNode => {
       if (isPublicComponent(exportNode)) {
-        const formattedData = await formatComponentData(exportNode, variantResult.allTypes, variantResult.typeNameMap || {}, rewriteContext, {
+        const formattedData = await formatComponentData(exportNode, variantResult.typeNameMap || {}, rewriteContext, {
           formatting: formattingOptions,
           externalTypes: externalTypesCollector,
           ordering: options.ordering,
+          constantGroups: constantGroups.byComponent.get(exportNode.name),
           descriptionReplacements: options.descriptionReplacements
         });
         return {
@@ -284,7 +203,9 @@ export async function loadServerTypesMeta(options) {
       const formattedData = await formatRawData(exportNode, exportNode.name, variantResult.typeNameMap || {}, rewriteContext, {
         formatting: formattingOptions,
         externalTypes: externalTypesCollector,
-        descriptionReplacements: options.descriptionReplacements
+        descriptionReplacements: options.descriptionReplacements,
+        constantGroup: constantGroups.targets.get(exportNode.name),
+        constantNamespace: constantNamespaces.has(exportNode.name)
       });
       return {
         type: 'raw',
@@ -470,11 +391,11 @@ export async function loadServerTypesMeta(options) {
 
     // Extract component name and suffix (e.g., "ButtonProps" -> component: "Button", suffix: "Props")
     // Handle both namespaced (ContextMenu.Root.Props) and non-namespaced (ButtonProps) names
-    const parts = typeMeta.name.match(/^(.+)\.(Props|State|DataAttributes|CssVars)$/);
+    const parts = typeMeta.name.match(/^(.+)\.Props$/);
     if (!parts) {
       return typeMeta;
     }
-    const [, componentName, suffix] = parts;
+    const [, componentName] = parts;
 
     // Find the corresponding component by checking both the full name and just the last part
     // e.g., for "ContextMenu.Root.Props", check both "ContextMenu.Root" and "Root"
@@ -484,7 +405,7 @@ export async function loadServerTypesMeta(options) {
     }
 
     // Check if Props is a re-export of the component's props
-    if (suffix === 'Props' && correspondingComponent.data.props) {
+    if (correspondingComponent.data.props) {
       const hasProps = Object.keys(correspondingComponent.data.props).length > 0;
       if (hasProps) {
         // Extract the display name (last part after dot) for the link text
@@ -504,48 +425,6 @@ export async function loadServerTypesMeta(options) {
         };
       }
     }
-
-    // Check if DataAttributes is a re-export of the component's data attributes
-    if (suffix === 'DataAttributes' && correspondingComponent.data.dataAttributes) {
-      const hasDataAttributes = Object.keys(correspondingComponent.data.dataAttributes).length > 0;
-      if (hasDataAttributes) {
-        // Extract the display name (last part after dot) for the link text
-        const displayName = componentName.includes('.') ? componentName.split('.').pop() : componentName;
-        return {
-          type: 'raw',
-          name: typeMeta.name,
-          data: {
-            ...typeMeta.data,
-            reExportOf: {
-              name: displayName,
-              slug: `#${displayName.toLowerCase()}`,
-              suffix: 'data-attributes'
-            }
-          }
-        };
-      }
-    }
-
-    // Check if CssVars is a re-export of the component's CSS variables
-    if (suffix === 'CssVars' && correspondingComponent.data.cssVariables) {
-      const hasCssVariables = Object.keys(correspondingComponent.data.cssVariables).length > 0;
-      if (hasCssVariables) {
-        // Extract the display name (last part after dot) for the link text
-        const displayName = componentName.includes('.') ? componentName.split('.').pop() : componentName;
-        return {
-          type: 'raw',
-          name: typeMeta.name,
-          data: {
-            ...typeMeta.data,
-            reExportOf: {
-              name: displayName,
-              slug: `#${displayName.toLowerCase()}`,
-              suffix: 'css-variables'
-            }
-          }
-        };
-      }
-    }
     return typeMeta;
   });
 

package/pipeline/loadServerTypesMeta/parseTestSources.d.mts

@@ -1,3 +1,4 @@
+import ts from 'typescript';
 import type * as tae from 'typescript-api-extractor';
 export interface ParseTestSourcesOptions {
   /**
@@ -21,4 +22,13 @@ export interface ParseTestSourcesOptions {
  * 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[];
+export declare function parseTestSources(sources: Record<string, string>, options?: ParseTestSourcesOptions): tae.ExportNode[];
+/**
+ * Builds a TypeScript program over in-memory sources, for tests that need the checker
+ * itself rather than parsed exports. Sources are keyed and resolved as in
+ * `parseTestSources`, and `entrypoint` is the path of the first one.
+ */
+export declare function createTestProgram(sources: Record<string, string>, lib?: string): {
+  program: ts.Program;
+  entrypoint: string;
+};

package/pipeline/loadServerTypesMeta/parseTestSources.mjs

@@ -16,9 +16,21 @@ const LIB_PATH = `${ROOT}/lib.d.ts`;
  */
 export function parseTestSources(sources, options = {}) {
   const {
-    lib,
-    parserOptions
-  } = options;
+    program,
+    entrypoint
+  } = createTestProgram(sources, options.lib);
+  return parseFromProgram(entrypoint, program, {
+    ...PARSER_OPTIONS,
+    ...options.parserOptions
+  }).exports;
+}
+
+/**
+ * Builds a TypeScript program over in-memory sources, for tests that need the checker
+ * itself rather than parsed exports. Sources are keyed and resolved as in
+ * `parseTestSources`, and `entrypoint` is the path of the first one.
+ */
+export function createTestProgram(sources, lib) {
   const sourceFiles = new Map();
   if (lib !== undefined) {
     sourceFiles.set(LIB_PATH, ts.createSourceFile(LIB_PATH, lib, ts.ScriptTarget.ESNext, true));
@@ -48,8 +60,8 @@ export function parseTestSources(sources, options = {}) {
     rootDir: ROOT,
     noLib: lib === undefined
   }, host);
-  return parseFromProgram(entryPaths[0], program, {
-    ...PARSER_OPTIONS,
-    ...parserOptions
-  }).exports;
+  return {
+    program,
+    entrypoint: entryPaths[0]
+  };
 }

package/pipeline/loadServerTypesMeta/processTypes.d.mts

@@ -4,7 +4,8 @@ import type { InheritedExternalPropsConfig } from "./inheritedExternalProps.mjs"
 import type { PerformanceLog } from "./performanceTracking.mjs";
 export interface VariantResult {
   exports: ExportNode[];
-  allTypes: ExportNode[];
+  /** Names of the exports folded from namespaces of constants (see `findConstantNamespaces`) */
+  constantNamespaces: string[];
   namespaces: string[];
   typeNameMap?: Record<string, string>;
 }
@@ -12,10 +13,6 @@ export interface WorkerRequest {
   requestId?: number;
   projectPath: string;
   compilerOptions: CompilerOptions;
-  /** All files for the TypeScript program (entrypoints + meta files) */
-  allEntrypoints: string[];
-  /** Meta files (DataAttributes, CssVars) - not entrypoints, just additional type info */
-  metaFiles: string[];
   /** Map serialized as array of [variantName, fileUrl] tuples where fileUrl uses file:// protocol */
   resolvedVariantMap: Array<[string, string]>;
   /** Dependency paths (filesystem paths, not URLs) */
@@ -37,9 +34,6 @@ export interface WorkerResponse {
   allDependencies?: string[];
   performanceLogs?: PerformanceLog[];
   error?: string;
-  debug?: {
-    metaFilesCount?: number;
-  };
 }
 /**
  * Process TypeScript types for the given request.

package/pipeline/loadServerTypesMeta/processTypes.mjs

@@ -4,7 +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 { findConstantNamespaces, foldConstantNamespaces } from "./constantGroups.mjs";
 import { PARSER_OPTIONS } from "./constants.mjs";
 import { extractJSDocText, isJSDocNodeArray } from "./extractJSDocText.mjs";
 import { PerformanceTracker } from "./performanceTracking.mjs";
@@ -76,7 +76,7 @@ function collectDocumentedNames(variantData) {
     }
   };
   for (const variant of Object.values(variantData)) {
-    for (const node of variant.allTypes) {
+    for (const node of variant.exports) {
       addName(node.name);
     }
     if (variant.typeNameMap) {
@@ -266,10 +266,9 @@ export async function processTypes(request) {
   try {
     // Create optimized TypeScript program
     const programWrapperStart = tracker.mark(nameMark(functionName, 'Program Creation Start', [request.relativePath], true));
-    const program = createOptimizedProgram(request.projectPath, request.compilerOptions, request.allEntrypoints, {}, tracker, functionName, [request.relativePath]);
+    const program = createOptimizedProgram(request.projectPath, request.compilerOptions, request.resolvedVariantMap.map(([, fileUrl]) => fileURLToPath(fileUrl)), {}, tracker, functionName, [request.relativePath]);
     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 = {};
 
     // Process variants in parallel
     const resolvedVariantMap = new Map(request.resolvedVariantMap);
@@ -288,9 +287,12 @@ export async function processTypes(request) {
 
         // Use parseFromProgram directly - it now handles namespace exports,
         // type aliases, and re-exports properly
-        const {
-          exports
-        } = parseFromProgram(entrypoint, program, PARSER_OPTIONS);
+        const parsed = parseFromProgram(entrypoint, program, PARSER_OPTIONS);
+
+        // Modules of constants exported as a namespace (`export * as ButtonDataAttributes`)
+        // arrive flattened into one export per member; document each as a single group.
+        const constantNamespaces = findConstantNamespaces(entrypoint, program);
+        const exports = foldConstantNamespaces(parsed.exports, constantNamespaces);
 
         // Re-add configured props that the parser dropped because they are
         // inherited from an externally declared type in node_modules
@@ -317,36 +319,7 @@ export async function processTypes(request) {
         // Include files from the TypeScript program for hot reloading support
         // We collect only files imported by THIS entrypoint, not all files in the program
         const entrypointDependencies = collectSourceFileDependencies(sourceFile, program, new Set());
-        const dependencies = [...request.dependencies, entrypoint, ...request.metaFiles, ...entrypointDependencies];
-
-        // Parse meta files (DataAttributes, CssVars) for additional type information
-        const allInternalTypes = request.metaFiles.map(file => {
-          if (internalTypesCache[file]) {
-            return internalTypesCache[file];
-          }
-
-          // Ensure the file is loaded in the program first
-          // This is important for meta files (DataAttributes, CssVars) that aren't imported
-          const fileSourceFile = program.getSourceFile(file);
-          if (!fileSourceFile) {
-            console.warn(`[processTypes] ${variantName} - Could not load source file: ${file}`);
-            return [];
-          }
-          const {
-            exports: internalExport
-          } = 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.
-          const groupExports = transformConstantGroup(file, internalExport);
-          internalTypesCache[file] = groupExports;
-          return groupExports;
-        });
-        const internalTypes = allInternalTypes.reduce((acc, cur) => {
-          acc.push(...cur);
-          return acc;
-        }, []);
-        const allTypes = [...exports, ...internalTypes];
+        const dependencies = [...request.dependencies, entrypoint, ...entrypointDependencies];
         const parseEnd = tracker.mark(nameMark(functionName, `Variant ${variantName} Parsed`, [request.relativePath]));
         tracker.measure(nameMark(functionName, `Variant ${variantName} Parsing`, [request.relativePath]), parseStart, parseEnd);
         const variantEnd = tracker.mark(nameMark(functionName, `Variant ${variantName} Complete`, [request.relativePath], true));
@@ -355,15 +328,12 @@ export async function processTypes(request) {
           variantName,
           variantData: {
             exports,
-            allTypes,
+            constantNamespaces: Array.from(constantNamespaces.keys()),
             namespaces,
             // Convert Map to Record for serialization across worker boundary
             typeNameMap: mergedTypeNameMap.size > 0 ? Object.fromEntries(mergedTypeNameMap) : undefined
           },
-          dependencies,
-          debug: {
-            metaFilesCount: request.metaFiles.length
-          }
+          dependencies
         };
       } catch (error) {
         throw new Error(`Failed to parse variant ${variantName} (${fileUrl}): \n${error && typeof error === 'object' && 'message' in error && error.message}`);
@@ -371,19 +341,15 @@ export async function processTypes(request) {
     });
     const variantResults = await Promise.all(variantPromises);
 
-    // Process results and collect dependencies and debug info
+    // Process results and collect dependencies
     const variantData = {};
     const allDependencies = [];
-    const debugInfo = {};
     for (const result of variantResults) {
       if (result) {
         variantData[result.variantName] = result.variantData;
         result.dependencies.forEach(file => {
           allDependencies.push(file);
         });
-        if (result.debug) {
-          debugInfo[result.variantName] = result.debug;
-        }
       }
     }
 
@@ -394,8 +360,7 @@ export async function processTypes(request) {
       success: true,
       variantData: serializedVariantData,
       allDependencies,
-      performanceLogs: tracker.getLogs(),
-      debug: Object.keys(debugInfo).length > 0 ? debugInfo[Object.keys(debugInfo)[0]] : undefined
+      performanceLogs: tracker.getLogs()
     };
   } catch (error) {
     return {

package/pipeline/syncTypes/generateTypesMarkdown.mjs

@@ -201,6 +201,9 @@ export async function generateTypesMarkdown(options) {
     // If there are multiple unique prefixes, don't strip anything
   }
 
+  // Strips the common prefix, as component headings always are
+  const stripCommonPrefix = part => commonPrefix && part.startsWith(`${commonPrefix}.`) ? part.slice(commonPrefix.length + 1) : part;
+
   // Helper function to generate markdown chunks for a single type
   // When useFullName is true, the type name is not stripped of the common prefix
   async function generateSingleTypeMarkdown(typeMeta, useFullName = false) {
@@ -228,12 +231,7 @@ export async function generateTypesMarkdown(options) {
     };
 
     // Helper to get display name - either full name or stripped prefix
-    const getDisplayName = part => {
-      if (useFullName) {
-        return part;
-      }
-      return commonPrefix && part.startsWith(`${commonPrefix}.`) ? part.slice(commonPrefix.length + 1) : part;
-    };
+    const getDisplayName = part => useFullName ? part : stripCommonPrefix(part);
     if (typeMeta.type === 'component') {
       // Use transformed name (e.g., "Component.Part" instead of "ComponentPart")
       const part = typeMeta.name;
@@ -599,14 +597,12 @@ export async function generateTypesMarkdown(options) {
       addHeading(3, displayName);
       if (data.reExportOf) {
         nodes.push(md.paragraph([md.text('Re-export of '), md.link(data.reExportOf.slug, data.reExportOf.name), md.text(` ${data.reExportOf.suffix}.`)]));
-      } else if (data.dataAttributesOf) {
-        const componentName = data.dataAttributesOf;
-        const anchorId = componentName.toLowerCase().replace(/\./g, '');
-        nodes.push(md.paragraph([md.text('Data attributes for '), md.link(`#${anchorId}`, componentName), md.text(' component.')]));
-      } else if (data.cssVarsOf) {
-        const componentName = data.cssVarsOf;
-        const anchorId = componentName.toLowerCase().replace(/\./g, '');
-        nodes.push(md.paragraph([md.text('CSS variables for '), md.link(`#${anchorId}`, componentName), md.text(' component.')]));
+      } else if (data.dataAttributesOf || data.cssVarsOf) {
+        // Link to the component whose table this group holds, then declare the group
+        // Link to the component's heading, named the way the heading itself is
+        const componentHeading = stripCommonPrefix(data.dataAttributesOf ?? data.cssVarsOf);
+        nodes.push(md.paragraph([md.text(data.dataAttributesOf ? 'Data attributes of ' : 'CSS variables of '), md.link(`#${componentHeading.toLowerCase().replaceAll('.', '')}`, componentHeading), md.text('.')]));
+        addCodeBlock(data.formattedCode, 'typescript');
       } else if (data.enumMembers && data.enumMembers.length > 0) {
         // Render enum as a table
         if (data.descriptionText) {

package/pipeline/loadServerTypesMeta/findMetaFiles.d.mts

@@ -1,9 +0,0 @@
-/**
- * Finds metadata files (DataAttributes, CssVars) in the directory of the given entrypoint file,
- * or recursively within the given directory.
- *
- * @param entrypoint - A filesystem path pointing to the entrypoint file or a directory
- * @param suffixes - File suffixes to search for (default: ['DataAttributes', 'CssVars'])
- * @returns Array of filesystem paths for matching files
- */
-export declare function findMetaFiles(entrypoint: string, suffixes?: string[]): Promise<string[]>;

package/pipeline/loadServerTypesMeta/findMetaFiles.mjs

@@ -1,45 +0,0 @@
-// eslint-disable-next-line n/prefer-node-protocol
-import path from 'path';
-// eslint-disable-next-line n/prefer-node-protocol
-import fs from 'fs/promises';
-function hasSuffix(suffixes, filename) {
-  return suffixes.some(suffix => filename.endsWith(`${suffix}.d.ts`) || filename.endsWith(`${suffix}.ts`) || filename.endsWith(`${suffix}.tsx`));
-}
-
-/**
- * Finds metadata files (DataAttributes, CssVars) in the directory of the given entrypoint file,
- * or recursively within the given directory.
- *
- * @param entrypoint - A filesystem path pointing to the entrypoint file or a directory
- * @param suffixes - File suffixes to search for (default: ['DataAttributes', 'CssVars'])
- * @returns Array of filesystem paths for matching files
- */
-export async function findMetaFiles(entrypoint, suffixes = ['DataAttributes', 'CssVars']) {
-  // Check if the path ends with / (directory hint) or check via stat
-  let dir;
-  if (entrypoint.endsWith('/')) {
-    // Path ends with / - it's explicitly a directory, walk it directly
-    dir = entrypoint.slice(0, -1); // Remove trailing slash for fs operations
-  } else {
-    // It's a file - walk its parent directory
-    dir = path.dirname(entrypoint);
-  }
-  const files = [];
-  async function walkDirectory(currentDir) {
-    const entries = await fs.readdir(currentDir, {
-      withFileTypes: true
-    });
-    const subdirectories = [];
-    for (const entry of entries) {
-      const fullPath = path.join(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        subdirectories.push(fullPath);
-      } else if (entry.isFile()) {
-        files.push(fullPath);
-      }
-    }
-    await Promise.all(subdirectories.map(subdir => walkDirectory(subdir)));
-  }
-  await walkDirectory(dir);
-  return files.filter(file => hasSuffix(suffixes, file));
-}

package/pipeline/loadServerTypesMeta/transformConstantGroup.d.mts

@@ -1,14 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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)];
-}