Load Server Types Meta

type ClassTypeMeta = {
  name: string;
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Constructor parameters */
  constructorParameters: FormattedParameter[];
  /** Public instance properties */
  properties: Record<string, FormattedProperty>;
  /** Public instance methods */
  methods: Record<string, FormattedMethod>;
  /** Type parameters (generics) if any */
  typeParameters?: string[];
}

type ComponentTypeMeta = {
  name: string;
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  props: Record<string, FormattedProperty>;
  dataAttributes: Record<string, FormattedEnumMember>;
  cssVariables: Record<string, FormattedEnumMember>;
}

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;
}

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;
}

type FormattedEnumMember = {
  /** Description of the enum member as parsed markdown HAST */
  description?: Root;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /**
   * Type annotation from JSDoc
   * @type tag
   */
  type?: string;
}

type 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?: Root;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Example usage as parsed markdown HAST */
  example?: Root;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /** @see as parsed markdown HAST */
  see?: Root;
  /**
   * Plain text version of
   * @see for markdown generation
   */
  seeText?: string;
}

type 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?: Root;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Example usage as parsed markdown HAST */
  example?: Root;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /** @see as parsed markdown HAST */
  see?: Root;
  /**
   * Plain text version of
   * @see for markdown generation
   */
  seeText?: string;
}

type FunctionTypeMeta = {
  name: string;
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Ordered function parameters */
  parameters?: FormattedParameter[];
  /**
   * Expanded properties from a single anonymous object parameter.
   * When populated, `parameters` should be omitted and headings should
   * say "Properties" instead of "Parameters".
   */
  expandedProperties?: Record<string, FormattedProperty>;
  /** Return value - either plain text string or object with properties (like hook return values) */
  returnValue: Record<string, FormattedProperty> | string;
  /** Plain text version of returnValue for markdown generation (when returnValue is string) */
  returnValueText?: string;
  /** Description of the return value (parsed markdown as HAST) */
  returnValueDescription?: HastRoot;
  /** Plain text version of returnValueDescription for markdown generation */
  returnValueDescriptionText?: string;
}

type HookTypeMeta = {
  name: string;
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Ordered function parameters */
  parameters?: FormattedParameter[];
  /**
   * Expanded properties from a single anonymous object parameter.
   * When populated, `parameters` should be omitted and headings should
   * say "Properties" instead of "Parameters".
   */
  expandedProperties?: Record<string, FormattedProperty>;
  returnValue: Record<string, FormattedProperty> | string;
  /** Plain text version of returnValue for markdown generation (when returnValue is string) */
  returnValueText?: string;
  /** Description of the return value (parsed markdown as HAST) */
  returnValueDescription?: HastRoot;
  /** Plain text version of returnValueDescription for markdown generation */
  returnValueDescriptionText?: string;
}

type LoadServerTypesMetaOptions = {
  /** Absolute path to the types.md file (used for deriving paths) */
  typesMarkdownPath: string;
  /** Root context directory (workspace root) */
  rootContext: string;
  /**
   * Map of variant name to file path (relative or package path).
   * Each variant is an entrypoint whose types are extracted independently then merged.
   * For single component: `{ Default: '@base-ui/react/checkbox' }`
   * For multiple: `{ Checkbox: '@base-ui/react/checkbox', Button: '@base-ui/react/button' }`
   */
  variants?: Record<string, string>;
  /**
   * When true, resolves library paths to their source files for watching.
   * Useful during development to watch the original source rather than built files.
   */
  watchSourceDirectly?: boolean;
  /** Options for formatting types in tables */
  formattingOptions?: FormatInlineTypeOptions;
  /**
   * Directory path for socket and lock files used for IPC between workers.
   * Useful for Windows where the default temp directory may not support Unix domain sockets.
   */
  socketDir?: string;
  /**
   * Optional regex pattern string to filter which external types to include.
   * External types are named union types (like `Orientation = 'horizontal' | 'vertical'`)
   * that are referenced in props but not exported from the component's module.
   *
   * When not provided, ALL qualifying named union types (unions of literals) will be
   * collected automatically. This is the recommended behavior for most projects.
   *
   * When provided, only external types whose names match this pattern will be collected.
   * @example undefined // Collect all qualifying external types (recommended)
   * @example '^(Orientation|Alignment|Side)$' // Only include specific types
   */
  externalTypesPattern?: string;
  /** Custom ordering configuration for sorting props, data attributes, exports, etc. */
  ordering?: OrderingConfig;
  /**
   * Pattern/replacement pairs to apply to JSDoc descriptions.
   * Each entry has a `pattern` (regex string) and `replacement` string.
   */
  descriptionReplacements?: DescriptionReplacement[];
}

