@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.130

package/plugin/globalJs/code-snippets.ts

@@ -13,23 +13,24 @@ document.addEventListener(getPageLoadEvent(), () => {
       const panelId = (tab as HTMLButtonElement).dataset.snippetResponseTabId;
 
       if (!panelId) {
-        console.error(`No panel found for tab: ${tab}`);
+        console.error(`No panel found for tab: ${tab.outerHTML}`);
         return;
       }
       document
         .querySelectorAll(`[data-snippet-response-pane-id="${panelId}"]`)
         .forEach((p) => p.classList.add('stldocs-snippet-response-pane-active'));
-      document
-        .querySelectorAll(`[data-snippet-response-tab-id="${panelId}"]`)
-        .forEach((p) => p.classList.add('stldocs-snippet-response-tab-item-active'));
+      document.querySelectorAll(`[data-snippet-response-tab-id="${panelId}"]`).forEach((p) => {
+        p.classList.add('stldocs-snippet-response-tab-item-active');
+        p.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'center' });
+      });
     });
   });
 
   document.getElementById('stl-snippet-expand-button')?.addEventListener('click', (e) => {
     const btn = e.currentTarget as HTMLButtonElement;
 
-    const collapsedDiv = document.querySelector('.stl-snippet-code-is-collapsed') as HTMLElement | null;
-    const expandedDiv = document.querySelector('.stl-snippet-code-is-expanded') as HTMLElement | null;
+    const collapsedDiv = document.querySelector('.stl-snippet-code-is-collapsed');
+    const expandedDiv = document.querySelector('.stl-snippet-code-is-expanded');
 
     // We need to use javascript for height animations due to having dynamic heights based on snippet size.
     const animateHeight = (el: HTMLElement, expand: boolean) => {
@@ -43,27 +44,34 @@ document.addEventListener(getPageLoadEvent(), () => {
       // This is a bit funky, but it animates pretty smooth.
       // 1. Toggle to new state so we can measure the target height
       // 2. Reset to starting height to trigger transition
-      const startHeight = el.scrollHeight;
+      el.style.height = '';
+      el.style.overflowY = '';
+      const startHeight = el.getBoundingClientRect().height;
       el.classList.toggle('stl-snippet-code-is-expanded', expand);
       el.classList.toggle('stl-snippet-code-is-collapsed', !expand);
 
-      const endHeight = el.scrollHeight;
-
-      el.style.height = `${startHeight}px`;
-
-      requestAnimationFrame(() => {
-        el.style.height = `${endHeight}px`;
-      });
+      const endHeight = el.getBoundingClientRect().height;
 
       const onEnd = (e: TransitionEvent) => {
         if (e.propertyName !== 'height') return;
         el.style.height = '';
+        el.style.overflowY = '';
         el.removeEventListener('transitionend', onEnd);
       };
       el.addEventListener('transitionend', onEnd);
+
+      // Set initial height
+      el.style.height = `${startHeight}px`;
+      el.style.overflowY = 'hidden';
+
+      // Force layout recalculation
+      el.getBoundingClientRect();
+
+      // Start transition to end state
+      el.style.height = `${endHeight}px`;
     };
 
-    if (collapsedDiv) {
+    if (collapsedDiv instanceof HTMLElement) {
       if (collapsedDiv) {
         collapsedDiv.querySelector('.shiki')?.setAttribute('style', `counter-reset: codeblock-line 0`);
       }
@@ -72,7 +80,7 @@ document.addEventListener(getPageLoadEvent(), () => {
       return;
     }
 
-    if (expandedDiv) {
+    if (expandedDiv instanceof HTMLElement) {
       const dataSnippetExpandedOffset = expandedDiv?.dataset.snippetExpandedOffset;
       if (dataSnippetExpandedOffset) {
         const offset = parseInt(dataSnippetExpandedOffset, 10);
@@ -84,4 +92,25 @@ document.addEventListener(getPageLoadEvent(), () => {
       btn.textContent = 'Show more';
     }
   });
+
+  document.querySelectorAll('[data-stldocs-multi-snippet-container]').forEach((container) => {
+    const radios = container.querySelectorAll<HTMLInputElement>('input[type="radio"]');
+    const panes = container.querySelectorAll<HTMLDivElement>('[data-stldocs-multi-snippet-id]');
+
+    radios.forEach((radio) => {
+      radio.addEventListener('change', (e) => {
+        if (!(e.target instanceof HTMLInputElement)) return;
+        if (e.target.checked) {
+          const selectedIndex = e.target.value;
+          panes.forEach((pane) => {
+            pane.classList.toggle(
+              'stldocs-snippet-multi-pane-active',
+              pane.dataset.stldocsMultiSnippetId === selectedIndex,
+            );
+          });
+          e.target.parentElement?.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'center' });
+        }
+      });
+    });
+  });
 });

package/plugin/globalJs/copy.ts

@@ -1,37 +1,125 @@
-import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import {
+  RESOLVED_API_REFERENCE_PATH,
+  EXPERIMENTAL_COLLAPSIBLE_SNIPPETS,
+} from 'virtual:stl-starlight-virtual-module';
+import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+import { updateSelectedLanguage } from '../languages';
+import { navigate } from 'astro/virtual-modules/transitions-router.js';
 const copyIcon = `<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>`;
 const circleAlertIcon = `<circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/>`;
 const checkIcon = `<path d="M20 6 9 17l-5-5"/>`;
 
-addEventListener('click', async (event) => {
-  const copyButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-copy]') as HTMLElement;
+function getContent(button: HTMLElement, full: boolean) {
+  const isContentCollapsed = !!document.querySelector('.stldocs-snippet-code.stl-snippet-code-is-collapsed');
+
+  const content = button.closest('[data-stldocs-copy-parent]')!.querySelector('[data-stldocs-copy-content]')!;
+
+  const contentCopy = content.cloneNode(true) as HTMLElement;
+
+  contentCopy.querySelectorAll('.ellipsis').forEach((el) => el.remove());
+  if (EXPERIMENTAL_COLLAPSIBLE_SNIPPETS && isContentCollapsed && !full) {
+    contentCopy.querySelectorAll('.hidden').forEach((el) => el.remove());
+    contentCopy.querySelectorAll('.leading-ws').forEach((el) => el.remove());
+  }
+
+  return contentCopy.textContent;
+}
+
+const preloadPlayground = (event: Event) => {
+  const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
+  if (playButton) {
+    loadPlayground(playButton);
+  }
+};
+addEventListener('mouseover', preloadPlayground);
+addEventListener('click', (event) => {
+  if (!(event.target instanceof Element)) return;
+  const copyButton = event.target.closest('[data-stldocs-snippet-copy]');
+  if (!(copyButton instanceof HTMLElement)) return;
+
   if (copyButton) {
     const iconElement = copyButton.querySelector('.stldocs-icon') as SVGElement;
     clearTimeout(copyButton.dataset.__stldocsCopyTimeout);
-    try {
-      const isContentCollapsed = !!document.querySelector(
-        '.stldocs-snippet-code.stl-snippet-code-is-collapsed',
-      );
-
-      const content = copyButton
-        .closest('[data-stldocs-copy-parent]')!
-        .querySelector('[data-stldocs-copy-content]')!;
-
-      const contentCopy = content.cloneNode(true) as HTMLElement;
-
-      contentCopy.querySelectorAll('.ellipsis').forEach((el) => el.remove());
-      if (EXPERIMENTAL_COLLAPSIBLE_SNIPPETS && isContentCollapsed) {
-        contentCopy.querySelectorAll('.hidden').forEach((el) => el.remove());
-        contentCopy.querySelectorAll('.leading-ws').forEach((el) => el.remove());
-      }
-      await navigator.clipboard.writeText(contentCopy.textContent!);
-      iconElement.innerHTML = checkIcon;
-    } catch {
-      iconElement.innerHTML = circleAlertIcon;
+    navigator.clipboard
+      .writeText(getContent(copyButton, false))
+      .then(() => {
+        iconElement.innerHTML = checkIcon;
+      })
+      .catch(() => {
+        iconElement.innerHTML = circleAlertIcon;
+      })
+      .finally(() => {
+        copyButton.dataset.__stldocsCopyTimeout = setTimeout(() => {
+          iconElement.innerHTML = copyIcon;
+        }).toString();
+      });
+  }
+
+  const playButton = event.target.closest('[data-stldocs-snippet-play]');
+  if (playButton instanceof HTMLElement) {
+    showPlayground(playButton).catch(() => {
+      console.error('Failed to load playground');
+    });
+  }
+});
+
+async function showPlayground(playButton: HTMLElement) {
+  if (playButton.getAttribute('aria-disabled') === 'true') return;
+  const iconElement = playButton.querySelector('.stldocs-icon') as SVGElement;
+  try {
+    // use aria-disabled, not disabled, to avoid losing focus
+    playButton.setAttribute('aria-disabled', 'true');
+    playButton.setAttribute('aria-label', 'Loading playground...');
+    playButton.classList.add('stl-ui-button--loading');
+    const showPlayground = loadPlayground(playButton);
+    await showPlayground();
+  } catch (e) {
+    console.error(e);
+    iconElement.innerHTML = circleAlertIcon;
+  }
+  playButton.removeAttribute('aria-disabled');
+  playButton.removeAttribute('aria-label');
+  playButton.classList.remove('stl-ui-button--loading');
+}
+
+function loadPlayground(playButton: HTMLElement) {
+  (playButton as any).__playgroundLoadPromise ??= (async () => {
+    const container = playButton.closest('.stldocs-snippet') as HTMLElement;
+    const language = (container.querySelector('.stl-sdk-select') as HTMLElement).dataset.currentValue;
+    const code = getContent(playButton, true);
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    if (import.meta.env.DEV) {
+      const id = '/@id/astro:scripts/before-hydration.js';
+      await import(/* @vite-ignore */ id).catch(console.warn);
     }
-    copyButton.dataset.__stldocsCopyTimeout =
-      setTimeout(() => {
-        iconElement.innerHTML = copyIcon;
-      }, 1000) + '';
+    const { createPlayground } = await import('virtual:stl-playground/create');
+    const { default: playgroundData } = await import('virtual:stl-playground/data');
+    return createPlayground({
+      lang: language as any,
+      doc: (language === 'python' ? 'from rich import print\n' : '') + code.trimEnd(),
+      container,
+      onLanguageSelect: (value) => {
+        const originalLanguage = container.querySelector<HTMLElement>('[data-stldocs-snippet-select]')
+          ?.dataset.currentValue;
+        const path: string = updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value);
+        navigate(path.replace(/(\?.+)?($|#)/, (_, str, end) => (str ? str + '&play' : '?play') + end));
+      },
+      ...playgroundData,
+    });
+  })();
+  return async () => {
+    const promise = (playButton as any).__playgroundLoadPromise;
+    (playButton as any).__playgroundLoadPromise = null;
+    await ((await promise) as () => Promise<void>)();
+  };
+}
+document.addEventListener(getPageLoadEvent(), () => {
+  if (new URL(location.href).searchParams.has('play')) {
+    document.querySelectorAll('[data-stldocs-snippet-play]').forEach((e) => {
+      if (e instanceof HTMLElement)
+        showPlayground(e).catch(() => {
+          console.error('Failed to load playground');
+        });
+    });
   }
 });

package/plugin/globalJs/create-playground.shim.ts

@@ -0,0 +1,3 @@
+export function createPlayground(): () => Promise<void> {
+  return () => Promise.resolve();
+}

package/plugin/globalJs/method-descriptions.ts

@@ -0,0 +1,33 @@
+document.addEventListener('DOMContentLoaded', function () {
+  const COLLAPSED_HEIGHT = 170;
+
+  const container = document.querySelector<HTMLElement>('[data-stldocs-property-group="method-description"]');
+
+  if (!container) return;
+
+  const toggle = document?.querySelector<HTMLButtonElement>('[data-method-description-toggle]');
+  if (!toggle) return;
+
+  // If content isn't tall enough, don't show the button
+  if (container.scrollHeight <= COLLAPSED_HEIGHT + 1) {
+    toggle.hidden = true;
+    container.dataset.collapsed = 'false';
+    return;
+  }
+
+  // Only show button if content is taller than collapsed max height
+  if (container.scrollHeight > COLLAPSED_HEIGHT + 1) {
+    toggle.hidden = false;
+  } else {
+    // Not tall enough to need collapsing — show full content and hide button
+    container.dataset.collapsed = 'false';
+    toggle.hidden = true;
+    return;
+  }
+
+  toggle.addEventListener('click', function () {
+    const isCollapsed = container.dataset.collapsed !== 'false';
+    container.dataset.collapsed = isCollapsed ? 'false' : 'true';
+    toggle.textContent = isCollapsed ? 'Show less' : 'Show more';
+  });
+});

package/plugin/globalJs/navigation.ts

@@ -1,19 +1,17 @@
-import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/src/routing';
-import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/routing';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { updateSelectedLanguage } from '../languages';
 import { navigate } from 'astro:transitions/client';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent.ts';
 
-import { initDropdown } from '@stainless-api/docs-ui/src/components/scripts/dropdown';
-import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
-import { copyCurrentPageAsMarkdown, onSelectAIOption } from './ai-dropdown.ts';
+import { initDropdown } from '@stainless-api/docs/components/scripts';
 
 history.scrollRestoration = 'auto';
 
 function getStainlessPathForLocation() {
   return document.location.hash
     ? decodeURI(document.location.hash)
-    : parseRoute(BASE_PATH, document.location.href)?.stainlessPath;
+    : parseRoute(RESOLVED_API_REFERENCE_PATH, document.location.href)?.stainlessPath;
 }
 
 window.addEventListener('popstate', (ev: PopStateEvent) => {
@@ -24,57 +22,39 @@ window.addEventListener('popstate', (ev: PopStateEvent) => {
 });
 
 document.addEventListener(getPageLoadEvent(), () => {
-  initDropdown({
-    dropdownId: 'stldocs-snippet-select',
-    onSelect: (value) => {
-      const originalLanguage = document.getElementById('stldocs-snippet-select')?.dataset.currentValue;
-      navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
-    },
+  document.querySelectorAll<HTMLElement>('[data-stldocs-snippet-select]').forEach((rootElement) => {
+    initDropdown({
+      root: rootElement,
+      onSelect: (value) => {
+        const originalLanguage = rootElement.dataset.currentValue;
+        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value)).catch((e) => {
+          console.error('Failed to navigate to selected language', e);
+        });
+      },
+    });
   });
 
   const path = getStainlessPathForLocation();
   if (path) setTimeout(() => scrollToPath(path.slice(1)), 10);
 });
 
-document.addEventListener(getPageLoadEvent(), () => {
-  initDropdownButton({
-    dropdownId: 'ai-dropdown-button',
-    onSelect: onSelectAIOption,
-    onPrimaryAction: (el) => {
-      copyCurrentPageAsMarkdown();
-      const innerText = el.querySelector('[data-part="primary-action-text"]');
-      if (!innerText) return;
-
-      const originalInnerHtml = innerText.innerHTML;
-      innerText.innerHTML = 'Copied!';
-      el.classList.add('disabled');
-      setTimeout(() => {
-        innerText.innerHTML = originalInnerHtml;
-        el.classList.remove('disabled');
-      }, 1000);
-    },
-  });
-});
-
 document.addEventListener('click', (event) => {
-  const toggle = (event.target as HTMLElement).closest(
-    '[data-stldocs-property-toggle-expanded] > .stldocs-expand-toggle-content',
-  )?.parentElement;
-
-  if (!toggle) return;
+  const toggle =
+    event.target instanceof HTMLElement && event.target.closest('[data-stldocs-property-toggle-expanded]');
+  if (!toggle || !(toggle instanceof HTMLElement)) return;
 
-  const state = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
-  toggle.dataset.stldocsPropertyToggleExpanded = state ? 'false' : 'true';
+  // Toggle the “expanded” state of the toggle
+  const toggleIsExpanded = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
+  toggle.dataset.stldocsPropertyToggleExpanded = (!toggleIsExpanded).toString();
 
+  // Find the described “property group”
   const targetGroup = toggle.dataset.stldocsPropertyToggleTarget;
   if (!targetGroup) return;
-
   const target = document.querySelector(`[data-stldocs-property-group=${targetGroup}]`);
   if (!target) return;
 
-  target.querySelectorAll('details').forEach((details) => {
-    const el = details as HTMLDetailsElement;
-    const initial = el.dataset.stldocsExpanderInitialState;
-    el.open = initial === 'true' ? true : !state;
+  // Expand or collapse all <details> elements within the target group
+  [...target.getElementsByTagName('details')].forEach((el) => {
+    el.open = el.dataset.stldocsExpanderInitialState === 'true' ? true : !toggleIsExpanded;
   });
 });

package/plugin/globalJs/playground-data.shim.ts

@@ -0,0 +1 @@
+export default {};

package/plugin/globalJs/playground-data.ts

@@ -0,0 +1,14 @@
+import wheelUrl from 'virtual:stl-playground/python/wheel.whl?url';
+import pyTypes from 'virtual:stl-playground/python.json';
+import tsTypes from 'virtual:stl-playground/typescript.json';
+import authData from 'virtual:stl-playground/auth.json';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { Config } from 'virtual:stl-playground/create';
+
+export default {
+  wheelUrl,
+  pyTypes,
+  tsTypes,
+  authData,
+  HIGHLIGHT_THEMES,
+} satisfies Config;

package/plugin/globalJs/summary-selection-tweak.ts

@@ -0,0 +1,29 @@
+// Let users select text in <summary> elements without toggling them
+
+document.addEventListener(
+  'mousedown',
+  (e) => {
+    const summary = (e.target as HTMLElement).closest('summary.stldocs-expander-summary');
+    if (!summary) return;
+    const selectionOnDown = window.getSelection()?.toString() ?? '';
+
+    document.addEventListener(
+      'mouseup',
+      () => {
+        const selectionOnUp = window.getSelection()?.toString() ?? '';
+
+        if (selectionOnUp && selectionOnUp !== selectionOnDown) {
+          summary.addEventListener(
+            'click',
+            (e) => {
+              e.preventDefault();
+            },
+            { once: true },
+          );
+        }
+      },
+      { once: true },
+    );
+  },
+  { capture: true },
+);

package/plugin/helpers/generateDocsRoutes.ts

@@ -0,0 +1,59 @@
+import type * as SDKJSON from '@stainless/sdk-json';
+import { DocsLanguage, generateRouteList } from '@stainless-api/docs-ui/routing';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { api } from 'virtual:stainless-apis-manifest';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+
+export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLanguage[] = EXCLUDE_LANGUAGES) {
+  const paths = generateRouteList({
+    spec,
+    excludeLanguages,
+  });
+  const readmes = Object.entries(spec.readme)
+    .filter(([language]) => language !== 'http')
+    .filter(([language]) => !excludeLanguages.includes(language as DocsLanguage))
+    .map(([language]) => ({
+      slug: language,
+      stainlessPath: null,
+      language: language as DocsLanguage,
+      title: 'Readme',
+      kind: 'readme' as const,
+    }));
+
+  return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {
+    return {
+      params: { slug },
+      props: { stainlessPath, language, title, kind },
+    };
+  });
+}
+
+export async function generateAllDocsRoutes() {
+  const uniquePaths = new Set<string>();
+
+  const allRoutes = (
+    await Promise.all(
+      api.languages.map(async (entry) => {
+        const spec = await getSDKJSONInSSR(entry.language);
+
+        // this is super annoying, but preview worker _always_ generates HTTP routes
+        // so, we exclude them unless the we're explicitly told to include them
+        const excludeLanguages = [...EXCLUDE_LANGUAGES];
+        if (entry.language !== 'http') {
+          excludeLanguages.push('http');
+        }
+
+        const routes = generateDocsRoutes(spec, excludeLanguages);
+        return routes.filter((route) => {
+          if (uniquePaths.has(route.params.slug)) {
+            return false;
+          }
+          uniquePaths.add(route.params.slug);
+          return true;
+        });
+      }),
+    )
+  ).flat();
+
+  return allRoutes;
+}

package/plugin/helpers/multiSpec.ts

@@ -0,0 +1,8 @@
+import { api } from 'virtual:stainless-apis-manifest';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+
+export function getDocsLanguages() {
+  return api.languages
+    .map((language) => language.language)
+    .filter((language) => !EXCLUDE_LANGUAGES.includes(language));
+}