@mui/internal-docs-infra/pipeline/loadServerTypes/highlightTypesMeta.d.mts

MUI Infra - internal documentation creation tools.

/**
 * Highlighted code types processing for converting plain text types to syntax-highlighted HAST.
 *
 * This module runs after highlightTypes() in the loadServerTypes pipeline and:
 * 1. Converts typeText strings to syntax-highlighted HAST (type field)
 * 2. Derives shortType HAST from the highlighted type structure
 * 3. Generates detailedType HAST with expanded type references
 * 4. Converts defaultText to syntax-highlighted HAST (default field)
 */
import type { Root as HastRoot } from 'hast';
import { type TransformHtmlCodeBlockOptions } from "../transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
import { type TypesMeta, type ComponentTypeMeta, type HookTypeMeta, type FunctionTypeMeta, type ClassTypeMeta, type RawTypeMeta, type FormattedProperty, type FormattedParameter } from "../loadServerTypesMeta/index.mjs";
import type { FormattedMethod } from "../loadServerTypesMeta/formatClass.mjs";
import type { EnumMemberMeta } from "../loadServerTypesMeta/formatRaw.mjs";
import { type FormatInlineTypeOptions } from "./typeHighlighting.mjs";
import { type SerializedHastRoot, type SerializedHastCompressed, type TypesOutputFormat } from "./hastTypeUtils.mjs";
/** A HAST root or its serialized/compressed wrapper. */
type HastField = HastRoot | SerializedHastRoot | SerializedHastCompressed;
/**
 * Highlighted property with syntax-highlighted HAST fields.
 */
export interface HighlightedProperty extends Omit<FormattedProperty, 'typeText' | 'description' | 'example' | 'see'> {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  /** Example with syntax highlighting as HAST */
  example?: HastField;
  /** See-also links as HAST */
  see?: HastField;
  /** Syntax-highlighted type as HAST */
  type: HastField;
  /** Short simplified type for table display (e.g., "Union", "function") */
  shortType?: HastField;
  /** Default value with syntax highlighting as HAST */
  default?: HastField;
  /** Detailed expanded type view (only when different from basic type) */
  detailedType?: HastField;
}
/**
 * Highlighted class property with syntax-highlighted HAST fields.
 * Extends HighlightedProperty with class-specific modifiers.
 */
export interface HighlightedClassProperty extends HighlightedProperty {
  /** Whether this is a static property */
  isStatic?: boolean;
  /** Whether this property is readonly */
  readonly?: boolean;
}
/**
 * Highlighted parameter with syntax-highlighted HAST fields.
 */
export interface HighlightedParameter extends Omit<FormattedParameter, 'typeText' | 'description' | 'example' | 'see'> {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  /** Example with syntax highlighting as HAST */
  example?: HastField;
  /** See-also links as HAST */
  see?: HastField;
  /** Syntax-highlighted type as HAST */
  type: HastField;
  /** Short simplified type for table display (e.g., "Union", "function") */
  shortType?: HastField;
  /** Default value with syntax highlighting as HAST */
  default?: HastField;
  /** Detailed type with expanded type references as HAST */
  detailedType?: HastField;
}
/**
 * Highlighted component type metadata with highlighted types.
 */
export interface HighlightedComponentTypeMeta extends Omit<ComponentTypeMeta, 'props'> {
  props: Record<string, HighlightedProperty>;
}
/**
 * Highlighted hook type metadata with highlighted types.
 */
export interface HighlightedHookTypeMeta extends Omit<HookTypeMeta, 'parameters' | 'expandedProperties' | 'returnValue' | 'returnValueDescription'> {
  parameters?: HighlightedParameter[];
  returnValue: Record<string, HighlightedProperty> | HastField;
  /** Expanded return type with resolved type references (only when returnValue is HastRoot) */
  returnValueDetailedType?: HastField;
  /** Description of the return value as HAST */
  returnValueDescription?: HastField;
  /** Original type name when return value was expanded from a named type reference */
  returnValueTypeName?: string;
  /** Expanded properties from a single-parameter type (anonymous or named) */
  expandedProperties?: Record<string, HighlightedProperty>;
  /** Type name of the expanded properties, when they came from a named type reference */
  expandedTypeName?: string;
}
/**
 * Highlighted function type metadata with highlighted types.
 */
export interface HighlightedFunctionTypeMeta extends Omit<FunctionTypeMeta, 'parameters' | 'expandedProperties' | 'returnValue' | 'returnValueDescription'> {
  parameters?: HighlightedParameter[];
  returnValue: Record<string, HighlightedProperty> | HastField;
  /** Expanded return type with resolved type references (only when returnValue is HastRoot) */
  returnValueDetailedType?: HastField;
  /** Description of the return value as HAST */
  returnValueDescription?: HastField;
  /** Original type name when return value was expanded from a named type reference */
  returnValueTypeName?: string;
  /** Expanded properties from a single-parameter type (anonymous or named) */
  expandedProperties?: Record<string, HighlightedProperty>;
  /** Type name of the expanded properties, when they came from a named type reference */
  expandedTypeName?: string;
}
/**
 * Highlighted method with syntax-highlighted HAST fields.
 */
