@stainless-api/docs 0.1.0-beta.6 → 0.1.0-beta.61

package/stl-docs/proseSearchIndexing.ts

@@ -0,0 +1,113 @@
+import type { AstroIntegration } from 'astro';
+import { readFile } from 'fs/promises';
+import { getSharedLogger } from '../shared/getSharedLogger';
+import { bold } from '../shared/terminalUtils';
+import { buildProseIndex } from '@stainless-api/docs-search/providers/algolia';
+import * as cheerio from 'cheerio';
+
+function chunkByWords(content: string, chunkSize: number = 30000, chunkOverlap: number = 10) {
+  if (Buffer.byteLength(content) < chunkSize) return [content];
+
+  const words = content.split(/\s+/);
+  const chunks: string[] = [];
+
+  let currentChunk: string[] = [];
+  let currentSize = 0;
+
+  for (const word of words) {
+    const wordSize = Buffer.byteLength(word + ' ', 'utf-8');
+
+    if (currentSize + wordSize > chunkSize && currentChunk.length > 0) {
+      chunks.push(currentChunk.join(' '));
+
+      const overlapStart = Math.max(0, currentChunk.length - chunkOverlap);
+      currentChunk = currentChunk.slice(overlapStart);
+      currentSize = Buffer.byteLength(currentChunk.join(' '), 'utf-8');
+    }
+
+    currentChunk.push(word);
+    currentSize += wordSize;
+  }
+
+  if (currentChunk.length > 0) {
+    chunks.push(currentChunk.join(' '));
+  }
+
+  return chunks;
+}
+
+export function* indexHTML(content: string, root: string, pattern: string) {
+  const $ = cheerio.load(content);
+  const matches = $(root).find(pattern);
+
+  for (const match of matches) {
+    const rawText = $(match).text().trim();
+    const chunks = chunkByWords(rawText);
+    const chunkId = crypto.randomUUID();
+
+    for (const [chunkN, content] of chunks.entries()) {
+      yield {
+        id: $(match).attr('id'),
+        tag: match.tagName.toLowerCase(),
+        content,
+        chunk: {
+          id: chunkId,
+          index: chunkN,
+          total: chunks.length,
+        },
+      };
+    }
+  }
+}
+
+const root = 'main';
+const pattern = 'h1, h2, h3, h4, h5, h6, p, li';
+
+export function stainlessDocsProseIndexing(): AstroIntegration {
+  return {
+    name: 'stl-docs-prose-indexing',
+    hooks: {
+      'astro:build:done': async ({ assets, logger: localLogger, dir }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
+        const outputBasePath = dir.pathname;
+
+        const {
+          PUBLIC_ALGOLIA_APP_ID: appId,
+          PUBLIC_ALGOLIA_INDEX: indexName,
+          PRIVATE_ALGOLIA_WRITE_KEY: algoliaWriteKey,
+        } = process.env;
+
+        if (!appId || !indexName || !algoliaWriteKey) {
+          logger.info('Skipping algolia indexing due to missing environment variables');
+          return;
+        }
+
+        const starlightPagePatterns = ['/[...slug]'];
+        const pagesToRender = Array.from(assets.entries())
+          .filter(([k]) => starlightPagePatterns.includes(k))
+          .map(([, v]) => v)
+          .flat()
+          .map((v) => v.pathname);
+
+        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for search`));
+
+        const objects = [];
+        for (const absHtmlPath of pagesToRender) {
+          const content = await readFile(absHtmlPath, 'utf-8');
+          const idx = indexHTML(content, root, pattern);
+          for (const entry of idx)
+            objects.push({
+              ...entry,
+              source: absHtmlPath.slice(outputBasePath.length),
+            });
+        }
+
+        try {
+          await buildProseIndex(appId, `${indexName}-prose`, algoliaWriteKey, objects);
+        } catch (err) {
+          logger.error(`Failed to index prose content: ${err}`);
+        }
+      },
+    },
+  };
+}

package/stl-docs/tabsMiddleware.ts

@@ -58,7 +58,7 @@ function getTabIndexForSlug(
   match: 'exact' | 'prefix';
 } | null {
   // ↓ exact match eg. slug = "/blog" and there is a link containing "/blog"
-  let tab = linksByTab.get(slug);
+  const tab = linksByTab.get(slug)!;
   if (typeof tab === 'string') {
     return {
       match: 'exact',
@@ -88,13 +88,19 @@ function getNonSplitLinksByTab() {
   const linksByTab = new Map<string, string>();
 
   for (let i = 0; i < TABS.length; i++) {
-    const tab = TABS[i];
+    const tab = TABS[i]!;
     linksByTab.set(tab.link, String(i));
   }
 
   return linksByTab;
 }
 
+export interface StarlightRouteWithStlDocs extends StarlightRouteData {
+  _stlDocs?: {
+    activeTabIndex: number;
+  };
+}
+
 export const onRequest = defineRouteMiddleware(async (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
@@ -143,7 +149,8 @@ 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 = {
+  const routeData: StarlightRouteWithStlDocs = context.locals.starlightRoute;
+  routeData._stlDocs = {
     activeTabIndex: activeTabIndex.index,
   };
 
@@ -179,5 +186,6 @@ export const onRequest = defineRouteMiddleware(async (context) => {
 
   matchingGroup?.entries.unshift(...mobileLinks);
 
+  (context.locals._stlStarlightPage ??= {}).fullSidebar = context.locals.starlightRoute.sidebar;
   context.locals.starlightRoute.sidebar = matchingGroup.entries;
 });

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(--stl-color-faint-background);
+  }
+
+  figure.frame {
+    box-shadow: none;
+  }
 
-    figure.frame {
-      box-shadow: none;
+  figure,
+  pre {
+    border-radius: var(--sl-button-border-radius);
+    border-color: var(--stl-color-border);
+  }
+
+  .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(--stl-color-border);
     }
 
-    figure,
     pre {
-      border-radius: var(--sl-button-border-radius);
-      border-color: var(--sl-color-hairline);
+      border-radius: 0 0 var(--sl-button-border-radius) var(--sl-button-border-radius);
+      border-color: var(--stl-color-border);
     }
+  }
 
-    .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(--stl-color-border);
+    }
 
-      .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(--stl-color-border);
+}
 
-  .stl-snippet-request-container {
-    position: relative;
+.stl-snippet-request-container {
+  position: relative;
+}
+
+.stl-snippet-expand-button {
+  display: none;
+
+  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,66 @@
       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;
-        }
-      }
-    }
-  }
-
-  .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;
-    }
+.stldocs-root .stl-snippet-dropdown-button-text,
+.stl-snippet-dropdown-button-text {
+  font-weight: 500;
+  font-style: normal;
+  font-family: var(--stl-typography-font);
+  line-height: 100%;
+  font-size: var(--stl-typography-scale-sm);
+  color: var(--stl-color-foreground);
+}
 
-    .stldocs-snippet-response-pane {
-      .shiki,
-      .shiki span,
-      .astro-code,
-      .astro-code span {
-        background-color: var(--sl-color-bg-inline-code) !important;
-      }
-    }
+.shiki,
+.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'] {
-    /* 
+: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 {
-        background-color: var(--sl-color-bg-inline-code) !important;
-      }
-    }
+  .shiki,
+  .shiki span,
+  .astro-code,
+  .astro-code span {
+    color: var(--shiki-dark) !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;
   }
 }

package/styles/fonts.css

@@ -4,65 +4,80 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-latin.woff2) format('woff2-variations');
-  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url(../assets/fonts/geist/geist-latin.woff2) format('woff2-variations');
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
 @font-face {
   font-family: 'Geist';
   font-style: italic;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-italic-latin.woff2) format('woff2-variations');
-  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url(../assets/fonts/geist/geist-italic-latin.woff2) format('woff2-variations');
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
 @font-face {
   font-family: 'Geist';
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-latin-ext.woff2) format('woff2-variations');
-  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url(../assets/fonts/geist/geist-latin-ext.woff2) format('woff2-variations');
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
+    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
 @font-face {
   font-family: 'Geist';
   font-style: italic;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-italic-latin-ext.woff2) format('woff2-variations');
-  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url(../assets/fonts/geist/geist-italic-latin-ext.woff2) format('woff2-variations');
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
+    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
 
-
 /* Geist Mono */
 @font-face {
   font-family: 'Geist Mono';
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-mono-latin.woff2) format('woff2-variations');
-  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url(../assets/fonts/geist/geist-mono-latin.woff2) format('woff2-variations');
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
 @font-face {
   font-family: 'Geist Mono';
   font-style: italic;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-mono-italic-latin.woff2) format('woff2-variations');
-  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url(../assets/fonts/geist/geist-mono-italic-latin.woff2) format('woff2-variations');
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
 @font-face {
   font-family: 'Geist Mono';
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-mono-latin-ext.woff2) format('woff2-variations');
-  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url(../assets/fonts/geist/geist-mono-latin-ext.woff2) format('woff2-variations');
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
+    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
 @font-face {
   font-family: 'Geist Mono';
   font-style: italic;
   font-display: swap;
   font-weight: 100 900;
-  src: url(../plugin/assets/fonts/geist/geist-mono-italic-latin-ext.woff2) format('woff2-variations');
-  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url(../assets/fonts/geist/geist-mono-italic-latin-ext.woff2) format('woff2-variations');
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
+    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }

package/styles/links.css

@@ -1,51 +1,14 @@
-@layer stainless {
-  .sl-link-card {
-    box-shadow: none;
-    border-radius: var(--sl-button-border-radius);
-    padding: 1.5rem;
-    margin-top: 16px;
-  }
+/* TODO: remove for real card component */
 
-  .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);
-      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%;
-    }
-
-    > a[rel='next'] {
-      margin-left: auto;
-    }
+.sl-link-card {
+  box-shadow: none;
+  border-radius: var(--sl-button-border-radius);
+  padding: 1.5rem;
+  margin-top: 16px;
+}
 
-    > a[rel='prev'] {
-      margin-right: auto;
-    }
-  }
+.sl-link-card:hover {
+  transition: 0.3s;
+  border: 1px solid var(--sl-color-accent-high);
+  background-color: var(--sl-color-accent-low);
 }

package/styles/method-descriptions.css

@@ -0,0 +1,36 @@
+.stldocs-root {
+  .stl-method-description-overflow-wrapper {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    /* Minimum height to minimize layout shift */
+    min-height: 24px;
+  }
+  .stl-method-description {
+    .stldocs-method-description {
+      overflow: hidden;
+      max-height: 170px;
+      transition: max-height 0.3s ease;
+      position: relative;
+
+      &::after {
+        content: '';
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        height: 3rem;
+        background: linear-gradient(to bottom, transparent, var(--stl-color-background));
+        pointer-events: none;
+      }
+
+      &[data-collapsed='false'] {
+        max-height: none;
+      }
+
+      &[data-collapsed='false']::after {
+        display: none;
+      }
+    }
+  }
+}