@kirchdev/duxt 0.1.0

package/app/composables/useDuxtSearch.ts

@@ -0,0 +1,208 @@
+import type { DuxtSearchSection } from '@duxt/composables/useFuzzySearch';
+
+/** A hit, with the source it came out of. */
+export interface DuxtSearchHit extends DuxtSearchSection {
+  /** Undefined on a site with one source: there is nothing to distinguish. */
+  source?: { label: string; collection: string };
+}
+
+/**
+ * Search across every source, not just the one being read.
+ *
+ * A site pulling three repositories had three separate searches, and which one
+ * a reader got depended on which page they happened to be standing on. This is
+ * the thing the `sources` model makes possible and a single-repository theme
+ * cannot do at all.
+ *
+ * RANKED TOGETHER, NOT GROUPED PER REPOSITORY. The choice matters and it is not
+ * obvious. Grouping per repository asks the reader to know which project their
+ * answer is in — but if they knew that, the search would be doing less work
+ * than the sidebar. So the lists are interleaved by rank and each hit carries a
+ * badge saying where it came from: the best answers first, provenance kept.
+ * The source being read goes first in each round, because a reader searching
+ * inside a project usually means that project.
+ *
+ * ONE VERSION PER REPOSITORY. Searching every version returns each page as many
+ * times as there are versions, which buries the answer under its own history.
+ * So each repository contributes the version the reader is in, or its default.
+ */
+export function useDuxtSearch() {
+  const duxt = useDuxtConfig();
+  const { source } = useDuxtCollection();
+
+  const sources = computed(() => duxt.resolvedSources ?? []);
+
+  /**
+   * The collections to search, one per repository.
+   *
+   * Fixed at setup, deliberately: each one needs its own `useSearchCollection`,
+   * and a composable list that grows with the route is not a thing. The
+   * manifest is build-time config and does not change while the app is running,
+   * so the set is complete from the start; which of them is FIRST still follows
+   * the route.
+   */
+  const searchable = sources.value.length
+    ? [
+        ...new Map(
+          sources.value.map((entry) => [entry.collection, entry])
+        ).values()
+      ]
+    : [];
+
+  const searches = searchable.map((entry) => ({
+    entry,
+    ...useSearchCollection(
+      entry.collection as unknown as Parameters<typeof useSearchCollection>[0],
+      {
+        // A table is flattened into one string, so its cells run together —
+        // `KeyWhat it controlstitleThe name in the navbar…`. Its content is
+        // still reachable through the page that holds it.
+        ignoredTags: ['table'],
+        immediate: false
+      }
+    )
+  }));
+
+  /**
+   * The approximate pass, one index per source.
+   *
+   * It used to run over the collection being read alone, which made a typo
+   * quietly narrow the search from every source back to one — the reader who
+   * most needed the other repositories searched was the reader who had
+   * mistyped. Each index is still built on first use and only on the path FTS
+   * could not answer, so a reader who types accurately downloads none of them.
+   */
+  const approximate = searchable.map((entry) => ({
+    entry,
+    search: useFuzzySearch(entry.collection as DuxtCollectionName, {
+      ignoredTags: ['table']
+    }).search
+  }));
+
+  /** One entry per repository: the version being read, else that repo's default. */
+  const active = computed(() => {
+    const current = source.value;
+    const byRepo = new Map<string, (typeof searchable)[number]>();
+
+    for (const entry of searchable) {
+      const key = entry.repo ?? '';
+      const chosen = byRepo.get(key);
+
+      if (entry.collection === current?.collection) {
+        byRepo.set(key, entry);
+        continue;
+      }
+
+      if (chosen?.collection === current?.collection) continue;
+      if (!chosen || (entry.isDefault && !chosen.isDefault)) {
+        byRepo.set(key, entry);
+      }
+    }
+
+    // The source being read leads; the rest keep the config's own order.
+    return [...byRepo.values()].sort((a, b) =>
+      a.collection === current?.collection
+        ? -1
+        : b.collection === current?.collection
+          ? 1
+          : 0
+    );
+  });
+
+  /** Only worth a badge when there is more than one thing to tell apart. */
+  const labelled = computed(() => active.value.length > 1);
+
+  const labelOf = (entry: (typeof searchable)[number]) =>
+    [entry.repo, entry.version].filter(Boolean).join(' ') ||
+    entry.prefix ||
+    '/';
+
+  async function init() {
+    await Promise.all(
+      searches
+        .filter((search) => active.value.includes(search.entry))
+        .filter((search) => search.status.value === 'idle')
+        .map((search) => search.init())
+    );
+  }
+
+  /**
+   * Interleave by rank.
+   *
+   * Without scores to compare across collections — each database ranks inside
+   * itself — position is the only comparable thing there is. Round-robin over
+   * the lists gives every source its best hit before any source gets its
+   * second, which is the closest honest approximation of "ranked together".
+   */
+  function interleave(lists: DuxtSearchHit[][], limit: number) {
+    const merged: DuxtSearchHit[] = [];
+    const depth = Math.max(0, ...lists.map((list) => list.length));
+
+    for (let rank = 0; rank < depth && merged.length < limit; rank++) {
+      for (const list of lists) {
+        const hit = list[rank];
+        if (hit) merged.push(hit);
+        if (merged.length >= limit) break;
+      }
+    }
+
+    return merged;
+  }
+
+  async function search(
+    term: string,
+    limit = 20
+  ): Promise<{ hits: DuxtSearchHit[]; approximate: boolean }> {
+    if (!term.trim()) return { hits: [], approximate: false };
+
+    const wanted = active.value;
+
+    const lists = await Promise.all(
+      searches
+        .filter((entry) => wanted.includes(entry.entry))
+        .map(async (entry) => {
+          const hits = (await entry.search(term, {
+            limit
+          })) as DuxtSearchSection[];
+
+          return hits.map((hit) => ({
+            ...hit,
+            source: labelled.value
+              ? {
+                  label: labelOf(entry.entry),
+                  collection: entry.entry.collection
+                }
+              : undefined
+          }));
+        })
+    );
+
+    const merged = interleave(lists, limit);
+    if (merged.length) return { hits: merged, approximate: false };
+
+    // FTS matches terms and prefixes, not near-misses, so one wrong letter
+    // leaves the reader with an empty box. Fuse gets a second look, over the
+    // same sources and merged the same way.
+    const fuzzy = await Promise.all(
+      approximate
+        .filter((entry) => wanted.includes(entry.entry))
+        .map(async (entry) => {
+          const hits = await entry.search(term, limit);
+
+          return hits.map((hit) => ({
+            ...hit,
+            source: labelled.value
+              ? {
+                  label: labelOf(entry.entry),
+                  collection: entry.entry.collection
+                }
+              : undefined
+          }));
+        })
+    );
+
+    return { hits: interleave(fuzzy, limit), approximate: true };
+  }
+
+  return { search, init, labelled };
+}

