@lupinum/ginko-docs 0.2.2

package/app/features/docs/components/DocsToc.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "#ginko-docs/lib/utils";
+import { useI18n } from "#imports";
+
+export interface TocItem {
+  id: string;
+  label: string;
+  depth?: number; // 2 = h2, 3 = h3
+}
+
+const props = withDefaults(
+  defineProps<{
+    items: TocItem[];
+    activeId?: string;
+    showTitle?: boolean;
+    class?: HTMLAttributes["class"];
+  }>(),
+  {
+    showTitle: true,
+  },
+);
+const { t } = useI18n();
+</script>
+
+<template>
+  <div v-if="items.length" :class="cn('w-full', props.class)">
+    <h3 v-if="showTitle" class="mb-4 flex items-center gap-2 text-sm font-semibold text-foreground">
+      <Icon name="lucide:list" class="size-3.5 shrink-0" aria-hidden="true" />
+      {{ t("docs.toc") }}
+    </h3>
+
+    <div class="relative space-y-1 border-l border-border pl-3 text-[13px]">
+      <!-- Animated active indicator -->
+      <div
+        class="absolute -left-px w-0.5 rounded-full bg-primary transition-all duration-200"
+        :style="
+          activeId && items.findIndex((i) => i.id === activeId) !== -1
+            ? `top: ${items.findIndex((i) => i.id === activeId) * 26 + 2}px; height: 20px; opacity: 1;`
+            : 'top: 2px; height: 20px; opacity: 0;'
+        "
+      />
+
+      <a
+        v-for="item in items"
+        :key="item.id"
+        :href="`#${item.id}`"
+        class="block truncate py-0.5 leading-5 transition-colors"
+        :class="[
+          item.depth === 3 ? 'pl-3' : (item.depth ?? 2) >= 4 ? 'pl-6' : '',
+          activeId === item.id
+            ? 'font-medium text-primary'
+            : 'text-muted-foreground hover:text-foreground',
+        ]"
+      >
+        {{ item.label }}
+      </a>
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,13 @@
+import { computed } from "vue";
+import { findFirstNavigationPage } from "@lupinum/ginko-content/client";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
+import { useDocsNavigationData } from "./useDocsNavigationData";
+
+export async function useDocsEntryPath() {
+  const localizedPath = useLocalizedPath();
+  const { data } = await useDocsNavigationData();
+
+  return computed(
+    () => findFirstNavigationPage(data.value ?? undefined)?.path ?? localizedPath("docs"),
+  );
+}

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

@@ -0,0 +1,29 @@
+import { computed } from "vue";
+import { useRoute } from "#imports";
+import {
+  findDocsNavigationTrail,
+  getDocsNavigationSections,
+  normalizeDocsNavigationItem,
+  type DocsNavigationSection,
+} from "../docs-navigation";
+import { useDocsNavigationData } from "./useDocsNavigationData";
+
+export async function useDocsNavigation() {
+  const route = useRoute();
+  const { data } = await useDocsNavigationData();
+
+  const roots = computed(() => {
+    return (data.value ?? []).map((item, index) => normalizeDocsNavigationItem(item, index));
+  });
+
+  const sections = computed<DocsNavigationSection[]>(() => {
+    return getDocsNavigationSections(roots.value);
+  });
+
+  const trail = computed(() => findDocsNavigationTrail(roots.value, route.path));
+
+  return {
+    sections,
+    trail,
+  };
+}

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

@@ -0,0 +1,15 @@
+import { computed } from "vue";
+import { navigation } from "@lupinum/ginko-content/client";
+import { useAsyncData, useI18n } from "#imports";
+
+export async function useDocsNavigationData() {
+  const { locale } = useI18n();
+  const navigationKey = computed(() => `docs-navigation:${locale.value}`);
+
+  return useAsyncData(navigationKey, () =>
+    navigation("docs", {
+      locale: locale.value,
+      select: ["icon", "badge", "sidebar"],
+    }),
+  );
+}

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

@@ -0,0 +1,67 @@
+import {
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+} from "vue";
+
+export function useScrollspy(ids: MaybeRefOrGetter<string[]>, offset = 112) {
+  const activeId = ref("");
+  let observed: HTMLElement[] = [];
+
+  // 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;
+
+  function updateFromScroll() {
+    const candidates = observed
+      .map((element) => ({
+        id: element.id,
+        top: element.getBoundingClientRect().top,
+      }))
+      .filter((item) => item.top <= offset + tolerance)
+      .sort((a, b) => b.top - a.top);
+
+    activeId.value = candidates[0]?.id ?? observed[0]?.id ?? "";
+  }
+
+  async function refresh() {
+    if (!import.meta.client) return;
+
+    await nextTick();
+    observed = toValue(ids)
+      .map((id) => document.getElementById(id))
+      .filter((element): element is HTMLElement => Boolean(element));
+
+    updateFromScroll();
+  }
+
+  onMounted(() => {
+    void refresh();
+    window.addEventListener("scroll", updateFromScroll, { passive: true });
+  });
+
+  onBeforeUnmount(() => {
+    observed = [];
+    if (import.meta.client) {
+      window.removeEventListener("scroll", updateFromScroll);
+    }
+  });
+
+  watch(
+    () => toValue(ids).join("|"),
+    () => {
+      void refresh();
+    },
+  );
+
+  return {
+    activeId,
+    refresh,
+  };
+}

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

