@kirchdev/duxt 0.1.0

package/app/components/content/PackageManagers.vue

@@ -0,0 +1,187 @@
+<script setup lang="ts">
+// `::package-managers{command="add -D @kirchdev/duxt"}` — one command, every
+// manager, in a single box: tabs and copy button sit in the code block's own
+// header rather than floating above a separate card.
+const props = defineProps<{
+  command: string;
+  managers?: DuxtPackageManager[];
+}>();
+
+const duxt = useDuxtConfig();
+
+// Per block, then the site's configured order, then all four.
+const offered = computed(
+  () => props.managers ?? duxt.packageManagers ?? duxtPackageManagers
+);
+
+/**
+ * A manager that cannot express this command gets NO TAB.
+ *
+ * Berry has no `outdated` and npm no `patch`, and the nearest relative in each
+ * case does a different job — so a tab there would be a control that lies.
+ * Dropping it reuses what the block could already do: it may list fewer
+ * managers than the reader's cookie covers, and falls back to its own first tab.
+ * `modules/validate.ts` reports which page asked, so the omission is not silent.
+ */
+const managers = computed(() =>
+  offered.value.filter(
+    (manager) => packageCommand(manager, props.command) !== undefined
+  )
+);
+
+/**
+ * The mark each manager is drawn with.
+ *
+ * vscode-icons, because it carries the real colours in the file itself — the
+ * same collection every file name and every fence language on this site is
+ * drawn from. What stood here before was simple-icons, which is monochrome by
+ * design, plus eight hand-set hex values: two per manager, because one cannot
+ * serve both themes. That table is gone with it.
+ */
+const managerIcons: Record<DuxtPackageManager, string> = {
+  npm: 'vscode-icons:file-type-npm',
+  pnpm: 'vscode-icons:file-type-pnpm',
+  yarn: 'vscode-icons:file-type-yarn',
+  bun: 'vscode-icons:file-type-bun'
+};
+
+/**
+ * pnpm, and pnpm alone, needs a second spelling.
+ *
+ * Its mark is orange squares AND WHITE ONES, so half the grid disappears on a
+ * white page. vscode-icons ships a `light` variant for exactly that — the white
+ * cells drawn `#4e4e4e` instead — and it ships one for no other manager here,
+ * which is the collection reaching the same conclusion. Two elements swapped by
+ * the theme class, the way the preview poster serves its two screenshots.
+ */
+const managerIconsLight: Partial<Record<DuxtPackageManager, string>> = {
+  pnpm: 'vscode-icons:file-type-light-pnpm'
+};
+
+const commands = computed(() =>
+  Object.fromEntries(
+    managers.value.map((manager) => [
+      manager,
+      packageCommand(manager, props.command)!
+    ])
+  )
+);
+
+const { data: highlighted } = await useAsyncData(
+  `package-managers-${props.command}`,
+  async () => {
+    const entries = await Promise.all(
+      Object.entries(commands.value).map(
+        async ([manager, command]) =>
+          [manager, await highlightCode(command, 'bash')] as const
+      )
+    );
+    return Object.fromEntries(entries);
+  }
+);
+
+// Shared across every block on the page and remembered between pages, so a
+// reader picks their manager once for the whole site. The value arrives with
+// the request, so the server renders the right tab and nothing jumps.
+const stored = usePackageManager();
+
+// A block can list fewer managers than the reader's choice covers; fall back to
+// its first rather than showing nothing.
+const active = computed<DuxtPackageManager>({
+  get: () =>
+    managers.value.find((manager) => manager === stored.value) ??
+    managers.value[0]!,
+  set: (value) => {
+    stored.value = value;
+  }
+});
+const copied = ref(false);
+const notify = useDuxtToast();
+const { t } = useI18n();
+
+async function copy() {
+  try {
+    await navigator.clipboard.writeText(commands.value[active.value]!);
+    copied.value = true;
+    notify.success(t('duxt.code.copiedToast'));
+    setTimeout(() => (copied.value = false), 2000);
+  } catch {
+    notify.error(
+      'Could not copy',
+      'The clipboard is unavailable in this context.'
+    );
+    // Clipboard is unavailable over plain HTTP; a failed copy stays silent.
+  }
+}
+</script>
+
+<template>
+  <!-- Nothing to show where NO manager can express the command: `active` has
+       no first tab to fall back on, and a card with an empty header reads as a
+       broken component rather than as a command nobody can run. The build
+       validator names the page. -->
+  <div
+    v-if="managers.length"
+    class="duxt-code my-6 overflow-hidden rounded-lg border bg-card"
+  >
+    <div
+      class="flex min-h-11 items-center gap-1 border-b bg-muted/40 px-2 py-1.5"
+    >
+      <button
+        v-for="manager in managers"
+        :key="manager"
+        type="button"
+        class="flex cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors"
+        :class="
+          active === manager
+            ? 'bg-background text-foreground shadow-sm'
+            : 'text-muted-foreground hover:bg-accent hover:text-foreground'
+        "
+        @click="active = manager"
+      >
+        <Icon
+          :name="
+            managerIconsLight[manager] ??
+            managerIcons[manager] ??
+            'lucide:terminal'
+          "
+          class="size-3.5"
+          :class="managerIconsLight[manager] ? 'dark:hidden' : ''"
+        />
+        <Icon
+          v-if="managerIconsLight[manager]"
+          :name="managerIcons[manager]"
+          class="hidden size-3.5 dark:block"
+        />
+        {{ manager }}
+      </button>
+
+      <UiButton
+        variant="ghost"
+        size="icon"
+        class="ml-auto size-7"
+        :aria-label="
+          copied ? $t('duxt.code.copied') : $t('duxt.code.copyCommand')
+        "
+        @click="copy"
+      >
+        <Icon
+          :name="copied ? 'lucide:check' : 'lucide:copy'"
+          class="size-3.5"
+        />
+      </UiButton>
+    </div>
+
+    <!-- eslint-disable-next-line vue/no-v-html -- Shiki output, built on the
+         server from this component's own prop, never from page content. -->
+    <div
+      v-if="highlighted?.[active]"
+      class="duxt-shell overflow-x-auto px-4 py-3 font-mono text-sm"
+      v-html="highlighted[active]"
+    />
+    <pre
+      v-else
+      class="overflow-x-auto px-4 py-3 font-mono text-sm"
+    ><code>{{ commands[active] }}</code></pre>
+  </div>
+</template>

