@lupinum/ginko-docs 0.2.2 → 0.2.5

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>

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

@@ -1,7 +1,12 @@
 <script setup lang="ts">
-import type { DocsNavigationSection } from "#ginko-docs/features/docs/docs-navigation";
+import { computed } from "vue";
+import {
+  resolveDocsSectionTargetPath,
+  type DocsNavigationSection,
+} from "#ginko-docs/features/docs/docs-navigation";
+import { Tabs, TabsList, TabsTrigger } from "#ginko-docs/components/ui/tabs";
 
-defineProps<{
+const props = defineProps<{
   sections: Array<DocsNavigationSection & { title: string }>;
   activeId: string;
 }>();
@@ -9,27 +14,46 @@ defineProps<{
 const emit = defineEmits<{
   "update:activeId": [id: string];
 }>();
+
+const tabs = computed(() =>
+  props.sections.map((section) => ({
+    id: section.id,
+    title: section.title,
+    target: resolveDocsSectionTargetPath(section),
+  })),
+);
+
+function onTabClick(id: string, event: MouseEvent) {
+  // Re-clicking the active section would otherwise navigate away from the
+  // current page to the section's first page.
+  if (id === props.activeId) event.preventDefault();
+}
 </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>
+  <Tabs :model-value="activeId" activation-mode="manual" data-slot="docs-sidebar-tabs">
+    <TabsList class="w-full">
+      <template v-for="tab in tabs" :key="tab.id">
+        <TabsTrigger v-if="tab.target" :value="tab.id" as-child>
+          <NuxtLink
+            :to="tab.target"
+            :title="tab.title"
+            class="min-w-0 flex-1 basis-0"
+            @click="onTabClick(tab.id, $event)"
+          >
+            <span class="truncate">{{ tab.title }}</span>
+          </NuxtLink>
+        </TabsTrigger>
+        <TabsTrigger
+          v-else
+          :value="tab.id"
+          :title="tab.title"
+          class="min-w-0 flex-1 basis-0"
+          @click="emit('update:activeId', tab.id)"
+        >
+          <span class="truncate">{{ tab.title }}</span>
+        </TabsTrigger>
+      </template>
+    </TabsList>
+  </Tabs>
 </template>

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

@@ -1,60 +1,106 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
-import { cn } from "#ginko-docs/lib/utils";
+import { nextTick, onMounted, ref, watch } from "vue";
+import { useEventListener } from "@vueuse/core";
+import { cn } from "#ginko-docs/utils";
+import type { FlatTocItem } from "#ginko-docs/utils/content";
 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;
+    items: FlatTocItem[];
+    activeIds?: string[];
     showTitle?: boolean;
     class?: HTMLAttributes["class"];
   }>(),
   {
     showTitle: true,
+    activeIds: () => [],
   },
 );
 const { t } = useI18n();
+
+// The sliding indicator spans the active rows. Measure the rendered rows
+// instead of assuming a fixed row height, so wrapped or restyled rows keep
+// the indicator aligned.
+const listRef = ref<HTMLElement | null>(null);
+const indicatorStyle = ref({ opacity: "0", top: "0px", height: "0px" });
+
+function measureIndicator() {
+  const list = listRef.value;
+  if (!list) return;
+  const active = list.querySelectorAll<HTMLElement>("[data-toc-active]");
+  const first = active[0];
+  const last = active[active.length - 1];
+  if (!first || !last) {
+    indicatorStyle.value = { ...indicatorStyle.value, opacity: "0" };
+    return;
+  }
+  indicatorStyle.value = {
+    opacity: "1",
+    top: `${first.offsetTop}px`,
+    height: `${last.offsetTop + last.offsetHeight - first.offsetTop}px`,
+  };
+}
+
+watch(
+  () => [props.activeIds, props.items],
+  () => nextTick(measureIndicator),
+  { deep: true },
+);
+onMounted(measureIndicator);
+useEventListener("resize", measureIndicator, { passive: true });
+
+function scrollToHeading(id: string) {
+  const element = document.getElementById(id);
+  if (!element) return;
+  // scrollIntoView ignores the global reduced-motion CSS override, so check
+  // explicitly. `scroll-margin-top` on headings handles the sticky offset.
+  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  element.scrollIntoView({ behavior: reducedMotion ? "auto" : "smooth", block: "start" });
+  // Sync the hash without router involvement — router-driven hash navigation
+  // would scroll-restore and fight the smooth scroll above.
+  history.replaceState(history.state, "", `#${encodeURIComponent(id)}`);
+}
 </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">
+  <nav v-if="items.length" :class="cn('w-full', props.class)" :aria-label="t('docs.toc')">
+    <h3
+      v-if="showTitle"
+      class="mb-4 flex items-center gap-2 text-xs font-semibold tracking-wider text-muted-foreground uppercase"
+    >
       <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="relative border-l border-border pl-3">
       <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;'
