@sigmacomputing/react-embed-sdk 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -1,6 +1,79 @@
+import * as react from 'react';
 import { WorkbookLoadedEvent, WorkbookErrorEvent } from '@sigmacomputing/embed-sdk';
+export * from '@sigmacomputing/embed-sdk';
 
-declare function useWorkbookLoaded(iframeRef: React.RefObject<HTMLIFrameElement>, onLoaded: (event: WorkbookLoadedEvent) => void): void;
-declare function useWorkbookError(iframeRef: React.RefObject<HTMLIFrameElement>, onError: (event: WorkbookErrorEvent) => void): void;
+type OnLoaded = (event: WorkbookLoadedEvent) => void;
+type OnError = (event: WorkbookErrorEvent) => void;
+/**
+ * Listen for a workbook loaded event, and execute the given callback when it occurs.
+ *
+ * @example
+ * ```
+ * function MyEmbed() {
+ *   const [loading, setLoading] = useState(true);
+ *   const loadingCallback = useCallback(() => setLoading(false), []);
+ *   const iframeRef = useRef<HTMLIFrameElement>(null);
+ *   useWorkbookLoaded(iframeRef, loadingCallback);
+ *   return (
+ *    <iframe
+ *      className{loading ? "hidden" : "show"}
+ *      ref={iframeRef}
+ *      src="https://sigmacomputing.app/embed"
+ *    />
+ *   );
+ * }
+ * ```
+ *
+ */
+declare function useWorkbookLoaded(iframeRef: React.RefObject<HTMLIFrameElement>, onLoaded: OnLoaded): void;
+/**
+ * Listen for a workbook error event, and execute the given callback when it occurs.
+ *
+ * @example
+ * ```
+ * function MyEmbed() {
+ *   const [error, setError] = useState<string | null>(null);
+ *   const onError = useCallback((event: WorkbookErrorEvent) => {
+ *     sendToErrorReporting(event.message);
+ *     setError(event.message);
+ *   }, []);
+ *   const iframeRef = useRef<HTMLIFrameElement>(null);
+ *   return (
+ *    <iframe
+ *      ref={iframeRef}
+ *      src="https://sigmacomputing.app/embed"
+ *    />
+ *   );
+ * }
+ * ```
+ *
+ */
+declare function useWorkbookError(iframeRef: React.RefObject<HTMLIFrameElement>, onError: OnError): void;
+/**
+ * A hook that returns a ref to be used with an iframe element, and the loading and error state of the embed.
+ *
+ * @example
+ * ```
+ * function MyEmbed() {
+ *  const { iframeRef, loading, error } = useSigmaIframe();
+ *  return (
+ *   <>
+ *     {loading && <p>Loading...</p>}
+ *     {error && <p>Error: {error.message}</p>}
+ *     <iframe
+ *       className={loading || error ? "hidden" : "show"}
+ *       ref={iframeRef}
+ *       src="https://sigmacomputing.app/embed"
+ *     />
+ *   </>
+ * );
+ * }
+ * ```
+ */
+declare function useSigmaIframe(): {
+    iframeRef: react.RefObject<HTMLIFrameElement>;
+    loading: boolean;
+    error: WorkbookErrorEvent | null;
+};
 
-export { useWorkbookError, useWorkbookLoaded };
+export { type OnError, type OnLoaded, useSigmaIframe, useWorkbookError, useWorkbookLoaded };

package/dist/index.d.ts

@@ -1,6 +1,79 @@
+import * as react from 'react';
 import { WorkbookLoadedEvent, WorkbookErrorEvent } from '@sigmacomputing/embed-sdk';
+export * from '@sigmacomputing/embed-sdk';
 
