@stainless-api/docs 0.1.0-beta.117 → 0.1.0-beta.119

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.119
+
+### Patch Changes
+
+- 403c097: Export additional components
+- Updated dependencies [848cff4]
+- Updated dependencies [ea2b90c]
+  - @stainless-api/ui-primitives@0.1.0-beta.50
+  - @stainless-api/docs-ui@0.1.0-beta.86
+  - @stainless-api/docs-search@0.1.0-beta.39
+
+## 0.1.0-beta.118
+
+### Minor Changes
+
+- 9599de4: Updates preview worker to improve response snippets
+
+### Patch Changes
+
+- 7901fd4: fix astro scoping for language-block style?
+- Updated dependencies [93a3767]
+  - @stainless-api/docs-ui@0.1.0-beta.85
+  - @stainless-api/docs-search@0.1.0-beta.38
+
 ## 0.1.0-beta.117
 
 ### Patch Changes

package/eslint-suppressions.json

@@ -4,14 +4,39 @@
       "count": 1
     }
   },
+  "plugin/components/StainlessIslands.tsx": {
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 1
+    },
+    "@typescript-eslint/no-unsafe-member-access": {
+      "count": 2
+    }
+  },
+  "plugin/generateAPIReferenceLink.ts": {
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 2
+    }
+  },
   "plugin/globalJs/copy.ts": {
     "@typescript-eslint/no-explicit-any": {
+      "count": 4
+    },
+    "@typescript-eslint/no-floating-promises": {
+      "count": 1
+    },
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 2
+    },
+    "@typescript-eslint/no-unsafe-member-access": {
       "count": 3
     }
   },
   "plugin/index.ts": {
     "@typescript-eslint/no-explicit-any": {
       "count": 1
+    },
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 1
     }
   },
   "plugin/languages.ts": {
@@ -19,9 +44,52 @@
       "count": 1
     }
   },
+  "plugin/referencePlaceholderUtils.ts": {
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 1
+    }
+  },
+  "plugin/specs/generateSpec.ts": {
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 2
+    }
+  },
   "plugin/specs/worker.ts": {
     "@typescript-eslint/no-explicit-any": {
       "count": 3
+    },
+    "@typescript-eslint/no-unsafe-argument": {
+      "count": 1
+    },
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 7
+    },
+    "@typescript-eslint/no-unsafe-member-access": {
+      "count": 4
+    },
+    "@typescript-eslint/no-unsafe-return": {
+      "count": 1
+    },
+    "@typescript-eslint/prefer-promise-reject-errors": {
+      "count": 4
+    }
+  },
+  "stl-docs/components/sidebars/convertAstroSidebarToStl.tsx": {
+    "@typescript-eslint/no-unsafe-argument": {
+      "count": 1
+    },
+    "@typescript-eslint/no-unsafe-assignment": {
+      "count": 1
+    }
+  },
+  "stl-docs/proseDocSync.ts": {
+    "@typescript-eslint/restrict-template-expressions": {
+      "count": 4
+    }
+  },
+  "stl-docs/proseSearchIndexing.ts": {
+    "@typescript-eslint/restrict-template-expressions": {
+      "count": 1
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.117",
+  "version": "0.1.0-beta.119",
   "publishConfig": {
     "access": "public"
   },
@@ -14,13 +14,18 @@
     "./plugin/languages": "./plugin/languages.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
-    "./components": "./stl-docs/components/index.ts",
-    "./components/scripts": "./stl-docs/components/scripts.ts",
     "./docs-config": "./stl-docs/loadStlDocsConfig.ts",
     "./specs/fetchSpecSSR": "./plugin/specs/fetchSpecSSR.ts",
     "./generate-docs-routes": "./plugin/helpers/generateDocsRoutes.ts",
+    "./components": "./stl-docs/components/index.ts",
+    "./components/scripts": "./stl-docs/components/scripts.ts",
     "./components/Head": "./stl-docs/components/Head.astro",
-    "./components/ContentBreadcrumbs": "./stl-docs/components/ContentBreadcrumbs.tsx"
+    "./components/PageFrame": "./stl-docs/components/PageFrame.astro",
+    "./components/PageTitle": "./stl-docs/components/PageTitle.astro",
+    "./components/ContentBreadcrumbs": "./stl-docs/components/ContentBreadcrumbs.tsx",
+    "./components/AIDropdown": "./stl-docs/components/AIDropdown.tsx",
+    "./components/Footer": "./stl-docs/components/Footer.astro",
+    "./components/Pagination": "./stl-docs/components/pagination/Pagination.astro"
   },
   "keywords": [],
   "author": "",
@@ -36,15 +41,15 @@
     "vite": ">=7.3.1"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.0.0",
-    "@astrojs/react": "^5.0.0",
-    "@stainless-api/sdk": "0.1.0-alpha.19",
-    "astro-expressive-code": "^0.41.6",
+    "@astrojs/markdown-remark": "^7.0.1",
+    "@astrojs/react": "^5.0.1",
+    "@stainless-api/sdk": "0.5.0",
+    "astro-expressive-code": "^0.41.7",
     "cheerio": "^1.2.0",
     "clsx": "^2.1.1",
     "dotenv": "17.3.1",
     "lucide-react": "^0.574.0",
-    "marked": "^17.0.3",
+    "marked": "^17.0.4",
     "node-html-parser": "^7.0.2",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
@@ -56,14 +61,14 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.37",
-    "@stainless-api/docs-ui": "0.1.0-beta.84",
-    "@stainless-api/ui-primitives": "0.1.0-beta.49"
+    "@stainless-api/docs-search": "0.1.0-beta.39",
+    "@stainless-api/docs-ui": "0.1.0-beta.86",
+    "@stainless-api/ui-primitives": "0.1.0-beta.50"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.9.7",
-    "@markdoc/markdoc": "^0.5.4",
-    "@types/node": "24.10.13",
+    "@astrojs/check": "^0.9.8",
+    "@markdoc/markdoc": "^0.5.6",
+    "@types/node": "24.12.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.4",

package/plugin/components/SnippetCode.tsx

@@ -140,7 +140,7 @@ function condensedShikiHtmlFull(docHtml: string, language: string, ranges: [numb
       out.push('<span class="line ellipsis">…\n</span>');
       didPushEllipsis = true;
     }
-    out.push($.html(lineEl)!);
+    out.push($.html(lineEl));
   });
 
   $code.html(out.join(''));

