# bare-v2 JavaScript API

Minimal TypeScript-based JavaScript library for bare-v2 functionality that cannot be achieved with CSS alone.

## Philosophy

**CSS-First Approach**: JavaScript is only used when absolutely necessary:
- ✅ **Toasts**: Require timing, auto-dismiss, dynamic stacking
- ✅ **Theme Management**: Requires localStorage and system preference detection  
- ❌ **Loaders**: Handled by CSS classes (`.loader`, `.btn-loading`)
- ❌ **Animations**: Handled by CSS transitions and keyframes
- ❌ **State Management**: Handled by CSS classes (`.active`, `.disabled`)

## Usage

### CDN / Script Tag
```html
<script src="https://cdn.jsdelivr.net/npm/@livx.cc/bare-v2/dist/bare.min.js"></script>
<script>
  // API is available globally as `bare`
  bare.toast.success('Hello', 'World!');
  bare.theme.toggle();
</script>
```

### ES Modules
```javascript
import bare from '@livx.cc/bare-v2/scripts';

// Or specific modules
import { toast, theme } from '@livx.cc/bare-v2/scripts';
```

## API Reference

### `bare.toast`

Non-blocking notification system with stacking support.

```javascript
// Basic usage
bare.toast.success('Success!', 'Operation completed');
bare.toast.error('Error!', 'Something went wrong');
bare.toast.warning('Warning!', 'Please review');
bare.toast.info('Info', 'Did you know...');

// Advanced usage
const id = bare.toast.show({
  title: 'Custom Toast',
  description: 'With custom options',
  variant: 'default',
  duration: 10000, // 0 = persistent
  icon: '<i class="fa-solid fa-rocket"></i>',
  action: '<button class="btn btn-primary btn-sm">Action</button>'
});

// Dismiss programmatically
bare.toast.dismiss(id);
```

**Variants:** `default`, `success`, `error`, `destructive`, `warning`, `info`

### `bare.theme`

Dark/light theme management with system preference detection.

```javascript
// Toggle between light/dark
bare.theme.toggle();

// Set specific theme
bare.theme.set('dark');
bare.theme.set('light');

// Get current theme
const current = bare.theme.get(); // 'light' | 'dark'

// Manual initialization (called automatically on load)
bare.theme.init();
```

**Features:**
- Automatic system preference detection
- localStorage persistence
- Smooth transitions with CSS
- Custom event dispatching (`bare-theme-change`)

## What's NOT Included

These are handled by CSS classes and don't need JavaScript:

### Loaders
```html
<!-- Pure CSS loaders -->
<div class="loader"></div>
<div class="loader loader-primary loader-lg"></div>

<!-- Button loading states -->
<button class="btn btn-primary btn-loading">Loading...</button>

<!-- Centered loader container -->
<div class="loader-center">
  <div class="loader"></div>
</div>
```

### Animations & States
```html
<!-- CSS handles all visual states -->
<button class="btn btn-primary" disabled>Disabled</button>
<div class="card card-interactive">Hover effects</div>
<div class="toast toast-success">Static toast</div>
```

## Building from Source

```bash
bun run build:scripts      # Build once
bun run dev:scripts        # Build with watch mode
```

## Architecture

- **Minimalist**: Only essential JavaScript functionality
- **Type-safe**: Full TypeScript support with strict typing
- **Framework-agnostic**: Works with any JavaScript framework
- **Lightweight**: ~5KB minified (only toasts + theme)

## Browser Support

- ES2022+ browsers
- Modern bundlers (Webpack, Vite, Rollup, etc.)
- CDN-friendly IIFE bundle included