package/app/composables/useDuxtSection.ts

@@ -0,0 +1,44 @@
+import type { ContentNavigationItem } from '@nuxt/content';
+import type { Ref } from 'vue';
+
+/**
+ * The documentation is split into sections, each owning a branch of the tree —
+ * so the sidebar shows one branch, not everything. Which branch follows from
+ * the path, falling back to the whole tree so a page outside any section still
+ * has a sidebar.
+ */
+export function useDuxtSection(
+  navigation: Ref<ContentNavigationItem[] | null | undefined>
+) {
+  const path = useDuxtPath();
+  const duxt = useDuxtConfig();
+
+  /**
+   * BOTH ROWS, sections first.
+   *
+   * A generated section can declare that its entry belongs in the top navbar
+   * rather than in the section row (`navigation: 'navigation'`), and a site can
+   * put an ordinary page there by hand. Neither stops being the branch its
+   * pages sit in — but reading only `sections` said it did: the sidebar fell
+   * back to the whole tree, and the breadcrumb lost its head, so a release page
+   * printed its own version and nothing above it.
+   */
+  /**
+   * LONGEST MATCH, not the first one written. `/demo` and `/demo/api` both
+   * prefix a page under the reference, and taking the first said the reader was
+   * in the prose beside it — so the sidebar drew that tree instead of the
+   * endpoints. Same rule, and the same bug, as `sourceForPath`.
+   */
+  const section = computed(() =>
+    currentSection(
+      [...(duxt.sections ?? []), ...(duxt.navigation ?? [])],
+      path.value
+    )
+  );
+
+  const items = computed(() =>
+    sectionItems(navigation.value ?? [], section.value?.to, path.value)
+  );
+
+  return { section, items };
+}

