types.ts

/**
 * Options that define the information necessary to find the api.json file
 * and create individual page json files out of it
 */
export interface IPageJsonOptions {
  /** Input files generated by api-extractor (one per package) */
  apiJsonPaths: string[];
  /** Output \*.page.json folder path. Page groups (if used) will go in subfolders. */
  outputRoot: string;
  /** If true, the generated files won't be pretty-formatted */
  min?: boolean;
  /**
   * List of allowed page names (`@docCategory` tag values) grouped by any desired criteria,
   * such as package name.
   */
  pageGroups?: PageGroups;
  /**
   * Group for any page names (`@docCategory` tag values) not listed in `pageGroups`.
   * If unspecified, unlisted pages will go under the root.
   */
  fallbackGroup?: string;
}

/** Map from group name to page names */
export type PageGroups = { [groupName: string]: string[] };

/**
 * Structure of the page.json files
 */
export interface IPageJson {
  tables: ITableJson[];
  name: string;
  group?: string;
}

export type ApiKind = 'interface' | 'enum' | 'class' | 'typeAlias';

/**
 * Info for a table representing a top-level API item: interface, enum, class, or type alias.
 */
export interface ITableJson {
  kind: ApiKind;
  name: string;
  description?: string;
  /**
   * Any types the item extends, translated to an array of text elements and links to other types.
   * For classes and interfaces only.
   *
   * Example: `Readonly<IFoo>` might translate to:
   * `[{ text: 'Readonly<' }, { text: 'IFoo', linkedPage: 'Foo', linkedPageGroup: 'components' }, { text: '>' }]`
   */
  extendsTokens?: ILinkToken[];
  members?: ITableRowJson[] | IEnumTableRowJson[];
  deprecated?: boolean;
  deprecatedMessage?: string;
}

/**
 * Generic row for API reference tables.
 * It can represent a member (property or method) of an interface or class.
 */
export interface ITableRowJson {
  name: string;
  kind?: 'method' | 'property';
  /**
   * The row's type translated to an array of text elements and links to other types.
   * For example, `Readonly<IFoo>` might translate to:
   * `[{ text: 'Readonly<' }, { text: 'IFoo', linkedPage: 'Foo', linkedPageGroup: 'components' }, { text: '>' }]`
   */
  typeTokens: ILinkToken[];
  defaultValue?: string;
  description?: string;
  deprecated?: boolean;
  deprecatedMessage?: string;
  required?: boolean;
}

/**
 * Enum member row for API reference tables.
 */
export type IEnumTableRowJson = Omit<ITableRowJson, 'kind' | 'typeTokens' | 'defaultValue' | 'required'> & {
  value: string;
};

/**
 * Text excerpt token that is part of a type definition or extends block and may have a link
 * to another doc page.
 */
export interface ILinkToken {
  text: string;
  /** If this token is a link, name of the doc page it points to */
  linkedPage?: string;
  /** If this token is a link, group/category of the doc page it points to */
  linkedPageGroup?: string;
}