vocs 2.0.17 → 2.1.2

package/src/react/internal/openapi/anchor-navigation.client.ts

@@ -0,0 +1,154 @@
+'use client'
+
+/**
+ * Client-side coordination for navigating to a schema property row from a
+ * response example line (or a copied property link). Left-hand schema rows live
+ * inside collapsed Base UI accordions; because those panels are kept mounted,
+ * the target element is always in the DOM. Each {@link Disclosure} registers its
+ * panel element and an `open()` callback here, so navigation can reveal every
+ * collapsed ancestor of a target before scrolling to it.
+ */
+
+type Registration = {
+  panel: HTMLElement
+  open: () => void
+}
+
+const disclosures = new Set<Registration>()
+
+/** Registers a disclosure panel so it can be auto-opened during navigation. */
+export function registerDisclosure(panel: HTMLElement, open: () => void): () => void {
+  const registration: Registration = { panel, open }
+  disclosures.add(registration)
+  return () => {
+    disclosures.delete(registration)
+  }
+}
+
+/**
+ * A code sample's anchor registration: `has(id)` reports whether the sample
+ * renders a line/span anchored to `id` (a response example line, or a request
+ * sample path/query parameter), and `select(id)` reveals it — switching to the
+ * owning response tab and/or expanding collapsed query parameters as needed.
+ */
+type SampleRegistration = {
+  has: (id: string) => boolean
+  select: (id: string) => void
+}
+
+const sampleRegistrations = new Set<SampleRegistration>()
+const sampleListeners = new Set<() => void>()
+
+/**
+ * Registers a code sample's anchors so a left-hand "Example" click can (a) tell
+ * whether a matching right-hand line exists ({@link hasSampleLine}) and (b)
+ * reveal it ({@link revealSampleLine}) by switching response tabs / expanding
+ * collapsed query parameters first.
+ */
+export function registerSampleAnchors(registration: SampleRegistration): () => void {
+  sampleRegistrations.add(registration)
+  for (const listener of sampleListeners) listener()
+  return () => {
+    sampleRegistrations.delete(registration)
+    for (const listener of sampleListeners) listener()
+  }
+}
+
+/** Whether any registered code sample renders a line/span anchored to `id`. */
+export function hasSampleLine(id: string): boolean {
+  for (const registration of sampleRegistrations) if (registration.has(id)) return true
+  return false
+}
+
+/**
+ * Subscribes to sample-anchor registration changes (for `useSyncExternalStore`
+ * so a left-hand "Example" can reactively gain its clickable affordance once the
+ * sibling code sample has mounted and registered).
+ */
+export function subscribeSampleAnchors(listener: () => void): () => void {
+  sampleListeners.add(listener)
+  return () => {
+    sampleListeners.delete(listener)
+  }
+}
+
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()))
+}
+
+/**
+ * Reveals and scrolls to the element with the given id, opening any registered
+ * disclosure panels that contain it first. Returns `false` if no such element
+ * exists.
+ */
+export async function revealAnchor(
+  id: string,
+  options: { updateHash?: boolean; behavior?: ScrollBehavior } = {},
+): Promise<boolean> {
+  const target = document.getElementById(id)
+  if (!target) return false
+
+  for (const disclosure of disclosures) if (disclosure.panel.contains(target)) disclosure.open()
+
+  // Let controlled accordions commit their open state (mount/reveal) before
+  // measuring scroll position.
+  await nextFrame()
+  await nextFrame()
+
+  const resolved = document.getElementById(id)
+  if (!resolved) return false
+
+  resolved.scrollIntoView({ block: 'start', behavior: options.behavior ?? 'smooth' })
+  if (options.updateHash !== false) history.pushState(null, '', `#${id}`)
+  flash(resolved)
+  return true
+}
+
+/**
+ * The reverse of {@link revealAnchor}: from a left-hand schema/parameter row,
+ * reveal and flash the matching line in the right-hand code sample (a response
+ * example line, or a request-sample path/query parameter). Switches to the
+ * owning response tab and/or expands collapsed query parameters first. Returns
+ * `false` when no matching line exists (e.g. request-body properties, which the
+ * samples don't anchor).
+ */
+export async function revealSampleLine(id: string): Promise<boolean> {
+  // Reveal the line in the right-hand panel (switch response tab / expand query
+  // params) before querying for it (no-op when it is already visible).
+  for (const registration of sampleRegistrations)
+    if (registration.has(id)) {
+      registration.select(id)
+      break
+    }
+
+  // Let the tab switch / expansion commit before querying for the line.
+  await nextFrame()
+  await nextFrame()
+
+  const selector = `[data-v-openapi-sample] [data-anchor="${cssEscape(id)}"]`
+  const target = document.querySelector<HTMLElement>(selector)
+  if (!target) return false
+
+  target.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+  flash(target)
+  return true
+}
+
+/** Escapes a string for safe use in a CSS attribute selector. */
+function cssEscape(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(value)
+  return value.replace(/["\\]/g, '\\$&')
+}
+
+/**
+ * Briefly highlights an element. Mirrors the `:target` flash used when clicking
+ * an anchor link, which `history.pushState` cannot trigger (and which never
+ * re-fires when navigating to the same id twice). Toggling a data attribute —
+ * with a forced reflow in between — restarts the CSS animation every time.
+ */
+function flash(element: HTMLElement): void {
+  element.removeAttribute('data-v-openapi-flash')
+  // Force a reflow so the animation restarts even if the attribute persists.
+  void element.offsetWidth
+  element.setAttribute('data-v-openapi-flash', '')
+}

package/src/react/internal/openapi/auth.ts

@@ -0,0 +1,69 @@
+/**
+ * Client-side persistence for the OpenAPI playground's authentication.
+ *
+ * The source of truth is Scalar's own auth UI inside the "Try" modal: whenever
+ * the consumer edits credentials there, the
+ * {@link file://./Playground.client.tsx playground provider} captures Scalar's
+ * exported auth state and persists it here (keyed per spec mount). Every other
+ * playground instance — on other pages of the same section, or after a reload —
+ * reads it back and loads it into its Scalar store, so a credential entered once
+ * in any "Try" applies everywhere.
+ *
+ * The persisted value is an opaque JSON string (Scalar's `auth.export()` /
+ * `auth.load()` shape); we never interpret it. The value lives in
+ * `localStorage` so it survives reloads, and everything is guarded for SSR (no
+ * `window`) and degrades to a no-op when storage is unavailable (private mode,
+ * blocked cookies).
+ */
+
+const prefix = 'vocs:openapi-auth:'
+const eventName = 'vocs:openapi-auth-change'
+
+function storageKey(mount: string) {
+  return prefix + (mount || '/')
+}
+
+/** Read the persisted auth blob for a mount (`null` when none/SSR). */
+export function read(mount: string): string | null {
+  if (typeof window === 'undefined') return null
+  try {
+    return window.localStorage.getItem(storageKey(mount))
+  } catch {
+    return null
+  }
+}
+
+/** Persist the auth blob for a mount and notify listeners (this tab + others). */
+export function write(mount: string, value: string | null): void {
+  if (typeof window === 'undefined') return
+  try {
+    if (value) window.localStorage.setItem(storageKey(mount), value)
+    else window.localStorage.removeItem(storageKey(mount))
+  } catch {}
+  // `storage` events only fire in *other* tabs, so dispatch our own for the
+  // current document (other playground instances on the page listen for it).
+  try {
+    window.dispatchEvent(new CustomEvent(eventName, { detail: { mount } }))
+  } catch {}
+}
+
+/**
+ * Subscribe to auth changes for a mount. Fires on same-tab writes (via the
+ * custom event) and cross-tab writes (via the native `storage` event). Returns
+ * an unsubscribe function.
+ */
+export function subscribe(mount: string, callback: () => void): () => void {
+  if (typeof window === 'undefined') return () => {}
+  const onCustom = (event: Event) => {
+    if ((event as CustomEvent<{ mount?: string }>).detail?.mount === mount) callback()
+  }
+  const onStorage = (event: StorageEvent) => {
+    if (event.key === storageKey(mount)) callback()
+  }
+  window.addEventListener(eventName, onCustom)
+  window.addEventListener('storage', onStorage)
+  return () => {
+    window.removeEventListener(eventName, onCustom)
+    window.removeEventListener('storage', onStorage)
+  }
+}

package/src/react/useLayout.ts

@@ -5,6 +5,8 @@ import { useSidebar } from './useSidebar.js'
 
 export type LayoutState = {
   layout: 'full' | 'minimal' | 'blank'
+  /** Content width: `default` (centered, readable) or `full` (full-bleed). */
+  contentWidth: 'default' | 'full'
   showAskAi: boolean
   showLogo: boolean
   showOutline: boolean
@@ -21,9 +23,11 @@ export function useLayout(): LayoutState {
 
   const layout = frontmatter?.layout ?? 'full'
   const outline = frontmatter?.outline
+  const contentWidth = frontmatter?.content?.width ?? 'default'
 
   return {
     layout,
+    contentWidth,
     get showSidebar() {
       if (frontmatter?.showSidebar !== undefined) return frontmatter.showSidebar
       if (sidebar.items.length === 0) return false

package/src/server/handlers.ts

@@ -1,10 +1,29 @@
-import { ImageResponse } from '@takumi-rs/image-response/wasm'
-// @ts-expect-error
-import wasm from '@takumi-rs/wasm/takumi_wasm_bg.wasm?url'
-
+/// <reference types="vite/client" />
 import * as Config from '../internal/config.js'
-// @ts-expect-error
-import font from './fonts/geist.woff2?arraybuffer'
+
+export { compose, openApi } from './openapi/handler.js'
+
+/**
+ * Loads the Vite-only OG assets (takumi wasm + font) via a Vite
+ * `import.meta.glob` trampoline.
+ *
+ * Vite implements `import.meta.glob` and rewrites it into a dynamic import of
+ * `./og-assets`, processing its `?url`/`?arraybuffer` asset imports normally.
+ * Bundlers that don't implement the macro (esbuild/Wrangler) leave the call
+ * untouched and never follow `./og-assets`, so importing the `vocs/server`
+ * barrel for `Handler.openApi` stays edge-safe. The glob is only evaluated when
+ * `og().fetch` actually runs, so the indirection costs non-Vite consumers
+ * nothing unless they call `Handler.og`.
+ */
+async function loadOgAssets(): Promise<typeof import('./og-assets.js')> {
+  const modules = import.meta.glob('./og-assets.{js,ts}')
+  const load = modules['./og-assets.js'] ?? modules['./og-assets.ts']
+  if (!load)
+    throw new Error(
+      '[vocs] `Handler.og` requires the Vocs/Vite build pipeline (the OG image assets are Vite transforms).',
+    )
+  return (await load()) as typeof import('./og-assets.js')
+}
 
 type Handler = {
   fetch: (request: Request) => Promise<Response>
@@ -35,6 +54,12 @@ type Handler = {
 export function og(render: (props: og.Props) => React.JSX.Element): Handler {
   return {
     fetch: async (request) => {
+      // Loaded lazily via a Vite glob trampoline (see `loadOgAssets`) so plain
+      // Node/edge consumers of `vocs/server` — e.g. `Handler.openApi` — can
+      // import the namespace without their bundler following the Vite-only
+      // takumi/font asset imports.
+      const { ImageResponse, wasm, font } = await loadOgAssets()
+
       const url = new URL(request.url)
       const config = await Config.resolve({ server: true })
 

package/src/server/og-assets.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+// Vite-only asset module. These specifiers (`?url`, `?arraybuffer`) are Vite
+// transforms, so this file is loaded indirectly via `import.meta.glob` in
+// `handlers.ts` rather than imported directly. That keeps non-Vite bundlers
+// (esbuild/Wrangler) from following these asset imports when they only import
+// the `vocs/server` barrel for `Handler.openApi`.
+
+export { ImageResponse } from '@takumi-rs/image-response/wasm'
+
+import wasm from '@takumi-rs/wasm/takumi_wasm_bg.wasm?url'
+import font from './fonts/geist.woff2?arraybuffer'
+
+export { font, wasm }