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

@@ -1,11 +1,11 @@
-import { HighlightedCode } from "codehike/code";
+import {HighlightedCode} from "codehike/code";
 import React from "react";
-import { SpeakeasyCodeSamplesCore } from "../core.js";
-import { codeSamplesGet } from "../funcs/codeSamplesGet.js";
-import { UsageSnippet } from "../models/components/usagesnippet.js";
-import { GetCodeSamplesRequest } from "../models/operations/getcodesamples.js";
-import { useSpeakeasyCodeSamplesContext } from "../react-query/_context.js";
-import { highlightCode } from "./utils.js";
+import {SpeakeasyCodeSamplesCore} from "../core.js";
+import {codeSamplesGet} from "../funcs/codeSamplesGet.js";
+import {UsageSnippet} from "../models/components/usagesnippet.js";
+import {GetCodeSamplesRequest} from "../models/operations/getcodesamples.js";
+import {useSpeakeasyCodeSamplesContext} from "../react-query/_context.js";
+import {highlightCode} from "./utils.js";
 
 export type SpeakeasyHighlightedCode = HighlightedCode & {
   /** The snippet data from the code samples api */
@@ -15,23 +15,23 @@ export type SpeakeasyHighlightedCode = HighlightedCode & {
 // Define the state shape.
 export type CodeSampleState =
   | {
-      status: "loading";
-      error?: Error | undefined;
-      snippets?: SpeakeasyHighlightedCode[] | undefined;
-      selectedSnippet?: SpeakeasyHighlightedCode | undefined;
-    }
+  status: "loading";
+  error?: Error | undefined;
+  snippets?: SpeakeasyHighlightedCode[] | undefined;
+  selectedSnippet?: SpeakeasyHighlightedCode | undefined;
+}
   | {
-      status: "success";
-      error?: Error | undefined;
-      snippets: SpeakeasyHighlightedCode[];
-      selectedSnippet: SpeakeasyHighlightedCode;
-    }
+  status: "success";
+  error?: Error | undefined;
+  snippets: SpeakeasyHighlightedCode[];
+  selectedSnippet: SpeakeasyHighlightedCode;
+}
   | {
-      status: "error";
-      error: Error;
-      snippets?: SpeakeasyHighlightedCode[] | undefined;
-      selectedSnippet?: SpeakeasyHighlightedCode | undefined;
-    };
+  status: "error";
+  error: Error;
+  snippets?: SpeakeasyHighlightedCode[] | undefined;
+  selectedSnippet?: SpeakeasyHighlightedCode | undefined;
+};
 
 type FetchSuccessPayload = {
   snippets: SpeakeasyHighlightedCode[];
@@ -43,21 +43,27 @@ 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 = {
+  operationId?: string | undefined;
+  language?: string | undefined;
+};
+
+function safeGetSnippet(
   snippets: SpeakeasyHighlightedCode[],
-  language?: string,
+  {operationId, 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(s.raw.operationId, operationId) && maybeEqual(s.lang, language));
   if (selectedSnippet) {
     return selectedSnippet;
   }
 
   console.warn(
-    `Could not find snippet for language "${language}".`,
+    `Could not find snippet for operationId "${operationId}".`,
     `Falling back to to first language in snippet array.`,
   );
 
@@ -70,14 +76,14 @@ const reducer: React.Reducer<CodeSampleState, Action> = (
 ) => {
   switch (action.type) {
     case "FETCH_INIT":
-      return { ...state, status: "loading" };
+      return {...state, status: "loading"};
     case "FETCH_SUCCESS":
       return {
         status: "success",
         snippets: action.payload.snippets,
-        selectedSnippet: safeGetSnippetForLanguage(
+        selectedSnippet: safeGetSnippet(
           action.payload.snippets,
-          action.payload.defaultLanguage,
+          {language: action.payload.defaultLanguage},
         ),
       };
     case "FETCH_FAILURE":
@@ -86,10 +92,10 @@ const reducer: React.Reducer<CodeSampleState, Action> = (
         status: "error",
         error: action.payload,
       };
-    case "SET_LANGUAGE":
+    case "SELECT":
       return {
         ...state,
-        selectedSnippet: safeGetSnippetForLanguage(
+        selectedSnippet: safeGetSnippet(
           state.snippets!,
           action.payload,
         ),
@@ -106,11 +112,11 @@ type UseCodeSampleStateInit = {
 };
 
 export const useCodeSampleState = ({
-  client: clientProp,
-  requestParams,
-  defaultLanguage,
-}: UseCodeSampleStateInit) => {
-  const [state, dispatch] = React.useReducer(reducer, { status: "loading" });
+                                     client: clientProp,
+                                     requestParams,
+                                     defaultLanguage,
+                                   }: UseCodeSampleStateInit) => {
+  const [state, dispatch] = React.useReducer(reducer, {status: "loading"});
   const client = useSafeSpeakeasyCodeSamplesContext(clientProp);
 
   const highlightSnippets = async (snippets: UsageSnippet[]) => {
@@ -122,17 +128,17 @@ export const useCodeSampleState = ({
           "github-from-css",
         );
 
-        return { ...highlightedCode, raw: snippet };
+        return {...highlightedCode, raw: snippet};
       }),
     );
   };
 
   async function handleMount() {
-    dispatch({ type: "FETCH_INIT" });
+    dispatch({type: "FETCH_INIT"});
     const result = await codeSamplesGet(client, requestParams);
 
     if (!result.ok) {
-      return dispatch({ type: "FETCH_FAILURE", payload: result.error });
+      return dispatch({type: "FETCH_FAILURE", payload: result.error});
     }
 
     dispatch({
@@ -148,11 +154,17 @@ 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,
+        operationId: state.selectedSnippet?.raw.operationId,
+        ...params,
+      }
+    });
   }
 
-  return { state, setSelectedLanguage };
+  return {state, selectSnippet};
 };
 
 /** Intended to give the user the option of providing their own client. */
@@ -169,7 +181,7 @@ export const useSafeSpeakeasyCodeSamplesContext = (
   } catch {
     throw new Error(
       "The Speakeasy Code Samples component must either be given an apiKey and " +
-        "registryUrl, or be wrapped in a SpeakeasyCodeSamplesProvider.",
+      "registryUrl, or be wrapped in a SpeakeasyCodeSamplesProvider.",
     );
   }
 };

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

@@ -1,5 +1,5 @@
-import { css } from "@emotion/css";
-import { cssVarKey } from "./styles.js";
+import {css} from "@emotion/css";
+import {cssVarKey} from "./styles.js";
 
 const classes = {
   root: css({
@@ -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",