refining the react component experience a bit

walker-tx · walker-tx · commit 33a675c49ac1 · 2025-01-13T15:33:59.000-06:00
diff --git a/.speakeasy/gen.lock b/.speakeasy/gen.lock
@@ -5,8 +5,8 @@ management:
   docVersion: 0.4.0
   speakeasyVersion: 1.468.0
   generationVersion: 2.492.3
-  releaseVersion: 2.0.11
-  configChecksum: 6131813611c165f99630ca021de715dc
+  releaseVersion: 2.0.12
+  configChecksum: c27aaa83187732b257c2a86fbfc4b1c5
   repoURL: https://github.com/speakeasy-api/speakeasy-code-samples-ts.git
   installationURL: https://github.com/speakeasy-api/speakeasy-code-samples-ts
   published: true
diff --git a/.speakeasy/gen.yaml b/.speakeasy/gen.yaml
@@ -16,7 +16,7 @@ generation:
     oAuth2ClientCredentialsEnabled: false
     oAuth2PasswordEnabled: false
 typescript:
-  version: 2.0.11
+  version: 2.0.12
   additionalDependencies:
     dependencies: {}
     devDependencies: {}
@@ -40,7 +40,7 @@ typescript:
   inputModelSuffix: input
   maxMethodParams: 1
   methodArguments: require-security-and-request
-  moduleFormat: commonjs
+  moduleFormat: esm
   outputModelSuffix: output
   packageName: '@speakeasyapi/code-samples'
   responseFormat: flat
diff --git a/.speakeasy/workflow.lock b/.speakeasy/workflow.lock
@@ -2,7 +2,7 @@ speakeasyVersion: 1.468.0
 sources:
     speakeasy-OAS:
         sourceNamespace: speakeasy-oas
-        sourceRevisionDigest: sha256:771ed09dacf285d6f18e27f01e0492f45f9248110476d381d0a6768cb4021320
+        sourceRevisionDigest: sha256:eccb5c0b494c102a3985fedd96b152ad956b8be90681e6f5f21b5756463f66ab
         sourceBlobDigest: sha256:6d9de4a70686f4366747b9dbf16917300a43dea8857ad6583f35ef3531bffbdb
         tags:
             - latest
@@ -11,10 +11,10 @@ targets:
     code_samples_typescript_sdk:
         source: speakeasy-OAS
         sourceNamespace: speakeasy-oas
-        sourceRevisionDigest: sha256:771ed09dacf285d6f18e27f01e0492f45f9248110476d381d0a6768cb4021320
+        sourceRevisionDigest: sha256:eccb5c0b494c102a3985fedd96b152ad956b8be90681e6f5f21b5756463f66ab
         sourceBlobDigest: sha256:6d9de4a70686f4366747b9dbf16917300a43dea8857ad6583f35ef3531bffbdb
         codeSamplesNamespace: speakeasy-oas-typescript-code-samples
-        codeSamplesRevisionDigest: sha256:12997450a71bf46eaf590c8da28f9c7599305c352f80814d77a29071c25a1f03
+        codeSamplesRevisionDigest: sha256:b21e9f5e10bf036c791b2e888f9d5eb8177a85f23f84ebdd01bac5bc90f418f3
 workflow:
     workflowVersion: 1.0.0
     speakeasyVersion: latest
