wovvmap-webview-bridge 1.0.5 → 1.0.7

package/README.md

@@ -1,180 +1,213 @@
-# 📱 Native Integration Guide – wovvmap-webview-bridge
-
-This guide explains how to use the `wovvmap-webview-bridge` package **from the React Native side**. This package helps you send data to a WebView and listen for data coming from the WebView.
-
----
-
-## ✅ Installation
-
-```bash
-npm install wovvmap-webview-bridge
-# or
-yarn add wovvmap-webview-bridge
-```
-
----
-
-## 🔌 Setup WebView
-
-Import and use the `<WebViewScreen />` component provided by the package:
-
-```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { WebViewScreen } from 'wovvmap-webview-bridge';
-
-export default function App() {
-  return (
-    <View style={{ flex: 1 }}>
-      <WebViewScreen url="http://localhost:5173/map" />
-    </View>
-  );
-}
-```
-
----
-
-## 📤 Send Data to WebView
-
-You can send navigation data (e.g. from, to, elevator, escalator) using `sendToWeb`:
-
-```ts
-import { sendToWeb } from 'wovvmap-webview-bridge';
-
-sendToWeb({
-  type: "setNavigationData",
-  payload: {
-    from: "store1",
-    to: "store9",
-    elevator: false,
-    escalator: true,
-    floor : 1
-  },
-});
-```
-
----
-
-## 📥 Receive Events from WebView
-
-Use `registerBridgeHandler` to listen for events sent from the web:
-
-```ts
-import { registerBridgeHandler } from 'wovvmap-webview-bridge';
-
-registerBridgeHandler("pathData", (points) => {
-  console.log("📍 Received pathData:", points);
-});
-
-registerBridgeHandler("PathFindingResult", (result) => {
-  console.log("🧭 Path result:", result);
-});
-
-registerBridgeHandler("changeFloor", (floor) => {
-  console.log("🏢 Web requested floor change:", floor);
-});
-```
-
----
-
-## 🧠 Data Types
-
-The bridge handles these types safely:
-
-```ts
-type SendToWebMessage = {
-  type: "setNavigationData";
-  payload: {
-    from?: string;
-    to?: string;
-    elevator?: boolean;
-    escalator?: boolean;
-    floor?: boolean;
-  };
-};
-
-type BridgeMessage =
-  | { type: "event"; key: "floor"; value: number }
-  | { type: "event"; key: "pathData"; value: NodePoint[] }
-  | { type: "event"; key: "PathFindingResult"; value: PathFindingResult }
-  | { type: "event"; key: "searchTextResult"; value: NodePoint[] }
-  | { type: "event"; key: "shapeZoomAndSelect"; value: NodePoint | undefined }
-  | { type: "event"; key: "searchablePoints"; value: NodePoint[] }
-  | { type: "event"; key: "nodePoint"; value: {[key:string]: NodePointOuterFiled} }
-  | { type: "event"; key: "nodeline"; value: {[key:string]: NodeLineOuterFiled} }
-  | { type: "event"; key: "categoryList"; value: { [key: string]: NodePoint } }
-  | {
-    type: "event"; key: "floorInfo"; value: {
-      floors: {
-        index: number;
-        shortName: string;
-        fullName: string;
-        floorNumber: number;
-      }[],
-      defaultFloorIndex: number
-    }
-  }
-  | { type: "event"; key: "to"; value:string}
-  | { type: "event"; key: "from"; value:string}
-  | { type: "event"; key: "elevator"; value:"true" | "false"}
-  | { type: "event"; key: "escalator"; value:"true" | "false"}
-
-
-
-  type EventHandlerMap = {
-    floor?: (floor: number) => void;
-    pathData?: (val: NodePoint[]) => void;
-    PathFindingResult?: (val: PathFindingResult) => void;
-    searchTextResult?: (val: NodePoint[]) => void;
-    shapeZoomAndSelect?: (val: NodePoint | undefined) => void;
-    searchablePoints?: (val: NodePoint[]) => void;
-    nodePoint?: (val: { [key: string]: NodePointOuterFiled }) => void;
-    nodeline?: (val: { [key: string]: NodeLineOuterFiled }) => void;
-    categoryList?: (val: { [key: string]: NodePoint }) => void;
-    floorInfo?: (val: {
-        floors: {
-        index: number;
-        shortName: string;
-        fullName: string;
-        floorNumber: number;
-        }[];
-        defaultFloorIndex: number;
-    }) => void;
-    to?: (val: string) => void;
-    from?: (val: string) => void;
-    elevator?: (val: "true" | "false") => void;
-    escalator?: (val: "true" | "false") => void;
-};
-
-```
-
----
-
-## 💡 Tips
-
-- All bridge messages are serialized using `JSON.stringify`. Avoid non-serializable data like Maps or circular references.
-- WebView must have messaging enabled (already done in `<WebViewScreen />`).
-- You can directly access the `webviewRef` if needed.
-
-```ts
-import { webviewRef } from 'wovvmap-webview-bridge';
-```
-
----
-
-## 📄 Summary of Exports (Native Side)
-
-```ts
-import {
-  WebViewScreen,
-  sendToWeb,
-  webviewRef,
-  registerBridgeHandler,
-} from 'wovvmap-webview-bridge';
-```
-
----
-
-## 📘 Done!
-
-You're now ready to communicate seamlessly between React Native and your WebView 🎉
+
+# React Native WebView Bridge
+
+A tiny bridge layer to communicate between a React Native app (using `react-native-webview`) and a web page. It provides:
+
+- A ready-to-use `<WebViewScreen />` wrapper
+- A simple `sendToWeb(...)` API for posting messages to the webview
+- Typed event handling for messages coming **from** the web page
+- Lightweight in-app state storage (via `koshin`) to keep UI in sync with bridge events
+
+> **Demo idea:** Your message referenced a Snack example. You can adapt this package to the same flow as in your Snack: https://snack.expo.dev/@krushnkant/react-native-webview
+
+---
+
+## Installation
+
+```bash
+# with npm
+npm i react-native-webview 
+
+# or with yarn
+yarn add react-native-webview 
+
+# or with pnpm
+pnpm add react-native-webview 
+```
+
+---
+
+## Quick Start
+
+1) **Render the WebView and hook the bridge handler**
+
+```tsx
+import React from "react";
+import { WebViewScreen } from "<your-package-name>";
+// If you want to register custom event callbacks:
+import { registerBridgeHandler } from "<your-package-name>";
+
+export default function App() {
+  React.useEffect(() => {
+    // Optional handlers for clicks coming from the web scene
+    registerBridgeHandler("isSceneClick", (evt) => {
+      console.log("Scene clicked:", evt);
+    });
+    registerBridgeHandler("isShapClick", (evt) => {
+      console.log("Shape clicked:", evt.value);
+    });
+  }, []);
+
+  return <WebViewScreen url={"https://your-web-app.example.com"} />;
+}
+```
+
+Under the hood, `<WebViewScreen />` wires `onMessage` to the bridge message handler so any `postMessage(...)` coming from your web page is typed and routed correctly.  fileciteturn1file6
+
+2) **Send commands *to* the web app**
+
+```ts
+import {
+  sendActiveFloorToBridge,
+  sendEndPointToBridge,
+  sendPathFinishBtnClick,
+  sendPathNextBtnClick,
+  sendPathPreBtnClick,
+  sendStartPointToBridge,
+} from "<your-package-name>";
+
+// examples:
+sendStartPointToBridge("node_123");
+sendEndPointToBridge("node_999");
+sendActiveFloorToBridge(2);
+sendPathNextBtnClick();
+sendPathPreBtnClick();
+sendPathFinishBtnClick();
+```
+
+These helpers call the shared `sendToWeb(...)` which posts a JSON-serialized message to the underlying `WebView` instance. fileciteturn1file1 fileciteturn1file7
+
+3) **Keep UI in sync with bridge state (optional)**
+
+```ts
+import { bridgeStorage } from "<your-package-name>";
+
+bridgeStorage.subscribe((state) => {
+  // state includes: isBridgeLoaded, isMapLoaded, searchablePoints, activeFloor, etc.
+  console.log(state);
+});
+```
+
+Internally this uses a small `koshin` store with fields like `isBridgeLoaded`, `isMapLoaded`, `searchablePoints`, `activeFloor`, `floorImages`, `stapByStapList`, and `nextPreState`.  fileciteturn1file0
+
+---
+
+## What the Web Page Should Send
+
+Your web page (inside the WebView) should `postMessage(JSON.stringify(...))` with the following **Incoming** event shapes:
+
+```ts
+type IncomingMessage =
+  | { type: "event"; key: "isConnection"; value: boolean; file: string }
+  | { type: "event"; key: "mapLoaded"; value: boolean; file: string }
+  | { type: "event"; key: "_searchablePoints"; value: NodePoint[]; file: string }
+  | { type: "event"; key: "Category"; value: Category[]; file: string }
+  | { type: "event"; key: "_activeFloor"; value: number; file: string }
+  | { type: "event"; key: "FloorImg"; value: FloorImage[]; file: string }
+  | { type: "event"; key: "isSceneClick"; file: string }
+  | { type: "event"; key: "isShapClick"; value: NodePoint; file: string }
+  | { type: "event"; key: "stapByStapList"; value: StepInstruction[]; file: string }
+  | { type: "event"; key: "pathNextPreState"; value: NavState; file: string };
+```
+The built-in handler parses the message, updates store fields, and triggers any registered callbacks for `isSceneClick` / `isShapClick`.  fileciteturn1file3 fileciteturn1file2
+
+---
+
+## What the App Sends to the Web Page
+
+Outgoing commands you can dispatch from React Native:
+
+```ts
+type OutgoingMessage =
+  | { type: "applyCSS"; selector: string; style: Partial<Record<string, string | number>> }
+  | { type: "event"; key: "ping"; value: boolean; file: string }
+  | { type: "event"; key: "setEndPoint"; value: string; file: string }
+  | { type: "event"; key: "setStartPoint"; value: string; file: string }
+  | { type: "event"; key: "setActiveFloor"; value: number; file: string }
+  | { type: "event"; key: "pathNextBtnClick"; file: string }
+  | { type: "event"; key: "pathPreBtnClick"; file: string }
+  | { type: "event"; key: "pathFinishBtnClick"; file: string };
+```
+These go through `sendToWeb(...)` which uses a shared `webviewRef` to `postMessage(...)`.  fileciteturn1file7
+
+---
+
+## API Reference
+
+### Components
+
+#### `<WebViewScreen />`
+A thin wrapper around `react-native-webview` that plugs in the bridge message handler.
+
+**Props**
+- `url: string` – the URL to load inside the WebView.
+
+fileciteturn1file6
+
+### Functions
+
+- `registerBridgeHandler(type, handler)` — Register a callback for `"isSceneClick"` or `"isShapClick"` events.  fileciteturn1file3
+- `sendStartPointToBridge(pointId)` — Ask web map to set the start point.  fileciteturn1file1
+- `sendEndPointToBridge(pointId)` — Ask web map to set the end point.  fileciteturn1file1
+- `sendActiveFloorToBridge(floorIndex)` — Switch active floor on the web map.  fileciteturn1file1
+- `sendPathNextBtnClick()` / `sendPathPreBtnClick()` / `sendPathFinishBtnClick()` — Control path stepper on the web map.  fileciteturn1file1
+- `bridgeStorage` — Reactive store with connection and navigation-related state.  fileciteturn1file0
+
+### Types (partial)
+- `NodePoint`, `Category`, `FloorImage`, `StepInstruction`, `NavState`, `IncomingMessage`, `OutgoingMessage` — TypeScript contracts shared across the bridge.  fileciteturn1file5
+
+---
+
+## Minimal Web Side (Example)
+
+Your web app should listen for messages and respond via `window.ReactNativeWebView.postMessage(...)`:
+
+```js
+// inside the web page
+window.addEventListener("message", (e) => {
+  try {
+    const msg = JSON.parse(e.data);
+    if (msg.type === "event" && msg.key === "setActiveFloor") {
+      // do something in the web app
+      console.log("Active floor requested:", msg.value);
+      // notify RN app that web is connected
+      window.ReactNativeWebView?.postMessage(JSON.stringify({
+        type: "event",
+        key: "isConnection",
+        value: true,
+        file: "web-app",
+      }));
+    }
+  } catch {}
+});
+```
+
+---
+
+## Project Structure (Library)
+
+```
+src/
+├─ index.ts                    # package exports  fileciteturn1file4
+├─ handlers/WebBridgeHandlers  # incoming event router & registration  fileciteturn1file3
+├─ webviewBridge/WebViewBridgeRef.ts  # shared ref + sendToWeb        fileciteturn1file7
+├─ webviewBridge/BridgeService.ts     # convenience sending helpers    fileciteturn1file1
+├─ webviewBridge/BridgeStorage.ts     # tiny state store (koshin)      fileciteturn1file0
+├─ webviewBridge/WebViewScreen.tsx    # ready-to-use WebView wrapper   fileciteturn1file6
+├─ types/types.ts                # shared TS contracts                 fileciteturn1file5
+```
+
+---
+
+## Requirements
+
+- React Native
+- [`react-native-webview`](https://github.com/react-native-webview/react-native-webview)
+- [`koshin`](https://www.npmjs.com/package/koshin)
+- TypeScript recommended
+
+---
+
+## License
+
+MIT © Your Name

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "wovvmap-webview-bridge",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "types": "dist/types/index.d.ts",
   "files": [
     "dist"
   ],