vitepress-plugin-field 0.2.0 → 0.4.0

package/dist/client/browser/index.d.ts

@@ -1,12 +1,31 @@
 import { EnhanceAppContext } from "vitepress";
 
 //#region src/client/VPField.vue.d.ts
+/**
+ * Vue component that renders a single field documentation entry.
+ *
+ * Renders the field name, optional badges (Required/Optional/Deprecated),
+ * type annotation, default value, and a description slot. Used by the
+ * `::: field` markdown container to display structured field information.
+ *
+ * Vue 组件，渲染单个字段文档条目。
+ *
+ * 渲染字段名称、可选徽章（Required/Optional/Deprecated）、类型注解、默认值
+ * 以及描述插槽。由 `::: field` markdown 容器用于展示结构化的字段信息。
+ *
+ * @example
+ * ```vue
+ * <VPField name="username" type="string" required>
+ *   The username used to log in.
+ * </VPField>
+ * ```
+ */
 type __VLS_Props = {
-  name: string;
-  type?: string;
-  required?: boolean;
-  optional?: boolean;
-  deprecated?: boolean;
+  /** Field name displayed as the title / 显示为标题的字段名称 */name: string; /** Type annotation rendered as inline code / 以行内代码渲染的类型注解 */
+  type?: string; /** Whether the field is required (shows "Required" badge) / 字段是否为必填（显示 "Required" 徽章） */
+  required?: boolean; /** Whether the field is optional (shows "Optional" badge) / 字段是否为可选（显示 "Optional" 徽章） */
+  optional?: boolean; /** Whether the field is deprecated (shows "Deprecated" badge) / 字段是否已弃用（显示 "Deprecated" 徽章） */
+  deprecated?: boolean; /** Default value rendered as inline code / 以行内代码渲染的默认值 */
   defaultValue?: string;
 };
 declare var __VLS_1: {};
@@ -23,6 +42,30 @@ type __VLS_WithSlots<T, S> = T & {
 };
 //#endregion
 //#region src/client/index.d.ts
+/**
+ * Client-side setup for `vitepress-plugin-field`.
+ *
+ * Registers the `<VPField>` component globally so it can be used in
+ * markdown-rendered content without explicit imports.
+ *
+ * `vitepress-plugin-field` 的客户端设置。
+ *
+ * 全局注册 `<VPField>` 组件，使其在 markdown 渲染的内容中无需显式导入即可使用。
+ *
+ * @param param0 - The VitePress enhance app context / VitePress 增强应用上下文
+ * @param param0.app - The Vue app instance to register the component on / 要注册组件的 Vue 应用实例
+ * @example
+ * ```ts
+ * // In `.vitepress/theme/index.ts`
+ * import { enhanceAppWithField } from 'vitepress-plugin-field/client'
+ *
+ * export default {
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithField(ctx)
+ *   },
+ * }
+ * ```
+ */
 declare function enhanceAppWithField({
   app
 }: EnhanceAppContext): void;

package/dist/client/browser/index.js

@@ -19,7 +19,26 @@ const _hoisted_6 = {
 	key: 1,
 	class: "description"
 };
