@scalar/astro 0.2.19 → 0.3.0

package/package.json

@@ -17,7 +17,7 @@
     "openapi",
     "swagger"
   ],
-  "version": "0.2.19",
+  "version": "0.3.0",
   "engines": {
     "node": ">=22"
   },
@@ -27,6 +27,8 @@
   },
   "files": [
     "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
     "index.ts"
   ],
   "readme": {
@@ -45,7 +47,7 @@
     "documentation": "https://scalar.com/products/api-references/integrations/astro"
   },
   "dependencies": {
-    "@scalar/client-side-rendering": "0.1.12"
+    "@scalar/client-side-rendering": "0.1.13"
   },
   "devDependencies": {
     "astro": "^4.0.0 || ^5.0.0 || ^6.0.0"
@@ -54,6 +56,7 @@
     "astro": "^4.0.0 || ^5.0.0"
   },
   "scripts": {
-    "dev": "cd playground && pnpm dev"
+    "dev": "cd playground && pnpm dev",
+    "test": "vitest --run"
   }
 }

package/src/ScalarClient.astro

@@ -0,0 +1,18 @@
+---
+import { getConfiguration, type HtmlRenderingConfiguration } from '@scalar/client-side-rendering'
+
+interface Props {
+  config: Omit<Partial<HtmlRenderingConfiguration>, 'cdn' | 'pageTitle'>
+  cdn?: string
+}
+
+const { config, cdn } = Astro.props
+---
+
+<div data-scalar-client data-configuration={JSON.stringify(getConfiguration(config))} data-cdn={cdn}></div>
+
+<script>
+  import { initScalarClient } from './client'
+
+  initScalarClient()
+</script>

package/src/ScalarComponent.astro

@@ -1,8 +1,21 @@
 ---
 import { renderApiReference, type HtmlRenderingConfiguration } from '@scalar/client-side-rendering'
 
