@kirchdev/duxt 0.1.0

package/app/components/DuxtLocale.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+/**
+ * The language switcher, built like DuxtVersion beside it: nothing at all when
+ * there is only one choice, a dropdown when there are several. A single-locale
+ * consumer therefore never sees that duxt speaks seven languages.
+ *
+ * `switchLocalePath` rather than a link to the locale's root — switching
+ * language on a page about deploying should land on that same page in the new
+ * language, not throw the reader back to the front door.
+ */
+const { locale, locales } = useI18n();
+const switchLocalePath = useSwitchLocalePath();
+
+const available = computed(() =>
+  locales.value.map((entry) => ({
+    code: entry.code,
+    // Falls back to the code so a consumer's own locale still reads as
+    // something rather than rendering blank when it declares no `name`.
+    label: entry.name ?? entry.code,
+    flag: flagFor(entry.code)
+  }))
+);
+
+const current = computed(() =>
+  available.value.find((entry) => entry.code === locale.value)
+);
+
+/**
+ * `flag:xx-4x3`, from the region half of the code — the same derivation the
+ * icon client bundle in nuxt.config.ts uses, so every flag this renders is one
+ * that was inlined at build time.
+ *
+ * Null for a locale that names no region (`ja`, `he`): there is no country to
+ * show, and a flag guessed from a language is wrong more often than it is
+ * right. The dropdown then simply shows the name.
+ */
+function flagFor(code: string): string | null {
+  const region = code.split('-')[1];
+  return region && /^[a-z]{2}$/i.test(region)
+    ? `flag:${region.toLowerCase()}-4x3`
+    : null;
+}
+</script>
+
+<template>
+  <UiDropdownMenu v-if="available.length > 1">
+    <UiDropdownMenuTrigger as-child>
+      <UiButton
+        variant="ghost"
+        size="icon"
+        :aria-label="$t('duxt.locale.switch')"
+      >
+        <Icon
+          v-if="current?.flag"
+          :name="current.flag"
+          class="size-4 rounded-[2px]"
+        />
+        <Icon v-else name="lucide:languages" class="size-4" />
+      </UiButton>
+    </UiDropdownMenuTrigger>
+
+    <UiDropdownMenuContent
+      align="end"
+      class="max-h-[min(20rem,var(--reka-dropdown-menu-content-available-height))] w-48"
+    >
+      <UiDropdownMenuItem v-for="entry in available" :key="entry.code" as-child>
+        <NuxtLink
+          :to="switchLocalePath(entry.code)"
+          class="flex items-center gap-2"
+        >
+          <Icon
+            v-if="entry.flag"
+            :name="entry.flag"
+            class="size-4 shrink-0 rounded-[2px]"
+          />
+          <span class="truncate text-sm">{{ entry.label }}</span>
+          <Icon
+            name="lucide:check"
+            class="ml-auto size-3.5 shrink-0"
+            :class="entry.code === locale ? '' : 'opacity-0'"
+          />
+        </NuxtLink>
+      </UiDropdownMenuItem>
+    </UiDropdownMenuContent>
+  </UiDropdownMenu>
+</template>

package/app/components/DuxtMetaList.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+/**
+ * The small block under a page: a few actions, a few facts, one spacing rule.
+ *
+ * It exists because the rule kept being written by hand and kept coming out
+ * differently — two links sat line on line with no gap at all while the note
+ * under them was pushed away by a margin of its own, so the same block read as
+ * cramped and loose at once. One container owns the gap here, and every item in
+ * it is spaced the same whatever it is.
+ *
+ * ACTIONS are links with an icon; NOTES are lines of text. Anything that is
+ * neither — a list of contributors, say — goes in the slot and is spaced as one
+ * more item, because the container spaces its children rather than its content.
+ *
+ * TWO LAYOUTS, one gap. The column is what the aside gets; `row` is what a page
+ * with no aside gets, where a stack hanging off the left edge under a
+ * full-width rule reads as leftovers.
+ *
+ * It draws NOTHING when it is handed nothing — no rule across a page whose
+ * source cannot be linked and whose history git could not be asked for.
+ */
+const props = withDefaults(
+  defineProps<{
+    /** Laid out as a row rather than a stack — see above. */
+    row?: boolean;
+    /**
+     * A link with an icon beside it. `external` opens a new tab and is the only
+     * reason this component knows what a target is: the caller decides whether
+     * the link leaves the site.
+     */
+    actions?: {
+      icon?: string;
+      label: string;
+      to: string;
+      external?: boolean;
+    }[];
+    /** A line of text — already formatted, already translated. */
+    notes?: string[];
+  }>(),
+  { actions: () => [], notes: () => [] }
+);
+
+const slots = useSlots();
+
+const empty = computed(
+  () => !props.actions.length && !props.notes.length && !slots.default
+);
+</script>
+
+<template>
+  <div
+    v-if="!empty"
+    class="mt-6 border-t pt-4 text-xs text-muted-foreground"
+    :class="
+      row
+        ? 'flex flex-wrap items-center justify-end gap-x-6 gap-y-2'
+        : 'space-y-2.5'
+    "
+  >
+    <a
+      v-for="action in actions"
+      :key="action.to"
+      :href="action.to"
+      :target="action.external ? '_blank' : undefined"
+      :rel="action.external ? 'noopener' : undefined"
+      class="flex items-center gap-1.5 transition-colors hover:text-foreground"
+    >
+      <Icon v-if="action.icon" :name="action.icon" class="size-3.5 shrink-0" />
+      {{ action.label }}
+    </a>
+
+    <p v-for="note in notes" :key="note">{{ note }}</p>
+
+    <slot />
+  </div>
+</template>

