vitepress-plugin-toolkit 0.3.0 → 0.5.0

package/dist/client/ssr/index.js

@@ -2,21 +2,97 @@ import { computed, defineComponent, isRef, mergeModels, mergeProps, nextTick, on
 import { ssrInterpolate, ssrRenderAttrs, ssrRenderClass, ssrRenderList } from "vue/server-renderer";
 import { useClipboard, useEventListener, useMediaQuery, useMutationObserver } from "@vueuse/core";
 //#region src/shared/link.ts
+/**
+* Regular expression that matches external URLs.
+*
+* Matches URLs that start with a protocol (such as `http:` or `mailto:`) or
+* with `//` (protocol-relative URLs).
+*
+* 匹配外部链接的正则表达式。
+*
+* 匹配以协议（如 `http:` 或 `mailto:`）或 `//`（协议相对链接）开头的 URL。
+*
+* @example
+* EXTERNAL_URL_RE.test('https://example.com') // true
+* EXTERNAL_URL_RE.test('//cdn.example.com/lib.js') // true
+* EXTERNAL_URL_RE.test('/about') // false
+*/
 const EXTERNAL_URL_RE = /^(?:[a-z]+:|\/\/)/i;
+/**
+* Checks whether the given path is an external URL.
+*
+* 判断给定路径是否为外部链接。
+*
+* @param path - The path to check / 要检查的路径
+* @returns `true` if the path is an external URL, otherwise `false` / 若为外部链接返回 `true`，否则返回 `false`
+* @example
+* isExternal('https://example.com') // true
+* isExternal('//cdn.example.com/lib.js') // true
+* isExternal('/about') // false
+* isExternal('mailto:foo@example.com') // true
+*/
 function isExternal(path) {
 	return EXTERNAL_URL_RE.test(path);
 }
+/**
+* Regular expression that matches the protocol scheme of a URL.
+*
+* Matches the leading protocol portion such as `http:`, `https:`, or
+* `mailto:`. Does not match protocol-relative URLs (`//`).
+*
+* 匹配 URL 协议部分的正则表达式。
+*
+* 匹配前导协议部分，如 `http:`、`https:` 或 `mailto:`。
+* 不匹配协议相对链接（`//`）。
+*
+* @example
+* URL_PROTOCOL_RE.test('https://example.com') // true
+* URL_PROTOCOL_RE.test('mailto:foo@example.com') // true
+* URL_PROTOCOL_RE.test('//cdn.example.com/lib.js') // false
+*/
 const URL_PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/;
+/**
+* Checks whether the given link contains a URL protocol scheme or is a
+* protocol-relative URL.
+*
+* Unlike {@link isExternal}, this function also matches links that start with
+* `//` via an additional check, in addition to those matched by
+* {@link URL_PROTOCOL_RE}.
+*
+* 判断给定链接是否包含 URL 协议部分或为协议相对链接。
+*
+* 与 {@link isExternal} 不同，此函数除了匹配 {@link URL_PROTOCOL_RE} 之外，
+* 还会通过额外检查匹配以 `//` 开头的链接。
+*
+* @param link - The link to check / 要检查的链接
+* @returns `true` if the link has a protocol or starts with `//` / 若链接包含协议或以 `//` 开头则返回 `true`
+* @example
+* isLinkWithProtocol('https://example.com') // true
+* isLinkWithProtocol('mailto:foo@example.com') // true
+* isLinkWithProtocol('//cdn.example.com/lib.js') // true
+* isLinkWithProtocol('/about') // false
+*/
 function isLinkWithProtocol(link) {
 	return URL_PROTOCOL_RE.test(link) || link.startsWith("//");
 }
 //#endregion
 //#region src/client/components/VPCopyButton.vue
+/** Text to copy to the clipboard / 要复制到剪贴板的文本 */
 const _sfc_main = /*@__PURE__*/ defineComponent({
 	__name: "VPCopyButton",
 	__ssrInlineRender: true,
 	props: { text: {} },
 	setup(__props) {
+		/**
+		* A button component that copies the given text to the clipboard.
+		*
+		* 复制指定文本到剪贴板的按钮组件。
+		*
+		* @example
+		* ```vue
+		* <VPCopyButton text="Hello, world!" />
+		* ```
+		*/
 		const { copied, copy } = useClipboard();
 		return (_ctx, _push, _parent, _attrs) => {
 			_push(`<button${ssrRenderAttrs(mergeProps({
@@ -43,6 +119,18 @@ const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 		height: {}
 	},
 	setup(__props) {
+		/**
+		* A loading indicator component with an animated SVG spinner.
+		*
+		* 带有 SVG 动画旋转图标的加载指示器组件。
+		*
+		* @example
+		* ```vue
+		* <VPLoading />
+		*
+		* <VPLoading absolute height="200px" />
+		* ```
+		*/
 		return (_ctx, _push, _parent, _attrs) => {
 			_push(`<div${ssrRenderAttrs(mergeProps({
 				class: ["vp-loading", { absolute: __props.absolute }],
@@ -59,6 +147,7 @@ _sfc_main$1.setup = (props, ctx) => {
 };
 //#endregion
 //#region src/client/components/VPTabSwitch.vue
+/** List of tab items to render / 要渲染的标签项列表 */
 const _sfc_main$2 = /*@__PURE__*/ defineComponent({
 	__name: "VPTabSwitch",
 	__ssrInlineRender: true,
@@ -68,6 +157,7 @@ const _sfc_main$2 = /*@__PURE__*/ defineComponent({
 	}),
 	emits: /*@__PURE__*/ mergeModels(["update"], ["update:modelValue"]),
 	setup(__props, { emit: __emit }) {
+		/** Current active tab value (v-model) / 当前活动标签的值（v-model） */
 		const tab = useModel(__props, "modelValue");
 		watch(() => __props.items, () => {
 			tab.value = __props.items[0].value;
@@ -89,6 +179,23 @@ _sfc_main$2.setup = (props, ctx) => {
 };
 //#endregion
 //#region src/client/composables/use-size.ts
+/**
+* Composable that provides reactive size tracking for an element based on width,
+* height, and aspect ratio options.
+*
+* 基于宽度、高度和宽高比选项为元素提供响应式尺寸追踪的组合式函数。
+*
+* @template T - HTMLElement type of the target element / 目标元素的 HTMLElement 类型
+* @param el - Template ref to the target element / 目标元素的模板 ref
+* @param options - Reactive size options (width, height, ratio) / 响应式尺寸选项（width、height、ratio）
+* @param extraHeight - Extra height in pixels to add to the computed height / 要加到计算高度上的额外像素高度
+* @returns Reactive size info with width, height, and a resize function / 包含 width、height 和 resize 函数的响应式尺寸信息
+* @example
+* ```ts
+* const el = ref<HTMLElement>()
+* const { width, height, resize } = useSize(el, toRefs({ width: '100%', ratio: '16:9' }))
+* ```
+*/
 function useSize(el, options, extraHeight = 0) {
 	const width = computed(() => toValue(options.width) || "100%");
 	const height = ref("auto");
@@ -112,6 +219,27 @@ function useSize(el, options, extraHeight = 0) {
 		resize
 	};
 }
+/**
+* Parse a ratio value into a numeric width-to-height ratio.
+*
+* 将宽高比值解析为数值形式的宽高比。
+*
+* Accepts a number, a string like `"16:9"`, or `undefined` (defaults to 16:9).
+*
+* 接受数字、形如 `"16:9"` 的字符串或 `undefined`（默认为 16:9）。
+*
+* @param ratio - Ratio value, can be:
+*   - `number`: Used directly as the ratio / 直接作为宽高比
+*   - `string`: Parsed from "width:height" format / 从 "width:height" 格式解析
+*   - `undefined`: Defaults to 16/9 / 默认为 16/9
+* @returns Numeric width-to-height ratio / 数值形式的宽高比
+* @example
+* ```ts
+* getRadio(2)        // 2
+* getRadio('16:9')   // 1.777...
+* getRadio(undefined) // 1.777...
+* ```
+*/
 function getRadio(ratio) {
 	if (typeof ratio === "string") {
 		const [width, height] = ratio.split(":");
@@ -122,6 +250,26 @@ function getRadio(ratio) {
 }
 //#endregion
 //#region src/client/composables/use-zoom-and-drag.ts
+/**
+* Composable that provides zoom and drag interaction for a content stage,
+* supporting mouse drag, touch drag, pinch-to-zoom, and programmatic zoom.
+*
+* 为内容舞台提供缩放和拖拽交互的组合式函数，支持鼠标拖拽、触摸拖拽、双指缩放和编程式缩放。
+*
+* @param parentEl - Template ref to the stage container element / 舞台容器元素的模板 ref
+* @returns Interaction controls and reactive state, including:
+*   - `actorStyle`: Reactive style object for the actor element / actor 元素的响应式样式对象
+*   - `zoom`: Reactive zoom percentage string / 响应式缩放百分比字符串
+*   - `reset`: Reset layout to fit the stage / 重置布局以适配舞台
+*   - `zoomIn`: Zoom in by one step / 放大一个步长
+*   - `zoomOut`: Zoom out by one step / 缩小一个步长
+*   - `resetZoom`: Reset zoom to the initial state / 重置缩放至初始状态
+* @example
+* ```ts
+* const stageEl = ref<HTMLDivElement>()
+* const { actorStyle, zoom, zoomIn, zoomOut, resetZoom, reset } = useZoomAndDrag(stageEl)
+* ```
+*/
 function useZoomAndDrag(parentEl) {
 	const actorEl = shallowRef();
 	let ratio = 0;
@@ -143,6 +291,14 @@ function useZoomAndDrag(parentEl) {
 		attributes: false
 	});
 	onMounted(() => nextTick(initialize));
+	/**
+	* Initialize the actor layout by measuring content size and computing the
+	* initial zoom, position, and stage height to fit the available space.
+	*
+	* 通过测量内容尺寸并计算初始缩放、位置和舞台高度来初始化 actor 布局，以适配可用空间。
+	*
+	* @param isFullscreen - Whether the stage is in fullscreen mode / 舞台是否处于全屏模式
+	*/
 	function initialize(isFullscreen = false) {
 		if (!parentEl.value) return;
 		const actor = parentEl.value.querySelector(".content");
@@ -236,6 +392,16 @@ function useZoomAndDrag(parentEl) {
 	useEventListener(parentEl, "touchend", () => {
 		isDragging = false;
 	}, { passive: false });
+	/**
+	* Adjust the zoom level by a fixed step, or reset to the initial state.
+	*
+	* 按固定步长调整缩放级别，或重置到初始状态。
+	*
+	* @param type - Zoom direction, can be:
+	*   - `1`: Zoom in by one step / 放大一个步长
+	*   - `-1`: Zoom out by one step / 缩小一个步长
+	*   - `0`: Reset to the initial zoom and position / 重置到初始缩放和位置
+	*/
 	function zoom(type) {
 		if (typeof width.value === "undefined" || !actorEl.value) return;
 		if (type === 0) {
@@ -253,6 +419,12 @@ function useZoomAndDrag(parentEl) {
 		}
 	}
 	let zoomTimer;
+	/**
+	* Temporarily add a `zooming` class to the actor element to enable CSS
+	* transitions during zoom, and remove it after the transition completes.
+	*
+	* 临时为 actor 元素添加 `zooming` 类以在缩放时启用 CSS 过渡，并在过渡结束后移除该类。
+	*/
 	function zooming() {
 		actorEl.value?.classList.add("zooming");
 		if (zoomTimer) clearTimeout(zoomTimer);
@@ -276,9 +448,24 @@ function useZoomAndDrag(parentEl) {
 }
 //#endregion
 //#region src/client/utils/env.ts
+/**
+* Get the platform string of the user device, preferring UA-CH data over the
+* legacy `navigator.platform`.
+*
+* 获取用户设备的平台字符串，优先使用 UA-CH 数据，其次使用传统的 `navigator.platform`。
+*
+* @returns Platform string / 平台字符串
+*/
 function getPlatform() {
 	return navigator.userAgentData?.platform ?? navigator.platform;
 }
+/**
+* Get the user agent string of the browser.
+*
+* 获取浏览器的 user agent 字符串。
+*
+* @returns User agent string / user agent 字符串
+*/
 const getUA = () => navigator.userAgent;
 /**
 * Check if the user device is iPhone or iPod.