package/app/composables/useDuxtSectionRow.ts

@@ -0,0 +1,49 @@
+/**
+ * Is the second navbar row showing?
+ *
+ * Two things need the answer and must not disagree about it: `DuxtSections`,
+ * which draws the row only where one of its sections is current — a page
+ * outside every section, or a generated section whose entry the site put in the
+ * top row instead, would otherwise get the whole row with nothing marked — and
+ * the LAYOUTS, whose sticky columns are offset by exactly the header above
+ * them. Answered in one place because a mismatch is silent: the row vanishes
+ * and the sidebars keep the gap where it used to be.
+ */
+export function useDuxtSectionRow() {
+  const duxt = useDuxtConfig();
+  const path = useDuxtPath();
+
+  /**
+   * THIS AREA'S ENTRIES, not every entry the site declared — see
+   * `sectionsForPath`. A second source has top-level parts of its own, and the
+   * row is "the parts of what you are reading" rather than a site index.
+   */
+  const sections = computed(() =>
+    sectionsForPath(duxt.sections ?? [], duxt.resolvedSources ?? [], path.value)
+  );
+
+  const visible = computed(() =>
+    sections.value.some(
+      (section) => section.to && path.value.startsWith(section.to)
+    )
+  );
+
+  /**
+   * How far down the page the header reaches — the navbar, plus the section row
+   * where there is one — as a length the layouts hand down in
+   * `--duxt-header-offset`.
+   *
+   * NOT `chrome`, which is what this was called. The word is right in the sense
+   * an interface means it and wrong in the sense most readers reach for first,
+   * and a name that has to be explained is a name chosen badly.
+   * `DuxtLiveWindow`'s `chrome` prop keeps it, because there it really is a
+   * drawn browser bar.
+   *
+   * A CSS variable rather than a class per case: the sticky columns live in
+   * three layouts and in the page's own contents column, and four copies of a
+   * pair of arbitrary values is four places to forget one.
+   */
+  const headerOffset = computed(() => (visible.value ? '6.5rem' : '3.75rem'));
+
+  return { sections, visible, headerOffset };
+}

package/app/composables/useDuxtShortcuts.ts

