@birhaus/primitives/README.md

BIRHAUS Primitive Components - Enhanced base UI components with DataTable, FilterBar, BulkActions, and cognitive load reduction

# @birhaus/primitives

Base components for the BIRHAUS design system implementing cognitive load reduction and Spanish-first internationalization.

## Installation

```bash
npm install @birhaus/primitives
```

## Key Features

- **Spanish-first design**: All components support `labelEs`/`labelEn` and `tituloEs`/`tituloEn` patterns
- **Cognitive load optimization**: Miller's Law (7±2) compliance built-in
- **Accessibility by design**: WCAG AA+ compliance with semantic HTML
- **Undo-over-confirm patterns**: No annoying confirmation dialogs
- **Performance optimized**: Virtual scrolling and optimistic updates
- **TypeScript first**: Full type safety with strict mode

## Components

### Core Components
- `BirhausButton` - Spanish-first buttons with undo patterns
- `BirhausInput` - Accessible form inputs with cognitive validation
- `BirhausCard` - Progressive disclosure containers
- `BirhausTable` - Data tables with virtual scrolling
- `BirhausSelect` - Dropdowns with Miller's Law compliance

### New Components (v0.8.0)
- `BirhausSearchableList` - Virtual scrolling list with search
- `BirhausResourceCard` - Progressive disclosure for complex data
- `BirhausBadge` - Semantic status indicators
- `BirhausDataTable` - Advanced data management
- `BirhausBulkActionBar` - Bulk operations with undo support

### Layout & Navigation
- `BirhausPageLayout` - Standard page structure
- `BirhausContainer` - Consistent spacing containers
- `BirhausPageHeader` - Page headers with breadcrumbs

## Usage

```tsx
import { BirhausButton, BirhausCard } from '@birhaus/primitives'

function DonationForm() {
  return (
    <BirhausCard
      titleEs="Nueva Donación"
      titleEn="New Donation"
      status="info"
    >
      <BirhausButton
        labelEs="Guardar Donación"
        labelEn="Save Donation"
        variant="primary"
        undoConfig={{
          enabled: true,
          messageEs: "Donación guardada",
          messageEn: "Donation saved"
        }}
        onClick={handleSave}
      />
    </BirhausCard>
  )
}
```

## BIRHAUS Principles

This package implements all core BIRHAUS principles:

1. **Spanish-first**: Primary labels in Spanish, English as fallback
2. **Miller's Law**: Maximum 7±2 items in lists, forms, navigation
3. **Undo over Confirm**: No confirmation dialogs, implement undo instead
4. **Progressive Disclosure**: Show details on demand
5. **Accessibility = Dignity**: WCAG AA+ baseline, semantic HTML
6. **Performance Constraints**: TTI < 2s, FCP < 1s

## Real-world Usage

Perfect for:
- Church administration systems (IPU PY Admin)
- Financial management dashboards
- Educational platforms
- Spanish-speaking user interfaces
- Applications requiring high accessibility

## API Documentation

All components support:
- Spanish-first labeling (`labelEs`, `labelEn`)
- Accessibility props (`aria-*`, `role`)
- Consistent sizing (`sm`, `md`, `lg`)
- Theme integration with `@birhaus/themes`

## Testing

Use `@birhaus/test-utils` for BIRHAUS-specific testing:

```tsx
import { expectBirhausCompliance } from '@birhaus/test-utils'

test('component follows BIRHAUS principles', async () => {
  render(<BirhausButton labelEs="Guardar" labelEn="Save" />)
  await expectBirhausCompliance(screen.getByRole('button'))
})
```

## Contributing

See the [main repository](https://github.com/anthonybir/birhaus-components) for contribution guidelines.

## License

MIT - see [LICENSE](../../LICENSE) for details.