obeyaka-ui 0.1.0

package/README.md

@@ -0,0 +1,285 @@
+# 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