@stainless-api/docs 0.1.0-beta.7 → 0.1.0-beta.70

package/plugin/globalJs/ai-dropdown-options.ts

@@ -0,0 +1,243 @@
+import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
+import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+
+export type DropdownIcon = 'markdown' | 'copy' | 'claude' | 'chatgpt' | 'gemini' | 'cursor';
+
+interface DropdownOptionInputProps {
+  onClick: () => void;
+  icon: DropdownIcon;
+  primaryAction?: boolean;
+  clientHidden?: boolean;
+  external: boolean;
+}
+
+function option(label: string[] | string, props: DropdownOptionInputProps) {
+  const labelArr = typeof label === 'string' ? [label] : label;
+  return {
+    ...props,
+    label: labelArr,
+    primaryAction: props.primaryAction ?? false,
+    clientHidden: props.clientHidden ?? false,
+    id: labelArr.join('').toLowerCase().replace(/ /g, '-'),
+  };
+}
+
+type DropdownOption = ReturnType<typeof option>;
+
+function getMarkdownUrl(type: 'relative' | 'absolute') {
+  const currentUrl = new URL(window.location.href);
+  const hasTrailingSlash = currentUrl.pathname.endsWith('/');
+
+  const markdownUrl = [
+    type === 'absolute' ? currentUrl.origin : '',
+    currentUrl.pathname,
+    hasTrailingSlash ? '' : '/',
+    'index.md',
+  ].join('');
+
+  return markdownUrl;
+}
+
+function getURLEncodedPrompt() {
+  const mdUrl = getMarkdownUrl('absolute');
+  const aiPrompt = encodeURIComponent(
+    `Load the contents of ${mdUrl} into this chat's context so we can discuss it.`,
+  );
+  return aiPrompt;
+}
+
+function openDeepLink({ deepLinkUrl, fallbackUrl }: { deepLinkUrl: string; fallbackUrl: string }) {
+  if (navigator.userAgent.includes('Safari') && !navigator.userAgent.includes('Chrom')) {
+    // safari doesn't let us detect if the deep link worked
+    window.open(fallbackUrl, '_blank');
+    return;
+  }
+
+  const controller = new AbortController();
+  let frame: HTMLIFrameElement | null;
+
+  // We are using a native deep link with a fallback web url.
+  if (navigator.userAgent.includes('Chrom')) {
+    // In Chrome, load it in a hidden frame, this shows the "Do you want to open ...?" prompt, but unlike
+    // top level navigation this preserves our userActivation, so we can open the fallback if it fails.
+    frame = Object.assign(document.createElement('iframe'), { src: deepLinkUrl });
+    document.head.append(frame);
+  } else {
+    // In Firefox do the opposite.
+    location.href = deepLinkUrl;
+  }
+
+  // The popup (in non-Safari browsers) fires a `blur` event.
+  window.addEventListener(
+    'blur',
+    () => {
+      controller.abort();
+    },
+    controller,
+  );
+
+  // If it's been 300ms with no popup, open the fallback web url.
+  const timeout = setTimeout(() => {
+    window.open(fallbackUrl, '_blank');
+  }, 300);
+
+  controller.signal.addEventListener('abort', () => {
+    clearTimeout(timeout);
+    frame?.remove();
+  });
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent#mobile_tablet_or_desktop
+const hasMobileUserAgent = navigator.userAgent.includes('Mobi');
+
+// 2d array of dropdown options
+// each sub-array is a group, separated by a horizontal rule in the UI
+const aiDropdownOptions: DropdownOption[][] = [
+  [
+    option(['Open in ', 'Claude'], {
+      onClick: () => {
+        window.open(`https://claude.ai/new?q=${getURLEncodedPrompt()}`, '_blank');
+      },
+      icon: 'claude',
+      primaryAction: false,
+      external: true,
+    }),
+    option(['Open in ', 'ChatGPT'], {
+      onClick: () => {
+        window.open(`https://chatgpt.com/?hints=search&prompt=${getURLEncodedPrompt()}`, '_blank');
+      },
+      icon: 'chatgpt',
+      primaryAction: false,
+      external: true,
+    }),
+    option(['Open in ', 'Cursor'], {
+      onClick: () => {
+        const aiPrompt = getURLEncodedPrompt();
+        openDeepLink({
+          deepLinkUrl: `cursor://anysphere.cursor-deeplink/prompt?text=${aiPrompt}`,
+          fallbackUrl: `https://cursor.com/link/prompt?text=${aiPrompt}`,
+        });
+      },
+      clientHidden: hasMobileUserAgent,
+      icon: 'cursor',
+      primaryAction: false,
+      external: true,
+    }),
+  ],
+  [
+    option('Copy Markdown', {
+      onClick: () => {
+        // Source: https://wolfgangrittner.dev/how-to-use-clipboard-api-in-firefox/
+        const markdownUrl = getMarkdownUrl('relative');
+        // ClipboardItem doesn't exist in every browser
+        // eslint-disable-next-line no-constant-binary-expression
+        if (typeof ClipboardItem && navigator.clipboard.write) {
+          // NOTE: Safari locks down the clipboard API to only work when triggered
+          //   by a direct user interaction. You can't use it async in a promise.
+          //   But! You can wrap the promise in a ClipboardItem, and give that to
+          //   the clipboard API.
+          //   Found this on https://developer.apple.com/forums/thread/691873
+          const text = new ClipboardItem({
+            'text/plain': fetch(markdownUrl)
+              .then((response) => response.text())
+              .then((text) => new Blob([text], { type: 'text/plain' })),
+          });
+          navigator.clipboard.write([text]);
+        } else {
+          // NOTE: Firefox has support for ClipboardItem and navigator.clipboard.write,
+          //   but those are behind `dom.events.asyncClipboard.clipboardItem` preference.
+          //   Good news is that other than Safari, Firefox does not care about
+          //   Clipboard API being used async in a Promise.
+          fetch(markdownUrl)
+            .then((response) => response.text())
+            .then((text) => navigator.clipboard.writeText(text));
+        }
+      },
+      icon: 'copy',
+      primaryAction: true,
+      external: false,
+    }),
+    option('View as Markdown', {
+      onClick: () => {
+        window.open(getMarkdownUrl('absolute'), '_blank');
+      },
+      icon: 'markdown',
+      primaryAction: false,
+      external: true,
+    }),
+  ],
+];
+
+// TODO: Add support for more LLMs
+// {
+//   label: ['Open in ', 'Gemini'],
+//   onClick: () => {
+//     openInLLM('https://gemini.google.com?prompt_action=prefill&prompt_text=');
+//   },
+//   icon: 'gemini',
+//   primaryAction: false,
+// },
+
+export function getAIDropdownOptions() {
+  const renderedOptions = aiDropdownOptions.map((group, index) => {
+    return {
+      options: group,
+      isLast: index === aiDropdownOptions.length - 1,
+      reactKey: index,
+    };
+  });
+
+  const allOptions = renderedOptions.flatMap((group) => group.options);
+  const primaryAction = allOptions.find((o) => o.primaryAction) ?? allOptions[0]!;
+
+  return {
+    primaryAction,
+    groups: renderedOptions,
+  };
+}
+
+export function wireAIDropdown() {
+  const { primaryAction, groups } = getAIDropdownOptions();
+  const flatOptions = groups.flatMap((group) => group.options);
+  function triggerOption(id: string) {
+    const option = flatOptions.find((option) => option.id === id);
+    if (!option) return;
+    option.onClick();
+  }
+
+  document.addEventListener(getPageLoadEvent(), () => {
+    // we hide the Cursor option on non-desktop devices
+    for (const option of flatOptions) {
+      if (option.clientHidden === true) {
+        const el = document.querySelector(
+          `[data-dropdown-id="ai-dropdown-button"] [data-value="${option.id}"]`,
+        );
+        if (el) {
+          el.remove();
+        }
+      }
+    }
+
+    const dropdowns = document.querySelectorAll('[data-dropdown-id="ai-dropdown-button"]');
+
+    dropdowns.forEach((dropdown) => {
+      initDropdownButton({
+        dropdown: dropdown,
+        onSelect: (value) => {
+          triggerOption(value);
+        },
+        onPrimaryAction: (el) => {
+          triggerOption(primaryAction.id);
+          const span = el.querySelector('[data-part="primary-action-text"]');
+          if (span) {
+            const originalContent = span.textContent;
+            span.textContent = 'Copied!';
+            setTimeout(() => {
+              span.textContent = originalContent;
+            }, 2000);
+          }
+        },
+      });
+    });
+  });
+}

package/plugin/globalJs/code-snippets.ts

@@ -43,24 +43,31 @@ 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) {

package/plugin/globalJs/copy.ts

@@ -1,30 +1,39 @@
 import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 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"/>`;
 
+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 = async (event: Event) => {
+  const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
+  if (playButton) {
+    loadPlayground(playButton);
+  }
+};
+addEventListener('mouseover', preloadPlayground);
 addEventListener('click', async (event) => {
   const copyButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-copy]') as HTMLElement;
   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!);
+      await navigator.clipboard.writeText(getContent(copyButton, false));
       iconElement.innerHTML = checkIcon;
     } catch {
       iconElement.innerHTML = circleAlertIcon;
@@ -34,4 +43,60 @@ addEventListener('click', async (event) => {
         iconElement.innerHTML = copyIcon;
       }, 1000) + '';
   }