@@ -0,0 +1,170 @@
+import type { ContentNavigationTreeItem } from "@lupinum/ginko-content/client";
+
+export type RawDocsTreeItem = Omit<ContentNavigationTreeItem, "children"> & {
+  icon?: unknown;
+  badge?: unknown;
+  sidebar?: unknown;
+  children?: RawDocsTreeItem[];
+};
+
+export type DocsNavigationItem = {
+  id: string;
+  title: string;
+  path?: string;
+  icon?: string;
+  badge?: string;
+  sidebar?: "section" | "group";
+  children: DocsNavigationItem[];
+};
+
+export type DocsNavigationSection = {
+  id: string;
+  title?: string;
+  path?: string;
+  icon?: string;
+  items: DocsNavigationItem[];
+};
+
+export type DocsNavigationGroup = {
+  id: string;
+  title?: string;
+  icon?: string;
+  items: DocsNavigationItem[];
+};
+
+function itemId(item: RawDocsTreeItem, position: string): string {
+  return item.path ?? `docs:${position}:${item.title}`;
+}
+
+export function normalizeDocsNavigationItem(
+  item: RawDocsTreeItem,
+  position: string | number = 0,
+): DocsNavigationItem {
+  const positionKey = String(position);
+  return {
+    id: itemId(item, positionKey),
+    title: item.title,
+    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,
+    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);
+  return (
+    (section.path !== undefined && normalizeDocsNavigationPath(section.path) === normalizedPath) ||
+    section.items.some((item) => docsNavigationItemContainsPath(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 [];
+}
+
+export function getDocsNavigationSections(items: DocsNavigationItem[]): DocsNavigationSection[] {
+  if (!items.some((item) => item.sidebar === "section")) {
+    return [{ id: "docs:main", items: [...items] }];
+  }
+
+  const sections: DocsNavigationSection[] = [];
+  let current: DocsNavigationSection | undefined;
+
+  for (const item of items) {
+    if (item.sidebar === "section") {
+      current = {
+        id: item.id,
+        title: item.title,
+        path: item.path,
+        icon: item.icon,
+        items: [...item.children],
+      };
+      sections.push(current);
+      continue;
+    }
+
+    if (!current) {
+      current = { id: "docs:main", items: [] };
+      sections.push(current);
+    }
+    current.items.push(item);
+  }
+
+  return sections;
+}
+
+export function getDocsNavigationGroups(section: DocsNavigationSection): DocsNavigationGroup[] {
+  const groups: DocsNavigationGroup[] = [];
+  const ungrouped: DocsNavigationItem[] = [];
+
+  if (section.path) {
+    ungrouped.push({
+      id: section.id,
+      title: section.title ?? "Overview",
+      path: section.path,
+      icon: section.icon,
+      children: [],
+    });
+  }
+
+  for (const child of section.items) {
+    if (child.sidebar !== "group") {
+      ungrouped.push(child);
+      continue;
+    }
+
+    const items = child.path
+      ? [
+          {
+            ...child,
+            children: [],
+          },
+          ...child.children,
+        ]
+      : child.children;
+
+    groups.push({
+      id: child.id,
+      title: child.title,
+      icon: child.icon,
+      items,
+    });
+  }
+
+  if (ungrouped.length) {
+    groups.unshift({
+      id: `${section.id}:main`,
+      items: ungrouped,
+    });
+  }
+
+  return groups.filter((group) => group.items.length > 0);
+}

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

@@ -0,0 +1,156 @@
+export type CommandCenterGroup = "recent" | "pages" | "docs_nav" | "blog" | "docs" | "actions";
+
+export interface CommandCenterItem {
+  id: string;
+  sourceId?: string;
+  title: string;
+  subtitle?: string;
+  href?: string;
+  external?: boolean;
+  group: CommandCenterGroup;
+  icon?: string;
+  keywords?: string[];
+  badge?: string;
+}
+
+export type StoredRecentItem = string;
+
+export interface CommandCenterGroupResult {
+  id: CommandCenterGroup;
+  title: string;
+  items: CommandCenterItem[];
+}
+
+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) => {
+    const key = item.href ?? item.sourceId ?? item.id;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+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);
+  }
+
+  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);
+}
+
+export function resolveRecentItems(
+  storedItems: StoredRecentItem[],
+  currentItems: CommandCenterItem[],
+): CommandCenterItem[] {
+  return storedItems
+    .map((id) => currentItems.find((item) => item.id === id))
+    .filter((item): item is CommandCenterItem => Boolean(item))
+    .slice(0, MAX_RECENT_ITEMS)
+    .map((item) => ({
+      ...item,
+      id: `recent-${item.id}`,
+      sourceId: item.id,
+      group: "recent",
+    }));
+}
+
+export function rememberRecentItem(
+  selectedItem: CommandCenterItem,
+  storedItems: StoredRecentItem[],
+): StoredRecentItem[] {
+  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";
+}