npm package: @globalleadership/card-engine
Description: A Vue 3 library for interactive card deck interfaces with drag & drop, animations, and mobile swipe support
Author: GLA Digital
Latest version: 0.3.11

# 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

```bash
npm install @globalleadership/card-engine
```

## Quick Start

### Option 1: Import Components (Recommended)

```vue
<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

```js
// 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');
```

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

## Development

```bash
# Install dependencies
npm install

# Build library
npm run build

# Preview build
npm run preview
```

## Documentation

- [API.md](./API.md) - Complete API reference
- [DROP_ZONES.md](./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:

```ts
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