@stainless-api/docs 0.1.0-beta.0

package/plugin/globalJs/navigation.ts

@@ -0,0 +1,81 @@
+import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/src/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';
+
+history.scrollRestoration = 'auto';
+
+function getStainlessPathForLocation() {
+  return document.location.hash
+    ? decodeURI(document.location.hash)
+    : parseRoute(BASE_PATH, document.location.href)?.stainlessPath;
+}
+
+window.addEventListener('popstate', (ev: PopStateEvent) => {
+  const path = getStainlessPathForLocation();
+  if (!path) return;
+  ev.preventDefault();
+  setTimeout(() => scrollToPath(path.slice(1)), 10);
+});
+
+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));
+    },
+  });
+
+  const path = getStainlessPathForLocation();
+  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',
+  )?.parentElement;
+
+  if (!toggle) return;
+
+  const state = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
+  toggle.dataset.stldocsPropertyToggleExpanded = state ? 'false' : 'true';
+
+  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;
+  });
+});

package/plugin/globalJs/tooltip.ts

@@ -0,0 +1,32 @@
+window.addEventListener('DOMContentLoaded', () => {
+  document.querySelectorAll('.stldocs-tooltip').forEach((tooltip) => {
+    const target = tooltip.querySelector<HTMLDivElement>('.stldocs-tooltip-host');
+
+    const content = tooltip.querySelector<HTMLDivElement>('.stldocs-tooltip-content');
+
+    if (!target || !content) return;
+
+    target.addEventListener('mouseenter', () => {
+      const targetRect = target.getBoundingClientRect();
+      const contentRect = content.getBoundingClientRect();
+
+      let top = targetRect.bottom + window.scrollY;
+      let left = targetRect.left + window.scrollX;
+
+      if (targetRect.bottom + contentRect.height > window.innerHeight) {
+        top = targetRect.top + window.scrollY - contentRect.height;
+      }
+
+      if (targetRect.left + contentRect.width > window.innerWidth) {
+        left = targetRect.right + window.scrollX - contentRect.width;
+      }
+
+      if (left < window.scrollX) {
+        left = window.scrollX;
+      }
+
+      content.style.top = `${top}px`;
+      content.style.left = `${left}px`;
+    });
+  });
+});

package/plugin/helpers/getPageLoadEvent.ts

@@ -0,0 +1,8 @@
+// import { ENABLE_CLIENT_ROUTER } from 'virtual:stl-stl-starlight-virtual-module';
+
+export function getPageLoadEvent() {
+  // if (ENABLE_CLIENT_ROUTER) {
+  //   return 'astro:page-load';
+  // }
+  return 'DOMContentLoaded';
+}

package/plugin/index.ts

