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

package/app/composables/useDuxtVersion.ts

@@ -105,14 +105,65 @@ export function useDuxtVersion() {
     () => isPreferred.value && status.value !== 'eol'
   );
 
-  /** The same page in the preferred version, for the banner and the canonical. */
-  const preferredPath = computed(() =>
-    versionPath(
+  /**
+   * Whether the same page is MISSING from the preferred version.
+   *
+   * Only a changelog release page can be: every version publishes its own
+   * changelog, and a branch's may carry a release the default version has not
+   * shipped. Swapping the prefix alone then pointed the banner's link and the
+   * canonical at a page that does not exist. Every other per-version tree is the
+   * same tree at another ref, so nothing else is looked up.
+   *
+   * `useAsyncData`, so the server waits for it and the canonical in the
+   * prerendered HTML is already right. Keyed per path, so the banner and the
+   * page share one lookup. Nothing after the `await` touches a composable.
+   */
+  const { data: preferredMissing } = useAsyncData(
+    () => `duxt-preferred-missing-${path.value}`,
+    async () => {
+      const own = current.value;
+      const target = preferred.value;
+      if (
+        !own ||
+        !target ||
+        own === target ||
+        own.generated?.type !== 'changelog' ||
+        path.value === own.prefix
+      ) {
+        return false;
+      }
+
+      const candidate = versionPath(
+        path.value,
+        own.prefix,
+        target.prefix || '/'
+      );
+      const hit = await queryCollection(target.collection as DuxtCollectionArg)
+        .path(candidate)
+        .select('path')
+        .first();
+
+      return !hit;
+    },
+    { default: () => false, watch: [path] }
+  );
+
+  /**
+   * The same page in the preferred version, for the banner and the canonical —
+   * or that version's own root where it never published the page. The same rule
+   * the switcher follows, see `versionSwitchPath`.
+   */
+  const preferredPath = computed(() => {
+    const to = preferred.value?.prefix || '/';
+    const candidate = versionPath(path.value, current.value?.prefix, to);
+
+    return versionSwitchPath(
       path.value,
       current.value?.prefix,
-      preferred.value?.prefix || '/'
-    )
-  );
+      to,
+      new Set(preferredMissing.value ? [candidate] : [])
+    );
+  });
 
   const shouldWarn = computed(
     () =>

package/app/composables/useDuxtViewportMeasure.ts

@@ -0,0 +1,37 @@
+/**
+ * Run a measurement whenever the window scrolls or resizes — at most once per
+ * painted frame.
+ *
+ * The reading-progress bar and the table of contents both answer a question
+ * about where the reader is, and both used to wire up the same two listeners by
+ * hand; only one of them coalesced into an animation frame, so the other ran
+ * its layout read on every scroll event however fast the wheel turned.
+ *
+ * Passive listeners, because this must never be what makes scrolling stutter.
+ * Measured once on mount, since a page can open already scrolled. Returns the
+ * scheduler, for a caller that knows of another moment worth measuring.
+ */
+import { useEventListener } from '@vueuse/core';
+
+export function useDuxtViewportMeasure(measure: () => void) {
+  let frame = 0;
+
+  function schedule() {
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      measure();
+    });
+  }
+
+  // `useEventListener` without a target binds to the window, and to nothing at
+  // all during server rendering.
+  useEventListener(['scroll', 'resize'], schedule, { passive: true });
+
+  onMounted(measure);
+  onBeforeUnmount(() => {
+    if (frame) cancelAnimationFrame(frame);
+  });
+
+  return schedule;
+}

package/app/composables/useFuzzySearch.ts

