feat(plugin-photo-swipe): add photo-swipe plugin (#69)

.vscode/settings.json

@@ -32,6 +32,7 @@
     "mdit",
     "nord",
     "nprogress",
+    "photoswipe",
     "prefetch",
     "preload",
     "prismjs",

docs/.vuepress/configs/navbar/en.ts

@@ -29,6 +29,7 @@ export const navbarEn: NavbarConfig = [
           '/plugins/google-analytics',
           '/plugins/medium-zoom',
           '/plugins/nprogress',
+          '/plugins/photo-swipe',
           '/plugins/redirect',
           '/plugins/register-components',
         ],

docs/.vuepress/configs/navbar/zh.ts

@@ -29,6 +29,7 @@ export const navbarZh: NavbarConfig = [
           '/zh/plugins/google-analytics',
           '/zh/plugins/medium-zoom',
           '/zh/plugins/nprogress',
+          '/zh/plugins/photo-swipe',
           '/zh/plugins/redirect',
           '/zh/plugins/register-components',
         ],

docs/.vuepress/configs/sidebar/en.ts

@@ -14,6 +14,7 @@ export const sidebarEn: SidebarConfig = {
         '/plugins/google-analytics',
         '/plugins/medium-zoom',
         '/plugins/nprogress',
+        '/plugins/photo-swipe',
         '/plugins/redirect',
         '/plugins/register-components',
       ],

docs/.vuepress/configs/sidebar/zh.ts

@@ -14,6 +14,7 @@ export const sidebarZh: SidebarConfig = {
         '/zh/plugins/google-analytics',
         '/zh/plugins/medium-zoom',
         '/zh/plugins/nprogress',
+        '/zh/plugins/photo-swipe',
         '/zh/plugins/redirect',
         '/zh/plugins/register-components',
       ],

docs/package.json

@@ -19,6 +19,7 @@
     "@vuepress/plugin-google-analytics": "workspace:*",
     "@vuepress/plugin-medium-zoom": "workspace:*",
     "@vuepress/plugin-nprogress": "workspace:*",
+    "@vuepress/plugin-photo-swipe": "workspace:*",
     "@vuepress/plugin-pwa-popup": "workspace:*",
     "@vuepress/plugin-redirect": "workspace:*",
     "@vuepress/plugin-register-components": "workspace:*",

docs/plugins/photo-swipe.md

@@ -0,0 +1,271 @@
+# photo-swipe
+
+<NpmBadge package="@vuepress/plugin-photo-swipe" />
+
+This plugin will make the pictures in the body of the page enter the preview mode when clicked.
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-photo-swipe@next
+```
+
+```ts
+import { photoSwipePlugin } from '@vuepress/plugin-photo-swipe'
+
+export default {
+  plugins: [
+    photoSwipePlugin({
+      // options
+    }),
+  ],
+}
+```
+
+In preview mode, you can:
+
+- Swipe left and right to preview other pictures on the page in order
+- View the description of the picture
+- Zoom in and zoom out the picture
+- View pictures in full screen
+- Download pictures
+- Share pictures
+
+::: tip
+
+- Besides clicking "×" in the upper right corner to exit the preview mode, scrolling up and down more than a certain distance will also exit preview mode.
+- On mobile devices, or using the PC trackpad, you can use pan and zoom gestures to pan and zoom in the preview mode.
+
+:::
+
+## Config
+
+### selector
+
+- Type: `string | string[]`
+- Default: `".theme-default-content :not(a) > img:not([no-view])"`
+- Details: Image selector
+
+### scrollToClose
+
+- Type: `boolean`
+- Default: `true`
+- Details: Whether close the current image when scrolling.
+
+### delay
+
+- Type: `number`
+- Default: `800`
+- Details:
+
+  The delay of operating dom, in ms.
+
+  ::: tip
+
+  If the theme you are using has a switching animation, it is recommended to configure this option to `Switch animation duration + 200`.
+
+  :::
+
+### locales
+
+- Type: `PhotoSwipeLocaleConfig`
+
+  ```ts
+  interface PhotoSwipeLocaleData {
+    /**
+     * Close button label text
+     */
+    close: string
+
+    /**
+     * Full screen button label text
+     */
+    fullscreen: string
+
+    /**
+     * Share button label text
+     */
+    share: string
+
+    /**
+     * Zoom button label text
+     */
+    zoom: string
+
+    /**
+     * Previous image button label text
+     */
+    prev: string
+
+    /**
+     * Next image button label text
+     */
+    next: string
+
+    /**
+     * Share button config
+     */
+    buttons: PhotoSwipeDefaultUI.ShareButtonData[]
+  }
+
+  interface PhotoSwipeLocaleConfig {
+    [localePath: string]: PhotoSwipeLocaleData
+  }
+  ```
+
+- Details: Locales config for photo-swipe plugin.
+
+- Example:
+
+  ```ts
+  import { defineUserConfig } from 'vuepress'
+  import { photoSwipePlugin } from '@vuepress/plugin-photo-swipe'
+
+  export default defineUserConfig({
+    locales: {
+      '/': {
+        // this is a supported language
+        lang: 'en-US',
+      },
+      '/xx/': {
+        // the plugin does not support this language
+        lang: 'mm-NN',
+      },
+    },
+
+    plugins: [
+      photoSwipePlugin({
+        locales: {
+          '/': {
+            // Override share label text
+            share: 'Share with friends',
+          },
+
+          '/xx/': {
+            // Complete locale config for `mm-NN` language here
+          },
+        },
+      }),
+    ],
+  })
+  ```
+
+::: details Built-in Supported Languages
+
+- **Simplified Chinese** (zh-CN)
+- **Traditional Chinese** (zh-TW)
+- **English (United States)** (en-US)
+- **German** (de-DE)
+- **German (Australia)** (de-AT)
+- **Russian** (ru-RU)
+- **Ukrainian** (uk-UA)
+- **Vietnamese** (vi-VN)
+- **Portuguese (Brazil)** (pt-BR)
+- **Polish** (pl-PL)
+- **French** (fr-FR)
+- **Spanish** (es-ES)
+- **Slovak** (sk-SK)
+- **Japanese** (ja-JP)
+- **Turkish** (tr-TR)
+- **Korean** (ko-KR)
+- **Finnish** (fi-FI)
+- **Indonesian** (id-ID)
+- **Dutch** (nl-NL)
+
+:::
+
+## Frontmatter
+
+- Type: `string | false`
+- Details:
+
+Image selector for the current page, or `false` to disable photo-swipe in current page.
+
+## Client Config
+
+### definePhotoSwipeConfig
+
+Options passed to [`photo-swipe`](http://photoswipe.com/)
+
+```ts title=".vuepress/client.ts"
+import { definePhotoSwipeConfig } from '@vuepress/plugin-photo-swipe/client'
+
+definePhotoSwipeConfig({
+  // set photoswipe options here
+})
+
+export default {}
+```
+
+## API
+
+You can also call photoswipe with apis.
+
+`createPhotoSwipe` allows you to programmatically view images links with PhotoSwipe:
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createPhotoSwipe } from "@vuepress/plugin-photo-swipe/client";
+
+let state: PhotoSwipeState | null = null;
+
+const openPhotoSwipe = (index: number) => {
+  state?.open(index - 1);
+};
+
+onMounted(async () => {
+  // create a new photoswipe instance with image links
+  state=  await createPhotoSwipe(
+    [
+      'https://exmaple.com/image1.png'
+      'https://exmaple.com/image2.png'
+      'https://exmaple.com/image3.png'
+    ],
+    {
+      // photoswipe options
+    }
+  );
+});
+
+onUnmounted(() => {
+  state?.destroy()
+})
+</script>
+
+<template>
+  <button v-for="i in 3" @click="openPhotoSwipe(i)">open photo {{ i }}</button>
+</template>
+```
+
+`registerPhotoSwipe` allows you to register photoswipe for the given image elements:
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue'
+import { registerPhotoSwipe } from '@vuepress/plugin-photo-swipe/client'
+
+let destroy: () => void | null = null
+
+onMounted(async () => {
+  await nextTick()
+
+  const images = Array.from(document.querySelectorAll('img'))
+
+  // create a new photoswipe instance on image elements
+  state = await registerPhotoSwipe(images, {
+    // photoswipe options
+  })
+})
+
+onUnmounted(() => {
+  destroy?.()
+})
+</script>
+```
+
+## Styles
+
+You can customize the style via CSS variables:
+
+@[code css](@vuepress/plugin-photo-swipe/src/client/styles/vars.css)