@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.130

package/stl-docs/chat/ui/components/MessageFeedback.tsx

@@ -0,0 +1,109 @@
+import { CheckIcon, CopyIcon, ThumbsDownIcon, ThumbsUpIcon } from 'lucide-react';
+import { motion } from 'motion/react';
+import { startTransition, useCallback, useOptimistic, useState } from 'react';
+
+import type { AssistantTextMessage } from '../types';
+
+import { Button } from '@stainless-api/ui-primitives';
+import clsx from 'clsx';
+import styles from '../AiChat.module.css';
+
+export default function MessageFeedbackButtons({
+  spanId,
+  messages,
+  rateMessage,
+  onCopyMessage,
+}: {
+  spanId: string;
+  messages: AssistantTextMessage[];
+  rateMessage?: (spanId: string, rating: 'up' | 'down') => Promise<boolean>;
+  onCopyMessage?: (spanId: string) => void;
+}) {
+  // Copy response as markdown
+  const [copied, setCopied] = useState(false);
+  const handleCopy = useCallback(() => {
+    onCopyMessage?.(spanId);
+    const combinedText = messages.map((msg) => msg.content).join('\n\n');
+    navigator.clipboard
+      .writeText(combinedText)
+      .then(() => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      })
+      .catch(() => {
+        setCopied(false);
+      });
+  }, [messages, spanId, onCopyMessage]);
+
+  // Provide message rating
+  const [rating, setRating] = useState<'up' | 'down' | null>(null);
+  const [optimisticRating, setOptimisticRating] = useOptimistic(
+    rating,
+    (current, newRating: NonNullable<typeof rating>) => newRating,
+  );
+  const handleRate = useCallback(
+    (newRating: 'up' | 'down') => {
+      if (!rateMessage) {
+        return;
+      }
+
+      startTransition(async () => {
+        setOptimisticRating(newRating);
+        const success = await rateMessage(spanId, newRating).catch(() => false);
+        if (success) setRating(newRating);
+      });
+    },
+    [spanId, setOptimisticRating, rateMessage],
+  );
+
+  return (
+    <motion.li
+      layout="position"
+      data-message-role="assistant"
+      className={clsx(styles['chat-message'], styles['feedback-buttons'])}
+    >
+      {rateMessage != null && (
+        <>
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            onClick={() => handleRate('up')}
+            className={clsx(optimisticRating === 'up' && styles.active)}
+            aria-label="Thumbs up"
+          >
+            <Button.Icon icon={ThumbsUpIcon} size={15} />
+          </Button>
+
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            onClick={() => handleRate('down')}
+            className={clsx(optimisticRating === 'down' && styles.active)}
+            aria-label="Thumbs down"
+          >
+            <Button.Icon icon={ThumbsDownIcon} size={15} />
+          </Button>
+        </>
+      )}
+
+      {messages.length > 0 && messages.some((msg) => msg.content.trim().length) && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={handleCopy}
+          className={clsx(copied && styles.active)}
+          aria-label={copied ? 'Copied' : 'Copy response'}
+        >
+          <Button.Icon
+            // TODO: nicer cross-fade transition
+            icon={copied ? CheckIcon : CopyIcon}
+            size={15}
+          />
+        </Button>
+      )}
+    </motion.li>
+  );
+}

package/stl-docs/chat/ui/components/Table.tsx

@@ -0,0 +1,15 @@
+import clsx from 'clsx';
+import type { Components } from 'react-markdown';
+import styles from '../AiChat.module.css';
+
+export default {
+  table(props) {
+    const { children, ...rest } = props;
+
+    return (
+      <div className={clsx(styles['chat-table'])}>
+        <table {...rest}>{children}</table>
+      </div>
+    );
+  },
+} satisfies Components;

package/stl-docs/chat/ui/components/ToolCall.tsx

@@ -0,0 +1,34 @@
+import { motion } from 'motion/react';
+import z from 'zod';
+
+import type { AssistantToolCallMessage } from '../types';
+
+import clsx from 'clsx';
+import styles from '../AiChat.module.css';
+
+export default function ToolCall({
+  message,
+}: {
+  message: Pick<AssistantToolCallMessage, 'id' | 'toolName' | 'input'>;
+}) {
+  // Render docs searches
+  if (message.toolName.endsWith('search_docs')) {
+    const parsed = z.object({ query: z.string() }).safeParse(message.input);
+    if (parsed.success) {
+      return (
+        <motion.li
+          layout="position"
+          data-message-role="assistant"
+          className={clsx(styles['chat-message'], styles['tool-use'])}
+        >
+          <p>
+            Fetching docs for <em>{parsed.data.query}</em>
+          </p>
+        </motion.li>
+      );
+    }
+  }
+
+  // No other tool renderers yet
+  return null;
+}

