@fawadmahmoodwashmen/washmen-js-native-bridge 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Washmen
+
+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,237 @@
+# washmen-js-native-bridge
+
+Reusable **bidirectional JSON-RPC** bridge between a **React** site (running inside `react-native-webview`) and **React Native**.
+
+- **Protocol:** `wm: 2` with `rpc: 1` (web → native) and `rpc: 3` (web reply to native `invokeWebMethod`).
+- **Canonical implementation surface:** [`src/wm-webview-bridge.ts`](./src/wm-webview-bridge.ts) (bootstrap string, parsers, RN hook).
+
+Published to the **public npm registry** — default install, no `.npmrc` required.
+
+```bash
+npm install @fawadmahmoodwashmen/washmen-js-native-bridge
+```
+
+**Peer:** `react` ≥ 18. Optional: `react-native`, `react-native-webview` (RN app).
+
+**Entry points**
+
+| Import path | Use in |
+|-------------|--------|
+| `@fawadmahmoodwashmen/washmen-js-native-bridge` | React **web** (in WebView) + re-exports protocol helpers |
+| `@fawadmahmoodwashmen/washmen-js-native-bridge/native` or `…/wm-webview-bridge` | React **Native** (bootstrap, parsers, `useWmWebViewBridge`) |
+
+---
+
+## Web → native (`rpc: 1`)
+
+1. RN injects `buildWmRpcBridgeBootstrapScript({ globalName: "globalRef" })` **before** content loads.
+2. That script defines:
+   - `window.__WM_RPC__._deliver(id, ok, jsonStringPayload)`
+   - `window.__WM_BIDIR__.register / unregister / fromNative`
+   - `window.globalRef` (default) — a **`Proxy`** so **any** `globalRef.someMethod(...args)` returns a `Promise` and posts:
+
+```json
+{ "wm": 2, "rpc": 1, "id": "<id>", "m": "<methodName>", "a": [/* args, JSON-serializable */] }
+```
+
+3. RN `onMessage` (via `useWmWebViewBridge`) runs your handler, then **`injectJavaScript`**:
+
+```js
+window.__WM_RPC__._deliver("id", true, "{\"quotes\":[]}"); true;
+```
+
+(`buildWmRpcDeliverScript` does this safely.)
+
+**Web (typed):**
+
+```tsx
+import { createNativeRpcClient, WmNativeApi } from "@fawadmahmoodwashmen/washmen-js-native-bridge";
+
+// Augment WmNativeApi in your app (declaration merge) for IDE types.
+const bridge = createNativeRpcClient<WmNativeApi>();
+const quotes = await bridge.getQuotes({ author: "x" });
+```
+
+If `ReactNativeWebView` is missing (Storybook / browser), `createNativeRpcClient` returns a **dead** proxy whose methods reject with a clear error.
+
+### Native shell back helper
+
+```tsx
+import { BACK_BUTTON_ARIA_LABEL, useNativeShell } from "@fawadmahmoodwashmen/washmen-js-native-bridge";
+
+function FooterBackButton() {
+  const { requestBack } = useNativeShell();
+  return (
+    <button
+      type="button"
+      aria-label={BACK_BUTTON_ARIA_LABEL}
+      onClick={() => void requestBack()}
+    >
+      Back
+    </button>
+  );
+}
+```
+
+In SPAs, always use a real `<button type="button">` and call `requestBack()` in `onClick`.
+Do not rely on injected click-capture scripts for first-party React UI controls.
+
+---
+
+## Native → web (`invokeWebMethod` + `rpc: 3`)
+
+1. Same bootstrap defines `__WM_BIDIR__.fromNative(callId, method, argsJsonStr)`.
+2. RN calls `invokeWebMethod("getPageSummaryForNative", [])`, which **`injectJavaScript`**s `fromNative(...)`.
+3. The page runs the registered handler (see below), then **`postMessage`**:
+
+```json
+{ "wm": 2, "rpc": 3, "callId": "<id>", "ok": true, "payload": "<JSON string of result>" }
+```
+
+On failure: `"ok": false`, `payload` is a JSON string like `{"message":"…"}`.
+
+**Web — register handlers (React):**
+
+```tsx
+import { WmWebBridgeProvider } from "@fawadmahmoodwashmen/washmen-js-native-bridge";
+
+<WmWebBridgeProvider
+  handlers={{
+    getPageSummaryForNative: async () => [{ title: "Intro" }],
+  }}
+>
+  <App />
+</WmWebBridgeProvider>
+```
+
+Or imperative: `registerWebRpcHandlers({ ... })` → returns `unregister()`.
+
+---
+
+## React Native — `useWmWebViewBridge`
+
+```tsx
+import WebView from "react-native-webview";
+import { useRef, useCallback } from "react";
+import { useWmWebViewBridge } from "@fawadmahmoodwashmen/washmen-js-native-bridge/native";
+
+export function BridgeWebView() {
+  const ref = useRef<WebView>(null);
+  const getHandlers = useCallback(
+    () => ({
+      getQuotes: async (_ctx, args: unknown[]) => {
+        const q = args[0] as { author: string };
+        return [{ id: "1", text: `Hello ${q.author}` }];
+      },
+    }),
+    [],
+  );
+
+  const { injectedJavaScriptBeforeContentLoaded, onMessage, invokeWebMethod } =
+    useWmWebViewBridge(getHandlers, ref, { globalName: "globalRef" });
+
+  async function askWeb() {
+    const summary = await invokeWebMethod("getPageSummaryForNative", []);
+    console.log(summary);
+  }
+
+  return (
+    <WebView
+      ref={ref}
+      source={{ uri: "https://your-web-app.com" }}
+      injectedJavaScriptBeforeContentLoaded={injectedJavaScriptBeforeContentLoaded}
+      onMessage={onMessage}
+    />
+  );
+}
+```
+
+**`onMessage` ordering:** `useWmWebViewBridge` / `handleWmWebViewBridgeMessage` parses **`rpc: 3` first**, then **`rpc: 1`**, so web replies never look like new web-initiated RPCs.
+
+---
+
+## Layout & scrolling (Android)
+
+If the `WebView` sits **inside** a `ScrollView`, give the WebView a **fixed height** (or `flex:1` inside a bounded parent) and set **`nestedScrollEnabled`** on Android so nested scrolling behaves.
+
+---
+
+## Modular RN handlers (recommended)
+
+Keep `getHandlers` as `useCallback` returning a **small map**; implement each method in its own module and compose:
+
+```ts
+const getHandlers = useCallback(
+  () => ({
+    ...quotesHandlers(queryClient),
+    ...authHandlers(store),
+  }),
+  [queryClient, store],
+);
+```
+
+Do **not** paste large business logic into the bootstrap string — only `buildWmRpcBridgeBootstrapScript()` (transport + Proxy).
+
+---
+
+## Types: `WmNativeApi` / `WmWebApi`
+
+Export interfaces in the package; **augment** in your apps so `createNativeRpcClient` / `invokeWebMethod` stay aligned:
+
+```ts
+declare module "@fawadmahmoodwashmen/washmen-js-native-bridge" {
+  interface WmNativeApi {
+    getQuotes(input: { author: string }): Promise<{ id: string; text: string }[]>;
+  }
+  interface WmWebApi {
+    getPageSummaryForNative(): Promise<{ title: string }[]>;
+  }
+}
+```
+
+(Optional next step: codegen from a shared `bridge.contract.ts` in a monorepo.)
+
+---
+
+## Flow (bullets)
+
+**Web → native**
+
+- Web: `await globalRef.method(...args)` (Proxy) → `postMessage` `rpc:1`.
+- Native: handler → `injectJavaScript` → `__WM_RPC__._deliver` → Promise resolves on web.
+
+**Native → web**
+
+- Native: `invokeWebMethod(method, args)` → `injectJavaScript` → `__WM_BIDIR__.fromNative`.
+- Web: registered handler → `postMessage` `rpc:3`.
+- Native: `onMessage` matches `callId`, resolves `invokeWebMethod` Promise.
+
+---
+
+## Non-goals
+
+No binary streams, no non-JSON payloads, no synchronous return across the WebView boundary (async-only from RN’s perspective for cross-runtime calls).
+
+---
+
+## Releasing
+
+Requires **Node.js ≥ 20.12** (for `release-it`). No **`GITHUB_TOKEN`** needed: GitHub Releases are disabled; publishing is **npm only**.
+
+GitHub **environment** `Publishing` with secret **`NPM_TOKEN`** ([npm access token](https://docs.npmjs.com/creating-and-viewing-access-tokens) that can publish this scope). The workflow job uses `environment: Publishing` so that secret is available.
+
+From a clean `main` working tree:
+
+```bash
+npm run release
+```
+
+You choose **patch / minor / major**, confirm steps. That runs tests + typecheck, bumps `package.json` + lockfile, commits, pushes, and creates tag **`vX.Y.Z`**. Pushing the tag triggers the **Publish npm** GitHub Action, which runs `npm publish` to **registry.npmjs.org**.
+
+Dry run: `npm run release:dry`
+
+---
+
+## License
+
+MIT