@openlaboratory/open-doc 0.1.0

package/app/src/components/DocsTableOfContents.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useRef, useState } from 'react'
+
+interface Heading {
+  depth: number
+  slug: string
+  text: string
+}
+
+interface Props {
+  headings: Heading[]
+}
+
+/** Right-hand "On this page" list with scroll-spy via IntersectionObserver. */
+export function DocsTableOfContents({ headings }: Props) {
+  const [activeId, setActiveId] = useState('')
+  const navRef = useRef<HTMLElement>(null)
+  const filtered = headings.filter((h) => h.depth === 2 || h.depth === 3)
+
+  useEffect(() => {
+    if (filtered.length === 0) return
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id)
+            break
+          }
+        }
+      },
+      { rootMargin: '-80px 0px -70% 0px', threshold: 0 },
+    )
+
+    filtered.forEach(({ slug }) => {
+      const el = document.getElementById(slug)
+      if (el) observer.observe(el)
+    })
+
+    // The bottom rootMargin means the last heading may never "activate"; force it
+    // active once the page is scrolled to the bottom.
+    const onScroll = () => {
+      if (window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2) {
+        setActiveId(filtered[filtered.length - 1].slug)
+      }
+    }
+    window.addEventListener('scroll', onScroll, { passive: true })
+
+    return () => {
+      observer.disconnect()
+      window.removeEventListener('scroll', onScroll)
+    }
+  }, [filtered])
+
+  // Keep the active item visible within the (scrollable) TOC.
+  useEffect(() => {
+    if (!activeId || !navRef.current) return
+    const link = navRef.current.querySelector(`a[href="#${CSS.escape(activeId)}"]`)
+    link?.scrollIntoView({ block: 'nearest' })
+  }, [activeId])
+
+  if (filtered.length === 0) return null
+
+  return (
+    <nav ref={navRef} aria-label="On this page">
+      <p className="mb-3 text-[11px] font-semibold uppercase tracking-widest text-foreground/40">
+        On this page
+      </p>
+      <ul className="flex flex-col gap-0.5">
+        {filtered.map((heading) => {
+          const isActive = activeId === heading.slug
+          return (
+            <li key={heading.slug}>
+              <a
+                href={`#${heading.slug}`}
+                aria-current={isActive ? 'location' : undefined}
+                className={[
+                  'block rounded py-1 text-sm leading-snug transition-colors',
+                  heading.depth === 3 ? 'pl-3' : '',
+                  isActive
+                    ? 'font-medium text-foreground'
+                    : 'text-foreground/50 hover:text-foreground/80',
+                ].join(' ')}
+              >
+                {heading.text}
+              </a>
+            </li>
+          )
+        })}
+      </ul>
+    </nav>
+  )
+}

package/app/src/components/Navbar.astro