package/app/components/content/PageCards.vue

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import type { ContentNavigationItem } from '@nuxt/content';
+// `::page-cards` on a section's index page: one card per child, taken from the
+// navigation, so a new page appears here without the index being edited.
+const props = defineProps<{ path?: string }>();
+
+const path = useDuxtPath();
+const localeLink = useDuxtLink();
+
+const { data: navigation } = await useDuxtNavigation();
+
+const base = computed(() => props.path ?? path.value);
+
+const items = computed(() => {
+  const branch = navigation.value?.find((item) => item.path === base.value);
+  return branch?.children?.filter((child) => child.path !== base.value) ?? [];
+});
+
+/** `icon` comes from frontmatter, which Content types as unknown. */
+const iconOf = (item: ContentNavigationItem) =>
+  typeof item.icon === 'string' ? item.icon : undefined;
+</script>
+
+<template>
+  <div v-if="items.length" class="not-typeset my-8 grid gap-4 sm:grid-cols-2">
+    <NuxtLink
+      v-for="item in items"
+      :key="item.path"
+      :to="localeLink(item.path)"
+    >
+      <UiCard
+        class="h-full transition-colors hover:border-foreground/20 hover:bg-accent/30"
+      >
+        <UiCardHeader>
+          <Icon
+            v-if="iconOf(item)"
+            :name="iconOf(item)!"
+            class="size-5 text-muted-foreground"
+          />
+          <UiCardTitle class="text-base">{{ item.title }}</UiCardTitle>
+          <UiCardDescription v-if="item.description">{{
+            item.description
+          }}</UiCardDescription>
+        </UiCardHeader>
+      </UiCard>
+    </NuxtLink>
+  </div>
+</template>

