@stainless-api/docs 0.1.0-beta.4 → 0.1.0-beta.40

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

@@ -0,0 +1,235 @@
+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: () => {
+          triggerOption(primaryAction.id);
+        },
+      });
+    });
+  });
+}

package/plugin/globalJs/navigation.ts

@@ -1,12 +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 { 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';
 
@@ -24,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));
     },
   });
@@ -36,27 +37,6 @@ document.addEventListener(getPageLoadEvent(), () => {
   if (path) setTimeout(() => scrollToPath(path.slice(1)), 10);
 });
 
-document.addEventListener(getPageLoadEvent(), () => {
-  console.log('Initializing AI Dropdown');
-  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',

package/plugin/helpers/getPageLoadEvent.ts

@@ -1,4 +1,4 @@
-// import { ENABLE_CLIENT_ROUTER } from 'virtual:stl-stl-starlight-virtual-module';
+// import { ENABLE_CLIENT_ROUTER } from 'virtual:stl-docs-virtual-module';
 
 export function getPageLoadEvent() {
   // if (ENABLE_CLIENT_ROUTER) {

package/plugin/index.ts

@@ -1,6 +1,6 @@
 import react from '@astrojs/react';
 import type { StarlightPlugin } from '@astrojs/starlight/types';
-import type { AstroIntegration } from 'astro';
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
 import { config } from 'dotenv';
 import getPort from 'get-port';
 import { startDevServer } from './cms/server';
@@ -21,13 +21,18 @@ import {
   type SpecRetrieverConfig,
 } from './loadPluginConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
+import type * as StlStarlightVirtualModule from 'virtual:stl-starlight-virtual-module';
 import path from 'path';
 import fs from 'fs';
+import { getSharedLogger } from '../shared/getSharedLogger';
+import { resolveSrcFile } from '../resolveSrcFile';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
 
-config();
+config({
+  quiet: true,
+});
 
 let sidebarIdCounter = 0;
 
@@ -108,6 +113,7 @@ function tmpGetCMSServerConfig(specRetrieverConfig: SpecRetrieverConfig) {
 
 async function stlStarlightAstroIntegration(
   pluginConfig: NormalizedStainlessStarlightConfig,
+  stlStarlightPluginLogger: AstroIntegrationLogger,
 ): Promise<AstroIntegration> {
   const virtualId = `virtual:stl-starlight-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
@@ -117,11 +123,12 @@ async function stlStarlightAstroIntegration(
 
   const { apiKey, version, devPaths } = tmpGetCMSServerConfig(pluginConfig.specRetrieverConfig);
 
-  const cmsServer = await startDevServer({
+  const cmsServer = startDevServer({
     port: CMS_PORT,
-    apiKey,
+    apiKey: apiKey.value,
     version,
     devPaths,
+    logger: stlStarlightPluginLogger,
     getGeneratedSidebarConfig: (id: number) => {
       const config = sidebarConfigs.get(id);
       if (!config) {
@@ -134,43 +141,45 @@ async function stlStarlightAstroIntegration(
   return {
     name: 'stl-starlight-astro',
     hooks: {
-      'astro:config:setup': async ({ injectRoute, updateConfig, logger, command, config: astroConfig }) => {
+      'astro:config:setup': async ({
+        injectRoute,
+        updateConfig,
+        logger: localLogger,
+        command,
+        config: astroConfig,
+      }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
         const projectDir = astroConfig.root.pathname;
 
         const middlewareFile = path.join(projectDir, 'middleware.stainless.ts');
 
         let vmMiddlewareExport = 'export const MIDDLEWARE = {};';
         if (fs.existsSync(middlewareFile)) {
-          logger.info(`Loading middleware from ${middlewareFile}`);
+          logger.debug(`Loading middleware from ${middlewareFile}`);
           vmMiddlewareExport = `export { default as MIDDLEWARE } from '${middlewareFile}';`;
         }
 
         injectRoute({
-          pattern: `${pluginConfig.basePath}/[...slug].md`,
-          entrypoint: '@stainless-api/docs/MarkdownRoute',
+          pattern: `${pluginConfig.basePath}/[...slug]/index.md`,
+          entrypoint: resolveSrcFile('/plugin/routes/markdown.ts'),
           prerender: command === 'build',
         });
 
-        const astroFile = command === 'build' ? 'DocsStaticRoute' : 'DocsRoute';
+        const astroFile = command === 'build' ? 'DocsStatic' : 'Docs';
         injectRoute({
           pattern: `${pluginConfig.basePath}/[...slug]`,
-          // in prod I think this points to @stainless-starlight/components/docs.astro
-          entrypoint: `@stainless-api/docs/${astroFile}`,
+          entrypoint: resolveSrcFile(`/plugin/routes/${astroFile}.astro`),
           prerender: command === 'build',
         });
 
         injectRoute({
           pattern: pluginConfig.basePath,
-          entrypoint: '@stainless-api/docs/OverviewRoute',
+          entrypoint: resolveSrcFile('/plugin/routes/Overview.astro'),
           prerender: command === 'build',
         });
 
         updateConfig({
           vite: {
-            ssr: {
-              noExternal: ['@stainless-api/ui-primitives'],
-            },
-            optimizeDeps: { include: ['@stainless-api/ui-primitives'] },
             plugins: [
               {
                 name: 'stl-starlight-vite',
@@ -213,7 +222,8 @@ async function stlStarlightAstroIntegration(
                         EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: pluginConfig.experimentalCollapsibleSnippets,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         SEARCH: pluginConfig.search,
-                      }),
+                        ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
+                      } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
                   }
@@ -241,15 +251,20 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
         command,
         config: starlightConfig,
         astroConfig,
-        logger,
+        logger: localLogger,
       }) => {
         if (command !== 'build' && command !== 'dev') {
           return;
         }
 
+        const logger = getSharedLogger({ fallback: localLogger });
+
         const configParseResult = parseStarlightPluginConfig(someUserConfig, command);
         if (configParseResult.result === 'error') {
-          logger.error(configParseResult.message);
+          const errorLines = configParseResult.message.split('\n');
+          for (const line of errorLines) {
+            logger.error(line);
+          }
           process.exit(1);
         }
         const config = configParseResult.config;
@@ -260,17 +275,30 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           addIntegration(react());
         }
 
+        if ('apiKey' in config.specRetrieverConfig) {
+          if (!config.specRetrieverConfig.apiKey) {
+            logger.info(`Stainless credentials not loaded`);
+          } else if (config.specRetrieverConfig.apiKey.source === 'explicit-config') {
+            logger.info(`Stainless credentials loaded from user config`);
+          } else if (config.specRetrieverConfig.apiKey.source === 'environment-variable') {
+            logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
+          } else if (config.specRetrieverConfig.apiKey.source === 'cli') {
+            logger.info('Stainless credentials loaded from `stl` CLI');
+          }
+        }
+
         if (
           command === 'build' &&
           config.specRetrieverConfig.kind === 'local_spec_server_with_remote_files'
         ) {
           await buildAlgoliaIndex({
             version: config.specRetrieverConfig.version,
-            apiKey: config.specRetrieverConfig.apiKey,
+            apiKey: config.specRetrieverConfig.apiKey.value,
+            logger,
           });
         }
 
-        addIntegration(await stlStarlightAstroIntegration(config));
+        addIntegration(await stlStarlightAstroIntegration(config, logger));
 
         if (starlightConfig.sidebar) {
           // for pagination (https://starlight.astro.build/reference/configuration/#pagination) to work correctly
@@ -295,7 +323,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
         });
 
         addRouteMiddleware({
-          entrypoint: '@stainless-api/docs/replaceSidebarPlaceholderMiddleware',
+          entrypoint: resolveSrcFile('/plugin/replaceSidebarPlaceholderMiddleware.ts'),
           order: 'post',
         });
       },
@@ -304,5 +332,5 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 }
 
 // Additional exports we want for Stainless <-> docs integration.
-export { parseStainlessPath } from '@stainless-api/docs-ui/src/routing';
-export { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+export { parseStainlessPath } from '@stainless-api/docs-ui/routing';
+export { renderMarkdown } from '@stainless-api/docs-ui/markdown';

package/plugin/languages.ts

@@ -1,4 +1,4 @@
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import KotlinIcon from './assets/languages/kotlin.svg';
 import RubyIcon from './assets/languages/ruby.svg';
 import TerraformIcon from './assets/languages/terraform.svg';
@@ -44,7 +44,7 @@ export function applyLanguageToLinks(basePath?: string, defaultLanguage?: string
     `[data-stldocs-overview],[data-stldocs-method],a.nav-link[href^='${basePath}']`,
   );
 
-  for (var link of links) {
+  for (const link of links) {
     const href = link.getAttribute('href');
     const prefix = generatePrefix(basePath, language);
     if (href?.startsWith(basePath) && !href?.startsWith(prefix)) {