@kirchdev/duxt 0.1.0

package/app/components/DuxtSearch.vue

@@ -0,0 +1,271 @@
+<script setup lang="ts">
+// Two roots — the trigger and the dialog — so Vue cannot decide which one
+// inherits a class from the parent and drops it with a warning. The trigger
+// takes them explicitly.
+defineOptions({ inheritAttrs: false });
+
+import type { DuxtSearchHit } from '@duxt/composables/useDuxtSearch';
+
+// Full-text search over EVERY source, not just the one being read. Content
+// builds the index at build time and queries it with SQLite's FTS, so the
+// ranking is the database's rather than a substring match of ours — and there
+// is no search service to run. The merge across sources, and why the results
+// are ranked together rather than grouped per repository, is in
+// `useDuxtSearch`.
+//
+// The index is fetched on first open, not shipped with every page: a docs site
+// should not pay for search on a page nobody searches from.
+const open = ref(false);
+const query = ref('');
+const router = useRouter();
+const localeLink = useDuxtLink();
+
+const { search, init, labelled } = useDuxtSearch();
+
+const results = ref<DuxtSearchHit[]>([]);
+
+/** True while the list shows near-misses rather than actual matches. */
+const approximate = ref(false);
+
+let pending: ReturnType<typeof setTimeout> | undefined;
+
+// Two awaits per keystroke, so a slow answer could land after a newer one and
+// overwrite it. Each run takes a number and drops its result if the term moved
+// on in the meantime.
+let run = 0;
+
+// Debounced by hand rather than through VueUse: one timer is not worth another
+// dependency in a layer a consumer installs.
+watch(query, (term) => {
+  clearTimeout(pending);
+  pending = setTimeout(async () => {
+    const current = ++run;
+
+    const settle = (hits: DuxtSearchHit[], fuzzy: boolean) => {
+      if (current !== run) return;
+      results.value = hits;
+      approximate.value = fuzzy;
+    };
+
+    if (!term.trim()) return settle([], false);
+
+    const found = await search(term, 20);
+    settle(found.hits, found.approximate);
+  }, 120);
+});
+
+const duxt = useDuxtConfig();
+const { recent, load } = useRecentPages();
+
+/** Which section a path belongs to, for grouping the hits. */
+function sectionOf(path: string) {
+  return (
+    duxt.sections?.find((section) => section.to && path.startsWith(section.to))
+      ?.label ?? 'Documentation'
+  );
+}
+
+/**
+ * Hits grouped by section rather than by page. Grouping by page produced one
+ * heading per result; a section groups many, which is what a heading is for —
+ * and the reader already thinks in sections, because the navbar shows them.
+ */
+const grouped = computed(() => {
+  // With several sources the list is ONE ranked list with a badge per hit —
+  // grouping it by section would re-sort exactly the ranking the merge just
+  // produced. See `useDuxtSearch` for why ranking beats grouping here.
+  if (labelled.value) {
+    return [{ label: '', hits: results.value }];
+  }
+
+  const bySection = new Map<string, DuxtSearchHit[]>();
+
+  for (const hit of results.value) {
+    // A section label may be configured per locale; the group key has to be a
+    // plain string, and by this point useDuxtConfig has resolved it.
+    const label = asText(sectionOf(hit.id)) ?? 'Documentation';
+    bySection.set(label, [...(bySection.get(label) ?? []), hit]);
+  }
+
+  return [...bySection.entries()].map(([label, hits]) => ({ label, hits }));
+});
+
+async function show() {
+  load();
+  open.value = true;
+  await init();
+}
+
+function go(id: string) {
+  open.value = false;
+  query.value = '';
+  results.value = [];
+  approximate.value = false;
+  router.push(localeLink(id)!);
+}
+
+/** Where a hit sits: the page, and the headings above it inside that page. */
+function context(result: DuxtSearchSection) {
+  const page = result.titles[0];
+  const between = result.titles.slice(1);
+
+  return [page, ...between].filter(Boolean).join(' › ');
+}
+
+onMounted(() => {
+  const handler = (event: KeyboardEvent) => {
+    if (event.key.toLowerCase() === 'k' && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault();
+
+      if (open.value) {
+        open.value = false;
+      } else {
+        void show();
+      }
+    }
+  };
+
+  window.addEventListener('keydown', handler);
+  onBeforeUnmount(() => window.removeEventListener('keydown', handler));
+});
+</script>
+
+<template>
+  <UiButton
+    v-bind="$attrs"
+    variant="outline"
+    size="sm"
+    class="w-full justify-start gap-2 text-muted-foreground"
+    @click="show"
+  >
+    <Icon name="lucide:search" class="size-4" />
+    <span class="text-sm">{{ $t('duxt.search.label') }}</span>
+    <kbd
+      class="ml-auto hidden rounded border bg-muted px-1.5 font-mono text-[10px] sm:inline-block"
+    >
+      ⌘K
+    </kbd>
+  </UiButton>
+
+  <UiCommandDialog v-model:open="open">
+    <!-- The input is ours, not CommandInput: that one writes into Command's own
+         filterState, and Command would then score the list a second time
+         against rendered text — dropping entries that mounted after the term
+         changed. Leaving its state empty keeps one filter in charge, the
+         database's. It also means CommandEmpty never renders, so the empty
+         state is ours too.
+
+         No clear button: DialogContent already draws a close X, and two of
+         them in the same corner is one too many. -->
+    <div class="flex items-center gap-2 border-b px-3">
+      <Icon
+        name="lucide:search"
+        class="size-4 shrink-0 text-muted-foreground"
+      />
+      <input
+        v-model="query"
+        class="flex h-11 w-full bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+        :placeholder="$t('duxt.search.placeholder')"
+        autofocus
+      />
+    </div>
+
+    <UiCommandList class="max-h-[60vh]">
+      <!-- An empty box is a dead end. Without a term the dialog offers the
+           sections as entry points and, once there is any history, the pages
+           this reader came from — which is what they are most likely after. -->
+      <template v-if="!query.trim()">
+        <UiCommandGroup
+          v-if="recent.length"
+          :heading="$t('duxt.search.recent')"
+        >
+          <UiCommandItem
+            v-for="page in recent"
+            :key="page.path"
+            :value="`recent ${page.path}`"
+            class="gap-2"
+            @select="go(page.path)"
+          >
+            <Icon
+              name="lucide:history"
+              class="size-3.5 shrink-0 text-muted-foreground"
+            />
+            <span class="truncate">{{ page.title }}</span>
+            <span class="ml-auto truncate pl-3 text-xs text-muted-foreground">
+              {{ sectionOf(page.path) }}
+            </span>
+          </UiCommandItem>
+        </UiCommandGroup>
+
+        <UiCommandGroup :heading="$t('duxt.search.sections')">
+          <UiCommandItem
+            v-for="section in duxt.sections ?? []"
+            :key="section.to"
+            :value="`section ${section.label}`"
+            class="gap-2"
+            @select="go(section.to ?? '/')"
+          >
+            <Icon
+              :name="section.icon ?? 'lucide:book-open'"
+              class="size-3.5 shrink-0 text-muted-foreground"
+            />
+            <span class="truncate">{{ section.label }}</span>
+          </UiCommandItem>
+        </UiCommandGroup>
+      </template>
+
+      <div
+        v-else-if="!results.length"
+        class="flex flex-col items-center gap-2 py-12 text-sm text-muted-foreground"
+      >
+        <Icon name="lucide:search-x" class="size-5 opacity-60" />
+        {{ $t('duxt.search.empty', { query }) }}
+      </div>
+
+      <!-- Say so when the exact search came up empty, otherwise a near-miss
+           reads as a match and the reader wonders why their term is missing
+           from the result. -->
+      <div
+        v-if="approximate"
+        class="flex items-center gap-2 px-3 pt-3 pb-1 text-xs text-muted-foreground"
+      >
+        <Icon name="lucide:sparkles" class="size-3.5 shrink-0" />
+        {{ $t('duxt.search.approximate', { query }) }}
+      </div>
+
+      <!-- One line per hit, grouped by section: the page is context on the
+           right, not a heading of its own. -->
+      <UiCommandGroup
+        v-for="group in grouped"
+        :key="group.label"
+        :heading="group.label || undefined"
+      >
+        <UiCommandItem
+          v-for="hit in group.hits"
+          :key="hit.id"
+          :value="hit.id"
+          class="gap-2"
+          @select="go(hit.id)"
+        >
+          <Icon
+            :name="hit.level > 1 ? 'lucide:hash' : 'lucide:file-text'"
+            class="size-3.5 shrink-0 text-muted-foreground"
+          />
+          <span class="truncate">{{ hit.title }}</span>
+          <span class="ml-auto truncate pl-3 text-xs text-muted-foreground">
+            {{ context(hit) }}
+          </span>
+          <!-- Which repository and version this came out of. Only drawn where
+               there is more than one, so a single-source site sees nothing. -->
+          <UiBadge
+            v-if="hit.source"
+            variant="secondary"
+            class="shrink-0 font-mono text-[10px]"
+          >
+            {{ hit.source.label }}
+          </UiBadge>
+        </UiCommandItem>
+      </UiCommandGroup>
+    </UiCommandList>
+  </UiCommandDialog>
+</template>