package/app/components/DuxtNavigation.vue

@@ -0,0 +1,94 @@
+<script setup lang="ts">
+import type { ContentNavigationItem } from '@nuxt/content';
+
+// The docs tree. Groups collapse, and the group holding the current page opens
+// on every navigation — not only on first render.
+//
+// `label` decides whether this instance is a LANDMARK. Only the outermost one
+// is: the component recurses into itself for nested folders, and the mobile
+// sheet renders a second copy of the whole tree, so a `<nav>` on every instance
+// put several landmarks with one name on the page — an axe `landmark-unique`
+// failure, and a screen-reader landmark list with the same entry three times.
+// Without a label it renders the list alone, which is what a nested group and a
+// sheet that already names itself both want.
+const props = defineProps<{
+  items: ContentNavigationItem[];
+  label?: string;
+}>();
+
+const path = useDuxtPath();
+
+// A page's own icon, else the section's `pageIcon`, else the site's — see
+// `resolvePageIcon`.
+const duxt = useDuxtConfig();
+const iconOf = (item: ContentNavigationItem) =>
+  resolvePageIcon(item, duxt.sections, duxt.pageIcon);
+
+const contains = (item: ContentNavigationItem): boolean =>
+  path.value === item.path ||
+  Boolean(item.children?.some((child) => contains(child)));
+
+// `default-open` is the INITIAL state of an uncontrolled collapsible: read once
+// and never again, so arriving in a collapsed group by search, a deep link or
+// the back button left it shut. The open state therefore belongs to the route —
+// but a group the reader closes by hand must stay closed, so the route only
+// forces it open when it moves into that group.
+const open = ref<Record<string, boolean>>({});
+
+watchEffect(() => {
+  for (const item of props.items) {
+    if (item.path && contains(item)) open.value[item.path] = true;
+  }
+});
+
+function isOpen(item: ContentNavigationItem) {
+  return open.value[item.path ?? ''] ?? false;
+}
+
+function setOpen(item: ContentNavigationItem, value: boolean) {
+  open.value[item.path ?? ''] = value;
+}
+</script>
+
+<template>
+  <component
+    :is="label ? 'nav' : 'div'"
+    class="text-[13px]"
+    :aria-label="label || undefined"
+  >
+    <ul class="space-y-0.5">
+      <li v-for="item in items" :key="item.path">
+        <UiCollapsible
+          v-if="item.children?.length"
+          :open="isOpen(item)"
+          @update:open="(value) => setOpen(item, value)"
+        >
+          <UiCollapsibleTrigger
+            class="group flex w-full cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 font-medium text-foreground transition-colors hover:bg-accent"
+          >
+            <Icon
+              v-if="iconOf(item)"
+              :name="iconOf(item)!"
+              class="size-4 text-muted-foreground"
+            />
+            <span class="truncate">{{ item.title }}</span>
+            <Icon
+              name="lucide:chevron-right"
+              class="ml-auto size-3.5 text-muted-foreground transition-transform group-data-[state=open]:rotate-90"
+            />
+          </UiCollapsibleTrigger>
+
+          <UiCollapsibleContent>
+            <ul class="mt-0.5 ml-3.5 space-y-0.5 border-l pl-2.5">
+              <li v-for="child in item.children" :key="child.path">
+                <DuxtNavigationLink :item="child" />
+              </li>
+            </ul>
+          </UiCollapsibleContent>
+        </UiCollapsible>
+
+        <DuxtNavigationLink v-else :item="item" />
+      </li>
+    </ul>
+  </component>
+</template>