diff --git a/README.md b/README.md
@@ -84,6 +84,10 @@ yarn add @tanstack/react-query react react-dom
 # Note that Yarn does not install peer dependencies automatically. You will need
 # to install zod as shown above.
 ```
+
+> [!NOTE]
+> This package is published as an ES Module (ESM) only. For applications using
+> CommonJS, use `await import("@speakeasyapi/code-samples")` to import and use this package.
 <!-- End SDK Installation [installation] -->
 
 <!-- Start Requirements [requirements] -->
diff --git a/jsr.json b/jsr.json
@@ -2,7 +2,7 @@
 
 {
   "name": "@speakeasyapi/code-samples",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "exports": {
     ".": "./src/index.ts",    
     "./models/errors": "./src/models/errors/index.ts",    
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,8 +1,47 @@
 {
   "name": "@speakeasyapi/code-samples",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "author": "Speakeasy",
-  "main": "./index.js",
+  "type": "module",
+  "main": "./esm/index.js",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./esm/index.d.ts",
+      "default": "./esm/index.js"
+    },
+    "./package.json": "./package.json",
+    "./types": {
+      "source": "./src/types/index.ts",
+      "types": "./esm/types/index.d.ts",
+      "default": "./esm/types/index.js"
+    },
+    "./models/errors": {
+      "source": "./src/models/errors/index.ts",
+      "types": "./esm/models/errors/index.d.ts",
+      "default": "./esm/models/errors/index.js"
+    },
+    "./models/components": {
+      "source": "./src/models/components/index.ts",
+      "types": "./esm/models/components/index.d.ts",
+      "default": "./esm/models/components/index.js"
+    },
+    "./models/operations": {
+      "source": "./src/models/operations/index.ts",
+      "types": "./esm/models/operations/index.d.ts",
+      "default": "./esm/models/operations/index.js"
+    },
+    "./*.js": {
+      "source": "./src/*.ts",
+      "types": "./esm/*.d.ts",
+      "default": "./esm/*.js"
+    },
+    "./*": {
+      "source": "./src/*.ts",
+      "types": "./esm/*.d.ts",
+      "default": "./esm/*.js"
+    }
+  },
   "sideEffects": false,
   "repository": {
     "type": "git",
diff --git a/src/index.extras.ts b/src/index.extras.ts
diff --git a/src/index.ts b/src/index.ts
@@ -5,5 +5,3 @@
 export * from "./lib/config.js";
 export * as files from "./lib/files.js";
 export * from "./sdk/sdk.js";
-
-export * from "./index.extras.js";
diff --git a/src/lib/config.ts b/src/lib/config.ts
@@ -57,8 +57,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "0.4.0",
-  sdkVersion: "2.0.11",
+  sdkVersion: "2.0.12",
   genVersion: "2.492.3",
   userAgent:
-    "speakeasy-sdk/typescript 2.0.11 2.492.3 0.4.0 @speakeasyapi/code-samples",
+    "speakeasy-sdk/typescript 2.0.12 2.492.3 0.4.0 @speakeasyapi/code-samples",
 } as const;
diff --git a/src/react.tsx b/src/react.tsx
@@ -1,86 +1,127 @@
 import React from "react";
-import { useCodeSamplesGet } from "./react-query/codeSamplesGet";
+import { QueryHookOptions } from "./react-query/_types.js";
+import {
+  CodeSamplesGetQueryData,
+  useCodeSamplesGet,
+} from "./react-query/codeSamplesGet.js";
 
-type SpeakeasyCodeSampleProps = {
+export * from "./react-query/index.js";
+
+type CodeSampleProps = {
   /**
-   * The URL of the registry that you would like to fetch a code sample from.
+   * The URL of the registry that you would like to fetch a code sample from. If
+   * the client was provided with a registry URL, then this prop is optional.
    *
    * @example "https://spec.speakeasy.com/my-org/my-workspace/my-source"
-   */
-  registryUrl: string;
+   * */
+  registryUrl?: string;
+
   /**
    * The `operationId` of the operation that you would like to fetch a code
    * sample for.
    *
    * @example "getPetById"
    * */
   operationId: string;
+
   /**
    * The language of the code sample that you would like to fetch.
    *
    * @example "typescript"
    * */
   language: string;
 
-  renderError?: (err: Error) => React.ReactNode;
-  renderPending?: () => React.ReactNode;
-  renderSuccess?: (codeSample: string) => React.ReactNode;
+  queryOptions?: QueryHookOptions<CodeSamplesGetQueryData>;
+
+  /**
+   * The component to render if there is an error fetching the code sample.
+   *
+   * @example
+   * ```tsx
+   * (err: Error) => <>{err.message}</>
+   * ```
+   */
+  error?: (err: Error) => React.ReactNode;
+
+  /**
+   * The component to render while fetching the code sample.
+   *
+   * @example
+   * ```tsx
+   * () => <>Fetching Code Sample...</>
+   * ```
+   */
+  pending?: React.ReactNode | (() => React.ReactNode);
+
+  /**
+   * The component to render when the code sample has been successfully fetched.
+   *
+   * @example
+   * ```tsx
+   * (codeSample: string) => <pre></code>{codeSample}</code></pre>
+   * ```
+   */
+  success?: (codeSample: string) => React.ReactNode;
 };
 
 /**
- * SpeakeasyCodeSample is a React component that fetches and displays a code
- * sample snippet from the Speakeasy Code Samples API. It uses the
- * `useCodeSamplesGet` hook to retrieve the code sample based on the provided
- * props.
+ * React component that fetches and displays a code sample snippet from the
+ * Speakeasy Code Samples API. It uses a Speakeasy-generated React Query to
+ * retrieve the code sample based on the provided props.
  *
- * @param {SpeakeasyCodeSampleProps} props - The properties passed to the component.
- * @param {string} props.registryUrl - The URL of the code sample registry.
- * @param {string} props.operationId - The operation ID for which the code sample is requested.
- * @param {string} props.language - The programming language of the code sample.
+ * __**IMPORTANT:**  This component must be rendered within a structure wrapped
+ * by both `QueryClientProvider` and `SpeakeasyCodeSamplesProvider`. This
+ * ensures that the necessary context and query client are properly initialized
+ * for the component to function.__
  *
- * @returns {JSX.Element} A JSX element that displays the code sample snippet, a loading message, or an error message.
+ * @param {CodeSampleProps} props - The properties passed to the component.
  *
+ * @returns {JSX.Element} A JSX element that displays the code sample snippet, a
+ * loading message, or an error message.
  * @example
  * Usage within a component that provides code highlighting:
  *
  * ```tsx
