@aspectly/web 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2022 Zhan Isaakian
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @aspectly/web
+
+React hooks for embedding iframes and communicating with them using the Aspectly bridge protocol.
+
+## Installation
+
+```bash
+# npm
+npm install @aspectly/web
+
+# pnpm
+pnpm add @aspectly/web
+
+# yarn
+yarn add @aspectly/web
+```
+
+## Overview
+
+`@aspectly/web` provides React hooks for the parent page to embed iframes and establish bidirectional communication with them. The iframe content should use `@aspectly/core` to communicate back.
+
+## Quick Start
+
+### Parent Page (Host)
+
+```tsx
+import { useAspectlyIframe } from '@aspectly/web';
+
+function App() {
+  const [bridge, loaded, Iframe] = useAspectlyIframe({
+    url: 'https://example.com/widget'
+  });
+
+  useEffect(() => {
+    if (loaded) {
+      // Initialize bridge with handlers
+      bridge.init({
+        getUser: async () => ({ name: 'John', id: 123 }),
+        saveData: async (params) => {
+          console.log('Saving:', params);
+          return { success: true };
+        }
+      });
+    }
+  }, [loaded, bridge]);
+
+  const handleSendMessage = async () => {
+    try {
+      const result = await bridge.send('greet', { name: 'World' });
+      console.log('Response:', result);
+    } catch (error) {
+      console.error('Error:', error);
+    }
+  };
+
+  return (
+    <div>
+      <h1>Parent App</h1>
+      <Iframe style={{ width: '100%', height: 400 }} />
+      <button onClick={handleSendMessage} disabled={!loaded}>
+        Send Message
+      </button>
+    </div>
+  );
+}
+```
+
+### iframe Content (Widget)
+
+The iframe should use `@aspectly/core`:
+
+```typescript
+// Inside the iframe
+import { AspectlyBridge } from '@aspectly/core';
+
+const bridge = new AspectlyBridge();
+
+// Initialize with handlers
+await bridge.init({
+  greet: async (params: { name: string }) => {
+    return { message: `Hello, ${params.name}!` };
+  }
+});
+
+// Call parent methods
+const user = await bridge.send('getUser');
+console.log('User:', user);
+```
+
+## API Reference
+
+### useAspectlyIframe
+
+```typescript
+const [bridge, loaded, IframeComponent] = useAspectlyIframe(options);
+```
+
+#### Options
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `url` | `string` | Yes | URL to load in the iframe |
+| `timeout` | `number` | No | Handler execution timeout in ms (default: 100000) |
+
+#### Returns
+
+| Index | Type | Description |
+|-------|------|-------------|
+| 0 | `BridgeBase` | Bridge instance for communication |
+| 1 | `boolean` | Whether the iframe has finished loading |
+| 2 | `FunctionComponent` | React component to render the iframe |
+
+### IframeComponent Props
+
+The returned iframe component accepts all standard `<iframe>` HTML attributes plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `style` | `CSSProperties` | Custom styles (border: 0 is applied by default) |
+| `onError` | `(error: unknown) => void` | Optional error handler |
+
+## Patterns
+
+### Checking Method Support
+
+```tsx
+const handleAction = async () => {
+  if (bridge.supports('advancedFeature')) {
+    await bridge.send('advancedFeature', { data: 'value' });
+  } else {
+    // Fallback for older widget versions
+    await bridge.send('basicFeature', { data: 'value' });
+  }
+};
+```
+
+### Subscribing to Events
+
+```tsx
+useEffect(() => {
+  const handleEvent = (result) => {
+    console.log('Bridge event:', result.method, result.data);
+  };
+
+  bridge.subscribe(handleEvent);
+
+  return () => bridge.unsubscribe(handleEvent);
+}, [bridge]);
+```
+
+### Error Handling
+
+```tsx
+import { BridgeErrorType } from '@aspectly/web';
+
+const handleSend = async () => {
+  try {
+    await bridge.send('action', { data: 'value' });
+  } catch (error) {
+    if (error.error_type === BridgeErrorType.BRIDGE_NOT_AVAILABLE) {
+      console.log('Widget not ready yet');
+    } else if (error.error_type === BridgeErrorType.UNSUPPORTED_METHOD) {
+      console.log('Method not supported by widget');
+    }
+  }
+};
+```
+
+## Security Considerations
+
+- The bridge uses `postMessage` for communication
+- By default, messages are sent with `'*'` origin - consider restricting this in production
+- Always validate incoming data in your handlers
+- Use HTTPS for iframe sources in production
+
+## Related Packages
+
+- [`@aspectly/core`](../core) - Core bridge framework (used inside iframes)
+- [`@aspectly/react-native`](../react-native) - React Native WebView integration
+- [`@aspectly/react-native-web`](../react-native-web) - React Native Web + iframe support
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+import { FunctionComponent, IframeHTMLAttributes, CSSProperties } from 'react';
+import { BridgeOptions, BridgeBase } from '@aspectly/core';
+export { AspectlyBridge, BridgeBase, BridgeErrorType, BridgeEventType, BridgeHandler, BridgeHandlers, BridgeListener, BridgeOptions, BridgeResultError, BridgeResultEvent, BridgeResultType } from '@aspectly/core';
+
+/**
+ * Options for the useAspectlyIframe hook
+ */
+interface UseAspectlyIframeOptions extends BridgeOptions {
+    /** URL to load in the iframe */
+    url: string;
+}
+/**
+ * Props for the iframe component
+ */
+interface AspectlyIframeProps extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'src' | 'onLoad'> {
+    /** Optional error handler */
+    onError?: (error: unknown) => void;
+    /** Custom styles */
+    style?: CSSProperties;
+}
+/**
+ * Return type for useAspectlyIframe hook
+ */
+type UseAspectlyIframeReturn = [
+    /** Bridge instance for communication */
+    bridge: BridgeBase,
+    /** Whether the iframe has loaded */
+    loaded: boolean,
+    /** React component to render the iframe */
+    IframeComponent: FunctionComponent<AspectlyIframeProps>
+];
+/**
+ * React hook for embedding an iframe and communicating with it via Aspectly bridge.
+ *
+ * @example
+ * ```tsx
+ * import { useAspectlyIframe } from '@aspectly/web';
+ *
+ * function App() {
+ *   const [bridge, loaded, Iframe] = useAspectlyIframe({
+ *     url: 'https://example.com/widget'
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (loaded) {
+ *       bridge.init({
+ *         getData: async () => ({ user: 'John' })
+ *       });
+ *     }
+ *   }, [loaded, bridge]);
+ *
+ *   const handleClick = async () => {
+ *     const result = await bridge.send('greet', { name: 'World' });
+ *     console.log(result);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <Iframe style={{ width: '100%', height: 400 }} />
+ *       <button onClick={handleClick}>Send Message</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useAspectlyIframe: ({ url, timeout, }: UseAspectlyIframeOptions) => UseAspectlyIframeReturn;
+
+export { type AspectlyIframeProps, type UseAspectlyIframeOptions, type UseAspectlyIframeReturn, useAspectlyIframe };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { FunctionComponent, IframeHTMLAttributes, CSSProperties } from 'react';
+import { BridgeOptions, BridgeBase } from '@aspectly/core';
+export { AspectlyBridge, BridgeBase, BridgeErrorType, BridgeEventType, BridgeHandler, BridgeHandlers, BridgeListener, BridgeOptions, BridgeResultError, BridgeResultEvent, BridgeResultType } from '@aspectly/core';
+
+/**
+ * Options for the useAspectlyIframe hook
+ */
+interface UseAspectlyIframeOptions extends BridgeOptions {
+    /** URL to load in the iframe */
+    url: string;
+}
+/**
+ * Props for the iframe component
+ */
+interface AspectlyIframeProps extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'src' | 'onLoad'> {
+    /** Optional error handler */
+    onError?: (error: unknown) => void;
+    /** Custom styles */
+    style?: CSSProperties;
+}
+/**
+ * Return type for useAspectlyIframe hook
+ */
+type UseAspectlyIframeReturn = [
+    /** Bridge instance for communication */
+    bridge: BridgeBase,
+    /** Whether the iframe has loaded */
+    loaded: boolean,
+    /** React component to render the iframe */
+    IframeComponent: FunctionComponent<AspectlyIframeProps>
+];
+/**
+ * React hook for embedding an iframe and communicating with it via Aspectly bridge.
+ *
+ * @example
+ * ```tsx
+ * import { useAspectlyIframe } from '@aspectly/web';
+ *
+ * function App() {
+ *   const [bridge, loaded, Iframe] = useAspectlyIframe({
+ *     url: 'https://example.com/widget'
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (loaded) {
+ *       bridge.init({
+ *         getData: async () => ({ user: 'John' })
+ *       });
+ *     }
+ *   }, [loaded, bridge]);
+ *
+ *   const handleClick = async () => {
+ *     const result = await bridge.send('greet', { name: 'World' });
+ *     console.log(result);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <Iframe style={{ width: '100%', height: 400 }} />
+ *       <button onClick={handleClick}>Send Message</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const useAspectlyIframe: ({ url, timeout, }: UseAspectlyIframeOptions) => UseAspectlyIframeReturn;
+
+export { type AspectlyIframeProps, type UseAspectlyIframeOptions, type UseAspectlyIframeReturn, useAspectlyIframe };

package/dist/index.js

@@ -0,0 +1,71 @@
+'use strict';
+
+var react = require('react');
+var core = require('@aspectly/core');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/useAspectlyIframe.tsx
+var useAspectlyIframe = ({
+  url,
+  timeout
+}) => {
+  const iframeRef = react.useRef(null);
+  const [loaded, setLoaded] = react.useState(false);
+  const bridge = react.useMemo(() => {
+    return new core.BridgeInternal((event) => {
+      const bridgeEvent = core.BridgeCore.wrapBridgeEvent(event);
+      iframeRef.current?.contentWindow?.postMessage(bridgeEvent, "*");
+    }, { timeout });
+  }, [timeout]);
+  const publicBridge = react.useMemo(() => new core.BridgeBase(bridge), [bridge]);
+  react.useEffect(() => {
+    const unsubscribe = core.BridgeCore.subscribe(
+      bridge.handleCoreEvent
+    );
+    return () => unsubscribe();
+  }, [bridge]);
+  const onLoad = react.useCallback(() => setLoaded(true), []);
+  const IframeComponent = react.useCallback(
+    ({ style, ...props }) => {
+      return /* @__PURE__ */ jsxRuntime.jsx(
+        "iframe",
+        {
+          ...props,
+          onLoad,
+          ref: iframeRef,
+          style: {
+            border: 0,
+            ...style
+          },
+          src: url
+        }
+      );
+    },
+    [url, onLoad]
+  );
+  return [publicBridge, loaded, IframeComponent];
+};
+
+Object.defineProperty(exports, "AspectlyBridge", {
+  enumerable: true,
+  get: function () { return core.AspectlyBridge; }
+});
+Object.defineProperty(exports, "BridgeBase", {
+  enumerable: true,
+  get: function () { return core.BridgeBase; }
+});
+Object.defineProperty(exports, "BridgeErrorType", {
+  enumerable: true,
+  get: function () { return core.BridgeErrorType; }
+});
+Object.defineProperty(exports, "BridgeEventType", {
+  enumerable: true,
+  get: function () { return core.BridgeEventType; }
+});
+Object.defineProperty(exports, "BridgeResultType", {
+  enumerable: true,
+  get: function () { return core.BridgeResultType; }
+});
+exports.useAspectlyIframe = useAspectlyIframe;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useAspectlyIframe.tsx"],"names":["useRef","useState","useMemo","BridgeInternal","BridgeCore","BridgeBase","useEffect","useCallback","jsx"],"mappings":";;;;;;;AAkFO,IAAM,oBAAoB,CAAC;AAAA,EAChC,GAAA;AAAA,EACA;AACF,CAAA,KAAyD;AACvD,EAAA,MAAM,SAAA,GAAYA,aAA0B,IAAI,CAAA;AAChD,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAIC,eAAkB,KAAK,CAAA;AAEnD,EAAA,MAAM,MAAA,GAASC,cAAQ,MAAM;AAC3B,IAAA,OAAO,IAAIC,mBAAA,CAAe,CAAC,KAAA,KAAwB;AACjD,MAAA,MAAM,WAAA,GAAcC,eAAA,CAAW,eAAA,CAAgB,KAAK,CAAA;AACpD,MAAA,SAAA,CAAU,OAAA,EAAS,aAAA,EAAe,WAAA,CAAY,WAAA,EAAa,GAAG,CAAA;AAAA,IAChE,CAAA,EAAG,EAAE,OAAA,EAAS,CAAA;AAAA,EAChB,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,MAAM,YAAA,GAAeF,cAAQ,MAAM,IAAIG,gBAAW,MAAM,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEnE,EAAAC,eAAA,CAAU,MAAM;AACd,IAAA,MAAM,cAAcF,eAAA,CAAW,SAAA;AAAA,MAC7B,MAAA,CAAO;AAAA,KACT;AACA,IAAA,OAAO,MAAM,WAAA,EAAY;AAAA,EAC3B,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,MAAM,SAASG,iBAAA,CAAY,MAAM,UAAU,IAAI,CAAA,EAAG,EAAE,CAAA;AAEpD,EAAA,MAAM,eAAA,GAA0DA,iBAAA;AAAA,IAC9D,CAAC,EAAE,KAAA,EAAO,GAAG,OAAM,KAA2B;AAC5C,MAAA,uBACEC,cAAA;AAAA,QAAC,QAAA;AAAA,QAAA;AAAA,UACE,GAAG,KAAA;AAAA,UACJ,MAAA;AAAA,UACA,GAAA,EAAK,SAAA;AAAA,UACL,KAAA,EAAO;AAAA,YACL,MAAA,EAAQ,CAAA;AAAA,YACR,GAAG;AAAA,WACL;AAAA,UACA,GAAA,EAAK;AAAA;AAAA,OACP;AAAA,IAEJ,CAAA;AAAA,IACA,CAAC,KAAK,MAAM;AAAA,GACd;AAEA,EAAA,OAAO,CAAC,YAAA,EAAc,MAAA,EAAQ,eAAe,CAAA;AAC/C","file":"index.js","sourcesContent":["import {\n  FunctionComponent,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  CSSProperties,\n  IframeHTMLAttributes,\n} from 'react';\nimport {\n  BridgeCore,\n  BridgeInternal,\n  BridgeBase,\n  BridgeOptions,\n} from '@aspectly/core';\n\n/**\n * Options for the useAspectlyIframe hook\n */\nexport interface UseAspectlyIframeOptions extends BridgeOptions {\n  /** URL to load in the iframe */\n  url: string;\n}\n\n/**\n * Props for the iframe component\n */\nexport interface AspectlyIframeProps\n  extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'src' | 'onLoad'> {\n  /** Optional error handler */\n  onError?: (error: unknown) => void;\n  /** Custom styles */\n  style?: CSSProperties;\n}\n\n/**\n * Return type for useAspectlyIframe hook\n */\nexport type UseAspectlyIframeReturn = [\n  /** Bridge instance for communication */\n  bridge: BridgeBase,\n  /** Whether the iframe has loaded */\n  loaded: boolean,\n  /** React component to render the iframe */\n  IframeComponent: FunctionComponent<AspectlyIframeProps>\n];\n\n/**\n * React hook for embedding an iframe and communicating with it via Aspectly bridge.\n *\n * @example\n * ```tsx\n * import { useAspectlyIframe } from '@aspectly/web';\n *\n * function App() {\n *   const [bridge, loaded, Iframe] = useAspectlyIframe({\n *     url: 'https://example.com/widget'\n *   });\n *\n *   useEffect(() => {\n *     if (loaded) {\n *       bridge.init({\n *         getData: async () => ({ user: 'John' })\n *       });\n *     }\n *   }, [loaded, bridge]);\n *\n *   const handleClick = async () => {\n *     const result = await bridge.send('greet', { name: 'World' });\n *     console.log(result);\n *   };\n *\n *   return (\n *     <div>\n *       <Iframe style={{ width: '100%', height: 400 }} />\n *       <button onClick={handleClick}>Send Message</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport const useAspectlyIframe = ({\n  url,\n  timeout,\n}: UseAspectlyIframeOptions): UseAspectlyIframeReturn => {\n  const iframeRef = useRef<HTMLIFrameElement>(null);\n  const [loaded, setLoaded] = useState<boolean>(false);\n\n  const bridge = useMemo(() => {\n    return new BridgeInternal((event: object): void => {\n      const bridgeEvent = BridgeCore.wrapBridgeEvent(event);\n      iframeRef.current?.contentWindow?.postMessage(bridgeEvent, '*');\n    }, { timeout });\n  }, [timeout]);\n\n  const publicBridge = useMemo(() => new BridgeBase(bridge), [bridge]);\n\n  useEffect(() => {\n    const unsubscribe = BridgeCore.subscribe(\n      bridge.handleCoreEvent as (event: unknown) => void\n    );\n    return () => unsubscribe();\n  }, [bridge]);\n\n  const onLoad = useCallback(() => setLoaded(true), []);\n\n  const IframeComponent: FunctionComponent<AspectlyIframeProps> = useCallback(\n    ({ style, ...props }: AspectlyIframeProps) => {\n      return (\n        <iframe\n          {...props}\n          onLoad={onLoad}\n          ref={iframeRef}\n          style={{\n            border: 0,\n            ...style,\n          }}\n          src={url}\n        />\n      );\n    },\n    [url, onLoad]\n  );\n\n  return [publicBridge, loaded, IframeComponent];\n};\n"]}

package/dist/index.mjs

@@ -0,0 +1,50 @@
+import { useRef, useState, useMemo, useEffect, useCallback } from 'react';
+import { BridgeInternal, BridgeCore, BridgeBase } from '@aspectly/core';
+export { AspectlyBridge, BridgeBase, BridgeErrorType, BridgeEventType, BridgeResultType } from '@aspectly/core';
+import { jsx } from 'react/jsx-runtime';
+
+// src/useAspectlyIframe.tsx
+var useAspectlyIframe = ({
+  url,
+  timeout
+}) => {
+  const iframeRef = useRef(null);
+  const [loaded, setLoaded] = useState(false);
+  const bridge = useMemo(() => {
+    return new BridgeInternal((event) => {
+      const bridgeEvent = BridgeCore.wrapBridgeEvent(event);
+      iframeRef.current?.contentWindow?.postMessage(bridgeEvent, "*");
+    }, { timeout });
+  }, [timeout]);
+  const publicBridge = useMemo(() => new BridgeBase(bridge), [bridge]);
+  useEffect(() => {
+    const unsubscribe = BridgeCore.subscribe(
+      bridge.handleCoreEvent
+    );
+    return () => unsubscribe();
+  }, [bridge]);
+  const onLoad = useCallback(() => setLoaded(true), []);
+  const IframeComponent = useCallback(
+    ({ style, ...props }) => {
+      return /* @__PURE__ */ jsx(
+        "iframe",
+        {
+          ...props,
+          onLoad,
+          ref: iframeRef,
+          style: {
+            border: 0,
+            ...style
+          },
+          src: url
+        }
+      );
+    },
+    [url, onLoad]
+  );
+  return [publicBridge, loaded, IframeComponent];
+};
+
+export { useAspectlyIframe };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useAspectlyIframe.tsx"],"names":[],"mappings":";;;;;;AAkFO,IAAM,oBAAoB,CAAC;AAAA,EAChC,GAAA;AAAA,EACA;AACF,CAAA,KAAyD;AACvD,EAAA,MAAM,SAAA,GAAY,OAA0B,IAAI,CAAA;AAChD,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,SAAkB,KAAK,CAAA;AAEnD,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAM;AAC3B,IAAA,OAAO,IAAI,cAAA,CAAe,CAAC,KAAA,KAAwB;AACjD,MAAA,MAAM,WAAA,GAAc,UAAA,CAAW,eAAA,CAAgB,KAAK,CAAA;AACpD,MAAA,SAAA,CAAU,OAAA,EAAS,aAAA,EAAe,WAAA,CAAY,WAAA,EAAa,GAAG,CAAA;AAAA,IAChE,CAAA,EAAG,EAAE,OAAA,EAAS,CAAA;AAAA,EAChB,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,MAAM,YAAA,GAAe,QAAQ,MAAM,IAAI,WAAW,MAAM,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEnE,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,MAAM,cAAc,UAAA,CAAW,SAAA;AAAA,MAC7B,MAAA,CAAO;AAAA,KACT;AACA,IAAA,OAAO,MAAM,WAAA,EAAY;AAAA,EAC3B,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,MAAM,SAAS,WAAA,CAAY,MAAM,UAAU,IAAI,CAAA,EAAG,EAAE,CAAA;AAEpD,EAAA,MAAM,eAAA,GAA0D,WAAA;AAAA,IAC9D,CAAC,EAAE,KAAA,EAAO,GAAG,OAAM,KAA2B;AAC5C,MAAA,uBACE,GAAA;AAAA,QAAC,QAAA;AAAA,QAAA;AAAA,UACE,GAAG,KAAA;AAAA,UACJ,MAAA;AAAA,UACA,GAAA,EAAK,SAAA;AAAA,UACL,KAAA,EAAO;AAAA,YACL,MAAA,EAAQ,CAAA;AAAA,YACR,GAAG;AAAA,WACL;AAAA,UACA,GAAA,EAAK;AAAA;AAAA,OACP;AAAA,IAEJ,CAAA;AAAA,IACA,CAAC,KAAK,MAAM;AAAA,GACd;AAEA,EAAA,OAAO,CAAC,YAAA,EAAc,MAAA,EAAQ,eAAe,CAAA;AAC/C","file":"index.mjs","sourcesContent":["import {\n  FunctionComponent,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  CSSProperties,\n  IframeHTMLAttributes,\n} from 'react';\nimport {\n  BridgeCore,\n  BridgeInternal,\n  BridgeBase,\n  BridgeOptions,\n} from '@aspectly/core';\n\n/**\n * Options for the useAspectlyIframe hook\n */\nexport interface UseAspectlyIframeOptions extends BridgeOptions {\n  /** URL to load in the iframe */\n  url: string;\n}\n\n/**\n * Props for the iframe component\n */\nexport interface AspectlyIframeProps\n  extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'src' | 'onLoad'> {\n  /** Optional error handler */\n  onError?: (error: unknown) => void;\n  /** Custom styles */\n  style?: CSSProperties;\n}\n\n/**\n * Return type for useAspectlyIframe hook\n */\nexport type UseAspectlyIframeReturn = [\n  /** Bridge instance for communication */\n  bridge: BridgeBase,\n  /** Whether the iframe has loaded */\n  loaded: boolean,\n  /** React component to render the iframe */\n  IframeComponent: FunctionComponent<AspectlyIframeProps>\n];\n\n/**\n * React hook for embedding an iframe and communicating with it via Aspectly bridge.\n *\n * @example\n * ```tsx\n * import { useAspectlyIframe } from '@aspectly/web';\n *\n * function App() {\n *   const [bridge, loaded, Iframe] = useAspectlyIframe({\n *     url: 'https://example.com/widget'\n *   });\n *\n *   useEffect(() => {\n *     if (loaded) {\n *       bridge.init({\n *         getData: async () => ({ user: 'John' })\n *       });\n *     }\n *   }, [loaded, bridge]);\n *\n *   const handleClick = async () => {\n *     const result = await bridge.send('greet', { name: 'World' });\n *     console.log(result);\n *   };\n *\n *   return (\n *     <div>\n *       <Iframe style={{ width: '100%', height: 400 }} />\n *       <button onClick={handleClick}>Send Message</button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport const useAspectlyIframe = ({\n  url,\n  timeout,\n}: UseAspectlyIframeOptions): UseAspectlyIframeReturn => {\n  const iframeRef = useRef<HTMLIFrameElement>(null);\n  const [loaded, setLoaded] = useState<boolean>(false);\n\n  const bridge = useMemo(() => {\n    return new BridgeInternal((event: object): void => {\n      const bridgeEvent = BridgeCore.wrapBridgeEvent(event);\n      iframeRef.current?.contentWindow?.postMessage(bridgeEvent, '*');\n    }, { timeout });\n  }, [timeout]);\n\n  const publicBridge = useMemo(() => new BridgeBase(bridge), [bridge]);\n\n  useEffect(() => {\n    const unsubscribe = BridgeCore.subscribe(\n      bridge.handleCoreEvent as (event: unknown) => void\n    );\n    return () => unsubscribe();\n  }, [bridge]);\n\n  const onLoad = useCallback(() => setLoaded(true), []);\n\n  const IframeComponent: FunctionComponent<AspectlyIframeProps> = useCallback(\n    ({ style, ...props }: AspectlyIframeProps) => {\n      return (\n        <iframe\n          {...props}\n          onLoad={onLoad}\n          ref={iframeRef}\n          style={{\n            border: 0,\n            ...style,\n          }}\n          src={url}\n        />\n      );\n    },\n    [url, onLoad]\n  );\n\n  return [publicBridge, loaded, IframeComponent];\n};\n"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@aspectly/web",
+  "version": "0.1.0",
+  "description": "Web/iframe integration for Aspectly bridge - React hooks for embedding and communicating with iframes",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "iframe",
+    "bridge",
+    "communication",
+    "react",
+    "hooks",
+    "postmessage",
+    "web"
+  ],
+  "author": "Zhan Isaakian <jeanisahkyan@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JeanIsahakyan/aspectly",
+    "directory": "packages/web"
+  },
+  "bugs": {
+    "url": "https://github.com/JeanIsahakyan/aspectly/issues"
+  },
+  "homepage": "https://github.com/JeanIsahakyan/aspectly/tree/main/packages/web#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "dependencies": {
+    "@aspectly/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.2",
+    "rimraf": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "clean": "rimraf dist",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Main exports
+export { useAspectlyIframe } from './useAspectlyIframe';
+
+// Type exports
+export type {
+  UseAspectlyIframeOptions,
+  UseAspectlyIframeReturn,
+  AspectlyIframeProps,
+} from './useAspectlyIframe';
+
+// Re-export core types for convenience
+export {
+  AspectlyBridge,
+  BridgeBase,
+  BridgeErrorType,
+  BridgeEventType,
+  BridgeResultType,
+} from '@aspectly/core';
+
+export type {
+  BridgeHandler,
+  BridgeHandlers,
+  BridgeListener,
+  BridgeOptions,
+  BridgeResultError,
+  BridgeResultEvent,
+} from '@aspectly/core';

package/src/useAspectlyIframe.test.tsx

@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useAspectlyIframe } from './useAspectlyIframe';
+
+// Mock @aspectly/core
+vi.mock('@aspectly/core', () => ({
+  BridgeCore: {
+    wrapBridgeEvent: vi.fn((event) => JSON.stringify({ type: 'BridgeEvent', event })),
+    subscribe: vi.fn().mockReturnValue(vi.fn()),
+  },
+  BridgeInternal: vi.fn().mockImplementation(() => ({
+    init: vi.fn().mockResolvedValue(true),
+    send: vi.fn().mockResolvedValue({}),
+    subscribe: vi.fn(),
+    unsubscribe: vi.fn(),
+    supports: vi.fn(),
+    isAvailable: vi.fn(),
+    handleCoreEvent: vi.fn(),
+  })),
+  BridgeBase: vi.fn().mockImplementation((internal) => ({
+    init: internal.init,
+    send: internal.send,
+    subscribe: internal.subscribe,
+    unsubscribe: internal.unsubscribe,
+    supports: internal.supports,
+    isAvailable: internal.isAvailable,
+  })),
+}));
+
+describe('useAspectlyIframe', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('hook return values', () => {
+    it('should return bridge, loaded state, and component', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [bridge, loaded, IframeComponent] = result.current;
+
+      expect(bridge).toBeDefined();
+      expect(typeof loaded).toBe('boolean');
+      expect(typeof IframeComponent).toBe('function');
+    });
+
+    it('should initially have loaded as false', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [, loaded] = result.current;
+      expect(loaded).toBe(false);
+    });
+  });
+
+  describe('bridge instance', () => {
+    it('should have init method', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [bridge] = result.current;
+      expect(typeof bridge.init).toBe('function');
+    });
+
+    it('should have send method', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [bridge] = result.current;
+      expect(typeof bridge.send).toBe('function');
+    });
+
+    it('should have subscribe method', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [bridge] = result.current;
+      expect(typeof bridge.subscribe).toBe('function');
+    });
+
+    it('should have unsubscribe method', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [bridge] = result.current;
+      expect(typeof bridge.unsubscribe).toBe('function');
+    });
+  });
+
+  describe('IframeComponent', () => {
+    it('should be a valid React component', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const [, , IframeComponent] = result.current;
+      expect(IframeComponent).toBeDefined();
+      expect(IframeComponent.name).toBeDefined();
+    });
+  });
+
+  describe('memoization', () => {
+    it('should return same bridge instance across re-renders', () => {
+      const { result, rerender } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const firstBridge = result.current[0];
+      rerender();
+      const secondBridge = result.current[0];
+
+      expect(firstBridge).toBe(secondBridge);
+    });
+
+    it('should return same component across re-renders with same url', () => {
+      const { result, rerender } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com' })
+      );
+
+      const firstComponent = result.current[2];
+      rerender();
+      const secondComponent = result.current[2];
+
+      expect(firstComponent).toBe(secondComponent);
+    });
+  });
+
+  describe('options', () => {
+    it('should accept timeout option', () => {
+      const { result } = renderHook(() =>
+        useAspectlyIframe({ url: 'https://example.com', timeout: 5000 })
+      );
+
+      expect(result.current).toBeDefined();
+    });
+  });
+});

package/src/useAspectlyIframe.tsx

@@ -0,0 +1,127 @@
+import {
+  FunctionComponent,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  CSSProperties,
+  IframeHTMLAttributes,
+} from 'react';
+import {
+  BridgeCore,
+  BridgeInternal,
+  BridgeBase,
+  BridgeOptions,
+} from '@aspectly/core';
+
+/**
+ * Options for the useAspectlyIframe hook
+ */
+export interface UseAspectlyIframeOptions extends BridgeOptions {
+  /** URL to load in the iframe */
+  url: string;
+}
+
+/**
+ * Props for the iframe component
+ */
+export interface AspectlyIframeProps
+  extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, 'src' | 'onLoad'> {
+  /** Optional error handler */
+  onError?: (error: unknown) => void;
+  /** Custom styles */
+  style?: CSSProperties;
+}
+
+/**
+ * Return type for useAspectlyIframe hook
+ */
+export type UseAspectlyIframeReturn = [
+  /** Bridge instance for communication */
+  bridge: BridgeBase,
+  /** Whether the iframe has loaded */
+  loaded: boolean,
+  /** React component to render the iframe */
+  IframeComponent: FunctionComponent<AspectlyIframeProps>
+];
+
+/**
+ * React hook for embedding an iframe and communicating with it via Aspectly bridge.
+ *
+ * @example
+ * ```tsx
+ * import { useAspectlyIframe } from '@aspectly/web';
+ *
+ * function App() {
+ *   const [bridge, loaded, Iframe] = useAspectlyIframe({
+ *     url: 'https://example.com/widget'
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (loaded) {
+ *       bridge.init({
+ *         getData: async () => ({ user: 'John' })
+ *       });
+ *     }
+ *   }, [loaded, bridge]);
+ *
+ *   const handleClick = async () => {
+ *     const result = await bridge.send('greet', { name: 'World' });
+ *     console.log(result);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <Iframe style={{ width: '100%', height: 400 }} />
+ *       <button onClick={handleClick}>Send Message</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useAspectlyIframe = ({
+  url,
+  timeout,
+}: UseAspectlyIframeOptions): UseAspectlyIframeReturn => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const [loaded, setLoaded] = useState<boolean>(false);
+
+  const bridge = useMemo(() => {
+    return new BridgeInternal((event: object): void => {
+      const bridgeEvent = BridgeCore.wrapBridgeEvent(event);
+      iframeRef.current?.contentWindow?.postMessage(bridgeEvent, '*');
+    }, { timeout });
+  }, [timeout]);
+
+  const publicBridge = useMemo(() => new BridgeBase(bridge), [bridge]);
+
+  useEffect(() => {
+    const unsubscribe = BridgeCore.subscribe(
+      bridge.handleCoreEvent as (event: unknown) => void
+    );
+    return () => unsubscribe();
+  }, [bridge]);
+
+  const onLoad = useCallback(() => setLoaded(true), []);
+
+  const IframeComponent: FunctionComponent<AspectlyIframeProps> = useCallback(
+    ({ style, ...props }: AspectlyIframeProps) => {
+      return (
+        <iframe
+          {...props}
+          onLoad={onLoad}
+          ref={iframeRef}
+          style={{
+            border: 0,
+            ...style,
+          }}
+          src={url}
+        />
+      );
+    },
+    [url, onLoad]
+  );
+
+  return [publicBridge, loaded, IframeComponent];
+};