@stainless-api/docs 0.1.0-beta.99 → 1.0.0-beta.140

package/plugin/components/SnippetCode.tsx

@@ -8,7 +8,6 @@ import style from '@stainless-api/docs-ui/style';
 import * as cheerio from 'cheerio/slim';
 import {
   EXPERIMENTAL_COLLAPSIBLE_SNIPPETS,
-  EXPERIMENTAL_PLAYGROUNDS,
   EXPERIMENTAL_REQUEST_BUILDER,
 } from 'virtual:stl-starlight-virtual-module';
 import clsx from 'clsx';
@@ -18,26 +17,6 @@ import React from 'react';
 import { RequestBuilder } from './RequestBuilder';
 import { Method } from '@stainless/sdk-json';
 
-function PlaygroundIcon() {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width={16}
-      height={16}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      className={'lucide ' + style.Icon}
-      aria-hidden="true"
-    >
-      <path d="m 1,2 h 1 a 4,4 0 0 1 4,4 v 1 m 5,15 H 10 A 4,4 0 0 1 6,18 V 6 a 4,4 0 0 1 4,-4 h 1 M 1,22 H 2 A 4,4 0 0 0 6,18 V 17 M 14.029059,8.147837 A 1.2853426,1.2853426 0 0 1 15.978924,7.0437277 L 22.40178,10.8959 a 1.2853426,1.2853426 0 0 1 0,2.208219 l -6.422856,3.852172 a 1.2853426,1.2853426 0 0 1 -1.949865,-1.105395 z" />
-    </svg>
-  );
-}
-
 /*
  * This may be replaced by additional data from the sdk.
  * Without information from the sdk, we use simple heuristics per language.
@@ -49,7 +28,7 @@ function getCollapsedRanges(content: string, language: string, signature?: strin
   const sigIdx = raw.findIndex((l) => l.includes(signature));
   if (sigIdx < 0) return [];
 
-  let finalIndex = undefined;
+  let finalIndex;
   if (language === 'kotlin' || language === 'java') {
     finalIndex = raw.findIndex((l, i) => i > sigIdx && l.trim() === '}');
   } else if (language === 'python') {
@@ -140,7 +119,7 @@ function condensedShikiHtmlFull(docHtml: string, language: string, ranges: [numb
       out.push('<span class="line ellipsis">…\n</span>');
       didPushEllipsis = true;
     }
-    out.push($.html(lineEl)!);
+    out.push($.html(lineEl));
   });
 
   $code.html(out.join(''));
@@ -172,21 +151,11 @@ export function SnippetContainer({ children, signature, method }: SnippetContain
   );
 }
 
-export function SnippetButtons({ content }: { content: string }) {
-  void content;
-  const language = useLanguage();
+export function SnippetButtons() {
   return (
-    <>
-      <Button variant="outline" data-stldocs-snippet-copy>
-        <CopyIcon size={16} className={style.Icon} />
-      </Button>
-      {EXPERIMENTAL_PLAYGROUNDS &&
-        (language === 'python' || language === 'typescript' || language === 'http') && (
-          <Button data-stldocs-snippet-play variant="muted" border title="Play">
-            <PlaygroundIcon />
-          </Button>
-        )}
-    </>
+    <Button variant="outline" data-stldocs-snippet-copy>
+      <CopyIcon size={16} className={style.Icon} />
+    </Button>
   );
 }
 

package/plugin/components/search/SearchAlgolia.astro

@@ -4,7 +4,7 @@ import { Button } from '@stainless-api/ui-primitives';
 import { SearchIcon, XIcon } from 'lucide-react';
 ---
 
-<site-search>
+<site-search class={Astro.props.class}>
   <Button
     popoverTarget="stldocs-search"
     data-open-modal

package/plugin/components/search/SearchIsland.tsx

@@ -1,4 +1,4 @@
-import * as React from 'react';
+import { useMemo } from 'react';
 import { RESOLVED_API_REFERENCE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
 import { parseRoute, generateRoute } from '@stainless-api/docs-ui/routing';
 import { SearchModal } from '@stainless-api/docs-search';
@@ -8,27 +8,28 @@ import type { BundledLanguage, BundledTheme, HighlighterGeneric } from 'shiki';
 
 import {
   DocsProvider,
-  type MarkdownContext,
-  MarkdownProvider,
+  type MarkdownContextValue,
   NavigationProvider,
+  SuspensefulMarkdownProvider,
 } from '@stainless-api/docs-ui/contexts';
 import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
 import { SearchProvider } from '@stainless-api/docs-search/context';
 import type { SearchSettings } from '@stainless-api/docs-search/types';
 
-let $$highlighter: HighlighterGeneric<BundledLanguage, BundledTheme> | null = null;
-async function getHighlighter() {
-  if ($$highlighter === null) {
-    $$highlighter = await createHighlighter({
+declare global {
+  var __docsSearchShikiSingleton: Promise<HighlighterGeneric<BundledLanguage, BundledTheme>> | undefined;
+}
+function getHighlighter() {
+  if (!globalThis.__docsSearchShikiSingleton) {
+    globalThis.__docsSearchShikiSingleton = createHighlighter({
       themes: ['github-dark'],
       langs: ['typescript', 'python', 'go', 'java', 'kotlin', 'ruby'],
     });
   }
-
-  return $$highlighter;
+  return globalThis.__docsSearchShikiSingleton;
 }
 
-async function createMarkdownRenderer(): Promise<MarkdownContext> {
+async function createMarkdownRenderer(): Promise<MarkdownContextValue> {
   const highlighter = await getHighlighter();
   const markdocConfig: Markdoc.Config = {
     nodes: {
@@ -37,8 +38,12 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         ...Markdoc.nodes.fence,
         transform(node, config) {
           const attributes = node.transformAttributes(config);
+          if (typeof node.attributes.language !== 'string' || typeof node.attributes.content !== 'string') {
+            throw new Error('Expected language and content to be strings');
+          }
           const lang = node.attributes.language === 'node' ? 'typescript' : node.attributes.language;
           const code = highlighter.codeToTokens(node.attributes.content, {
+            // @ts-expect-error - TODO: narrowing
             lang,
             theme: 'github-dark',
           });
@@ -63,6 +68,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         transform(node, config) {
           const children = node.transformChildren(config);
           const attrs = node.transformAttributes(config);
+          if (typeof attrs['href'] !== 'string') throw new Error('Expected href to be a string');
           const href = attrs['href'].replace('docs://BASE_PATH', RESOLVED_API_REFERENCE_PATH);
           return new Markdoc.Tag(this.render, { ...attrs, href }, children);
         },
@@ -86,7 +92,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
 }
 
 export function DocsSearch({ settings, currentPath }: { settings: SearchSettings; currentPath: string }) {
-  const markdownRenderer = React.use(createMarkdownRenderer());
+  const rendererPromise = useMemo(() => createMarkdownRenderer(), []);
   const { stainlessPath, language } = parseRoute(RESOLVED_API_REFERENCE_PATH, currentPath);
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   const pageFind = import.meta.env.DEV
@@ -104,13 +110,13 @@ export function DocsSearch({ settings, currentPath }: { settings: SearchSettings
     <DocsProvider spec={null} language={language}>
       <ComponentProvider>
         <NavigationProvider basePath="/" selectedPath={stainlessPath}>
-          <MarkdownProvider {...markdownRenderer}>
+          <SuspensefulMarkdownProvider value={rendererPromise}>
             <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
               <div className="stldocs-root">
                 <SearchModal id="stldocs-search" />
               </div>
             </SearchProvider>
-          </MarkdownProvider>
+          </SuspensefulMarkdownProvider>
         </NavigationProvider>
       </ComponentProvider>
     </DocsProvider>

package/plugin/generateAPIReferenceLink.ts

@@ -1,47 +1,7 @@
 // This is probably temporary, but it fills in functionality needed for Mintlify imports
 
-import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import type * as SDKJSON from '@stainless/sdk-json';
-import { walkTree } from '@stainless-api/docs-ui/routing';
-
 const INTERNAL_REFERENCE_ENTRY_MARKER = 'STL_STARLIGHT_API_REFERENCE_METHOD_LINK_PLACEHOLDER';
 
-type SidebarEntry = StarlightRouteData['sidebar'][number];
-
-type SidebarLink = Extract<SidebarEntry, { href: string }>;
-
-export function getMethodFromSDKJSON(spec: SDKJSON.Spec, endpoint: string) {
-  for (const entry of walkTree(spec)) {
-    if (entry.data.kind === 'http_method' && entry.data.endpoint === endpoint) {
-      return entry.data;
-    }
-  }
-  throw new Error(`Endpoint ${endpoint} not found in API`);
-}
-
-export function recursiveReplacePlaceholderItems(
-  sidebar: SidebarEntry[],
-  modifyFn: (entry: SidebarLink, props: { endpoint: string; label?: string }) => void,
-) {
-  for (const entry of sidebar) {
-    const endpoint = 'attrs' in entry && entry.attrs?.['data-stldocs-endpoint'];
-    if (
-      'attrs' in entry &&
-      entry.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER &&
-      endpoint &&
-      typeof endpoint === 'string'
-    ) {
-      modifyFn(entry, {
-        endpoint,
-        label: entry.attrs?.['data-stldocs-label'],
-      });
-    }
-    if ('entries' in entry) {
-      recursiveReplacePlaceholderItems(entry.entries, modifyFn);
-    }
-  }
-}
-
 type GenerateProps = string | { label?: string; endpoint: string };
 
 function normalizeGenerateProps(generateProps: GenerateProps) {

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

@@ -1,5 +1,6 @@
 import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+import { CONTEXT_MENU_ENABLE_THIRD_PARTY } from 'virtual:stl-docs-virtual-module';
 
 export type DropdownIcon = 'markdown' | 'copy' | 'claude' | 'chatgpt' | 'gemini' | 'cursor';
 
@@ -9,6 +10,7 @@ interface DropdownOptionInputProps {
   primaryAction?: boolean;
   clientHidden?: () => boolean;
   external: boolean;
+  thirdParty?: boolean;
 }
 
 function option(label: string[] | string, props: DropdownOptionInputProps) {
@@ -101,6 +103,7 @@ const aiDropdownOptions: DropdownOption[][] = [
       icon: 'claude',
       primaryAction: false,
       external: true,
+      thirdParty: true,
     }),
     option(['Open in ', 'ChatGPT'], {
       onClick: () => {
@@ -109,6 +112,7 @@ const aiDropdownOptions: DropdownOption[][] = [
       icon: 'chatgpt',
       primaryAction: false,
       external: true,
+      thirdParty: true,
     }),
     option(['Open in ', 'Cursor'], {
       onClick: () => {
@@ -122,6 +126,7 @@ const aiDropdownOptions: DropdownOption[][] = [
       icon: 'cursor',
       primaryAction: false,
       external: true,
+      thirdParty: true,
     }),
   ],
   [
@@ -142,7 +147,9 @@ const aiDropdownOptions: DropdownOption[][] = [
               .then((response) => response.text())
               .then((text) => new Blob([text], { type: 'text/plain' })),
           });
-          navigator.clipboard.write([text]);
+          navigator.clipboard.write([text]).catch(() => {
+            console.error('Failed to copy to clipboard using ClipboardItem');
+          });
         } else {
           // NOTE: Firefox has support for ClipboardItem and navigator.clipboard.write,
           //   but those are behind `dom.events.asyncClipboard.clipboardItem` preference.
@@ -150,7 +157,10 @@ const aiDropdownOptions: DropdownOption[][] = [
           //   Clipboard API being used async in a Promise.
           fetch(markdownUrl)
             .then((response) => response.text())
-            .then((text) => navigator.clipboard.writeText(text));
+            .then((text) => navigator.clipboard.writeText(text))
+            .catch(() => {
+              console.error('Failed to copy to clipboard');
+            });
         }
       },
       icon: 'copy',
@@ -179,13 +189,16 @@ const aiDropdownOptions: DropdownOption[][] = [
 // },
 
 export function getAIDropdownOptions() {
-  const renderedOptions = aiDropdownOptions.map((group, index) => {
-    return {
-      options: group,
-      isLast: index === aiDropdownOptions.length - 1,
-      reactKey: index,
-    };
-  });
+  const renderedOptions = aiDropdownOptions
+    .map((e) => e.filter((e) => CONTEXT_MENU_ENABLE_THIRD_PARTY || !e.thirdParty))
+    .filter((e) => e.length)
+    .map((group, index, array) => {
+      return {
+        options: group,
+        isLast: index === array.length - 1,
+        reactKey: index,
+      };
+    });
 
   const allOptions = renderedOptions.flatMap((group) => group.options);
   const primaryAction = allOptions.find((o) => o.primaryAction) ?? allOptions[0]!;

package/plugin/globalJs/code-snippets.ts

@@ -13,7 +13,7 @@ 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
@@ -29,8 +29,8 @@ document.addEventListener(getPageLoadEvent(), () => {
   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) => {
@@ -71,7 +71,7 @@ document.addEventListener(getPageLoadEvent(), () => {
       el.style.height = `${endHeight}px`;
     };
 
-    if (collapsedDiv) {
+    if (collapsedDiv instanceof HTMLElement) {
       if (collapsedDiv) {
         collapsedDiv.querySelector('.shiki')?.setAttribute('style', `counter-reset: codeblock-line 0`);
       }
@@ -80,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);

package/plugin/globalJs/copy.ts

@@ -1,10 +1,4 @@
-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';
+import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
 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"/>`;
@@ -22,94 +16,29 @@ function getContent(button: HTMLElement, full: boolean) {
     contentCopy.querySelectorAll('.leading-ws').forEach((el) => el.remove());
   }
 
-  return contentCopy.textContent!;
+  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;
+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 {
-      await navigator.clipboard.writeText(getContent(copyButton, false));
-      iconElement.innerHTML = checkIcon;
-    } catch {
-      iconElement.innerHTML = circleAlertIcon;
-    }
-    copyButton.dataset.__stldocsCopyTimeout =
-      setTimeout(() => {
-        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');
-    const { default: playgroundData } = await import('virtual:stl-playground/data');
-    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,
-      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) => {
-      showPlayground(e as HTMLElement);
-    });
+    navigator.clipboard
+      .writeText(getContent(copyButton, false))
+      .then(() => {
+        iconElement.innerHTML = checkIcon;
+      })
+      .catch(() => {
+        iconElement.innerHTML = circleAlertIcon;
+      })
+      .finally(() => {
+        copyButton.dataset.__stldocsCopyTimeout = setTimeout(() => {
+          iconElement.innerHTML = copyIcon;
+        }).toString();
+      });
   }
 });

package/plugin/globalJs/navigation.ts

@@ -27,7 +27,9 @@ document.addEventListener(getPageLoadEvent(), () => {
       root: rootElement,
       onSelect: (value) => {
         const originalLanguage = rootElement.dataset.currentValue;
-        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
+        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value)).catch((e) => {
+          console.error('Failed to navigate to selected language', e);
+        });
       },
     });
   });
@@ -37,24 +39,22 @@ document.addEventListener(getPageLoadEvent(), () => {
 });
 
 document.addEventListener('click', (event) => {
-  const toggle = (event.target as HTMLElement).closest(
-    '[data-stldocs-property-toggle-expanded] > .stldocs-expand-toggle-content',
-  )?.parentElement;
+  const toggle =
+    event.target instanceof HTMLElement && event.target.closest('[data-stldocs-property-toggle-expanded]');
+  if (!toggle || !(toggle instanceof HTMLElement)) return;
 
-  if (!toggle) 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/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 },
+);