@sigmela/router 0.2.8 → 0.3.1

package/README.md

@@ -8,9 +8,11 @@ This library is **URL-first**: you navigate by **paths** (`/users/42?tab=posts`)
 
 - **Stacks**: predictable stack-based navigation
 - **Tabs**: `TabBar` with native + web renderers (or custom tab bar)
+- **Drawer**: side-panel navigation (`Drawer`)
 - **Split view**: master/details navigation (`SplitView`)
 - **Modals & sheets**: via `stackPresentation` (`modal`, `sheet`, …)
 - **Controllers**: async/guarded navigation (only present when ready)
+- **Appearance**: global styling via `NavigationAppearance` (tab bar colors, fonts, blur effects, etc.)
 - **Web History integration**: keeps Router state in sync with `pushState`, `replaceState`, `popstate`
 - **Dynamic root**: swap root navigation tree at runtime (`router.setRoot`)
 - **Type-safe hooks**: `useParams`, `useQueryParams`, `useRoute`, `useCurrentRoute`
@@ -27,7 +29,7 @@ yarn add @sigmela/native-sheet
 
 - `react`
 - `react-native`
-- `react-native-screens` (>= `4.18.0`)
+- `react-native-screens` (>= `4.24.0`)
 - `@sigmela/native-sheet` (>= `0.0.1`) — only if you use sheets
 
 ### Web CSS
@@ -292,10 +294,45 @@ Key methods:
 Notes:
 - Exactly one of `stack`, `node`, `screen` must be provided.
 - Use `prefix` to mount a tab's routes under a base path (e.g. `/mail`).
+- All `TabsScreenProps` from `react-native-screens` are forwarded to native. This includes lifecycle events (`onWillAppear`, `onDidAppear`, `onWillDisappear`, `onDidDisappear`), accessibility props (`testID`, `accessibilityLabel`, `tabBarItemTestID`, `tabBarItemAccessibilityLabel`), `orientation`, `systemItem`, `freezeContents`, `placeholder`, `scrollEdgeEffects`, badge styling, and more.
+
+#### `setTabBarConfig()`
+
+Runtime tab bar configuration:
+
+```tsx
+tabBar.setTabBarConfig({
+  bottomAccessory: (environment) => <MiniPlayer layout={environment} />,  // iOS 26+
+  experimentalControlNavigationStateInJS: true,
+});
+```
 
 Web behavior note:
 - The built-in **web** tab bar renderer resets Router history on tab switch (to keep URL and Router state consistent) using `router.reset(firstRoutePath)`.
 
+### `Drawer`
+
+`Drawer` provides side-panel navigation, similar to `TabBar` but with a slide-out panel.
+
+```tsx
+import { Drawer, NavigationStack } from '@sigmela/router';
+
+const homeStack = new NavigationStack().addScreen('/', HomeScreen);
+const settingsStack = new NavigationStack().addScreen('/settings', SettingsScreen);
+
+const drawer = new Drawer({ width: 280 })
+  .addTab({ key: 'home', stack: homeStack, title: 'Home' })
+  .addTab({ key: 'settings', stack: settingsStack, title: 'Settings' });
+```
+
+Key methods:
+- `addTab({ key, stack?, node?, screen?, prefix?, title?, icon?, ... })`
+- `open()`, `close()`, `toggle()` — manage drawer state
+- `getIsOpen()` — current open state
+- `subscribeOpenState(listener)` — subscribe to open/close changes
+- `onIndexChange(index)` — switch active tab
+- `setBadge(index, badge | null)`
+
 ### `SplitView`
 
 `SplitView` renders **two stacks**: `primary` and `secondary`.
@@ -350,6 +387,54 @@ stack.addScreen('/users/:userId', UserDetails);
 
 If you never call `present()`, the screen is not pushed/replaced.
 
