npm package: @mks2508/basecoat-astro-components
Description: Complete collection of Basecoat CSS components and icons for Astro projects, with TypeScript support and custom enhancements
Author: MKS2508
Latest version: 1.0.4

# @mks2508/basecoat-astro-components

Complete collection of **25 UI components** and **12 icons** for Astro projects, built with Basecoat CSS and enhanced with TypeScript support.

## 🚀 Features

- ✅ **25 Production-Ready Components** organized by category
- ✅ **12 Cohesive Icons** for consistent UI design
- ✅ **Full TypeScript Support** with proper Astro component typing
- ✅ **Basecoat CSS Integration** with custom enhancements
- ✅ **Responsive Design** with Tailwind v4 compatibility
- ✅ **Accessibility First** following ARIA guidelines
- ✅ **Zero Configuration** - just install and use

## 📦 Installation

```bash
npm install @mks2508/basecoat-astro-components
```

### Prerequisites

Make sure you have these dependencies in your Astro project:

```bash
npm install astro basecoat-css tailwindcss @tailwindcss/vite
```

### CSS Setup

You need to import Basecoat CSS and configure Tailwind in your project:

#### Option 1: Use the provided CSS file
Copy the example CSS file to your project:

```astro
---
// In your Layout.astro or main CSS file
import '@mks2508/basecoat-astro-components/styles/basecoat.css';
---
```

#### Option 2: Manual CSS setup
Create a CSS file (e.g., `src/styles/global.css`) with:

```css
@import "tailwindcss";
@import "basecoat-css";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... other theme variables */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  
  body {
    @apply bg-background text-foreground;
  }
}
```

### JavaScript Setup (Required for Interactive Components)

Some components require Basecoat's JavaScript. Add this to your layout:

```astro
<!-- In your Layout.astro head section -->
<script is:inline src="https://cdn.jsdelivr.net/npm/basecoat-css@0.3.2/dist/js/all.min.js" defer></script>

<!-- For Toast notifications, add this container to your body -->
<div id="toaster" class="toaster" data-align="end"></div>
```

### Astro Configuration

Configure Tailwind in your `astro.config.mjs`:

```javascript
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()]
  }
});
```

### Interactive Components Requiring JavaScript

These components need the Basecoat JavaScript to function:
- **Dropdown Menu** - Menu interactions and keyboard navigation
- **Popover** - Show/hide and positioning
- **Select** - Dropdown functionality
- **Sidebar** - Toggle and responsive behavior
- **Tabs** - Tab switching and keyboard navigation
- **Toast** - Auto-dismiss and animations

## 🎯 Usage

### Import Components

```astro
---
// Individual imports
import { Button, Card, Alert } from '@mks2508/basecoat-astro-components';
import { SunIcon, MoonIcon } from '@mks2508/basecoat-astro-components';

// Or use direct paths
import Button from '@mks2508/basecoat-astro-components/components/Button.astro';
import SunIcon from '@mks2508/basecoat-astro-components/icons/SunIcon.astro';
---

<Card title="Welcome">
  <p>Hello from Basecoat components!</p>
  <Button variant="primary">
    <SunIcon />
    Click me
  </Button>
</Card>
```

## 🧩 Components

### Form Controls (9 components)
- **Button** - Customizable button with variants and sizes
- **Input** - Text input with validation support
- **Label** - Accessible form labels
- **Select** - Dropdown select with options
- **Textarea** - Multi-line text input with auto-resize
- **Checkbox** - Checkbox with custom styling
- **Switch** - Toggle switch component
- **RadioGroup** - Radio button groups
- **Toggle** - Toggle button component

### Display (8 components)
- **Card** - Flexible card container with slots
- **Alert** - Alert messages with variants (success, warning, error)
- **Badge** - Status badges with color variants
- **Avatar** - User avatar with fallback text
- **Progress** - Progress bar with customizable values
- **Skeleton** - Loading skeleton placeholders
- **Toast** - Toast notifications with event system
- **Breadcrumb** - Navigation breadcrumb trails

### Navigation (6 components)
- **Tabs** - Tabbed interface with accessibility
- **SimpleTabs** - Lightweight tab component
- **Accordion** - Collapsible content sections
- **DropdownMenu** - Dropdown menu with keyboard navigation
- **Sidebar** - Navigation sidebar with groups and submenus
- **Table** - Data table with styling

### Overlays (4 components)
- **AlertDialog** - Modal alert dialogs
- **Modal** - General purpose modal dialogs
- **Popover** - Contextual popover content
- **Tooltip** - Hover tooltips with positioning

## 🎨 Icons (12 components)

- **MonitorIcon** - Display/monitor icon
- **PlusIcon** - Add/plus icon  
- **SettingsIcon** - Settings/gear icon
- **TrashIcon** - Delete/trash icon
- **BoltIcon** - Lightning/performance icon
- **SearchIcon** - Search/magnifying glass icon
- **PaletteIcon** - Color/palette icon
- **DownloadIcon** - Download arrow icon
- **ChevronDownIcon** - Dropdown arrow icon
- **MoonIcon** - Dark mode icon
- **CheckIcon** - Checkmark/success icon
- **SunIcon** - Light mode icon

## 💡 Examples

### Form with Validation
```astro
---
import { Card, Label, Input, Button, Alert } from '@mks2508/basecoat-astro-components';
---

<Card title="Contact Form">
  <form class="space-y-4">
    <div>
      <Label for="email">Email Address</Label>
      <Input id="email" type="email" placeholder="Enter your email" required />
    </div>
    
    <Alert variant="info" title="Info" description="All fields are required." />
    
    <Button variant="primary" type="submit">
      Submit Form
    </Button>
  </form>
</Card>
```

### Navigation with Icons
```astro
---
import { Button, DropdownMenu } from '@mks2508/basecoat-astro-components';
import { SettingsIcon, SunIcon, MoonIcon } from '@mks2508/basecoat-astro-components';
---

<div class="flex items-center gap-2">
  <Button variant="outline">
    <SettingsIcon />
    Settings
  </Button>
  
  <Button variant="ghost" id="theme-toggle">
    <SunIcon id="light-icon" />
    <MoonIcon id="dark-icon" class="hidden" />
  </Button>
</div>
```

## 🎨 Styling

All components use **Basecoat CSS** classes and are fully compatible with **Tailwind v4**. You can customize styling by:

1. **Override CSS Variables** - Modify Basecoat's design tokens
2. **Add Custom Classes** - Use Tailwind utilities alongside component classes
3. **Theme Integration** - Works with any Basecoat-compatible theme

### Example Customization
```astro
<Button variant="primary" class="!bg-purple-600 hover:!bg-purple-700">
  Custom Purple Button
</Button>
```

## 🔧 TypeScript Support

All components include full TypeScript definitions:

```astro
---
// TypeScript interfaces are automatically available
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'link' | 'destructive' | 'icon';
  size?: 'sm' | 'lg';
  disabled?: boolean;
  class?: string;
}
---
```

## 🤝 Contributing

Issues and pull requests welcome at [GitHub repository](https://github.com/MKS2508/basecoat-astro-components).

## 📄 License

MIT License - see [LICENSE](./LICENSE) file for details.

---

Built with ❤️ using [Astro](https://astro.build) and [Basecoat CSS](https://basecoat.org)