@arkeytyp/valu-api 1.1.1 → 1.1.2

package/README.md

@@ -225,6 +225,102 @@ const reply = await valuApi.runConsoleCommand(
 console.log(reply);
 ```
 
+# Routing in Valu iFrame Applications
+
+The application is embedded inside Valuverse and controlled by the host.
+
+- Valuverse owns the global routing context
+- Your app receives route updates from Valu
+- Your app should push navigation changes back to Valu
+
+---
+
+## Important Concept: Route Visibility
+
+There are **two different routing scopes**:
+
+### Local (App-only) Routing
+Routing handled only inside your application (e.g. React Router).
+
+- ✅ App works normally
+- ❌ Routes are **not visible** to Valuverse
+- ❌ No deep linking from the main application
+
+### Valu Routing (Host-aware)
+Routing handled through Valu API.
+
+- ✅ Routes appear in the main application
+- ✅ Deep linking works
+- ✅ Navigation state is shared with Valuverse
+
+---
+
+## Using React Router in an iFrame App
+
+Using **React Router inside an iFrame Valu app is totally fine**.
+
+Your application will:
+- render pages correctly
+- navigate normally
+- function as a self-contained UI
+
+However:
+
+- those routes are **internal only**
+- they **do not propagate** to Valuverse
+- the main application will not see or control them
+
+This approach is acceptable for:
+- demo applications
+- prototypes
+- isolated tools
+- apps that do not need host-level routing
+
+---
+
+## Best Practice for Valuverse Applications
+
+If your application is built to behave like a **native Valuverse app**, the recommended approach is:
+
+> **Use Valu routing instead of (or in addition to) local routing.**
+
+This ensures:
+- consistent navigation behavior
+- correct deep linking
+- visibility in the main application router
+- proper docking and context switching
+
+---
+
+## Valu Routing API
+
+### Subscribing to Route Changes
+
+Valu notifies your application when the route changes:
+
+```ts
+valuApi.addEventListener(ValuApi.ON_ROUTE, (route) => {
+  // route example:
+  // "/console"
+  // "/api/users/id/123"
+});
+```
+
+### Pushing a New Route
+
+Navigate forward:
+
+```ts
+valuApi.pushRoute("/documentation");
+```
+
+Replacing the Current Route
+Redirect without adding a history entry:
+
+```ts
+valuApi.replaceRoute("/console");
+```
+
 ## Sample Project
 
 We've created a sample application integrated with Valu API.  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkeytyp/valu-api",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "A package for developing iframe applications for Valu Social. Allows invoking functions of registered Valu applications and subscribing to events, as well as other features that enable developers creating own ifram apps for the value social",
   "main": "src/ValuApi.js",
   "scripts": {

package/src/ValuApi.js

@@ -17,6 +17,7 @@ export { APIPointer } from "./APIPointer.js";
 export class ValuApi {
 
   static API_READY = 'api:ready'
+  static ON_ROUTE = `on_route`;
 
   #eventEmitter;
   #valuApplication = {};
@@ -184,6 +185,40 @@ export class ValuApi {
     return deferredPromise.promise;
   }
 
+
+  #runCommand(name, data) {
+    this.#postToValuApp('api:run-command', {
+      command: name,
+      data: data,
+    });
+  }
+
+  /**
+   * Pushes a new route onto the navigation stack.
+   *
+   * Use this when:
+   *   navigating forward
+   *   opening a new view
+   *   preserving back-navigation history
+   * @param path
+   */
+  pushRoute = (path) => {
+    this.#runCommand('pushRoute', path);
+  }
+
+  /**
+   * Replaces the current route without adding a new history entry.
+   * Use this when:
+   *    redirecting
+   *    normalizing URLs
+   *    preventing back-navigation to the previous route
+   * @param {string }path
+   */
+  replaceRoute = (path) => {
+    this.#runCommand('replaceRoute', path);
+  }
+
+
   #createDeferred() {
     let resolve, reject;
     const promise = new Promise((res, rej) => {
@@ -219,9 +254,20 @@ export class ValuApi {
         break;
       }
 
+      case 'api:trigger': {
+        switch (message.action) {
+          case ValuApi.ON_ROUTE: {
+            this.#eventEmitter.emit(ValuApi.ON_ROUTE, message.data);
+            this.#applicationInstance?.onUpdateRouterContext(message.data);
+          }
+        }
+        break;
+      }
+
       case 'api:new-intent': {
         const intent = new Intent(message.applicationId, message.action, message.params);
         this.#applicationInstance?.onNewIntent(intent);
+        break;
       }
 
       case 'api:run-console-completed': {

package/src/ValuApplication.js

@@ -28,4 +28,15 @@ export class ValuApplication {
    * Called when the app is about to be destroyed.
    */
   async onDestroy() {}
+
+
+  /**
+   * Called when the application’s router context changes.
+   *
+   * This typically happens when:
+   *  the app moves between main / side / modal containers
+   *  the host updates routing or layout state
+   * @param {string} context
+   */
+  onUpdateRouterContext(context) {};
 }

package/types/valu-api.d.ts

@@ -1,6 +1,7 @@
 declare module '@arkeytyp/valu-api' {
     export class ValuApi {
         static API_READY: string;
+        static ON_ROUTE : string;
 
         get connected(): boolean;
 
@@ -22,6 +23,27 @@ declare module '@arkeytyp/valu-api' {
         removeEventListener(event: string, callback: (data: any) => void): void;
         getApi(apiName: string, version?: number): Promise<APIPointer>;
         runConsoleCommand(command: string): Promise<any | string>;
+
+        /**
+         * Pushes a new route onto the navigation stack.
+         *
+         * Use this when:
+         *   navigating forward
+         *   opening a new view
+         *   preserving back-navigation history
+         * @param path
+         */
+        pushRoute(path: string): void;
+
+        /**
+         * Replaces the current route without adding a new history entry.
+         * Use this when:
+         *    redirecting
+         *    normalizing URLs
+         *    preventing back-navigation to the previous route
+         * @param {string }path
+         */
+        replaceRoute(path: string): void;
     }
 
     export class APIPointer {
@@ -107,5 +129,15 @@ declare module '@arkeytyp/valu-api' {
          * Use this to clean up resources (e.g., closing connections, clearing timers).
          */
         onDestroy(): void;
+
+        /**
+         * Called when the application’s router context changes.
+         *
+         * This typically happens when:
+         *  the app moves between main / side / modal containers
+         *  the host updates routing or layout state
+         * @param context - updated application route
+         */
+        onUpdateRouterContext(context: string): void;
     }
 }