@kirchdev/duxt 0.1.0

package/app/composables/useDuxtAnimatedHeight.ts

@@ -0,0 +1,155 @@
+/**
+ * A box whose height FOLLOWS its content instead of switching to it.
+ *
+ * Two places need this and they need exactly the same thing: the request-sample
+ * card, whose `curl` of four lines becomes a Go client of twenty, and
+ * `CodeGroup`, whose tabs hold files of different lengths. Both used to change
+ * height in a single frame, which moves everything below them at once.
+ *
+ * MEASURED, because CSS cannot do it. `transition: height` needs two computed
+ * values to travel between, and a box that sizes to its content is `auto`
+ * before and `auto` after — no change a browser can see. `interpolate-size:
+ * allow-keywords` does not help either: it makes `auto` a value a transition
+ * can REACH, not one that transitions to itself.
+ *
+ * A `ResizeObserver` rather than a watcher on whatever changed, and that is the
+ * part that matters. Highlighted code arrives asynchronously — the string
+ * changes on the click, the markup a tick or two later — so anything measuring
+ * straight after the click measures the content on its way out. The observer
+ * measures what is actually there, whenever it is there, and catches the other
+ * reasons a box resizes too: the window narrowing, a line rewrapping, a font
+ * finishing loading.
+ */
+
+/**
+ * The step the height moves in — a line of code plus its leading.
+ *
+ * A threshold on the CHANGE was the first attempt and it still jumped: below it
+ * the box snapped, above it the box slid, and a reader switching tabs got both.
+ * A grid removes the small changes instead of deciding what to do about them. A
+ * reflow of two pixels lands on the same step and is not a height change at
+ * all; a different file is at least one step away and always animates.
+ *
+ * The buffer it adds is never more than a line's worth of space under the last
+ * line.
+ */
+const HEIGHT_STEP = 24;
+
+/**
+ * How long a measurement has to hold still before it counts.
+ *
+ * Long enough to cover an unmount, a mount and the tick that swaps plain code
+ * for highlighted code; short enough that the box does not feel late. Every
+ * resize inside the window replaces the one before it, so only the last one is
+ * ever acted on.
+ */
+const SETTLE_MS = 60;
+
+/**
+ * How long the content takes to come back once the box is on its way.
+ *
+ * Shorter than the box's own 300ms on purpose: the point is to be readable
+ * again well before the box stops moving, not to make the reader wait out two
+ * animations in a row.
+ */
+const FADE_MS = 200;
+
+export function useDuxtAnimatedHeight(
+  shell: Readonly<import('vue').ShallowRef<HTMLElement | null>>,
+  body: Readonly<import('vue').ShallowRef<HTMLElement | null>>,
+  /** Whether to follow at all — a layout that should size at once passes false. */
+  enabled: () => boolean = () => true
+): void {
+  onMounted(() => {
+    if (!enabled() || !('ResizeObserver' in window)) return;
+
+    const box = shell.value;
+    const content = body.value;
+    if (!box || !content) return;
+
+    // The box carries the border and `box-sizing: border-box`, so its height
+    // has to include what that border takes; the content's height does not.
+    const chrome = box.offsetHeight - box.clientHeight;
+
+    const step = (height: number) =>
+      Math.ceil((height + chrome) / HEIGHT_STEP) * HEIGHT_STEP;
+
+    let last = step(content.offsetHeight);
+
+    // PIN THE STARTING HEIGHT, without animating to it.
+    //
+    // Until a height is set the box is `auto`, and `auto` is not a value a
+    // transition can travel FROM — so the very first change jumped instead of
+    // sliding, however carefully everything after it was handled. Set once, on
+    // mount, with the transition off for that one frame.
+    box.style.transition = 'none';
+    box.style.height = `${last}px`;
+    requestAnimationFrame(() => {
+      box.style.transition = '';
+    });
+
+    let settle: ReturnType<typeof setTimeout> | undefined;
+
+    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    const observer = new ResizeObserver(() => {
+      const next = step(content.offsetHeight);
+      if (next === last) return;
+
+      // THE CONTENT FADES WHILE THE BOX TRAVELS.
+      //
+      // The new panel is there the instant the tab is clicked, and until the
+      // box has grown to fit it, `overflow-hidden` cuts it off — a taller
+      // sample appeared with its last lines sliced away for the length of the
+      // animation. Hidden for that moment and faded back in as the box arrives,
+      // there is nothing cut off to see: what a reader watches is one sample
+      // replacing another, not a box catching up with its contents.
+      //
+      // Set with the transition off, so it is instant going out and animated
+      // coming back — a fade in both directions would be twice as long a wait
+      // for the same effect.
+      if (!reduced.matches) {
+        content.style.transition = 'none';
+        content.style.opacity = '0';
+      }
+
+      // ONLY THE VALUE IT SETTLES ON, never the ones on the way.
+      //
+      // A tab change is not one resize, it is several: the old panel unmounts,
+      // leaving nothing for a frame; the new one mounts unhighlighted; the
+      // highlighted markup replaces it a tick later. Followed literally, the box
+      // collapsed to nothing, sprang open at one size and slid to another —
+      // which is the "the tab disappears first, then it expands" of it.
+      //
+      // Waiting for the measurement to hold still skips all of that: one
+      // animation, from the height before the click to the height after it.
+      clearTimeout(settle);
+      settle = setTimeout(() => {
+        const settled = step(content.offsetHeight);
+
+        if (settled !== last) {
+          last = settled;
+          box.style.height = `${settled}px`;
+        }
+
+        if (!reduced.matches) {
+          requestAnimationFrame(() => {
+            content.style.transition = `opacity ${FADE_MS}ms ease-out`;
+            content.style.opacity = '1';
+          });
+        }
+      }, SETTLE_MS);
+    });
+
+    observer.observe(content);
+
+    onBeforeUnmount(() => {
+      observer.disconnect();
+      clearTimeout(settle);
+      box.style.height = '';
+      box.style.transition = '';
+      content.style.opacity = '';
+      content.style.transition = '';
+    });
+  });
+}

