valaxy-theme-press 1.0.0-rc.8 → 1.0.0

package/.npmignore

@@ -0,0 +1,8 @@
+# dev / tooling files — themes publish their source, so only exclude non-runtime junk
+.codebuddy
+bump.config.ts
+docs
+tsconfig.json
+*.tsbuildinfo
+*.log
+.DS_Store

package/README.md

@@ -33,3 +33,12 @@ export default defineValaxyConfig<PressTheme.Config>({
 
 - [vitepress](https://vitepress.dev/)
 - [nextjs](https://nextjs.org/)
+
+## Native theme styles
+
+Press ships its own documentation styles and `PressTheme.SidebarItem` type; it does
+not require the `vitepress` package. Theme CSS uses `--press-*` variables and
+`.press-doc`. When updating custom styles, replace `--vp-*` and `.vp-doc` with
+these names. Valaxy’s shared Markdown code-group classes remain supported.
+See [third-party notices](./THIRD-PARTY-NOTICES.md) for the adapted styles’ source
+and license.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+The styles in `styles/tokens.css`, `styles/doc.css`, `styles/code.css`, and
+`styles/code-group.css` are adapted from [VitePress 2.0.0-alpha.20](https://github.com/vuejs/vitepress/tree/v2.0.0-alpha.20/src/client/theme-default/styles).
+Valaxy owns the `press-*` namespace; the `vp-code-group` and `vp-block` selectors
+remain compatible with Valaxy’s existing Markdown output. Copy icons use Valaxy’s
+existing `--va-icon-copy` and `--va-icon-copied` variables.
+
+MIT License
+
+Copyright (c) 2019-present, Yuxi (Evan) You
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/components/PressAlgoliaSearch.vue

@@ -1,9 +1,10 @@
 <script setup lang="ts">
-import type { DocSearchInstance, DocSearchProps } from '@docsearch/js'
+import type { DocSearchProps as DocSearchAIProps, DocSearchInstance } from '@docsearch/js'
+import type { DocSearchProps } from '@docsearch/js/docsearch'
 import type { SidepanelInstance, SidepanelProps } from '@docsearch/sidepanel-js'
 import type { AlgoliaSearchOptions } from '../types/algolia'
 import { useAddonConfig } from 'valaxy'
-import { nextTick, onUnmounted, watch } from 'vue'
+import { nextTick, onMounted, onUnmounted, watch } from 'vue'
 import { useRouter } from 'vue-router'
 
 import '../styles/docsearch.css'
@@ -19,27 +20,32 @@ const router = useRouter()
 
 const algoliaConfig = useAddonConfig<AlgoliaSearchOptions>('valaxy-addon-algolia')
 
-let cleanup = () => {}
 let docsearchInstance: DocSearchInstance | undefined
 let sidepanelInstance: SidepanelInstance | undefined
 let openOnReady: 'search' | 'askAi' | null = null
 let initializeCount = 0
-let docsearchLoader: Promise<typeof import('@docsearch/js')> | undefined
+let docsearchLoader: Promise<typeof import('@docsearch/js/docsearch')> | undefined
+let docsearchAiLoader: Promise<typeof import('@docsearch/js')> | undefined
 let sidepanelLoader: Promise<typeof import('@docsearch/sidepanel-js')> | undefined
 let lastFocusedElement: HTMLElement | null = null
 let skipEventDocsearch = false
 let skipEventSidepanel = false
 
-watch(
+onMounted(() => watch(
   () => algoliaConfig.value?.options,
   (options) => {
     if (options)
       update(options)
   },
   { immediate: true },
-)
+))
 
-onUnmounted(cleanup)
+onUnmounted(() => {
+  ++initializeCount
+  cleanup()
+  openOnReady = null
+  lastFocusedElement = null
+})
 
 watch(
   () => props.openRequest?.nonce,
@@ -84,11 +90,14 @@ watch(
 )
 
 async function update(options: AlgoliaSearchOptions) {
+  const currentInitialize = ++initializeCount
   await nextTick()
+  if (currentInitialize !== initializeCount)
+    return
 
-  // Normalize askAi: string -> { assistantId }
+  // Normalize askAi: string -> { agentId }
   const askAi = typeof options.askAi === 'string'
-    ? { assistantId: options.askAi }
+    ? { agentId: options.askAi }
     : options.askAi || undefined
 
   const appId = options.appId ?? askAi?.appId
@@ -109,15 +118,22 @@ async function initialize(userOptions: AlgoliaSearchOptions) {
   // Always tear down previous instances first
   cleanup()
 
-  const { askAi: _askAi, locales: _locales, mode: _mode, ...docSearchUserOptions } = userOptions
-  // Normalize askAi: string -> { assistantId }
-  const askAi = typeof _askAi === 'string'
-    ? { assistantId: _askAi }
+  const {
+    askAi: _askAi,
+    locales: _locales,
+    mode: _mode,
+    indexName,
+    searchParameters,
+    translations,
+    ...docSearchUserOptions
+  } = userOptions
+  // Normalize askAi: string -> { agentId }
+  const normalizedAskAi = typeof _askAi === 'string'
+    ? { agentId: _askAi }
     : _askAi || undefined
-
-  const { default: docsearch } = await loadDocsearch()
-  if (currentInitialize !== initializeCount)
-    return
+  const askAi = normalizedAskAi?.agentId ? normalizedAskAi : undefined
+  if (normalizedAskAi && !askAi)
+    console.warn('[valaxy-theme-press] Ask AI requires a published Agent Studio agentId. Migrate the legacy assistant in the Algolia dashboard.')
 
   // Initialize sidepanel if askAi.sidePanel is configured
   if (askAi?.sidePanel) {
@@ -130,10 +146,11 @@ async function initialize(userOptions: AlgoliaSearchOptions) {
     sidepanelInstance = sidepanel({
       ...sidePanelConfig,
       container: '#press-docsearch-sidepanel',
-      indexName: askAi.indexName ?? docSearchUserOptions.indexName,
       appId: askAi.appId ?? docSearchUserOptions.appId,
       apiKey: askAi.apiKey ?? docSearchUserOptions.apiKey,
-      assistantId: askAi.assistantId,
+      agentId: askAi.agentId,
+      indices: askAi.indices ?? [askAi.indexName ?? indexName],
+      searchParameters: askAi.searchParameters,
       onOpen: focusInput,
       onClose: onClose.bind(null, 'sidepanel'),
       onReady: () => {
@@ -149,8 +166,13 @@ async function initialize(userOptions: AlgoliaSearchOptions) {
   }
 
   const options: DocSearchProps = {
-    ...docSearchUserOptions as DocSearchProps,
+    ...docSearchUserOptions as Omit<DocSearchProps, 'container' | 'indices'>,
     container: '#press-docsearch',
+    indices: [{
+      name: indexName,
+      searchParameters: searchParameters as Exclude<DocSearchProps['indices'][number], string>['searchParameters'],
+    }],
+    translations: normalizeTranslations(translations),
     navigator: {
       navigate(item) {
         const { pathname, hash } = new URL(item.itemUrl, location.origin)
@@ -162,13 +184,6 @@ async function initialize(userOptions: AlgoliaSearchOptions) {
         ...item,
         url: getRelativePath(item.url),
       })),
-    // When sidepanel is enabled, intercept Ask AI events to open it instead
-    ...(sidepanelInstance && {
-      interceptAskAiEvent: (initialMessage: any) => {
-        onBeforeOpen('sidepanel', () => sidepanelInstance?.open(initialMessage))
-        return true
-      },
-    }),
     onOpen: focusInput,
     onClose: onClose.bind(null, 'docsearch'),
     onReady: () => {
@@ -187,18 +202,45 @@ async function initialize(userOptions: AlgoliaSearchOptions) {
     },
   }
 
-  docsearchInstance = docsearch(options)
+  if (askAi) {
+    const { default: docsearchAi } = await loadDocsearchAi()
+    if (currentInitialize !== initializeCount)
+      return
 
-  cleanup = () => {
-    docsearchInstance?.destroy()
-    sidepanelInstance?.destroy()
-    docsearchInstance = undefined
-    sidepanelInstance = undefined
-    openOnReady = null
-    lastFocusedElement = null
+    const aiOptions: DocSearchAIProps = {
+      ...options,
+      askAi: {
+        agentId: askAi.agentId,
+        appId: askAi.appId,
+        apiKey: askAi.apiKey,
+        indices: askAi.indices ?? [askAi.indexName ?? indexName],
+        searchParameters: askAi.searchParameters,
+        suggestedQuestions: askAi.suggestedQuestions,
+      },
+      ...(sidepanelInstance && {
+        interceptAskAiEvent: (initialMessage) => {
+          onBeforeOpen('sidepanel', () => sidepanelInstance?.open(initialMessage))
+          return true
+        },
+      }),
+    }
+    docsearchInstance = docsearchAi(aiOptions)
+  }
+  else {
+    const { default: docsearch } = await loadDocsearch()
+    if (currentInitialize !== initializeCount)
+      return
+    docsearchInstance = docsearch(options)
   }
 }
 
+function cleanup() {
+  docsearchInstance?.destroy()
+  sidepanelInstance?.destroy()
+  docsearchInstance = undefined
+  sidepanelInstance = undefined
+}
+
 function focusInput() {
   requestAnimationFrame(() => {
     const input
@@ -253,16 +295,48 @@ function onClose(target: 'docsearch' | 'sidepanel') {
 
 function loadDocsearch() {
   if (!docsearchLoader)
-    docsearchLoader = import('@docsearch/js')
+    docsearchLoader = import('@docsearch/js/docsearch')
   return docsearchLoader
 }
 
+function loadDocsearchAi() {
+  if (!docsearchAiLoader)
+    docsearchAiLoader = import('@docsearch/js')
+  return docsearchAiLoader
+}
+
 function loadSidepanel() {
   if (!sidepanelLoader)
     sidepanelLoader = import('@docsearch/sidepanel-js')
   return sidepanelLoader
 }
 
+function normalizeTranslations(translations: AlgoliaSearchOptions['translations']): DocSearchProps['translations'] {
+  if (!translations)
+    return undefined
+
+  const modal = translations.modal as Record<string, any> | undefined
+  const searchBox = modal?.searchBox as Record<string, string> | undefined
+  const footer = modal?.footer as Record<string, string> | undefined
+  const { searchBox: _searchBox, footer: _footer, ...screenTranslations } = modal ?? {}
+  return {
+    button: translations.button,
+    modal: {
+      ...screenTranslations,
+      searchBox: searchBox && {
+        clearButtonTitle: searchBox.resetButtonTitle,
+        clearButtonAriaLabel: searchBox.resetButtonAriaLabel,
+        closeButtonText: searchBox.cancelButtonText,
+        closeButtonAriaLabel: searchBox.cancelButtonAriaLabel,
+      },
+      footer: footer && {
+        ...footer,
+        poweredByText: footer.searchByText,
+      },
+    },
+  }
+}
+
 function getRelativePath(url: string) {
   const { pathname, hash } = new URL(url, location.origin)
   return pathname.replace(/\.html$/, '') + hash

package/components/PressApiIndex.vue

@@ -0,0 +1,245 @@
+<script setup lang="ts">
+import type { ApiIndexGroup } from '../utils/api-index'
+import { computed, onMounted, shallowRef, useId } from 'vue'
+import { filterApiGroups } from '../utils/api-index'
+
+const props = withDefaults(defineProps<{
+  groups: ApiIndexGroup[]
+  label?: string
+  placeholder?: string
+  emptyText?: string
+  allText?: string
+  clearText?: string
+  resultsText?: string
+}>(), {
+  label: 'Filter APIs',
+  placeholder: 'Search by name or category',
+  emptyText: 'No matching APIs.',
+  allText: 'All modules',
+  clearText: 'Clear filters',
+  resultsText: 'APIs',
+})
+const query = shallowRef('')
+const ready = shallowRef(false)
+onMounted(() => ready.value = true)
+const module = shallowRef('')
+const inputId = useId()
+const modules = computed(() => [...new Set(props.groups.map(group => group.module).filter((name): name is string => !!name))])
+const filtered = computed(() => filterApiGroups(props.groups, query.value, module.value))
+const count = computed(() => filtered.value.reduce((total, group) => total + group.items.length, 0))
+const sections = computed(() => [...new Set(filtered.value.map(group => group.module || ''))].map(name => ({
+  name,
+  groups: filtered.value.filter(group => (group.module || '') === name),
+})))
+function clear() {
+  query.value = ''
+  module.value = ''
+}
+</script>
+
+<template>
+  <div class="press-api-index not-prose">
+    <div class="api-filter">
+      <label :for="inputId" class="api-filter-label">{{ label }}</label>
+      <div class="api-search-field">
+        <span class="api-search-icon" aria-hidden="true">⌕</span>
+        <input :id="inputId" v-model="query" :disabled="!ready" type="search" class="api-filter-input" :placeholder="placeholder" autocomplete="off" spellcheck="false">
+      </div>
+      <span class="api-result-count" role="status" aria-live="polite">{{ count }} {{ resultsText }}</span>
+    </div>
+    <div v-if="modules.length > 1" class="api-module-filter" role="group" :aria-label="allText">
+      <button type="button" :disabled="!ready" :aria-pressed="!module" @click="module = ''">
+        {{ allText }}
+      </button>
+      <button v-for="name in modules" :key="name" type="button" :disabled="!ready" :aria-pressed="module === name" @click="module = name">
+        {{ name }}
+      </button>
+    </div>
+    <section v-for="section in sections" :key="section.name" class="api-module">
+      <h2 v-if="section.name" class="api-module-title">
+        {{ section.name }}
+      </h2>
+      <div class="api-groups">
+        <section v-for="group in section.groups" :key="group.title" class="api-group">
+          <h3 class="api-group-title">
+            {{ group.title }} <span>{{ group.items.length }}</span>
+          </h3>
+          <ul class="api-items">
+            <li v-for="item in group.items" :key="item.link" class="api-item">
+              <AppLink :to="item.link" class="api-link">
+                {{ item.text }}
+              </AppLink>
+            </li>
+          </ul>
+        </section>
+      </div>
+    </section>
+    <div v-if="!filtered.length" class="api-empty">
+      <p>{{ emptyText }}</p>
+      <button type="button" class="api-clear" @click="clear">
+        {{ clearText }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.press-api-index {
+  margin-top: 1.5rem;
+}
+
+.api-filter {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.api-filter-label {
+  width: 100%;
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.api-search-field {
+  display: flex;
+  align-items: center;
+  flex: 1;
+  min-width: 0;
+  border: 1px solid var(--pr-c-divider-light);
+  border-radius: 8px;
+  background: var(--pr-c-surface);
+}
+
+.api-search-icon {
+  padding-left: 0.875rem;
+  font-size: 1.5rem;
+  color: var(--pr-c-text-2);
+}
+
+.api-filter-input {
+  width: 100%;
+  min-width: 0;
+  padding: 0.75rem;
+  background: transparent;
+  color: var(--pr-c-text-1);
+  font: inherit;
+  font-size: 1rem;
+}
+
+.api-search-field:focus-within {
+  outline: 2px solid var(--pr-c-brand);
+  outline-offset: 2px;
+}
+
+.api-filter-input:focus {
+  outline: none;
+}
+
+.api-result-count {
+  font-size: 0.75rem;
+  color: var(--pr-c-text-2);
+  font-variant-numeric: tabular-nums;
+}
+
+.api-module-filter {
+  display: flex;
+  gap: 0.375rem;
+  flex-wrap: wrap;
+  margin: 1rem 0 2.5rem;
+}
+
+.api-module-filter button {
+  padding: 0.375rem 0.875rem;
+  border-radius: 6px;
+  color: var(--pr-c-text-2);
+  font-size: 0.8125rem;
+  cursor: pointer;
+}
+
+.api-module-filter button[aria-pressed="true"] {
+  background: var(--pr-c-brand-soft);
+  color: var(--pr-c-brand);
+  font-weight: 600;
+}
+
+.api-module-filter button:hover {
+  color: var(--pr-c-brand);
+}
+
+.api-module + .api-module {
+  margin-top: 3rem;
+}
+
+.press-api-index .api-module-title {
+  margin: 0 0 1.25rem;
+  padding: 0 0 0.75rem;
+  border: 0;
+  border-bottom: 1px solid var(--pr-c-divider-light);
+  color: var(--pr-c-text-1);
+  font-size: 1.5rem;
+  font-family: var(--pr-font-mono);
+  letter-spacing: -0.03em;
+}
+
+.api-groups {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 15rem), 1fr));
+  gap: 1.75rem;
+  align-items: start;
+}
+
+.press-api-index .api-group-title {
+  margin: 0 0 0.625rem;
+  padding: 0;
+  border: 0;
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--pr-c-text-2);
+  letter-spacing: 0;
+}
+
+.api-group-title span {
+  margin-left: 0.375rem;
+  font-weight: 400;
+  font-size: 0.75rem;
+}
+
+.api-items {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.api-item {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.api-link {
+  display: block;
+  padding: 0.25rem 0;
+  color: var(--pr-c-brand);
+  font-size: 0.8125rem;
+  line-height: 1.65;
+  font-family: var(--pr-font-mono);
+}
+
+.api-empty {
+  padding: 2rem 0;
+  color: var(--pr-c-text-2);
+}
+
+.api-clear {
+  margin-top: 1rem;
+  color: var(--pr-c-brand);
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+@media (width < 640px) {
+  .api-result-count {
+    width: 100%;
+  }
+}
+</style>