@lupinum/ginko-docs 0.2.2

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

@@ -0,0 +1,188 @@
+<script setup lang="ts">
+import { createContentNotFoundError } from "#ginko-docs/lib/errors";
+import { filterTocByDepth, flattenTocLinks } from "#ginko-docs/utils/content";
+import ContentFeedback from "#ginko-docs/components/content/Feedback.vue";
+import DocsMobileToc from "./DocsMobileToc.vue";
+import DocsPageNav from "./DocsPageNav.vue";
+import DocsToc from "./DocsToc.vue";
+import DocsContributeLinks from "./DocsContributeLinks.vue";
+import { computed, watch } from "vue";
+import { useAppConfig, useContentPage, useHead, useI18n, useRoute, useSeoMeta } from "#imports";
+import { useCanonicalUrl } from "#ginko-docs/composables/useCanonicalUrl";
+import { useGinkoOgImage } from "#ginko-docs/composables/useGinkoOgImage";
+import { useScrollspy } from "#ginko-docs/features/docs/composables/useScrollspy";
+import PageMarkdownCopy from "#ginko-docs/components/content/PageMarkdownCopy.vue";
+import { Separator } from "#ginko-docs/components/ui/separator";
+import { getLocalizedSiteText } from "#ginko-docs/config/site.utils";
+import { useSchemaJsonLd } from "#ginko-docs/composables/useSchemaJsonLd";
+import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
+import { useDocsNavigation } from "#ginko-docs/features/docs/composables/useDocsNavigation";
+import { syncContentRouteAlternates } from "#ginko-docs/composables/useContentRouteAlternates";
+
+type DocsNavLink = {
+  path: string;
+  title: string;
+};
+
+function toDocsNavLink(
+  item: { path?: string; title?: string } | null | undefined,
+): DocsNavLink | null {
+  return item?.path && item?.title ? { path: item.path, title: item.title } : null;
+}
+
+const { locale, t } = useI18n();
+const config = useAppConfig().ginkoDocs;
+const route = useRoute();
+const localizedPath = useLocalizedPath();
+const {
+  page,
+  previous,
+  next: nextContent,
+} = await useContentPage("docs", {
+  locale: () => locale.value,
+  fallback: true,
+  surround: true,
+});
+if (!page.value) throw createContentNotFoundError();
+syncContentRouteAlternates(page);
+const { trail } = await useDocsNavigation();
+
+const siteName = computed(() => getLocalizedSiteText(config.site.name, locale.value));
+const pageTitle = computed(() => page.value?.title ?? t("docs.fallbackTitle"));
+const pageDescription = computed(() => page.value?.description ?? t("docs.fallbackDescription"));
+const canonicalUrl = useCanonicalUrl();
+const tocItems = computed(() =>
+  filterTocByDepth(flattenTocLinks(page.value?.body?.toc?.links), config.toc?.depth ?? 3),
+);
+const prev = computed(() => toDocsNavLink(previous.value));
+const next = computed(() => toDocsNavLink(nextContent.value));
+const visibleTrail = computed(() => trail.value.slice(0, -1));
+const schemaBreadcrumbs = computed(() => [
+  { name: siteName.value, path: localizedPath("home") },
+  ...trail.value
+    .filter((item) => item.path)
+    .map((item) => ({ name: item.title, path: item.path! })),
+]);
+const { activeId, refresh } = useScrollspy(computed(() => tocItems.value.map((item) => item.id)));
+
+watch(tocItems, () => {
+  void refresh();
+});
+
+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 page title (no site-name suffix baked in).
+useGinkoOgImage({
+  title: pageTitle.value,
+  description: pageDescription.value,
+  locale: locale.value,
+});
+
+useSchemaJsonLd(() => [
+  {
+    "@type": "TechArticle",
+    headline: pageTitle.value,
+    description: pageDescription.value,
+    url: canonicalUrl.value,
+    inLanguage: locale.value,
+    dateModified: page.value?.updated,
+    isPartOf: { "@type": "WebSite", name: siteName.value, url: config.site.url },
+    publisher: { "@type": "Organization", name: siteName.value, url: config.site.url },
+  },
+  {
+    "@type": "BreadcrumbList",
+    itemListElement: schemaBreadcrumbs.value.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: new URL(item.path, config.site.url).toString(),
+    })),
+  },
+]);
+
+useHead(() => ({
+  link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
+  meta: [{ property: "og:type", content: "article" }],
+}));
+</script>
+
+<template>
+  <div class="flex min-w-0 flex-1 flex-col xl:flex-row">
+    <div class="flex min-w-0 flex-1 flex-col">
+      <DocsMobileToc
+        class="order-1"
+        :items="tocItems"
+        :active-id="activeId"
+        :page-title="pageTitle"
+      />
+
+      <main
+        id="main-content"
+        class="order-2 mx-auto w-full max-w-3xl flex-1 px-4 py-8 md:px-6 xl:py-14"
+      >
+        <article v-if="page">
+          <div class="flex items-start justify-between gap-4 sm:gap-6">
+            <div class="min-w-0">
+              <nav
+                v-if="visibleTrail.length"
+                class="mb-2 flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground"
+                :aria-label="t('docs.breadcrumbs')"
+              >
+                <template v-for="(item, index) in visibleTrail" :key="item.id">
+                  <Icon
+                    v-if="index > 0"
+                    name="lucide:chevron-right"
+                    class="size-3.5 text-border"
+                    aria-hidden="true"
+                  />
+                  <NuxtLink
+                    v-if="item.path"
+                    :to="item.path"
+                    class="rounded-sm transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {{ item.title }}
+                  </NuxtLink>
+                  <span v-else>{{ item.title }}</span>
+                </template>
+              </nav>
+              <h1
+                class="font-heading text-[2rem] leading-[1.15] font-semibold tracking-[-0.025em] text-balance text-foreground sm:text-[2.25rem]"
+              >
+                {{ page.title }}
+              </h1>
+              <p v-if="page.description" class="mt-2 text-lg leading-7 text-muted-foreground">
+                {{ page.description }}
+              </p>
+            </div>
+            <PageMarkdownCopy />
+          </div>
+          <Separator class="my-8" />
+
+          <div class="content-prose content-prose-docs">
+            <ContentRenderer :value="page" />
+          </div>
+
+          <DocsContributeLinks :stem="page.stem" :extension="page.extension" :title="pageTitle" />
+          <DocsPageNav :prev="prev" :next="next" />
+          <ContentFeedback :label="t('feedback.label')" />
+        </article>
+      </main>
+    </div>
+
+    <aside
+      class="sticky top-[var(--site-header-height)] hidden h-[calc(100vh-var(--site-header-height))] w-[var(--docs-toc-width)] shrink-0 flex-col overflow-y-auto pt-10 pr-4 pb-6 xl:flex"
+      :aria-label="t('docs.toc')"
+    >
+      <DocsToc :items="tocItems" :active-id="activeId" />
+    </aside>
+  </div>
+</template>

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

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+import { useI18n } from "#imports";
+
+defineProps<{
+  prev?: { path?: string; title?: string } | null;
+  next?: { path?: string; title?: string } | null;
+}>();
+const { t } = useI18n();
+</script>
+
+<template>
+  <nav
+    v-if="prev || next"
+    class="mt-12 grid grid-cols-1 gap-3 border-t border-border pt-8 sm:grid-cols-2"
+    :aria-label="t('docs.pageNavigation')"
+  >
+    <!-- Previous -->
+    <NuxtLink
+      v-if="prev"
+      :to="prev.path"
+      class="group flex min-h-20 flex-col gap-1.5 rounded-xl border border-border bg-card px-5 py-4 transition-[border-color,background-color] duration-200 hover:border-foreground/20 hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring sm:col-start-1"
+    >
+      <span
+        class="flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors group-hover:text-foreground"
+      >
+        <Icon
+          name="lucide:chevron-left"
+          class="size-3.5 transition-transform group-hover:-translate-x-0.5"
+          aria-hidden="true"
+        />
+        {{ t("docs.previous") }}
+      </span>
+      <span class="text-sm leading-snug font-semibold text-foreground">{{ prev.title }}</span>
+    </NuxtLink>
+    <div v-else class="hidden sm:block" />
+
+    <!-- Next -->
+    <NuxtLink
+      v-if="next"
+      :to="next.path"
+      class="group flex min-h-20 flex-col items-end gap-1.5 rounded-xl border border-border bg-card px-5 py-4 text-right transition-[border-color,background-color] duration-200 hover:border-foreground/20 hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring sm:col-start-2"
+    >
+      <span
+        class="flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors group-hover:text-foreground"
+      >
+        {{ t("docs.next") }}
+        <Icon
+          name="lucide:chevron-right"
+          class="size-3.5 transition-transform group-hover:translate-x-0.5"
+          aria-hidden="true"
+        />
+      </span>
+      <span class="text-sm leading-snug font-semibold text-foreground">{{ next.title }}</span>
+    </NuxtLink>
+    <div v-else class="hidden sm:block" />
+  </nav>
+</template>

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