package/app/components/DuxtNavigationLink.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import type { ContentNavigationItem } from '@nuxt/content';
+
+// A leaf in the docs tree. Nested groups recurse back into DuxtNavigation, so
+// a folder inside a folder keeps working without a second component.
+defineProps<{ item: ContentNavigationItem }>();
+
+const path = useDuxtPath();
+const localeLink = useDuxtLink();
+
+// A page's own icon, else the section's `pageIcon`, else the site's — see
+// `resolvePageIcon`.
+const duxt = useDuxtConfig();
+const iconOf = (item: ContentNavigationItem) =>
+  resolvePageIcon(item, duxt.sections, duxt.pageIcon);
+</script>
+
+<template>
+  <DuxtNavigation v-if="item.children?.length" :items="[item]" />
+
+  <NuxtLink
+    v-else
+    :to="localeLink(item.path)"
+    :aria-current="path === item.path ? 'page' : undefined"
+    class="flex items-center gap-2 rounded-md px-2 py-1.5 leading-5 transition-colors"
+    :class="
+      path === item.path
+        ? 'bg-primary/10 font-medium text-primary'
+        : 'text-muted-foreground hover:bg-accent hover:text-foreground'
+    "
+  >
+    <Icon v-if="iconOf(item)" :name="iconOf(item)!" class="size-4 shrink-0" />
+    <!-- Truncated, not wrapped, and the reason is the active state: `font-medium`
+         is wider than the same string at normal weight, so an entry that fitted
+         on one line reflowed onto two the moment it became the current page and
+         the whole sidebar shifted under the pointer. One line per entry makes the
+         weight change invisible to the layout. The `title` keeps the full text
+         reachable for the handful of entries long enough to be cut. -->
+    <span class="truncate" :title="item.title">{{ item.title }}</span>
+  </NuxtLink>
+</template>

package/app/components/DuxtOpenApiCallbacks.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import type { DuxtOpenApiCallback } from '../../openapi-model';
+
+/**
+ * The requests the API sends BACK, and where it sends them.
+ *
+ * A callback inverts the direction: the reader becomes the server. So it gets a
+ * section of its own rather than being folded in beside the responses, and the
+ * runtime expression — `{$request.body#/callbackUrl}` — is shown verbatim,
+ * because it is the literal string the document uses to say which field of the
+ * original request holds the URL.
+ *
+ * No try-it client here, and that is not an omission: nothing in a browser can
+ * receive one.
+ */
+defineProps<{ callbacks?: DuxtOpenApiCallback[] }>();
+</script>
+
+<template>
+  <section v-if="callbacks?.length" class="mt-8">
+    <h2 class="duxt-label">
+      {{ $t('duxt.openapi.callbacks') }}
+    </h2>
+
+    <div v-for="callback in callbacks" :key="callback.name" class="mt-4">
+      <h3 class="font-mono text-sm font-medium">{{ callback.name }}</h3>
+
+      <div
+        v-for="(operation, index) in callback.operations ?? []"
+        :key="index"
+        class="mt-3 border-t border-border/60"
+      >
+        <div class="flex flex-wrap items-center gap-2 pt-3">
+          <DuxtOpenApiMethod :method="operation.method" />
+          <code class="font-mono text-sm break-all">
+            {{ operation.expression }}
+          </code>
+        </div>
+
+        <div class="mt-3 space-y-4">
+          <p v-if="operation.summary" class="text-sm">
+            {{ operation.summary }}
+          </p>
+          <p v-if="operation.description" class="text-sm text-muted-foreground">
+            {{ operation.description }}
+          </p>
+
+          <!-- A callback is a request the SERVER sends, so its body travels
+               the same way any request body does. Its responses are drawn as
+               status chips here, with no schema to give a direction to. -->
+          <DuxtOpenApiMedia
+            v-if="operation.requestBody?.content?.length"
+            :content="operation.requestBody.content"
+            direction="request"
+          />
+
+          <!-- NAMED, because the direction is inverted and a bare status chip
+               under a request body reads as one of the operation's own answers.
+               It is the opposite: what the API expects the READER's endpoint to
+               reply with. The document's own description of it is drawn beside
+               the status, which is the whole of what it says. -->
+          <div v-if="operation.responses?.length">
+            <p class="text-xs font-medium text-foreground/80">
+              {{ $t('duxt.openapi.expects') }}
+            </p>
+
+            <ul class="mt-2 space-y-1.5">
+              <li
+                v-for="response in operation.responses"
+                :key="response.status"
+                class="flex flex-wrap items-center gap-3"
+              >
+                <UiBadge
+                  :class="[
+                    'h-5 px-1.5 font-mono text-[0.6875rem] leading-none font-semibold tabular-nums',
+                    openApiStatusTone(response.status)
+                  ]"
+                >
+                  {{ response.status }}
+                </UiBadge>
+
+                <span v-if="response.description" class="text-sm">
+                  {{ response.description }}
+                </span>
+              </li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>