package/app/components/content/Partial.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { partialsCollection } from '../../../sources-resolve';
+
+/**
+ * `:partial{name="install"}` — a block written once and rendered in every
+ * source that needs it.
+ *
+ * Content ships no include directive, and across repositories that is a gap
+ * with no workaround: an install note that must read the same in three projects
+ * is copied into three projects and drifts. The partials collection is built
+ * from every source's `_partials/` folder, so a block defined in one repository
+ * is available to the pages of another.
+ *
+ * TRANSLATED like the pages around it, and through the same chain: a partials
+ * collection per language, tried best first, falling back to the untranslated
+ * original. Without that a German page including `:partial{name="install"}`
+ * renders an English block in the middle of German prose — which is worse than
+ * an untranslated page, because nothing on the page says it happened.
+ *
+ * A missing partial renders nothing rather than an error. A page whose install
+ * note failed to resolve is still a readable page; the build says so instead —
+ * see `modules/validate.ts`.
+ */
+const props = defineProps<{ name?: string }>();
+
+const { source, fallbacks } = useDuxtCollection();
+
+/**
+ * The collections to try, best first — the page's own chain, mapped onto the
+ * partials collections. The same order, deliberately: a page and the blocks it
+ * includes falling back to different languages is how a page ends up half
+ * translated.
+ */
+const chain = computed(() =>
+  [
+    ...new Set(
+      [source.value, ...fallbacks.value]
+        .filter(Boolean)
+        .map((entry) => partialsCollection(entry!))
+    )
+  ].map((name) => name as DuxtCollectionArg)
+);
+
+const { data: partial } = await useAsyncData(
+  () => `duxt-partial-${props.name}`,
+  async () => {
+    if (!props.name) return null;
+
+    for (const collection of chain.value) {
+      const found = await queryCollection(collection)
+        .where('stem', 'LIKE', `%_partials/${props.name}`)
+        .first();
+
+      if (found) return found;
+    }
+
+    return null;
+  },
+  { watch: [() => props.name, chain] }
+);
+</script>
+
+<template>
+  <ContentRenderer v-if="partial" :value="partial" />
+</template>

package/app/components/content/Preview.vue

