@baybreezy/docd 0.0.1

package/app/composables/useScrollspy.ts

@@ -0,0 +1,327 @@
+type TargetLike =
+  | HTMLElement
+  | Window
+  | Document
+  | null
+  | undefined
+  | MaybeRefOrGetter<HTMLElement | Window | Document | null | undefined>;
+
+type AnchorRecord = {
+  anchor: HTMLElement;
+  section: HTMLElement;
+  sectionId: string;
+  offset: number;
+};
+
+export interface UseScrollspyOptions {
+  /** Container that actually scrolls (ref or element). Omit to use `window`. */
+  target?: TargetLike;
+  /** Element containing the ANCHORS (ref or element). If omitted, use the returned `root` ref. */
+  root?: HTMLElement | null | Ref<HTMLElement | null | undefined>;
+  /** Base data-* name -> anchors should have `data-[name]-anchor="sectionId"`. */
+  dataAttribute?: string;
+  /** Default offset from top (px) when computing active section / scrolling. */
+  offset?: number;
+  /** Smooth scroll on click. */
+  smooth?: boolean;
+  /** Update URL hash as active section changes. */
+  history?: boolean;
+  /** Throttle time (ms) for scroll handler. */
+  throttleTime?: number;
+  /** Whether to mark only the current section or every visible section as active. */
+  mode?: "single" | "multiple";
+  /** Optional callback when active id changes (you can also watch `activeId`). */
+  onChange?: (id: string) => void;
+}
+
+export function useScrollspy(options: UseScrollspyOptions = {}) {
+  const {
+    target,
+    root: rootOpt,
+    dataAttribute = "scrollspy",
+    offset = 0,
+    smooth = true,
+    history = true,
+    throttleTime = 50,
+    mode = "single",
+    onChange,
+  } = options;
+
+  // Anchors live inside this container; use returned `root` if none passed
+  const root = (rootOpt ?? ref<HTMLElement | null>(null)) as Ref<HTMLElement | null>;
+  const anchors = shallowRef<HTMLElement[]>([]);
+  const activeId = ref<string | null>(null);
+  const activeIds = ref<string[]>([]);
+  const prevId = ref<string | null>(null);
+
+  // --- Resolve the scroller (window by default) ---
+  const scroller = shallowRef<Window | HTMLElement | null>(null);
+
+  function sectionTopWithinScroller(sectionEl: HTMLElement): number {
+    const se = scroller.value;
+    const rect = sectionEl.getBoundingClientRect();
+    if (!se || se === window) {
+      return rect.top + (window.scrollY || document.documentElement.scrollTop);
+    }
+
+    const scRect = se.getBoundingClientRect();
+    return rect.top - scRect.top + se.scrollTop;
+  }
+
+  function resolveScroller() {
+    const t = unrefElement(target as any);
+    if (!t || t === window || t === document) {
+      scroller.value = window;
+    } else if (t instanceof HTMLElement) {
+      scroller.value = t;
+    } else {
+      scroller.value = window;
+    }
+  }
+
+  onMounted(resolveScroller);
+  watch(() => unrefElement(target as any), resolveScroller, { immediate: true });
+
+  // --- Discover anchors inside `root` and keep updated on DOM changes ---
+  function queryAnchors() {
+    anchors.value = root.value
+      ? Array.from(root.value.querySelectorAll<HTMLElement>(`[data-${dataAttribute}-anchor]`))
+      : [];
+    // After any DOM change that updates anchors (e.g. route-driven re-render),
+    // recompute the active section without waiting for a scroll event.
+    void nextTick(() => handleScroll());
+  }
+  onMounted(queryAnchors);
+  useMutationObserver(root, queryAnchors, { childList: true, subtree: true });
+
+  // Helpers for scroll metrics
+  function getScrollTop(se: Window | HTMLElement | null) {
+    if (!se || se === window) {
+      return window.scrollY || document.documentElement.scrollTop;
+    }
+
+    return se.scrollTop;
+  }
+
+  function getScrollHeight(se: Window | HTMLElement | null) {
+    if (!se || se === window) {
+      return document.documentElement.scrollHeight;
+    }
+
+    return se.scrollHeight;
+  }
+
+  function getClientHeight(se: Window | HTMLElement | null) {
+    if (!se || se === window) {
+      return window.innerHeight;
+    }
+
+    return se.clientHeight;
+  }
+
+  function getViewportBounds(customOffset: number) {
+    const se = scroller.value;
+    if (!se || se === window) {
+      return {
+        top: customOffset,
+        bottom: window.innerHeight,
+      };
+    }
+
+    const rect = se.getBoundingClientRect();
+
+    return {
+      top: rect.top + customOffset,
+      bottom: rect.bottom,
+    };
+  }
+
+  function getAnchorRecords() {
+    return anchors.value.reduce<AnchorRecord[]>((records, anchor) => {
+      const sectionId =
+        anchor.getAttribute(`data-${dataAttribute}-anchor`)?.replace("#", "") || null;
+      if (!sectionId) return records;
+
+      const section = document.getElementById(sectionId);
+      if (!section) return records;
+
+      let customOffset = offset;
+      const dataOffset = anchor.getAttribute(`data-${dataAttribute}-offset`);
+      if (dataOffset) customOffset = parseInt(dataOffset, 10);
+
+      records.push({
+        anchor,
+        section,
+        sectionId,
+        offset: customOffset,
+      });
+
+      return records;
+    }, []);
+  }
+
+  // --- Core: compute active anchor on scroll ---
+  function setActive(nextActiveIds: string[], sectionId: string | null, force = false) {
+    const activeIdSet = new Set(nextActiveIds);
+
+    anchors.value.forEach((anchor) => {
+      const id = anchor.getAttribute(`data-${dataAttribute}-anchor`)?.replace("#", "") || null;
+      if (id && activeIdSet.has(id)) anchor.setAttribute("data-active", "true");
+      else anchor.removeAttribute("data-active");
+    });
+
+    activeIds.value = nextActiveIds;
+    activeId.value = sectionId;
+
+    if (sectionId && history && (force || prevId.value !== sectionId)) {
+      window.history.replaceState({}, "", `#${sectionId}`);
+    }
+
+    if (sectionId && prevId.value !== sectionId) {
+      onChange?.(sectionId);
+      prevId.value = sectionId;
+    }
+  }
+
+  function handleScroll() {
+    if (!anchors.value.length) {
+      setActive([], null);
+      return;
+    }
+
+    const se = scroller.value;
+    const scrollTop = getScrollTop(se);
+    const records = getAnchorRecords();
+    if (!records.length) {
+      setActive([], null);
+      return;
+    }
+
+    let activeIdx = 0;
+    let minDelta = Infinity;
+
+    records.forEach((record, idx) => {
+      const top = sectionTopWithinScroller(record.section) - record.offset;
+      const delta = Math.abs(top - scrollTop);
+
+      if (top <= scrollTop && delta < minDelta) {
+        minDelta = delta;
+        activeIdx = idx;
+      }
+    });
+
+    // At bottom → force last anchor active
+    const atBottom = scrollTop + getClientHeight(se) >= getScrollHeight(se) - 2;
+    if (atBottom) activeIdx = records.length - 1;
+
+    const currentId = records[activeIdx]?.sectionId || null;
+    const nextActiveIds =
+      mode === "multiple"
+        ? records
+            .filter((record) => {
+              const rect = record.section.getBoundingClientRect();
+              const viewport = getViewportBounds(record.offset);
+              return rect.bottom > viewport.top && rect.top < viewport.bottom;
+            })
+            .map((record) => record.sectionId)
+        : currentId
+          ? [currentId]
+          : [];
+
+    setActive(nextActiveIds, currentId);
+  }
+
+  const onScroll = throttleTime
+    ? useThrottleFn(handleScroll, throttleTime, true, false)
+    : handleScroll;
+
+  // Rebind when scroller changes
+  useEventListener(scroller, "scroll", onScroll, { passive: true });
+
+  // --- Click to scroll ---
+  function scrollTo(
+    idOrEl: string | HTMLElement,
+    behavior: ScrollBehavior = smooth ? "smooth" : "auto"
+  ) {
+    let anchorEl: HTMLElement | null = null;
+    let sectionId: string | null = null;
+
+    if (typeof idOrEl === "string") {
+      sectionId = idOrEl;
+      anchorEl =
+        anchors.value.find((a) => a.getAttribute(`data-${dataAttribute}-anchor`) === idOrEl) ||
+        anchors.value.find(
+          (a) => a.getAttribute(`data-${dataAttribute}-anchor`) === `#${idOrEl}`
+        ) ||
+        null;
+    } else {
+      anchorEl = idOrEl;
+      sectionId = anchorEl.getAttribute(`data-${dataAttribute}-anchor`)?.replace("#", "") || null;
+    }
+    if (!sectionId) return;
+
+    const sectionEl = document.getElementById(sectionId);
+    if (!sectionEl) return;
+
+    let customOffset = offset;
+    const dataOffset = anchorEl?.getAttribute?.(`data-${dataAttribute}-offset`);
+    if (dataOffset) customOffset = parseInt(dataOffset, 10);
+
+    const top = sectionTopWithinScroller(sectionEl) - customOffset;
+    const se = scroller.value ?? window;
+
+    if ("scrollTo" in se) {
+      (se as Window | HTMLElement).scrollTo({ top, left: 0, behavior });
+    } else {
+      window.scrollTo({ top, left: 0, behavior });
+    }
+    setActive([sectionId], sectionId, true);
+  }
+
+  // Bind click listeners to anchors and auto-clean when the list changes
+  watch(
+    anchors,
+    (list, _old, onCleanup) => {
+      const stops: Array<() => void> = [];
+      list.forEach((el) => {
+        stops.push(
+          useEventListener(el, "click", (e) => {
+            e.preventDefault();
+            scrollTo(el as HTMLElement);
+          })
+        );
+      });
+      onCleanup(() => stops.forEach((s) => s()));
+    },
+    { immediate: true }
+  );
+
+  // Initial sync after mount
+  onMounted(() => {
+    // If URL has a hash, scroll there
+    const raw = window.location.hash.replace("#", "");
+    if (raw) {
+      const safe = window.CSS && "escape" in window.CSS ? (window.CSS as any).escape(raw) : raw;
+      const targetAnchor = root.value?.querySelector(
+        `[data-${dataAttribute}-anchor="${safe}"], [data-${dataAttribute}-anchor="#${safe}"]`
+      ) as HTMLElement | null;
+      if (targetAnchor) scrollTo(targetAnchor, "auto");
+    }
+    // Compute initial active anchor after layout has settled (double-RAF is more
+    // reliable than a fixed timeout because it waits for two full paint frames).
+    requestAnimationFrame(() => requestAnimationFrame(() => handleScroll()));
+  });
+
+  return {
+    /** Container that holds the anchors (use this if you didn't pass `root`) */
+    root,
+    /** Currently active section id */
+    activeId,
+    /** Currently active section ids */
+    activeIds,
+    /** Programmatically scroll to a section id or anchor element */
+    scrollTo,
+    /** Force recompute (e.g., after dynamic layout changes) */
+    recompute: () => handleScroll(),
+  };
+}

