npm package: @mks2508/mobile-bottom-nav
Description: Production-ready mobile bottom navigation for Next.js with advanced viewport handling
Author: MKS2508
Latest version: 4.0.0

# @mks/mobile-bottom-nav

Production-ready mobile bottom navigation component for Next.js with advanced viewport handling, SSR support, and complete TypeScript integration.

## Features

- 🚀 **Next.js Optimized**: Full SSR/CSR support with Next.js Link and Image
- 📱 **Advanced Viewport Handling**: Supports `100dvh`, `100svh`, `100lvh` with fallbacks
- 🎨 **Tailwind CSS**: 95% utility classes, minimal custom CSS
- 🔧 **TypeScript**: Complete type safety and IntelliSense
- ♿ **Accessible**: WCAG compliant with ARIA attributes
- 🎯 **Platform Detection**: iOS/Android specific optimizations
- 🛡️ **Safe Area Support**: Respects device notches and home indicators
- 🖼️ **Flexible Icons**: Support for React components or Next/Image
- 🎭 **Multiple Variants**: Default, floating, and minimal styles
- 📦 **Lightweight**: ~8KB minified + gzipped

## Installation

```bash
npm install @mks/mobile-bottom-nav
# or
yarn add @mks/mobile-bottom-nav
# or
bun add @mks/mobile-bottom-nav
```

## Quick Start

```tsx
import { MobileBottomNav } from '@mks/mobile-bottom-nav'
import '@mks/mobile-bottom-nav/styles' // Critical CSS (~1KB)
import { Home, Search, Plus, Heart, User } from 'lucide-react'

const navItems = [
  { 
    name: 'Home', 
    href: '/', 
    icon: Home,
    alt: 'Go to homepage'
  },
  { 
    name: 'Search', 
    href: '/search', 
    icon: Search 
  },
  { 
    name: 'Create', 
    href: '/create', 
    icon: Plus,
    badge: '3' // Optional badge
  },
  { 
    name: 'Favorites', 
    href: '/likes', 
    icon: Heart 
  },
  { 
    name: 'Profile', 
    href: '/profile', 
    icon: User 
  }
]

export default function Layout({ children }) {
  return (
    <>
      {children}
      <MobileBottomNav 
        items={navItems}
        variant="default"
        showLabels={true}
        iconSize="md"
      />
    </>
  )
}
```

## Advanced Usage

### With Next/Image

```tsx
const navItems = [
  {
    name: 'Dashboard',
    href: '/dashboard',
    image: {
      src: '/icons/dashboard.svg',
      alt: 'Dashboard icon',
      width: 24,
      height: 24
    }
  },
  // Mix icons and images
  {
    name: 'Settings',
    href: '/settings',
    icon: Settings // Lucide icon
  }
]
```

### Floating Variant

```tsx
<MobileBottomNav 
  items={navItems}
  variant="floating" // Adds margin and rounded corners
  className="shadow-2xl" // Additional styling
/>
```

### Controlled Active State

```tsx
function MyApp() {
  const [activeIndex, setActiveIndex] = useState(0)
  
  return (
    <MobileBottomNav 
      items={navItems}
      activeIndex={activeIndex}
      onNavigate={(item, index) => {
        console.log('Navigating to:', item.href)
        setActiveIndex(index)
      }}
    />
  )
}
```

### Custom Active Indicator

```tsx
<MobileBottomNav 
  items={navItems}
  showActiveIndicator={true}
  activeIndicator={
    <div className="absolute -bottom-1 w-8 h-1 bg-gradient-to-r from-blue-500 to-purple-500 rounded-full" />
  }
/>
```

### External Links

```tsx
const navItems = [
  {
    name: 'Documentation',
    href: 'https://docs.example.com',
    icon: Book,
    useNextLink: false // Forces regular anchor tag
  }
]
```

## Props

### MobileBottomNavProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `NavItemConfig[]` | Required | Navigation items configuration |
| `className` | `string` | - | Additional container classes |
| `activeIndex` | `number` | - | Controlled active item index |
| `onNavigate` | `(item, index) => void` | - | Navigation callback |
| `debug` | `boolean` | `false` | Show debug information |
| `variant` | `'default' \| 'floating' \| 'minimal'` | `'default'` | Visual style variant |
| `showLabels` | `boolean` | `true` | Show text labels |
| `iconSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Icon size |
| `showActiveIndicator` | `boolean` | `false` | Show active indicator |
| `activeIndicator` | `ReactNode` | - | Custom active indicator |
| `sticky` | `boolean` | `true` | Use sticky positioning |
| `zIndex` | `number` | `40` | Z-index value |

### NavItemConfig

| Prop | Type | Description |
|------|------|-------------|
| `name` | `string` | Display text |
| `href` | `string` | Navigation URL |
| `alt` | `string` | Accessibility text |
| `icon` | `ComponentType` | React icon component |
| `image` | `object` | Next/Image config |
| `badge` | `ReactNode` | Badge content |
| `onClick` | `() => void` | Click handler |
| `className` | `string` | Item classes |
| `useNextLink` | `boolean` | Force Link usage |

## Styling

The component uses Tailwind CSS classes. Ensure your project has Tailwind configured.

### Required Tailwind Classes

The component expects these Tailwind utilities:
- Layout: `flex`, `sticky`, `fixed`, `bottom-0`
- Spacing: `px-2`, `py-1`, `mb-1`
- Colors: `bg-background`, `text-primary`, `text-muted-foreground`
- Effects: `backdrop-blur-md`, `border`, `rounded-lg`
- Animations: `transition-all`, `duration-200`, `active:scale-95`

### Custom CSS Variables

Add to your global CSS for theming:

```css
:root {
  --navbar-bottom: 0px; /* Set dynamically by component */
}
```

## Browser Support

- Chrome/Edge 108+ (100dvh support)
- Safari iOS 15.4+
- Firefox 101+
- Samsung Internet 19+

Includes automatic fallbacks for older browsers.

## TypeScript

Full TypeScript support with exported types:

```tsx
import type { 
  NavItemConfig, 
  MobileBottomNavProps,
  NavVariant,
  IconSize 
} from '@mks/mobile-bottom-nav'
```

## Performance

- Lazy loads images with Next/Image
- Uses React.memo for items
- Throttled viewport listeners (60fps)
- CSS containment for reflow optimization
- Touch-optimized with `touch-action: manipulation`

## Accessibility

- Semantic HTML with `<nav>` element
- ARIA labels and current page indication
- Keyboard navigation support
- Focus indicators
- Screen reader friendly

## License

MIT

## Author

MKS2508