talkjs · Asha20 · Nov 3, 2023 · Nov 3, 2023 · Nov 3, 2023 · Nov 29, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## v0.1.4
+
+- Add `<HtmlPanel>` component
+
 ## v0.1.3
 
 - Add `signature?: string` prop to `Session`

diff --git a/README.md b/README.md
@@ -274,13 +274,28 @@ Accepted props:
   loading
 - `chatboxRef` (resp. `inboxRef`, `popupRef`) - Pass a ref (created with `useRef`) and it'll be set to the vanilla JS [Chatbox](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/) (resp. [Inbox](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/), [Popup](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Popup/)) instance. See [above](#using-refs) for an example.
 - All [Talk.ChatboxOptions](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Session/#ChatboxOptions)
+- `children?: ReactNode` - Optional. You can provide an `<HtmlPanel>` component as a child to use [HTML Panels](https://talkjs.com/docs/Features/Customizations/HTML_Panels/).
 
 Accepted events (props that start with "on"):
 
 - All events accepted by [`Talk.Chatbox`](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Chatbox/#Chatbox__methods) (resp. [Inbox](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/#Inbox__methods), [Popup](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Popup/#Popup__methods))
 
 Note: For `<Chatbox>` and `<Popup>`, you must provide exactly one of `conversationId` and `syncConversation`. For `<Inbox>`, leaving both unset selects the latest conversation this user participates in (if any). See [Inbox.select](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Inbox/#Inbox__select) for more information.
 
+### `<HtmlPanel>`
+
+Accepted props:
+
+- `url: string` - The URL you want to load inside the HTML panel. The URL can be absolute or relative. We recommend using same origin pages to have better control of the page. Learn more about HTML Panels and same origin pages [here](https://talkjs.com/docs/Features/Customizations/HTML_Panels/)
+
+- `height?: number` - Optional. The panel height in pixels. Defaults to `100px`.
+
+- `show?: boolean` - Optional. Sets the visibility of the panel. Defaults to `true`.
+
+- `conversationId?: string` - Optional. If given, the panel will only show up for the conversation that has an `id` matching the one given.
+
+- `children: React.ReactNode` - The content that gets rendered inside the `<body>` of the panel.
+
 
 ## Contributing
 

diff --git a/example/App.tsx b/example/App.tsx
@@ -1,6 +1,6 @@
 import "./App.css";
 
-import { Session, Chatbox } from "../lib/main";
+import { Session, Chatbox, HtmlPanel } from "../lib/main";
 import Talk from "talkjs";
 import { ChangeEvent, useCallback, useMemo, useRef, useState } from "react";
 
@@ -104,6 +104,9 @@ function App() {
     setDn(JSON.parse(event.target!.value));
   }, []);
 
+  const [panelHeight, setPanelHeight] = useState(100);
+  const [panelVisible, setPanelVisible] = useState(true);
+
   if (typeof import.meta.env.VITE_APP_ID !== "string") {
     return (
       <div style={{ maxWidth: "50em" }}>
@@ -150,8 +153,23 @@ function App() {
           loadingComponent={<span>LOADING....</span>}
           {...(blur ? { onBlur } : {})}
           style={{ width: 500, height: 600 }}
-        />
+        >
+          <HtmlPanel
+            url="/example/panel.html"
+            height={panelHeight}
+            show={panelVisible}
+          >
+            I am an HTML panel.
+            <button
+              onClick={() => setPanelHeight(panelHeight > 100 ? 100 : 150)}
+            >
+              Toggle panel height
+            </button>
+            <button onClick={() => setPanelVisible(false)}>Hide panel</button>
+          </HtmlPanel>
+        </Chatbox>
       </Session>
+
       <button onClick={otherMe}>switch user (new session)</button>
       <br />
       <button onClick={switchConv}>

diff --git a/example/panel.html b/example/panel.html
@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Document</title>
+    <style>
+      body {
+        background-color: lightblue;
+      }
+      button {
+        display: block;
+        width: 10rem;
+        margin: 0.6rem auto;
+      }
+    </style>
+  </head>
+  <body></body>
+</html>
diff --git a/lib/HtmlPanel.tsx b/lib/HtmlPanel.tsx
@@ -0,0 +1,94 @@
+import { useContext, useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import Talk from "talkjs";
+import { BoxContext } from "./MountedBox";
+
+type HtmlPanelProps = {
+  /**
+   * The URL you want to load inside the HTML panel. The URL can be absolute or
+   * relative. We recommend using same origin pages to have better control of
+   * the page. Learn more about HTML Panels and same origin pages {@link https://talkjs.com/docs/Features/Customizations/HTML_Panels/ | here}.
+   */
+  url: string;
+
+  /** The panel height in pixels. Defaults to `100px`. */
+  height?: number;
+
+  /** Sets the visibility of the panel. Defaults to `true`. */
+  show?: boolean;
+
+  /** If given, the panel will only show up for the conversation that has an `id` matching the one given. */
+  conversationId?: string;
+
+  /** The content that gets rendered inside the `<body>` of the panel. */
+  children: React.ReactNode;
+};
+
+type State =
+  | { type: "none" }
+  | { type: "loading" }
+  | { type: "loaded"; panel: Talk.HtmlPanel };
+
+export function HtmlPanel({
+  url,
+  height = 100,
+  show = true,
+  conversationId,
+  children,
+}: HtmlPanelProps) {
+  const [state, setState] = useState<State>({ type: "none" });
+  const box = useContext(BoxContext);
+
+  useEffect(() => {
+    async function run() {
+      if (state.type !== "none" || !box) return;
+
+      setState({ type: "loading" });
+      const panel = await box.createHtmlPanel({
+        url,
+        conversation: conversationId,
+        height,
+        show,
+      });
+      await panel.windowLoadedPromise;
+      setState({ type: "loaded", panel });
+    }
+
+    run();
+
+    return () => {
+      if (state.type === "loaded") {
+        state.panel.destroy();
+        setState({ type: "none" });
+      }
+    };
+    // We intentionally exclude `height` and `show` from the dependency array so
+    // that we update them later via methods instead of by re-creating the
+    // entire panel from scratch each time.
+    //
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state, url, box, conversationId]);
+
+  useEffect(() => {
+    if (state.type === "loaded") {
+      state.panel.setHeight(height);
+    }
+  }, [state, height]);
+
+  useEffect(() => {
+    if (state.type === "loaded") {
+      if (show) {
+        state.panel.show();
+      } else {
+        state.panel.hide();
+      }
+    }
+  }, [state, show]);
+
+  return (
+    <>
+      {state.type === "loaded" &&
+        createPortal(children, state.panel.window.document.body)}
+    </>
+  );
+}
diff --git a/lib/MountedBox.tsx b/lib/MountedBox.tsx
@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode, useRef } from "react";
+import React, { CSSProperties, ReactNode, useRef } from "react";
 import type Talk from "talkjs";
 import { EventListeners } from "./EventListeners";
 import { useMountBox } from "./hooks";
@@ -11,31 +11,37 @@ interface Props {
   className?: string;
 
   handlers: Record<`on${string}`, Func>;
+  children?: React.ReactNode;
 }
 
 /**
  * Mounts the given `UIBox` and attaches event handlers to it. Renders a
  * `loadingComponent` fallback until the mount is complete.
  */
 export function MountedBox(props: Props & { session: Talk.Session }) {
-  const { box, loadingComponent, className, handlers } = props;
+  const { box, loadingComponent, className, children, handlers } = props;
 
   const ref = useRef<HTMLDivElement>(null);
   const mounted = useMountBox(box, ref.current);
 
   const style = mounted ? props.style : { ...props.style, display: "none" };
 
   return (
-    <>
+    <BoxContext.Provider value={box}>
       {!mounted && (
         <div style={props.style} className={className}>
           {loadingComponent}
         </div>
       )}
 
       <div ref={ref} style={style} className={className} />
+      {children}
 
       <EventListeners target={box} handlers={handlers} />
-    </>
+    </BoxContext.Provider>
   );
 }
+
+export const BoxContext = React.createContext<Talk.UIBox | undefined>(
+  undefined,
+);
diff --git a/lib/main.tsx b/lib/main.tsx
@@ -4,3 +4,4 @@ export { Chatbox } from "./ui/Chatbox";
 export { Inbox } from "./ui/Inbox";
 export { Popup } from "./ui/Popup";
 export { useSession } from "./SessionContext";
+export { HtmlPanel } from "./HtmlPanel";
diff --git a/lib/ui/Chatbox.tsx b/lib/ui/Chatbox.tsx
@@ -13,6 +13,7 @@ type ChatboxProps = UIBoxProps<Talk.Chatbox> &
     loadingComponent?: ReactNode;
     style?: CSSProperties;
     className?: string;
+    children?: React.ReactNode;
   };
 
 export function Chatbox(props: ChatboxProps) {
@@ -39,6 +40,7 @@ function ActiveChatbox(props: ChatboxProps & { session: Talk.Session }) {
     style,
     className,
     loadingComponent,
+    children,
     ...optionsAndEvents
   } = props;
 
@@ -60,6 +62,7 @@ function ActiveChatbox(props: ChatboxProps & { session: Talk.Session }) {
       style={style}
       loadingComponent={loadingComponent}
       handlers={events}
+      children={children}
     />
   );
 }
diff --git a/package.json b/package.json
@@ -28,7 +28,7 @@
     "url": "https://github.com/talkjs/talkjs-react/issues"
   },
   "homepage": "https://talkjs.com",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "files": [
     "dist"