{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "research-report", "title": "Research Report", "description": "The finished output of a deep-research run — prose whose citation numbers are derived from one walk of the data, per-section source chips, an outline that follows the reader, and a methodology footer that shows the queries run and the sources rejected.", "dependencies": [ "lucide-react", "zod" ], "registryDependencies": [ "utils" ], "files": [ { "path": "src/registry/blocks/research-report.tsx", "content": "\"use client\"\n\nimport * as React from \"react\"\nimport {\n AlertCircle,\n Ban,\n BookMarked,\n ChevronDown,\n Clock,\n FileSearch,\n FileText,\n FlaskConical,\n Globe,\n ListTree,\n Lock,\n RotateCcw,\n Search,\n ShieldAlert,\n ShieldCheck,\n ShieldQuestion,\n Sparkles,\n} from \"lucide-react\"\nimport { cn } from \"@/lib/utils\"\nimport type {\n ResearchConfidence,\n ResearchMethodology,\n ResearchReportData,\n ResearchSection,\n ResearchSource,\n ResearchSourceKind,\n} from \"./research-report.contract\"\n\n/* ------------------------------------------------------------------ citations */\n\n/**\n * The one piece of markup a paragraph may contain: `[^source-id]`. The id may not\n * contain whitespace or `]`, which is what keeps an ordinary bracket in prose\n * (\"see table [2] below\") from being swallowed as a marker.\n *\n * Two shapes of the same pattern: a capturing split (used with `String.split`, so\n * the odd indices come back as the raw markers) and a global scan (used with\n * `matchAll` to collect ids in reading order). `matchAll` does not advance the\n * literal's own `lastIndex`, so the module-level regex is safe to share.\n */\nconst CITATION_SPLIT = /(\\[\\^[^\\]\\s]+\\])/\nconst CITATION_ONE = /\\[\\^([^\\]\\s]+)\\]/\nconst CITATION_SCAN = /\\[\\^([^\\]\\s]+)\\]/g\n\n/**\n * Three treatments that stay apart without hue — solid tint, neutral fill, dashed\n * outline — and each is announced by an ICON and a WORD before colour is\n * involved, so the grade survives greyscale and a re-themed palette.\n */\nconst CONFIDENCE_META: Record = {\n high: { className: \"bg-primary/10 text-primary\", icon: ShieldCheck, label: \"High confidence\" },\n medium: { className: \"bg-muted text-foreground\", icon: ShieldAlert, label: \"Medium confidence\" },\n low: { className: \"border border-dashed text-muted-foreground\", icon: ShieldQuestion, label: \"Low confidence\" },\n}\n\nconst KIND_ICON: Record = {\n file: FileText,\n internal: Lock,\n paper: BookMarked,\n web: Globe,\n}\n\n/** Only shown when a source has no domain — it answers \"why is this one not a link?\". */\nconst KIND_LABEL: Record = {\n file: \"uploaded file\",\n internal: \"internal document\",\n paper: \"paper\",\n web: \"web page\",\n}\n\nconst BUTTON_CLASS =\n \"inline-flex cursor-pointer items-center gap-1.5 rounded-md border px-2.5 py-1.5 text-xs font-medium \" +\n \"transition-colors hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none \" +\n \"motion-reduce:transition-none\"\n\nconst LINK_CLASS =\n \"rounded-sm underline-offset-2 hover:underline focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none\"\n\ninterface CitationIndex {\n /** Report-wide citation number per source id, in first-appearance order. */\n numbers: Map\n /** Source lookup; the FIRST record wins if the pool repeats an id. */\n sources: Map\n /** Ordered, de-duplicated source ids for each section, by section index. */\n perSection: string[][]\n /** Sources in the pool that no section ever references. */\n uncited: number\n}\n\nfunction collectMarkers(section: ResearchSection): string[] {\n const ids: string[] = []\n for (const paragraph of section.paragraphs) {\n for (const match of paragraph.matchAll(CITATION_SCAN)) ids.push(match[1])\n }\n return ids\n}\n\n/**\n * ONE walk of the data produces both the inline numbers and the per-section\n * chips, which is the only reason the two can never disagree. Reading order\n * decides everything: the markers inside a section's paragraphs first, then that\n * section's marker-less `citations`, then on to the next section.\n */\nfunction buildIndex(sections: ResearchSection[], sources: ResearchSource[]): CitationIndex {\n const byId = new Map()\n for (const source of sources) if (!byId.has(source.id)) byId.set(source.id, source)\n\n const numbers = new Map()\n const perSection: string[][] = []\n\n for (const section of sections) {\n const seen = new Set()\n const list: string[] = []\n for (const id of [...collectMarkers(section), ...section.citations]) {\n // An id the pool does not contain gets no number and no chip: the marker in\n // the prose degrades instead of pointing at a source that is not there.\n if (!byId.has(id) || seen.has(id)) continue\n seen.add(id)\n list.push(id)\n if (!numbers.has(id)) numbers.set(id, numbers.size + 1)\n }\n perSection.push(list)\n }\n\n let uncited = 0\n for (const id of byId.keys()) if (!numbers.has(id)) uncited += 1\n\n return { numbers, perSection, sources: byId, uncited }\n}\n\n/* ------------------------------------------------------------------ formatting */\n\n/**\n * A source URL comes out of a crawler or a model, so `javascript:` is a live\n * possibility and must never reach the DOM. `\"\"`, whitespace and `\"#\"` mean\n * \"absent\", not \"a link that goes nowhere\".\n */\nfunction safeHref(url: string | undefined): string | null {\n const value = url?.trim()\n if (!value || value === \"#\") return null\n if (value.startsWith(\"/\")) return value\n return /^(?:https?:|mailto:)/i.test(value) ? value : null\n}\n\nfunction displayDomain(source: ResearchSource): string | null {\n const explicit = source.domain?.trim()\n if (explicit) return explicit\n const href = safeHref(source.url)\n if (!href || href.startsWith(\"/\")) return null\n try {\n return new URL(href).hostname.replace(/^www\\./, \"\") || null\n } catch {\n // Not parseable as an absolute URL — show nothing rather than a broken host.\n return null\n }\n}\n\n/** Epoch ms, or null when the instant cannot be parsed — never \"Invalid Date\". */\nfunction toMs(iso: string | undefined): number | null {\n if (!iso) return null\n const ms = Date.parse(iso)\n return Number.isFinite(ms) ? ms : null\n}\n\n/**\n * Compact run length. Deliberately not `Intl.DurationFormat` — it is not in every\n * runtime this ships to yet, and a meta bar reads better as \"4m 24s\" than as\n * \"4 minutes, 24 seconds\".\n */\nfunction formatDuration(ms: number | undefined): string | null {\n if (ms === undefined || !Number.isFinite(ms) || ms < 0) return null\n const seconds = Math.round(ms / 1000)\n if (seconds < 60) return `${seconds}s`\n const minutes = Math.floor(seconds / 60)\n if (minutes < 60) {\n const rest = seconds % 60\n return rest ? `${minutes}m ${rest}s` : `${minutes}m`\n }\n const hours = Math.floor(minutes / 60)\n const rest = minutes % 60\n return rest ? `${hours}h ${rest}m` : `${hours}h`\n}\n\n/**\n * `generatedAt` is printed in an EXPLICIT zone, never the reader's: a server\n * render and a client render must produce the same string, or hydration swaps one\n * timestamp for another.\n */\nfunction buildDateFormat(locale: string, timeZone: string): Intl.DateTimeFormat {\n for (const tag of [locale, \"en-US\"]) {\n try {\n return new Intl.DateTimeFormat(tag, { dateStyle: \"medium\", timeStyle: \"short\", timeZone })\n } catch {\n // Malformed BCP-47 tag or unknown zone — `Intl` throws RangeError; try the next fallback.\n }\n }\n return new Intl.DateTimeFormat(\"en-US\", { dateStyle: \"medium\", timeStyle: \"short\", timeZone: \"UTC\" })\n}\n\nfunction buildNumberFormat(locale: string): Intl.NumberFormat {\n try {\n return new Intl.NumberFormat(locale)\n } catch {\n // Same story: a bad tag falls back instead of throwing during render.\n return new Intl.NumberFormat(\"en-US\")\n }\n}\n\nfunction plural(count: number, noun: string, format: Intl.NumberFormat) {\n return `${format.format(count)} ${noun}${count === 1 ? \"\" : \"s\"}`\n}\n\n/** DOM ids are built from indices, never from payload ids — a source id may contain anything. */\nfunction sectionDomId(uid: string, index: number) {\n return `${uid}-s${index}`\n}\n\nfunction citationDomId(uid: string, sectionIndex: number, number: number) {\n return `${uid}-s${sectionIndex}-c${number}`\n}\n\nfunction usePrefersReducedMotion() {\n const [reduced, setReduced] = React.useState(false)\n React.useEffect(() => {\n const query = window.matchMedia(\"(prefers-reduced-motion: reduce)\")\n const update = () => setReduced(query.matches)\n update()\n query.addEventListener(\"change\", update)\n return () => query.removeEventListener(\"change\", update)\n }, [])\n return reduced\n}\n\n/* ------------------------------------------------------------------ pieces */\n\nfunction SkeletonBar({ className }: { className?: string }) {\n return
\n}\n\nfunction MethodologyPanel({\n methodology,\n numberFormat,\n uncited,\n}: {\n methodology: ResearchMethodology\n numberFormat: Intl.NumberFormat\n uncited: number\n}) {\n return (\n
\n {methodology.queries.length > 0 && (\n
\n

{`Queries run (${numberFormat.format(methodology.queries.length)})`}

\n
    \n {methodology.queries.map((query, queryIndex) => (\n
  1. \n \n {query.text}\n {query.engine && {query.engine}}\n {typeof query.results === \"number\" && Number.isFinite(query.results) && (\n \n {plural(query.results, \"hit\", numberFormat)}\n \n )}\n
    2. \n ))}\n
\n
\n )}\n\n {methodology.rejected.length > 0 && (\n
\n

\n {`Sources rejected (${numberFormat.format(methodology.rejected.length)})`}\n

\n
    \n {methodology.rejected.map(item => {\n const href = safeHref(item.url)\n const domain = item.domain?.trim()\n return (\n
  • \n \n
    \n \n {href ? (\n \n {item.title}\n \n ) : (\n item.title\n )}\n {domain && {` · ${domain}`}}\n \n {/* The reason is the whole point of this list: \"4 rejected\" is a\n number, \"rejected because it re-quotes the vendor\" is evidence. */}\n {item.reason}\n
    \n
    • \n )\n })}\n
\n
\n )}\n\n {methodology.notes && methodology.notes.length > 0 && (\n
\n

Limits

\n
    \n {methodology.notes.map((note, noteIndex) => (\n
  • \n {note}\n
    • \n ))}\n
\n
\n )}\n\n {uncited > 0 && (\n // Payload hygiene, reported rather than swallowed: sources that arrived in\n // the pool but were never referenced by any section.\n

\n {`${plural(uncited, \"source\", numberFormat)} in the payload ${uncited === 1 ? \"was\" : \"were\"} never referenced by a section.`}\n

\n )}\n
\n )\n}\n\n/* ------------------------------------------------------------------ component */\n\nexport interface ResearchReportProps\n extends ResearchReportData,\n Omit, \"children\" | \"title\"> {\n /** BCP-47 tag for the counts and the generated-at stamp. Explicit so SSR and CSR agree. */\n locale?: string\n /** IANA zone `meta.generatedAt` is printed in. The reader's zone is never guessed. */\n timeZone?: string\n /**\n * Height of the host's sticky header in px. It moves three things at once — the\n * outline's active line, the scroll target of a click, and the rail's own sticky\n * top — so they can never disagree about where \"the top\" is.\n */\n offset?: number\n /**\n * Export / share controls, rendered in the header of the READY state only. The\n * block never fakes an export: the host ships buttons that really do something.\n */\n actions?: React.ReactNode\n /** Fired after an outline click with the section's contract id. The component never writes to `location`. */\n onNavigate?: (sectionId: string) => void\n /** Omit to drop the retry affordance from the error state entirely. */\n onRetry?: () => void\n /** Start the methodology footer expanded. */\n defaultMethodologyOpen?: boolean\n /** Section placeholders in the loading state; clamped to 1–6. */\n skeletonSections?: number\n /**\n * What to do with a `[^id]` whose id is missing from `sources`: keep it as a\n * muted, inert `[?]` (default — the reader can see something was dropped), or\n * remove it from the prose entirely.\n */\n unresolvedCitations?: \"mark\" | \"hide\"\n}\n\nexport const ResearchReport = React.forwardRef(function ResearchReport(\n {\n actions,\n className,\n defaultMethodologyOpen = false,\n locale = \"en-US\",\n meta,\n methodology,\n offset = 96,\n onNavigate,\n onRetry,\n sections,\n skeletonSections = 3,\n sources,\n status,\n timeZone = \"UTC\",\n title,\n unresolvedCitations = \"mark\",\n ...props\n },\n ref,\n) {\n const uid = React.useId()\n const titleId = `${uid}-title`\n const panelId = `${uid}-methodology`\n\n const [activeSection, setActiveSection] = React.useState(0)\n const [highlighted, setHighlighted] = React.useState(null)\n const [methodologyOpen, setMethodologyOpen] = React.useState(defaultMethodologyOpen)\n\n const sectionNodes = React.useRef<(HTMLElement | null)[]>([])\n const lockedSection = React.useRef(null)\n const lockTimer = React.useRef(null)\n const reduced = usePrefersReducedMotion()\n\n const index = React.useMemo(() => buildIndex(sections, sources), [sections, sources])\n const dateFormat = React.useMemo(() => buildDateFormat(locale, timeZone), [locale, timeZone])\n const numberFormat = React.useMemo(() => buildNumberFormat(locale), [locale])\n\n // \"ready\" with nothing written is the empty panel, not an empty page with an\n // outline rail and a \"0 sources\" meta bar. A race between status and data\n // degrades to the branch that can actually be rendered.\n const branch = status === \"ready\" && sections.length === 0 ? \"empty\" : status\n // A one-section report has nothing to navigate: the rail would be a control that\n // always points at where the reader already is.\n const showOutline = branch === \"ready\" && sections.length > 1\n const activeIndex = Math.min(activeSection, Math.max(0, sections.length - 1))\n\n /**\n * Which section is being read, recomputed from rectangles on a rAF-throttled\n * scroll listener. Rect scanning rather than an IntersectionObserver band\n * because two of the three rules below describe positions where NOTHING crosses\n * a boundary — a section taller than the viewport, and the last section at the\n * bottom of the page — and those produce no observer callback at all.\n */\n React.useEffect(() => {\n if (!showOutline) return\n // Drop refs left behind by a longer previous report before anything reads them.\n sectionNodes.current.length = sections.length\n let frame = 0\n\n const resolve = () => {\n const nodes = sectionNodes.current\n if (nodes.length === 0) return\n const line = offset + 8\n\n // The last heading that has passed under the sticky header wins. That also\n // covers a section taller than the viewport: nothing has to be \"in a band\".\n let next = 0\n for (let i = 0; i < nodes.length; i += 1) {\n const node = nodes[i]\n if (node && node.getBoundingClientRect().top <= line) next = i\n }\n\n // End of the document beats both. The final section usually cannot reach the\n // line — there is no scroll distance left below it — so without this it could\n // never light up, and clicking it would bounce the highlight back one entry.\n const doc = document.documentElement\n const scrollable = doc.scrollHeight - window.innerHeight > 4\n if (scrollable && window.scrollY + window.innerHeight >= doc.scrollHeight - 4) {\n next = nodes.length - 1\n }\n if (next < 0) return\n\n // One-shot lock: a click owns the highlight until the smooth scroll it started\n // arrives, otherwise every section the page flies past would flash active on\n // the way there. Released on arrival OR by the timer — never left set.\n if (lockedSection.current !== null) {\n if (lockedSection.current !== next) return\n lockedSection.current = null\n }\n setActiveSection(next)\n }\n\n const onScroll = () => {\n if (frame) return\n frame = window.requestAnimationFrame(() => {\n frame = 0\n resolve()\n })\n }\n\n resolve()\n window.addEventListener(\"scroll\", onScroll, { passive: true })\n window.addEventListener(\"resize\", onScroll)\n return () => {\n if (frame) window.cancelAnimationFrame(frame)\n window.removeEventListener(\"scroll\", onScroll)\n window.removeEventListener(\"resize\", onScroll)\n }\n }, [offset, sections, showOutline])\n\n // The lock timer is armed from a click handler, so it outlives the effect above\n // and gets its own unmount cleanup.\n React.useEffect(\n () => () => {\n if (lockTimer.current) window.clearTimeout(lockTimer.current)\n },\n [],\n )\n\n const scrollToNode = React.useCallback(\n (node: HTMLElement) => {\n const top = node.getBoundingClientRect().top + window.scrollY - offset\n window.scrollTo({ behavior: reduced ? \"auto\" : \"smooth\", top: Math.max(0, top) })\n },\n [offset, reduced],\n )\n\n const goToSection = (target: number) => {\n const node = sectionNodes.current[target]\n const section = sections[target]\n if (!node || !section) return\n\n setActiveSection(target)\n lockedSection.current = target\n if (lockTimer.current) window.clearTimeout(lockTimer.current)\n lockTimer.current = window.setTimeout(() => {\n lockedSection.current = null\n lockTimer.current = null\n }, 1200)\n\n scrollToNode(node)\n // preventScroll, or focus() would jump instantly and cancel the smooth scroll\n // that was just started. Keyboard users still land inside the section they asked for.\n node.focus({ preventScroll: true })\n onNavigate?.(section.id)\n }\n\n const goToCitation = (chipId: string) => {\n const node = document.getElementById(chipId)\n if (!node) return\n setHighlighted(chipId)\n const rect = node.getBoundingClientRect()\n // Most chips sit one paragraph below their marker: moving the page when the\n // target is already on screen is disorienting, so only scroll when it is not.\n if (rect.top < offset || rect.bottom > window.innerHeight) scrollToNode(node)\n node.focus({ preventScroll: true })\n }\n\n /**\n * Structural rendering: the paragraph is SPLIT on the marker pattern and\n * reassembled as text nodes plus elements. Nothing is ever handed to\n * `dangerouslySetInnerHTML`, so a crawled `