Obeyaka UI Library

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

npm install obeyaka-ui

Setup with ThemeProvider

⚠️ IMPORTANT: Import Mantine CSS styles first

You must import the required Mantine CSS styles before using the components:

// Import Mantine styles (REQUIRED)
import '@mantine/core/styles.css';
// ‼️ import charts styles after core package styles
import '@mantine/charts/styles.css';
import '@mantine/notifications/styles.css';
import '@mantine/dates/styles.css';

// Then wrap your application with ThemeProvider
import { ThemeProvider } from 'obeyaka-ui';

function App() {
  return (
    <ThemeProvider>
      {/* Your application components */}
      <YourApp />
    </ThemeProvider>
  );
}

Full Setup Example:

import '@mantine/core/styles.css';
// ‼️ import charts styles after core package styles
import '@mantine/charts/styles.css';
import '@mantine/notifications/styles.css';
import '@mantine/dates/styles.css';
import '@mantine/spotlight/styles.css';
import '@mantine/code-highlight/styles.css';
import '@mantine/dropzone/styles.css';
import '@mantine/carousel/styles.css';
import '@mantine/nprogress/styles.css';
import '@mantine/tiptap/styles.css';

import { ThemeProvider } from 'obeyaka-ui';

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  );
}

Basic Usage

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

function MyComponent() {
  return (
    <div>
      {/* Action Button */}
      <ActionIcon
        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.

• ActionIcon - 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:

npm run dev

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

Demo App (Component Showcase)

Start the demo application:

npm run dev:app

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

Build

Build Storybook

npm run build:storybook

Build Demo App

npm run build:app

Build Library for npm

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

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:

# 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:

   npm run build:lib

2. Publish to npm:

   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 - Amazing React components library
• Tabler Icons - Beautiful icons
• Storybook - Component development environment
• React - UI library
• TypeScript - Type safety