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

package/plugin/vendor/templates/go.md

@@ -31,7 +31,7 @@ SDK_ReleasePleaseMarkdownBlockEnd
 
 ## Requirements
 
-This library requires Go 1.18+.
+This library requires Go 1.22+.
 
 ## Usage
 

package/plugin/vendor/templates/python.md

@@ -242,7 +242,7 @@ print(SDK_PythonPackageImportName.__version__)
 
 ## Requirements
 
-Python 3.8 or higher.
+Python 3.9 or higher.
 
 ## Contributing
 

package/resolveSrcFile.ts

@@ -0,0 +1,10 @@
+import { join } from 'path';
+const dirName = import.meta.dirname;
+/**
+ * Resolve a source file path relative to the stl-starlight package.
+ * @param projectPath - The relative path to the source file.
+ * @returns The absolute path to the source file.
+ */
+export function resolveSrcFile(...projectPath: string[]) {
+  return join(dirName, ...projectPath);
+}

package/scripts/vendor_deps.ts

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
 
-import { Languages } from '@stainless-api/docs-ui/src/routing';
+import { Languages } from '@stainless-api/docs-ui/routing';
 
 const DEPS_DIR = './plugin/vendor';
 
@@ -11,12 +11,12 @@ config();
 
 const envSchema = z.object({
   // absolute path to the Stainless monorepo root
-  STAINLESS_MONOREPO_PATH: z.string(),
+  STAINLESS_ROOT: z.string(),
 });
 
 const env = envSchema.parse(process.env);
 
