vocs 2.0.17 → 2.1.2

package/src/react/internal/CodeToHtml.client.tsx

@@ -17,24 +17,74 @@ import { useEffect, useState } from 'react'
  * bundle is dynamically imported and the snippet highlighted on demand.
  */
 export function CodeToHtml(props: CodeToHtml.Props) {
-  const { code, lang } = props
-  // Initialize from the cache so a snippet that was already highlighted (e.g.
-  // pre-highlighted by the popover before opening, or shown previously) renders
-  // highlighted immediately without a plain-text flash.
-  const [html, setHtml] = useState<string | null>(() => getCached(code, lang) ?? null)
+  const {
+    anchorRanges,
+    code,
+    colorRanges,
+    dimRanges,
+    lang,
+    lineAnchors,
+    shrinkIndent = true,
+  } = props
+  const key = cacheKey(code, lang, shrinkIndent, dimRanges, lineAnchors, anchorRanges, colorRanges)
+  // Track the highlighted HTML alongside the key it was computed for. Storing
+  // the key lets us detect when `code`/`lang` change (e.g. switching the cURL /
+  // JavaScript request sample tab) and resync — otherwise the component keeps
+  // rendering the previously highlighted snippet.
+  const [state, setState] = useState<{ key: string; html: string } | null>(() => {
+    const cached = getCached(
+      code,
+      lang,
+      shrinkIndent,
+      dimRanges,
+      lineAnchors,
+      anchorRanges,
+      colorRanges,
+    )
+    return cached ? { key, html: cached } : null
+  })
+
+  // When the snippet changes, resync from the cache during render so an already
+  // highlighted snippet shows immediately without a plain-text flash.
+  if (state && state.key !== key) {
+    const cached = getCached(
+      code,
+      lang,
+      shrinkIndent,
+      dimRanges,
+      lineAnchors,
+      anchorRanges,
+      colorRanges,
+    )
+    setState(cached ? { key, html: cached } : null)
+  }
+
+  const html = state?.key === key ? state.html : null
 
   useEffect(() => {
     if (html) return
     let cancelled = false
-    highlight(code, lang)
+    highlight(code, lang, shrinkIndent, dimRanges, lineAnchors, anchorRanges, colorRanges)
       .then((result) => {
-        if (!cancelled) setHtml(result)
+        if (!cancelled)
+          setState({
+            key: cacheKey(
+              code,
+              lang,
+              shrinkIndent,
+              dimRanges,
+              lineAnchors,
+              anchorRanges,
+              colorRanges,
+            ),
+            html: result,
+          })
       })
       .catch(() => {})
     return () => {
       cancelled = true
     }
-  }, [code, lang, html])
+  }, [code, lang, shrinkIndent, dimRanges, lineAnchors, anchorRanges, colorRanges, html])
 
   if (html)
     // biome-ignore lint/security/noDangerouslySetInnerHtml: highlighted by Shiki