+## Appearance
+
+Pass `NavigationAppearance` to `<Navigation>` to customize styling globally:
+
+```tsx
+import { Navigation, type NavigationAppearance } from '@sigmela/router';
+
+const appearance: NavigationAppearance = {
+  tabBar: {
+    backgroundColor: '#ffffff',
+    iconColor: '#999999',
+    iconColorActive: '#007AFF',
+    badgeBackgroundColor: '#FF3B30',
+    iOSShadowColor: '#00000020',
+    title: {
+      fontFamily: 'Inter',
+      fontSize: 10,
+      color: '#999999',
+      activeColor: '#007AFF',
+      activeFontSize: 12,       // Android: active tab title font size
+    },
+
+    // Android-specific
+    androidActiveIndicatorEnabled: true,
+    androidActiveIndicatorColor: '#007AFF20',
+    androidRippleColor: '#007AFF10',
+    labelVisibilityMode: 'labeled',
+
+    // Tab bar behavior
+    hidden: false,                           // hide/show the tab bar
+    tintColor: '#007AFF',                    // iOS: selected tab tint + glow color
+    controllerMode: 'automatic',             // iOS 18+: 'automatic' | 'tabBar' | 'tabSidebar'
+    minimizeBehavior: 'automatic',           // iOS 26+: 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp'
+    nativeContainerBackgroundColor: '#fff',   // native container background
+    iOSBlurEffect: 'systemDefault',          // iOS: tab bar blur effect
+  },
+  header: { /* ScreenStackHeaderConfigProps */ },
+  sheet: {
+    cornerRadius: 16,
+    backgroundColor: '#ffffff',
+  },
+};
+
+export default function App() {
+  return <Navigation router={router} appearance={appearance} />;
+}
+```
+
 ## Hooks
 
 ### `useRouter()`