package/stl-docs/chat/ui/components/hljs-github.css

@@ -0,0 +1,81 @@
+.hljs-github {
+  /* color: light-dark(#24292e, #c9d1d9); */
+  /* background: light-dark(#ffffff, #0d1117); */
+
+  .hljs-doctag,
+  .hljs-keyword,
+  .hljs-meta .hljs-keyword,
+  .hljs-template-tag,
+  .hljs-template-variable,
+  .hljs-type,
+  .hljs-variable.language_ {
+    color: light-dark(#d73a49, #ff7b72);
+  }
+
+  .hljs-title,
+  .hljs-title.class_,
+  .hljs-title.class_.inherited__,
+  .hljs-title.function_ {
+    color: light-dark(#6f42c1, #d2a8ff);
+  }
+
+  .hljs-attr,
+  .hljs-attribute,
+  .hljs-literal,
+  .hljs-meta,
+  .hljs-number,
+  .hljs-operator,
+  .hljs-variable,
+  .hljs-selector-attr,
+  .hljs-selector-class,
+  .hljs-selector-id {
+    color: light-dark(#005cc5, #79c0ff);
+  }
+
+  .hljs-regexp,
+  .hljs-string,
+  .hljs-meta .hljs-string {
+    color: light-dark(#032f62, #a5d6ff);
+  }
+
+  .hljs-built_in,
+  .hljs-symbol {
+    color: light-dark(#e36209, #ffa657);
+  }
+
+  .hljs-comment,
+  .hljs-code,
+  .hljs-formula {
+    color: light-dark(#6a737d, #8b949e);
+  }
+
+  .hljs-name,
+  .hljs-quote,
+  .hljs-selector-tag,
+  .hljs-selector-pseudo {
+    color: light-dark(#22863a, #7ee787);
+  }
+
+  .hljs-subst {
+    color: light-dark(#24292e, #c9d1d9);
+  }
+
+  .hljs-section {
+    color: light-dark(#005cc5, #1f6feb);
+    font-weight: bold;
+  }
+
+  .hljs-bullet {
+    color: light-dark(#735c0f, #f2cc60);
+  }
+
+  .hljs-emphasis {
+    color: light-dark(#24292e, #c9d1d9);
+    font-style: italic;
+  }
+
+  .hljs-strong {
+    color: light-dark(#24292e, #c9d1d9);
+    font-weight: bold;
+  }
+}

package/stl-docs/chat/ui/scroll-manager.ts

@@ -0,0 +1,86 @@
+import React, { useEffect } from 'react';
+
+const THRESHOLD_FROM_BOTTOM = 32; // px
+
+/** Keep chat area scrolled to bottom */
+export function useScrollToBottom(
+  scrollAreaRef: React.RefObject<HTMLDivElement | null>,
+  scrollContentsRef: React.RefObject<HTMLDivElement | null>,
+  watchValue: unknown,
+) {
+  /**
+   * Set `overflow` based on whether content is actually overflowing.
+   *   - The reason this behavior is different than `overflow: auto` is that `overflow: auto` would
+   *     show scrollbars while `motion` transitions are in flight applying scale correction to the
+   *     children (i.e. while the chat area is animating to accommodate increased child height).
+   *   - If we measure with `offsetHeight`/`clientHeight`, we only see the eventual “resting”
+   *     dimensions (unaffected by transforms) so we know better whether a scrollbar should actually
+   *     show, and avoid distracting flicker of scrollbars appearing & disappearing
+   */
+  useEffect(() => {
+    if (!scrollAreaRef.current || !scrollContentsRef.current) return;
+    const containerStyle = getComputedStyle(scrollAreaRef.current);
+    const scrollAreaHeight = scrollAreaRef.current.clientHeight;
+    const scrollContentsHeight = // scrollHeight is sometimes off; maybe because of scale correction?
+      scrollContentsRef.current.offsetHeight +
+      parseFloat(containerStyle.paddingTop) +
+      parseFloat(containerStyle.paddingBottom);
+    const canScroll = scrollContentsHeight > scrollAreaHeight + 1;
+    scrollAreaRef.current.style.overflowY = canScroll ? 'auto' : 'hidden';
+  }, [watchValue, scrollAreaRef, scrollContentsRef]);
+
+  /**
+   * Flip scroll direction based on user’s scroll position
+   *   - By default, we need to keep the container scrolled all the way to the end during streaming,
+   *     so that the user sees the new content that is appearing.
+   *   - However, if the user scrolls upwards to read previous content, we shouldn’t scroll them
+   *     back to the bottom while they’re trying to read content further up, even if more content is
+   *     streaming.
+   *
+   * The smoothest way to accomplish this interaction is to flip the container’s scroll direction
+   * using flex-direction:
+   *   - When the scroll position is near the bottom, scrolling should run in reverse direction—so
+   *     that at a constant `0` scrollTop, the scroll stays at the end (no js-driven scrolling with
+   *     distracting scrollbar flashing).
+   *   - When the user scrolls upwards by a certain threshold, we flip scroll direction to normal,
+   *     so that as scroll position holds constant, the still-streaming content below doesn’t push
+   *     up the content the user is trying to read.
+   *
+   * When changing the flex direction, the meaning of `scrollTop` changes dramatically, so we need
+   * to manually adjust `scrollTop` to keep the scroll position visually seamless.
+   */
+  useEffect(() => {
+    if (!scrollAreaRef.current) return;
+    const ac = new AbortController();
+    scrollAreaRef.current.addEventListener(
+      'scroll',
+      (e) => {
+        const scroller = e.currentTarget;
+        if (!(scroller instanceof HTMLElement)) return;
+        const appliedScrollDirection = scroller.classList.contains('scrolls-up') ? 'up' : 'down';
+        if (!appliedScrollDirection) return;
+        const { scrollHeight, clientHeight, scrollTop } = scroller;
+        // scrollTop is measured from the opposite edge depending on the appliedScrollDirection
+        // prettier-ignore
+        const distanceFromBottom = appliedScrollDirection === 'up'
+          ? -scrollTop
+          : scrollHeight - clientHeight - scrollTop;
+
+        // apply reverse scroll when the container is scrolled near the bottom, so that new content
+        // pushes old content up and the bottom edge stays constant.
+        if (appliedScrollDirection === 'down' && distanceFromBottom < THRESHOLD_FROM_BOTTOM) {
+          scroller.classList.add('scrolls-up');
+          scroller.scrollTop = -distanceFromBottom;
+        }
+        // flip to forward scroll when the user scrolls up from the bottom, so that new content
+        // doesn’t push up the content the user is trying to read.
+        if (appliedScrollDirection === 'up' && distanceFromBottom > THRESHOLD_FROM_BOTTOM) {
+          scroller.classList.remove('scrolls-up');
+          scroller.scrollTop = scrollHeight - clientHeight + scrollTop;
+        }
+      },
+      { capture: false, signal: ac.signal },
+    );
+    return () => ac.abort();
+  }, [scrollAreaRef]);
+}

package/stl-docs/chat/ui/types.ts

@@ -0,0 +1,45 @@
+// Base
+type BaseMessage = { id: string };
+type BaseTextMessage = BaseMessage & { content: string };
+// User
+export type UserMessage = BaseTextMessage & { role: 'user' };
+// Assistant
+export type AssistantTextMessage = BaseMessage & {
+  role: 'assistant';
+  respondingTo: string;
+  messageType: 'text';
+  content: string;
+  isComplete: boolean;
+};
+export type AssistantToolCallMessage = BaseMessage & {
+  role: 'assistant';
+  respondingTo: string;
+  messageType: 'tool_use';
+  toolName: string;
+  input: Record<string, unknown> | undefined;
+};
+export type AssistantDoneMessage = BaseMessage & {
+  role: 'assistant';
+  respondingTo: string;
+  messageType: 'done';
+  spanId: string;
+};
+export type AssistantErrorMessage = BaseMessage & {
+  role: 'assistant';
+  respondingTo: string;
+  messageType: 'error';
+  errorMessage: string;
+};
+
+export type ChatMessage =
+  | UserMessage
+  | AssistantTextMessage
+  | AssistantToolCallMessage
+  | AssistantDoneMessage
+  | AssistantErrorMessage;
+
+export type ExamplePrompt = {
+  longPrompt: string;
+  shortPrompt: string;
+  icon: React.ComponentType;
+};

package/stl-docs/components/AIDropdown.tsx

@@ -0,0 +1,63 @@
+import { DropdownButton } from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+import { ChatGPTIcon } from './icons/chat-gpt';
+import { ClaudeIcon } from './icons/claude';
+import { GeminiIcon } from './icons/gemini';
+import { MarkdownIcon } from './icons/markdown';
+import { CursorIcon } from './icons/cursor';
+import React from 'react';
+
+import { getAIDropdownOptions, type DropdownIcon } from '../../plugin/globalJs/ai-dropdown-options';
+
+const iconMap: { [key in DropdownIcon]: React.ReactNode } = {
+  markdown: <MarkdownIcon />,
+  copy: <CopyIcon size={16} />,
+  claude: <ClaudeIcon />,
+  chatgpt: <ChatGPTIcon />,
+  gemini: <GeminiIcon />,
+  cursor: <CursorIcon />,
+};
+
+const { primaryAction, groups } = getAIDropdownOptions();
+
+function ItemLabel({ label }: { label: string[] }) {
+  if (label.length > 1) {
+    return (
+      <DropdownButton.MenuItemText subtle>
+        {label[0]}
+        <strong>{label[1]}</strong>
+      </DropdownButton.MenuItemText>
+    );
+  }
+
+  return (
+    <DropdownButton.MenuItemText>
+      <strong>{label[0]}</strong>
+    </DropdownButton.MenuItemText>
+  );
+}
+
+export function AIDropdown() {
+  return (
+    <DropdownButton data-dropdown-id="ai-dropdown-button">
+      <DropdownButton.PrimaryAction>
+        {iconMap[primaryAction.icon]}
+        <DropdownButton.PrimaryActionText>{primaryAction.label}</DropdownButton.PrimaryActionText>
+      </DropdownButton.PrimaryAction>
+      <DropdownButton.Trigger />
+      <DropdownButton.Menu>
+        {groups.map((group) => (
+          <React.Fragment key={group.reactKey}>
+            {group.options.map((option) => (
+              <DropdownButton.MenuItem value={option.id} isExternalLink={option.external} key={option.id}>
+                <DropdownButton.Icon>{iconMap[option.icon]}</DropdownButton.Icon>
+                <ItemLabel label={option.label} />
+              </DropdownButton.MenuItem>
+            ))}
+            {group.isLast ? null : <hr />}
+          </React.Fragment>
+        ))}
+      </DropdownButton.Menu>
+    </DropdownButton>
+  );
+}

package/stl-docs/components/AiChatIsland.tsx

@@ -0,0 +1,16 @@
+// Conditionally load DocsChat only if it is enabled
+// this way the virtual module imports aren’t evaluated and don’t cause errors when the feature is disabled
+
+// This conditional can’t be inlined into PageFrame because it breaks Astro’s static analysis of imports of client islands
+const AiChat = __STLDOCS_ENABLE_AI_CHAT__ ? (await import('../chat/ui/AiChat')).default : null;
+
+const STAINLESS_PROJECT = __STLDOCS_HAS_API_REFERENCE__
+  ? (await import('virtual:stl-starlight-virtual-module')).STAINLESS_PROJECT
+  : undefined;
+
+export default function DocsChatLazy(
+  props: Omit<React.ComponentProps<NonNullable<typeof AiChat>>, 'stainlessProject'>,
+) {
+  if (!AiChat || !STAINLESS_PROJECT) return null;
+  return <AiChat {...props} stainlessProject={STAINLESS_PROJECT} />;
+}

package/stl-docs/components/{content-panel/ContentBreadcrumbs.tsx → ContentBreadcrumbs.tsx}

@@ -1,6 +1,6 @@
 import { ChevronRight } from 'lucide-react';
-import { Join } from '@stainless-api/docs-ui/src/components';
-import style from '@stainless-api/docs-ui/src/style';
+import { Join } from '@stainless-api/docs-ui/components';
+import style from '@stainless-api/docs-ui/style';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 type Breadcrumb = { title: string; href: string };

package/stl-docs/components/ContentPanel.astro

@@ -0,0 +1,9 @@
+<div class="stl-ui-prose stl-content-panel">
+  <slot />
+</div>
+
+<style>
+  .stl-content-panel + .stl-content-panel {
+    margin-top: 24px;
+  }
+</style>

package/stl-docs/components/Footer.astro

@@ -0,0 +1,89 @@
+---
+import EditLink from 'virtual:starlight/components/EditLink';
+import LastUpdated from 'virtual:starlight/components/LastUpdated';
+import Pagination from 'virtual:starlight/components/Pagination';
+import { RENDER_CREDITS } from 'virtual:stl-docs-virtual-module';
+import StainlessLogo from './StainlessLogo.svg';
+---
+
+<footer class="stl-footer">
+  <div class="stl-footer-row meta">
+    <EditLink />
+    <LastUpdated />
+  </div>
+
+  <Pagination />
+
+  {
+    RENDER_CREDITS && (
+      <div class="stl-footer-row">
+        <a
+          class="stl-footer-credits"
+          href="https://www.stainless.com/products/docs"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Powered by <StainlessLogo />
+        </a>
+      </div>
+    )
+  }
+</footer>
+
+<style is:global>
+  .stl-footer {
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+    margin-block-start: 4rem;
+    padding-block-start: 1rem;
+    padding-block-end: 4rem;
+
+    .stl-footer-row {
+      display: flex;
+      gap: 1rem;
+      justify-content: space-between;
+
+      &:empty,
+      &:not(:has(> *)) {
+        display: none;
+      }
+    }
+
+    .pagination-links {
+      margin-inline: calc(-0.25 * var(--stl-ui-pagination-border-radius-outer));
+    }
+  }
+
+  .stl-footer-credits {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    text-decoration: none;
+    margin-inline-start: auto;
+    margin-block-start: 1rem;
+    font-size: var(--stl-typography-scale-sm);
+
+    /* duck text opacity by more than image opacity */
+    opacity: 0.75;
+    color: rgb(from var(--stl-color-foreground-reduced) r g b / calc(alpha * 0.9));
+    transition:
+      opacity 0.15s ease,
+      color 0.15s ease;
+    /* both text & image to full opacity */
+    &:hover {
+      opacity: 1;
+      color: var(--stl-color-foreground-reduced);
+    }
+
+    svg {
+      height: 1.4em;
+      width: auto;
+      display: inline-block;
+      margin-inline-start: 0.5ch;
+      image {
+        transform: translateX(0.15ch);
+      }
+    }
+  }
+</style>

package/stl-docs/components/Head.astro

@@ -0,0 +1,20 @@
+---
+import { Font } from 'astro:assets';
+import { FONTS } from 'virtual:stl-docs-virtual-module';
+import Default from '@astrojs/starlight/components/Head.astro';
+import path from 'path';
+
+const mdPath = path.posix.join(Astro.url.pathname, 'index.md');
+const fonts = [FONTS.primary, FONTS.heading, FONTS.mono, ...(FONTS.additional ?? [])].filter(Boolean);
+---
+
+<Default />
+
+{fonts.map((font) => <Font cssVariable={font.cssVariable} preload={font.preload} />)}
+
+<link rel="alternate" type="text/markdown" href={mdPath} />
+
+<script>
+  import { wireAIDropdown } from '../../plugin/globalJs/ai-dropdown-options.ts';
+  wireAIDropdown();
+</script>

package/stl-docs/components/Header.astro

@@ -23,14 +23,6 @@ const shouldRenderSearch = !!(
 
 <style is:global>
   @layer starlight.core {
-    header {
-      border-color: var(--sl-color-hairline);
-
-      &.header {
-        border-bottom-color: var(--sl-color-hairline);
-      }
-    }
-
     .header {
       display: flex;
       gap: var(--sl-nav-gap);
@@ -46,6 +38,8 @@ const shouldRenderSearch = !!(
       padding: 0.25rem;
       margin: -0.25rem;
       min-width: 0;
+      /* Max height should match button height */
+      max-height: 32px;
     }
 
     .default-tabs-container {
@@ -83,7 +77,7 @@ const shouldRenderSearch = !!(
 
     @media (min-width: 50rem) {
       .default-tabs-container {
-        min-width: 440px;
+        min-width: 540px;
       }
     }
   }

package/stl-docs/components/PageFrame.astro

@@ -0,0 +1,37 @@
+---
+import Sidebar from 'virtual:starlight/components/Sidebar';
+import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
+
+import AiChatIsland from './AiChatIsland.tsx'; // entrypoint for client island can’t be conditionally import()ed
+import clsx from 'clsx';
+
+import starlightConfig from 'virtual:starlight/user-config';
+const locale = Astro.currentLocale ?? starlightConfig.defaultLocale.lang;
+const siteTitle = locale && starlightConfig.title[locale];
+
+const { hasSidebar } = Astro.locals.starlightRoute;
+---
+
+<div class="page">
+  <header>
+    <slot name="header" slot="header" />
+  </header>
+
+  <nav
+    class={clsx('sidebar', !hasSidebar && 'hidden')}
+    aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}
+  >
+    <MobileMenuToggle />
+    <div id="starlight__sidebar" class="sidebar-pane">
+      <Sidebar />
+    </div>
+  </nav>
+
+  <slot />
+
+  {
+    __STLDOCS_ENABLE_AI_CHAT__ && (
+      <AiChatIsland client:load currentLanguage={Astro.locals.language} siteTitle={siteTitle} />
+    )
+  }
+</div>

package/stl-docs/components/PageSidebar.astro

@@ -0,0 +1,11 @@
+---
+import TableOfContents from 'virtual:starlight/components/TableOfContents';
+---
+
+{
+  Astro.locals.starlightRoute.toc && (
+    <div class="right-sidebar-panel">
+      <TableOfContents />
+    </div>
+  )
+}