npm package: @ixo/ui
Description: IXO UI library
Author: IXO
Latest version: 0.1.17

# @ixo/ui

A comprehensive React UI component library built with **Emotion** and **Mantine**, featuring a complete theming system, extensive icon library, and components designed for impact-focused applications.

## ✨ Features

- 🎨 **Theming System**: Light/dark theme support with customizable theme overrides
- 🧩 **100+ Components**: Buttons, cards, forms, navigation, data display, and specialized components
- 🎯 **Icon Library**: 300+ icons including crypto currencies, SDG icons, and general purpose icons
- 📱 **Responsive**: Mobile-first design with responsive breakpoints
- 🎭 **Emotion CSS-in-JS**: Styled with Emotion for dynamic styling and theme integration
- 📖 **Storybook**: Comprehensive component documentation and playground
- 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
- ⚡ **Tree-shakeable**: Optimized bundle size with selective imports

## 🚀 Installation

```bash
npm install @ixo/ui @emotion/react @emotion/cache
# or
pnpm add @ixo/ui @emotion/react @emotion/cache
# or
yarn add @ixo/ui @emotion/react @emotion/cache
```

## 🛠️ Setup

### 1. Wrap your app with UiProvider

The `UiProvider` is **required** to provide theming context using Emotion's ThemeProvider:

```tsx
import { UiProvider } from "@ixo/ui/components";

function App() {
  return <UiProvider>{/* Your app content */}</UiProvider>;
}
```

### 2. Custom Theme (Optional)

You can customize both light and dark themes:

```tsx
import { UiProvider } from "@ixo/ui/components";

const customLightTheme = {
  colors: {
    focus: "#ff6b35", // Custom accent color
    focusHover: "#ff8c66"
  },
  text: {
    main: "#1a1a1a"
  }
};

const customDarkTheme = {
  colors: {
    focus: "#00d2ff",
    focusHover: "#2ad9ff"
  }
};

function App() {
  return (
    <UiProvider customlightTheme={customLightTheme} customDarkTheme={customDarkTheme}>
      {/* Your app content */}
    </UiProvider>
  );
}
```

### 3. Next.js Setup (SSR Support)

For Next.js applications, add Emotion cache provider:

```tsx
// pages/_app.tsx
import { CacheProvider } from "@emotion/react";
import createCache from "@emotion/cache";
import { UiProvider } from "@ixo/ui/components";

const cache = createCache({ key: "css", prepend: true });

function MyApp({ Component, pageProps }) {
  return (
    <CacheProvider value={cache}>
      <UiProvider>
        <Component {...pageProps} />
      </UiProvider>
    </CacheProvider>
  );
}
```

## 📦 Usage

### Components

```tsx
import { Button, Card, Typography, TextInput, Avatar, Tag } from "@ixo/ui/components";

function MyComponent() {
  return (
    <Card>
      <Typography variant="h2">Welcome to IXO</Typography>

      <Avatar src="/path/to/avatar.jpg" name="John Doe" size="lg" />

      <TextInput label="Email" placeholder="Enter your email" required />

      <Tag value="Verified" color="success" />

      <Button value="Get Started" lg onClick={() => console.log("Button clicked!")} />
    </Card>
  );
}
```

### Icons

```tsx
import { Heart, User, Search, ChevronDown } from "@ixo/ui/icons";

function IconExample() {
  return (
    <div>
      <Heart size={24} color="#ff6b35" />
      <User size={20} />
      <Search size={16} />
    </div>
  );
}
```

### Crypto Icons

```tsx
import { Bitcoin, Ethereum, Solana } from "@ixo/ui/icons/crypto";

function CryptoIcons() {
  return (
    <div>
      <Bitcoin size={32} />
      <Ethereum size={32} />
      <Solana size={32} />
    </div>
  );
}
```

### SDG Icons (Sustainable Development Goals)

```tsx
import { SDG1, SDG2, SDG3 } from "@ixo/ui/icons/sdg";

function SDGIcons() {
  return (
    <div>
      <SDG1 size={48} />
      <SDG2 size={48} />
      <SDG3 size={48} />
    </div>
  );
}
```

### Pictograms

```tsx
import { Services, Impacts, Portfolio } from "@ixo/ui/pictograms";

function PictogramExample() {
  return (
    <div>
      <Services size={64} />
      <Impacts size={64} />
      <Portfolio size={64} />
    </div>
  );
}
```

### Hooks

