@kirchdev/duxt 0.1.0

package/app/components/content/CodeGroup.vue

@@ -0,0 +1,183 @@
+<script setup lang="ts">
+import { TabsContent, TabsList, TabsRoot, TabsTrigger } from 'reka-ui';
+
+/**
+ * Several fences, one block, one tab each.
+ *
+ * `::code-group` around a run of fenced blocks. The label of each tab is the
+ * fence's own filename — ```ts [nuxt.config.ts] — because that is what a reader
+ * is choosing between, and it is already written.
+ *
+ * The children are read from the default slot's VNodes rather than registered
+ * by a child component: a fence is a `ProsePre`, not something this block can
+ * ask to announce itself, and its filename is a prop on that VNode.
+ *
+ * NOT ONLY FOR FENCES. Anything rendering a `DuxtCodeBlock` and carrying a
+ * `filename` or `language` prop works here — the landing page's code demos hand
+ * it blocks built from config rather than from Markdown. That is why this is a
+ * component and the landing page does not grow a second tab bar of its own.
+ *
+ * THE BAR IS `PackageManagers`' BAR: pills with the file's own icon, and the
+ * copy button at the end of the same row. Those two components are the same
+ * control — pick one of several spellings of one thing, copy the one you
+ * picked — and they read as one only if they look alike.
+ */
+const slots = useSlots();
+
+interface Entry {
+  value: string;
+  label: string;
+  icon: string;
+  code: string;
+  node: VNode;
+}
+
+const entries = computed<Entry[]>(() => {
+  const nodes = (slots.default?.() ?? []).flatMap((node) =>
+    Array.isArray(node.children) && typeof node.type === 'symbol'
+      ? (node.children as VNode[])
+      : [node]
+  );
+
+  return nodes
+    .filter((node) => typeof node.type === 'object')
+    .map((node, index) => {
+      const props = (node.props ?? {}) as {
+        filename?: string;
+        language?: string;
+        code?: string;
+      };
+
+      return {
+        value: `code-${index}`,
+        label: props.filename ?? props.language ?? `${index + 1}`,
+        icon: fileIcon(
+          props.filename ?? props.language,
+          props.language ? 'lucide:terminal' : 'lucide:file'
+        ),
+        code: props.code ?? '',
+        node
+      };
+    });
+});
+
+const active = ref('code-0');
+
+watchEffect(() => {
+  if (!entries.value.some((entry) => entry.value === active.value)) {
+    active.value = entries.value[0]?.value ?? 'code-0';
+  }
+});
+
+const current = computed(() =>
+  entries.value.find((entry) => entry.value === active.value)
+);
+
+/**
+ * The copy button, on the group rather than on each fence.
+ *
+ * `code` is the fence's raw source and is the honest thing to copy; a group
+ * whose children were built without it falls back to the rendered text of the
+ * panel that is showing, which is what `DuxtCodeBlock` does for itself.
+ */
+const root = useTemplateRef<HTMLElement>('root');
+
+/** The height follows the file that is showing — see the composable. */
+const shell = useTemplateRef<HTMLElement>('shell');
+const body = useTemplateRef<HTMLElement>('body');
+
+useDuxtAnimatedHeight(shell, body);
+const copied = ref(false);
+const notify = useDuxtToast();
+const { t } = useI18n();
+
+async function copy() {
+  const text =
+    current.value?.code ||
+    root.value?.querySelector('[data-state="active"] code')?.textContent ||
+    '';
+
+  try {
+    await navigator.clipboard.writeText(text);
+    copied.value = true;
+    notify.success(t('duxt.code.copiedToast'));
+    setTimeout(() => (copied.value = false), 2000);
+  } catch {
+    notify.error(t('duxt.page.copyFailed'));
+  }
+}
+</script>
+
+<template>
+  <TabsRoot
+    ref="root"
+    v-model="active"
+    class="duxt-code my-6 overflow-hidden rounded-lg border bg-card"
+  >
+    <!-- THE BUTTON IS NOT IN THE TABLIST. It looks like one row and has to be
+         one row, but `role="tablist"` may only contain tabs — a copy button
+         inside it is a control a screen reader is told to treat as a tab and
+         cannot. So the row is a plain box and the tablist is the part of it
+         that actually holds tabs. -->
+    <div
+      class="flex min-h-11 items-center gap-1 border-b bg-muted/40 px-2 py-1.5"
+    >
+      <TabsList
+        class="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto"
+        :aria-label="$t('duxt.page.tabs') as string"
+      >
+        <TabsTrigger
+          v-for="entry in entries"
+          :key="entry.value"
+          :value="entry.value"
+          class="flex shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1 font-mono text-xs transition-colors data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm data-[state=inactive]:text-muted-foreground hover:bg-accent hover:text-foreground"
+        >
+          <Icon :name="entry.icon" class="size-3.5" />
+          {{ entry.label }}
+        </TabsTrigger>
+      </TabsList>
+
+      <UiButton
+        variant="ghost"
+        size="icon"
+        class="size-7 shrink-0"
+        :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>
+
+    <!-- THE BLOCK FOLLOWS THE FILE THAT IS SHOWING, over 300ms.
+
+         The first version mounted every panel stacked in one grid cell, so the
+         block was always as tall as the LONGEST file. It never moved, which was
+         the point — and it left a three-line config sitting in the space a
+         twelve-line one needs, which is a lot of empty box on a landing page.
+
+         So one panel at a time, and the height is animated instead of switched:
+         the same treatment the request-sample card gets, out of the same
+         composable. Nothing below the block jumps, and nothing above it sits in
+         a hole. -->
+    <div
+      ref="shell"
+      class="overflow-hidden motion-safe:transition-[height] motion-safe:duration-300 motion-safe:ease-out"
+    >
+      <div ref="body">
+        <TabsContent
+          v-for="entry in entries"
+          :key="entry.value"
+          :value="entry.value"
+          class="focus-visible:outline-none [&_.duxt-code]:my-0 [&_.duxt-code]:rounded-none [&_.duxt-code]:border-0"
+        >
+          <!-- `:header="false"`: the tab above already says what the bar inside
+               would, and the copy button now sits beside the tabs. -->
+          <component :is="entry.node" :header="false" />
+        </TabsContent>
+      </div>
+    </div>
+  </TabsRoot>
+</template>