package/plugin/components/search/SearchIsland.tsx

@@ -37,8 +37,12 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         ...Markdoc.nodes.fence,
         transform(node, config) {
           const attributes = node.transformAttributes(config);
+          if (typeof node.attributes.language !== 'string' || typeof node.attributes.content !== 'string') {
+            throw new Error('Expected language and content to be strings');
+          }
           const lang = node.attributes.language === 'node' ? 'typescript' : node.attributes.language;
           const code = highlighter.codeToTokens(node.attributes.content, {
+            // @ts-expect-error - TODO: narrowing
             lang,
             theme: 'github-dark',
           });
@@ -63,6 +67,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         transform(node, config) {
           const children = node.transformChildren(config);
           const attrs = node.transformAttributes(config);
+          if (typeof attrs['href'] !== 'string') throw new Error('Expected href to be a string');
           const href = attrs['href'].replace('docs://BASE_PATH', RESOLVED_API_REFERENCE_PATH);
           return new Markdoc.Tag(this.render, { ...attrs, href }, children);
         },

package/plugin/globalJs/ai-dropdown-options.ts

@@ -142,7 +142,9 @@ const aiDropdownOptions: DropdownOption[][] = [
               .then((response) => response.text())
               .then((text) => new Blob([text], { type: 'text/plain' })),
           });
-          navigator.clipboard.write([text]);
+          navigator.clipboard.write([text]).catch(() => {
+            console.error('Failed to copy to clipboard using ClipboardItem');
+          });
         } else {
           // NOTE: Firefox has support for ClipboardItem and navigator.clipboard.write,
           //   but those are behind `dom.events.asyncClipboard.clipboardItem` preference.
@@ -150,7 +152,10 @@ const aiDropdownOptions: DropdownOption[][] = [
           //   Clipboard API being used async in a Promise.
           fetch(markdownUrl)
             .then((response) => response.text())
-            .then((text) => navigator.clipboard.writeText(text));
+            .then((text) => navigator.clipboard.writeText(text))
+            .catch(() => {
+              console.error('Failed to copy to clipboard');
+            });
         }
       },
       icon: 'copy',

package/plugin/globalJs/code-snippets.ts