@@ -0,0 +1,308 @@
+import react from '@astrojs/react';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import type { AstroIntegration } from 'astro';
+import { config } from 'dotenv';
+import getPort from 'get-port';
+import { startDevServer } from './cms/server';
+import { buildAlgoliaIndex } from './buildAlgoliaIndex';
+import {
+  getAPIReferencePlaceholderItemFromSidebarConfig,
+  makePlaceholderItems,
+} from './referencePlaceholderUtils';
+import type {
+  GeneratedSidebarConfig,
+  ReferenceSidebarConfigGenerateOptions,
+  ReferenceSidebarConfigItem,
+} from './cms/sidebar-builder';
+import {
+  parseStarlightPluginConfig,
+  type NormalizedStainlessStarlightConfig,
+  type SomeStainlessStarlightUserConfig,
+  type SpecRetrieverConfig,
+} from './loadPluginConfig';
+import { buildVirtualModuleString } from '../shared/virtualModule';
+import path from 'path';
+import fs from 'fs';
+
+export { generateAPILink } from './generateAPIReferenceLink';
+export type { ReferenceSidebarConfigItem };
+
+config();
+
+let sidebarIdCounter = 0;
+
+const sidebarConfigs = new Map<number, GeneratedSidebarConfig>();
+
+type PlaceholderEntries = {
+  label: string;
+  link: string;
+  attrs?: any; // tbd what type this should be. I sort of don't want to say what it _really_ is, bc I don't want people messing with it
+}[];
+
+/**
+ * This returns placeholder entries that indicate where the API reference items should be inserted.
+ * The placeholder entries are replaced with the actual API reference items by the Stainless Starlight plugin.
+ *
+ * You may place the placeholders wherever you want your API reference items to be inserted.
+ *
+ * **IMPORTANT:** DO NOT MODIFY THESE ENTRIES. Doing so will prevent items from being inserted correctly.
+ */
+
+type SidebarTransformFn = GeneratedSidebarConfig['transformFn'];
+
+export function generateAPIReferenceItems(
+  options: ReferenceSidebarConfigGenerateOptions,
+  fn?: SidebarTransformFn,
+): PlaceholderEntries;
+export function generateAPIReferenceItems(fn?: SidebarTransformFn): PlaceholderEntries;
+export function generateAPIReferenceItems(
+  arg1: SidebarTransformFn | ReferenceSidebarConfigGenerateOptions,
+  arg2?: SidebarTransformFn,
+): PlaceholderEntries {
+  sidebarIdCounter++;
+  const id = sidebarIdCounter;
+
+  let fn: SidebarTransformFn | undefined;
+  if (typeof arg1 === 'function') {
+    fn = arg1;
+  } else if (typeof arg2 === 'function') {
+    fn = arg2;
+  }
+
+  let options: ReferenceSidebarConfigGenerateOptions | undefined;
+  if (typeof arg1 === 'object') {
+    options = arg1;
+  }
+
+  sidebarConfigs.set(id, { transformFn: fn, options });
+  return makePlaceholderItems(id);
+}
+
+function tmpGetCMSServerConfig(specRetrieverConfig: SpecRetrieverConfig) {
+  if (specRetrieverConfig.kind === 'external_spec_server') {
+    throw new Error('External spec server is not yet supported');
+  }
+  if (specRetrieverConfig.kind === 'local_spec_server_with_files') {
+    if (!specRetrieverConfig.apiKey) {
+      throw new Error('API key is required');
+    }
+    return {
+      apiKey: specRetrieverConfig.apiKey,
+      version: specRetrieverConfig.version,
+      devPaths: specRetrieverConfig.devPaths,
+    };
+  }
+
+  if (specRetrieverConfig.kind === 'local_spec_server_with_remote_files') {
+    return {
+      apiKey: specRetrieverConfig.apiKey,
+      version: specRetrieverConfig.version,
+      devPaths: {
+        oasPath: undefined,
+        configPath: undefined,
+      },
+    };
+  }
+  throw new Error('Invalid spec retriever config');
+}
+
+async function stlStarlightAstroIntegration(
+  pluginConfig: NormalizedStainlessStarlightConfig,
+): 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.
+  const resolvedId = `\0${virtualId}`;
+
+  const CMS_PORT = await getPort();
+
+  const { apiKey, version, devPaths } = tmpGetCMSServerConfig(pluginConfig.specRetrieverConfig);
+
+  const cmsServer = await startDevServer({
+    port: CMS_PORT,
+    apiKey,
+    version,
+    devPaths,
+    getGeneratedSidebarConfig: (id: number) => {
+      const config = sidebarConfigs.get(id);
+      if (!config) {
+        return null;
+      }
+      return config;
+    },
+  });
+
+  return {
+    name: 'stl-starlight-astro',
+    hooks: {
+      'astro:config:setup': async ({ injectRoute, updateConfig, logger, command, config: astroConfig }) => {
+        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}`);
+          vmMiddlewareExport = `export { default as MIDDLEWARE } from '${middlewareFile}';`;
+        }
+
+        injectRoute({
+          pattern: `${pluginConfig.basePath}/[...slug].md`,
+          entrypoint: '@stainless-api/docs/MarkdownRoute',
+          prerender: command === 'build',
+        });
+
+        const astroFile = command === 'build' ? 'DocsStaticRoute' : 'DocsRoute';
+        injectRoute({
+          pattern: `${pluginConfig.basePath}/[...slug]`,
+          // in prod I think this points to @stainless-starlight/components/docs.astro
+          entrypoint: `@stainless-api/docs/${astroFile}`,
+          prerender: command === 'build',
+        });
+
+        injectRoute({
+          pattern: pluginConfig.basePath,
+          entrypoint: '@stainless-api/docs/OverviewRoute',
+          prerender: command === 'build',
+        });
+
+        updateConfig({
+          vite: {
+            ssr: {
+              noExternal: ['@stainless-api/ui-primitives'],
+            },
+            optimizeDeps: { include: ['@stainless-api/ui-primitives'] },
+            plugins: [
+              {
+                name: 'stl-starlight-vite',
+                configureServer(server) {
+                  for (const filePath of Object.values(devPaths)) {
+                    if (!filePath) {
+                      continue;
+                    }
+                    server.watcher.add(filePath);
+                  }
+
+                  server.watcher.on('change', async (changed) => {
+                    if (Object.values(devPaths).includes(changed)) {
+                      logger.info(`${changed} changed, reloading...`);
+                      cmsServer.invalidate();
+                      server.hot.send({
+                        type: 'full-reload',
+                        path: '*',
+                      });
+                    }
+                  });
+                },
+                resolveId(id) {
+                  if (id === virtualId) {
+                    return resolvedId;
+                  }
+                },
+                load(id) {
+                  if (id === resolvedId) {
+                    return [
+                      buildVirtualModuleString({
+                        BASE_PATH: pluginConfig.basePath,
+                        CMS_PORT,
+                        EXCLUDE_LANGUAGES: pluginConfig.excludeLanguages,
+                        DEFAULT_LANGUAGE: pluginConfig.defaultLanguage,
+                        BREADCRUMB_CONFIG: pluginConfig.breadcrumbs,
+                        EXPAND_RESOURCES: pluginConfig.expandResources,
+                        HIGHLIGHT_THEMES: pluginConfig.highlighting.themes,
+                        CONTENT_PANEL_LAYOUT: pluginConfig.contentPanel.layout,
+                        EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: pluginConfig.experimentalCollapsibleSnippets,
+                        PROPERTY_SETTINGS: pluginConfig.propertySettings,
+                        SEARCH: pluginConfig.search,
+                      }),
+                      vmMiddlewareExport,
+                    ].join('\n');
+                  }
+                },
+              },
+            ],
+          },
+        });
+      },
+      'astro:server:done': async () => {
+        await cmsServer.destroy();
+      },
+    },
+  };
+}
+
+export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserConfig): StarlightPlugin {
+  return {
+    name: 'stl-starlight',
+    hooks: {
+      'config:setup': async ({
+        addIntegration,
+        updateConfig,
+        addRouteMiddleware,
+        command,
+        config: starlightConfig,
+        astroConfig,
+        logger,
+      }) => {
+        if (command !== 'build' && command !== 'dev') {
+          return;
+        }
+
+        const configParseResult = parseStarlightPluginConfig(someUserConfig, command);
+        if (configParseResult.result === 'error') {
+          logger.error(configParseResult.message);
+          process.exit(1);
+        }
+        const config = configParseResult.config;
+
+        const isReactLoaded = astroConfig.integrations.find(({ name }) => name === '@astrojs/react');
+
+        if (!isReactLoaded) {
+          addIntegration(react());
+        }
+
+        if (
+          command === 'build' &&
+          config.specRetrieverConfig.kind === 'local_spec_server_with_remote_files'
+        ) {
+          await buildAlgoliaIndex({
+            version: config.specRetrieverConfig.version,
+            apiKey: config.specRetrieverConfig.apiKey,
+          });
+        }
+
+        addIntegration(await stlStarlightAstroIntegration(config));
+
+        if (starlightConfig.sidebar) {
+          // for pagination (https://starlight.astro.build/reference/configuration/#pagination) to work correctly
+          // update the placeholder link to be correct
+          const item = getAPIReferencePlaceholderItemFromSidebarConfig(starlightConfig.sidebar);
+          if (item && typeof item === 'object' && 'link' in item) {
+            item.link = config.basePath;
+          }
+        }
+
+        const currentExpressiveCode =
+          typeof starlightConfig.expressiveCode === 'object' ? starlightConfig.expressiveCode : {};
+        updateConfig({
+          expressiveCode: {
+            ...currentExpressiveCode,
+            themes: [...(currentExpressiveCode.themes || []), 'github-light', 'github-dark'],
+          },
+        });
+
+        updateConfig({
+          sidebar: starlightConfig.sidebar,
+        });
+
+        addRouteMiddleware({
+          entrypoint: '@stainless-api/docs/replaceSidebarPlaceholderMiddleware',
+          order: 'post',
+        });
+      },
+    },
+  };
+}
+
+// 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';

package/plugin/languages.ts

@@ -0,0 +1,67 @@
+import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import KotlinIcon from './assets/languages/kotlin.svg';
+import RubyIcon from './assets/languages/ruby.svg';
+import TerraformIcon from './assets/languages/terraform.svg';
+import TypescriptIcon from './assets/languages/typescript.svg';
+import PythonIcon from './assets/languages/python.svg';
+import JavaIcon from './assets/languages/java.svg';
+import GoIcon from './assets/languages/go.svg';
+import CurlIcon from './assets/languages/curl.svg';
+
+export const Languages: Record<
+  DocsLanguage,
+  {
+    name: string;
+    icon: ((_props: astroHTML.JSX.SVGAttributes) => any) & ImageMetadata;
+    alt: string;
+  }
+> = {
+  node: { name: 'TypeScript', icon: TypescriptIcon, alt: 'Node.js logo' },
+  typescript: {
+    name: 'TypeScript',
+    icon: TypescriptIcon,
+    alt: 'TypeScript logo',
+  },
+  python: { name: 'Python', icon: PythonIcon, alt: 'Python logo' },
+  go: { name: 'Go', icon: GoIcon, alt: 'Go logo' },
+  java: { name: 'Java', icon: JavaIcon, alt: 'Java logo' },
+  kotlin: { name: 'Kotlin', icon: KotlinIcon, alt: 'Kotlin logo' },
+  http: { name: 'HTTP', icon: CurlIcon, alt: 'HTTP logo' },
+  terraform: { name: 'Terraform', icon: TerraformIcon, alt: 'Terraform logo' },
+  ruby: { name: 'Ruby', icon: RubyIcon, alt: 'Ruby logo' },
+};
+
+export function generatePrefix(basePath: string, language: string) {
+  return language === 'http' ? basePath : [basePath, language].join('/');
+}
+
+export function applyLanguageToLinks(basePath?: string, defaultLanguage?: string) {
+  const language = localStorage.getItem('stldocs-selected-language') ?? defaultLanguage;
+
+  if (!basePath || !language || language === 'http') return;
+
+  const links = document.querySelectorAll(
+    `[data-stldocs-overview],[data-stldocs-method],a.nav-link[href^='${basePath}']`,
+  );
+
+  for (var link of links) {
+    const href = link.getAttribute('href');
+    const prefix = generatePrefix(basePath, language);
+    if (href?.startsWith(basePath) && !href?.startsWith(prefix)) {
+      const rest = href.slice(basePath.length);
+      link.setAttribute('href', prefix + rest);
+    }
+  }
+}
+
+export function updateSelectedLanguage(
+  basePath: string,
+  previousLanguage: string | undefined,
+  newValue: string,
+) {
+  const previous = generatePrefix(basePath, previousLanguage ?? 'http');
+  const current = generatePrefix(basePath, newValue ?? 'http');
+  const rest = window.location.pathname.slice(previous.length);
+  localStorage.setItem('stldocs-selected-language', newValue);
+  return current + rest;
+}