package/app/components/DuxtSections.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+// The second navbar row: top-level sections of the documentation, each an
+// entry point into a part of the tree. nuxt.com's docs read this way, and it
+// keeps the sidebar showing one section instead of everything at once.
+const path = useDuxtPath();
+const localeLink = useDuxtLink();
+
+// Whether the row shows at all is shared with the layouts, which offset their
+// sticky columns by the header this row is part of — see `useDuxtSectionRow`.
+const { sections, visible } = useDuxtSectionRow();
+
+/**
+ * ONE entry is lit, never two — see `currentSection`. An area whose parts nest
+ * (`/demo` and `/demo/api`) had both chips marked, and a row that says the
+ * reader is in two places at once says nothing.
+ */
+const active = computed(() => currentSection(sections.value, path.value));
+
+function isActive(to?: string) {
+  return Boolean(to && to === active.value?.to);
+}
+
+/**
+ * A section is rarely the page itself — it is the branch the page sits in. So
+ * the exact match announces `page` and an ancestor announces `true`, which is
+ * the distinction `aria-current` exists to make.
+ */
+function current(to?: string) {
+  if (!isActive(to)) return undefined;
+  return path.value === to ? 'page' : 'true';
+}
+</script>
+
+<template>
+  <!-- Hidden below lg: the mobile sheet lists the same sections, and a row
+       that scrolls sideways under the header is worse than no row. -->
+  <!-- `top-14` is one pixel short: the header is h-14 PLUS its own border-b,
+       so the row parked over that border and the two swapped places by a pixel
+       as the browser rounded the scroll offset. -->
+  <div
+    v-if="visible"
+    class="sticky top-[calc(3.5rem_+_1px)] z-40 hidden border-b bg-background/95 backdrop-blur-md lg:block"
+  >
+    <nav
+      class="mx-auto flex max-w-[90rem] items-center gap-1 overflow-x-auto px-4 lg:px-8"
+      :aria-label="$t('duxt.nav.sections')"
+    >
+      <NuxtLink
+        v-for="section in sections"
+        :key="section.to"
+        :to="localeLink(section.to)"
+        :aria-current="current(section.to)"
+        class="my-1.5 flex shrink-0 items-center gap-2 rounded-md px-3 py-1.5 text-sm transition-colors"
+        :class="
+          isActive(section.to)
+            ? 'bg-accent font-medium text-foreground'
+            : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
+        "
+      >
+        <Icon v-if="section.icon" :name="section.icon" class="size-4" />
+        {{ section.label }}
+      </NuxtLink>
+    </nav>
+  </div>
+</template>

