@stainless-api/docs 0.1.0-beta.8 → 0.1.0-beta.80

package/plugin/components/SnippetCode.tsx

@@ -1,13 +1,42 @@
-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';
+import {
+  type SnippetCodeProps,
+  type SnippetContainerProps,
+  SnippetResponse as DocsUiSnippetResponse,
+} 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,
+  EXPERIMENTAL_REQUEST_BUILDER,
+} from 'virtual:stl-starlight-virtual-module';
 import clsx from 'clsx';
+import { Button } from '@stainless-api/ui-primitives';
+import { CopyIcon, PlayIcon } from 'lucide-react';
+import React from 'react';
+import { RequestBuilder } from './RequestBuilder';
+
+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 +82,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)}`);
 }
 
@@ -123,61 +152,36 @@ function useIsCollapsible({ signature }: { signature?: string }): boolean {
   return Boolean(EXPERIMENTAL_COLLAPSIBLE_SNIPPETS && signature && language);
 }
 
-export function SnippetRequestContainer({ children, signature }: SnippetRequestContainerProps) {
+export function SnippetContainer({ children, signature, method }: SnippetContainerProps) {
   const isCollapsible = useIsCollapsible({ signature });
-
-  return (
-    <div className="stl-snippet-request-container">
-      {children}
-      {signature && isCollapsible && (
-        <button
-          className={clsx(style.Button, style.ButtonSecondary, 'stl-snippet-expand-button')}
-          id="stl-snippet-expand-button"
-        >
-          Show more
-        </button>
-      )}
-    </div>
+  const className = clsx(
+    style.Snippet,
+    isCollapsible ? 'stl-snippet-collapsible' : 'stl-snippet-non-collapsible',
   );
-}
-
-export function SnippetContainer({ children, signature }: SnippetContainerProps) {
-  const isCollapsible = useIsCollapsible({ signature });
-
-  return (
-    <div
-      className={clsx(
-        style.Snippet,
-        isCollapsible ? 'stl-snippet-collapsible' : 'stl-snippet-non-collapsible',
-      )}
-    >
+  return EXPERIMENTAL_REQUEST_BUILDER ? (
+    <RequestBuilder className={className} method={method}>
       {children}
-    </div>
+    </RequestBuilder>
+  ) : (
+    <div className={className}>{children}</div>
   );
 }
 
-export function CondensibleSnippetCode({
-  content,
-  language,
-  signature,
-  highlighted,
-}: SnippetCodeProps & { signature: string; highlighted: string; language: string }) {
-  const ranges = getCollapsedRanges(content, language, signature);
-  const html = condensedShikiHtmlFull(highlighted, language, ranges);
-  const offset = getCounterOffset(ranges);
-
+export function SnippetButtons({ content }: { content: string }) {
+  void content;
+  const language = useLanguage();
   return (
-    <div
-      className={clsx(style.SnippetCode, 'stl-snippet-code-is-collapsed')}
-      data-snippet-expanded-offset={offset}
-    >
-      <pre className={style.SnippetCodeContent} data-stldocs-copy-content>
-        <code
-          className={language === 'json' ? 'snippet-json' : 'snippet'}
-          dangerouslySetInnerHTML={{ __html: html }}
-        />
-      </pre>
-    </div>
+    <>
+      <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>
+        )}
+    </>
   );
 }
 
@@ -197,16 +201,52 @@ export function SnippetCode({ content, signature, language: forcedLanguage }: Sn
   }
 
   return (
-    <div
-      className={clsx(style.SnippetCode, isCollapsible && 'stl-snippet-code-is-collapsed')}
-      data-snippet-expanded-offset={offset}
-    >
-      <pre className={style.SnippetCodeContent} data-stldocs-copy-content>
-        <code
-          className={(language as string) === 'json' ? 'snippet-json' : 'snippet'}
-          dangerouslySetInnerHTML={{ __html: highlighted }}
-        />
-      </pre>
+    <>
+      <div
+        className={clsx(style.SnippetCode, isCollapsible && 'stl-snippet-code-is-collapsed')}
+        data-snippet-expanded-offset={offset}
+        data-stldocs-copy-content
+        dangerouslySetInnerHTML={{ __html: highlighted }}
+      />
+      {signature && isCollapsible && (
+        <Button
+          className={'stl-snippet-expand-button'}
+          id="stl-snippet-expand-button"
+          size="sm"
+          variant="outline"
+        >
+          Show more
+        </Button>
+      )}
+      {EXPERIMENTAL_REQUEST_BUILDER && (
+        <div className="request-builder-container" style={{ display: 'contents' }}></div>
+      )}
+    </>
+  );
+}
+
+export function SnippetFooter() {
+  if (!EXPERIMENTAL_REQUEST_BUILDER) return null;
+  return (
+    <div className={clsx(style.SnippetFooter, 'try-it-footer')}>
+      {EXPERIMENTAL_REQUEST_BUILDER && (
+        <div className="request-builder-footer" style={{ display: 'contents' }}></div>
+      )}
+      <Button variant="accent" className="try-it-button">
+        <Button.Label>Try it</Button.Label>
+        <Button.Icon icon={PlayIcon} />
+      </Button>
     </div>
   );
 }
+
+export function SnippetResponse({ ...props }: React.ComponentProps<typeof DocsUiSnippetResponse>) {
+  return (
+    <>
+      <DocsUiSnippetResponse {...props} />
+      {EXPERIMENTAL_REQUEST_BUILDER && (
+        <div className="request-builder-response" style={{ display: 'contents' }} />
+      )}
+    </>
+  );
+}

package/plugin/components/StainlessIslands.tsx

@@ -0,0 +1,126 @@
+/**
+ * Technical overview:
+ * - `StainlessIslands.ts` is an Astro Client Island wherein we register a HTML custom element called `stl-island`
+ *     - When a `<stl-island component="MyComponent">` is added to the DOM, we:
+ *         1. receive a callback from the browser
+ *         2. dynamic-import `MyComponent`
+ *         3. create an instance of `MyComponent`, to which we pass the **`stl-island` DOM node** as a prop named `parent`
+ *         4. register the (`stlIslandDomNode` → `ReactNode`) pair in a global map named `roots`
+ *     - The actual Astro client island is a simple React component that renders all of the ReactNodes from the global `roots` map
+ *         - it uses a `useSyncExternalStore` to be notified of changes to the global `roots` map by registering a callback
+ *     - Each “stainless island” (instantiated by the custom element handler and rendered by the Astro client island) is responsible for using the `parent` prop it receives to identify one or more **portal targets** into which it can render its contents.
+ *         - the react parent of all Stainless Islands is the global `<StainlessIslands client:load />` singleton, but the _DOM parent_ is the various portal targets of all of the stainless islands
+ */
+
+import { useSyncExternalStore, ReactNode } from 'react';
+
+type StlIslandComponent = ({ parent }: { parent: HTMLElement }) => ReactNode;
+
+/**
+ * Register new Stainless Islands in this map.
+ * The component should be the default export and should be able to be dynamic-imported.
+ * The component should accept a single prop: `parent: HTMLElement`, which is the DOM node of the `<stl-island>` element.
+ * The component can create portals to render into the DOM subtree of the `parent`.
+ */
+const componentsMap: Record<string, () => Promise<{ default: StlIslandComponent }>> = {
+  SnippetStainlessIsland: () => import('./RequestBuilder/SnippetStainlessIsland'),
+};
+
+interface State {
+  roots: Map<HTMLElement, ReactNode>;
+  onRootsChange?: (() => void) | undefined;
+}
+
+// keep state in import.meta.hot.data so that our record of our react roots is not lost across HMR
+const state: State = import.meta.hot?.data?.state ?? {
+  roots: new Map(),
+};
+
+if (import.meta.hot?.data) {
+  import.meta.hot.data.state = state;
+}
+
+let key = 0;
+
+/**
+ * Custom element mounts and unmounts components and gives them a reference to the parent
+ * so they can render in portals.
+ */
+class StlIsland extends (globalThis?.HTMLElement ?? Object) {
+  connectedCallback(this: StlIsland) {
+    const componentName = this.getAttribute('component');
+    if (!componentName) {
+      console.error('[stl-island] missing required attribute "component"');
+      return;
+    }
+
+    if (!componentsMap[componentName]) {
+      console.error(`[stl-island] unknown component "${componentName}"`);
+      return;
+    }
+
+    componentsMap[componentName]().then(
+      ({ default: Component }) => {
+        state.roots = new Map(state.roots).set(this, <Component parent={this} key={key++} />);
+        state.onRootsChange?.();
+      },
+      (e) => {
+        console.error(`[stl-island] failed to load component "${componentName}":`, e);
+      },
+    );
+  }
+  connectedMoveCallback() {
+    // empty so we don't get disconnected/reconnected if the dom element gets moved
+  }
+  disconnectedCallback() {
+    state.roots = new Map(state.roots);
+    state.roots.delete(this);
+    state.onRootsChange?.();
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('stl-island')) {
+  customElements.define('stl-island', StlIsland);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'stl-island': StlIsland;
+  }
+}
+declare module 'react' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      // client-loaded
+      'stl-island': React.DetailedHTMLProps<React.HTMLAttributes<StlIsland>, StlIsland> & {
+        component: keyof typeof componentsMap;
+      };
+    }
+  }
+}
+
+/** Renders all StainlessIslands that have been registered in the global `state.roots` map */
+function StainlessIslandsInner() {
+  const roots = useSyncExternalStore<Map<HTMLElement, ReactNode> | null>(
+    (onChange) => {
+      state.onRootsChange = onChange;
+      return () => {
+        state.onRootsChange = undefined;
+      };
+    },
+    () => {
+      return state.roots;
+    },
+    () => null,
+  );
+  if (!roots) return null;
+  return [...roots.values()];
+}
+
+export function StainlessIslands() {
+  // Astro tries to call this function outside of react to detect if it's
+  // an Astro JSX or React JSX component, which causes warnings if we use hooks,
+  // so we use a wrapper component to avoid the hook calls.
+  return <StainlessIslandsInner />;
+}

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,35 +70,49 @@ 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);
-  const pageFind = import.meta.env.DEV ? undefined : '/pagefind/pagefind.js';
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const pageFind = import.meta.env.DEV
+    ? undefined
+    : `${import.meta.env.BASE_URL}/pagefind/pagefind.js`.replace(/\/+/g, '/');
 
-  function handleSelect(path: string) {
-    const url = path.startsWith('/') ? path : generateRoute(BASE_PATH, language, path);
+  function handleSelect(selectedPath: string) {
+    const url = selectedPath.startsWith('/')
+      ? selectedPath
+      : generateRoute(BASE_PATH, language, selectedPath);
     if (url) window.location.href = url;
   }
 
   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/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';