@stainless-api/docs 0.1.0-beta.129 → 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/AiChatIsland.tsx

@@ -1,14 +1,16 @@
-import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
-import AiChat, { STAINLESS_PROJECT } from 'virtual:stl-docs/components/AiChat.tsx';
+// 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
 
-export default function AiChatIsland({
-  currentLanguage,
-  siteTitle,
-}: {
-  currentLanguage: DocsLanguage | undefined;
-  siteTitle: string | undefined;
-}) {
-  if (!AiChat) throw new Error('AiChatIsland was rendered but could not load AiChat component');
-  if (!STAINLESS_PROJECT) return null;
-  return <AiChat projectId={STAINLESS_PROJECT} language={currentLanguage} siteTitle={siteTitle} />;
+// 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/PageFrame.astro

@@ -2,15 +2,14 @@
 import Sidebar from 'virtual:starlight/components/Sidebar';
 import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
 
-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
+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;
-import clsx from 'clsx';
 ---
 
 <div class="page">
@@ -30,5 +29,9 @@ import clsx from 'clsx';
 
   <slot />
 
-  {!!AiChat && <AiChatIsland client:load currentLanguage={Astro.locals.language} siteTitle={siteTitle} />}
+  {
+    __STLDOCS_ENABLE_AI_CHAT__ && (
+      <AiChatIsland client:load currentLanguage={Astro.locals.language} siteTitle={siteTitle} />
+    )
+  }
 </div>

package/stl-docs/components/headers/DefaultHeader.astro

@@ -7,9 +7,9 @@ import NavLinks from '../nav-tabs/NavTabs.astro';
 import { TABS } from 'virtual:stl-docs-virtual-module';
 import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 
-interface Props {
+type Props = {
   shouldRenderSearch?: boolean;
-}
+};
 
 const { shouldRenderSearch } = Astro.props;
 ---

package/stl-docs/components/headers/StackedHeader.astro

@@ -6,9 +6,9 @@ import HeaderLinks from './HeaderLinks.astro';
 import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 import SecondaryNavTabs from '../nav-tabs/SecondaryNavTabs.astro';
 
-interface Props {
+type Props = {
   shouldRenderSearch?: boolean;
-}
+};
 
 const { shouldRenderSearch } = Astro.props;
 ---

package/stl-docs/components/mintlify-compat/Accordion.astro

@@ -1,8 +1,8 @@
 ---
-export interface Props {
+type Props = {
   title: string;
   children: astroHTML.JSX.Children;
-}
+};
 
 const { title } = Astro.props;
 

package/stl-docs/components/mintlify-compat/AccordionGroup.astro

@@ -1,9 +1,5 @@
 ---
 import { Accordion as StainlessAccordion } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <StainlessAccordion.Group>

package/stl-docs/components/mintlify-compat/Columns.astro

@@ -1,9 +1,9 @@
 ---
 import clsx from 'clsx';
 
-export interface Props {
+type Props = {
   cols: number;
-}
+};
 
 const { cols } = Astro.props;
 ---

package/stl-docs/components/mintlify-compat/Frame.astro

@@ -1,7 +1,7 @@
 ---
-export interface Props {
+type Props = {
   caption?: string;
-}
+};
 
 const { caption } = Astro.props;
 ---

package/stl-docs/components/mintlify-compat/Tab.astro

@@ -1,9 +1,9 @@
 ---
 import { TabItem } from '@astrojs/starlight/components';
 
-export interface Props {
+type Props = {
   title: string;
-}
+};
 
 const { title } = Astro.props;
 ---

package/stl-docs/components/mintlify-compat/callouts/Callout.astro

@@ -1,10 +1,10 @@
 ---
 import { Callout as StainlessCallout, type CalloutVariant } from '@stainless-api/ui-primitives';
 
-export interface Props {
+type Props = {
   variant?: CalloutVariant;
   children: astroHTML.JSX.Children;
-}
+};
 
 const { variant } = Astro.props;
 ---

package/stl-docs/components/mintlify-compat/callouts/Check.astro

@@ -1,9 +1,5 @@
 ---
 import { Callout } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <Callout variant="success">

package/stl-docs/components/mintlify-compat/callouts/Danger.astro

@@ -1,9 +1,5 @@
 ---
 import { Callout } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <Callout variant="danger">

package/stl-docs/components/mintlify-compat/callouts/Info.astro

@@ -1,9 +1,5 @@
 ---
 import { Callout } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <Callout variant="info">

package/stl-docs/components/mintlify-compat/callouts/Note.astro

@@ -1,9 +1,5 @@
 ---
 import { Callout } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <Callout variant="note">

package/stl-docs/components/mintlify-compat/callouts/Tip.astro

@@ -1,9 +1,5 @@
 ---
 import { Callout } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <Callout variant="tip">

package/stl-docs/components/mintlify-compat/callouts/Warning.astro

@@ -1,9 +1,5 @@
 ---
 import { Callout } from '@stainless-api/ui-primitives';
-
-export interface Props {
-  children: astroHTML.JSX.Children;
-}
 ---
 
 <Callout variant="warning">

package/stl-docs/components/nav-tabs/NavDropdown.astro

@@ -4,7 +4,7 @@ import { Dropdown } from '@stainless-api/docs/components';
 
 import type { NavLink } from './buildNavLinks';
 
-export type Props = {
+type Props = {
   links: NavLink[];
   currentItem: NavLink | null;
 };

package/stl-docs/components/pagination/PaginationLinkEmphasized.astro

@@ -1,10 +1,10 @@
 ---
 import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
 const { href, direction } = Astro.props;
-export interface Props {
+type Props = {
   href: string;
   direction: 'prev' | 'next';
-}
+};
 ---
 
 <a href={href} class="pagination-links__link pagination-links__link--emphasized">

package/stl-docs/components/pagination/PaginationLinkQuiet.astro

@@ -1,8 +1,8 @@
 ---
 const { href } = Astro.props;
-export interface Props {
+type Props = {
   href: string;
-}
+};
 ---
 
 <a href={href} class="pagination-links__link pagination-links__button pagination-links__link--quiet">

package/stl-docs/components/pagination/util.ts

@@ -2,10 +2,10 @@ import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import { getCollection } from 'astro:content';
 
 export type SidebarEntry = StarlightRouteData['sidebar'][number];
-export type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
-export type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
+type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
+type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
 
-export const flattenSidebar = (sidebar: SidebarEntry[]): SidebarLink[] =>
+const flattenSidebar = (sidebar: SidebarEntry[]): SidebarLink[] =>
   sidebar.flatMap((e) => (e.type === 'group' ? flattenSidebar(e.entries) : e));
 
 function findParentOfSidebarEntry(sidebar: SidebarEntry[], targetEntry: SidebarEntry): SidebarGroup | null {

package/stl-docs/disableCalloutSyntax.ts

@@ -1,7 +1,7 @@
 import type { AstroIntegration } from 'astro';
 import type { StarlightPlugin } from '@astrojs/starlight/types';
 
-export const disableCalloutSyntaxAstroIntegration = {
+const disableCalloutSyntaxAstroIntegration = {
   name: 'stl-starlight-remove-callout-syntax',
   hooks: {
     'astro:config:setup': ({ config: astroConfig }) => {