@kirchdev/duxt 0.1.0

package/app/components/content/OpenApiOperation.vue

@@ -0,0 +1,185 @@
+<script setup lang="ts">
+import type {
+  DuxtOpenApiOperation,
+  DuxtOpenApiSecurity,
+  DuxtOpenApiSecurityScheme,
+  DuxtOpenApiServer
+} from '../../../openapi-model';
+
+/**
+ * One operation, as the two right-hand columns of the reference.
+ *
+ * MDC: the `openapi` section type writes `::open-api-operation` into every
+ * operation page, with the structure as props and the operation's own
+ * description in the slot. The description is Markdown because the
+ * specification says it is CommonMark — rendering it as plain text is the
+ * commonest thing a reference gets wrong, and it costs the author every link
+ * and every code span they wrote.
+ *
+ * THE COLUMNS. The `reference` layout gives the operation list on the left and
+ * the full width; this splits what is left into the description in the middle
+ * and the client on the right, which is the arrangement the issue settled on.
+ * It is one grid rather than two page regions on purpose: the right column is a
+ * property of the OPERATION — its servers, its parameters, its security — so it
+ * has to be rendered by whatever renders the operation, and a layout cannot
+ * reach it.
+ *
+ * The structural blocks carry `not-typeset`; the slot does not. A page's prose
+ * wants the typeset preset and a parameter table does not, and they are
+ * siblings here so each gets what it needs.
+ */
+const props = defineProps<{
+  operation: DuxtOpenApiOperation;
+  servers?: DuxtOpenApiServer[];
+  security?: DuxtOpenApiSecurity;
+  securitySchemes?: DuxtOpenApiSecurityScheme[];
+}>();
+
+/**
+ * A fragment that lands on the client rather than at the top of the page.
+ *
+ * The panel sits beside the endpoint at `xl` and BELOW the whole description
+ * everywhere narrower — so on a phone, and in any frame narrower than 80rem, a
+ * link to the operation shows the prose and hides the one control the page is
+ * about. `#…-try-it` is how a reader, a release note or the landing page's own
+ * window points at it.
+ *
+ * Keyed by the operation rather than a bare `try-it`, because
+ * `OpenApiOperations` renders a run of these on one page and a duplicated id is
+ * an anchor that resolves to whichever came first.
+ */
+const clientAnchor = computed(() =>
+  `${props.operation.operationId ?? `${props.operation.method}-${props.operation.path}`}-try-it`
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+);
+</script>
+
+<template>
+  <!-- Wider on a wide screen: a `curl` line with a couple of headers wraps at
+       23rem however much room the window has, and the column that shows it is
+       why `reference` hands its page the whole column rather than capping it at
+       a reading measure the way `docs` and `changelog` do.
+       
+       30rem AT `2xl`, not the 34 it was. That number was chosen while the shell
+       ran to 100rem, where it left the description the larger half; inside
+       90rem the same 34 split the row down the middle, and the description —
+       which is what the page is FOR — became the narrower side of a client. -->
+  <div
+    class="grid gap-8 xl:grid-cols-[minmax(0,1fr)_23rem] 2xl:grid-cols-[minmax(0,1fr)_30rem]"
+  >
+    <div class="min-w-0">
+      <div class="not-typeset flex flex-wrap items-center gap-2">
+        <DuxtOpenApiMethod :method="operation.method" class="h-6 px-2" />
+
+        <code class="font-mono text-sm break-all">{{ operation.path }}</code>
+
+        <!-- A webhook is the same object pointing the other way, and a reader
+             who does not know that will try to call it. -->
+        <UiBadge v-if="operation.kind === 'webhook'" variant="secondary">
+          {{ $t('duxt.openapi.webhook') }}
+        </UiBadge>
+
+        <UiBadge v-if="operation.deprecated" variant="destructive">
+          {{ $t('duxt.openapi.deprecated') }}
+        </UiBadge>
+      </div>
+
+      <p
+        v-if="operation.operationId"
+        class="not-typeset mt-2 font-mono text-xs text-muted-foreground"
+      >
+        {{ operation.operationId }}
+      </p>
+
+      <div class="mt-4">
+        <slot />
+      </div>
+
+      <div class="not-typeset">
+        <DuxtOpenApiSecurity :security="security" />
+
+        <DuxtOpenApiParameters :parameters="operation.parameters" />
+
+        <section v-if="operation.requestBody?.content?.length" class="mt-8">
+          <h2 class="duxt-label">
+            {{ $t('duxt.openapi.requestBody') }}
+            <span
+              v-if="operation.requestBody.required"
+              class="ml-1 text-xs font-medium text-destructive"
+            >
+              {{ $t('duxt.openapi.required') }}
+            </span>
+          </h2>
+
+          <p
+            v-if="operation.requestBody.description"
+            class="mt-2 text-sm text-muted-foreground"
+          >
+            {{ operation.requestBody.description }}
+          </p>
+
+          <div class="mt-3 border-t border-border/60 pt-3">
+            <DuxtOpenApiMedia
+              :content="operation.requestBody.content"
+              direction="request"
+            />
+          </div>
+        </section>
+
+        <DuxtOpenApiResponses :responses="operation.responses" />
+
+        <DuxtOpenApiCallbacks :callbacks="operation.callbacks" />
+
+        <p v-if="operation.externalDocs" class="mt-8 text-sm">
+          <a
+            :href="operation.externalDocs.url"
+            rel="noopener noreferrer"
+            target="_blank"
+            class="text-primary underline underline-offset-4"
+          >
+            {{
+              operation.externalDocs.description ?? $t('duxt.openapi.moreInfo')
+            }}
+          </a>
+        </p>
+      </div>
+    </div>
+
+    <!-- Sticky only where there is a column to be sticky in: below `xl` the
+         client sits after the description, which is the order a phone reads.
+
+         AND IT SCROLLS ITSELF, the way the sidebar and the table of contents
+         already do — same expression, `100vh` less the chrome above it. Sticky
+         alone pinned a panel taller than the viewport, so the request samples
+         under the send button were cut off and only came into view once the
+         reader had scrolled the whole page to its end: the panel is beside the
+         endpoint precisely so it does not have to be chased there.
+
+         Bounded and scrollable only at `xl`, because below it the client is in
+         normal flow and a second scrollbar inside the page would be one nobody
+         asked for.
+
+         AND IT KEEPS A REM OFF THE CHROME. Pinned at exactly `--duxt-header-offset`
+         the card's top border sat against the navbar's bottom border, so the
+         two read as one thick line and the panel looked attached to the header
+         rather than floating under it. The `max-h` gives the same rem back at
+         the bottom, so the panel still ends clear of the viewport edge. -->
+    <div
+      :id="clientAnchor"
+      class="not-typeset min-w-0 scroll-mt-[var(--duxt-header-offset)]"
+    >
+      <div
+        class="xl:sticky xl:top-[calc(var(--duxt-header-offset)+1rem)] xl:max-h-[calc(100vh-var(--duxt-header-offset)-2.5rem)] xl:overflow-y-auto xl:pr-1"
+      >
+        <DuxtOpenApiClient
+          :operation="operation"
+          :servers="servers"
+          :security="security"
+          :security-schemes="securitySchemes"
+        />
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/content/OpenApiOperations.vue

