@stainless-api/docs 0.1.0-beta.1 → 0.1.0-beta.11

package/stl-docs/index.ts

@@ -40,14 +40,21 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
   }
 
   type ComponentOverrides = StarlightConfigDefined['components'];
+  const plugins = [...config.starlightCompat.plugins];
+
   const componentOverrides: ComponentOverrides = {
-    Search: '@stainless-api/docs/Search',
-    Sidebar: '@stainless-api/docs/Sidebar',
+    Sidebar: '@stainless-api/docs/BaseSidebar',
     Header: '@stainless-api/docs/Header',
     ThemeSelect: '@stainless-api/docs/ThemeSelect',
     ContentPanel: '@stainless-api/docs/ContentPanel',
   };
 
+  if (config.apiReference !== null) {
+    componentOverrides.Sidebar = '@stainless-api/docs/SDKSelectSidebar';
+    componentOverrides.Search = '@stainless-api/docs/Search';
+    plugins.unshift(stainlessStarlight(config.apiReference));
+  }
+
   // TODO: re-add once we figure out what to do with the client router
   // if (config.enableClientRouter) {
   //   // logger.info(`Client router is enabled`);
@@ -94,12 +101,12 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
     ],
     routeMiddleware: [...config.starlightCompat.routeMiddleware, '@stainless-api/docs/tabsMiddleware'],
     customCss: ['@stainless-api/docs/theme', ...config.customCss],