-const _sfc_main = /* @__PURE__ */ defineComponent({
+/**
+* Vue component that renders a single field documentation entry.
+*
+* Renders the field name, optional badges (Required/Optional/Deprecated),
+* type annotation, default value, and a description slot. Used by the
+* `::: field` markdown container to display structured field information.
+*
+* Vue 组件，渲染单个字段文档条目。
+*
+* 渲染字段名称、可选徽章（Required/Optional/Deprecated）、类型注解、默认值
+* 以及描述插槽。由 `::: field` markdown 容器用于展示结构化的字段信息。
+*
+* @example
+* ```vue
+* <VPField name="username" type="string" required>
+*   The username used to log in.
+* </VPField>
+* ```
+*/
+const _sfc_main = /*@__PURE__*/ defineComponent({
 	__name: "VPField",
 	props: {
 		name: {},
@@ -30,6 +49,11 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 		defaultValue: {}
 	},
 	setup(__props) {
+		/**
+		* Resolves the badge label based on the required/optional flags.
+		*
+		* 根据 required/optional 标志解析徽章标签。
+		*/
 		const badge = computed(() => __props.required ? "Required" : __props.optional ? "Optional" : "");
 		return (_ctx, _cache) => {
 			return openBlock(), createElementBlock("div", { class: normalizeClass(["vp-field", {
@@ -57,6 +81,30 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 });
 //#endregion
 //#region src/client/index.ts
+/**
+* Client-side setup for `vitepress-plugin-field`.
+*
+* Registers the `<VPField>` component globally so it can be used in
+* markdown-rendered content without explicit imports.
+*
+* `vitepress-plugin-field` 的客户端设置。
+*
+* 全局注册 `<VPField>` 组件，使其在 markdown 渲染的内容中无需显式导入即可使用。
+*
+* @param param0 - The VitePress enhance app context / VitePress 增强应用上下文
+* @param param0.app - The Vue app instance to register the component on / 要注册组件的 Vue 应用实例
+* @example
+* ```ts
+* // In `.vitepress/theme/index.ts`
+* import { enhanceAppWithField } from 'vitepress-plugin-field/client'
+*
+* export default {
+*   enhanceApp(ctx) {
+*     enhanceAppWithField(ctx)
+*   },
+* }
+* ```
+*/
 function enhanceAppWithField({ app }) {
 	app.component("VPField", _sfc_main);
 }

package/dist/client/ssr/index.d.ts

@@ -1,12 +1,31 @@
 import { EnhanceAppContext } from "vitepress";
 
 //#region src/client/VPField.vue.d.ts
+/**
+ * Vue component that renders a single field documentation entry.
+ *
+ * Renders the field name, optional badges (Required/Optional/Deprecated),
+ * type annotation, default value, and a description slot. Used by the
+ * `::: field` markdown container to display structured field information.
+ *
+ * Vue 组件，渲染单个字段文档条目。
+ *
+ * 渲染字段名称、可选徽章（Required/Optional/Deprecated）、类型注解、默认值
+ * 以及描述插槽。由 `::: field` markdown 容器用于展示结构化的字段信息。
+ *
+ * @example
+ * ```vue
+ * <VPField name="username" type="string" required>
+ *   The username used to log in.
+ * </VPField>
+ * ```
+ */
 type __VLS_Props = {
-  name: string;
-  type?: string;
-  required?: boolean;
-  optional?: boolean;
-  deprecated?: boolean;
+  /** Field name displayed as the title / 显示为标题的字段名称 */name: string; /** Type annotation rendered as inline code / 以行内代码渲染的类型注解 */
+  type?: string; /** Whether the field is required (shows "Required" badge) / 字段是否为必填（显示 "Required" 徽章） */
+  required?: boolean; /** Whether the field is optional (shows "Optional" badge) / 字段是否为可选（显示 "Optional" 徽章） */
+  optional?: boolean; /** Whether the field is deprecated (shows "Deprecated" badge) / 字段是否已弃用（显示 "Deprecated" 徽章） */
+  deprecated?: boolean; /** Default value rendered as inline code / 以行内代码渲染的默认值 */
   defaultValue?: string;
 };
 declare var __VLS_1: {};
@@ -23,6 +42,30 @@ type __VLS_WithSlots<T, S> = T & {
 };
 //#endregion
 //#region src/client/index.d.ts
+/**
+ * Client-side setup for `vitepress-plugin-field`.
+ *
+ * Registers the `<VPField>` component globally so it can be used in
+ * markdown-rendered content without explicit imports.
+ *
+ * `vitepress-plugin-field` 的客户端设置。
+ *
+ * 全局注册 `<VPField>` 组件，使其在 markdown 渲染的内容中无需显式导入即可使用。
+ *
+ * @param param0 - The VitePress enhance app context / VitePress 增强应用上下文
+ * @param param0.app - The Vue app instance to register the component on / 要注册组件的 Vue 应用实例
+ * @example
+ * ```ts
+ * // In `.vitepress/theme/index.ts`
+ * import { enhanceAppWithField } from 'vitepress-plugin-field/client'
+ *
+ * export default {
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithField(ctx)
+ *   },
+ * }
+ * ```
+ */
 declare function enhanceAppWithField({
   app
 }: EnhanceAppContext): void;

package/dist/client/ssr/index.js

@@ -1,7 +1,26 @@
 import { computed, defineComponent, mergeProps, useSSRContext } from "vue";
 import { ssrInterpolate, ssrRenderAttrs, ssrRenderClass, ssrRenderSlot } from "vue/server-renderer";
 //#region src/client/VPField.vue
-const _sfc_main = /* @__PURE__ */ defineComponent({
+/**
+* Vue component that renders a single field documentation entry.
+*
+* Renders the field name, optional badges (Required/Optional/Deprecated),
+* type annotation, default value, and a description slot. Used by the
+* `::: field` markdown container to display structured field information.
+*
+* Vue 组件，渲染单个字段文档条目。
+*
+* 渲染字段名称、可选徽章（Required/Optional/Deprecated）、类型注解、默认值
+* 以及描述插槽。由 `::: field` markdown 容器用于展示结构化的字段信息。
+*
+* @example
+* ```vue
+* <VPField name="username" type="string" required>
+*   The username used to log in.
+* </VPField>
+* ```
+*/
+const _sfc_main = /*@__PURE__*/ defineComponent({
 	__name: "VPField",
 	__ssrInlineRender: true,
 	props: {
@@ -13,6 +32,11 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 		defaultValue: {}
 	},
 	setup(__props) {
+		/**
+		* Resolves the badge label based on the required/optional flags.
+		*
+		* 根据 required/optional 标志解析徽章标签。
+		*/
 		const badge = computed(() => __props.required ? "Required" : __props.optional ? "Optional" : "");
 		return (_ctx, _push, _parent, _attrs) => {
 			_push(`<div${ssrRenderAttrs(mergeProps({ class: ["vp-field", {
@@ -49,6 +73,30 @@ _sfc_main.setup = (props, ctx) => {
 };
 //#endregion
 //#region src/client/index.ts
+/**
+* Client-side setup for `vitepress-plugin-field`.
+*
+* Registers the `<VPField>` component globally so it can be used in
+* markdown-rendered content without explicit imports.
+*
+* `vitepress-plugin-field` 的客户端设置。
+*
+* 全局注册 `<VPField>` 组件，使其在 markdown 渲染的内容中无需显式导入即可使用。
+*
+* @param param0 - The VitePress enhance app context / VitePress 增强应用上下文
+* @param param0.app - The Vue app instance to register the component on / 要注册组件的 Vue 应用实例
+* @example
+* ```ts
+* // In `.vitepress/theme/index.ts`
+* import { enhanceAppWithField } from 'vitepress-plugin-field/client'
+*
+* export default {
+*   enhanceApp(ctx) {
+*     enhanceAppWithField(ctx)
+*   },
+* }
+* ```
+*/
 function enhanceAppWithField({ app }) {
 	app.component("VPField", _sfc_main);
 }

package/dist/node/index.d.ts

@@ -1,9 +1,57 @@
 import { PluginSimple } from "markdown-it";
 
-//#region src/node/fieldPlugin.d.ts
-declare const fieldMarkdownPlugin: PluginSimple;
+//#region src/node/plugin.d.ts
+/**
+ * VitePress plugin for rendering structured field documentation blocks.
+ *
+ * Registers a markdown-it container plugin that transforms `::: field` blocks
+ * into interactive `<VPField>` Vue components, and wires up the client-side
+ * component registration via `enhanceAppWithField`.
+ *
+ * VitePress 插件，用于渲染结构化的字段文档块。
+ *
+ * 注册 markdown-it 容器插件，将 `::: field` 块转换为交互式 `<VPField>` Vue 组件，
+ * 并通过 `enhanceAppWithField` 完成客户端组件注册。
+ *
+ * @example
+ * `.vitepress/config.ts`
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import field from 'vitepress-plugin-field'
+ *
+ * export default defineConfig({
+ *   plugins: [field()],
+ * })
+ * ```
+ */
+declare const field: (options?: unknown) => import("vitepress-tuck").VitepressPlugin;
 //#endregion
-//#region src/node/index.d.ts
-declare const _default: (option?: unknown) => import("vitepress-tuck").VitepressPlugin;
+//#region src/node/markdown.d.ts
+/**
+ * markdown-it plugin that registers `::: field` and `::: field-group` containers.
+ *
+ * Registers two container syntaxes:
+ * - `::: field-group` — wraps a group of fields in a `<div class="vp-field-group">`
+ * - `::: field` — parses the container body via `parseFieldContent` and renders
+ *   a `<VPField>` Vue component with the extracted props
+ *
+ * markdown-it 插件，注册 `::: field` 和 `::: field-group` 容器。
+ *
+ * 注册两种容器语法：
+ * - `::: field-group` — 将一组字段包裹在 `<div class="vp-field-group">` 中
+ * - `::: field` — 通过 `parseFieldContent` 解析容器正文，并渲染带有提取属性的
+ *   `<VPField>` Vue 组件
+ *
+ * @param md - The markdown-it instance to extend / 要扩展的 markdown-it 实例
+ * @example
+ * ```ts
+ * import MarkdownIt from 'markdown-it'
+ * import { fieldMarkdownPlugin } from 'vitepress-plugin-field/node'
+ *
+ * const md = new MarkdownIt()
+ * md.use(fieldMarkdownPlugin)
+ * ```
+ */
+declare const fieldMarkdownPlugin: PluginSimple;
 //#endregion
-export { _default as default, fieldMarkdownPlugin };
+export { field as default, field, fieldMarkdownPlugin };

package/dist/node/index.js

@@ -2,8 +2,12 @@ import { definePlugin } from "vitepress-tuck";
 import { isUndefined } from "@pengzhanbo/utils";
 import { createContainerPlugin, createContainerSyntaxPlugin, stringifyAttrs } from "vitepress-plugin-toolkit";
 //#region src/node/parseFieldContent.ts
-/** Tags that carry structured meaning; everything else is description text. */
-const KNOWN_TAGS = new Set([
+/**
+* Tags that carry structured meaning; everything else is description text.
+*
+* 携带结构化含义的标签；其他内容均视为描述文本。
+*/
+const KNOWN_TAGS = /* @__PURE__ */ new Set([
 	"name",
 	"type",
 	"default",
@@ -41,8 +45,8 @@ const KNOWN_TAGS = new Set([
 * 未知的以 `@` 开头的标签将被视为描述文本。
 * 空行会被忽略，且不会中断描述段落。
 *
-* @param content Raw text inside the `:::` container
-* @param info    Text after `::: field` on the opening line (the field name)
+* @param content - Raw text inside the `:::` container / `:::` 容器内的原始文本
+* @param info - Text after `::: field` on the opening line (the field name) / 起始行中 `::: field` 之后的文本（字段名称）
 */
 function parseFieldContent(content, info) {
 	const lines = content.split("\n");
@@ -50,10 +54,15 @@ function parseFieldContent(content, info) {
 		name: info.trim(),
 		description: ""
 	};
-	/** Accumulates the current description paragraph. */
+	/** Accumulates the current description paragraph. / 累积当前描述段落。 */
 	let currentDesc = "";
-	/** Completed description segments, joined with `\n` at the end. */
+	/** Completed description segments, joined with `\n` at the end. / 已完成的描述片段，最后以 `\n` 连接。 */
 	const descriptions = [];
+	/**
+	* Flushes the accumulated description paragraph into the `descriptions` array.
+	*
+	* 将已累积的描述段落刷新到 `descriptions` 数组中。
+	*/
 	function flushDesc() {
 		if (currentDesc) {
 			descriptions.push(currentDesc);
@@ -104,7 +113,32 @@ function parseFieldContent(content, info) {
 	return result;
 }
 //#endregion
-//#region src/node/fieldPlugin.ts
+//#region src/node/markdown.ts
+/**
+* markdown-it plugin that registers `::: field` and `::: field-group` containers.
+*
+* Registers two container syntaxes:
+* - `::: field-group` — wraps a group of fields in a `<div class="vp-field-group">`
+* - `::: field` — parses the container body via `parseFieldContent` and renders
+*   a `<VPField>` Vue component with the extracted props
+*
+* markdown-it 插件，注册 `::: field` 和 `::: field-group` 容器。
+*
+* 注册两种容器语法：
+* - `::: field-group` — 将一组字段包裹在 `<div class="vp-field-group">` 中
+* - `::: field` — 通过 `parseFieldContent` 解析容器正文，并渲染带有提取属性的
+*   `<VPField>` Vue 组件
+*
+* @param md - The markdown-it instance to extend / 要扩展的 markdown-it 实例
+* @example
+* ```ts
+* import MarkdownIt from 'markdown-it'
+* import { fieldMarkdownPlugin } from 'vitepress-plugin-field/node'
+*
+* const md = new MarkdownIt()
+* md.use(fieldMarkdownPlugin)
+* ```
+*/
 const fieldMarkdownPlugin = (md) => {
 	createContainerPlugin(md, "field-group", { before: () => "<div class=\"vp-field-group\">" });
 	createContainerSyntaxPlugin(md, "field", (tokens, idx, _, env) => {
@@ -114,8 +148,31 @@ const fieldMarkdownPlugin = (md) => {
 	});
 };
 //#endregion
-//#region src/node/index.ts
-var node_default = definePlugin(() => ({
+//#region src/node/plugin.ts
+/**
+* VitePress plugin for rendering structured field documentation blocks.
+*
+* Registers a markdown-it container plugin that transforms `::: field` blocks
+* into interactive `<VPField>` Vue components, and wires up the client-side
+* component registration via `enhanceAppWithField`.
+*
+* VitePress 插件，用于渲染结构化的字段文档块。
+*
+* 注册 markdown-it 容器插件，将 `::: field` 块转换为交互式 `<VPField>` Vue 组件，
+* 并通过 `enhanceAppWithField` 完成客户端组件注册。
+*
+* @example
+* `.vitepress/config.ts`
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import field from 'vitepress-plugin-field'
+*
+* export default defineConfig({
+*   plugins: [field()],
+* })
+* ```
+*/
+const field = definePlugin(() => ({
 	name: "vitepress-plugin-field",
 	client: { enhance: "enhanceAppWithField" },
 	markdown: { config(md) {
@@ -123,4 +180,12 @@ var node_default = definePlugin(() => ({
 	} }
 }));
 //#endregion
-export { node_default as default, fieldMarkdownPlugin };
+//#region src/node/index.ts
+/**
+* Node-side entry point for `vitepress-plugin-field`.
+*
+* `vitepress-plugin-field` 的 Node 端入口模块。
+*/
+var node_default = field;
+//#endregion
+export { node_default as default, field, fieldMarkdownPlugin };

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "vitepress-plugin-field",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Render structured API fields and properties documentation in your VitePress site.",
   "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
   "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/plugins/field",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
     "directory": "packages/plugin-field"
   },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
   "keywords": [
     "vitepress",
     "vitepress-plugin",
@@ -34,8 +38,8 @@
   },
   "dependencies": {
     "@pengzhanbo/utils": "^3.7.3",
-    "vitepress-plugin-toolkit": "0.2.0",
-    "vitepress-tuck": "0.2.0"
+    "vitepress-plugin-toolkit": "0.4.0",
+    "vitepress-tuck": "0.4.0"
   },
   "publishConfig": {
     "access": "public",