@@ -410,6 +495,27 @@ function ScreenInsideTabs() {
 }
 ```
 
+### `useTabBarHeight()`
+
+Returns the tab bar height constant (`57`). Useful for bottom padding.
+
+### `useDrawer()`
+
+Returns the nearest `Drawer` from context (only inside drawer screens).
+
+```tsx
+import { useDrawer } from '@sigmela/router';
+
+function ScreenInsideDrawer() {
+  const drawer = useDrawer();
+  return <Button title="Open menu" onPress={() => drawer.open()} />;
+}
+```
+
+### `useSplitView()`
+
+Returns the nearest `SplitView` from context (only inside split view screens).
+
 ## Web integration
 
 ### History API syncing

package/lib/module/Drawer/Drawer.js

@@ -0,0 +1,250 @@
+"use strict";
+
+import React from 'react';
+import { RenderDrawer } from './RenderDrawer';
+export class Drawer {
+  screens = {};
+  stacks = {};
+  nodes = {};
+  listeners = new Set();
+  openListeners = new Set();
+  constructor(options = {}) {
+    this.drawerId = `drawer-${Math.random().toString(36).slice(2)}`;
+    this.width = options.width ?? 280;
+    this.state = {
+      tabs: [],
+      index: options.initialIndex ?? 0,
+      config: {
+        component: options.component
+      },
+      isOpen: false
+    };
+  }
+  getId() {
+    return this.drawerId;
+  }
+  addTab(tab) {
+    const sourcesCount = (tab.stack ? 1 : 0) + (tab.node ? 1 : 0) + (tab.screen ? 1 : 0);
+    if (sourcesCount !== 1) {
+      throw new Error(`Drawer.addTab: exactly one of { stack, node, screen } must be provided (got ${sourcesCount})`);
+    }
+    const {
+      key,
+      ...rest
+    } = tab;
+    const nextIndex = this.state.tabs.length;
+    const tabKey = key ?? `drawer-item-${nextIndex}`;
+    const nextTabs = [...this.state.tabs, {
+      tabKey,
+      tabPrefix: tab.prefix,
+      title: rest.title,
+      icon: rest.icon,
+      selectedIcon: rest.selectedIcon,
+      badgeValue: rest.badgeValue
+    }];
+    this.setState({
+      tabs: nextTabs
+    });
+    if (tab.stack) {
+      this.stacks[tabKey] = tab.stack;
+    } else if (tab.node) {
+      this.nodes[tabKey] = tab.node;
+    } else if (tab.screen) {
+      this.screens[tabKey] = tab.screen;
+    }
+    return this;
+  }
+  setBadge(tabIndex, badge) {
+    this.setState({
+      tabs: this.state.tabs.map((item, index) => index === tabIndex ? {
+        ...item,
+        badgeValue: badge ?? undefined
+      } : item)
+    });
+  }
+  setTabBarConfig(config) {
+    this.setState({
+      config: {
+        ...this.state.config,
+        ...config
+      }
+    });
+  }
+  onIndexChange(index) {
+    this.setState({
+      index
+    });
+  }
+
+  // ---- Open/Close state ----
+
+  open() {
+    if (!this.state.isOpen) {
+      this.setState({
+        isOpen: true
+      });
+      this.notifyOpenListeners(true);
+    }
+  }
+  close() {
+    if (this.state.isOpen) {
+      this.setState({
+        isOpen: false
+      });
+      this.notifyOpenListeners(false);
+    }
+  }
+  toggle() {
+    if (this.state.isOpen) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+  getIsOpen() {
+    return this.state.isOpen;
+  }
+  subscribeOpenState(listener) {
+    this.openListeners.add(listener);
+    return () => {
+      this.openListeners.delete(listener);
+    };
+  }
+  notifyOpenListeners(isOpen) {
+    for (const listener of Array.from(this.openListeners)) {
+      try {
+        listener(isOpen);
+      } catch (e) {
+        if (__DEV__) {
+          console.error('[Drawer] openListener error', e);
+        }
+      }
+    }
+  }
+
+  // ---- Standard TabBar-like methods ----
+
+  getState = () => {
+    return this.state;
+  };
+  setState(state) {
+    this.state = {
+      ...this.state,
+      ...state
+    };
+    this.notifyListeners();
+  }
+  notifyListeners() {
+    for (const listener of Array.from(this.listeners)) {
+      try {
+        listener();
+      } catch (e) {
+        if (__DEV__) {
+          console.error('[Drawer] listener error', e);
+        }
+      }
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  getTabs() {
+    return this.state.tabs.slice();
+  }
+  getInitialIndex() {
+    return this.state.index ?? 0;
+  }
+  getActiveChildId() {
+    const activeTab = this.state.tabs[this.state.index];
+    if (!activeTab) return undefined;
+    const node = this.nodes[activeTab.tabKey] ?? this.stacks[activeTab.tabKey];
+    return node?.getId();
+  }
+  switchToRoute(routeId) {
+    const idx = this.findTabIndexByRoute(routeId);
+    if (idx === -1) return;
+    if (idx === this.state.index) return;
+    this.setState({
+      index: idx
+    });
+  }
+  hasRoute(routeId) {
+    return this.findTabIndexByRoute(routeId) !== -1;
+  }
+  setActiveChildByRoute(routeId) {
+    this.switchToRoute(routeId);
+  }
+  getNodeRoutes() {
+    return [];
+  }
+  getNodeChildren() {
+    const children = [];
+    for (let idx = 0; idx < this.state.tabs.length; idx++) {
+      const tab = this.state.tabs[idx];
+      const node = tab ? this.nodes[tab.tabKey] ?? this.stacks[tab.tabKey] : undefined;
+      if (node) {
+        children.push({
+          prefix: tab?.tabPrefix ?? '',
+          node,
+          onMatch: () => this.onIndexChange(idx)
+        });
+      }
+    }
+    return children;
+  }
+  getRenderer() {
+    const drawerInstance = this;
+    return function DrawerScreen(props) {
+      return /*#__PURE__*/React.createElement(RenderDrawer, {
+        drawer: drawerInstance,
+        appearance: props?.appearance
+      });
+    };
+  }
+  seed() {
+    const activeTab = this.state.tabs[this.state.index];
+    if (!activeTab) return null;
+    const node = this.nodes[activeTab.tabKey];
+    if (node) {
+      return node.seed?.() ?? null;
+    }
+    const stack = this.stacks[activeTab.tabKey];
+    if (!stack) return null;
+    const firstRoute = stack.getFirstRoute();
+    if (!firstRoute) return null;
+    return {
+      routeId: firstRoute.routeId,
+      path: firstRoute.path,
+      stackId: stack.getId()
+    };
+  }
+  findTabIndexByRoute(routeId) {
+    for (let i = 0; i < this.state.tabs.length; i++) {
+      const tab = this.state.tabs[i];
+      const node = tab ? this.nodes[tab.tabKey] ?? this.stacks[tab.tabKey] : undefined;
+      if (!node) continue;
+      const hasRoute = this.nodeHasRoute(node, routeId);
+      if (hasRoute) {
+        return i;
+      }
+    }
+    return -1;
+  }
+  nodeHasRoute(node, routeId) {
+    const routes = node.getNodeRoutes();
+    for (const r of routes) {
+      if (r.routeId === routeId) return true;
+      if (r.childNode) {
+        if (this.nodeHasRoute(r.childNode, routeId)) return true;
+      }
+    }
+    const children = node.getNodeChildren();
+    for (const child of children) {
+      if (this.nodeHasRoute(child.node, routeId)) return true;
+    }
+    return false;
+  }
+}

package/lib/module/Drawer/DrawerContext.js

@@ -0,0 +1,4 @@
+"use strict";
+
+import { createContext } from 'react';
+export const DrawerContext = /*#__PURE__*/createContext(null);

package/lib/module/Drawer/DrawerIcon.web.js

@@ -0,0 +1,47 @@
+"use strict";
+
+import { memo, useMemo } from 'react';
+import { Image } from 'react-native';
+import { jsx as _jsx } from "react/jsx-runtime";
+const resolveImageUri = source => {
+  if (!source) return undefined;
+  const resolved = typeof Image.resolveAssetSource === 'function' ? Image.resolveAssetSource(source) : undefined;
+  if (resolved?.uri) return resolved.uri;
+  if (Array.isArray(source)) {
+    const first = source[0];
+    if (first && typeof first === 'object' && 'uri' in first) return first.uri;
+  }
+  if (typeof source === 'object' && source && 'uri' in source) return source.uri;
+  return undefined;
+};
+export const DrawerIcon = /*#__PURE__*/memo(({
+  source,
+  tintColor
+}) => {
+  const iconUri = resolveImageUri(source);
+  const useMask = Boolean(tintColor && iconUri);
+  const maskStyle = useMemo(() => {
+    if (!useMask || !iconUri) return undefined;
+    return {
+      backgroundColor: tintColor,
+      WebkitMaskImage: `url(${iconUri})`,
+      WebkitMaskSize: 'contain',
+      WebkitMaskRepeat: 'no-repeat',
+      WebkitMaskPosition: 'center',
+      maskImage: `url(${iconUri})`,
+      maskSize: 'contain',
+      maskRepeat: 'no-repeat',
+      maskPosition: 'center',
+      width: '100%',
+      height: '100%'
+    };
+  }, [tintColor, iconUri, useMask]);
+  if (maskStyle) {
+    return /*#__PURE__*/_jsx("div", {
+      style: maskStyle
+    });
+  }
+  return /*#__PURE__*/_jsx(Image, {
+    source: source
+  });
+});

package/lib/module/Drawer/RenderDrawer.native.js

@@ -0,0 +1,244 @@
+"use strict";
+
+import { StackRenderer } from "../StackRenderer.js";
+import { DrawerContext } from "./DrawerContext.js";
+import { useRouter } from "../RouterContext.js";
+import { ScreenStackItem } from 'react-native-screens';
+import { Pressable, StyleSheet, View, Text } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useCallback, useSyncExternalStore, memo, useEffect, useState, useMemo } from 'react';
+import Animated, { useSharedValue, useAnimatedStyle, withTiming, Easing } from 'react-native-reanimated';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const TIMING_CONFIG = {
+  duration: 300,
+  easing: Easing.bezier(0.22, 0.61, 0.36, 1)
+};
+const DrawerStackRenderer = /*#__PURE__*/memo(({
+  stack,
+  appearance
+}) => {
+  const router = useRouter();
+  const stackId = stack.getId();
+  const subscribe = useCallback(cb => router.subscribeStack(stackId, cb), [router, stackId]);
+  const get = useCallback(() => router.getStackHistory(stackId), [router, stackId]);
+  const history = useSyncExternalStore(subscribe, get, get);
+  return /*#__PURE__*/_jsx(StackRenderer, {
+    appearance: appearance,
+    stackId: stackId,
+    history: history
+  });
+});
+DrawerStackRenderer.displayName = 'DrawerStackRenderer';
+const DrawerNodeRenderer = /*#__PURE__*/memo(({
+  node,
+  appearance
+}) => {
+  const Renderer = useMemo(() => node.getRenderer(), [node]);
+  return /*#__PURE__*/_jsx(Renderer, {
+    appearance: appearance
+  });
+});
+DrawerNodeRenderer.displayName = 'DrawerNodeRenderer';
+export const RenderDrawer = /*#__PURE__*/memo(({
+  drawer,
+  appearance = {}
+}) => {
+  const router = useRouter();
+  const insets = useSafeAreaInsets();
+  const drawerWidth = drawer.width;
+  const subscribe = useCallback(cb => drawer.subscribe(cb), [drawer]);
+  const snapshot = useSyncExternalStore(subscribe, drawer.getState, drawer.getState);
+  const {
+    tabs,
+    index,
+    config,
+    isOpen
+  } = snapshot;
+
+  // Reanimated shared value for drawer position
+  const translateX = useSharedValue(0);
+  const overlayOpacity = useSharedValue(0);
+  useEffect(() => {
+    translateX.value = withTiming(isOpen ? drawerWidth : 0, TIMING_CONFIG);
+    overlayOpacity.value = withTiming(isOpen ? 0.3 : 0, TIMING_CONFIG);
+  }, [isOpen, drawerWidth, translateX, overlayOpacity]);
+  const drawerStyle = useAnimatedStyle(() => ({
+    transform: [{
+      translateX: translateX.value - drawerWidth
+    }]
+  }));
+  const mainStyle = useAnimatedStyle(() => ({
+    transform: [{
+      translateX: translateX.value
+    }]
+  }));
+  const overlayStyle = useAnimatedStyle(() => ({
+    opacity: overlayOpacity.value,
+    pointerEvents: isOpen ? 'auto' : 'none'
+  }));
+  const onItemPress = useCallback(nextIndex => {
+    const targetTab = tabs[nextIndex];
+    if (!targetTab) return;
+    const targetStack = drawer.stacks[targetTab.tabKey];
+    const targetNode = drawer.nodes[targetTab.tabKey];
+    if (nextIndex !== index) {
+      drawer.onIndexChange(nextIndex);
+    }
+    if (targetStack) {
+      const stackId = targetStack.getId();
+      const stackHistory = router.getStackHistory(stackId);
+      if (stackHistory.length === 0) {
+        const firstRoute = targetStack.getFirstRoute();
+        if (firstRoute?.path) {
+          router.navigate(firstRoute.path);
+        }
+      }
+    } else if (targetNode) {
+      const nodeId = targetNode.getId?.();
+      if (nodeId) {
+        const nodeHistory = router.getStackHistory(nodeId);
+        if (nodeHistory.length === 0) {
+          const seed = targetNode.seed?.();
+          if (seed?.path) {
+            const prefix = targetTab.tabPrefix ?? '';
+            const fullPath = prefix && !seed.path.startsWith(prefix) ? `${prefix}${seed.path.startsWith('/') ? '' : '/'}${seed.path}` : seed.path;
+            router.navigate(fullPath);
+          }
+        }
+      }
+    }
+    drawer.close();
+  }, [tabs, drawer, index, router]);
+  const handleOverlayPress = useCallback(() => {
+    drawer.close();
+  }, [drawer]);
+  const [visited, setVisited] = useState({});
+  useEffect(() => {
+    const key = tabs[index]?.tabKey;
+    if (key) {
+      setVisited(prev => prev[key] ? prev : {
+        ...prev,
+        [key]: true
+      });
+    }
+  }, [tabs, index]);
+  const CustomDrawer = config.component;
+  return /*#__PURE__*/_jsx(ScreenStackItem, {
+    screenId: "root-drawer",
+    headerConfig: {
+      hidden: true
+    },
+    style: StyleSheet.absoluteFill,
+    stackAnimation: "slide_from_right",
+    children: /*#__PURE__*/_jsx(DrawerContext.Provider, {
+      value: drawer,
+      children: /*#__PURE__*/_jsxs(View, {
+        style: styles.container,
+        children: [/*#__PURE__*/_jsx(Animated.View, {
+          style: [styles.sidebar, {
+            width: drawerWidth
+          }, drawerStyle],
+          children: CustomDrawer ? /*#__PURE__*/_jsx(CustomDrawer, {
+            onItemPress: onItemPress,
+            activeIndex: index,
+            items: tabs,
+            isOpen: isOpen,
+            onClose: handleOverlayPress
+          }) : /*#__PURE__*/_jsx(View, {
+            style: [styles.sidebarContent, {
+              paddingTop: insets.top + 12
+            }],
+            children: tabs.map((tab, i) => {
+              const isActive = i === index;
+              return /*#__PURE__*/_jsx(Pressable, {
+                onPress: () => onItemPress(i),
+                style: [styles.item, isActive && styles.itemActive],
+                children: /*#__PURE__*/_jsx(Text, {
+                  style: [styles.itemText, isActive && styles.itemTextActive],
+                  children: tab.title
+                })
+              }, tab.tabKey);
+            })
+          })
+        }), /*#__PURE__*/_jsx(Animated.View, {
+          style: [styles.overlay, overlayStyle],
+          children: /*#__PURE__*/_jsx(Pressable, {
+            style: StyleSheet.absoluteFill,
+            onPress: handleOverlayPress
+          })
+        }), /*#__PURE__*/_jsx(Animated.View, {
+          style: [styles.main, mainStyle],
+          children: tabs.filter(t => visited[t.tabKey]).map(tab => {
+            const isActive = tab.tabKey === tabs[index]?.tabKey;
+            const stackForTab = drawer.stacks[tab.tabKey];
+            const nodeForTab = drawer.nodes[tab.tabKey];
+            const ScreenForTab = drawer.screens[tab.tabKey];
+            return /*#__PURE__*/_jsx(View, {
+              style: [styles.flex, !isActive && styles.hidden],
+              children: stackForTab ? /*#__PURE__*/_jsx(DrawerStackRenderer, {
+                appearance: appearance,
+                stack: stackForTab
+              }) : nodeForTab ? /*#__PURE__*/_jsx(DrawerNodeRenderer, {
+                appearance: appearance,
+                node: nodeForTab
+              }) : ScreenForTab ? /*#__PURE__*/_jsx(ScreenForTab, {}) : null
+            }, `drawer-content-${tab.tabKey}`);
+          })
+        })]
+      })
+    })
+  });
+});
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    flexDirection: 'row',
+    overflow: 'hidden'
+  },
+  sidebar: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    left: 0,
+    zIndex: 10,
+    backgroundColor: '#ffffff'
+  },
+  sidebarContent: {
+    flex: 1
+  },
+  main: {
+    flex: 1,
+    width: '100%'
+  },
+  overlay: {
+    ...StyleSheet.absoluteFillObject,
+    zIndex: 5,
+    backgroundColor: '#000000'
+  },
+  item: {
+    height: 44,
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 12,
+    marginHorizontal: 12,
+    marginBottom: 4,
+    borderRadius: 10
+  },
+  itemActive: {
+    backgroundColor: 'rgba(201, 204, 209, 0.32)'
+  },
+  itemText: {
+    flex: 1,
+    fontSize: 14,
+    fontWeight: '600'
+  },
+  itemTextActive: {
+    fontWeight: '700'
+  },
+  flex: {
+    flex: 1
+  },
+  hidden: {
+    display: 'none'
+  }
+});