@kirchdev/duxt 0.1.0

package/app/components/DuxtLandingShowcase.vue

@@ -0,0 +1,295 @@
+<script setup lang="ts">
+import { sourcesForRoute } from '../../sources-resolve';
+
+/**
+ * One feature, given a whole band: its prose on one side and the thing itself
+ * on the other.
+ *
+ * The feature GRID says what a site can do in four words per card. This says it
+ * in a paragraph and a running example, which is the difference between a list
+ * of claims and a demonstration — and the reason a landing page needs both
+ * rather than a longer grid.
+ *
+ * The sides alternate, and the alternation is decided by the CALLER's index
+ * rather than counted here: a component that counted its own instances would
+ * flip when a band is added above it, and a `reverse` written per band would be
+ * a layout decision in every entry of a config that should only carry content.
+ */
+const props = defineProps<{
+  showcase: DuxtResolved<DuxtShowcase>;
+  /** Position in the list. Even bands put the demo on the right. */
+  index: number;
+}>();
+
+const localeLink = useDuxtLink();
+
+/** A band's own `reverse` wins; otherwise the position decides. */
+const reversed = computed(
+  () => props.showcase.reverse ?? props.index % 2 === 1
+);
+
+const demo = computed(() => props.showcase.demo);
+
+/**
+ * Whether the CLIENT lays the band out rather than this component.
+ *
+ * A split client is two rows with prose beside each, and only it knows where
+ * those rows are — so it takes the words through its slots and this component
+ * draws none of its own. Anything else keeps the ordinary two columns.
+ */
+const splitClient = computed(
+  () =>
+    demo.value.type === 'operation' &&
+    (demo.value.layout ?? (props.showcase.full ? 'split' : 'panel')) === 'split'
+);
+
+/**
+ * The heading each band contributes to the document outline.
+ *
+ * An id per band rather than one shared one: `aria-labelledby` on the section
+ * needs a target that is THIS band's title, and a landing page with five bands
+ * pointing at the same node is five sections claiming one name.
+ */
+const headingId = computed(() => `duxt-showcase-${props.index}`);
+
+/** The files of a code demo. One draws a plain block, several draw a group. */
+const files = computed(() =>
+  demo.value.type === 'code' ? demo.value.files : []
+);
+
+/**
+ * The operation behind an `operation` demo — the try-it client on its own.
+ *
+ * Read out of the page Content already built for that endpoint, so nothing here
+ * parses OpenAPI a second time and a band and its page can never disagree. The
+ * collection is resolved from the TARGET's path rather than from the route this
+ * component happens to stand on, which is the landing page and belongs to no
+ * source.
+ */
+const duxt = useDuxtConfig();
+const { locale, fallbackLocale } = useI18n();
+
+const operationPath = computed(() =>
+  demo.value.type === 'operation' ? demo.value.to : undefined
+);
+
+const { data: operationPage } = await useAsyncData(
+  () => `duxt-showcase-operation-${operationPath.value ?? props.index}`,
+  () => {
+    const path = operationPath.value;
+    if (!path) return Promise.resolve(null);
+
+    const chain = sourcesForRoute(
+      path,
+      locale.value,
+      duxt.resolvedSources ?? [],
+      fallbackLocale.value as string | string[] | undefined
+    );
+
+    const collection = (chain[0]?.collection ?? 'docs') as DuxtCollectionArg;
+
+    return queryCollection(collection).path(path).first();
+  },
+  { watch: [operationPath, locale] }
+);
+
+/**
+ * Its props, in the shape `OpenApiOperation` hands the client.
+ *
+ * Undefined where the page carries no operation — a mistyped path, a section
+ * that is not an API reference — and the band then draws no demo rather than
+ * throwing on the landing page.
+ */
+const operation = computed(() =>
+  openApiOperationProps(
+    (operationPage.value as { body?: unknown } | null)?.body
+  )
+);
+</script>
+
+<template>
+  <section
+    class="mx-auto max-w-[90rem] px-4 py-12 sm:py-16 lg:px-8"
+    :aria-labelledby="headingId"
+  >
+    <!-- TWO COLUMNS, OR ONE. A demo that is a PICTURE of something — a framed
+         page, a screenshot, a block of config — reads fine beside its
+         paragraph. A demo that IS the thing needs the width the thing was built
+         for, and then the prose goes above it rather than beside it. -->
+    <div
+      :class="
+        splitClient
+          ? ''
+          : showcase.full
+            ? 'flex flex-col gap-8'
+            : 'grid items-center gap-8 lg:grid-cols-2 lg:gap-16'
+      "
+    >
+      <!-- THE PROSE. `lg:order-2` rather than a reordered DOM: the reading
+           order is title, text, list, link in every band, and a source order
+           that alternates would hand a screen reader a demo before the sentence
+           that says what it is.
+
+           A SPLIT CLIENT DRAWS ITS OWN. It is two rows, each with prose beside
+           it, and both come from this same component through its slots — see
+           the demo below. -->
+      <DuxtLandingProse
+        v-if="!splitClient"
+        :prose="showcase"
+        :heading-id="headingId"
+        :class="[
+          reversed && !showcase.full ? 'lg:order-2' : '',
+          showcase.full ? 'max-w-3xl' : ''
+        ]"
+      />
+
+      <!-- THE DEMO. `min-w-0` because a highlighted line of config is wider
+           than its column and a grid track sized to its content would push the
+           prose off the page rather than scroll the code. -->
+      <!-- `self-start`: a demo that changes height — a code group whose tabs
+           hold files of different lengths — grows DOWNWARDS from a fixed top
+           edge. Centred it grew in both directions, so the tab strip the reader
+           just clicked moved up under their cursor. The prose beside it stays
+           centred, which is what the row's `items-center` does. -->
+      <div
+        class="min-w-0 lg:self-start"
+        :class="reversed && !showcase.full ? 'lg:order-1' : ''"
+      >
+        <DuxtLiveWindow
+          v-if="demo.type === 'frame'"
+          :tabs="[
+            { label: showcase.title, to: demo.to, skeleton: demo.skeleton }
+          ]"
+          :height="demo.height"
+          :chrome="demo.chrome ?? true"
+        />
+
+        <!-- THE CLIENT, ON ITS OWN. Not the page it lives on: the panel sits
+             beside the endpoint only above 80rem and under the whole
+             description everywhere narrower, so a band-sized frame of that page
+             showed prose and hid the control the band is named for. This is the
+             control, with nothing around it — and less to download than the
+             second copy of the application a frame would have booted. -->
+        <!-- AND IT SCROLLS ITSELF, the way the operation page bounds the same
+             panel at `xl`. A full client is server, authentication, parameters,
+             a body editor, the send button and the samples under it — running
+             to twice the height of every other band, with its own paragraph
+             sitting in the middle of a column of nothing.
+
+             `max-h`, not `h`: a GET with two parameters is a short panel, and
+             padding it out to a POST's height is a box mostly empty. No border
+             and no padding here either — the client brings its own, and a
+             second one around it was a box drawn around a box.
+
+             NONE OF THAT IN A `full` BAND. There the client has the width it
+             was built for and splits itself into two cards, so there is no
+             column of nothing to rescue and nothing to cap. -->
+        <div
+          v-else-if="demo.type === 'operation'"
+          class="not-typeset"
+          :class="
+            showcase.full
+              ? ''
+              : 'max-h-[38rem] overflow-y-auto max-lg:max-h-[32rem]'
+          "
+          :style="
+            !showcase.full && demo.height
+              ? { maxHeight: demo.height }
+              : undefined
+          "
+        >
+          <!-- `v-bind` on a typed component: the props come out of a page's
+               body, so they are a record here and the component's own contract
+               is what checks them at the other end. -->
+          <DuxtOpenApiClient
+            v-if="operation"
+            :key="demo.to"
+            v-bind="operation as any"
+            :layout="demo.layout ?? (showcase.full ? 'split' : 'panel')"
+            :reverse="reversed"
+          >
+            <!-- The band's own words, handed to the row they belong beside.
+                 The `h2` the section is labelled by goes with the form; the
+                 samples row gets an `h3`, because it is a part of this section
+                 rather than a section of its own. -->
+            <template #beside-form>
+              <DuxtLandingProse :prose="showcase" :heading-id="headingId" />
+            </template>
+
+            <!-- THE `v-if` IS ON THE CONTENT, NOT ON THE SLOT. A
+                 `<template v-if>` around a named slot means the slot is not
+                 PASSED at all when the condition is false — and the server and
+                 the client disagree about what stands in its place, which is
+                 the hydration mismatch this produced:
+
+                   rendered on server: (start of fragment)
+                   expected on client: Symbol(v-cmt)
+
+                 Passed always, with the condition inside, both render the same
+                 comment node when there is nothing to show. -->
+            <template #beside-samples>
+              <DuxtLandingProse
+                v-if="demo.samples"
+                :prose="demo.samples"
+                :level="3"
+              />
+            </template>
+          </DuxtOpenApiClient>
+        </div>
+
+        <!-- ONE FILE: the block, with its own header naming it.
+
+             SEVERAL: `CodeGroup` — the same component `::code-group` draws on a
+             docs page, handed blocks built from config instead of from
+             Markdown. It reads the label off each child's `filename` and
+             switches that child's own header off, so a reader meets one control
+             in both places and this page grows no tab bar of its own. -->
+        <CodeGroup
+          v-else-if="demo.type === 'code' && files.length > 1"
+          class="my-0!"
+        >
+          <DuxtCodeBlock
+            v-for="(file, position) in files"
+            :key="file.name ?? position"
+            :code="file.code"
+            :language="file.language"
+            :filename="file.name"
+          />
+        </CodeGroup>
+
+        <DuxtCodeBlock
+          v-else-if="demo.type === 'code' && files[0]"
+          :code="files[0].code"
+          :language="files[0].language"
+          :filename="files[0].name"
+          class="my-0!"
+        />
+
+        <!-- Two <img>s rather than one: a screenshot of a light interface on a
+             dark page is a torch, and `srcDark` is how a site hands over the
+             other file. Without one, `src` serves both. -->
+        <div
+          v-else-if="demo.type === 'image'"
+          class="overflow-hidden rounded-xl border bg-background shadow-sm"
+        >
+          <img
+            :src="demo.src"
+            :alt="demo.alt ?? ''"
+            loading="lazy"
+            decoding="async"
+            class="w-full"
+            :class="demo.srcDark ? 'dark:hidden' : ''"
+          />
+          <img
+            v-if="demo.srcDark"
+            :src="demo.srcDark"
+            alt=""
+            loading="lazy"
+            decoding="async"
+            class="hidden w-full dark:block"
+          />
+        </div>
+      </div>
+    </div>
+  </section>
+</template>

