@voidzero-dev/vitepress-theme 4.4.2 → 4.5.0

package/src/styles/vitepress-default/docsearch.css

@@ -0,0 +1,120 @@
+@import '@docsearch/css/dist/style.css';
+@import '@docsearch/css/dist/sidepanel.css';
+
+#vp-docsearch,
+#vp-docsearch-sidepanel,
+.DocSearch-SidepanelButton {
+  display: none;
+}
+
+:root:root {
+  --docsearch-actions-height: auto;
+  --docsearch-actions-width: auto;
+  --docsearch-background-color: var(--vp-c-bg-soft);
+  --docsearch-container-background: var(--vp-backdrop-bg-color);
+  --docsearch-dropdown-menu-background: var(--vp-c-bg-elv);
+  --docsearch-dropdown-menu-item-hover-background: var(--vp-c-default-soft);
+  --docsearch-focus-color: var(--vp-c-brand-1);
+  --docsearch-footer-background: var(--vp-c-bg-alt);
+  --docsearch-highlight-color: var(--vp-c-brand-1);
+  --docsearch-hit-background: var(--vp-c-bg);
+  --docsearch-hit-color: var(--vp-c-text-1);
+  --docsearch-hit-highlight-color: var(--vp-c-brand-soft);
+  --docsearch-icon-color: var(--vp-c-text-2);
+  --docsearch-key-background: var(--vp-code-bg);
+  --docsearch-modal-background: var(--vp-c-bg-soft);
+  --docsearch-muted-color: var(--vp-c-text-2);
+  --docsearch-primary-color: var(--vp-c-brand-1);
+  --docsearch-searchbox-background: var(--vp-c-bg-alt);
+  --docsearch-searchbox-focus-background: transparent;
+  --docsearch-secondary-text-color: var(--vp-c-text-2);
+  --docsearch-sidepanel-accent-muted: var(--vp-c-text-3);
+  --docsearch-sidepanel-text-base: var(--vp-c-text-1);
+  --docsearch-soft-muted-color: var(--vp-c-default-soft);
+  --docsearch-soft-primary-color: var(--vp-c-brand-soft);
+  --docsearch-subtle-color: var(--vp-c-divider);
+  --docsearch-success-color: var(--vp-c-brand-soft);
+  --docsearch-text-color: var(--vp-c-text-1);
+}
+
+:root.dark {
+  --docsearch-modal-shadow: none;
+}
+
+.DocSearch-AskAiScreen-RelatedSources-Item-Link {
+  padding: 8px 12px 8px 10px;
+}
+
+.DocSearch-AskAiScreen-RelatedSources-Item-Link svg {
+  width: 16px;
+  height: 16px;
+}
+
+.DocSearch-AskAiScreen-RelatedSources-Title {
+  padding-bottom: 0;
+  font-size: 12px;
+}
+
+.DocSearch-Clear {
+  padding-right: 6px;
+}
+
+.DocSearch-Commands-Key {
+  padding: 4px;
+  border: 1px solid var(--docsearch-subtle-color);
+  border-radius: 4px;
+}
+
+.DocSearch-Hit a:focus-visible {
+  outline: 2px solid var(--docsearch-focus-color);
+}
+
+.DocSearch-Logo [class^='cls-'] {
+  fill: currentColor;
+}
+
+.DocSearch-Markdown-Content code {
+  padding: 0.2em 0.4em;
+}
+
+.DocSearch-Menu-content {
+  margin-top: -4px;
+  padding: 6px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 6px;
+  box-shadow: var(--vp-shadow-2);
+}
+
+.DocSearch-Menu-item {
+  border-radius: 4px;
+}
+
+.DocSearch-SearchBar + .DocSearch-Footer {
+  border-top-color: transparent;
+}
+
+.DocSearch-Sidepanel-Prompt--form {
+  border-color: var(--docsearch-subtle-color);
+  transition: border-color 0.2s;
+}
+
+.DocSearch-Sidepanel-Prompt--submit {
+  background-color: var(--docsearch-soft-primary-color);
+  color: var(--docsearch-primary-color);
+}
+
+.DocSearch-Sidepanel-Prompt--submit:hover {
+  background-color: var(--vp-button-brand-hover-bg);
+  color: var(--vp-button-brand-text);
+}
+
+.DocSearch-Sidepanel-Prompt--submit:disabled,
+.DocSearch-Sidepanel-Prompt--submit[aria-disabled='true'] {
+  background-color: var(--docsearch-soft-muted-color);
+  color: var(--docsearch-muted-color);
+}
+
+.DocSearch-Title {
+  font-size: revert;
+  line-height: revert;
+}