-        "
+        class="pointer-events-none absolute -left-px w-0.5 rounded-full bg-primary transition-all duration-200 ease-out"
+        :style="indicatorStyle"
       />
 
-      <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>
+      <ul ref="listRef" class="space-y-1">
+        <li v-for="item in items" :key="item.id">
+          <a
+            :href="`#${item.id}`"
+            :title="item.label"
+            :data-toc-active="activeIds.includes(item.id) ? 'true' : undefined"
+            class="block truncate rounded-sm py-0.5 text-[13px] leading-5 transition-colors focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+            :class="
+              cn(
+                item.depth === 3 ? 'pl-3' : (item.depth ?? 2) >= 4 ? 'pl-6' : '',
+                activeIds.includes(item.id)
+                  ? 'font-medium text-primary'
+                  : 'text-muted-foreground hover:text-foreground',
+              )
+            "
+            @click.prevent="scrollToHeading(item.id)"
+          >
+            {{ item.label }}
+          </a>
+        </li>
+      </ul>
     </div>
-  </div>
+  </nav>
 </template>

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

@@ -1,7 +1,7 @@
 import { computed } from "vue";
+import { findNavigationTrail } from "@lupinum/ginko-content/navigation";
 import { useRoute } from "#imports";
 import {
-  findDocsNavigationTrail,
   getDocsNavigationSections,
   normalizeDocsNavigationItem,
   type DocsNavigationSection,
@@ -20,7 +20,7 @@ export async function useDocsNavigation() {
     return getDocsNavigationSections(roots.value);
   });
 
-  const trail = computed(() => findDocsNavigationTrail(roots.value, route.path));
+  const trail = computed(() => findNavigationTrail(roots.value, route.path));
 
   return {
     sections,

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

@@ -2,7 +2,10 @@ import { computed } from "vue";
 import { navigation } from "@lupinum/ginko-content/client";
 import { useAsyncData, useI18n } from "#imports";
 
-export async function useDocsNavigationData() {
+// Sync on purpose: the returned AsyncData is itself awaitable, so async callers
+// still `await` it, while sync callers (e.g. the site header) read `data`
+// reactively without suspending.
+export function useDocsNavigationData() {
   const { locale } = useI18n();
   const navigationKey = computed(() => `docs-navigation:${locale.value}`);
 

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

@@ -0,0 +1,58 @@
+import type { Ref } from "vue";
+
+export interface RevealActiveOptions {
+  /** Band padding in px; the active element is left alone inside the band. */
+  topPad?: number;
+  bottomPad?: number;
+}
+
+export interface RevealMetrics {
+  scrollTop: number;
+  containerHeight: number;
+  /** Active element's offset from the container's visible top edge. */
+  activeTop: number;
+  activeHeight: number;
+  topPad: number;
+  bottomPad: number;
+}
+
+/** Returns the scrollTop that centers the active element, or null if it is
+ * already inside the visible band. */
+export function computeRevealScrollTop(metrics: RevealMetrics): number | null {
+  const { scrollTop, containerHeight, activeTop, activeHeight, topPad, bottomPad } = metrics;
+  const visible = activeTop >= topPad && activeTop + activeHeight <= containerHeight - bottomPad;
+  if (visible) return null;
+  return scrollTop + activeTop - containerHeight / 2 + activeHeight / 2;
+}
+
+/**
+ * Keeps the active element of an overflowing container visible by centering
+ * it when it drifts outside the visible band. Scrolling is instant on
+ * purpose: this is positioning, not motion, and must not compete with the
+ * page scroll. Callers decide when to schedule `reveal` (nextTick, rAF, …).
+ */
+export function useRevealActive(
+  container: Ref<HTMLElement | null> | (() => HTMLElement | null | undefined),
+  selector: string,
+  options: RevealActiveOptions = {},
+) {
+  function reveal() {
+    const el = typeof container === "function" ? container() : container.value;
+    if (!el || el.scrollHeight <= el.clientHeight) return;
+    const active = el.querySelector<HTMLElement>(selector);
+    if (!active) return;
+    const containerRect = el.getBoundingClientRect();
+    const activeRect = active.getBoundingClientRect();
+    const next = computeRevealScrollTop({
+      scrollTop: el.scrollTop,
+      containerHeight: el.clientHeight,
+      activeTop: activeRect.top - containerRect.top,
+      activeHeight: activeRect.height,
+      topPad: options.topPad ?? 8,
+      bottomPad: options.bottomPad ?? 8,
+    });
+    if (next !== null) el.scrollTop = next;
+  }
+
+  return { reveal };
+}