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

package/plugin/cms/worker.ts

@@ -1,10 +1,11 @@
 import Worker from 'web-worker';
-import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import fs from 'fs/promises';
 import pathutils from 'path';
+import type { VersionUserConfig } from '../loadPluginConfig';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -12,7 +13,81 @@ const __dirname = dirname(__filename);
 const workerPath = resolve(__dirname, '..', 'vendor', 'preview.worker.docs.js');
 
 type OpenAPIDocument = Record<string, any>;
-type ParsedConfig = Record<string, any>;
+export type ParsedConfig = {
+  docs:
+    | {
+        title?: string | undefined;
+        favicon?: string | undefined;
+        logo_icon?: string | undefined;
+        search?:
+          | {
+              algolia?:
+                | {
+                    app_id: string;
+                    index_name: string;
+                    search_key: string;
+                  }
+                | undefined;
+            }
+          | undefined;
+        description?: string | undefined;
+        languages?:
+          | ('node' | 'typescript' | 'python' | 'java' | 'kotlin' | 'go' | 'ruby' | 'terraform' | 'http')[]
+          | undefined;
+        snippets?:
+          | {
+              exclude_languages?: string[] | undefined;
+            }
+          | undefined;
+        show_security?: boolean | undefined;
+        show_readme?: boolean | undefined;
+        base_path?: string | undefined;
+        navigation?:
+          | {
+              menubar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+              sidebar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+            }
+          | undefined;
+        pages?: unknown;
+        resources?: unknown[] | undefined;
+      }
+    | undefined;
+  targets: Record<string, { skip?: boolean }>;
+  client_settings: {
+    opts: {
+      [x: string]: {
+        type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+        nullable: boolean;
+        description?: string | undefined;
+        example?: unknown;
+        default?: unknown;
+        read_env?: string | undefined;
+        auth?:
+          | {
+              security_scheme: string;
+              role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+            }
+          | undefined;
+      };
+    };
+  };
+};
 
 function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; data: any }) {
   const stainlessWorker = new Worker(workerPath, {
@@ -22,6 +97,7 @@ function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; da
 
   return new Promise<any>((resolve, reject) => {
     stainlessWorker.addEventListener('error', (e) => {
+      e.preventDefault();
       reject(e);
     });
 
@@ -85,10 +161,12 @@ export async function createSDKJSON({
   oas,
   config,
   languages,
+  version,
 }: {
   oas: OpenAPIDocument;
   config: ParsedConfig;
   languages: DocsLanguage[];
+  version: VersionUserConfig;
 }) {
   const templatePath = resolve(__dirname, '../vendor/templates');
   const readmeLoader = await Promise.all(
@@ -98,7 +176,7 @@ export async function createSDKJSON({
       try {
         const content = await fs.readFile(mdfile);
         return [language, content.toString()];
-      } catch (err) {
+      } catch {
         return [language, null];
       }
     }),
@@ -113,7 +191,7 @@ export async function createSDKJSON({
       config,
       languages,
       transform: false,
-      projectName: '',
+      projectName: version.stainlessProject,
       readmeTemplates,
     },
   });

package/plugin/components/MethodDescription.tsx

@@ -0,0 +1,54 @@
+import { MethodDescriptionProps } from '@stainless-api/docs-ui/components';
+import { useComponents } from '@stainless-api/docs-ui/contexts/use-components';
+import style from '@stainless-api/docs-ui/style';
+import { Button } from '@stainless-api/ui-primitives';
+
+function shouldCollapseDescription(description: string) {
+  const MIN_CHARS = 400;
+  const MIN_LINES = 6;
+
+  const lineCount = description.split('\n').length;
+
+  if (description.length >= MIN_CHARS) return true;
+  if (lineCount >= MIN_LINES) return true;
+
+  // Markdown structure often means longer content
+  if (/#\s/.test(description)) return true; // has headings
+  if (/```/.test(description)) return true; // has code blocks
+  if (/^\s*[-*]\s+/m.test(description)) return true; // has lists
+
+  return false;
+}
+
+export function MethodDescription({ description }: MethodDescriptionProps) {
+  const { Markdown } = useComponents();
+
+  if (description) {
+    // Attempt to determine if we should make the description collapsible initially
+    // or not. If we get this right, there will be no FOUC.
+    const collapsible = shouldCollapseDescription(description);
+
+    return (
+      <div className="stl-method-description">
+        <div
+          className={style.MethodDescription}
+          data-stldocs-property-group="method-description"
+          data-collapsed={collapsible ? 'true' : 'false'}
+        >
+          <Markdown content={description} />
+        </div>
+        <div className="stl-method-description-overflow-wrapper">
+          <Button
+            type="button"
+            data-method-description-toggle
+            size="sm"
+            variant="ghost"
+            hidden={!collapsible}
+          >
+            Show more
+          </Button>
+        </div>
+      </div>
+    );
+  }
+}

package/plugin/components/SDKSelect.astro

@@ -1,6 +1,6 @@
 ---
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
 import { cmsClient } from '../cms/client';
 import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
@@ -53,100 +53,20 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
   )
 }
 
-<style>
-  @layer starlight.core {
-    label {
-      --sl-label-icon-size: 16px;
-      --sl-caret-size: 1.25rem;
-      --sl-inline-padding: 0.5rem;
-      position: relative;
-      display: flex;
-      align-items: center;
-      gap: 0.25rem;
-      color: var(--sl-color-gray-1);
-    }
-
-    label:hover {
-      color: var(--sl-color-gray-2);
-    }
-
-    .icon {
-      position: absolute;
-      top: 50%;
-      transform: translateY(-50%);
-      pointer-events: none;
-      width: 16px;
-    }
-
-    select {
-      padding-block: 0.3rem;
-      padding-inline: calc(var(--sl-label-icon-size) + var(--sl-inline-padding) + 0.5rem)
-        calc(var(--sl-caret-size) + var(--sl-inline-padding) + 0.25rem);
-      margin-inline: calc(var(--sl-inline-padding) * -1);
-      width: calc(var(--sl-select-width) + var(--sl-inline-padding) * 2);
-      text-overflow: ellipsis;
-      color: inherit;
-      cursor: pointer;
-      appearance: none;
-      font-weight: 600;
-      text-transform: capitalize;
-    }
-
-    select:active {
-      font-weight: inherit;
-      /* font-family: sans-serif;
-      font-weight: 400; */
-    }
-
-    option {
-      background-color: var(--sl-color-bg-nav);
-      color: var(--sl-color-gray-1);
-    }
-
-    @media (min-width: 50rem) {
-      select {
-        font-size: var(--sl-text-sm);
-      }
-    }
-  }
-
-  @layer starlight.components {
-    .label-icon {
-      font-size: var(--sl-label-icon-size);
-      inset-inline-start: 0;
-    }
-
-    .caret {
-      font-size: var(--sl-caret-size);
-      inset-inline-end: 0;
-    }
-  }
-
-  .custom-select-wrapper {
-    --sl-inline-padding: 0.5rem;
-    position: relative;
-    display: inline-block;
-    /* These match the padding on the sidebar menu */
-    padding-left: var(--sl-inline-padding);
-    padding-right: var(--sl-inline-padding);
-
-    .icon.http path {
-      fill: var(--sl-color-text);
-    }
-  }
-</style>
 <script>
   import { navigate } from 'astro:transitions/client';
   import { updateSelectedLanguage } from '../languages';
-  import { initDropdown } from '@stainless-api/docs-ui/src/components/scripts/dropdown';
+  import { initDropdown } from '@stainless-api/docs/components/scripts';
   import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
   import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 
   document.addEventListener(getPageLoadEvent(), () => {
+    const sdkSelect = document.getElementById('sidebar-sdk-select');
+    if (!sdkSelect) return;
     initDropdown({
-      dropdownId: 'sidebar-sdk-select',
+      root: sdkSelect,
       onSelect: (value) => {
-        const originalLanguage = document.getElementById('sidebar-sdk-select')?.dataset.currentValue;
+        const originalLanguage = sdkSelect.dataset.currentValue;
         navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
       },
     });

package/plugin/components/SnippetCode.tsx

@@ -2,12 +2,38 @@ import type {
   SnippetCodeProps,
   SnippetContainerProps,
   SnippetRequestContainerProps,
-} from '@stainless-api/docs-ui/src/components';
-import { useHighlight, useLanguage } from '@stainless-api/docs-ui/src/contexts';
-import style from '@stainless-api/docs-ui/src/style';
+} from '@stainless-api/docs-ui/components';
+import { useHighlight, useLanguage } from '@stainless-api/docs-ui/contexts';
+import style from '@stainless-api/docs-ui/style';
 import * as cheerio from 'cheerio/slim';
-import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import {
+  EXPERIMENTAL_COLLAPSIBLE_SNIPPETS,
+  EXPERIMENTAL_PLAYGROUNDS,
+} from 'virtual:stl-starlight-virtual-module';
 import clsx from 'clsx';
+import { Button } from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+
+function PlaygroundIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={'lucide ' + style.Icon}
+      aria-hidden="true"
+    >
+      <path d="m 1,2 h 1 a 4,4 0 0 1 4,4 v 1 m 5,15 H 10 A 4,4 0 0 1 6,18 V 6 a 4,4 0 0 1 4,-4 h 1 M 1,22 H 2 A 4,4 0 0 0 6,18 V 17 M 14.029059,8.147837 A 1.2853426,1.2853426 0 0 1 15.978924,7.0437277 L 22.40178,10.8959 a 1.2853426,1.2853426 0 0 1 0,2.208219 l -6.422856,3.852172 a 1.2853426,1.2853426 0 0 1 -1.949865,-1.105395 z" />
+    </svg>
+  );
+}
+
 /*
  * This may be replaced by additional data from the sdk.
  * Without information from the sdk, we use simple heuristics per language.
@@ -53,7 +79,7 @@ function wrapFirstNSpaces($line: cheerio.Cheerio<any>, n: number) {
   const m = inner.match(new RegExp(`^( {1,${n}})`));
   if (!m) return;
 
-  const lead = m[1];
+  const lead = m[1]!;
   $firstSpan.html(`<span class="leading-ws">${lead}</span>${inner.slice(lead.length)}`);
 }
 
@@ -130,12 +156,14 @@ export function SnippetRequestContainer({ children, signature }: SnippetRequestC
     <div className="stl-snippet-request-container">
       {children}
       {signature && isCollapsible && (
-        <button
-          className={clsx(style.Button, style.ButtonSecondary, 'stl-snippet-expand-button')}
+        <Button
+          className={'stl-snippet-expand-button'}
           id="stl-snippet-expand-button"
+          size="sm"
+          variant="outline"
         >
           Show more
-        </button>
+        </Button>
       )}
     </div>
   );
@@ -181,6 +209,23 @@ export function CondensibleSnippetCode({
   );
 }
 
+export function SnippetButtons({ content }: { content: string }) {
+  void content;
+  const language = useLanguage();
+  return (
+    <>
+      <Button variant="outline" data-stldocs-snippet-copy>
+        <CopyIcon size={16} className={style.Icon} />
+      </Button>
+      {EXPERIMENTAL_PLAYGROUNDS &&
+        (language === 'python' || language === 'typescript' || language === 'http') && (
+          <Button data-stldocs-snippet-play variant="muted" border title="Play">
+            <PlaygroundIcon />
+          </Button>
+        )}
+    </>
+  );
+}
 export function SnippetCode({ content, signature, language: forcedLanguage }: SnippetCodeProps) {
   const lang = useLanguage();
   const language = forcedLanguage || lang;

package/plugin/components/search/SearchAlgolia.astro

@@ -1,23 +1,25 @@
 ---
-import { Icon } from '@astrojs/starlight/components';
 import { DocsSearch } from './SearchIsland';
-import { SEARCH } from 'virtual:stl-starlight-virtual-module';
+import { Button } from '@stainless-api/ui-primitives';
+import { SearchIcon, XIcon } from 'lucide-react';
 ---
 
 <site-search>
-  <button
-    popovertarget="stldocs-search"
+  <Button
+    popoverTarget="stldocs-search"
     data-open-modal
     aria-label={Astro.locals.t('search.label')}
     aria-keyshortcuts="Control+K"
-    class="stldocs-button stldocs-button-secondary"
+    variant="outline"
+    className="stl-algolia-search"
   >
-    <Icon name="magnifier" />
+    <SearchIcon className="icon-search" size={14} />
+    <XIcon className="icon-close" size={14} />
     <span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>
     <kbd class="sl-hidden md:sl-flex" style="display: none;">
       <kbd>{Astro.locals.t('search.ctrlKey')}</kbd><kbd>K</kbd>
     </kbd>
-  </button>
+  </Button>
 
   <DocsSearch
     client:only="react"
@@ -31,27 +33,6 @@ import { SEARCH } from 'virtual:stl-starlight-virtual-module';
   />
 </site-search>
 
-{
-  SEARCH?.enableAISearch === true && (
-    <button id="chat-button" popovertarget="stldocs-chat" data-open-modal>
-      <Icon name="comment" />
-    </button>
-  )
-}
-
-<style>
-  #chat-button {
-    background: var(--sl-color-bg-ui);
-    border: 1px solid var(--sl-color-hairline);
-    height: 2.25rem;
-    width: 2.25rem;
-
-    &:hover {
-      border: 1px solid rgb(64, 64, 64);
-    }
-  }
-</style>
-
 <script is:inline>
   function setupShortcut() {
     const openBtn = document.querySelector('button[data-open-modal]');
@@ -78,3 +59,39 @@ import { SEARCH } from 'virtual:stl-starlight-virtual-module';
     }
   });
 </script>
+
+<style is:inline>
+  .default-tabs-container .stl-algolia-search {
+    max-width: unset;
+    width: unset;
+    flex-grow: 1;
+  }
+  .stl-algolia-search {
+    padding: 0;
+  }
+  @media (min-width: 50rem) {
+    .stl-algolia-search {
+      padding: 8px 10px;
+    }
+  }
+
+  .stl-algolia-search {
+    .icon-search {
+      display: inline;
+    }
+
+    .icon-close {
+      display: none;
+    }
+  }
+
+  site-search:has(#stldocs-search[data-stldocs-modal-open='true']) .stl-algolia-search {
+    .icon-search {
+      display: none;
+    }
+
+    .icon-close {
+      display: inline;
+    }
+  }
+</style>

package/plugin/components/search/SearchIsland.tsx

@@ -1,19 +1,20 @@
 import * as React from 'react';
-import { BASE_PATH, SEARCH } from 'virtual:stl-starlight-virtual-module';
-import { parseRoute, generateRoute } from '@stainless-api/docs-ui/src/routing';
-import { SearchModal } from '@stainless-api/docs-ui/src/search/index';
-import { ChatModal } from '@stainless-api/docs-ui/src/components/chat';
+import { BASE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { parseRoute, generateRoute } from '@stainless-api/docs-ui/routing';
+import { SearchModal } from '@stainless-api/docs-search';
 import * as Markdoc from '@markdoc/markdoc';
 import { createHighlighter } from 'shiki';
 import type { BundledLanguage, BundledTheme, HighlighterGeneric } from 'shiki';
 
 import {
   DocsProvider,
+  type MarkdownContext,
   MarkdownProvider,
   NavigationProvider,
-  SearchProvider,
-} from '@stainless-api/docs-ui/src/contexts';
-import type { SearchSettings } from '@stainless-api/docs-ui/src/search/types';
+} from '@stainless-api/docs-ui/contexts';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+import { SearchProvider } from '@stainless-api/docs-search/context';
+import type { SearchSettings } from '@stainless-api/docs-search/types';
 
 let $$highlighter: HighlighterGeneric<BundledLanguage, BundledTheme> | null = null;
 async function getHighlighter() {
@@ -27,7 +28,7 @@ async function getHighlighter() {
   return $$highlighter;
 }
 
-async function createMarkdownRenderer() {
+async function createMarkdownRenderer(): Promise<MarkdownContext> {
   const highlighter = await getHighlighter();
   const markdocConfig: Markdoc.Config = {
     nodes: {
@@ -37,7 +38,10 @@ async function createMarkdownRenderer() {
         transform(node, config) {
           const attributes = node.transformAttributes(config);
           const lang = node.attributes.language === 'node' ? 'typescript' : node.attributes.language;
-          const code = highlighter.codeToTokens(node.attributes.content, { lang, theme: 'github-dark' });
+          const code = highlighter.codeToTokens(node.attributes.content, {
+            lang,
+            theme: 'github-dark',
+          });
 
           return new Markdoc.Tag(
             'pre',
@@ -66,16 +70,25 @@ async function createMarkdownRenderer() {
     },
   };
 
-  return (content: string) => {
-    const ast = Markdoc.parse(content);
-    const transformed = Markdoc.transform(ast, markdocConfig);
-    return Markdoc.renderers.html(transformed);
+  return {
+    render: (content: string) => {
+      const ast = Markdoc.parse(content);
+      const transformed = Markdoc.transform(ast, markdocConfig);
+      return Markdoc.renderers.html(transformed);
+    },
+    highlight: (content: string, language: string) => {
+      return highlighter.codeToHtml(content, {
+        lang: language ?? 'javascript',
+        themes: HIGHLIGHT_THEMES || {},
+      });
+    },
   };
 }
 
 export function DocsSearch({ settings, currentPath }: { settings: SearchSettings; currentPath: string }) {
-  const renderMarkdown = React.use(createMarkdownRenderer());
+  const markdownRenderer = React.use(createMarkdownRenderer());
   const { stainlessPath, language } = parseRoute(BASE_PATH, currentPath);
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
   const pageFind = import.meta.env.DEV ? undefined : '/pagefind/pagefind.js';
 
   function handleSelect(path: string) {
@@ -85,16 +98,17 @@ export function DocsSearch({ settings, currentPath }: { settings: SearchSettings
 
   return (
     <DocsProvider spec={null} language={language}>
-      <NavigationProvider basePath="/" selectedPath={stainlessPath}>
-        <MarkdownProvider render={renderMarkdown}>
-          <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
-            <div className="stldocs-root">
-              <SearchModal id="stldocs-search" />
-              {SEARCH?.enableAISearch === true && <ChatModal id="stldocs-chat" />}
-            </div>
-          </SearchProvider>
-        </MarkdownProvider>
-      </NavigationProvider>
+      <ComponentProvider>
+        <NavigationProvider basePath="/" selectedPath={stainlessPath}>
+          <MarkdownProvider {...markdownRenderer}>
+            <SearchProvider onSelect={handleSelect} pageFind={pageFind} settings={settings}>
+              <div className="stldocs-root">
+                <SearchModal id="stldocs-search" />
+              </div>
+            </SearchProvider>
+          </MarkdownProvider>
+        </NavigationProvider>
+      </ComponentProvider>
     </DocsProvider>
   );
 }

package/plugin/create-playground.shim.tsx

@@ -0,0 +1,3 @@
+export function createPlayground(): () => Promise<void> {
+  return () => Promise.resolve();
+}

package/plugin/generateAPIReferenceLink.ts

@@ -1,8 +1,8 @@
 // This is probably temporary, but it fills in functionality needed for Mintlify imports
 
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import { walkTree } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { walkTree } from '@stainless-api/docs-ui/routing';
 
 const INTERNAL_REFERENCE_ENTRY_MARKER = 'STL_STARLIGHT_API_REFERENCE_METHOD_LINK_PLACEHOLDER';