npm package: @liaskos/floating-navigation
Description: A beautiful, accessible floating navigation component for React applications
Author: Alexandros Liaskos
Latest version: 1.0.0

# @pmcs/floating-navigation

> A beautiful, accessible floating navigation component for React applications

[![npm version](https://badge.fury.io/js/%40pmcs%2Ffloating-navigation.svg)](https://badge.fury.io/js/%40pmcs%2Ffloating-navigation)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@pmcs/floating-navigation)](https://bundlephobia.com/package/@pmcs/floating-navigation)

## ✨ Features

- 🎨 **Beautiful Design** - Matches professional UI standards
- ♿ **Fully Accessible** - ARIA compliant with keyboard navigation
- 📱 **Responsive** - Works on desktop, tablet, and mobile
- 🎯 **TypeScript** - Full TypeScript support with comprehensive types
- 🎨 **Themeable** - Customizable design system
- 📦 **Lightweight** - Only ~3KB gzipped
- 🔧 **Zero Config** - Works out of the box with sensible defaults
- 🚀 **Framework Agnostic** - Works with Next.js, CRA, Vite, etc.

## 🚀 Quick Start

### Installation

```bash
npm install @pmcs/floating-navigation
# or
yarn add @pmcs/floating-navigation
# or
pnpm add @pmcs/floating-navigation
```

### Basic Usage

```tsx
import { FloatingNavigation } from '@pmcs/floating-navigation';
import { Home, Folder, Settings, Users } from 'lucide-react';

function App() {
  return (
    <div>
      <FloatingNavigation />
      <main>Your app content...</main>
    </div>
  );
}
```

### Custom Navigation Items

```tsx
import { FloatingNavigation, type NavigationItem } from '@pmcs/floating-navigation';
import { Dashboard, Analytics, Settings, Profile } from 'lucide-react';

const customItems: NavigationItem[] = [
  { id: 'dashboard', icon: Dashboard, label: 'Dashboard', href: '/dashboard' },
  { id: 'analytics', icon: Analytics, label: 'Analytics', href: '/analytics' },
  { id: 'settings', icon: Settings, label: 'Settings', href: '/settings' },
  { id: 'profile', icon: Profile, label: 'Profile', href: '/profile' },
];

function App() {
  return (
    <FloatingNavigation
      items={customItems}
      position="right"
      initialActiveItem="dashboard"
      onItemClick={(item) => {
        console.log('Navigating to:', item.label);
        // Handle navigation (React Router, Next.js Router, etc.)
      }}
    />
  );
}
```

## 📚 API Reference

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `NavigationItem[]` | Default items | Array of navigation items |
| `initialActiveItem` | `string` | `'home'` | ID of initially active item |
| `position` | `'left' \| 'right'` | `'left'` | Position of the navigation |
| `onItemClick` | `(item: NavigationItem) => void` | `undefined` | Click handler for items |
| `style` | `React.CSSProperties` | `undefined` | Custom styles |
| `className` | `string` | `undefined` | CSS class name |

### NavigationItem

```tsx
interface NavigationItem {
  id: string;           // Unique identifier
  icon: LucideIcon;     // Lucide React icon component
  label: string;        // Accessible label
  href?: string;        // Optional URL/route
  disabled?: boolean;   // Optional disabled state
}
```

## 🎨 Theming

### Custom Theme

```tsx
import { FloatingNavigation, createStyles } from '@pmcs/floating-navigation';

const darkTheme = {
  colors: {
    background: 'hsl(220 13% 18%)',
    border: 'hsl(217 19% 27%)',
    active: 'hsl(224 71% 4%)',
    hover: 'hsl(215 28% 17%)',
    text: 'hsl(213 31% 91%)',
  },
  // ... other theme properties
};

function App() {
  return (
    <FloatingNavigation
      style={createStyles(darkTheme).container}
    />
  );
}
```

## 🔌 Framework Integration

### Next.js

```tsx
import { FloatingNavigation } from '@pmcs/floating-navigation';
import { useRouter } from 'next/router';

function Navigation() {
  const router = useRouter();

  return (
    <FloatingNavigation
      onItemClick={(item) => {
        if (item.href) {
          router.push(item.href);
        }
      }}
    />
  );
}
```

### React Router

```tsx
import { FloatingNavigation } from '@pmcs/floating-navigation';
import { useNavigate } from 'react-router-dom';

function Navigation() {
  const navigate = useNavigate();

  return (
    <FloatingNavigation
      onItemClick={(item) => {
        if (item.href) {
          navigate(item.href);
        }
      }}
    />
  );
}
```

## 🎯 Examples

### E-commerce App
```tsx
const ecommerceItems = [
  { id: 'home', icon: Home, label: 'Home', href: '/' },
  { id: 'products', icon: Package, label: 'Products', href: '/products' },
  { id: 'cart', icon: ShoppingCart, label: 'Cart', href: '/cart' },
  { id: 'orders', icon: Receipt, label: 'Orders', href: '/orders' },
];

<FloatingNavigation items={ecommerceItems} />
```

### Admin Dashboard
```tsx
const adminItems = [
  { id: 'dashboard', icon: BarChart3, label: 'Dashboard', href: '/admin' },
  { id: 'users', icon: Users, label: 'Users', href: '/admin/users' },
  { id: 'settings', icon: Settings, label: 'Settings', href: '/admin/settings' },
  { id: 'analytics', icon: TrendingUp, label: 'Analytics', href: '/admin/analytics' },
];

<FloatingNavigation items={adminItems} position="right" />
```

## 🧪 Testing

The component includes built-in accessibility features and can be tested using standard React testing libraries:

```tsx
import { render, screen } from '@testing-library/react';
import { FloatingNavigation } from '@pmcs/floating-navigation';

test('renders navigation items', () => {
  render(<FloatingNavigation />);
  
  expect(screen.getByLabelText('Home')).toBeInTheDocument();
  expect(screen.getByLabelText('Projects')).toBeInTheDocument();
});
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT © Alexandros Liaskos

---

<p align="center">
  May the force be with you - Alexandros Liaskos
</p>