@mui/internal-docs-infra/pipeline/loadServerTypesMeta/format.d.mts

MUI Infra - internal documentation creation tools.

import type * as tae from 'typescript-api-extractor';
import type { Root as HastRoot } from 'hast';
import type { ExternalTypesCollector } from "./externalTypes.mjs";
/**
 * A pattern/replacement pair for transforming description text.
 * The pattern is compiled into a RegExp internally.
 */
export type DescriptionReplacement = {
  /** Regex pattern string to match in descriptions */
  pattern: string;
  /** Replacement string (supports regex replacement syntax like $1) */
  replacement: string;
  /** Regex flags (e.g. 'g', 'm', 'gm'). Defaults to no flags. */
  flags?: string;
};
/**
 * Applies a list of description replacements to a text string.
 * Each replacement's pattern is compiled into a RegExp and cached per object reference.
 */
export declare function applyDescriptionReplacements(text: string | undefined, replacements?: DescriptionReplacement[]): string | undefined;
/**
 * Formatted property metadata with plain text types and parsed markdown descriptions.
 *
 * Type highlighting (type → HAST, shortType, detailedType) is deferred to
 * the loadServerTypes stage via highlightTypesMeta() after highlightTypes().
 */
export interface FormattedProperty {
  /** Plain text type string */
  typeText: string;
  /** Plain text default value */
  defaultText?: string;
  /** Whether the property is required */
  required?: true;
  /** Description as parsed markdown HAST */
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Example usage as parsed markdown HAST */
  example?: HastRoot;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /** @see references as parsed markdown HAST */
  see?: HastRoot;
  /** Plain text version of @see references for markdown generation */
  seeText?: string;
}
/**
 * Formatted enum member metadata.
 */
export interface FormattedEnumMember {
  /** Description of the enum member as parsed markdown HAST */
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Type annotation from JSDoc @type tag */
  type?: string;
}
/**
 * Formatted parameter metadata for functions and hooks.
 *
 * Type highlighting is deferred to the loadServerTypes stage via
 * highlightTypesMeta() after highlightTypes().
 */
export interface FormattedParameter {
  /** Parameter name */
  name: string;
  /** Plain text type string */
  typeText: string;
  /** Plain text default value */
  defaultText?: string;
  /** Whether the parameter is optional */
  optional?: true;
  /** Description from JSDoc as parsed markdown HAST */
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Example usage as parsed markdown HAST */
  example?: HastRoot;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /** @see references as parsed markdown HAST */
  see?: HastRoot;
  /** Plain text version of @see references for markdown generation */
  seeText?: string;
}
/**
 * Transform an array of raw `@see` tag values into a markdown bullet list.
 * Returns `undefined` when the input is empty.
 */
export declare function formatSeeTags(values: (string | undefined)[]): string | undefined;
/**
 * Formats an array of type arguments into a type parameter declaration string.
 *
 * Only includes entries that are `TypeParameterNode`s (i.e., actual type parameters
 * like `T`, not concrete type arguments like `string`). Each parameter is formatted
 * with its constraint and default value when present.
 *
 * @returns A string like `<T, K extends string>` or `''` if there are no type parameters.
 */
export declare function formatTypeParameterDeclaration(typeArguments: readonly tae.TypeArgument[], typeNameMap?: Record<string, string>): string;
/**
 * Extracts type parameter declarations from an AnyType node.
 *
 * Reads `typeName.typeArguments` from types that carry a `typeName` property
 * (ObjectNode, UnionNode, IntersectionNode) and formats them as a declaration string.
 *
 * @returns A string like `<T, K extends string>` or `''` if the type has no type parameters.
 */
export declare function extractTypeParameters(type: tae.AnyType, typeNameMap?: Record<string, string>): string;
/**
 * Converts markdown text to HAST (HTML Abstract Syntax Tree) with syntax-highlighted code blocks.
 *
 * This enables rendering rich formatted descriptions including code examples, lists, and links
 * while preserving all markdown features and applying syntax highlighting to code blocks.
 */
export declare function parseMarkdownToHast(markdown: string): Promise<HastRoot>;
/**
 * Options for formatting inline types as HAST.
 */