@@ -0,0 +1,58 @@
+/**
+ * One place that knows which keys the theme listens to.
+ *
+ * The overlay on `?` and the handlers themselves have to agree, and the only
+ * way they do is by being the same list — a shortcut sheet that lists a key
+ * nothing binds is worse than no sheet.
+ *
+ * A shortcut never fires while the reader is typing. Without that guard, `?`
+ * in the search box opens the overlay instead of being searched for, which is
+ * the single most common bug in this kind of feature.
+ */
+export interface DuxtShortcut {
+  /** The key, as `KeyboardEvent.key` reports it. */
+  key: string;
+  /** Requires ⌘ on a Mac, Ctrl elsewhere. */
+  meta?: boolean;
+  /** i18n key for what it does. */
+  label: string;
+  /** How to draw it. */
+  keys: string[];
+}
+
+export const duxtShortcuts: DuxtShortcut[] = [
+  { key: 'k', meta: true, label: 'duxt.shortcuts.search', keys: ['⌘', 'K'] },
+  { key: '?', label: 'duxt.shortcuts.help', keys: ['?'] },
+  { key: '[', label: 'duxt.shortcuts.previous', keys: ['['] },
+  { key: ']', label: 'duxt.shortcuts.next', keys: [']'] }
+];
+
+/** Is the reader typing? Then the key belongs to whatever they are typing in. */
+export function isTyping(target: EventTarget | null): boolean {
+  const element = target as HTMLElement | null;
+  if (!element) return false;
+
+  return (
+    element.isContentEditable ||
+    ['INPUT', 'TEXTAREA', 'SELECT'].includes(element.tagName)
+  );
+}
+
+/** Bind one key, with the guards every one of them needs. */
+export function onDuxtShortcut(
+  match: (event: KeyboardEvent) => boolean,
+  run: (event: KeyboardEvent) => void
+) {
+  onMounted(() => {
+    const handler = (event: KeyboardEvent) => {
+      if (isTyping(event.target)) return;
+      if (!match(event)) return;
+
+      event.preventDefault();
+      run(event);
+    };
+
+    window.addEventListener('keydown', handler);
+    onBeforeUnmount(() => window.removeEventListener('keydown', handler));
+  });
+}

package/app/composables/useDuxtSiteUrl.ts

@@ -0,0 +1,27 @@
+/**
+ * The site's own origin, and paths made absolute against it.
+ *
+ * duxt cannot guess this — a layer has no idea what domain it will be served
+ * from — so it reads `i18n.baseUrl`, the one place a Nuxt site already has to
+ * state it for hreflang. Where it is unset, `absolute()` hands back the path
+ * unchanged: a relative `canonical` is valid and resolves correctly, whereas a
+ * guessed origin in a `canonical` is actively wrong. Same stance `app.vue`
+ * takes on the alternate links, for the same reason.
+ *
+ * Set `NUXT_PUBLIC_I18N_BASE_URL` in the deployment, or `i18n.baseUrl` in the
+ * consumer's nuxt.config.
+ */
+export function useDuxtSiteUrl() {
+  const runtime = useRuntimeConfig().public as {
+    i18n?: { baseUrl?: string };
+  };
+
+  const origin = computed(
+    () => runtime.i18n?.baseUrl?.replace(/\/+$/, '') ?? ''
+  );
+
+  const absolute = (path: string) =>
+    origin.value ? `${origin.value}${path}` : path;
+
+  return { origin, absolute };
+}

package/app/composables/useDuxtToast.ts

@@ -0,0 +1,25 @@
+import { toast } from 'vue-sonner';
+
+/**
+ * Toasts, wrapped so components never import vue-sonner directly.
+ *
+ * The wrapper is the seam: a consumer that wants a different notification
+ * system replaces this one composable instead of every call site, and the
+ * layer's own components keep working. Each level maps to Sonner's own type,
+ * which picks the icon and its status colour.
+ */
+export function useDuxtToast() {
+  return {
+    success: (message: string, description?: string) =>
+      toast.success(message, { description }),
+    info: (message: string, description?: string) =>
+      toast.info(message, { description }),
+    warning: (message: string, description?: string) =>
+      toast.warning(message, { description }),
+    error: (message: string, description?: string) =>
+      toast.error(message, { description }),
+    /** A toast that stays until the promise settles. */
+    loading: (message: string) => toast.loading(message),
+    dismiss: (id?: number | string) => toast.dismiss(id)
+  };
+}

package/app/composables/useDuxtVersion.ts