export interface HighlightedMethod extends Omit<FormattedMethod, 'parameters' | 'returnValue' | 'returnValueDescription' | 'description'> {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  parameters: HighlightedParameter[];
  returnValue: HastField;
  returnValueDescription?: HastField;
}
/**
 * Highlighted class type metadata with highlighted types.
 */
export interface HighlightedClassTypeMeta extends Omit<ClassTypeMeta, 'constructorParameters' | 'properties' | 'methods' | 'description'> {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  constructorParameters: HighlightedParameter[];
  properties: Record<string, HighlightedClassProperty>;
  methods: Record<string, HighlightedMethod>;
}
/**
 * Highlighted enum member with syntax-highlighted HAST fields.
 */
export interface HighlightedEnumMemberMeta extends Omit<EnumMemberMeta, 'description'> {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
}
/**
 * Highlighted raw type metadata with syntax-highlighted HAST fields.
 */
export interface HighlightedRawTypeMeta extends Omit<RawTypeMeta, 'description' | 'formattedCode' | 'enumMembers' | 'properties'> {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  /** The formatted type declaration as syntax-highlighted HAST */
  formattedCode: HastField;
  /** For enum types, the individual members with their values and descriptions */
  enumMembers?: HighlightedEnumMemberMeta[];
  /**
   * Highlighted properties extracted from the type.
   * JSDoc comments are extracted from the formattedCode via `extractTypeProps`
   * and added here with syntax-highlighted HAST fields.
   * Property paths use dot-notation for nested objects (e.g., `appearance.theme`).
   */
  properties?: Record<string, HighlightedProperty>;
}
/**
 * Highlighted TypesMeta with highlighted type fields.
 */
export type HighlightedTypesMeta = {
  type: 'component';
  name: string;
  /** The anchor slug for linking to this type (e.g., "trigger" or "trigger.state") */
  slug?: string;
  /** Alternative names this type can be looked up by (e.g., flat export name like "AccordionRootProps") */
  aliases?: string[];
  data: HighlightedComponentTypeMeta;
} | {
  type: 'hook';
  name: string;
  /** The anchor slug for linking to this type (e.g., "usescrolllock") */
  slug?: string;
  /** Alternative names this type can be looked up by */
  aliases?: string[];
  data: HighlightedHookTypeMeta;
} | {
  type: 'function';
  name: string;
  /** The anchor slug for linking to this type (e.g., "createtheme") */
  slug?: string;
  /** Alternative names this type can be looked up by */
  aliases?: string[];
  data: HighlightedFunctionTypeMeta;
} | {
  type: 'class';
  name: string;
  /** The anchor slug for linking to this type (e.g., "handle") */
  slug?: string;
  /** Alternative names this type can be looked up by */
  aliases?: string[];
  data: HighlightedClassTypeMeta;
} | {
  type: 'raw';
  name: string;
  /** The anchor slug for linking to this type (e.g., "trigger.props") */
  slug?: string;
  /** Alternative names this type can be looked up by (e.g., flat export name like "AccordionRootState") */
  aliases?: string[];
  data: HighlightedRawTypeMeta;
};
/**
 * Options for highlightTypesMeta.
 */
export interface HighlightTypesMetaOptions {
  /** Map of export names to their highlighted HAST definitions for type expansion */
  highlightedExports?: Record<string, HastRoot>;
  /** Map of type names to their structured properties from raw types */
  rawTypeProperties?: Record<string, Record<string, FormattedProperty>>;
  /** Options for inline type formatting */
  formatting?: FormatInlineTypeOptions;
  /** Options for code blocks highlighted inside raw type descriptions and examples */
  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
  /**
   * When true, replaces every HastRoot field in the output with
   * `{ hastJson: string }` (typed as HastRoot to keep the interface stable).
   * This defers tree allocation to render time and provides a free deep clone
   * via `JSON.parse`, eliminating the need for `structuredClone`.
   */
  output?: TypesOutputFormat;
}
/**
 * Highlights TypesMeta by converting plain text type strings to syntax-highlighted HAST.
 *
 * This function processes all TypesMeta objects and:
 * - Converts typeText → type (HAST)
 * - Derives shortType from the highlighted HAST structure
 * - Generates detailedType with expanded references
 * - Converts defaultText → default (HAST)
 *
 * @param types - Types array with plain text type fields
 * @param options - Options including highlightedExports map for type expansion
 * @returns Highlighted types array with HAST type fields
 */
export declare function highlightTypesMeta(types: TypesMeta[], options?: HighlightTypesMetaOptions): Promise<HighlightedTypesMeta[]>;
export {};