package/app/components/DuxtShortcuts.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+/**
+ * The shortcut sheet, on `?`.
+ *
+ * Its list is `duxtShortcuts`, the same array the handlers match against, so
+ * the sheet cannot come to advertise a key nothing binds.
+ */
+const open = ref(false);
+
+onDuxtShortcut(
+  (event) => event.key === '?' && !event.metaKey && !event.ctrlKey,
+  () => (open.value = !open.value)
+);
+</script>
+
+<template>
+  <UiDialog v-model:open="open">
+    <UiDialogContent class="sm:max-w-sm">
+      <UiDialogHeader>
+        <UiDialogTitle>{{ $t('duxt.shortcuts.title') }}</UiDialogTitle>
+        <UiDialogDescription class="sr-only">
+          {{ $t('duxt.shortcuts.title') }}
+        </UiDialogDescription>
+      </UiDialogHeader>
+
+      <ul class="flex flex-col gap-2 text-sm">
+        <li
+          v-for="shortcut in duxtShortcuts"
+          :key="shortcut.label"
+          class="flex items-center justify-between gap-4"
+        >
+          <span>{{ $t(shortcut.label) }}</span>
+          <span class="flex gap-1">
+            <kbd
+              v-for="key in shortcut.keys"
+              :key="key"
+              class="rounded border bg-muted px-1.5 py-0.5 font-mono text-xs"
+            >
+              {{ key }}
+            </kbd>
+          </span>
+        </li>
+      </ul>
+    </UiDialogContent>
+  </UiDialog>
+</template>

