@kirchdev/duxt 0.1.0

package/app/components/DuxtPageInfo.vue

@@ -0,0 +1,194 @@
+<script setup lang="ts">
+/**
+ * Where the page came from, under the table of contents.
+ *
+ * Not at the foot of the ARTICLE, which is where it sat first and where it read
+ * as an afterthought below the prev/next links. "Edit this page", when it last
+ * changed and who wrote it are one question — provenance — and the right-hand
+ * column is already the one answering what a page IS rather than what it says.
+ *
+ * Everything here is derived. The `sources` entry carries the repository, the
+ * ref and the folder; the page carries its own file name and, where git could
+ * be asked, its history.
+ */
+const props = defineProps<{
+  /**
+   * Lay it out as a ROW rather than a stack.
+   *
+   * The column form is the one this was written for; the row is what it needs
+   * where there is no column to sit in — under the article of a page whose
+   * layout fills the right-hand side itself, where a stack of three lines
+   * hanging off the left edge under a full-width rule reads as leftovers.
+   */
+  row?: boolean;
+  page:
+    | {
+        stem?: string;
+        /**
+         * The day a dated page names — a release, and nothing else so far.
+         * It REPLACES the last commit rather than joining it: every release of
+         * a changelog shares one file, so their last commit is the same date on
+         * all of them and says nothing about any.
+         */
+        date?: string;
+        /** The diff a release was cut from, where its heading linked one. */
+        compare?: string;
+        lastUpdated?: string;
+        contributors?: { name: string; commits: number; username?: string }[];
+      }
+    | null
+    | undefined;
+}>();
+
+const page = computed(() => props.page);
+
+const { source } = useDuxtCollection();
+const { locale, t } = useI18n();
+
+const file = computed(() => {
+  // A GENERATED SECTION has no file per page: every page in it was split out of
+  // one artefact, and `path` is that artefact. Sending the reader to a file
+  // named after the URL would be a 404 with an edit form on it.
+  if (source.value?.generated) return source.value.path;
+
+  return page.value?.stem
+    ? sourceFilePath(
+        page.value.stem,
+        source.value?.prefix ?? '',
+        source.value?.path ?? 'docs'
+      )
+    : undefined;
+});
+
+const link = computed(() =>
+  file.value
+    ? sourceLink(
+        source.value?.repositoryUrl,
+        source.value?.ref,
+        source.value?.refKind,
+        file.value
+      )
+    : undefined
+);
+
+/**
+ * The day this page names, where it names one.
+ *
+ * `timeZone: 'UTC'`, unlike the commit date below it: a release date is a
+ * calendar day and not a moment, so read as local time it is the day before for
+ * every reader west of Greenwich — and a different day on the server than in
+ * the browser, which is a hydration mismatch as well as a wrong date. The
+ * commit date IS a moment and is left alone.
+ */
+const released = computed(() => changelogDate(page.value?.date, locale.value));
+
+const updated = computed(() => {
+  // The page's own date wins. Both lines would be true and only one is useful:
+  // a changelog's releases all live in one file, so the commit that last
+  // touched it dates every release the same day, which is at best the newest
+  // one's and at worst years off.
+  if (page.value?.date) return undefined;
+
+  const value = page.value?.lastUpdated;
+  if (!value) return undefined;
+
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return undefined;
+
+  return new Intl.DateTimeFormat(locale.value, { dateStyle: 'medium' }).format(
+    date
+  );
+});
+
+const contributors = computed(() => page.value?.contributors ?? []);
+
+/**
+ * What this page lets a reader DO with where it came from.
+ *
+ * The compare link goes above the edit link, because the two are the same kind
+ * of thing pointing at the same repository — where the page came FROM, rather
+ * than what it says — and it is the one a reader of a release wants first: the
+ * notes are the summary, the diff is what actually shipped.
+ */
+const actions = computed(() => {
+  const entries: { icon: string; label: string; to: string; external: true }[] =
+    [];
+
+  // The diff a release links, where its heading linked an absolute one — see
+  // the parser. `git-compare` rather than the crossed arrows: at 14 px beside a
+  // pencil the arrows read as a knot rather than as two branches.
+  if (page.value?.compare) {
+    entries.push({
+      icon: 'lucide:git-compare',
+      label: t('duxt.page.compare'),
+      to: page.value.compare,
+      external: true
+    });
+  }
+
+  // A tag has no edit form — see `sourceLink`. The label follows the kind
+  // rather than promising a form that answers with a 404.
+  if (link.value) {
+    entries.push({
+      icon: link.value.kind === 'edit' ? 'lucide:pencil' : 'lucide:file-code-2',
+      label: t(
+        link.value.kind === 'edit' ? 'duxt.page.edit' : 'duxt.page.view'
+      ),
+      to: link.value.url,
+      external: true
+    });
+  }
+
+  return entries;
+});
+
+/** The dated facts, in the order they are read. */
+const notes = computed(() => {
+  const lines: string[] = [];
+
+  if (released.value) {
+    lines.push(t('duxt.page.released', { date: released.value }));
+  } else if (updated.value) {
+    lines.push(t('duxt.page.lastUpdated', { date: updated.value }));
+  }
+
+  return lines;
+});
+</script>
+
+<template>
+  <!-- One block, one spacing rule — see `DuxtMetaList`. The contributors are
+       the one part that is neither an action nor a line of text, so they go in
+       the slot and are spaced as one more item. -->
+  <DuxtMetaList :row="row" :actions="actions" :notes="notes">
+    <div v-if="contributors.length" :class="row ? '' : 'space-y-1.5'">
+      <p>{{ $t('duxt.page.contributors') }}</p>
+
+      <ul class="flex flex-wrap items-center gap-x-2 gap-y-1.5">
+        <li
+          v-for="person in contributors"
+          :key="person.name"
+          class="flex items-center gap-1.5"
+        >
+          <img
+            v-if="person.username"
+            :src="`https://github.com/${person.username}.png?size=40`"
+            alt=""
+            width="18"
+            height="18"
+            loading="lazy"
+            class="size-[18px] rounded-full border"
+          />
+          <span
+            v-else
+            aria-hidden="true"
+            class="flex size-[18px] items-center justify-center rounded-full border bg-muted text-[9px] font-medium"
+          >
+            {{ person.name.slice(0, 1).toUpperCase() }}
+          </span>
+          <span>{{ person.name }}</span>
+        </li>
+      </ul>
+    </div>
+  </DuxtMetaList>
+</template>

