npm package: @rmx-ui/ui-library-core
Description: Modern atomic design component library built with Stencil.js - Tree-shakeable, framework-agnostic web components for React, Vue, Angular, and Vanilla JS
Author: Luis Velito
Latest version: 1.0.4

# 🎨 UI Library Ecosystem - Complete Boilerplate

**Production-ready boilerplate for building modern component libraries with atomic design principles.**

[![npm version](https://badge.fury.io/js/%40rmx-ui%2Fui-library-core.svg)](https://badge.fury.io/js/%40rmx-ui%2Fui-library-core)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Start

### NPM Installation (Recommended)

```bash
# For React (needs TypeScript types for JSX)
npm install @rmx-ui/ui-library-core @rmx-ui/types

# For Vue (no additional types needed)
npm install @rmx-ui/ui-library-core

# For Angular (no additional types needed)
npm install @rmx-ui/ui-library-core

# Framework-specific wrappers (optional)
npm install @rmx-ui/ui-library-react    # React
npm install @rmx-ui/ui-library-vue      # Vue  
npm install @rmx-ui/ui-library-angular  # Angular
```

### CDN Usage (For prototyping)

```html
<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rmx-ui/ui-library-core@latest/dist/cdn/ui-library.css">

<!-- JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/@rmx-ui/ui-library-core@latest/dist/cdn/ui-library.min.js"></script>

<!-- Use components -->
<ui-avatar src="avatar.jpg" size="lg"></ui-avatar>
<contact-cell name="John Doe" email="john@example.com"></contact-cell>
```

## 📦 Usage Examples

### React

```bash
npm install @rmx-ui/ui-library-core @rmx-ui/types
```

```typescript
// Add to src/react-app-env.d.ts
/// <reference types="react-scripts" />
/// <reference types="@rmx-ui/types/react" />
```

```tsx
import React from 'react';
import '@rmx-ui/ui-library-core/dist/ui-library/ui-library.css';
import { defineCustomElements } from '@rmx-ui/ui-library-core/loader';

defineCustomElements();

function App() {
  return (
    <div>
      <ui-avatar src="avatar.jpg" size="lg" />
      <contact-cell name="John Doe" />
    </div>
  );
}
```

### Vue

```bash
npm install @rmx-ui/ui-library-core
```

```javascript
// In main.js
import { defineCustomElements } from '@rmx-ui/ui-library-core/loader';
import '@rmx-ui/ui-library-core/dist/ui-library/ui-library.css';

defineCustomElements();
```

```vue
<template>
  <div>
    <ui-avatar src="avatar.jpg" size="lg" />
    <contact-cell name="John Doe" />
  </div>
</template>
```

### Angular

```bash
npm install @rmx-ui/ui-library-core
```

```javascript
// In main.ts
import { defineCustomElements } from '@rmx-ui/ui-library-core/loader';
defineCustomElements();
```

```typescript
// In angular.json, add to styles array:
"@rmx-ui/ui-library-core/dist/ui-library/ui-library.css"

// In app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

// In component
@Component({
  template: `
    <ui-avatar src="avatar.jpg" size="lg"></ui-avatar>
    <contact-cell name="John Doe"></contact-cell>
  `
})
export class AppComponent {}
```

## 🏗️ Atomic Design Architecture

### 🔸 Atoms (Basic building blocks)
- `ui-avatar` - User avatars with multiple fallback options
- `ui-icon` - SVG icon system
- `status-badge` - Status indicators
- `status-icon` - Status icons
- `ui-text` - Typography component

### 🧬 Molecules (Component combinations)
- `contact-cell` - Contact information display
- `contact-info-cell` - Interactive contact info
- `order-id-cell` - Order IDs with notifications
- `status-cell` - Status display cells
- `table-header-cell` - Sortable table headers

### 🦠 Organisms (Complex components)
- `repair-orders-table` - Complete data tables
- `table-header` - Table header rows
- `table-row` - Table data rows

## ✨ Features

- 🌳 **Tree-shaking support** - Import only what you need
- 📱 **Framework agnostic** - React, Vue, Angular, Vanilla JS
- 🎨 **Atomic design** - Scalable component architecture
- 📦 **Multiple distributions** - NPM, CDN, ESM, CJS
- 🔷 **TypeScript first** - Full type safety
- 🎭 **Shadow DOM** - Encapsulated styles
- 📖 **Storybook** - Interactive documentation
- 🧪 **Fully tested** - Unit and E2E tests
- 🚀 **Production ready** - Used in real applications

## 📋 Browser Support

- Chrome 61+
- Firefox 63+
- Safari 10.1+
- Edge 79+

## 🛠️ Development

This is a complete boilerplate for building your own component library:

```bash
# Clone the repository
git clone https://github.com/lvelitoruiz/mfl-boilerplate.git

# Install dependencies
npm install

# Start development servers
npm run start

# Build for production
npm run build:all
```

### Available Services

- **Storybook**: http://localhost:6006/
- **React Test App**: http://localhost:3000
- **Angular Test App**: http://localhost:4200/
- **Vue Test App**: http://localhost:5173/
- **CDN Demo**: http://localhost:8000/

## 📚 Documentation

- [Storybook](http://localhost:6006/) - Interactive component playground
- [Development Guide](./DEVELOPMENT_GUIDE.md) - How to extend and customize
- [Component API](./docs/components/) - Detailed component documentation

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) first.

## 📄 License

MIT © [RMX UI Library](./LICENSE)

---

## 🎯 Using This as a Boilerplate

This repository serves as a complete boilerplate for building component libraries. To adapt it for your own project:

### 1. Change Organization/Scope

Update `package.json` files to use your scope:

```json
{
  "name": "@your-org/ui-library-core"
}
```

### 2. Update Branding

- Replace "RMX UI" with your library name
- Update README.md, package.json descriptions
- Customize design tokens in `/core/ui-library/src/tokens/`

### 3. Customize Components

- Modify existing components in `/core/ui-library/src/components/`
- Follow atomic design principles
- Update stories in Storybook

### 4. Deploy Your Library

```bash
# Build everything
npm run build:all

# Publish to NPM
npm publish --access public
```

## 🔄 Migration from RMX UI

If you're migrating from `@rmx-ui/*` packages:

```bash
# Old
npm install @rmx-ui/ui-library-core

# New (your packages)
npm install @your-org/ui-library-core
```

The API remains the same, only the package names change.

## 🌟 Showcase

Built with this boilerplate:
- [RMX UI Library](https://rmx-ui.dev) - The original implementation
- Your library here! (Submit a PR to be featured)

## 🔧 Development Commands

Each package can be developed and published independently while sharing the same core web components.