vitepress-plugin-toolkit 0.2.0 → 0.4.0

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

@@ -1,64 +1,269 @@
 import { MaybeRef, Ref, TemplateRef, ToRefs } from "vue";
 
 //#region src/shared/link.d.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
+ */
 declare const EXTERNAL_URL_RE: RegExp;
+/**
+ * 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
+ */
 declare function isExternal(path: string): boolean;
+/**
+ * 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
+ */
 declare const URL_PROTOCOL_RE: RegExp;
+/**
+ * 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
+ */
 declare function isLinkWithProtocol(link: string): boolean;
 //#endregion
 //#region src/shared/size.d.ts
 /**
- * Size Options
+ * Options for describing the size of an element.
+ *
+ * Used by plugins to normalize width, height, and aspect ratio inputs into a
+ * consistent CSS-friendly form.
+ *
+ * 描述元素尺寸的选项。
+ *
+ * 供插件使用，将宽度、高度和宽高比输入归一化为一致的 CSS 友好形式。
  *
- * 尺寸选项
+ * @example
+ * const options: SizeOptions = {
+ *   width: '100%',
+ *   ratio: 16 / 9,
+ * }
  */
 interface SizeOptions {
   /**
-   * Width
+   * Width of the element, expressed as a CSS value.
    *
-   * 宽度
+   * 元素的宽度，以 CSS 值表示。
+   *
+   * @example
+   * '100%' | '640px' | 'auto'
    */
   width?: string;
   /**
-   * Height
+   * Height of the element, expressed as a CSS value.
+   *
+   * 元素的高度，以 CSS 值表示。
    *
-   * 高度
+   * @example
+   * '100%' | '360px' | 'auto'
    */
   height?: string;
   /**
-   * Aspect ratio
+   * Aspect ratio of the element. Can be:
+   *   - `number`: Numeric ratio (for example `16 / 9` represents 16:9)
+   *   - `string`: CSS aspect-ratio value (for example `'16 / 9'` or `'1.77'`)
+   *
+   * 元素的宽高比。可以是：
+   *   - `number`：数字比例（例如 `16 / 9` 表示 16:9）
+   *   - `string`：CSS aspect-ratio 值（例如 `'16 / 9'` 或 `'1.77'`）
    *
-   * 宽高比
+   * @example
+   * 16 / 9
+   * '16 / 9'
    */
   ratio?: number | string;
 }
 //#endregion
 //#region src/client/components/VPCopyButton.vue.d.ts
+/** Text to copy to the clipboard / 要复制到剪贴板的文本 */
 type __VLS_Props$1 = {
   text: string;
 };
-declare const __VLS_export$1: import("vue").DefineComponent<__VLS_Props$1, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props$1> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default: typeof __VLS_export$1;
+declare const __VLS_export$2: import("vue").DefineComponent<__VLS_Props$1, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props$1> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export$2;
 //#endregion
 //#region src/client/components/VPLoading.vue.d.ts
+/**
+ * A loading indicator component with an animated SVG spinner.
+ *
+ * 带有 SVG 动画旋转图标的加载指示器组件。
+ *
+ * @example
+ * ```vue
+ * <VPLoading />
+ *
+ * <VPLoading absolute height="200px" />
+ * ```
+ */
 type __VLS_Props = {
-  absolute?: boolean;
+  /** Whether to position the loader absolutely / 是否以绝对定位渲染加载器 */absolute?: boolean; /** Custom height for the loading container / 加载容器的自定义高度 */
   height?: string;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default$1: typeof __VLS_export;
+declare const __VLS_export$1: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$1: typeof __VLS_export$1;
+//#endregion
+//#region src/client/components/VPTabSwitch.vue.d.ts
+/**
+ * Represents a single tab item.
+ *
+ * 表示单个标签项。
+ *
+ * @template T - Type of the tab value / 标签值的类型
+ */
+interface Item<T> {
+  /** Value of the tab item / 标签项的值 */
+  value: T;
+  /** Display label of the tab item / 标签项的显示文本 */
+  label: string;
+}
+declare const __VLS_export: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: import("vue").PublicProps & __VLS_PrettifyLocal<({
+    items: Item<T>[];
+  } & {
+    /** Current active tab value (v-model) / 当前活动标签的值（v-model） */modelValue?: T;
+  }) & {
+    onUpdate?: ((tab: T) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: T | undefined) => any) | undefined;
+  }> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: {}) => void;
+  attrs: any;
+  slots: {};
+  emit: ((evt: "update", tab: T) => void) & ((event: "update:modelValue", value: T | undefined) => void);
+}>) => import("vue").VNode & {
+  __ctx?: Awaited<typeof __VLS_setup>;
+};
+declare const _default$2: typeof __VLS_export;
+type __VLS_PrettifyLocal<T> = (T extends any ? { [K in keyof T]: T[K] } : { [K in keyof T as K]: T[K] }) & {};
 //#endregion
 //#region src/client/composables/use-size.d.ts
+/**
+ * Reactive size information returned by `useSize`.
+ *
+ * `useSize` 返回的响应式尺寸信息。
+ */
 interface SizeInfo {
+  /** Reactive width value (e.g. "100%" or "500px") / 响应式宽度值（例如 "100%" 或 "500px"） */
   width: Ref<string>;
+  /** Reactive height value (e.g. "auto" or "300px") / 响应式高度值（例如 "auto" 或 "300px"） */
   height: Ref<string>;
+  /** Manually trigger a size recalculation / 手动触发尺寸重新计算 */
   resize: () => void;
 }
+/**
+ * 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' }))
+ * ```
+ */
 declare function useSize<T extends HTMLElement>(el: TemplateRef<T>, options: ToRefs<SizeOptions>, extraHeight?: MaybeRef<number>): SizeInfo;
 //#endregion
+//#region src/client/composables/use-zoom-and-drag.d.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)
+ * ```
+ */
+declare function useZoomAndDrag(parentEl: TemplateRef<HTMLDivElement>): {
+  actorStyle: import("vue").ComputedRef<{
+    left: string;
+    top: string;
+    width: string | undefined;
+    height: string;
+  }>;
+  zoom: import("vue").ComputedRef<string>;
+  reset: (isFullscreen?: boolean) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  resetZoom: () => void;
+};
+//#endregion
 //#region src/client/utils/env.d.ts
+/**
+ * User-Agent Client Hints data provided by modern browsers.
+ *
+ * 现代浏览器提供的 User-Agent 客户端提示数据。
+ */
 interface NavigatorUAData {
+  /** Operating system platform identifier / 操作系统平台标识符 */
   platform?: string;
+  /** Whether the device is a mobile device / 设备是否为移动设备 */
   mobile?: boolean;
 }
 declare global {
@@ -123,4 +328,4 @@ declare function isMobile(): boolean;
  */
 declare function isSafari(): boolean;
 //#endregion
-export { EXTERNAL_URL_RE, SizeInfo, SizeOptions, URL_PROTOCOL_RE, _default as VPCopyButton, _default$1 as VPLoading, isExternal, isIOS, isLinkWithProtocol, isMacOS, isMobile, isSafari, isWindows, isiPad, isiPhone, useSize };
+export { EXTERNAL_URL_RE, SizeInfo, SizeOptions, URL_PROTOCOL_RE, _default as VPCopyButton, _default$1 as VPLoading, _default$2 as VPTabSwitch, isExternal, isIOS, isLinkWithProtocol, isMacOS, isMobile, isSafari, isWindows, isiPad, isiPhone, useSize, useZoomAndDrag };