/**
 * API 文档数据类型。
 *
 * 这些结构由 Node 侧的 `plugins/docgen.ts` 产出，通过虚拟模块交给浏览器渲染，
 * 因此刻意保持为不含第三方类型的纯数据，避免 `vue-docgen-api` 被打进客户端产物。
 */

/** 单个 prop 的表格行数据。 */
export interface ApiPropRow {
	/** prop 名称。 */
	name: string;
	/** 类型签名，如 `string`、`Article`。 */
	type: string;
	/** 默认值，未声明时为空字符串。 */
	defaultValue: string;
	/** 是否必填。 */
	required: boolean;
	/** 注释说明，取自源码 JSDoc。 */
	description: string;
}

/** 单个事件的表格行数据。 */
export interface ApiEventRow {
	/** 事件名，如 `update:modelValue`。 */
	name: string;
	/** 回调参数签名。 */
	type: string;
	/** 注释说明。 */
	description: string;
}

/** 单个插槽的表格行数据。 */
export interface ApiSlotRow {
	/** 插槽名。 */
	name: string;
	/** 注释说明或作用域参数。 */
	description: string;
}

/** 单个暴露方法或属性的表格行数据。 */
export interface ApiExposeRow {
	/** 暴露的名称。 */
	name: string;
	/** 类型签名。 */
	type: string;
	/** 注释说明。 */
	description: string;
}

/** 一个组件解析完成后的完整 API 数据。 */
export interface ComponentApi {
	/** 组件名。 */
	name: string;
	/** 组件自身的注释说明。 */
	description: string;
	/**
	 * 源码是否解析成功。
	 *
	 * 用来区分「解析失败」与「组件本身就没有 props/events/slots/expose」，
	 * 两者都会得到空数组，但提示语完全不同。
	 */
	parsed: boolean;
	props: ApiPropRow[];
	events: ApiEventRow[];
	slots: ApiSlotRow[];
	exposes: ApiExposeRow[];
}

/** 全部组件的 API 数据，键为组件名。 */
export type ComponentApiMap = Record<string, ComponentApi>;

/** 生成一个空的 API 数据，用于解析失败时兜底，保证文档站不因单个组件而白屏。 */
export function createEmptyApi(name: string): ComponentApi {
	return {
		name,
		description: "",
		parsed: false,
		props: [],
		events: [],
		slots: [],
		exposes: []
	};
}