@gingersnap/toolbox/README.md

A comprehensive Vue 3 component library with Tailwind CSS integration, built with JavaScript

# @gingersnap/toolbox

A comprehensive Vue 3 component library designed for modern admin interfaces and enterprise applications. Built with Tailwind CSS and featuring a complete design system.

## 🎯 Overview

The Workbench Toolbox provides enterprise-grade UI components, design tokens, and composables specifically designed for admin platforms and internal tools. This library emphasizes developer experience, accessibility, and consistent design patterns.

## 📦 Installation

```bash
npm install @gingersnap/toolbox
# or
yarn add @gingersnap/toolbox
# or
pnpm add @gingersnap/toolbox
```

### Peer Dependencies

```bash
npm install vue@^3.4.0 reka-ui@^2.3.0 lucide-vue-next@^0.525.0
```

## 🚀 Quick Start

```vue
<template>
  <div>
    <!-- Use the enhanced modal component -->
    <TbModal v-model:show="showModal" title="Enhanced Modal" size="lg">
      <p>This modal has enhanced TypeScript support and better API</p>
      <template #actions>
        <button @click="showModal = false">Close</button>
      </template>
    </TbModal>

    <!-- Use curated icons -->
    <Edit :size="16" class="text-primary" />
    
    <!-- Use toast notifications -->
    <button @click="toast.success('Operation completed!')">
      Show Toast
    </button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TbModal, Edit, useToast } from '@gingersnap/toolbox'
import '@gingersnap/toolbox/style.css'

const showModal = ref(false)
const { toast } = useToast()
</script>
```

## 📂 Package Structure

```
packages/toolbox/
├── src/
│   ├── components/
│   │   ├── foundations/     # Core components (TbModal, TbSelect, etc.)
│   │   ├── patterns/        # Layout components (TbBreadcrumb, etc.)
│   │   └── feedback/        # User feedback (TbToast, etc.)
│   ├── composables/         # Vue composables (useToast, etc.)
│   ├── icons/              # Curated Lucide icon exports
│   ├── tokens/             # Design tokens and Tailwind preset
│   └── styles/             # Base styles and CSS
├── dist/                   # Built library files
└── docs/                   # Component documentation
```

## 🎨 Design System Features

### Semantic Colors
- **Primary**: Sky-based palette for main actions
- **Secondary**: Gray-based palette for secondary actions  
- **Success**: Emerald-based palette for positive feedback
- **Danger**: Red-based palette for destructive actions

Each color includes variants: `DEFAULT`, `hover`, `focus`, `light`, `muted`

### Typography
- **Font**: Inter font family with web font loading
- **Scales**: Consistent text sizing and line heights

### Layout
- **Radius**: `rounded-base` for consistent border radius
- **Shadow**: `shadow-base` for consistent drop shadows
- **Spacing**: Tailwind's spacing scale

## 🧩 Components

### TbModal
Enhanced modal component with TypeScript support and advanced features:

```vue
<TbModal 
  v-model:show="isOpen"
  title="Modal Title"
  description="Optional description"
  size="lg"
  variant="default"
  :allow-close="true"
  :persistent="false"
  animation="scale"
>
  <p>Modal content</p>
  <template #actions>
    <button @click="isOpen = false">Cancel</button>
    <button @click="handleSave">Save</button>
  </template>
</TbModal>
```

**Props:**
- `show: boolean` - Controls modal visibility
- `size: 'sm' | 'md' | 'lg' | 'xl' | 'full'` - Modal size
- `variant: 'default' | 'destructive'` - Visual variant
- `animation: 'scale' | 'slide' | 'fade'` - Animation type
- `persistent: boolean` - Prevents closing on outside click/escape

## 🔧 Composables

### useToast()
Toast notification system with TypeScript support:

```javascript
import { useToast } from '@gingersnap/toolbox'

const { success, danger, primary, secondary, show, remove, clear } = useToast()

// Convenience methods
success('Operation completed!')
danger('Something went wrong!')

// Custom toast
show({
  type: 'primary',
  title: 'Custom Title',
  message: 'Custom message',
  duration: 5000,
  persistent: false
})
```

## 🎭 Icons

Curated selection of Lucide icons organized by category:

```javascript
import { 
  // Navigation
  ChevronDown, ChevronUp, ArrowLeft, ArrowRight,
  
  // Actions  
  Edit, Trash2, Save, RefreshCw,
  
  // Status
  Check, CheckCircle, AlertCircle, Info,
  
  // Utility
  Search, Filter, Download, Upload
} from '@gingersnap/toolbox'
```

## 🎨 Tailwind Integration

Include the Tailwind preset in your configuration:

```javascript
// tailwind.config.js
import { tailwindPreset } from '@gingersnap/toolbox'

export default {
  presets: [tailwindPreset],
  content: [
    './src/**/*.{vue,js,ts}',
    './node_modules/@gingersnap/toolbox/dist/**/*.js'
  ]
}
```

## 🏗️ Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build

# Type checking
npm run typecheck
```

## 📈 Build Output

The library builds to multiple formats:
- **ES Modules** (`toolbox.es.js`) - For modern bundlers
- **UMD** (`toolbox.umd.js`) - For legacy support and CDN usage
- **CSS** (`style.css`) - Complete design system styles
- **TypeScript** (`*.d.ts`) - Full type declarations

## 🔗 Integration with Main App

The toolbox can be used alongside existing Base components:

```vue
<!-- Existing BaseModal continues to work -->
<BaseModal v-model:show="showOld" size="md">
  <p>Legacy modal</p>
</BaseModal>

<!-- Enhanced TbModal with new features -->
<TbModal v-model:show="showNew" variant="destructive" animation="slide">
  <p>Enhanced modal with better API</p>
</TbModal>
```

## 📋 Roadmap

- [ ] Complete component migration (TbSelect, TbToast, etc.)
- [ ] Enhanced documentation with live examples
- [ ] Storybook integration for component playground
- [ ] NPM publication for external use
- [ ] Advanced theming system with CSS custom properties

## 🤝 Contributing

1. Components should maintain consistency with existing Base components
2. All components must include TypeScript support
3. Follow the established naming convention: `Tb` prefix
4. Include comprehensive prop interfaces and emit types
5. Maintain backward compatibility when possible

## 📄 License

MIT License - See LICENSE file for details