@birhaus/navigation/README.md

BIRHAUS Navigation Components - FourThreeOneNav implementing 4-3-1 cognitive rule

# @birhaus/navigation

BIRHAUS Navigation Components - FourThreeOneNav implementing the 4-3-1 cognitive rule.

## Installation

```bash
npm install @birhaus/navigation
```

## Peer Dependencies

- `react >= 18.0.0`
- `react-dom >= 18.0.0`

## Usage

### FourThreeOneNav

```tsx
import { FourThreeOneNav, ContextualActions, SearchAndCommandPalette } from '@birhaus/navigation'

function AppLayout() {
  const navigationItems = [
    { labelEs: 'Inicio', labelEn: 'Home', href: '/' },
    { labelEs: 'Estudiantes', labelEn: 'Students', href: '/students' },
    { labelEs: 'Cursos', labelEn: 'Courses', href: '/courses' },
    { labelEs: 'Reportes', labelEn: 'Reports', href: '/reports' },
  ] // Max 4 items (4-3-1 rule)

  const contextualActions = [
    { labelEs: 'Exportar', labelEn: 'Export', onClick: handleExport },
    { labelEs: 'Filtrar', labelEn: 'Filter', onClick: handleFilter },
    { labelEs: 'Buscar', labelEn: 'Search', onClick: handleSearch },
  ] // Max 3 actions (4-3-1 rule)

  return (
    <FourThreeOneNav
      navigationItems={navigationItems}
      contextualActions={contextualActions}
      primaryAction={{
        labelEs: 'Crear Nuevo',
        labelEn: 'Create New',
        onClick: handleCreate
      }} // Only 1 primary action (4-3-1 rule)
      logo={<YourLogo />}
      enableCognitiveLoadWarnings={true}
    />
  )
}
```

### Mobile Navigation

```tsx
import { MobileNavigation, MobileMenuButton } from '@birhaus/navigation'

function MobileLayout() {
  return (
    <div>
      <MobileMenuButton />
      <MobileNavigation
        items={navigationItems}
        isOpen={isMenuOpen}
        onClose={closeMenu}
      />
    </div>
  )
}
```

## Features

- **4-3-1 Cognitive Rule**: Enforces max 4 navigation items, 3 contextual actions, 1 primary action
- **Miller's Law**: Prevents cognitive overload with item limits
- **Spanish-first**: Primary labels in Spanish, English fallbacks
- **Mobile Responsive**: Automatic mobile navigation patterns
- **Command Palette**: Integrated search and command system
- **Cognitive Load Warnings**: Alerts when exceeding BIRHAUS limits

## Components

- `FourThreeOneNav` - Main navigation with cognitive rule enforcement
- `DesktopNavigation` - Desktop-specific navigation layout
- `MobileNavigation` - Mobile navigation drawer
- `MobileMenuButton` - Hamburger menu button
- `ContextualActions` - Action buttons with 3-item limit
- `LogoSection` - Logo and branding area
- `SearchAndCommandPalette` - Integrated search functionality

## BIRHAUS Principles

- **Cognitive Load Reduction**: Visual warnings when limits exceeded
- **Undo over Confirm**: Actions are undoable, not confirmed
- **Progressive Disclosure**: Show navigation contextually
- **Accessibility**: Semantic HTML, keyboard navigation, screen reader support

## License

MIT