@brett_lamy/docstream 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
   "scripts": {
@@ -30,6 +30,10 @@
       "types": "./src/streamdown.tsx",
       "import": "./src/streamdown.tsx"
     },
+    "./reference": {
+      "types": "./src/docs/reference.tsx",
+      "import": "./src/docs/reference.tsx"
+    },
     "./assets": {
       "types": "./src/assets.ts",
       "import": "./src/assets.ts"

package/src/docs/reference.tsx

@@ -1,17 +1,99 @@
-import { createContext, useContext, useState, type ReactNode } from "react"
-import { AtSign, Globe, Hash } from "lucide-react"
+import { createContext, useContext, useId, useState, type ReactNode } from "react"
+import { ArrowUpRight, AtSign, Globe, Hash } from "lucide-react"
 
 import type { CitationDef, ReferenceNode } from "../gitbook/ast"
 
+export interface CitationPreview {
+  title?: string
+  description?: string
+  image?: string
+  siteName?: string
+  favicon?: string
+}
+
+export type CitationPreviewResolver = (citation: ReferenceNode) => CitationPreview | null | Promise<CitationPreview | null>
+
 export interface DocstreamRefContextValue {
   /** Called when a mention/tag chip (or a citation, if it has no url) is clicked. */
   onReferenceClick?: (ref: ReferenceNode) => void
   /** Full override for chip rendering; return null to fall back to the default. */
   renderReference?: (ref: ReferenceNode) => ReactNode | null
+  /** Resolves Open Graph-style metadata when a linked citation is hovered or focused. */
+  resolveCitationPreview?: CitationPreviewResolver
 }
 
 export const DocstreamRefContext = createContext<DocstreamRefContextValue>({})
 
+const previewCaches = new WeakMap<CitationPreviewResolver, Map<string, Promise<CitationPreview | null>>>()
+
+function resolvePreview(resolver: CitationPreviewResolver, citation: ReferenceNode) {
+  let cache = previewCaches.get(resolver)
+  if (!cache) {
+    cache = new Map()
+    previewCaches.set(resolver, cache)
+  }
+  const key = citation.url ?? citation.id
+  let request = cache.get(key)
+  if (!request) {
+    request = Promise.resolve(resolver(citation)).catch(() => null)
+    cache.set(key, request)
+  }
+  return request
+}
+
+function CitationHoverCard({ node }: { node: ReferenceNode }) {
+  const { onReferenceClick, resolveCitationPreview } = useContext(DocstreamRefContext)
+  const [preview, setPreview] = useState<CitationPreview | null>(null)
+  const [imageFailed, setImageFailed] = useState(false)
+  const [requested, setRequested] = useState(false)
+  const cardId = useId()
+  const host = node.url ? hostnameOf(node.url) : null
+
+  const requestPreview = () => {
+    if (!resolveCitationPreview || requested) return
+    setRequested(true)
+    void resolvePreview(resolveCitationPreview, node).then((value) => setPreview(value))
+  }
+
+  const title = preview?.title ?? node.label ?? host ?? node.url
+  const siteName = preview?.siteName ?? host
+  const favicon = preview?.favicon ?? (host ? `https://www.google.com/s2/favicons?sz=32&domain=${host}` : undefined)
+
+  return (
+    <span className="docs-cite-wrap" onMouseEnter={requestPreview} onFocus={requestPreview}>
+      <a
+        className="docs-cite"
+        href={node.url}
+        target="_blank"
+        rel="noreferrer"
+        aria-describedby={cardId}
+        onClick={() => onReferenceClick?.(node)}
+      >
+        {node.id}
+      </a>
+      <span className="docs-cite-card" id={cardId} role="tooltip">
+        {preview?.image && !imageFailed ? (
+          <span className="docs-cite-card-image-wrap">
+            <img className="docs-cite-card-image" src={preview.image} alt="" onError={() => setImageFailed(true)} />
+          </span>
+        ) : null}
+        <span className="docs-cite-card-body">
+          <span className="docs-cite-card-source">
+            {favicon ? <img className="docs-cite-card-favicon" src={favicon} alt="" /> : <Globe className="docs-cite-card-favicon" />}
+            <span>{siteName}</span>
+          </span>
+          <span className="docs-cite-card-title">{title}</span>
+          {preview?.description ? <span className="docs-cite-card-description">{preview.description}</span> : null}
+          <span className="docs-cite-card-url">
+            {node.url}
+            <ArrowUpRight aria-hidden="true" />
+          </span>
+        </span>
+      </span>
+    </span>
+  )
+}
+
 export function InlineReference({ node }: { node: ReferenceNode }) {
   const { onReferenceClick, renderReference } = useContext(DocstreamRefContext)
   const custom = renderReference?.(node)
@@ -20,18 +102,7 @@ export function InlineReference({ node }: { node: ReferenceNode }) {
   if (node.kind === "citation") {
     // Citations default to linking their source; hosts can still observe clicks.
     if (node.url) {
-      return (
-        <a
-          className="docs-cite"
-          href={node.url}
-          target="_blank"
-          rel="noreferrer"
-          title={node.label ?? node.url}
-          onClick={() => onReferenceClick?.(node)}
-        >
-          {node.id}
-        </a>
-      )
+      return <CitationHoverCard node={node} />
     }
     // Definition missing (not yet streamed, or standalone parseInline call).
     return (

package/src/index.ts

@@ -3,7 +3,7 @@ export type { PlaygroundStreamdownProps as GitbookStreamdownProps } from "./play
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
 export type { LivePreviewProps, LivePreviewRenderer, SourceReferenceRenderer } from "./docs/DocsRenderer"
 export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/reference"
-export type { DocstreamRefContextValue } from "./docs/reference"
+export type { CitationPreview, CitationPreviewResolver, DocstreamRefContextValue } from "./docs/reference"
 export { ReplayEmbed, ReplayPreview } from "./replay"
 export type {
   ReplayEventsSource,

package/src/streamdown.tsx

@@ -2,6 +2,11 @@ import { useMemo } from "react"
 import { DocsRenderer } from "./docs/DocsRenderer"
 import { parseMarkdown, trimPartialInlineToken } from "./gitbook/parse"
 
+// Re-exported so markdown-only consumers of ./streamdown can wire chip
+// click handling without importing the heavy root entry.
+export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/reference"
+export type { CitationPreview, CitationPreviewResolver, DocstreamRefContextValue } from "./docs/reference"
+
 export interface GitbookStreamdownProps {
   children?: string
   className?: string

package/src/styles.css

@@ -996,6 +996,12 @@
   color: var(--gb-accent-foreground);
 }
 
+.docs-cite-wrap {
+  position: relative;
+  display: inline-block;
+  vertical-align: super;
+}
+
 .docs-cite {
   display: inline-block;
   padding: 1px 5px;
@@ -1005,7 +1011,7 @@
   font-size: 10px;
   font-weight: 700;
   line-height: 1.4;
-  vertical-align: super;
+  vertical-align: baseline;
   text-decoration: none !important;
   cursor: pointer;
 }
@@ -1014,6 +1020,121 @@
   background: rgba(59, 130, 246, 0.22);
 }
 
+.docs-cite:focus-visible {
+  outline: 2px solid var(--gb-info);
+  outline-offset: 2px;
+}
+
+.docs-cite-card {
+  position: absolute;
+  top: calc(100% + 10px);
+  left: 50%;
+  z-index: 50;
+  display: block;
+  width: min(320px, calc(100vw - 32px));
+  overflow: hidden;
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  color: var(--gb-panel-foreground);
+  background: var(--gb-panel);
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.16), 0 2px 8px rgba(15, 23, 42, 0.08);
+  opacity: 0;
+  visibility: hidden;
+  transform: translate(-50%, -4px);
+  transition: opacity 120ms ease, transform 120ms ease, visibility 120ms;
+  pointer-events: none;
+  text-align: left;
+  white-space: normal;
+}
+
+.docs-cite-wrap:hover .docs-cite-card,
+.docs-cite-wrap:focus-within .docs-cite-card {
+  opacity: 1;
+  visibility: visible;
+  transform: translate(-50%, 0);
+}
+
+.docs-cite-card-image-wrap {
+  display: block;
+  aspect-ratio: 1.91 / 1;
+  overflow: hidden;
+  border-bottom: 1px solid var(--gb-border);
+  background: var(--gb-muted);
+}
+
+.docs-cite-card-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.docs-cite-card-body {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 14px 13px;
+}
+
+.docs-cite-card-source,
+.docs-cite-card-url {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  color: var(--gb-muted-foreground);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1.35;
+}
+
+.docs-cite-card-favicon {
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  border-radius: 3px;
+}
+
+.docs-cite-card-title {
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--gb-panel-foreground);
+  font-size: 14px;
+  font-weight: 650;
+  line-height: 1.35;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.docs-cite-card-description {
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--gb-muted-foreground);
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 1.45;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+}
+
+.docs-cite-card-url {
+  margin-top: 2px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.docs-cite-card-url svg {
+  width: 12px;
+  height: 12px;
+  flex: 0 0 auto;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docs-cite-card {
+    transition: none;
+  }
+}
+
 .docs-sources {
   display: flex;
   flex-wrap: wrap;