@lupinum/ginko-docs 0.2.2 → 0.2.3

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

@@ -8,14 +8,14 @@ import {
   SheetTitle,
   SheetTrigger,
 } from "#ginko-docs/components/ui/sheet";
-import { cn } from "#ginko-docs/lib/utils";
-import type { TocItem } from "./DocsToc.vue";
+import { cn } from "#ginko-docs/utils";
+import type { FlatTocItem } from "#ginko-docs/utils/content";
 import DocsToc from "./DocsToc.vue";
 import { useI18n, useRoute } from "#imports";
 
 const props = defineProps<{
-  items: TocItem[];
-  activeId?: string;
+  items: FlatTocItem[];
+  activeIds?: string[];
   pageTitle?: string;
   class?: HTMLAttributes["class"];
 }>();
@@ -53,7 +53,7 @@ watch(
       <SheetTrigger as-child>
         <button
           type="button"
-          class="-ml-1 flex h-8 min-w-0 items-center gap-2 rounded-lg px-2 text-sm font-medium text-foreground transition-colors hover:bg-muted"
+          class="-ml-1 flex h-8 min-w-0 items-center gap-2 rounded-lg px-2 text-sm font-medium text-foreground transition-colors hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
           :aria-label="t('docs.pageNavigation')"
         >
           <Icon
@@ -65,7 +65,10 @@ watch(
         </button>
       </SheetTrigger>
 
-      <SheetContent side="left" class="flex w-[20rem] max-w-[86vw] flex-col gap-0 p-0">
+      <SheetContent
+        side="left"
+        class="flex w-[var(--docs-sidebar-width)] max-w-[85vw] flex-col gap-0 p-0"
+      >
         <div class="border-b border-border px-4 py-3">
           <SheetTitle class="text-sm font-semibold">{{ t("docs.label") }}</SheetTitle>
           <SheetDescription class="sr-only">{{ t("docs.pageNavigation") }}</SheetDescription>
@@ -79,7 +82,8 @@ watch(
     <Sheet v-if="items.length" v-model:open="tocOpen">
       <SheetTrigger as-child>
         <button
-          class="-mr-1 flex h-7 shrink-0 items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+          type="button"
+          class="-mr-1 flex h-7 shrink-0 items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
         >
           <Icon name="lucide:list" class="size-3.5" aria-hidden="true" />
           <span>{{ t("docs.toc") }}</span>
@@ -96,7 +100,7 @@ watch(
         </div>
 
         <div class="flex-1 overflow-y-auto px-6 py-5" @click="tocOpen = false">
-          <DocsToc :items="items" :active-id="activeId" :show-title="false" />
+          <DocsToc :items="items" :active-ids="activeIds" :show-title="false" />
         </div>
       </SheetContent>
     </Sheet>

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

@@ -1,23 +1,33 @@
 <script setup lang="ts">
-import { createContentNotFoundError } from "#ginko-docs/lib/errors";
-import { filterTocByDepth, flattenTocLinks } from "#ginko-docs/utils/content";
+import { filterTocByDepth, flattenTocLinks, getMarkdownTocLinks } from "#ginko-docs/utils/content";
 import ContentFeedback from "#ginko-docs/components/content/Feedback.vue";
+import DocsBreadcrumb from "./DocsBreadcrumb.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 { computed, provide, ref, watch } from "vue";
+import { docsTocKey } from "#ginko-docs/features/docs/toc-context";
+import {
+  createError,
+  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 { useRevealActive } from "#ginko-docs/features/docs/composables/useRevealActive";
 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";
+import { useContentRouteAlternates } from "#ginko-docs/composables/useContentRouteAlternates";
 
 type DocsNavLink = {
   path: string;
@@ -34,25 +44,26 @@ 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,
+const canonicalUrl = useCanonicalUrl();
+const { sync: syncContentRouteAlternates } = useContentRouteAlternates();
+const contentPageResult = useContentPage("docs", {
   fallback: true,
   surround: true,
 });
-if (!page.value) throw createContentNotFoundError();
+const docsNavigationResult = useDocsNavigation();
+const [{ page, previous, next: nextContent, error }, { trail }] = await Promise.all([
+  contentPageResult,
+  docsNavigationResult,
+]);
+if (error.value) throw error.value;
+if (!page.value) throw createError({ statusCode: 404, statusMessage: "Not Found" });
 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),
+  filterTocByDepth(flattenTocLinks(getMarkdownTocLinks(page.value?.body)), config.toc?.depth ?? 3),
 );
 const prev = computed(() => toDocsNavLink(previous.value));
 const next = computed(() => toDocsNavLink(nextContent.value));
@@ -63,12 +74,24 @@ const schemaBreadcrumbs = computed(() => [
     .filter((item) => item.path)
     .map((item) => ({ name: item.title, path: item.path! })),
 ]);
-const { activeId, refresh } = useScrollspy(computed(() => tocItems.value.map((item) => item.id)));
+provide(docsTocKey, tocItems);
+const { activeIds, refresh } = useScrollspy(computed(() => tocItems.value.map((item) => item.id)));
 
 watch(tocItems, () => {
   void refresh();
 });
 
+// Keep the active TOC region visible when a long TOC overflows the sticky
+// aside.
+const tocAside = ref<HTMLElement | null>(null);
+const { reveal: revealActiveTocLink } = useRevealActive(tocAside, "[data-toc-active]", {
+  topPad: 16,
+  bottomPad: 44,
+});
+watch(activeIds, () => {
+  requestAnimationFrame(revealActiveTocLink);
+});
+
 useSeoMeta({
   title: computed(() => `${pageTitle.value} - ${siteName.value}`),
   description: pageDescription,
@@ -113,6 +136,11 @@ useHead(() => ({
   link: [{ key: "canonical", rel: "canonical", href: canonicalUrl.value }],
   meta: [{ property: "og:type", content: "article" }],
 }));
+
+function scrollToTop() {
+  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  window.scrollTo({ top: 0, behavior: reducedMotion ? "auto" : "smooth" });
+}
 </script>
 
 <template>
@@ -121,45 +149,27 @@ useHead(() => ({
       <DocsMobileToc
         class="order-1"
         :items="tocItems"
-        :active-id="activeId"
+        :active-ids="activeIds"
         :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"
+        class="order-2 mx-auto w-full max-w-[72ch] 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>
+              <DocsBreadcrumb class="mb-2" :items="visibleTrail" />
               <h1
-                class="font-heading text-[2rem] leading-[1.15] font-semibold tracking-[-0.025em] text-balance text-foreground sm:text-[2.25rem]"
+                class="font-heading text-[27px] leading-[1.15] font-semibold tracking-[-0.02em] text-balance text-foreground"
               >
                 {{ page.title }}
               </h1>
-              <p v-if="page.description" class="mt-2 text-lg leading-7 text-muted-foreground">
+              <p
+                v-if="page.description"
+                class="mt-2 text-base leading-[1.55] text-muted-foreground"
+              >
                 {{ page.description }}
               </p>
             </div>
@@ -171,18 +181,45 @@ useHead(() => ({
             <ContentRenderer :value="page" />
           </div>
 
-          <DocsContributeLinks :stem="page.stem" :extension="page.extension" :title="pageTitle" />
-          <DocsPageNav :prev="prev" :next="next" />
-          <ContentFeedback :label="t('feedback.label')" />
+          <footer class="mt-12 border-t border-border pt-6">
+            <div class="flex flex-wrap items-center justify-between gap-x-6 gap-y-4">
+              <ContentFeedback :label="t('feedback.label')" />
+              <DocsContributeLinks
+                class="xl:hidden"
+                :stem="page.stem"
+                :extension="page.extension"
+                :title="pageTitle"
+              />
+            </div>
+            <DocsPageNav class="mt-8" :prev="prev" :next="next" />
+          </footer>
         </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"
+      ref="tocAside"
+      class="sticky top-[var(--site-header-height)] hidden h-[calc(100dvh-var(--site-header-height)-var(--site-banner-height,0px))] 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" />
+      <DocsToc class="mb-6" :items="tocItems" :active-ids="activeIds" />
+
+      <div class="mt-auto flex flex-col gap-2.5 border-t border-border/70 pt-5">
+        <DocsContributeLinks
+          variant="rail"
+          :stem="page?.stem"
+          :extension="page?.extension"
+          :title="pageTitle"
+        />
+        <button
+          type="button"
+          class="inline-flex items-center gap-1.5 self-start text-sm font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:rounded-sm focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+          @click="scrollToTop"
+        >
+          <Icon name="lucide:arrow-up" class="size-4" aria-hidden="true" />
+          {{ t("docs.backToTop") }}
+        </button>
+      </div>
     </aside>
   </div>
 </template>

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

@@ -11,7 +11,7 @@ const { t } = useI18n();
 <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"
+    class="grid grid-cols-1 gap-3 sm:grid-cols-2"
     :aria-label="t('docs.pageNavigation')"
   >
     <!-- Previous -->

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

@@ -1,17 +1,19 @@
 <script setup lang="ts">
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 import { useDocsNavigation } from "#ginko-docs/features/docs/composables/useDocsNavigation";
-import { findFirstNavigationPage } from "@lupinum/ginko-content/client";
 import {
   docsNavigationSectionContainsPath,
   getDocsNavigationGroups,
+  resolveDocsSectionTargetPath,
   type DocsNavigationSection,
 } from "#ginko-docs/features/docs/docs-navigation";
+import { ScrollArea } from "#ginko-docs/components/ui/scroll-area";
+import { useRevealActive } from "#ginko-docs/features/docs/composables/useRevealActive";
 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 { computed, nextTick, onMounted, ref, watch } from "vue";
 import { navigateTo, useAppConfig, useI18n, useRoute } from "#imports";
 
 const props = withDefaults(
@@ -54,16 +56,32 @@ watch(
 );
 
 function setActiveSection(id: string) {
+  // Re-selecting the active section must not navigate away from the current page.
+  if (id === activeSectionId.value) return;
   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;
+  const path = section ? resolveDocsSectionTargetPath(section) : undefined;
   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)]";
+  "size-full rounded-[inherit] p-4 pt-2 overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,white_12px,white_calc(100%-12px),transparent)]";
+
+// Deep links can land on an item far outside the visible band — center it
+// once on mount and on section switches.
+const scrollArea = ref<{ $el?: HTMLElement } | null>(null);
+
+const { reveal: revealActiveItem } = useRevealActive(
+  () => scrollArea.value?.$el?.querySelector<HTMLElement>("[data-slot='scroll-area-viewport']"),
+  "[data-active='true']",
+);
+
+onMounted(() => {
+  void nextTick(revealActiveItem);
+});
+watch(activeSectionId, () => {
+  void nextTick(revealActiveItem);
+});
 
 const asideClass = computed(() =>
   cn(
@@ -76,13 +94,7 @@ const asideClass = computed(() =>
 </script>
 
 <template>
-  <aside
-    data-hovered="false"
-    :data-variant="variant"
-    :id="variant === 'desktop' ? 'nd-sidebar' : undefined"
-    :aria-label="t('docs.label')"
-    :class="asideClass"
-  >
+  <aside :data-variant="variant" :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'"
@@ -104,15 +116,13 @@ const asideClass = computed(() =>
       />
     </div>
 
-    <div
-      :class="[scrollViewportClass, switcherSections.length > 1 ? 'pt-2' : 'pt-4']"
-      :data-switcher="switcherSections.length > 1"
-    >
+    <ScrollArea ref="scrollArea" class="min-h-0 flex-1" :viewport-class="scrollViewportClass">
       <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"
+            data-slot="docs-sidebar-group-title"
+            class="mt-5 mb-1.5 inline-flex items-center gap-2 px-2 text-[11px] font-semibold tracking-wider text-muted-foreground uppercase first:mt-0"
           >
             {{ group.title }}
           </p>
@@ -124,6 +134,6 @@ const asideClass = computed(() =>
           />
         </template>
       </div>
-    </div>
+    </ScrollArea>
   </aside>
 </template>

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

@@ -2,12 +2,18 @@
 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";
+  navigationItemContainsPath,
+  normalizeNavigationPath,
+} from "@lupinum/ginko-content/navigation";
+import type { DocsNavigationItem } from "#ginko-docs/features/docs/docs-navigation";
+import { Button } from "#ginko-docs/components/ui/button";
+import DocsSidebarRow from "./DocsSidebarRow.vue";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "#ginko-docs/components/ui/collapsible";
+import { cn } from "#ginko-docs/utils";
 
 defineOptions({
   name: "DocsSidebarItem",
@@ -21,44 +27,36 @@ const props = defineProps<{
 const route = useRoute();
 
 function itemIsExactActive(path: string, item: DocsNavigationItem): boolean {
-  return Boolean(
-    item.path && normalizeDocsNavigationPath(path) === normalizeDocsNavigationPath(item.path),
-  );
+  return Boolean(item.path && normalizeNavigationPath(path) === normalizeNavigationPath(item.path));
 }
 
 function folderShouldBeOpen(path: string, item: DocsNavigationItem): boolean {
-  return item.children.length > 0 && docsNavigationItemContainsPath(item, path);
+  return item.children.length > 0 && navigationItemContainsPath(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 steps = ["ps-[13px]", "ps-[25px]", "ps-[37px]"] as const;
+  return steps[Math.min(Math.max(props.depth - 1, 0), steps.length - 1)]!;
 });
 
+// Depth 0: compact pill rows. Depth > 0: each row carries the rail as its own
+// start border so the active segment recolors it — aligned by construction.
 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",
+    "group relative flex w-full flex-row items-center gap-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,
+    "data-[active=true]:bg-primary/10 data-[active=true]:text-primary data-[active=true]:font-medium data-[active=true]:hover:transition-colors",
+    props.depth === 0
+      ? "rounded-[7px] px-2 py-[5.5px] text-[13px]"
+      : cn(
+          "rounded-e-[7px] border-s border-border py-[5px] pe-2 text-[12.5px]",
+          "hover:border-s-muted-foreground/40",
+          "data-[active=true]:border-s-primary",
+          paddingClass.value,
+        ),
   ),
 );
 
@@ -73,82 +71,45 @@ watch(
   },
 );
 
-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-['']";
+// No gap between child rows: their start borders stack into one continuous
+// rail. Deeper levels indent via padding only, sharing the same rail.
+const contentRailClass = computed(() =>
+  props.depth === 0 ? "ms-[15.5px] mt-0.5 mb-1 flex flex-col" : "flex flex-col",
+);
 </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'"
-    >
+  <Collapsible v-if="item.children.length > 0" v-model:open="folderOpen" :unmount-on-hide="false">
+    <CollapsibleTrigger v-if="item.path" as-child>
       <NuxtLink
         :to="item.path"
+        :class="linkRowClass"
         :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"
+        :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>
+        <DocsSidebarRow :item="item" show-chevron />
       </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]"
+    </CollapsibleTrigger>
+    <CollapsibleTrigger v-else as-child>
+      <Button
+        variant="ghost"
+        :class="linkRowClass"
+        class="h-auto justify-start"
+        :data-active="isExactActive ? 'true' : 'false'"
       >
-        {{ 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">
+        <DocsSidebarRow :item="item" show-chevron />
+      </Button>
+    </CollapsibleTrigger>
+
+    <CollapsibleContent :class="contentRailClass">
       <DocsSidebarItem
         v-for="child in item.children"
         :key="child.path ?? child.title"
         :item="child"
         :depth="depth + 1"
       />
-    </div>
-  </div>
+    </CollapsibleContent>
+  </Collapsible>
   <NuxtLink
     v-else-if="item.path"
     :to="item.path"
@@ -156,14 +117,6 @@ const contentRailClass =
     :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>
+    <DocsSidebarRow :item="item" />
   </NuxtLink>
 </template>

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

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import type { DocsNavigationItem } from "#ginko-docs/features/docs/docs-navigation";
+import { Badge } from "#ginko-docs/components/ui/badge";
+
+defineProps<{
+  item: DocsNavigationItem;
+  showChevron?: boolean;
+}>();
+</script>
+
+<template>
+  <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-full px-1.5 py-0 text-[10px]"
+  >
+    {{ item.badge }}
+  </Badge>
+  <Icon
+    v-if="showChevron"
+    name="lucide:chevron-down"
+    class="ms-auto size-3.5 shrink-0 -rotate-90 text-muted-foreground/70 transition-transform duration-200 ease-out group-hover:text-muted-foreground group-data-[state=open]:rotate-0 group-data-[active=true]:text-primary/70 rtl:rotate-90"
+    aria-hidden="true"
+  />
+</template>