package/app/composables/useDuxtBreadcrumb.ts

@@ -0,0 +1,60 @@
+import type { ContentNavigationItem } from '@nuxt/content';
+import type { MaybeRefOrGetter } from 'vue';
+
+/**
+ * The trail from the section down to a page.
+ *
+ * Lives in a composable rather than in `DuxtBreadcrumb` because two things want
+ * it: the component draws it, and the page emits it as `BreadcrumbList`
+ * JSON-LD. Computing it twice is how the drawn trail and the structured one
+ * would come to disagree.
+ */
+export async function useDuxtBreadcrumb(path: MaybeRefOrGetter<string>) {
+  // EVERY composable call happens before the await, deliberately. This is a
+  // plain async function, not a `<script setup>` block, so nothing restores the
+  // Nuxt instance after an await inside it — a call placed below one dies with
+  // E1001 and takes the whole page render with it. `useAsyncData`'s return is
+  // awaitable as well as reactive, which is what lets the fetch be started here
+  // and waited for at the end.
+  const navigation = useDuxtNavigation();
+  const { source } = useDuxtCollection();
+  const { section } = useDuxtSection(navigation.data);
+
+  const trail = computed<ContentNavigationItem[]>(() => {
+    const current = toValue(path);
+
+    // The trail starts at the section — the entry the reader clicked in the row
+    // above — and continues with what lies below the source's own prefix.
+    const below = trailBelowPrefix(
+      navigation.data.value ?? [],
+      current,
+      source.value?.prefix ?? ''
+    );
+
+    const head = section.value?.to
+      ? [
+          {
+            title: section.value.label,
+            path: section.value.to
+          } as ContentNavigationItem
+        ]
+      : [];
+
+    // A section's index page is the section: both carry `/duxt/getting-started`,
+    // so the trail listed the same destination twice under two names — the
+    // config's label and the page's own title. Keep the first of each path.
+    const seen = new Set<string>();
+
+    return [...head, ...below].filter((item) => {
+      const itemPath = item.path ?? '';
+      if (seen.has(itemPath)) return false;
+
+      seen.add(itemPath);
+      return true;
+    });
+  });
+
+  await navigation;
+
+  return trail;
+}