package/app/composables/useSeo.ts

@@ -0,0 +1,240 @@
+import type { ContentNavigationItem } from "@nuxt/content";
+import { joinURL, withoutTrailingSlash } from "ufo";
+import type { MaybeRefOrGetter } from "vue";
+
+export interface BreadcrumbItem {
+  title: string;
+  path: string;
+}
+
+/**
+ * Find breadcrumb path to a page in the navigation tree
+ */
+export function findPageBreadcrumbs(
+  navigation: ContentNavigationItem[] | undefined,
+  path: string,
+  currentPath: BreadcrumbItem[] = []
+): BreadcrumbItem[] | undefined {
+  if (!navigation) return undefined;
+
+  for (const item of navigation) {
+    const itemPath = [...currentPath, { title: item.title, path: item.path }];
+
+    if (item.path === path) {
+      return itemPath;
+    }
+
+    if (item.children) {
+      const found = findPageBreadcrumbs(item.children, path, itemPath);
+      if (found) return found;
+    }
+  }
+
+  return undefined;
+}
+
+export interface UseSeoOptions {
+  /**
+   * Page title
+   */
+  title: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Page description
+   */
+  description: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Page type for og:type (default: 'article' for docs, 'website' for landing)
+   */
+  type?: MaybeRefOrGetter<"website" | "article">;
+  /**
+   * Custom OG image URL (absolute)
+   */
+  ogImage?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Published date for article schema
+   */
+  publishedAt?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Modified date for article schema
+   */
+  modifiedAt?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * Breadcrumb items for BreadcrumbList schema
+   */
+  breadcrumbs?: MaybeRefOrGetter<BreadcrumbItem[] | undefined>;
+  /**
+   * Language for the page
+   */
+  lang?: MaybeRefOrGetter<string | undefined>;
+}
+
+/**
+ * Composable for comprehensive SEO setup including:
+ * - Meta tags (title, description, og:*, twitter:*)
+ * - Canonical URLs
+ * - Hreflang tags for i18n
+ * - JSON-LD structured data
+ */
+export function useSeo(options: UseSeoOptions) {
+  const route = useRoute();
+  const site = useSiteConfig();
+  const { logo } = useDocd();
+  const title = computed(() => toValue(options.title));
+  const description = computed(() => toValue(options.description));
+  const type = computed(() => toValue(options.type) || "article");
+  const ogImage = computed(() => toValue(options.ogImage));
+  const publishedAt = computed(() => toValue(options.publishedAt));
+  const modifiedAt = computed(() => toValue(options.modifiedAt));
+  const breadcrumbs = computed(() => toValue(options.breadcrumbs));
+  const lang = computed(() => toValue(options.lang) || site.language || "en");
+
+  // Build canonical URL
+  const canonicalUrl = computed(() => {
+    if (!site.url) return undefined;
+    return joinURL(site.url, route.path);
+  });
+
+  // Base URL for building other URLs
+  const baseUrl = computed(() => (site.url ? withoutTrailingSlash(site.url) : ""));
+
+  // Set meta tags
+  useSeoMeta({
+    title,
+    description,
+    ogTitle: title,
+    ogDescription: description,
+    ogType: type,
+    ogUrl: canonicalUrl,
+    twitterTitle: title,
+    twitterDescription: description,
+    twitterCard: "summary_large_image",
+  });
+
+  // Set canonical link
+  useHead({
+    link: computed(() => {
+      const links: Array<{ rel: string; href?: string; hreflang?: string }> = [];
+
+      // Canonical URL
+      if (canonicalUrl.value) {
+        links.push({
+          rel: "canonical",
+          href: canonicalUrl.value,
+        });
+      }
+
+      // Logo favicon as icon
+      if (logo.value?.favicon) {
+        links.push({
+          rel: "icon",
+          href: logo.value.favicon,
+        });
+      } else if (logo.value?.light) {
+        links.push({
+          rel: "icon",
+          href: logo.value.light,
+        });
+      } else if (logo.value?.dark) {
+        links.push({
+          rel: "icon",
+          href: logo.value.dark,
+        });
+      }
+
+      return links;
+    }),
+  });
+
+  // Custom OG image handling
+  if (ogImage.value) {
+    useSeoMeta({
+      ogImage: ogImage.value,
+      twitterImage: ogImage.value,
+      twitterCard: "summary_large_image",
+    });
+  }
+
+  // JSON-LD structured data
+  useHead({
+    htmlAttrs: { lang },
+    script: computed(() => {
+      const scripts: Array<{ type: string; innerHTML: string }> = [];
+
+      if (!baseUrl.value || !title.value) return scripts;
+
+      const pageUrl = joinURL(baseUrl.value, route.path);
+
+      // Article schema for documentation pages
+      if (type.value === "article") {
+        const articleSchema: Record<string, unknown> = {
+          "@context": "https://schema.org",
+          "@type": "Article",
+          headline: title.value,
+          description: description.value,
+          url: pageUrl,
+          mainEntityOfPage: {
+            "@type": "WebPage",
+            "@id": pageUrl,
+          },
+        };
+
+        if (publishedAt.value) {
+          articleSchema.datePublished = publishedAt.value;
+        }
+
+        if (modifiedAt.value) {
+          articleSchema.dateModified = modifiedAt.value;
+        }
+
+        if (site.name) {
+          articleSchema.publisher = {
+            "@type": "Organization",
+            name: site.name,
+          };
+        }
+
+        scripts.push({
+          type: "application/ld+json",
+          innerHTML: JSON.stringify(articleSchema),
+        });
+      }
+
+      // WebSite schema for landing pages
+      if (type.value === "website") {
+        const websiteSchema: Record<string, unknown> = {
+          "@context": "https://schema.org",
+          "@type": "WebSite",
+          name: site.name || title.value,
+          description: description.value,
+          url: baseUrl.value,
+        };
+
+        scripts.push({
+          type: "application/ld+json",
+          innerHTML: JSON.stringify(websiteSchema),
+        });
+      }
+
+      // BreadcrumbList schema for navigation
+      if (breadcrumbs.value && breadcrumbs.value.length > 0) {
+        const breadcrumbSchema = {
+          "@context": "https://schema.org",
+          "@type": "BreadcrumbList",
+          itemListElement: breadcrumbs.value.map((item, index) => ({
+            "@type": "ListItem",
+            position: index + 1,
+            name: item.title,
+            item: joinURL(baseUrl.value, item.path),
+          })),
+        };
+
+        scripts.push({
+          type: "application/ld+json",
+          innerHTML: JSON.stringify(breadcrumbSchema),
+        });
+      }
+
+      return scripts;
+    }),
+  });
+}