@@ -0,0 +1,129 @@
+<script setup lang="ts">
+import { cn } from "#ginko-docs/lib/utils";
+import { useDocsNavigation } from "#ginko-docs/features/docs/composables/useDocsNavigation";
+import { findFirstNavigationPage } from "@lupinum/ginko-content/client";
+import {
+  docsNavigationSectionContainsPath,
+  getDocsNavigationGroups,
+  type DocsNavigationSection,
+} from "#ginko-docs/features/docs/docs-navigation";
+import DocsSidebarItem from "./DocsSidebarItem.vue";
+import DocsSidebarDropdown from "./DocsSidebarDropdown.vue";
+import DocsSidebarList from "./DocsSidebarList.vue";
+import DocsSidebarTabs from "./DocsSidebarTabs.vue";
+import { computed, ref, watch } from "vue";
+import { navigateTo, useAppConfig, useI18n, useRoute } from "#imports";
+
+const props = withDefaults(
+  defineProps<{
+    variant?: "desktop" | "drawer";
+  }>(),
+  {
+    variant: "desktop",
+  },
+);
+
+const { t } = useI18n();
+const route = useRoute();
+const sidebarSwitcher = useAppConfig().ginkoDocs.site.docsSidebarSwitcher;
+const { sections } = await useDocsNavigation();
+const switcherSections = computed(() =>
+  sections.value.filter((section): section is DocsNavigationSection & { title: string } =>
+    Boolean(section.title),
+  ),
+);
+const selectedSectionId = ref("");
+const routeSection = computed(() =>
+  sections.value.find((section) => docsNavigationSectionContainsPath(section, route.path)),
+);
+const activeSectionId = computed(
+  () => selectedSectionId.value || routeSection.value?.id || sections.value[0]?.id || "",
+);
+const activeSection = computed(
+  () => sections.value.find((section) => section.id === activeSectionId.value) ?? sections.value[0],
+);
+const groups = computed(() =>
+  activeSection.value ? getDocsNavigationGroups(activeSection.value) : [],
+);
+
+watch(
+  () => route.path,
+  () => {
+    selectedSectionId.value = "";
+  },
+);
+
+function setActiveSection(id: string) {
+  selectedSectionId.value = id;
+  const section = sections.value.find((entry) => entry.id === id);
+  // Structural sections have no page of their own — land on their first page
+  // instead of only swapping the sidebar contents.
+  const path = section?.path ?? findFirstNavigationPage(section?.items)?.path;
+  if (path) void navigateTo(path);
+}
+
+const scrollViewportClass =
+  "min-h-0 flex-1 overflow-y-auto px-4 pb-4 overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,white_12px,white_calc(100%-12px),transparent)]";
+
+const asideClass = computed(() =>
+  cn(
+    "flex h-full w-full flex-col text-sm transition-[border-color] duration-[250ms] ease-out *:w-full",
+    props.variant === "desktop"
+      ? "absolute inset-y-0 start-0 items-end border-e border-border"
+      : "relative min-h-0 items-stretch border-e-0",
+  ),
+);
+</script>
+
+<template>
+  <aside
+    data-hovered="false"
+    :data-variant="variant"
+    :id="variant === 'desktop' ? 'nd-sidebar' : undefined"
+    :aria-label="t('docs.label')"
+    :class="asideClass"
+  >
+    <div v-if="switcherSections.length > 1" class="flex flex-col gap-3 p-4 pb-2">
+      <DocsSidebarTabs
+        v-if="sidebarSwitcher === 'tabs'"
+        :sections="switcherSections"
+        :active-id="activeSectionId"
+        @update:active-id="setActiveSection"
+      />
+      <DocsSidebarDropdown
+        v-else-if="sidebarSwitcher === 'dropdown'"
+        :sections="switcherSections"
+        :active-id="activeSectionId"
+        @update:active-id="setActiveSection"
+      />
+      <DocsSidebarList
+        v-else
+        :sections="switcherSections"
+        :active-id="activeSectionId"
+        @update:active-id="setActiveSection"
+      />
+    </div>
+
+    <div
+      :class="[scrollViewportClass, switcherSections.length > 1 ? 'pt-2' : 'pt-4']"
+      :data-switcher="switcherSections.length > 1"
+    >
+      <div class="flex min-w-full flex-col gap-0.5">
+        <template v-for="group in groups" :key="group.id">
+          <p
+            v-if="group.title"
+            class="mt-6 mb-1 inline-flex items-center gap-2 px-2 text-sm font-semibold text-foreground first:mt-0"
+          >
+            {{ group.title }}
+          </p>
+          <DocsSidebarItem
+            v-for="item in group.items"
+            :key="item.path ?? item.title"
+            :item="item"
+            :depth="0"
+          />
+        </template>
+      </div>
+    </div>
+  </aside>
+</template>

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

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { DocsNavigationSection } from "#ginko-docs/features/docs/docs-navigation";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "#ginko-docs/components/ui/dropdown-menu";
+
+const defaultIcon = "lucide:book-open";
+
+const props = defineProps<{
+  sections: Array<DocsNavigationSection & { title: string }>;
+  activeId: string;
+}>();
+
+const emit = defineEmits<{
+  "update:activeId": [id: string];
+}>();
+
+const activeSection = computed(
+  () => props.sections.find((section) => section.id === props.activeId) ?? props.sections[0],
+);
+
+function selectSection(value: unknown) {
+  if (typeof value === "string") emit("update:activeId", value);
+}
+</script>
+
+<template>
+  <DropdownMenu v-if="activeSection">
+    <DropdownMenuTrigger as-child>
+      <button
+        type="button"
+        class="flex h-10 w-full items-center gap-2 rounded-lg border border-border bg-background px-3 text-start text-foreground transition-colors outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring"
+        data-slot="docs-sidebar-dropdown"
+      >
+        <Icon
+          :name="activeSection.icon ?? defaultIcon"
+          class="size-4 shrink-0"
+          aria-hidden="true"
+        />
+        <span class="min-w-0 flex-1 truncate text-sm font-medium">{{ activeSection.title }}</span>
+        <Icon
+          name="lucide:chevrons-up-down"
+          class="size-4 shrink-0 text-muted-foreground"
+          aria-hidden="true"
+        />
+      </button>
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="start" class="w-(--reka-dropdown-menu-trigger-width)">
+      <DropdownMenuRadioGroup :model-value="activeId" @update:model-value="selectSection">
+        <DropdownMenuRadioItem
+          v-for="section in sections"
+          :key="section.id"
+          :value="section.id"
+          class="gap-2"
+        >
+          <template #indicator-icon>
+            <Icon name="lucide:check" class="size-4" aria-hidden="true" />
+          </template>
+          <Icon :name="section.icon ?? defaultIcon" class="size-4 shrink-0" aria-hidden="true" />
+          <span class="truncate">{{ section.title }}</span>
+        </DropdownMenuRadioItem>
+      </DropdownMenuRadioGroup>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</template>

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

