@stainless-api/docs 0.1.0-beta.99 → 1.0.0-beta.141

package/stl-docs/chat/ui/AiChat.tsx

@@ -0,0 +1,175 @@
+import { motion } from 'motion/react';
+import { Suspense, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { useScrollToBottom } from './scroll-manager';
+import { useChat } from '../hook';
+import type { DocsChatHandler } from '../docs-chat-handler';
+
+import ChatLog from './components/ChatLog';
+import AiChatTrigger from './Trigger';
+import ChatEmpty from './components/ChatEmpty';
+import ChatControls from './components/ChatControls';
+import { AI_CHAT_HANDLER } from 'virtual:stl-docs-ai-chat';
+
+import styles from './AiChat.module.css';
+import clsx from 'clsx';
+
+const borderRadius = 16;
+
+/** Remembers user preference but returns 'floating' if panel is not supported */
+function usePresentation(supportsPanel: boolean) {
+  const [presentation, setPresentation] = useState<'floating' | 'panel'>('floating');
+  const appliedPresentation = supportsPanel ? presentation : 'floating';
+  return [appliedPresentation, setPresentation] as const;
+}
+
+const examplesPromise = import('virtual:stl-docs-ai-chat-examples')
+  .then((mod) => mod.examples)
+  .catch(() => undefined);
+
+export default function AiChat({ siteTitle }: { siteTitle?: string }) {
+  if (!AI_CHAT_HANDLER) {
+    return null;
+  }
+  return <AiChatInner siteTitle={siteTitle} handler={AI_CHAT_HANDLER} />;
+}
+
+function AiChatInner({ siteTitle, handler }: { siteTitle?: string; handler: DocsChatHandler }) {
+  const { chatMessages, sendMessage, rateMessage } = useChat({
+    handler,
+  });
+
+  // panel mode is supported only on larger viewports
+  const supportsPanel = useSyncExternalStore(
+    (cb) => {
+      window.addEventListener('resize', cb);
+      return () => window.removeEventListener('resize', cb);
+    },
+    () => window.innerWidth >= 968,
+    () => false,
+  );
+
+  const baseRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const [focused, setFocused] = useState(false);
+
+  const [presentation, setPresentation] = usePresentation(supportsPanel);
+  const expanded = focused || presentation === 'panel';
+
+  // Manage “focus” state
+  // prettier-ignore
+  useEffect(() => {
+    const ac = new AbortController();
+    // “focus” in/out with click
+    window.addEventListener('click', (e) => {
+      if (!(e.target instanceof Element) || !baseRef.current || !document.contains(e.target)) return;
+      // clicks on elements with this attribute shouldn’t change focus state
+      // e.g. clicking minimize button shouldn’t cause the chat to _become_ focused
+      if (e.target.closest('[data-ai-chat-hit-ignore]')) return;
+      const hit = baseRef.current.contains(e.target);
+      setFocused(hit);
+    }, { signal: ac.signal });
+    // leave with escape
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') {
+        setFocused(false);
+        setPresentation('floating');
+        inputRef.current?.blur(); // this is the one case where the input won’t have already lost focus
+      }
+    }, { signal: ac.signal });
+
+    // record focus state when our chat elements receive focus
+    // unfocus when another element outside of our component gets focus (incl. by keyboard)
+    document.addEventListener('focusin', (e) => {
+      if (!(e.target instanceof Element) || !baseRef.current || !document.contains(e.target)) return;
+      setFocused(baseRef.current.contains(e.target));
+    }, { signal: ac.signal });
+    return () => ac.abort();
+  }, [setPresentation]);
+
+  const [pendingResponses, setPendingResponses] = useState(0);
+  const handleSendMessage = useCallback(
+    (q: string) => {
+      setPendingResponses((p) => p + 1);
+      sendMessage(q)
+        .catch(() => {})
+        .finally(() => {
+          setPendingResponses((p) => p - 1);
+        });
+    },
+    [sendMessage],
+  );
+
+  // scroll to bottom when new messages come in
+  const scrollAreaRef = useRef<HTMLDivElement>(null);
+  const scrollContentsRef = useRef<HTMLDivElement>(null);
+  useScrollToBottom(
+    scrollAreaRef,
+    scrollContentsRef,
+    // deps to re-run scroll
+    useMemo(() => [chatMessages, presentation], [chatMessages, presentation]),
+  );
+
+  return (
+    <div className={clsx(styles['outer-wrapper'], styles[`presentation-${presentation}`])} ref={baseRef}>
+      <AiChatTrigger
+        expanded={expanded}
+        updateFocused={setFocused}
+        sendMessage={handleSendMessage}
+        inputRef={inputRef}
+        borderRadius={borderRadius}
+      />
+
+      <motion.div
+        layout
+        className={styles['chat-area-container']}
+        variants={{
+          floating: { borderRadius: borderRadius + 1, '--shadow-color': 'var(--base-shadow-color)' },
+          panel: { borderRadius: 0, '--shadow-color': 'transparent' },
+        }}
+        animate={presentation}
+        style={{
+          display: expanded ? 'flex' : 'none',
+          boxShadow: '0 8px 20px -8px var(--shadow-color)',
+        }}
+      >
+        <motion.div
+          layout
+          className={clsx(styles['chat-area'], 'scrolls-up')}
+          variants={{ floating: { borderRadius }, panel: { borderRadius: 0 } }}
+          animate={presentation}
+          ref={scrollAreaRef}
+        >
+          <div className={styles['chat-scroll-contents']} ref={scrollContentsRef}>
+            <ChatControls
+              presentation={presentation}
+              setPresentation={(p) => {
+                setPresentation(p);
+                inputRef.current?.focus();
+              }}
+              supportsPanel={supportsPanel}
+              setClosed={() => {
+                setFocused(false);
+                setPresentation('floating');
+              }}
+            />
+            {chatMessages.length > 0 ? (
+              <ChatLog
+                messages={chatMessages}
+                rateMessage={rateMessage}
+                responsePending={pendingResponses > 0}
+              />
+            ) : (
+              <Suspense fallback={null}>
+                <ChatEmpty
+                  siteTitle={siteTitle}
+                  promptExamples={examplesPromise}
+                  sendMessage={handleSendMessage}
+                />
+              </Suspense>
+            )}
+          </div>
+        </motion.div>
+      </motion.div>
+    </div>
+  );
+}

