docs-please 0.2.0-beta.0 → 0.2.1-beta.0

package/app/app.config.ts

@@ -1,8 +1,16 @@
 export default defineAppConfig({
   docs: {
     title: 'Documentation',
-    description: 'Documentation site powered by @pleaseai/docs',
+    description: 'Documentation site powered by docs-please',
     url: '',
+    header: {
+      title: '',
+      logo: {
+        light: '',
+        dark: '',
+        alt: '',
+      },
+    },
     github: {
       owner: '',
       name: '',

package/app/assets/css/main.css

@@ -354,11 +354,11 @@
   }
 
   .prose th {
-    @apply border px-4 py-2 text-left font-bold [&[align=center]]:text-center [&[align=right]]:text-right;
+    @apply px-4 py-2 text-left font-bold [&[align=center]]:text-center [&[align=right]]:text-right;
   }
 
   .prose td {
-    @apply border px-4 py-2 text-left [&[align=center]]:text-center [&[align=right]]:text-right;
+    @apply px-4 py-2 text-left [&[align=center]]:text-center [&[align=right]]:text-right;
   }
 
   .prose hr {

package/app/components/app/AppHeader.vue

@@ -1,57 +1,112 @@
 <script setup lang="ts">
-import { Moon, Sun } from 'lucide-vue-next'
+import { Github, Moon, Sun } from 'lucide-vue-next'
 import { Button } from '~/components/ui/button'
+import { Separator } from '~/components/ui/separator'
 
+const appConfig = useAppConfig()
 const colorMode = useColorMode()
 
+const isDark = computed(() => colorMode.value === 'dark')
+
 function toggleColorMode() {
-  colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
+  colorMode.preference = isDark.value ? 'light' : 'dark'
 }
 
-const appConfig = useAppConfig()
-const title = computed(() => appConfig.docs?.title || 'Docs')
+const links = computed(() => {
+  const result = []
+  if (appConfig.docs?.github?.url) {
+    result.push({
+      icon: Github,
+      to: appConfig.docs.github.url,
+      target: '_blank',
+      ariaLabel: 'GitHub',
+    })
+  }
+  return result
+})
 </script>
 
 <template>
   <header class="sticky top-0 z-50 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+    <!-- Skip to main content link for accessibility -->
+    <a
+      href="#main-content"
+      class="sr-only focus:not-sr-only focus:absolute focus:left-2 focus:top-2 focus:z-[100] focus:rounded-md focus:border focus:bg-background focus:px-4 focus:py-2"
+    >
+      Skip to main content
+    </a>
+
     <div class="container flex h-14 items-center">
       <!-- Logo -->
-      <div class="mr-4 flex">
-        <NuxtLink
-          to="/"
-          class="flex items-center space-x-2"
-        >
-          <span class="font-bold">{{ title }}</span>
-        </NuxtLink>
+      <NuxtLink
+        to="/"
+        class="mr-4 flex items-center gap-2"
+        :aria-label="`${appConfig.docs?.title || 'Home'} - Go to homepage`"
+      >
+        <AppHeaderLogo class="h-6 w-auto shrink-0" />
+      </NuxtLink>
+
+      <!-- Center (Search) -->
+      <div class="hidden flex-1 justify-center lg:flex">
+        <AppHeaderCenter />
       </div>
 
-      <!-- Navigation -->
-      <nav class="flex flex-1 items-center space-x-6 text-sm font-medium">
-        <NuxtLink
-          to="/docs"
-          class="text-muted-foreground transition-colors hover:text-foreground"
-        >
-          Documentation
-        </NuxtLink>
-      </nav>
-
-      <!-- Actions -->
-      <div class="flex items-center space-x-2">
-        <Button
-          variant="ghost"
-          size="icon"
-          @click="toggleColorMode"
-        >
-          <Sun
-            v-if="colorMode.value === 'dark'"
-            class="size-5"
-          />
-          <Moon
-            v-else
-            class="size-5"
+      <!-- Spacer for mobile -->
+      <div class="flex-1 lg:hidden" />
+
+      <!-- Right Actions -->
+      <div class="flex items-center gap-1">
+        <!-- Search button (mobile) -->
+        <AppHeaderSearch class="lg:hidden" />
+
+        <!-- Color mode toggle -->
+        <ClientOnly>
+          <Button
+            variant="ghost"
+            size="icon"
+            @click="toggleColorMode"
+          >
+            <Moon
+              v-if="isDark"
+              class="size-5"
+            />
+            <Sun
+              v-else
+              class="size-5"
+            />
+            <span class="sr-only">Toggle theme</span>
+          </Button>
+
+          <template #fallback>
+            <div class="size-8 animate-pulse rounded-md bg-muted" />
+          </template>
+        </ClientOnly>
+
+        <!-- External links (GitHub, etc.) -->
+        <template v-if="links.length">
+          <Separator
+            orientation="vertical"
+            class="mx-1 h-6"
           />
-          <span class="sr-only">Toggle theme</span>
-        </Button>
+          <Button
+            v-for="link in links"
+            :key="link.to"
+            variant="ghost"
+            size="icon"
+            as-child
+          >
+            <a
+              :href="link.to"
+              :target="link.target"
+              :aria-label="link.ariaLabel"
+            >
+              <component
+                :is="link.icon"
+                class="size-5"
+              />
+            </a>
+          </Button>
+        </template>
       </div>
     </div>
   </header>

package/app/components/app/AppHeaderCenter.vue

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

package/app/components/app/AppHeaderLogo.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const colorMode = useColorMode()
+
+const logoSrc = computed(() => {
+  const header = appConfig.docs?.header
+  if (!header?.logo) return null
+
+  if (colorMode.value === 'dark' && header.logo.dark) {
+    return header.logo.dark
+  }
+  return header.logo.light || header.logo.dark
+})
+
+const logoAlt = computed(() => {
+  return appConfig.docs?.header?.logo?.alt || appConfig.docs?.title || 'Logo'
+})
+
+const title = computed(() => {
+  return appConfig.docs?.header?.title || appConfig.docs?.title || 'Documentation'
+})
+</script>
+
+<template>
+  <ClientOnly>
+    <img
+      v-if="logoSrc"
+      :src="logoSrc"
+      :alt="logoAlt"
+      class="h-6 w-auto shrink-0"
+    >
+    <span
+      v-else
+      class="font-bold"
+    >
+      {{ title }}
+    </span>
+
+    <template #fallback>
+      <span class="font-bold">{{ title }}</span>
+    </template>
+  </ClientOnly>
+</template>

package/app/components/app/AppHeaderSearch.vue

@@ -0,0 +1,3 @@
+<template>
+  <AppSearchButton collapsed />
+</template>

package/app/components/app/AppSearch.vue

@@ -0,0 +1,189 @@
+<script setup lang="ts">
+import { ArrowRight, FileText, Monitor, Moon, Sun } from 'lucide-vue-next'
+import { useFuse } from '@vueuse/integrations/useFuse'
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from '~/components/ui/command'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '~/components/ui/dialog'
+import { flattenNavigation, useContentSearch } from '~/composables/useContentSearch'
+
+const router = useRouter()
+const colorMode = useColorMode()
+const { open } = useContentSearch()
+const { data: navigation } = await useNavigation()
+
+const searchTerm = ref('')
+
+// Flatten navigation for search
+const searchItems = computed(() => flattenNavigation(navigation.value))
+
+// Fuse search
+const { results } = useFuse(searchTerm, searchItems, {
+  fuseOptions: {
+    keys: ['label', 'prefix'],
+    threshold: 0.3,
+  },
+  matchAllWhenSearchEmpty: true,
+})
+
+const filteredItems = computed(() => {
+  if (!searchTerm.value) {
+    return searchItems.value
+  }
+  return results.value.map(r => r.item)
+})
+
+// Group items by prefix (parent title)
+const groupedItems = computed(() => {
+  const groups = new Map<string, typeof searchItems.value>()
+
+  for (const item of filteredItems.value) {
+    const groupKey = item.prefix || 'Pages'
+    if (!groups.has(groupKey)) {
+      groups.set(groupKey, [])
+    }
+    groups.get(groupKey)!.push(item)
+  }
+
+  return Array.from(groups.entries()).map(([label, items]) => ({
+    label,
+    items,
+  }))
+})
+
+function runCommand(command: () => unknown) {
+  open.value = false
+  searchTerm.value = ''
+  command()
+}
+
+function handleColorMode(mode: 'system' | 'light' | 'dark') {
+  runCommand(() => {
+    colorMode.preference = mode
+  })
+}
+
+// Keyboard shortcut
+onMounted(() => {
+  const down = (e: KeyboardEvent) => {
+    if ((e.key === 'k' && (e.metaKey || e.ctrlKey)) || e.key === '/') {
+      if (
+        (e.target instanceof HTMLElement && e.target.isContentEditable)
+        || e.target instanceof HTMLInputElement
+        || e.target instanceof HTMLTextAreaElement
+        || e.target instanceof HTMLSelectElement
+      ) {
+        return
+      }
+      e.preventDefault()
+      open.value = !open.value
+    }
+  }
+  document.addEventListener('keydown', down)
+  onUnmounted(() => document.removeEventListener('keydown', down))
+})
+</script>
+
+<template>
+  <Dialog v-model:open="open">
+    <DialogContent
+      class="overflow-hidden p-0 shadow-lg"
+      :show-close-button="false"
+    >
+      <DialogHeader class="sr-only">
+        <DialogTitle>Search documentation</DialogTitle>
+        <DialogDescription>Search for pages in the documentation</DialogDescription>
+      </DialogHeader>
+      <Command
+        v-model:search-term="searchTerm"
+        class="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:size-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:size-5"
+      >
+        <CommandInput placeholder="Search documentation..." />
+        <CommandList class="max-h-[300px]">
+          <CommandEmpty>No results found.</CommandEmpty>
+
+          <!-- Navigation groups -->
+          <CommandGroup
+            v-for="group in groupedItems"
+            :key="group.label"
+            :heading="group.label"
+          >
+            <CommandItem
+              v-for="item in group.items"
+              :key="item.id"
+              :value="item.label"
+              @select="() => runCommand(() => router.push(item.to!))"
+            >
+              <FileText
+                v-if="item.isDoc"
+                class="mr-2 size-4"
+              />
+              <ArrowRight
+                v-else
+                class="mr-2 size-4"
+              />
+              <span>{{ item.label }}</span>
+            </CommandItem>
+          </CommandGroup>
+
+          <CommandSeparator />
+
+          <!-- Theme group -->
+          <CommandGroup heading="Theme">
+            <CommandItem
+              value="System theme"
+              @select="() => handleColorMode('system')"
+            >
+              <Monitor class="mr-2 size-4" />
+              <span>System</span>
+              <span
+                v-if="colorMode.preference === 'system'"
+                class="ml-auto text-xs text-muted-foreground"
+              >
+                Active
+              </span>
+            </CommandItem>
+            <CommandItem
+              value="Light theme"
+              @select="() => handleColorMode('light')"
+            >
+              <Sun class="mr-2 size-4" />
+              <span>Light</span>
+              <span
+                v-if="colorMode.preference === 'light'"
+                class="ml-auto text-xs text-muted-foreground"
+              >
+                Active
+              </span>
+            </CommandItem>
+            <CommandItem
+              value="Dark theme"
+              @select="() => handleColorMode('dark')"
+            >
+              <Moon class="mr-2 size-4" />
+              <span>Dark</span>
+              <span
+                v-if="colorMode.preference === 'dark'"
+                class="ml-auto text-xs text-muted-foreground"
+              >
+                Active
+              </span>
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </Command>
+    </DialogContent>
+  </Dialog>
+</template>

package/app/components/app/AppSearchButton.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { Search } from 'lucide-vue-next'
+import { Button } from '~/components/ui/button'
+import { Kbd, KbdGroup } from '~/components/ui/kbd'
+import { useContentSearch } from '~/composables/useContentSearch'
+
+interface Props {
+  collapsed?: boolean
+}
+
+withDefaults(defineProps<Props>(), {
+  collapsed: false,
+})
+
+const { open } = useContentSearch()
+
+const isMac = computed(() => {
+  if (import.meta.server) return true
+  return navigator.platform.toUpperCase().includes('MAC')
+})
+</script>
+
+<template>
+  <Button
+    v-if="collapsed"
+    variant="ghost"
+    size="icon"
+    aria-label="Search documentation"
+    @click="open = true"
+  >
+    <Search class="size-5" />
+  </Button>
+  <Button
+    v-else
+    variant="outline"
+    class="relative h-8 w-full max-w-sm justify-start bg-muted/50 text-sm font-normal text-muted-foreground shadow-none sm:pr-12 md:w-48 lg:w-56 xl:w-64"
+    @click="open = true"
+  >
+    <Search class="mr-2 size-4" />
+    <span class="hidden lg:inline-flex">Search documentation...</span>
+    <span class="inline-flex lg:hidden">Search...</span>
+    <div class="absolute right-1.5 top-1.5 hidden gap-1 sm:flex">
+      <ClientOnly>
+        <KbdGroup>
+          <Kbd class="border">{{ isMac ? '⌘' : 'Ctrl' }}</Kbd>
+          <Kbd class="border">K</Kbd>
+        </KbdGroup>
+      </ClientOnly>
+    </div>
+  </Button>
+</template>

package/app/components/content/Accordion.vue

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+import type { HTMLAttributes, VNode } from 'vue'
+import { computed, onBeforeUpdate, ref } from 'vue'
+import { cn } from '~/lib/utils'
+import {
+  Accordion as UIAccordion,
+  AccordionContent as UIAccordionContent,
+  AccordionItem as UIAccordionItem,
+  AccordionTrigger as UIAccordionTrigger,
+} from '~/components/ui/accordion'
+
+export interface AccordionProps {
+  /**
+   * Accordion type - single or multiple items open at once.
+   * @default 'multiple'
+   */
+  type?: 'single' | 'multiple'
+  /**
+   * Default open items (comma-separated indices for multiple, single index for single).
+   * @example '0,1' or '0'
+   */
+  defaultValue?: string
+  class?: HTMLAttributes['class']
+}
+
+const props = withDefaults(defineProps<AccordionProps>(), {
+  type: 'multiple',
+})
+
+const slots = defineSlots<{
+  default(): VNode[]
+}>()
+
+const rerenderCount = ref(1)
+
+interface AccordionItemData {
+  value: string
+  label: string
+  icon?: string
+  component: VNode
+}
+
+const items = computed<AccordionItemData[]>(() => {
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  rerenderCount.value
+
+  let counter = 0
+  function transformSlot(slot: VNode): AccordionItemData | null {
+    if (typeof slot.type === 'symbol') {
+      return null
+    }
+
+    const slotProps = slot.props as { label?: string, icon?: string } | null
+    if (!slotProps?.label) {
+      return null
+    }
+
+    return {
+      value: String(counter++),
+      label: slotProps.label,
+      icon: slotProps.icon,
+      component: slot,
+    }
+  }
+
+  function flattenSlots(slot: VNode): VNode[] {
+    if (typeof slot.type === 'symbol') {
+      const children = slot.children as VNode[] | null
+      return children?.flatMap(flattenSlots) ?? []
+    }
+    return [slot]
+  }
+
+  return slots.default?.()?.flatMap(flattenSlots).map(transformSlot).filter((item): item is AccordionItemData => item !== null) || []
+})
+
+const defaultValue = computed(() => {
+  if (props.defaultValue) {
+    return props.type === 'multiple'
+      ? props.defaultValue.split(',').map(v => v.trim())
+      : props.defaultValue
+  }
+  return props.type === 'multiple' ? [] : undefined
+})
+
+onBeforeUpdate(() => rerenderCount.value++)
+</script>
+
+<template>
+  <UIAccordion
+    :type="type"
+    :default-value="defaultValue"
+    :class="cn('mt-6', props.class)"
+    collapsible
+  >
+    <UIAccordionItem
+      v-for="item in items"
+      :key="item.value"
+      :value="item.value"
+    >
+      <UIAccordionTrigger class="items-center">
+        <div class="flex items-center text-left">
+          <Icon
+            v-if="item.icon"
+            :name="item.icon"
+            class="size-4 mr-2 shrink-0"
+            aria-hidden="true"
+          />
+          <span>{{ item.label }}</span>
+        </div>
+      </UIAccordionTrigger>
+      <UIAccordionContent class="text-left">
+        <component :is="item.component" />
+      </UIAccordionContent>
+    </UIAccordionItem>
+  </UIAccordion>
+</template>

package/app/components/content/AccordionItem.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import type { HTMLAttributes, VNode } from 'vue'
+import { cn } from '~/lib/utils'
+
+export interface AccordionItemProps {
+  /**
+   * The label displayed in the accordion trigger.
+   */
+  label: string
+  /**
+   * Optional icon name for the accordion item.
+   */
+  icon?: string
+  class?: HTMLAttributes['class']
+}
+
+const props = defineProps<AccordionItemProps>()
+defineSlots<{
+  default(): VNode[]
+}>()
+</script>
+
+<template>
+  <div :class="cn('text-left', props.class)">
+    <slot />
+  </div>
+</template>

package/app/components/content/Badge.vue

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import type { HTMLAttributes, VNode } from 'vue'
+import { cn } from '~/lib/utils'
+
+export interface BadgeProps {
+  /**
+   * Badge color variant.
+   * @default 'primary'
+   */
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'destructive' | 'muted'
+  class?: HTMLAttributes['class']
+}
+
+const props = withDefaults(defineProps<BadgeProps>(), {
+  color: 'primary',
+})
+
+defineSlots<{
+  default(): VNode[]
+}>()
+
+const colorClasses: Record<string, string> = {
+  primary: 'bg-primary/10 text-primary border-primary/20',
+  secondary: 'bg-secondary text-secondary-foreground border-secondary',
+  success: 'bg-green-500/10 text-green-600 border-green-500/20 dark:text-green-400',
+  warning: 'bg-yellow-500/10 text-yellow-600 border-yellow-500/20 dark:text-yellow-400',
+  destructive: 'bg-destructive/10 text-destructive border-destructive/20',
+  muted: 'bg-muted text-muted-foreground border-border',
+}
+</script>
+
+<template>
+  <span
+    :class="cn(
+      'inline-flex items-center rounded-md border px-2 py-0.5 text-xs font-medium',
+      colorClasses[color],
+      props.class,
+    )"
+  >
+    <slot mdc-unwrap="p" />
+  </span>
+</template>