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

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,23 +26,22 @@ 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,
   EXCLUDE_LANGUAGES,
@@ -48,37 +49,22 @@ import {
   HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
+  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,
+  SnippetRequestContainer,
+  SnippetButtons,
+} from '../components/SnippetCode';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
-import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
-
-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 (
@@ -119,7 +105,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,
@@ -151,19 +136,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,
@@ -177,30 +201,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>
   );
 }
@@ -216,13 +246,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;
@@ -232,9 +262,18 @@ export type SpecMetadata = [
   },
 ][];
 
+const componentOverrides = {
+  SDKRequestTitle,
+  SnippetCode,
+  SnippetContainer,
+  SnippetRequestContainer,
+  SnippetButtons,
+  ...(EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS ? { MethodDescription } : {}),
+};
+
 export function RenderLibraries({ metadata }: { metadata: SpecMetadata }) {
   return (
-    <ComponentProvider components={{}}>
+    <ComponentProvider components={componentOverrides}>
       {metadata.map(([language, data]) => (
         <SDKLanguageBlock
           language={language}
@@ -252,14 +291,7 @@ export function RenderSpecOverview({ spec, language }: { spec: SDKJSON.Spec; lan
 
   return (
     <DocsProvider spec={spec} language={language ?? 'node'}>
-      <ComponentProvider
-        components={{
-          SDKRequestTitle,
-          SnippetCode,
-          SnippetContainer,
-          SnippetRequestContainer,
-        }}
-      >
+      <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={BASE_PATH}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
             <div className={style.Overview}>
@@ -301,7 +333,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
@@ -312,40 +347,30 @@ export function RenderSpec({
         properties: PROPERTY_SETTINGS,
       }}
     >
-      <ComponentProvider
-        components={{
-          SDKRequestTitle,
-          SnippetCode,
-          SnippetContainer,
-          SnippetRequestContainer,
-        }}
-      >
+      <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
-            {kind === 'http_method' ? (
+            {
               <div className="stldocs-root stl-ui-not-prose">
-                <SDKBreadcrumbs
-                  spec={spec as SDKJSON.Spec}
-                  currentPath={currentPath}
-                  basePath={BASE_PATH}
-                  config={BREADCRUMB_CONFIG}
-                />
-                <SDKMethod
-                  method={resource.methods[parsed.method]}
-                  transformRequestSnippet={transformRequestSnippet}
-                />
-              </div>
-            ) : (
-              <div className="stldocs-root stl-ui-not-prose">
-                <SDKBreadcrumbs
-                  spec={spec as SDKJSON.Spec}
-                  currentPath={currentPath}
-                  basePath={BASE_PATH}
-                  config={BREADCRUMB_CONFIG}
-                />
-                <SDKOverview resource={resource} />
+                <div className="stl-page-nav-container">
+                  <SDKBreadcrumbs
+                    spec={spec as SDKJSON.Spec}
+                    currentPath={currentPath}
+                    basePath={BASE_PATH}
+                    config={BREADCRUMB_CONFIG}
+                  />
+                  {ENABLE_CONTEXT_MENU && <AIDropdown />}
+                </div>
+                {kind === 'http_method' ? (
+                  <SDKMethod
+                    method={resource.methods[parsed.method!]!}
+                    transformRequestSnippet={transformRequestSnippet}
+                  />
+                ) : (
+                  <SDKOverview resource={resource} />
+                )}
               </div>
-            )}
+            }
           </MarkdownProvider>
         </NavigationProvider>
       </ComponentProvider>
@@ -359,10 +384,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) {
@@ -375,13 +404,75 @@ export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguag
       const response = await fetch(`${rawUrl}/refs/heads/main/README.md`);
       if (response && response.ok) return response.text();
     }
-  } catch (err) {}
+  } catch {
+    // ignore
+  }
 
   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) {
@@ -397,18 +488,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

@@ -58,7 +58,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

@@ -5,7 +5,7 @@ import { BASE_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';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 
@@ -15,6 +15,10 @@ export const onRequest = defineRouteMiddleware(async (context) => {
 
   const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
 
+  context.locals.starlightRoute._stlStarlight = {
+    basePath: BASE_PATH,
+  };
+
   const apiReferencePlaceholderItems = getAPIReferencePlaceholderItems(context.locals.starlightRoute.sidebar);
 
   const spec = await cmsClient.getSpec();