@@ -0,0 +1,173 @@
+<script setup lang="ts">
+import { TabsContent, TabsList, TabsRoot, TabsTrigger } from 'reka-ui';
+
+/**
+ * `::preview` — a component rendered as the page renders it, with the MDC that
+ * produced it one tab away.
+ *
+ * The documentation of a theme has one problem no prose solves: a page can
+ * describe `::callout{type="warning"}`, and the reader still has to build the
+ * site to find out what it looks like. This block renders the real component in
+ * the real theme — same tokens, same dark mode, same page — so the example is
+ * the thing itself rather than a picture of it.
+ *
+ *     ::preview
+ *     :::callout{type="tip"}
+ *     Rendered by the page you are reading.
+ *     :::
+ *
+ *     #code
+ *     ```mdc
+ *     ::callout{type="tip"}
+ *     Rendered by the page you are reading.
+ *     ::
+ *     ```
+ *     ::
+ *
+ * The source is WRITTEN OUT in the `#code` slot rather than derived from the
+ * default slot, and that is a deliberate limit, not a shortcut: by the time this
+ * component exists its children are rendered VNodes, and the Markdown that
+ * produced them is gone — reconstructing it would mean re-serialising an AST
+ * into a syntax it never came from, and getting it subtly wrong on every block
+ * that nests. Two tabs and no `#code` is a valid block: the example renders and
+ * no source tab appears.
+ */
+const slots = useSlots();
+
+const hasCode = computed(() => Boolean(slots.code));
+const active = ref('preview');
+
+const { t } = useI18n();
+
+/**
+ * The fence in `#code`, read off its VNode — the same trick `::code-group`
+ * uses on its children. What it yields is the filename or the language, which
+ * is what the tab should say and which icon it should carry: a reader picking
+ * between an example and its source is picking between a rendered thing and a
+ * `.vue`, a `.md` or an `.mdc` file, and the icon says which without a word.
+ */
+const codeMeta = computed(() => {
+  const nodes = (slots.code?.() ?? []).flatMap((node) =>
+    Array.isArray(node.children) && typeof node.type === 'symbol'
+      ? (node.children as VNode[])
+      : [node]
+  );
+
+  const props = (nodes.find((node) => typeof node.type === 'object')?.props ??
+    {}) as { filename?: string; language?: string; code?: string };
+
+  return {
+    label: props.filename ?? props.language ?? t('duxt.code.source'),
+    icon: fileIcon(props.filename ?? props.language ?? 'md'),
+    code: props.code
+  };
+});
+
+/**
+ * The copy button lives up here rather than in the fence's own header, because
+ * the fence's header is hidden: it would say `mdc` directly under a tab that
+ * already says `mdc`, and one card does not need naming twice.
+ */
+const notify = useDuxtToast();
+const copied = ref(false);
+
+async function copy() {
+  const code = codeMeta.value.code;
+  if (!code) return;
+
+  try {
+    await navigator.clipboard.writeText(code);
+    copied.value = true;
+    notify.success(t('duxt.code.copiedToast'));
+    setTimeout(() => (copied.value = false), 2000);
+  } catch {
+    notify.error(t('duxt.page.copyFailed'));
+  }
+}
+
+const tabs = computed(() => [
+  { value: 'preview', label: t('duxt.code.preview'), icon: 'lucide:eye' },
+  { value: 'code', label: codeMeta.value.label, icon: codeMeta.value.icon }
+]);
+</script>
+
+<template>
+  <!-- No tabs at all when there is no source: a tab strip with one tab is a
+       control that cannot be operated, and reka would still put it in the
+       accessibility tree as one. -->
+  <div v-if="!hasCode" class="my-6">
+    <slot />
+  </div>
+
+  <!-- One card, built like the package-manager block and the code block beside
+       it: a header of pills, then the panel. Three blocks on a page that all
+       switch between things should not switch in three different shapes.
+
+       One surface for the whole card, example and source alike: switching
+       tabs should change what is in the box, not what the box is made of. -->
+  <TabsRoot
+    v-else
+    v-model="active"
+    class="my-6 overflow-hidden rounded-lg border bg-card"
+  >
+    <!-- The header row is the flex container, and the strip is one child of
+         it: a `tablist` may hold tabs and nothing else, and a button inside one
+         is an `aria-required-children` failure — latent here only because it
+         renders on the source tab, which is not the tab a page loads on. -->
+    <div
+      class="flex min-h-11 items-center gap-1 border-b bg-muted/40 px-2 py-1.5"
+    >
+      <TabsList
+        class="flex items-center gap-1"
+        :aria-label="$t('duxt.code.previewTabs') as string"
+      >
+        <TabsTrigger
+          v-for="tab in tabs"
+          :key="tab.value"
+          :value="tab.value"
+          class="flex cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm"
+        >
+          <Icon :name="tab.icon" class="size-3.5" />
+          {{ tab.label }}
+        </TabsTrigger>
+      </TabsList>
+
+      <!-- Right of the tabs, where every other card on the site puts it. Only
+           on the source tab: a copy button beside a rendered example copies
+           something the reader cannot see. -->
+      <UiButton
+        v-if="active === 'code' && codeMeta.code"
+        variant="ghost"
+        size="icon"
+        class="ml-auto size-7"
+        :aria-label="copied ? $t('duxt.code.copied') : $t('duxt.code.copy')"
+        @click="copy"
+      >
+        <Icon
+          :name="copied ? 'lucide:check' : 'lucide:copy'"
+          class="size-3.5"
+        />
+      </UiButton>
+    </div>
+
+    <TabsContent value="preview" class="outline-none">
+      <!-- The example on the card's own surface, its outer margins taken off:
+           a callout carries `my-6`, and inside a padded panel that margin is
+           the padding a second time. -->
+      <div class="px-4 py-6 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
+        <slot />
+      </div>
+    </TabsContent>
+
+    <!-- The fence brought its own card into a card, so its frame, its rounding
+         and its own header come off — the tab above already names the language,
+         and the copy button moved up there with it. Its surface stays, and it is
+         the card's own — so the panel does not change colour between tabs. -->
+    <TabsContent
+      value="code"
+      class="outline-none [&_.duxt-code]:my-0 [&_.duxt-code]:rounded-none [&_.duxt-code]:border-0 [&_.duxt-code-header]:hidden [&_.duxt-code-copy]:hidden"
+    >
+      <slot name="code" />
+    </TabsContent>
+  </TabsRoot>
+</template>

