@kirchdev/duxt 0.1.0

package/app/composables/useRecentPages.ts

@@ -0,0 +1,52 @@
+/** 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;
+}
+
+/**
+ * The pages this reader visited last, for the search dialog's empty state.
+ *
+ * localStorage, not a cookie: unlike the package-manager choice this is never
+ * needed during server rendering, so it has no business travelling with every
+ * request. It stays in the browser, identifies nobody, and clearing site data
+ * forgets it.
+ */
+export function useRecentPages() {
+  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 [];
+    }
+  }
+
+  function remember(page: RecentPage) {
+    if (!import.meta.client || !page.path || !page.title) return;
+
+    const next = [
+      page,
+      ...read().filter((entry) => entry.path !== page.path)
+    ].slice(0, LIMIT);
+    recent.value = next;
+
+    try {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
+    } catch {
+      // A convenience not worth an error.
+    }
+  }
+
+  function load() {
+    if (import.meta.client) recent.value = read();
+  }
+
+  return { recent, remember, load };
+}

package/app/error.vue

@@ -0,0 +1,133 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app';
+
+const props = defineProps<{ error: NuxtError }>();
+
+const localeLink = useDuxtLink();
+const path = useDuxtPath();
+const duxt = useDuxtConfig();
+const { locale } = useI18n();
+
+/**
+ * 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.
+ */
+useHead(() => ({
+  htmlAttrs: { lang: locale.value },
+  title: `${props.error.statusCode} · ${duxt.title}`
+}));
+
+/**
+ * An error page is not a page of the site.
+ *
+ * Nothing stopped a crawler indexing this one, and a 404 that gets indexed
+ * competes in a search result with the page the reader was actually looking
+ * for. `follow` on purpose: the suggestions below are real pages and a crawler
+ * that arrived here by a broken link should still reach them.
+ */
+useSeoMeta({ robots: 'noindex, follow' });
+
+/**
+ * The nearest real pages, from the navigation the layout already fetched.
+ *
+ * A 404 in versioned documentation is usually a URL that is nearly right, and
+ * an empty "not found" tells that reader nothing. Only for a 404 — a 500 has
+ * no near miss to offer, and suggesting pages after a server error reads as if
+ * the site had decided the reader was mistaken.
+ */
+const { data: navigation } = await useDuxtNavigation();
+
+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);
+});
+
+// A page missing from one version but present in another is the interesting
+// case: the reader asked for something real, just not here.
+const elsewhere = computed(
+  () =>
+    (
+      props.error.data as {
+        elsewhere?: { version: { label: string }; path: string }[];
+      }
+    )?.elsewhere ?? []
+);
+</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>
+
+      <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>
+        <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>
+</template>

package/app/layouts/changelog.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+/**
+ * The shell a release history gets: the releases beside it, and a reading
+ * column for the entries.
+ *
+ * THE SECOND NAME THROUGH THE SHARED SLOT (`DuxtSectionType.layout`), and the
+ * shape a changelog needs — which is not the shape the API reference needed.
+ * `reference` hands its page the whole column it has, because parameter tables
+ * and a request client want it; a release note is prose, and prose set across
+ * that column is unreadable. So the column is capped at a measure and the
+ * releases take the sidebar. Both shells stop at the same 90rem the header and
+ * the footer do — the difference is what each gives its page inside that.
+ *
+ * Two differences from `docs`, and both follow from what the pages ARE. The
+ * sidebar is the release list rather than a prose tree — same navigation, same
+ * collection, because a generated section is an ordinary collection and its
+ * pages are the releases. And the reading column is capped inside a window that
+ * still leaves room for the contents on the right, which is why `main` carries
+ * a width rather than the page: a layout owns how wide its prose is set, and
+ * `pages/[...slug].vue` draws the same column for every generated section.
+ *
+ * The contents column IS there, and its links are not the ones Content found:
+ * a release page's headings are drawn by `ChangelogGroup` from a prop, so the
+ * outline is read back off the page's own AST — see `generated-toc.ts`.
+ *
+ * Bound only by the SPLIT granularity. A changelog asked for as the one file it
+ * was written as is an ordinary docs page and renders in the docs shell — see
+ * `changelogSectionType.layout`.
+ *
+ * A page rendered here draws its own header: see the `owned` computed in
+ * `pages/[...slug].vue`.
+ */
+const { data: navigation } = await useDuxtNavigation();
+
+const { items } = useDuxtSection(navigation);
+
+// The header the sticky columns hang under — `6.5rem` with the section row,
+// less without it. Handed down as a variable so the columns here and the
+// contents column `pages/[...slug].vue` draws all read one value.
+const { headerOffset } = useDuxtSectionRow();
+</script>
+
+<template>
+  <div
+    class="flex min-h-[100dvh] flex-col bg-background text-foreground"
+    :style="{ '--duxt-header-offset': headerOffset }"
+  >
+    <DuxtSkipLink />
+
+    <DuxtProgress />
+    <DuxtShortcuts />
+
+    <DuxtHeader />
+    <DuxtSections />
+
+    <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"
+        >
+          <DuxtNavigation
+            :items="items"
+            :label="$t('duxt.changelog.releases')"
+          />
+        </div>
+      </div>
+
+      <main
+        id="duxt-main"
+        tabindex="-1"
+        class="mx-auto flex w-full min-w-0 max-w-5xl flex-1 outline-none"
+      >
+        <slot />
+      </main>
+    </div>
+
+    <DuxtFooter />
+
+    <!-- One toaster per layout: toast() needs a mounted target to draw into. -->
+    <UiToaster position="bottom-right" />
+  </div>
+</template>

