chore: add jsdoc (#60)

* chore: add jsdoc * chore: add fallback for undefined bridge methods
gronxb · Jul 11, 2024 · 93a282e · 93a282e
1 parent 0ff0cd4
commit 93a282e
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 0 deletions.
diff --git a/packages/react-native/src/createWebView.tsx b/packages/react-native/src/createWebView.tsx
@@ -32,17 +32,88 @@ export type CreateWebViewArgs<
   BridgeObject extends Bridge,
   PostMessageSchema extends ParserSchema<any>,
 > = {
+  /**
+   * The bridge object to be used in the WebView.
+  * @example
+    import { createWebView, bridge } from "@webview-bridge/react-native";
+    import InAppBrowser from "react-native-inappbrowser-reborn";
+
+    // Register functions in the bridge object in your React Native code
+    export const appBridge = bridge({
+      async getMessage() {
+        return "Hello, I'm native";
+      },
+      async sum(a: number, b: number) {
+        return a + b;
+      },
+      async openInAppBrowser(url: string) {
+        if (await InAppBrowser.isAvailable()) {
+          await InAppBrowser.open(url);
+        }
+      },
+      // ... Add more functions as needed
+    });
+
+    export const { WebView } = createWebView({
+      bridge: appBridge,
+      debug: true, // Enable console.log visibility in the native WebView
+    });
+    */
   bridge: BridgeStore<BridgeObject>;
+  /**
+   * If `true`, the console.log visibility in the WebView is enabled.
+   * @default false
+   */
   debug?: boolean;
+  /**
+   * Set the timeout in milliseconds for the response from the web method.
+   * @default 2000
+   */
   responseTimeout?: number;
+  /**
+   * The schema for the postMessage method.
+   * @link https://gronxb.github.io/webview-bridge/using-a-post-message.html
+   */
   postMessageSchema?: PostMessageSchema;
+  /**
+   * Callback function when a method that is not defined in the bridge is called.
+   * @link https://gronxb.github.io/webview-bridge/backward-compatibility/new-method.html#react-native-part
+   */
   fallback?: (method: keyof BridgeObject) => void;
 };
 
 export type WebMethod<T> = T & {
   isReady: boolean;
 };
 
+/**
+ * Create a WebView component that can communicate with the bridge.
+ * @link https://gronxb.github.io/webview-bridge/getting-started.html
+ * @example
+    import { createWebView, bridge } from "@webview-bridge/react-native";
+    import InAppBrowser from "react-native-inappbrowser-reborn";
+
+    // Register functions in the bridge object in your React Native code
+    export const appBridge = bridge({
+      async getMessage() {
+        return "Hello, I'm native";
+      },
+      async sum(a: number, b: number) {
+        return a + b;
+      },
+      async openInAppBrowser(url: string) {
+        if (await InAppBrowser.isAvailable()) {
+          await InAppBrowser.open(url);
+        }
+      },
+      // ... Add more functions as needed
+    });
+
+    export const { WebView } = createWebView({
+      bridge: appBridge,
+      debug: true, // Enable console.log visibility in the native WebView
+    });
+ */
 export const createWebView = <
   BridgeObject extends Bridge,
   PostMessageSchema extends ParserSchema<any>,
@@ -71,6 +142,10 @@ export const createWebView = <
   });
 
   return {
+    /**
+     * Sends an event from React Native to the Web.
+     * @link https://gronxb.github.io/webview-bridge/using-a-post-message.html
+     */
     postMessage: <
       EventName extends KeyOfOrString<PostMessageSchema>,
       Args extends Parser<PostMessageSchema, EventName>,

diff --git a/packages/web/src/linkBridge.ts b/packages/web/src/linkBridge.ts
@@ -17,10 +17,29 @@ export interface LinkBridgeOptions<
   T extends BridgeStore<T extends Bridge ? T : any>,
   V extends ParserSchema<any>,
 > {
+  /**
+   * It is possible to configure `initialBridge` to operate in a non-React Native environment.
+   * Prioritize applying the bridge of the React Native WebView, and if it is unavailable, apply the `initialBridge`.
+   * Therefore, if `initialBridge` is configured, `bridge.isWebViewBridgeAvailable` should be true even in environments that are not React Native.
+   * @link https://gronxb.github.io/webview-bridge/non-react-native-environment.html
+   */
   initialBridge?: Partial<ExtractStore<T>>;
+  /**
+   * Set the timeout in milliseconds after calling the native method.
+   * @default 2000
+   */
   timeout?: number;
+  /**
+   * If `true`, an error will be thrown when calling a method that is not defined in the bridge.
+   */
   throwOnError?: boolean | (keyof ExtractStore<T>)[] | string[];
+  /**
+   * Callback function when a method that is not defined in the bridge is called.
+   */
   onFallback?: (methodName: string, args: unknown[]) => void;
+  /**
+   * Callback function when the bridge is ready.
+   */
   onReady?: (
     method: LinkBridge<
       ExcludePrimitive<ExtractStore<T>>,
@@ -35,6 +54,10 @@ type HydrateEventPayload = {
   nativeInitialState: PrimitiveObject;
 };
 
+/**
+ * Create a link to the bridge connected to the React Native WebView.
+ * @link https://gronxb.github.io/webview-bridge/getting-started.html
+ */
 export const linkBridge = <
   T extends BridgeStore<T extends Bridge ? T : any>,
   V extends ParserSchema<any> = ParserSchema<any>,