@kirchdev/duxt 0.3.4-dev-main.41-23ded41 → 0.3.5-dev-main.43-3310f4b

package/app/components/DuxtSearch.vue

@@ -9,8 +9,8 @@ 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
+// is no search service to run. The merge across sources, and why their locally
+// ranked lists are interleaved rather than compared by score, is in
 // `useDuxtSearch`.
 //
 // The index is fetched on first open, not shipped with every page: a docs site
@@ -21,9 +21,19 @@ const router = useRouter();
 const localeLink = useDuxtLink();
 
 const { search, init, labelled } = useDuxtSearch();
+const analytics = useDuxtAnalytics();
 
 const results = ref<DuxtSearchHit[]>([]);
 
+/**
+ * The term the current results were produced for.
+ *
+ * Not `query`, which moves with every keystroke: the excerpts window themselves
+ * around a literal match, and windowing them against a term newer than the
+ * results already on screen makes the previews jump while the reader types.
+ */
+const matched = ref('');
+
 /** True while the list shows near-misses rather than actual matches. */
 const approximate = ref(false);
 
@@ -42,54 +52,142 @@ watch(query, (term) => {
     const current = ++run;
 
     const settle = (hits: DuxtSearchHit[], fuzzy: boolean) => {
-      if (current !== run) return;
+      if (current !== run) return false;
       results.value = hits;
       approximate.value = fuzzy;
+      matched.value = term;
+      return true;
     };
 
-    if (!term.trim()) return settle([], false);
+    if (!term.trim()) return void settle([], false);
 
     const found = await search(term, 20);
-    settle(found.hits, found.approximate);
+
+    // ONE EVENT PER SETTLED SEARCH, which is why it hangs off `settle` rather
+    // than off the call. The debounce already dropped the keystrokes nobody
+    // finished, and a run whose answer landed after a newer one shows the
+    // reader nothing — reporting it would count a search that never happened.
+    // A search that found nothing is reported like any other: "no result" is
+    // the finding a documentation site most needs out of this.
+    if (settle(found.hits, found.approximate)) {
+      analytics.track({
+        name: 'search',
+        query: term,
+        results: found.hits.length,
+        approximate: found.approximate
+      });
+    }
   }, 120);
 });
 
 const duxt = useDuxtConfig();