@@ -0,0 +1,72 @@
+<script setup lang="ts">
+import type { DuxtOpenApiExternalDocs } from '../../../openapi-model';
+
+/**
+ * The endpoints under one tag, as the list a reader scans.
+ *
+ * MDC: `::open-api-operations` on a tag's index page. The method is a coloured
+ * chip and the path is the link text, because "find this endpoint" is the
+ * search a reader actually performs — a list of summaries alone makes them read
+ * every line to find `DELETE /pets/{id}`.
+ */
+defineProps<{
+  operations?: {
+    method: string;
+    path: string;
+    kind?: string;
+    summary?: string;
+    deprecated?: boolean;
+    to: string;
+  }[];
+  externalDocs?: DuxtOpenApiExternalDocs;
+}>();
+
+const localeLink = useDuxtLink();
+</script>
+
+<template>
+  <div>
+    <!-- Outside `not-typeset`: the tag's own description is Markdown and wants
+         the typeset preset; the list below emphatically does not. -->
+    <slot />
+
+    <ul v-if="operations?.length" class="not-typeset mt-6 -mx-3">
+      <li
+        v-for="entry in operations"
+        :key="`${entry.method}-${entry.to}`"
+        class="border-t border-border/60 first:border-t-0"
+      >
+        <NuxtLink
+          :to="localeLink(entry.to) ?? entry.to"
+          class="flex flex-wrap items-center gap-3 rounded-lg px-3 py-3 transition-colors hover:bg-muted/40"
+        >
+          <DuxtOpenApiMethod :method="entry.method" class="w-16" />
+
+          <code class="font-mono text-sm break-all">{{ entry.path }}</code>
+
+          <span
+            v-if="entry.summary"
+            class="w-full text-sm text-muted-foreground sm:ml-auto sm:w-auto sm:text-right"
+          >
+            {{ entry.summary }}
+          </span>
+
+          <UiBadge v-if="entry.deprecated" variant="destructive">
+            {{ $t('duxt.openapi.deprecated') }}
+          </UiBadge>
+        </NuxtLink>
+      </li>
+    </ul>
+
+    <p v-if="externalDocs" class="not-typeset mt-6 text-sm">
+      <a
+        :href="externalDocs.url"
+        rel="noopener noreferrer"
+        target="_blank"
+        class="text-primary underline underline-offset-4"
+      >
+        {{ externalDocs.description ?? $t('duxt.openapi.moreInfo') }}
+      </a>
+    </p>
+  </div>
+</template>

