npm package: @shared-cms/badge
Description: A reusable badge component built with Lit, TypeScript, and TailwindCSS. Perfect for notifications, status indicators, and tags.
Author: Your Name
Latest version: 1.0.13

# @shared-cms/badge

A reusable badge component built with Lit, TypeScript, and TailwindCSS. Perfect for notifications, status indicators, tags, and labels.

## ✨ Features

- 🏷️ **Multiple Variants** - Primary, secondary, success, warning, danger, info, and outline styles
- 📏 **Flexible Sizes** - Small, medium, and large options for different use cases
- 🔢 **Count Display** - Perfect for notifications and numeric indicators
- 🔵 **Dot Indicators** - Status dots for online presence and activity states
- 🗑️ **Removable** - Built-in remove functionality with custom events
- 🚀 **Framework Agnostic** - Works with React, Angular, Vue, and vanilla JavaScript
- 📱 **Responsive Design** - Mobile-first, accessible badge component
- 🌙 **Shadow DOM** - Complete style isolation, no CSS conflicts
- 📦 **Lightweight** - Optimized bundle size with minimal dependencies
- 🔧 **TypeScript** - Full TypeScript support with comprehensive type definitions
- ♿ **Accessible** - WCAG compliant with proper ARIA attributes
- 🎯 **Custom Events** - Emits standard and custom events for easy integration

## 📦 Installation

```bash
npm install @shared-cms/badge
# or
yarn add @shared-cms/badge
# or
pnpm add @shared-cms/badge
```

## 🚀 Quick Start

### HTML/Vanilla JavaScript

```html
<!DOCTYPE html>
<html>
<head>
  <script type="module" src="node_modules/@shared-cms/badge/dist/shared-badge.es.js"></script>
</head>
<body>
  <shared-badge label="Primary" variant="primary"></shared-badge>
  <shared-badge count={5} variant="danger"></shared-badge>
  <shared-badge dot variant="success"></shared-badge>
  <shared-badge label="Removable" variant="secondary" removable></shared-badge>

  <script>
    // Listen to custom events
    document.querySelector('shared-badge').addEventListener('badge-click', (e) => {
      console.log('Badge clicked!', e.detail);
    });

    document.querySelector('shared-badge[removable]').addEventListener('badge-remove', (e) => {
      console.log('Badge removed!', e.detail);
    });
  </script>
</body>
</html>
```

### React

#### Natural React Component Usage

```tsx
// Import as default export - most natural for React users
import SharedBadge from '@shared-cms/badge';

function App() {
  const handleRemove = (badge) => {
    console.log('Removing badge:', badge.detail);
  };

  return (
    <div>
      <SharedBadge label="React" variant="primary" />
      <SharedBadge count={12} variant="danger" removable onBadgeRemove={handleRemove} />
      <SharedBadge dot variant="success" />
      <SharedBadge
        label="Click me"
        variant="secondary"
        onClick={() => console.log('badge clicked')}
      />
    </div>
  );
}

export default App;
```

#### Advanced Usage with TypeScript

```tsx
import SharedBadge, { SharedBadgeProps, SharedBadgeElement } from '@shared-cms/badge';
import { useRef, useCallback } from 'react';

function AdvancedExample() {
  const badgeRef = useRef<SharedBadgeElement>(null);

  const handleClick = useCallback((event: React.MouseEvent) => {
    console.log('React onClick triggered!', event);
    badgeRef.current?.focus();
  }, []);

  const handleBadgeClick = useCallback((event: CustomEvent) => {
    console.log('Custom badge-click event!', event.detail);
  }, []);

  const handleRemove = useCallback((event: CustomEvent) => {
    console.log('Badge removed!', event.detail);
    // Remove from UI or update state
  }, []);

  return (
    <SharedBadge
      ref={badgeRef}
      label="Advanced Badge"
      variant="primary"
      onClick={handleClick}
      onBadgeClick={handleBadgeClick}
      onBadgeRemove={handleRemove}
      removable
      id="my-badge"
      aria-label="Status badge"
    />
  );
}
```

#### Different Import Options