```tsx
import { useColorScheme, useUITheme, useEventSubscribe } from "@ixo/ui/hooks";

function HookExample() {
  const theme = useUITheme();
  const { isDark, toggle } = useColorScheme();

  return (
    <div style={{ color: theme.text.main }}>
      <p>Current theme: {isDark ? "Dark" : "Light"}</p>
      <button onClick={toggle}>Toggle Theme</button>
    </div>
  );
}
```

## 📚 Available Components

### Layout & Navigation

- `Layout`, `NavigationBar`, `NavButton`, `TabNavigation`, `TabSelector`

### Buttons & Actions

- `Button`, `ButtonBasic`, `ButtonSubtle`, `RoundedButton`, `IconButton`, `ActionCard`

### Data Display

- `Card`, `Table`, `Tag`, `Avatar`, `Typography`, `Chart`, `Tooltip`

### Forms & Inputs

- `TextInput`, `Select`, `Checkbox`, `Switch`, `ComboBox`, `SearchInput`

### Feedback & Loading

- `Loader`, `Modal`, `Toast`, `FeedbackMessage`, `Tooltip`

### Specialized Components

- `ActivityCard`, `ProfileCard`, `EcosystemCard`, `SodaCard`, `PlanCard`
- `EntityList`, `GroupSelector`, `FilterTags`, `ImpactCreditState`

And many more! See the full list in [Storybook](#storybook).

## 🎨 Theme System

The library uses a comprehensive theme system with:

- **Colors**: Focus colors, semantic colors (success, warning, error), neutral shades
- **Typography**: Font sizes, weights, and responsive text scaling
- **Spacing**: Consistent spacing scale for margins and padding
- **Breakpoints**: Mobile-first responsive breakpoints
- **Glass effects**: Modern glassmorphism styling
- **Automatic theme switching**: Based on user preference stored in localStorage

### Theme Structure

```typescript
type UITheme = {
  colors: {
    focus: string;
    focusSecondary: string;
    focusHover: string;
    // ... more colors
  };
  text: {
    main: string;
    secondary: string;
    overPicture: string;
  };
  bg: {
    card: string;
    main: string;
    navbar: string;
    // ... more backgrounds
  };
  semantic: {
    success: string;
    warning: string;
    error: string;
  };
  // ... spacing, radius, etc.
};
```

## 🧑‍💻 Local Development

### Prerequisites

- Node.js 20+
- pnpm 10.6.5+

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd ixo-ui

# Install dependencies
pnpm install
```

### Development Commands

```bash
# Start Storybook development server
pnpm dev

# Build the library
pnpm build

# Build for local testing (creates .tgz package)
pnpm build:local

# Lint code
pnpm lint
pnpm lint:fix

# Format code
pnpm format
pnpm format:check

# Build Storybook for production
pnpm build:storybook
```

### Storybook

Launch the component playground and documentation:

```bash
pnpm dev
```

This will start Storybook at `http://localhost:6006` where you can:

- 📖 Browse all components with live examples
- 🎛️ Interact with component props in real-time
- 🎨 Test different themes and configurations
- 📱 Test responsive behavior
- 📋 Copy code examples
- 🧪 Test accessibility features

### Adding New Components

1. Create component directory: `src/components/MyComponent/`
2. Add implementation: `index.tsx`, `types.ts`
3. Create Storybook story: `MyComponent.stories.tsx`
4. Export from: `src/export/components.ts`
5. Test in Storybook: `pnpm dev`

## 🏗️ Build System

Built with **Vite** and configured for optimal library distribution:

- **Multiple entry points**: Components, hooks, icons, themes
- **Dual format**: ES modules (.mjs) and CommonJS (.cjs)
- **TypeScript declarations**: Full type support
- **Tree-shaking**: Import only what you need
- **Emotion externalization**: Prevents SSR issues
- **Source maps**: For easier debugging

### Build Outputs

```
dist/
├── export/
│   ├── components.mjs/.cjs/.d.ts
│   ├── hooks.mjs/.cjs/.d.ts
│   ├── icons/index.mjs/.cjs/.d.ts
│   ├── icons/crypto.mjs/.cjs/.d.ts
│   ├── icons/sdg.mjs/.cjs/.d.ts
│   ├── pictograms.mjs/.cjs/.d.ts
│   ├── themes.mjs/.cjs/.d.ts
│   └── types.mjs/.cjs/.d.ts
```

## 🤝 Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-component`
3. Add your component with proper TypeScript types
4. Create comprehensive Storybook stories
5. Add component to exports
6. Test thoroughly in Storybook
7. Commit changes: `git commit -m 'Add amazing component'`
8. Push to branch: `git push origin feature/amazing-component`
9. Open a Pull Request