@kirchdev/duxt 0.1.0

package/app/components/DuxtVersion.vue

@@ -0,0 +1,168 @@
+<script setup lang="ts">
+/**
+ * The one place a version is shown.
+ *
+ * Before, the project's version sat as a badge beside the title while the
+ * documentation's versions lived in a separate dropdown on the far right —
+ * two controls saying different things, and the right-hand one appeared only
+ * on sources that have versions, so the icons beside it shifted as you moved
+ * between repositories.
+ *
+ * Now it is one element next to the title: a badge when there is nothing to
+ * choose, the same badge as a trigger when there is.
+ */
+
+/**
+ * `badge` is the header's inline pill. `block` is the mobile sheet's: a
+ * full-width control with its own caption, because in a column of navigation
+ * rows a bare pill reads as a label rather than as something to press.
+ */
+const props = withDefaults(defineProps<{ variant?: 'badge' | 'block' }>(), {
+  variant: 'badge'
+});
+
+const duxt = useDuxtConfig();
+const path = useDuxtPath();
+const localeLink = useDuxtLink();
+
+/**
+ * Versions come from the resolved source manifest, so the control can only
+ * offer what has a collection behind it, and only for the repository being
+ * read — one project's versions say nothing about another's. The list itself
+ * is `useDuxtVersion`'s, because the sheet asks for it too — see
+ * `versionChoices`.
+ */
+const { choices: versions } = useDuxtVersion();
+
+const current = computed(() =>
+  sourceForPath(
+    path.value,
+    versions.value.map((version) => ({ ...version, prefix: version.to ?? '' }))
+  )
+);
+
+const { t, te } = useI18n();
+
+/**
+ * The caption beside an entry.
+ *
+ * The list carries a translation KEY where the layer wrote one
+ * (`duxt.version.status.deprecated`) and a plain word where a consumer did, so
+ * a key that resolves is translated and anything else is shown as written.
+ * `asText` because the config type keeps `DuxtText` even though
+ * `useDuxtConfig` has already collapsed it to a string.
+ */
+function caption(version: DuxtLink) {
+  const value = asText(version.description);
+  if (!value) return undefined;
+
+  return te(value) ? t(value) : value;
+}
+
+/** Same page, other version: swap the prefix rather than jumping to its root. */
+function pathIn(version: { to?: string }) {
+  return localeLink(
+    versionPath(path.value, current.value?.to, version.to ?? '/')
+  );
+}
+</script>
+
+<template>
+  <UiDropdownMenu v-if="versions.length > 1">
+    <!-- The trigger is a real <button>, with the Badge inside it. reka-ui puts
+         `aria-haspopup` and `aria-expanded` on whatever element it is handed,
+         and a <span> is allowed neither — which axe reports and a screen
+         reader acts on. -->
+    <UiDropdownMenuTrigger as-child>
+      <!-- Built like shadcn's own large sidebar button: a square mark, then
+           two lines, then the chevrons. The VERSION LEADS and the caption sits
+           under it — the reverse of what this was, where the reader met the
+           word "Version" before the number they came to read. The caption is
+           the version's own lifecycle where it has one ("default",
+           "maintenance"), because on a switcher that is the fact worth the
+           second line; the label is what is left when it has none. -->
+      <button
+        v-if="props.variant === 'block'"
+        type="button"
+        class="flex w-full cursor-pointer items-center gap-2 rounded-md border p-2 text-left transition-colors hover:bg-accent"
+      >
+        <span
+          class="flex aspect-square size-8 shrink-0 items-center justify-center rounded-lg bg-primary text-primary-foreground"
+        >
+          <Icon name="lucide:git-branch" class="size-4" />
+        </span>
+
+        <span class="grid min-w-0 flex-1 leading-tight">
+          <span class="truncate font-mono text-sm font-medium">
+            {{ current?.label ?? duxt.version }}
+          </span>
+          <span class="truncate text-xs text-muted-foreground">
+            {{ (current && caption(current)) ?? $t('duxt.version.label') }}
+          </span>
+        </span>
+
+        <Icon
+          name="lucide:chevrons-up-down"
+          class="size-4 shrink-0 text-muted-foreground"
+        />
+      </button>
+
+      <button v-else type="button" class="cursor-pointer">
+        <UiBadge
+          variant="secondary"
+          class="gap-1 font-mono text-[10px] hover:bg-accent"
+        >
+          {{ current?.label ?? duxt.version }}
+          <Icon name="lucide:chevron-down" class="size-3 opacity-60" />
+        </UiBadge>
+      </button>
+    </UiDropdownMenuTrigger>
+
+    <!-- A project with thirty versions would otherwise open a menu the height
+         of the window: reka's available-height only stops it at the viewport
+         edge. `min()` keeps that cap and adds a shorter one, so the list
+         scrolls at about ten entries instead of filling the screen. -->
+    <UiDropdownMenuContent
+      align="start"
+      class="max-h-[min(20rem,var(--reka-dropdown-menu-content-available-height))]"
+      :class="
+        props.variant === 'block'
+          ? 'w-[var(--reka-dropdown-menu-trigger-width)]'
+          : 'w-44'
+      "
+    >
+      <UiDropdownMenuItem
+        v-for="version in versions"
+        :key="version.to"
+        as-child
+      >
+        <NuxtLink :to="pathIn(version)" class="flex items-center gap-2">
+          <Icon
+            name="lucide:check"
+            class="size-3.5"
+            :class="version.label === current?.label ? '' : 'opacity-0'"
+          />
+          <span class="font-mono text-xs">{{ version.label }}</span>
+          <span
+            v-if="caption(version)"
+            class="ml-auto text-xs text-muted-foreground"
+          >
+            {{ caption(version) }}
+          </span>
+        </NuxtLink>
+      </UiDropdownMenuItem>
+    </UiDropdownMenuContent>
+  </UiDropdownMenu>
+
+  <!-- Nothing to choose: the project's own version, stated rather than offered.
+       Always the badge, `block` included — a bordered box with a caption and no
+       control in it looks like a select that has stopped working, and the sheet
+       puts this one beside the brand rather than in the switcher's strip. -->
+  <UiBadge
+    v-else-if="duxt.version"
+    variant="secondary"
+    class="font-mono text-[10px]"
+  >
+    {{ duxt.version }}
+  </UiBadge>
+</template>

