vitepress-plugin-toolkit 0.3.0 → 0.5.0

package/README.zh-CN.md

@@ -0,0 +1,389 @@
+# vitepress-plugin-toolkit
+
+> [English Documentation](./README.md)
+
+VitePress 插件开发工具包，为 VitePress 插件作者提供 Node 端和 Client 端的通用工具、组件和组合式函数。
+
+## 安装
+
+```bash
+pnpm add vitepress-plugin-toolkit
+```
+
+## 入口
+
+| 入口                                | 说明                                                           |
+| ----------------------------------- | -------------------------------------------------------------- |
+| `vitepress-plugin-toolkit`          | Node 端工具（markdown-it 插件、Vite 插件、VitePress 配置工具） |
+| `vitepress-plugin-toolkit/client`   | Client 端工具（Vue 组件、composables、环境检测工具）           |
+| `vitepress-plugin-toolkit/styles/*` | CSS 过渡动效和组件样式                                         |
+
+## Node 端 API
+
+### Markdown 工具
+
+#### `createEmbedRuleBlock(md, options)`
+
+创建一个嵌入规则块，用于解析 `@[type info](source)` 语法的 markdown 标记。
+
+```ts
+import { createEmbedRuleBlock } from 'vitepress-plugin-toolkit'
+
+createEmbedRuleBlock(md, {
+  type: 'video',
+  meta: (info, source) => ({ src: source, title: info }),
+  content: meta => `<video src="${meta.src}" title="${meta.title}"></video>`,
+})
+```
+
+Markdown 中使用：
+
+```md
+@[video 我的视频](https://example.com/video.mp4)
+```
+
+**选项:**
+
+| 参数      | 类型                                       | 说明                                            |
+| --------- | ------------------------------------------ | ----------------------------------------------- |
+| `type`    | `string`                                   | 嵌入类型标识，如 `'video'`、`'embed'`           |
+| `name`    | `string`                                   | 可选，自定义 token 名称，默认为 `embed_${type}` |
+| `meta`    | `(info: string, source: string) => Meta`   | 解析 info 和 source 为元数据对象                |
+| `content` | `(meta: Meta, env: MarkdownEnv) => string` | 可选，从元数据生成 HTML 内容                    |
+
+#### `createContainerPlugin(md, type, options?)`
+
+基于 `markdown-it-container` 创建自定义容器插件。内容由 markdown-it 正常处理。
+
+```ts
+import { createContainerPlugin } from 'vitepress-plugin-toolkit'
+
+md.use(createContainerPlugin, 'tip', {
+  before: info => `<div class="tip">${info}`,
+  after: () => '</div>',
+})
+```
+
+Markdown 中使用：
+
+```md
+::: tip 提示
+这是一条提示信息
+:::
+```
+
+**选项:**
+
+| 参数     | 类型                                                  | 说明                     |
+| -------- | ----------------------------------------------------- | ------------------------ |
+| `before` | `(info: string, ...args: RenderRuleParams) => string` | 可选，容器开始标签的回调 |
+| `after`  | `(info: string, ...args: RenderRuleParams) => string` | 可选，容器结束标签的回调 |
+
+#### `createContainerSyntaxPlugin(md, type, render?)`
+
+创建一个自定义容器语法插件，容器内的内容**不经过** markdown-it 处理，而是完整交给自定义渲染函数。
+
+```ts
+import { createContainerSyntaxPlugin } from 'vitepress-plugin-toolkit'
+
+createContainerSyntaxPlugin(md, 'chart', (tokens, idx) => {
+  const { content, meta } = tokens[idx]
+  return `<div class="chart">${content}</div>`
+})
+```
+
+### VitePress 配置工具
+
+#### `getVitepressConfig()`
+
+从 `globalThis.VITEPRESS_CONFIG` 获取当前 VitePress 站点配置。
+
+```ts
+import { getVitepressConfig } from 'vitepress-plugin-toolkit'
+
+const config = getVitepressConfig()
+console.log(config.userConfig.title)
+```
+
+#### `createLocales(builtinLocales, userLocales?)`
+
+创建多语言配置，合并内置语言数据和用户自定义语言数据。
+
+```ts
+import { createLocales } from 'vitepress-plugin-toolkit'
+
+const locales = createLocales(
+  [
+    [['en', 'en-US'], { title: 'English' }],
+    [['zh', 'zh-CN'], { title: '中文' }],
+  ],
+  { zh: { title: '我的站点' } },
+)
+```
+
+#### `resolveRouteLink(url, env)`
+
+根据 VitePress 路由规则解析 markdown 链接。支持：
+
+- 外部链接原样返回
+- 绝对路径自动添加 site base 前缀
+- 相对 `.md` 链接按 `cleanUrls` 设置转换为 `.html`
+- `index.md` 折叠为目录路径
+- 哈希片段自动 slugify
+
+```ts
+import { resolveRouteLink } from 'vitepress-plugin-toolkit'
+
+resolveRouteLink('./guide.md', env) // -> './guide.html' (取决于 cleanUrls)
+```
+
+#### `getLocaleWithPath(path)`
+
+根据路径获取对应的语言代码和语言环境前缀。
+
+```ts
+import { getLocaleWithPath } from 'vitepress-plugin-toolkit'
+
+getLocaleWithPath('/zh/guide/') // { lang: 'zh-CN', locale: '/zh/' }
+getLocaleWithPath('/guide/')   // { lang: 'en', locale: '' } (root)
+```
+
+### Vite 插件
+
+#### `iconPlugin(icons)`
+
+创建一个 Vite 插件，将 SVG 图标注册为 CSS 自定义属性（`--icon`），生成类如 `.vpi-<name>` 的 CSS 选择器。
+
+```ts
+import { iconPlugin } from 'vitepress-plugin-toolkit'
+
+defineConfig({
+  vite: {
+    plugins: [
+      iconPlugin([
+        { name: 'github', svg: '<svg>...</svg>' },
+        { name: 'twitter', svg: '<svg>...</svg>' },
+      ]),
+    ],
+  },
+})
+```
+
+使用时只需添加类名即可显示图标：
+
+```html
+<span class="vpi-github"></span>
+```
+
+### 节点工具函数
+
+#### `resolveAttrs(info)` / `resolveAttr(info, key)`
+
+将属性字符串解析为对象，或提取单个属性值。支持 `key="value"` 格式和布尔属性（`disabled` 等）。
+
+```ts
+import { resolveAttrs, resolveAttr } from 'vitepress-plugin-toolkit'
+
+resolveAttrs('width="100" height="50"') // { width: '100', height: '50' }
+resolveAttr('width="100" height="50"', 'width') // '100'
+```
+
+#### `stringifyAttrs(attrs, withUndefinedOrNull?, forceStringify?)`
+
+将属性对象字符串化为 HTML 属性字符串。自动处理 Boolean、Number、String 等类型。
+
+```ts
+import { stringifyAttrs } from 'vitepress-plugin-toolkit'
+
+stringifyAttrs({ width: 100, disabled: true })
+// ' :width="100" disabled'
+```
+
+#### `parseRect(str, unit?)`
+
+解析尺寸字符串，纯数字自动添加单位（默认 `px`）。
+
+```ts
+import { parseRect } from 'vitepress-plugin-toolkit'
+
+parseRect('100')    // '100px'
+parseRect('50%')    // '50%'
+parseRect('200', 'rpx') // '200rpx'
+```
+
+#### `slugify(str)`
+
+生成 URL 友好的 slug，移除重音符号、控制字符、特殊字符，合并连续分隔符。
+
+```ts
+import { slugify } from 'vitepress-plugin-toolkit'
+
+slugify('Hello World!') // 'hello-world'
+```
+
+#### `genHash(data, length?)`
+
+为任意数据生成 SHA-256 哈希值，可指定截断长度。
+
+```ts
+import { genHash } from 'vitepress-plugin-toolkit'
+
+genHash('hello')      // 完整 SHA-256 哈希
+genHash({ a: 1 }, 8)  // 8 位哈希
+```
+
+#### `treatAsHtml(filename)`
+
+判断文件是否为 HTML 路由文件（非静态资源）。
+
+```ts
+import { treatAsHtml } from 'vitepress-plugin-toolkit'
+
+treatAsHtml('about')   // true
+treatAsHtml('logo.png') // false
+```
+
+#### `createLogger(prefix, defaultLevel?)`
+
+创建带颜色标签、时间戳的格式化日志实例。
+
+```ts
+import { createLogger } from 'vitepress-plugin-toolkit'
+
+const logger = createLogger('my-plugin', 'info')
+logger.info('构建开始')
+logger.warn('使用了已废弃的功能')
+logger.debug('详细日志', 'debug')
+```
+
+#### 常量
+
+```ts
+import {
+  isBuild,          // 是否生产构建
+  isDev,            // 是否开发模式
+  EXTENSION_VIDEOS, // 浏览器支持的视频扩展名
+  EXTENSION_IMAGES, // 浏览器支持的图片扩展名
+  EXTENSION_AUDIOS, // 浏览器支持的音频扩展名
+} from 'vitepress-plugin-toolkit'
+```
+
+## Client 端 API
+
+### Vue 组件
+
+- `VPCopyButton` — 复制按钮组件
+- `VPLoading` — 加载动画组件
+- `VPTabSwitch` — Tab 切换组件
+
+```vue
+<script setup>
+import { VPCopyButton, VPLoading, VPTabSwitch } from 'vitepress-plugin-toolkit/client'
+</script>
+
+<template>
+  <VPCopyButton text="点击复制此文本" />
+  <VPLoading :size="40" />
+  <VPTabSwitch :tabs="['代码', '预览']" />
+</template>
+```
+
+### Composables
+
+#### `useSize(el, options, extraHeight?)`
+
+基于宽度、高度和宽高比选项的响应式尺寸计算。自动监听窗口 resize 和 orientationchange 事件。
+
+```ts
+import { useSize } from 'vitepress-plugin-toolkit/client'
+
+const el = ref<HTMLElement>()
+const { width, height, resize } = useSize(
+  el,
+  toRefs({ width: '100%', ratio: '16:9' }),
+)
+```
+
+#### `useZoomAndDrag(parentEl)`
+
+为内容舞台提供缩放和拖拽交互功能，支持鼠标拖拽、触摸拖拽和双指缩放。
+
+```ts
+import { useZoomAndDrag } from 'vitepress-plugin-toolkit/client'
+
+const stageEl = ref<HTMLDivElement>()
+const { actorStyle, zoom, zoomIn, zoomOut, resetZoom, reset } = useZoomAndDrag(stageEl)
+```
+
+### 环境检测
+
+```ts
+import {
+  isiPhone,    // 是否 iPhone
+  isiPad,      // 是否 iPad
+  isIOS,       // 是否 iOS
+  isWindows,   // 是否 Windows
+  isMacOS,     // 是否 macOS
+  isSafari,    // 是否 Safari 浏览器
+  isMobile,    // 是否移动设备
+} from 'vitepress-plugin-toolkit/client'
+```
+
+### CSS 过渡动效
+
+通过 `vitepress-plugin-toolkit/styles/*` 导入预置的 CSS 过渡动效类：
+
+```
+vitepress-plugin-toolkit/styles/transition/fade-in.css
+vitepress-plugin-toolkit/styles/transition/fade-in-up.css
+vitepress-plugin-toolkit/styles/transition/fade-in-down.css
+vitepress-plugin-toolkit/styles/transition/fade-in-left.css
+vitepress-plugin-toolkit/styles/transition/fade-in-right.css
+vitepress-plugin-toolkit/styles/transition/fade-in-scale-up.css
+vitepress-plugin-toolkit/styles/transition/fade-in-width-expand.css
+vitepress-plugin-toolkit/styles/transition/fade-in-height-expand.css
+vitepress-plugin-toolkit/styles/transition/slide-in-up.css
+vitepress-plugin-toolkit/styles/transition/slide-in-down.css
+vitepress-plugin-toolkit/styles/transition/slide-in-left.css
+vitepress-plugin-toolkit/styles/transition/slide-in-right.css
+```
+
+```ts
+import 'vitepress-plugin-toolkit/styles/transition/fade-in-up.css'
+```
+
+## Shared（共享）
+
+以下工具同时在 Node 端和 Client 端可用。
+
+### `isExternal(path)` / `isLinkWithProtocol(link)`
+
+判断是否为外部链接。
+
+```ts
+import { isExternal, isLinkWithProtocol } from 'vitepress-plugin-toolkit'
+
+isExternal('https://example.com') // true
+isExternal('/about')              // false
+isLinkWithProtocol('//cdn.example.com/lib.js') // true
+```
+
+### `EXTERNAL_URL_RE` / `URL_PROTOCOL_RE`
+
+匹配外部 URL 和协议的正则表达式。
+
+### `SizeOptions`
+
+尺寸配置的 TypeScript 接口：
+
+```ts
+interface SizeOptions {
+  width?: string          // 宽度 CSS 值，如 '100%'、'640px'
+  height?: string         // 高度 CSS 值，如 'auto'、'360px'
+  ratio?: number | string // 宽高比，如 16/9 或 '16:9'
+}
+```
+
+## 许可
+
+MIT

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

@@ -1,39 +1,130 @@
 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;
 };
@@ -41,23 +132,44 @@ declare const __VLS_export$2: import("vue").DefineComponent<__VLS_Props$1, {}, {
 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$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>[];
   } & {
-    modelValue?: T;
+    /** Current active tab value (v-model) / 当前活动标签的值（v-model） */modelValue?: T;
   }) & {
     onUpdate?: ((tab: T) => any) | undefined;
     "onUpdate:modelValue"?: ((value: T | undefined) => any) | undefined;
@@ -75,14 +187,59 @@ 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;
@@ -98,8 +255,15 @@ declare function useZoomAndDrag(parentEl: TemplateRef<HTMLDivElement>): {
 };
 //#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 {