package/src/styles/vitepress-default/icons.css

@@ -74,7 +74,10 @@
   --icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='none' stroke='black' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2c-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z'/%3E%3C/svg%3E");
 }
 .vpi-search {
-  --icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cg fill='none' stroke='black' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.6'%3E%3Cpath d='m21 21l-4.34-4.34'/%3E%3Ccircle cx='11' cy='11' r='8' stroke-width='1.4'/%3E%3C/g%3E%3C/svg%3E");
+  --icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cg fill='none' stroke='black' stroke-linecap='round' stroke-linejoin='round' stroke-width='2'%3E%3Cpath d='m21 21l-4.34-4.34'/%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3C/g%3E%3C/svg%3E");
+}
+.vpi-sparkles {
+  --icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cg fill='none' stroke='black' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.8'%3E%3Cpath d='M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594zM20 2v4m2-2h-4'/%3E%3Ccircle cx='4' cy='20' r='2'/%3E%3C/g%3E%3C/svg%3E");
 }
 .vpi-layout-list {
   --icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cg fill='none' stroke='black' stroke-linecap='round' stroke-linejoin='round' stroke-width='2'%3E%3Crect width='7' height='7' x='3' y='3' rx='1'/%3E%3Crect width='7' height='7' x='3' y='14' rx='1'/%3E%3Cpath d='M14 4h7m-7 5h7m-7 6h7m-7 5h7'/%3E%3C/g%3E%3C/svg%3E");

package/src/styles/vitepress-default/vars.css

@@ -396,6 +396,9 @@
 :lang(zh) {
   --vp-code-copy-copied-text-content: '已复制';
 }
+:lang(ja) {
+  --vp-code-copy-copied-text-content: 'コピー完了';
+}
 
 /**
  * Component: Button
@@ -537,7 +540,8 @@
   --vp-backdrop-bg-color: rgba(255, 255, 255, 0.7);
 }
 
-.dark {
+.dark,
+[data-theme="dark"] {
   --vp-backdrop-bg-color: rgba(22, 23, 29, 0.8);
 }
 

package/src/support/vitepress-default/docsearch.ts

@@ -0,0 +1,253 @@
+import type { DefaultTheme } from 'vitepress/theme'
+import type { DocSearchAskAi } from '../../types/docsearch'
+import { isObject } from '@vueuse/shared'
+
+export type FacetFilter = string | string[] | FacetFilter[]
+
+export interface ValidatedCredentials {
+  valid: boolean
+  appId?: string
+  apiKey?: string
+  indexName?: string
+}
+
+export type DocSearchMode = 'auto' | 'sidePanel' | 'hybrid' | 'modal'
+
+export interface ResolvedMode {
+  mode: DocSearchMode
+  showKeywordSearch: boolean
+  useSidePanel: boolean
+}
+
+/**
+ * Resolves the effective mode based on config and available features.
+ *
+ * - 'auto': infer hybrid vs sidePanel-only from provided config
+ * - 'sidePanel': force sidePanel-only even if keyword search is configured
+ * - 'hybrid': force hybrid (error if keyword search is not configured)
+ * - 'modal': force modal even if sidePanel is configured
+ */
+export function resolveMode(
+  options: Pick<
+    DefaultTheme.AlgoliaSearchOptions,
+    'appId' | 'apiKey' | 'indexName' | 'askAi' | 'mode'
+  >
+): ResolvedMode {
+  const mode = options.mode ?? 'auto'
+  const hasKeyword = hasKeywordSearch(options)
+  const askAi = options.askAi
+  const hasSidePanelConfig = Boolean(
+    askAi && typeof askAi === 'object' && askAi.sidePanel
+  )
+
+  switch (mode) {
+    case 'sidePanel':
+      // Force sidePanel-only - hide keyword search
+      return {
+        mode,
+        showKeywordSearch: false,
+        useSidePanel: true
+      }
+
+    case 'hybrid':
+      // Force hybrid - keyword search must be configured
+      if (!hasKeyword) {
+        console.error(
+          '[vitepress] mode: "hybrid" requires keyword search credentials (appId, apiKey, indexName).'
+        )
+      }
+      return {
+        mode,
+        showKeywordSearch: hasKeyword,
+        useSidePanel: true
+      }
+
+    case 'modal':
+      // Force modal - don't use sidepanel for askai, even if configured
+      return {
+        mode,
+        showKeywordSearch: hasKeyword,
+        useSidePanel: false
+      }
+
+    case 'auto':
+    default:
+      // Auto-detect based on config
+      return {
+        mode: 'auto',
+        showKeywordSearch: hasKeyword,
+        useSidePanel: hasSidePanelConfig
+      }
+  }
+}
+
+export function hasKeywordSearch(
+  options: Pick<
+    DefaultTheme.AlgoliaSearchOptions,
+    'appId' | 'apiKey' | 'indexName'
+  >
+): boolean {
+  return Boolean(options.appId && options.apiKey && options.indexName)
+}
+
+export function hasAskAi(
+  askAi: DefaultTheme.AlgoliaSearchOptions['askAi']
+): boolean {
+  if (!askAi) return false
+  if (typeof askAi === 'string') return askAi.length > 0
+  return Boolean(askAi.assistantId)
+}
+
+/**
+ * Removes existing `lang:` filters and appends `lang:${lang}`.
+ * Handles both flat arrays and nested arrays (for OR conditions).
+ */
+export function mergeLangFacetFilters(
+  rawFacetFilters: FacetFilter | FacetFilter[] | undefined,
+  lang: string
+): FacetFilter[] {
+  const input = Array.isArray(rawFacetFilters)
+    ? rawFacetFilters
+    : rawFacetFilters
+      ? [rawFacetFilters]
+      : []
+
+  const filtered = input
+    .map((filter) => {
+      if (Array.isArray(filter)) {
+        // Handle nested arrays (OR conditions)
+        return filter.filter(
+          (f) => typeof f === 'string' && !f.startsWith('lang:')
+        )
+      }
+      return filter
+    })
+    .filter((filter) => {
+      if (typeof filter === 'string') {
+        return !filter.startsWith('lang:')
+      }
+      // Keep nested arrays with remaining filters
+      return Array.isArray(filter) && filter.length > 0
+    })
+
+  return [...filtered, `lang:${lang}`]
+}
+
+/**
+ * Validates that required Algolia credentials are present.
+ */
+export function validateCredentials(
+  options: Pick<
+    DefaultTheme.AlgoliaSearchOptions,
+    'appId' | 'apiKey' | 'indexName'
+  >
+): ValidatedCredentials {
+  const appId = options.appId
+  const apiKey = options.apiKey
+  const indexName = options.indexName
+
+  return {
+    valid: Boolean(appId && apiKey && indexName),
+    appId,
+    apiKey,
+    indexName
+  }
+}
+
+/**
+ * Builds Ask AI configuration from various input formats.
+ */
+export function buildAskAiConfig(
+  askAiProp: NonNullable<DefaultTheme.AlgoliaSearchOptions['askAi']>,
+  options: DefaultTheme.AlgoliaSearchOptions,
+  lang: string
+): DocSearchAskAi {
+  const isAskAiString = typeof askAiProp === 'string'
+
+  const askAiSearchParameters =
+    !isAskAiString && askAiProp.searchParameters
+      ? { ...askAiProp.searchParameters }
+      : undefined
+
+  // If Ask AI defines its own facetFilters, merge lang filtering into those.
+  // Otherwise, reuse the keyword search facetFilters so Ask AI follows the
+  // same language filtering behavior by default.
+  const askAiFacetFiltersSource =
+    askAiSearchParameters?.facetFilters ??
+    options.searchParameters?.facetFilters
+  const askAiFacetFilters = mergeLangFacetFilters(
+    askAiFacetFiltersSource as FacetFilter | FacetFilter[] | undefined,
+    lang
+  )
+
+  const mergedAskAiSearchParameters = {
+    ...askAiSearchParameters,
+    facetFilters: askAiFacetFilters.length ? askAiFacetFilters : undefined
+  }
+
+  const result: Record<string, any> = {
+    ...(isAskAiString ? {} : askAiProp),
+    indexName: isAskAiString ? options.indexName : askAiProp.indexName,
+    apiKey: isAskAiString ? options.apiKey : askAiProp.apiKey,
+    appId: isAskAiString ? options.appId : askAiProp.appId,
+    assistantId: isAskAiString ? askAiProp : askAiProp.assistantId
+  }
+
+  // Keep `searchParameters` undefined unless it has at least one key.
+  if (Object.values(mergedAskAiSearchParameters).some((v) => v != null)) {
+    result.searchParameters = mergedAskAiSearchParameters
+  }
+
+  return result
+}
+
+/**
+ * Resolves Algolia search options for the given language,
+ * merging in locale-specific overrides and language facet filters.
+ */
+export function resolveOptionsForLanguage(
+  options: DefaultTheme.AlgoliaSearchOptions,
+  localeIndex: string,
+  lang: string
+): DefaultTheme.AlgoliaSearchOptions {
+  options = deepMerge(options, options.locales?.[localeIndex] || {})
+
+  const facetFilters = mergeLangFacetFilters(
+    options.searchParameters?.facetFilters,
+    lang
+  )
+  const askAi = options.askAi
+    ? buildAskAiConfig(options.askAi, options, lang)
+    : undefined
+
+  return {
+    ...options,
+    searchParameters: { ...options.searchParameters, facetFilters },
+    askAi
+  }
+}
+
+function deepMerge<T>(target: T, source: Partial<T>): T {
+  const result = { ...target } as any
+
+  for (const key in source) {
+    const value = source[key]
+    if (value === undefined) continue
+
+    // special case: replace entirely
+    if (key === 'searchParameters') {
+      result[key] = value
+      continue
+    }
+
+    // deep-merge only plain objects; arrays are replaced entirely
+    if (isObject(value) && isObject(result[key])) {
+      result[key] = deepMerge(result[key], value)
+    } else {
+      result[key] = value
+    }
+  }
+
+  delete result.locales
+  return result
+}

package/src/support/vitepress-default/reactivity.ts

@@ -0,0 +1,14 @@
+import { type ComputedRef, computed } from 'vue'
+
+export function smartComputed<T>(
+  getter: () => T,
+  comparator = (oldValue: T, newValue: T) =>
+    JSON.stringify(oldValue) === JSON.stringify(newValue)
+): ComputedRef<T> {
+  return computed((oldValue) => {
+    const newValue = getter()
+    return oldValue === undefined || !comparator(oldValue, newValue)
+      ? newValue
+      : oldValue
+  })
+}

package/src/types/docsearch.d.ts

@@ -1,31 +1,63 @@
-/**
- * Type declarations for @docsearch packages.
- *
- * These are optional peer dependencies that may or may not be installed.
- * The declarations ensure TypeScript doesn't error on dynamic imports.
- */
+import { type DocSearchProps as DocSearchPropsJS } from '@docsearch/js'
+import { type SidepanelProps as SidepanelPropsBase } from '@docsearch/sidepanel-js'
 
-declare module '@docsearch/css' {
-  // CSS module - no exports, just side effects
-  const css: void
-  export default css
+export type DocSearchProps = Partial<
+  Pick<
+    DocSearchPropsJS,
+    | 'appId'
+    | 'apiKey'
+    | 'placeholder'
+    | 'maxResultsPerGroup'
+    | 'disableUserPersonalization'
+    | 'initialQuery'
+    | 'translations'
+    | 'recentSearchesLimit'
+    | 'recentSearchesWithFavoritesLimit'
+  >
+> & {
+  /**
+   * Name of the algolia index to query.
+   */
+  indexName?: string
+  /**
+   * Additional algolia search parameters to merge into each query.
+   */
+  searchParameters?: DocSearchPropsJS['searchParameters']
+  /**
+   * Insights client integration options to send analytics events.
+   */
+  insights?: boolean
+  /**
+   * Configuration or assistant id to enable ask ai mode. Pass a string assistant id or a full config object.
+   */
+  askAi?: DocSearchAskAi | string
+  /**
+   * Ask AI side panel integration mode.
+   *
+   * - 'auto': infer hybrid vs sidePanel-only from provided config
+   * - 'sidePanel': force sidePanel-only even if keyword search is configured
+   * - 'hybrid': force hybrid (error if keyword search is not configured)
+   * - 'modal': force modal even if sidePanel is configured (ask ai in modal stays in modal)
+   *
+   * @default 'auto'
+   */
+  mode?: 'auto' | 'sidePanel' | 'hybrid' | 'modal'
 }
 
-declare module '@docsearch/js' {
-  interface DocSearchProps {
-    appId: string
-    apiKey: string
-    indexName: string
-    container: string | HTMLElement
-    placeholder?: string
-    searchParameters?: Record<string, any>
-    transformItems?: (items: any[]) => any[]
-    navigator?: {
-      navigate?: (params: { itemUrl: string }) => void
-    }
-    [key: string]: any
-  }
+export type DocSearchAskAi = Partial<
+  Exclude<DocSearchPropsJS['askAi'], string | undefined>
+> & {
+  /**
+   * Ask AI side panel configuration.
+   */
+  sidePanel?: boolean | SidepanelProps
+}
 
-  function docsearch(props: DocSearchProps): void
-  export default docsearch
+export type SidepanelProps = Partial<
+  Pick<SidepanelPropsBase, 'button' | 'keyboardShortcuts'>
+> & {
+  /**
+   * Props specific to the Sidepanel panel.
+   */
+  panel?: Omit<NonNullable<SidepanelPropsBase['panel']>, 'portalContainer'>
 }

package/src/types/local-search.d.ts

@@ -1,38 +1,33 @@
-/**
- * Type definitions for local search functionality
- */
+export interface LocalSearchTranslations {
+  button?: ButtonTranslations
+  modal?: ModalTranslations
+}
+
+export interface ButtonTranslations {
+  buttonText?: string
+  buttonAriaLabel?: string
+}
 
 export interface ModalTranslations {
-  modal?: {
-    displayDetails?: string
-    resetButtonTitle?: string
-    backButtonTitle?: string
-    noResultsText?: string
-    footer?: {
-      selectText?: string
-      selectKeyAriaLabel?: string
-      navigateText?: string
-      navigateUpKeyAriaLabel?: string
-      navigateDownKeyAriaLabel?: string
-      closeText?: string
-      closeKeyAriaLabel?: string
-    }
-  }
+  displayDetails?: string
+  resetButtonTitle?: string
+  backButtonTitle?: string
+  noResultsText?: string
+  footer?: FooterTranslations
 }
 
-export interface ButtonTranslations {
-  button?: {
-    buttonText?: string
-    buttonAriaLabel?: string
-  }
+export interface FooterTranslations {
+  selectText?: string
+  selectKeyAriaLabel?: string
+  navigateText?: string
+  navigateUpKeyAriaLabel?: string
+  navigateDownKeyAriaLabel?: string
+  closeText?: string
+  closeKeyAriaLabel?: string
 }
 
-/**
- * Virtual module declaration for @localSearchIndex
- * This module is dynamically generated by VitePress's localSearchPlugin
- * during downstream project builds.
- */
-declare module '@localSearchIndex' {
-  const data: Record<string, () => Promise<{ default: string }>>
-  export default data
+export interface PageSplitSection {
+  anchor?: string
+  titles: string[]
+  text: string
 }