package/app/composables/useDuxtChoice.ts

@@ -0,0 +1,28 @@
+/**
+ * A choice the reader made, remembered across pages.
+ *
+ * A cookie rather than localStorage, and the reason is the jump: storage is
+ * readable only in the browser, so the server always renders the default and
+ * the control visibly switches after hydration. Reading it earlier does not
+ * help — the server has already sent the wrong markup. A cookie travels with
+ * the request, so the first byte is already correct.
+ *
+ * Still privacy-clean: first-party, no identifier, no analytics, a value the
+ * reader set by clicking a tab. Under GDPR/ePrivacy that is a functional
+ * preference the reader asked for, not something needing consent — the same
+ * category as a language or theme choice. SameSite=Lax keeps it off cross-site
+ * requests, and it expires after a year.
+ *
+ * ONE PER KIND OF CONTROL, never one per instance: a reader who picked `pnpm`
+ * on the install page means it on every other page, and the same is true of
+ * `curl` over `fetch` and of the form over raw JSON. A component that stores
+ * its own answer per block asks the same question again three screens later.
+ */
+export function useDuxtChoice(name: string) {
+  return useCookie<string | undefined>(`duxt-${name}`, {
+    sameSite: 'lax',
+    maxAge: 60 * 60 * 24 * 365,
+    // No `secure: true`: it would drop the cookie on a plain-HTTP preview.
+    default: () => undefined
+  });
+}

package/app/composables/useDuxtCollection.ts

@@ -0,0 +1,89 @@
+import { sourcesForRoute } from '../../sources-resolve';
+
+/**
+ * Which collection serves the current route.
+ *
+ * `duxtSources` generates one collection per source, version and language,
+ * named after what it serves. Every query in the theme has to ask the right
+ * one, or a site with two sources shows nothing at all — the collection a
+ * single source produces is called `docs`, and the ones a versioned or
+ * translated site produces are not.
+ *
+ * The choice itself is `sourcesForRoute`, pure and tested beside the resolver,
+ * so the devtools path debugger answers with the same chain rather than a
+ * second implementation of it. This composable is the reactive wrapper: the
+ * route, the locale, and vue-i18n's own fallback — used so the interface and
+ * the pages agree on where a missing translation resolves to.
+ *
+ * The manifest reaches the app through `app.config.ts`, because Content loads
+ * `content.config.ts` in its own pass and the app never sees the result. Both
+ * come from one call site; see the Sources reference.
+ */
+export function useDuxtCollection() {
+  const duxt = useDuxtConfig();
+  const path = useDuxtPath();
+  const { locale, fallbackLocale } = useI18n();
+
+  const sources = computed(() => duxt.resolvedSources ?? []);
+
+  /**
+   * The collections to try, best first.
+   *
+   * One entry on a site without translations, which is every site that does
+   * not set `locales` — and then this composable behaves exactly as it did
+   * before the key existed.
+   */
+  const chain = computed(() =>
+    sourcesForRoute(
+      path.value,
+      locale.value,
+      sources.value,
+      fallbackLocale.value as string | string[] | undefined
+    )
+  );
+
+  const current = computed(() => chain.value[0]);
+
+  /**
+   * The default-language entry for this prefix.
+   *
+   * The one collection guaranteed to hold every page, which is what a
+   * navigation tree has to be built from — see `overlayTranslations`.
+   */
+  const base = computed(
+    () =>
+      sources.value.find(
+        (source) =>
+          source.prefix === current.value?.prefix && source.isDefaultLocale
+      ) ?? current.value
+  );
+
+  /** Cast because the name is data: Content types collections from the config. */
+  const name = computed(
+    () => (current.value?.collection ?? 'docs') as DuxtCollectionName
+  );
+
+  return {
+    collection: name,
+    /** The complete tree's collection — the default language for this prefix. */
+    baseCollection: computed(
+      () => (base.value?.collection ?? 'docs') as DuxtCollectionName
+    ),
+    source: current,
+    /** The collections a missing page falls back to, after the first. */
+    fallbacks: computed(() => chain.value.slice(1)),
+    /**
+     * Whether this site declares translations at all.
+     *
+     * Without it the fallback banner cannot be told apart from the normal
+     * state of a single-language site: there, every locale but the default one
+     * is served the same pages by design, and announcing that as a missing
+     * translation would put a notice on six of seven languages of every duxt
+     * site that never asked for any of this.
+     */
+    translates: computed(() =>
+      sources.value.some((source) => source.locale && !source.isDefaultLocale)
+    ),
+    sources: computed(() => sources.value)
+  };
+}

