# 🌍 Logosphere UI
A modern, framework-agnostic UI component library built with Lit and Web Components. Works seamlessly with React, Angular, Vue, and Vanilla JavaScript.
## ✨ Features
- 🔧 **Framework Agnostic**: Works with React, Angular, Vue, and Vanilla JS
- 🌳 **Tree-shakable**: Import only what you need
- 📦 **Monolith Package**: Single npm package with granular imports
- 🎨 **Modern CSS**: Enterprise-grade CSS architecture with custom design system
- 🚀 **Zero Dependencies**: No utility framework bloat - pure, optimized CSS
- 🔄 **TypeScript**: Full TypeScript support with type declarations
- 📱 **Responsive**: Mobile-first design
- ♿ **Accessible**: Built with accessibility in mind
## 📦 Installation
```bash
npm install logosphere-ui
```
## 🎯 Usage
### 📦 CSS Import (Required)
Logosphere UI uses a modern, enterprise-grade CSS architecture. Simply import the main CSS file:
**In CSS files:**
```css
@import 'logosphere-ui/css';
```
**In JavaScript/TypeScript:**
```javascript
import 'logosphere-ui/css';
```
**In HTML:**
```html
```
#### Features of our CSS Architecture
- ✅ **Modern CSS Variables** - Theme-based design tokens
- ✅ **Scoped Reset** - Custom reset for web components (`.logoui-wrapper`)
- ✅ **No Framework Dependencies** - Pure, optimized CSS
- ✅ **Tree-shakable** - Import only what you use
- ✅ **Dark Mode Support** - Built-in dark theme via `[data-theme="dark"]`
- ✅ **Utility Classes** - Common utilities for rapid development
- ✅ **Icon Font Included** - Unicons icon set bundled
#### Quick Import Reference
| Framework | Import Method | Example |
|-----------|--------------|---------|
| **Vanilla JS** | HTML Link | `` |
| **React** | ES Import | `import 'logosphere-ui/css';` |
| **Angular** | styles.css | `@import 'logosphere-ui/css';` |
| **Vue 3** | main.ts | `import 'logosphere-ui/css';` |
| **Any CSS** | CSS Import | `@import 'logosphere-ui/css';` |
### Vanilla JavaScript / HTML
```html
Click me!
Modal Content
This is a modal
```
### React
```tsx
import React from 'react';
// Import CSS: Choose scoped (recommended) or base
import 'logosphere-ui/css/scoped';
import { Button, Modal, Checkbox } from 'logosphere-ui/react';
function App() {
const [isOpen, setIsOpen] = React.useState(false);
return (
setIsOpen(false)}
>
React Modal
console.log(e.detail.checked)}
/>
);
}
export default App;
```
### Angular
```typescript
// app.module.ts
import { NgModule } from '@angular/core';
import { LogosphereButtonModule } from 'logosphere-ui/angular/button';
import { LogosphereModalModule } from 'logosphere-ui/angular/modal';
@NgModule({
imports: [
LogosphereButtonModule,
LogosphereModalModule,
// ... other imports
],
// ...
})
export class AppModule { }
```
```typescript
// app.component.ts
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
template: \`
Open Modal
Angular Modal
Modal content here
\`,
styleUrls: ['./app.component.css']
})
export class AppComponent {
isModalOpen = false;
openModal() {
this.isModalOpen = true;
}
closeModal() {
this.isModalOpen = false;
}
}
```
**Import CSS in your global styles:**
```css
/* src/styles.css */
@import 'logosphere-ui/css/scoped'; /* Recommended */
```
**Or add to angular.json:**
```json
{
"projects": {
"your-app": {
"architect": {
"build": {
"options": {
"styles": [
"node_modules/logosphere-ui/dist/logosphere-scoped.css",
"src/styles.css"
]
}
}
}
}
}
}
```
### Vue 3
```typescript
// main.ts
import { createApp } from 'vue';
import LogosphereUI from 'logosphere-ui/vue';
// Import CSS: Choose scoped (recommended) or base
import 'logosphere-ui/css/scoped';
import App from './App.vue';
const app = createApp(App);
app.use(LogosphereUI);
app.mount('#app');
```
```vue
Open Modal
Vue Modal
```
## 🔧 Framework Integration Paths
### Individual Component Imports (Tree-shaking friendly)
```javascript
// Vanilla JS
import 'logosphere-ui/button';
import 'logosphere-ui/modal';
// React
import { Button, Modal } from 'logosphere-ui/react';
// Angular (granular modules)
import { LogosphereButtonModule } from 'logosphere-ui/angular/button';
import { LogosphereModalModule } from 'logosphere-ui/angular/modal';
// Vue
import LogosphereUI from 'logosphere-ui/vue';
```
### Complete Import
```javascript
// Import all components (larger bundle)
import 'logosphere-ui';
// React - all components
import * as LogosphereReact from 'logosphere-ui/react';
// Vue - plugin with all components
import LogosphereUI from 'logosphere-ui/vue';
```
## 🎨 Styling & Theming
The library uses Tailwind CSS with a custom design system. The CSS bundle includes:
- Base component styles
- Tailwind utilities
- Design tokens (colors, spacing, typography)
- Icon font (Unicons)
### Custom Themes
You can override CSS custom properties to create custom themes:
```css
:root {
--color-primary: #your-primary-color;
--color-secondary: #your-secondary-color;
/* ... other design tokens */
}
```
## 🛠️ DX Guide
### Quick Start: Adding a New Component
Use the fully automated component generator:
```bash
npm run create-new-component [ComponentName]
```
This will automatically create and configure:
- ✅ Component files with proper structure
- ✅ TypeScript definitions and tests
- ✅ Storybook stories
- ✅ React wrapper in `src/frameworks/react/index.ts`
- ✅ Angular module in `src/frameworks/angular/[ComponentName].ts`
- ✅ Vue support in `src/frameworks/vue/index.ts`
- ✅ Build configuration updates (`vite.build.config.ts`)
- ✅ Package.json exports for component and Angular module
- ✅ Main index.ts export additions
### Manual Steps: Adding a New Component (Advanced)
> **💡 Tip:** Use `npm run create-new-component ComponentName` for automatic setup!
If you prefer manual setup or need to understand the process, follow these **12 detailed steps**:
**Overview:**
1. Create component files and structure
2. Implement the LitElement component
3. Export component properly
4. Update main index.ts export
5. Configure build system (Vite)
6. Add package.json exports
7. Create React wrapper
8. Create Angular module
9. Add Vue support
10. Update Angular build config
11. Update README documentation
12. Verification & testing
**Detailed Implementation:**
#### 1. **Create Component Structure**
```bash
src/
YourComponent/
├── index.ts # Export file
├── your-component.ts # Main component
├── your-component.stories.ts # Storybook stories
└── your-component.test.ts # Tests
```
#### 2. **Component Implementation**
```typescript
// src/YourComponent/your-component.ts
import { html, LitElement, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';
@customElement('logosphere-your-component')
export class YourComponent extends LitElement {
@property({ type: String }) variant: 'primary' | 'secondary' = 'primary';
static styles = css`
/* Component styles */
`;
render() {
return html`
`;
}
}
```
#### 3. **Export Component**
```typescript
// src/YourComponent/index.ts
export * from './your-component.js';
```
#### 4. **Update Main Index File**
```typescript
// src/index.ts
export * from './YourComponent/index.js';
```
#### 5. **Update Build Configuration**
```typescript
// vite.build.config.ts
const componentEntries: Record = {
// ... existing components
yourcomponent: resolve(__dirname, 'src/YourComponent/index.ts'),
};
```
#### 6. **Update Package.json Exports**
```json
{
"exports": {
"./yourcomponent": {
"types": "./dist/yourcomponent.d.ts",
"import": "./dist/yourcomponent.js",
"require": "./dist/yourcomponent.cjs"
}
}
}
```
#### 7. **Add React Wrapper**
```typescript
// src/frameworks/react/index.ts
import { YourComponent as YourComponentWC } from '../../YourComponent/index.js';
export const YourComponent = createComponent({
tagName: 'logosphere-your-component',
elementClass: YourComponentWC,
react: React,
events: {
onChange: 'change'
}
});
```
#### 8. **Add Angular Module**
```typescript
// src/frameworks/angular/your-component.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { CommonModule } from '@angular/common';
import '../../YourComponent/index.js';
@NgModule({
imports: [CommonModule],
schemas: [CUSTOM_ELEMENTS_SCHEMA],
declarations: [],
exports: []
})
export class LogosphereYourComponentModule {}
export { YourComponent } from '../../YourComponent/index.js';
```
#### 9. **Add Vue Support**
```typescript
// src/frameworks/vue/index.ts
// Import the component
import '../../YourComponent/index.js';
// Add to tag name exports
export const LogosphereYourComponent = 'logosphere-your-component';
// Add to useLogosphereComponents
export const useLogosphereComponents = () => {
return {
// ... existing components
LogosphereYourComponent
};
};
```
#### 10. **Update Build Configuration for Angular Export**
```typescript
// vite.build.config.ts
const componentEntries: Record = {
// ... existing entries
'angular/your-component': resolve(__dirname, 'src/frameworks/angular/your-component.ts'),
};
```
```json
// package.json exports
{
"./angular/your-component": {
"types": "./dist/angular/your-component.d.ts",
"import": "./dist/angular/your-component.js",
"require": "./dist/angular/your-component.cjs"
}
}
```
#### 11. **Update README Documentation**
Add your component to the components table:
```markdown
| YourComponent | `logosphere-ui/yourcomponent` | Description of your component |
```
#### 12. **Verification & Testing**
After completing all manual steps, verify everything works:
```bash
# 1. Build the project
npm run build
# 2. Check for linting errors
npm run lint
# 3. Run tests
npm run test
# 4. Test version bump (optional)
npm run version:alpha
# 5. Check package contents
npm pack
```
**Verify files are created:**
- ✅ `dist/yourcomponent.js` and `dist/yourcomponent.cjs`
- ✅ `dist/yourcomponent.d.ts`
- ✅ `dist/angular/your-component.js` and `.d.ts`
- ✅ React wrapper exports `YourComponent`
- ✅ Vue plugin includes component
**Test the component:**
```bash
# Test imports work
node -e "console.log(require('./dist/yourcomponent.cjs'))"
node -e "import('./dist/yourcomponent.js').then(console.log)"
```
### ⚠️ **Critical Requirements**
#### **Naming Conventions:**
- ✅ **Component tag**: `logosphere-{component-name}` (kebab-case)
- ✅ **Class name**: `{ComponentName}` (PascalCase)
- ✅ **File names**: `{component-name}.ts` (kebab-case)
- ✅ **Export paths**: `./componentname` (lowercase, no hyphens)
#### **TypeScript:**
- ✅ Always export types and interfaces
- ✅ Use proper JSDoc comments
- ✅ Ensure `@customElement` decorator is used
- ✅ All properties must use `@property` decorator
#### **Styling:**
- ✅ Use Tailwind CSS classes
- ✅ Follow design token system
- ✅ Test responsiveness
- ✅ Ensure accessibility (ARIA attributes)
#### **Testing:**
- ✅ Write unit tests for all public methods
- ✅ Test property changes
- ✅ Test event emissions
- ✅ Test accessibility features
#### **Events:**
- ✅ Use CustomEvent for component events
- ✅ Follow naming convention: `component-action` (e.g., `modal-close`)
- ✅ Include proper event detail data
#### **Build Verification:**
```bash
# After adding component, always run:
npm run build # Verify build works
npm run lint # Check for lint errors
npm run test # Run tests
npm pack # Test package contents
```
### 📋 **Checklist for New Components**
- [ ] Component file created with proper naming
- [ ] `@customElement` decorator with correct tag name
- [ ] Export added to main index.ts
- [ ] Build config updated (vite.build.config.ts)
- [ ] Package.json exports updated
- [ ] React wrapper added
- [ ] Angular module created
- [ ] Vue support added
- [ ] Tests written and passing
- [ ] Stories created for Storybook
- [ ] README documentation updated
- [ ] Build verification completed
### 🔄 **Version Management & Publishing**
The library uses semantic versioning with intelligent prerelease handling:
#### **Pre-release Versions (Development/Testing)**
```bash
# Alpha releases (early development)
npm run publish:alpha
# Examples: 1.0.0 → 1.0.1-alpha.0 → 1.0.1-alpha.1
# Beta releases (feature complete, testing)
npm run publish:beta
# Examples: 1.0.0 → 1.0.1-beta.0 → 1.0.1-beta.1
```
#### **Stable Releases (Production)**
```bash
# Patch releases (bug fixes)
npm run publish:patch
# Examples: 1.0.0 → 1.0.1 or 1.0.1-alpha.2 → 1.0.1
# Minor releases (new features)
npm run publish:minor
# Examples: 1.0.0 → 1.1.0 or 1.0.1-beta.1 → 1.1.0
# Major releases (breaking changes)
npm run publish:major
# Examples: 1.0.0 → 2.0.0 or 1.5.3-alpha.1 → 2.0.0
```
#### **Versioning Logic**
**Alpha/Beta Rules:**
- If current version is alpha → increments alpha number
- If current version is beta → increments beta number
- If current version is stable → bumps patch and adds alpha.0/beta.0
**Stable Release Rules:**
- **Patch**: Increments patch number, removes prerelease
- **Minor**: Increments minor, resets patch to 0, removes prerelease
- **Major**: Increments major, resets minor and patch to 0, removes prerelease
| Current Version | Command | New Version | Description |
|---|---|---|---|
| `1.0.0` | `publish:alpha` | `1.0.1-alpha.0` | First alpha of next patch |
| `1.0.1-alpha.0` | `publish:alpha` | `1.0.1-alpha.1` | Increment alpha |
| `1.0.1-alpha.2` | `publish:beta` | `1.0.1-beta.0` | Switch to beta |
| `1.0.1-beta.0` | `publish:beta` | `1.0.1-beta.1` | Increment beta |
| `1.0.1-alpha.3` | `publish:patch` | `1.0.1` | Remove prerelease |
| `1.0.1-beta.2` | `publish:minor` | `1.1.0` | Minor bump, remove prerelease |
| `1.5.3-alpha.1` | `publish:major` | `2.0.0` | Major bump, remove prerelease |
#### **Installation Examples**
```bash
# Latest stable
npm install logosphere-ui
# Alpha version (latest)
npm install logosphere-ui@alpha
# Beta version (latest)
npm install logosphere-ui@beta
# Specific version
npm install logosphere-ui@1.2.3-alpha.1
```
#### **Testing Version Changes (No Git/Publish)**
```bash
# Test version bumps without git tags or publishing
npm run version:alpha # Test alpha version bump
npm run version:beta # Test beta version bump
npm run version:patch # Test patch version bump
npm run version:minor # Test minor version bump
npm run version:major # Test major version bump
```
#### **Release Workflow Examples**
**Feature Development:**
```bash
# 1. Create new component
npm run create-new-component NewFeature
# 2. Alpha testing
npm run publish:alpha
# → 1.0.0 → 1.0.1-alpha.0
# 3. More alpha iterations
npm run publish:alpha
# → 1.0.1-alpha.0 → 1.0.1-alpha.1
# 4. Beta testing
npm run publish:beta
# → 1.0.1-alpha.1 → 1.0.1-beta.0
# 5. Stable release
npm run publish:minor
# → 1.0.1-beta.0 → 1.1.0
```
**Bug Fix:**
```bash
# 1. Fix implemented
# 2. Alpha test
npm run publish:alpha
# → 1.1.0 → 1.1.1-alpha.0
# 3. Stable patch
npm run publish:patch
# → 1.1.1-alpha.0 → 1.1.1
```
### 🚨 **Common Issues & Troubleshooting**
#### **Build Errors:**
```bash
# Clear dist and rebuild
rm -rf dist/
npm run build
# Clear node_modules if needed
rm -rf node_modules package-lock.json
npm install
```
#### **TypeScript Errors:**
- ✅ Ensure all components use `@customElement` decorator
- ✅ Check import paths end with `.js` (not `.ts`)
- ✅ Verify `tsconfig.json` includes the component directory
- ✅ Run `npm run build:types` to check declaration generation
#### **React Wrapper Issues:**
- ✅ Component must be imported before creating wrapper
- ✅ Events must be mapped correctly in `createComponent`
- ✅ React peer dependencies must be installed
#### **Angular Module Issues:**
- ✅ Add `CUSTOM_ELEMENTS_SCHEMA` to module
- ✅ Import component before module definition
- ✅ Export both module and component class
#### **CSS/Styling Issues:**
- ✅ Ensure Tailwind CSS is imported: `import 'logosphere-ui/dist/logosphere-ui.css'`
- ✅ Check CSS bundle is built: `npm run build:css-bundle`
- ✅ Verify component styles use Tailwind classes
#### **Package Publication:**
```bash
# Check what will be published
npm pack
# Verify package.json exports
npm pkg fix
# Check build output
npm run build
ls -la dist/
```