@resistdesign/voltra 3.0.0-alpha.26 → 3.0.0-alpha.27

package/README.md

@@ -218,6 +218,14 @@ How it works:
 - Strategy is auto-selected:
   - DOM + History API => browser history strategy.
   - Otherwise => in-memory native strategy.
+- Native strategy automatically wires Android hardware back to route history.
+  - If Voltra can go back (`history.index > 0`), it consumes the event and navigates back.
+  - If Voltra cannot go back, the event is not consumed so OS/native container behavior continues.
+
+Optional back affordances:
+
+- `adapter.back?.()` navigates backward when supported.
+- `adapter.canGoBack?.()` reports whether back navigation is currently possible.
 
 Escape hatches (root-only):
 

package/app/index.js

@@ -603,6 +603,20 @@ var computeTrackPixels = ({
 };
 
 // src/app/utils/History.ts
+var createHistoryBackHandler = (history) => {
+  return {
+    /**
+     * @returns True when back navigation was handled by history.
+     */
+    handle: () => {
+      if (history.index > 0) {
+        history.back();
+        return true;
+      }
+      return false;
+    }
+  };
+};
 var ensurePrefix = (value, prefix) => value ? value.startsWith(prefix) ? value : `${prefix}${value}` : "";
 var parseHistoryPath = (inputPath) => {
   const raw = String(inputPath ?? "").trim();
@@ -756,7 +770,9 @@ var createRouteAdapterFromHistory = (history) => {
     },
     replace: (path) => {
       history.replace(path, { replaceSearch: true });
-    }
+    },
+    back: history.back,
+    canGoBack: () => history.index > 0
   };
 };
 
@@ -770,6 +786,37 @@ var getWindow = () => {
   }
   return void 0;
 };
