@openlaboratory/open-doc 0.1.3 → 0.1.4

package/README.md

@@ -83,8 +83,8 @@ Set these in `open-doc.config.ts`:
 The full guide and a live example live in the
 [project repository](https://github.com/openlaboratory-org/open-doc).
 
-> MDX pages and custom React components require `react` and `react-dom` in your
-> project. Plain Markdown needs nothing else.
+> `open-doc` provides the React runtime for MDX components. TSX authoring and
+> `open-doc check` still need `@types/react` and `@types/react-dom` in your project.
 
 ## License
 

package/app/src/components/DocsMobileNav.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react'
 import type { DocSection } from '../lib/navigation'
+import { tagReactComponent } from '../lib/reactRenderer'
 import { withBase } from '../lib/withBase'
 
 interface Props {
@@ -122,3 +123,5 @@ export function DocsMobileNav({ navigation, currentSlug }: Props) {
     </>
   )
 }
+
+tagReactComponent(DocsMobileNav)

package/app/src/components/DocsSearch.tsx

@@ -1,6 +1,8 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
 import Fuse from 'fuse.js'
 import type { DocSection, DocPage } from '../lib/navigation'
+import { tagReactComponent } from '../lib/reactRenderer'
 import { withBase } from '../lib/withBase'
 
 interface Props {
@@ -26,6 +28,10 @@ function isEditableTarget(target: EventTarget | null): boolean {
   )
 }
 
+function isVisibleElement(element: HTMLElement | null): boolean {
+  return !!element && element.getClientRects().length > 0
+}
+
 /**
  * ⌘K search modal. Uses Pagefind full-text search against the built site, and
  * gracefully falls back to a lightweight title/description search (Fuse.js) when
@@ -34,6 +40,10 @@ function isEditableTarget(target: EventTarget | null): boolean {
  */
 export function DocsSearch({ navigation }: Props) {
   const allPages = useMemo<DocPage[]>(() => navigation.flatMap((s) => s.pages), [navigation])
+  const indexedSections = useMemo(
+    () => navigation.filter((section) => section.pages.length > 0).slice(0, 3),
+    [navigation],
+  )
   const fuse = useMemo(
     () => new Fuse(allPages, { keys: ['title', 'description'], threshold: 0.4 }),
     [allPages],
@@ -55,10 +65,13 @@ export function DocsSearch({ navigation }: Props) {
 
   useEffect(() => {
     const handleKey = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+      const key = e.key.toLowerCase()
+      if ((e.metaKey || e.ctrlKey) && key === 'k') {
+        if (!isVisibleElement(triggerRef.current)) return
         e.preventDefault()
         setOpen(true)
       } else if (e.key === '/' && !isEditableTarget(e.target)) {
+        if (!isVisibleElement(triggerRef.current)) return
         e.preventDefault()
         setOpen(true)
       } else if (e.key === 'Escape') {
@@ -152,6 +165,195 @@ export function DocsSearch({ navigation }: Props) {
     }
   }
 
+  const hasQuery = query.trim().length > 0
+  const pageCountLabel = `${allPages.length} ${allPages.length === 1 ? 'page' : 'pages'}`
+
+  const searchDialog = open ? (
+    <div
+      className="fixed inset-0 z-[1000] flex items-start justify-center px-4 pt-[15vh]"
+      onClick={(e) => {
+        if (!dialogRef.current?.contains(e.target as Node)) setOpen(false)
+      }}
+    >
+      <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" />
+
+      <div
+        ref={dialogRef}
+        className="relative w-full max-w-xl overflow-hidden rounded-xl border border-foreground/[0.12] bg-surface-raised shadow-2xl"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search documentation"
+      >
+        <div className="flex items-center gap-3 border-b border-foreground/[0.08] px-4 py-3">
+          <svg
+            className="h-4 w-4 shrink-0 text-foreground/40"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+            />
+          </svg>
+          <input
+            ref={inputRef}
+            type="text"
+            placeholder="Search documentation…"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={handleKeyDown}
+            role="combobox"
+            aria-expanded={hasQuery && results.length > 0}
+            aria-controls="od-search-results"
+            aria-activedescendant={
+              hasQuery && results[selectedIndex] ? `od-search-option-${selectedIndex}` : undefined
+            }
+            className="flex-1 bg-transparent text-sm text-foreground placeholder-foreground/30 outline-none"
+          />
+          <button
+            onClick={() => setOpen(false)}
+            className="rounded border border-foreground/[0.1] px-1.5 py-0.5 text-[11px] text-foreground/40 transition-colors hover:text-foreground/70"
+          >
+            Esc
+          </button>
+        </div>
+
+        <div
+          className="max-h-[360px] overflow-y-auto py-2"
+          id="od-search-results"
+          role={hasQuery ? 'listbox' : undefined}
+        >
+          {!hasQuery ? (
+            <div className="px-4 py-3">
+              <div className="flex items-center gap-3 rounded-lg border border-foreground/[0.08] bg-foreground/[0.025] px-3 py-2.5">
+                <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md border border-link/15 bg-link/10 text-link">
+                  <svg
+                    className="h-4 w-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    strokeWidth={1.8}
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M7 7h6M7 11h4m2 8H6a2 2 0 01-2-2V5a2 2 0 012-2h8l4 4v3.5"
+                    />
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M15.5 17.5l3 3m1-5a4 4 0 11-8 0 4 4 0 018 0z"
+                    />
+                  </svg>
+                </div>
+                <div className="min-w-0 flex-1">
+                  <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+                    <span className="text-sm font-medium text-foreground/75">{pageCountLabel}</span>
+                    <span className="text-xs text-foreground/35">available</span>
+                  </div>
+                  {indexedSections.length > 0 && (
+                    <div className="mt-1.5 flex flex-wrap gap-1.5">
+                      {indexedSections.map((section) => (
+                        <span
+                          key={section.label}
+                          className="rounded border border-foreground/[0.08] bg-surface-raised px-1.5 py-0.5 text-[11px] font-medium text-foreground/50"
+                        >
+                          {section.label}
+                        </span>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              </div>
+            </div>
+          ) : results.length === 0 ? (
+            <p className="px-4 py-8 text-center text-sm text-foreground/40">
+              No results for &ldquo;{query}&rdquo;
+            </p>
+          ) : (
+            results.map((result, i) => {
+              const isSelected = i === selectedIndex
+              return (
+                <a
+                  key={result.url + i}
+                  id={`od-search-option-${i}`}
+                  role="option"
+                  aria-selected={isSelected}
+                  href={result.url}
+                  onClick={() => setOpen(false)}
+                  onMouseEnter={() => setSelectedIndex(i)}
+                  className={[
+                    'flex items-start gap-3 px-4 py-2.5 transition-colors',
+                    isSelected ? 'bg-foreground/[0.08]' : 'hover:bg-foreground/[0.04]',
+                  ].join(' ')}
+                >
+                  <svg
+                    className="mt-0.5 h-4 w-4 shrink-0 text-foreground/30"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    strokeWidth={2}
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+                    />
+                  </svg>
+                  <div className="min-w-0">
+                    <div className="text-sm font-medium leading-snug text-foreground/90">
+                      {result.title}
+                    </div>
+                    {result.excerpt &&
+                      (result.html ? (
+                        <div
+                          className="search-excerpt mt-0.5 line-clamp-2 text-xs text-foreground/45"
+                          dangerouslySetInnerHTML={{ __html: result.excerpt }}
+                        />
+                      ) : (
+                        <div className="mt-0.5 truncate text-xs text-foreground/45">
+                          {result.excerpt}
+                        </div>
+                      ))}
+                  </div>
+                </a>
+              )
+            })
+          )}
+        </div>
+
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-2 border-t border-foreground/[0.06] px-4 py-3 text-[13px] text-foreground/50">
+          <span className="flex items-center gap-1.5 whitespace-nowrap">
+            <kbd className="inline-flex h-6 min-w-6 items-center justify-center rounded border border-foreground/[0.14] bg-foreground/[0.04] px-2 font-mono text-xs leading-none text-foreground/65">
+              ↑↓
+            </kbd>
+            navigate
+          </span>
+          <span className="flex items-center gap-1.5 whitespace-nowrap">
+            <kbd className="inline-flex h-6 min-w-6 items-center justify-center rounded border border-foreground/[0.14] bg-foreground/[0.04] px-2 font-mono text-xs leading-none text-foreground/65">
+              ↵
+            </kbd>
+            open
+          </span>
+          <span className="flex items-center gap-1.5 whitespace-nowrap">
+            <kbd className="inline-flex h-6 min-w-6 items-center justify-center rounded border border-foreground/[0.14] bg-foreground/[0.04] px-2 font-mono text-xs leading-none text-foreground/65">
+              Esc
+            </kbd>
+            close
+          </span>
+          {!fullText && (
+            <span className="text-foreground/40 sm:ml-auto">
+              Title search · run a build for full-text
+            </span>
+          )}
+        </div>
+      </div>
+    </div>
+  ) : null
+
   return (
     <>
       <button
@@ -179,137 +381,9 @@ export function DocsSearch({ navigation }: Props) {
         </kbd>
       </button>
 
-      {open && (
-        <div
-          className="fixed inset-0 z-[100] flex items-start justify-center px-4 pt-[15vh]"
-          onClick={(e) => {
-            if (!dialogRef.current?.contains(e.target as Node)) setOpen(false)
-          }}
-        >
-          <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" />
-
-          <div
-            ref={dialogRef}
-            className="relative w-full max-w-xl overflow-hidden rounded-xl border border-foreground/[0.12] bg-surface-raised shadow-2xl"
-            role="dialog"
-            aria-modal="true"
-            aria-label="Search documentation"
-          >
-            <div className="flex items-center gap-3 border-b border-foreground/[0.08] px-4 py-3">
-              <svg
-                className="h-4 w-4 shrink-0 text-foreground/40"
-                fill="none"
-                viewBox="0 0 24 24"
-                stroke="currentColor"
-                strokeWidth={2}
-              >
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
-                />
-              </svg>
-              <input
-                ref={inputRef}
-                type="text"
-                placeholder="Search documentation…"
-                value={query}
-                onChange={(e) => setQuery(e.target.value)}
-                onKeyDown={handleKeyDown}
-                role="combobox"
-                aria-expanded={results.length > 0}
-                aria-controls="od-search-results"
-                aria-activedescendant={
-                  results[selectedIndex] ? `od-search-option-${selectedIndex}` : undefined
-                }
-                className="flex-1 bg-transparent text-sm text-foreground placeholder-foreground/30 outline-none"
-              />
-              <button
-                onClick={() => setOpen(false)}
-                className="rounded border border-foreground/[0.1] px-1.5 py-0.5 text-[11px] text-foreground/40 transition-colors hover:text-foreground/70"
-              >
-                Esc
-              </button>
-            </div>
-
-            <div
-              className="max-h-[360px] overflow-y-auto py-2"
-              id="od-search-results"
-              role="listbox"
-            >
-              {query.trim() && results.length === 0 ? (
-                <p className="px-4 py-8 text-center text-sm text-foreground/40">
-                  No results for &ldquo;{query}&rdquo;
-                </p>
-              ) : (
-                results.map((result, i) => {
-                  const isSelected = i === selectedIndex
-                  return (
-                    <a
-                      key={result.url + i}
-                      id={`od-search-option-${i}`}
-                      role="option"
-                      aria-selected={isSelected}
-                      href={result.url}
-                      onClick={() => setOpen(false)}
-                      onMouseEnter={() => setSelectedIndex(i)}
-                      className={[
-                        'flex items-start gap-3 px-4 py-2.5 transition-colors',
-                        isSelected ? 'bg-foreground/[0.08]' : 'hover:bg-foreground/[0.04]',
-                      ].join(' ')}
-                    >
-                      <svg
-                        className="mt-0.5 h-4 w-4 shrink-0 text-foreground/30"
-                        fill="none"
-                        viewBox="0 0 24 24"
-                        stroke="currentColor"
-                        strokeWidth={2}
-                      >
-                        <path
-                          strokeLinecap="round"
-                          strokeLinejoin="round"
-                          d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
-                        />
-                      </svg>
-                      <div className="min-w-0">
-                        <div className="text-sm font-medium leading-snug text-foreground/90">
-                          {result.title}
-                        </div>
-                        {result.excerpt &&
-                          (result.html ? (
-                            <div
-                              className="search-excerpt mt-0.5 line-clamp-2 text-xs text-foreground/45"
-                              dangerouslySetInnerHTML={{ __html: result.excerpt }}
-                            />
-                          ) : (
-                            <div className="mt-0.5 truncate text-xs text-foreground/45">
-                              {result.excerpt}
-                            </div>
-                          ))}
-                      </div>
-                    </a>
-                  )
-                })
-              )}
-            </div>
-
-            <div className="flex items-center gap-4 border-t border-foreground/[0.06] px-4 py-2 text-[10px] text-foreground/30">
-              <span className="flex items-center gap-1">
-                <kbd className="font-mono">↑↓</kbd> navigate
-              </span>
-              <span className="flex items-center gap-1">
-                <kbd className="font-mono">↵</kbd> open
-              </span>
-              <span className="flex items-center gap-1">
-                <kbd className="font-mono">esc</kbd> close
-              </span>
-              {!fullText && (
-                <span className="ml-auto">Title search · run a build for full-text</span>
-              )}
-            </div>
-          </div>
-        </div>
-      )}
+      {searchDialog && createPortal(searchDialog, document.body)}
     </>
   )
 }
+
+tagReactComponent(DocsSearch)

package/app/src/components/DocsTableOfContents.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
+import { tagReactComponent } from '../lib/reactRenderer'
 
 interface Heading {
   depth: number
@@ -90,3 +91,5 @@ export function DocsTableOfContents({ headings }: Props) {
     </nav>
   )
 }
+
+tagReactComponent(DocsTableOfContents)

package/app/src/components/ThemeToggle.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react'
+import { tagReactComponent } from '../lib/reactRenderer'
 
 const STORAGE_KEY = 'open-doc-theme'
 
@@ -60,3 +61,5 @@ export function ThemeToggle() {
     </button>
   )
 }
+
+tagReactComponent(ThemeToggle)

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

@@ -1,5 +1,6 @@
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
+import { dirname } from 'node:path'
 
 // The bundled Astro app this integration ships inside, e.g.
 // `…/node_modules/@openlaboratory/open-doc/app`. Its `src/` holds the React
@@ -8,6 +9,7 @@ const APP_ROOT = fileURLToPath(new URL('../../', import.meta.url))
 
 // Resolve specifiers from open-doc's own install (not the consumer's).
 const require = createRequire(import.meta.url)
+const ASTRO_ROOT = dirname(require.resolve('astro/package.json'))
 
 /**
  * Astro's static build emits an SSR server bundle into the consumer's `dist/`
@@ -69,8 +71,9 @@ export function openDocConfig({ contentDir, publicDir } = {}) {
   const configJson = process.env.OPEN_DOC_CONFIG_JSON || '{}'
   // The app lives in node_modules (under pnpm, behind a symlinked .pnpm path),
   // so its island sources fall outside Vite's default fs.allow and 404 in dev.
-  // Allow the app root explicitly alongside the consumer's content/public dirs.
-  const allow = [APP_ROOT, contentDir, publicDir].filter(Boolean)
+  // Allow the app root, Astro's dev-toolbar client, and the consumer's
+  // content/public dirs explicitly.
+  const allow = [APP_ROOT, ASTRO_ROOT, contentDir, publicDir].filter(Boolean)
 
   return {
     name: 'open-doc:config',

package/app/src/layouts/DocsLayout.astro

@@ -335,9 +335,21 @@ const darkVars = toVars(config.theme.dark)
         const prose = document.querySelector('.docs-prose')
         if (!prose) return
         prose.querySelectorAll('pre').forEach((pre) => {
-          if (pre.querySelector('.code-copy-btn')) return
+          const existingWrapper = pre.parentElement?.classList.contains('code-block')
+            ? pre.parentElement
+            : null
+          if (existingWrapper?.querySelector('.code-copy-btn')) return
+
+          const wrapper = existingWrapper ?? document.createElement('div')
+          if (!existingWrapper) {
+            wrapper.className = 'code-block'
+            pre.parentNode?.insertBefore(wrapper, pre)
+            wrapper.appendChild(pre)
+          }
+
           const btn = document.createElement('button')
           btn.className = 'code-copy-btn'
+          btn.type = 'button'
           btn.setAttribute('aria-label', 'Copy code')
           btn.innerHTML = clipboardIcon
           btn.addEventListener('click', () => {
@@ -352,7 +364,7 @@ const darkVars = toVars(config.theme.dark)
               }, 2000)
             })
           })
-          pre.appendChild(btn)
+          wrapper.appendChild(btn)
         })
       }
 

package/app/src/lib/reactRenderer.ts

@@ -0,0 +1,12 @@
+const ASTRO_RENDERER = Symbol.for('astro:renderer')
+
+export function tagReactComponent<T extends (...args: any[]) => unknown>(Component: T): T {
+  if (!(ASTRO_RENDERER in Component)) {
+    Object.defineProperty(Component, ASTRO_RENDERER, {
+      value: '@astrojs/react',
+      enumerable: false,
+      writable: false,
+    })
+  }
+  return Component
+}

package/app/src/styles/global.css

@@ -155,12 +155,33 @@
   content: none;
 }
 
+.docs-prose kbd {
+  border: 1px solid hsl(var(--foreground) / 0.16);
+  border-radius: 0.375rem;
+  background: hsl(var(--surface-raised));
+  box-shadow:
+    0 1px 0 hsl(var(--foreground) / 0.12),
+    inset 0 -1px 0 hsl(var(--foreground) / 0.08);
+  color: hsl(var(--foreground) / 0.88);
+}
+
 .docs-prose pre {
   border: 1px solid hsl(var(--code-border));
   border-radius: 0.625rem;
   position: relative;
 }
 
+.docs-prose .code-block {
+  position: relative;
+  margin-top: 1.7142857em;
+  margin-bottom: 1.7142857em;
+}
+
+.docs-prose .code-block pre {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
 .docs-prose blockquote {
   border-left: 2px solid hsl(var(--border));
   background: hsl(var(--foreground) / 0.03);
@@ -240,6 +261,13 @@
   position: relative;
 }
 
+.docs-prose h1[id],
+.docs-prose h2[id],
+.docs-prose h3[id],
+.docs-prose h4[id] {
+  scroll-margin-top: calc(57px + 1rem);
+}
+
 .docs-prose .heading-anchor {
   position: absolute;
   right: 100%;
@@ -289,7 +317,8 @@
     background 0.15s;
 }
 
-.docs-prose pre:hover .code-copy-btn {
+.docs-prose .code-block:hover .code-copy-btn,
+.code-copy-btn:focus-visible {
   opacity: 1;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlaboratory/open-doc",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A polished, GitBook-style documentation-site framework. Write Markdown, run one command, get a beautiful static site.",
   "keywords": [
     "documentation",
@@ -25,7 +25,7 @@
   },
   "type": "module",
   "bin": {
-    "open-doc": "./bin/open-doc.js"
+    "open-doc": "bin/open-doc.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",