type LoadServerTypesMetaResult = {
  /** All dependencies that should be watched for changes */
  allDependencies: string[];
  /** Type name map from variant processing */
  typeNameMap?: Record<string, string>;
  /**
   * External types discovered during formatting.
   * These are types referenced in props/params that are not publicly exported,
   * but whose definitions are useful for documentation (e.g., union types).
   * Map from type name to its definition string.
   */
  externalTypes: Record<string, string>;
  /** Resource name derived from the types path */
  resourceName: string;
  /** Export data where each export has a main type and related additional types */
  exports: Record<string, { type: TypesMeta; additionalTypes: TypesMeta[] }>;
  /** Top-level non-namespaced types not claimed by any variant-only group */
  additionalTypes: TypesMeta[];
  /**
   * Types belonging to variant-only groups (variants with no main export).
   * Keyed by variant name, each entry contains the types from that variant.
   * These are separated from `additionalTypes` to avoid duplication.
   */
  variantOnlyAdditionalTypes: Record<string, TypesMeta[]>;
  /**
   * Maps variant names to the type names that originated from that variant.
   * Used for namespace imports (e.g., `* as Types`) to filter additionalTypes
   * to only show types from that specific module.
   */
  variantTypeNames: Record<string, string[]>;
  /**
   * Maps variant names to their per-variant typeNameMaps.
   * Used for Canonical Types annotations showing which variants contain each type.
   */
  variantTypeNameMaps: Record<string, Record<string, string>>;
}

type RawTypeMeta = {
  /** Display name for this type (may include dots like "Component.Root.State") */
  name: string;
  /** Description parsed from JSDoc as HAST */
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /**
   * The formatted type declaration as plain text (e.g., "type ButtonProps = { ... }").
   * Will be highlighted to HAST in loadServerTypes.
   */
  formattedCode: string;
  /**
   * For enum types, the individual members with their values and descriptions.
   * When present, indicates this type should be rendered as an enum table.
   */
  enumMembers?: EnumMemberMeta[];
  /**
   * For re-exports, information about the component this type re-exports from.
   * When set, indicates this should be rendered as a link to the component.
   */
  reExportOf?: ReExportInfo;
  /** For DataAttributes types, the component name this type belongs to. */
  dataAttributesOf?: string;
  /** For CssVars types, the component name this type belongs to. */
  cssVarsOf?: string;
  /**
   * For object types, the individual properties with their types and descriptions.
   * Used by the enhancement stage to convert named return type references into property tables.
   */
  properties?: Record<string, FormattedProperty>;
}

type ReExportInfo = {
  /** Display name of the component (e.g., "Trigger" from "Accordion.Trigger") */
  name: string;
  /** Anchor slug for linking (e.g., "#trigger") */
  slug: string;
  /** What kind of type this re-exports */
  suffix: 'props' | 'css-variables' | 'data-attributes';
}

type TypesMeta = (
  | { type: 'class'; data: ClassTypeMeta }
  | { type: 'component'; data: ComponentTypeMeta }
  | { type: 'hook'; data: HookTypeMeta }
  | { type: 'function'; data: FunctionTypeMeta }
  | { type: 'raw'; data: RawTypeMeta }
) & {
  name: string;
  slug?: string;
  /** Alternative names this type can be looked up by (e.g., flat export name like "AccordionRootState") */
  aliases?: string[];
}