Merge pull request #21 from speakeasy-api/chase/improvements

feat: support operationId selection out of the box

Author: chase-crumbaugh

.gitignore

@@ -20,3 +20,6 @@
 /__tests__
 /.speakeasy/reports
 /react.*
+.idea
+pnpm-lock.yaml
+*.iml

src/react-components/code-sample.state.tsx

@@ -43,21 +43,31 @@ type Action =
   | { type: "FETCH_INIT" }
   | { type: "FETCH_SUCCESS"; payload: FetchSuccessPayload }
   | { type: "FETCH_FAILURE"; payload: Error }
-  | { type: "SET_LANGUAGE"; payload: string };
+  | { type: "SELECT"; payload: SafeGetSnippetParams };
 
-function safeGetSnippetForLanguage(
+type SafeGetSnippetParams = {
+  methodPath?: string | undefined;
+  language?: string | undefined;
+};
+
+function safeGetSnippet(
   snippets: SpeakeasyHighlightedCode[],
-  language?: string,
+  { methodPath, language }: SafeGetSnippetParams,
 ): SpeakeasyHighlightedCode {
-  if (!language) return snippets[0]!;
+  const maybeEqual = (a: string, b: string | undefined) =>
+    b === undefined || a.toLowerCase() === b.toLowerCase();
 
-  const selectedSnippet = snippets.find((s) => s.lang === language);
+  const selectedSnippet = snippets.find(
+    (s) =>
+      maybeEqual(getMethodPath(s.raw), methodPath) &&
+      maybeEqual(s.lang, language),
+  );
   if (selectedSnippet) {
     return selectedSnippet;
   }
 
   console.warn(
-    `Could not find snippet for language "${language}".`,
+    `Could not find snippet for method and path "${methodPath}".`,
     `Falling back to to first language in snippet array.`,
   );
 
@@ -75,24 +85,20 @@ const reducer: React.Reducer<CodeSampleState, Action> = (
       return {
         status: "success",
         snippets: action.payload.snippets,
-        selectedSnippet: safeGetSnippetForLanguage(
-          action.payload.snippets,
-          action.payload.defaultLanguage,
-        ),
+        selectedSnippet: safeGetSnippet(action.payload.snippets, {
+          language: action.payload.defaultLanguage,
+        }),
       };
     case "FETCH_FAILURE":
       return {
         ...state,
         status: "error",
         error: action.payload,
       };
-    case "SET_LANGUAGE":
+    case "SELECT":
       return {
         ...state,
-        selectedSnippet: safeGetSnippetForLanguage(
-          state.snippets!,
-          action.payload,
-        ),
+        selectedSnippet: safeGetSnippet(state.snippets!, action.payload),
       };
     default:
       return state;
@@ -148,13 +154,23 @@ export const useCodeSampleState = ({
     handleMount();
   }, []);
 
-  function setSelectedLanguage(language: string) {
-    dispatch({ type: "SET_LANGUAGE", payload: language });
+  function selectSnippet(params: SafeGetSnippetParams) {
+    dispatch({
+      type: "SELECT",
+      payload: {
+        language: state.selectedSnippet?.raw.language,
+        methodPath: getMethodPath(state.selectedSnippet?.raw),
+        ...params,
+      },
+    });
   }
 
-  return { state, setSelectedLanguage };
+  return { state, selectSnippet };
 };
 
+export const getMethodPath = (snippet: UsageSnippet | undefined): string =>
+  snippet ? `${snippet.method.toUpperCase()} ${snippet.path}` : "";
+
 /** Intended to give the user the option of providing their own client. */
 export const useSafeSpeakeasyCodeSamplesContext = (
   coreClient?: SpeakeasyCodeSamplesCore,

src/react-components/code-sample.styles.ts

@@ -14,9 +14,23 @@ const classes = {
     display: "flex",
     justifyContent: "space-between",
     borderBottom: `1px solid var(${cssVarKey.border})`,
-    padding: "0.5rem",
+    padding: "0.5rem 1rem",
+  }),
+  selector: css({
+    padding: "0.5rem 0.25rem 0.5rem 0.5rem", // Less padding on the right side to account for the arrow
+    borderRadius: "0.25rem",
+    backgroundColor: `var(${cssVarKey.bgPrimary})`,
+    fontSize: "0.875rem",
+    border: `1px solid var(${cssVarKey.border})`,
+    cursor: "pointer",
+    transition: "all 0.2s ease",
+    "&:hover": {
+      backgroundColor: `var(${cssVarKey.bgMuted})`,
+    },
+    "&::-webkit-select-arrow": {
+      color: `red`, // For WebKit browsers
+    },
   }),
-  selector: css({}),
   codeContainer: css({
     position: "relative",
     paddingInline: "0.75rem",

src/react-components/code-sample.tsx

@@ -1,26 +1,34 @@
-import { LazyMotion, domMax } from "motion/react";
-import React from "react";
+import { domMax, LazyMotion } from "motion/react";
+import React, { useEffect, useMemo } from "react";
 import { SpeakeasyCodeSamplesCore } from "../core.js";
 import {
   GetCodeSamplesRequest,
   MethodPaths,
 } from "../models/operations/getcodesamples.js";
 import { OperationId } from "../types/custom.js";
-import { useCodeSampleState } from "./code-sample.state.js";
+import { getMethodPath, useCodeSampleState } from "./code-sample.state.js";
 import classes from "./code-sample.styles.js";
 import { CodeViewer, ErrorDisplay } from "./code-viewer.js";
 import codehikeTheme from "./codehike/theme.js";
 import { CopyButton } from "./copy-button.js";
-import { LanguageSelector } from "./language-selector.js";
 import { LanguageSelectorSkeleton, LoadingSkeleton } from "./skeleton.js";
 import { getCssVars, useSystemColorMode } from "./styles.js";
-import { type CodeSampleTitleComponent, CodeSampleTitle } from "./titles.js";
+import {
+  CodeSampleFilenameTitle,
+  CodeSampleTitle,
+  type CodeSampleTitleComponent,
+} from "./titles.js";
+import { prettyLanguageName } from "./utils.js";
+import { Selector } from "./selector";
+import { UsageSnippet } from "../models/components";
 
 export type CodeSamplesViewerProps = {
   /** Whether the code snippet should be copyable. */
   copyable?: boolean;
-  /** Default language to show in the code playground. */
-  defaultLang?: string;
+
+  /** Default language to show in the code playground. If not found in the snippets, the first one will be used. */
+  defaultLanguage?: string;
+
   /**
    * The color mode for the code playground. If "system", the component will
    * detect the system color scheme automagically.
@@ -32,50 +40,106 @@ export type CodeSamplesViewerProps = {
    * A component to render as the snippet title in the upper-right corner of
    * the component. Receives data about the selected code sample. The library
    * comes pre-packaged with some sensible options.
+   * If set to false, no title bar will be shown.
    *
-   * @see CodeSampleMethodTitle
+   * @see CodeSampleTitle
    * @see CodeSampleFilenameTitle
    * @default CodeSampleMethodTitle
    */
-  title?: CodeSampleTitleComponent | React.ReactNode | string;
-  /** The operation to get a code sample for. Can be queried by either
-   * operationId or method+path.
+  title?: CodeSampleTitleComponent | React.ReactNode | string | false;
+  /**
+   * The operations to get code samples for. If only one is provided, no selector will be shown.
+   * Can be queried by either operationId or method+path.
    */
-  operation: MethodPaths | OperationId;
+  operations?: MethodPaths[] | OperationId[];
   /**
    * Optional client. Use this if the component is being used outside of
    * SpeakeasyCodeSamplesContext.
    */
   client?: SpeakeasyCodeSamplesCore;
+  /**
+   * Sets the style of the code window.
+   */
+  codeWindowStyle?: React.CSSProperties;
+  /**
+   * If true, the code window will be fixed to the height of the longest code snippet.
+   * This can be useful for preventing layout shifts when switching between code snippets.
+   * Overrides any height set in codeWindowStyle.
+   */
+  fixedHeight?: boolean;
+
   className?: string | undefined;
   style?: React.CSSProperties;
 };
 
 export function CodeSamplesViewer({
   theme = "system",
-  className,
-  title,
-  operation,
-  style,
+  title = CodeSampleFilenameTitle,
+  defaultLanguage,
+  operations,
   copyable,
   client: clientProp,
+  style,
+  codeWindowStyle,
+  fixedHeight,
+  className,
 }: CodeSamplesViewerProps) {
-  const request: GetCodeSamplesRequest = React.useMemo(() => {
-    if (typeof operation === "string") return { operationIds: [operation] };
-    return { methoPaths: [operation] };
-  }, [operation]);
+  const requestParams: GetCodeSamplesRequest = React.useMemo(() => {
+    if (typeof operations?.[0] === "string")
+      return { operationIds: operations as OperationId[] };
+    else if (operations?.[0]?.method && operations[0].path)
+      return { methodPaths: operations as MethodPaths[] };
 
-  const { state, setSelectedLanguage } = useCodeSampleState({
+    return {};
+  }, [operations]);
+
+  const { state, selectSnippet } = useCodeSampleState({
     client: clientProp,
-    requestParams: request,
+    requestParams,
   });
 
+  // On mount, select the defaults
+  useEffect(() => {
+    if (!state.snippets || state.status !== "success") return;
+    selectSnippet({ language: defaultLanguage });
+  }, [state.status]);
+
   const systemColorMode = useSystemColorMode();
   const codeTheme = React.useMemo(() => {
     if (theme === "system") return codehikeTheme[systemColorMode];
     return codehikeTheme[theme];
   }, [theme, systemColorMode]);
 
+  const languages: string[] = useMemo(() => {
+    return [
+      ...new Set(
+        state.snippets?.map(({ raw }) => prettyLanguageName(raw.language)),
+      ),
+    ];
+  }, [state.snippets]);
+
+  const getOperationKey = (snippet: UsageSnippet | undefined): string => {
+    let { operationId } = snippet;
+    const methodPathDisplay = getMethodPath(snippet);
+    if (!operationId) {
+      operationId = methodPathDisplay;
+    }
+    return operationId;
+  };
+
+  // We need this methodAndPath stuff because not all snippets will have operation ids
+  // For the selector, we try to show operation ID but fall back on method+path if it's missing
+  const operationIdToMethodAndPath: Record<string, string> = useMemo(() => {
+    return Object.fromEntries(
+      state.snippets?.map(({ raw }) => [
+        getOperationKey(raw),
+        getMethodPath(raw),
+      ]) ?? [],
+    );
+  }, [state.snippets]);
+
+  const operationIds = Object.keys(operationIdToMethodAndPath);
+
   const longestCodeHeight = React.useMemo(() => {
     const largestLines = Math.max(
       ...Object.values(state.snippets ?? [])
@@ -88,6 +152,13 @@ export function CodeSamplesViewer({
     return largestLines * lineHeight + padding * 2;
   }, [state.snippets]);
 
+  if (fixedHeight) {
+    codeWindowStyle = {
+      ...codeWindowStyle,
+      height: longestCodeHeight,
+    };
+  }
+
   return (
     <LazyMotion strict features={domMax}>
       <div
@@ -100,24 +171,44 @@ export function CodeSamplesViewer({
         }}
         className={`${classes.root} ${className ?? ""}`}
       >
-        <div className={classes.heading}>
-          <CodeSampleTitle
-            component={title}
-            status={state.status}
-            data={state.selectedSnippet?.raw}
-          />
-          <>
-            {state.status === "loading" && <LanguageSelectorSkeleton />}
-            {state.status === "success" && (
-              <LanguageSelector
-                value={state.selectedSnippet?.lang}
-                onChange={setSelectedLanguage}
-                snippets={state.snippets ?? []}
-                className={classes.selector}
-              />
-            )}
-          </>
-        </div>
+        {title !== false && (
+          <div className={classes.heading}>
+            <CodeSampleTitle
+              component={title}
+              status={state.status}
+              data={state.selectedSnippet?.raw}
+            />
+            <div style={{ display: "flex", gap: "0.75rem" }}>
+              {state.status === "loading" && (
+                <div style={{ width: "180px" }}>
+                  <LanguageSelectorSkeleton />
+                </div>
+              )}
+              {state.status === "success" && operationIds.length > 1 && (
+                <Selector
+                  value={getOperationKey(state.selectedSnippet?.raw)}
+                  values={operationIds}
+                  onChange={(operationId: string) =>
+                    selectSnippet({
+                      methodPath: operationIdToMethodAndPath[operationId],
+                    })
+                  }
+                  className={classes.selector}
+                />
+              )}
+              {state.status === "success" && (
+                <Selector
+                  value={prettyLanguageName(
+                    state.selectedSnippet?.raw.language,
+                  )}
+                  values={languages}
+                  onChange={(language: string) => selectSnippet({ language })}
+                  className={classes.selector}
+                />
+              )}
+            </div>
+          </div>
+        )}
         <div className={classes.codeContainer}>
           {state.status === "success" && copyable && (
             <CopyButton code={state.selectedSnippet.code} />
@@ -128,7 +219,7 @@ export function CodeSamplesViewer({
             <CodeViewer
               status={state.status}
               code={state.selectedSnippet}
-              longestCodeHeight={longestCodeHeight}
+              style={codeWindowStyle}
             />
           )}
         </div>