@sigmela/router 0.2.0 → 0.2.1

package/lib/module/Router.js

@@ -351,6 +351,27 @@ export class Router {
     }
     const matchResult = base.matchPath(pathname);
     const params = matchResult ? matchResult.params : undefined;
+
+    // Smart navigate:
+    // If navigate(push) targets the currently active routeId within the same stack, treat it as
+    // "same screen, new data" and perform a replace (preserving the existing key) by default.
+    //
+    // Consumers can opt out per-route via ScreenOptions.allowMultipleInstances=true.
+    if (action === 'push' && base.stackId) {
+      const mergedOptions = this.mergeOptions(base.options, base.stackId);
+      const allowMultipleInstances = mergedOptions?.allowMultipleInstances === true;
+      const isActiveSameStack = this.activeRoute?.stackId === base.stackId;
+      const isActiveSameRoute = this.activeRoute?.routeId === base.routeId;
+
+      // Optional safety: only apply to push-presentation screens by default.
+      const presentation = mergedOptions?.stackPresentation ?? 'push';
+      const isPushPresentation = presentation === 'push';
+      if (!allowMultipleInstances && isPushPresentation && isActiveSameStack && isActiveSameRoute) {
+        const newItem = this.createHistoryItem(base, params, query, pathname);
+        this.applyHistoryChange('replace', newItem);
+        return;
+      }
+    }
     if (action === 'push') {
       if (base.stackId) {
         let existing = this.findExistingRoute(base.stackId, base.routeId, pathname, params ?? {});

package/lib/module/ScreenStack/ScreenStack.web.js

@@ -2,7 +2,7 @@
 
 import { memo, useRef, useLayoutEffect, useMemo, useEffect, Children, isValidElement, Fragment } from 'react';
 import { useTransitionMap } from 'react-transition-state';
-import { ScreenStackItemsContext, ScreenStackAnimatingContext } from "./ScreenStackContext.js";
+import { ScreenStackItemsContext, ScreenStackAnimatingContext, useScreenStackConfig } from "./ScreenStackContext.js";
 import { getPresentationTypeClass, computeAnimationType } from "./animationHelpers.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 const devLog = (_, __) => {};
@@ -61,6 +61,8 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
   });
   const containerRef = useRef(null);
   const isInitialMountRef = useRef(true);
+  const suppressEnterAfterEmptyRef = useRef(false);
+  const suppressedEnterKeyRef = useRef(null);
   const prevKeysRef = useRef([]);
   const lastDirectionRef = useRef('forward');
   const childMapRef = useRef(new Map());
@@ -146,6 +148,8 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     routeKeys,
     direction
   });