+
+  const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
+  if (playButton) {
+    showPlayground(playButton);
+  }
+});
+
+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);
+    }
+    const { createPlayground } = await import('virtual:stl-playground/create');
+    return createPlayground({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      lang: language as any,
+      doc: (language === 'python' ? 'from rich import print\n' : '') + code.trimEnd(),
+      container,
+    });
+  })();
+  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) => {
+      showPlayground(e as HTMLElement);
+    });
+  }
 });

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,10 +1,10 @@
-import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/src/routing';
+import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/routing';
 import { BASE_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 { initDropdown } from '@stainless-api/docs/components/scripts';
 
 history.scrollRestoration = 'auto';
 
@@ -22,10 +22,13 @@ window.addEventListener('popstate', (ev: PopStateEvent) => {
 });
 
 document.addEventListener(getPageLoadEvent(), () => {
+  const rootElement = document.getElementById('stldocs-snippet-select');
+  if (!rootElement) return;
+
   initDropdown({
-    dropdownId: 'stldocs-snippet-select',
+    root: rootElement,
     onSelect: (value) => {
-      const originalLanguage = document.getElementById('stldocs-snippet-select')?.dataset.currentValue;
+      const originalLanguage = rootElement?.dataset.currentValue;
       navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
     },
   });

package/plugin/helpers/generateDocsRoutes.ts

@@ -0,0 +1,27 @@
+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';
+
+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',
+    }));
+
+  return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {
+    return {
+      params: { slug },
+      props: { stainlessPath, language, title, kind },
+    };
+  });
+}