package/app/components/DuxtPageNav.vue

@@ -0,0 +1,93 @@
+<script setup lang="ts">
+import type { ContentNavigationItem } from '@nuxt/content';
+// Previous and next within the current section only. Content's own
+// surroundings query walks the whole collection in one flat order, so the last
+// page of one section would offer a "next" that lands in another — crossing a
+// section is the section row's job, not a link reading "the next page".
+const props = defineProps<{ path: string }>();
+
+const { data: navigation } = await useDuxtNavigation();
+
+const { items } = useDuxtSection(navigation);
+const localeLink = useDuxtLink();
+
+/** The section's pages in reading order, groups flattened into their children. */
+const pages = computed(() => {
+  const flat: ContentNavigationItem[] = [];
+
+  const walk = (entries: ContentNavigationItem[]) => {
+    for (const entry of entries) {
+      if (entry.page !== false) flat.push(entry);
+      if (entry.children?.length) walk(entry.children);
+    }
+  };
+
+  walk(items.value);
+  return flat;
+});
+
+const index = computed(() =>
+  pages.value.findIndex((page) => page.path === props.path)
+);
+const previous = computed(() =>
+  index.value > 0 ? pages.value[index.value - 1] : undefined
+);
+const next = computed(() =>
+  index.value >= 0 ? pages.value[index.value + 1] : undefined
+);
+
+/**
+ * `[` and `]` move through the section the same way the two links do.
+ *
+ * Bound here rather than in the layout because this component already knows
+ * which pages are adjacent — a second computation of that would be a second
+ * chance to disagree with what the links say.
+ */
+const router = useRouter();
+
+onDuxtShortcut(
+  (event) =>
+    (event.key === '[' || event.key === ']') &&
+    !event.metaKey &&
+    !event.ctrlKey,
+  (event) => {
+    const target = event.key === '[' ? previous.value : next.value;
+    if (target?.path) void router.push(localeLink(target.path)!);
+  }
+);
+</script>
+
+<template>
+  <nav
+    v-if="previous || next"
+    class="mt-16 grid gap-4 border-t pt-8 sm:grid-cols-2"
+    :aria-label="$t('duxt.nav.pagination')"
+  >
+    <NuxtLink
+      v-if="previous"
+      :to="localeLink(previous.path)"
+      class="flex flex-col gap-1 rounded-lg border p-4 transition-colors hover:bg-accent"
+    >
+      <span class="flex items-center gap-1 text-xs text-muted-foreground">
+        <Icon name="lucide:arrow-left" class="size-3.5" />
+        {{ $t('duxt.nav.previous') }}
+      </span>
+      <span class="font-medium">{{ previous.title }}</span>
+    </NuxtLink>
+    <span v-else class="hidden sm:block" />
+
+    <NuxtLink
+      v-if="next"
+      :to="localeLink(next.path)"
+      class="flex flex-col gap-1 rounded-lg border p-4 text-right transition-colors hover:bg-accent"
+    >
+      <span
+        class="flex items-center justify-end gap-1 text-xs text-muted-foreground"
+      >
+        {{ $t('duxt.nav.next') }}
+        <Icon name="lucide:arrow-right" class="size-3.5" />
+      </span>
+      <span class="font-medium">{{ next.title }}</span>
+    </NuxtLink>
+  </nav>
+</template>

