feat(plugin-docsearch): add docsearch plugin

Author: meteorlxy

.vscode/settings.json

@@ -18,6 +18,7 @@
   "vetur.validation.template": false,
   "cSpell.words": [
     "devtool",
+    "docsearch",
     "frontmatter",
     "globby",
     "nprogress",

README.md

@@ -61,13 +61,13 @@ Features in the following list are not fully determined, and might be changed or
   - [x] @vuepress/plugin-active-header-links
   - [x] @vuepress/plugin-back-to-top
   - [x] @vuepress/plugin-container
+  - [x] @vuepress/plugin-docsearch
   - [x] @vuepress/plugin-git
   - [x] @vuepress/plugin-google-analytics
   - [x] @vuepress/plugin-medium-zoom
   - [x] @vuepress/plugin-nprogress
   - [x] @vuepress/plugin-palette-stylus
   - [ ] @vuepress/plugin-pwa
-  - [ ] @vuepress/plugin-search-algolia
 
 - [ ] Documentation
   - [ ] Guide

packages/@vuepress/plugin-docsearch/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@vuepress/plugin-docsearch",
+  "version": "2.0.0-alpha.0",
+  "description": "VuePress plugin - docsearch",
+  "keywords": [
+    "vuepress",
+    "plugin",
+    "docsearch",
+    "search",
+    "algolia"
+  ],
+  "homepage": "https://github.com/vuepress",
+  "bugs": {
+    "url": "https://github.com/vuepress/vuepress-next/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuepress/vuepress-next.git"
+  },
+  "license": "MIT",
+  "author": "meteorlxy",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf lib *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@docsearch/css": "3.0.0-alpha.31",
+    "@docsearch/js": "3.0.0-alpha.31",
+    "@types/react": "^17.0.0",
+    "@vuepress/client": "2.0.0-alpha.0",
+    "@vuepress/core": "2.0.0-alpha.0",
+    "@vuepress/shared": "2.0.0-alpha.0",
+    "@vuepress/utils": "2.0.0-alpha.0",
+    "preact": "^10.0.0",
+    "vue": "^3.0.0",
+    "vue-router": "4.0.0-rc.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/@vuepress/plugin-docsearch/src/clientAppEnhance.ts

@@ -0,0 +1,38 @@
+import { computed, h } from 'vue'
+import { useRouteLocale } from '@vuepress/client'
+import type { ClientAppEnhance } from '@vuepress/client'
+import type { LocaleConfig } from '@vuepress/shared'
+import { Docsearch } from './components/Docsearch'
+import type { DocsearchProps } from './components/Docsearch'
+
+declare const DOCSEARCH_PROPS: DocsearchProps
+declare const DOCSEARCH_LOCALES: LocaleConfig<Pick<
+  DocsearchProps,
+  'placeholder'
+>>
+
+const props = DOCSEARCH_PROPS
+const locales = DOCSEARCH_LOCALES
+
+const clientAppEnhance: ClientAppEnhance = ({ app }) => {
+  // wrap the `<Docsearch />` component with plugin options
+  // eslint-disable-next-line vue/match-component-file-name
+  app.component('Docsearch', {
+    setup() {
+      const routeLocale = useRouteLocale()
+
+      const locale = computed(() => locales[routeLocale.value])
+
+      return () =>
+        h(Docsearch, {
+          options: {
+            ...props,
+            ...locale.value,
+            // TODO: add language filter to support multiple locales
+          },
+        })
+    },
+  })
+}
+
+export default clientAppEnhance

packages/@vuepress/plugin-docsearch/src/components/Docsearch.ts

@@ -0,0 +1,124 @@
+import { createElement } from 'preact'
+import { defineComponent, getCurrentInstance, h, onMounted, watch } from 'vue'
+import type { PropType } from 'vue'
+import { useRouter } from 'vue-router'
+import type { DocSearchProps } from '@docsearch/react'
+import { useSiteData } from '@vuepress/client'
+import { resolveRoutePathFromUrl } from '@vuepress/shared'
+
+import '@docsearch/css'
+
+export type DocsearchProps = DocSearchProps
+
+type DocsearchFuncProps = DocSearchProps & {
+  container: string
+}
+
+type DocsearchFunc = (props: DocsearchFuncProps) => void
+
+const loadDocsearch = async (): Promise<DocsearchFunc> => {
+  // @ts-ignore: docsearch types issue
+  const docsearch = await import('@docsearch/js')
+  return docsearch.default
+}
+
+const isSpecialClick = (event: MouseEvent): boolean => {
+  return (
+    event.button === 1 ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.metaKey ||
+    event.shiftKey
+  )
+}
+
+export const Docsearch = defineComponent({
+  name: 'Docsearch',
+
+  props: {
+    options: {
+      type: Object as PropType<DocsearchProps>,
+      required: true,
+    },
+  },
+
+  setup(props) {
+    const router = useRouter()
+    const site = useSiteData()
+    const vm = getCurrentInstance()
+
+    const initialize = (options: DocsearchProps): void => {
+      loadDocsearch().then((docsearch) => {
+        docsearch({
+          ...options,
+
+          // the container selector
+          container: '#docsearch',
+
+          // navigation behavior triggered by `onKeyDown` internally
+          // @ts-ignore: docsearch types issue
+          navigator: {
+            // when pressing Enter without metaKey
+            navigate: ({ itemUrl }) => {
+              router.push(itemUrl)
+            },
+          },
+
+          // transform full url to route path
+          transformItems: (items) =>
+            items.map((item) => {
+              // the `item.url` is full url with protocol and hostname
+              // so we have to transform it to vue-router path
+              return {
+                ...item,
+                url: resolveRoutePathFromUrl(item.url, site.value.base),
+              }
+            }),
+
+          // handle `onClick` by `router.push`
+          hitComponent: ({ hit, children }) =>
+            createElement(
+              'a',
+              {
+                href: hit.url,
+                onClick: (event: MouseEvent) => {
+                  if (isSpecialClick(event)) {
+                    return
+                  }
+                  event.preventDefault()
+                  router.push(hit.url)
+                },
+              },
+              children
+            ),
+        })
+      })
+    }
+
+    const update = (options: DocsearchProps): void => {
+      if (vm && vm.vnode.el) {
+        vm.vnode.el.innerHTML = '<div id="docsearch"></div>'
+        initialize(options)
+      }
+    }
+
+    watch(
+      () => props.options,
+      (val, prevVal) => {
+        // check if the options are modified
+        const keys = Object.keys(val)
+        const prevKeys = Object.keys(prevVal)
+        if (
+          keys.length !== prevKeys.length ||
+          keys.some((key) => val[key] !== prevVal[key])
+        ) {
+          update(val)
+        }
+      }
+    )
+
+    onMounted(() => initialize(props.options))
+
+    return () => h('div', { id: 'docsearch' })
+  },
+})

packages/@vuepress/plugin-docsearch/src/index.ts

@@ -0,0 +1,47 @@
+import { resolve } from 'path'
+import type { DocSearchProps } from '@docsearch/react'
+import type { Plugin, PluginObject } from '@vuepress/core'
+import type { LocaleConfig } from '@vuepress/shared'
+import { logger } from '@vuepress/utils'
+
+export interface DocsearchPluginOptions
+  extends Pick<
+    DocSearchProps,
+    | 'appId'
+    | 'apiKey'
+    | 'indexName'
+    | 'searchParameters'
+    | 'disableUserPersonalization'
+    | 'initialQuery'
+  > {
+  locales?: LocaleConfig<Pick<DocSearchProps, 'placeholder'>>
+}
+
+export const docsearchPlugin: Plugin<DocsearchPluginOptions> = ({
+  locales,
+  ...props
+}) => {
+  const plugin: PluginObject = {
+    name: '@vuepress/plugin-docsearch',
+  }
+
+  // if the required options are not set
+  // print warning and return a noop plugin
+  if (!props.apiKey || !props.indexName) {
+    logger.warn(`[${plugin.name}] 'apiKey' and 'indexName' are required`)
+    return plugin
+  }
+
+  return {
+    ...plugin,
+
+    clientAppEnhanceFiles: resolve(__dirname, './clientAppEnhance.js'),
+
+    define: {
+      DOCSEARCH_PROPS: props,
+      DOCSEARCH_LOCALES: locales,
+    },
+  }
+}
+
+export default docsearchPlugin

packages/@vuepress/plugin-docsearch/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "references": [
+    { "path": "../client/tsconfig.build.json" },
+    { "path": "../core/tsconfig.build.json" },
+    { "path": "../shared/tsconfig.build.json" },
+    { "path": "../utils/tsconfig.build.json" },
+    { "path": "./tsconfig.esm.json" },
+    { "path": "./tsconfig.cjs.json" }
+  ],
+  "files": []
+}

packages/@vuepress/plugin-docsearch/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "rootDir": "./src",
+    "outDir": "./lib"
+  },
+  "include": ["./src/index.ts"]
+}

packages/@vuepress/plugin-docsearch/tsconfig.esm.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "rootDir": "./src",
+    "outDir": "./lib"
+  },
+  "include": ["./src"],
+  "exclude": ["./src/index.ts"]
+}

packages/@vuepress/plugin-docsearch/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["./src", "./__tests__"]
+}