+var getRuntimeRequire = () => {
+  const runtimeRequire = globalThis.__voltra_require__;
+  if (typeof runtimeRequire === "function") {
+    return runtimeRequire;
+  }
+  try {
+    return (0, eval)("require");
+  } catch (error) {
+    return void 0;
+  }
+};
+var tryGetReactNativeBackHandler = () => {
+  const runtimeRequire = getRuntimeRequire();
+  if (!runtimeRequire) {
+    return void 0;
+  }
+  try {
+    const reactNativeModule = runtimeRequire("react-native");
+    const platform = reactNativeModule?.Platform;
+    const backHandler = reactNativeModule?.BackHandler;
+    if (platform?.OS !== "android") {
+      return void 0;
+    }
+    if (typeof backHandler?.addEventListener !== "function") {
+      return void 0;
+    }
+    return backHandler;
+  } catch (error) {
+    return void 0;
+  }
+};
 var canUseBrowserHistory = () => {
   const WINDOW = getWindow();
   return Boolean(
@@ -823,7 +870,9 @@ var createBrowserRouteAdapter = () => {
       }
       WINDOW.history.replaceState({}, title, path);
       notify();
-    }
+    },
+    back: () => WINDOW?.history?.back(),
+    canGoBack: () => (WINDOW?.history?.length ?? 0) > 1
   };
 };
 var createNativeRouteAdapter = (initialPath = "/", ingress) => {
@@ -832,7 +881,8 @@ var createNativeRouteAdapter = (initialPath = "/", ingress) => {
   const history = createMemoryHistory(initialPath);
   const adapter = createRouteAdapterFromHistory(history);
   let stopIngress;
-  let started = false;
+  let stopBackHandler;
+  let ingressStarted = false;
   let subscribers = 0;
   const applyPath = (path, mode) => {
     const normalizedPath = parseHistoryPath(path).path;
@@ -846,10 +896,10 @@ var createNativeRouteAdapter = (initialPath = "/", ingress) => {
     history.replace(normalizedPath, { replaceSearch: true });
   };
   const startIngress = async () => {
-    if (started || !ingress) {
+    if (ingressStarted || !ingress) {
       return;
     }
-    started = true;
+    ingressStarted = true;
     const startKey = history.location.key;
     const startIndex = history.index;
     if (ingress.subscribe) {
@@ -870,6 +920,31 @@ var createNativeRouteAdapter = (initialPath = "/", ingress) => {
       }
     }
   };
+  const startBackHandler = () => {
+    if (stopBackHandler) {
+      return;
+    }
+    const reactNativeBackHandler = tryGetReactNativeBackHandler();
+    if (!reactNativeBackHandler) {
+      return;
+    }
+    const historyBackHandler = createHistoryBackHandler(history);
+    const handleHardwareBackPress = () => historyBackHandler.handle();
+    const subscription = reactNativeBackHandler.addEventListener(
+      "hardwareBackPress",
+      handleHardwareBackPress
+    );
+    stopBackHandler = () => {
+      if (typeof subscription?.remove === "function") {
+        subscription.remove();
+        return;
+      }
+      reactNativeBackHandler.removeEventListener?.(
+        "hardwareBackPress",
+        handleHardwareBackPress
+      );
+    };
+  };
   return {
     ...adapter,
     push: (path, title) => {
@@ -888,18 +963,23 @@ var createNativeRouteAdapter = (initialPath = "/", ingress) => {
       subscribers += 1;
       if (subscribers === 1) {
         void startIngress();
+        startBackHandler();
       }
       const unlisten = adapter.subscribe(listener);
       return () => {
         unlisten();
         subscribers = Math.max(0, subscribers - 1);
-        if (subscribers === 0 && stopIngress) {
-          stopIngress();
+        if (subscribers === 0) {
+          stopIngress?.();
           stopIngress = void 0;
-          started = false;
+          ingressStarted = false;
+          stopBackHandler?.();
+          stopBackHandler = void 0;
         }
       };
-    }
+    },
+    back: adapter.back,
+    canGoBack: adapter.canGoBack
   };
 };
 var createUniversalAdapter = (options = {}) => {
@@ -1735,4 +1815,4 @@ var AutoForm = ({
   );
 };
 
-export { ApplicationStateContext, ApplicationStateProvider, AutoForm, AutoFormView, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, TypeInfoORMClient, buildHistoryPath, buildQueryString, buildRoutePath, canUseBrowserHistory, computeAreaBounds, computeTrackPixels, createAutoField, createBrowserRouteAdapter, createEasyLayout, createFormRenderer, createManualRouteAdapter, createMemoryHistory, createNativeRouteAdapter, createRouteAdapterFromHistory, createUniversalAdapter, getApplicationStateIdentifier, getApplicationStateModified, getApplicationStateValue, getApplicationStateValueStructure, getChangedDependencyIndexes, getEasyLayoutTemplateDetails, getFieldKind, getFullUrl, getPascalCaseAreaName, handleRequest, mergeSuites, parseHistoryPath, parseTemplate, requestHandlerFactory, resolveSuite, sendServiceRequest, setApplicationStateModified, setApplicationStateValue, useApplicationStateLoader, useApplicationStateValue, useApplicationStateValueStructure, useController, useDebugDependencies, useFormEngine, useRouteContext, useTypeInfoORMAPI, validateAreas, withRendererOverride };
+export { ApplicationStateContext, ApplicationStateProvider, AutoForm, AutoFormView, Route, RouteContext, RouteContextConsumer, RouteContextProvider, RouteProvider, TypeInfoORMClient, buildHistoryPath, buildQueryString, buildRoutePath, canUseBrowserHistory, computeAreaBounds, computeTrackPixels, createAutoField, createBrowserRouteAdapter, createEasyLayout, createFormRenderer, createHistoryBackHandler, createManualRouteAdapter, createMemoryHistory, createNativeRouteAdapter, createRouteAdapterFromHistory, createUniversalAdapter, getApplicationStateIdentifier, getApplicationStateModified, getApplicationStateValue, getApplicationStateValueStructure, getChangedDependencyIndexes, getEasyLayoutTemplateDetails, getFieldKind, getFullUrl, getPascalCaseAreaName, handleRequest, mergeSuites, parseHistoryPath, parseTemplate, requestHandlerFactory, resolveSuite, sendServiceRequest, setApplicationStateModified, setApplicationStateValue, tryGetReactNativeBackHandler, useApplicationStateLoader, useApplicationStateValue, useApplicationStateValueStructure, useController, useDebugDependencies, useFormEngine, useRouteContext, useTypeInfoORMAPI, validateAreas, withRendererOverride };

package/app/utils/History.d.ts

@@ -98,6 +98,23 @@ export type HistoryController = {
      */
     listen: (listener: HistoryListener) => () => void;
 };
+/**
+ * Back-navigation consumption helper for shared history controllers.
+ *
+ * Returns `true` only when history consumed the back action.
+ *
+ * Example:
+ * ```ts
+ * const handler = createHistoryBackHandler(history);
+ * const consumed = handler.handle();
+ * ```
+ */
+export declare const createHistoryBackHandler: (history: HistoryController) => {
+    /**
+     * @returns True when back navigation was handled by history.
+     */
+    handle: () => boolean;
+};
 /**
  * Parse a path-like value into normalized path/search/hash parts.
  *

package/app/utils/Route.d.ts

@@ -18,6 +18,10 @@ export type RouteAdapter = {
     push?: (path: string, title?: string) => void;
     /** Optional navigation helper for adapters that can replace state. */
     replace?: (path: string, title?: string) => void;
+    /** Optional navigation helper for adapters that can go backward. */
+    back?: () => void;
+    /** Optional capability check for backward navigation. */
+    canGoBack?: () => boolean;
 };
 /**
  * Supported query value types for route serialization.

package/app/utils/UniversalRouteAdapter.d.ts

@@ -55,6 +55,16 @@ export type UniversalRouteIngress = {
      */
     mapURLToPath?: (url: string) => string;
 };
+type ReactNativeBackHandler = {
+    addEventListener: (eventName: "hardwareBackPress", listener: () => boolean) => {
+        remove?: () => void;
+    } | void;
+    removeEventListener?: (eventName: "hardwareBackPress", listener: () => boolean) => void;
+};
+/**
+ * Safely resolve React Native BackHandler for Android runtimes only.
+ */
+export declare const tryGetReactNativeBackHandler: () => ReactNativeBackHandler | undefined;
 /**
  * Detect whether browser history is available at runtime.
  */
@@ -71,3 +81,4 @@ export declare const createNativeRouteAdapter: (initialPath?: string, ingress?:
  * Create a runtime-selected RouteAdapter for web/native environments.
  */
 export declare const createUniversalAdapter: (options?: CreateUniversalAdapterOptions) => RouteAdapter;
+export {};

package/native/index.js

@@ -721,6 +721,20 @@ var AutoForm2 = (props) => {
 };
 
 // src/app/utils/History.ts
+var createHistoryBackHandler = (history) => {
+  return {
+    /**
+     * @returns True when back navigation was handled by history.
+     */
+    handle: () => {
+      if (history.index > 0) {
+        history.back();
+        return true;
+      }
+      return false;
+    }
+  };
+};
 var ensurePrefix = (value, prefix) => value ? value.startsWith(prefix) ? value : `${prefix}${value}` : "";
 var parseHistoryPath = (inputPath) => {
   const raw = String(inputPath ?? "").trim();
@@ -1252,20 +1266,7 @@ var createNativeHistory = (options = {}) => {
     }
   };
 };
-var createNativeBackHandler = (history) => {
-  return {
-    /**
-     * @returns True when back navigation was handled by history.
-     */
-    handle: () => {
-      if (history.index > 0) {
-        history.back();
-        return true;
-      }
-      return false;
-    }
-  };
-};
+var createNativeBackHandler = (history) => createHistoryBackHandler(history);
 
 // src/common/Routing.ts
 var PATH_DELIMITER = "/";
@@ -1356,4 +1357,4 @@ var buildPathFromRouteChain = (routeChain, config, query) => {
   return buildRoutePath(segments, query);
 };
 
-export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm2 as AutoForm, AutoFormView2 as AutoFormView, Button, ErrorMessage, FieldWrapper, NativeEasyLayoutView, buildHistoryPath, buildPathFromRouteChain, createMemoryHistory, createNativeBackHandler, createNativeFormRenderer, createNativeHistory, createNavigationStateRouteAdapter, makeNativeEasyLayout, mapNativeURLToPath, nativeAutoField, nativeSuite, parseHistoryPath, useNativeEasyLayout };
+export { ArrayContainer, ArrayItemWrapper, AutoField, AutoForm2 as AutoForm, AutoFormView2 as AutoFormView, Button, ErrorMessage, FieldWrapper, NativeEasyLayoutView, buildHistoryPath, buildPathFromRouteChain, createHistoryBackHandler, createMemoryHistory, createNativeBackHandler, createNativeFormRenderer, createNativeHistory, createNavigationStateRouteAdapter, makeNativeEasyLayout, mapNativeURLToPath, nativeAutoField, nativeSuite, parseHistoryPath, useNativeEasyLayout };

package/native/utils/History.d.ts

@@ -95,19 +95,8 @@ export declare const mapNativeURLToPath: (url: string) => string;
  */
 export declare const createNativeHistory: (options?: CreateNativeHistoryOptions) => NativeHistoryController;
 /**
- * Create an Android back-handler helper for native history.
- *
- * Returns `true` only when history consumed the back action.
- *
- * Example:
- * ```ts
- * const handler = createNativeBackHandler(history);
- * const consumed = handler.handle();
- * ```
+ * @deprecated Use {@link createHistoryBackHandler} from `app/utils/History`.
  */
 export declare const createNativeBackHandler: (history: HistoryController) => {
-    /**
-     * @returns True when back navigation was handled by history.
-     */
     handle: () => boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resistdesign/voltra",
-  "version": "3.0.0-alpha.26",
+  "version": "3.0.0-alpha.27",
   "description": "With our powers combined!",
   "homepage": "https://voltra.app",
   "repository": "git@github.com:resistdesign/voltra.git",