package/stl-docs/chat/ui/Trigger.tsx

@@ -0,0 +1,154 @@
+// TODO: move to components
+import React, { useState } from 'react';
+import { ArrowUpIcon, BotMessageSquareIcon } from 'lucide-react';
+import clsx from 'clsx';
+import { Transition } from 'motion';
+import styles from './AiChat.module.css';
+import { motion } from 'motion/react';
+
+const MotionBotIcon = motion.create(BotMessageSquareIcon);
+
+export default function AiChatTrigger({
+  expanded,
+  updateFocused,
+  sendMessage,
+  inputRef,
+  borderRadius,
+}: {
+  expanded: boolean;
+  updateFocused: (focused: boolean) => void;
+  sendMessage: (question: string) => void;
+  inputRef: React.RefObject<HTMLTextAreaElement | null>;
+  borderRadius: number;
+}) {
+  const [empty, setEmpty] = useState(true);
+  const [resetKey, setResetKey] = useState(0);
+
+  const layoutTransition = {
+    type: 'spring',
+    mass: 0.7,
+    stiffness: 275,
+    damping: 20,
+  } satisfies Transition;
+
+  const crossBlurTransition = {
+    delay: expanded ? 0.07 : 0,
+    duration: 0.1,
+    ease: 'easeInOut',
+  } satisfies Transition;
+
+  const [willChange, setWillChange] = useState(false);
+  const willChangeStyle = willChange ? { willChange: 'transform' as const } : {};
+
+  return (
+    <form
+      style={{ display: 'contents' }}
+      action={(formData) => {
+        const question = formData.get('question');
+        if (typeof question === 'string' && question.trim().length) {
+          sendMessage(question);
+          setResetKey((k) => k + 1);
+          setEmpty(true);
+        }
+      }}
+    >
+      <motion.label
+        layout
+        transition={layoutTransition}
+        className={styles['trigger-outer']}
+        style={{
+          borderRadius: borderRadius + 1,
+          boxShadow: '0 4px 12px -4px var(--shadow-color)',
+          ...willChangeStyle,
+        }}
+        // set will-change when hovering the collapsed trigger
+        onMouseEnter={() => {
+          setWillChange(!expanded);
+        }}
+        onMouseLeave={() => setWillChange(false)}
+      >
+        <motion.div
+          layout
+          transition={layoutTransition}
+          className={clsx(styles.trigger, expanded && styles.expanded)}
+          style={{ borderRadius: borderRadius, '--border-radius': `${borderRadius}px`, ...willChangeStyle }}
+        >
+          {/* Bot icon is visible while closed */}
+          <MotionBotIcon
+            layout
+            className={styles['bot-icon']}
+            animate={{
+              opacity: expanded ? 0 : 1,
+              scale: expanded ? 0.75 : 1,
+              filter: expanded ? 'blur(4px)' : 'blur(0px)',
+            }}
+            style={willChange ? { willChange: 'filter, transform' } : {}}
+            transition={crossBlurTransition}
+            aria-label="AI chat"
+          />
+
+          {/* Input & send button are visible while open */}
+          <motion.div
+            layout
+            className={styles['expanded-contents']}
+            initial={{ opacity: 0 }}
+            animate={{
+              opacity: expanded ? 1 : 0,
+              filter: expanded ? 'blur(0px)' : 'blur(4px)',
+            }}
+            style={willChange ? { willChange: 'filter, transform' } : {}}
+            transition={crossBlurTransition}
+          >
+            <motion.textarea
+              layout
+              transition={layoutTransition}
+              name="question"
+              style={willChangeStyle}
+              rows={1}
+              placeholder="Ask a question"
+              // Keep track of whether the question is submittable
+              onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => {
+                setEmpty(e.target.value.trim().length === 0);
+              }}
+              // Submit on Cmd+Enter
+              onKeyDown={(e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+                if (e.key === 'Enter' && !e.shiftKey) {
+                  e.preventDefault();
+                  e.currentTarget.form?.requestSubmit();
+                }
+              }}
+              // Update textarea height to fit content as user types
+              ref={(el: HTMLTextAreaElement | null) => {
+                inputRef.current = el;
+                if (!el) return;
+                const updateSize = () => {
+                  el.style.height = 'auto';
+                  el.style.height = `${el.scrollHeight}px`;
+                };
+                const ac = new AbortController();
+                el.addEventListener('input', updateSize, { signal: ac.signal });
+                updateSize();
+                // in case the user focused it before we mounted
+                if (document.activeElement === el) updateFocused(true);
+                // Re-focus after remount (e.g., after form submission resets the key)
+                if (expanded) el.focus();
+                return () => ac.abort();
+              }}
+              // make the ref re-mount so we get a fresh height measurement after reset
+              key={resetKey}
+            />
+            <motion.button
+              layout
+              type="submit"
+              disabled={empty}
+              transition={layoutTransition}
+              style={willChangeStyle}
+            >
+              <ArrowUpIcon aria-label="Send" />
+            </motion.button>
+          </motion.div>
+        </motion.div>
+      </motion.label>
+    </form>
+  );
+}

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