+import ScalarClient from './ScalarClient.astro'
+
 export interface Props {
   configuration: Partial<HtmlRenderingConfiguration>
+  /**
+   * How the API reference is rendered.
+   *
+   * - `'static'` (default) renders a full HTML document ahead of time. Its
+   *   embedded script only runs on a hard page load.
+   * - `'client'` renders an empty container and mounts Scalar in the browser,
+   *   re-mounting around Astro view-transition events. Use this on Starlight
+   *   pages and other Astro sites with client-side navigation, where the
+   *   static script would otherwise only render after a manual refresh.
+   */
+  renderMode?: 'static' | 'client'
 }
 
 /**
@@ -13,18 +26,19 @@ const DEFAULT_CONFIGURATION: Partial<HtmlRenderingConfiguration> = {
   // _integration: 'astro',
 }
 
-const { configuration } = Astro.props
+const { configuration, renderMode = 'static' } = Astro.props
 
 const finalConfiguration = {
   ...DEFAULT_CONFIGURATION,
   ...configuration,
 }
 const { cdn, pageTitle, ...config } = finalConfiguration
-const html = renderApiReference({
-  config,
-  cdn,
-  pageTitle,
-})
 ---
 
-<div set:html={html}></div>
+{
+  renderMode === 'client' ? (
+    <ScalarClient config={config} cdn={cdn} />
+  ) : (
+    <div set:html={renderApiReference({ config, cdn, pageTitle })} />
+  )
+}

package/src/client.ts

@@ -0,0 +1,253 @@
+/**
+ * Client-side mounting for `<ScalarComponent renderMode="client" />`.
+ *
+ * Instead of a pre-rendered HTML document, the component renders an empty
+ * `[data-scalar-client]` container. This module loads the Scalar standalone
+ * bundle from the CDN and mounts the API reference into that container in the
+ * browser.
+ *
+ * Most importantly, it re-mounts around Astro's view-transition events. A
+ * server-rendered `<script>` runs on a hard page load but not after a
+ * client-side navigation, which is why the API reference used to appear only
+ * after a manual refresh on Starlight pages and other Astro sites that use
+ * `<ClientRouter />`.
+ */
+import { DEFAULT_CDN } from '@scalar/client-side-rendering'
+
+/** A mounted API reference, as returned by `window.Scalar.createApiReference`. */
+type ScalarInstance = {
+  destroy: () => void
+}
+
+type ScalarGlobal = {
+  createApiReference: (element: Element, configuration: unknown) => ScalarInstance
+}
+
+/** Shared, page-wide state. */
+type ClientState = {
+  /** Whether the view-transition listeners have been registered. */
+  initialized: boolean
+  /**
+   * Bumped by every `unmountAll`. A mount started before the bump belongs to
+   * a page that has since been swapped away, so its (async) CDN load must not
+   * create an instance once it finally resolves.
+   */
+  generation: number
+  /** Live instances, keyed by their container element. */
+  instances: Map<HTMLElement, ScalarInstance>
+  /** Containers with a mount currently in flight, so it is not started twice. */
+  pending: Set<HTMLElement>
+  /**
+   * CDN script loads in flight (or settled), keyed by their resolved URL. Each
+   * resolves with the `Scalar` global that bundle installed (see `loadCdn`).
+   */
+  cdnLoads: Map<string, Promise<ScalarGlobal | undefined>>
+}
+
+type ScalarWindow = Window & {
+  Scalar?: ScalarGlobal
+  __scalarAstroClient?: ClientState
+}
+
+/**
+ * Read the shared state from `window`, creating it on first access.
+ *
+ * Astro may bundle this module into more than one page chunk, so module-level
+ * variables are not guaranteed to be shared across navigations. `window` is.
+ */
+const getState = (): ClientState => {
+  const win = window as ScalarWindow
+
+  win.__scalarAstroClient ??= {
+    initialized: false,
+    generation: 0,
+    instances: new Map(),
+    pending: new Set(),
+    cdnLoads: new Map(),
+  }
+
+  return win.__scalarAstroClient
+}
+
+/**
+ * Inject the Scalar standalone bundle, loading each CDN URL at most once, and
+ * resolve with the global that bundle installs.
+ *
+ * The global is captured synchronously inside the `load` handler — the instant
+ * this bundle's script has run — rather than read back from `window.Scalar`
+ * later. A page that mixes containers with distinct `data-cdn` URLs loads
+ * several bundles that all claim the single `window.Scalar` global, so reading
+ * it after an `await` could pick up whichever bundle happened to finish last.
+ * (Distinct bundles sharing one global is inherently last-one-wins; capturing
+ * here keeps the common single-CDN page correct and narrows the window for the
+ * rest.)
+ */
+const loadCdn = (cdn: string): Promise<ScalarGlobal | undefined> => {
+  const { cdnLoads } = getState()
+  const cached = cdnLoads.get(cdn)
+
+  if (cached) {
+    return cached
+  }
+
+  const load = new Promise<ScalarGlobal | undefined>((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = cdn
+    script.addEventListener('load', () => resolve((window as ScalarWindow).Scalar), { once: true })
+    script.addEventListener(
+      'error',
+      () => {
+        // Drop the cached failure (and the dead tag) so a later mount or
+        // navigation can retry, instead of replaying this rejection forever.
+        cdnLoads.delete(cdn)
+        script.remove()
+        reject(new Error(`[@scalar/astro] Could not load ${cdn}`))
+      },
+      { once: true },
+    )
+    document.head.appendChild(script)
+  })
+
+  cdnLoads.set(cdn, load)
+
+  return load
+}
+
+/** Mount a single container, unless it is already mounted or mounting. */
+const mountContainer = (element: HTMLElement): void => {
+  const state = getState()
+
+  // Skip containers that are already mounted, or have a mount in flight. This
+  // also dedupes the two `mountAll()` calls the initial page load triggers
+  // (our own call in `initScalarClient`, plus `astro:page-load`).
+  if (state.instances.has(element) || state.pending.has(element)) {
+    return
+  }
+
+  let configuration: unknown
+
+  try {
+    configuration = JSON.parse(element.dataset.configuration || '{}')
+  } catch (error) {
+    // A bad configuration is left untracked, so a corrected one on a later
+    // navigation still gets a chance to mount.
+    console.error('[@scalar/astro] Could not parse the configuration.', error)
+    return
+  }
+
+  const cdn = element.dataset.cdn || DEFAULT_CDN
+  // Remember which lifecycle this mount belongs to (see `ClientState`).
+  const { generation } = state
+
+  state.pending.add(element)
+
+  void loadCdn(cdn)
+    .then((Scalar) => {
+      // Mount only if this page is still live (no view transition happened
+      // while the CDN loaded) and the element is still in the document.
+      if (state.generation === generation && element.isConnected && Scalar?.createApiReference) {
+        state.instances.set(element, Scalar.createApiReference(element, configuration))
+      }
+    })
+    .catch((error) => console.error('[@scalar/astro] Could not mount the API reference.', error))
+    .finally(() => {
+      // Release the pending slot — but only if a view transition has not
+      // already cleared it, in which case the slot belongs to a newer attempt.
+      if (state.generation === generation) {
+        state.pending.delete(element)
+      }
+    })
+}
+
+/** Mount every client-rendered container currently in the document. */
+const mountAll = (): void => {
+  document.querySelectorAll<HTMLElement>('[data-scalar-client]').forEach(mountContainer)
+}
+
+/** Destroy every mounted instance, e.g. before Astro swaps the page out. */
+const unmountAll = (): void => {
+  const state = getState()
+
+  state.instances.forEach((instance) => {
+    try {
+      instance.destroy()
+    } catch (error) {
+      console.error('[@scalar/astro] Could not destroy the API reference.', error)
+    }
+  })
+
+  state.instances.clear()
+  state.pending.clear()
+
+  // Invalidate in-flight mounts: their CDN load may still resolve, but it
+  // belongs to the page being swapped away. The next `astro:page-load` then
+  // mounts every container afresh — including any that survive the swap via
+  // `transition:persist`, which are no longer tracked as mounted.
+  state.generation += 1
+}
+
+/** The `astro:before-swap` event, narrowed to the part this module uses. */
+type BeforeSwapEvent = Event & { newDocument?: Document }
+
+/**
+ * Carry Scalar's stylesheet into the next page during a view transition.
+ *
+ * The standalone bundle injects its CSS into `<head>` once, when the CDN
+ * script first runs. Astro replaces `<head>` on every navigation, which would
+ * drop that `<style>` and leave the reference unstyled after a client-side
+ * navigation. Cloning it into the incoming document keeps the styles in place.
+ *
+ * This runs on every navigation, even to pages without a reference: that
+ * `<style>` is the only copy, so a page in between (an "About" page, say) has
+ * to carry it along, otherwise it is gone for good once the user navigates on.
+ */
+const persistScalarStyles = (newDocument: Document): void => {
+  document.head.querySelectorAll('style').forEach((style) => {
+    // Scalar's design tokens are namespaced `--scalar-*`, which reliably
+    // fingerprints the (otherwise unmarked) `<style>` the bundle injects.
+    if (!style.textContent?.includes('--scalar-')) {
+      return
+    }
+
+    const alreadyThere = Array.from(newDocument.head.querySelectorAll('style')).some((candidate) =>
+      candidate.isEqualNode(style),
+    )
+
+    if (!alreadyThere) {
+      newDocument.head.appendChild(style.cloneNode(true))
+    }
+  })
+}
+
+/** Persist styles and tear down instances before Astro swaps the page out. */
+const handleBeforeSwap = (event: Event): void => {
+  const { newDocument } = event as BeforeSwapEvent
+
+  if (newDocument) {
+    persistScalarStyles(newDocument)
+  }
+
+  unmountAll()
+}
+
+/**
+ * Mount client-rendered API references and keep them working across Astro
+ * view transitions. Safe to call repeatedly — the listeners register once.
+ */
+export const initScalarClient = (): void => {
+  // Mount right away. This covers the initial page load, including sites
+  // without `<ClientRouter />`, where `astro:page-load` never fires.
+  mountAll()
+
+  const state = getState()
+
+  if (state.initialized) {
+    return
+  }
+  state.initialized = true
+
+  // `astro:before-swap` fires before the outgoing page is replaced, and
+  // `astro:page-load` once the new page is in place — destroy, then re-mount.
+  document.addEventListener('astro:before-swap', handleBeforeSwap)
+  document.addEventListener('astro:page-load', mountAll)
+}