feat(sidebar): add Sidebar component with nav utilities

- Add collapsible Sidebar with spring animations, active-state
  highlighting, persisted open/close state, and external link support
- Add NavItem/NavSection types with optional `exact` flag for
  controlling prefix-matching behavior per item
- Add isActivePath and getDocsTitleByPath nav utilities
- Add fetchOtherProjects server helper for Humanspeak registry
- Add runed dependency for PersistedState
- Export all new public API from index.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jaysin586

package.json

@@ -97,6 +97,7 @@
         "@resvg/resvg-js": "^2.6.2",
         "bits-ui": "^2.16.2",
         "clsx": "^2.1.1",
+        "runed": "^0.37.1",
         "satori": "^0.24.1",
         "satori-html": "^0.3.2",
         "tailwind-merge": "^3.5.0"

pnpm-lock.yaml

@@ -0,0 +1,166 @@
+<!--
+  Shared sidebar navigation component for Humanspeak docs sites.
+  Collapsible sections with spring animations, active-state highlighting, and external link support.
+-->
+<script lang="ts">
+    import { motion } from '@humanspeak/svelte-motion'
+    import ArrowRight from '@lucide/svelte/icons/arrow-right'
+    import ChevronDown from '@lucide/svelte/icons/chevron-down'
+    import ExternalLink from '@lucide/svelte/icons/external-link'
+    import Heart from '@lucide/svelte/icons/heart'
+    import { PersistedState } from 'runed'
+    import { slide } from 'svelte/transition'
+    import type { DocsKitConfig } from '../config.js'
+    import type { NavItem, NavSection } from '../types/nav.js'
+    import { isActivePath } from '../utils/nav.js'
+
+    const defaultLoveAndRespect: NavItem[] = [
+        { title: 'Beye.ai', href: 'https://beye.ai', icon: Heart, external: true }
+    ]
+
+    const hoverScale = { scale: 1.25 }
+    const hoverShift = { x: 2 }
+    const springFast = { type: 'spring' as const, stiffness: 500, damping: 15 }
+    const springSoft = { type: 'spring' as const, stiffness: 400, damping: 25 }
+
+    const {
+        config,
+        sections,
+        currentPath,
+        otherProjects = [],
+        loveAndRespect = defaultLoveAndRespect
+    }: {
+        config: DocsKitConfig
+        sections: NavSection[]
+        currentPath: string
+        otherProjects?: NavItem[]
+        loveAndRespect?: NavItem[]
+    } = $props()
+
+    const openSections = new PersistedState<Record<string, boolean>>(
+        `${config.slug}-sidebar-sections`,
+        {}
+    )
+
+    // Ensure items in built-in sections have Heart icons as defaults
+    // (otherProjects come from server data and can't carry component references)
+    const withDefaultIcon = (items: NavItem[], defaultIcon: typeof Heart): NavItem[] =>
+        items.map((item) => (item.icon ? item : { ...item, icon: defaultIcon }))
+
+    const navigation: NavSection[] = $derived([
+        ...sections,
+        ...(loveAndRespect.length > 0
+            ? [
+                  {
+                      title: 'Love and Respect',
+                      icon: Heart,
+                      items: withDefaultIcon(loveAndRespect, Heart)
+                  }
+              ]
+            : []),
+        ...(otherProjects.length > 0
+            ? [
+                  {
+                      title: 'Other Projects',
+                      icon: Heart,
+                      items: withDefaultIcon(otherProjects, Heart)
+                  }
+              ]
+            : [])
+    ])
+
+    const isSectionOpen = (section: NavSection): boolean => {
+        if (section.title in openSections.current) return openSections.current[section.title]
+        return true
+    }
+
+    const toggleSection = (section: NavSection) => {
+        openSections.current = {
+            ...openSections.current,
+            [section.title]: !isSectionOpen(section)
+        }
+    }
+</script>
+
+<nav class="p-2">
+    <div class="space-y-2">
+        {#each navigation as section (section.title)}
+            <div>
+                <button
+                    onclick={() => toggleSection(section)}
+                    class="flex w-full items-center justify-between rounded-md px-3 py-1.5 text-sm font-semibold tracking-wide text-text-primary uppercase transition-colors duration-150 hover:bg-muted"
+                >
+                    <span class="flex items-center gap-2 text-left">
+                        <motion.span
+                            class="inline-flex shrink-0"
+                            whileHover={hoverScale}
+                            transition={springFast}
+                        >
+                            {#if section.icon}
+                                <svelte:component
+                                    this={section.icon}
+                                    size={14}
+                                    class="text-muted-foreground"
+                                />
+                            {/if}
+                        </motion.span>
+                        {section.title}
+                    </span>
+                    <ChevronDown
+                        size={12}
+                        class="shrink-0 text-muted-foreground transition-transform duration-200 {isSectionOpen(
+                            section
+                        )
+                            ? 'rotate-180'
+                            : ''}"
+                    />
+                </button>
+                {#if isSectionOpen(section)}
+                    <ul
+                        class="mt-1 ml-3 space-y-1 border-l border-border pl-1"
+                        transition:slide={{ duration: 200 }}
+                    >
+                        {#each section.items as item (item.href)}
+                            <motion.li
+                                whileHover={hoverShift}
+                                transition={springSoft}
+                            >
+                                <a
+                                    href={item.href}
+                                    target={item?.external ? '_blank' : undefined}
+                                    rel={item?.external ? 'noopener' : undefined}
+                                    class="group flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors duration-150
+                                     {isActivePath(item.href, currentPath, item.exact)
+                                        ? 'bg-accent text-accent-foreground'
+                                        : 'text-muted-foreground hover:bg-muted hover:text-foreground'}"
+                                >
+                                    {#if item.icon}
+                                        <motion.span
+                                            class="mr-3 inline-flex"
+                                            whileHover={hoverScale}
+                                            transition={springFast}
+                                        >
+                                            <svelte:component
+                                                this={item.icon}
+                                                size={14}
+                                                class={isActivePath(item.href, currentPath, item.exact)
+                                                    ? 'text-accent-foreground'
+                                                    : 'text-muted-foreground group-hover:text-foreground'}
+                                            />
+                                        </motion.span>
+                                    {:else}
+                                        <ArrowRight size={12} class="mr-3 text-muted-foreground" />
+                                    {/if}
+                                    {item.title}
+                                    {#if item?.external}
+                                        <ExternalLink size={12} class="ml-2 opacity-50" />
+                                    {/if}
+                                </a>
+                            </motion.li>
+                        {/each}
+                    </ul>
+                {/if}
+            </div>
+        {/each}
+    </div>
+</nav>

src/lib/components/Sidebar.svelte

@@ -9,13 +9,19 @@ export { default as Header } from './components/Header.svelte'
 export { default as OG } from './components/OG.svelte'
 export { default as SeoContextProvider } from './components/SeoContextProvider.svelte'
 export { default as SeoHead } from './components/SeoHead.svelte'
+export { default as Sidebar } from './components/Sidebar.svelte'
 export { default as ThemeToggle } from './components/ThemeToggle.svelte'
 
 // Icons (brand icons only — use @lucide/svelte for UI icons)
 export { default as GitHubIcon } from './components/icons/GitHubIcon.svelte'
 export { default as NpmIcon } from './components/icons/NpmIcon.svelte'
 
+// Nav types
+export type { NavItem, NavSection } from './types/nav.js'
+
 // Utilities
+export { fetchOtherProjects } from './utils/fetchOtherProjects.js'
+export { getDocsTitleByPath, isActivePath } from './utils/nav.js'
 export { cn } from './utils/shadcn.js'
 
 // Contexts

src/lib/index.ts

@@ -0,0 +1,16 @@
+import type { Component } from 'svelte'
+
+export type NavItem = {
+    title: string
+    href: string
+    icon?: Component
+    external?: boolean
+    /** When true, only exact path matches activate this item (no prefix matching) */
+    exact?: boolean
+}
+
+export type NavSection = {
+    title: string
+    icon?: Component
+    items: NavItem[]
+}

src/lib/types/nav.ts

@@ -0,0 +1,54 @@
+import type { NavItem } from '../types/nav.js'
+
+type OtherProject = {
+    url: string
+    slug: string
+    shortDescription: string
+}
+
+/**
+ * Server-side helper to fetch "Other Projects" from the Humanspeak registry.
+ * Filters out the current project by slug and returns NavItem[] for direct use in Sidebar.
+ *
+ * @param slug - The current project's slug to filter out (e.g., 'markdown', 'motion')
+ * @returns NavItem[] of other Humanspeak projects
+ */
+export async function fetchOtherProjects(slug: string): Promise<NavItem[]> {
+    try {
+        const controller = new AbortController()
+        const timeoutId = setTimeout(() => controller.abort(), 5000)
+
+        const response = await fetch('https://svelte.page/api/v1/others', {
+            signal: controller.signal
+        })
+        clearTimeout(timeoutId)
+
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`)
+        }
+
+        const projects = (await response.json()) as OtherProject[]
+
+        if (!Array.isArray(projects)) {
+            throw new Error('Invalid response: expected array')
+        }
+
+        return projects
+            .filter(
+                (p): p is OtherProject =>
+                    p != null &&
+                    typeof p.slug === 'string' &&
+                    typeof p.url === 'string' &&
+                    typeof p.shortDescription === 'string'
+            )
+            .filter((project) => project.slug !== slug)
+            .map((project) => ({
+                title: project.slug.toLowerCase(),
+                href: project.url,
+                external: true
+            }))
+    } catch (error) {
+        console.error('Failed to fetch other projects:', error)
+        return []
+    }
+}

src/lib/utils/fetchOtherProjects.ts

@@ -0,0 +1,37 @@
+import type { NavSection } from '../types/nav.js'
+
+/**
+ * Look up a docs page title by its pathname
+ * @param sections - The navigation sections to search
+ * @param pathname - The URL pathname (e.g., '/docs/infinite-scroll')
+ * @returns The page title or null if not found
+ */
+export function getDocsTitleByPath(sections: NavSection[], pathname: string): string | null {
+    for (const section of sections) {
+        const item = section.items.find((item) => item.href === pathname)
+        if (item) return item.title
+    }
+    return null
+}
+
+/**
+ * Check if a navigation item is active based on the current path.
+ * By default uses prefix matching (e.g. `/docs/foo` matches `/docs/foo/bar`).
+ * Set `exact: true` to disable prefix matching for index-style routes.
+ */
+export function isActivePath(href: string, currentPath: string, exact = false): boolean {
+    const basePath = currentPath.split(/[?#]/)[0]
+    if (exact) {
+        return (
+            basePath === href ||
+            currentPath.startsWith(`${href}?`) ||
+            currentPath.startsWith(`${href}#`)
+        )
+    }
+    return (
+        basePath === href ||
+        currentPath.startsWith(`${href}?`) ||
+        currentPath.startsWith(`${href}#`) ||
+        basePath.startsWith(`${href}/`)
+    )
+}