@stainless-api/docs 0.1.0-beta.53 → 0.1.0-beta.56

package/plugin/index.ts

@@ -4,7 +4,7 @@ import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
 import type { BundledTheme } from 'shiki';
 import { config } from 'dotenv';
 import getPort from 'get-port';
-import { startDevServer } from './cms/server';
+import { startDevServer, type SpecResp } from './cms/server';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import {
   getAPIReferencePlaceholderItemFromSidebarConfig,
@@ -27,6 +27,9 @@ import path from 'path';
 import fs from 'fs';
 import { getSharedLogger } from '../shared/getSharedLogger';
 import { resolveSrcFile } from '../resolveSrcFile';
+import { mkdir } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import prebundleWorkers from 'vite-plugin-prebundle-workers';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -119,6 +122,8 @@ async function stlStarlightAstroIntegration(
   const virtualId = `virtual:stl-starlight-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolvedId = `\0${virtualId}`;
+  let playgroundsBase: string | undefined;
+  let buildPlaygrounds;
 
   const CMS_PORT = await getPort();
 
@@ -139,6 +144,38 @@ async function stlStarlightAstroIntegration(
     },
   });
 
+  let building: Promise<void> | undefined;
+  let reportError: ((message: string) => void) | null = null;
+  let collectedErrors: string[] | null = null;
+
+  function startPlaygroundsBuild(playgroundsCachePath: string) {
+    if (!pluginConfig.experimentalPlaygrounds) return;
+    if (building) return building;
+    return (building = (async () => {
+      const { data: spec, auth } = (await (
+        await fetch(`http://localhost:${CMS_PORT}/retrieve_spec`, {
+          method: 'POST',
+          body: JSON.stringify({}),
+        })
+      ).json()) as SpecResp;
+      if (!spec || !auth) throw new Error('expected spec');
+
+      const langs = (spec.docs?.languages ?? ['http'])
+        .filter((lang) => lang !== 'terraform')
+        .filter((lang) => !pluginConfig.excludeLanguages?.includes(lang));
+
+      await buildPlaygrounds!({
+        spec,
+        langs,
+        auth,
+        playPath: playgroundsCachePath,
+        reportError(message: string) {
+          (reportError ?? console.error)(message);
+        },
+      });
+    })());
+  }
+
   return {
     name: 'stl-starlight-astro',
     hooks: {
@@ -152,6 +189,12 @@ async function stlStarlightAstroIntegration(
         const logger = getSharedLogger({ fallback: localLogger });
         const projectDir = astroConfig.root.pathname;
 
+        reportError = (message: string) => logger.error(message);
+
+        if (pluginConfig.experimentalPlaygrounds) {
+          playgroundsBase = pluginConfig.experimentalPlaygrounds.playgroundsBase;
+        }
+
         const middlewareFile = path.join(projectDir, 'middleware.stainless.ts');
 
         let vmMiddlewareExport = 'export const MIDDLEWARE = {};';
@@ -184,7 +227,15 @@ async function stlStarlightAstroIntegration(
             plugins: [
               {
                 name: 'stl-starlight-vite',
-                configureServer(server) {
+                buildStart() {
+                  building = undefined;
+                },
+                async configureServer(server) {
+                  if (playgroundsBase) {
+                    buildPlaygrounds = (await server.ssrLoadModule(playgroundsBase + '/src/build.ts'))
+                      .buildPlaygrounds;
+                  }
+
                   for (const filePath of Object.values(devPaths)) {
                     if (!filePath) {
                       continue;
@@ -207,6 +258,30 @@ async function stlStarlightAstroIntegration(
                   if (id === virtualId) {
                     return resolvedId;
                   }
+                  if (id === 'virtual:stl-playground/unstable-update-language') {
+                    return resolveSrcFile('plugin/languages.ts');
+                  }
+                  if (id === 'virtual:stl-playground/create') {
+                    return fileURLToPath(
+                      new URL(
+                        pluginConfig.experimentalPlaygrounds
+                          ? path.join(playgroundsBase!, '/src/create.tsx')
+                          : './create-playground.shim.tsx',
+                        import.meta.url,
+                      ),
+                    );
+                  }
+                  if (id.startsWith('virtual:stl-playground/')) {
+                    const result = path.join(
+                      this.environment.getTopLevelConfig().cacheDir,
+                      'stl-playground',
+                      id.slice('virtual:stl-playground/'.length),
+                    );
+                    const config = this.environment.getTopLevelConfig();
+                    return startPlaygroundsBuild(path.join(config.cacheDir, 'stl-playground'))?.then(
+                      () => result,
+                    );
+                  }
                 },
                 load(id) {
                   if (id === resolvedId) {
@@ -214,7 +289,7 @@ async function stlStarlightAstroIntegration(
                       buildVirtualModuleString({
                         BASE_PATH: pluginConfig.basePath,
                         CMS_PORT,
-                        EXCLUDE_LANGUAGES: pluginConfig.excludeLanguages,
+                        EXCLUDE_LANGUAGES: ['php', ...pluginConfig.excludeLanguages],
                         DEFAULT_LANGUAGE: pluginConfig.defaultLanguage,
                         BREADCRUMB_CONFIG: pluginConfig.breadcrumbs,
                         EXPAND_RESOURCES: pluginConfig.expandResources,
@@ -225,12 +300,28 @@ async function stlStarlightAstroIntegration(
                           pluginConfig.experimentalCollapsibleMethodDescriptions,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
+                        EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
                   }
                 },
               },
+              prebundleWorkers({
+                include: [
+                  '**/typescript/runner*',
+                  '**/typescript/worker*',
+                  '**/pyright.worker*',
+                  '**/python/pyodide*',
+                ],
+                configureEsBuild(_, opts) {
+                  opts.external ??= [];
+                  opts.external.push('url');
+                  opts.loader ??= {};
+                  opts.loader['.wasm'] = 'dataurl';
+                  return opts;
+                },
+              }),
             ],
           },
         });
@@ -238,6 +329,24 @@ async function stlStarlightAstroIntegration(
       'astro:server:done': async () => {
         await cmsServer.destroy();
       },
+      'astro:build:start'({ logger }) {
+        collectedErrors = [];
+        reportError = (message: string) => {
+          logger.error(message);
+          collectedErrors!.push(message);
+        };
+      },
+      'astro:build:done': async ({ dir, logger }) => {
+        const dist = fileURLToPath(dir);
+        const stainlessDir = path.join(dist, '_stainless');
+        await mkdir(stainlessDir, { recursive: true });
+        if (collectedErrors) {
+          for (const error of collectedErrors) {
+            logger.error(error);
+          }
+          collectedErrors = null;
+        }
+      },
     },
   };
 }

package/plugin/languages.ts

@@ -7,6 +7,7 @@ import PythonIcon from './assets/languages/python.svg';
 import JavaIcon from './assets/languages/java.svg';
 import GoIcon from './assets/languages/go.svg';
 import CurlIcon from './assets/languages/curl.svg';
+import CSharpIcon from './assets/languages/csharp.svg';
 
 export const Languages: Record<
   DocsLanguage,
@@ -29,6 +30,8 @@ export const Languages: Record<
   http: { name: 'HTTP', icon: CurlIcon, alt: 'HTTP logo' },
   terraform: { name: 'Terraform', icon: TerraformIcon, alt: 'Terraform logo' },
   ruby: { name: 'Ruby', icon: RubyIcon, alt: 'Ruby logo' },
+  csharp: { name: 'C#', icon: CSharpIcon, alt: 'C# logo' },
+  php: { name: 'PHP', icon: CSharpIcon, alt: 'PHP logo' }, // TODO update PHP icon
 };
 
 export function generatePrefix(basePath: string, language: string) {

package/plugin/loadPluginConfig.ts

@@ -129,7 +129,14 @@ export type StainlessStarlightUserConfig = {
    *
    * @default true
    */
+
   contextMenu?: boolean;
+
+  /**
+   * When set to `import playgrounds from '@stainless-api/playgrounds'`, code snippets will have a "Play" button,
+   * allowing users to edit and run code snippets in their browser.
+   */
+  experimentalPlaygrounds?: { playgroundsBase: string };
 };
 
 export type ExternalSpecServerUserConfig = Omit<StainlessStarlightUserConfig, 'stainlessProject'> & {
@@ -259,10 +266,12 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
     propertySettings: {
       types: partial.propertySettings?.types ?? 'rich',
       collapseDescription: partial.propertySettings?.collapseDescription ?? true,
+      showTitle: partial.propertySettings?.showTitle ?? false,
       expandDepth: partial.propertySettings?.expandDepth ?? 0,
       includeModelProperties: partial.propertySettings?.includeModelProperties ?? true,
     },
     contextMenu: partial.contextMenu ?? true,
+    experimentalPlaygrounds: partial.experimentalPlaygrounds ?? undefined,
   };
 
   function getSpecRetrieverConfig(): SpecRetrieverConfig {

package/plugin/react/Routing.tsx

@@ -55,7 +55,12 @@ import {
 } from 'virtual:stl-starlight-virtual-module';
 import style from '@stainless-api/docs-ui/style';
 import { BundledTheme, createHighlighter, HighlighterGeneric, type BundledLanguage } from 'shiki';
-import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
+import {
+  SnippetCode,
+  SnippetContainer,
+  SnippetRequestContainer,
+  SnippetButtons,
+} from '../components/SnippetCode';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
 import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
 import { AIDropdown } from '../../stl-docs/components/AIDropdown';
@@ -266,13 +271,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;
@@ -282,9 +287,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}
@@ -302,14 +316,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}>
@@ -365,15 +372,7 @@ export function RenderSpec({
         properties: PROPERTY_SETTINGS,
       }}
     >
-      <ComponentProvider
-        components={{
-          SDKRequestTitle,
-          SnippetCode,
-          SnippetContainer,
-          SnippetRequestContainer,
-          ...(EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS ? { MethodDescription } : {}),
-        }}
-      >
+      <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
             {
@@ -498,7 +497,7 @@ async function astroHighlight() {
 }
 
 // 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) {