docus 5.4.4 → 5.5.1

package/modules/assistant/README.md

@@ -0,0 +1,213 @@
+# Assistant Module
+
+A Nuxt module that provides an AI-powered chat interface using MCP (Model Context Protocol) tools.
+
+## Features
+
+- AI chat slideover component with streaming responses
+- Floating input component for quick questions
+- MCP tools integration for documentation search
+- Syntax highlighting for code blocks
+- FAQ suggestions
+- Persistent chat state
+- Keyboard shortcuts support
+
+## Installation
+
+1. Copy the `modules/assistant` folder to your Nuxt project
+2. Install the required dependencies:
+
+```bash
+pnpm add @ai-sdk/mcp @ai-sdk/vue @ai-sdk/gateway ai motion-v shiki shiki-stream
+```
+
+3. Add the module to your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['./modules/assistant'],
+
+  assistant: {
+    apiPath: '/__docus__/assistant',
+    mcpServer: '/mcp',
+    model: 'google/gemini-3-flash',
+  }
+})
+```
+
+4. Set up your API key as an environment variable:
+
+```bash
+AI_GATEWAY_API_KEY=your-gateway-key
+```
+
+> **Note:** The module will only be enabled if `AI_GATEWAY_API_KEY` is detected. If no key is found, the module is disabled and a message is logged to the console.
+
+## Usage
+
+Add the components to your app:
+
+```vue
+<template>
+  <div>
+    <!-- Button to open the chat -->
+    <AssistantChat />
+
+    <!-- Chat panel (place once in your app/layout) -->
+    <AssistantPanel />
+  </div>
+</template>
+```
+
+### FAQ Questions
+
+Configure FAQ questions in your `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+  assistant: {
+    faqQuestions: [
+      {
+        category: 'Getting Started',
+        items: ['How do I install?', 'How do I configure?'],
+      },
+      {
+        category: 'Advanced',
+        items: ['How do I customize?'],
+      },
+    ],
+  },
+})
+```
+
+You can also use localized FAQ questions:
+
+```ts
+export default defineAppConfig({
+  assistant: {
+    faqQuestions: {
+      en: ['How do I install?', 'How do I configure?'],
+      fr: ['Comment installer ?', 'Comment configurer ?'],
+    },
+  },
+})
+```
+
+### Floating Input
+
+Use `AssistantFloatingInput` for a floating input at the bottom of the page.
+
+**Recommended:** Use `Teleport` to render the floating input at the body level, ensuring it stays fixed at the bottom regardless of your component hierarchy:
+
+```vue
+<template>
+  <div>
+    <!-- Teleport to body for proper fixed positioning -->
+    <Teleport to="body">
+      <ClientOnly>
+        <LazyAssistantFloatingInput />
+      </ClientOnly>
+    </Teleport>
+
+    <!-- Chat panel (required to display responses) -->
+    <AssistantPanel />
+  </div>
+</template>
+```
+
+The floating input:
+- Appears at the bottom center of the viewport
+- Automatically hides when the chat slideover is open
+- Expands on focus for better typing experience
+- Supports keyboard shortcuts: `⌘I` to focus, `Escape` to blur
+
+### Programmatic Control
+
+Use the `useAssistant` composable to control the chat:
+
+```vue
+<script setup>
+const { open, close, toggle, isOpen, messages, clearMessages } = useAssistant()
+
+// Open chat with an initial message
+open('How do I install the module?')
+
+// Open and clear previous messages
+open('New question', true)
+
+// Toggle chat visibility
+toggle()
+
+// Clear all messages
+clearMessages()
+</script>
+```
+
+## Module Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiPath` | `string` | `/__docus__/assistant` | API endpoint path for the chat |
+| `mcpServer` | `string` | `/mcp` | MCP server path or full URL (e.g., `https://docs.example.com/mcp` for external servers) |
+| `model` | `string` | `google/gemini-3-flash` | AI model identifier for AI SDK Gateway |
+
+## Components
+
+### `<AssistantChat>`
+
+Button to toggle the chat panel. The tooltip text is automatically translated using i18n (`assistant.tooltip`).
+
+### `<AssistantPanel>`
+
+Main chat interface displayed as a side panel. Configuration is done via `app.config.ts` (see FAQ Questions section above).
+
+### `<AssistantFloatingInput>`
+
+Floating input field positioned at the bottom of the viewport. No props required.
+
+**Keyboard shortcuts:**
+- `⌘I` / `Ctrl+I` - Focus the input
+- `Escape` - Blur the input
+- `Enter` - Submit the question
+
+## Composables
+
+### `useAssistant`
+
+Main composable for controlling the chat state.
+
+```ts
+const {
+  isOpen,         // Ref<boolean> - Whether the chat is open
+  messages,       // Ref<UIMessage[]> - Chat messages
+  pendingMessage, // Ref<string | undefined> - Pending message to send
+  faqQuestions,   // ComputedRef<FaqCategory[]> - FAQ questions from config
+  open,           // (message?: string, clearPrevious?: boolean) => void
+  close,          // () => void
+  toggle,         // () => void
+  clearMessages,  // () => void
+  clearPending,   // () => void
+} = useAssistant()
+```
+
+### `useHighlighter`
+
+Composable for syntax highlighting code blocks with Shiki.
+
+## Requirements
+
+- Nuxt 4.x
+- Nuxt UI 3.x (for `USlideover`, `UButton`, `UTextarea`, `UChatMessages`, etc.)
+- An MCP server running (path configurable via `mcpServer`)
+- `AI_GATEWAY_API_KEY` environment variable
+
+## Customization
+
+### System Prompt
+
+To customize the AI's behavior, edit the system prompt in:
+`runtime/server/api/search.ts`
+
+### Styling
+
+The components use Nuxt UI and Tailwind CSS design tokens. Customize the appearance by modifying the component files or overriding the UI props.

