@lupinum/ginko-docs 0.2.2

package/app/features/search/useCommandCenter.ts

@@ -0,0 +1,300 @@
+import { useLocalStorage } from "@vueuse/core";
+import { useContentSearch } from "@lupinum/ginko-content/client";
+import { computed, watch } from "vue";
+import { navigateTo, useI18n, useRoute, useState } from "#imports";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
+import { useSiteNavigation } from "#ginko-docs/composables/useSiteNavigation";
+import {
+  getDocsNavigationGroups,
+  type DocsNavigationItem,
+} from "#ginko-docs/features/docs/docs-navigation";
+import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
+import { useDocsNavigation } from "#ginko-docs/features/docs/composables/useDocsNavigation";
+import {
+  contentSearchGroup,
+  dedupeCommandCenterItems,
+  groupCommandCenterItems,
+  PAGE_HIGHLIGHT_STORAGE_KEY,
+  rememberRecentItem,
+  resolveRecentItems,
+  type CommandCenterItem,
+  type StoredRecentItem,
+} from "#ginko-docs/features/search/command-center";
+
+type ContentSearchHit = {
+  collection: string;
+  path: string;
+  title: string;
+  excerpt?: string;
+  anchor?: string;
+};
+
+const MAX_DEFAULT_PAGE_ITEMS = 6;
+const MAX_DEFAULT_DOC_ITEMS = 3;
+
+export function useCommandCenterState() {
+  const open = useState<boolean>("site-command-center-open", () => false);
+  const query = useState<string>("site-command-center-query", () => "");
+
+  function closeCommandCenter() {
+    open.value = false;
+    query.value = "";
+  }
+
+  function openCommandCenter(initialQuery = "") {
+    query.value = initialQuery;
+    open.value = true;
+  }
+
+  return {
+    open,
+    query,
+    openCommandCenter,
+    closeCommandCenter,
+  };
+}
+
+function flattenNavItems(items: DocsNavigationItem[]): DocsNavigationItem[] {
+  const output: DocsNavigationItem[] = [];
+  for (const item of items) {
+    output.push(item);
+    if (item.children.length > 0) {
+      output.push(...flattenNavItems(item.children));
+    }
+  }
+  return output;
+}
+
+export async function useCommandCenter() {
+  const route = useRoute();
+  const { locale, t } = useI18n();
+  const localizedPath = useLocalizedPath();
+  const {
+    open,
+    query,
+    openCommandCenter,
+    closeCommandCenter: closeState,
+  } = useCommandCenterState();
+  const recentSelections = useLocalStorage<StoredRecentItem[]>("site-command-center-recent", []);
+
+  const { mainNav, footerNav, socialLinks } = useSiteNavigation();
+  // Start every context-bound composable before the first await. Calling a
+  // Nuxt/i18n composable after an awaited operation loses the setup context.
+  const docsEntryPathResult = useDocsEntryPath();
+  const docsNavigationResult = useDocsNavigation();
+  const contentSearchResult = useContentSearch({
+    limit: 12,
+    locale: () => locale.value,
+  });
+  const [docsEntryPath, { sections }, { query: searchQuery, results: searchResults }] =
+    await Promise.all([docsEntryPathResult, docsNavigationResult, contentSearchResult]);
+
+  const contentSearchItems = computed<CommandCenterItem[]>(() =>
+    searchResults.value.map((hit: ContentSearchHit) => {
+      const group = contentSearchGroup(hit.collection);
+      const href = hit.anchor ? `${hit.path}#${hit.anchor}` : hit.path;
+
+      return {
+        id: `search-${href}`,
+        title: hit.title,
+        subtitle: hit.excerpt,
+        href,
+        group,
+        icon: group === "blog" ? "lucide:newspaper" : "lucide:book-open",
+        keywords: [group, hit.title, hit.excerpt ?? ""],
+        badge: group === "blog" ? t("nav.blog") : t("docs.label"),
+      };
+    }),
+  );
+
+  const pageItems = computed<CommandCenterItem[]>(() => {
+    const featured: CommandCenterItem[] = [
+      {
+        id: "page-home",
+        title: t("command.pages.home.title"),
+        subtitle: t("command.pages.home.description"),
+        href: localizedPath("home"),
+        group: "pages",
+        icon: "lucide:home",
+        keywords: ["landing", "overview", "hero"],
+      },
+    ];
+
+    const fromMainNav = mainNav.value.map<CommandCenterItem>((item) => ({
+      id: `page-main-${item.href}`,
+      title: item.label,
+      subtitle: t("command.pages.primary"),
+      href: item.href,
+      group: "pages",
+      icon: item.href === localizedPath("blog") ? "lucide:newspaper" : "lucide:file-text",
+      keywords: ["navigation", item.label],
+    }));
+
+    const footerResources = [
+      { label: t("nav.documentation"), href: docsEntryPath.value },
+      ...footerNav.value.resources,
+    ];
+    const fromFooter = [...footerNav.value.product, ...footerResources, ...footerNav.value.company]
+      .filter((item) => !(item as { external?: boolean }).external)
+      .map<CommandCenterItem>((item) => ({
+        id: `page-footer-${item.href}`,
+        title: item.label,
+        subtitle: t("command.pages.secondary"),
+        href: item.href,
+        group: "pages",
+        icon: "lucide:file-text",
+        keywords: ["footer", item.label],
+      }));
+
+    return dedupeCommandCenterItems([...featured, ...fromMainNav, ...fromFooter]);
+  });
+
+  const docsItems = computed<CommandCenterItem[]>(() => {
+    const navigationEntries = sections.value.flatMap((section) =>
+      getDocsNavigationGroups(section).flatMap((group) =>
+        flattenNavItems(group.items)
+          .filter((item) => item.path)
+          .map<CommandCenterItem>((item) => ({
+            id: `doc-${item.path}`,
+            title: item.title,
+            subtitle: group.title ?? section.title ?? t("docs.label"),
+            href: item.path,
+            group: "docs_nav",
+            icon: item.icon ?? "lucide:book-open",
+            keywords: [section.title ?? "", group.title ?? "", item.badge ?? "", item.title],
+            badge: item.badge,
+          })),
+      ),
+    );
+
+    const sectionIndexEntries = sections.value.flatMap<CommandCenterItem>((section) =>
+      section.path && section.title
+        ? [
+            {
+              id: `doc-section-${section.path}`,
+              title: section.title,
+              subtitle: t("command.pages.documentation"),
+              href: section.path,
+              group: "docs",
+              icon: section.icon ?? "lucide:book-open",
+              keywords: [section.title],
+            },
+          ]
+        : [],
+    );
+
+    return dedupeCommandCenterItems([...sectionIndexEntries, ...navigationEntries]);
+  });
+
+  const actionItems = computed<CommandCenterItem[]>(() => {
+    const github = socialLinks.value.find((item) => item.icon === "lucide:github");
+    return github
+      ? [
+          {
+            id: "action-github",
+            title: t("command.actions.github.title"),
+            subtitle: t("command.actions.github.description"),
+            href: github.href,
+            external: true,
+            group: "actions" as const,
+            icon: "lucide:github",
+            keywords: ["repo", "source", "code"],
+          },
+        ]
+      : [];
+  });
+
+  // Cross-group dedupe: a page reachable via nav can also appear as a content
+  // search hit with the same href. First occurrence wins, so nav entries
+  // (higher group priority) shadow duplicate search results while anchored
+  // hits (#section) stay distinct.
+  const allItems = computed(() =>
+    dedupeCommandCenterItems([
+      ...pageItems.value,
+      ...docsItems.value,
+      ...contentSearchItems.value,
+      ...actionItems.value,
+    ]),
+  );
+
+  const recentItems = computed<CommandCenterItem[]>(() => {
+    if (query.value) return [];
+
+    return resolveRecentItems(recentSelections.value, allItems.value);
+  });
+
+  const defaultItems = computed<CommandCenterItem[]>(() => {
+    const recentSourceIds = new Set(recentItems.value.map((item) => item.sourceId));
+    const docSectionItems = docsItems.value
+      .filter((item) => item.id.startsWith("doc-switcher-"))
+      .slice(0, MAX_DEFAULT_DOC_ITEMS);
+
+    return dedupeCommandCenterItems([
+      ...pageItems.value.slice(0, MAX_DEFAULT_PAGE_ITEMS),
+      ...docSectionItems,
+      ...actionItems.value,
+    ]).filter((item) => !recentSourceIds.has(item.id));
+  });
+
+  const groupedItems = computed(() => {
+    const candidates = query.value.trim()
+      ? allItems.value
+      : [...recentItems.value, ...defaultItems.value];
+    return groupCommandCenterItems(candidates, query.value, (group) =>
+      t(`command.groups.${group}`),
+    );
+  });
+
+  function rememberSelection(item: CommandCenterItem) {
+    recentSelections.value = rememberRecentItem(item, recentSelections.value);
+  }
+
+  function closeCommandCenter() {
+    closeState();
+    searchQuery.value = "";
+  }
+
+  async function selectItem(item: CommandCenterItem) {
+    const submittedQuery = query.value.trim();
+    rememberSelection(item);
+    closeCommandCenter();
+
+    if (!item.href) return;
+
+    if (item.external) {
+      if (import.meta.client) {
+        window.open(item.href, "_blank", "noopener,noreferrer");
+      }
+      return;
+    }
+
+    if (submittedQuery && import.meta.client) {
+      sessionStorage.setItem(
+        PAGE_HIGHLIGHT_STORAGE_KEY,
+        JSON.stringify({ href: item.href, query: submittedQuery }),
+      );
+    }
+
+    await navigateTo(item.href);
+  }
+
+  watch(query, (value) => {
+    searchQuery.value = value;
+  });
+
+  watch(
+    () => route.fullPath,
+    () => {
+      closeCommandCenter();
+    },
+  );
+
+  return {
+    open,
+    query,
+    groupedItems,
+    openCommandCenter,
+    closeCommandCenter,
+    selectItem,
+  };
+}