@@ -31,7 +31,12 @@ export function useFuzzySearch(
    * the approximate pass reading the same one.
    */
   collection: MaybeRefOrGetter<DuxtCollectionName> = 'docs' as DuxtCollectionName,
-  options?: { ignoredTags?: string[] }
+  options?: {
+    ignoredTags?: string[];
+    threshold?: number;
+    minMatchCharLength?: number;
+    limit?: number;
+  }
 ) {
   let index: Promise<Fuse<DuxtSearchSection>> | undefined;
   let indexedFor: string | undefined;
@@ -58,12 +63,12 @@ export function useFuzzySearch(
 
       // 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
+      threshold: options?.threshold ?? 0.35,
+      minMatchCharLength: options?.minMatchCharLength ?? 3
     });
   }
 
-  async function search(term: string, limit = 20) {
+  async function search(term: string, limit = options?.limit ?? 20) {
     const name = toValue(collection);
 
     // Built on first use, and again when the route moves to another collection

package/app/composables/useRecentPages.ts

@@ -1,7 +1,5 @@
 /** Where the list is kept. Namespaced so a consumer's own keys cannot collide. */
 const STORAGE_KEY = 'duxt:recent-pages';
-const LIMIT = 5;
-
 export interface RecentPage {
   path: string;
   title: string;
@@ -15,17 +13,19 @@ export interface RecentPage {
  * request. It stays in the browser, identifies nobody, and clearing site data
  * forgets it.
  */
-export function useRecentPages() {
+export function useRecentPages(limit = 5) {
   const recent = useState<RecentPage[]>('duxt-recent-pages', () => []);
 
   function read(): RecentPage[] {
-    try {
-      const stored = window.localStorage.getItem(STORAGE_KEY);
-      return stored ? (JSON.parse(stored) as RecentPage[]) : [];
-    } catch {
-      // Blocked storage, or a value someone else wrote — either way, no history.
-      return [];
-    }
+    // Blocked storage, or a value someone else wrote — either way, no history.
+    const parsed = readStoredJson(STORAGE_KEY);
+
+    return Array.isArray(parsed)
+      ? parsed.filter(
+          (entry): entry is RecentPage =>
+            typeof entry?.path === 'string' && typeof entry?.title === 'string'
+        )
+      : [];
   }
 
   function remember(page: RecentPage) {
@@ -34,18 +34,15 @@ export function useRecentPages() {
     const next = [
       page,
       ...read().filter((entry) => entry.path !== page.path)
-    ].slice(0, LIMIT);
+    ].slice(0, Math.max(0, limit));
     recent.value = next;
 
-    try {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
-    } catch {
-      // A convenience not worth an error.
-    }
+    // A convenience not worth an error.
+    writeStoredJson(STORAGE_KEY, next);
   }
 
   function load() {
-    if (import.meta.client) recent.value = read();
+    if (import.meta.client) recent.value = read().slice(0, Math.max(0, limit));
   }
 
   return { recent, remember, load };

package/app/error.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { NuxtError } from '#app';
+import { ConfigProvider } from 'reka-ui';
 
 const props = defineProps<{ error: NuxtError }>();
 
@@ -7,16 +8,27 @@ const localeLink = useDuxtLink();
 const path = useDuxtPath();
 const duxt = useDuxtConfig();
 const { locale } = useI18n();
+const direction = useDuxtDirection();
 
 /**
  * The error page replaces `app.vue`, so it inherits nothing from it — not the
- * `lang` attribute and not the title template. Both have to be set again here,
- * or the one page a reader reaches by accident is the one page with an
- * untitled, language-less document.
+ * `lang` attribute, not the `dir` one and not the title template. All three
+ * have to be set again here, or the one page a reader reaches by accident is
+ * the one page with an untitled, language-less, wrong-way-round document.
+ *
+ * `dir` was the one that was missing, which is the whole shape of the problem:
+ * nothing failed, the error page simply stayed left-to-right while the rest of
+ * the site turned round.
  */
 useHead(() => ({
-  htmlAttrs: { lang: locale.value },
-  title: `${props.error.statusCode} · ${duxt.title}`
+  htmlAttrs: { lang: locale.value, dir: direction.value },
+  // The status code alone, through the same template `app.vue` sets. After a
+  // client-side navigation that template is still mounted, so a title that
+  // already carried the site name came out as "404 · duxt · duxt"; rendered on
+  // the server it is not, and this page has to bring its own.
+  title: String(props.error.statusCode),
+  titleTemplate: (title?: string) =>
+    title ? `${title} · ${duxt.title}` : duxt.title
 }));
 
 /**
@@ -39,25 +51,20 @@ useSeoMeta({ robots: 'noindex, follow' });
  */
 const { data: navigation } = await useDuxtNavigation();
 
+// `flattenedNavigationPages` rather than a walk of its own: it honours
+// `page: false`, and a group that is not a route — a tfplugindocs `subcategory`
+// is the standing example — was being offered here as a near miss, which is a
+// 404 suggesting another 404.
 const suggestions = computed(() => {
   if (props.error.statusCode !== 404) return [];
 
-  const pages: { path: string; title?: string }[] = [];
-
-  const walk = (
-    items: { path?: string; title?: string; children?: unknown[] }[]
-  ) => {
-    for (const item of items) {
-      if (item.path) pages.push({ path: item.path, title: item.title });
-      if (Array.isArray(item.children)) {
-        walk(item.children as { path?: string; title?: string }[]);
-      }
-    }
-  };
-
-  walk((navigation.value ?? []) as { path?: string; title?: string }[]);
-
-  return nearestPages(path.value, pages);
+  return nearestPages(
+    path.value,
+    flattenedNavigationPages(navigation.value ?? []).map((item) => ({
+      path: item.path,
+      title: item.title
+    }))
+  );
 });
 
 // A page missing from one version but present in another is the interesting
@@ -73,61 +80,92 @@ const elsewhere = computed(
 </script>
 
 <template>
-  <NuxtLayout>
-    <div
-      class="mx-auto flex max-w-2xl flex-col items-center px-4 py-32 text-center"
-    >
-      <p class="font-mono text-sm text-muted-foreground">
-        {{ error.statusCode }}
-      </p>
-      <h1 class="mt-3 text-3xl font-semibold tracking-tight text-balance">
-        {{ error.statusMessage ?? $t('duxt.error.title') }}
-      </h1>
+  <!-- The same provider `app.vue` mounts, for the same reason: this page
+       replaces that one, so the reka primitives inside the layout below would
+       otherwise be left with the `ltr` default. The tooltip provider likewise:
+       the header's icon controls carry tooltips, and without one a client-side
+       navigation to this page threw before it could draw. -->
+  <ConfigProvider :dir="direction">
+    <UiTooltipProvider>
+      <NuxtLayout>
+        <div
+          class="mx-auto flex max-w-2xl flex-col items-center px-4 py-32 text-center"
+        >
+          <p class="font-mono text-sm text-muted-foreground">
+            {{ error.statusCode }}
+          </p>
+          <h1 class="mt-3 text-3xl font-semibold tracking-tight text-balance">
+            {{ error.statusMessage ?? $t('duxt.error.title') }}
+          </h1>
 
-      <div v-if="elsewhere.length" class="mt-8 w-full">
-        <p class="mb-3 text-sm text-muted-foreground">
-          {{ $t('duxt.error.elsewhere') }}
-        </p>
-        <div class="flex flex-wrap justify-center gap-2">
-          <UiButton
-            v-for="entry in elsewhere"
-            :key="entry.path"
-            as-child
-            variant="outline"
-            size="sm"
-          >
-            <NuxtLink :to="localeLink(entry.path)" class="font-mono text-xs">
-              {{ entry.version.label }}
+          <div v-if="elsewhere.length" class="mt-8 w-full">
+            <p class="mb-3 text-sm text-muted-foreground">
+              {{ $t('duxt.error.elsewhere') }}
+            </p>
+            <div class="flex flex-wrap justify-center gap-2">
+              <UiButton
+                v-for="entry in elsewhere"
+                :key="entry.path"
+                as-child
+                variant="outline"
+                size="sm"
+              >
+                <NuxtLink
+                  :to="localeLink(entry.path)"
+                  class="font-mono text-xs"
+                >
+                  {{ entry.version.label }}
+                </NuxtLink>
+              </UiButton>
+            </div>
+          </div>
+
+          <div v-if="suggestions.length" class="mt-8 w-full">
+            <p class="mb-3 text-sm text-muted-foreground">
+              {{ $t('duxt.error.nearest') }}
+            </p>
+            <!-- ROWS, NOT A CENTRED LINE PER PAGE. Each suggestion used to be a
+               title and its path run together on one centred line, so every
+               row started somewhere else and the paths wandered from line to
+               line. Left-aligned in one column — title over path, the way the
+               search dialog lists a page — the list reads down at a glance. -->
+            <ul class="mx-auto flex w-full max-w-md flex-col gap-1 text-start">
+              <li v-for="page in suggestions" :key="page.path">
+                <NuxtLink
+                  :to="localeLink(page.path)"
+                  class="group flex items-center gap-3 rounded-md px-3 py-2 transition-colors hover:bg-accent focus-visible:bg-accent focus-visible:outline-none"
+                >
+                  <Icon
+                    name="lucide:file-text"
+                    class="size-4 shrink-0 text-muted-foreground"
+                  />
+                  <span class="min-w-0 flex-1">
+                    <span class="block truncate text-sm font-medium">
+                      {{ page.title ?? page.path }}
+                    </span>
+                    <span
+                      class="block truncate font-mono text-xs text-muted-foreground"
+                    >
+                      {{ page.path }}
+                    </span>
+                  </span>
+                  <Icon
+                    name="lucide:chevron-right"
+                    class="size-4 shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100 rtl:-scale-x-100"
+                  />
+                </NuxtLink>
+              </li>
+            </ul>
+          </div>
+
+          <UiButton as-child class="mt-10">
+            <NuxtLink :to="localeLink('/')">
+              <Icon name="lucide:arrow-left" class="size-4 rtl:-scale-x-100" />
+              {{ $t('duxt.error.back') }}
             </NuxtLink>
           </UiButton>
         </div>
-      </div>
-
-      <div v-if="suggestions.length" class="mt-8 w-full">
-        <p class="mb-3 text-sm text-muted-foreground">
-          {{ $t('duxt.error.nearest') }}
-        </p>
-        <ul class="flex flex-col gap-1 text-sm">
-          <li v-for="page in suggestions" :key="page.path">
-            <NuxtLink
-              :to="localeLink(page.path)"
-              class="flex items-center justify-center gap-2 rounded-md px-3 py-1.5 transition-colors hover:bg-accent"
-            >
-              <span class="font-medium">{{ page.title ?? page.path }}</span>
-              <span class="font-mono text-xs text-muted-foreground">{{
-                page.path
-              }}</span>
-            </NuxtLink>
-          </li>
-        </ul>
-      </div>
-
-      <UiButton as-child class="mt-10">
-        <NuxtLink :to="localeLink('/')">
-          <Icon name="lucide:arrow-left" class="size-4" />
-          {{ $t('duxt.error.back') }}
-        </NuxtLink>
-      </UiButton>
-    </div>
-  </NuxtLayout>
+      </NuxtLayout>
+    </UiTooltipProvider>
+  </ConfigProvider>
 </template>

package/app/layouts/changelog.vue

@@ -50,16 +50,24 @@ const { headerOffset } = useDuxtSectionRow();
     <DuxtProgress />
     <DuxtShortcuts />
 
+    <!-- The site the layer is rendering may have something to say. Both strips
+         draw nothing at all until `duxt.announcements` holds one, space
+         included; the third placement, `above-content`, belongs to the page
+         rather than to the shell. -->
+    <DuxtAnnouncements placement="above-header" />
+
     <DuxtHeader />
     <DuxtSections />
 
+    <DuxtAnnouncements placement="below-header" />
+
     <div class="mx-auto flex w-full max-w-[90rem] flex-1 gap-8 px-4 lg:px-8">
       <!-- A section with one page has nothing to navigate, exactly as in the
            docs layout: the column would list the page the reader is on. That is
            the whole overview of a changelog with a single release. -->
       <div v-if="items.length > 1" class="hidden w-56 shrink-0 lg:block">
         <div
-          class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8 pr-2"
+          class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8 pe-2"
         >
           <DuxtNavigation
             :items="items"

package/app/layouts/default.vue

@@ -11,7 +11,16 @@
     <DuxtProgress />
     <DuxtShortcuts />
 
+    <!-- The site the layer is rendering may have something to say. Both strips
+         draw nothing at all until `duxt.announcements` holds one, space
+         included; the third placement, `above-content`, belongs to the page
+         rather than to the shell. -->
+    <DuxtAnnouncements placement="above-header" />
+
     <DuxtHeader />
+
+    <DuxtAnnouncements placement="below-header" />
+
     <main id="duxt-main" tabindex="-1" class="flex-1 outline-none">
       <slot />
     </main>

package/app/layouts/docs.vue

@@ -21,12 +21,20 @@ const { headerOffset } = useDuxtSectionRow();
     <DuxtProgress />
     <DuxtShortcuts />
 
+    <!-- The site the layer is rendering may have something to say. Both strips
+         draw nothing at all until `duxt.announcements` holds one, space
+         included; the third placement, `above-content`, belongs to the page
+         rather than to the shell. -->
+    <DuxtAnnouncements placement="above-header" />
+
     <DuxtHeader />
 
     <!-- The section row sits with the docs, not in the global header: the
          landing page has no sections to show. -->
     <DuxtSections />
 
+    <DuxtAnnouncements placement="below-header" />
+
     <!-- Three columns inside one centred container, not a sidebar pinned to the
          window edge: on a wide screen the docs stay a readable block instead of
          drifting apart. -->
@@ -39,7 +47,7 @@ const { headerOffset } = useDuxtSectionRow();
            the content takes the width. -->
       <div v-if="items.length > 1" class="hidden w-56 shrink-0 lg:block">
         <div
-          class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8 pr-2"
+          class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8 pe-2"
         >
           <DuxtNavigation :items="items" :label="$t('duxt.nav.docs')" />
         </div>

package/app/layouts/reference.vue

@@ -51,15 +51,23 @@ const { headerOffset } = useDuxtSectionRow();
     <DuxtProgress />
     <DuxtShortcuts />
 
+    <!-- The site the layer is rendering may have something to say. Both strips
+         draw nothing at all until `duxt.announcements` holds one, space
+         included; the third placement, `above-content`, belongs to the page
+         rather than to the shell. -->
+    <DuxtAnnouncements placement="above-header" />
+
     <DuxtHeader />
     <DuxtSections />
 
+    <DuxtAnnouncements placement="below-header" />
+
     <div class="mx-auto flex w-full max-w-[90rem] flex-1 gap-8 px-4 lg:px-8">
       <!-- A section with one page has nothing to navigate, exactly as in the
            docs layout: the column would list the page the reader is on. -->
       <div v-if="items.length > 1" class="hidden w-64 shrink-0 lg:block">
         <div
-          class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8 pr-2"
+          class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8 pe-2"
         >
           <DuxtNavigation
             :items="items"

package/app/middleware/duxt-section-layout.global.ts

@@ -51,7 +51,5 @@ function localeCodes(): string[] {
     | { locales?: { value?: (string | { code: string })[] } }
     | undefined;
 
-  return (i18n?.locales?.value ?? []).map((entry) =>
-    typeof entry === 'string' ? entry : entry.code
-  );
+  return localeCodesOf(i18n?.locales?.value);
 }