package/app/layouts/default.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// The landing layout: full width, no sidebar. Docs pages opt into `docs`.
+</script>
+
+<template>
+  <div class="flex min-h-[100dvh] flex-col bg-background text-foreground">
+    <DuxtSkipLink />
+
+    <!-- How far down the page the reader is, and the `?` sheet listing every
+         key the theme binds. -->
+    <DuxtProgress />
+    <DuxtShortcuts />
+
+    <DuxtHeader />
+    <main id="duxt-main" tabindex="-1" class="flex-1 outline-none">
+      <slot />
+    </main>
+    <DuxtFooter />
+
+    <!-- One toaster per layout: toast() needs a mounted target to draw into. -->
+    <UiToaster position="bottom-right" />
+  </div>
+</template>

package/app/layouts/docs.vue

@@ -0,0 +1,62 @@
+<script setup lang="ts">
+const { data: navigation } = await useDuxtNavigation();
+
+const { items } = useDuxtSection(navigation);
+
+// The header the sticky columns hang under — `6.5rem` with the section row,
+// less without it. Handed down as a variable so the columns here and the
+// contents column `pages/[...slug].vue` draws all read one value.
+const { headerOffset } = useDuxtSectionRow();
+</script>
+
+<template>
+  <div
+    class="flex min-h-[100dvh] flex-col bg-background text-foreground"
+    :style="{ '--duxt-header-offset': headerOffset }"
+  >
+    <DuxtSkipLink />
+
+    <!-- How far down the page the reader is, and the `?` sheet listing every
+         key the theme binds. -->
+    <DuxtProgress />
+    <DuxtShortcuts />
+
+    <DuxtHeader />
+
+    <!-- The section row sits with the docs, not in the global header: the
+         landing page has no sections to show. -->
+    <DuxtSections />
+
+    <!-- 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. -->
+    <div class="mx-auto flex w-full max-w-[90rem] flex-1 gap-8 px-4 lg:px-8">
+      <!-- A div, not an aside. The <nav> inside is the landmark and carries
+           the label; a second, unnamed `complementary` around it only makes a
+           screen reader's landmark list longer. -->
+      <!-- A section with one page has nothing to navigate: the sidebar would be
+           a column listing the page the reader is already on. It drops out, and
+           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"
+        >
+          <DuxtNavigation :items="items" :label="$t('duxt.nav.docs')" />
+        </div>
+      </div>
+
+      <main
+        id="duxt-main"
+        tabindex="-1"
+        class="flex min-w-0 flex-1 outline-none"
+      >
+        <slot />
+      </main>
+    </div>
+
+    <DuxtFooter />
+
+    <!-- One toaster per layout: toast() needs a mounted target to draw into. -->
+    <UiToaster position="bottom-right" />
+  </div>
+</template>

