vocs 2.0.17 → 2.1.2

package/src/react/internal/openapi/CodeSample.client.tsx

@@ -0,0 +1,294 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import LucideCheck from '~icons/lucide/check'
+import LucideChevronDown from '~icons/lucide/chevron-down'
+import LucideChevronUp from '~icons/lucide/chevron-up'
+import LucideClipboard from '~icons/lucide/clipboard'
+import { schemaPropertyId } from '../../../internal/openapi/anchors.js'
+import type * as OpenApi from '../../../internal/openapi/index.js'
+import { CodeToHtml } from '../CodeToHtml.client.js'
+import { registerSampleAnchors, revealAnchor } from './anchor-navigation.client.js'
+
+/**
+ * The sticky right-hand panel for an operation: a request code sample with a
+ * language selector, an action slot (the `Test Request` button), and the
+ * response examples grouped by status code.
+ *
+ * Snippets are generated server-side with `@scalar/snippetz`; this component
+ * only handles tab selection and defers highlighting to Vocs's own Shiki
+ * highlighter via `CodeToHtml`. All styling lives in `openapi.css` keyed on the
+ * `data-v-openapi-sample*` attributes below.
+ */
+export function CodeSample(props: CodeSample.Props) {
+  const { samples, responses, action } = props
+  const [sampleId, setSampleId] = useState(samples[0]?.id)
+  const [status, setStatus] = useState(responses[0]?.status)
+  // When a request has many query params, the extras collapse by default.
+  const [queryExpanded, setQueryExpanded] = useState(false)
+
+  const sample = samples.find((entry) => entry.id === sampleId) ?? samples[0]
+  const response = responses.find((entry) => entry.status === status) ?? responses[0]
+
+  // Map each response to the set of schema anchor ids its example lines target,
+  // so a left-hand "Example" click can switch to the owning response tab before
+  // the matching line is revealed (see `revealResponseLine`).
+  const responseAnchors = useMemo(
+    () =>
+      responses.map((entry) => ({
+        status: entry.status,
+        ids: new Set(
+          entry.linePaths
+            .map((path) => (path ? schemaPropertyId(entry.idBase, path) : undefined))
+            .filter((value): value is string => Boolean(value)),
+        ),
+      })),
+    [responses],
+  )
+
+  // Request sample anchor ids (path + query parameters). Path params are inline
+  // spans; query params are whole lines. Both share the operation-scoped id used
+  // by the left-hand parameter rows, so a left "Example" can reveal them too.
+  // Query params beyond the collapse threshold only render once expanded, so we
+  // track which ids are hidden to expand the snippet before revealing them.
+  const requestAnchors = useMemo(() => {
+    const ids = new Set<string>()
+    const collapsedIds = new Set<string>()
+    let hasCollapsed = false
+    for (const entry of samples) {
+      for (const anchor of entry.anchors) ids.add(anchor.id)
+      for (const id of entry.lineAnchors) if (id) ids.add(id)
+      if (entry.collapsed) {
+        hasCollapsed = true
+        for (const anchor of entry.collapsed.anchors) collapsedIds.add(anchor.id)
+        for (const id of entry.collapsed.lineAnchors) if (id) collapsedIds.add(id)
+      }
+    }
+    const hiddenIds = hasCollapsed
+      ? new Set([...ids].filter((id) => !collapsedIds.has(id)))
+      : new Set<string>()
+    return { ids, hiddenIds }
+  }, [samples])
+
+  useEffect(
+    () =>
+      registerSampleAnchors({
+        has: (id) =>
+          requestAnchors.ids.has(id) || responseAnchors.some((entry) => entry.ids.has(id)),
+        select: (id) => {
+          const match = responseAnchors.find((entry) => entry.ids.has(id))
+          if (match) {
+            setStatus(match.status)
+            return
+          }
+          if (requestAnchors.hiddenIds.has(id)) setQueryExpanded(true)
+        },
+      }),
+    [responseAnchors, requestAnchors],
+  )
+
+  // Use the collapsed snippet variant (first few query params) unless expanded.
+  const view = sample?.collapsed && !queryExpanded ? sample.collapsed : sample
+
+  return (
+    <div data-v-openapi-sample>
+      {sample && view && (
+        <div data-v-openapi-sample-request>
+          <div data-v-openapi-sample-header>
+            <LanguageDropdown
+              samples={samples}
+              selected={sample}
+              onSelect={(id) => setSampleId(id)}
+            />
+            <div data-v-openapi-sample-actions>
+              <CopyButton code={sample.code} />
+              {action}
+            </div>
+          </div>
+          {/* biome-ignore lint/a11y/useKeyWithClickEvents: param spans are also reachable via copyable property anchors */}
+          {/* biome-ignore lint/a11y/noStaticElementInteractions: progressive enhancement over already-linkable property anchors */}
+          <div data-v-openapi-sample-request-body onClick={onAnchorClick}>
+            <CodeToHtml
+              code={view.display}
+              lang={sample.lang}
+              shrinkIndent={false}
+              anchorRanges={view.anchors}
+              colorRanges={view.colorRanges}
+              lineAnchors={view.lineAnchors}
+            />
+          </div>
+          {sample.collapsed && (
+            <button
+              type="button"
+              data-v-openapi-sample-more
+              onClick={() => setQueryExpanded((value) => !value)}
+            >
+              {queryExpanded ? (
+                <>
+                  <LucideChevronUp data-v-openapi-sample-more-icon />
+                  Show less
+                </>
+              ) : (
+                <>
+                  <LucideChevronDown data-v-openapi-sample-more-icon />
+                  Show {sample.hiddenQueryCount} more
+                </>
+              )}
+            </button>
+          )}
+        </div>
+      )}
+
+      {response && (
+        <div data-v-openapi-sample-response>
+          <div data-v-openapi-sample-tabs>
+            {responses.map((entry) => (
+              <Tab
+                key={entry.status}
+                active={entry.status === response.status}
+                onClick={() => setStatus(entry.status)}
+              >
+                {entry.status}
+              </Tab>
+            ))}
+          </div>
+          {/* biome-ignore lint/a11y/useKeyWithClickEvents: rows are also reachable via copyable property anchors */}
+          {/* biome-ignore lint/a11y/noStaticElementInteractions: progressive enhancement over already-linkable property anchors */}
+          <div data-v-openapi-sample-response-body onClick={onAnchorClick}>
+            <CodeToHtml
+              code={response.code}
+              lang={response.lang}
+              shrinkIndent={false}
+              dimRanges={response.placeholders}
+              lineAnchors={response.linePaths.map((path) =>
+                path ? schemaPropertyId(response.idBase, path) : undefined,
+              )}
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Navigates to the schema row matching a clicked element carrying a
+ * `data-anchor` id. Used for both response example lines (per-line anchors) and
+ * request sample path/query parameter spans (per-range anchors).
+ */
+function onAnchorClick(event: React.MouseEvent<HTMLDivElement>) {
+  // Don't hijack text selection.
+  if (window.getSelection()?.toString()) return
+  if (!(event.target instanceof Element)) return
+  const line = event.target.closest<HTMLElement>('[data-anchor]')
+  if (!line || !event.currentTarget.contains(line)) return
+  const anchor = line.dataset['anchor']
+  if (!anchor) return
+  event.preventDefault()
+  void revealAnchor(anchor)
+}
+
+/** Copies the current request sample's source to the clipboard. */
+function CopyButton(props: { code: string }) {
+  const { code } = props
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (!copied) return
+    const timeout = setTimeout(() => setCopied(false), 1000)
+    return () => clearTimeout(timeout)
+  }, [copied])
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        navigator.clipboard?.writeText(code).then(
+          () => setCopied(true),
+          () => {},
+        )
+      }}
+      data-v-openapi-action
+    >
+      {copied ? (
+        <LucideCheck data-v-openapi-action-icon data-copied />
+      ) : (
+        <LucideClipboard data-v-openapi-action-icon />
+      )}
+      Copy
+    </button>
+  )
+}
+
+/**
+ * Language selector for the request sample, rendered as a dropdown (defaulting
+ * to the first sample, i.e. cURL) rather than a row of tabs.
+ */
+function LanguageDropdown(props: {
+  samples: OpenApi.CodeSample[]
+  selected: OpenApi.CodeSample
+  onSelect: (id: string) => void
+}) {
+  const { samples, selected, onSelect } = props
+  const [open, setOpen] = useState(false)
+  if (samples.length <= 1) return <span data-v-openapi-lang-label>{selected.label}</span>
+  return (
+    <div data-v-openapi-lang>
+      <button type="button" onClick={() => setOpen((value) => !value)} data-v-openapi-lang-trigger>
+        {selected.label}
+        <LucideChevronDown data-v-openapi-lang-chevron />
+      </button>
+      {open && (
+        <>
+          <button
+            type="button"
+            aria-label="Close"
+            tabIndex={-1}
+            data-v-openapi-dropdown-backdrop
+            onClick={() => setOpen(false)}
+          />
+          <ul data-v-openapi-lang-menu>
+            {samples.map((entry) => (
+              <li key={entry.id}>
+                <button
+                  type="button"
+                  onClick={() => {
+                    onSelect(entry.id)
+                    setOpen(false)
+                  }}
+                  data-v-openapi-lang-option
+                  data-selected={entry.id === selected.id || undefined}
+                >
+                  <LucideCheck data-v-openapi-lang-option-check />
+                  <span data-v-openapi-lang-option-label>{entry.label}</span>
+                </button>
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+    </div>
+  )
+}
+
+function Tab(props: { active: boolean; onClick: () => void; children: React.ReactNode }) {
+  return (
+    <button
+      type="button"
+      onClick={props.onClick}
+      data-v-openapi-tab
+      data-active={props.active || undefined}
+    >
+      {props.children}
+    </button>
+  )
+}
+
+export declare namespace CodeSample {
+  type Props = {
+    samples: OpenApi.CodeSample[]
+    responses: OpenApi.ResponseSample[]
+    /** Action slot rendered between the request and response (the test button). */
+    action?: React.ReactNode
+  }
+}

package/src/react/internal/openapi/CollapsibleChildren.client.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+import LucidePlus from '~icons/lucide/plus'
+import LucideX from '~icons/lucide/x'
+import { Disclosure } from './Disclosure.client.js'
+
+/**
+ * Collapses nested schema properties (e.g. `error.details`) behind a toggle,
+ * matching the "Show/Hide Child Attributes" pattern from Scalar/Stripe.
+ * Built on the shared {@link Disclosure} accordion. The wrapping
+ * `data-v-openapi-collapse` element scopes the trigger/panel styling (see
+ * `openapi.css`); the Show/Hide icons and labels swap on the trigger's Base UI
+ * `data-panel-open` state.
+ */
+export function CollapsibleChildren(props: CollapsibleChildren.Props) {
+  const { children, label = 'Child Attributes' } = props
+  return (
+    <div data-v-openapi-collapse>
+      <Disclosure
+        trigger={
+          <>
+            <LucidePlus data-v-openapi-collapse-icon-show />
+            <LucideX data-v-openapi-collapse-icon-hide />
+            <span data-v-openapi-collapse-label-show>Show {label}</span>
+            <span data-v-openapi-collapse-label-hide>Hide {label}</span>
+          </>
+        }
+      >
+        {children}
+      </Disclosure>
+    </div>
+  )
+}
+
+export declare namespace CollapsibleChildren {
+  type Props = {
+    children: React.ReactNode
+    /** Text after the Show/Hide verb. @default 'Child Attributes' */
+    label?: string | undefined
+  }
+}

package/src/react/internal/openapi/Disclosure.client.tsx

@@ -0,0 +1,67 @@
+'use client'
+
+import { Accordion } from '@base-ui/react/accordion'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { registerDisclosure } from './anchor-navigation.client.js'
+
+/**
+ * A single collapsible disclosure built on the Base UI Accordion primitive,
+ * used for the toggleable sections across OpenAPI pages (nested "child
+ * attributes", responses, etc.). Collapsed by default.
+ *
+ * The panel is kept mounted so its content is always present in the DOM; this
+ * lets {@link revealAnchor} scroll to a property inside a collapsed disclosure
+ * (e.g. when clicking a response example line). The disclosure registers its
+ * panel + an `open()` callback so navigation can reveal it on demand.
+ *
+ * The trigger is a plain node so it can be passed from server components.
+ * Styling is attached via stable data attributes — `data-v-openapi-disclosure`,
+ * `-disclosure-trigger`, `-disclosure-panel` — which consumers scope by
+ * ancestor (e.g. `[data-v-openapi-response] [data-v-openapi-disclosure-trigger]`)
+ * so no Tailwind classes are passed through props. Open-state styling is driven
+ * via the Base UI `data-panel-open` attribute on the trigger.
+ */
+export function Disclosure(props: Disclosure.Props) {
+  const { trigger, defaultOpen = false, children } = props
+  const [value, setValue] = useState<string[]>(defaultOpen ? ['disclosure'] : [])
+  const panelRef = useRef<HTMLDivElement | null>(null)
+
+  const open = useCallback(() => {
+    setValue((current) => (current.includes('disclosure') ? current : ['disclosure']))
+  }, [])
+
+  useEffect(() => {
+    const panel = panelRef.current
+    if (!panel) return
+    return registerDisclosure(panel, open)
+  }, [open])
+
+  return (
+    <Accordion.Root
+      data-v-openapi-disclosure
+      value={value}
+      onValueChange={(next) => setValue(next as string[])}
+      multiple
+      keepMounted
+    >
+      <Accordion.Item value="disclosure">
+        <Accordion.Header data-v-openapi-disclosure-header>
+          <Accordion.Trigger data-v-openapi-disclosure-trigger>{trigger}</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel ref={panelRef} data-v-openapi-disclosure-panel>
+          {children}
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  )
+}
+
+export declare namespace Disclosure {
+  type Props = {
+    /** Content of the trigger button. Style open state via `data-panel-open`. */
+    trigger: React.ReactNode
+    /** @default false */
+    defaultOpen?: boolean | undefined
+    children: React.ReactNode
+  }
+}

package/src/react/internal/openapi/Endpoints.tsx

@@ -0,0 +1,58 @@
+import { specs } from 'virtual:vocs/openapi'
+import { Link } from '../../Link.js'
+import { EndpointsView } from './EndpointsView.js'
+
+/**
+ * Renders the domain/category list for an OpenAPI spec as an accordion (Vite/RSC
+ * site integration). The UI lives in the framework-agnostic
+ * {@link file://./EndpointsView.tsx `EndpointsView`}; this is the Waku adapter
+ * that resolves the spec from `virtual:vocs/openapi` and links with the Vocs
+ * `Link`.
+ *
+ * This is an opt-in component — OpenAPI landing pages no longer render the list
+ * automatically. Drop `<OpenApi.Endpoints />` into a consumer override page
+ * (e.g. `pages/api.mdx`) to surface it.
+ *
+ * The target spec is resolved from `path` (the OpenAPI mount, e.g. `/api`).
+ * When omitted, it defaults to the only configured spec; if multiple specs
+ * exist, `path` is required.
+ */
+export function Endpoints(props: Endpoints.Props) {
+  const mounts = Object.keys(specs)
+  const mount = props.path ?? (mounts.length === 1 ? mounts[0] : undefined)
+
+  if (!mount) {
+    if (mounts.length === 0) return <p>No OpenAPI spec is configured.</p>
+    return (
+      <p>
+        Multiple OpenAPI specs are configured. Pass a <code>path</code> to{' '}
+        <code>&lt;Endpoints /&gt;</code> (one of: {mounts.join(', ')}).
+      </p>
+    )
+  }
+
+  const ir = specs[mount]
+  if (!ir) return <p>No OpenAPI spec is mounted at {mount}.</p>
+
+  return (
+    <EndpointsView
+      ir={ir}
+      href={(to) => to}
+      Link={({ href, children, ...rest }) => (
+        <Link to={href ?? ''} {...rest}>
+          {children}
+        </Link>
+      )}
+    />
+  )
+}
+
+export declare namespace Endpoints {
+  type Props = {
+    /**
+     * OpenAPI mount path identifying which spec to render (e.g. `/api`).
+     * Optional when only one spec is configured.
+     */
+    path?: string | undefined
+  }
+}

package/src/react/internal/openapi/EndpointsView.tsx

@@ -0,0 +1,76 @@
+import type { ComponentType } from 'react'
+import LucideChevronRight from '~icons/lucide/chevron-right'
+import type { Ir } from '../../../internal/openapi/parser.js'
+import { methodVariant } from '../../../internal/openapi/sidebar.js'
+import { Badge } from '../../Badge.js'
+import { Disclosure } from './Disclosure.client.js'
+
+/**
+ * Prop-driven domain/category accordion for an OpenAPI spec: each category
+ * expands to its operations (method badge + summary), every entry linking to
+ * that operation's anchor on its category page.
+ *
+ * Framework-agnostic — the caller supplies the parsed {@link Ir}, an `href`
+ * mapper (so links resolve correctly under any mount), and an optional `Link`
+ * component (the Vocs/Waku `Link` for the site, a plain `<a>` for the standalone
+ * client).
+ */
+export function EndpointsView(props: EndpointsView.Props) {
+  const { ir, href, Link = DefaultLink } = props
+  // Root-mounted specs have `ir.path === '/'`; collapse it to '' so links read
+  // `/group#op` instead of `//group#op` (which the browser treats as a host).
+  const base = ir.path === '/' ? '' : ir.path.replace(/\/$/, '')
+  return (
+    <div data-v-openapi-overview>
+      {ir.groups.map((category) => (
+        <div key={category.id} data-v-openapi-overview-category>
+          <Disclosure
+            trigger={
+              <>
+                <LucideChevronRight data-v-openapi-overview-chevron />
+                <span data-v-openapi-overview-category-head>
+                  <span data-v-openapi-overview-category-name>{category.name}</span>
+                  {category.description && (
+                    <span data-v-openapi-overview-category-description>{category.description}</span>
+                  )}
+                </span>
+              </>
+            }
+          >
+            <ul data-v-openapi-overview-endpoints>
+              {category.operations.map((operation) => (
+                <li key={operation.id}>
+                  <Link
+                    href={href(`${base}/${category.id}#${operation.id}`)}
+                    data-v-openapi-overview-endpoint
+                  >
+                    <Badge variant={methodVariant(operation.method)}>{operation.method}</Badge>
+                    <span data-v-openapi-overview-endpoint-title>
+                      {operation.summary || operation.path}
+                    </span>
+                    <LucideChevronRight data-v-openapi-overview-endpoint-chevron />
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </Disclosure>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function DefaultLink(props: React.ComponentProps<'a'>) {
+  return <a {...props} />
+}
+
+export declare namespace EndpointsView {
+  type Props = {
+    /** Parsed OpenAPI spec. */
+    ir: Ir
+    /** Maps a section-relative href to a final href (e.g. mount-prefixed). */
+    href: (to: string) => string
+    /** Link component. Defaults to a plain anchor. */
+    Link?: ComponentType<React.ComponentProps<'a'>> | undefined
+  }
+}

package/src/react/internal/openapi/EnumValues.client.tsx

@@ -0,0 +1,49 @@
+'use client'
+
+import { useState } from 'react'
+import LucidePlus from '~icons/lucide/plus'
+import LucideX from '~icons/lucide/x'
+
+const previewCount = 5
+
+/**
+ * Renders a schema's enum literals as a vertical "values" list (one per row)
+ * rather than a wrapping inline union. Shows the first {@link previewCount}
+ * values and reveals the rest behind a "Show all values" toggle, matching the
+ * Scalar/Stripe reference UI.
+ */
+export function EnumValues(props: EnumValues.Props) {
+  const { values } = props
+  const [expanded, setExpanded] = useState(false)
+  const hasMore = values.length > previewCount
+  const visible = expanded ? values : values.slice(0, previewCount)
+  return (
+    <div data-v-openapi-values>
+      <span data-v-openapi-values-label>Values</span>
+      <div data-v-openapi-values-list>
+        {visible.map((value) => (
+          <code key={value} data-v-openapi-values-item>
+            {value}
+          </code>
+        ))}
+      </div>
+      {hasMore && (
+        <button type="button" onClick={() => setExpanded((value) => !value)} data-v-openapi-pill>
+          {expanded ? (
+            <LucideX data-v-openapi-pill-icon />
+          ) : (
+            <LucidePlus data-v-openapi-pill-icon />
+          )}
+          {expanded ? 'Hide values' : 'Show all values'}
+        </button>
+      )}
+    </div>
+  )
+}
+
+export declare namespace EnumValues {
+  type Props = {
+    /** Enum literal values as display strings. */
+    values: string[]
+  }
+}

package/src/react/internal/openapi/HeadingAnchor.tsx

@@ -0,0 +1,28 @@
+import LucideLink from '~icons/lucide/link'
+
+/**
+ * A copy-link anchor appended to an OpenAPI heading. Reuses the markdown
+ * `heading-anchor`/`heading-anchor-icon` classes so it inherits the same
+ * hover-reveal and "copied" styling, and is handled by the global
+ * `HeadingAnchors` client (which copies the anchor's URL on click).
+ */
+export function HeadingAnchor(props: HeadingAnchor.Props) {
+  return (
+    <a
+      href={`#${props.id}`}
+      className={`heading-anchor${props.className ? ` ${props.className}` : ''}`}
+      aria-label="Copy link and go to this section"
+      title="Copy link and go to this section"
+    >
+      <LucideLink className="heading-anchor-icon vocs:size-[0.75em]" />
+    </a>
+  )
+}
+
+export declare namespace HeadingAnchor {
+  type Props = {
+    id: string
+    /** Extra classes appended to the anchor (e.g. to override the left margin). */
+    className?: string | undefined
+  }
+}