@stainless-api/docs 0.1.0-beta.9 → 0.1.0-beta.90

package/plugin/react/Routing.tsx

@@ -1,22 +1,24 @@
 import * as React from 'react';
-import { marked } from 'marked';
-import hljs from 'highlight.js';
-import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
+import { marked, Tokens } from 'marked';
+
+import {
+  createMarkdownProcessor,
+  CreateShikiHighlighterOptions,
+  type MarkdownProcessor,
+} from '@astrojs/markdown-remark';
 import remarkGfmAlerts from 'remark-github-alerts';
 
 import type { MarkdownHeading } from 'astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { LanguageNames, SupportedLanguageSyntaxes, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 import {
-  generateRouteList,
   generateRoute,
   parseStainlessPath,
   walkTree,
-  SupportedLanguageSyntaxes,
   getLanguageSnippet,
-} from '@stainless-api/docs-ui/src/routing';
+} from '@stainless-api/docs-ui/routing';
 
 import {
   DocsProvider,
@@ -24,63 +26,46 @@ import {
   NavigationProvider,
   useSpec,
   type ContentPanelLayout,
-} from '@stainless-api/docs-ui/src/contexts';
+} from '@stainless-api/docs-ui/contexts';
 
-import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
 import {
   SDKMethod,
   SDKResource,
   type SDKRequestTitleProps,
   SDKBreadcrumbs,
-  Dropdown,
-  DropdownTrigger,
-  DropdownMenu,
-  DropdownItem,
   SDKIcon,
   SDKOverview,
   SDKLanguageBlock,
-} from '@stainless-api/docs-ui/src/components';
+} from '@stainless-api/docs-ui/components';
+
+import { Dropdown } from '@stainless-api/docs/components';
+
 import {
-  BASE_PATH,
+  RESOLVED_API_REFERENCE_PATH,
   EXCLUDE_LANGUAGES,
   EXPAND_RESOURCES,
   HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
-  INCLUDE_AI_DROPDOWN_OPTIONS,
+  ENABLE_CONTEXT_MENU,
+  EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS,
 } from 'virtual:stl-starlight-virtual-module';