package/app/composables/useUIConfig.ts

@@ -0,0 +1,36 @@
+import type { BorderType, DocdExtraLink, DocdTransitionConfig, DocLogoConfig } from "../app.config";
+
+interface DocdUIMap {
+  header: {
+    title?: string;
+    hideSearch?: boolean;
+    logo?: DocLogoConfig;
+  };
+  footer?: {
+    hideThemeCustomizer?: boolean;
+    hideLightDarkToggle?: boolean;
+  };
+  toc: {
+    title?: string;
+    icon?: string;
+  };
+  borderType: BorderType;
+  transition: DocdTransitionConfig;
+  extraLinks: DocdExtraLink[];
+}
+
+export function useUIConfig<K extends keyof DocdUIMap>(section: K): ComputedRef<DocdUIMap[K]> {
+  const appConfig = useAppConfig();
+  return computed(() => {
+    const ui = (appConfig.docd as { ui?: Partial<DocdUIMap> } | undefined)?.ui;
+    return (ui?.[section] ?? defaultValues[section]) as DocdUIMap[K];
+  });
+}
+
+const defaultValues: DocdUIMap = {
+  header: {},
+  toc: { title: "On this page", icon: "lucide:list" },
+  borderType: "dashed",
+  transition: { name: "fade", duration: 0.35, easing: "easeOut" },
+  extraLinks: [],
+};

