npm package: @publikit/bottomnavigation
Description: Mobile horizontal bottom navigation bar component with scrollable items and workspace switcher support
Author: Pirimera
Latest version: 0.1.0

# @publikit/bottomnavigation

Mobile horizontal bottom navigation bar component with scrollable items and optional pinned home item.

## Features

- **Mobile-First** - Designed for mobile devices with `md:hidden` breakpoint
- **Simple & Lightweight** - Minimal dependencies, relies on `@publikit/base`
- **Horizontal Scroll** - Scrollable items with CSS snap scrolling
- **Pinned Home Item** - Optionally pin any item to the left via `homeItemId`
- **Routing Adapter** - Plug in any router (React Router, Next.js, etc.)
- **Type-Safe** - Full TypeScript support with exported types

## Installation

```bash
npm install @publikit/bottomnavigation
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install react react-dom lucide-react tailwindcss @publikit/base
```

### Tailwind CSS Setup

The component uses the following Tailwind utilities that may require configuration:

- `bg-background` - requires a `background` color in your theme
- `scrollbar-none` - requires `tailwind-scrollbar` plugin or custom utility
- `safe-area-inset-bottom` - for iOS safe area support

## Quick Start

```tsx
import { BottomNavigation } from '@publikit/bottomnavigation';
import { Home, Newspaper, MessageSquare } from 'lucide-react';

const items = [
  { id: 'home', name: 'Home', href: '/', icon: Home, badge: null },
  { id: 'feed', name: 'Feed', href: '/feed', icon: Newspaper, badge: 3 },
  { id: 'chat', name: 'Chat', href: '/chat', icon: MessageSquare, badge: null },
];

<BottomNavigation
  config={{
    items,
    homeItemId: 'home',
  }}
/>
```

## With Routing Adapter

```tsx
import { NavLink, useMatch } from 'react-router-dom';

<BottomNavigation
  config={{ items, homeItemId: 'home' }}
  adapters={{ routing: { Link: NavLink, useMatch } }}
/>
```

## With Trailing Content

```tsx
<BottomNavigation
  config={{ items, homeItemId: 'home' }}
  trailing={<WorkspaceSwitcher variant="mobile" />}
/>
```

## With Badge Callback

```tsx
<BottomNavigation
  config={{
    items,
    homeItemId: 'home',
    getItemBadge: (item) => unreadCounts[item.id] ?? null,
  }}
/>
```

## Layout Structure

```
+---------------------------------------------+
| [Home] | [Item1] [Item2] [Item3] | [Trail]  |
|  fixed | ←  scrollable snap  →   |  fixed   |
+---------------------------------------------+
```

- **Home**: Pinned on the left (optional, set via `homeItemId`)
- **Items**: Scrollable middle section with snap
- **Trailing**: Fixed on the right (optional)

## API Reference

### BottomNavigationProps

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `config` | `BottomNavigationConfig` | Yes | Navigation configuration |
| `adapters` | `BottomNavigationAdapters` | No | Optional routing adapter |
| `trailing` | `ReactNode` | No | Trailing content (e.g., workspace switcher) |
| `className` | `string` | No | Additional class for the root `<nav>` element |

### BottomNavigationConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `items` | `NavigationItem[]` | Yes | Navigation items to display |
| `homeItemId` | `string` | No | ID of the item to pin as "home" on the left |
| `getItemBadge` | `(item) => number \| null` | No | Badge value resolver callback |

### NavigationItem

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes | Unique identifier |
| `name` | `string` | Yes | Display label (pre-translated by consumer) |
| `href` | `string` | Yes | Navigation path |
| `icon` | `LucideIcon` | Yes | Icon component from lucide-react |
| `badge` | `number \| null` | Yes | Default badge value (`null` to hide) |
| `visible` | `boolean` | No | Whether item is visible |

## License

MIT