@@ -0,0 +1,169 @@
+<script setup lang="ts">
+import { computed, ref, watch } from "vue";
+import { useRoute } from "vue-router";
+import {
+  docsNavigationItemContainsPath,
+  normalizeDocsNavigationPath,
+  type DocsNavigationItem,
+} from "#ginko-docs/features/docs/docs-navigation";
+import { Badge } from "#ginko-docs/components/ui/badge";
+import { cn } from "#ginko-docs/lib/utils";
+
+defineOptions({
+  name: "DocsSidebarItem",
+});
+
+const props = defineProps<{
+  item: DocsNavigationItem;
+  depth: number;
+}>();
+
+const route = useRoute();
+
+function itemIsExactActive(path: string, item: DocsNavigationItem): boolean {
+  return Boolean(
+    item.path && normalizeDocsNavigationPath(path) === normalizeDocsNavigationPath(item.path),
+  );
+}
+
+function folderShouldBeOpen(path: string, item: DocsNavigationItem): boolean {
+  return item.children.length > 0 && docsNavigationItemContainsPath(item, path);
+}
+
+const isExactActive = computed(() => itemIsExactActive(route.path, props.item));
+
+const paddingClass = computed(() => {
+  const steps = ["ps-2", "ps-5", "ps-8", "ps-11"] as const;
+  return steps[Math.min(props.depth, steps.length - 1)]!;
+});
+
+const linkRowClass = computed(() =>
+  cn(
+    "group relative flex min-h-10 w-full flex-row items-center gap-2 rounded-lg px-2 py-2 text-start [overflow-wrap:anywhere] text-muted-foreground transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring",
+    "[&_svg]:size-4 [&_svg]:shrink-0",
+    "hover:bg-accent/50 hover:text-accent-foreground/80 hover:transition-none",
+    "data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-foreground data-[active=true]:hover:transition-colors",
+    props.depth > 0
+      ? "data-[active=true]:before:absolute data-[active=true]:before:inset-y-2.5 data-[active=true]:before:start-2.5 data-[active=true]:before:w-px data-[active=true]:before:bg-primary data-[active=true]:before:content-['']"
+      : undefined,
+    paddingClass.value,
+  ),
+);
+
+const splitFolderRowClass = computed(() =>
+  cn(
+    "group relative flex min-h-10 w-full flex-row items-center rounded-lg text-start [overflow-wrap:anywhere] text-muted-foreground transition-colors outline-none",
+    "hover:bg-accent/50 hover:text-accent-foreground/80 hover:transition-none",
+    "data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-foreground data-[active=true]:hover:transition-colors",
+    props.depth > 0
+      ? "data-[active=true]:before:absolute data-[active=true]:before:inset-y-2.5 data-[active=true]:before:start-2.5 data-[active=true]:before:w-px data-[active=true]:before:bg-primary data-[active=true]:before:content-['']"
+      : undefined,
+    paddingClass.value,
+  ),
+);
+
+const folderOpen = ref(folderShouldBeOpen(route.path, props.item));
+
+watch(
+  () => route.path,
+  () => {
+    if (folderShouldBeOpen(route.path, props.item)) {
+      folderOpen.value = true;
+    }
+  },
+);
+
+const contentRailClass =
+  "relative flex flex-col gap-0.5 *:first:mt-0.5 before:absolute before:start-2.5 before:inset-y-1 before:w-px before:bg-border before:content-['']";
+</script>
+
+<template>
+  <div v-if="item.children.length > 0" :data-state="folderOpen ? 'open' : 'closed'">
+    <div
+      v-if="item.path"
+      :class="splitFolderRowClass"
+      :data-active="isExactActive ? 'true' : 'false'"
+    >
+      <NuxtLink
+        :to="item.path"
+        :aria-current="isExactActive ? 'page' : undefined"
+        class="flex min-w-0 flex-1 items-center gap-2 rounded-s-lg py-2 pe-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        data-slot="docs-sidebar-folder-link"
+      >
+        <Icon v-if="item.icon" :name="item.icon" class="size-4 shrink-0" aria-hidden="true" />
+        <span class="min-w-0 truncate">{{ item.title }}</span>
+        <Badge
+          v-if="item.badge"
+          variant="secondary"
+          class="ms-auto h-4 shrink-0 rounded-sm px-1.5 py-0 text-[10px]"
+        >
+          {{ item.badge }}
+        </Badge>
+      </NuxtLink>
+      <button
+        class="group flex size-10 shrink-0 items-center justify-center rounded-e-lg transition-colors outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring"
+        data-slot="docs-sidebar-folder-toggle"
+        type="button"
+        :aria-expanded="folderOpen"
+        :data-state="folderOpen ? 'open' : 'closed'"
+        @click="folderOpen = !folderOpen"
+      >
+        <Icon
+          name="lucide:chevron-down"
+          class="size-4 shrink-0 -rotate-90 transition-transform duration-200 group-data-[state=open]:rotate-0 rtl:rotate-90"
+          aria-hidden="true"
+        />
+        <span class="sr-only">{{ item.title }}</span>
+      </button>
+    </div>
+    <button
+      v-else
+      :class="linkRowClass"
+      :data-active="isExactActive ? 'true' : 'false'"
+      :data-state="folderOpen ? 'open' : 'closed'"
+      :aria-expanded="folderOpen"
+      type="button"
+      @click="folderOpen = !folderOpen"
+    >
+      <Icon v-if="item.icon" :name="item.icon" class="size-4 shrink-0" aria-hidden="true" />
+      <span class="min-w-0 truncate">{{ item.title }}</span>
+      <Badge
+        v-if="item.badge"
+        variant="secondary"
+        class="ms-auto h-4 shrink-0 rounded-sm px-1.5 py-0 text-[10px]"
+      >
+        {{ item.badge }}
+      </Badge>
+      <Icon
+        name="lucide:chevron-down"
+        class="ms-auto size-4 shrink-0 -rotate-90 transition-transform duration-200 group-data-[state=open]:rotate-0 rtl:rotate-90"
+        aria-hidden="true"
+      />
+    </button>
+    <div v-show="folderOpen" :class="contentRailClass">
+      <DocsSidebarItem
+        v-for="child in item.children"
+        :key="child.path ?? child.title"
+        :item="child"
+        :depth="depth + 1"
+      />
+    </div>
+  </div>
+  <NuxtLink
+    v-else-if="item.path"
+    :to="item.path"
+    :aria-current="isExactActive ? 'page' : undefined"
+    :class="linkRowClass"
+    :data-active="isExactActive ? 'true' : 'false'"
+  >
+    <Icon v-if="item.icon" :name="item.icon" class="size-4 shrink-0" aria-hidden="true" />
+    <span class="min-w-0 truncate">{{ item.title }}</span>
+    <Badge
+      v-if="item.badge"
+      variant="secondary"
+      class="ms-auto h-4 shrink-0 rounded-sm px-1.5 py-0 text-[10px]"
+    >
+      {{ item.badge }}
+    </Badge>
+  </NuxtLink>
+</template>

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

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import type { DocsNavigationSection } from "#ginko-docs/features/docs/docs-navigation";
+
+const defaultIcon = "lucide:book-open";
+
+defineProps<{
+  sections: Array<DocsNavigationSection & { title: string }>;
+  activeId: string;
+}>();
+
+const emit = defineEmits<{
+  "update:activeId": [id: string];
+}>();
+</script>
+
+<template>
+  <ul class="flex flex-col gap-0.5" data-slot="docs-sidebar-list">
+    <li v-for="section in sections" :key="section.id">
+      <button
+        type="button"
+        class="flex min-h-9 w-full items-center gap-2 rounded-lg px-2 text-start text-sm transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        :class="
+          activeId === section.id
+            ? 'bg-accent font-medium text-foreground'
+            : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground'
+        "
+        :aria-pressed="activeId === section.id"
+        @click="emit('update:activeId', section.id)"
+      >
+        <Icon :name="section.icon ?? defaultIcon" class="size-4 shrink-0" aria-hidden="true" />
+        <span class="truncate">{{ section.title }}</span>
+      </button>
+    </li>
+  </ul>
+</template>

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

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import type { DocsNavigationSection } from "#ginko-docs/features/docs/docs-navigation";
+
+defineProps<{
+  sections: Array<DocsNavigationSection & { title: string }>;
+  activeId: string;
+}>();
+
+const emit = defineEmits<{
+  "update:activeId": [id: string];
+}>();
+</script>
+
+<template>
+  <div
+    class="inline-flex h-9 w-full items-center justify-center overflow-hidden rounded-lg bg-muted p-[3px] text-muted-foreground"
+    role="tablist"
+    aria-orientation="horizontal"
+    data-slot="docs-sidebar-tabs"
+  >
+    <button
+      v-for="section in sections"
+      :key="section.id"
+      type="button"
+      role="tab"
+      :title="section.title"
+      :aria-selected="activeId === section.id"
+      :data-state="activeId === section.id ? 'active' : 'inactive'"
+      class="inline-flex h-[calc(100%-1px)] min-w-0 flex-1 basis-0 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap text-foreground transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring data-[state=active]:bg-background data-[state=active]:shadow-sm dark:text-muted-foreground dark:data-[state=active]:border-input dark:data-[state=active]:bg-input/30 dark:data-[state=active]:text-foreground"
+      @click="emit('update:activeId', section.id)"
+    >
+      {{ section.title }}
+    </button>
+  </div>
+</template>