npm package: @rodolfopena/obeyaka-ui
Description: Professional UI component library with React, TypeScript, Storybook, and Mantine
Author: Rodolfo Peña
Latest version: 0.1.1

# Obeyaka UI Library

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)](https://reactjs.org/)
[![Mantine](https://img.shields.io/badge/Mantine-339AF0?style=for-the-badge&logo=mantine&logoColor=white)](https://mantine.dev/)
[![Storybook](https://img.shields.io/badge/Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white)](https://storybook.js.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

Professional UI component library built with React, TypeScript, Storybook, and Mantine 8. Following Atomic Design principles for scalable and maintainable component architecture.

## ✨ Features

- 🎨 **15+ Professional Components** - Atoms, Molecules, and Organisms
- 🔧 **100% TypeScript** - Full type safety and excellent developer experience
- 🎯 **Atomic Design** - Organized components following atomic design principles
- 📱 **Responsive Design** - Mobile-first approach with adaptive layouts
- ♿ **Accessibility First** - WCAG compliant with full keyboard navigation
- ⚡ **Performance Optimized** - Memoized components and efficient rendering
- 🧪 **Comprehensive Testing** - Unit tests for critical components
- 📚 **Rich Documentation** - Storybook stories and detailed READMEs
- 🎨 **Customizable Theming** - Flexible styling with Mantine's theming system

## 🚀 Quick Start

### Prerequisites

- Node.js >= 16.0.0
- npm >= 8.0.0

### Installation

```bash
npm install @obeyaka/ui
```

### Basic Usage

```tsx
import { ActionButton, BoxAvatar, GenericTable } from '@obeyaka/ui';
import { IconPlus, IconUser } from '@tabler/icons-react';

function MyComponent() {
  return (
    <div>
      {/* Action Button */}
      <ActionButton
        icon={IconPlus}
        tooltip="Add new item"
        onClick={() => console.log('clicked')}
      />

      {/* Avatar */}
      <BoxAvatar avatar={{ type: 'emoji', value: '😀' }} size="md" />

      {/* Data Table */}
      <GenericTable
        tableName="Users"
        data={users}
        columns={columns}
        onAddItem={() => openAddModal()}
      />
    </div>
  );
}
```

## 📦 Component Categories

### Atoms (4 components)

Basic building blocks of the UI system.

- **ActionButton** - Professional action button with multiple variants
- **BoxAvatar** - Flexible avatar supporting emoji, image, and placeholder
- **TextButton** - Simple text button with hover and active states
- **Logo** - Brand logo component with customizable sizing

### Molecules (4 components)

Simple component groups combining atoms.

- **ExpandableSearch** - Animated search input that expands from an icon
- **FilterDropdown** - Comprehensive filtering system with active tags
- **Menu** - Dropdown menu with dynamic width and custom styling
- **NavButton** - Navigation button with icon, label, and indicator

### Organisms (7 components)

Complex component groups for specific functionality.

- **AvatarSelector** - Complete avatar selection with emoji, icon, and image pickers
- **GenericTable** - Advanced data table with search, filtering, and sorting
- **InvitedUserCard** - User invitation and management interface
- **NotificationSidebar** - Real-time notification management with infinite scroll
- **PopoverSelector** - Flexible selection component with custom options
- **ShareMenu** - Collaboration interface with user invitation and role management
- **WorkspaceSelector** - Multi-workspace management with search and switching

## 🛠️ Development

### Storybook (Component Development)

Start Storybook development server:

```bash
npm run dev
```

This will start Storybook on `http://localhost:6006`

### Demo App (Component Showcase)

Start the demo application:

```bash
npm run dev:app
```

This will start the demo app on `http://localhost:8081`

### Build

#### Build Storybook

```bash
npm run build:storybook
```

#### Build Demo App

```bash
npm run build:app
```

#### Build Library for npm

```bash
npm run build:lib
```

## 🎨 Theming

The project uses Mantine's theming system. You can customize the theme in:

- `.storybook/theme.ts` - For Storybook
- `src/app/theme.ts` - For the demo app

### Custom Theme Example

```tsx
import { createTheme } from '@mantine/core';

const theme = createTheme({
  primaryColor: 'blue',
  fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
  colors: {
    blue: [
      '#e7f5ff',
      '#d0ebff',
      '#a5d8ff',
      '#74c0fc',
      '#339af0',
      '#228be6',
      '#1c7ed6',
      '#1971c2',
      '#1864ab',
      '#0c528b',
    ],
  },
});
```

## 📁 Project Structure

```
src/
├── components/     # Reusable UI components (for npm)
│   ├── atoms/      # Basic building blocks (4 components)
│   ├── molecules/  # Simple component groups (4 components)
│   ├── organisms/  # Complex component groups (7 components)
│   └── templates/  # Page-level components
├── app/            # Demo application (development only)
│   ├── App.tsx     # Main app component
│   ├── main.tsx    # App entry point
│   ├── pages/      # Demo pages (Home, Components)
│   └── components/ # Demo-specific components
├── stories/        # Storybook stories
├── types/          # TypeScript type definitions
└── index.ts        # Library entry point (for npm)

.storybook/         # Storybook configuration
├── main.ts         # Storybook main config
├── preview.tsx     # Global decorators and parameters
└── theme.ts        # Mantine theme configuration
```

## 🧪 Testing

The library includes comprehensive unit tests for critical components:

```bash
# Run all tests
npm test

# Run tests for specific component
npm test ActionButton
npm test GenericTable
```

### Test Coverage

- ✅ ActionButton - Full test coverage
- ✅ TextButton - Core functionality tests
- ✅ NavButton - Navigation and interaction tests
- ✅ BoxAvatar - Avatar type and state tests
- ✅ GenericTable - Data management tests

## 📚 Documentation

Each component includes:

- **JSDoc Comments** - Comprehensive inline documentation
- **TypeScript Types** - Full type definitions and interfaces
- **Storybook Stories** - Interactive examples and variations
- **README Files** - Detailed documentation for complex organisms
- **Usage Examples** - Real-world implementation examples

## 🚀 Publishing to npm

To publish your component library:

1. Build the library:

   ```bash
   npm run build:lib
   ```

2. Publish to npm:
   ```bash
   npm publish
   ```

## 📝 Scripts

- `npm run dev` - Start Storybook development server
- `npm run dev:app` - Start demo app development server
- `npm run build:storybook` - Build Storybook for production
- `npm run build:app` - Build demo app for production
- `npm run build:lib` - Build library for npm publishing
- `npm run preview` - Preview built demo app
- `npm run lint` - Run ESLint
- `npm run lint:fix` - Fix ESLint issues
- `npm run type-check` - Run TypeScript type checking

## 🤝 Contributing

1. Create your components in `src/components/`
2. Add stories in `src/stories/`
3. Test components in the demo app (`src/app/`)
4. Follow the established patterns and conventions
5. Ensure all components are properly typed with TypeScript
6. Add tests for new components
7. Update documentation

### Development Guidelines

- Follow Atomic Design principles
- Use TypeScript for all components
- Include comprehensive JSDoc comments
- Add Storybook stories for all components
- Write tests for critical functionality
- Ensure accessibility compliance
- Use consistent naming conventions

## 📄 License

MIT License - see LICENSE file for details.

## 🙏 Acknowledgments

- [Mantine](https://mantine.dev/) - Amazing React components library
- [Tabler Icons](https://tabler-icons.io/) - Beautiful icons
- [Storybook](https://storybook.js.org/) - Component development environment
- [React](https://reactjs.org/) - UI library
- [TypeScript](https://www.typescriptlang.org/) - Type safety