package/app/components/DuxtPreviewSkeleton.vue

@@ -0,0 +1,262 @@
+<script setup lang="ts">
+/**
+ * The SHAPE of a documentation page, for the moment before the real one is up.
+ *
+ * The landing page's window frames a second copy of the application, and
+ * between the band arriving and that copy booting there was an empty box the
+ * height of a page. A spinner would have said "wait"; this says what is coming.
+ *
+ * DRAWN RATHER THAN PHOTOGRAPHED, and that is the whole point of it. A
+ * screenshot has to exist, has to be produced twice for the two themes, and is
+ * wrong the day the theme changes — none of which a layer can ask of every site
+ * that extends it. This is the theme's own tokens in the theme's own measures,
+ * so it is correct in light and dark by construction and needs no asset. A site
+ * that would rather show a real picture sets `duxt.landing.preview.src`.
+ *
+ * SIZED BY ITS BOX, NOT BY THE WINDOW. Every breakpoint here is a container
+ * query — `@2xl` where the page says `sm`, `@5xl` where it says `lg`, `@7xl`
+ * where it says `xl`, all at the same widths. It has to be: this poster is
+ * drawn in the LANDING PAGE's document, so a viewport breakpoint asks how wide
+ * the browser is when the question is how wide the window is. Half-width, in a
+ * showcase band on a wide screen, that drew the full desktop page — two
+ * sidebars, a section row — squeezed into a 30 rem box. The frame underneath
+ * has no such problem: an iframe carries a viewport of its own.
+ *
+ * THE MEASURES ARE THE REAL ONES, not a sketch: `h-14` for the header, `w-56`
+ * for each of the two columns, the section row at `lg` where `DuxtSections`
+ * appears, the same `gap-8` and `max-w-[90rem]` the docs layout sets. A poster
+ * whose columns sit somewhere else than the page's is a poster the reader
+ * watches jump when the frame takes over — which is the one thing it exists to
+ * prevent.
+ *
+ * Nothing here is content: no words, no links, no headings. It is `aria-hidden`
+ * where it stands, and every bar is a rounded rectangle.
+ *
+ * THREE SHAPES, because the window points at three kinds of page and one shape
+ * fitted only the first. A poster whose layout is not the layout that arrives
+ * is worse than a plain box: it says a page is coming and then a different one
+ * does, which reads as the frame having loaded the wrong thing.
+ */
+withDefaults(
+  defineProps<{
+    /**
+     * `docs` — a Markdown page: two sidebars, prose, a code card.
+     * `api` — an operation list: a run of method-and-path rows.
+     * `text` — a plain-text artefact such as `llms.txt`: no chrome at all,
+     * because the browser renders one in a bare monospace document.
+     */
+    variant?: DuxtSkeletonVariant;
+  }>(),
+  { variant: 'docs' }
+);
+</script>
+
+<template>
+  <!-- A PLAIN-TEXT ARTEFACT. No header, no sidebars, no article measures: the
+       browser renders `text/plain` as a bare monospace document, and drawing a
+       documentation page in front of one is a promise the frame then breaks.
+       Ragged line lengths, because that is what a file looks like. -->
+  <div
+    v-if="variant === 'text'"
+    class="flex h-full w-full flex-col gap-2.5 overflow-hidden bg-background p-4 font-mono"
+  >
+    <div
+      v-for="(width, index) in [
+        22, 0, 74, 68, 0, 30, 0, 88, 82, 90, 76, 84, 70, 86, 62, 0, 26, 0, 80,
+        72, 88, 66, 84, 78, 90, 58
+      ]"
+      :key="index"
+      class="h-2.5 shrink-0 rounded"
+      :class="width ? 'bg-muted/50' : ''"
+      :style="width ? { width: `${width}%` } : { height: '0.25rem' }"
+    />
+  </div>
+
+  <div v-else class="flex h-full w-full flex-col bg-background">
+    <!-- The header: the wordmark, the navbar row, the version pill and search.
+         `h-14` plus its border, as `DuxtHeader` sets it. -->
+    <div class="flex h-14 shrink-0 items-center gap-4 border-b px-4 @5xl:px-8">
+      <div class="h-4 w-16 rounded bg-muted" />
+
+      <!-- The navbar row, then a clear gap, then the version pill, the search
+           box at its real `w-56` and the three icons. Measured off the page
+           this stands in for, not sketched. -->
+      <div class="ml-auto hidden items-center gap-6 @2xl:flex">
+        <div
+          v-for="width in [32, 62, 50, 42]"
+          :key="width"
+          class="h-3 rounded bg-muted/60"
+          :style="{ width: `${width}px` }"
+        />
+      </div>
+
+      <div class="ml-6 flex items-center gap-6">
+        <div class="h-5 w-12 rounded-full bg-muted/60" />
+        <div class="h-8 w-56 rounded-md border bg-muted/30 @max-2xl:w-24" />
+        <div class="hidden gap-6 @2xl:flex">
+          <div
+            v-for="icon in 3"
+            :key="icon"
+            class="size-4 rounded bg-muted/60"
+          />
+        </div>
+      </div>
+    </div>
+
+    <!-- The section row. Hidden below `lg`, exactly where the real one is. -->
+    <div
+      class="hidden h-11 shrink-0 items-center gap-1 border-b px-4 @5xl:flex @5xl:px-8"
+    >
+      <div
+        v-for="(width, index) in [58, 54, 40, 58, 72, 108, 24]"
+        :key="width"
+        class="flex items-center gap-2 rounded-md px-3 py-1.5"
+        :class="index === 0 ? 'bg-accent' : ''"
+      >
+        <div class="size-3.5 rounded bg-muted/60" />
+        <div class="h-3 rounded bg-muted/60" :style="{ width: `${width}px` }" />
+      </div>
+    </div>
+
+    <div
+      class="mx-auto flex min-h-0 w-full max-w-[90rem] flex-1 gap-8 px-4 @5xl:px-8"
+    >
+      <!-- The section's own pages, one line each — a docs sidebar lists a
+           branch, not a table of contents. -->
+      <div class="hidden w-56 shrink-0 flex-col gap-1 py-8 @5xl:flex">
+        <div
+          v-for="(width, index) in [64, 56, 76]"
+          :key="width"
+          class="flex items-center gap-2 rounded-md px-2 py-1.5"
+          :class="index === 0 ? 'bg-accent' : ''"
+        >
+          <div class="size-3.5 rounded bg-muted/60" />
+          <div
+            class="h-3 rounded bg-muted/60"
+            :style="{ width: `${width}px` }"
+          />
+        </div>
+      </div>
+
+      <!-- The article: breadcrumb, title with the copy control beside it, the
+           lead, the rule under the header, then prose and a code card. -->
+      <div class="flex min-w-0 max-w-3xl flex-1 flex-col py-8">
+        <div class="h-2.5 w-16 rounded bg-muted/60" />
+
+        <div class="mt-3 flex items-start justify-between gap-4">
+          <div class="h-9 w-56 rounded bg-muted" />
+          <div class="h-8 w-36 rounded-md border bg-muted/30" />
+        </div>
+
+        <div class="mt-4 h-3.5 w-4/5 rounded bg-muted/60" />
+
+        <div class="my-8 h-px w-full bg-border" />
+
+        <!-- AN OPERATION LIST, for a tag page built from an OpenAPI document:
+             one lead line and then a run of bordered rows, each a method pill,
+             a path and a summary pushed to the end. Nothing like the prose and
+             the code card below it, which is exactly why it is drawn
+             separately — the two pages look nothing alike. -->
+        <template v-if="variant === 'api'">
+          <div class="h-2.5 w-4/5 rounded bg-muted/60" />
+
+          <div class="mt-6 flex flex-col gap-2">
+            <div
+              v-for="(row, index) in [
+                { method: 34, path: 52, summary: 62 },
+                { method: 38, path: 52, summary: 68 },
+                { method: 34, path: 88, summary: 60 },
+                { method: 44, path: 88, summary: 66 },
+                { method: 46, path: 88, summary: 64 }
+              ]"
+              :key="index"
+              class="flex items-center gap-3 rounded-lg border px-3 py-2.5"
+            >
+              <div
+                class="h-5 shrink-0 rounded bg-muted"
+                :style="{ width: `${row.method}px` }"
+              />
+              <div
+                class="h-2.5 rounded bg-muted/60"
+                :style="{ width: `${row.path}px` }"
+              />
+              <div
+                class="ml-auto h-2.5 rounded bg-muted/40"
+                :style="{ width: `${row.summary}px` }"
+              />
+            </div>
+          </div>
+        </template>
+
+        <template v-else>
+          <div class="flex flex-col gap-2.5">
+            <div
+              v-for="line in ['100%', '88%']"
+              :key="line"
+              class="h-2.5 rounded bg-muted/60"
+              :style="{ width: line }"
+            />
+          </div>
+
+          <div class="my-6 overflow-hidden rounded-lg border">
+            <div class="flex h-11 items-center gap-2 border-b bg-muted/40 px-3">
+              <div class="size-3.5 rounded bg-muted/60" />
+              <div class="h-2.5 w-20 rounded bg-muted/60" />
+            </div>
+            <div class="flex flex-col gap-2 p-4">
+              <div
+                v-for="line in ['58%', '44%', '20%']"
+                :key="line"
+                class="h-2.5 rounded bg-muted/40"
+                :style="{ width: line }"
+              />
+            </div>
+          </div>
+
+          <div class="h-2.5 w-3/5 rounded bg-muted/60" />
+          <div class="mt-8 h-5 w-40 rounded bg-muted" />
+        </template>
+      </div>
+
+      <!-- The contents column: the page's own outline, then the aside's fixed
+           links, then the provenance under a rule. -->
+      <div class="hidden w-56 shrink-0 flex-col gap-6 py-8 @7xl:flex">
+        <div class="flex flex-col gap-2">
+          <div class="h-3 w-24 rounded bg-muted" />
+          <div class="h-2.5 w-20 rounded bg-muted/60" />
+          <div class="h-2.5 w-28 rounded bg-muted/60" />
+        </div>
+
+        <div class="flex flex-col gap-2">
+          <div class="h-3 w-20 rounded bg-muted" />
+          <div
+            v-for="width in [76, 68, 88, 72]"
+            :key="width"
+            class="flex items-center gap-2"
+          >
+            <div class="size-3 rounded bg-muted/60" />
+            <div
+              class="h-2.5 rounded bg-muted/60"
+              :style="{ width: `${width}px` }"
+            />
+          </div>
+        </div>
+
+        <!-- Provenance under its rule: the edit link, when it last changed,
+             and who wrote it beside their avatar. -->
+        <div class="flex flex-col gap-3 border-t pt-4">
+          <div class="flex items-center gap-2">
+            <div class="size-3 rounded bg-muted/60" />
+            <div class="h-2.5 w-20 rounded bg-muted/60" />
+          </div>
+          <div class="h-2.5 w-32 rounded bg-muted/40" />
+          <div class="h-2.5 w-16 rounded bg-muted/40" />
+          <div class="flex items-center gap-2">
+            <div class="size-4 rounded-full bg-muted/60" />
+            <div class="h-2.5 w-16 rounded bg-muted/40" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/DuxtProgress.vue