-const { recent, load } = useRecentPages();
+const { recent, load } = useRecentPages(duxt.search?.recentPages);
+
+const sections = computed(() => duxt.sections ?? []);
+const sources = computed(() => duxt.resolvedSources ?? []);
 
 /** 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'
+    sectionLabelForPath(path, sections.value, sources.value) ?? 'Documentation'
   );
 }
 
+/**
+ * What each source is CALLED, rather than which URL segment it occupies.
+ *
+ * The context line below used to spell its source slot out of the manifest's
+ * `repo`, which is an address: documentation served at the root had none and
+ * showed nothing, and a source whose segment is an abbreviation showed the
+ * abbreviation. See `sourceDisplayNames` for the ladder, and `sources[].name`
+ * for the one rung a consumer writes.
+ */
+const names = computed(() =>
+  sourceDisplayNames(sources.value, asText(duxt.title) ?? '')
+);
+
+/**
+ * The line under every row's title, and deliberately the SAME line in both
+ * lists.
+ *
+ * "Recently viewed" showed a title and its section, which on a site serving
+ * several editions of one repository is three identical rows — the reader saw
+ * `Harbour` three times and had to open them to find out which was which. A hit
+ * had the opposite problem: it named the page it sat in but not the edition
+ * that page came from. One `section · source/version · route` answers both, and
+ * answering them the same way is what makes the palette scannable.
+ */
+const contextOf = (path: string) =>
+  searchContext(path, sections.value, sources.value, { names: names.value });
+
+const history = computed(() =>
+  recent.value.map((page) => ({ ...page, context: contextOf(page.path) }))
+);
+
 /**
  * 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.
+  const rows = results.value.map((hit) => ({
+    ...hit,
+    // WITHOUT the source slot wherever a caption above the run already states
+    // it — see `searchRows`. The section and the route stay, because those are
+    // the row's own and are what tell two editions of one title apart.
+    context: searchContext(hit.id, sections.value, sources.value, {
+      names: names.value,
+      source: !labelled.value
+    }),
+    // A title and a route say where a result IS; they do not say whether it
+    // answers the question, which is the judgement made before opening a page.
+    excerpt: searchExcerpt(hit.content, matched.value)
+  }));
+
+  // With several sources the list is ONE ranked list whose rows say where they
+  // came from — grouping it by section would re-sort exactly the ranking the
+  // merge just produced. See `useDuxtSearch` for why ranking beats grouping.
   if (labelled.value) {
-    return [{ label: '', hits: results.value }];
+    return [{ label: '', hits: rows }];
   }
 
-  const bySection = new Map<string, DuxtSearchHit[]>();
+  const bySection = new Map<string, typeof rows>();
 
-  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';
+  for (const hit of rows) {
+    const label = sectionOf(hit.id);
     bySection.set(label, [...(bySection.get(label) ?? []), hit]);
   }
 
   return [...bySection.entries()].map(([label, hits]) => ({ label, hits }));
 });
 
+/**
+ * The groups above, with each one's repeated source label lifted into captions.
+ *
+ * Per GROUP rather than over the flat list: a caption opens a run, and a run
+ * reaching across a section heading would be opened by a caption sitting under
+ * the wrong heading. `searchRows` keeps the order and the count of what it is
+ * given either way — see there for why provenance must never re-sort.
+ */
+const groups = computed(() =>
+  grouped.value.map((group) => ({
+    label: group.label,
+    rows: searchRows(group.hits)
+  }))
+);
+
+const filter = useTemplateRef<{ refresh: () => void }>('filter');
+
+/**
+ * Hand the highlight back to the input's list every time the rows change.
+ *
+ * `flush: 'post'`, because what the input re-seats the highlight against is the
+ * DOM: asked before Vue has patched it, reka would measure the rows this
+ * answer just replaced. Why the input owns that decision rather than this
+ * component, and what it does with it, is in `DuxtSearchInput.refresh`.
+ */
+watch(results, () => filter.value?.refresh(), { flush: 'post' });
+
 async function show() {
   load();
   open.value = true;
@@ -104,30 +202,45 @@ function go(id: string) {
   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(' › ');
+/**
+ * A hit the reader opened — not a section tile and not a recent page, which
+ * `go` also serves and which nobody searched for.
+ *
+ * The rank is the position in the MERGED list rather than in the group it is
+ * drawn in: the list is one ranking with headings and captions over it, so a
+ * hit's place in its section says nothing about how well the search did. Found
+ * by `id` rather than by identity, because a row is a COPY of its hit — it
+ * carries the context line and excerpt spread onto it — so the object the
+ * template hands back is never the one sitting in `results`. Reported before
+ * `go`, which clears the term this hit was found with.
+ */
+function openResult(hit: DuxtSearchHit) {
+  analytics.track({
+    name: 'search-result',
+    query: query.value,
+    rank: results.value.findIndex((entry) => entry.id === hit.id) + 1,
+    // The path, never the hit's rendered text.
+    to: hit.id,
+    collection: hit.source?.collection
+  });
+
+  go(hit.id);
 }
 
-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();
-      }
-    }
-  };
+const { hint, on } = useDuxtShortcuts();
 
-  window.addEventListener('keydown', handler);
-  onBeforeUnmount(() => window.removeEventListener('keydown', handler));
+on('search', () => {
+  if (open.value) open.value = false;
+  else void show();
 });
+
+/**
+ * The hint on the button, from the same definition the handler binds.
+ *
+ * Through the LIVE list rather than the raw table, so a site that has unbound
+ * the key draws no cap at all instead of advertising a chord nothing answers.
+ */
+const searchHint = computed(() => hint('search'));
 </script>
 
 <template>
