@sigmela/router 0.3.7 → 0.5.0

package/README.md

@@ -1,537 +1,193 @@
-# Sigmela Router (`@sigmela/router`)
+# @sigmela/router
 
-Modern, lightweight navigation for **React Native** and **Web**, built on top of [`react-native-screens`](https://github.com/software-mansion/react-native-screens).
+A router for React web apps that behave like native apps: screen stacks with
+animated push/pop, modals and bottom sheets with swipe-to-dismiss, tab bars,
+drawers and split views — all declared as JSX routes.
 
-This library is **URL-first**: you navigate by **paths** (`/users/42?tab=posts`), and the router derives `params` and `query` for screens.
-
-## Features
-
-- **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`
-
-## Installation
+Built on [wouter](https://github.com/molefrog/wouter) for matching and
+[motion](https://motion.dev) for transitions.
 
 ```bash
-yarn add @sigmela/router react-native-screens
-# optional (required only if you use sheet presentation)
-yarn add @sigmela/native-sheet
+npm install @sigmela/router
 ```
 
-### Peer dependencies
-
-- `react`
-- `react-native`
-- `react-native-screens` (>= `4.24.0`)
-- `@sigmela/native-sheet` (>= `0.0.1`) — only if you use sheets
-
-### Web CSS
-
-On web you must import the bundled stylesheet **once**:
-
-```ts
-import '@sigmela/router/styles.css';
-```
+`react` and `react-dom` (>= 19) are peer dependencies.
 
 ## Quick start
 
-### Simple stack
-
-```tsx
-import {
-  Navigation,
-  NavigationStack,
-  Router,
-  useParams,
-  useQueryParams,
-  useRouter,
-} from '@sigmela/router';
-
-function HomeScreen() {
-  const router = useRouter();
-  return (
-    <Button
-      title="Open details"
-      onPress={() => router.navigate('/details/42?from=home')}
-    />
-  );
-}
-
-function DetailsScreen() {
-  const { id } = useParams<{ id: string }>();
-  const { from } = useQueryParams<{ from?: string }>();
-  return <Text>Details: id={id}, from={from ?? 'n/a'}</Text>;
-}
-
-const rootStack = new NavigationStack()
-  .addScreen('/', HomeScreen, { header: { title: 'Home' } })
-  .addScreen('/details/:id', DetailsScreen, { header: { title: 'Details' } });
-
-const router = new Router({ roots: { app: rootStack }, root: 'app' });
-
-export default function App() {
-  return <Navigation router={router} />;
-}
-```
-
-### Tabs
-
-```tsx
-import { Navigation, NavigationStack, Router, TabBar } from '@sigmela/router';
-
-const homeStack = new NavigationStack().addScreen('/', HomeScreen);
-
-const catalogStack = new NavigationStack()
-  .addScreen('/catalog', CatalogScreen)
-  .addScreen('/catalog/products/:productId', ProductScreen);
-
-const tabBar = new TabBar({ initialIndex: 0 })
-  .addTab({ key: 'home', stack: homeStack, title: 'Home' })
-  .addTab({ key: 'catalog', stack: catalogStack, title: 'Catalog' });
-
-const router = new Router({ roots: { app: tabBar }, root: 'app' });
-
-export default function App() {
-  return <Navigation router={router} />;
-}
-```
-
-### Tabs wrapped by a root stack (like `example/src/navigation/stacks.ts`)
-
-In the example app, tabs are mounted as a **screen** inside a root `NavigationStack`. This lets you keep tab navigation plus define modals/overlays at the root level.
-
-```tsx
-import { NavigationStack, TabBar } from '@sigmela/router';
-
-const homeStack = new NavigationStack().addScreen('/', HomeScreen);
-const catalogStack = new NavigationStack().addScreen('/catalog', CatalogScreen);
-
-const tabBar = new TabBar()
-  .addTab({
-    key: 'home',
-    stack: homeStack,
-    title: 'Home',
-    icon: require('./assets/home.png'),
-  })
-  .addTab({
-    key: 'catalog',
-    stack: catalogStack,
-    title: 'Catalog',
-    icon: require('./assets/catalog.png'),
-  });
-
-// Root stack hosts the tab bar AND top-level modals/overlays.
-export const rootStack = new NavigationStack()
-  .addScreen('/', tabBar)
-  .addModal('/auth', AuthScreen, { header: { title: 'Login', hidden: true } })
-  .addModal('*?modal=promo', PromoModal);
-```
-
-## Core concepts
-
-### `NavigationStack`
-
-A `NavigationStack` defines a set of routes and how to match them.
-
-```tsx
-const stack = new NavigationStack({ header: { largeTitle: true } })
-  .addScreen('/feed', FeedScreen)
-  .addScreen('/feed/:id', FeedItemScreen)
-  .addModal('/auth', AuthScreen)
-  .addSheet('/settings', SettingsSheet);
-```
-
-Key methods:
-- `addScreen(pathPattern, componentOrNode, options?)`
-- `addModal(pathPattern, componentOrStack, options?)` (shorthand for `stackPresentation: 'modal'`)
-- `addSheet(pathPattern, componentOrStack, options?)` (shorthand for `stackPresentation: 'sheet'`)
-- `addStack(prefixOrStack, maybeStack?)` — compose nested stacks under a prefix
-
-#### Provider Context
-
-You can wrap an entire stack with a React context provider by passing a `provider` option:
-
-```tsx
-import { ThemeProvider } from './theme';
-
-const stack = new NavigationStack({
-  header: { largeTitle: true },
-  provider: ThemeProvider,
-})
-  .addScreen('/feed', FeedScreen)
-  .addScreen('/feed/:id', FeedItemScreen);
-```
-
-The `provider` component wraps the entire stack renderer, making the context available to all screens in the stack. This is useful for:
-- **Theme providers**: Apply theme context to all screens
-- **Auth providers**: Share authentication state across screens
-- **Localization**: Provide i18n context to the entire stack
-
-**Composing multiple providers:**
-
-If you need multiple providers, create a composed component:
-
 ```tsx
-const ComposedProvider = ({ children }) => (
-  <ThemeProvider>
-    <AuthProvider>
-      <I18nProvider>
-        {children}
-      </I18nProvider>
-    </AuthProvider>
-  </ThemeProvider>
-);
-
-const stack = new NavigationStack({ provider: ComposedProvider })
-  .addScreen('/', HomeScreen);
-```
-
-**Important:** The provider should be a stable reference (not an inline arrow function) to avoid unnecessary re-renders.
-
-### Modal Stacks (Stack in Stack)
-
-You can pass an entire `NavigationStack` to `addModal()` or `addSheet()` to create a multi-screen flow inside a modal:
-
-```tsx
-// Define a flow with multiple screens
-const emailVerifyStack = new NavigationStack()
-  .addScreen('/verify', EmailInputScreen)
-  .addScreen('/verify/sent', EmailSentScreen);
-
-// Mount the entire stack as a modal
-const rootStack = new NavigationStack()
-  .addScreen('/', HomeScreen)
-  .addModal('/verify', emailVerifyStack);
-```
+import { Router, useRouter } from '@sigmela/router';
 
-**How it works:**
-- Navigating to `/verify` opens the modal with `EmailInputScreen`
-- Inside the modal, `router.navigate('/verify/sent')` pushes `EmailSentScreen` within the same modal
-- `router.goBack()` navigates back inside the modal stack
-- `router.dismiss()` closes the entire modal from any depth
-
-**Example screen with navigation inside modal:**
-
-```tsx
-function EmailInputScreen() {
-  const router = useRouter();
-  
+function App() {
   return (
-    <View>
-      <Button title="Next" onPress={() => router.navigate('/verify/sent')} />
-      <Button title="Close" onPress={() => router.dismiss()} />
-    </View>
+    <Router>
+      <Router.Screen path="/" element={HomeScreen} />
+      <Router.Stack path="/products">
+        <Router.Screen element={ProductListScreen} />
+        <Router.Screen path=":id" element={ProductScreen} />
+        <Router.Modal path=":id/edit" element={EditProductModal} />
+        <Router.Sheet path=":id/share" element={ShareSheet} />
+      </Router.Stack>
+    </Router>
   );
 }
 
-function EmailSentScreen() {
+function ProductCard({ id }: { id: string }) {
   const router = useRouter();
-  
-  return (
-    <View>
-      <Button title="Back" onPress={() => router.goBack()} />
-      <Button title="Done" onPress={() => router.dismiss()} />
-    </View>
-  );
+  return <button onClick={() => router.navigate(`/products/${id}`)}>Open</button>;
 }
 ```
 
-This pattern works recursively — you can nest stacks inside stacks to any depth.
+Styles ship with the bundle: `dist/index.js` imports `router.css`, so bundlers
+that handle CSS from dependencies (Vite, webpack, Next, Parcel) pick it up
+automatically — no extra import needed.
 
-### `Router`
-
-The `Router` holds navigation state and performs path matching.
+Environments without a CSS loader — plain Node, some SSR pipelines — cannot
+resolve that import. Load the stylesheet explicitly there:
 
 ```ts
-const router = new Router({
-  roots: { app: root }, // NavigationNode (NavigationStack, TabBar, SplitView, ...)
-  root: 'app',
-  screenOptions, // optional defaults
-  debug, // optional
-});
+import '@sigmela/router/router.css';
 ```
 
-Navigation:
-- `router.navigate(path)` — push
-- `router.replace(path, dedupe?)` — replace top of the active stack
-- `router.goBack()` — pop top of the active stack
-- `router.dismiss()` — close the nearest modal or sheet (including all screens in a modal stack)
-- `router.reset(path)` — **web-only**: rebuild Router state as if app loaded at `path`
-- `router.setRoot(rootKey, { transition? })` — swap root at runtime (`rootKey` from `config.roots`)
-
-State/subscriptions:
-- `router.getState()` → `{ history: HistoryItem[] }`
-- `router.getActiveRoute()` → `ActiveRoute | null`
-- `router.subscribe(cb)` — notify on any history change
-- `router.subscribeStack(stackId, cb)` — notify when a particular stack slice changes
-- `router.subscribeRoot(cb)` — notify when root is replaced via `setRoot`
-- `router.getStackHistory(stackId)` — slice of history for a stack
+For Vitest with the `node` environment, inline the package so Vite handles the
+CSS import instead of Node:
 
-### `TabBar`
-
-`TabBar` is a container node that renders one tab at a time.
-
-```tsx
-const tabBar = new TabBar({ component: CustomTabBar, initialIndex: 0 })
-  .addTab({ key: 'home', stack: homeStack, title: 'Home' })
-  .addTab({ key: 'search', screen: SearchScreen, title: 'Search' });
+```ts
+// vitest.config.ts
+test: {
+  environment: 'node',
+  server: { deps: { inline: [/@sigmela\/router/] } },
+}
 ```
 
-Key methods:
-- `addTab({ key, stack?, node?, screen?, prefix?, title?, icon?, selectedIcon?, ... })`
-- `onIndexChange(index)` — switch active tab
-- `setBadge(index, badge | null)`
-- `setTabBarConfig(partialConfig)`
-- `getState()` and `subscribe(cb)`
-
-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()`
+## Route primitives
 
-Runtime tab bar configuration:
+| Element | Purpose |
+| --- | --- |
+| `Router.Screen` | A routed screen inside the current stack |
+| `Router.Stack` | Groups screens that push and pop with a shared animation |
+| `Router.Redirect` | Declarative redirect |
+| `Router.Modal` | Full-cover or content-sized overlay above the current screen |
+| `Router.Sheet` | Bottom sheet, content-sized or fullscreen |
+| `Router.TabBar` / `Router.TabBarItem` | Tab navigation; selecting a tab routes to its root path |
+| `Router.Drawer` / `Router.DrawerGroup` / `Router.DrawerSection` / `Router.DrawerItem` | Persistent side navigation |
+| `Router.SplitView` | Primary/secondary panes above a width breakpoint |
+| `Router.Protected` | Guarded subtree with a redirect target |
 
-```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`
+### Overlays with their own stack
 
-`Drawer` provides side-panel navigation, similar to `TabBar` but with a slide-out panel.
+`Router.Modal` and `Router.Sheet` can own a local push stack. The children share
+one surface and leave the browser URL on the underlying screen:
 
 ```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' });
+<Router.Modal path="/auth/email">
+  <Router.Screen element={AuthEmailModal} />
+  <Router.Screen path="verify" element={AuthEmailVerifyModal} />
+  <Router.Screen path="name" element={AuthEmailNameModal} />
+</Router.Modal>
 ```
 
-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)`
+`navigate()` and `replace()` resolve matching children inside the active
+overlay. `goBack()` pops the local stack first, then closes the overlay from its
+root. The close button, backdrop tap, Escape, swipe dismissal and
+`useCurrentModal().close()` all dismiss the whole flow from any depth.
 
-### `SplitView`
+### Content-sized modals
 
-`SplitView` renders **two stacks**: `primary` and `secondary`.
-
-- On **native**, `secondary` overlays `primary` when it has at least one screen in its history.
-- On **web**, the layout becomes side-by-side at a fixed breakpoint (`minWidth`, default `640px`).
+A modal covers the viewport by default. Content that renders `<Modal>` with
+`presentation="content"` sizes the surface to its content instead — floored at
+half the viewport, capped at full height, with the page behind left undimmed:
 
 ```tsx
-import { NavigationStack, SplitView, TabBar } from '@sigmela/router';
-
-const master = new NavigationStack().addScreen('/', ThreadsScreen);
-const detail = new NavigationStack().addScreen('/:threadId', ThreadScreen);
-
-const splitView = new SplitView({
-  minWidth: 640,
-  primary: master,
-  secondary: detail,
-  primaryMaxWidth: 390,
-});
-
-// Mount SplitView directly as a tab (no wrapper stack needed).
-const tabBar = new TabBar()
-  .addTab({ key: 'mail', node: splitView, prefix: '/mail', title: 'Mail' })
-  .addTab({ key: 'settings', stack: settingsStack, title: 'Settings' });
-```
-
-## Controllers
-
-Controllers let you delay/guard navigation. A route can be registered as:
-
-```tsx
-import { createController } from '@sigmela/router';
-
-const UserDetails = {
-  component: UserDetailsScreen,
-  controller: createController<{ userId: string }, { tab?: string }>(
-    async ({ params, query }, present) => {
-      const ok = await checkAuth();
-      if (!ok) {
-        router.replace('/login', true);
-        return;
-      }
-
-      const user = await fetchUser(params.userId);
-      present({ user, tab: query.tab });
-    }
-  ),
-};
-
-stack.addScreen('/users/:userId', UserDetails);
-```
-
-If you never call `present()`, the screen is not pushed/replaced.
-
-## Appearance
+import { Modal } from '@sigmela/router';
 
-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} />;
+function ProductDetail({ product }) {
+  return (
+    <Modal presentation={product.image ? 'fullscreen' : 'content'}>
+      {/* … */}
+    </Modal>
+  );
 }
 ```
 
 ## Hooks
 
-### `useRouter()`
+| Hook | Returns |
+| --- | --- |
+| `useRouter()` | `navigate`, `replace`, `goBack`, and overlay controls |
+| `useCurrentRoute()` | The active route: `pathname`, `search`, `searchParams` |
+| `useParams()` | Path parameters of the current route |
+| `useSearchParams()` | Query string as `URLSearchParams` |
+| `useRoute(pattern)` | Match test for an arbitrary pattern |
+| `useHistoryState()` | State passed through `navigate(path, { state })` |
+| `useCurrentModal()` | `close()` / `id` for the overlay a component renders in |
+| `useDrawer()` | Drawer open state and controls |
 
-Access the router instance.
+## Theming
 
-### `useCurrentRoute()`
+The stylesheet reads CSS custom properties, so an app can restyle every surface
+without overriding selectors. Set them on `:root` or on an app shell element:
 
-Subscribes to `router.getActiveRoute()`.
+**Base** — `--router-bg`, `--router-text`, `--router-line`, `--router-scrim`,
+`--router-container`, `--router-card-shadow`, `--router-glass-bg`,
+`--router-transparent`, `--router-divider`
 
-Returns `ActiveRoute | null` (shape from `src/types.ts`):
+**Overlay/footer** — `--router-footer-fade-bg`,
+`--router-footer-fade-transparent`
 
-```ts
-type ActiveRoute = {
-  routeId: string;
-  stackId?: string;
-  tabIndex?: number;
-  path?: string;
-  params?: Record<string, unknown>;
-  query?: Record<string, unknown>;
-} | null;
-```
+**Drawer** — `--router-drawer-bg`, `--router-drawer-text`,
+`--router-drawer-hover-bg`, `--router-drawer-active-bg`,
+`--router-drawer-badge-bg`, `--router-drawer-badge-text`,
+`--router-drawer-focus-ring`, `--router-drawer-overlay-color`,
+`--router-drawer-overlay-bg`, `--router-drawer-overlay-open-bg`
 
-### `useParams<T>()` / `useQueryParams<T>()`
+**Close button** — `--router-close-button-bg`, `--router-close-button-text`,
+`--router-close-button-light-text`, `--router-close-button-glass-bg`,
+`--router-close-button-shadow`, `--router-close-button-shine`,
+`--router-mask-fill`
 
-Returns params/query for the **current screen** (from route context).
+**Typography/layout** — `--router-title-font-family`,
+`--router-title-font-size`, `--router-title-line-height`,
+`--router-title-font-weight`, `--router-safe-area-bottom`
 
-### `useRoute()`
+Every token falls back to a sensible default, so the router renders correctly
+with no theming at all.
 
-Returns route-local context for the current screen:
+## Scope
 
-```ts
-type RouteLocalContextValue = {
-  presentation: StackPresentationTypes;
-  params?: Record<string, unknown>;
-  query?: Record<string, unknown>;
-  pattern?: string;
-  path?: string;
-};
-```
+The router owns navigation, overlay surfaces and their gestures. It never
+imports application features, i18n, data layers or design-system components —
+screens and layouts are supplied by the host app as JSX.
 
-### `useTabBar()`
+## Sandbox
 
-Returns the nearest `TabBar` from context (only inside tab screens).
+`example/` is a Vite playground that exercises every primitive against the
+router source, with hot reload:
 
-```tsx
-import { useTabBar } from '@sigmela/router';
-
-function ScreenInsideTabs() {
-  const tabBar = useTabBar();
-
-  return (
-    <Button
-      title="Go to second tab"
-      onPress={() => tabBar.onIndexChange(1)}
-    />
-  );
-}
+```bash
+npm install
+npm run example        # http://localhost:5180
 ```
 
-### `useTabBarHeight()`
+It has three shells you can switch between: **Stack & overlays** (pushes,
+params, search params, fullscreen and content-sized modals, a sheet, and a
+modal owning its own three-step stack), **Tab bar** (per-tab routes, history
+state), and **Drawer & split** (drawer groups and sections, a split view, and a
+guarded route). `example/src/theme.css` shows the `--router-*` tokens driving
+the whole look.
 
-Returns the tab bar height constant (`57`). Useful for bottom padding.
+## Development
 
-### `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()} />;
-}
+```bash
+npm install
+npm run typecheck
+npm test          # 58 contract tests
+npm run lint
+npm run build     # dist/index.js + dist/router.css + type declarations
+npm run example   # Vite sandbox on the source
 ```
 
-### `useSplitView()`
-
-Returns the nearest `SplitView` from context (only inside split view screens).
-
-## Web integration
-
-### History API syncing
-
-On web, Router integrates with the browser History API using custom events:
-
-- `router.navigate('/x')` writes `history.pushState({ __srPath: ... })`
-- `router.replace('/x')` writes `history.replaceState({ __srPath: ... })`
-- Browser back/forward triggers `popstate` and Router updates its state accordingly
-
-Important behavioral detail:
-- `router.goBack()` **does not call** `history.back()`. It pops Router state and updates the URL via `replaceState` (so it doesn’t grow/rewind the browser stack).
-
-### `syncWithUrl: false`
-
-If a route has `screenOptions.syncWithUrl = false`, Router stores the “real” router path in `history.state.__srPath` while keeping the visible URL unchanged.
+`ROUTER_CONTRACT.md` documents the invariants the contract tests protect.
 
 ## License