Card Engine

A Vue 3 library for interactive card deck interfaces with drag & drop, animations, and mobile swipe support.

Features

• 🎴 Flexible Card Design: Customizable images, text, colors, borders, and rounded corners
• 🎯 Drag & Drop: Intuitive drag and drop with touch and mouse support
• 📱 Mobile-First: Tinder-like swipe interface for mobile devices
• ✨ Smooth Animations: GPU-accelerated animations using Web Animations API
• 🎲 Shuffle Animation: Visual card shuffling with full motion animation
• 📊 Multiple Layouts: Scatter (random) or grid layout modes
• 🎯 Drop Zones: Define areas where cards can be dropped with stacking and trash icon modes
• ♿ Accessible: Full keyboard navigation and screen reader support
• 🎨 Customizable: Override default styles with CSS
• 📦 TypeScript: Full type definitions included
• 🌳 Tree-shakeable: Import only what you need

Installation

npm install @globalleadership/card-engine

Quick Start

Option 1: Import Components (Recommended)

<script setup lang="ts">
import { ref } from 'vue';
import { CardDeck, type CardData, type DeckConfig } from '@globalleadership/card-engine';
import '@globalleadership/card-engine/style.css';

const cards = ref<CardData[]>([
  {
    id: 1,
    image: '/images/card1.jpg',
    text: 'Card 1',
    backgroundColor: '#ffffff',
  },
  {
    id: 2,
    image: '/images/card2.jpg',
    text: 'Card 2',
    backgroundColor: '#f0f0f0',
  },
]);

const config: DeckConfig = {
  aspectRatio: 0.7,
  cardWidth: 200,
  layout: 'scatter',
  enableShuffle: true,
  enableEnlarge: true,
};
</script>

<template>
  <CardDeck :cards="cards" :config="config" />
</template>

Option 2: Install as Plugin

// main.js
import { createApp } from 'vue';
import CardEngine from '@globalleadership/card-engine';
import '@globalleadership/card-engine/style.css';
import App from './App.vue';

const app = createApp(App);
app.use(CardEngine);
app.mount('#app');

<!-- No imports needed, components available globally -->
<template>
  <CardDeck :cards="cards" :config="config" />
</template>

Development

# Install dependencies
npm install

# Build library
npm run build

# Preview build
npm run preview

Documentation

• API.md - Complete API reference
• DROP_ZONES.md - Drop zone features and configuration guide

Working with Zones

Card Engine tracks which cards are currently in each drop zone. You can query this via the imperative API after a drag/drop phase using a template ref:

const deckRef = ref<CardDeckAPI | null>(null);

// Later, e.g. when the user clicks "Next phase"
const keepCards = deckRef.value?.getCardsInZone('keep') ?? [];
const allZones = deckRef.value?.getZoneAssignments() ?? {};

// keepCards can now be reused as input to another CardDeck, or for your own logic

Features Status

• [x] Basic card rendering with full customization
• [x] Scatter and grid layouts (with fit-all and stack modes)
• [x] Multi-select support (Cmd/Ctrl+Click)
• [x] Drag & drop functionality
• [x] Drop zones with snap-to-center
• [x] Stacked card layout in drop zones (horizontal/vertical)
• [x] Trash icon mode for drop zones
• [x] Shuffle animation
• [x] Enlarge/modal view
• [x] Entry/exit animations with stagger
• [x] Window resize with proportional scaling
• [x] Performance tested with 100+ cards
• [x] Full TypeScript support
• [x] Complete API documentation
• [ ] Mobile swipe interface (planned)
• [ ] Accessibility features (planned)

License

MIT