chore: clean up interface, use method+path

Author: chase-crumbaugh

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

@@ -46,28 +46,28 @@ type Action =
   | { type: "SELECT"; payload: SafeGetSnippetParams };
 
 type SafeGetSnippetParams = {
-  operationId?: string | undefined;
+  methodPath?: string | undefined;
   language?: string | undefined;
 };
 
 function safeGetSnippet(
   snippets: SpeakeasyHighlightedCode[],
-  { operationId, language }: SafeGetSnippetParams,
+  { methodPath, language }: SafeGetSnippetParams,
 ): SpeakeasyHighlightedCode {
   const maybeEqual = (a: string, b: string | undefined) =>
     b === undefined || a.toLowerCase() === b.toLowerCase();
 
   const selectedSnippet = snippets.find(
     (s) =>
-      maybeEqual(s.raw.operationId, operationId) &&
+      maybeEqual(getMethodPath(s.raw), methodPath) &&
       maybeEqual(s.lang, language),
   );
   if (selectedSnippet) {
     return selectedSnippet;
   }
 
   console.warn(
-    `Could not find snippet for operationId "${operationId}".`,
+    `Could not find snippet for method and path "${methodPath}".`,
     `Falling back to to first language in snippet array.`,
   );
 
@@ -159,7 +159,7 @@ export const useCodeSampleState = ({
       type: "SELECT",
       payload: {
         language: state.selectedSnippet?.raw.language,
-        operationId: state.selectedSnippet?.raw.operationId,
+        methodPath: getMethodPath(state.selectedSnippet?.raw),
         ...params,
       },
     });
@@ -168,6 +168,9 @@ export const useCodeSampleState = ({
   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.tsx

@@ -6,7 +6,7 @@ import {
   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";
@@ -20,15 +20,15 @@ import {
 } 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. If not found in the snippets, the first one will be used. */
   defaultLanguage?: string;
-  /** Default operation to show in the code playground. If not found in the snippets, the first one will be used. */
-  defaultOperation?: string;
+
   /**
    * The color mode for the code playground. If "system", the component will
    * detect the system color scheme automagically.
@@ -40,12 +40,13 @@ 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 CodeSampleTitle
    * @see CodeSampleFilenameTitle
    * @default CodeSampleMethodTitle
    */
-  title?: CodeSampleTitleComponent | React.ReactNode | string | "none";
+  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.
    */
@@ -68,7 +69,6 @@ export function CodeSamplesViewer({
   theme = "system",
   title = CodeSampleFilenameTitle,
   defaultLanguage,
-  defaultOperation,
   operations,
   copyable,
   client: clientProp,
@@ -93,7 +93,7 @@ export function CodeSamplesViewer({
   // On mount, select the defaults
   useEffect(() => {
     if (!state.snippets || state.status !== "success") return;
-    selectSnippet({ language: defaultLanguage, operationId: defaultOperation });
+    selectSnippet({ language: defaultLanguage });
   }, [state.status]);
 
   const systemColorMode = useSystemColorMode();
@@ -110,12 +110,28 @@ export function CodeSamplesViewer({
     ];
   }, [state.snippets]);
 
-  const operationIds: string[] = useMemo(() => {
-    return [
-      ...new Set(state.snippets?.map(({ raw }) => raw.operationId) ?? []),
-    ];
+  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);
+
   return (
     <LazyMotion strict features={domMax}>
       <div
@@ -128,7 +144,7 @@ export function CodeSamplesViewer({
         }}
         className={`${classes.root} ${className ?? ""}`}
       >
-        {title !== "none" && (
+        {title !== false && (
           <div className={classes.heading}>
             <CodeSampleTitle
               component={title}
@@ -143,9 +159,13 @@ export function CodeSamplesViewer({
               )}
               {state.status === "success" && operationIds.length > 1 && (
                 <Selector
-                  value={state.selectedSnippet?.raw.operationId}
+                  value={getOperationKey(state.selectedSnippet?.raw)}
                   values={operationIds}
-                  onChange={(operationId) => selectSnippet({ operationId })}
+                  onChange={(operationId: string) =>
+                    selectSnippet({
+                      methodPath: operationIdToMethodAndPath[operationId],
+                    })
+                  }
                   className={classes.selector}
                 />
               )}
@@ -155,7 +175,7 @@ export function CodeSamplesViewer({
                     state.selectedSnippet?.raw.language,
                   )}
                   values={languages}
-                  onChange={(language) => selectSnippet({ language })}
+                  onChange={(language: string) => selectSnippet({ language })}
                   className={classes.selector}
                 />
               )}

src/react-components/titles.tsx

@@ -81,10 +81,13 @@ export const CodeSampleTitle: React.FC<TitleComponentProps> = (props) => {
 
   if (props.status !== "success") return <TitleSkeleton />;
 
+  if (props.component === false) {
+    return null;
+  }
+
   if (React.isValidElement(props.component)) return props.component;
 
   if (typeof props.component === "string") {
-    if (props.component === "none") return null;
     return <span>{props.component}</span>;
   }