package/app/layouts/reference.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+/**
+ * The layout a generated section's type binds when the docs shell will not do.
+ *
+ * THE FIRST NAME THROUGH THE SHARED SLOT (`DuxtSectionType.layout`), and the
+ * shape the API reference needs: the operations on the left, and the whole
+ * remaining width for the page — which then splits itself into the description
+ * and the client, because those two are properties of the operation and a
+ * layout cannot reach them.
+ *
+ * ONE difference from `docs`, and it is the sidebar: the endpoint list rather
+ * than a prose tree — the same navigation, from the same collection, because a
+ * generated section is an ordinary collection and its pages ARE the endpoints.
+ *
+ * The WIDTH is not a difference, and it was: this shell ran to 100rem where
+ * every other one on the site stops at 90rem, so on a wide screen the reference
+ * stood ten rem past the header above it and the footer below it. The argument
+ * for it — parameter tables and a request client want room — was an argument
+ * about the OPERATION, which splits itself and can be given that room there;
+ * it was never an argument for the page hanging over the site's own edge.
+ * Alignment with the header is worth more than ten rem nobody asked for.
+ *
+ * A page rendered here draws its own header: see the `owned` computed in
+ * `pages/[...slug].vue`.
+ *
+ * NO CONTENTS COLUMN, and it is this layout that has to say so — the page
+ * cannot know. An operation already fills its right-hand side with the request
+ * client, and a second sticky column beside that one is two columns of
+ * furniture around a table of parameters. `provide` before any await, or the
+ * value never reaches the page.
+ */
+provide(DUXT_ASIDE, false);
+
+const { data: navigation } = await useDuxtNavigation();
+
+const { items } = useDuxtSection(navigation);
+
+// The header the sticky columns hang under — `6.5rem` with the section row,
+// less without it. Handed down as a variable so the columns here and the
+// contents column `pages/[...slug].vue` draws all read one value.
+const { headerOffset } = useDuxtSectionRow();
+</script>
+
+<template>
+  <div
+    class="flex min-h-[100dvh] flex-col bg-background text-foreground"
+    :style="{ '--duxt-header-offset': headerOffset }"
+  >
+    <DuxtSkipLink />
+
+    <DuxtProgress />
+    <DuxtShortcuts />
+
+    <DuxtHeader />
+    <DuxtSections />
+
+    <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"
+        >
+          <DuxtNavigation
+            :items="items"
+            :label="$t('duxt.openapi.endpoints')"
+          />
+        </div>
+      </div>
+
+      <main
+        id="duxt-main"
+        tabindex="-1"
+        class="flex min-w-0 flex-1 outline-none"
+      >
+        <slot />
+      </main>
+    </div>
+
+    <DuxtFooter />
+
+    <!-- One toaster per layout: toast() needs a mounted target to draw into. -->
+    <UiToaster position="bottom-right" />
+  </div>
+</template>

package/app/lib/utils.ts

@@ -0,0 +1,7 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/** Merge conditional class lists, letting later Tailwind utilities win. */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

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

@@ -0,0 +1,57 @@
+/**
+ * The layout slot a generated section's type renders through.
+ *
+ * A ROUTE MIDDLEWARE, and deliberately not `<NuxtLayout>` inside the page: a
+ * layout rendered from within a page is remounted on every navigation, which
+ * would rebuild the header, the section row and the sidebar — losing their
+ * scroll and their open groups — on every click of a docs site. `setPageLayout`
+ * from a middleware is the one place the choice can be made before the route
+ * resolves, so the layout stays where it is and only its name changes.
+ *
+ * Cheap where no type names a layout: `generatedLayout` filters to the sections
+ * that do and answers before matching a single prefix. The path it is handed is
+ * still computed either way — arguments are evaluated first — which is one
+ * `stripLocalePrefix` per navigation and nothing else.
+ */
+export default defineNuxtRouteMiddleware((to) => {
+  const sources =
+    (useAppConfig().duxt as DuxtConfig | undefined)?.resolvedSources ?? [];
+
+  const layout = generatedLayout(
+    // The DOCUMENTATION path, as every other lookup in the theme means it: the
+    // locale translates the interface, not the content tree, so the manifest's
+    // prefixes have no locale segment in front of them.
+    stripLocalePrefix(to.path, localeCodes()),
+    sources
+  );
+
+  // Cast for the reason `DuxtCollectionName` is a plain string: the name is
+  // DATA. Nuxt types `setPageLayout` by the layouts it found in this app, and a
+  // type's layout is named in a config the layer cannot see at build time.
+  //
+  // The FUNCTION is cast, not the argument. `setPageLayout` is generic over
+  // `keyof NuxtLayouts`, so `Parameters<typeof setPageLayout>[0]` resolves
+  // through a conditional on the type parameter and lands back on `string` —
+  // which is then not assignable to the parameter it was derived from. Casting
+  // the call signature says the one thing that is actually true: this name is
+  // checked at run time, against a registry the compiler cannot see.
+  if (layout) (setPageLayout as (name: string) => void)(layout);
+});
+
+/**
+ * The locales the site serves, read off the plugin rather than `useI18n()`.
+ *
+ * `useI18n()` wants a component instance; a middleware has none, and
+ * `nuxtApp.$i18n` is what @nuxtjs/i18n exposes for exactly this. Absent — a
+ * consumer who removed the module — the path is used as it stands, which is
+ * correct for a site with no locale prefixes to strip.
+ */
+function localeCodes(): string[] {
+  const i18n = useNuxtApp().$i18n as
+    | { locales?: { value?: (string | { code: string })[] } }
+    | undefined;
+
+  return (i18n?.locales?.value ?? []).map((entry) =>
+    typeof entry === 'string' ? entry : entry.code
+  );
+}