package/app/components/DuxtVersionBanner.vue

@@ -0,0 +1,109 @@
+<script setup lang="ts">
+/**
+ * The visible half of the version problem.
+ *
+ * `canonical` and `noindex` tell a crawler which version to serve; they tell
+ * the reader nothing. Someone who arrived on v0.7.0 from a search result, or
+ * from a link in an old issue, sees documentation that looks exactly like the
+ * current one. Either half alone leaves one audience wrong, so the head tags in
+ * `[...slug].vue` and this banner ship together.
+ */
+const { current, kind, preferred, preferredPath, shouldWarn } =
+  useDuxtVersion();
+const localeLink = useDuxtLink();
+
+const message = computed(() => `duxt.version.${kind.value}`);
+
+/**
+ * An upcoming version is not a mistake to correct.
+ *
+ * Its reader is told what changes under them, not to upgrade — so the link out
+ * is offered only where going to the current version is actually the answer.
+ */
+const offersUpgrade = computed(() =>
+  ['old', 'deprecated', 'eol'].includes(kind.value)
+);
+
+/**
+ * Drawn as a Callout, because the theme already has a notice and this is one.
+ *
+ * The first version of this invented a second: a full coloured border over a
+ * tinted surface, beside a Callout three paragraphs below it in the same quiet
+ * style. Two notice styles on one page is one too many — a reader learns what a
+ * bordered panel means once. So the colour sits on the icon and a thin left
+ * rule, the surface stays close to the page, and the state reads as a title
+ * with the sentence beneath it.
+ *
+ * Same palette as `Callout`'s variants, on purpose: sky for information, amber
+ * for old, red for over. Whole class names rather than composed ones, because
+ * Tailwind scans source text and a class assembled at runtime is not in the
+ * stylesheet.
+ */
+const TONES = {
+  upcoming: {
+    rule: 'border-l-sky-500',
+    text: 'text-sky-500',
+    icon: 'lucide:flask-conical'
+  },
+  old: {
+    rule: 'border-l-amber-500',
+    text: 'text-amber-500',
+    icon: 'lucide:triangle-alert'
+  },
+  deprecated: {
+    rule: 'border-l-red-500',
+    text: 'text-red-500',
+    icon: 'lucide:triangle-alert'
+  },
+  eol: {
+    rule: 'border-l-red-500',
+    text: 'text-red-500',
+    icon: 'lucide:circle-off'
+  }
+} as const;
+
+const tone = computed(
+  () => TONES[kind.value as keyof typeof TONES] ?? TONES.old
+);
+</script>
+
+<template>
+  <!-- The icon belongs to the FIRST LINE of the text, not to a line of its own.
+       As siblings of one flex row the sentence became its own item and wrapped
+       below, leaving the icon stranded above it. -->
+  <UiAlert
+    v-if="shouldWarn"
+    role="status"
+    class="mb-6 flex items-start gap-2.5 rounded-md border border-l-2 bg-muted/30 px-3 py-2.5"
+    :class="tone.rule"
+  >
+    <Icon
+      :name="tone.icon"
+      class="mt-[3px] size-4 shrink-0"
+      :class="tone.text"
+    />
+
+    <div class="min-w-0 flex-1">
+      <UiAlertTitle class="mb-0.5 font-medium text-foreground">
+        {{ $t(`duxt.version.titles.${kind}`) }}
+      </UiAlertTitle>
+
+      <UiAlertDescription class="text-muted-foreground">
+        {{
+          $t(message, {
+            version: current?.version ?? '',
+            preferred: preferred?.version ?? ''
+          })
+        }}
+
+        <NuxtLink
+          v-if="offersUpgrade && preferred"
+          :to="localeLink(preferredPath)"
+          class="font-medium text-foreground underline underline-offset-4"
+        >
+          {{ $t('duxt.version.goToCurrent', { preferred: preferred.version }) }}
+        </NuxtLink>
+      </UiAlertDescription>
+    </div>
+  </UiAlert>
+</template>