export type FormatInlineTypeOptions = {
  /**
   * Maximum line width before union types in shortType fields are split across multiple lines.
   * When a union type exceeds this width, it will be formatted with each
   * member on a separate line with leading pipe characters.
   * @default 40
   */
  shortTypeUnionPrintWidth?: number;
  /**
   * Maximum line width before union types in defaultValue fields are split across multiple lines.
   * When a union type exceeds this width, it will be formatted with each
   * member on a separate line with leading pipe characters.
   * @default 40
   */
  defaultValueUnionPrintWidth?: number;
  /**
   * Maximum line width for Prettier formatting of type definitions.
   * @default 60
   */
  typePrintWidth?: number;
};
/**
 * Formats a TypeScript type string with Prettier, optionally preserving the type declaration.
 *
 * This function wraps the type in a `type Name = ...` declaration, formats it with Prettier,
 * and then removes or preserves the prefix based on the provided typeName and formatting.
 *
 * @param type - The type string to format
 * @param typeName - Optional type name to use in the declaration. If provided and the type
 *                   is multi-line, the `type Name = ...` prefix will be preserved.
 * @param printWidth - Optional maximum line width for Prettier formatting (default: 100)
 * @returns The formatted type string
 */
/**
 * Formats a markdown string with Prettier's markdown parser.
 * Used for non-code sections of generated markdown to ensure consistent formatting.
 *
 * @param markdown - The markdown string to format
 * @param printWidth - Optional maximum line width for Prettier formatting (default: 100)
 * @returns The formatted markdown string
 */
export declare function prettyFormatMarkdown(markdown: string, printWidth?: number): Promise<string>;
export declare function prettyFormat(type: string, typeName?: string | null, printWidth?: number): Promise<string>;
/**
 * Options for formatting properties.
 */
export interface FormatPropertiesOptions {
  exportNames: string[];
  typeNameMap: Record<string, string>;
  isComponentContext?: boolean;
  /** Options for inline type formatting (e.g., unionPrintWidth) */
  formatting?: FormatInlineTypeOptions;
  /** Collector for external types discovered during formatting */
  externalTypes?: ExternalTypesCollector;
  /** Pattern/replacement pairs to apply to descriptions */
  descriptionReplacements?: DescriptionReplacement[];
}
/**
 * Formats component or hook properties into a structured object with plain text types.
 *
 * Each property includes its type (as plain text), description (parsed markdown),
 * and default value. Type highlighting (type → HAST, shortType, detailedType) is
 * deferred to the loadServerTypes stage via highlightTypesMeta() after highlightTypes().
 *
 * This function handles the conversion of TypeScript type information into a format
 * suitable for documentation display.
 */
export declare function formatProperties(props: tae.PropertyNode[], options?: FormatPropertiesOptions): Promise<Record<string, FormattedProperty>>;
/**
 * Options for formatting parameters.
 */
export interface FormatParametersOptions {
  exportNames: string[];
  typeNameMap: Record<string, string>;
  /** Options for inline type formatting (e.g., unionPrintWidth) */
  formatting?: FormatInlineTypeOptions;
  /** Collector for external types discovered during formatting */
  externalTypes?: ExternalTypesCollector;
  /** Pattern/replacement pairs to apply to descriptions */
  descriptionReplacements?: DescriptionReplacement[];
}
/**
 * Formats function or hook parameters into a structured object.
 *
 * Each parameter includes its type (as plain text string), description (parsed markdown as HAST),
 * default value, and whether it's optional. Type highlighting is deferred to the
 * loadServerTypes stage via highlightTypesMeta() after highlightTypes().
 */
export declare function formatParameters(params: tae.Parameter[], options?: FormatParametersOptions): Promise<FormattedParameter[]>;
/**
 * Options for formatting detailed types.
 */
export interface FormatDetailedTypeOptions {
  allExports: tae.ExportNode[];
  exportNames: string[];
  typeNameMap: Record<string, string>;
  /** @internal Used for cycle detection in recursive calls */
  visited?: Set<string>;
}
/**
 * Recursively expands type aliases and external type references to their full definitions.
 *
 * This function resolves external types by looking them up in the provided exports,
 * and recursively expands union and intersection types. It includes cycle detection
 * to prevent infinite recursion on self-referential types.
 */
export declare function formatDetailedType(type: tae.AnyType, options: FormatDetailedTypeOptions): string;
/**
 * Formats an enum type into a structured object mapping enum values to their metadata.
 *
 * The result includes each enum member's description (parsed markdown as HAST) and type
 * information from JSDoc tags. Members are sorted by their value for consistent output.
 */
export declare function formatEnum(enumNode: tae.EnumNode, descriptionReplacements?: DescriptionReplacement[]): Promise<Record<string, FormattedEnumMember>>;