package/app/components/content/ProseA.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+/**
+ * A link inside a page, resolved against the source it was written in.
+ *
+ * Markdown has no idea it is being served under a prefix. `/getting-started`
+ * written in this repository's `docs/` is correct on a site with one source and
+ * a 404 on a site with two, where the same page lives at
+ * `/duxt/getting-started` — and the author of the Markdown, who may be another
+ * repository entirely, cannot know which. Worse across versions: a link written
+ * in v0.7.0 must stay inside v0.7.0, or the reader silently changes version
+ * mid-sentence.
+ *
+ * So an absolute internal path is read as relative TO ITS OWN SOURCE, and the
+ * prefix is put back here. A path that already carries the prefix is left
+ * alone, so a link written the long way round still works.
+ */
+const props = defineProps<{
+  href?: string;
+  target?: string;
+}>();
+
+const { source } = useDuxtCollection();
+const localeLink = useDuxtLink();
+
+const external = computed(() =>
+  Boolean(props.href && /^(?:[a-z]+:|\/\/)/i.test(props.href))
+);
+
+const to = computed(() => {
+  const href = props.href ?? '';
+  if (external.value || !href.startsWith('/')) return href;
+
+  const prefix = source.value?.prefix ?? '';
+  const [path, hash] = href.split('#');
+  const resolved =
+    prefix && !isInside(path!, prefix) ? `${prefix}${path}` : path!;
+
+  return `${localeLink(resolved)}${hash ? `#${hash}` : ''}`;
+});
+</script>
+
+<template>
+  <a
+    v-if="external || !href?.startsWith('/')"
+    :href="href"
+    :target="target ?? (external ? '_blank' : undefined)"
+    :rel="external ? 'noopener' : undefined"
+  >
+    <slot />
+  </a>
+
+  <NuxtLink v-else :to="to" :target="target">
+    <slot />
+  </NuxtLink>
+</template>

package/app/components/content/ProseH2.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+/**
+ * THE WHOLE HEADING IS THE LINK, not just the marker beside it.
+ *
+ * A '#' that appears at -left-5 on hover is a target most readers never find,
+ * and no touch device can hover onto it at all. The words are what someone aims
+ * at when they want to link to a section.
+ *
+ * The marker stays, now decorative: it says the heading is anchored. It is
+ * aria-hidden so the link is announced by the heading text itself, which also
+ * drops the generic "anchor" label a screen reader used to read in its place.
+ *
+ * `scroll-mt-28` clears the whole sticky stack — the 57px header AND the
+ * section row under it — because 20 (80px) only cleared the header and left an
+ * anchored heading hiding behind the sections.
+ *
+ * The explanation sits here rather than in the template because a Prose heading
+ * is instantiated once per heading: Vue keeps template comments in the rendered
+ * HTML, so a comment there ships to the browser as many times as the page has
+ * headings.
+ */
+defineProps<{ id?: string }>();
+
+const slots = useSlots();
+
+/**
+ * A heading that IS a link cannot be wrapped in one — see `headingHasLink`.
+ * The marker beside it becomes the anchor instead, and stops being decorative:
+ * it is the only thing left to announce, so it takes a name.
+ */
+const nested = computed(() => headingHasLink(slots.default?.()));
+</script>
+
+<template>
+  <h2 :id="id" class="group scroll-mt-28">
+    <a v-if="id && !nested" :href="`#${id}`" class="duxt-heading-link">
+      <span class="duxt-anchor" aria-hidden="true">#</span>
+      <slot />
+    </a>
+
+    <template v-else-if="id">
+      <a
+        :href="`#${id}`"
+        class="duxt-anchor duxt-anchor-only"
+        :aria-label="$t('duxt.page.anchor')"
+        >#</a
+      >
+      <slot />
+    </template>
+
+    <slot v-else />
+  </h2>
+</template>