package/app/components/OgImage/Duxt.satori.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+/**
+ * The layer's Open Graph image.
+ *
+ * Rendered by satori, not a browser, so this is a deliberately small subset of
+ * CSS: flexbox, colours, borders, and nothing that needs layout beyond that. No
+ * icon font and no external image, because satori resolves neither.
+ *
+ * The `.satori` in the file name is not decoration: nuxt-og-image reads the
+ * renderer out of it and ignores a template that does not name one.
+ *
+ * A consumer overrides it the ordinary way — its own
+ * `app/components/OgImage/Duxt.satori.vue` wins over the layer's, and pages go
+ * on asking for `'Duxt'`.
+ */
+withDefaults(
+  defineProps<{
+    title?: string;
+    description?: string;
+    site?: string;
+    version?: string;
+  }>(),
+  {
+    title: 'Documentation',
+    description: '',
+    site: '',
+    version: ''
+  }
+);
+</script>
+
+<template>
+  <div
+    style="
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+      width: 100%;
+      height: 100%;
+      padding: 80px;
+      background: #0a0a0a;
+      color: #fafafa;
+      font-family: sans-serif;
+    "
+  >
+    <div style="display: flex; align-items: center; font-size: 30px">
+      <span style="font-weight: 700">{{ site }}</span>
+      <span
+        v-if="version"
+        style="
+          margin-left: 20px;
+          padding: 6px 16px;
+          border: 2px solid #404040;
+          border-radius: 999px;
+          font-size: 22px;
+          color: #a3a3a3;
+        "
+      >
+        {{ version }}
+      </span>
+    </div>
+
+    <div style="display: flex; flex-direction: column">
+      <div style="font-size: 68px; font-weight: 700; line-height: 1.1">
+        {{ title }}
+      </div>
+      <div
+        v-if="description"
+        style="
+          margin-top: 24px;
+          font-size: 30px;
+          line-height: 1.4;
+          color: #a3a3a3;
+        "
+      >
+        {{ description.slice(0, 140) }}
+      </div>
+    </div>
+
+    <div style="display: flex; height: 10px; background: #fafafa" />
+  </div>
+</template>

