@stainless-api/docs 0.1.0-beta.98 → 1.0.0-beta.140

package/styles/page.css

@@ -1,69 +1,159 @@
-.page,
-.page > header .header,
-.page > header .stl-secondary-nav-tabs {
-  max-width: var(--sl-page-max-width);
-  margin: 0 auto;
+:root {
+  --stl-page-max-width: 90rem;
 
-  @media (min-width: 50rem) {
-    padding-inline: var(--stl-ui-page-padding-inline);
+  /* 0.75rem at 25rem width (phone); 1.5rem at 72rem width (desktop) */
+  --_stl-page-min-padding-mobile-rem: 0.75;
+  --_stl-page-min-padding-desktop-rem: 1.5;
+  --_stl-page-min-padding-slope: (
+    (var(--_stl-page-min-padding-desktop-rem) - var(--_stl-page-min-padding-mobile-rem)) / (72 - 25)
+  );
+  --stl-page-min-padding: clamp(
+    var(--_stl-page-min-padding-mobile-rem) * 1rem,
+    var(--_stl-page-min-padding-slope) * (100vw - 25rem) + var(--_stl-page-min-padding-mobile-rem) * 1rem,
+    var(--_stl-page-min-padding-desktop-rem) * 1rem
+  );
+
+  --stl-content-max-width: 52rem;
+  --stl-content-padding: 2rem;
+  --stl-two-column-content-max-width: 80rem;
+
+  --stl-sidebar-width: 16.5rem;
+  --stl-nav-height: 3.5rem; /* has to be statically sized in order to correctly position the viewport-end grid area :( */
+  --stl-nav-gap: 0.5rem;
+
+  --stl-page-width: min(var(--stl-page-max-width), 100vw);
+  --vw: calc(var(--stl-page-width) / 100);
+
+  scroll-padding-top: calc(var(--stl-nav-height) + 1rem);
+}
+@media (min-width: 50rem) {
+  :root:has(.stl-secondary-nav-tabs) {
+    --stl-nav-height: 5.5rem;
+    header {
+      padding-top: 0.25rem;
+    }
   }
 }
 
+/* Grid layout */
+
 .page {
-  position: relative;
-  max-width: var(--sl-page-max-width);
+  display: grid;
 
-  .right-sidebar {
-    border-inline-start: unset;
-  }
+  /* TODO: verify that env-safe-area-inset is behaving as we expect */
+  --stl-viewport-width: calc(
+    100vw - env(safe-area-inset-left, 0px) - env(safe-area-inset-right, 0px) -
+      var(--stl-chat-panel-width, 0px)
+  );
+  --stl-page-gutter-left: calc(
+    env(safe-area-inset-left, 0px) +
+      max(var(--stl-page-min-padding), (var(--stl-viewport-width) - var(--stl-page-max-width)) / 2)
+  );
+  --stl-page-gutter-right: calc(
+    env(safe-area-inset-right, 0px) +
+      max(var(--stl-page-min-padding), (var(--stl-viewport-width) - var(--stl-page-max-width)) / 2)
+  );
 
-  .mobile-preferences {
-    margin-top: 1rem;
-    display: flex;
-    justify-content: flex-end;
-  }
+  /* prettier-ignore */
+  grid:
+    /*  header + content have two identical columns because in mobile layout the menu trigger takes up the latter */
+    ' gutter-left                  header                   header          header   header  gutter-right                  chat' var(--stl-nav-height)                 /* nav */
+    ' gutter-left                  sidebar                  content         content  toc     gutter-right                  chat' calc(100dvh - var(--stl-nav-height))  /* viewport (above the fold) */
+    [viewport-end]
+    ' gutter-left                  .                        content         content  .       gutter-right                  .   ' auto                                  /* rest of page height */
+    / var(--stl-page-gutter-left)  var(--stl-sidebar-width) minmax(0, 1fr)  auto     auto    var(--stl-page-gutter-right)  auto;
 }
 
-:root {
-  --sl-mobile-toc-height: 4rem;
+.page > main,
+.page > .sidebar > .sidebar-pane,
+.page > .right-sidebar-panel nav {
+  padding-block-start: 1rem;
 }
 
-@media (min-width: 50rem) {
-  .page .sidebar-pane {
-    left: unset;
-  }
-  /* on desktop, adjust sidebar so that its _text content_ aligns with the page left edge.
-   * padding (visible on hover) bleeds out beyond the page left edge, covered by --stl-ui-page-padding-inline */
-  .sidebar-pane {
-    /* 12px comes from --stl-sidebar-item-padding-inline (which is unfortunately defined deeper than
-    this component). Please keep in sync. */
-    margin-inline-start: calc(-1 * (var(--sl-sidebar-pad-x) + 12px));
-  }
+/* Sticky header and tabs */
 
-  .header,
-  .header {
-    padding-inline-start: 0;
-    padding-inline-end: 0;
-  }
+.page > header {
+  grid-area: header;
+  margin-left: calc(-1 * var(--stl-page-gutter-left));
+  margin-right: calc(-1 * var(--stl-page-gutter-right));
+  padding-left: var(--stl-page-gutter-left);
+  padding-right: var(--stl-page-gutter-right);
+}
 
-  mobile-starlight-toc nav {
-    inset-inline-start: calc(var(--sl-content-inline-start, 0) + var(--sl-sidebar-pad-x));
-  }
+header {
+  display: flex;
+  flex-direction: column;
+  border-bottom: 1px solid var(--stl-color-border-faint);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: var(--stl-color-background);
 }
 
-.stl-content-breadcrumbs {
-  .stldocs-breadcrumbs {
-    padding-left: 0;
+@layer starlight.core {
+  header > .header {
+    all: revert-layer;
   }
 }
 
-.stl-page-nav-container {
+header > .header {
+  flex: 1;
   display: flex;
+  gap: var(--stl-nav-gap);
   align-items: center;
   justify-content: space-between;
-  gap: 1rem;
-  padding: 1rem 0 0 0;
-  flex-wrap: wrap;
+}
+
+.header site-search > button {
+  @media (min-width: 50rem) {
+    margin-inline: 2rem;
+    flex: 1 1 12rem;
+  }
+}
+
+.header .right-group {
+  display: flex;
+  align-items: stretch;
+}
+
+/* Sticky sidebar and toc. Outer wrapper “sticks” to top of page, subgrid pushes child down below header */
+.page > .sidebar {
+  grid-area: sidebar;
+  /* sidebar should bleed to left edge of page in case people want to color it */
+  margin-left: calc(-1 * var(--stl-page-gutter-left));
+  padding-left: var(--stl-page-gutter-left);
+}
+
+.page > .right-sidebar-panel {
+  grid-area: toc;
+}
+
+.page > .sidebar,
+.page > .right-sidebar-panel {
+  align-self: start;
+  grid-row-start: header-start;
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+  position: sticky;
+  top: 0;
+}
+.page > .sidebar > .sidebar-pane,
+.page > .right-sidebar-panel > starlight-toc {
+  grid-area: inherit;
+  grid-row-start: header-end;
+  overflow-y: auto;
+  overflow-x: clip;
+}
+
+/* Page content */
+
+.page > main {
+  grid-area: content;
+  width: 100%;
+  max-width: min(var(--stl-content-max-width), 100%);
+  justify-self: center;
+  padding-inline: var(--stl-content-padding);
 }
 
 .stl-page-nav-container {
@@ -71,47 +161,96 @@
   align-items: center;
   justify-content: space-between;
   gap: 1rem;
-  padding: 1rem 0 0 0;
   flex-wrap: wrap;
 }
 
-.stldocs-root .stl-page-nav-container {
-  padding: 1rem 0 0 var(--stldocs-content-padding);
+.mobile-preferences {
+  margin-top: 1rem;
+  display: flex;
+  justify-content: flex-end;
 }
 
-[data-has-sidebar]:not([data-has-toc]) .sl-container {
-  max-width: 1428px;
+/* Two-column layouts go wider */
+.page > main:where(:has(.stldocs-method-double-pane)) {
+  max-width: min(var(--stl-two-column-content-max-width), 100%);
+  padding-inline-start: clamp(
+    var(--stl-content-padding),
+    var(--stl-page-gutter-right) - env(safe-area-inset-right, 0px),
+    var(--stl-content-padding) * 2
+  );
+  padding-inline-end: 0;
 }
 
-.stl-overview {
-  max-width: var(--sl-content-width);
-}
+/* Responsive page layout */
 
-@media (min-width: 50rem) {
-  :root[data-has-sidebar] {
-    --sl-content-inline-start: calc(var(--sl-sidebar-width) + 2rem);
+/* On smaller screens, the main panel takes up the full width and the TOC is hidden */
+@media not (min-width: 72rem) {
+  .page > main {
+    /* right edge of content goes up to right gutter to align with header */
+    padding-inline-end: 0;
+    max-width: 100%;
   }
 
-  .stldocs-root .stl-page-nav-container {
-    padding: 1rem 0 0 0;
+  .page > .right-sidebar-panel {
+    display: none;
   }
 }
 
-@media (min-width: 72rem) {
+/* On mobile screens, the sidebar and nav links collapse */
+@media not (min-width: 50rem) {
+  header {
+    padding-top: 0;
+    display: grid;
+    grid-template-columns: subgrid;
+  }
+
+  header > .header {
+    grid-column: span 2;
+  }
+
+  /* Sidebar moves to cover content area, hidden by default */
   :root {
-    --sl-mobile-toc-height: 0rem;
+    --stl-sidebar-width: 0px;
+  }
+  .page > .sidebar,
+  .page > .sidebar.hidden {
+    display: contents;
+  }
+  .page > .sidebar > .sidebar-pane {
+    visibility: hidden;
+    grid-area: content;
+    grid-row-end: viewport-end;
+    z-index: 9;
+    /* extend to right edge of page */
+    margin-inline-end: calc(-1 * var(--stl-page-gutter-right));
+    padding-inline-end: var(--stl-page-gutter-right);
+    border-inline-end: 0;
+  }
+  .page > .sidebar > starlight-menu-button[aria-expanded='true'] ~ .sidebar-pane {
+    visibility: visible;
   }
-}
 
-.content-panel footer {
-  /* Don’t render empty footer meta, which results in extra margin getting applied on behalf of the flex gap.
-   * Instead, move its margin to its parent. */
-  margin-top: 3rem;
-  .meta {
-    margin-top: 0;
-    &:empty,
-    &:not(:has(> *)) {
-      display: none;
-    }
+  /* left padding becomes the left gutter when there’s no sidebar */
+  .page > main {
+    padding-inline-start: 0;
+  }
+
+  /* Sidebar menu button moves to end of header; takes up space in layout (not absolutely positioned as in starlight) */
+  .sidebar starlight-menu-button {
+    grid-column: span 1 / content-end;
+    grid-row: header;
+    display: flex;
+    align-items: center;
+    position: sticky;
+    top: 0;
+    padding-left: var(--stl-nav-gap);
+    z-index: 11;
+  }
+  .sidebar starlight-menu-button button {
+    position: static;
+  }
+
+  .header .right-group {
+    display: none;
   }
 }

package/styles/sidebar.css

@@ -1,23 +1,27 @@
-/* reset starlight styles */
-@layer starlight.core {
-  .sidebar .sidebar-pane .sidebar-content {
-    * {
-      all: revert-layer;
-      &::before,
-      &::after {
-        all: revert-layer;
-      }
-    }
-  }
-}
-
-.sidebar-pane {
+.page > .sidebar > .sidebar-pane {
+  padding-inline-end: 1rem;
   border-inline-end: 1px solid var(--stl-color-border-faint);
+  padding-block-end: calc(2rem + env(safe-area-inset-bottom));
+
+  /* make sure the sidebar doesn’t get clipped on the left by overflow */
+  margin-inline-start: calc(-1 * var(--stl-page-gutter-left));
+  padding-inline-start: var(--stl-page-gutter-left);
+
+  background-color: var(--stl-color-background);
+  /* work around chrome bug where the background-color isn’t getting painted in the overscroll? */
+  background-image: linear-gradient(to bottom, var(--stl-color-background), var(--stl-color-background));
+  background-attachment: fixed;
+
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
 }
 
-.sidebar-content .stl-mobile-only-sidebar-item-last {
-  margin-bottom: 2rem;
-  position: relative;
+@media (min-width: 50rem) {
+  .page > .sidebar :is(.stl-sdk-select, .stldocs-sidebar) {
+    /* align left edge of text with container */
+    margin-inline-start: calc(-1 * var(--stldocs-sidebar-item-padding-inline));
+  }
 }
 
 .stl-sidebar-header-links {
@@ -36,3 +40,12 @@
     display: none;
   }
 }
+
+/* No sidebar on splash pages */
+.page > .sidebar.hidden {
+  /* Note: on mobile, this will be overridden to display: contents; in order to show the mobile menu */
+  display: none;
+}
+:root:has(.page > .sidebar.hidden) {
+  --stl-sidebar-width: 0px;
+}

package/styles/sl-variables.css

@@ -1,19 +1,14 @@
 :root {
   --sl-color-bg-table-row: #ffffff0a;
   --sl-button-border-radius: 8px;
-  --sl-content-width: 52rem;
-  --sl-nav-pad-y: 0.5rem;
-  --sl-nav-height: 56px;
-  --sl-sidebar-width: 19rem;
   --sl-button-size: 32px;
   --sl-button-padding-x: 0.75rem;
   --sl-button-padding-y: 0.5rem;
   --sl-button-icon-offset: 0.2rem;
-  --sl-menu-button-size: var(--sl-button-size);
+
+  /* TODO: remove --sl-nav-height dependencies */
+  --sl-nav-height: 56px;
 
   --sl-nav-gap: 0.5rem;
   --sl-icon-color: var(--stl-color-foreground);
-  --sl-page-max-width: unset;
-
-  --sl-content-pad-x: 1rem;
 }

package/styles/stldocs-variables.css

@@ -1,6 +1,6 @@
 @import '@stainless-api/docs-ui/styles/variables.css';
 
 :root {
-  --stldocs-content-width: var(--sl-content-width);
-  --stldocs-content-padding: var(--sl-content-pad-x);
+  --stldocs-content-width: var(--stl-content-max-width);
+  --stldocs-content-padding-inline: 0;
 }

package/styles/toc.css

@@ -1,5 +1,11 @@
 .right-sidebar-panel {
   font-size: var(--stl-typography-scale-sm);
+  overflow-wrap: break-word;
+
+  nav {
+    width: calc(16 * var(--vw));
+    min-width: 14ch;
+  }
 
   nav > ul {
     padding-top: 0;
@@ -17,6 +23,7 @@
     color: var(--stl-color-foreground-reduced);
     position: relative;
     font-size: inherit;
+    text-decoration: none;
 
     &:hover {
       text-decoration: underline;
@@ -45,5 +52,6 @@
     line-height: 150%;
     text-decoration: none;
     font-weight: 400;
+    margin-bottom: 0.5em;
   }
 }

package/tsconfig.json

@@ -7,7 +7,7 @@
     ".stl-docs/**/*",
     "./plugin/**/*"
   ],
-  "exclude": ["dist", "**/preview.worker.docs.js"],
+  "exclude": ["dist"],
   "compilerOptions": {
     "jsx": "react-jsx",
     "jsxImportSource": "react"

package/virtual-module.d.ts

@@ -15,12 +15,14 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const CONTENT_PANEL_LAYOUT: 'double-pane' | 'single-pane';
   export const EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: boolean | undefined;
   export const EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS: boolean | undefined;
-  export const EXPERIMENTAL_PLAYGROUNDS: boolean | undefined;
   export const EXPERIMENTAL_REQUEST_BUILDER: boolean | undefined;
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const CONTEXT_MENU_ENABLE_THIRD_PARTY: boolean;
   export const STAINLESS_PROJECT: string | undefined;
+  export const LLMS_TXT_DESCRIPTION: string | null;
+  export const LLMS_TXT_DETAIL_THRESHOLD: number;
 }
 
 declare module 'virtual:stl-docs-virtual-module' {
@@ -52,25 +54,27 @@ declare module 'virtual:stl-docs-virtual-module' {
   export const API_REFERENCE_BASE_PATH: string;
   export const ENABLE_PROSE_MARKDOWN_RENDERING: boolean;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const CONTEXT_MENU_ENABLE_THIRD_PARTY: boolean;
   export const RENDER_PAGE_DESCRIPTIONS: boolean;
+  export const LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: boolean;
   export const FONTS: {
     primary?: FontConfig;
     heading?: FontConfig;
     mono?: FontConfig;
     additional?: FontConfig[];
   };
+  export const RENDER_CREDITS: boolean;
+  export const SITE_TITLE: string;
 }
 
-declare module 'virtual:stl-docs/components/AiChat.tsx' {
-  const AiChatComponent:
-    | import('react').ComponentType<{
-        projectId: string;
-        language: import('@stainless-api/docs-ui/routing').DocsLanguage | undefined;
-        siteTitle: string | undefined;
-      }>
-    | null;
-  export default AiChatComponent;
-  export const STAINLESS_PROJECT: string | undefined;
+declare module 'virtual:stl-docs-ai-chat' {
+  export const AI_CHAT_HANDLER: import('./stl-docs/chat/docs-chat-handler').DocsChatHandler | undefined;
+}
+
+declare module 'virtual:stl-docs-ai-chat-examples' {
+  import type { ExamplePrompt } from './stl-docs/chat/ui/types';
+
+  export const examples: ExamplePrompt[] | undefined;
 }
 
 declare module 'virtual:stainless-apis-manifest' {
@@ -98,3 +102,23 @@ declare module 'virtual:stl-starlight-reference-sidebars' {
 
   export const sidebars: GeneratedSidebarDef[];
 }
+
+declare module 'virtual:stainless-docs/docs-og-image' {
+  import type { StarlightUserConfig } from '@astrojs/starlight/types';
+
+  export const LOGO: StarlightUserConfig['logo'];
+  export const OG_IMAGE_OPTIONS: import('./stl-docs/og-image/config').OGImageConfig | undefined;
+}
+
+declare module 'virtual:stainless-docs/docs-og-image/components/OpenGraphImage' {
+  const OpenGraphImage: typeof import('./stl-docs/og-image/components/OpenGraphImage').default;
+  export default OpenGraphImage;
+}
+
+declare module 'virtual:stainless-docs/docs-og-image/components/OpenGraphFunctionSignature' {
+  const OpenGraphFunctionSignature: typeof import('./stl-docs/og-image/components/OpenGraphFunctionSignature').default;
+  export default OpenGraphFunctionSignature;
+}
+
+declare const __STLDOCS_HAS_API_REFERENCE__: boolean;
+declare const __STLDOCS_ENABLE_AI_CHAT__: boolean;

package/playground-virtual-modules.d.ts

@@ -1,96 +0,0 @@
-declare module 'virtual:stl-playground/typescript.json' {
-  const data: {
-    links: [string, string][];
-    files: [string, string][];
-  } | null;
-  export { data as default };
-}
-declare module 'virtual:stl-playground/python.json' {
-  const data: { files: Record<string, string>; wheel: string } | null;
-  export { data as default };
-}
-declare module 'virtual:stl-playground/auth.json' {
-  const data:
-    | ({
-        type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
-        description?: string;
-        name: string;
-        title: string;
-        header: string | undefined;
-        example: string | undefined;
-      } & {
-        opts: {
-          name: string;
-          type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
-          nullable: boolean;
-          description?: string | undefined;
-          example?: unknown;
-          default?: unknown;
-          read_env?: string | undefined;
-          auth?:
-            | {
-                security_scheme: string;
-                role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
-              }
-            | undefined;
-        }[];
-      })[]
-    | null;
-  export { data as default };
-}
-declare module 'virtual:stl-playground/data' {
-  import type { Config } from 'virtual:stl-playground/create';
-  declare const data: Config;
-  export { data as default };
-}
-declare module 'virtual:stl-playground/create' {
-  export type PlaygroundLanguage = 'python' | 'typescript' | 'http';
-  export type Config = {
-    wheelUrl: string;
-    pyTypes: {
-      files: Record<string, string>;
-      wheel: string;
-    } | null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    HIGHLIGHT_THEMES: any;
-    tsTypes: {
-      links: [string, string][];
-      files: [string, string][];
-    } | null;
-    authData:
-      | ({
-          type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
-          description?: string;
-          name: string;
-          title: string;
-          header: string | undefined;
-          example: string | undefined;
-        } & {
-          opts: {
-            name: string;
-            type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
-            nullable: boolean;
-            description?: string | undefined;
-            example?: unknown;
-            default?: unknown;
-            read_env?: string | undefined;
-            auth?:
-              | {
-                  security_scheme: string;
-                  role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
-                }
-              | undefined;
-          }[];
-        })[]
-      | null;
-  };
-  export function createPlayground(
-    props: {
-      lang: PlaygroundLanguage;
-      doc: string;
-      /** div.stl-snippet-request-container */
-      container: HTMLElement;
-      onLanguageSelect: (value: string) => void;
-    } & Config,
-  ): () => Promise<void>;
-}

package/plugin/globalJs/create-playground.shim.ts

@@ -1,3 +0,0 @@
-export function createPlayground(): () => Promise<void> {
-  return () => Promise.resolve();
-}

package/plugin/globalJs/playground-data.shim.ts

@@ -1 +0,0 @@
-export default {};

package/plugin/globalJs/playground-data.ts

@@ -1,14 +0,0 @@
-import wheelUrl from 'virtual:stl-playground/python/wheel.whl?url';
-import pyTypes from 'virtual:stl-playground/python.json';
-import tsTypes from 'virtual:stl-playground/typescript.json';
-import authData from 'virtual:stl-playground/auth.json';
-import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
-import { Config } from 'virtual:stl-playground/create';
-
-export default {
-  wheelUrl,
-  pyTypes,
-  tsTypes,
-  authData,
-  HIGHLIGHT_THEMES,
-} satisfies Config;