@lupinum/ginko-docs 0.4.0-rc.9 → 0.4.0

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

@@ -1,27 +0,0 @@
-<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,59 +0,0 @@
-<script setup lang="ts">
-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";
-
-const props = defineProps<{
-  sections: Array<DocsNavigationSection & { title: string }>;
-  activeId: string;
-}>();
-
-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>
-  <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,106 +0,0 @@
-<script setup lang="ts">
-import type { HTMLAttributes } from "vue";
-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";
-
-const props = withDefaults(
-  defineProps<{
-    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>
-  <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 border-l border-border pl-3">
-      <div
-        class="pointer-events-none absolute -left-px w-0.5 rounded-full bg-brand transition-all duration-200 ease-out"
-        :style="indicatorStyle"
-      />
-
-      <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-foreground'
-                  : 'text-muted-foreground hover:text-foreground',
-              )
-            "
-            @click.prevent="scrollToHeading(item.id)"
-          >
-            {{ item.label }}
-          </a>
-        </li>
-      </ul>
-    </div>
-  </nav>
-</template>

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

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

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

@@ -1,18 +0,0 @@
-import { computed } from "vue";
-import { navigation } from "@lupinum/ginko-content/client";
-import { useAsyncData, useI18n } from "#imports";
-
-// 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}`);
-
-  return useAsyncData(navigationKey, () =>
-    navigation("docs", {
-      locale: locale.value,
-      select: ["icon", "badge", "sidebar"],
-    }),
-  );
-}

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

@@ -1,58 +0,0 @@
-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 };
-}

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

@@ -1,135 +0,0 @@
-import {
-  nextTick,
-  onBeforeUnmount,
-  onMounted,
-  ref,
-  toValue,
-  watch,
-  type MaybeRefOrGetter,
-} from "vue";
-
-export type ScrollspyHeading = {
-  id: string;
-  /** Viewport-relative top, in document order. */
-  top: number;
-};
-
-export type ScrollspyZone = {
-  zoneTop: number;
-  zoneBottom: number;
-  /** Viewport-relative bottom of the document (scrollHeight - scrollY). */
-  docEnd: number;
-  /** When the page is scrolled to the very bottom, the zone extends to docEnd
-   * so a short final section still activates. */
-  atBottom: boolean;
-};
-
-// Headings use `scroll-margin-top: 7rem` (= ZONE_TOP), so after an anchor jump
-// the clicked heading sits exactly at the zone top and becomes the first
-// active entry. The tolerance absorbs sub-pixel layout drift.
-const ZONE_TOP = 112;
-const TOLERANCE = 8;
-
-/**
- * A heading is active while any part of its section (heading → next heading)
- * intersects the reading zone. Pure so the zone model is unit-testable.
- */
-export function computeActiveIds(headings: ScrollspyHeading[], zone: ScrollspyZone): string[] {
-  if (headings.length === 0) return [];
-
-  const zoneTop = zone.zoneTop + TOLERANCE;
-  const zoneBottom = zone.atBottom ? zone.docEnd : zone.zoneBottom;
-
-  const active: string[] = [];
-  for (let index = 0; index < headings.length; index++) {
-    const sectionTop = headings[index]!.top;
-    const sectionBottom = index < headings.length - 1 ? headings[index + 1]!.top : zone.docEnd;
-    if (sectionBottom > zoneTop && sectionTop < zoneBottom) {
-      active.push(headings[index]!.id);
-    }
-  }
-  if (active.length > 0) return active;
-
-  // No section in the zone (e.g. a long passage between headings): fall back
-  // to the last heading scrolled past the zone top, then to the first heading.
-  for (let index = headings.length - 1; index >= 0; index--) {
-    if (headings[index]!.top <= zoneTop) return [headings[index]!.id];
-  }
-  return [headings[0]!.id];
-}
-
-export function useScrollspy(ids: MaybeRefOrGetter<string[]>) {
-  const activeIds = ref<string[]>([]);
-  let observed: HTMLElement[] = [];
-  let rafId: number | null = null;
-
-  function update() {
-    const scrollY = window.scrollY;
-    const innerHeight = window.innerHeight;
-    const scrollHeight = document.documentElement.scrollHeight;
-    const next = computeActiveIds(
-      observed.map((element) => ({
-        id: element.id,
-        top: element.getBoundingClientRect().top,
-      })),
-      {
-        zoneTop: ZONE_TOP,
-        zoneBottom: innerHeight * 0.8,
-        docEnd: scrollHeight - scrollY,
-        atBottom: scrollY + innerHeight >= scrollHeight - 2,
-      },
-    );
-    if (
-      next.length !== activeIds.value.length ||
-      next.some((id, index) => id !== activeIds.value[index])
-    ) {
-      activeIds.value = next;
-    }
-  }
-
-  function scheduleUpdate() {
-    if (rafId !== null) return;
-    rafId = requestAnimationFrame(() => {
-      rafId = null;
-      update();
-    });
-  }
-
-  async function refresh() {
-    if (!import.meta.client) return;
-
-    await nextTick();
-    observed = toValue(ids)
-      .map((id) => document.getElementById(id))
-      .filter((element): element is HTMLElement => Boolean(element));
-
-    update();
-  }
-
-  onMounted(() => {
-    void refresh();
-    window.addEventListener("scroll", scheduleUpdate, { passive: true });
-    window.addEventListener("resize", scheduleUpdate, { passive: true });
-  });
-
-  onBeforeUnmount(() => {
-    observed = [];
-    if (import.meta.client) {
-      window.removeEventListener("scroll", scheduleUpdate);
-      window.removeEventListener("resize", scheduleUpdate);
-      if (rafId !== null) cancelAnimationFrame(rafId);
-    }
-  });
-
-  watch(
-    () => toValue(ids).join("|"),
-    () => {
-      void refresh();
-    },
-  );
-
-  return {
-    activeIds,
-    refresh,
-  };
-}

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