package/app/composables/useDuxtConfig.ts

@@ -0,0 +1,47 @@
+import { toReactive } from '@vueuse/core';
+
+/**
+ * The layer's config, with the consumer's app.config merged over it and every
+ * text field resolved for the current locale.
+ *
+ * Two things happen here that a component should never have to know about:
+ *
+ *  - Nuxt's own app.config merge APPENDS arrays instead of replacing them, so
+ *    a consumer overriding `navigation` would get the layer's entries after
+ *    its own — see `duxt-config.ts`.
+ *  - a label may be a literal, an i18n key or a per-locale record, and
+ *    `resolveDuxtTexts` collapses all three to a string — see `duxt-text.ts`.
+ *  - a generated section's navbar entry is not in the config a human wrote at
+ *    all; it follows from the resolved manifest AND from where the reader
+ *    currently is — see `withGeneratedSections`.
+ *
+ * Resolving here rather than at each call site is the point: `DuxtHeader`,
+ * `DuxtFooter` and the rest keep writing `{{ section.label }}` and none of them
+ * imports i18n. `toReactive` keeps the result live, so switching language
+ * updates the navbar without a full page load.
+ */
+export function useDuxtConfig(): DuxtConfigResolved {
+  const appConfig = useAppConfig();
+  const { t, te, locale } = useI18n();
+  // The reader's position, because a section resolved per version has one
+  // entry and it is the one for the version being read.
+  const path = useDuxtPath();
+
+  return toReactive(
+    computed(() =>
+      resolveDuxtTexts(
+        // After the merge, because a generated section's entry is APPENDED to
+        // whatever list the consumer wrote — see `withGeneratedSections`.
+        withGeneratedSections(
+          mergeDuxtConfig(appConfig.duxt, duxtDefaults),
+          path.value
+        ),
+        locale.value,
+        // `te` first, so a literal never reaches `t` and never produces a
+        // "key not found" warning. duxt's OWN missing keys still warn, which a
+        // global `missingWarn: false` would have silenced along with them.
+        (key) => (te(key) ? t(key) : undefined)
+      )
+    )
+  ) as DuxtConfigResolved;
+}

package/app/composables/useDuxtNavigation.ts

@@ -0,0 +1,87 @@
+import type { ContentNavigationItem } from '@nuxt/content';
+
+/**
+ * Which collections the navigation is being fetched from.
+ *
+ * `useState`, and neither a module-level ref nor a closure, because the two
+ * obvious options each break one half of this:
+ *
+ *  - A MODULE-LEVEL ref is one variable shared by every request the server has
+ *    in flight. With two of them and two awaits in the handler below, one
+ *    request could read what another had just written — the server then
+ *    rendered one collection's navigation and the browser another, and the
+ *    hydration mismatch took the page down with it.
+ *  - A CLOSURE is a new function on every call, and Nuxt compares handlers by
+ *    reference: several components asking for the same key with a handler each
+ *    is NUXT_E3004, after which the first handler wins and the rest are
+ *    silently ignored.
+ *
+ * `useState` is per request and reachable from a handler that stays one stable
+ * function, which is what both halves need.
+ */
+const useNavigationSource = () =>
+  useState('duxt-navigation-source', () => ({
+    base: 'docs' as DuxtCollectionName,
+    translation: 'docs' as DuxtCollectionName
+  }));
+
+/**
+ * The tree of the default language, wearing the translated titles.
+ *
+ * Never the translation's own tree: a partly translated documentation would
+ * then lose every page it has not reached yet — pages the fallback serves
+ * perfectly well, so hiding them from the sidebar leaves the reader with no way
+ * to them at all. Structure from the original, wording from the translation;
+ * see `overlayTranslations`.
+ */
+const handler = async (): Promise<ContentNavigationItem[]> => {
+  // Read BEFORE the first await: after it, the route may have moved on.
+  const { base, translation } = useNavigationSource().value;
+
+  const tree = await queryCollectionNavigation(base as DuxtCollectionArg, [
+    'icon',
+    'description'
+  ]);
+
+  // Before the overlay: a folder's title comes from its own index page, and a
+  // translated index has to be able to carry that up with it.
+  const named = titleFoldersFromIndex(tree);
+
+  if (translation === base) return named;
+
+  const translated = await queryCollection(translation as DuxtCollectionArg)
+    .select('path', 'title', 'description')
+    .all();
+
+  return titleFoldersFromIndex(
+    overlayTranslations(
+      named,
+      new Map(translated.map((page) => [page.path, page]))
+    )
+  );
+};
+
+/**
+ * The navigation tree for the collection serving this route.
+ *
+ * The key tracks both collections: two sources are two trees and must not share
+ * one cache entry, and neither may two languages of one.
+ */
+export function useDuxtNavigation() {
+  const { collection, baseCollection } = useDuxtCollection();
+  const source = useNavigationSource();
+
+  // Kept in step before every fetch, including the ones `watch` triggers.
+  watchEffect(() => {
+    source.value = {
+      base: baseCollection.value,
+      translation: collection.value
+    };
+  });
+
+  return useAsyncData<ContentNavigationItem[]>(
+    () => `duxt-navigation-${baseCollection.value}-${collection.value}`,
+    handler,
+    { watch: [collection, baseCollection] }
+  );
+}