package/app/components/DuxtLiveWindow.vue

@@ -0,0 +1,343 @@
+<script setup lang="ts">
+/**
+ * A page of this site, framed as a browser window and operable — the reader
+ * scrolls it, opens its navigation and flips its theme without leaving the
+ * page it stands on.
+ *
+ * The landing page had one of these written into it. It now needs four: the big
+ * one under the hero, and one per showcase band that would rather show the real
+ * thing than a screenshot of it. So the window is a component, and everything
+ * that made the original one expensive to get right lives here once:
+ *
+ *  - it is mounted ON APPROACH, never on the server. The frame is a second copy
+ *    of the application, and an iframe in the initial HTML is a second full page
+ *    load competing with the first paint;
+ *  - a POSTER covers the box until that copy has booted, so the band has its
+ *    height from the first byte rather than jumping to a page's worth;
+ *  - the address bar is polled rather than listened for. The frame is
+ *    same-origin, so its location is readable — but the site inside it is a Nuxt
+ *    app, and a client-side route change fires no `load` on the element.
+ *
+ * TABS ARE PAGES, NOT PANES. One frame, one page loaded at a time: four frames
+ * behind a tab bar would be four copies of the application booting for a band
+ * the reader sees one quarter of.
+ */
+const props = withDefaults(
+  defineProps<{
+    /** The pages behind the tab bar. One entry draws no tab bar at all. */
+    tabs?: DuxtResolved<DuxtDemoTab>[];
+    /** Window height, any CSS length. */
+    height?: string;
+    /** The browser chrome. `false` leaves the page in a plain bordered box. */
+    chrome?: boolean;
+    /** Prefetch the first tab's document while the browser is idle. */
+    prefetch?: boolean;
+    /**
+     * A screenshot shown until the live page is up — or instead of it, where
+     * `live` is false. Without one the window draws the SHAPE of a page from
+     * the theme's own tokens, which needs no asset and is right in both modes
+     * by construction.
+     */
+    poster?: string;
+    /** The dark-mode file. Without one, `poster` serves both — a torch. */
+    posterDark?: string;
+    /** The poster's alt text. Only read where the poster is the content. */
+    posterAlt?: string;
+    /**
+     * Load the page at all. `false` shows only the poster, which is what a site
+     * picks when a second copy of the application is a cost it will not pay.
+     */
+    live?: boolean;
+  }>(),
+  { chrome: true, prefetch: false, live: true }
+);
+
+const localeLink = useDuxtLink();
+const { t } = useI18n();
+
+const active = ref(0);
+const tabs = computed(() => props.tabs ?? []);
+const current = computed(() => tabs.value[active.value] ?? tabs.value[0]);
+
+/** Where the frame is pointed, in the reader's own language. */
+const target = computed(() => localeLink(current.value?.to ?? '/'));
+
+const root = useTemplateRef<HTMLElement>('root');
+const frame = useTemplateRef<HTMLIFrameElement>('frame');
+
+/** Mounted only once the band is on its way in — see the note above. */
+const visible = ref(false);
+
+/**
+ * True until the framed page has loaded once. Reset on a tab change, because
+ * that IS a first load — a different page, fetched from scratch.
+ *
+ * Only the first load of each: a route change the reader makes INSIDE the frame
+ * is the app's own navigation, which draws its own progress bar, and a second
+ * spinner over it would report the same thing twice.
+ */
+const loading = ref(true);
+
+const location = ref<{ href: string; path: string }>();
+
+function readFrameLocation() {
+  try {
+    const view = frame.value?.contentWindow;
+    if (!view) return;
+
+    const { href, pathname, search, hash } = view.location;
+    // The bar shows the whole URL the way a browser's does — origin included,
+    // which is only knowable in the browser. The link keeps the path, because
+    // that is what the router routes on.
+    location.value = { href, path: `${pathname}${search}${hash}` };
+  } catch {
+    // A cross-origin document: nothing to read, and nothing to report.
+  }
+}
+
+function select(index: number) {
+  if (index === active.value) return;
+  active.value = index;
+  loading.value = true;
+  // The bar would otherwise keep printing the page we just navigated away
+  // from, for as long as the new one takes to answer.
+  location.value = undefined;
+}
+
+/**
+ * The document, fetched into the cache while the browser is idle.
+ *
+ * The frame still mounts on approach — a prefetch is not an execution. What it
+ * removes is the SLOW half: a document, its entry chunk, its payload. By the
+ * time the observer says "now" there is nothing left to download.
+ * `as="document"` is what makes the browser reuse it for an iframe rather than
+ * fetch it a second time.
+ *
+ * Off by default, and set only on the window a reader is certain to reach. Four
+ * prefetched applications is not a saving, it is the first paint again.
+ */
+useHead(() => ({
+  link:
+    props.prefetch && props.live
+      ? [{ rel: 'prefetch', as: 'document', href: target.value }]
+      : []
+}));
+
+onMounted(() => {
+  if (!props.live) return;
+
+  const element = root.value;
+  if (!element) return;
+
+  // No IntersectionObserver (an old browser, a test environment): show it
+  // rather than leave an empty box on the page.
+  if (!('IntersectionObserver' in window)) {
+    visible.value = true;
+  } else {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return;
+        visible.value = true;
+        observer.disconnect();
+      },
+      // Far enough ahead that the frame has begun booting by the time the band
+      // is on screen: it is a second copy of the application, so the gap
+      // between "in view" and "usable" is a page load rather than a paint.
+      { rootMargin: '600px' }
+    );
+
+    observer.observe(element);
+    onBeforeUnmount(() => observer.disconnect());
+  }
+
+  const timer = setInterval(readFrameLocation, 500);
+  onBeforeUnmount(() => clearInterval(timer));
+});
+
+/**
+ * The origin comes from the REQUEST, which both halves can read: `window` on
+ * the client, the incoming headers on the server. Every other source swaps the
+ * printed string once — at the frame's first load, or at hydration — and that
+ * swap is a flicker between two spellings of one page.
+ */
+const requestUrl = useRequestURL({
+  xForwardedHost: true,
+  xForwardedProto: true
+});
+
+const href = computed(
+  () => location.value?.href ?? `${requestUrl.origin}${target.value}`
+);
+
+/** The frame's current page, falling back to the one it was pointed at. */
+const path = computed(() => location.value?.path ?? target.value);
+
+const title = computed(
+  () => current.value?.label ?? t('duxt.defaults.landing.preview')
+);
+</script>
+
+<template>
+  <div
+    ref="root"
+    class="overflow-hidden rounded-xl border bg-background shadow-sm"
+  >
+    <!-- The window's own frame. The address bar is a <div>, not an input: it
+         says which page is inside, and a text field a reader can type into but
+         not submit is a control that lies. -->
+    <div
+      v-if="chrome"
+      class="flex items-center gap-3 border-b bg-muted/60 px-4 py-2.5"
+    >
+      <div aria-hidden="true" class="flex shrink-0 items-center gap-1.5">
+        <span class="size-2.5 rounded-full bg-muted-foreground/30" />
+        <span class="size-2.5 rounded-full bg-muted-foreground/30" />
+        <span class="size-2.5 rounded-full bg-muted-foreground/30" />
+      </div>
+
+      <!-- One fixed width, centred: a bar sized to its text grows and shrinks
+           on every navigation inside the frame, which reads as the frame
+           jittering rather than as a URL changing. The status icon sits where a
+           browser puts its padlock — leftmost, always there, so the URL never
+           shifts when it changes. -->
+      <div class="flex min-w-0 flex-1 justify-center">
+        <div
+          class="flex w-full max-w-md items-center gap-2 rounded-md bg-background/70 px-3 py-1 font-mono text-xs text-muted-foreground"
+        >
+          <Icon
+            :name="loading && live ? 'lucide:loader-circle' : 'lucide:globe'"
+            class="size-3 shrink-0"
+            :class="loading && live ? 'animate-spin' : 'opacity-60'"
+            role="status"
+            :aria-label="
+              loading && live ? $t('duxt.defaults.landing.preview') : undefined
+            "
+          />
+          <span class="truncate">{{ href }}</span>
+        </div>
+      </div>
+
+      <!-- The way out of the frame. A page read inside a 30 rem window is a
+           demonstration; at some point the reader wants the real one. -->
+      <UiButton as-child size="sm" variant="ghost" class="shrink-0">
+        <NuxtLink :to="path">
+          <Icon name="lucide:external-link" class="size-3.5" />
+          <span class="sr-only sm:not-sr-only">
+            {{ $t('duxt.defaults.landing.previewOpen') }}
+          </span>
+        </NuxtLink>
+      </UiButton>
+    </div>
+
+    <!-- The tab bar, where there is more than one page to show. Real buttons
+         with `aria-selected` rather than a styled div: this is a tablist, the
+         arrow keys are expected to work, and they do because the buttons are
+         focusable in order. -->
+    <div
+      v-if="tabs.length > 1"
+      role="tablist"
+      :aria-label="$t('duxt.defaults.landing.demoTitle')"
+      class="flex gap-1 overflow-x-auto border-b bg-muted/30 px-2 py-1.5"
+    >
+      <button
+        v-for="(tab, index) in tabs"
+        :key="tab.to"
+        type="button"
+        role="tab"
+        :aria-selected="index === active"
+        class="flex shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-3 py-1.5 text-sm font-medium transition-colors"
+        :class="
+          index === active
+            ? 'bg-background text-foreground shadow-sm'
+            : 'text-muted-foreground hover:bg-background/60 hover:text-foreground'
+        "
+        @click="select(index)"
+      >
+        <Icon v-if="tab.icon" :name="tab.icon" class="size-4" />
+        {{ tab.label }}
+      </button>
+    </div>
+
+    <!-- THE BOX OWNS THE HEIGHT, not whatever happens to be inside it. The
+         frame is mounted late and the poster is absolutely positioned, so with
+         the height on the frame the band would have none at all until the frame
+         arrived, and then jump to a page's worth. -->
+    <!-- `@container`, because what is inside is sized by THIS BOX and not by
+         the browser window. The frame gets that for free — an iframe carries a
+         viewport of its own — but the poster is drawn in this document, and
+         with viewport breakpoints a half-width window on a wide screen drew the
+         full desktop page squeezed into it. -->
+    <div
+      class="relative @container h-[44rem] max-lg:h-[36rem] max-sm:h-[28rem]"
+      :style="height ? { height } : undefined"
+    >
+      <ClientOnly v-if="live">
+        <!-- `:key` on the target, so a tab change REPLACES the element rather
+             than repointing it: repointing an iframe pushes an entry onto the
+             browser's own history, and the reader's back button then walks the
+             tab bar instead of leaving the page.
+
+             NO `loading="lazy"`. The observer above has already decided this
+             frame should load, and the attribute puts the browser's heuristic
+             in front of that decision. -->
+        <iframe
+          v-if="visible"
+          :key="target"
+          ref="frame"
+          :src="target"
+          :title="title"
+          class="h-full w-full"
+          @load="
+            loading = false;
+            readFrameLocation();
+          "
+        />
+      </ClientOnly>
+
+      <!-- Over the frame until it has loaded once, then gone. Not `v-if`-ed
+           away on the same tick it stops being needed: a poster that vanishes
+           the instant the frame reports `load` swaps one picture for another
+           mid-paint, and a fade covers exactly that. `pointer-events-none` so a
+           poster on its way out cannot eat the click that lands underneath. -->
+      <Transition
+        enter-from-class="opacity-0"
+        leave-to-class="opacity-0"
+        enter-active-class="transition-opacity"
+        leave-active-class="transition-opacity duration-500"
+      >
+        <div
+          v-if="loading || !live"
+          class="absolute inset-0 overflow-hidden bg-background"
+          :class="live ? 'pointer-events-none' : ''"
+          :aria-hidden="live ? 'true' : undefined"
+        >
+          <!-- Two <img>s rather than one: a screenshot of a light theme on a
+               dark page is a torch, and `posterDark` is how a site hands over
+               the other file. Without one, `poster` serves both. -->
+          <template v-if="poster">
+            <img
+              :src="poster"
+              :alt="posterAlt ?? ''"
+              decoding="async"
+              class="h-full w-full object-cover object-top"
+              :class="posterDark ? 'dark:hidden' : ''"
+            />
+            <img
+              v-if="posterDark"
+              :src="posterDark"
+              alt=""
+              decoding="async"
+              class="hidden h-full w-full object-cover object-top dark:block"
+            />
+          </template>
+
+          <!-- No screenshot: the SHAPE of a documentation page, drawn from the
+               theme's own tokens. It needs no asset, it is right in both modes
+               by construction, and it says "a page is coming" where a blank box
+               said nothing. -->
+          <DuxtPreviewSkeleton v-else />
+        </div>
+      </Transition>
+    </div>
+  </div>
+</template>