package/modules/assistant/index.ts

@@ -0,0 +1,100 @@
+import { addComponent, addImports, addServerHandler, createResolver, defineNuxtModule, logger } from '@nuxt/kit'
+
+export interface AssistantModuleOptions {
+  /**
+   * API endpoint path for the assistant
+   * @default '/__docus__/assistant'
+   */
+  apiPath?: string
+  /**
+   * MCP server URL or path.
+   * - Use a path like '/mcp' to use the built-in Docus MCP server
+   * - Use a full URL like 'https://docs.example.com/mcp' for external MCP servers
+   * @default '/mcp'
+   */
+  mcpServer?: string
+  /**
+   * AI model to use via AI SDK Gateway
+   * @default 'google/gemini-3-flash'
+   */
+  model?: string
+}
+
+const log = logger.withTag('Docus')
+
+export default defineNuxtModule<AssistantModuleOptions>({
+  meta: {
+    name: 'assistant',
+    configKey: 'assistant',
+  },
+  defaults: {
+    apiPath: '/__docus__/assistant',
+    mcpServer: '/mcp',
+    model: 'google/gemini-3-flash',
+  },
+  setup(options, nuxt) {
+    const hasApiKey = !!process.env.AI_GATEWAY_API_KEY
+
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.options.runtimeConfig.public.assistant = {
+      enabled: hasApiKey,
+      apiPath: options.apiPath!,
+    }
+
+    addImports([
+      {
+        name: 'useAssistant',
+        from: resolve('./runtime/composables/useAssistant'),
+      },
+    ])
+
+    const components = [
+      'AssistantChat',
+      'AssistantPanel',
+      'AssistantFloatingInput',
+      'AssistantLoading',
+      'AssistantMatrix',
+    ]
+
+    components.forEach(name =>
+      addComponent({
+        name,
+        filePath: hasApiKey
+          ? resolve(`./runtime/components/${name}.vue`)
+          : resolve('./runtime/components/AssistantChatDisabled.vue'),
+      }),
+    )
+
+    if (!hasApiKey) {
+      log.warn('AI assistant disabled: AI_GATEWAY_API_KEY not found')
+      return
+    }
+
+    nuxt.options.runtimeConfig.assistant = {
+      mcpServer: options.mcpServer!,
+      model: options.model!,
+    }
+
+    const routePath = options.apiPath!.replace(/^\//, '')
+    addServerHandler({
+      route: `/${routePath}`,
+      handler: resolve('./runtime/server/api/search'),
+    })
+  },
+})
+
+declare module 'nuxt/schema' {
+  interface PublicRuntimeConfig {
+    assistant: {
+      enabled: boolean
+      apiPath: string
+    }
+  }
+  interface RuntimeConfig {
+    assistant: {
+      mcpServer: string
+      model: string
+    }
+  }
+}

package/modules/assistant/runtime/components/AssistantChat.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { useDocusI18n } from '../../../../app/composables/useDocusI18n'
+
+const appConfig = useAppConfig()
+const { toggle } = useAssistant()
+const { t } = useDocusI18n()
+
+const tooltipText = computed(() => t('assistant.tooltip'))
+const triggerIcon = computed(() => appConfig.assistant?.icons?.trigger || 'i-lucide-sparkles')
+</script>
+
+<template>
+  <UTooltip :text="tooltipText">
+    <UButton
+      :icon="triggerIcon"
+      variant="ghost"
+      class="rounded-full"
+      @click="toggle"
+    />
+  </UTooltip>
+</template>

package/modules/assistant/runtime/components/AssistantChatDisabled.vue

@@ -0,0 +1,3 @@
+<template>
+  <div />
+</template>

package/modules/assistant/runtime/components/AssistantFloatingInput.vue

@@ -0,0 +1,110 @@
+<script setup lang="ts">
+import { AnimatePresence, motion } from 'motion-v'
+import { useDocusI18n } from '../../../../app/composables/useDocusI18n'
+
+const route = useRoute()
+const appConfig = useAppConfig()
+const { open, isOpen } = useAssistant()
+const { t } = useDocusI18n()
+const input = ref('')
+const isVisible = ref(true)
+const inputRef = ref<{ inputRef: HTMLInputElement } | null>(null)
+
+const isDocsRoute = computed(() => route.meta.layout === 'docs')
+const isFloatingInputEnabled = computed(() => appConfig.assistant?.floatingInput !== false)
+const focusInputShortcut = computed(() => appConfig.assistant?.shortcuts?.focusInput || 'meta_i')
+const placeholder = computed(() => t('assistant.placeholder'))
+
+const shortcutDisplayKeys = computed(() => {
+  const shortcut = focusInputShortcut.value
+  const parts = shortcut.split('_')
+  return parts.map(part => part === 'meta' ? 'meta' : part.toUpperCase())
+})
+
+function handleSubmit() {
+  if (!input.value.trim()) return
+
+  const message = input.value
+  isVisible.value = false
+
+  setTimeout(() => {
+    open(message, true)
+    input.value = ''
+    isVisible.value = true
+  }, 200)
+}
+
+const shortcuts = computed(() => ({
+  [focusInputShortcut.value]: {
+    usingInput: true,
+    handler: () => {
+      if (!isDocsRoute.value || !isFloatingInputEnabled.value) return
+      inputRef.value?.inputRef?.focus()
+    },
+  },
+  escape: {
+    usingInput: true,
+    handler: () => {
+      inputRef.value?.inputRef?.blur()
+    },
+  },
+}))
+
+defineShortcuts(shortcuts)
+</script>
+
+<template>
+  <AnimatePresence>
+    <motion.div
+      v-if="isFloatingInputEnabled && isDocsRoute && isVisible && !isOpen"
+      key="floating-input"
+      :initial="{ y: 20, opacity: 0 }"
+      :animate="{ y: 0, opacity: 1 }"
+      :exit="{ y: 100, opacity: 0 }"
+      :transition="{ duration: 0.2, ease: 'easeOut' }"
+      class="fixed inset-x-0 z-10 px-4 sm:px-80 bottom-[max(1.5rem,env(safe-area-inset-bottom))]"
+      style="will-change: transform"
+    >
+      <form
+        class="flex w-full justify-center"
+        @submit.prevent="handleSubmit"
+      >
+        <div class="w-full max-w-96">
+          <UInput
+            ref="inputRef"
+            v-model="input"
+            :placeholder="placeholder"
+            size="lg"
+            maxlength="1000"
+            :ui="{
+              root: 'group w-full! min-w-0 sm:max-w-96 transition-all duration-300 ease-out [@media(hover:hover)]:hover:scale-105 [@media(hover:hover)]:focus-within:scale-105',
+              base: 'bg-default shadow-lg rounded-xl text-base',
+              trailing: 'pe-2',
+            }"
+            @keydown.enter.exact.prevent="handleSubmit"
+          >
+            <template #trailing>
+              <div class="flex items-center gap-2">
+                <div class="hidden sm:flex group-focus-within:hidden items-center gap-1">
+                  <UKbd
+                    v-for="key in shortcutDisplayKeys"
+                    :key="key"
+                    :value="key"
+                  />
+                </div>
+
+                <UButton
+                  type="submit"
+                  icon="i-lucide-arrow-up"
+                  color="primary"
+                  size="xs"
+                  :disabled="!input.trim()"
+                />
+              </div>
+            </template>
+          </UInput>
+        </div>
+      </form>
+    </motion.div>
+  </AnimatePresence>
+</template>