package/app/components/content/Accordion.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { AccordionRoot } from 'reka-ui';
+
+/**
+ * `::accordion` around `:::accordion-item{label="…"}` blocks.
+ *
+ * On reka-ui's primitives, like the tree and the tabs, for the same reason:
+ * a hand-rolled disclosure has no keyboard handling, no `aria-expanded` and no
+ * relationship between the trigger and the region it opens.
+ *
+ * `type="multiple"` on purpose. A FAQ where opening one answer closes the one
+ * you were half-way through is a worse FAQ.
+ */
+export interface DuxtAccordionContext {
+  register: (label: string) => string;
+}
+
+const items = ref<{ value: string; label: string }[]>([]);
+
+provide<DuxtAccordionContext>('duxt-accordion', {
+  register(label: string) {
+    const value = `item-${items.value.length}`;
+    items.value.push({ value, label });
+    return value;
+  }
+});
+
+// The item component imports its own primitives from reka-ui. Re-exporting them
+// here would be an ES module export inside <script setup>, which the SFC
+// compiler rejects outright — a type export is fine, a value export is not.
+</script>
+
+<template>
+  <AccordionRoot type="multiple" class="my-6 rounded-lg border">
+    <slot />
+  </AccordionRoot>
+</template>

package/app/components/content/AccordionItem.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import {
+  AccordionContent,
+  AccordionHeader,
+  AccordionItem as Item,
+  AccordionTrigger
+} from 'reka-ui';
+import type { DuxtAccordionContext } from './Accordion.vue';
+
+const props = defineProps<{ label?: string; icon?: string }>();
+
+const parent = inject<DuxtAccordionContext | undefined>(
+  'duxt-accordion',
+  undefined
+);
+
+const value = parent?.register(props.label ?? '') ?? 'item-0';
+</script>
+
+<template>
+  <Item :value="value" class="border-b last:border-b-0">
+    <AccordionHeader>
+      <AccordionTrigger
+        class="group flex w-full cursor-pointer items-center gap-2 px-4 py-3 text-left text-sm font-medium hover:bg-accent/50"
+      >
+        <Icon v-if="icon" :name="icon" class="size-4 text-muted-foreground" />
+        <span class="min-w-0">{{ label }}</span>
+        <Icon
+          name="lucide:chevron-down"
+          class="ml-auto size-4 shrink-0 text-muted-foreground transition-transform group-data-[state=open]:rotate-180"
+        />
+      </AccordionTrigger>
+    </AccordionHeader>
+
+    <!-- No enter/leave animation: the keyframes shadcn's own Accordion ships
+         come with that component, which this theme does not install. An
+         unstyled `animate-accordion-down` class is a silent no-op, and a
+         disclosure that opens instantly is not worse than one that appears
+         to. -->
+    <AccordionContent class="overflow-hidden">
+      <div class="px-4 pb-3 text-sm [&>*:last-child]:mb-0">
+        <slot />
+      </div>
+    </AccordionContent>
+  </Item>
+</template>

package/app/components/content/Callout.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+// MDC: `::callout{type="warning"}`. Quieter than a coloured panel — the colour
+// sits on the icon and a thin left rule, the surface stays close to the page,
+// and the title reads as text rather than as a warning label.
+const props = withDefaults(
+  defineProps<{
+    type?: 'info' | 'tip' | 'warning' | 'danger';
+    title?: string;
+    icon?: string;
+  }>(),
+  { type: 'info' }
+);
+
+const variants = {
+  info: { icon: 'lucide:info', rule: 'border-l-sky-500', text: 'text-sky-500' },
+  tip: {
+    icon: 'lucide:lightbulb',
+    rule: 'border-l-emerald-500',
+    text: 'text-emerald-500'
+  },
+  warning: {
+    icon: 'lucide:triangle-alert',
+    rule: 'border-l-amber-500',
+    text: 'text-amber-500'
+  },
+  danger: {
+    icon: 'lucide:octagon-alert',
+    rule: 'border-l-red-500',
+    text: 'text-red-500'
+  }
+};
+
+const variant = computed(() => variants[props.type]);
+</script>
+
+<template>
+  <UiAlert
+    class="my-5 flex items-start gap-2.5 rounded-md border border-l-2 bg-muted/30 px-3 py-2.5"
+    :class="variant.rule"
+  >
+    <Icon
+      :name="icon ?? variant.icon"
+      class="mt-[3px] size-4 shrink-0"
+      :class="variant.text"
+    />
+
+    <div class="min-w-0 flex-1">
+      <UiAlertTitle v-if="title" class="mb-0.5 font-medium text-foreground">
+        {{ title }}
+      </UiAlertTitle>
+      <UiAlertDescription
+        class="text-muted-foreground [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 [&_a]:text-foreground [&_code]:text-foreground [&_p]:my-1.5"
+      >
+        <slot />
+      </UiAlertDescription>
+    </div>
+  </UiAlert>
+</template>

