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

MUI Infra - internal documentation creation tools.

/**
 * Type highlighting utilities for converting plain text types to syntax-highlighted HAST.
 *
 * These functions are used in the loadServerTypes pipeline after highlightTypes()
 * to convert plain text type strings into syntax-highlighted HAST with proper
 * formatting for display in documentation.
 */
import type { Root as HastRoot } from 'hast';
/**
 * 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;
  /**
   * Maximum line width for Prettier formatting of top-level types that
   * aren't individual properties, such as whole return types and raw type definitions.
   * Note: Prettier is already run once during `syncTypes` using the project's configured width.
   * This option re-runs Prettier at a different width and should only be used when
   * the display width in the browser differs from the project's configuration.
   * When not specified, the additional Prettier pass is skipped.
   */
  topLevelTypePrintWidth?: number;
};
/** Default width for splitting union types across multiple lines */
export declare const DEFAULT_UNION_PRINT_WIDTH = 40;
/** Default width for Prettier formatting of type definitions */
export declare const DEFAULT_TYPE_PRINT_WIDTH = 60;
/**
 * Splits union types across multiple lines.
 *
 * This function processes HAST nodes containing syntax-highlighted union types and
 * reformats them with each union member on a separate line, prefixed with a pipe character.
 * Only top-level pipes are split (not those inside parentheses or braces).
 *
 * Matches the behavior of TableCode.tsx in base-ui docs:
 * - Groups content by top-level pipe separators
 * - Adds a leading `| ` before the first group
 * - Adds `<br>` + `| ` before subsequent groups
 * - Removes original pipe nodes (they're replaced by the new styled pipes)
 *
 * @param hast - The HAST root containing syntax-highlighted type nodes
 * @returns A new HAST root with multiline formatting applied
 */
export declare function formatMultilineUnionHast(hast: HastRoot): HastRoot;
/**
 * Formats an inline type string with syntax highlighting.
 *
 * This function transforms type strings (like `string`, `number | null`, etc.) into
 * syntax-highlighted HAST nodes. It ensures proper TypeScript context by prefixing
 * the type with `type _ =` before highlighting, then removes the prefix from the result.
 *
 * @param typeText - The type string to format (e.g., "string | number")
 * @param unionPrintWidth - Optional width threshold for multiline union formatting.
 *                          When set, unions exceeding this width are split across lines.
 * @returns A promise that resolves to a HAST root containing highlighted nodes
 *
 * @example
 * ```ts
 * await formatInlineTypeAsHast('string | number')
 * // Returns HAST nodes with syntax highlighting for "string | number"
 *
 * await formatInlineTypeAsHast('"a" | "b" | "c" | "d" | "e"', 20)
 * // Returns HAST nodes with multiline formatting for long unions
 * ```
 */
export declare function formatInlineTypeAsHast(typeText: string, unionPrintWidth?: number): Promise<HastRoot>;
/**
 * Wraps a HAST produced by formatInlineTypeAsHast in a <pre> element.
 * Converts root > code > [spans] into root > pre > code > [line-wrapped spans].
 *
 * This also:
 * - Removes the `data-inline` attribute that was added during inline highlighting
 *   (since the code is no longer inline once wrapped in <pre>)
 * - Wraps each line of content in <span class="line"> elements so that
 *   CSS rules like `.Code .line { white-space: pre }` apply correctly
 */
export declare function wrapInlineTypeInPre(hast: HastRoot): HastRoot;
/**
 * Formats TypeScript type text as HAST with full syntax highlighting in a code block.
 * This is used for detailed/expanded type displays (equivalent to triple backticks in MDX).
 * Unlike formatInlineTypeAsHast which uses <code>, this creates a <pre><code> structure
 * and also includes line numbers via starryNightGutter.
 */
export declare function formatDetailedTypeAsHast(typeText: string): Promise<HastRoot>;
/**
 * Determines whether a property should display its full type definition or a simplified version.
 *
 * Properties with complex types (unions, callbacks, etc.) benefit from expandable detailed views,
 * while simple types (string, number, boolean) can be shown inline without expansion.
 *
 * @param name - The property name (used for special cases like className, render, event handlers)
 * @param type - The plain text type string to analyze
 * @returns true if the property should have an expandable detailed type view
 */
export declare function shouldShowDetailedType(name: string, type: string | undefined): boolean;
/**
 * Gets the short representation of a type for display in tables.
 *
 * Returns a simplified type string for complex types (e.g., "Union", "function").
 * Simple types like `string`, `number`, `boolean` return undefined (no shortening needed).
 *
 * @param name - The property name (used for special cases like className, style, render, event handlers)
 * @param typeText - The plain text type string to analyze
 * @returns A short type string, or undefined if no shortening is needed
 */
export declare function getShortTypeString(name: string, typeText: string): string | undefined;