@@ -0,0 +1,51 @@
+import type { Dispatch, SetStateAction } from 'react';
+import { motion } from 'motion/react';
+
+import { Button } from '@stainless-api/ui-primitives';
+import { PictureInPictureIcon, PanelRightCloseIcon as PanelRightIcon, MinusIcon } from 'lucide-react';
+
+import styles from '../AiChat.module.css';
+
+export default function ChatControls({
+  presentation,
+  setPresentation,
+  supportsPanel,
+  setClosed,
+}: {
+  presentation: 'floating' | 'panel';
+  setPresentation: Dispatch<SetStateAction<'floating' | 'panel'>>;
+  supportsPanel: boolean;
+  setClosed: (e: React.MouseEvent<HTMLElement>) => void;
+}) {
+  return (
+    <motion.div layout className={styles['controls']}>
+      {supportsPanel && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          aria-label={{ panel: 'Switch to floating chat', floating: 'Switch to panel chat' }[presentation]}
+          onClick={() => {
+            setPresentation(presentation === 'floating' ? 'panel' : 'floating');
+          }}
+        >
+          <Button.Icon
+            icon={{ panel: PictureInPictureIcon, floating: PanelRightIcon }[presentation]}
+            size={15}
+          />
+        </Button>
+      )}
+
+      <Button
+        type="button"
+        variant="ghost"
+        size="sm"
+        aria-label="Close chat"
+        onClick={setClosed}
+        data-ai-chat-hit-ignore
+      >
+        <Button.Icon icon={MinusIcon} size={15} />
+      </Button>
+    </motion.div>
+  );
+}

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