package/app/components/content/ChangelogGroup.vue

@@ -0,0 +1,91 @@
+<script setup lang="ts">
+/**
+ * One group of a release — "Features", "Bug Fixes", whatever the file said.
+ *
+ * MDC: `::changelog-group{name}`, written by `sections-changelog.ts` around the
+ * entries it found under one heading. The NAME IS THE FILE'S OWN, verbatim and
+ * untranslated: release-please, changesets and Keep a Changelog each write
+ * their own set, in the language the project is kept in, and a layer that
+ * mapped them onto a fixed taxonomy would drop the first heading it did not
+ * recognise. The count beside it is the entries this group lists.
+ *
+ * The entries themselves arrive in the SLOT, as the Markdown they were written
+ * as — so the search indexes them, `llms-full.txt` carries them and the copy
+ * button hands a model prose rather than a component call.
+ *
+ * A LABEL, NOT A HEADLINE. The name is set small, upper-case and in the
+ * group's own tone, above a list that closes up under it — the shape a release
+ * note actually has. Set as a 20-pixel headline it claimed the weight of a
+ * chapter for a word that names four bullet points, and six of them down a page
+ * read as six sections rather than as one release. It is still an `<h2>`: the
+ * outline, the contents column and the anchor are unchanged, and only its
+ * setting says what it is worth.
+ *
+ * The COLOUR is the one thing added to the name, and it is the same colour the
+ * group has on the overview — see `changelogTone`. Here it is the tone's TEXT
+ * pair rather than the dot's fill: a run of words and a six-pixel dot do not
+ * clear contrast at the same lightness. It stays a hint and never a meaning: a
+ * name the hint list does not know still gets a stable colour of its own, which
+ * is what makes the same kind of change scannable down a page of forty releases
+ * in any language.
+ *
+ * The `⚠` release-please prefixes its breaking block with is DRAWN AWAY rather
+ * than parsed away — see `changelogLabel`. The name it matches, anchors and
+ * filters on is still the file's own, whole.
+ *
+ * The entries' own markers are GREY, and deliberately not the tone. The colour
+ * is already stated once, in the label directly above them; stated again on
+ * every line it stopped being a signal and became a page of confetti — which is
+ * the failure a hint makes when it is repeated rather than placed. They are
+ * styled from `duxt.css`, because they arrive as Markdown from the slot.
+ */
+const props = defineProps<{ name: string; count?: number }>();
+
+/**
+ * The heading's anchor, so one group of one release can be linked to.
+ *
+ * Shared with the contents column, which is built from the page's AST and
+ * never sees this component render — a slug computed in both places is a
+ * contents column whose links go nowhere. See `app/utils/changelog.ts`.
+ */
+const anchor = computed(() => changelogAnchor(props.name));
+
+const tone = computed(() => changelogTone(props.name));
+</script>
+
+<template>
+  <section class="mt-9 first:mt-5">
+    <!-- Flex rather than inline runs, which is what put the count a few pixels
+         off the word beside it: a badge set with `align-middle` sits on the
+         font's own middle, and neither an upper-case label nor a 0.75rem number
+         is centred there. A flex line centres the boxes, and `leading-none`
+         is what makes the number's box its digits — with the inherited line
+         height it sits low by the difference. -->
+    <h2
+      :id="anchor"
+      class="duxt-label group mb-3 flex scroll-mt-28 items-center gap-2"
+      :class="tone.text"
+    >
+      <a v-if="anchor" :href="`#${anchor}`" class="duxt-heading-link">
+        <span class="duxt-anchor" aria-hidden="true">#</span>
+        {{ changelogLabel(name) }}
+      </a>
+      <template v-else>{{ changelogLabel(name) }}</template>
+
+      <!-- Outside the link: a count is a fact about the group, not part of the
+           words it is called. A `span`, because a heading holds phrasing
+           content. Its own tracking, because the label's letter-spacing is for
+           upper-case words and pushes a number away from nothing. -->
+      <span
+        v-if="count"
+        class="text-xs leading-none font-medium tracking-normal text-muted-foreground tabular-nums"
+      >
+        {{ count }}
+      </span>
+    </h2>
+
+    <div class="duxt-release">
+      <slot />
+    </div>
+  </section>
+</template>