Merge pull request #23 from sigmacomputing/embed-sdk-add-sample-app

Embed-SDK Add sample application

embed-sdk-react/README.md

@@ -1,39 +1,45 @@
-# embed-sdk
+# Sigma Embed-SDK for React
+Sigma provides several methods to allow users and developers to interact with its systems including web-ui, REST API, Javascript Embed API and an SDK for the React framework.
 
-SDK for Sigma Computing Embeds. They are a wrapper over postmessage APIs.
+The Embed-SDK for React provides an addition avenue, targeted at software developers who prefer to use a software development kit (SDK), as opposed to using the Sigmas JavaScript Embed-API, which can require writing additional code. 
+
+If the basic instructions below are not sufficient, please review the [QuickStart here.](https://quickstarts.sigmacomputing.com/guide/embedding_15_embed_sdk/index.html?index=..%2F..index#0)
 
 ## Getting Started
+1: Clone the repository
 
-This repo uses pnpm and node18+. To get started
+2: Setup your local environment for project dependencies:
+- Node.js (version 18+)
+- pnpm
+- corepack (needs to be enabled)
 
-```sh
-corepack enable
-pnpm i
+3: Start the development server
+```code
+pnpm run dev
 ```
 
+4: Browse to http://localhost:3000
+
+## Building
 The repo uses turbo for its build system. It currently has 3 packages:
 
 - embed-sdk: "barebones" wrappers over postMessages
 - react-embed-sdk: React hooks to easily use the embed-sdk
 - docs: Some barebone documentation / examples.
 
 To build:
-
-```
+```code
 pnpm run build
 ```
 
 ## Publish flow:
-
 Publishes are handled by changesets. To add a changeset, in your PR run:
-
-```
+```code
 pnpm changeset
 ```
 
 This will prompt you to add a changeset. Once merged, a PR will be opened to bump the version and publish the package.
 
-## Add iframe events
-
+## Adding iframe events
 - [Example](https://github.com/sigmacomputing/embed-sdk/pull/31) for adding an inbound event
 - Add a changeset for both the embed-sdk and react-embed-sdk.

embed-sdk-react/docs/basic-examples/.env

@@ -4,3 +4,4 @@
 EMBED_URL={url path to embed}
 EMBED_CLIENT_ID={your client id}
 EMBED_SECRET=(your embed secret)
+EMBED_EMAIL=[email protected] 

embed-sdk-react/docs/basic-examples/app/examples/basic-example/TooltipComponent.tsx

@@ -0,0 +1,23 @@
+// TooltipComponent.tsx
+import React from 'react';
+
+interface TooltipProps {
+  text: string; // Text to display in the tooltip
+  children: React.ReactNode; // The content that triggers the tooltip
+}
+
+const TooltipComponent: React.FC<TooltipProps> = ({ text, children }) => (
+  <div className="relative group inline-block">
+    {/* Trigger Element */}
+    {children}
+    {/* Tooltip Box */}
+    <div
+      className="absolute left-1/2 transform -translate-x-1/2 mt-2 px-4 py-2 bg-gray-800 text-white text-sm rounded-lg shadow-lg opacity-0 group-hover:opacity-100 transition-opacity duration-300 z-50"
+      style={{ minWidth: '400px', maxWidth: '600px', pointerEvents: 'none' }}
+    >
+      {text}
+    </div>
+  </div>
+);
+
+export default TooltipComponent;

embed-sdk-react/docs/basic-examples/app/examples/basic-example/basic-example-embed.tsx

@@ -1,19 +1,31 @@
-"use client";
+// basic-example-embed.tsx
+// Utilizes the Sigma Computing Embed SDK to integrate an iframe within a React application.
+
+"use client"; // Next.js directive to ensure this component runs only on the client-side.
+
+import React from "react";
+// Import the useSigmaIframe hook from the Sigma Computing React Embed SDK
 import { useSigmaIframe } from "@sigmacomputing/react-embed-sdk";
 
+// Define the BasicExample component, which receives a 'src' prop for the iframe URL
 export default function BasicExample({ src }: { src: string }) {
+  // Destructure the iframeRef, loading, and error values from the useSigmaIframe hook
   const { iframeRef, loading, error } = useSigmaIframe();
+
   return (
-    <>
-      <p className={loading ? "show" : "hidden"}> Loading...</p>
-      <p className={error ? "show" : "hidden"}> Error loading iframe</p>
+    // Parent container with full height
+    <div className="h-full">
+      {/* Conditional rendering: Display loading text if the iframe is loading */}
+      {loading && <p className="text-center">Loading...</p>}
+      {/* Conditional rendering: Display error message if there is an error loading the iframe */}
+      {error && <p className="text-center text-red-500">Error loading iframe</p>}
+      {/* Render the iframe, filling the parent container */}
       <iframe
-        src={src}
-        ref={iframeRef}
-        className={loading || error ? "hidden" : "show"}
-        width={"100%"}
-        height={"100%"}
+        src={src} // Source URL for the iframe
+        ref={iframeRef} // Reference from useSigmaIframe hook for managing iframe interactions
+        className={`w-full h-full ${loading || error ? "hidden" : ""}`} // CSS classes for full width/height and conditional visibility
+        style={{ border: "none" }} // Inline style to remove default border
       />
-    </>
+    </div>
   );
-}
+}

embed-sdk-react/docs/basic-examples/app/examples/basic-example/basic-example-wrapper.tsx

@@ -1,9 +1,30 @@
+// basic-example-wrapper.tsx
+// The SignedIframe component is responsible for securely embedding a Sigma Computing dashboard into a React application.
+// 	signEmbedUrl: This function is imported from the Sigma Embed SDK library and is used to generate a signed URL for secure access to a Sigma dashboard.
+
+// Import the signEmbedUrl function from the utilities module
 import { signEmbedUrl } from "@/lib/utils";
+// Import the BasicExample component, which is responsible for rendering the iframe
 import BasicExample from "./basic-example-embed";
 
+// Define an asynchronous component to sign the URL and render the iframe
 export default async function SignedIframe() {
-  const src =
-    "process.env.EMBED_URL;";
-  const signedSrc = await signEmbedUrl(src);
-  return <BasicExample src={signedSrc} />;
-}
+  // The base URL for the Sigma Computing dashboard or visualization to be embedded
+   const src = "YOUR_SIGMA_EMBED_PATH"; // The embed URL created in Sigma 
+   // const src = ""; // My Sigma instance
+
+  try {
+    // Await the signed URL by passing the base URL to the signEmbedUrl function
+    const signedSrc = await signEmbedUrl(src);
+
+    // Log the base and signed URLs as output in server-side terminal session
+    console.log("Signed URL:", signedSrc);
+
+    // Return the BasicExample component with the signed URL as a prop
+    return <BasicExample src={signedSrc} />;
+  } catch (error) {
+    // Log any errors encountered during signing
+    console.error("Error signing URL:", error);
+    return <p>Error loading iframe</p>;
+  }
+}

embed-sdk-react/docs/basic-examples/app/examples/basic-example/page.mdx

@@ -1,28 +1,71 @@
-import BasicExample from "./basic-example-wrapper";
+{/* page.mdx */}
+{/*Renders the webpage and SignedIframe*/}
 
-<section>
-```tsx
-import { useSigmaIframe } from "@sigmacomputing/react-embed-sdk";
-function BasicExample({ src }: { src: string }) {
-  const { iframeRef, loading, error } = useSigmaIframe(); // [!code highlight]
+import SignedIframe from './basic-example-wrapper';
+import TooltipComponent from './TooltipComponent';
+
+export default function ExamplePage() {
   return (
-    <>
-      <p className={loading ? "show" : "hidden"}> Loading...</p> // [!code highlight]
-      <p className={error ? "show" : "hidden"}> Error loading iframe</p> // [!code highlight]
-      <iframe
-        src={src}
-        ref={iframeRef} // [!code highlight]
-        className={loading || error ? "hidden" : "show"} // [!code highlight]
-        width={"100%"}
-        height={"100%"}
-      />
-    </>
-  );
-}
-```
-</section>
+    <div className="p-4">
+      <h1 className="text-2xl font-bold mb-4">Sigma Dashboard Example</h1>
+
+      {/* Grid Container */}
+      <div className="grid grid-cols-1 gap-8 md:grid-cols-2">
 
-<section>
+        {/* Example Embed */}
+        <div className="bg-gray-100 p-6 rounded-lg shadow-md mb-8">
+          <h2 className="text-xl font-bold">Example Embed</h2>
+          <p>
+            The embed shown below is provided free of charge by Sigma Computing, as an example only. The files that
+            have been customized are listed on your left.
+          </p>
+          <p>
+            While you will not be able to customize this example in terms of parameters that are
+            sent to Sigma by the Embed-SDK, you can review the files involved to see a working example of what is
+            minimally required.
+          </p>
+        </div>
 
-<BasicExample src="https://staging.sigmacomputing.io/embed/1-156WHbeEOtenyfjDhfsnjY" />
-</section>
+        {/*Files Involved*/}
+        <div className="bg-gray-50 p-6 rounded-lg shadow-md mb-8">
+          <h2 className="text-xl font-bold">Files Involved (all files in docs/basic-examples/..) </h2>
+          <ul className="list-disc pl-5 mt-2 space-y-2">
+    <li className="list-inside">
+              <TooltipComponent text="Application environment variables file. This is where we are storing the Sigma embed credentials">
+               .env
+              </TooltipComponent>
+            </li>
+    <li className="list-inside">
+              <TooltipComponent text="This file contains utility functions that facilitate the embedding of Sigma dashboards into a web application by generating signed URLs. These signed URLs ensure secure and authorized access to Sigma dashboards or visualizations.">
+                /lib/utils.ts
+              </TooltipComponent>
+            </li>
+    <li className="list-inside">
+              <TooltipComponent text="The SignedIframe component is responsible for securely embedding a Sigma Computing dashboard into a React application.">
+                app/examples/basic-example/basic-example-wrapper.tsx
+              </TooltipComponent>
+            </li>
+    <li className="list-inside">
+              <TooltipComponent text="This file is a React component designed to embed a Sigma Computing dashboard using an iframe within a React application.">
+                /app/examples/basic-example/basic-example-embed.tsx
+              </TooltipComponent>
+            </li>
+                <li className="list-inside">
+              <TooltipComponent text="This file is a React component designed to embed a Sigma Computing dashboard using an iframe within a React application.">
+                /app/examples/basic-example/basic-example-embed.tsx
+              </TooltipComponent>
+            </li>
+          </ul>
+        </div>
+      </div>
+
+      {/* BasicExample Block - Full Width */}
+      <div className="bg-white p-6 rounded-lg shadow-md h-[calc(100vh-16rem)] w-full">
+        <SignedIframe />
+      </div>
+    </div>
+  );
+}
+
+{/* Generate Signed URL for console log display only */}
+console.log("Signed URL:", signedSrc);

embed-sdk-react/docs/basic-examples/app/globals.css

@@ -20,4 +20,37 @@ body {
   .text-balance {
     text-wrap: balance;
   }
+
+  /* Tooltip container */
+.tooltip {
+  position: relative;
+  display: inline-block;
+}
+
+/* Tooltip text */
+.tooltip .tooltiptext {
+  visibility: hidden;
+  width: 120px;
+  background-color: black;
+  color: #fff;
+  text-align: center;
+  border-radius: 6px;
+  padding: 5px 0;
+  position: absolute;
+  z-index: 1;
+  bottom: 150%;
+  left: 50%;
+  margin-left: -60px;
+  opacity: 0;
+  transition: opacity 0.3s;
+}
+
+/* Show the tooltip text when you mouse over the tooltip container */
+.tooltip:hover .tooltiptext {
+  visibility: visible;
+  opacity: 1;
+}
+
 }
+
+