-declare function useWorkbookLoaded(iframeRef: React.RefObject<HTMLIFrameElement>, onLoaded: (event: WorkbookLoadedEvent) => void): void;
-declare function useWorkbookError(iframeRef: React.RefObject<HTMLIFrameElement>, onError: (event: WorkbookErrorEvent) => void): void;
+type OnLoaded = (event: WorkbookLoadedEvent) => void;
+type OnError = (event: WorkbookErrorEvent) => void;
+/**
+ * Listen for a workbook loaded event, and execute the given callback when it occurs.
+ *
+ * @example
+ * ```
+ * function MyEmbed() {
+ *   const [loading, setLoading] = useState(true);
+ *   const loadingCallback = useCallback(() => setLoading(false), []);
+ *   const iframeRef = useRef<HTMLIFrameElement>(null);
+ *   useWorkbookLoaded(iframeRef, loadingCallback);
+ *   return (
+ *    <iframe
+ *      className{loading ? "hidden" : "show"}
+ *      ref={iframeRef}
+ *      src="https://sigmacomputing.app/embed"
+ *    />
+ *   );
+ * }
+ * ```
+ *
+ */
+declare function useWorkbookLoaded(iframeRef: React.RefObject<HTMLIFrameElement>, onLoaded: OnLoaded): void;
+/**
+ * Listen for a workbook error event, and execute the given callback when it occurs.
+ *
+ * @example
+ * ```
+ * function MyEmbed() {
+ *   const [error, setError] = useState<string | null>(null);
+ *   const onError = useCallback((event: WorkbookErrorEvent) => {
+ *     sendToErrorReporting(event.message);
+ *     setError(event.message);
+ *   }, []);
+ *   const iframeRef = useRef<HTMLIFrameElement>(null);
+ *   return (
+ *    <iframe
+ *      ref={iframeRef}
+ *      src="https://sigmacomputing.app/embed"
+ *    />
+ *   );
+ * }
+ * ```
+ *
+ */
+declare function useWorkbookError(iframeRef: React.RefObject<HTMLIFrameElement>, onError: OnError): void;
+/**
+ * A hook that returns a ref to be used with an iframe element, and the loading and error state of the embed.
+ *
+ * @example
+ * ```
+ * function MyEmbed() {
+ *  const { iframeRef, loading, error } = useSigmaIframe();
+ *  return (
+ *   <>
+ *     {loading && <p>Loading...</p>}
+ *     {error && <p>Error: {error.message}</p>}
+ *     <iframe
+ *       className={loading || error ? "hidden" : "show"}
+ *       ref={iframeRef}
+ *       src="https://sigmacomputing.app/embed"
+ *     />
+ *   </>
+ * );
+ * }
+ * ```
+ */
+declare function useSigmaIframe(): {
+    iframeRef: react.RefObject<HTMLIFrameElement>;
+    loading: boolean;
+    error: WorkbookErrorEvent | null;
+};
 
-export { useWorkbookError, useWorkbookLoaded };
+export { type OnError, type OnLoaded, useSigmaIframe, useWorkbookError, useWorkbookLoaded };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  useSigmaIframe: () => useSigmaIframe,
   useWorkbookError: () => useWorkbookError,
   useWorkbookLoaded: () => useWorkbookLoaded
 });
@@ -50,8 +51,22 @@ function useWorkbookError(iframeRef, onError) {
     return () => window.removeEventListener("message", listener);
   }, [iframeRef, onError]);
 }
+function useSigmaIframe() {
+  const iframeRef = (0, import_react.useRef)(null);
+  const [loading, setLoading] = (0, import_react.useState)(true);
+  const [error, setError] = (0, import_react.useState)(null);
+  const loadingCallback = (0, import_react.useCallback)(() => setLoading(false), []);
+  const errorCallback = (0, import_react.useCallback)((event) => {
+    setError(event);
+    setLoading(false);
+  }, []);
+  useWorkbookLoaded(iframeRef, loadingCallback);
+  useWorkbookError(iframeRef, errorCallback);
+  return { iframeRef, loading, error };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  useSigmaIframe,
   useWorkbookError,
   useWorkbookLoaded
 });

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-import { useEffect } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
   workbookErrorListener,
   workbookLoadedListener
@@ -28,7 +28,21 @@ function useWorkbookError(iframeRef, onError) {
     return () => window.removeEventListener("message", listener);
   }, [iframeRef, onError]);
 }
+function useSigmaIframe() {
+  const iframeRef = useRef(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const loadingCallback = useCallback(() => setLoading(false), []);
+  const errorCallback = useCallback((event) => {
+    setError(event);
+    setLoading(false);
+  }, []);
+  useWorkbookLoaded(iframeRef, loadingCallback);
+  useWorkbookError(iframeRef, errorCallback);
+  return { iframeRef, loading, error };
+}
 export {
+  useSigmaIframe,
   useWorkbookError,
   useWorkbookLoaded
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigmacomputing/react-embed-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "React JavaScript SDK to interact with Sigma Computing's Embed API",
   "scripts": {
     "prepublish": "npm run build",
@@ -23,11 +23,12 @@
     "react-dom": "^16.8 || ^17 || ^18"
   },
   "devDependencies": {
+    "@sigmacomputing/typescript-config": "*",
     "@types/react": "^18.2.66",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "dependencies": {
-    "@sigmacomputing/embed-sdk": "^0.2.0"
+    "@sigmacomputing/embed-sdk": "latest"
   }
 }