@lupinum/ginko-docs 0.2.2 → 0.2.5

package/app/features/docs/composables/useScrollspy.ts

@@ -8,26 +8,91 @@ import {
   type MaybeRefOrGetter,
 } from "vue";
 
-export function useScrollspy(ids: MaybeRefOrGetter<string[]>, offset = 112) {
-  const activeId = ref("");
-  let observed: HTMLElement[] = [];
+export type ScrollspyHeading = {
+  id: string;
+  /** Viewport-relative top, in document order. */
+  top: number;
+};
+
+export type ScrollspyZone = {
+  zoneTop: number;
+  zoneBottom: number;
+  /** Viewport-relative bottom of the document (scrollHeight - scrollY). */
+  docEnd: number;
+  /** When the page is scrolled to the very bottom, the zone extends to docEnd
+   * so a short final section still activates. */
+  atBottom: boolean;
+};
+
+// Headings use `scroll-margin-top: 7rem` (= ZONE_TOP), so after an anchor jump
+// the clicked heading sits exactly at the zone top and becomes the first
+// active entry. The tolerance absorbs sub-pixel layout drift.
+const ZONE_TOP = 112;
+const TOLERANCE = 8;
+
+/**
+ * A heading is active while any part of its section (heading → next heading)
+ * intersects the reading zone. Pure so the zone model is unit-testable.
+ */
+export function computeActiveIds(headings: ScrollspyHeading[], zone: ScrollspyZone): string[] {
+  if (headings.length === 0) return [];
+
+  const zoneTop = zone.zoneTop + TOLERANCE;
+  const zoneBottom = zone.atBottom ? zone.docEnd : zone.zoneBottom;
+
+  const active: string[] = [];
+  for (let index = 0; index < headings.length; index++) {
+    const sectionTop = headings[index]!.top;
+    const sectionBottom = index < headings.length - 1 ? headings[index + 1]!.top : zone.docEnd;
+    if (sectionBottom > zoneTop && sectionTop < zoneBottom) {
+      active.push(headings[index]!.id);
+    }
+  }
+  if (active.length > 0) return active;
 
-  // Headings use `scroll-margin-top: 7rem` (= offset), so after an anchor jump
-  // a heading sits at exactly `offset` — with sub-pixel layout it can land a
-  // fraction below. The tolerance keeps that heading active instead of the
-  // previous section.
-  const tolerance = 8;
+  // No section in the zone (e.g. a long passage between headings): fall back
+  // to the last heading scrolled past the zone top, then to the first heading.
+  for (let index = headings.length - 1; index >= 0; index--) {
+    if (headings[index]!.top <= zoneTop) return [headings[index]!.id];
+  }
+  return [headings[0]!.id];
+}
 
-  function updateFromScroll() {
-    const candidates = observed
-      .map((element) => ({
+export function useScrollspy(ids: MaybeRefOrGetter<string[]>) {
+  const activeIds = ref<string[]>([]);
+  let observed: HTMLElement[] = [];
+  let rafId: number | null = null;
+
+  function update() {
+    const scrollY = window.scrollY;
+    const innerHeight = window.innerHeight;
+    const scrollHeight = document.documentElement.scrollHeight;
+    const next = computeActiveIds(
+      observed.map((element) => ({
         id: element.id,
         top: element.getBoundingClientRect().top,
-      }))
-      .filter((item) => item.top <= offset + tolerance)
-      .sort((a, b) => b.top - a.top);
+      })),
+      {
+        zoneTop: ZONE_TOP,
+        zoneBottom: innerHeight * 0.8,
+        docEnd: scrollHeight - scrollY,
+        atBottom: scrollY + innerHeight >= scrollHeight - 2,
+      },
+    );
+    if (
+      next.length !== activeIds.value.length ||
+      next.some((id, index) => id !== activeIds.value[index])
+    ) {
+      activeIds.value = next;
+    }
+  }
 
-    activeId.value = candidates[0]?.id ?? observed[0]?.id ?? "";
+  function scheduleUpdate() {
+    if (rafId !== null) return;
+    rafId = requestAnimationFrame(() => {
+      rafId = null;
+      update();
+    });
   }
 
   async function refresh() {
@@ -38,18 +103,21 @@ export function useScrollspy(ids: MaybeRefOrGetter<string[]>, offset = 112) {
       .map((id) => document.getElementById(id))
       .filter((element): element is HTMLElement => Boolean(element));
 
-    updateFromScroll();
+    update();
   }
 
   onMounted(() => {
     void refresh();
-    window.addEventListener("scroll", updateFromScroll, { passive: true });
+    window.addEventListener("scroll", scheduleUpdate, { passive: true });
+    window.addEventListener("resize", scheduleUpdate, { passive: true });
   });
 
   onBeforeUnmount(() => {
     observed = [];
     if (import.meta.client) {
-      window.removeEventListener("scroll", updateFromScroll);
+      window.removeEventListener("scroll", scheduleUpdate);
+      window.removeEventListener("resize", scheduleUpdate);
+      if (rafId !== null) cancelAnimationFrame(rafId);
     }
   });
 
@@ -61,7 +129,7 @@ export function useScrollspy(ids: MaybeRefOrGetter<string[]>, offset = 112) {
   );
 
   return {
-    activeId,
+    activeIds,
     refresh,
   };
 }

package/app/features/docs/docs-navigation.ts

@@ -1,9 +1,14 @@
-import type { ContentNavigationTreeItem } from "@lupinum/ginko-content/client";
+import {
+  findFirstNavigationPage,
+  navigationItemContainsPath,
+  normalizeNavigationPath,
+  type ContentNavigationTreeItem,
+  type NavigationSidebar,
+} from "@lupinum/ginko-content/navigation";
 
 export type RawDocsTreeItem = Omit<ContentNavigationTreeItem, "children"> & {
   icon?: unknown;
   badge?: unknown;
-  sidebar?: unknown;
   children?: RawDocsTreeItem[];
 };
 
@@ -13,7 +18,7 @@ export type DocsNavigationItem = {
   path?: string;
   icon?: string;
   badge?: string;
-  sidebar?: "section" | "group";
+  sidebar?: NavigationSidebar;
   children: DocsNavigationItem[];
 };
 
@@ -47,47 +52,29 @@ export function normalizeDocsNavigationItem(
     path: item.path,
     icon: typeof item.icon === "string" ? item.icon : undefined,
     badge: typeof item.badge === "string" ? item.badge : undefined,
-    sidebar: item.sidebar === "section" || item.sidebar === "group" ? item.sidebar : undefined,
+    sidebar: item.sidebar,
     children: (item.children ?? []).map((child, index) =>
       normalizeDocsNavigationItem(child, `${positionKey}.${index}`),
     ),
   };
 }
 
-export function normalizeDocsNavigationPath(path: string): string {
-  return path.length > 1 ? path.replace(/\/+$/, "") : path;
-}
-
-export function docsNavigationItemContainsPath(item: DocsNavigationItem, path: string): boolean {
-  const normalizedPath = normalizeDocsNavigationPath(path);
-  return (
-    (item.path !== undefined && normalizeDocsNavigationPath(item.path) === normalizedPath) ||
-    item.children.some((child) => docsNavigationItemContainsPath(child, normalizedPath))
-  );
-}
-
 export function docsNavigationSectionContainsPath(
   section: DocsNavigationSection,
   path: string,
 ): boolean {
-  const normalizedPath = normalizeDocsNavigationPath(path);
+  const normalizedPath = normalizeNavigationPath(path);
   return (
-    (section.path !== undefined && normalizeDocsNavigationPath(section.path) === normalizedPath) ||
-    section.items.some((item) => docsNavigationItemContainsPath(item, normalizedPath))
+    (section.path !== undefined && normalizeNavigationPath(section.path) === normalizedPath) ||
+    section.items.some((item) => navigationItemContainsPath(item, normalizedPath))
   );
 }
 
-export function findDocsNavigationTrail(
-  items: DocsNavigationItem[],
-  path: string,
-): DocsNavigationItem[] {
-  const normalizedPath = normalizeDocsNavigationPath(path);
-  for (const item of items) {
-    if (item.path && normalizeDocsNavigationPath(item.path) === normalizedPath) return [item];
-    const descendants = findDocsNavigationTrail(item.children, normalizedPath);
-    if (descendants.length > 0) return [item, ...descendants];
-  }
-  return [];
+// Structural sections have no page of their own — they resolve to their first
+// navigable page so switching to them lands somewhere instead of only swapping
+// the sidebar contents.
+export function resolveDocsSectionTargetPath(section: DocsNavigationSection): string | undefined {
+  return section.path ?? findFirstNavigationPage(section.items)?.path;
 }
 
 export function getDocsNavigationSections(items: DocsNavigationItem[]): DocsNavigationSection[] {

package/app/features/docs/toc-context.ts

@@ -0,0 +1,6 @@
+import type { ComputedRef, InjectionKey } from "vue";
+import type { FlatTocItem } from "#ginko-docs/utils/content";
+
+/** Current page TOC, provided by the docs page shell so in-content components
+ * (e.g. the `::toc` inline table of contents) can render it. */
+export const docsTocKey: InjectionKey<ComputedRef<FlatTocItem[]>> = Symbol("ginko-docs-toc");

package/app/features/search/command-center.ts

@@ -1,4 +1,4 @@
-export type CommandCenterGroup = "recent" | "pages" | "docs_nav" | "blog" | "docs" | "actions";
+export type CommandCenterGroup = "recent" | "pages" | "docs_nav" | "actions" | "search";
 
 export interface CommandCenterItem {
   id: string;
@@ -24,19 +24,6 @@ export interface CommandCenterGroupResult {
 export const MAX_RECENT_ITEMS = 5;
 export const PAGE_HIGHLIGHT_STORAGE_KEY = "site-command-center-page-highlight";
 
-const GROUP_PRIORITY: Record<CommandCenterGroup, number> = {
-  recent: 0,
-  pages: 1,
-  docs_nav: 2,
-  blog: 3,
-  docs: 4,
-  actions: 5,
-};
-
-function normalizeValue(value: string) {
-  return value.toLocaleLowerCase().trim();
-}
-
 export function dedupeCommandCenterItems(items: CommandCenterItem[]) {
   const seen = new Set<string>();
   return items.filter((item) => {
@@ -47,84 +34,22 @@ export function dedupeCommandCenterItems(items: CommandCenterItem[]) {
   });
 }
 
-export function scoreCommandCenterItem(item: CommandCenterItem, query: string) {
-  if (!query.trim()) return 1;
-
-  const normalizedQuery = normalizeValue(query);
-  const tokens = normalizedQuery.split(/\s+/).filter(Boolean);
-  const title = normalizeValue(item.title);
-  const subtitle = normalizeValue(item.subtitle ?? "");
-  const keywords = (item.keywords ?? []).map(normalizeValue);
-  const haystacks = [title, subtitle, ...keywords].filter(Boolean);
-  const isAnchoredResult = item.href?.includes("#") ?? false;
-
-  if (!tokens.every((token) => haystacks.some((value) => value.includes(token)))) return 0;
-
-  let score = 0;
-  if (title === normalizedQuery) score += isAnchoredResult ? 48 : 140;
-  if (title.startsWith(normalizedQuery)) score += isAnchoredResult ? 40 : 110;
-  if (title.includes(normalizedQuery)) score += isAnchoredResult ? 32 : 80;
-  if (subtitle.includes(normalizedQuery)) score += 48;
-
-  for (const keyword of keywords) {
-    if (keyword === normalizedQuery) score += 90;
-    else if (keyword.startsWith(normalizedQuery)) score += 56;
-    else if (keyword.includes(normalizedQuery)) score += 32;
-  }
-
-  for (const token of tokens) {
-    if (title.startsWith(token)) score += 18;
-    if (title.includes(token)) score += 12;
-    if (subtitle.includes(token)) score += 8;
-    if (keywords.some((keyword) => keyword.startsWith(token))) score += 10;
-  }
-
-  if (item.href && !isAnchoredResult) score += 16;
-  if (isAnchoredResult) score -= 12;
-  if (item.group === "pages") score += 20;
-  return score;
-}
-
 export function groupCommandCenterItems(
   items: CommandCenterItem[],
-  query: string,
   groupTitle: (group: CommandCenterGroup) => string,
 ): CommandCenterGroupResult[] {
-  const isSearching = query.trim().length > 0;
-  const ranked = items
-    .map((item) => ({
-      item,
-      score: item.group === "recent" && !isSearching ? 999 : scoreCommandCenterItem(item, query),
-    }))
-    .filter(({ score }) => score > 0)
-    .sort((left, right) => {
-      if (isSearching && left.score !== right.score) return right.score - left.score;
-      if (left.item.group !== right.item.group) {
-        return GROUP_PRIORITY[left.item.group] - GROUP_PRIORITY[right.item.group];
-      }
-      return isSearching ? left.item.title.localeCompare(right.item.title) : 0;
-    })
-    .slice(0, isSearching ? 12 : undefined);
-
-  const groups = new Map<CommandCenterGroup, Array<{ item: CommandCenterItem; score: number }>>();
-  for (const entry of ranked) {
-    const group = groups.get(entry.item.group) ?? [];
-    group.push(entry);
-    groups.set(entry.item.group, group);
+  const groups = new Map<CommandCenterGroup, CommandCenterItem[]>();
+  for (const item of items) {
+    const group = groups.get(item.group) ?? [];
+    group.push(item);
+    groups.set(item.group, group);
   }
 
-  return [...groups.entries()]
-    .map(([id, entries]) => ({
-      id,
-      title: groupTitle(id),
-      maxScore: Math.max(...entries.map((entry) => entry.score)),
-      items: entries.slice(0, 5).map((entry) => entry.item),
-    }))
-    .sort((left, right) => {
-      if (isSearching && left.maxScore !== right.maxScore) return right.maxScore - left.maxScore;
-      return GROUP_PRIORITY[left.id] - GROUP_PRIORITY[right.id];
-    })
-    .map(({ maxScore: _maxScore, ...group }) => group);
+  return [...groups].map(([id, groupItems]) => ({
+    id,
+    title: groupTitle(id),
+    items: groupItems.slice(0, 5),
+  }));
 }
 
 export function resolveRecentItems(
@@ -150,7 +75,3 @@ export function rememberRecentItem(
   const id = selectedItem.sourceId ?? selectedItem.id;
   return [id, ...storedItems.filter((item) => item !== id)].slice(0, MAX_RECENT_ITEMS);
 }
-
-export function contentSearchGroup(collection: string): "blog" | "docs" {
-  return collection === "blog" ? "blog" : "docs";
-}

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