@stainless-api/docs 0.1.0-beta.59 → 0.1.0-beta.60

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.60
+
+### Patch Changes
+
+- 2d00f0d: compatibility with the first alpha version of docs-ai-chat
+- Updated dependencies [2d00f0d]
+  - @stainless-api/docs-ui@0.1.0-beta.50
+  - @stainless-api/ui-primitives@0.1.0-beta.37
+  - @stainless-api/docs-search@0.1.0-beta.2
+
 ## 0.1.0-beta.59
 
 ### Patch Changes

package/locals.d.ts

@@ -10,5 +10,7 @@ declare namespace App {
       hasMarkdownRoute?: boolean;
       fullSidebar?: SidebarEntry[];
     };
+
+    language?: import('@stainless-api/docs-ui/routing').DocsLanguage;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.59",
+  "version": "0.1.0-beta.60",
   "publishConfig": {
     "access": "public"
   },
@@ -52,9 +52,9 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-ui": "0.1.0-beta.49",
-    "@stainless-api/docs-search": "0.1.0-beta.1",
-    "@stainless-api/ui-primitives": "0.1.0-beta.36"
+    "@stainless-api/docs-ui": "0.1.0-beta.50",
+    "@stainless-api/docs-search": "0.1.0-beta.2",
+    "@stainless-api/ui-primitives": "0.1.0-beta.37"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",

package/plugin/index.ts