package/app/components/content/OpenApiOverview.vue

@@ -0,0 +1,302 @@
+<script setup lang="ts">
+import type {
+  DuxtOpenApiExternalDocs,
+  DuxtOpenApiSecurity,
+  DuxtOpenApiSecurityScheme,
+  DuxtOpenApiServer
+} from '../../../openapi-model';
+
+/**
+ * The reference's front page: what the API is, where it lives, how to get in.
+ *
+ * MDC: `::open-api-overview` on the section's index page, with the document's
+ * own `info.description` in the slot. It is the page a reader lands on from the
+ * navbar entry, and the three questions it answers — base URL, authentication,
+ * which groups of endpoints exist — are the three a reference is opened for
+ * before any single endpoint is.
+ */
+const props = defineProps<{
+  version?: string;
+  servers?: DuxtOpenApiServer[];
+  securitySchemes?: DuxtOpenApiSecurityScheme[];
+  security?: DuxtOpenApiSecurity;
+  contact?: { name?: string; url?: string; email?: string };
+  license?: { name?: string; identifier?: string; url?: string };
+  termsOfService?: string;
+  externalDocs?: DuxtOpenApiExternalDocs;
+  groups?: {
+    name: string;
+    description?: string;
+    webhooks?: boolean;
+    operations?: number;
+    to: string;
+  }[];
+}>();
+
+const localeLink = useDuxtLink();
+
+/** Every operation the document describes, counted over its groups. */
+const operations = computed(() =>
+  (props.groups ?? []).reduce((all, group) => all + (group.operations ?? 0), 0)
+);
+</script>
+
+<template>
+  <div>
+    <!-- NO SUMMARY LINE. `info.summary` is this page's description, and the
+         shell draws a description under the title like it does on every written
+         page — printing it here as well put the lead below the rule, where the
+         body starts, and said the same sentence twice. -->
+    <!-- The document's own description, as the Markdown it is written in. -->
+    <slot />
+
+    <!-- WHAT THE DOCUMENT IS, in figures — the same row the release history
+         opens with, and the reason the version is no longer a badge floating
+         over the page: a version is a fact about the document, and a fact
+         belongs where the other facts are. On its own above the title it read
+         as a label for the page, which it never was. -->
+    <dl
+      v-if="version || groups?.length"
+      class="not-typeset mt-8 grid grid-cols-2 gap-x-6 gap-y-7 border-b pb-5 sm:grid-cols-4"
+    >
+      <div v-if="version" class="flex flex-col gap-1">
+        <dd
+          class="font-mono text-2xl font-semibold tracking-tight tabular-nums sm:text-3xl"
+        >
+          {{ version }}
+        </dd>
+        <dt class="flex items-center gap-1.5 text-xs font-medium text-primary">
+          <Icon name="lucide:tag" class="size-3.5" />
+          {{ $t('duxt.openapi.version') }}
+        </dt>
+      </div>
+
+      <div v-if="groups?.length" class="flex flex-col gap-1">
+        <dd
+          class="text-2xl font-semibold tracking-tight tabular-nums sm:text-3xl"
+        >
+          {{ operations }}
+        </dd>
+        <dt class="flex items-center gap-1.5 text-xs font-medium text-primary">
+          <Icon name="lucide:arrow-left-right" class="size-3.5" />
+          {{ $t('duxt.openapi.operations') }}
+        </dt>
+      </div>
+
+      <div v-if="groups?.length" class="flex flex-col gap-1">
+        <dd
+          class="text-2xl font-semibold tracking-tight tabular-nums sm:text-3xl"
+        >
+          {{ groups.length }}
+        </dd>
+        <dt class="flex items-center gap-1.5 text-xs font-medium text-primary">
+          <Icon name="lucide:folder-tree" class="size-3.5" />
+          {{ $t('duxt.openapi.groups') }}
+        </dt>
+      </div>
+
+      <div v-if="servers?.length" class="flex flex-col gap-1">
+        <dd
+          class="text-2xl font-semibold tracking-tight tabular-nums sm:text-3xl"
+        >
+          {{ servers.length }}
+        </dd>
+        <dt class="flex items-center gap-1.5 text-xs font-medium text-primary">
+          <Icon name="lucide:server" class="size-3.5" />
+          {{ $t('duxt.openapi.serverCount') }}
+        </dt>
+      </div>
+    </dl>
+
+    <div class="not-typeset">
+      <!-- THE GROUPS FIRST, and that is the whole of this reordering: they
+           are what a reader opened the reference for, and they stood third —
+           under the base URL and the authentication, which are details you
+           come back to once you know which endpoint you want. -->
+      <section v-if="groups?.length" class="mt-8">
+        <h2 class="duxt-label">
+          {{ $t('duxt.openapi.endpoints') }}
+        </h2>
+
+        <!-- The groups as rows, with the arrow every other list of links on
+             this site steps forward under the pointer. A grid of cards claimed
+             they are alternatives to choose between; they are a table of
+             contents. -->
+        <ul class="mt-3 -mx-3">
+          <li
+            v-for="group in groups"
+            :key="group.to"
+            class="border-t border-border/60 first:border-t-0"
+          >
+            <NuxtLink
+              :to="localeLink(group.to) ?? group.to"
+              class="group flex items-start gap-3 rounded-lg px-3 py-3 transition-colors hover:bg-muted/40"
+            >
+              <span class="min-w-0 flex-1">
+                <span class="flex flex-wrap items-baseline gap-x-3">
+                  <span class="font-medium">{{ group.name }}</span>
+                  <span class="text-xs text-muted-foreground tabular-nums">
+                    {{ group.operations }}
+                  </span>
+                </span>
+
+                <span
+                  v-if="group.description"
+                  class="mt-1 line-clamp-2 block text-sm text-muted-foreground"
+                >
+                  {{ group.description }}
+                </span>
+              </span>
+
+              <Icon
+                name="lucide:arrow-right"
+                aria-hidden="true"
+                class="mt-1 size-3.5 shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5"
+              />
+            </NuxtLink>
+          </li>
+        </ul>
+      </section>
+
+      <section v-if="servers?.length" class="mt-8">
+        <h2 class="duxt-label">
+          {{ $t('duxt.openapi.servers') }}
+        </h2>
+
+        <!-- Rows a hairline apart rather than a bordered card: the card said
+             "one object" about a list of several, and three of them down a page
+             put a frame around every fact the page states. -->
+        <ul class="mt-3 divide-y divide-border/60 border-t border-border/60">
+          <li v-for="server in servers" :key="server.url" class="py-3">
+            <code class="font-mono text-sm break-all">{{ server.url }}</code>
+
+            <p
+              v-if="server.description"
+              class="mt-1 text-sm text-muted-foreground"
+            >
+              {{ server.description }}
+            </p>
+
+            <!-- A `{variable}` in the URL is not decoration: without its
+                 default and its allowed values the base URL is unusable. -->
+            <dl
+              v-if="server.variables?.length"
+              class="mt-2 space-y-1 text-xs text-muted-foreground"
+            >
+              <div
+                v-for="variable in server.variables"
+                :key="variable.name"
+                class="flex flex-wrap gap-x-2"
+              >
+                <dt class="font-mono">{{ variable.name }}</dt>
+                <dd class="font-mono">{{ variable.default }}</dd>
+                <dd v-if="variable.enum?.length" class="font-mono">
+                  {{ variable.enum.join(' · ') }}
+                </dd>
+              </div>
+            </dl>
+          </li>
+        </ul>
+      </section>
+
+      <section v-if="securitySchemes?.length" class="mt-8">
+        <h2 class="duxt-label">
+          {{ $t('duxt.openapi.authentication') }}
+        </h2>
+
+        <ul class="mt-3 divide-y divide-border/60 border-t border-border/60">
+          <li v-for="scheme in securitySchemes" :key="scheme.key" class="py-3">
+            <div class="flex flex-wrap items-baseline gap-2">
+              <code class="font-mono text-sm font-medium">{{
+                scheme.key
+              }}</code>
+              <span class="text-xs text-muted-foreground">
+                {{ scheme.type }}
+                <template v-if="scheme.scheme">· {{ scheme.scheme }}</template>
+                <template v-if="scheme.name">· {{ scheme.name }}</template>
+                <template v-if="scheme.in">
+                  · {{ $t(`duxt.openapi.in.${scheme.in}`) }}
+                </template>
+              </span>
+            </div>
+
+            <p
+              v-if="scheme.description"
+              class="mt-1 text-sm text-muted-foreground"
+            >
+              {{ scheme.description }}
+            </p>
+          </li>
+        </ul>
+      </section>
+
+      <!-- ONE ROW, not four labelled lines. Contact, licence and terms are
+           what a reader looks up once and never reads: as a definition list
+           they took four lines and the visual weight of a section, under an
+           actual section that answers what the API does. -->
+      <p
+        v-if="contact ?? license ?? termsOfService ?? externalDocs"
+        class="mt-10 flex flex-wrap items-center gap-x-5 gap-y-2 border-t pt-5 text-xs text-muted-foreground"
+      >
+        <a
+          v-if="contact"
+          :href="contact.url ?? `mailto:${contact.email}`"
+          rel="noopener noreferrer"
+          class="inline-flex items-center gap-1.5 transition-colors hover:text-foreground"
+        >
+          <Icon name="lucide:mail" class="size-3.5" />
+          <!-- The words the label used to print, kept for whoever cannot see
+               the icon that replaced them: an envelope beside "Support" says
+               "contact" only to a reader who can see the envelope. -->
+          <span class="sr-only">{{ $t('duxt.openapi.contact') }}:</span>
+          {{ contact.name ?? contact.url ?? contact.email }}
+        </a>
+
+        <a
+          v-if="license"
+          :href="license.url"
+          rel="noopener noreferrer"
+          class="inline-flex items-center gap-1.5 transition-colors hover:text-foreground"
+        >
+          <Icon name="lucide:scale" class="size-3.5" />
+          <span class="sr-only">{{ $t('duxt.openapi.license') }}:</span>
+          {{ license.name ?? license.identifier }}
+        </a>
+
+        <a
+          v-if="termsOfService"
+          :href="termsOfService"
+          rel="noopener noreferrer"
+          class="inline-flex items-center gap-1.5 transition-colors hover:text-foreground"
+        >
+          <Icon name="lucide:file-text" class="size-3.5" />
+          {{ $t('duxt.openapi.terms') }}
+        </a>
+
+        <!-- The one item here whose text the DOCUMENT wrote. `description` is
+             prose in OpenAPI's own words, so it may be a label ("Guide") or a
+             whole sentence — and a sentence in a row of two-word chips reads as
+             a paragraph that lost its paragraph. It is clamped rather than
+             shortened: the full text stays in the link, which is what a screen
+             reader announces and what the title shows on hover. -->
+        <a
+          v-if="externalDocs"
+          :href="externalDocs.url"
+          :title="externalDocs.description"
+          rel="noopener noreferrer"
+          target="_blank"
+          class="inline-flex min-w-0 items-center gap-1.5 transition-colors hover:text-foreground"
+        >
+          <Icon name="lucide:book-open" class="size-3.5 shrink-0" />
+          <span class="max-w-64 truncate">
+            {{ externalDocs.description ?? $t('duxt.openapi.moreInfo') }}
+          </span>
+          <Icon
+            name="lucide:arrow-up-right"
+            class="size-3 shrink-0 opacity-60"
+          />
+        </a>
+      </p>
+    </div>
+  </div>
+</template>