package/app/components/DuxtSkipLink.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+/**
+ * The first focusable element on the page.
+ *
+ * Without it every page change means tabbing through the header, the section
+ * row and the whole sidebar before the first word of the text. Invisible until
+ * focused — `sr-only` collapses it to a single pixel, and the focus state puts
+ * it back on screen above everything else.
+ *
+ * The click is handled rather than left to the hash, because the browser only
+ * moves FOCUS to a fragment target that can hold it. Moving it here keeps the
+ * URL clean and works whether or not `<main>` carries a tabindex.
+ */
+const target = '#duxt-main';
+
+function jump(event: MouseEvent) {
+  const main = document.querySelector<HTMLElement>(target);
+  if (!main) return;
+
+  event.preventDefault();
+  main.focus();
+  main.scrollIntoView();
+}
+</script>
+
+<template>
+  <a
+    :href="target"
+    class="sr-only rounded-md bg-background px-4 py-2 text-sm font-medium ring-2 ring-ring focus:not-sr-only focus:fixed focus:top-3 focus:left-3 focus:z-100"
+    @click="jump"
+  >
+    {{ $t('duxt.nav.skip') }}
+  </a>
+</template>

package/app/components/DuxtToc.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+interface TocLink {
+  id: string;
+  text: string;
+  depth: number;
+  children?: TocLink[];
+}
+
+const props = defineProps<{ links: TocLink[] }>();
+
+const duxt = useDuxtConfig();
+const localeLink = useDuxtLink();
+
+// Flat list of every id, in document order, for the observer to watch.
+const ids = computed(() =>
+  props.links.flatMap((link) => [
+    link.id,
+    ...(link.children ?? []).map((child) => child.id)
+  ])
+);
+
+const active = useActiveHeading(ids);
+</script>
+
+<template>
+  <div class="space-y-8 text-sm">
+    <nav v-if="links?.length" :aria-label="$t('duxt.toc.title')">
+      <p class="mb-3 font-medium">{{ $t('duxt.toc.title') }}</p>
+      <ul class="space-y-1 border-l">
+        <li v-for="link in links" :key="link.id">
+          <a
+            :href="`#${link.id}`"
+            class="-ml-px block border-l py-1 pl-4 transition-colors"
+            :class="
+              active === link.id
+                ? 'border-primary text-foreground'
+                : 'border-transparent text-muted-foreground hover:border-primary/60 hover:text-foreground'
+            "
+          >
+            {{ link.text }}
+          </a>
+          <ul v-if="link.children?.length">
+            <li v-for="child in link.children" :key="child.id">
+              <a
+                :href="`#${child.id}`"
+                class="-ml-px block border-l py-1 pl-7 transition-colors"
+                :class="
+                  active === child.id
+                    ? 'border-primary text-foreground'
+                    : 'border-transparent text-muted-foreground hover:border-primary/60 hover:text-foreground'
+                "
+              >
+                {{ child.text }}
+              </a>
+            </li>
+          </ul>
+        </li>
+      </ul>
+    </nav>
+
+    <!-- The fixed link block that belongs on every page, configured once. -->
+    <nav
+      v-if="duxt.aside?.links?.length"
+      :aria-label="duxt.aside.title ?? 'Community'"
+    >
+      <p class="mb-3 font-medium">{{ duxt.aside.title ?? 'Community' }}</p>
+      <ul class="space-y-2">
+        <li v-for="link in duxt.aside.links" :key="link.to">
+          <NuxtLink
+            :to="localeLink(link.to)"
+            :target="link.external ? '_blank' : undefined"
+            class="flex items-center gap-2 text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <Icon v-if="link.icon" :name="link.icon" class="size-4" />
+            {{ link.label }}
+            <Icon
+              v-if="link.external"
+              name="lucide:arrow-up-right"
+              class="size-3 opacity-50"
+            />
+          </NuxtLink>
+        </li>
+      </ul>
+    </nav>
+  </div>
+</template>