-console.log(`Using Stainless monorepo at ${env.STAINLESS_MONOREPO_PATH}`);
+console.log(`Using Stainless monorepo at ${env.STAINLESS_ROOT}`);
 
 if (fs.existsSync(DEPS_DIR)) {
   fs.rmSync(DEPS_DIR, { recursive: true });
@@ -25,11 +25,11 @@ if (fs.existsSync(DEPS_DIR)) {
 fs.mkdirSync(DEPS_DIR, { recursive: true });
 
 const previewWorkerPath = path.join(
-  env.STAINLESS_MONOREPO_PATH,
+  env.STAINLESS_ROOT,
   '/packages/preview-worker/dist/stainless/preview.worker.docs.js',
 );
 
-const readmeTemplatePath = path.join(env.STAINLESS_MONOREPO_PATH, '/legacy-dir-root/templates');
+const readmeTemplatePath = path.join(env.STAINLESS_ROOT, '/legacy-dir-root/templates');
 
 fs.copyFileSync(previewWorkerPath, path.join(DEPS_DIR, 'preview.worker.docs.js'));
 

package/shared/getProsePages.ts

@@ -0,0 +1,42 @@
+import { readdir } from 'fs/promises';
+import { join, relative } from 'path';
+
+/**
+ * Get all prose pages after a build, by reading all HTML files from the
+ * given output directory, and not from assets.
+ *
+ * We cannot use the `assets` map here because it is not guaranteed to
+ * contain all files, especially if they were generated by other integrations.
+ * Other astro integrations may hijack the "[...slug]" entrypoint, and any files
+ * previously in the [...slug] asset map entry would be lost (this is where starlight stores
+ * its prose HTML files).
+ */
+export async function getProsePages({
+  apiReferenceBasePath,
+  outputBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+  outputBasePath: string;
+}): Promise<string[]> {
+  const allFiles = await readdir(outputBasePath, {
+    recursive: true,
+    withFileTypes: true,
+  });
+
+  const htmlFiles = allFiles
+    .filter((file) => file.isFile() && file.name.endsWith('.html'))
+    .map((file) => join(file.parentPath, file.name));
+
+  // Filter out API reference pages
+  const pagesToRender = htmlFiles.filter((absPath) => {
+    if (!apiReferenceBasePath) {
+      return true;
+    }
+    const relPath = relative(outputBasePath, absPath);
+    // Normalize by removing leading/trailing slashes from apiReferenceBasePath
+    const normalizedApiPath = apiReferenceBasePath.replace(/^\/+|\/+$/g, '');
+    return !relPath.startsWith(normalizedApiPath);
+  });
+
+  return pagesToRender;
+}

package/shared/getSharedLogger.ts

@@ -0,0 +1,15 @@
+import { AstroIntegrationLogger } from 'astro';
+
+let sharedLogger: AstroIntegrationLogger | null = null;
+
+// This is probably temporary, but it's a quick way to share a logger between our many integrations
+// we want to share a logger so they have the same "stainless" label
+
+export function setSharedLogger(logger: AstroIntegrationLogger) {
+  sharedLogger = logger;
+}
+
+// a fallback is probably not required, but it's a good safeguard in case we somehow call a logger before the shared logger is set
+export function getSharedLogger({ fallback }: { fallback: AstroIntegrationLogger }) {
+  return sharedLogger ?? fallback;
+}

package/shared/terminalUtils.ts

@@ -0,0 +1,3 @@
+export function bold(text: string) {
+  return `\x1b[1m${text}\x1b[0m`;
+}

package/src/content.config.ts

@@ -0,0 +1,9 @@
+// Stub here so that `astro sync` generates the correct types for the `docs` content collection
+
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/stl-docs/components/AIDropdown.tsx

@@ -0,0 +1,63 @@
+import { DropdownButton } from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+import { ChatGPTIcon } from './icons/chat-gpt';
+import { ClaudeIcon } from './icons/claude';
+import { GeminiIcon } from './icons/gemini';
+import { MarkdownIcon } from './icons/markdown';
+import { CursorIcon } from './icons/cursor';
+import React from 'react';
+
+import { getAIDropdownOptions, type DropdownIcon } from '../../plugin/globalJs/ai-dropdown-options';
+
+const iconMap: { [key in DropdownIcon]: React.ReactNode } = {
+  markdown: <MarkdownIcon />,
+  copy: <CopyIcon size={16} />,
+  claude: <ClaudeIcon />,
+  chatgpt: <ChatGPTIcon />,
+  gemini: <GeminiIcon />,
+  cursor: <CursorIcon />,
+};
+
+const { primaryAction, groups } = getAIDropdownOptions();
+
+function ItemLabel({ label }: { label: string[] }) {
+  if (label.length > 1) {
+    return (
+      <DropdownButton.MenuItemText subtle>
+        {label[0]}
+        <strong>{label[1]}</strong>
+      </DropdownButton.MenuItemText>
+    );
+  }
+
+  return (
+    <DropdownButton.MenuItemText>
+      <strong>{label[0]}</strong>
+    </DropdownButton.MenuItemText>
+  );
+}
+
+export function AIDropdown() {
+  return (
+    <DropdownButton data-dropdown-id="ai-dropdown-button">
+      <DropdownButton.PrimaryAction>
+        {iconMap[primaryAction.icon]}
+        <DropdownButton.PrimaryActionText>{primaryAction.label}</DropdownButton.PrimaryActionText>
+      </DropdownButton.PrimaryAction>
+      <DropdownButton.Trigger />
+      <DropdownButton.Menu>
+        {groups.map((group) => (
+          <React.Fragment key={group.reactKey}>
+            {group.options.map((option) => (
+              <DropdownButton.MenuItem value={option.id} isExternalLink={option.external} key={option.id}>
+                <DropdownButton.Icon>{iconMap[option.icon]}</DropdownButton.Icon>
+                <ItemLabel label={option.label} />
+              </DropdownButton.MenuItem>
+            ))}
+            {group.isLast ? null : <hr />}
+          </React.Fragment>
+        ))}
+      </DropdownButton.Menu>
+    </DropdownButton>
+  );
+}

package/stl-docs/components/AiChatIsland.tsx

@@ -0,0 +1,14 @@
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import AiChat, { STAINLESS_PROJECT } from 'virtual:stl-docs/components/AiChat.tsx';
+
+export default function AiChatIsland({
+  currentLanguage,
+  siteTitle,
+}: {
+  currentLanguage: DocsLanguage | undefined;
+  siteTitle: string | undefined;
+}) {
+  if (!AiChat) throw new Error('AiChatIsland was rendered but could not load AiChat component');
+  if (!STAINLESS_PROJECT) return null;
+  return <AiChat projectId={STAINLESS_PROJECT} language={currentLanguage} siteTitle={siteTitle} />;
+}

package/stl-docs/components/{content-panel/ContentBreadcrumbs.tsx → ContentBreadcrumbs.tsx}

@@ -1,29 +1,26 @@
 import { ChevronRight } from 'lucide-react';
-import { Join } from '@stainless-api/docs-ui/src/components';
-import style from '@stainless-api/docs-ui/src/style';
+import { Join } from '@stainless-api/docs-ui/components';
+import style from '@stainless-api/docs-ui/style';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 type Breadcrumb = { title: string; href: string };
 
-// because this component is used in Stainless Docs and stl-starlight, we need to conditionally import the BASE_PATH from the virtual module
-let basePath: string | null = null;
-try {
-  const mod = await import('virtual:stl-starlight-virtual-module');
-  basePath = mod.BASE_PATH;
-  // eslint-disable-next-line no-empty, @typescript-eslint/no-unused-vars
-} catch (_e) {}
-
 // Normalize paths to avoid mismatches due to trailing slashes
 function normalizePath(path: string) {
   return path.endsWith('/') ? path : path + '/';
 }
 
-function findBreadcrumbTrail(
-  entries: StarlightRouteData['sidebar'],
+export function findBreadcrumbTrail(
+  sidebarEntry: StarlightRouteData['sidebar'],
   targetPath: string,
   includeCurrentPage: boolean,
   trail: Breadcrumb[] = [],
 ): Breadcrumb[] | null {
+  const entries = sidebarEntry.filter((entry) => {
+    return !(
+      entry as StarlightRouteData['sidebar'][number] & { attrs?: { class?: string } }
+    ).attrs?.class?.includes('stl-mobile-only-sidebar-item');
+  });
   const normalizedTarget = normalizePath(targetPath);
 
   for (const entry of entries) {
@@ -57,12 +54,7 @@ export function ContentBreadcrumbs({
   currentPath: string;
   sidebarEntry: StarlightRouteData['sidebar'];
 }) {
-  if (basePath && currentPath.startsWith(basePath)) {
-    return null;
-  }
-
-  const entryWithoutTopLevelLinks = sidebarEntry.filter((entry) => entry.type !== 'link');
-  const breadcrumbs = findBreadcrumbTrail(entryWithoutTopLevelLinks, currentPath, true);
+  const breadcrumbs = findBreadcrumbTrail(sidebarEntry, currentPath, true);
 
   if (!breadcrumbs) {
     return null;

package/stl-docs/components/Head.astro

@@ -0,0 +1,16 @@
+---
+import Default from '@astrojs/starlight/components/Head.astro';
+
+// TODO: for users who are overriding the font stack in their own styles, how can we know that and
+// preload their font instead of ours?
+import geistPath from '../../assets/fonts/geist/geist-latin.woff2';
+---
+
+<Default />
+
+<link rel="preload" as="font" type="font/woff2" crossorigin="anonymous" href={geistPath} />
+
+<script>
+  import { wireAIDropdown } from '../../plugin/globalJs/ai-dropdown-options.ts';
+  wireAIDropdown();
+</script>

package/stl-docs/components/Header.astro

@@ -23,12 +23,9 @@ const shouldRenderSearch = !!(
 
 <style is:global>
   @layer starlight.core {
-    header {
-      border-color: var(--sl-color-hairline);
-
-      &.header {
-        border-bottom-color: var(--sl-color-hairline);
-      }
+    header,
+    header.header {
+      border-color: var(--stl-color-border-faint);
     }
 
     .header {
@@ -44,9 +41,10 @@ const shouldRenderSearch = !!(
       overflow: clip;
       /* Avoid clipping focus ring around link inside title wrapper. */
       padding: 0.25rem;
-      padding-left: 0;
       margin: -0.25rem;
       min-width: 0;
+      /* Max height should match button height */
+      max-height: 32px;
     }
 
     .default-tabs-container {
@@ -84,7 +82,7 @@ const shouldRenderSearch = !!(
 
     @media (min-width: 50rem) {
       .default-tabs-container {
-        min-width: 440px;
+        min-width: 540px;
       }
     }
   }

package/stl-docs/components/PageFrame.astro

@@ -0,0 +1,18 @@
+---
+import Default from '@astrojs/starlight/components/PageFrame.astro';
+import AiChat from 'virtual:stl-docs/components/AiChat.tsx'; // conditionally resolves to null if ai chat module is not injected
+import AiChatIsland from './AiChatIsland.tsx'; // entrypoint for client island can’t be a virtual module
+
+import starlightConfig from 'virtual:starlight/user-config';
+const locale = Astro.currentLocale ?? starlightConfig.defaultLocale.lang;
+const siteTitle = locale && starlightConfig.title[locale];
+---
+
+<Default>
+  <slot name="header" slot="header" />
+  <slot name="sidebar" slot="sidebar" />
+
+  <slot />
+
+  {!!AiChat && <AiChatIsland client:load currentLanguage={Astro.locals.language} siteTitle={siteTitle} />}
+</Default>

package/stl-docs/components/PageTitle.astro

@@ -0,0 +1,82 @@
+---
+import {
+  ENABLE_PROSE_MARKDOWN_RENDERING,
+  ENABLE_CONTEXT_MENU,
+  RENDER_PAGE_DESCRIPTIONS,
+} from 'virtual:stl-docs-virtual-module';
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import Default from '@astrojs/starlight/components/PageTitle.astro';
+import { ContentBreadcrumbs } from './ContentBreadcrumbs';
+import { AIDropdown } from './AIDropdown';
+
+function sidebarHasEntry(sidebarEntry: StarlightRouteData['sidebar'], currentPath?: string) {
+  if (!currentPath) return false;
+  const normalizePath = (path: string) => {
+    return path.endsWith('/') ? path : path + '/';
+  };
+
+  const normalizedCurrent = normalizePath(currentPath);
+
+  for (const entry of sidebarEntry) {
+    if (entry.type === 'link') {
+      const normalizedHref = normalizePath(entry.href);
+      if (normalizedHref === normalizedCurrent) {
+        return true;
+      }
+    } else if (entry.type === 'group') {
+      const hasInGroup = sidebarHasEntry(entry.entries, currentPath);
+      if (hasInGroup) return true;
+    }
+  }
+
+  return false;
+}
+
+const skipRenderingStarlightTitle = Astro.locals._stlStarlightPage?.skipRenderingStarlightTitle ?? false;
+
+const hasMarkdownRoute = Astro.locals._stlStarlightPage?.hasMarkdownRoute ?? true;
+// ⬆️ hopefully this is temporary. But for now, we don't have a markdown representation of the API reference overview page
+
+const currentPath = Astro.url.pathname;
+
+function shouldShowAIDropdown() {
+  // Hide if there is no associated sidebar entry. This applies to pages like the 404 page.
+  const hasSidebarEntry = sidebarHasEntry(Astro.locals.starlightRoute.sidebar, currentPath);
+  if (!hasSidebarEntry) return false;
+
+  if (!hasMarkdownRoute) return false;
+
+  if (!ENABLE_PROSE_MARKDOWN_RENDERING) return false;
+  if (!ENABLE_CONTEXT_MENU) return false;
+
+  return true;
+}
+
+const showAIDropdown = shouldShowAIDropdown();
+
+const description = Astro.locals.starlightRoute.entry.data.description;
+const shouldRenderDescription = RENDER_PAGE_DESCRIPTIONS;
+---
+
+{
+  skipRenderingStarlightTitle ? null : (
+    <>
+      <div class="stl-ui-not-prose stl-page-nav-container stl-prose-page-nav-container">
+        <ContentBreadcrumbs currentPath={currentPath} sidebarEntry={Astro.locals.starlightRoute.sidebar} />
+        {showAIDropdown && <AIDropdown />}
+      </div>
+      <Default />
+      {!!description && shouldRenderDescription && <p class="description">{description}</p>}
+    </>
+  )
+}
+
+<style>
+  p.description {
+    font-size: var(--stl-typography-scale-xl);
+    font-weight: 400;
+    line-height: 1.4;
+    letter-spacing: -0.02em;
+    margin-top: 0.4em;
+  }
+</style>

package/stl-docs/components/TableOfContents.astro

@@ -0,0 +1,34 @@
+---
+import Default from '@astrojs/starlight/components/TableOfContents.astro';
+---
+
+<Default {...Astro.props} />
+
+<script>
+  /**
+   * Starlight will mark TOC links as active as they are scrolled to. However, it does not mark
+   * a link as active if it cannot be scrolled to on the page. This happens for small sections at
+   * the bottom of the page which are not large enough to scroll to the top of the viewport.
+   *
+   * This script will mark a section as active if its corresponding hash is in the URL, even if
+   * it cannot be scrolled to.
+   */
+  document.addEventListener('DOMContentLoaded', () => {
+    const tocLinks = document.querySelectorAll('starlight-toc a') as NodeListOf<HTMLAnchorElement>;
+
+    function updateAriaCurrent() {
+      const current = decodeURIComponent(window.location.hash || '');
+      tocLinks.forEach((link) => {
+        const linkHash = decodeURIComponent(link.hash || link.getAttribute('href') || '');
+        if (linkHash === current) {
+          link.setAttribute('aria-current', 'true');
+        } else {
+          link.removeAttribute('aria-current');
+        }
+      });
+    }
+
+    window.addEventListener('hashchange', updateAriaCurrent);
+    updateAriaCurrent();
+  });
+</script>

package/stl-docs/components/ThemeProvider.astro

@@ -0,0 +1,36 @@
+{/* Inlined to avoid FOUC. All theme selects are initialized here */}
+<script is:inline>
+  window.didInitThemePickers = window.didInitThemePickers ?? false;
+
+  // Only run once.
+  if (!window.didInitThemePickers) {
+    window.didInitThemePickers = true;
+
+    // The stored theme will be either 'auto', 'light', 'dark' or null.
+    const storedTheme = typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
+
+    // This theme is either 'light' or 'dark'. It's used for setting the data-theme attribute.
+    const theme =
+      !storedTheme || storedTheme === 'auto'
+        ? window.matchMedia('(prefers-color-scheme: light)').matches
+          ? 'light'
+          : 'dark'
+        : storedTheme;
+
+    document.documentElement.dataset.theme = theme === 'light' ? 'light' : 'dark';
+
+    const themeSelects = document.querySelectorAll('[data-theme-select]');
+    const selectedThemeValue = storedTheme || 'auto';
+
+    themeSelects.forEach((select) => {
+      const tmpl = select.querySelector(`[data-value="${selectedThemeValue}"] template`);
+      const selectedSlot = select.querySelector('[data-part="trigger-selected"]');
+
+      selectedSlot.innerHTML = '';
+      if (tmpl) {
+        selectedSlot.appendChild(tmpl.content.cloneNode(true));
+        return;
+      }
+    });
+  }
+</script>