@@ -82,21 +132,68 @@ export namespace CodeToHtml {
   export type Props = {
     code: string
     lang: string
+    /**
+     * Whether to halve leading indentation (2 spaces → 1) for a more compact
+     * code block. Defaults to `true`; set `false` to preserve the source's
+     * indentation (e.g. for pretty-printed JSON response samples).
+     */
+    shrinkIndent?: boolean | undefined
+    /**
+     * `[start, end]` character ranges to visually dim (e.g. synthesized
+     * placeholder values in a response example). Implemented via Shiki
+     * decorations, so ranges must be non-overlapping and within bounds.
+     */
+    dimRanges?: [number, number][] | undefined
+    /**
+     * Per-line anchor ids. `lineAnchors[i]` (0-based) sets `data-anchor` on line
+     * `i`'s element so the line can be made clickable (e.g. to jump from a
+     * response example to the matching schema row).
+     */
+    lineAnchors?: (string | undefined)[] | undefined
+    /**
+     * Inline clickable spans: each `range` is a `[start, end]` character range
+     * wrapped in a `data-anchor` span pointing at `id` (e.g. path/query params
+     * in a request sample). Implemented via Shiki decorations, so ranges must be
+     * non-overlapping and within bounds.
+     */
+    anchorRanges?: { range: [number, number]; id: string }[] | undefined
+    /**
+     * `[start, end]` character ranges to recolor with a semantic token color:
+     * `'key'` uses the JSON-string color and `'value'` the JSON-number color (as
+     * captured from the active Shiki theme). Used to make request-sample query
+     * parameter names/values read like the JSON response example. Ranges must be
+     * non-overlapping and within bounds.
+     */
+    colorRanges?: { range: [number, number]; kind: 'key' | 'value' }[] | undefined
   }
 }
 
 let highlighterPromise:
   | Promise<{
-      codeToHtml: (code: string, lang: string) => Promise<string>
+      codeToHtml: (
+        code: string,
+        lang: string,
+        shrinkIndent: boolean,
+        dimRanges?: [number, number][] | undefined,
+        lineAnchors?: (string | undefined)[] | undefined,
+        anchorRanges?: { range: [number, number]; id: string }[] | undefined,
+        colorRanges?: { range: [number, number]; kind: 'key' | 'value' }[] | undefined,
+      ) => Promise<string>
     }>
   | undefined
 
 function getHighlighter() {
   if (!highlighterPromise)
     highlighterPromise = (async () => {
-      const { bundledLanguages, createHighlighter, hastToHtml } = await import('shiki/bundle/web')
+      const [{ bundledLanguages, createHighlighter, hastToHtml }, { langs }] = await Promise.all([
+        import('shiki/bundle/web'),
+        import('virtual:vocs/langs'),
+      ])
       const { codeHighlight } = config
       const { langAlias = {}, themes } = codeHighlight
+      const extraLanguages = new Map(
+        langs.flatMap((lang) => [lang.name, ...(lang.aliases ?? [])].map((name) => [name, lang])),
+      )
       // Note: `langAlias` is intentionally not passed to the highlighter.
       // Passing a custom `langAlias` registers languages under their alias name
       // when lazily loaded (e.g. `loadLanguage('ts')` registers as `ts` instead
@@ -106,19 +203,67 @@ function getHighlighter() {
         themes: Object.values(themes) as never,
         langs: [],
       })
+      // Capture the active theme's JSON property-name/number colors once and
+      // expose them as CSS variables, so request samples can recolor query/path
+      // parameter names/values to match the JSON response example (openapi.css).
+      void applyTokenColors(highlighter, themes)
       return {
-        async codeToHtml(code: string, lang: string) {
+        async codeToHtml(
+          code: string,
+          lang: string,
+          shrinkIndent: boolean,
+          dimRanges?: [number, number][] | undefined,
+          lineAnchors?: (string | undefined)[] | undefined,
+          anchorRanges?: { range: [number, number]; id: string }[] | undefined,
+          colorRanges?: { range: [number, number]; kind: 'key' | 'value' }[] | undefined,
+        ) {
           const base = langAlias[lang] ?? lang
-          const resolvedLang = base in bundledLanguages ? base : 'txt'
-          if (!highlighter.getLoadedLanguages().includes(resolvedLang))
-            await highlighter.loadLanguage(resolvedLang as never)
+          const extraLanguage = extraLanguages.get(base)
+          const resolvedLang = base in bundledLanguages ? base : (extraLanguage?.name ?? 'txt')
+          if (!highlighter.getLoadedLanguages().includes(resolvedLang)) {
+            if (extraLanguage) await highlighter.loadLanguage(extraLanguage)
+            else await highlighter.loadLanguage(resolvedLang as never)
+          }
+          // Clamp/validate ranges so a bad offset can't throw inside Shiki.
+          const decorations = [
+            ...(dimRanges ?? [])
+              .filter(([start, end]) => start >= 0 && end <= code.length && start < end)
+              .map(([start, end]) => ({
+                start,
+                end,
+                properties: { 'data-v-openapi-placeholder': '' },
+              })),
+            ...(anchorRanges ?? [])
+              .filter(({ range: [start, end] }) => start >= 0 && end <= code.length && start < end)
+              .map(({ range: [start, end], id }) => ({
+                start,
+                end,
+                // Path parameter values are always values → color them blue.
+                properties: {
+                  'data-anchor': id,
+                  'data-v-openapi-anchor': '',
+                  'data-v-openapi-token': 'value',
+                },
+              })),
+            ...(colorRanges ?? [])
+              .filter(({ range: [start, end] }) => start >= 0 && end <= code.length && start < end)
+              .map(({ range: [start, end], kind }) => ({
+                start,
+                end,
+                properties: { 'data-v-openapi-token': kind },
+              })),
+          ]
           const hast = highlighter.codeToHast(code, {
             defaultColor: 'light-dark()',
             lang: resolvedLang,
             rootStyle: false,
             meta: { 'data-v-overflow-fade': true },
             themes,
-            transformers: [transformerShrinkIndent()],
+            transformers: [
+              ...(shrinkIndent ? [transformerShrinkIndent()] : []),
+              ...(lineAnchors ? [transformerLineAnchors(lineAnchors)] : []),
+            ],
+            ...(decorations.length > 0 ? { decorations } : {}),
           })
           const pre = hast.children[0]
           if (pre && pre.type === 'element' && pre.tagName === 'pre')
@@ -137,22 +282,60 @@ function getHighlighter() {
 
 const cache = new Map<string, string>()
 
-function cacheKey(code: string, lang: string) {
-  return `${lang}\n${code}`
+function cacheKey(
+  code: string,
+  lang: string,
+  shrinkIndent = true,
+  dimRanges?: [number, number][] | undefined,
+  lineAnchors?: (string | undefined)[] | undefined,
+  anchorRanges?: { range: [number, number]; id: string }[] | undefined,
+  colorRanges?: { range: [number, number]; kind: 'key' | 'value' }[] | undefined,
+) {
+  const ranges = dimRanges && dimRanges.length > 0 ? JSON.stringify(dimRanges) : ''
+  const anchors = lineAnchors && lineAnchors.length > 0 ? JSON.stringify(lineAnchors) : ''
+  const spans = anchorRanges && anchorRanges.length > 0 ? JSON.stringify(anchorRanges) : ''
+  const colors = colorRanges && colorRanges.length > 0 ? JSON.stringify(colorRanges) : ''
+  return `${lang}\n${shrinkIndent ? '1' : '0'}\n${ranges}\n${anchors}\n${spans}\n${colors}\n${code}`
 }
 
 /** Returns the highlighted HTML for a snippet if it has already been computed. */
-export function getCached(code: string, lang: string) {
-  return cache.get(cacheKey(code, lang))
+export function getCached(
+  code: string,
+  lang: string,
+  shrinkIndent = true,
+  dimRanges?: [number, number][] | undefined,
+  lineAnchors?: (string | undefined)[] | undefined,
+  anchorRanges?: { range: [number, number]; id: string }[] | undefined,
+  colorRanges?: { range: [number, number]; kind: 'key' | 'value' }[] | undefined,
+) {
+  return cache.get(
+    cacheKey(code, lang, shrinkIndent, dimRanges, lineAnchors, anchorRanges, colorRanges),
+  )
 }
 
 /** Highlights a snippet (memoized), loading the Shiki bundle on first use. */
-export async function highlight(code: string, lang: string) {
-  const key = cacheKey(code, lang)
+export async function highlight(
+  code: string,
+  lang: string,
+  shrinkIndent = true,
+  dimRanges?: [number, number][] | undefined,
+  lineAnchors?: (string | undefined)[] | undefined,
+  anchorRanges?: { range: [number, number]; id: string }[] | undefined,
+  colorRanges?: { range: [number, number]; kind: 'key' | 'value' }[] | undefined,
+) {
+  const key = cacheKey(code, lang, shrinkIndent, dimRanges, lineAnchors, anchorRanges, colorRanges)
   const cached = cache.get(key)
   if (cached !== undefined) return cached
   const highlighter = await getHighlighter()
-  const html = await highlighter.codeToHtml(code, lang)
+  const html = await highlighter.codeToHtml(
+    code,
+    lang,
+    shrinkIndent,
+    dimRanges,
+    lineAnchors,
+    anchorRanges,
+    colorRanges,
+  )
   cache.set(key, html)
   return html
 }
@@ -162,6 +345,84 @@ export function prewarm() {
   void getHighlighter()
 }
 
+function transformerLineAnchors(lineAnchors: readonly (string | undefined)[]) {
+  return {
+    name: 'line-anchors',
+    // Shiki's `line` hook is 1-based.
+    line(hast: { properties?: Record<string, unknown> }, line: number) {
+      const anchor = lineAnchors[line - 1]
+      if (!anchor) return
+      hast.properties ??= {}
+      hast.properties['data-anchor'] = anchor
+    },
+  }
+}
+
+/**
+ * Highlights a tiny probe JSON snippet to read the active theme's token colors,
+ * then exposes them as CSS variables on `:root` so request samples can recolor
+ * query/path parameter names/values to match the JSON response example: names
+ * use the JSON property-name color (green in the default dark theme) and values
+ * the JSON number color (blue). The captured values are `light-dark()` pairs, so
+ * both color schemes match the response example. Runs once per highlighter;
+ * failures are silent (CSS falls back to `--vocs-color-green`/`--vocs-color-blue`).
+ */
+async function applyTokenColors(
+  highlighter: {
+    getLoadedLanguages: () => string[]
+    loadLanguage: (lang: never) => Promise<unknown>
+    codeToHast: (code: string, options: never) => unknown
+  },
+  themes: Record<string, unknown>,
+) {
+  if (typeof document === 'undefined') return
+  try {
+    if (!highlighter.getLoadedLanguages().includes('json'))
+      await highlighter.loadLanguage('json' as never)
+    const hast = highlighter.codeToHast('{ "a": "abc", "b": 123 }', {
+      defaultColor: 'light-dark()',
+      lang: 'json',
+      themes,
+    } as never) as HastRoot
+    // Names use the JSON property-name color (`"a"`); values the number color
+    // (`123`). In the default dark theme these are green and blue respectively.
+    const colors: { key?: string; value?: string } = {}
+    walkHast(hast, (text, style) => {
+      const color = style.match(/color:\s*([^;]+)/)?.[1]?.trim()
+      if (!color) return
+      if (text === '"a"') colors.key ??= color
+      else if (text === '123') colors.value ??= color
+    })
+    const root = document.documentElement
+    if (colors.key) root.style.setProperty('--vocs-openapi-token-key', colors.key)
+    if (colors.value) root.style.setProperty('--vocs-openapi-token-value', colors.value)
+  } catch {}
+}
+
+type HastNode = {
+  type: string
+  tagName?: string
+  value?: string
+  properties?: Record<string, unknown>
+  children?: HastNode[]
+}
+type HastRoot = { children?: HastNode[] }
+
+/** Visits every text-bearing span in a hast tree with its text and inline style. */
+function walkHast(node: HastNode | HastRoot, visit: (text: string, style: string) => void) {
+  const children = (node as HastNode).children
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      if (child.type === 'element' && child.tagName === 'span') {
+        const text = child.children?.[0]?.value
+        const style = child.properties?.['style']
+        if (typeof text === 'string' && typeof style === 'string') visit(text, style)
+      }
+      walkHast(child, visit)
+    }
+  }
+}
+
 function transformerShrinkIndent() {
   return {
     name: 'indent',

package/src/react/internal/Sidebar.tsx

@@ -14,6 +14,76 @@ import { useSidebar } from '../useSidebar.js'
 
 const maxDepth = 5
 
+/** Active in-page anchor id, for hash-link sidebar items (e.g. OpenAPI). */
+const ActiveAnchorContext = React.createContext<string | null>(null)
+
+/** Whether any sidebar item links to an in-page anchor. */
+function hasHashLink(items: Sidebar_core.SidebarItem[]): boolean {
+  return items.some((item) => item.link?.includes('#') || (item.items && hasHashLink(item.items)))
+}
+
+/**
+ * Tracks the in-page section currently in view, so hash-link sidebar items
+ * (used by the OpenAPI section) can show active state. Mirrors the Outline's
+ * IntersectionObserver approach.
+ */
+function useActiveAnchor(enabled: boolean, path: string): string | null {
+  const [activeId, setActiveId] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return
+
+    // Reset on every client-side navigation: derive the active section from the
+    // hash of the destination `path` (landing pages like the OpenAPI section
+    // root have none, so they start with no active section). Reading `path`
+    // here — rather than only `window.location` — keeps it a genuine effect
+    // dependency so navigation reliably re-runs this.
+    const hashFromPath = path.includes('#') ? path.slice(path.indexOf('#') + 1) : ''
+    const hash = hashFromPath || (window.location.hash ? window.location.hash.slice(1) : '')
+    setActiveId(hash || null)
+
+    // OpenAPI pages render inside `article[data-v-content]` too, so the generic
+    // markdown selector would also match operation sub-headings (Parameters,
+    // Responses, schema anchors, …) whose ids have no sidebar entry — hijacking
+    // the active anchor as you scroll through a section. On those pages observe
+    // only the group header (`<h1>`) and per-operation titles, which back the
+    // hash-link sidebar items, so the active item persists across the section.
+    const isOpenApi = document.querySelector('[data-v-openapi]') !== null
+    const selector = isOpenApi
+      ? '[data-v-openapi-h1][id], [data-v-openapi-operation-title][id]'
+      : 'article[data-v-content] :is(h2, h3, h4, h5, h6)[id]'
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries)
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id)
+            break
+          }
+      },
+      { rootMargin: '0px 0px -80% 0px' },
+    )
+
+    const observeAll = () => {
+      observer.disconnect()
+      for (const element of document.querySelectorAll(selector)) observer.observe(element)
+    }
+    observeAll()
+
+    const content =
+      document.querySelector('article[data-v-content]') ??
+      document.querySelector('[data-v-openapi]')
+    const mutation = content ? new MutationObserver(observeAll) : null
+    if (content && mutation) mutation.observe(content, { childList: true, subtree: true })
+
+    return () => {
+      observer.disconnect()
+      mutation?.disconnect()
+    }
+  }, [enabled, path])
+
+  return activeId
+}
+
 export function Sidebar(props: Sidebar.Props) {
   const { className, onNavigate, scrollRef } = props
 
@@ -22,26 +92,31 @@ export function Sidebar(props: Sidebar.Props) {
     () => Sidebar_core.length(sidebar.items, { startDepth: 2 }) > 25,
     [sidebar.items],
   )
+  const hashLinks = React.useMemo(() => hasHashLink(sidebar.items), [sidebar.items])
+  const { path } = useRouter()
+  const activeAnchor = useActiveAnchor(hashLinks, path)
 
   return (
-    <nav
-      className={cx(
-        "vocs:flex-1 vocs:flex vocs:flex-col vocs:text-sm vocs:font-[450] vocs:[&>*:not(:last-child)[data-collapsed='false']]:mb-4",
-        className,
-      )}
-      data-v-sidebar
-    >
-      {sidebar.backLink && <BackLink onNavigate={onNavigate} />}
-      {sidebar.items.map((item, i) => (
-        <Section
-          key={`${item.text}-${i}`}
-          {...item}
-          condensed={condenseSidebar}
-          onNavigate={onNavigate}
-          scrollRef={scrollRef}
-        />
-      ))}
-    </nav>
+    <ActiveAnchorContext.Provider value={activeAnchor}>
+      <nav
+        className={cx(
+          "vocs:flex-1 vocs:flex vocs:flex-col vocs:text-sm vocs:font-[450] vocs:[&>*:not(:last-child)[data-collapsed='false']]:mb-4",
+          className,
+        )}
+        data-v-sidebar
+      >
+        {sidebar.backLink && <BackLink onNavigate={onNavigate} />}
+        {sidebar.items.map((item, i) => (
+          <Section
+            key={`${item.text}-${i}`}
+            {...item}
+            condensed={condenseSidebar}
+            onNavigate={onNavigate}
+            scrollRef={scrollRef}
+          />
+        ))}
+      </nav>
+    </ActiveAnchorContext.Provider>
   )
 }
 
@@ -99,10 +174,21 @@ function Item(props: Item.Props) {
 
   const { path } = useRouter()
   const isExternal = external ?? Path.isExternal(link)
-  const active = React.useMemo(
-    () => (isExternal ? false : Path.matches(path, link)),
-    [path, link, isExternal],
-  )
+  const activeAnchor = React.useContext(ActiveAnchorContext)
+  const hashId = link?.includes('#') ? link.split('#')[1] : undefined
+  const active = React.useMemo(() => {
+    if (isExternal) return false
+    if (hashId) return hashId === activeAnchor
+    if (!Path.matches(path, link)) return false
+    // Page-level item (e.g. the OpenAPI "Overview"). When in-page anchor
+    // tracking is active, only highlight it while viewing the top of the page —
+    // i.e. when the active section is the page's top heading (whose id matches
+    // the last path segment) or no section is active yet. Otherwise the matching
+    // anchor item below it is highlighted instead.
+    if (activeAnchor == null) return true
+    const topId = (link?.split('#')[0] ?? '').split('/').filter(Boolean).pop()
+    return activeAnchor === topId
+  }, [path, link, isExternal, hashId, activeAnchor])
 
   const itemRef = React.useRef<HTMLElement>(null)
   const prevPath = React.useRef(path)
@@ -135,6 +221,24 @@ function Item(props: Item.Props) {
     })
   }, [link, path, scrollRef])
 
+  // Keep the active in-page anchor item (OpenAPI endpoints) visible as the page
+  // scrolls, since `path` doesn't change between same-page anchors.
+  React.useEffect(() => {
+    if (!active || !hashId) return
+    const item = itemRef.current
+    const container = scrollRef?.current
+    if (!item || !container) return
+
+    const itemTop = item.offsetTop
+    const itemBottom = itemTop + item.offsetHeight
+    const containerScrollTop = container.scrollTop
+    const containerHeight = container.clientHeight
+
+    if (itemTop >= containerScrollTop && itemBottom <= containerScrollTop + containerHeight) return
+
+    container.scrollTo({ behavior: 'smooth', top: itemTop - 100 })
+  }, [active, hashId, scrollRef])
+
   if (link && !disabled) {
     if (isExternal)
       return (