package/app/composables/useDuxtPageFocus.ts

@@ -0,0 +1,30 @@
+/**
+ * Move focus to the page's own heading after a client-side navigation.
+ *
+ * Vue Router replaces the view without touching focus, so after a sidebar click
+ * the focus is still on the link that was left behind: a keyboard reader's next
+ * Tab continues down the sidebar, and a screen reader is told nothing at all
+ * about the page that just arrived. Focusing the `<h1>` puts both back at the
+ * top of the new document.
+ *
+ * Not on the first paint. On a full load the focus is already at the start of
+ * the document, and taking it would scroll past the header before the reader
+ * has seen the page — so only a route CHANGE moves it.
+ *
+ * The announcement is a separate job, done by `<NuxtRouteAnnouncer>` in
+ * `app.vue`, which reads the new title into a live region.
+ */
+export function useDuxtPageFocus() {
+  const heading = ref<HTMLElement | null>(null);
+  const route = useRoute();
+
+  watch(
+    () => route.fullPath,
+    async () => {
+      await nextTick();
+      heading.value?.focus();
+    }
+  );
+
+  return heading;
+}

package/app/composables/useDuxtPath.ts

@@ -0,0 +1,42 @@
+/**
+ * The path the DOCUMENTATION is at, as opposed to the one the browser shows.
+ *
+ * The two differ by the locale segment. Read `stripLocalePrefix` for why every
+ * content lookup wants this one rather than `route.path`.
+ */
+export function useDuxtPath() {
+  const route = useRoute();
+  const { locales } = useI18n();
+
+  const codes = computed(() =>
+    locales.value.map((entry) =>
+      typeof entry === 'string' ? entry : entry.code
+    )
+  );
+
+  return computed(() => stripLocalePrefix(route.path, codes.value));
+}
+
+/**
+ * The counterpart: a documentation path, written back out as a link the
+ * current locale can be reached at.
+ *
+ * Only paths are localised. An absolute URL, a mail link or a bare hash passes
+ * through untouched, so the same helper serves the navbar's external entries
+ * and the sidebar's internal ones without either side special-casing the other.
+ */
+export function useDuxtLink() {
+  const localePath = useLocalePath();
+
+  return (to?: string) => {
+    if (!to?.startsWith('/')) return to;
+
+    // localePath resolves a route, and a trailing anchor is not part of one.
+    // Split it off and put it back, so a sidebar entry pointing at a heading
+    // keeps pointing at that heading.
+    const [path, hash] = to.split('#');
+    const localised = localePath(path!);
+
+    return hash ? `${localised}#${hash}` : localised;
+  };
+}