package/app/components/content/ProseH3.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+/**
+ * THE WHOLE HEADING IS THE LINK, not just the marker beside it.
+ *
+ * A '#' that appears at -left-5 on hover is a target most readers never find,
+ * and no touch device can hover onto it at all. The words are what someone aims
+ * at when they want to link to a section.
+ *
+ * The marker stays, now decorative: it says the heading is anchored. It is
+ * aria-hidden so the link is announced by the heading text itself, which also
+ * drops the generic "anchor" label a screen reader used to read in its place.
+ *
+ * `scroll-mt-28` clears the whole sticky stack — the 57px header AND the
+ * section row under it — because 20 (80px) only cleared the header and left an
+ * anchored heading hiding behind the sections.
+ *
+ * The explanation sits here rather than in the template because a Prose heading
+ * is instantiated once per heading: Vue keeps template comments in the rendered
+ * HTML, so a comment there ships to the browser as many times as the page has
+ * headings.
+ */
+defineProps<{ id?: string }>();
+
+const slots = useSlots();
+
+/**
+ * A heading that IS a link cannot be wrapped in one — see `headingHasLink`.
+ * The marker beside it becomes the anchor instead, and stops being decorative:
+ * it is the only thing left to announce, so it takes a name.
+ */
+const nested = computed(() => headingHasLink(slots.default?.()));
+</script>
+
+<template>
+  <h3 :id="id" class="group scroll-mt-28">
+    <a v-if="id && !nested" :href="`#${id}`" class="duxt-heading-link">
+      <span class="duxt-anchor" aria-hidden="true">#</span>
+      <slot />
+    </a>
+
+    <template v-else-if="id">
+      <a
+        :href="`#${id}`"
+        class="duxt-anchor duxt-anchor-only"
+        :aria-label="$t('duxt.page.anchor')"
+        >#</a
+      >
+      <slot />
+    </template>
+
+    <slot v-else />
+  </h3>
+</template>

package/app/components/content/ProseH4.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+/**
+ * THE WHOLE HEADING IS THE LINK, not just the marker beside it.
+ *
+ * A '#' that appears at -left-5 on hover is a target most readers never find,
+ * and no touch device can hover onto it at all. The words are what someone aims
+ * at when they want to link to a section.
+ *
+ * The marker stays, now decorative: it says the heading is anchored. It is
+ * aria-hidden so the link is announced by the heading text itself, which also
+ * drops the generic "anchor" label a screen reader used to read in its place.
+ *
+ * `scroll-mt-28` clears the whole sticky stack — the 57px header AND the
+ * section row under it — because 20 (80px) only cleared the header and left an
+ * anchored heading hiding behind the sections.
+ *
+ * The explanation sits here rather than in the template because a Prose heading
+ * is instantiated once per heading: Vue keeps template comments in the rendered
+ * HTML, so a comment there ships to the browser as many times as the page has
+ * headings.
+ */
+defineProps<{ id?: string }>();
+
+const slots = useSlots();
+
+/**
+ * A heading that IS a link cannot be wrapped in one — see `headingHasLink`.
+ * The marker beside it becomes the anchor instead, and stops being decorative:
+ * it is the only thing left to announce, so it takes a name.
+ */
+const nested = computed(() => headingHasLink(slots.default?.()));
+</script>
+
+<template>
+  <h4 :id="id" class="group scroll-mt-28">
+    <a v-if="id && !nested" :href="`#${id}`" class="duxt-heading-link">
+      <span class="duxt-anchor" aria-hidden="true">#</span>
+      <slot />
+    </a>
+
+    <template v-else-if="id">
+      <a
+        :href="`#${id}`"
+        class="duxt-anchor duxt-anchor-only"
+        :aria-label="$t('duxt.page.anchor')"
+        >#</a
+      >
+      <slot />
+    </template>
+
+    <slot v-else />
+  </h4>
+</template>