@@ -141,9 +254,10 @@ onMounted(() => {
     <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"
+      v-if="searchHint"
+      class="ms-auto hidden rounded border bg-muted px-1.5 font-mono text-[10px] sm:inline-block"
     >
-      ⌘K
+      {{ searchHint }}
     </kbd>
   </UiButton>
 
@@ -153,22 +267,9 @@ onMounted(() => {
          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>
+         state is ours too. What it is INSTEAD, and why that is a component
+         rather than an `<input>`, is in `DuxtSearchInput`. -->
+    <DuxtSearchInput ref="filter" v-model="query" />
 
     <UiCommandList class="max-h-[60vh]">
       <!-- An empty box is a dead end. Without a term the dialog offers the
@@ -180,19 +281,24 @@ onMounted(() => {
           :heading="$t('duxt.search.recent')"
         >
           <UiCommandItem
-            v-for="page in recent"
+            v-for="page in history"
             :key="page.path"
             :value="`recent ${page.path}`"
-            class="gap-2"
+            class="items-start gap-2"
             @select="go(page.path)"
           >
             <Icon
               name="lucide:history"
-              class="size-3.5 shrink-0 text-muted-foreground"
+              class="mt-0.5 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 class="flex min-w-0 flex-col">
+              <span class="truncate">{{ page.title }}</span>
+              <span
+                v-if="page.context"
+                class="truncate text-xs text-muted-foreground"
+              >
+                {{ page.context }}
+              </span>
             </span>
           </UiCommandItem>
         </UiCommandGroup>
@@ -224,47 +330,81 @@ onMounted(() => {
 
       <!-- 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. -->
+           from the result.
+
+           ONLY WITH SOMETHING TO SHOW. The approximate pass can come up empty
+           too, and then this line stood under "Nothing found" promising the
+           closest matches of a list that had none. -->
       <div
-        v-if="approximate"
+        v-if="approximate && results.length"
         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. -->
+      <!-- THREE LINES per hit: the title, the same context line the history
+           above carries, and an excerpt of the section's own text. The
+           repository badge is gone — provenance is stated once at the head of
+           each run of results that share it, rather than printed onto every
+           row, which was the repetition both halves of this dialog were asked
+           to remove. -->
       <UiCommandGroup
-        v-for="group in grouped"
+        v-for="group in groups"
         :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]"
+        <template v-for="row in group.rows" :key="row.hit.id">
+          <!-- Opens a run of hits from one source. `aria-hidden`, because the
+               same text reaches a screen reader on every row below through
+               `row.provenance` — a caption is a way of not repeating something
+               visually, and repeating it to one reader while hiding it from
+               another is how a shared label becomes a lie. -->
+          <div
+            v-if="row.caption"
+            aria-hidden="true"
+            class="truncate px-2 pt-3 pb-1 text-[11px] font-medium text-muted-foreground/80 first:pt-1"
+          >
+            {{ row.caption }}
+          </div>
+
+          <UiCommandItem
+            :value="row.hit.id"
+            class="items-start gap-2"
+            @select="openResult(row.hit)"
           >
-            {{ hit.source.label }}
-          </UiBadge>
-        </UiCommandItem>
+            <Icon
+              :name="row.hit.level > 1 ? 'lucide:hash' : 'lucide:file-text'"
+              class="mt-0.5 size-3.5 shrink-0 text-muted-foreground"
+            />
+            <!-- `min-w-0` is what actually lets the lines truncate: a flex item
+                 defaults to `min-width: auto`, which refuses to shrink below
+                 its content and pushes the dialog into a horizontal scroll on a
+                 320px screen instead. -->
+            <span class="flex min-w-0 flex-col">
+              <span class="truncate">{{ row.hit.title }}</span>
+              <span
+                v-if="row.hit.context"
+                class="truncate text-xs text-muted-foreground"
+              >
+                {{ row.hit.context }}
+              </span>
+              <!-- Interpolated, never `v-html`: this is a document's own text,
+                   and a page that writes about `<script>` must read as prose
+                   rather than run as markup. Dropped entirely when the section
+                   has no text, so an empty preview leaves no empty row. -->
+              <span
+                v-if="row.hit.excerpt"
+                class="line-clamp-2 text-xs text-muted-foreground/80"
+              >
+                {{ row.hit.excerpt }}
+              </span>
+              <span v-if="row.provenance" class="sr-only">
+                {{ row.provenance }}
+              </span>
+            </span>
+          </UiCommandItem>
+        </template>
       </UiCommandGroup>
     </UiCommandList>
   </UiCommandDialog>

package/app/components/DuxtSearchInput.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+// The search dialog's input — reka's `ListboxFilter`, and NOT shadcn's
+// `CommandInput`.
+//
+// `CommandInput` is `ListboxFilter` plus one line: it writes the term into
+// Command's own `filterState`, and Command then scores the rendered list a
+// SECOND time against its text — dropping entries that mounted after the term
+// changed, and re-ranking what the database already ranked. So the term must
+// never reach `filterState`, and the conclusion long drawn from that was to
+// drop `ListboxFilter` along with it and type into a plain `<input>`.
+//
+// That threw away the half that was never the problem. `ListboxFilter` filters
+// NOTHING. What it does is the combobox wiring: forward Arrow/Home/End to the
+// listbox and Enter to the highlighted item, publish `aria-activedescendant`,
+// and clear `focusable` so the list leaves the tab order and the input keeps
+// focus while the list keeps the highlight. Without it the results were
+// reachable by mouse only — #89.
+//
+// It is a component of its own because `highlightFirstItem` is reka's API for a
+// DESCENDANT of the listbox root, and `DuxtSearch` is its PARENT: it renders
+// the root, so it cannot reach in. One component inside the dialog can, and
+// `refresh()` is what it hands back.
+//
+// No clear button: `DialogContent` already draws a close X, and two of them in
+// the same corner is one too many.
+import { ListboxFilter, injectListboxRootContext } from 'reka-ui';
+
+const query = defineModel<string>({ default: '' });
+
+const root = injectListboxRootContext();
+
+/**
+ * Re-seat the highlight on the first row once a search has settled.
+ *
+ * `ListboxFilter` highlights the first item on every KEYSTROKE, which is right
+ * for a list filtered synchronously and wrong for one that is fetched: the
+ * database answers a debounce later, and by then the row it highlighted has
+ * unmounted. reka keeps the reference either way, so what is left is an
+ * `aria-activedescendant` naming an element no longer in the document and an
+ * Enter that does nothing — reka guards that one with `isConnected`. Those are
+ * #89's two symptoms again, one step further along.
+ *
+ * A highlight still on a live row is left exactly where it is: the reader put
+ * it there with the arrow keys, and a search that settles without changing the
+ * rows must not move it.
+ */
+function refresh() {
+  if (root.highlightedElement.value?.isConnected) return;
+
+  // Cleared FIRST, so a search that found nothing ends with no active
+  // descendant rather than a dangling one: `highlightFirstItem` only ever
+  // assigns, and over an empty collection it does nothing at all.
+  root.highlightedElement.value = null;
+  root.highlightFirstItem();
+}
+
+defineExpose({ refresh });
+</script>
+
+<template>
+  <div class="flex items-center gap-2 border-b px-3">
+    <Icon name="lucide:search" class="size-4 shrink-0 text-muted-foreground" />
+    <ListboxFilter
+      v-model="query"
+      auto-focus
+      class="flex h-11 w-full bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+      :placeholder="$t('duxt.search.placeholder')"
+    />
+  </div>
+</template>

package/app/components/DuxtSections.vue

@@ -58,7 +58,17 @@ function current(to?: string) {
         "
       >
         <Icon v-if="section.icon" :name="section.icon" class="size-4" />
-        {{ section.label }}
+        <!-- The lit chip is `font-medium`, which is wider than the regular
+             weight, so every chip after it shifted sideways on each navigation.
+             The invisible zero-height `::after` carries the label at the medium
+             weight and reserves that width whether the chip is lit or not. A
+             pseudo-element rather than a second span, so `textContent` stays the
+             label once and `visibility: hidden` keeps it out of the name. -->
+        <span
+          class="inline-flex flex-col after:invisible after:h-0 after:overflow-hidden after:font-medium after:content-[attr(data-label)]"
+          :data-label="section.label"
+          >{{ section.label }}</span
+        >
       </NuxtLink>
     </nav>
   </div>

package/app/components/DuxtSegmented.vue

@@ -0,0 +1,64 @@
+<script setup lang="ts" generic="T extends string">
+import type { HTMLAttributes } from 'vue';
+import { cn } from '@duxt/lib/utils';
+
+/**
+ * A row of pressed-or-not buttons: pick one of a few, see which is picked.
+ *
+ * `role="group"` with `aria-pressed`, NOT a radiogroup or a tablist: a
+ * radiogroup promises arrow-key navigation between its options and a tablist
+ * promises panels, and this implements neither. A group of pressed buttons
+ * promises only what it does — every one reachable by Tab, every one saying
+ * whether it is on. Where a strip really does switch panels, it is a
+ * `UiTabsList` with `variant="pill"`, which draws the same pill.
+ *
+ * The `option` slot is for a label that is more than an icon and a word — the
+ * package managers swap their mark with the theme.
+ */
+export interface DuxtSegmentedOption<Value extends string = string> {
+  value: Value;
+  label: string;
+  icon?: string;
+}
+
+const props = withDefaults(
+  defineProps<{
+    options: readonly DuxtSegmentedOption<T>[];
+    /** The group's accessible name. */
+    label?: string;
+    size?: DuxtPillSize;
+    tone?: DuxtPillTone;
+    /** Monospaced labels, for things a reader would type: a media type, a client. */
+    mono?: boolean;
+    class?: HTMLAttributes['class'];
+  }>(),
+  { size: 'md', tone: 'raised', mono: false }
+);
+
+const model = defineModel<T>({ required: true });
+</script>
+
+<template>
+  <div
+    role="group"
+    :aria-label="label"
+    :class="cn('flex items-center gap-1', props.class)"
+  >
+    <button
+      v-for="option in options"
+      :key="option.value"
+      type="button"
+      :aria-pressed="model === option.value"
+      :class="[
+        duxtPill(model === option.value, { size, tone }),
+        mono && 'font-mono'
+      ]"
+      @click="model = option.value"
+    >
+      <slot name="option" :option="option" :active="model === option.value">
+        <Icon v-if="option.icon" :name="option.icon" class="size-3.5" />
+        {{ option.label }}
+      </slot>
+    </button>
+  </div>
+</template>

package/app/components/DuxtShortcuts.vue

@@ -1,16 +1,21 @@
 <script setup lang="ts">
 /**
- * The shortcut sheet, on `?`.
+ * The shortcut sheet — on `?`, and on the control that opens it.
  *
- * Its list is `duxtShortcuts`, the same array the handlers match against, so
- * the sheet cannot come to advertise a key nothing binds.
+ * It lists what `useDuxtShortcuts()` reports as live — the same list, under the
+ * same policy, that the handlers bind — so it cannot advertise a key nothing
+ * listens to.
+ *
+ * Its open state lives in `useDuxtShortcutSheet()` rather than in a `ref` here,
+ * because `?` is no longer the only way in: `DuxtShortcutsTrigger` opens the
+ * same sheet from the header, and on a site with
+ * `shortcuts.singleCharacter: false` it is the only thing that can — there is
+ * no `?` binding left.
  */
-const open = ref(false);
+const { open } = useDuxtShortcutSheet();
+const { shortcuts, keys, on } = useDuxtShortcuts();
 
-onDuxtShortcut(
-  (event) => event.key === '?' && !event.metaKey && !event.ctrlKey,
-  () => (open.value = !open.value)
-);
+on('help', () => (open.value = !open.value));
 </script>
 
 <template>
@@ -25,14 +30,14 @@ onDuxtShortcut(
 
       <ul class="flex flex-col gap-2 text-sm">
         <li
-          v-for="shortcut in duxtShortcuts"
-          :key="shortcut.label"
+          v-for="shortcut in shortcuts"
+          :key="shortcut.action"
           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"
+              v-for="key in keys(shortcut)"
               :key="key"
               class="rounded border bg-muted px-1.5 py-0.5 font-mono text-xs"
             >