package/app/components/DuxtTranslationBanner.vue

@@ -0,0 +1,64 @@
+<script setup lang="ts">
+/**
+ * The visible half of a missing translation.
+ *
+ * `noindex` and the canonical in `[...slug].vue` tell a crawler that this page
+ * is not a German page; they tell the reader nothing, and the reader is the one
+ * looking at English text on a URL that promised their language. Silently
+ * serving the fallback is what Docusaurus and VitePress do, and it is why a
+ * stale or absent translation there is invisible to everyone except the person
+ * reading it.
+ *
+ * A 404 would be the other option and the worse one: it punishes a reader for a
+ * gap the writer left.
+ */
+const props = defineProps<{
+  /** The locale actually served; absent means the untranslated original. */
+  from?: string;
+}>();
+
+const { locales, defaultLocale } = useI18n();
+
+/**
+ * The language's own name, not its code.
+ *
+ * `nuxt.config.ts` carries the endonym on every locale — each language written
+ * in itself — because that is what a language switcher must show, and it is
+ * what this sentence needs too.
+ */
+const languageOf = (code: string | undefined) =>
+  locales.value.find((entry) =>
+    typeof entry === 'string' ? entry === code : entry.code === code
+  );
+
+const shown = computed(() => {
+  const entry = languageOf(props.from ?? defaultLocale);
+  return typeof entry === 'string' ? entry : (entry?.name ?? entry?.code ?? '');
+});
+</script>
+
+<template>
+  <!-- Same shape as DuxtVersionBanner, deliberately: a reader learns what a
+       bordered notice above the title means once, and a second style for a
+       second kind of notice is one style too many. Sky, because this is
+       information about the page rather than a warning about its content. -->
+  <UiAlert
+    role="status"
+    class="mb-6 flex items-start gap-2.5 rounded-md border border-l-2 border-l-sky-500 bg-muted/30 px-3 py-2.5"
+  >
+    <Icon
+      name="lucide:languages"
+      class="mt-[3px] size-4 shrink-0 text-sky-500"
+    />
+
+    <div class="min-w-0 flex-1">
+      <UiAlertTitle class="mb-0.5 font-medium text-foreground">
+        {{ $t('duxt.page.untranslated.title') }}
+      </UiAlertTitle>
+
+      <UiAlertDescription class="text-muted-foreground">
+        {{ $t('duxt.page.untranslated.description', { language: shown }) }}
+      </UiAlertDescription>
+    </div>
+  </UiAlert>
+</template>