@lupinum/ginko-docs 0.2.2 → 0.2.3

package/app/features/search/components/SiteCommandCenter.vue

@@ -16,39 +16,24 @@ const { t } = useI18n();
 const route = useRoute();
 const inputRef = useTemplateRef<HTMLInputElement>("input");
 const highlightedId = ref("");
-const { open, query, groupedItems, selectItem } = await useCommandCenter();
+const { open, query, groupedItems, searchPending, searchError, searchIsEmpty, selectItem } =
+  await useCommandCenter();
 
 const visibleItems = computed(() => groupedItems.value.flatMap((g) => g.items));
+const isSearching = computed(() => query.value.trim().length > 0);
 
 // ── text highlighting ──────────────────────────────────────────────────────
-function escapeHtml(str: string) {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-function highlight(text: string, q: string): string {
-  if (!q.trim()) return escapeHtml(text);
-  const pattern = q
-    .trim()
-    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-    .split(/\s+/)
-    .filter(Boolean)
-    .join("|");
-  const parts = text.split(new RegExp(`(${pattern})`, "gi"));
-  return parts
-    .map((part) =>
-      part.toLowerCase() === q.trim().toLowerCase() ||
-      q
-        .trim()
-        .split(/\s+/)
-        .some((t) => part.toLowerCase() === t.toLowerCase())
-        ? `<mark class="bg-primary/15 text-primary rounded-[3px] font-medium not-italic">${escapeHtml(part)}</mark>`
-        : escapeHtml(part),
-    )
-    .join("");
+function highlightTokens(text: string, q: string): { text: string; match: boolean }[] {
+  const terms = q.trim().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [{ text, match: false }];
+  const pattern = terms.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+  return text
+    .split(new RegExp(`(${pattern})`, "gi"))
+    .filter((part) => part !== "")
+    .map((part) => ({
+      text: part,
+      match: terms.some((term) => part.toLowerCase() === term.toLowerCase()),
+    }));
 }
 
 // ── keyboard navigation ────────────────────────────────────────────────────
@@ -181,8 +166,26 @@ onMounted(async () => {
 
         <!-- Results -->
         <div class="min-h-0 flex-1 overflow-y-auto overscroll-contain py-2">
+          <div
+            v-if="isSearching && searchPending"
+            class="flex items-center justify-center gap-2 px-6 py-12 text-sm text-muted-foreground"
+            role="status"
+          >
+            <Icon name="lucide:loader-circle" class="size-4 animate-spin" aria-hidden="true" />
+            {{ t("command.loading") }}
+          </div>
+
+          <div
+            v-else-if="isSearching && searchError"
+            class="flex flex-col items-center justify-center gap-2 px-6 py-12 text-center"
+            role="alert"
+          >
+            <Icon name="lucide:circle-alert" class="size-5 text-destructive" aria-hidden="true" />
+            <p class="max-w-sm text-sm font-medium text-foreground">{{ t("command.error") }}</p>
+          </div>
+
           <!-- Groups -->
-          <template v-if="visibleItems.length">
+          <template v-else-if="visibleItems.length">
             <div v-for="group in groupedItems" :key="group.id" class="mb-1 px-2 last:mb-0">
               <div class="flex items-center gap-2 px-2 pt-1.5 pb-1">
                 <span class="text-[11px] font-medium text-muted-foreground">{{ group.title }}</span>
@@ -225,11 +228,18 @@ onMounted(async () => {
                 <!-- Text -->
                 <div class="min-w-0 flex-1">
                   <div class="flex min-w-0 items-center gap-2">
-                    <!-- eslint-disable vue/no-v-html -->
-                    <span
-                      class="min-w-0 truncate text-sm leading-5 font-medium"
-                      v-html="highlight(item.title, query)"
-                    />
+                    <span class="min-w-0 truncate text-sm leading-5 font-medium">
+                      <template
+                        v-for="(token, tokenIndex) in highlightTokens(item.title, query)"
+                        :key="tokenIndex"
+                      >
+                        <mark
+                          v-if="token.match"
+                          class="rounded-[3px] bg-primary/15 font-medium text-primary not-italic"
+                          >{{ token.text }}</mark
+                        ><template v-else>{{ token.text }}</template>
+                      </template>
+                    </span>
                     <span
                       v-if="item.badge"
                       class="shrink-0 rounded-full bg-primary/10 px-1.5 py-px text-[10px] font-medium text-primary"
@@ -246,8 +256,18 @@ onMounted(async () => {
                       class="mt-1 size-3 shrink-0 opacity-50"
                       aria-hidden="true"
                     />
-                    <span class="line-clamp-2 min-w-0" v-html="highlight(item.subtitle, query)" />
-                    <!-- eslint-enable vue/no-v-html -->
+                    <span class="line-clamp-2 min-w-0">
+                      <template
+                        v-for="(token, tokenIndex) in highlightTokens(item.subtitle, query)"
+                        :key="tokenIndex"
+                      >
+                        <mark
+                          v-if="token.match"
+                          class="rounded-[3px] bg-primary/15 font-medium text-primary not-italic"
+                          >{{ token.text }}</mark
+                        ><template v-else>{{ token.text }}</template>
+                      </template>
+                    </span>
                   </p>
                 </div>
 
@@ -274,7 +294,7 @@ onMounted(async () => {
 
           <!-- Empty state -->
           <div
-            v-else
+            v-else-if="!isSearching || searchIsEmpty"
             class="flex flex-col items-center justify-center gap-2 px-6 py-12 text-center"
           >
             <div

package/app/features/search/useCommandCenter.ts

@@ -8,10 +8,8 @@ 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,
@@ -21,14 +19,6 @@ import {
   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;
 
@@ -77,21 +67,27 @@ export async function useCommandCenter() {
   } = useCommandCenterState();
   const recentSelections = useLocalStorage<StoredRecentItem[]>("site-command-center-recent", []);
 
-  const { mainNav, footerNav, socialLinks } = useSiteNavigation();
+  const { mainNav, 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 [
+    { sections },
+    {
+      query: searchQuery,
+      results: searchResults,
+      pending: searchPending,
+      error: searchError,
+      isEmpty: searchIsEmpty,
+    },
+  ] = await Promise.all([docsNavigationResult, contentSearchResult]);
 
   const contentSearchItems = computed<CommandCenterItem[]>(() =>
-    searchResults.value.map((hit: ContentSearchHit) => {
-      const group = contentSearchGroup(hit.collection);
+    searchResults.value.map((hit) => {
       const href = hit.anchor ? `${hit.path}#${hit.anchor}` : hit.path;
 
       return {
@@ -99,10 +95,9 @@ export async function useCommandCenter() {
         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"),
+        group: "search",
+        icon: hit.collection === "blog" ? "lucide:newspaper" : "lucide:book-open",
+        badge: hit.collection === "blog" ? t("nav.blog") : t("docs.label"),
       };
     }),
   );
@@ -130,11 +125,10 @@ export async function useCommandCenter() {
       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]
+    const fromFooter = [
+      { label: t("nav.documentation"), href: localizedPath("docs") },
+      ...socialLinks.value,
+    ]
       .filter((item) => !(item as { external?: boolean }).external)
       .map<CommandCenterItem>((item) => ({
         id: `page-footer-${item.href}`,
@@ -175,7 +169,7 @@ export async function useCommandCenter() {
               title: section.title,
               subtitle: t("command.pages.documentation"),
               href: section.path,
-              group: "docs",
+              group: "docs_nav",
               icon: section.icon ?? "lucide:book-open",
               keywords: [section.title],
             },
@@ -204,30 +198,19 @@ export async function useCommandCenter() {
       : [];
   });
 
-  // 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 canonicalItems = computed(() =>
+    dedupeCommandCenterItems([...pageItems.value, ...docsItems.value, ...actionItems.value]),
   );
 
   const recentItems = computed<CommandCenterItem[]>(() => {
     if (query.value) return [];
 
-    return resolveRecentItems(recentSelections.value, allItems.value);
+    return resolveRecentItems(recentSelections.value, canonicalItems.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);
+    const docSectionItems = docsItems.value.slice(0, MAX_DEFAULT_DOC_ITEMS);
 
     return dedupeCommandCenterItems([
       ...pageItems.value.slice(0, MAX_DEFAULT_PAGE_ITEMS),
@@ -237,16 +220,30 @@ export async function useCommandCenter() {
   });
 
   const groupedItems = computed(() => {
-    const candidates = query.value.trim()
-      ? allItems.value
-      : [...recentItems.value, ...defaultItems.value];
-    return groupCommandCenterItems(candidates, query.value, (group) =>
+    if (query.value.trim()) {
+      return contentSearchItems.value.length
+        ? [
+            {
+              id: "search" as const,
+              title: t("command.groups.search"),
+              items: contentSearchItems.value,
+            },
+          ]
+        : [];
+    }
+    return groupCommandCenterItems([...recentItems.value, ...defaultItems.value], (group) =>
       t(`command.groups.${group}`),
     );
   });
 
   function rememberSelection(item: CommandCenterItem) {
-    recentSelections.value = rememberRecentItem(item, recentSelections.value);
+    const canonicalItem =
+      item.group === "search"
+        ? canonicalItems.value.find((candidate) => candidate.href === item.href)
+        : item;
+    if (canonicalItem) {
+      recentSelections.value = rememberRecentItem(canonicalItem, recentSelections.value);
+    }
   }
 
   function closeCommandCenter() {
@@ -293,6 +290,9 @@ export async function useCommandCenter() {
     open,
     query,
     groupedItems,
+    searchPending,
+    searchError,
+    searchIsEmpty,
     openCommandCenter,
     closeCommandCenter,
     selectItem,

package/app/layouts/docs.vue

@@ -6,7 +6,7 @@
 
     <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"
+        class="pointer-events-none sticky top-[var(--site-header-height)] z-20 hidden h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] w-[var(--docs-sidebar-width)] shrink-0 overflow-hidden *:pointer-events-auto md:block"
       >
         <DocsSidebar />
       </div>

package/app/lib/errors.ts

@@ -2,31 +2,12 @@ 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> {
@@ -44,41 +25,13 @@ function toStatusCode(error: ErrorLike): number {
 
 function errorKind(statusCode: number): ErrorKind {
   if (statusCode === 404) return "notFound";
-  if (statusCode === 403) return "accessDenied";
+  if (statusCode === 401 || 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;
+  return { kind: errorKind(statusCode), statusCode };
 }

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

@@ -2,13 +2,18 @@
 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 {
+  filterTocByDepth,
+  flattenTocLinks,
+  formatContentDate,
+  getMarkdownTocLinks,
+} from "#ginko-docs/utils/content";
 import { computed, watch } from "vue";
 import {
   definePageMeta,
+  createError,
   useAppConfig,
   useContentPage,
   useHead,
@@ -22,7 +27,7 @@ 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";
+import { useContentRouteAlternates } from "#ginko-docs/composables/useContentRouteAlternates";
 
 definePageMeta({ layout: "blog" });
 
@@ -30,26 +35,26 @@ const { locale, t } = useI18n();
 const config = useAppConfig().ginkoDocs;
 const route = useRoute();
 const localizedPath = useLocalizedPath();
+const canonicalUrl = useCanonicalUrl();
+const { sync: syncContentRouteAlternates } = useContentRouteAlternates();
 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();
+if (!post.value) throw createError({ statusCode: 404, statusMessage: "Not Found" });
 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),
+  filterTocByDepth(flattenTocLinks(getMarkdownTocLinks(post.value?.body)), config.toc?.depth ?? 3),
 );
 const formattedDate = computed(() => formatContentDate(post.value?.date, locale.value));
 const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
@@ -181,7 +186,10 @@ useSchemaJsonLd(() =>
       <ContentRenderer :value="post" />
     </div>
 
-    <ContentFeedback :label="t('feedback.articleLabel')" />
+    <ContentFeedback
+      class="mt-14 border-y border-border py-5"
+      :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">

package/app/pages/blog/index.vue

@@ -7,22 +7,12 @@ import { computed } from "vue";
 import { definePageMeta, useAppConfig, useAsyncData, useHead, useI18n, useSeoMeta } from "#imports";
 import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
 
+const MAX_BLOG_POSTS = 50;
+
 definePageMeta({ layout: "blog" });
 
 const { locale, t } = useI18n();
 const postsKey = computed(() => `blog-posts:${locale.value}`);
-const { data: posts } = await useAsyncData(
-  postsKey,
-  () =>
-    many("blog", {
-      locale: locale.value,
-      fallback: true,
-      populate: { author: "authors" },
-      sort: { date: "desc" },
-      limit: 50,
-    }),
-  { watch: [locale] },
-);
 const canonicalUrl = useCanonicalUrl();
 const config = useAppConfig().ginkoDocs;
 const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
@@ -40,6 +30,26 @@ useSeoMeta({
 useHead(() => ({
   link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
 }));
+
+const { data: queriedPosts, error } = await useAsyncData(
+  postsKey,
+  () =>
+    many("blog", {
+      locale: locale.value,
+      fallback: true,
+      populate: { author: "authors" },
+      sort: { date: "desc" },
+      limit: MAX_BLOG_POSTS + 1,
+    }),
+  { watch: [locale] },
+);
+if (error.value) throw error.value;
+if ((queriedPosts.value?.length ?? 0) > MAX_BLOG_POSTS) {
+  throw new Error(
+    `Blog supports at most ${MAX_BLOG_POSTS} posts; add pagination before publishing more`,
+  );
+}
+const posts = computed(() => queriedPosts.value ?? []);
 </script>
 
 <template>
@@ -49,7 +59,10 @@ useHead(() => ({
       <p class="mt-2 text-muted-foreground">{{ t("blog.description") }}</p>
     </div>
 
-    <div class="divide-y divide-border">
+    <p v-if="posts.length === 0" class="py-12 text-center text-sm text-muted-foreground">
+      {{ t("blog.empty") }}
+    </p>
+    <div v-else class="divide-y divide-border">
       <article v-for="post in posts" :key="post.route.resolvedPath" class="group py-8">
         <NuxtLink
           :to="post.route.resolvedPath"

package/app/pages/docs/index.vue

@@ -1,23 +1,19 @@
 <script setup lang="ts">
-import { definePageMeta, navigateTo, useRoute } from "#imports";
-import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
+import { findFirstNavigationPage } from "@lupinum/ginko-content/navigation";
+import { createError, definePageMeta, navigateTo } from "#imports";
+import { useDocsNavigationData } from "#ginko-docs/features/docs/composables/useDocsNavigationData";
 
 definePageMeta({ layout: "docs" });
 
-const route = useRoute();
-const entryPath = await useDocsEntryPath();
-
-// Redirect the bare docs root to the first documentation page. Guard against
-// self-redirects when no docs pages exist (entry path falls back to the root).
-if (entryPath.value && entryPath.value !== route.path) {
-  await navigateTo(entryPath.value, { redirectCode: 302, replace: true });
+const { data, error } = await useDocsNavigationData();
+if (error.value) throw error.value;
+const entryPath = findFirstNavigationPage(data.value ?? undefined)?.path;
+if (!entryPath) {
+  throw createError({ statusCode: 404, statusMessage: "Documentation is empty" });
 }
+await navigateTo(entryPath, { redirectCode: 302, replace: true });
 </script>
 
 <template>
-  <main id="main-content" class="flex-1 px-4 py-12 md:px-6">
-    <NuxtLink v-if="entryPath && entryPath !== route.path" :to="entryPath" class="underline">
-      {{ entryPath }}
-    </NuxtLink>
-  </main>
+  <main id="main-content" />
 </template>