-import style from '@stainless-api/docs-ui/src/style';
-import { createHighlighter, type BundledLanguage, type BundledTheme, type HighlighterGeneric } from 'shiki';
-import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
-import clsx from 'clsx';
+import style from '@stainless-api/docs-ui/style';
+import { BundledTheme, createHighlighter, HighlighterGeneric, type BundledLanguage } from 'shiki';
+import {
+  SnippetCode,
+  SnippetContainer,
+  SnippetButtons,
+  SnippetFooter,
+  SnippetResponse,
+} from '../components/SnippetCode';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
-import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
-import { APIReferenceAIDropdown } from '../../stl-docs/components/APIReferenceAIDropdown';
-
-export function generateDocsRoutes(spec: SDKJSON.Spec) {
-  const paths = generateRouteList({
-    spec,
-    excludeLanguages: EXCLUDE_LANGUAGES as DocsLanguage[],
-  });
-  const readmes = Object.entries(spec.readme)
-    .filter(([language]) => language !== 'http')
-    .filter(([language]) => !EXCLUDE_LANGUAGES.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 },
-    };
-  });
-}
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+import { AIDropdown } from '../../stl-docs/components/AIDropdown';
+import { ChevronsUpDownIcon } from 'lucide-react';
+import { MethodDescription } from '../components/MethodDescription';
 
 function isResourceNonEmpty(resource: SDKJSON.Resource) {
   return (
@@ -121,7 +106,6 @@ export function buildSidebar(
 
       const meths: SidebarEntry[] = Object.values(resource.methods ?? [])
         .filter((method) => spec.decls?.[language]?.[method.stainlessPath])
-        .toSorted((first, second) => first.name.localeCompare(second.name))
         .map((method) => ({
           type: 'link',
           isCurrent: current === method.stainlessPath,
@@ -153,19 +137,58 @@ export function buildPageNavigation(resource: SDKJSON.Resource, depth: number =
   return [...output, ...subs];
 }
 
-function renderMarkdown(content: string) {
-  return marked.parse(content, { gfm: true }) as string;
+async function renderMarkdown(content: string) {
+  const highlighter = await astroHighlight();
+
+  const renderer = {
+    code({ text, lang }: Tokens.Code) {
+      return shikiHighlight({
+        highlighter,
+        content: text,
+        language: lang,
+      });
+    },
+  };
+
+  marked.use({ renderer });
+  return marked.parse(content, {
+    gfm: true,
+  }) as string;
 }
 
-async function highlight(content: string, language?: string) {
-  if (language === 'json') return hljs.highlight(content, { language }).value;
-  const highlighter = await astroHighlight();
+function shikiHighlight({
+  highlighter,
+  content,
+  language,
+  themes,
+}: {
+  highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+  content: string;
+  language?: string;
+  themes?: CreateShikiHighlighterOptions['themes'] | Record<string, 'stainless-docs-json'>;
+}) {
+  let _themes = themes;
+  if (!themes && language === 'json') {
+    _themes = {
+      light: 'stainless-docs-json',
+      dark: 'stainless-docs-json',
+    };
+  }
+
+  if (!_themes) {
+    _themes = HIGHLIGHT_THEMES;
+  }
   return highlighter.codeToHtml(content, {
     lang: language ?? 'javascript',
-    themes: HIGHLIGHT_THEMES || {},
+    themes: _themes || {},
   });
 }
 
+async function highlight(content: string, language?: string) {
+  const highlighter = await astroHighlight();
+  return shikiHighlight({ highlighter, content, language });
+}
+
 export function SDKSelectReactComponent({
   selected,
   languages,
@@ -179,30 +202,36 @@ export function SDKSelectReactComponent({
 }) {
   return (
     <Dropdown id={id} data-current-value={selected} className={className}>
-      <DropdownTrigger
-        className="dropdown-toggle stldocs-button-tertiary"
-        type="button"
-        id="stldocs-snippet-title-button"
-        aria-expanded="false"
-        withChevron
-      >
-        <SDKIcon language={getLanguageSnippet(selected)} size={16} />
-        <span className={clsx('stl-snippet-dropdown-button-text', selected)}>{selected}</span>
-      </DropdownTrigger>
-      <DropdownMenu
+      <Dropdown.Trigger>
+        <Dropdown.TriggerSelectedItem>
+          <Dropdown.Icon>
+            <SDKIcon language={getLanguageSnippet(selected)} />
+          </Dropdown.Icon>
+          <span className="stl-snippet-dropdown-button-text">{LanguageNames[selected]}</span>
+        </Dropdown.TriggerSelectedItem>
+        <Dropdown.TriggerIcon>
+          <ChevronsUpDownIcon size={16} />
+        </Dropdown.TriggerIcon>
+      </Dropdown.Trigger>
+      <Dropdown.Menu
         className="dropdown-menu stl-sdk-select-dropdown-menu"
-        position="below"
-        aria-labelledby="stldocs-snippet-title-button"
+        aria-labelledby="stl-docs-snippet-title-button"
       >
         {languages.map((item) => (
-          <DropdownItem key={item} value={item} selected={item === selected}>
-            <div>
+          <Dropdown.MenuItem key={item} value={item} isSelected={item === selected}>
+            <Dropdown.Icon>
               <SDKIcon language={getLanguageSnippet(item)} size={16} />
-              <span className={clsx('stl-snippet-dropdown-button-text', item)}>{item}</span>
-            </div>
-          </DropdownItem>
+            </Dropdown.Icon>
+            <Dropdown.MenuItemText>{LanguageNames[item]}</Dropdown.MenuItemText>
+            <Dropdown.MenuItemTemplate>
+              <Dropdown.Icon>
+                <SDKIcon language={getLanguageSnippet(item)} size={16} />
+              </Dropdown.Icon>
+              <span className="stl-snippet-dropdown-button-text">{LanguageNames[item]}</span>
+            </Dropdown.MenuItemTemplate>
+          </Dropdown.MenuItem>
         ))}
-      </DropdownMenu>
+      </Dropdown.Menu>
     </Dropdown>
   );
 }
@@ -218,13 +247,13 @@ function SDKRequestTitle({ snippetLanguage }: SDKRequestTitleProps) {
       selected={selected || 'http'}
       languages={languages}
       id="stldocs-snippet-select"
-      className="stl-sdk-select"
+      className="stl-sdk-select stl-ui-not-prose"
     />
   );
 }
 
 export type SpecMetadata = [
-  'http' | 'node' | 'python' | 'go' | 'typescript' | 'terraform' | 'ruby' | 'java' | 'kotlin',
+  DocsLanguage,
   {
     repo_url?: string;
     code_url?: string;
@@ -234,15 +263,26 @@ export type SpecMetadata = [
   },
 ][];
 
+const componentOverrides = {
+  SDKRequestTitle,
+  SnippetCode,
+  SnippetContainer,
+  SnippetButtons,
+  SnippetFooter,
+  SnippetResponse,
+  ...(EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS ? { MethodDescription } : {}),
+} satisfies React.ComponentProps<typeof ComponentProvider>['components'];
+
 export function RenderLibraries({ metadata }: { metadata: SpecMetadata }) {
   return (
-    <ComponentProvider components={{}}>
+    <ComponentProvider components={componentOverrides}>
       {metadata.map(([language, data]) => (
         <SDKLanguageBlock
+          key={language}
           language={language}
           version={data.version || ''}
           install={data.install || ''}
-          links={{ repo: data.repo_url || '#', docs: `${BASE_PATH}/${language}` }}
+          links={{ repo: data.repo_url || '#', docs: `${RESOLVED_API_REFERENCE_PATH}/${language}` }}
         />
       ))}
     </ComponentProvider>
@@ -254,15 +294,8 @@ export function RenderSpecOverview({ spec, language }: { spec: SDKJSON.Spec; lan
 
   return (
     <DocsProvider spec={spec} language={language ?? 'node'}>
-      <ComponentProvider
-        components={{
-          SDKRequestTitle,
-          SnippetCode,
-          SnippetContainer,
-          SnippetRequestContainer,
-        }}
-      >
-        <NavigationProvider basePath={BASE_PATH}>
+      <ComponentProvider components={componentOverrides}>
+        <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
             <div className={style.Overview}>
               {resources
@@ -303,7 +336,10 @@ export function RenderSpec({
   const parsed = parseStainlessPath(path);
   const resource = getResourceFromSpec(path, spec);
 
-  if (!resource || !parsed) return null;
+  if (!resource || !parsed) {
+    console.warn(`Could not find resource or parsed path for '${path}'`);
+    return null;
+  }
 
   return (
     <DocsProvider
@@ -314,46 +350,30 @@ export function RenderSpec({
         properties: PROPERTY_SETTINGS,
       }}
     >
-      <ComponentProvider
-        components={{
-          SDKRequestTitle,
-          SnippetCode,
-          SnippetContainer,
-          SnippetRequestContainer,
-        }}
-      >
-        <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
+      <ComponentProvider components={componentOverrides}>
+        <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH} selectedPath={path}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
-            {kind === 'http_method' ? (
+            {
               <div className="stldocs-root stl-ui-not-prose">
                 <div className="stl-page-nav-container">
                   <SDKBreadcrumbs
                     spec={spec as SDKJSON.Spec}
                     currentPath={currentPath}
-                    basePath={BASE_PATH}
+                    basePath={RESOLVED_API_REFERENCE_PATH}
                     config={BREADCRUMB_CONFIG}
                   />
-                  {INCLUDE_AI_DROPDOWN_OPTIONS && <APIReferenceAIDropdown />}
+                  {ENABLE_CONTEXT_MENU && <AIDropdown />}
                 </div>
-                <SDKMethod
-                  method={resource.methods[parsed.method]}
-                  transformRequestSnippet={transformRequestSnippet}
-                />
-              </div>
-            ) : (
-              <div className="stldocs-root stl-ui-not-prose">
-                <div className="stl-page-nav-container">
-                  <SDKBreadcrumbs
-                    spec={spec as SDKJSON.Spec}
-                    currentPath={currentPath}
-                    basePath={BASE_PATH}
-                    config={BREADCRUMB_CONFIG}
+                {kind === 'http_method' ? (
+                  <SDKMethod
+                    method={resource.methods[parsed.method!]!}
+                    transformRequestSnippet={transformRequestSnippet}
                   />
-                  {INCLUDE_AI_DROPDOWN_OPTIONS && <APIReferenceAIDropdown />}
-                </div>
-                <SDKOverview resource={resource} />
+                ) : (
+                  <SDKOverview resource={resource} />
+                )}
               </div>
-            )}
+            }
           </MarkdownProvider>
         </NavigationProvider>
       </ComponentProvider>
@@ -367,10 +387,14 @@ export function RenderMethod({ path }: { path: string }) {
 
   const parsed = parseStainlessPath(path);
   const resource = getResourceFromSpec(path, spec);
-  if (!resource || !parsed) return null;
 
-  const meth = resource.methods[parsed.method];
-  return <SDKMethod method={meth} />;
+  if (!resource || !parsed) {
+    console.warn(`Could not find resource or parsed path for '${path}'`);
+    return null;
+  }
+
+  const method = resource.methods[parsed.method!]!;
+  return <SDKMethod method={method} />;
 }
 
 export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguage) {
@@ -390,8 +414,68 @@ export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguag
   return spec.readme[language];
 }
 
+let astroShikiHighlighter:
+  | HighlighterGeneric<BundledLanguage, BundledTheme>
+  | Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
+  | null = null;
+
+async function astroHighlight() {
+  if (astroShikiHighlighter) {
+    return astroShikiHighlighter;
+  }
+
+  astroShikiHighlighter = createHighlighter({
+    themes: [
+      'github-light',
+      'github-dark',
+      {
+        name: 'stainless-docs-json',
+        colors: {
+          'editor.background': 'var(--stl-color-background)',
+          'editor.foreground': 'var(--stl-color-foreground)',
+        },
+
+        tokenColors: [
+          {
+            scope: ['comment', 'punctuation.definition.comment'],
+            settings: { foreground: 'var(--stl-color-foreground-muted)' },
+          },
+          // numbers, booleans, null
+          {
+            scope: ['constant.numeric', 'constant.language'],
+            settings: { foreground: 'var(--stl-color-orange-foreground)' },
+          },
+          // strings
+          {
+            scope: ['string', 'string.quoted', 'string.template'],
+            settings: { foreground: 'var(--stl-color-green-foreground)' },
+          },
+          // Keys, brackets
+          {
+            scope: ['support.type', 'meta'],
+            settings: { foreground: 'var(--stl-color-foreground)' },
+          },
+          // brackets
+          {
+            scope: ['meta'],
+            settings: { foreground: 'var(--stl-color-foreground-muted)' },
+          },
+          // built-in types
+          {
+            scope: ['support.type.builtin'],
+            settings: { foreground: 'var(--stl-color-purple-foreground)' },
+          },
+        ],
+      },
+    ],
+    langs: SupportedLanguageSyntaxes,
+  });
+
+  return astroShikiHighlighter;
+}
+
 // Astro's markdown processor is a singleton
-// Need to cache it instead of instanting per request
+// Need to cache it instead of instantiating per request
 let astroMarkdownProcessor: MarkdownProcessor;
 async function astroMarkdown() {
   if (!astroMarkdownProcessor) {
@@ -407,18 +491,6 @@ async function astroMarkdown() {
   return astroMarkdownProcessor;
 }
 
-let astroShikiHighlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
-async function astroHighlight() {
-  if (!astroShikiHighlighter) {
-    astroShikiHighlighter = await createHighlighter({
-      themes: ['github-light', 'github-dark'],
-      langs: SupportedLanguageSyntaxes,
-    });
-  }
-
-  return astroShikiHighlighter;
-}
-
 export async function astroMarkdownRender(content: string) {
   const md = await astroMarkdown();
   const output = await md.render(content);

package/plugin/referencePlaceholderUtils.ts

@@ -21,27 +21,30 @@ export function makePlaceholderItems(id: number) {
 
 type StarlightConfig = Parameters<typeof starlight>[0];
 
-type SidebarConfigEntry = Exclude<StarlightConfig['sidebar'], undefined>[number];
+export type SidebarConfigEntry = Exclude<StarlightConfig['sidebar'], undefined>[number];
 
 export function getAPIReferencePlaceholderItemFromSidebarConfig(
   sidebar: SidebarConfigEntry[],
-): SidebarConfigEntry | null {
-  for (const item of sidebar) {
-    if (typeof item === 'string') {
-      continue;
-    }
-    if ('items' in item) {
-      const found = getAPIReferencePlaceholderItemFromSidebarConfig(item.items);
-      if (found) {
-        return found;
+): SidebarConfigEntry[] {
+  const items: SidebarConfigEntry[] = [];
+
+  function recursiveGetPlaceholderItems(entries: SidebarConfigEntry[]) {
+    for (const item of entries) {
+      if (typeof item === 'string') {
+        continue;
+      }
+      if ('attrs' in item && item.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER) {
+        items.push(item);
+      }
+      if ('items' in item) {
+        recursiveGetPlaceholderItems(item.items);
       }
-    }
-    if ('attrs' in item && item.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER) {
-      return item;
     }
   }
 
-  return null;
+  recursiveGetPlaceholderItems(sidebar);
+
+  return items;
 }
 
 type SidebarEntry = StarlightRouteData['sidebar'][number];
@@ -58,7 +61,7 @@ function recursiveGetPlaceholderItems(
   items: PlaceholderItemResult[],
 ): PlaceholderItemResult[] {
   for (let i = 0; i < sidebar.length; i++) {
-    const entry = sidebar[i];
+    const entry = sidebar[i]!;
     if ('attrs' in entry && entry.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER) {
       items.push({
         index: i,

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -1,54 +1,58 @@
-import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+import { defineRouteMiddleware, StarlightRouteData } from '@astrojs/starlight/route-data';
 
-import { cmsClient } from './cms/client';
-import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { getAPIReferencePlaceholderItems } from './referencePlaceholderUtils';
-import { getMethodFromSDKJSON, recursiveReplacePlaceholderItems } from './generateAPIReferenceLink';
-import { forceGenerateRoute } from './cms/sidebar-builder';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
+import path from 'path';
+import { sidebars } from 'virtual:stl-starlight-reference-sidebars';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 
+type SidebarEntry = StarlightRouteData['sidebar'][number];
+
+const removeTrailingSlash = (value: string) => (value.endsWith('/') ? value.slice(0, -1) : value);
+
+function markCurrentItems(sidebar: SidebarEntry[], currentSlug: string) {
+  // IMPORTANT: we need to clone the sidebar to avoid mutating the original sidebar
+  const mutableSidebarInstance = structuredClone(sidebar);
+  const normalizedCurrentSlug = removeTrailingSlash(currentSlug);
+
+  function recursiveMarkCurrent(entries: SidebarEntry[]) {
+    for (const entry of entries) {
+      if (entry.type === 'link') {
+        entry.isCurrent = removeTrailingSlash(entry.href) === normalizedCurrentSlug;
+      }
+      if (entry.type === 'group') {
+        recursiveMarkCurrent(entry.entries);
+      }
+    }
+  }
+  recursiveMarkCurrent(mutableSidebarInstance);
+
+  return mutableSidebarInstance;
+}
+
 export const onRequest = defineRouteMiddleware(async (context) => {
   // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
   // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
-
-  const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
+  const slug = path.posix.join(import.meta.env.BASE_URL ?? '', `/${context.locals.starlightRoute.id}`); // same as .slug but not deprecated
 
   context.locals.starlightRoute._stlStarlight = {
-    basePath: BASE_PATH,
+    basePath: RESOLVED_API_REFERENCE_PATH,
   };
 
   const apiReferencePlaceholderItems = getAPIReferencePlaceholderItems(context.locals.starlightRoute.sidebar);
 
-  const spec = await cmsClient.getSpec();
-
-  const { language, stainlessPath } = parseRoute(BASE_PATH, slug);
-
-  // This is probably temporary, but it fills in functionality needed for Mintlify imports
-  recursiveReplacePlaceholderItems(context.locals.starlightRoute.sidebar, (entry, { endpoint, label }) => {
-    const method = getMethodFromSDKJSON(spec, endpoint);
-
-    const route = forceGenerateRoute({
-      basePath: BASE_PATH,
-      stainlessPath: method.stainlessPath,
-      language,
-    });
-    entry.href = route;
-    entry.isCurrent = method.stainlessPath === stainlessPath;
-    if (!label) {
-      entry.label = method.summary ?? method.name;
-    }
-    entry.attrs['data-stldocs-method'] = method.httpMethod;
-  });
+  const { language } = parseRoute(RESOLVED_API_REFERENCE_PATH, slug);
 
   for (const item of apiReferencePlaceholderItems) {
-    const entries = await cmsClient.buildSidebar({
-      basePath: BASE_PATH,
-      currentSlug: slug,
-      sidebarId: item.sidebarId,
-    });
+    const entries = sidebars.find((sb) => sb.id === item.sidebarId && sb.language === language)?.entries;
+    if (!entries) {
+      throw new Error(`Expected sidebar entries for sidebar ID ${item.sidebarId} and language ${language}`);
+    }
 
     item.group.splice(item.index, 1, ...entries);
   }
+
+  context.locals.starlightRoute.sidebar = markCurrentItems(context.locals.starlightRoute.sidebar, slug);
 });