package/app/layouts/blog.vue

@@ -0,0 +1,15 @@
+<template>
+  <div class="flex min-h-dvh flex-col bg-background text-foreground selection:bg-primary/15">
+    <SiteSkipLink />
+    <SiteBanner />
+    <SiteHeader />
+    <main
+      id="main-content"
+      class="mx-auto w-full max-w-screen-2xl flex-1 px-4 pt-6 pb-12 md:px-6 md:pt-8 md:pb-16"
+    >
+      <slot />
+    </main>
+    <SiteFooter />
+    <SiteInteractionLayer />
+  </div>
+</template>

package/app/layouts/default.vue

@@ -0,0 +1,12 @@
+<template>
+  <div class="flex min-h-dvh flex-col bg-background text-foreground">
+    <SiteSkipLink />
+    <SiteBanner landing />
+    <SiteHeader />
+    <main id="main-content" class="flex-1">
+      <slot />
+    </main>
+    <SiteFooter />
+    <SiteInteractionLayer />
+  </div>
+</template>

package/app/layouts/docs.vue

@@ -0,0 +1,20 @@
+<template>
+  <div class="flex min-h-dvh flex-col bg-background text-foreground selection:bg-primary/15">
+    <SiteSkipLink />
+    <SiteBanner />
+    <SiteHeader />
+
+    <div class="mx-auto flex w-full max-w-screen-2xl min-w-0 flex-1">
+      <div
+        class="pointer-events-none sticky top-[var(--site-header-height)] z-20 hidden h-[calc(100dvh-var(--site-header-height))] w-[var(--docs-sidebar-width)] shrink-0 overflow-hidden *:pointer-events-auto md:block"
+      >
+        <DocsSidebar />
+      </div>
+
+      <slot />
+    </div>
+
+    <SiteFooter />
+    <SiteInteractionLayer />
+  </div>
+</template>