package/app/components/content/DevtoolsPanel.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+/**
+ * `::devtools-panel{tab="pages"}` — one panel of the devtools tab, embedded.
+ *
+ * The alternative was a screenshot, and a screenshot of a table is out of date
+ * the day a column is added; the panel's real route is no alternative at all,
+ * because `modules/devtools.ts` registers nothing outside a dev server, so a
+ * published page would frame a 404. What is embedded here is the panel's OWN
+ * renderer, run over a fixture site at build time and written to
+ * `public/devtools/<tab>.html` by `pnpm previews` — the LAYER's public
+ * directory, so the documents ship in the package beside the pages that ask
+ * for them. Nuxt serves every layer's `public/`, which is what lets a consumer
+ * rendering this reference get the frames rather than ten empty boxes.
+ *
+ * An iframe rather than inline markup, and deliberately: the panel ships its
+ * own stylesheet, written against a documentation site's tokens it knows
+ * nothing about. Inlining it would mean two cascades in one document, each
+ * quietly restyling the other.
+ *
+ * Two messages cross the frame. The theme goes in, because the reader's choice
+ * is a class on this page and a media query is all the frame would otherwise
+ * see; the height comes back, because only the framed document knows how tall
+ * its table turned out. Both are best-effort — with the script blocked, the
+ * frame keeps its default height and follows the system theme.
+ *
+ * `allow-scripts` WITHOUT `allow-same-origin`, and the pair is the point: on a
+ * document served from this site's own origin the two together hand the frame
+ * back everything the attribute withheld. Nothing here needs it — `postMessage`
+ * crosses origins by design, and the two messages above are all the framed page
+ * does. What is framed is generated HTML nobody reviews per release, so the
+ * sandbox is worth keeping teeth in.
+ */
+const props = withDefaults(
+  defineProps<{
+    /** The panel's slug, as the tab row spells it. */
+    tab?: string;
+    /** Starting height in pixels, before the frame reports its own. */
+    height?: number | string;
+    /** Upper bound, so a long table scrolls inside the frame. */
+    max?: number | string;
+  }>(),
+  { tab: 'sources', height: 360, max: 620 }
+);
+
+const frame = useTemplateRef<HTMLIFrameElement>('frame');
+const colorMode = useColorMode();
+const { t } = useI18n();
+
+const number = (value: number | string, fallback: number) => {
+  const parsed = typeof value === 'number' ? value : Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+const ceiling = computed(() => number(props.max, 620));
+const height = ref(number(props.height, 360));
+
+const dark = computed(() => colorMode.value === 'dark');
+
+/**
+ * The theme is in the URL as well as in a message: the query settles the very
+ * first paint, the message every change after it. Without the query the frame
+ * renders light and flips a moment later, which is exactly the flash the
+ * theme-aware image support elsewhere in this layer exists to avoid.
+ */
+const src = computed(
+  () =>
+    `/devtools/${props.tab || 'sources'}.html?theme=${dark.value ? 'dark' : 'light'}`
+);
+
+function tell() {
+  frame.value?.contentWindow?.postMessage(
+    { duxtTheme: dark.value ? 'dark' : 'light' },
+    '*'
+  );
+}
+
+watch(dark, tell);
+
+function onMessage(event: MessageEvent) {
+  // Only this frame's own message, and only a number: the listener is on the
+  // window, which every other frame and script on the page can post to.
+  if (event.source !== frame.value?.contentWindow) return;
+
+  const reported = (event.data as { duxtHeight?: unknown } | null)?.duxtHeight;
+  if (typeof reported !== 'number') return;
+
+  height.value = Math.min(Math.max(Math.round(reported), 200), ceiling.value);
+}
+
+onMounted(() => window.addEventListener('message', onMessage));
+onBeforeUnmount(() => window.removeEventListener('message', onMessage));
+</script>
+
+<template>
+  <div class="border-border my-6 overflow-hidden rounded-lg border">
+    <iframe
+      ref="frame"
+      :src="src"
+      :title="t('duxt.devtools.preview', { tab })"
+      :style="{ height: `${height}px` }"
+      class="block w-full"
+      loading="lazy"
+      sandbox="allow-scripts"
+      @load="tell"
+    />
+  </div>
+</template>

package/app/components/content/Field.vue

@@ -0,0 +1,50 @@
+<script setup lang="ts">
+/**
+ * One parameter, property or option — the most-used component a docs theme is
+ * missing.
+ *
+ *     ::field{name="showRepo" type="boolean" default="false"}
+ *     Force a repository segment even with a single repository.
+ *     ::
+ *
+ * A definition list would be the semantic choice and is the wrong one here: the
+ * name, the type, the default and whether it is required are four different
+ * things, and `<dt>` gives them one slot between them. So each is drawn as
+ * itself, and the description is the only prose.
+ */
+defineProps<{
+  name?: string;
+  type?: string;
+  default?: string;
+  required?: boolean;
+}>();
+</script>
+
+<template>
+  <div class="border-b py-3 last:border-b-0">
+    <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+      <code class="font-mono text-sm font-medium text-foreground">{{
+        name
+      }}</code>
+
+      <code v-if="type" class="font-mono text-xs text-muted-foreground">{{
+        type
+      }}</code>
+
+      <UiBadge v-if="required" variant="secondary" class="text-[10px]">
+        required
+      </UiBadge>
+
+      <code
+        v-if="$props.default !== undefined"
+        class="ml-auto font-mono text-xs text-muted-foreground"
+      >
+        = {{ $props.default }}
+      </code>
+    </div>
+
+    <div class="mt-1.5 text-sm text-muted-foreground [&>*:last-child]:mb-0">
+      <slot />
+    </div>
+  </div>
+</template>

package/app/components/content/FieldGroup.vue

@@ -0,0 +1,8 @@
+<template>
+  <!-- `::field-group` around several `::field` blocks. One border round the
+       set, so a list of options reads as a table without being one — a table
+       cell cannot hold the paragraph a field's description usually is. -->
+  <div class="my-6 rounded-lg border px-4">
+    <slot />
+  </div>
+</template>

package/app/components/content/FileTree.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { TreeItem, TreeRoot } from 'reka-ui';
+
+interface Entry {
+  name: string;
+  children?: Entry[];
+}
+
+// `::file-tree` with a `tree` prop. Built on Reka UI's Tree rather than
+// hand-rolled `<ul>` recursion, so it comes with roving focus, arrow-key
+// navigation, expand and collapse, and the ARIA roles a tree needs — all of
+// which the hand-rolled version had none of.
+const props = defineProps<{ tree?: Entry[]; title?: string }>();
+
+const items = computed(() => props.tree ?? []);
+
+const isDirectory = (entry: Entry) =>
+  Boolean(entry.children?.length) || entry.name.endsWith('/');
+
+const label = (entry: Entry) => entry.name.replace(/\/$/, '');
+
+/** Unique per node: names repeat across branches, paths do not. */
+function key(entry: Entry) {
+  return entry.name;
+}
+
+/** Everything open on first render — a docs tree is there to be read, not explored. */
+const expanded = computed(() => {
+  const keys: string[] = [];
+
+  const walk = (entries: Entry[]) => {
+    for (const entry of entries) {
+      if (entry.children?.length) {
+        keys.push(key(entry));
+        walk(entry.children);
+      }
+    }
+  };
+
+  walk(items.value);
+  return keys;
+});
+</script>
+
+<template>
+  <div class="not-typeset my-6 overflow-hidden rounded-lg border bg-card">
+    <div
+      v-if="title"
+      class="flex min-h-11 items-center gap-2 border-b bg-muted/40 px-3 py-2 text-xs text-muted-foreground"
+    >
+      <Icon name="lucide:folder-tree" class="size-4" />
+      <span class="font-mono">{{ title }}</span>
+    </div>
+
+    <TreeRoot
+      v-slot="{ flattenItems }"
+      :items="items"
+      :get-key="key"
+      :get-children="(entry: Entry) => entry.children"
+      :default-expanded="expanded"
+      class="overflow-x-auto p-3 font-mono text-[13px] leading-6 select-none"
+    >
+      <TreeItem
+        v-for="item in flattenItems"
+        v-slot="{ isExpanded }"
+        :key="item._id"
+        v-bind="item.bind"
+        :style="{ paddingLeft: `${item.level - 1}rem` }"
+        class="flex items-center gap-1.5 rounded px-1 py-[3px] outline-none focus:bg-accent data-[selected]:bg-accent/60"
+      >
+        <template v-if="isDirectory(item.value)">
+          <Icon
+            name="lucide:chevron-right"
+            class="size-3 shrink-0 text-muted-foreground transition-transform"
+            :class="{ 'rotate-90': isExpanded }"
+          />
+          <Icon
+            :name="isExpanded ? 'lucide:folder-open' : 'lucide:folder'"
+            class="size-4 shrink-0 text-muted-foreground/70"
+          />
+          <span class="text-foreground">{{ label(item.value) }}</span>
+        </template>
+
+        <template v-else>
+          <span class="w-3 shrink-0" />
+          <Icon :name="fileIcon(item.value.name)" class="size-4 shrink-0" />
+          <span class="text-muted-foreground">{{ label(item.value) }}</span>
+        </template>
+      </TreeItem>
+    </TreeRoot>
+  </div>
+</template>

package/app/components/content/Mermaid.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+/**
+ * A mermaid diagram, from ```mermaid or from `::mermaid`.
+ *
+ * Loaded on demand and only in the browser: mermaid is roughly half a megabyte
+ * and pulls in its own parser, and a documentation site where three pages in
+ * sixty carry a diagram must not make the other fifty-seven pay for it. That
+ * also means the diagram is client-rendered — the SSR output is the source
+ * text, which is the honest fallback for a reader with no JavaScript.
+ *
+ * The theme follows the site's own: mermaid takes a base theme at init, so the
+ * colour mode is read and the diagram is re-rendered when it changes.
+ */
+const props = defineProps<{ code?: string }>();
+
+const container = useTemplateRef<HTMLElement>('container');
+const colorMode = useColorMode();
+const slots = useSlots();
+const source = ref('');
+const failed = ref(false);
+
+let mermaid: typeof import('mermaid').default | undefined;
+let counter = 0;
+
+async function render() {
+  if (!import.meta.client || !container.value) return;
+
+  const text = source.value.trim();
+  if (!text) return;
+
+  try {
+    mermaid ??= (await import('mermaid')).default;
+
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'strict',
+      theme: colorMode.value === 'dark' ? 'dark' : 'default'
+    });
+
+    const { svg } = await mermaid.render(`duxt-mermaid-${counter++}`, text);
+    container.value.innerHTML = svg;
+    failed.value = false;
+  } catch {
+    // A diagram that does not parse must not take the page with it. The source
+    // stays on screen, which is more useful than an empty box.
+    failed.value = true;
+  }
+}
+
+onMounted(() => {
+  source.value =
+    props.code ??
+    container.value?.textContent?.trim() ??
+    (typeof slots.default?.()[0]?.children === 'string'
+      ? (slots.default()[0]!.children as string)
+      : '');
+
+  void render();
+});
+
+watch(() => colorMode.value, render);
+</script>
+
+<template>
+  <div class="my-6 flex justify-center overflow-x-auto rounded-lg border p-4">
+    <div ref="container" :class="{ 'text-sm whitespace-pre': failed }">
+      <slot>{{ code }}</slot>
+    </div>
+  </div>
+</template>