@idealyst/navigation 1.0.82 → 1.0.84

package/src/routing/types.ts

@@ -1,14 +1,5 @@
 import React from "react";
 
-export type ScreenOptions = {
-    /**
-     * Screen title for navigation headers
-     */
-    title?: string;
-    headerShown?: boolean;
-    
-};
-
 /**
  * Tab bar specific screen options
  */
@@ -63,6 +54,16 @@ export type NavigatorOptions = {
     headerShown?: boolean;
 }
 
+export type ScreenOptions = {
+    /**
+     * Screen title for navigation headers
+     */
+    title?: string;
+    headerShown?: boolean;
+
+} & NavigatorOptions;
+
+
 export type BaseNavigatorParam = {
     path: string
     type: 'navigator'
@@ -81,7 +82,36 @@ export type StackNavigatorParam = {
     layoutComponent?: StackLayoutComponent
 } & BaseNavigatorParam
 
-export type NavigatorParam = TabNavigatorParam | StackNavigatorParam
+/**
+ * Props passed to drawer sidebar components on mobile
+ * Includes safe area insets for proper layout
+ */
+export type DrawerSidebarProps = {
+    /**
+     * Safe area insets (mobile only)
+     * Use these to add padding to avoid notches, status bars, etc.
+     */
+    insets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+};
+
+export type DrawerNavigatorParam = {
+    layout: 'drawer'
+    routes: RouteParam<TabBarScreenOptions>[]
+    layoutComponent?: TabLayoutComponent
+    /**
+     * Custom component to render in the drawer sidebar
+     * This component will have access to useNavigator hook
+     * On mobile, receives DrawerSidebarProps with safe area insets
+     */
+    sidebarComponent?: React.ComponentType<DrawerSidebarProps>
+} & BaseNavigatorParam
+
+export type NavigatorParam = TabNavigatorParam | StackNavigatorParam | DrawerNavigatorParam
 
 export type ScreenParam<T = ScreenOptions> = {
     path: string
@@ -102,14 +132,12 @@ export type RouteWithFullPath<T = ScreenOptions> = RouteParam<T> & {
 export type TabLayoutProps = {
     options?: NavigatorOptions
     routes: RouteWithFullPath<TabBarScreenOptions>[]
-    onNavigate: (path: string) => void
     currentPath: string
 }
 
 export type StackLayoutProps = {
     options?: NavigatorOptions
     routes: RouteWithFullPath<ScreenOptions>[]
-    onNavigate: (path: string) => void
     currentPath: string
 }
 

package/CLAUDE.md

@@ -1,417 +0,0 @@
-# @idealyst/navigation - LLM Documentation
-
-This file provides comprehensive navigation documentation for LLMs working with the @idealyst/navigation library.
-
-## Library Overview
-
-@idealyst/navigation is a cross-platform navigation library with:
-- Unified API for React and React Native
-- Built on React Navigation (Native) and React Router (Web)
-- 4 layout types: stack, tab, drawer, modal
-- Theme system integration
-- Complete working examples for quick start
-
-## Quick Start with Examples
-
-The fastest way to get started is using pre-built example routers:
-
-```tsx
-import { NavigatorProvider } from '@idealyst/navigation';
-import { ExampleStackRouter } from '@idealyst/navigation/examples';
-
-// Instant working app with header, sidebar, and component examples
-<NavigatorProvider route={ExampleStackRouter} />
-```
-
-## Core Components
-
-### NavigatorProvider
-Root provider that wraps the entire app:
-
-```tsx
-<NavigatorProvider route={routeConfig}>
-  {/* App content handled by router */}
-</NavigatorProvider>
-```
-
-### useNavigator Hook
-Access navigation from any component:
-
-```tsx
-import { useNavigator } from '@idealyst/navigation';
-
-const navigator = useNavigator();
-navigator.navigate({ path: "/profile", vars: { id: "123" } });
-```
-
-## Route Configuration
-
-Define app navigation structure with `RouteParam`:
-
-```tsx
-const AppRouter: RouteParam = {
-  path: "/",
-  component: HomeScreen,
-  layout: { type: "stack" }, // "stack" | "tab" | "drawer" | "modal"
-  routes: [
-    { path: "profile", component: ProfileScreen },
-    { path: "settings", component: SettingsScreen },
-  ],
-};
-```
-
-## Layout Types
-
-### Stack Layout
-Linear navigation (most common):
-```tsx
-layout: { type: "stack" }
-```
-- **Use for**: Most mobile apps, hierarchical navigation
-- **Platform**: Native stack (RN), browser history (Web)
-
-### Tab Layout  
-Section-based navigation:
-```tsx
-layout: { type: "tab" }
-```
-- **Use for**: Main app sections, content browsing
-- **Platform**: Bottom tabs (RN), top/side tabs (Web)
-
-### Drawer Layout
-Side menu navigation:
-```tsx
-layout: { type: "drawer" }
-```
-- **Use for**: Desktop apps, admin panels
-- **Platform**: Gesture drawer (RN), sidebar (Web)
-
-### Modal Layout
-Overlay navigation:
-```tsx
-layout: { type: "modal" }
-```
-- **Use for**: Forms, dialogs, temporary content
-- **Platform**: Modal presentation (RN), overlay (Web)
-
-## Navigation Patterns
-
-### Basic Navigation
-```tsx
-const navigator = useNavigator();
-navigator.navigate({ path: "/settings", vars: {} });
-```
-
-### With Parameters
-```tsx
-navigator.navigate({ 
-  path: "/user/:id", 
-  vars: { id: "123" } 
-});
-```
-
-### Nested Routes
-```tsx
-const router: RouteParam = {
-  path: "/",
-  component: HomeScreen,
-  layout: { type: "stack" },
-  routes: [
-    {
-      path: "dashboard",
-      component: DashboardScreen,
-      layout: { type: "tab" },
-      routes: [
-        { path: "analytics", component: AnalyticsScreen },
-        { path: "reports", component: ReportsScreen },
-      ],
-    },
-  ],
-};
-```
-
-## GeneralLayout Component
-
-Flexible layout with header and sidebar:
-
-```tsx
-import { GeneralLayout } from '@idealyst/navigation';
-
-<GeneralLayout
-  header={{
-    enabled: true,
-    content: <Text>My App</Text>,
-  }}
-  sidebar={{
-    enabled: true,
-    collapsible: true,
-    position: 'left',
-    content: <NavigationMenu />,
-  }}
->
-  {children}
-</GeneralLayout>
-```
-
-### Header Configuration
-- `enabled`: Show/hide header
-- `height`: Header height (pixels)
-- `content`: Header content (React component)
-- `style`: Custom styles
-
-### Sidebar Configuration
-- `enabled`: Show/hide sidebar
-- `collapsible`: Allow collapse/expand
-- `position`: 'left' or 'right'
-- `initiallyExpanded`: Initial state
-- `expandedWidth`/`collapsedWidth`: Sidebar widths
-- `content`: Sidebar content (React component)
-
-## Example Routers (Quick Start)
-
-### ExampleStackRouter
-Desktop/web app with header and sidebar:
-```tsx
-import { ExampleStackRouter } from '@idealyst/navigation/examples';
-<NavigatorProvider route={ExampleStackRouter} />
-```
-
-**Features**: Header, collapsible sidebar, theme controls, all component examples
-
-### ExampleTabRouter  
-Mobile app with tab navigation:
-```tsx
-import { ExampleTabRouter } from '@idealyst/navigation/examples';
-<NavigatorProvider route={ExampleTabRouter} />
-```
-
-**Features**: Tab navigation, component examples, theme controls
-
-### ExampleDrawerRouter
-Desktop app with drawer menu:
-```tsx
-import { ExampleDrawerRouter } from '@idealyst/navigation/examples';
-<NavigatorProvider route={ExampleDrawerRouter} />
-```
-
-**Features**: Slide-out drawer, organized navigation, component examples
-
-## Theme Integration
-
-All navigation components integrate with @idealyst/theme:
-
-```tsx
-// Theme switching works automatically
-import { UnistylesRuntime } from 'react-native-unistyles';
-UnistylesRuntime.setTheme('dark');
-UnistylesRuntime.setTheme('lightHighContrast');
-```
-
-### Theme Utilities
-```tsx
-import { 
-  getNextTheme, 
-  getThemeDisplayName, 
-  isHighContrastTheme 
-} from '@idealyst/navigation/examples/unistyles';
-```
-
-## Custom Layouts
-
-Create custom layout components:
-
-```tsx
-const CustomLayout: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
-  <GeneralLayout
-    header={{ content: <CustomHeader /> }}
-    sidebar={{ content: <CustomSidebar /> }}
-  >
-    {children}
-  </GeneralLayout>
-);
-
-const router: RouteParam = {
-  layout: { type: "stack", component: CustomLayout },
-  // ...
-};
-```
-
-## Common Patterns
-
-### Dashboard Layout
-```tsx
-<GeneralLayout
-  header={{
-    content: (
-      <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
-        <Text size="large" weight="bold">Dashboard</Text>
-        <UserMenu />
-      </View>
-    ),
-  }}
-  sidebar={{
-    enabled: true,
-    collapsible: true,
-    content: <NavigationMenu />,
-  }}
->
-  {children}
-</GeneralLayout>
-```
-
-### Mobile App Structure
-```tsx
-const MobileRouter: RouteParam = {
-  path: "/",
-  component: HomeScreen,
-  layout: { type: "tab" },
-  routes: [
-    { path: "feed", component: FeedScreen },
-    { path: "search", component: SearchScreen },
-    { path: "profile", component: ProfileScreen },
-  ],
-};
-```
-
-### Admin Interface
-```tsx
-const AdminRouter: RouteParam = {
-  path: "/admin",
-  component: AdminDashboard,
-  layout: { 
-    type: "drawer",
-    component: AdminLayout,
-  },
-  routes: [
-    { path: "users", component: UserManagement },
-    { path: "settings", component: AdminSettings },
-  ],
-};
-```
-
-## Route Guards and Conditional Navigation
-
-```tsx
-const ProtectedRoute: React.FC<{ children?: React.ReactNode }> = ({ children }) => {
-  const { user } = useAuth();
-  return user ? <>{children}</> : <LoginScreen />;
-};
-
-const router: RouteParam = {
-  path: "/dashboard",
-  component: ProtectedRoute,
-  routes: [
-    // Protected routes here
-  ],
-};
-```
-
-## Platform Differences
-
-### React Native
-- Uses React Navigation internally
-- Native animations and gestures
-- Hardware back button support
-- Bottom tab navigation
-
-### Web
-- Uses React Router internally
-- Browser URL integration
-- Keyboard navigation
-- Top tab or sidebar navigation
-
-The API remains identical across platforms.
-
-## Best Practices for LLMs
-
-1. **Start with examples** - Use ExampleStackRouter, ExampleTabRouter, or ExampleDrawerRouter
-2. **Choose appropriate layouts** - Stack for mobile, tabs for sections, drawer for desktop
-3. **Use GeneralLayout** for header/sidebar layouts
-4. **Keep routes shallow** - Avoid deeply nested structures  
-5. **Leverage theme integration** - Components automatically adapt to theme changes
-6. **Test cross-platform** - Verify navigation works on both React and React Native
-
-## File-Based Documentation Access
-
-Complete documentation is available as markdown files:
-
-```bash
-# Main overview
-README.md
-
-# Component-specific documentation  
-src/context/README.md          # Navigation context and providers
-src/routing/README.md          # Core routing system
-src/layouts/GeneralLayout/README.md  # Layout component
-src/examples/README.md         # Example routers and quick start
-
-# LLM-optimized reference
-CLAUDE.md                      # This file
-```
-
-## Import Patterns
-
-```tsx
-// Core navigation
-import { NavigatorProvider, useNavigator } from '@idealyst/navigation';
-
-// Layout components
-import { GeneralLayout } from '@idealyst/navigation';
-
-// Example routers (quick start)
-import { 
-  ExampleStackRouter, 
-  ExampleTabRouter, 
-  ExampleDrawerRouter 
-} from '@idealyst/navigation/examples';
-
-// Theme utilities
-import { getNextTheme } from '@idealyst/navigation/examples/unistyles';
-```
-
-## TypeScript Support
-
-Full type safety for navigation:
-
-```tsx
-// Route configuration is typed
-const router: RouteParam = {
-  path: "/users/:id",
-  component: UserScreen,
-  // TypeScript validates structure
-};
-
-// Navigation is type-safe
-type NavigateParams = {
-  path: string;
-  vars: Record<string, string>;
-};
-```
-
-## Quick Reference
-
-### Essential Imports
-```tsx
-import { NavigatorProvider, useNavigator } from '@idealyst/navigation';
-import { ExampleStackRouter } from '@idealyst/navigation/examples';
-```
-
-### Minimal Setup
-```tsx
-<NavigatorProvider route={ExampleStackRouter} />
-```
-
-### Navigation Usage
-```tsx
-const navigator = useNavigator();
-navigator.navigate({ path: "/route", vars: {} });
-```
-
-### Custom Layout
-```tsx
-<GeneralLayout header={{...}} sidebar={{...}}>
-  {children}
-</GeneralLayout>
-```
-
-This provides everything needed to build sophisticated cross-platform navigation experiences with minimal code.

package/LLM-ACCESS-GUIDE.md

@@ -1,166 +0,0 @@
-# LLM Documentation Access Guide - Navigation
-
-This guide explains exactly how LLMs can access @idealyst/navigation documentation in real-world scenarios.
-
-## Scenario 1: Working in a Project with the Package Installed
-
-When helping a developer who has `@idealyst/navigation` installed in their project:
-
-### Quick Overview
-```bash
-# Read the main documentation file
-cat node_modules/@idealyst/navigation/CLAUDE.md
-```
-This gives you everything in one file - all components, layouts, examples, and patterns.
-
-### Specific Component Details
-```bash
-# Navigation context and providers
-cat node_modules/@idealyst/navigation/src/context/README.md
-
-# Core routing system
-cat node_modules/@idealyst/navigation/src/routing/README.md
-
-# GeneralLayout component
-cat node_modules/@idealyst/navigation/src/layouts/GeneralLayout/README.md
-
-# Example routers and quick start
-cat node_modules/@idealyst/navigation/src/examples/README.md
-```
-
-### Component Discovery
-```bash
-# See all available documentation
-ls node_modules/@idealyst/navigation/src/*/README.md
-
-# Will show:
-# node_modules/@idealyst/navigation/src/context/README.md
-# node_modules/@idealyst/navigation/src/routing/README.md
-# node_modules/@idealyst/navigation/src/layouts/GeneralLayout/README.md
-# node_modules/@idealyst/navigation/src/examples/README.md
-```
-
-## Scenario 2: Repository/GitHub Access
-
-When working with the source repository or GitHub:
-
-### Main Documentation
-- `packages/navigation/README.md` - Complete overview with examples
-- `packages/navigation/CLAUDE.md` - LLM-optimized quick reference
-
-### Component Documentation
-- `packages/navigation/src/context/README.md` - Navigation context system
-- `packages/navigation/src/routing/README.md` - Core routing engine
-- `packages/navigation/src/layouts/GeneralLayout/README.md` - Layout component
-- `packages/navigation/src/examples/README.md` - Example routers
-
-## Scenario 3: Package Manager Info
-
-```bash
-# View package information
-npm info @idealyst/navigation
-
-# View package README
-npm docs @idealyst/navigation
-
-# Download and examine (if needed)
-npm pack @idealyst/navigation
-tar -tf idealyst-navigation-*.tgz | grep README
-```
-
-## Recommended LLM Workflow
-
-### Step 1: Quick Reference
-Start with `CLAUDE.md` for:
-- All navigation components and patterns
-- Layout types (stack, tab, drawer, modal)
-- Example router usage
-- Quick setup instructions
-
-### Step 2: Specific Component Help
-When user asks about specific navigation features:
-1. Read relevant README.md file for complete details
-2. Use the detailed API reference, examples, and best practices
-
-### Step 3: Example Router Discovery
-When user asks "how do I create navigation":
-1. Point to example routers in `src/examples/README.md`
-2. Show ExampleStackRouter, ExampleTabRouter, ExampleDrawerRouter
-3. Explain customization approaches
-
-## File Locations Summary
-
-```
-@idealyst/navigation/
-├── README.md                    # Complete overview + examples
-├── CLAUDE.md                    # LLM quick reference (START HERE)
-├── LLM-ACCESS-GUIDE.md         # This access guide
-├── src/
-│   ├── context/README.md       # Navigation context & providers
-│   ├── routing/README.md       # Core routing system
-│   ├── layouts/
-│   │   └── GeneralLayout/README.md  # Layout component docs
-│   └── examples/README.md      # Example routers & quick start
-```
-
-## Pro Tips for LLMs
-
-1. **Always start with `CLAUDE.md`** - it has everything you need for 90% of navigation questions
-2. **Example routers are key** - ExampleStackRouter, ExampleTabRouter, ExampleDrawerRouter provide working starting points
-3. **Layout types matter** - stack (mobile), tab (sections), drawer (desktop), modal (overlays)
-4. **GeneralLayout is powerful** - flexible header/sidebar component for custom layouts
-5. **Theme integration is automatic** - all navigation components work with @idealyst/theme
-
-## Quick Command Reference
-
-```bash
-# Essential reads for any LLM session
-cat CLAUDE.md                           # Complete navigation reference
-cat README.md                           # Overview + example implementations
-
-# Specific component help
-cat src/context/README.md               # Navigation context
-cat src/routing/README.md               # Routing system
-cat src/layouts/GeneralLayout/README.md # Layout component
-cat src/examples/README.md              # Example routers
-
-# Discovery
-ls src/*/README.md                      # List all component docs
-```
-
-## Navigation-Specific Guidance
-
-### For "How do I set up navigation?" questions:
-1. Start with `src/examples/README.md`
-2. Show ExampleStackRouter for desktop/web apps
-3. Show ExampleTabRouter for mobile apps
-4. Show ExampleDrawerRouter for complex desktop interfaces
-
-### For "How do I customize navigation?" questions:
-1. Read `src/routing/README.md` for route configuration
-2. Read `src/layouts/GeneralLayout/README.md` for layout customization
-3. Show example router customization patterns
-
-### For "How does cross-platform navigation work?" questions:
-1. Reference `src/routing/README.md` platform differences section
-2. Explain React Navigation (Native) vs React Router (Web) integration
-3. Show unified API examples
-
-### For "What layout should I use?" questions:
-- **Stack**: Most mobile apps, hierarchical navigation
-- **Tab**: Main app sections, content browsing  
-- **Drawer**: Desktop apps, admin panels, many sections
-- **Modal**: Forms, dialogs, temporary content
-
-## Common User Questions and File References
-
-| User Question | Primary Reference | Secondary References |
-|---------------|------------------|---------------------|
-| "How do I set up navigation?" | `src/examples/README.md` | `CLAUDE.md`, `README.md` |
-| "What's the difference between layout types?" | `src/routing/README.md` | `CLAUDE.md` |
-| "How do I create a header and sidebar?" | `src/layouts/GeneralLayout/README.md` | `src/examples/README.md` |
-| "How do I navigate between screens?" | `src/context/README.md` | `CLAUDE.md` |
-| "Can you show me a working example?" | `src/examples/README.md` | `README.md` |
-| "How does this work on mobile vs web?" | `src/routing/README.md` | `src/context/README.md` |
-
-This approach ensures LLMs have clear, practical access to all navigation documentation while understanding the quick-start nature of the example routers.