vitepress-plugin-toolkit 0.2.0 → 0.4.0

package/dist/client/ssr/index.js

@@ -1,22 +1,98 @@
-import { computed, defineComponent, isRef, mergeProps, onMounted, ref, toValue, unref, useSSRContext, watch } from "vue";
-import { ssrRenderAttrs } from "vue/server-renderer";
-import { useClipboard, useEventListener } from "@vueuse/core";
+import { computed, defineComponent, isRef, mergeModels, mergeProps, nextTick, onMounted, ref, shallowRef, toValue, unref, useModel, useSSRContext, watch } from "vue";
+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
-const _sfc_main = /* @__PURE__ */ defineComponent({
+/** 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({
@@ -27,15 +103,15 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 		};
 	}
 });
-const _sfc_setup$1 = _sfc_main.setup;
+const _sfc_setup$2 = _sfc_main.setup;
 _sfc_main.setup = (props, ctx) => {
 	const ssrContext = useSSRContext();
 	(ssrContext.modules || (ssrContext.modules = /* @__PURE__ */ new Set())).add("src/client/components/VPCopyButton.vue");
-	return _sfc_setup$1 ? _sfc_setup$1(props, ctx) : void 0;
+	return _sfc_setup$2 ? _sfc_setup$2(props, ctx) : void 0;
 };
 //#endregion
 //#region src/client/components/VPLoading.vue
-const _sfc_main$1 = /* @__PURE__ */ defineComponent({
+const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 	__name: "VPLoading",
 	__ssrInlineRender: true,
 	props: {
@@ -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 }],
@@ -51,14 +139,63 @@ const _sfc_main$1 = /* @__PURE__ */ defineComponent({
 		};
 	}
 });
-const _sfc_setup = _sfc_main$1.setup;
+const _sfc_setup$1 = _sfc_main$1.setup;
 _sfc_main$1.setup = (props, ctx) => {
 	const ssrContext = useSSRContext();
 	(ssrContext.modules || (ssrContext.modules = /* @__PURE__ */ new Set())).add("src/client/components/VPLoading.vue");
+	return _sfc_setup$1 ? _sfc_setup$1(props, ctx) : void 0;
+};
+//#endregion
+//#region src/client/components/VPTabSwitch.vue
+/** List of tab items to render / 要渲染的标签项列表 */
+const _sfc_main$2 = /*@__PURE__*/ defineComponent({
+	__name: "VPTabSwitch",
+	__ssrInlineRender: true,
+	props: /*@__PURE__*/ mergeModels({ items: {} }, {
+		"modelValue": {},
+		"modelModifiers": {}
+	}),
+	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;
+		});
+		return (_ctx, _push, _parent, _attrs) => {
+			_push(`<div${ssrRenderAttrs(mergeProps({ class: "vp-tab-switch-list" }, _attrs))}><!--[-->`);
+			ssrRenderList(__props.items, (item) => {
+				_push(`<button class="${ssrRenderClass({ active: tab.value === item.value })}">${ssrInterpolate(item.label)}</button>`);
+			});
+			_push(`<!--]--></div>`);
+		};
+	}
+});
+const _sfc_setup = _sfc_main$2.setup;
+_sfc_main$2.setup = (props, ctx) => {
+	const ssrContext = useSSRContext();
+	(ssrContext.modules || (ssrContext.modules = /* @__PURE__ */ new Set())).add("src/client/components/VPTabSwitch.vue");
 	return _sfc_setup ? _sfc_setup(props, ctx) : void 0;
 };
 //#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");
@@ -82,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(":");
@@ -91,10 +249,223 @@ function getRadio(ratio) {
 	return typeof ratio === "number" ? ratio : 16 / 9;
 }
 //#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;