@@ -0,0 +1,45 @@
+<script setup lang="ts">
+/**
+ * How far down the page the reader is.
+ *
+ * A two-pixel rule under the header rather than a number: on a long reference
+ * page the useful question is "am I near the end", and a percentage answers it
+ * worse than a line does. `aria-hidden`, because it says nothing a screen
+ * reader cannot already ask the document.
+ *
+ * Measured against the document, not against a scroll container, so it is
+ * correct on the docs layout and on the landing page alike. Passive listener:
+ * this must never be the thing that makes scrolling stutter.
+ */
+const progress = ref(0);
+
+function measure() {
+  const doc = document.documentElement;
+  const scrollable = doc.scrollHeight - doc.clientHeight;
+
+  progress.value = scrollable > 0 ? (doc.scrollTop / scrollable) * 100 : 0;
+}
+
+onMounted(() => {
+  measure();
+  window.addEventListener('scroll', measure, { passive: true });
+  window.addEventListener('resize', measure, { passive: true });
+
+  onBeforeUnmount(() => {
+    window.removeEventListener('scroll', measure);
+    window.removeEventListener('resize', measure);
+  });
+});
+</script>
+
+<template>
+  <div
+    aria-hidden="true"
+    class="pointer-events-none fixed inset-x-0 top-0 z-50 h-0.5"
+  >
+    <div
+      class="h-full bg-primary transition-[width] duration-75"
+      :style="{ width: `${progress}%` }"
+    />
+  </div>
+</template>