@@ -0,0 +1,39 @@
+---
+import config from 'virtual:open-doc-config'
+import { withBase } from '../lib/withBase'
+import { ThemeToggle } from './ThemeToggle'
+import SocialIcon from './SocialIcon.astro'
+
+const { logo, title, social, themeToggle } = config
+---
+
+<header
+  class="sticky top-0 z-40 h-[57px] border-b border-foreground/[0.08] bg-surface-sidebar/80 backdrop-blur supports-[backdrop-filter]:bg-surface-sidebar/70"
+>
+  <div class="flex h-full items-center justify-between gap-4 px-4 sm:px-6">
+    <a
+      href={withBase(logo.href)}
+      class="flex items-center gap-2.5 text-foreground/90 transition-colors hover:text-foreground"
+    >
+      {logo.src && <img src={withBase(logo.src)} alt={title} class="h-6 w-auto" />}
+      {logo.text && <span class="text-sm font-semibold tracking-tight">{logo.text}</span>}
+    </a>
+
+    <div class="flex items-center gap-1">
+      {
+        social.map((item) => (
+          <a
+            href={item.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            class="flex h-8 w-8 items-center justify-center rounded-md text-foreground/55 transition-colors hover:bg-foreground/[0.06] hover:text-foreground/90"
+            aria-label={item.label ?? item.icon ?? 'Link'}
+          >
+            <SocialIcon name={item.icon} />
+          </a>
+        ))
+      }
+      {themeToggle && <ThemeToggle client:load />}
+    </div>
+  </div>
+</header>

package/app/src/components/SocialIcon.astro

@@ -0,0 +1,54 @@
+---
+// Renders a brand glyph for a social link. Falls back to a generic link icon.
+interface Props {
+  name?: string
+  class?: string
+}
+const { name, class: className = 'h-[18px] w-[18px]' } = Astro.props
+
+// Brand glyphs (single-path, 24x24, fill=currentColor).
+const brands: Record<string, string> = {
+  github:
+    'M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61-.546-1.387-1.333-1.757-1.333-1.757-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.509 11.509 0 0112 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222 0 1.606-.014 2.898-.014 3.293 0 .322.216.694.825.576C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12',
+  x: 'M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z',
+  twitter:
+    'M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z',
+  discord:
+    'M20.317 4.369a19.791 19.791 0 00-4.885-1.515.074.074 0 00-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 00-5.487 0 12.64 12.64 0 00-.617-1.25.077.077 0 00-.079-.037A19.736 19.736 0 003.677 4.37a.07.07 0 00-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 00.031.057 19.9 19.9 0 005.993 3.03.078.078 0 00.084-.028c.462-.63.874-1.295 1.226-1.994a.076.076 0 00-.041-.106 13.107 13.107 0 01-1.872-.892.077.077 0 01-.008-.128c.126-.094.252-.192.371-.291a.074.074 0 01.077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 01.078.009c.12.099.245.198.372.292a.077.077 0 01-.006.127c-.598.35-1.22.645-1.873.892a.077.077 0 00-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 00.084.028 19.839 19.839 0 006.002-3.03.077.077 0 00.032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 00-.031-.03zM8.02 15.331c-1.183 0-2.157-1.086-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.332-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.086-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.332-.946 2.418-2.157 2.418z',
+  linkedin:
+    'M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.062 2.062 0 01-2.063-2.065 2.064 2.064 0 112.063 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z',
+  youtube:
+    'M23.498 6.186a3.016 3.016 0 00-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 00.502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 002.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 002.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z',
+  mastodon:
+    'M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.073 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 00.023-.043v-1.809a.052.052 0 00-.02-.041.053.053 0 00-.046-.01 20.282 20.282 0 01-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 01-.319-1.433.053.053 0 01.066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.67 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z',
+  slack:
+    'M5.042 15.165a2.528 2.528 0 01-2.52 2.523A2.528 2.528 0 010 15.165a2.527 2.527 0 012.522-2.52h2.52v2.52zm1.271 0a2.527 2.527 0 012.521-2.52 2.527 2.527 0 012.521 2.52v6.313A2.528 2.528 0 018.834 24a2.528 2.528 0 01-2.521-2.522v-6.313zM8.834 5.042a2.528 2.528 0 01-2.521-2.52A2.528 2.528 0 018.834 0a2.528 2.528 0 012.521 2.522v2.52H8.834zm0 1.271a2.528 2.528 0 012.521 2.521 2.528 2.528 0 01-2.521 2.521H2.522A2.528 2.528 0 010 8.834a2.528 2.528 0 012.522-2.521h6.312zm10.122 2.521a2.528 2.528 0 012.522-2.521A2.528 2.528 0 0124 8.834a2.528 2.528 0 01-2.522 2.521h-2.522V8.834zm-1.268 0a2.528 2.528 0 01-2.523 2.521 2.527 2.527 0 01-2.52-2.521V2.522A2.527 2.527 0 0115.165 0a2.528 2.528 0 012.523 2.522v6.312zm-2.523 10.122a2.528 2.528 0 012.523 2.522A2.528 2.528 0 0115.165 24a2.527 2.527 0 01-2.52-2.522v-2.522h2.52zm0-1.268a2.527 2.527 0 01-2.52-2.523 2.526 2.526 0 012.52-2.52h6.313A2.527 2.527 0 0124 15.165a2.528 2.528 0 01-2.522 2.523h-6.313z',
+  bluesky:
+    'M12 10.8c-1.087-2.114-4.046-6.053-6.798-7.995C2.566.944 1.561 1.266.902 1.565.139 1.908 0 3.08 0 3.768c0 .69.378 5.65.624 6.479.815 2.736 3.713 3.66 6.383 3.364.136-.02.275-.039.415-.056-.138.022-.276.04-.415.056-3.912.58-7.387 2.005-2.83 7.078 5.013 5.19 6.87-1.113 7.823-4.308.953 3.195 2.05 9.271 7.733 4.308 4.267-4.308 1.172-6.498-2.74-7.078a8.741 8.741 0 01-.415-.056c.14.017.279.036.415.056 2.67.297 5.568-.628 6.383-3.364.246-.828.624-5.789.624-6.479 0-.688-.139-1.86-.902-2.203-.659-.299-1.664-.621-4.3 1.24C16.046 4.748 13.087 8.687 12 10.8z',
+}
+
+const path = (name && brands[name]) || null
+---
+
+{
+  path ? (
+    <svg class={className} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d={path} />
+    </svg>
+  ) : (
+    <svg
+      class={className}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      aria-hidden="true"
+    >
+      <path
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        d="M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m13.35-.622l1.757-1.757a4.5 4.5 0 00-6.364-6.364l-4.5 4.5a4.5 4.5 0 001.242 7.244"
+      />
+    </svg>
+  )
+}

package/app/src/components/ThemeToggle.tsx

@@ -0,0 +1,62 @@
+import { useEffect, useState } from 'react'
+
+const STORAGE_KEY = 'open-doc-theme'
+
+/** Header button that toggles the `.dark` class and persists the choice. */
+export function ThemeToggle() {
+  const [isDark, setIsDark] = useState(true)
+
+  useEffect(() => {
+    setIsDark(document.documentElement.classList.contains('dark'))
+  }, [])
+
+  const toggle = () => {
+    const next = !isDark
+    setIsDark(next)
+    document.documentElement.classList.toggle('dark', next)
+    try {
+      localStorage.setItem(STORAGE_KEY, next ? 'dark' : 'light')
+    } catch {
+      /* storage unavailable — ignore */
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      className="flex h-8 w-8 items-center justify-center rounded-md text-foreground/55 transition-colors hover:bg-foreground/[0.06] hover:text-foreground/90"
+      aria-label={isDark ? 'Switch to light theme' : 'Switch to dark theme'}
+    >
+      {isDark ? (
+        <svg
+          className="h-[18px] w-[18px]"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z"
+          />
+        </svg>
+      ) : (
+        <svg
+          className="h-[18px] w-[18px]"
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z"
+          />
+        </svg>
+      )}
+    </button>
+  )
+}

package/app/src/content.config.ts

@@ -0,0 +1,17 @@
+import { defineCollection, z } from 'astro:content'
+import { glob } from 'astro/loaders'
+
+// The CLI sets OPEN_DOC_CONTENT_DIR to the consumer's content directory.
+const base = process.env.OPEN_DOC_CONTENT_DIR ?? './content'
+
+const docs = defineCollection({
+  // Underscore-prefixed files/folders (e.g. _components) are ignored as pages,
+  // so they can hold partials & components imported by your MDX.
+  loader: glob({ pattern: ['**/*.{md,mdx}', '!**/_*', '!**/_*/**'], base }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+  }),
+})
+
+export const collections = { docs }

package/app/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />
+
+declare module 'virtual:open-doc-config' {
+  const config: import('./lib/config').ResolvedConfig
+  export default config
+}

package/app/src/integrations/open-doc-config.mjs

@@ -0,0 +1,65 @@
+/**
+ * Internal Astro integration that wires the consumer's project into the bundled
+ * app:
+ *   • exposes the resolved config as the `virtual:open-doc-config` module
+ *   • aliases `@docs` to the consumer's content directory
+ *   • allows Vite to read files from the (external) content + public dirs
+ *
+ * The resolved config is passed from the CLI via OPEN_DOC_CONFIG_JSON.
+ *
+ * @param {{ contentDir?: string, publicDir?: string }} options
+ * @returns {import('astro').AstroIntegration}
+ */
+export function openDocConfig({ contentDir, publicDir } = {}) {
+  const configJson = process.env.OPEN_DOC_CONFIG_JSON || '{}'
+  const allow = [contentDir, publicDir].filter(Boolean)
+
+  return {
+    name: 'open-doc:config',
+    hooks: {
+      'astro:config:setup': ({ command, updateConfig }) => {
+        // For `build`, bundle open-doc's runtime deps into the SSR output so the
+        // build is self-contained under every package manager (their files live
+        // in open-doc's node_modules, not the consumer's). In `dev` they must
+        // stay external — bundling CommonJS React breaks the dev SSR runtime.
+        const noExternal =
+          command === 'build' ? ['fuse.js', 'react', 'react-dom', '@astrojs/react'] : []
+
+        updateConfig({
+          vite: {
+            plugins: [virtualConfigPlugin(configJson)],
+            resolve: {
+              alias: contentDir ? { '@docs': contentDir } : {},
+              // One React instance, even if a consumer installs their own for MDX.
+              dedupe: ['react', 'react-dom'],
+            },
+            ssr: { noExternal },
+            // Merged additively with Vite's defaults by Astro's config merge.
+            server: { fs: { allow } },
+          },
+        })
+      },
+    },
+  }
+}
+
+/**
+ * Emits the resolved config object as a virtual ES module so any `.astro` /
+ * `.tsx` component can `import config from 'virtual:open-doc-config'`.
+ *
+ * @param {string} json
+ * @returns {import('vite').Plugin}
+ */
+function virtualConfigPlugin(json) {
+  const id = 'virtual:open-doc-config'
+  const resolvedId = '\0' + id
+  return {
+    name: 'open-doc:virtual-config',
+    resolveId(source) {
+      if (source === id) return resolvedId
+    },
+    load(thisId) {
+      if (thisId === resolvedId) return `export default ${json}`
+    },
+  }
+}