@vuepress-plume/plugin-search 1.0.0-rc.210 → 1.0.0-rc.212

package/dist/client/components/SearchBox.vue

@@ -25,6 +25,7 @@ import {
   watch,
 } from 'vue'
 import { usePageLang, useRouteLocale, useRouter, withBase } from 'vuepress/client'
+import { createTokenizer } from '../../shared/index.js'
 import { useLocale, useSearchIndex } from '../composables/index.js'
 import { LRUCache } from '../utils/index.js'
 import BackIcon from './icons/BackIcon.vue'
@@ -62,17 +63,61 @@ const isSearching = ref(false)
 
 const showSearchSpinner = computed(() => isSearchIndexLoading.value || isSearching.value)
 
-const searchIndex = computedAsync(async () => {
-  let tokenize: ((str: string) => string[]) | undefined
-  if (typeof Intl.Segmenter !== 'undefined') {
-    const segmenter = new Intl.Segmenter(lang.value, { granularity: 'word' })
-    tokenize = str => Array.from(segmenter.segment(str)).map(s => s.segment)
+/**
+ * Visible error message when the search index is missing or fails to load.
+ *
+ * 搜索索引缺失或加载失败时显示的可见提示。
+ */
+const searchIndexError = ref('')
+
+const searchIndexErrorText = computed(() =>
+  locale.value.searchIndexErrorText || 'Failed to load the search index.',
+)
+
+/**
+ * Create an empty index used as a fallback when the index is missing or fails
+ * to load, so searching returns an empty result set instead of throwing.
+ *
+ * 创建空索引，在索引缺失或加载失败时兜底，使检索返回空结果而不是抛出异常。
+ */
+function createEmptyIndex(): MiniSearch<Result> {
+  return new MiniSearch<Result>({
+    fields: ['title', 'titles', 'text'],
+    storeFields: ['title', 'titles'],
+  })
+}
+
+const searchIndex = computedAsync(async (onCancel) => {
+  // 标记本次求值是否已被新一轮加载取代（例如 HMR 更新索引）。
+  // 过期任务不得再写入错误状态，否则有效结果旁会残留加载失败提示。
+  //
+  // Mark this evaluation as stale (e.g. superseded by a newer load during HMR).
+  // A stale task must not write the error state, otherwise a load failure message
+  // would persist next to valid results.
+  let canceled = false
+  onCancel(() => {
+    canceled = true
+  })
+
+  searchIndexError.value = ''
+
+  // 使用与 Node 端建索引时完全一致的分词策略，避免两端词元不匹配导致检索失效。
+  // Use the same tokenizer as the node build side so query tokens always match the index.
+  const tokenize = createTokenizer(lang.value)
+
+  const loadIndex = searchIndexData.value[routeLocale.value]
+  // 当前语言缺少索引文件时回退到空索引，并给出可见提示，避免静默无结果。
+  // Fall back to an empty index and show a visible message when the locale has no index.
+  if (!loadIndex) {
+    if (!canceled)
+      searchIndexError.value = searchIndexErrorText.value
+    return markRaw(createEmptyIndex())
   }
 
-  return markRaw(
-    MiniSearch.loadJSON<Result>(
-      (await searchIndexData.value[routeLocale.value]?.())?.default,
-      {
+  try {
+    const json = (await loadIndex())?.default
+    return markRaw(
+      MiniSearch.loadJSON<Result>(json, {
         fields: ['title', 'titles', 'text'],
         storeFields: ['title', 'titles'],
         searchOptions: {
@@ -83,9 +128,15 @@ const searchIndex = computedAsync(async () => {
         },
         ...options.miniSearch?.searchOptions,
         ...options.miniSearch?.options,
-      },
-    ),
-  )
+      }),
+    )
+  }
+  catch (error) {
+    console.error('[plugin-search] failed to load the search index:', error)
+    if (!canceled)
+      searchIndexError.value = searchIndexErrorText.value
+    return markRaw(createEmptyIndex())
+  }
 }, undefined, isSearchIndexLoading)
 
 const disableQueryPersistence = computed(() =>
@@ -447,7 +498,14 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
             </a>
           </li>
           <li
-            v-if="filterText && !results.length && enableNoResults"
+            v-if="searchIndexError"
+            class="no-results error"
+            role="alert"
+          >
+            {{ searchIndexError }}
+          </li>
+          <li
+            v-else-if="filterText && !results.length && enableNoResults"
             class="no-results"
           >
             {{ locale.noResultsText }} "<strong>{{ filterText }}</strong>"
@@ -815,4 +873,8 @@ svg {
   font-size: 0.9rem;
   text-align: center;
 }
+
+.no-results.error {
+  color: var(--vp-c-danger-1, #b8272c);
+}
 </style>

package/dist/client/composables/index.js

@@ -8,6 +8,7 @@ const defaultLocales = {
     resetButtonTitle: 'Reset search',
     backButtonTitle: 'Close search',
     noResultsText: 'No results for',
+    searchIndexErrorText: 'Failed to load the search index.',
     footer: {
       selectText: 'to select',
       selectKeyAriaLabel: 'enter',

package/dist/node/index.js

@@ -1,3 +1,4 @@
+import {createTokenizer} from '../shared/index.js'
 import MiniSearch from 'minisearch'
 import pMap from 'p-map'
 import sanitizeHTML from 'sanitize-html'
@@ -14,13 +15,10 @@ const indexCache = new Map()
 function getIndexByLocale(locale, lang, options) {
   let index = indexByLocales.get(locale)
   if (!index) {
-    const segmenter = new Intl.Segmenter(lang, {granularity: 'word'})
     index = new MiniSearch({
       fields: ['title', 'titles', 'text'],
       storeFields: ['title', 'titles'],
-      tokenize(text) {
-        return Array.from(segmenter.segment(text)).map((s) => s.segment)
-      },
+      tokenize: createTokenizer(lang),
       ...options.miniSearch?.options,
     })
     indexByLocales.set(locale, index)
@@ -56,7 +54,46 @@ async function prepareSearchIndex({app, isSearchable, searchOptions}) {
       `\n[${colors.green('@vuepress-plume/plugin-search')}] prepare search time spent: ${(performance.now() - start).toFixed(2)}ms`,
     )
 }
-Promise.resolve()
+
+let indexTaskQueue = Promise.resolve()
+function runExclusive(task) {
+  const result = indexTaskQueue.then(task)
+  indexTaskQueue = result.then(
+    () => {},
+    () => {},
+  )
+  return result
+}
+
+function prepareSearchIndexInBackground(options) {
+  runExclusive(() => prepareSearchIndex(options)).catch((error) => {
+    logger.error(
+      `${colors.green('[@vuepress-plume/plugin-search]')} failed to prepare search index:`,
+      error,
+    )
+  })
+}
+
+async function onSearchIndexUpdated(app, {page, isSearchable, searchOptions}) {
+  if (isSearchable && !isSearchable(page)) return
+  await runExclusive(async () => {
+    await indexFile(page, searchOptions, isSearchable)
+    await writeTemp(app)
+  })
+}
+
+async function onSearchIndexRemoved(app, {page, isSearchable, searchOptions}) {
+  if (isSearchable && !isSearchable(page)) return
+  const cacheKey = page.filePathRelative
+  if (!cacheKey) return
+  await runExclusive(async () => {
+    const index = getIndexByLocale(page.pathLocale, page.lang, searchOptions)
+    const cache = indexCache.get(cacheKey)
+    if (cache?.length) index.removeAll(cache)
+    indexCache.delete(cacheKey)
+    await writeTemp(app)
+  })
+}
 
 async function writeTemp(app) {
   const records = []
@@ -85,39 +122,40 @@ async function indexFile(page, options, isSearchable) {
   if (!page.filePath || page.frontmatter?.search === false) return
   if (isSearchable && !isSearchable(page)) return
   const fileId = page.path
-  const locale = page.pathLocale
-  const lang = page.lang
-  const index = getIndexByLocale(locale, lang, options)
-  const cache = getIndexCache(fileId)
-  const sections =
-    splitPageIntoSections(`<h1><a href="#"><span>${page.frontmatter.title || page.title}</span></a></h1>
-${page.contentRendered}`)
+  const index = getIndexByLocale(page.pathLocale, page.lang, options)
+  const cache = getIndexCache(page.filePathRelative ?? fileId)
   try {
-    if (cache && cache.length) index.removeAll(cache)
+    if (cache.length) index.removeAll(cache)
   } catch {}
-  for await (const section of sections) {
-    if (!section || !(section.text || section.titles)) break
-    const {anchor, text, titles} = section
-    const id = anchor ? [fileId, anchor].join('#') : fileId
-    if (index.has(id)) {
-      if (anchor)
+  cache.length = 0
+  for (const item of createPageSectionItems(page))
+    if (index.has(item.id)) {
+      if (item.id !== fileId)
         logger.error(
-          `${colors.green('[@vuepress-plume/plugin-search]')} duplicate heading anchor : ${colors.cyan(titles.join(' >> '))} \n at ${colors.cyan(fileId)}`,
+          `${colors.green('[@vuepress-plume/plugin-search]')} duplicate heading anchor : ${colors.cyan([...item.titles, item.title].join(' >> '))} \n at ${colors.cyan(fileId)}`,
         )
       else
         logger.error(
           `${colors.green('[@vuepress-plume/plugin-search]')} duplicate page permalink : ${colors.cyan(fileId)}`,
         )
     } else {
-      const item = {
-        id,
-        text,
-        title: titles.at(-1),
-        titles: titles.slice(0, -1),
-      }
       index.add(item)
       cache.push(item)
     }
+}
+
+function* createPageSectionItems(page) {
+  const html = `<h1><a href="#"><span>${page.frontmatter.title || page.title || page.filePathRelative || ''}</span></a></h1>\n${page.contentRendered}`
+  const fileId = page.path
+  for (const section of splitPageIntoSections(html)) {
+    const {anchor, text, titles} = section
+    if (!text && !titles.length) continue
+    yield {
+      id: anchor ? `${fileId}#${anchor}` : fileId,
+      text,
+      title: titles.at(-1),
+      titles: titles.slice(0, -1),
+    }
   }
 }
 
@@ -191,6 +229,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Reset search',
       backButtonTitle: 'Close search',
       noResultsText: 'No results for',
+      searchIndexErrorText: 'Failed to load the search index.',
       footer: {
         selectText: 'to select',
         selectKeyAriaLabel: 'enter',
@@ -209,6 +248,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: '重置搜索',
       backButtonTitle: '关闭',
       noResultsText: '无搜索结果：',
+      searchIndexErrorText: '搜索索引加载失败。',
       footer: {
         selectText: '选择',
         selectKeyAriaLabel: '输入',
@@ -227,6 +267,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: '重設搜尋',
       backButtonTitle: '關閉',
       noResultsText: '無搜尋結果：',
+      searchIndexErrorText: '搜尋索引載入失敗。',
       footer: {
         selectText: '選擇',
         selectKeyAriaLabel: '輸入',
@@ -245,6 +286,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Suche zurücksetzen',
       backButtonTitle: 'Schließen',
       noResultsText: 'Keine Suchergebnisse:',
+      searchIndexErrorText: 'Der Suchindex konnte nicht geladen werden.',
       footer: {
         selectText: 'Auswählen',
         selectKeyAriaLabel: 'Eingabe',
@@ -263,6 +305,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Réinitialiser la recherche',
       backButtonTitle: 'Fermer',
       noResultsText: 'Aucun résultat trouvé :',
+      searchIndexErrorText: 'Échec du chargement de l’index de recherche.',
       footer: {
         selectText: 'sélectionner',
         selectKeyAriaLabel: 'Entrée',
@@ -281,6 +324,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Сбросить поиск',
       backButtonTitle: 'Закрыть',
       noResultsText: 'Нет результатов поиска:',
+      searchIndexErrorText: 'Не удалось загрузить поисковый индекс.',
       footer: {
         selectText: 'Выбрать',
         selectKeyAriaLabel: 'Ввод',
@@ -299,6 +343,7 @@ const SEARCH_LOCALES = [
       resetButtonTitle: '検索をリセット',
       backButtonTitle: '閉じる',
       noResultsText: '検索結果がありません：',
+      searchIndexErrorText: '検索インデックスの読み込みに失敗しました。',
       footer: {
         selectText: '選択',
         selectKeyAriaLabel: '入力',
@@ -343,13 +388,39 @@ function searchPlugin({locales = {}, isSearchable, ...searchOptions} = {}) {
         })
       else {
         await prepareSearchIndexPlaceholder(app)
-        prepareSearchIndex({
+        prepareSearchIndexInBackground({
           app,
           isSearchable,
           searchOptions,
         })
       }
     },
+    onPageUpdated: async (app, type, pageNew, pageOld) => {
+      if (type === 'delete') {
+        if (pageOld?.filePathRelative)
+          await onSearchIndexRemoved(app, {
+            page: pageOld,
+            isSearchable,
+            searchOptions,
+          })
+        return
+      }
+      const becameUnsearchable = !!isSearchable && !!pageNew && !isSearchable(pageNew)
+      const page = becameUnsearchable ? pageOld : pageNew
+      if (!page?.filePathRelative) return
+      if (becameUnsearchable)
+        await onSearchIndexRemoved(app, {
+          page,
+          isSearchable,
+          searchOptions,
+        })
+      else
+        await onSearchIndexUpdated(app, {
+          page,
+          isSearchable,
+          searchOptions,
+        })
+    },
   })
 }
 

package/dist/shared/index.d.ts

@@ -16,6 +16,12 @@ export interface SearchLocaleOptions {
   backButtonTitle: string
   /** Text shown when no results found / 无搜索结果时显示的文本 */
   noResultsText: string
+  /**
+   * Text shown when the search index is missing or fails to load.
+   *
+   * 搜索索引缺失或加载失败时显示的文本。
+   */
+  searchIndexErrorText?: string
   /** Footer keyboard shortcut hints / 底部键盘快捷键提示 */
   footer: {
     /** Text for select action / 选择操作的文本 */
@@ -40,6 +46,26 @@ export interface SearchLocaleOptions {
  * 搜索框的语言配置类型。
  */
 export type SearchBoxLocales = LocaleConfig<SearchLocaleOptions>
+/**
+ * Create a tokenizer shared by the node (index build) and client (query) sides.
+ *
+ * 创建由 Node 端（构建索引）与客户端（查询）共享的分词器。
+ *
+ * MiniSearch requires the tokenizer used to build the index to be identical to
+ * the one used at query time. Defining it in one place guarantees both sides
+ * use the same strategy: `Intl.Segmenter` when available, otherwise the same
+ * deterministic whitespace fallback.
+ *
+ * MiniSearch 要求构建索引与查询时使用完全一致的分词器。集中定义可保证两端策略一致：
+ * 支持 `Intl.Segmenter` 时使用它分词，否则统一退化为确定性的空白符分词。
+ *
+ * @param lang - Language code for word segmentation / 用于分词的语言代码
+ * @returns Tokenizer that splits a string into tokens / 将字符串切分为词元的函数
+ * @example
+ * const tokenize = createTokenizer('en')
+ * tokenize('Hello world') // ['Hello', ' ', 'world'] with Intl.Segmenter
+ */
+export declare function createTokenizer(lang: string): (text: string) => string[]
 /**
  * Options for the search plugin.
  *

package/dist/shared/index.js

@@ -1 +1,9 @@
-export {}
+function createTokenizer(lang) {
+  if (typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function') {
+    const segmenter = new Intl.Segmenter(lang, {granularity: 'word'})
+    return (text) => Array.from(segmenter.segment(text)).map((segment) => segment.segment)
+  }
+  return (text) => text.split(/\s+/).filter(Boolean)
+}
+
+export {createTokenizer}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vuepress-plume/plugin-search",
   "type": "module",
-  "version": "1.0.0-rc.210",
+  "version": "1.0.0-rc.212",
   "description": "The Plugin for VuePress 2 - local search",
   "author": "pengzhanbo <volodymyr@foxmail.com>",
   "license": "MIT",
@@ -34,16 +34,16 @@
     "vuepress": "2.0.0-rc.31"
   },
   "dependencies": {
-    "@vuepress/helper": "2.0.0-rc.134",
-    "@vueuse/core": "^14.4.0",
-    "@vueuse/integrations": "^14.4.0",
+    "@vuepress/helper": "2.0.0-rc.135",
+    "@vueuse/core": "^15.0.0",
+    "@vueuse/integrations": "^15.0.0",
     "chokidar": "5.0.0",
     "focus-trap": "^8.2.2",
     "mark.js": "^8.11.1",
     "minisearch": "^7.2.0",
-    "p-map": "^7.0.7",
+    "p-map": "^7.0.8",
     "sanitize-html": "^2.17.7",
-    "vue": "^3.5.42"
+    "vue": "^3.5.43"
   },
   "publishConfig": {
     "access": "public",