```tsx
// Option 1: Default export (recommended for React)
import SharedBadge from '@shared-cms/badge';

// Option 2: Named export
import { ReactSharedBadge } from '@shared-cms/badge';
// Usage: <ReactSharedBadge />

// Option 3: With types
import SharedBadge, { SharedBadgeProps } from '@shared-cms/badge';

// Option 4: For vanilla JS usage
import { LitBadge } from '@shared-cms/badge';
```

## 🎨 API Reference

### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `label` | `string` | `""` | Badge text/content |
| `variant` | `"primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info" \| "outline"` | `"primary"` | Badge style variant |
| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Badge size |
| `count` | `number \| null` | `null` | Numeric count for notifications |
| `removable` | `boolean` | `false` | Whether badge shows remove button |
| `dot` | `boolean` | `false` | Show as dot indicator |
| `disabled` | `boolean` | `false` | Whether badge is disabled |

### Events

| Event | Type | Description |
|-------|------|-------------|
| `badge-click` | `CustomEvent` | Fired when badge is clicked |
| `badge-remove` | `CustomEvent` | Fired when remove button is clicked |
| `click` | `Event` | Standard DOM click event |

### Styling

The component uses TailwindCSS classes internally within Shadow DOM:

```css
/* Primary variant */
.badge-primary {
  @apply bg-blue-600 text-white rounded-full font-medium;
}

/* Count indicator */
.badge-count {
  @apply bg-red-500 text-white text-xs font-bold rounded-full;
}

/* Dot indicator */
.badge-dot {
  @apply w-2 h-2 rounded-full;
}

/* Removable badge */
.badge-remove {
  @apply ml-1 text-gray-400 hover:text-gray-600 cursor-pointer;
}
```

## 🎯 Usage Examples

### Basic Badges

```tsx
<SharedBadge label="Primary" variant="primary" />
<SharedBadge label="Success" variant="success" />
<SharedBadge label="Warning" variant="warning" />
<SharedBadge label="Danger" variant="danger" />
```

### Count Badges

```tsx
<SharedBadge count={5} variant="danger" />
<SharedBadge count={12} variant="info" />
<SharedBadge count={99} variant="warning" />
```

### Dot Indicators

```tsx
<SharedBadge dot variant="success" />  {/* Online */}
<SharedBadge dot variant="warning" />  {/* Away */}
<SharedBadge dot variant="secondary" /> {/* Offline */}
```

### Removable Badges

```tsx
const [tags, setTags] = useState(['React', 'TypeScript', 'Lit']);

return (
  <div>
    {tags.map((tag, index) => (
      <SharedBadge
        key={index}
        label={tag}
        variant="primary"
        removable
        onBadgeRemove={(e) => {
          setTags(prev => prev.filter((_, i) => i !== index));
        }}
      />
    ))}
  </div>
);
```

### Size Variations

```tsx
<SharedBadge label="Small" size="small" variant="primary" />
<SharedBadge label="Medium" size="medium" variant="primary" />
<SharedBadge label="Large" size="large" variant="primary" />
```

## 🔧 Development

```bash
# Install dependencies
npm install

# Start development server
npm run serve

# Build for production
npm run build

# Build and watch for changes
npm run dev
```

## 📁 Project Structure

```
packages/badge/
├── src/
│   ├── Badge.ts               # Main Lit component
│   ├── react-wrapper.tsx      # React wrapper
│   ├── Badge.module.scss      # Component styles
│   ├── index.ts              # Exports
│   └── styles/
│       └── tailwind.css      # TailwindCSS base styles
├── dist/
│   ├── shared-badge.es.js    # ES Module build
│   ├── shared-badge.umd.js   # UMD build
│   └── index.d.ts            # TypeScript definitions
├── package.json
├── README.md
├── LICENSE
└── vite.config.ts
```

## 🌟 Browser Support

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

## 📄 License

MIT License - see LICENSE file for details

## 🔗 Related Packages

- [`@shared-cms/button`](https://npmjs.com/package/@shared-cms/button) - Button component
- [`@shared-cms/card`](https://npmjs.com/package/@shared-cms/card) - Card component
- [`@shared-cms/input`](https://npmjs.com/package/@shared-cms/input) - Input component
- [`@shared-cms/modal`](https://npmjs.com/package/@shared-cms/modal) - Modal component

## 📞 Support

For support, questions, or contributions, please visit our [GitHub repository](https://github.com/your-org/shared-cms) or contact us at support@example.com.