@@ -1,157 +0,0 @@
-import {
-  findFirstNavigationPage,
-  navigationItemContainsPath,
-  normalizeNavigationPath,
-  type ContentNavigationTreeItem,
-  type NavigationSidebar,
-} from "@lupinum/ginko-content/navigation";
-
-export type RawDocsTreeItem = Omit<ContentNavigationTreeItem, "children"> & {
-  icon?: unknown;
-  badge?: unknown;
-  children?: RawDocsTreeItem[];
-};
-
-export type DocsNavigationItem = {
-  id: string;
-  title: string;
-  path?: string;
-  icon?: string;
-  badge?: string;
-  sidebar?: NavigationSidebar;
-  children: DocsNavigationItem[];
-};
-
-export type DocsNavigationSection = {
-  id: string;
-  title?: string;
-  path?: string;
-  icon?: string;
-  items: DocsNavigationItem[];
-};
-
-export type DocsNavigationGroup = {
-  id: string;
-  title?: string;
-  icon?: string;
-  items: DocsNavigationItem[];
-};
-
-function itemId(item: RawDocsTreeItem, position: string): string {
-  return item.path ?? `docs:${position}:${item.title}`;
-}
-
-export function normalizeDocsNavigationItem(
-  item: RawDocsTreeItem,
-  position: string | number = 0,
-): DocsNavigationItem {
-  const positionKey = String(position);
-  return {
-    id: itemId(item, positionKey),
-    title: item.title,
-    path: item.path,
-    icon: typeof item.icon === "string" ? item.icon : undefined,
-    badge: typeof item.badge === "string" ? item.badge : undefined,
-    sidebar: item.sidebar,
-    children: (item.children ?? []).map((child, index) =>
-      normalizeDocsNavigationItem(child, `${positionKey}.${index}`),
-    ),
-  };
-}
-
-export function docsNavigationSectionContainsPath(
-  section: DocsNavigationSection,
-  path: string,
-): boolean {
-  const normalizedPath = normalizeNavigationPath(path);
-  return (
-    (section.path !== undefined && normalizeNavigationPath(section.path) === normalizedPath) ||
-    section.items.some((item) => navigationItemContainsPath(item, normalizedPath))
-  );
-}
-
-// Structural sections have no page of their own — they resolve to their first
-// navigable page so switching to them lands somewhere instead of only swapping
-// the sidebar contents.
-export function resolveDocsSectionTargetPath(section: DocsNavigationSection): string | undefined {
-  return section.path ?? findFirstNavigationPage(section.items)?.path;
-}
-
-export function getDocsNavigationSections(items: DocsNavigationItem[]): DocsNavigationSection[] {
-  if (!items.some((item) => item.sidebar === "section")) {
-    return [{ id: "docs:main", items: [...items] }];
-  }
-
-  const sections: DocsNavigationSection[] = [];
-  let current: DocsNavigationSection | undefined;
-
-  for (const item of items) {
-    if (item.sidebar === "section") {
-      current = {
-        id: item.id,
-        title: item.title,
-        path: item.path,
-        icon: item.icon,
-        items: [...item.children],
-      };
-      sections.push(current);
-      continue;
-    }
-
-    if (!current) {
-      current = { id: "docs:main", items: [] };
-      sections.push(current);
-    }
-    current.items.push(item);
-  }
-
-  return sections;
-}
-
-export function getDocsNavigationGroups(section: DocsNavigationSection): DocsNavigationGroup[] {
-  const groups: DocsNavigationGroup[] = [];
-  const ungrouped: DocsNavigationItem[] = [];
-
-  if (section.path) {
-    ungrouped.push({
-      id: section.id,
-      title: section.title ?? "Overview",
-      path: section.path,
-      icon: section.icon,
-      children: [],
-    });
-  }
-
-  for (const child of section.items) {
-    if (child.sidebar !== "group") {
-      ungrouped.push(child);
-      continue;
-    }
-
-    const items = child.path
-      ? [
-          {
-            ...child,
-            children: [],
-          },
-          ...child.children,
-        ]
-      : child.children;
-
-    groups.push({
-      id: child.id,
-      title: child.title,
-      icon: child.icon,
-      items,
-    });
-  }
-
-  if (ungrouped.length) {
-    groups.unshift({
-      id: `${section.id}:main`,
-      items: ungrouped,
-    });
-  }
-
-  return groups.filter((group) => group.items.length > 0);
-}

package/app/features/docs/toc-context.ts

@@ -1,6 +0,0 @@
-import type { ComputedRef, InjectionKey } from "vue";
-import type { FlatTocItem } from "#ginko-docs/utils/content";
-
-/** Current page TOC, provided by the docs page shell so in-content components
- * (e.g. the `::toc` inline table of contents) can render it. */
-export const docsTocKey: InjectionKey<ComputedRef<FlatTocItem[]>> = Symbol("ginko-docs-toc");