+	const x = ref(0);
+	const y = ref(0);
+	const width = ref(void 0);
+	let originalWidth = 0;
+	let initialState = {
+		width: 0,
+		x: 0,
+		y: 0
+	};
+	const isDesktop = useMediaQuery("(min-width: 640px)");
+	useMutationObserver(actorEl, (mutationList) => {
+		if (mutationList.some((mutation) => mutation.type === "childList")) nextTick(initialize);
+	}, {
+		subtree: true,
+		childList: true,
+		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");
+		actorEl.value = actor;
+		if (!actor) return;
+		actor.style.width = "max-content";
+		actor.style.height = "";
+		const stage = parentEl.value;
+		const clientHeight = document.documentElement.clientHeight;
+		const maxHeight = isFullscreen ? clientHeight : isDesktop.value ? clientHeight * .75 : clientHeight / 2;
+		const { offsetWidth: actorWidth, offsetHeight: actorHeight } = actor;
+		const stageWidth = stage.offsetWidth;
+		ratio = actorWidth / actorHeight;
+		let tryZoom = 1;
+		let stageHeight = isFullscreen ? clientHeight : actorHeight;
+		let newActorHeight = actorHeight;
+		if (actorWidth > stageWidth) {
+			tryZoom = stageWidth / actorWidth;
+			newActorHeight = actorHeight * tryZoom;
+		}
+		if (newActorHeight > maxHeight) {
+			tryZoom = maxHeight / actorHeight;
+			stageHeight = maxHeight;
+		}
+		stage.style.height = `${stageHeight + 24}px`;
+		if (tryZoom === 1) {
+			width.value = actorWidth;
+			x.value = (stageWidth - width.value) / 2;
+			y.value = (stageHeight - actorHeight) / 2;
+		} else {
+			width.value = actorWidth * tryZoom;
+			const zoomHeight = width.value / ratio;
+			x.value = (stageWidth - width.value) / 2;
+			y.value = Math.max(0, ((isFullscreen ? clientHeight : stage.offsetHeight) - zoomHeight) / 2);
+		}
+		originalWidth = actorWidth;
+		initialState = {
+			width: width.value,
+			x: x.value,
+			y: y.value
+		};
+	}
+	let isDragging = false;
+	let startX = 0;
+	let startY = 0;
+	useEventListener(parentEl, "mousedown", (e) => {
+		if (e.target.matches("button,[class^=\"vpi-\"]")) return;
+		e.preventDefault();
+		startX = e.clientX;
+		startY = e.clientY;
+		isDragging = true;
+		parentEl.value.style.cursor = "move";
+	});
+	useEventListener(parentEl, "mousemove", (e) => {
+		if (isDragging) {
+			e.preventDefault();
+			x.value += e.clientX - startX;
+			y.value += e.clientY - startY;
+			startX = e.clientX;
+			startY = e.clientY;
+		}
+	});
+	useEventListener(parentEl, "mouseup", () => {
+		isDragging = false;
+		parentEl.value.style.cursor = "";
+	});
+	let startGap = 0;
+	let currentWidth = 0;
+	useEventListener(parentEl, "touchstart", (e) => {
+		if (e.target.matches("button,[class^=\"vpi-\"]")) return;
+		e.preventDefault();
+		const touches = e.touches;
+		startX = touches[0].clientX;
+		startY = touches[0].clientY;
+		isDragging = true;
+		if (touches[1]) {
+			startGap = Math.abs(touches[1].clientX - touches[0].clientX);
+			currentWidth = width.value || originalWidth;
+		}
+	}, { passive: false });
+	useEventListener(parentEl, "touchmove", (e) => {
+		if (!isDragging) return;
+		const touches = e.touches;
+		e.preventDefault();
+		x.value += touches[0].clientX - startX;
+		y.value += touches[0].clientY - startY;
+		startX = touches[0].clientX;
+		startY = touches[0].clientY;
+		if (touches[1]) width.value = currentWidth + Math.abs(touches[1].clientX - touches[0].clientX) - startGap;
+	}, { passive: false });
+	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) {
+			zooming();
+			x.value = initialState.x;
+			y.value = initialState.y;
+			width.value = initialState.width;
+		} else {
+			const steps = initialState.width / 10 * type;
+			if (width.value + steps <= 100) return;
+			zooming();
+			width.value += steps;
+			x.value -= steps / 2;
+			y.value -= steps / ratio / 2;
+		}
+	}
+	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);
+		zoomTimer = setTimeout(() => {
+			actorEl.value.classList.remove("zooming");
+		}, 250);
+	}
+	return {
+		actorStyle: computed(() => ({
+			left: `${Math.ceil(x.value)}px`,
+			top: `${Math.ceil(y.value)}px`,
+			width: width.value ? `${Math.ceil(width.value)}px` : void 0,
+			height: `${width.value ? Math.ceil(width.value / ratio) : void 0}px`
+		})),
+		zoom: computed(() => `${Math.round((width.value || originalWidth) / originalWidth * 100)}%`),
+		reset: initialize,
+		zoomIn: () => zoom(1),
+		zoomOut: () => zoom(-1),
+		resetZoom: () => zoom(0)
+	};
+}
+//#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.
@@ -168,4 +539,4 @@ function isSafari() {
 	return /safari/iu.test(ua) && !/chrome|crios|fxios|edgios|edg|opr|opera|ucbrowser|qqbrowser|baidubrowser/iu.test(ua);
 }
 //#endregion
-export { EXTERNAL_URL_RE, URL_PROTOCOL_RE, _sfc_main as VPCopyButton, _sfc_main$1 as VPLoading, isExternal, isIOS, isLinkWithProtocol, isMacOS, isMobile, isSafari, isWindows, isiPad, isiPhone, useSize };
+export { EXTERNAL_URL_RE, URL_PROTOCOL_RE, _sfc_main as VPCopyButton, _sfc_main$1 as VPLoading, _sfc_main$2 as VPTabSwitch, isExternal, isIOS, isLinkWithProtocol, isMacOS, isMobile, isSafari, isWindows, isiPad, isiPhone, useSize, useZoomAndDrag };

package/dist/client/styles/tab-switch.css

@@ -0,0 +1,31 @@
+.vp-tab-switch-list {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: center;
+  padding-block: 2px;
+  padding-inline: 4px;
+  background-color: var(--vp-c-gray-soft);
+  border-radius: 6px;
+}
+
+.vp-tab-switch-list button {
+  display: inline-block;
+  padding-block: 2px;
+  padding-inline: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 18px;
+  color: var(--vp-c-text-3);
+  cursor: pointer;
+  user-select: none;
+  background-color: transparent;
+  border-radius: 6px;
+  transition: background-color 0.25s ease-in-out;
+}
+
+.vp-tab-switch-list button.active {
+  color: var(--vp-c-text-1);
+  background-color: var(--vp-c-bg);
+  box-shadow: var(--vp-shadow-1);
+}