package/modules/assistant/runtime/components/AssistantLoading.vue

@@ -0,0 +1,164 @@
+<script setup lang="ts">
+import { motion } from 'motion-v'
+import { useDocusI18n } from '../../../../app/composables/useDocusI18n'
+
+interface ToolCall {
+  toolCallId: string
+  toolName: string
+  args: Record<string, unknown>
+}
+
+const props = defineProps<{
+  text?: string
+  toolCalls?: ToolCall[]
+  isLoading?: boolean
+}>()
+
+const { t } = useDocusI18n()
+
+const messages = computed(() => [
+  t('assistant.loading.searching'),
+  t('assistant.loading.reading'),
+  t('assistant.loading.analyzing'),
+  t('assistant.loading.finding'),
+])
+
+const finishedMessage = computed(() => t('assistant.loading.finished'))
+
+const currentIndex = ref(0)
+const targetText = computed(() => {
+  if (!props.isLoading) {
+    return finishedMessage.value
+  }
+  return props.text || messages.value[currentIndex.value]
+})
+const displayedText = ref(targetText.value)
+
+const chars = 'abcdefghijklmnopqrstuvwxyz'
+
+function scrambleText(from: string, to: string) {
+  const maxLength = Math.max(from.length, to.length)
+  let frame = 0
+  const totalFrames = 15
+
+  const animate = () => {
+    frame++
+    let result = ''
+
+    for (let i = 0; i < maxLength; i++) {
+      const progress = frame / totalFrames
+      const charProgress = progress * maxLength
+
+      if (i < charProgress - 2) {
+        result += to[i] || ''
+      }
+      else if (i < charProgress) {
+        result += chars[Math.floor(Math.random() * chars.length)]
+      }
+      else {
+        result += from[i] || ''
+      }
+    }
+
+    displayedText.value = result
+
+    if (frame < totalFrames) {
+      requestAnimationFrame(animate)
+    }
+    else {
+      displayedText.value = to
+    }
+  }
+
+  requestAnimationFrame(animate)
+}
+
+let textInterval: ReturnType<typeof setInterval> | null = null
+
+watch(targetText, (newText, oldText) => {
+  if (newText !== oldText && newText && oldText) {
+    scrambleText(oldText, newText)
+  }
+})
+
+// Stop text rotation when loading finishes
+watch(() => props.isLoading, (isLoading) => {
+  if (!isLoading && textInterval) {
+    clearInterval(textInterval)
+    textInterval = null
+  }
+})
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getToolLabel(toolName: string, args: any) {
+  const path = args?.path || ''
+
+  if (toolName === 'list-pages') {
+    return t('assistant.toolListPages')
+  }
+
+  if (toolName === 'get-page') {
+    return `${t('assistant.toolReadPage')} ${path || '...'}`
+  }
+
+  return toolName
+}
+
+onMounted(() => {
+  // Text rotation only when loading
+  if (!props.text && props.isLoading) {
+    textInterval = setInterval(() => {
+      currentIndex.value = (currentIndex.value + 1) % messages.value.length
+    }, 3500)
+  }
+})
+
+onUnmounted(() => {
+  if (textInterval) clearInterval(textInterval)
+})
+</script>
+
+<template>
+  <div class="flex flex-col gap-2">
+    <!-- Main loader with matrix and text -->
+    <div class="flex items-center text-xs text-muted overflow-hidden">
+      <motion.div
+        v-if="isLoading"
+        :initial="{ opacity: 1, width: 'auto' }"
+        :exit="{ opacity: 0, width: 0 }"
+        :transition="{ duration: 0.2 }"
+        class="shrink-0 mr-2"
+      >
+        <AssistantMatrix />
+      </motion.div>
+      <motion.span
+        :animate="{ x: 0 }"
+        :transition="{ duration: 0.2 }"
+        class="font-mono tracking-tight"
+      >
+        {{ displayedText }}
+      </motion.span>
+    </div>
+
+    <!-- Tool calls displayed below -->
+    <div
+      v-if="toolCalls?.length"
+      class="flex flex-col gap-1"
+      :class="isLoading ? 'pl-[22px]' : 'pl-0'"
+    >
+      <motion.div
+        v-for="tool in toolCalls"
+        :key="`${tool.toolCallId}-${JSON.stringify(tool.args)}`"
+        :initial="{ opacity: 0, x: -4 }"
+        :animate="{ opacity: 1, x: 0 }"
+        :transition="{ duration: 0.15 }"
+        class="flex items-center gap-1.5"
+      >
+        <span class="size-1 rounded-full bg-current opacity-40" />
+        <span class="text-[11px] text-dimmed truncate max-w-[200px]">
+          {{ getToolLabel(tool.toolName, tool.args) }}
+        </span>
+      </motion.div>
+    </div>
+  </div>
+</template>