@@ -13,7 +13,7 @@ document.addEventListener(getPageLoadEvent(), () => {
       const panelId = (tab as HTMLButtonElement).dataset.snippetResponseTabId;
 
       if (!panelId) {
-        console.error(`No panel found for tab: ${tab}`);
+        console.error(`No panel found for tab: ${tab.outerHTML}`);
         return;
       }
       document
@@ -29,8 +29,8 @@ document.addEventListener(getPageLoadEvent(), () => {
   document.getElementById('stl-snippet-expand-button')?.addEventListener('click', (e) => {
     const btn = e.currentTarget as HTMLButtonElement;
 
-    const collapsedDiv = document.querySelector('.stl-snippet-code-is-collapsed') as HTMLElement | null;
-    const expandedDiv = document.querySelector('.stl-snippet-code-is-expanded') as HTMLElement | null;
+    const collapsedDiv = document.querySelector('.stl-snippet-code-is-collapsed');
+    const expandedDiv = document.querySelector('.stl-snippet-code-is-expanded');
 
     // We need to use javascript for height animations due to having dynamic heights based on snippet size.
     const animateHeight = (el: HTMLElement, expand: boolean) => {
@@ -71,7 +71,7 @@ document.addEventListener(getPageLoadEvent(), () => {
       el.style.height = `${endHeight}px`;
     };
 
-    if (collapsedDiv) {
+    if (collapsedDiv instanceof HTMLElement) {
       if (collapsedDiv) {
         collapsedDiv.querySelector('.shiki')?.setAttribute('style', `counter-reset: codeblock-line 0`);
       }
@@ -80,7 +80,7 @@ document.addEventListener(getPageLoadEvent(), () => {
       return;
     }
 
-    if (expandedDiv) {
+    if (expandedDiv instanceof HTMLElement) {
       const dataSnippetExpandedOffset = expandedDiv?.dataset.snippetExpandedOffset;
       if (dataSnippetExpandedOffset) {
         const offset = parseInt(dataSnippetExpandedOffset, 10);

package/plugin/globalJs/copy.ts

@@ -22,36 +22,44 @@ function getContent(button: HTMLElement, full: boolean) {
     contentCopy.querySelectorAll('.leading-ws').forEach((el) => el.remove());
   }
 
-  return contentCopy.textContent!;
+  return contentCopy.textContent;
 }
 
-const preloadPlayground = async (event: Event) => {
+const preloadPlayground = (event: Event) => {
   const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
   if (playButton) {
     loadPlayground(playButton);
   }
 };
 addEventListener('mouseover', preloadPlayground);
-addEventListener('click', async (event) => {
-  const copyButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-copy]') as HTMLElement;
+addEventListener('click', (event) => {
+  if (!(event.target instanceof HTMLElement)) return;
+  const copyButton = event.target.closest('[data-stldocs-snippet-copy]');
+  if (!(copyButton instanceof HTMLElement)) return;
+
   if (copyButton) {
     const iconElement = copyButton.querySelector('.stldocs-icon') as SVGElement;
     clearTimeout(copyButton.dataset.__stldocsCopyTimeout);
-    try {
-      await navigator.clipboard.writeText(getContent(copyButton, false));
-      iconElement.innerHTML = checkIcon;
-    } catch {
-      iconElement.innerHTML = circleAlertIcon;
-    }
-    copyButton.dataset.__stldocsCopyTimeout =
-      setTimeout(() => {
-        iconElement.innerHTML = copyIcon;
-      }, 1000) + '';
+    navigator.clipboard
+      .writeText(getContent(copyButton, false))
+      .then(() => {
+        iconElement.innerHTML = checkIcon;
+      })
+      .catch(() => {
+        iconElement.innerHTML = circleAlertIcon;
+      })
+      .finally(() => {
+        copyButton.dataset.__stldocsCopyTimeout = setTimeout(() => {
+          iconElement.innerHTML = copyIcon;
+        }).toString();
+      });
   }
 
-  const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
-  if (playButton) {
-    showPlayground(playButton);
+  const playButton = event.target.closest('[data-stldocs-snippet-play]');
+  if (playButton instanceof HTMLElement) {
+    showPlayground(playButton).catch(() => {
+      console.error('Failed to load playground');
+    });
   }
 });
 
@@ -87,7 +95,6 @@ function loadPlayground(playButton: HTMLElement) {
     const { createPlayground } = await import('virtual:stl-playground/create');
     const { default: playgroundData } = await import('virtual:stl-playground/data');
     return createPlayground({
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       lang: language as any,
       doc: (language === 'python' ? 'from rich import print\n' : '') + code.trimEnd(),
       container,
@@ -109,7 +116,10 @@ function loadPlayground(playButton: HTMLElement) {
 document.addEventListener(getPageLoadEvent(), () => {
   if (new URL(location.href).searchParams.has('play')) {
     document.querySelectorAll('[data-stldocs-snippet-play]').forEach((e) => {
-      showPlayground(e as HTMLElement);
+      if (e instanceof HTMLElement)
+        showPlayground(e).catch(() => {
+          console.error('Failed to load playground');
+        });
     });
   }
 });

package/plugin/globalJs/navigation.ts

@@ -27,7 +27,9 @@ document.addEventListener(getPageLoadEvent(), () => {
       root: rootElement,
       onSelect: (value) => {
         const originalLanguage = rootElement.dataset.currentValue;
-        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
+        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value)).catch((e) => {
+          console.error('Failed to navigate to selected language', e);
+        });
       },
     });
   });
@@ -53,7 +55,7 @@ document.addEventListener('click', (event) => {
   if (!target) return;
 
   target.querySelectorAll('details').forEach((details) => {
-    const el = details as HTMLDetailsElement;
+    const el = details;
     const initial = el.dataset.stldocsExpanderInitialState;
     el.open = initial === 'true' ? true : !state;
   });

package/plugin/index.ts

@@ -89,14 +89,12 @@ export function generateAPIReferenceItems(
   return makePlaceholderItems(id);
 }
 
-async function stlStarlightAstroIntegration(
-  pluginConfig: NormalizedStainlessStarlightConfig,
-): Promise<AstroIntegration> {
+function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlightConfig): AstroIntegration {
   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;
+  let buildPlaygrounds: (args: unknown) => Promise<void> | undefined;
   let astroBase = '/';
 
   let specLoader: SpecLoader | undefined;
@@ -125,7 +123,7 @@ async function stlStarlightAstroIntegration(
 
       const langs = specComposite.getLanguages();
 
-      await buildPlaygrounds!({
+      return buildPlaygrounds?.({
         spec,
         langs,
         auth,
@@ -133,6 +131,8 @@ async function stlStarlightAstroIntegration(
         reportError(message: string) {
           (reportError ?? console.error)(message);
         },
+      })?.catch(() => {
+        console.error('Failed to build playgrounds');
       });
     })());
   }
@@ -396,7 +396,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
   return {
     name: 'stl-starlight',
     hooks: {
-      'config:setup': async ({
+      'config:setup': ({
         addIntegration,
         updateConfig,
         addRouteMiddleware,
@@ -456,7 +456,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           }
         }
 
-        addIntegration(await stlStarlightAstroIntegration(config));
+        addIntegration(stlStarlightAstroIntegration(config));
 
         const expressiveCodeConfig =
           typeof starlightConfig.expressiveCode === 'object' ? starlightConfig.expressiveCode : {};

package/plugin/react/Routing.tsx

@@ -342,7 +342,7 @@ export function RenderSpec({
 
   return (
     <DocsProvider
-      spec={spec as SDKJSON.Spec}
+      spec={spec}
       language={language ?? 'node'}
       settings={{
         contentPanelLayout,
@@ -356,7 +356,7 @@ export function RenderSpec({
               <div className="stldocs-root stl-ui-not-prose">
                 <div className="stl-page-nav-container">
                   <SDKBreadcrumbs
-                    spec={spec as SDKJSON.Spec}
+                    spec={spec}
                     currentPath={currentPath}
                     basePath={RESOLVED_API_REFERENCE_PATH}
                     config={BREADCRUMB_CONFIG}

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -32,7 +32,7 @@ function markCurrentItems(sidebar: SidebarEntry[], currentSlug: string) {
   return mutableSidebarInstance;
 }
 
-export const onRequest = defineRouteMiddleware(async (context) => {
+export const onRequest = defineRouteMiddleware((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 = path.posix.join(import.meta.env.BASE_URL ?? '', `/${context.locals.starlightRoute.id}`); // same as .slug but not deprecated

package/plugin/routes/Overview.astro

@@ -68,7 +68,7 @@ Astro.locals._stlStarlightPage = {
     gap: 1rem;
     margin-top: 2rem;
 
-    .stldocs-language-block {
+    > * {
       width: 0;
       flex: 1 1 350px;
     }

package/plugin/specs/index.ts

@@ -93,13 +93,18 @@ export async function startSpecLoader(
     const specs = await pluginConfig.api.loadSpecs();
 
     // not awaited since it's just cleanup
-    specCache.cleanupUnusedFiles().then((result) => {
-      if (result.deletedCount > 0) {
-        logger.info(`Cleaned up ${result.deletedCount} unused spec files`);
-      } else {
-        logger.debug(`No unused spec files to clean up`);
-      }
-    });
+    specCache
+      .cleanupUnusedFiles()
+      .then((result) => {
+        if (result.deletedCount > 0) {
+          logger.info(`Cleaned up ${result.deletedCount} unused spec files`);
+        } else {
+          logger.debug(`No unused spec files to clean up`);
+        }
+      })
+      .catch(() => {
+        logger.warn(`Failed to clean up unused spec files`);
+      });
 
     return {
       specComposite: new SpecComposite(specs),

package/plugin/specs/inputResolver.ts

@@ -7,7 +7,9 @@ import Stainless, { APIError } from '@stainless-api/sdk';
 import { GenerateSpecRawInputs } from './generateSpec';
 
 export type SpecInputResolver = {
-  resolve: (context: { apiKey: LoadedApiKey | null }) => Promise<GenerateSpecRawInputs>;
+  resolve: (context: {
+    apiKey: LoadedApiKey | null;
+  }) => GenerateSpecRawInputs | Promise<GenerateSpecRawInputs>;
   printError: (error: Error, logger: AstroIntegrationLogger) => void;
 };
 
@@ -123,7 +125,7 @@ function fromStrings({
   stainlessProject: string;
 }): SpecInputResolver {
   return {
-    async resolve() {
+    resolve() {
       return {
         oasStr,
         configStr,