@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

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

Peer Dependencies

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

🚀 Quick Start

<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:

<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:

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:

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:

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

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

🏗️ Development

# 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:

<!-- 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