@@ -301,6 +301,7 @@ async function stlStarlightAstroIntegration(
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
                         EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
+                        STAINLESS_PROJECT: version.stainlessProject,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');

package/plugin/routes/Docs.astro

@@ -38,6 +38,7 @@ const pageNav =
       : [];
 
 const props = route.props;
+Astro.locals.language = props.language;
 
 if (readme) {
   const repo = spec.metadata?.[props.language]?.code_url;

package/stl-docs/components/AiChatIsland.tsx

@@ -0,0 +1,10 @@
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import AiChat from 'virtual:stl-docs/components/AiChat.tsx';
+// right now loading AiChat without API reference plugin is unsupported
+// because the AiChat is for talking about the SDKs
+import { STAINLESS_PROJECT } from 'virtual:stl-starlight-virtual-module';
+
+export default function AiChatIsland({ currentLanguage }: { currentLanguage: DocsLanguage | undefined }) {
+  if (!AiChat) throw new Error('AiChatIsland was rendered but could not load AiChat component');
+  return <AiChat projectId={STAINLESS_PROJECT} language={currentLanguage} />;
+}

package/stl-docs/components/PageFrame.astro

@@ -0,0 +1,14 @@
+---
+import Default from '@astrojs/starlight/components/PageFrame.astro';
+import AiChat from 'virtual:stl-docs/components/AiChat.tsx'; // conditionally resolves to null if ai chat module is not injected
+import AiChatIsland from './AiChatIsland.tsx'; // entrypoint for client island can’t be a virtual module
+---
+
+<Default>
+  <slot name="header" slot="header" />
+  <slot name="sidebar" slot="sidebar" />
+
+  <slot />
+
+  {!!AiChat && <AiChatIsland client:load currentLanguage={Astro.locals.language} />}
+</Default>

package/stl-docs/index.ts

@@ -48,12 +48,16 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
 
   type ComponentOverrides = StarlightConfigDefined['components'];
   const componentOverrides: ComponentOverrides = {
-    Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
-    Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
+    PageFrame: resolveSrcFile(COMPONENTS_FOLDER, './PageFrame.astro'),
+
     Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
+    Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
     ThemeSelect: resolveSrcFile(COMPONENTS_FOLDER, './ThemeSelect.astro'),
+
+    Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
     ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './content-panel/ContentPanel.astro'),
     TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
+
     PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
     Pagination: resolveSrcFile(COMPONENTS_FOLDER, './pagination/Pagination.astro'),
   };
@@ -144,17 +148,38 @@ function stainlessDocsIntegration(
   config: NormalizedStainlessDocsConfig,
   apiReferenceBasePath: string | null,
 ): AstroIntegration {
-  const virtualId = `virtual:stl-docs-virtual-module`;
+  const virtualModules = new Map(
+    Object.entries({
+      'virtual:stl-docs-virtual-module': buildVirtualModuleString({
+        TABS: config.tabs,
+        SPLIT_TABS_ENABLED: config.splitTabsEnabled,
+        HEADER_LINKS: config.header.links,
+        HEADER_LAYOUT: config.header.layout,
+        ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+        API_REFERENCE_BASE_PATH: apiReferenceBasePath,
+        ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+        // TODO: do not duplicate this between both virtual modules
+        ENABLE_CONTEXT_MENU: config.contextMenu,
+        RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+      } satisfies typeof StlDocsVirtualModule),
+
+      'virtual:stl-docs/components/AiChat.tsx': config.aiChat
+        ? `export { default } from ${JSON.stringify(config.aiChat.chatComponentPath)};`
+        : // export null when no AI chat component is provided
+          `export default null;`,
+    }),
+  );
+
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
-  const resolvedId = `\0${virtualId}`;
+  const resolveVirtualModuleId = (id: string) => `\0${id}`;
   let redirects: NormalizedRedirectConfig | null = null;
 
   return {
     name: 'stl-docs-astro',
     hooks: {
       'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
-        // // we only handle redirects for builds
-        // // in dev, Astro handles them for us
+        // we only handle redirects for builds
+        // in dev, Astro handles them for us
         if (command === 'build' && astroConfig.redirects) {
           redirects = normalizeRedirects(astroConfig.redirects);
         }
@@ -165,25 +190,11 @@ function stainlessDocsIntegration(
               {
                 name: 'stl-docs-vite',
                 resolveId(id) {
-                  if (id === virtualId) {
-                    return resolvedId;
-                  }
+                  if (virtualModules.has(id)) return resolveVirtualModuleId(id);
                 },
                 load(id) {
-                  if (id === resolvedId) {
-                    return buildVirtualModuleString({
-                      TABS: config.tabs,
-                      SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-                      HEADER_LINKS: config.header.links,
-                      HEADER_LAYOUT: config.header.layout,
-                      ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-                      API_REFERENCE_BASE_PATH: apiReferenceBasePath,
-                      ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
-                      // TODO: do not duplicate this between both virtual modules
-                      ENABLE_CONTEXT_MENU: config.contextMenu,
-                      RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
-                    } satisfies typeof StlDocsVirtualModule);
-                  }
+                  const bare = id.replace(/^\0/, '');
+                  if (virtualModules.has(bare)) return virtualModules.get(bare);
                 },
               },
             ],

package/stl-docs/loadStlDocsConfig.ts

@@ -75,6 +75,7 @@ export type StainlessDocsUserConfig = {
      * @default false
      */
     disableProseMarkdownRendering?: boolean;
+    aiChat?: { chatComponentPath: string };
   };
   /**
    * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
@@ -166,6 +167,7 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
     expressiveCode: userConfig.expressiveCode,
     renderPageDescriptions: userConfig.renderPageDescriptions ?? true,
     plugins: userConfig.plugins ?? [],
+    aiChat: userConfig.experimental?.aiChat,
   };
 
   return configWithDefaults;

package/styles/code.css

@@ -131,6 +131,11 @@
 .astro-code,
 .stldocs-snippet-response-pane {
   background-color: var(--shiki-background, var(--stl-color-faint-background)) !important;
+  .shiki,
+  .astro-code,
+  .stldocs-snippet-response-pane {
+    background-color: transparent !important;
+  }
 }
 
 :root[data-theme='dark'] {

package/virtual-module.d.ts

@@ -23,6 +23,7 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const STAINLESS_PROJECT: string;
 }
 
 declare module 'virtual:stl-docs-virtual-module' {
@@ -50,3 +51,13 @@ declare module 'virtual:stl-docs-virtual-module' {
   export const ENABLE_CONTEXT_MENU: boolean;
   export const RENDER_PAGE_DESCRIPTIONS: boolean;
 }
+
+declare module 'virtual:stl-docs/components/AiChat.tsx' {
+  const AiChatComponent:
+    | import('react').ComponentType<{
+        projectId: string;
+        language: import('@stainless-api/docs-ui/routing').DocsLanguage | undefined;
+      }>
+    | null;
+  export default AiChatComponent;
+}