package/modules/assistant/runtime/components/AssistantMatrix.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+interface Props {
+  size?: number
+  dotSize?: number
+  gap?: number
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  size: 4,
+  dotSize: 2,
+  gap: 2,
+})
+
+const totalDots = computed(() => props.size * props.size)
+const activeDots = ref<Set<number>>(new Set())
+
+// Patterns for 4x4 grid (indices 0-15)
+// Grid layout:
+//  0  1  2  3
+//  4  5  6  7
+//  8  9 10 11
+// 12 13 14 15
+const patterns = [
+  // Spiral inward
+  [[0], [1], [2], [3], [7], [11], [15], [14], [13], [12], [8], [4], [5], [6], [10], [9]],
+  // Wave horizontal
+  [[0, 4, 8, 12], [1, 5, 9, 13], [2, 6, 10, 14], [3, 7, 11, 15]],
+  // Diamond pulse
+  [[5, 6, 9, 10], [1, 4, 7, 8, 11, 14], [0, 3, 12, 15], [1, 4, 7, 8, 11, 14], [5, 6, 9, 10]],
+  // Loading bar
+  [[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11], [12, 13, 14, 15]],
+  // Corners rotate
+  [[0], [3], [15], [12]],
+  // Cross pulse
+  [[5, 6, 9, 10], [1, 2, 4, 7, 8, 11, 13, 14], [0, 3, 12, 15]],
+  // Snake
+  [[0], [1], [2], [3], [7], [6], [5], [4], [8], [9], [10], [11], [15], [14], [13], [12]],
+  // Diagonal wave
+  [[0], [1, 4], [2, 5, 8], [3, 6, 9, 12], [7, 10, 13], [11, 14], [15]],
+]
+
+let patternIndex = 0
+let stepIndex = 0
+let interval: ReturnType<typeof setInterval> | null = null
+
+function nextStep() {
+  const pattern = patterns[patternIndex]
+  if (!pattern) return
+
+  activeDots.value = new Set(pattern[stepIndex])
+  stepIndex++
+
+  if (stepIndex >= pattern.length) {
+    stepIndex = 0
+    patternIndex = (patternIndex + 1) % patterns.length
+  }
+}
+
+const gridStyle = computed(() => ({
+  display: 'grid',
+  gridTemplateColumns: `repeat(${props.size}, 1fr)`,
+  gap: `${props.gap}px`,
+  width: `${props.size * props.dotSize + (props.size - 1) * props.gap}px`,
+  height: `${props.size * props.dotSize + (props.size - 1) * props.gap}px`,
+}))
+
+const dotStyle = computed(() => ({
+  width: `${props.dotSize}px`,
+  height: `${props.dotSize}px`,
+}))
+
+onMounted(() => {
+  interval = setInterval(nextStep, 120)
+  nextStep()
+})
+
+onUnmounted(() => {
+  if (interval) clearInterval(interval)
+})
+</script>
+
+<template>
+  <div :style="gridStyle">
+    <span
+      v-for="i in totalDots"
+      :key="i"
+      class="rounded-[0.5px] bg-current transition-opacity duration-100"
+      :class="activeDots.has(i - 1) ? 'opacity-100' : 'opacity-20'"
+      :style="dotStyle"
+    />
+  </div>
+</template>