@@ -0,0 +1,138 @@
+/**
+ * What the reader needs to be told about the version they are in.
+ *
+ * Three questions, one answer, because they are the same question asked by
+ * different parts of the page: the banner needs to know whether this version is
+ * still the one to read, the head needs to know whether a crawler should index
+ * it, and the switcher needs a badge per entry. All three follow from the
+ * resolved source manifest — which version serves this path, which one serves
+ * it without a prefix, and what the config says each is worth.
+ */
+export function useDuxtVersion() {
+  const duxt = useDuxtConfig();
+  const path = useDuxtPath();
+
+  const sources = computed(() => duxt.resolvedSources ?? []);
+
+  /** The source serving this route. */
+  const current = computed(() => sourceForPath(path.value, sources.value));
+
+  /**
+   * The version to send the reader to instead — the default of the SAME
+   * repository. Another project's default says nothing about this one.
+   *
+   * A VERSION-NEUTRAL GENERATED SECTION is its own answer. A changelog is one
+   * global history served at a URL with no version in it, so there is no other
+   * version of it to prefer: left to the search below it would have matched the
+   * documentation's default instead, and the page would then have carried
+   * `noindex` and a canonical pointing at a URL that does not exist.
+   */
+  const preferred = computed(() =>
+    current.value?.generated?.versioning === 'global'
+      ? current.value
+      : sources.value.find(
+          (source) =>
+            source.isDefault &&
+            source.generated?.versioning !== 'global' &&
+            source.repo === current.value?.repo &&
+            // The default of the same ARTEFACT — see `sameArtefact`. Without
+            // it a reference page's canonical pointed at the documentation's
+            // default, which is a different document at a different URL.
+            sameArtefact(source, current.value)
+        )
+  );
+
+  /** Is this the version a first-time reader should be on? */
+  const isPreferred = computed(
+    () => !current.value || current.value === preferred.value
+  );
+
+  const status = computed(() => current.value?.status ?? 'current');
+
+  /**
+   * The versions the switcher may offer — see `versionChoices`.
+   *
+   * Here rather than in `DuxtVersion` because the mobile sheet asks the same
+   * question to decide WHERE the version goes: a full-width select in its own
+   * strip when there is a choice, a badge beside the brand when there is not.
+   */
+  const choices = computed(() =>
+    versionChoices(sources.value, current.value, duxt.versions)
+  );
+
+  /** Is there anything to switch to? */
+  const switchable = computed(() => choices.value.length > 1);
+
+  /**
+   * WHICH KIND of "not the current version" this is.
+   *
+   * `isDefault` says only "not the one served by default", and that covers two
+   * readers who need opposite things told: someone on a release from two years
+   * ago should be told to upgrade, and someone on the branch documenting next
+   * month's should be told that what they are reading may still change. Telling
+   * the second one to upgrade is exactly backwards, which is what the banner
+   * did before this.
+   *
+   * The config wins where it speaks — `status: 'upcoming'` on a branch called
+   * `next` is a fact only the maintainer has. Where it does not, semver decides,
+   * and where semver cannot (a branch beside a tag) the version is treated as
+   * old: a tag next to a default branch is almost always a past release, and
+   * the maintainer can say otherwise in one word.
+   */
+  const kind = computed<'current' | 'upcoming' | 'old' | 'deprecated' | 'eol'>(
+    () => {
+      if (status.value === 'eol') return 'eol';
+      if (status.value === 'deprecated') return 'deprecated';
+      if (status.value === 'upcoming') return 'upcoming';
+      if (isPreferred.value) return 'current';
+
+      return versionRelation(
+        current.value?.version,
+        preferred.value?.version
+      ) === 'newer'
+        ? 'upcoming'
+        : 'old';
+    }
+  );
+
+  /**
+   * A crawler is as likely to serve v0.7.0 as the current docs, and nothing on
+   * the page says which it is. So an older or dead version points at the
+   * current one and asks not to be indexed itself — `follow`, because the links
+   * out of it are still worth crawling.
+   */
+  const shouldIndex = computed(
+    () => isPreferred.value && status.value !== 'eol'
+  );
+
+  /** The same page in the preferred version, for the banner and the canonical. */
+  const preferredPath = computed(() =>
+    versionPath(
+      path.value,
+      current.value?.prefix,
+      preferred.value?.prefix || '/'
+    )
+  );
+
+  const shouldWarn = computed(
+    () =>
+      Boolean(current.value?.version) &&
+      (!isPreferred.value ||
+        status.value === 'deprecated' ||
+        status.value === 'eol')
+  );
+
+  return {
+    sources,
+    choices,
+    switchable,
+    current,
+    preferred,
+    isPreferred,
+    status,
+    kind,
+    shouldIndex,
+    shouldWarn,
+    preferredPath
+  };
+}