package/app/lib/errors.ts

@@ -0,0 +1,84 @@
+export type ErrorKind = "accessDenied" | "notFound" | "server" | "unavailable";
+
+export interface NormalizedAppError {
+  kind: ErrorKind;
+  message: string;
+  statusCode: number;
+  statusMessage: string;
+}
+
+type ErrorLike = {
+  data?: unknown;
+  fatal?: boolean;
+  message?: string;
+  name?: string;
+  status?: number;
+  statusCode?: number;
+  statusMessage?: string;
+  statusText?: string;
+};
+
+type ContentNotFoundError = Error & {
+  data: {
+    kind: "content-not-found";
+  };
+  fatal: true;
+  status: 404;
+  statusCode: 404;
+  statusMessage: "Not Found";
+  statusText: "Not Found";
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object");
+}
+
+function toErrorLike(error: unknown): ErrorLike {
+  return isObject(error) ? error : {};
+}
+
+function toStatusCode(error: ErrorLike): number {
+  const status = error.statusCode ?? error.status;
+  return typeof status === "number" && Number.isInteger(status) ? status : 500;
+}
+
+function errorKind(statusCode: number): ErrorKind {
+  if (statusCode === 404) return "notFound";
+  if (statusCode === 403) return "accessDenied";
+  if (statusCode >= 500) return "server";
+  return "unavailable";
+}
+
+function defaultStatusMessage(statusCode: number, kind: ErrorKind): string {
+  if (kind === "notFound") return "Not Found";
+  if (kind === "accessDenied") return "Forbidden";
+  if (kind === "server") return "Internal Server Error";
+  return statusCode >= 400 ? "Unavailable" : "Error";
+}
+
+export function normalizeAppError(error: unknown): NormalizedAppError {
+  const source = toErrorLike(error);
+  const statusCode = toStatusCode(source);
+  const kind = errorKind(statusCode);
+  const statusMessage =
+    source.statusMessage ?? source.statusText ?? defaultStatusMessage(statusCode, kind);
+  const message = source.message ?? statusMessage;
+
+  return {
+    kind,
+    message,
+    statusCode,
+    statusMessage,
+  };
+}
+
+export function createContentNotFoundError(): ContentNotFoundError {
+  const error = new Error("Content not found") as ContentNotFoundError;
+  error.data = { kind: "content-not-found" };
+  error.fatal = true;
+  error.status = 404;
+  error.statusCode = 404;
+  error.statusMessage = "Not Found";
+  error.statusText = "Not Found";
+  return error;
+}