@@ -0,0 +1,42 @@
+import { use } from 'react';
+import { motion } from 'motion/react';
+import { BotMessageSquareIcon as BotIcon } from 'lucide-react';
+import type { ExamplePrompt } from '../types';
+import styles from '../AiChat.module.css';
+
+export default function ChatEmpty({
+  siteTitle,
+  promptExamples: promptExamplesPromise,
+  sendMessage,
+}: {
+  siteTitle?: string;
+  promptExamples?: Promise<ExamplePrompt[] | undefined>;
+  sendMessage: (question: string) => void;
+}) {
+  const promptExamples = promptExamplesPromise && use(promptExamplesPromise);
+
+  return (
+    <motion.div layout className={styles['chat-empty-state']}>
+      <BotIcon />
+      <h2>What can I help you with?</h2>
+
+      {promptExamples?.length ? (
+        <>
+          <h3>Suggestions</h3>
+          <ul>
+            {promptExamples.map(({ shortPrompt, longPrompt, icon: Icon }) => (
+              <li key={shortPrompt} className={styles['chat-example']}>
+                <button type="button" onClick={() => sendMessage(longPrompt)}>
+                  <Icon />
+                  {shortPrompt}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </>
+      ) : (
+        <p>I can help answer questions about {siteTitle ?? 'this API'}. What do you want to build?</p>
+      )}
+    </motion.div>
+  );
+}

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

@@ -0,0 +1,93 @@
+import type { ChatMessage } from '../types';
+import Message from './ChatMessage';
+import MessageFeedbackButtons from './MessageFeedback';
+import ToolCall from './ToolCall';
+
+import { motion } from 'motion/react';
+
+import styles from '../AiChat.module.css';
+import { LoaderCircleIcon } from 'lucide-react';
+
+export default function ChatLog({
+  messages,
+  rateMessage,
+  responsePending = false,
+}: {
+  messages: ChatMessage[];
+  rateMessage?: (spanId: string, rating: 'up' | 'down') => Promise<boolean>;
+  responsePending?: boolean;
+}) {
+  const lastMessage = messages.at(-1);
+
+  return (
+    <motion.ul
+      layout
+      role="log"
+      aria-live="polite"
+      className={styles['message-log']}
+      initial={{ opacity: 0, filter: `blur(4px)` }}
+      animate={{ opacity: 1, filter: `blur(0px)` }}
+    >
+      {messages.map((msg) => {
+        if (msg.role === 'user') {
+          return (
+            <Message key={msg.id} role="user">
+              {msg.content}
+            </Message>
+          );
+        }
+
+        if (msg.role === 'assistant' && msg.messageType === 'text') {
+          return (
+            <Message key={msg.id} role={msg.role} isMarkdown isStreaming={!msg.isComplete}>
+              {msg.content}
+            </Message>
+          );
+        }
+
+        if (msg.role === 'assistant' && msg.messageType === 'tool_use') {
+          return <ToolCall key={msg.id} message={msg} />;
+        }
+
+        if (msg.role === 'assistant' && msg.messageType === 'done') {
+          return (
+            <MessageFeedbackButtons
+              key={msg.id}
+              spanId={msg.spanId}
+              rateMessage={rateMessage}
+              // all "text" responses to the given message
+              messages={messages.flatMap((msg2) =>
+                msg2.role === 'assistant' &&
+                msg2.respondingTo === msg.respondingTo &&
+                msg2.messageType === 'text'
+                  ? msg2
+                  : [],
+              )}
+            />
+          );
+        }
+
+        if (msg.role === 'assistant' && msg.messageType === 'error') {
+          return (
+            <Message key={msg.id} role="error">
+              {msg.errorMessage}
+            </Message>
+          );
+        }
+
+        return null;
+      })}
+
+      {lastMessage?.role === 'user' && responsePending && (
+        <Message key={`${lastMessage.id}-response`} role="assistant">
+          {'Thinking'.split('').map((char, i) => (
+            <span key={i} className={styles['shimmer-letter']} style={{ '--i': i }}>
+              {char}
+            </span>
+          ))}
+          <LoaderCircleIcon className={styles['message-loader']} />
+        </Message>
+      )}
+    </motion.ul>
+  );
+}

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

@@ -0,0 +1,47 @@
+import remend from 'remend';
+import Markdown from 'react-markdown';
+import { motion } from 'motion/react';
+
+import highlightCodeComponent from './CodeBlock';
+import tableComponent from './Table';
+
+import clsx from 'clsx';
+import styles from '../AiChat.module.css';
+import remarkGfm from 'remark-gfm';
+
+export default function ChatMessage({
+  children,
+  role,
+  isStreaming = false,
+  isMarkdown = false,
+}: {
+  children: React.ReactNode;
+  role: 'user' | 'assistant' | 'error';
+  isStreaming?: boolean;
+  isMarkdown?: boolean;
+}) {
+  return (
+    <motion.li
+      layout="position"
+      data-message-role={role}
+      className={clsx(styles['chat-message'], 'stl-ui-prose', 'smaller-headings')}
+      style={{ borderRadius: 16 }}
+    >
+      {/* inner div provides scale correction while outer container transforms */}
+      {isMarkdown && typeof children === 'string' ? (
+        <Markdown
+          remarkPlugins={[remarkGfm]}
+          components={{
+            ...highlightCodeComponent,
+            ...tableComponent,
+          }}
+        >
+          {/* repair incomplete markdown syntax during streaming to ensure proper rendering */}
+          {isStreaming ? remend(children) : children}
+        </Markdown>
+      ) : (
+        <p>{children}</p>
+      )}
+    </motion.li>
+  );
+}

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

@@ -0,0 +1,33 @@
+import { Fragment } from 'react';
+
+import { LightAsync as SyntaxHighlighter } from 'react-syntax-highlighter';
+
+import type { Components } from 'react-markdown';
+import clsx from 'clsx';
+import './hljs-github.css';
+
+function NoPropsFragment({ children }: { children: React.ReactNode }) {
+  return <Fragment>{children}</Fragment>;
+}
+
+export default {
+  code(props) {
+    const { children, className, ref, style, ...rest } = props;
+    const match = /language-(\w+)/.exec(className || '');
+    return match && typeof children === 'string' ? (
+      <SyntaxHighlighter
+        {...rest}
+        PreTag={NoPropsFragment}
+        language={match[1]}
+        useInlineStyles
+        codeTagProps={{ className: clsx(className, 'hljs-github') }}
+      >
+        {children.replace(/\n$/, '')}
+      </SyntaxHighlighter>
+    ) : (
+      <code {...rest} className={className}>
+        {children}
+      </code>
+    );
+  },
+} satisfies Components;