package/app/layouts/default.vue

@@ -0,0 +1,5 @@
+<template>
+  <main>
+    <slot />
+  </main>
+</template>

package/app/layouts/docs.vue

@@ -0,0 +1,64 @@
+<template>
+  <div class="grid min-h-dvh w-full grid-cols-1 tablet:grid-cols-[var(--nav-width)_minmax(0,1fr)]">
+    <aside
+      class="sticky top-0 z-20 hidden h-dvh flex-col border-r text-card-foreground tablet:flex"
+      :class="isDashed ? 'border-dashed' : ''"
+    >
+      <div
+        class="sticky top-0 mb-4 border-b bg-background/80 backdrop-blur-lg"
+        :class="isDashed ? 'border-dashed' : ''"
+      >
+        <div class="flex h-(--header-height) items-center justify-between px-4">
+          <DocsLogo />
+          <DocsSearchButton v-if="!hideSearch" />
+        </div>
+      </div>
+      <UiScrollArea
+        class="h-[calc(100dvh-calc(var(--header-height)*2))] flex-1 mask-[linear-gradient(to_bottom,transparent,white_12px,white_calc(100%-12px),transparent)] px-4"
+      >
+        <DocsNav v-if="navigation" :items="navigation" />
+      </UiScrollArea>
+      <div
+        class="mt-auto flex h-(--header-height) items-center justify-between gap-3 border-t px-2"
+        :class="isDashed ? 'border-dashed' : ''"
+      >
+        <template v-if="github">
+          <DocsGithubLink />
+        </template>
+        <div class="ml-auto flex items-center gap-1.5">
+          <template v-if="github && (!hideThemeCustomizer || !hideLightDarkToggle)">
+            <UiDivider
+              :type="isDashed ? 'dashed' : 'solid'"
+              orientation="vertical"
+              class="h-[calc(var(--header-height)-2rem)]"
+            />
+          </template>
+          <DocsThemeCustomizer v-if="!hideThemeCustomizer" />
+          <DocsThemeToggler v-if="!hideLightDarkToggle" class="dark:text-muted-foreground" />
+        </div>
+      </div>
+    </aside>
+    <main class="flex min-h-dvh flex-col">
+      <header
+        class="sticky top-0 z-50 shrink-0 bg-background/80 backdrop-blur-lg"
+        :class="isDashed ? 'border-dashed' : ''"
+      >
+        <DocsMobileBar />
+        <div class="border-b" :class="isDashed ? 'border-dashed' : ''">
+          <UiContainer class="flex h-(--header-height) items-center">
+            <DocsHeader />
+          </UiContainer>
+        </div>
+      </header>
+      <PageMobileToc />
+      <div class="grow">
+        <slot />
+      </div>
+    </main>
+  </div>
+</template>
+
+<script lang="ts" setup>
+  const { navigation } = await useDocPage();
+  const { isDashed, github, hideSearch, hideLightDarkToggle, hideThemeCustomizer } = useDocd();
+</script>

package/app/middleware/colorMode.global.ts

@@ -0,0 +1,8 @@
+export default defineNuxtRouteMiddleware((to) => {
+  const appConfig = useAppConfig();
+  const forced = appConfig.docd.ui?.colorMode;
+
+  if (forced === "light" || forced === "dark") {
+    to.meta.colorMode = forced;
+  }
+});

package/app/middleware/doc-page-layout.ts

@@ -0,0 +1,11 @@
+interface DocPageLayout {
+  layout?: string;
+}
+
+export default defineNuxtRouteMiddleware(async (to) => {
+  const page = (await queryCollection("docs" as never)
+    .path(to.path)
+    .first()) as DocPageLayout | null;
+
+  setPageLayout(page?.layout || "docs");
+});

package/app/middleware/landing-page-layout.ts

@@ -0,0 +1,11 @@
+interface LandingPageLayout {
+  layout?: string;
+}
+
+export default defineNuxtRouteMiddleware(async (to) => {
+  const page = (await queryCollection("landing" as never)
+    .path(to.path)
+    .first()) as LandingPageLayout | null;
+
+  setPageLayout(page?.layout || "default");
+});