package/app/lib/schema-org.ts

@@ -0,0 +1,38 @@
+import type { LocaleCode } from "../../i18n/locales";
+
+function absoluteUrl(path: string, siteUrl: string) {
+  return new URL(path, siteUrl).toString();
+}
+
+export function createBreadcrumbSchema(
+  items: Array<{ name: string; path: string }>,
+  siteUrl: string,
+) {
+  return {
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: absoluteUrl(item.path, siteUrl),
+    })),
+  };
+}
+
+export function createArticleSchema(
+  article: { date: string; description: string; title: string },
+  url: string,
+  authorName: string,
+  locale: LocaleCode,
+) {
+  return {
+    "@type": "TechArticle",
+    headline: article.title,
+    description: article.description,
+    datePublished: article.date,
+    dateModified: article.date,
+    url,
+    inLanguage: locale,
+    author: authorName ? { name: authorName } : undefined,
+  };
+}

package/app/lib/utils.ts

@@ -0,0 +1,7 @@
+import type { ClassValue } from "clsx";
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/app/pages/blog/[slug].vue

@@ -0,0 +1,211 @@
+<script setup lang="ts">
+import { Badge } from "#ginko-docs/components/ui/badge";
+import ContentFeedback from "#ginko-docs/components/content/Feedback.vue";
+import { Button } from "#ginko-docs/components/ui/button";
+import { createContentNotFoundError } from "#ginko-docs/lib/errors";
+import { createArticleSchema, createBreadcrumbSchema } from "#ginko-docs/lib/schema-org";
+import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
+import { filterTocByDepth, flattenTocLinks, formatContentDate } from "#ginko-docs/utils/content";
+import { computed, watch } from "vue";
+import {
+  definePageMeta,
+  useAppConfig,
+  useContentPage,
+  useHead,
+  useI18n,
+  useRoute,
+  useSeoMeta,
+} from "#imports";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
+import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
+import { useGinkoOgImage } from "#ginko-docs/composables/useGinkoOgImage";
+import { useSchemaJsonLd } from "#ginko-docs/composables/useSchemaJsonLd";
+import DocumentPageShell from "#ginko-docs/components/content/DocumentPageShell.vue";
+import PageMarkdownCopy from "#ginko-docs/components/content/PageMarkdownCopy.vue";
+import { syncContentRouteAlternates } from "#ginko-docs/composables/useContentRouteAlternates";
+
+definePageMeta({ layout: "blog" });
+
+const { locale, t } = useI18n();
+const config = useAppConfig().ginkoDocs;
+const route = useRoute();
+const localizedPath = useLocalizedPath();
+const {
+  page: post,
+  previous,
+  next,
+  error,
+} = await useContentPage("blog", {
+  locale: () => locale.value,
+  fallback: true,
+  populate: { author: "authors" },
+  surround: true,
+});
+if (error.value) throw error.value;
+if (!post.value) throw createContentNotFoundError();
+syncContentRouteAlternates(post);
+
+const pageTitle = computed(() => post.value?.title ?? t("blog.fallbackTitle"));
+const pageDescription = computed(() => post.value?.description ?? t("blog.fallbackDescription"));
+const canonicalUrl = useCanonicalUrl();
+const tocItems = computed(() =>
+  filterTocByDepth(flattenTocLinks(post.value?.body?.toc?.links), config.toc?.depth ?? 3),
+);
+const formattedDate = computed(() => formatContentDate(post.value?.date, locale.value));
+const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
+const articleAuthor = computed(() => post.value?.author?.name ?? siteName.value);
+const suggestions = computed(() => [previous.value, next.value].filter((entry) => entry !== null));
+
+useSeoMeta({
+  title: computed(() => `${pageTitle.value} - ${siteName.value}`),
+  description: pageDescription,
+  ogTitle: computed(() => `${pageTitle.value} - ${siteName.value}`),
+  ogDescription: pageDescription,
+  ogUrl: canonicalUrl,
+  twitterCard: "summary_large_image",
+  twitterTitle: computed(() => `${pageTitle.value} - ${siteName.value}`),
+  twitterDescription: pageDescription,
+});
+
+// Social card with the raw post title (no site-name suffix baked in).
+useGinkoOgImage({
+  title: pageTitle.value,
+  description: pageDescription.value,
+  locale: locale.value,
+});
+
+useHead(() => ({
+  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+  meta: [{ property: "og:type", content: "article" }],
+}));
+
+useSchemaJsonLd(() =>
+  post.value
+    ? [
+        createBreadcrumbSchema(
+          [
+            { name: t("blog.title"), path: localizedPath("blog") },
+            { name: post.value.title, path: post.value.route.resolvedPath },
+          ],
+          config.site.url,
+        ),
+        createArticleSchema(
+          {
+            date: post.value.date,
+            description: post.value.description,
+            title: post.value.title,
+          },
+          canonicalUrl.value,
+          articleAuthor.value,
+          locale.value,
+        ),
+      ]
+    : [],
+);
+</script>
+
+<template>
+  <DocumentPageShell :padded="false">
+    <Button as-child variant="ghost" class="mb-8 -ml-2 text-muted-foreground">
+      <NuxtLink :to="localizedPath('blog')">
+        <Icon name="lucide:arrow-left" class="size-4" aria-hidden="true" />
+        {{ t("blog.back") }}
+      </NuxtLink>
+    </Button>
+
+    <div v-if="post" class="mb-12">
+      <div class="mb-8 flex items-center justify-between gap-4">
+        <div class="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2">
+          <Badge v-if="post.badge" variant="secondary">{{ post.badge }}</Badge>
+          <span class="text-sm text-muted-foreground"
+            >{{ formattedDate
+            }}<template v-if="post.readingTime"> · {{ post.readingTime }}</template></span
+          >
+          <span class="hidden text-sm text-muted-foreground sm:inline" aria-hidden="true"> · </span>
+          <span class="inline-flex items-center gap-2 text-sm text-muted-foreground">
+            <img
+              v-if="post.author?.avatar"
+              :src="post.author.avatar"
+              :alt="articleAuthor"
+              class="size-5 shrink-0 rounded-full border border-border object-cover"
+              loading="lazy"
+            />
+            {{ articleAuthor }}
+          </span>
+        </div>
+        <PageMarkdownCopy />
+      </div>
+      <h1
+        class="font-serif text-3xl leading-tight font-semibold tracking-tight text-foreground sm:text-4xl md:text-5xl"
+      >
+        {{ post.title }}
+      </h1>
+      <p class="mt-6 text-lg leading-8 text-muted-foreground sm:text-xl">{{ post.description }}</p>
+    </div>
+
+    <nav
+      v-if="tocItems.length"
+      :aria-label="t('blog.toc')"
+      class="not-prose mx-auto mb-12 max-w-[44rem] border-y border-border py-7"
+    >
+      <p class="mb-6 text-sm font-semibold text-foreground">{{ t("blog.toc") }}</p>
+      <ol class="grid gap-x-12 gap-y-2 sm:grid-cols-2" role="list">
+        <li v-for="(item, index) in tocItems" :key="item.id">
+          <a
+            :href="`#${item.id}`"
+            class="group grid grid-cols-[2rem_minmax(0,1fr)] gap-3 rounded-md py-1.5 transition-colors hover:bg-accent/45 sm:-mx-2 sm:px-2"
+          >
+            <span
+              class="pt-0.5 font-mono text-xs leading-6 text-muted-foreground tabular-nums transition-colors group-hover:text-foreground/70"
+            >
+              {{ String(index + 1).padStart(2, "0") }}
+            </span>
+            <span
+              class="text-sm leading-6 text-foreground/80 transition-colors group-hover:text-foreground"
+              :class="
+                item.depth === 3
+                  ? 'pl-3 text-muted-foreground'
+                  : (item.depth ?? 2) >= 4
+                    ? 'pl-6 text-muted-foreground'
+                    : ''
+              "
+            >
+              {{ item.label }}
+            </span>
+          </a>
+        </li>
+      </ol>
+    </nav>
+
+    <div v-if="post" class="content-prose mx-auto max-w-[42rem]">
+      <ContentRenderer :value="post" />
+    </div>
+
+    <ContentFeedback :label="t('feedback.articleLabel')" />
+
+    <div v-if="suggestions.length" class="mt-14">
+      <h2 class="mb-6 text-sm font-semibold tracking-wider text-muted-foreground uppercase">
+        {{ t("blog.moreArticles") }}
+      </h2>
+      <div class="divide-y divide-border border-y border-border">
+        <NuxtLink
+          v-for="p in suggestions"
+          :key="p.path"
+          :to="p.path"
+          class="group grid grid-cols-[minmax(0,1fr)_1.5rem] items-center gap-4 py-6 transition-colors hover:bg-accent/35 sm:px-2"
+        >
+          <h3
+            class="font-serif text-lg leading-snug font-semibold text-foreground transition-colors group-hover:text-primary"
+          >
+            {{ p.title }}
+          </h3>
+          <Icon
+            name="lucide:arrow-right"
+            class="hidden size-4 self-center text-muted-foreground transition-all group-hover:translate-x-0.5 group-hover:text-primary sm:block"
+            aria-hidden="true"
+          />
+        </NuxtLink>
+      </div>
+    </div>
+  </DocumentPageShell>
+</template>