@lupinum/ginko-docs 0.2.2 → 0.2.5

package/app/composables/useSiteNavigation.ts

@@ -3,12 +3,12 @@ import { useI18n, useRouter } from "#imports";
 import { useLocalizedPath } from "#ginko-docs/composables/useLocalizedPath";
 import { computed } from "vue";
 import { useGinkoDocsConfig } from "./useGinkoDocsConfig";
-import { resolveBanner, resolveMainNav, type NavItem } from "./site-navigation.utils";
-
-export interface SidebarSection {
-  title: string;
-  items: { label: string; href: string; badge?: string }[];
-}
+import {
+  resolveBanner,
+  resolveMainNav,
+  resolveSocialLinks,
+  type NavItem,
+} from "./site-navigation.utils";
 
 export const useSiteNavigation = () => {
   const config = useGinkoDocsConfig();
@@ -32,34 +32,12 @@ export const useSiteNavigation = () => {
   const banner = computed(() =>
     resolveBanner(config.banner, {
       locale: locale.value,
-      blogPath: blogPath.value,
-      blogExists: blogExists.value,
       defaultText: t("banner.text"),
       defaultLinkLabel: t("banner.linkLabel"),
     }),
   );
 
-  const socialLinks = computed<NavItem[]>(
-    () =>
-      [
-        config.social.github
-          ? {
-              label: t("nav.github"),
-              href: config.social.github,
-              external: true,
-              icon: "lucide:github",
-            }
-          : null,
-        config.social.linkedin
-          ? {
-              label: "LinkedIn",
-              href: config.social.linkedin,
-              external: true,
-              icon: "lucide:linkedin",
-            }
-          : null,
-      ].filter(Boolean) as NavItem[],
-  );
+  const socialLinks = computed<NavItem[]>(() => resolveSocialLinks(config.social));
 
   const mainNav = computed<NavItem[]>(() =>
     resolveMainNav(config.nav.links, {
@@ -69,18 +47,10 @@ export const useSiteNavigation = () => {
       blogExists: blogExists.value,
       docsLabel: t("nav.documentation"),
       blogLabel: t("nav.blog"),
+      docsDescription: t("nav.docsDescription"),
+      blogDescription: t("nav.blogDescription"),
     }),
   );
 
-  const footerNav = computed<{
-    product: NavItem[];
-    resources: NavItem[];
-    company: NavItem[];
-  }>(() => ({
-    product: [],
-    resources: [...socialLinks.value],
-    company: [],
-  }));
-
-  return { site, banner, mainNav, footerNav, socialLinks };
+  return { site, banner, mainNav, socialLinks };
 };

package/app/config/site.utils.ts

@@ -2,7 +2,7 @@ import type { GinkoDocsLocalizedText } from "../../shared/types/app-config";
 import { defaultLocale, type LocaleCode } from "../../i18n/locales";
 
 export function getLocalizedSiteText(
-  value: GinkoDocsLocalizedText | string,
+  value: GinkoDocsLocalizedText,
   locale: string,
   fallbackLocale: LocaleCode = defaultLocale,
 ): string {

package/app/error.vue

@@ -4,7 +4,6 @@ import { messages } from "../i18n/messages/index";
 import { normalizeAppError } from "./lib/errors";
 import { computed } from "vue";
 import { clearError, useHead } from "#imports";
-import { useDocsEntryPath } from "#ginko-docs/features/docs/composables/useDocsEntryPath";
 import { localeFromPath, localizedPath } from "../i18n/locales";
 
 type NuxtErrorLike = {
@@ -29,8 +28,8 @@ const copy = computed(() => {
   const catalog = messages[locale.value].errors;
   return catalog[normalized.value.kind] ?? catalog.unavailable;
 });
-const docsPath = await useDocsEntryPath();
 const homePath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].home));
+const docsPath = computed(() => localizedPath(locale.value, localizedRoutes[locale.value].docs));
 const title = computed(() => `${normalized.value.statusCode} - ${copy.value.title}`);
 // Keep the full site chrome for content-level errors (404 and friends); hard
 // server failures fall back to the bare page so the error screen cannot crash.
@@ -59,9 +58,6 @@ const handleError = () => clearError({ redirect: homePath.value });
           {{ normalized.statusCode }}
         </p>
 
-        <p class="mb-3 text-sm font-medium tracking-wider text-primary uppercase">
-          {{ normalized.statusMessage }}
-        </p>
         <h1 class="mb-4 text-3xl font-semibold tracking-tight text-foreground sm:text-4xl">
           {{ copy.title }}
         </h1>

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

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { cn } from "#ginko-docs/utils";
+import { useI18n } from "#imports";
+
+const props = defineProps<{
+  items: { title: string; path?: string }[];
+  class?: HTMLAttributes["class"];
+}>();
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <nav
+    v-if="items.length"
+    :class="cn('flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground', props.class)"
+    :aria-label="t('docs.breadcrumbs')"
+  >
+    <template v-for="(item, index) in items" :key="item.path ?? item.title">
+      <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>
+</template>

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

@@ -2,12 +2,19 @@
 import type { GinkoDocsAppConfig } from "../../../../shared/types/app-config";
 import { computed } from "vue";
 import { useAppConfig, useI18n, useRoute } from "#imports";
+import { buildRepoEditUrl, buildRepoIssueUrl } from "#ginko-docs/utils/repository";
 
-const props = defineProps<{
-  stem?: string;
-  extension?: string;
-  title: string;
-}>();
+const props = withDefaults(
+  defineProps<{
+    stem?: string;
+    extension?: string;
+    title: string;
+    variant?: "article" | "rail";
+  }>(),
+  {
+    variant: "article",
+  },
+);
 
 const route = useRoute();
 const { t } = useI18n();
@@ -20,25 +27,28 @@ const sourcePath = computed(() => {
   return `${directory}/${props.stem}.${extension}`;
 });
 
-const editUrl = computed(() => {
-  if (!repository || !sourcePath.value) return null;
-  const branch = repository.branch || "main";
-  return `${repository.url.replace(/\/$/, "")}/edit/${encodeURIComponent(branch)}/${sourcePath.value}`;
-});
+const editUrl = computed(() =>
+  repository && sourcePath.value ? buildRepoEditUrl(repository, sourcePath.value) : null,
+);
 
-const issueUrl = computed(() => {
-  if (!repository) return null;
-  const url = new URL(`${repository.url.replace(/\/$/, "")}/issues/new`);
-  url.searchParams.set("title", t("docs.issueTitle", { title: props.title }));
-  url.searchParams.set("body", t("docs.issueBody", { path: route.path }));
-  return url.toString();
-});
+const issueUrl = computed(() =>
+  repository
+    ? buildRepoIssueUrl(repository, {
+        title: t("docs.issueTitle", { title: props.title }),
+        body: t("docs.issueBody", { path: route.path }),
+      })
+    : null,
+);
 </script>
 
 <template>
   <div
     v-if="repository"
-    class="mt-12 flex flex-wrap items-center gap-x-4 gap-y-2 border-t border-border pt-5 text-sm"
+    :class="
+      variant === 'rail'
+        ? 'flex flex-col gap-2.5 text-sm'
+        : 'flex flex-wrap items-center gap-x-4 gap-y-2 text-sm'
+    "
     :aria-label="t('docs.contribute')"
   >
     <a

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,38 @@
 <script setup lang="ts">
-import { createContentNotFoundError } from "#ginko-docs/lib/errors";
-import { filterTocByDepth, flattenTocLinks } from "#ginko-docs/utils/content";
+import {
+  filterTocByDepth,
+  flattenTocLinks,
+  formatContentDate,
+  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 +49,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 +79,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 +141,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 +154,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 +186,49 @@ 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">
+            <p v-if="page.updated" class="mb-4 text-sm text-muted-foreground">
+              {{ t("docs.lastUpdated") }}:
+              <time :datetime="page.updated">{{ formatContentDate(page.updated, locale) }}</time>
+            </p>
+            <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,38 @@ 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)]";
+// The reduced top padding only applies under the section switcher; without it
+// the scroll mask would fade into the first group label.
+const scrollViewportClass = computed(() =>
+  cn(
+    "size-full rounded-[inherit] p-4 overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,white_12px,white_calc(100%-12px),transparent)]",
+    switcherSections.value.length > 1 && "pt-2",
+  ),
+);
+
+// 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 +100,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 +122,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 +140,6 @@ const asideClass = computed(() =>
           />
         </template>
       </div>
-    </div>
+    </ScrollArea>
   </aside>
 </template>