-    plugins: [stainlessStarlight(config.apiReference), ...config.starlightCompat.plugins],
+    plugins,
   });
 }
 
 function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroIntegration {
-  const virtualId = `virtual:stl-stl-starlight-virtual-module`;
+  const virtualId = `virtual:stl-docs-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolvedId = `\0${virtualId}`;
   let redirects: NormalizedRedirectConfig | null = null;
@@ -116,6 +123,10 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
 
         updateConfig({
           vite: {
+            ssr: {
+              noExternal: ['@stainless-api/ui-primitives'],
+            },
+            optimizeDeps: { include: ['@stainless-api/ui-primitives'] },
             plugins: [
               {
                 name: 'stl-docs-vite',
@@ -132,6 +143,7 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
                       HEADER_LINKS: config.header.links,
                       HEADER_LAYOUT: config.header.layout,
                       ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+                      INCLUDE_AI_DROPDOWN_OPTIONS: config.includeAIDropdownOptions,
                     });
                   }
                 },
@@ -166,6 +178,7 @@ export function stainlessDocs(config: StainlessDocsUserConfig) {
     process.exit(1);
   }
   const normalizedConfig = normalizedConfigResult.config;
+
   return [
     react(),
     stainlessDocsStarlightIntegration(normalizedConfig),

package/stl-docs/loadStlDocsConfig.ts

@@ -58,7 +58,7 @@ export type HeaderLink = {
 };
 
 export type StainlessDocsUserConfig = {
-  apiReference: StainlessStarlightUserConfig;
+  apiReference?: StainlessStarlightUserConfig;
   tabs?: Tabs;
   header?: {
     layout?: HeaderLayout;
@@ -126,8 +126,9 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
       routeMiddleware: normalizeRouteMiddleware(userConfig),
     },
     enableClientRouter: userConfig.experimental?.enableClientRouter ?? false,
-    apiReference: userConfig.apiReference,
+    apiReference: userConfig.apiReference ?? null,
     sidebar: userConfig.sidebar,
+    includeAIDropdownOptions: userConfig.apiReference?.includeAIDropdownOptions ?? false,
   };
 
   return configWithDefaults;

package/stl-docs/tabsMiddleware.ts

@@ -1,7 +1,7 @@
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 
-import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-stl-starlight-virtual-module';
+import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-docs-virtual-module';
 import clsx from 'clsx';
 
 // this fn is loaded in the plugin via addRouteMiddleware
@@ -143,7 +143,7 @@ export const onRequest = defineRouteMiddleware(async (context) => {
   }
 
   // We store the active tab index so we can use it in our nav tabs component
-  context.locals.starlightRoute._stlStarlight = {
+  context.locals.starlightRoute._stlDocs = {
     activeTabIndex: activeTabIndex.index,
   };
 

package/styles/code.css

@@ -1,72 +1,90 @@
-@layer stainless {
-  .expressive-code {
-    .frame {
-      --code-background: var(--sl-color-bg-inline-code);
-    }
+.expressive-code {
+  .frame {
+    --code-background: var(--sl-color-bg-inline-code);
+  }
 
-    figure.frame {
-      box-shadow: none;
+  figure.frame {
+    box-shadow: none;
+  }
+
+  figure,
+  pre {
+    border-radius: var(--sl-button-border-radius);
+    border-color: var(--sl-color-hairline);
+  }
+
+  .frame.has-title:not(.is-terminal),
+  .frame.is-terminal {
+    figcaption {
+      border-radius: var(--sl-button-border-radius) var(--sl-button-border-radius) 0 0;
+      border-color: var(--sl-color-hairline);
     }
 
-    figure,
     pre {
-      border-radius: var(--sl-button-border-radius);
+      border-radius: 0 0 var(--sl-button-border-radius) var(--sl-button-border-radius);
       border-color: var(--sl-color-hairline);
     }
+  }
 
-    .frame.has-title:not(.is-terminal),
-    .frame.is-terminal {
-      figcaption {
-        border-radius: var(--sl-button-border-radius) var(--sl-button-border-radius) 0 0;
-        border-color: var(--sl-color-hairline);
-      }
-
-      pre {
-        border-radius: 0 0 var(--sl-button-border-radius) var(--sl-button-border-radius);
-        border-color: var(--sl-color-hairline);
-      }
+  .frame.has-title:not(.is-terminal) {
+    figcaption span:first-child {
+      border-top-left-radius: var(--sl-button-border-radius);
     }
 
-    .frame.has-title:not(.is-terminal) {
-      figcaption span:first-child {
-        border-top-left-radius: var(--sl-button-border-radius);
-      }
-
-      .header::before {
-        border-color: var(--sl-color-hairline);
-      }
+    .header::before {
+      border-color: var(--sl-color-hairline);
+    }
 
-      .title::after {
-        bottom: -1px;
-        top: unset;
-      }
+    .title::after {
+      bottom: -1px;
+      top: unset;
     }
   }
+}
 
-  .astro-code {
-    border-radius: var(--sl-button-border-radius);
-    border-color: var(--sl-color-hairline);
-  }
+.astro-code {
+  border-radius: var(--sl-button-border-radius);
+  border-color: var(--sl-color-hairline);
+}
+
+.stl-snippet-request-container {
+  position: relative;
+}
+
+.stl-snippet-expand-button {
+  display: none;
 
-  .stl-snippet-request-container {
-    position: relative;
+  position: relative;
+  left: 50%;
+  transform: translateX(-50%);
+  bottom: 12px;
+  cursor: pointer;
+  height: auto;
+}
+
+.stl-snippet-code-is-expanded {
+  .ellipsis {
+    display: none;
   }
+}
 
+.stl-snippet-collapsible {
   .stl-snippet-expand-button {
-    display: none;
+    display: block;
+    margin-bottom: -23px;
+    /* Prevent clipping of the button with the container below */
+    z-index: 100;
+  }
 
-    position: relative;
-    left: 50%;
-    transform: translateX(-50%);
-    bottom: 12px;
-    background-color: var(--stldocs-color-bg-inline-code);
-    cursor: pointer;
-    font-weight: 500;
-    line-height: 100%;
-    font-size: var(--stldocs-font-size-body-sm);
-    font-family: var(--stldocs-font);
-    padding: 4px 7px 4px 7px;
-    height: auto;
+  .stl-snippet-code-is-collapsed {
+    .hidden {
+      display: none;
+      opacity: 0;
+    }
+
+    .leading-ws {
+      display: none;
+    }
   }
 
   .stl-snippet-code-is-expanded {
@@ -74,116 +92,91 @@
       display: none;
     }
   }
+}
 
-  .stl-snippet-collapsible {
-    .stl-snippet-expand-button {
-      display: block;
-      margin-bottom: -23px;
-      /* Prevent clipping of the button with the container below */
-      z-index: 100;
+.stldocs-root {
+  .stl-snippets-non-collapsible {
+    .shiki {
+      counter-reset: codeblock-line 0 !important;
     }
 
-    .stl-snippet-code-is-collapsed {
+    .stldocs-snippet {
       .hidden {
-        display: none;
-        opacity: 0;
+        display: inline;
+        opacity: 1;
       }
 
       .leading-ws {
-        display: none;
+        display: inline;
       }
-    }
 
-    .stl-snippet-code-is-expanded {
       .ellipsis {
         display: none;
       }
     }
   }
+}
 
-  .stldocs-root {
-    .stl-snippets-non-collapsible {
-      .shiki {
-        counter-reset: codeblock-line 0 !important;
-      }
-
-      .stldocs-snippet {
-        .hidden {
-          display: inline;
-          opacity: 1;
-        }
-
-        .leading-ws {
-          display: inline;
-        }
-
-        .ellipsis {
-          display: none;
-        }
-      }
-    }
+.stldocs-root .stl-snippet-dropdown-button-text,
+.stl-snippet-dropdown-button-text {
+  font-weight: 500;
+  font-style: normal;
+  font-family: var(--stldocs-font);
+  line-height: 100%;
+  font-size: var(--sl-text-body-sm);
+  color: var(--sl-color-text);
+  text-transform: capitalize;
+
+  &.http {
+    text-transform: uppercase;
   }
+}
 
-  .stl-snippet-dropdown-button-text {
-    font-weight: 500;
-    font-style: normal;
-    font-family: var(--stldocs-font);
-    line-height: 100%;
-    font-size: var(--sl-text-body-sm);
-    color: var(--sl-color-text);
-    text-transform: capitalize;
-
-    &.http {
-      text-transform: uppercase;
-    }
+:root[data-theme='light'] {
+  .astro-code,
+  .astro-code span {
+    background-color: var(--sl-color-bg-inline-code) !important;
   }
 
-  :root[data-theme='light'] {
+  .stldocs-snippet-response-pane {
+    .shiki,
+    .shiki span,
     .astro-code,
     .astro-code span {
       background-color: var(--sl-color-bg-inline-code) !important;
     }
-
-    .stldocs-snippet-response-pane {
-      .shiki,
-      .shiki span,
-      .astro-code,
-      .astro-code span {
-        background-color: var(--sl-color-bg-inline-code) !important;
-      }
-    }
   }
+}
 
-  :root[data-theme='dark'] {
-    /* 
+:root[data-theme='dark'] {
+  /* 
     Need to use important to override inline variables. This is the
     recommended pattern in the shiki docs.
 
     https://shiki.style/guide/dual-themes#query-based-dark-mode
    */
+  .shiki,
+  .shiki span,
+  .astro-code,
+  .astro-code span {
+    color: var(--shiki-dark) !important;
+    background-color: var(--sl-color-bg) !important;
+    font-style: var(--shiki-dark-font-style) !important;
+    font-weight: var(--shiki-dark-font-weight) !important;
+    text-decoration: var(--shiki-dark-text-decoration) !important;
+  }
+
+  .astro-code,
+  .astro-code span {
+    background-color: var(--sl-color-bg-inline-code) !important;
+  }
+
+  .stldocs-snippet-response-pane {
     .shiki,
     .shiki span,
-    .astro-code,
-    .astro-code span {
-      color: var(--shiki-dark) !important;
-      background-color: var(--sl-color-bg) !important;
-      font-style: var(--shiki-dark-font-style) !important;
-      font-weight: var(--shiki-dark-font-weight) !important;
-      text-decoration: var(--shiki-dark-text-decoration) !important;
-    }
-
     .astro-code,
     .astro-code span {
       background-color: var(--sl-color-bg-inline-code) !important;
     }
-
-    .stldocs-snippet-response-pane {
-      .shiki,
-      .shiki span,
-      .astro-code,
-      .astro-code span {
-        background-color: var(--sl-color-bg-inline-code) !important;
-      }
-    }
   }
 }

package/styles/links.css

@@ -1,51 +1,49 @@
-@layer stainless {
-  .sl-link-card {
-    box-shadow: none;
+.sl-link-card {
+  box-shadow: none;
+  border-radius: var(--sl-button-border-radius);
+  padding: 1.5rem;
+  margin-top: 16px;
+}
+
+.sl-link-card:hover {
+  transition: 0.3s;
+  border: 1px solid var(--sl-color-accent-high);
+  background-color: var(--sl-color-accent-low);
+}
+
+.pagination-links {
+  margin-bottom: 2rem;
+
+  > a {
     border-radius: var(--sl-button-border-radius);
-    padding: 1.5rem;
-    margin-top: 16px;
+    border: 1px solid transparent;
+    box-shadow: none;
+    max-width: 90%;
+    text-decoration: none;
+
+    svg {
+      margin-top: 0;
+      transform: translateY(6px);
+    }
   }
 
-  .sl-link-card:hover {
+  > a:hover {
     transition: 0.3s;
     border: 1px solid var(--sl-color-accent-high);
     background-color: var(--sl-color-accent-low);
+    box-shadow: none;
   }
 
-  .pagination-links {
-    margin-bottom: 2rem;
-
-    > a {
-      border-radius: var(--sl-button-border-radius);
-      border: 1px solid transparent;
-      box-shadow: none;
-      max-width: 90%;
-      text-decoration: none;
-
-      svg {
-        margin-top: 0;
-        transform: translateY(6px);
-      }
-    }
-
-    > a:hover {
-      transition: 0.3s;
-      border: 1px solid var(--sl-color-accent-high);
-      background-color: var(--sl-color-accent-low);
-      box-shadow: none;
-    }
-
-    /* if only one pagination direction */
-    > a:first-child:nth-last-child(1) {
-      max-width: 45%;
-    }
+  /* if only one pagination direction */
+  > a:first-child:nth-last-child(1) {
+    max-width: 45%;
+  }
 
-    > a[rel='next'] {
-      margin-left: auto;
-    }
+  > a[rel='next'] {
+    margin-left: auto;
+  }
 
-    > a[rel='prev'] {
-      margin-right: auto;
-    }
+  > a[rel='prev'] {
+    margin-right: auto;
   }
 }

package/styles/overrides.css

@@ -1,79 +1,77 @@
-@layer stainless {
-  html {
-    font-size: 16px;
-  }
+html {
+  font-size: 16px;
+}
 
-  .site-title {
-    color: var(--sl-color-white);
-    max-width: 144px;
+.site-title {
+  color: var(--sl-color-white);
+  max-width: 144px;
 
-    img {
-      height: 32px;
-      width: auto;
-    }
+  img {
+    height: 32px;
+    width: auto;
   }
+}
+
+/* Hide the text in the theme select dropdown */
+starlight-theme-select select {
+  width: 0;
+  overflow: hidden;
+}
 
-  /* Hide the text in the theme select dropdown */
-  starlight-theme-select select {
-    width: 0;
-    overflow: hidden;
+.custom-select-wrapper select,
+.stldocs-button-secondary {
+  background-color: var(--sl-color-bg-ui);
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: var(--sl-button-border-radius);
+
+  &:hover {
+    border-color: var(--sl-color-hairline-shade);
   }
+}
+
+.content-panel {
+  border-top: 0;
+}
 
-  .custom-select-wrapper select,
-  .stldocs-button-secondary {
-    background-color: var(--sl-color-bg-ui);
-    border: 1px solid var(--sl-color-hairline);
-    border-radius: var(--sl-button-border-radius);
+starlight-menu-button button {
+  box-shadow: none;
+  background-color: var(--sl-color-bg-ui);
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: var(--sl-button-border-radius);
+  height: var(--sl-button-size);
+  width: var(--sl-button-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
 
-    &:hover {
-      border-color: var(--sl-color-hairline-shade);
-    }
+  &:hover {
+    border-color: var(--sl-color-hairline-shade);
   }
+}
 
-  .content-panel {
-    border-top: 0;
+mobile-starlight-toc {
+  nav {
+    background-color: var(--sl-color-bg);
   }
 
-  starlight-menu-button button {
-    box-shadow: none;
-    background-color: var(--sl-color-bg-ui);
-    border: 1px solid var(--sl-color-hairline);
-    border-radius: var(--sl-button-border-radius);
-    height: var(--sl-button-size);
-    width: var(--sl-button-size);
-    display: flex;
-    align-items: center;
-    justify-content: center;
+  summary {
+    padding: 2rem 1rem;
+    border-bottom-color: var(--sl-color-hairline-light);
+  }
+}
 
-    &:hover {
-      border-color: var(--sl-color-hairline-shade);
-    }
+@media (min-width: 50rem) {
+  starlight-menu-button button {
+    display: none;
   }
 
   mobile-starlight-toc {
     nav {
-      background-color: var(--sl-color-bg);
+      inset-inline-start: calc(var(--sl-content-inline-start, 0));
     }
 
     summary {
-      padding: 2rem 1rem;
-      border-bottom-color: var(--sl-color-hairline-light);
-    }
-  }
-
-  @media (min-width: 50rem) {
-    starlight-menu-button button {
-      display: none;
-    }
-
-    mobile-starlight-toc {
-      nav {
-        inset-inline-start: calc(var(--sl-content-inline-start, 0));
-      }
-
-      summary {
-        padding: 2rem 2rem;
-      }
+      padding: 2rem 2rem;
     }
   }
 }