npm package: @majkapp/plugin-ui
Description: Reusable UI component library for Majk plugins with built-in theming
Author: Majk Contributors
Latest version: 1.5.0

# @majkapp/plugin-ui

Reusable UI component library for Majk plugins with built-in theming support.

**Dual-purpose package:**
1. 📚 **Component Library** - Import reusable UI components in your plugins
2. 🔌 **Installable Plugin** - Install as a plugin to view the Kitchen Sink demo

## Installation

### As a Component Library

```bash
npm install @majkapp/plugin-ui @majkapp/plugin-theme @heroui/react framer-motion
```

### As a Majk Plugin

Install via Majk's plugin system to view the interactive Kitchen Sink demo:

```bash
# In your Majk plugins directory
npm install @majkapp/plugin-ui
```

The plugin will automatically appear in the top bar with a 🎨 icon showing all available components.

## Quick Start

```jsx
import React from 'react';
import { PluginThemeProvider } from '@majkapp/plugin-theme/src/react';
import { KitchenSink } from '@majkapp/plugin-ui';

function App() {
  return (
    <PluginThemeProvider>
      <KitchenSink />
    </PluginThemeProvider>
  );
}
```

## Components

### PluginCard
Themed card component for displaying content.

```jsx
import { PluginCard } from '@majkapp/plugin-ui';

<PluginCard
  title="My Card"
  subtitle="Card subtitle"
  variant="default" // default | primary | highlight | subtle
  hover={true}
  footer={<button>Action</button>}
>
  Card content goes here
</PluginCard>
```

### PluginButton
Themed button with multiple variants.

```jsx
import { PluginButton } from '@majkapp/plugin-ui';

<PluginButton
  variant="primary" // primary | secondary | ghost | danger | success
  size="md" // sm | md | lg
  loading={false}
  disabled={false}
  fullWidth={false}
  startIcon="🚀"
  onClick={() => console.log('clicked')}
>
  Click Me
</PluginButton>
```

### PluginHeader
Page header with title, subtitle, and actions.

```jsx
import { PluginHeader } from '@majkapp/plugin-ui';

<PluginHeader
  title="My Plugin"
  subtitle="Plugin description"
  actions={
    <>
      <PluginButton>Action 1</PluginButton>
      <PluginButton>Action 2</PluginButton>
    </>
  }
/>
```

### PluginChip
Chips/badges for tags, status indicators.

```jsx
import { PluginChip } from '@majkapp/plugin-ui';

<PluginChip
  variant="success" // default | user | assistant | success | warning | error | info
  size="sm"
  onClose={() => console.log('closed')}
>
  Status
</PluginChip>
```

### PluginList & PluginListItem
Display lists of items.

```jsx
import { PluginList, PluginListItem } from '@majkapp/plugin-ui';

<PluginList
  items={[
    {
      icon: '📝',
      title: 'Item 1',
      subtitle: 'Description',
      badge: <PluginChip>New</PluginChip>,
      onClick: () => console.log('clicked')
    }
  ]}
  emptyMessage="No items"
  loading={false}
/>

// Or custom items
<PluginListItem
  avatar="https://..."
  title="Custom Item"
  subtitle="Description"
  selected={false}
  rightContent={<span>Details</span>}
  onClick={() => {}}
/>
```

### PluginActionPanel
Panel for grouping related actions.

```jsx
import { PluginActionPanel } from '@majkapp/plugin-ui';

<PluginActionPanel
  title="Quick Actions"
  actions={[
    { label: 'Create', icon: '➕', onClick: () => {}, variant: 'primary' },
    { label: 'Refresh', icon: '🔄', onClick: () => {} },
    { label: 'Delete', icon: '🗑', onClick: () => {}, variant: 'danger' }
  ]}
/>
```

### PluginStatCard & PluginStatGrid
Display statistics and metrics.

```jsx
import { PluginStatCard, PluginStatGrid } from '@majkapp/plugin-ui';

<PluginStatGrid columns={3}>
  <PluginStatCard
    label="Total Users"
    value="1,234"
    icon="👥"
    trend="up" // up | down | neutral
    trendValue="+12%"
    variant="success"
  />
  <PluginStatCard
    label="Active Tasks"
    value="42"
    icon="📋"
  />
</PluginStatGrid>
```

### KitchenSink
Interactive demo of all components. Use as your default plugin screen during development.

```jsx
import { KitchenSink } from '@majkapp/plugin-ui';

<KitchenSink />
```

## Theming

All components automatically adapt to the current Majk theme using CSS variables from `@majkapp/plugin-theme`. No additional configuration needed!

The theme is injected via URL parameter (`majk_theme`) by the main app, ensuring zero flash and consistent styling.

## Development

```bash
# Install dependencies
npm install

# Build the UI
npm run build

# Use in your plugin
import { PluginCard, PluginButton } from '@majkapp/plugin-ui';
```

## License

MIT