package/app/composables/useFuzzySearch.ts

@@ -0,0 +1,83 @@
+import type Fuse from 'fuse.js';
+import type { MaybeRefOrGetter } from 'vue';
+
+/** One entry of Content's search index: a page, or a heading inside one. */
+export interface DuxtSearchSection {
+  id: string;
+  title: string;
+  titles: string[];
+  level: number;
+  content: string;
+}
+
+/**
+ * Typo tolerance beside Content's FTS index.
+ *
+ * FTS5 matches terms and prefixes, never near-misses, so a single wrong letter
+ * returns nothing at all. Fuse matches approximately over the same sections the
+ * database indexes.
+ *
+ * Both the library and the sections are loaded on the first query the database
+ * cannot answer, not when the dialog opens: a reader who types accurately never
+ * downloads either. The sections come through Content's client database, which
+ * the FTS index has already loaded by then, so the fallback costs no second
+ * payload — only Fuse itself.
+ */
+export function useFuzzySearch(
+  /**
+   * Which collection to fall back over. A versioned site names its collections
+   * after the prefix they serve, so this follows `useDuxtCollection()` once the
+   * dialog does — it is passed rather than resolved here to keep the exact and
+   * the approximate pass reading the same one.
+   */
+  collection: MaybeRefOrGetter<DuxtCollectionName> = 'docs' as DuxtCollectionName,
+  options?: { ignoredTags?: string[] }
+) {
+  let index: Promise<Fuse<DuxtSearchSection>> | undefined;
+  let indexedFor: string | undefined;
+
+  async function build(name: DuxtCollectionName) {
+    const [{ default: Fuse }, sections] = await Promise.all([
+      import('fuse.js'),
+      queryCollectionSearchSections(name as DuxtCollectionArg, options)
+    ]);
+
+    return new Fuse(sections as DuxtSearchSection[], {
+      // A hit in the heading outranks one buried in a paragraph, and the
+      // headings above a section still say more than its body text.
+      keys: [
+        { name: 'title', weight: 3 },
+        { name: 'titles', weight: 2 },
+        { name: 'content', weight: 1 }
+      ],
+
+      // By default Fuse scores a match by how near the start of the field it
+      // sits, which says nothing about a paragraph — only the quality of the
+      // match should count here.
+      ignoreLocation: true,
+
+      // Loose enough to survive a transposed letter, tight enough that a short
+      // term does not drag in half the documentation.
+      threshold: 0.35,
+      minMatchCharLength: 3
+    });
+  }
+
+  async function search(term: string, limit = 20) {
+    const name = toValue(collection);
+
+    // Built on first use, and again when the route moves to another collection
+    // — otherwise a versioned site would keep answering out of the version the
+    // reader happened to arrive from.
+    if (!index || name !== indexedFor) {
+      indexedFor = name;
+      index = build(name);
+    }
+
+    const fuse = await index;
+
+    return fuse.search(term, { limit }).map((hit) => hit.item);
+  }
+
+  return { search };
+}

package/app/composables/usePackageManager.ts

@@ -0,0 +1,4 @@
+/** The package manager the reader picked — see `useDuxtChoice`. */
+export function usePackageManager() {
+  return useDuxtChoice('package-manager');
+}