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

package/dist/client/components/Search.vue

@@ -2,12 +2,17 @@
 import type { SearchBoxLocales, SearchOptions } from '../../shared/index.js'
 import { onKeyStroke } from '@vueuse/core'
 import {
+  computed,
   defineAsyncComponent,
+  nextTick,
   ref,
+  toRef,
+  useTemplateRef,
 } from 'vue'
+import { useLocale } from '../composables/index.js'
 import SearchButton from './SearchButton.vue'
 
-defineProps<{
+const props = defineProps<{
   locales: SearchBoxLocales
   options: SearchOptions
 }>()
@@ -16,15 +21,72 @@ const SearchBox = defineAsyncComponent(() => import('./SearchBox.vue'))
 
 const showSearch = ref(false)
 
+const searchButtonRef = useTemplateRef<{ focus: () => void }>('searchButton')
+
+const locale = useLocale(toRef(() => props.locales))
+
+/**
+ * Hand focus back to the trigger button.
+ *
+ * 把焦点归还给触发按钮。
+ *
+ * The search box unmounts its own focus trap, so without this the focused input
+ * disappears and focus falls back to `<body>`, forcing keyboard users to tab
+ * through the whole page again.
+ *
+ * 搜索框卸载时会一并销毁自身的焦点陷阱：若不显式归还，被聚焦的输入框随组件
+ * 消失后焦点会落到 `<body>`，键盘用户只能从页面第一个元素重新 Tab 一遍。
+ */
+function restoreSearchFocus() {
+  // 等待卸载完成（焦点陷阱销毁）后再归还焦点，否则会被其收尾逻辑覆盖。
+  // Wait until the unmount finished (the focus trap is destroyed), otherwise the
+  // trap teardown would override the focus we just set.
+  nextTick(() => searchButtonRef.value?.focus())
+}
+
+function closeSearch(options?: { restoreFocus?: boolean }) {
+  showSearch.value = false
+
+  if (options?.restoreFocus === false) {
+    nextTick(() => {
+      const main = document.querySelector<HTMLElement>('main, [role="main"]')
+      if (!main) {
+        searchButtonRef.value?.focus()
+        return
+      }
+      if (!main.hasAttribute('tabindex'))
+        main.setAttribute('tabindex', '-1')
+      main.focus({ preventScroll: true })
+    })
+    return
+  }
+
+  restoreSearchFocus()
+}
+
+const noscriptText = computed(
+  () => locale.value.noscriptText || 'Search is unavailable without JavaScript.',
+)
+
 onKeyStroke('k', (event) => {
-  if (event.ctrlKey || event.metaKey) {
+  // 在输入框 / 可编辑区域内不劫持 Ctrl/Cmd + K（如 macOS 的删除至行尾）。
+  // Do not hijack Ctrl/Cmd + K while editing content (e.g. macOS delete-to-end-of-line).
+  if ((event.ctrlKey || event.metaKey) && !isEditingContent(event)) {
     event.preventDefault()
     showSearch.value = true
   }
 })
 
 onKeyStroke('/', (event) => {
-  if (!isEditingContent(event)) {
+  // 仅在无修饰键且不在编辑内容时劫持，避免与浏览器/系统组合键冲突。
+  // Only hijack without modifiers and outside editable content to avoid clashing
+  // with browser/system shortcuts.
+  if (
+    !event.ctrlKey
+    && !event.metaKey
+    && !event.altKey
+    && !isEditingContent(event)
+  ) {
     event.preventDefault()
     showSearch.value = true
   }
@@ -49,12 +111,14 @@ function isEditingContent(event: KeyboardEvent): boolean {
       v-if="showSearch"
       :locales="locales"
       :options="options"
-      @close="showSearch = false"
+      @close="closeSearch"
     />
 
     <div id="local-search">
-      <SearchButton :locales="locales" @click="showSearch = true" />
+      <SearchButton ref="searchButton" :locales="locales" :expanded="showSearch" @click="showSearch = true" />
     </div>
+
+    <noscript>{{ noscriptText }}</noscript>
   </div>
 </template>
 
@@ -64,6 +128,12 @@ function isEditingContent(event: KeyboardEvent): boolean {
   align-items: center;
 }
 
+.search-wrapper noscript {
+  font-size: 13px;
+  line-height: 1.4;
+  color: var(--vp-c-text-2);
+}
+
 @media (min-width: 768px) {
   .search-wrapper {
     flex-grow: 1;

package/dist/client/components/SearchBox.vue

@@ -22,12 +22,13 @@ import {
   ref,
   shallowRef,
   toRef,
+  useId,
   watch,
 } from 'vue'
+import { isNavigationFailure, NavigationFailureType } from 'vue-router'
 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 { loadSearchIndexJSON, useLocale } from '../composables/index.js'
 import BackIcon from './icons/BackIcon.vue'
 import ClearIcon from './icons/ClearIcon.vue'
 import SearchIcon from './icons/SearchIcon.vue'
@@ -38,7 +39,11 @@ const { locales, options } = defineProps<{
 }>()
 
 const emit = defineEmits<{
-  (e: 'close'): void
+  // `restoreFocus: false` 表示关闭是因为页面已切换到搜索结果，焦点不应归还给触发按钮。
+  //
+  // `restoreFocus: false` means the box is closing because the page really moved to
+  // the result, so focus must not go back to the trigger button.
+  (e: 'close', options?: { restoreFocus?: boolean }): void
 }>()
 
 const routeLocale = useRouteLocale()
@@ -48,15 +53,21 @@ const lang = usePageLang()
 const el = shallowRef<HTMLElement>()
 const resultsEl = shallowRef<HTMLElement>()
 
-const searchIndexData = useSearchIndex()
+const uid = useId()
+const labelId = `${uid}-label`
+const inputId = `${uid}-input`
+const listId = `${uid}-list`
+
+function optionId(index: number) {
+  return `${uid}-option-${index}`
+}
 
 interface Result {
   title: string
   titles: string[]
-  text?: string
 }
 
-const { activate } = useFocusTrap(el, { immediate: true })
+const { activate } = useFocusTrap(el, { immediate: true, returnFocusOnDeactivate: false })
 
 const isSearchIndexLoading = ref(false)
 const isSearching = ref(false)
@@ -105,19 +116,27 @@ const searchIndex = computedAsync(async (onCancel) => {
   // 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())
-  }
-
   try {
-    const json = (await loadIndex())?.default
+    // 分片索引在客户端按片合并并让出主线程，避免大索引长时间阻塞渲染。
+    // Sharded indexes are merged piece by piece on the client, yielding to the main
+    // thread, so a large index never blocks rendering for long.
+    const indexJson = await loadSearchIndexJSON(routeLocale.value)
+
+    // 当前语言缺少索引文件时回退到空索引，并给出可见提示，避免静默无结果。
+    // Fall back to an empty index and show a visible message when the locale has no index.
+    if (!indexJson) {
+      if (!canceled)
+        searchIndexError.value = searchIndexErrorText.value
+      return markRaw(createEmptyIndex())
+    }
+
+    // 使用公开的异步反序列化 API（`loadJSAsync` 为 `@ignore` 的内部 API），
+    // 它在批次之间让出主线程，避免大索引同步解析长时间阻塞。
+    // Use the public async deserialization API (`loadJSAsync` is an `@ignore`d
+    // internal API). It yields to the main thread between batches, so a large index
+    // never blocks rendering for long.
     return markRaw(
-      MiniSearch.loadJSON<Result>(json, {
+      await MiniSearch.loadJSONAsync<Result>(indexJson, {
         fields: ['title', 'titles', 'text'],
         storeFields: ['title', 'titles'],
         searchOptions: {
@@ -125,8 +144,8 @@ const searchIndex = computedAsync(async (onCancel) => {
           prefix: true,
           boost: { title: 4, text: 2, titles: 1 },
           tokenize,
+          ...options.miniSearch?.searchOptions,
         },
-        ...options.miniSearch?.searchOptions,
         ...options.miniSearch?.options,
       }),
     )
@@ -156,22 +175,25 @@ watch(filterText, () => {
   enableNoResults.value = false
 })
 
+const searchStatusText = computed(() => {
+  if (searchIndexError.value)
+    return searchIndexError.value
+  if (!filterText.value || !enableNoResults.value)
+    return ''
+  if (!results.value.length)
+    return `${locale.value.noResultsText || 'No results for'} "${filterText.value}"`
+  return `${results.value.length} results`
+})
+
 const mark = computedAsync(async () => {
   if (!resultsEl.value)
     return
   return markRaw(new Mark(resultsEl.value))
 }, null)
 
-const cache = new LRUCache<string, Map<string, string>>(64) // 64 files
-
 watchDebounced(
   () => [searchIndex.value, filterText.value] as const,
-  async ([index, filterTextValue], old, onCleanup) => {
-    if (old?.[0] !== index) {
-      // in case of hmr
-      cache.clear()
-    }
-
+  async ([index, filterTextValue], _old, onCleanup) => {
     let canceled = false
     onCleanup(() => {
       canceled = true
@@ -191,25 +213,19 @@ watchDebounced(
     enableNoResults.value = true
 
     const terms = new Set<string>()
-
-    results.value = results.value.map((r) => {
-      const [id, anchor] = r.id.split('#')
-      const map = cache.get(id)
-      const text = map?.get(anchor) ?? ''
-      for (const term in r.match)
+    for (const result of results.value) {
+      for (const term in result.match)
         terms.add(term)
-
-      return { ...r, text }
-    })
+    }
 
     await nextTick()
     if (canceled)
       return
 
-    await new Promise((r) => {
+    await new Promise((done) => {
       mark.value?.unmark({
         done: () => {
-          mark.value?.markRegExp(formMarkRegex(terms), { done: r })
+          mark.value?.markRegExp(formMarkRegex(terms), { done })
         },
       })
     })
@@ -245,6 +261,10 @@ function onSearchBarClick(event: PointerEvent) {
 const selectedIndex = ref(-1)
 const disableMouseOver = ref(false)
 
+const activeDescendantId = computed(() =>
+  results.value[selectedIndex.value] ? optionId(selectedIndex.value) : undefined,
+)
+
 watch(results, (r) => {
   selectedIndex.value = r.length ? 0 : -1
   scrollToSelectedResult()
@@ -273,6 +293,12 @@ function isMacCtrlShortcut(event: KeyboardEvent) {
 
 function selectPreviousResult(event: KeyboardEvent) {
   event.preventDefault()
+
+  if (!results.value.length) {
+    selectedIndex.value = -1
+    return
+  }
+
   selectedIndex.value--
   if (selectedIndex.value < 0)
     selectedIndex.value = results.value.length - 1
@@ -283,6 +309,12 @@ function selectPreviousResult(event: KeyboardEvent) {
 
 function selectNextResult(event: KeyboardEvent) {
   event.preventDefault()
+
+  if (!results.value.length) {
+    selectedIndex.value = -1
+    return
+  }
+
   selectedIndex.value++
   if (selectedIndex.value >= results.value.length)
     selectedIndex.value = 0
@@ -306,6 +338,46 @@ onKeyStroke(['n', 'N'], (event) => {
 
 const router = useRouter()
 
+/**
+ * Whether the browser back button already closed the search box.
+ *
+ * 浏览器后退键是否已关闭搜索框。
+ *
+ * When true the extra history entry created on mount has been consumed, so the
+ * unmount handler must not roll history back again.
+ *
+ * 为 true 时说明挂载时压入的额外历史条目已被消费，卸载时不应再回退历史。
+ */
+let closedByPopstate = false
+
+/**
+ * Whether the URL leaves the current page because a result is being opened, so
+ * unmount must not roll back the temporary history entry pushed on mount.
+ *
+ * 为 true 表示 URL 会离开当前页（搜索结果导航在途、已成功或被更新的导航接替），
+ * 卸载时不能回退挂载时压入的临时历史条目。
+ */
+let navigatingToResult = false
+
+/**
+ * Open a search result: navigate to the target page, then close the box.
+ *
+ * 打开搜索结果：跳转到目标页面后再关闭搜索框。
+ */
+async function openResult(id: string) {
+  navigatingToResult = true
+  // 用 replace 顶替挂载时 pushState 的临时历史条目，避免从结果页返回时多一次 Back。
+  const navigation = router.replace(id)
+
+  const navigated = await navigation.then(
+    failure => failure === undefined || isNavigationFailure(failure, NavigationFailureType.cancelled),
+    () => false,
+  )
+
+  navigatingToResult = navigated
+  emit('close', { restoreFocus: !navigated })
+}
+
 onKeyStroke('Enter', (e) => {
   if (e.isComposing)
     return
@@ -319,10 +391,8 @@ onKeyStroke('Enter', (e) => {
     return
   }
 
-  if (selectedPackage) {
-    router.push(selectedPackage.id)
-    emit('close')
-  }
+  if (selectedPackage)
+    openResult(selectedPackage.id)
 })
 
 onKeyStroke('Escape', () => {
@@ -338,12 +408,15 @@ onMounted(() => {
 
 useEventListener('popstate', (event) => {
   event.preventDefault()
+  closedByPopstate = true
   emit('close')
 })
 
 /** Lock body */
 const isLocked = useScrollLock(typeof document !== 'undefined' ? document.body : null)
 
+let appEl: Element | null = null
+
 onMounted(() => {
   nextTick(() => {
     isLocked.value = true
@@ -351,8 +424,21 @@ onMounted(() => {
   })
 })
 
+onMounted(() => {
+  appEl = document.querySelector('#app')
+  appEl?.setAttribute('inert', '')
+})
+
+onBeforeUnmount(() => {
+  appEl?.removeAttribute('inert')
+})
+
 onBeforeUnmount(() => {
   isLocked.value = false
+  // 配对挂载时的 pushState，避免反复开关搜索框累积历史条目。
+  // 若该条目已被浏览器后退键（popstate）消费，或正在跳转到搜索结果，则不能回退。
+  if (!closedByPopstate && !navigatingToResult)
+    window.history.back()
 })
 
 function resetSearch() {
@@ -375,9 +461,11 @@ function formMarkRegex(terms: Set<string>) {
 }
 
 function selectedClick(e: MouseEvent, p: SearchResult & Result) {
+  if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+    return
+
   e.preventDefault()
-  router.push(p.id)
-  emit('close')
+  openResult(p.id)
 }
 </script>
 
@@ -385,16 +473,23 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
   <Teleport to="body">
     <div
       ref="el"
-      role="button"
-      :aria-owns="results?.length ? 'localsearch-list' : undefined"
-      aria-expanded="true"
-      aria-haspopup="listbox"
-      aria-labelledby="mini-search-label"
+      role="dialog"
+      aria-modal="true"
+      :aria-label="buttonText"
       class="VPLocalSearchBox"
     >
+      <!-- eslint-disable-next-line vue-a11y/no-static-element-interactions, vue-a11y/click-events-have-key-events -->
       <div class="backdrop" @click="$emit('close')" />
 
       <div class="shell">
+        <div
+          class="sr-only"
+          role="status"
+          aria-live="polite"
+          aria-atomic="true"
+        >
+          {{ searchStatusText }}
+        </div>
         <form
           class="search-bar"
           @pointerup="onSearchBarClick($event)"
@@ -402,15 +497,18 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
         >
           <!-- eslint-disable vue-a11y/label-has-for -->
           <label
-            id="localsearch-label"
+            :id="labelId"
             :title="buttonText"
-            for="localsearch-input"
+            :for="inputId"
           >
             <SearchIcon class="search-icon" />
+            <span class="sr-only">{{ buttonText }}</span>
           </label>
           <div class="search-actions before">
             <button
+              type="button"
               class="back-button"
+              :aria-label="locale.backButtonTitle"
               :title="locale.backButtonTitle"
               @click="$emit('close')"
             >
@@ -418,20 +516,23 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
             </button>
           </div>
           <input
-            id="localsearch-input"
+            :id="inputId"
             ref="searchInput"
             v-model="filterText"
             :placeholder="buttonText"
-            aria-labelledby="localsearch-label"
+            role="combobox"
+            aria-autocomplete="list"
+            :aria-expanded="results.length > 0 ? 'true' : 'false'"
+            :aria-controls="listId"
+            :aria-labelledby="labelId"
+            :aria-activedescendant="activeDescendantId"
             class="search-input"
           >
           <div class="search-actions">
             <span
               class="search-loading"
               :class="{ active: showSearchSpinner }"
-              :role="showSearchSpinner ? 'status' : undefined"
-              aria-live="polite"
-              :aria-label="showSearchSpinner ? 'Loading search results' : undefined"
+              aria-hidden="true"
             />
             <button
               class="clear-button"
@@ -446,40 +547,42 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
         </form>
 
         <ul
-          :id="results?.length ? 'localsearch-list' : undefined"
+          :id="listId"
           ref="resultsEl"
-          :role="results?.length ? 'listbox' : undefined"
-          :aria-labelledby="results?.length ? 'localsearch-label' : undefined"
+          role="listbox"
+          :aria-labelledby="labelId"
           class="results"
+          tabindex="-1"
           @mousemove="disableMouseOver = false"
         >
           <li
             v-for="(p, index) in results"
+            :id="optionId(index)"
             :key="p.id"
             role="option"
             :aria-selected="selectedIndex === index ? 'true' : 'false'"
+            tabindex="-1"
+            @mouseenter="!disableMouseOver && (selectedIndex = index)"
+            @focusin="selectedIndex = index"
           >
             <a
-              :href="withBase(p.id)"
               class="result"
               :class="{
                 selected: selectedIndex === index,
               }"
-              :aria-label="[...p.titles, p.title].join(' > ')"
-              @mouseenter="!disableMouseOver && (selectedIndex = index)"
-              @focusin="selectedIndex = index"
+              :href="withBase(p.id)"
               @click="selectedClick($event, p)"
             >
               <div>
                 <div class="titles">
-                  <span class="title-icon">#</span>
+                  <span class="title-icon" aria-hidden="true">#</span>
                   <span
                     v-for="(t, i) in p.titles"
                     :key="i"
                     class="title"
                   >
                     <span class="text" v-html="t" />
-                    <svg width="18" height="18" viewBox="0 0 24 24">
+                    <svg width="18" height="18" viewBox="0 0 24 24" aria-hidden="true">
                       <path
                         fill="none"
                         stroke="currentColor"
@@ -497,24 +600,24 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
               </div>
             </a>
           </li>
-          <li
-            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>"
-          </li>
         </ul>
 
+        <div
+          v-if="searchIndexError"
+          class="no-results error"
+        >
+          {{ searchIndexError }}
+        </div>
+        <div
+          v-else-if="filterText && !results.length && enableNoResults"
+          class="no-results"
+        >
+          {{ locale.noResultsText }} "<strong>{{ filterText }}</strong>"
+        </div>
+
         <div class="search-keyboard-shortcuts">
           <span>
-            <kbd :aria-label="locale.footer?.navigateUpKeyAriaLabel ?? ''">
+            <kbd :aria-label="locale.footer?.navigateUpKeyAriaLabel || 'up arrow'">
               <svg width="14" height="14" viewBox="0 0 24 24">
                 <path
                   fill="none"
@@ -526,7 +629,7 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
                 />
               </svg>
             </kbd>
-            <kbd :aria-label="locale.footer?.navigateDownKeyAriaLabel ?? ''">
+            <kbd :aria-label="locale.footer?.navigateDownKeyAriaLabel || 'down arrow'">
               <svg width="14" height="14" viewBox="0 0 24 24">
                 <path
                   fill="none"
@@ -541,7 +644,7 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
             {{ locale.footer?.navigateText ?? '' }}
           </span>
           <span>
-            <kbd :aria-label="locale.footer?.selectKeyAriaLabel ?? ''">
+            <kbd :aria-label="locale.footer?.selectKeyAriaLabel || 'enter'">
               <svg width="14" height="14" viewBox="0 0 24 24">
                 <g
                   fill="none"
@@ -558,7 +661,7 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
             {{ locale.footer?.selectText ?? '' }}
           </span>
           <span>
-            <kbd :aria-label="locale.footer?.closeKeyAriaLabel ?? ''">esc</kbd>
+            <kbd :aria-label="locale.footer?.closeKeyAriaLabel || 'esc'">esc</kbd>
             {{ locale.footer?.closeText ?? '' }}
           </span>
         </div>
@@ -600,6 +703,7 @@ svg {
 
 .shell {
   position: relative;
+  box-sizing: border-box;
   display: flex;
   flex-direction: column;
   gap: 16px;
@@ -615,7 +719,7 @@ svg {
 @media (max-width: 767px) {
   .shell {
     width: 100vw;
-    height: 100vh;
+    height: 100dvh;
     max-height: none;
     margin: 0;
     border-radius: 0;
@@ -627,7 +731,7 @@ svg {
   align-items: center;
   padding: 0 12px;
   cursor: text;
-  border: 1px solid var(--vp-c-divider);
+  border: 1px solid var(--vp-c-text-2);
   border-radius: 4px;
 }
 
@@ -712,7 +816,7 @@ svg {
   height: 18px;
   margin: 8px;
   visibility: hidden;
-  border: 2px solid var(--vp-c-divider);
+  border: 2px solid var(--vp-c-text-2);
   border-top-color: var(--vp-c-brand-1);
   border-radius: 50%;
 }
@@ -796,6 +900,10 @@ svg {
   list-style: none;
 }
 
+.results:empty {
+  display: none;
+}
+
 .result {
   display: flex;
   gap: 8px;
@@ -803,10 +911,14 @@ svg {
   line-height: 1rem;
   border: solid 2px var(--vp-mini-search-result-border);
   border-radius: 4px;
-  outline: none;
   transition: none;
 }
 
+.result:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
 .result > div {
   width: 100%;
   margin: 12px;
@@ -840,8 +952,7 @@ svg {
 
 .title-icon {
   font-weight: 500;
-  color: var(--vp-c-brand-1);
-  opacity: 0.5;
+  color: var(--vp-c-text-2);
 }
 
 .title :deep(svg) {