@arkeytyp/valu-api - npm Package Compare versions

Comparing version 1.1.1 to 1.1.2

package.json

 {
   "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",
@@ -5,0 +5,0 @@ "main": "src/ValuApi.js",

README.md

@@ -228,2 +228,98 @@ The `valu-api` package enables developers to build custom iframe applications for Valu Social.
 
+# 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
@@ -230,0 +326,0 @@

src/ValuApi.js

@@ -20,2 +20,3 @@ import {EventEmitter} from "./EventEmitter.js";
   static API_READY = 'api:ready'
+  static ON_ROUTE = `on_route`;
 
@@ -188,2 +189,36 @@ #eventEmitter;
 
+
+  #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() {
@@ -224,5 +259,16 @@ let resolve, reject;
 
+      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;
       }
@@ -229,0 +275,0 @@

src/ValuApplication.js

@@ -31,2 +31,13 @@
   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) {};
 }

types/valu-api.d.ts

 declare module '@arkeytyp/valu-api' {
     export class ValuApi {
         static API_READY: string;
+        static ON_ROUTE : string;
 
@@ -25,2 +26,23 @@ get connected(): boolean;
         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;
     }
@@ -111,3 +133,13 @@
         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;
     }
 }

No alert changes

Improved metrics

Total package byte prevSize

41080

12%

Lines of code

630

14.13%

Number of lines in readme file

331

40.85%

No dependency changes