- * import { SpeakeasyCodeSample } from "@speakeasyapi/react";
+ * import { CodeSample } from "@speakeasyapi/code-samples/react";
  * import { Code } from './components/code-highlighting';
  *
  * const ExampleComponent: React.FC = () => (
- *   <Code language="typescript">
- *     <SpeakeasyCodeSample
+ *     <CodeSample
  *       registryUrl="https://spec.speakeasy.com/my-org/my-workspace/my-source"
  *       operationId="getPetById"
  *       language="typescript"
+ *       error={(err) => <>{err.message}</>}
+ *       pending={() => <>Fetching Code Sample...</>}
+ *       success={(snippet) => <Code language="typescript" code={snippet} />}
  *     />
- *   </Code>
  * );
  * ```
- */
-export const SpeakeasyCodeSample: React.FC<SpeakeasyCodeSampleProps> = (
-  props
-) => {
+ * */
+export const CodeSample: React.FC<CodeSampleProps> = (props) => {
   const {
-    renderError = (err: Error) => <>{err.message}</>,
-    renderPending = () => <>Fetching Code Sample...</>,
-    renderSuccess = (codeSample: string) => <>{codeSample}</>,
+    error: renderError = (err: Error) => <>{err.message}</>,
+    pending: renderPending = <>Fetching Code Sample...</>,
+    success: renderSuccess = (codeSample: string) => <>{codeSample}</>,
+    queryOptions,
     ...queryParams
   } = props;
 
-  const { isPending, isError, error, data } = useCodeSamplesGet({
-    registryUrl: queryParams.registryUrl,
-    operationIds: [queryParams.operationId],
-    languages: [queryParams.language],
-  });
+  const { isPending, isError, error, data } = useCodeSamplesGet(
+    {
+      registryUrl: queryParams.registryUrl,
+      operationIds: [queryParams.operationId],
+      languages: [queryParams.language],
+    },
+    queryOptions
+  );
 
   if (isPending) {
-    return renderPending();
+    return renderPending instanceof Function ? renderPending() : renderPending;
   }
 
   if (isError) {
     return renderError(error);
   }
 
-  return <>{data.snippets[0]?.code ?? "No code snippet found."}</>;
+  return renderSuccess(data.snippets[0]!.code);
 };
diff --git a/tsconfig.json b/tsconfig.json
@@ -14,7 +14,7 @@
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
-    "outDir": ".",
+    "outDir": "esm",
     
 
     // https://github.com/tsconfig/bases/blob/a1bf7c0fa2e094b068ca3e1448ca2ece4157977e/bases/strictest.json

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`
`3`	`3`	`{`
`4`	`4`	`"name": "@speakeasyapi/code-samples",`
`5`		`- "version": "2.0.11",`
	`5`	`+ "version": "2.0.12",`
`6`	`6`	`"exports": {`
`7`	`7`	`".": "./src/index.ts",`
`8`	`8`	`"./models/errors": "./src/models/errors/index.ts",`