Load Server Types

type HighlightedClassProperty = {
  /** Whether this is a static property */
  isStatic?: boolean;
  /** Whether this property is readonly */
  readonly?: boolean;
  /** 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;
  /** Plain text version of shortType for accessibility */
  shortTypeText?: string;
  /** Default value with syntax highlighting as HAST */
  default?: HastField;
  /** Detailed expanded type view (only when different from basic type) */
  detailedType?: HastField;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Plain text type string */
  typeText: string;
  /** Plain text default value */
  defaultText?: string;
  /** Whether the property is required */
  required?: true;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /**
   * Plain text version of
   * @see for markdown generation
   */
  seeText?: string;
}

type HighlightedClassTypeMeta = {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  constructorParameters: HighlightedParameter[];
  properties: Record<string, HighlightedClassProperty>;
  methods: Record<string, HighlightedMethod>;
  name: string;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Type parameters (generics) if any */
  typeParameters?: string[];
}

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

type HighlightedEnumMemberMeta = {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  name: string;
  descriptionText?: string;
  value?: string | number;
}

type HighlightedFunctionTypeMeta = {
  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;
  name: string;
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Plain text version of returnValue for markdown generation (when returnValue is string) */
  returnValueText?: string;
  /** Plain text version of returnValueDescription for markdown generation */
  returnValueDescriptionText?: string;
}

type HighlightedHookTypeMeta = {
  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;
  name: string;
  description?: HastRoot;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Plain text version of returnValue for markdown generation (when returnValue is string) */
  returnValueText?: string;
  /** Plain text version of returnValueDescription for markdown generation */
  returnValueDescriptionText?: string;
}

type HighlightedMethod = {
  /** Description with syntax highlighting as HAST */
  description?: HastField;
  parameters: HighlightedParameter[];
  returnValue: HastField;
  returnValueDescription?: HastField;
  name: string;
  descriptionText?: string;
  returnValueDescriptionText?: string;
  isStatic: boolean;
}

type HighlightedParameter = {
  /** 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;
  /** Plain text version of shortType for accessibility */
  shortTypeText?: string;
  /** Default value with syntax highlighting as HAST */
  default?: HastField;
  /** Detailed type with expanded type references as HAST */
  detailedType?: HastField;
  /** Parameter name */
  name: string;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Plain text type string */
  typeText: string;
  /** Plain text default value */
  defaultText?: string;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /**
   * Plain text version of
   * @see for markdown generation
   */
  seeText?: string;
  /** Whether the parameter is optional */
  optional?: true;
}

type HighlightedProperty = {
  /** 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;
  /** Plain text version of shortType for accessibility */
  shortTypeText?: string;
  /** Default value with syntax highlighting as HAST */
  default?: HastField;
  /** Detailed expanded type view (only when different from basic type) */
  detailedType?: HastField;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /** Plain text type string */
  typeText: string;
  /** Plain text default value */
  defaultText?: string;
  /** Whether the property is required */
  required?: true;
  /** Plain text version of example for markdown generation */
  exampleText?: string;
  /**
   * Plain text version of
   * @see for markdown generation
   */
  seeText?: string;
}

type HighlightedRawTypeMeta = {
  /** 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>;
  /** Display name for this type (may include dots like "Component.Root.State") */
  name: string;
  /** Plain text version of description for markdown generation */
  descriptionText?: string;
  /**
   * 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;
}

type HighlightedTypesMeta = (
  | { type: 'component'; data: HighlightedComponentTypeMeta }
  | { type: 'hook'; data: HighlightedHookTypeMeta }
  | { type: 'function'; data: HighlightedFunctionTypeMeta }
  | { type: 'class'; data: HighlightedClassTypeMeta }
  | { type: 'raw'; data: HighlightedRawTypeMeta }
) & {
  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[];
}

type LoadServerTypesOptions = {
  /**
   * When true, calls syncTypes to extract types from TypeScript source,
   * generate markdown, and write to disk before highlighting.
   *
   * When false, loads types from an existing types.md file using
   * loadServerTypesText, skipping type extraction and markdown generation.
   * @default false
   */
  sync?: boolean;
  /**
   * When true, replaces HAST Root nodes in the result with `{ hastJson: string }`
   * wrappers. This defers tree allocation from module-evaluation time to render
   * time: V8 only creates a string instead of the full object graph, and
   * `JSON.parse` at render time provides both deserialization and a free deep
   * clone (eliminating the need for `structuredClone`).
   * @default false
   */
  serializeHast?: boolean;
  /** Absolute path to the types.md file to generate */
  typesMarkdownPath: string;
  /** Root context directory (workspace root) */
  rootContext: string;
  /**
   * Map of variant name to file path (relative or package path).
   * For single component: `{ Default: './Component' }`
   * For multiple: `{ CssModules: './css-modules/Component', Tailwind: './tailwind/Component' }`
   */
  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;
  /** Enable performance logging */
  performanceLogging?: boolean;
  /**
   * Options for updating the parent index page with component metadata.
   * When provided, will call syncPageIndex to update the parent directory's page.mdx
   * with props, dataAttributes, and cssVariables extracted from the component types.
   *
   * These options are passed through to syncPageIndex.
   */
  updateParentIndex?: {
    baseDir?: string;
    onlyUpdateIndexes?: boolean;
    markerDir?: string;
    errorIfOutOfDate?: boolean;
    indexFileName?: 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 LoadServerTypesResult = {
  /** Export data where each export has a main type and related additional types */
  exports: Record<string, ExportData>;
  /** Top-level non-namespaced types not claimed by any variant-only group */
  additionalTypes: HighlightedTypesMeta[];
  /**
   * Types belonging to variant-only groups (variants with no main export).
   * Keyed by variant name, containing the types from that variant.
   */
  variantOnlyAdditionalTypes: Record<string, HighlightedTypesMeta[]>;
  /**
   * 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[]>;
  /** All dependencies that should be watched for changes */
  allDependencies: string[];
  /** Type name map from variant processing */
  typeNameMap?: Record<string, string>;
  /**
   * Platform-scoped anchor maps for linking type references in code.
   * Keys include both dotted names ("Accordion.Trigger") and flat names ("AccordionTrigger").
   */
  anchorMap: { js?: Record<string, string>; css?: Record<string, string> };
}

type SerializedHastRoot = { hastJson: string }