+  const screenStackConfig = useScreenStackConfig();
+  const animateFirstScreenAfterEmpty = screenStackConfig.animateFirstScreenAfterEmpty ?? true;
   const isInitialPhase = isInitialMountRef.current;
   const keysToRender = useMemo(() => {
     const routeKeySet = new Set(routeKeys);
@@ -179,10 +183,27 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     }
     const newKeys = routeKeys.filter(key => !existingKeySet.has(key));
     const removedKeys = [...existingKeySet].filter(key => !routeKeySet.has(key));
+
+    // Track "became empty" state to suppress the next enter animation when configured.
+    // This is SplitView-secondary-only (via ScreenStackConfigContext), not global behavior.
+    if (!animateFirstScreenAfterEmpty) {
+      if (routeKeys.length === 0) {
+        suppressEnterAfterEmptyRef.current = true;
+        suppressedEnterKeyRef.current = null;
+      }
+    }
     devLog('[ScreenStack] Lifecycle diff', {
       newKeys,
       removedKeys
     });
+
+    // If this is the first pushed key after the stack was empty, remember its key so we can
+    // suppress only its enter animation (without affecting exit animations).
+    if (!animateFirstScreenAfterEmpty && suppressEnterAfterEmptyRef.current && routeKeys.length > 0 && newKeys.length > 0) {
+      const candidate = newKeys[newKeys.length - 1] ?? null;
+      suppressedEnterKeyRef.current = candidate;
+      suppressEnterAfterEmptyRef.current = false;
+    }
     for (const key of newKeys) {
       devLog(`[ScreenStack] Adding item: ${key}`);
       setItem(key);
@@ -206,7 +227,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     }
     lastDirectionRef.current = direction;
     devLog('[ScreenStack] === LIFECYCLE EFFECT END ===');
-  }, [routeKeys, direction, setItem, toggle, stateMapEntries, stateMap]);
+  }, [routeKeys, direction, setItem, toggle, stateMapEntries, stateMap, animateFirstScreenAfterEmpty]);
   useLayoutEffect(() => {
     devLog('[ScreenStack] === CLEANUP EFFECT START ===');
     const routeKeySet = new Set(routeKeys);
@@ -240,15 +261,31 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     // If the stack mounts empty, we still want the first pushed screen to animate.
     // Mark initial mount as completed immediately in that case.
     if (!hasMountedItem && routeKeys.length === 0) {
-      isInitialMountRef.current = false;
-      devLog('[ScreenStack] Initial mount completed (empty stack)');
+      if (animateFirstScreenAfterEmpty) {
+        isInitialMountRef.current = false;
+        devLog('[ScreenStack] Initial mount completed (empty stack)');
+      }
       return;
     }
     if (hasMountedItem) {
       isInitialMountRef.current = false;
       devLog('[ScreenStack] Initial mount completed');
     }
-  }, [stateMapEntries, routeKeys.length]);
+  }, [stateMapEntries, routeKeys.length, animateFirstScreenAfterEmpty]);
+
+  // Clear suppression key once it is no longer the top screen (so it can animate normally as
+  // a background when new screens are pushed).
+  useLayoutEffect(() => {
+    if (animateFirstScreenAfterEmpty) return;
+    const topKey = routeKeys[routeKeys.length - 1] ?? null;
+    if (!topKey) {
+      suppressedEnterKeyRef.current = null;
+      return;
+    }
+    if (suppressedEnterKeyRef.current && suppressedEnterKeyRef.current !== topKey) {
+      suppressedEnterKeyRef.current = null;
+    }
+  }, [routeKeys, animateFirstScreenAfterEmpty]);
   useEffect(() => {
     if (!containerRef.current) return;
     const items = containerRef.current.querySelectorAll('.screen-stack-item');
@@ -289,7 +326,12 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
       const routeIndex = routeKeys.indexOf(key);
       const zIndex = routeIndex >= 0 ? routeIndex + 1 : keysToRender.length + index + 1;
       const presentationType = getPresentationTypeClass(presentation);
-      const animationType = computeAnimationType(key, isInStack, isTop, direction, presentation, isInitialPhase, animated);
+      let animationType = computeAnimationType(key, isInStack, isTop, direction, presentation, isInitialPhase, animated);
+
+      // SplitView-secondary-only: suppress enter animation for the first screen after empty.
+      if (!animateFirstScreenAfterEmpty && isTop && direction === 'forward' && suppressedEnterKeyRef.current === key) {
+        animationType = 'none';
+      }
       items[key] = {
         presentationType,
         animationType,
@@ -316,7 +358,10 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
         phase = 'inactive';
       }
       const presentationType = getPresentationTypeClass(presentation);
-      const animationType = isInitialPhase ? 'none' : computeAnimationType(key, isInStack, isTop, direction, presentation, isInitialPhase, animated);
+      let animationType = isInitialPhase ? 'none' : computeAnimationType(key, isInStack, isTop, direction, presentation, isInitialPhase, animated);
+      if (!animateFirstScreenAfterEmpty && isTop && direction === 'forward' && suppressedEnterKeyRef.current === key) {
+        animationType = 'none';
+      }
       items[key] = {
         presentationType,
         animationType,
@@ -328,7 +373,7 @@ export const ScreenStack = /*#__PURE__*/memo(props => {
     return {
       items
     };
-  }, [keysToRender, stateMap, childMap, routeKeySet, topKey, isInitialPhase, routeKeys, direction]);
+  }, [keysToRender, stateMap, childMap, routeKeySet, topKey, isInitialPhase, routeKeys, direction, animateFirstScreenAfterEmpty]);
   const animating = useMemo(() => {
     return stateMapEntries.some(([, state]) => state.isMounted && (state.status === 'entering' || state.status === 'exiting' || state.status === 'preEnter' || state.status === 'preExit'));
   }, [stateMapEntries]);

package/lib/module/ScreenStack/ScreenStackContext.js

@@ -3,6 +3,12 @@
 import { createContext, useContext } from 'react';
 export const ScreenStackItemsContext = /*#__PURE__*/createContext(null);
 export const ScreenStackAnimatingContext = /*#__PURE__*/createContext(false);
+export const ScreenStackConfigContext = /*#__PURE__*/createContext({
+  animateFirstScreenAfterEmpty: true
+});
+export const useScreenStackConfig = () => {
+  return useContext(ScreenStackConfigContext);
+};
 export const useScreenStackItemsContext = () => {
   const ctx = useContext(ScreenStackItemsContext);
   if (!ctx) {

package/lib/module/SplitView/RenderSplitView.web.js

@@ -3,7 +3,8 @@
 import { StackRenderer } from "../StackRenderer.js";
 import { SplitViewContext } from "./SplitViewContext.js";
 import { useRouter } from "../RouterContext.js";
-import { memo, useCallback, useMemo, useSyncExternalStore } from 'react';
+import { ScreenStackConfigContext } from "../ScreenStack/ScreenStackContext.js";
+import { memo, useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const StackSliceRenderer = /*#__PURE__*/memo(({
   stack,
@@ -46,7 +47,31 @@ export const RenderSplitView = /*#__PURE__*/memo(({
   splitView,
   appearance
 }) => {
-  const instanceClass = useMemo(() => `split-view-instance-${splitView.getId()}`, [splitView]);
+  const [isWide, setIsWide] = useState(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+      return false;
+    }
+    return window.matchMedia(`(min-width: ${splitView.minWidth}px)`).matches;
+  });
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+      return;
+    }
+    const mq = window.matchMedia(`(min-width: ${splitView.minWidth}px)`);
+    const onChange = ev => setIsWide(ev.matches);
+
+    // Sync immediately.
+    setIsWide(mq.matches);
+    if (typeof mq.addEventListener === 'function') {
+      mq.addEventListener('change', onChange);
+      return () => mq.removeEventListener('change', onChange);
+    }
+
+    // Safari < 14 fallback (deprecated, but still needed).
+    const mqAny = mq;
+    mqAny.addListener?.(onChange);
+    return () => mqAny.removeListener?.(onChange);
+  }, [splitView.minWidth]);
   const containerStyle = useMemo(() => {
     return {
       '--split-view-primary-max-width': `${splitView.primaryMaxWidth}px`
@@ -54,26 +79,31 @@ export const RenderSplitView = /*#__PURE__*/memo(({
   }, [splitView.primaryMaxWidth]);
   return /*#__PURE__*/_jsx(SplitViewContext.Provider, {
     value: splitView,
-    children: /*#__PURE__*/_jsx("div", {
-      className: instanceClass,
-      children: /*#__PURE__*/_jsxs("div", {
-        className: "split-view-container",
-        style: containerStyle,
-        children: [/*#__PURE__*/_jsx("div", {
-          className: "split-view-primary",
-          children: /*#__PURE__*/_jsx(StackSliceRenderer, {
-            appearance: appearance,
-            stack: splitView.primary,
-            fallbackToFirstRoute: true
-          })
-        }), /*#__PURE__*/_jsx("div", {
-          className: "split-view-secondary",
+    children: /*#__PURE__*/_jsxs("div", {
+      className: "split-view-container",
+      style: containerStyle,
+      children: [/*#__PURE__*/_jsx("div", {
+        className: "split-view-primary",
+        children: /*#__PURE__*/_jsx(StackSliceRenderer, {
+          appearance: appearance,
+          stack: splitView.primary,
+          fallbackToFirstRoute: true
+        })
+      }), /*#__PURE__*/_jsx("div", {
+        className: "split-view-secondary",
+        children: isWide ? /*#__PURE__*/_jsx(ScreenStackConfigContext.Provider, {
+          value: {
+            animateFirstScreenAfterEmpty: false
+          },
           children: /*#__PURE__*/_jsx(StackSliceRenderer, {
             appearance: appearance,
             stack: splitView.secondary
           })
-        })]
-      })
+        }) : /*#__PURE__*/_jsx(StackSliceRenderer, {
+          appearance: appearance,
+          stack: splitView.secondary
+        })
+      })]
     })
   });
 });

package/lib/module/TabBar/TabBar.js

@@ -82,7 +82,6 @@ export class TabBar {
       } catch (e) {
         // TabBar has no debug flag; keep behavior quiet in production.
         if (__DEV__) {
-          // eslint-disable-next-line no-console
           console.error('[TabBar] listener error', e);
         }
       }

package/lib/module/TabBar/useTabBarHeight.js

@@ -8,7 +8,7 @@ export const TAB_BAR_HEIGHT = 57;
 /**
  * Hook that returns the height of the TabBar
  * @returns {number} The height of the TabBar in pixels
- * 
+ *
  * @example
  * ```tsx
  * const TabBarExample = () => {

package/lib/typescript/src/ScreenStack/ScreenStackContext.d.ts

@@ -17,6 +17,15 @@ export type ScreenStackItemsContextValue = {
 export type ScreenStackAnimatingContextValue = boolean;
 export declare const ScreenStackItemsContext: import("react").Context<ScreenStackItemsContextValue | null>;
 export declare const ScreenStackAnimatingContext: import("react").Context<boolean>;
+export type ScreenStackConfig = {
+    /**
+     * When false, the first screen pushed after the stack becomes empty will NOT animate
+     * (treated as an initial render). Subsequent pushes/pops still animate normally.
+     */
+    animateFirstScreenAfterEmpty?: boolean;
+};
+export declare const ScreenStackConfigContext: import("react").Context<ScreenStackConfig>;
+export declare const useScreenStackConfig: () => ScreenStackConfig;
 export declare const useScreenStackItemsContext: () => ScreenStackItemsContextValue;
 export declare const useScreenStackAnimatingContext: () => boolean;
 //# sourceMappingURL=ScreenStackContext.d.ts.map

package/lib/typescript/src/types.d.ts

@@ -16,6 +16,14 @@ export type ScreenOptions = Partial<Omit<RNSScreenProps, 'stackPresentation'>> &
     syncWithUrl?: boolean;
     tabBarIcon?: TabBarIcon;
     animated?: boolean;
+    /**
+     * Allows pushing multiple instances of the same screen (same routeId) onto a stack.
+     *
+     * By default, Router.navigate() will behave like "replace" when targeting the currently
+     * active routeId in the same stack (i.e. treat it as "same screen, new data").
+     * Set this to true to force "push" even when navigating to the active routeId.
+     */
+    allowMultipleInstances?: boolean;
     /**
      * Allows Router.goBack() to pop the last (root) screen of a stack.
      * Useful for secondary stacks in split-view / overlays.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigmela/router",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "React Native Router",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",