feat: add loop and drag events

Author: vad1ym

README.md

@@ -278,6 +278,10 @@ function blurTransform(position) {
 | approve | `item: T` | Emitted when a card is approved (swiped right or approved via actions) |
 | reject | `item: T` | Emitted when a card is rejected (swiped left or rejected via actions) |
 | restore | `item: T` | Emitted when a card is restored (returned to the stack via restore action) |
+| loop | - | Emitted when a new loop cycle starts in loop mode (all cards have been swiped) |
+| dragstart | `item: T` | Emitted when user starts dragging a card |
+| dragmove | `item: T, type: SwipeAction \| null, delta: number` | Emitted during card dragging with movement details |
+| dragend | `item: T` | Emitted when user stops dragging a card |
 
 ## Exposed
 | Method/Property | Type | Description |

docs/api/flashcards.md

@@ -362,6 +362,28 @@ function blurTransform(position) {
 - **Payload:** `item: T`
 - **Description:** Emitted when a card is restored (returned to the stack via restore action).
 
+### `loop`
+
+- **Payload:** None
+- **Description:** Emitted when a new loop cycle starts in loop mode. This event fires when all cards have been swiped and the component starts over from the beginning. Only triggered when `loop` prop is enabled.
+
+### `dragstart`
+
+- **Payload:** `item: T`
+- **Description:** Emitted when user starts dragging a card. Fires immediately when dragging begins, before any movement threshold is reached.
+
+### `dragmove`
+
+- **Payload:** `item: T, type: SwipeAction | null, delta: number`
+- **Description:** Emitted during card dragging with real-time movement details. The `type` indicates the swipe direction (`'approve'` for right/up, `'reject'` for left/down, or `null` if within threshold). The `delta` is a normalized value (-1 to 1) representing drag progress relative to swipe threshold.
+
+### `dragend`
+
+- **Payload:** `item: T`
+- **Description:** Emitted when user stops dragging a card, regardless of whether the swipe completed or was cancelled.
+
+**Usage example with all events:**
+
 ```vue
 <script setup>
 function handleApprove(item) {
@@ -378,14 +400,39 @@ function handleRestore(item) {
   console.log('Restored:', item)
   // Remove from approved/rejected lists, etc.
 }
+
+function handleLoop() {
+  console.log('New loop cycle started!')
+  // Analytics, reset counters, etc.
+}
+
+function handleDragStart(item) {
+  console.log('Started dragging:', item)
+  // Show drag hints, haptic feedback, etc.
+}
+
+function handleDragMove(item, type, delta) {
+  console.log('Dragging:', item, 'Direction:', type, 'Progress:', delta)
+  // Update UI indicators, play sounds, etc.
+}
+
+function handleDragEnd(item) {
+  console.log('Stopped dragging:', item)
+  // Hide drag hints, etc.
+}
 </script>
 
 <template>
   <FlashCards
     :items="cards"
+    :loop="true"
     @approve="handleApprove"
     @reject="handleReject"
     @restore="handleRestore"
+    @loop="handleLoop"
+    @dragstart="handleDragStart"
+    @dragmove="handleDragMove"
+    @dragend="handleDragEnd"
   >
     <!-- slots -->
   </FlashCards>

src/FlashCard.vue

@@ -48,6 +48,21 @@ const emit = defineEmits<{
    * Event fired when animation ends
    */
   animationend: []
+
+  /**
+   * Event fired when drag starts
+   */
+  dragstart: []
+
+  /**
+   * Event fired during dragging movement
+   */
+  dragmove: [type: SwipeAction | null, delta: number]
+
+  /**
+   * Event fired when drag ends
+   */
+  dragend: []
 }>()
 
 defineSlots<{
@@ -82,6 +97,15 @@ const {
 } = useDragSetup(el, () => ({
   ...params,
   ...animation,
+  onDragStart() {
+    emit('dragstart')
+  },
+  onDragMove(type, delta) {
+    emit('dragmove', type, delta)
+  },
+  onDragEnd() {
+    emit('dragend')
+  },
   onDragComplete(action) {
     emit('complete', action, position)
   },

src/FlashCards.vue

@@ -60,6 +60,10 @@ const emit = defineEmits<{
   approve: [item: T]
   reject: [item: T]
   restore: [item: T]
+  loop: []
+  dragstart: [item: T]
+  dragmove: [item: T, type: SwipeAction | null, delta: number]
+  dragend: [item: T]
 }>()
 
 defineSlots<{
@@ -109,7 +113,11 @@ const {
   removeAnimatingCard,
   reset,
   currentItemId,
-} = useStackList<T>(() => ({ ...config.value, renderLimit: renderLimit.value }))
+} = useStackList<T>(() => ({
+  ...config.value,
+  renderLimit: renderLimit.value,
+  onLoop: () => emit('loop'),
+}))
 
 /**
  * STACK TRANSFORM
@@ -209,6 +217,9 @@ defineExpose({
           :class="{ 'flashcards__card--active': itemId === currentItemId }"
           @complete="(action, pos) => handleCardSwipe(itemId, action, pos)"
           @mounted="containerHeight = Math.max($event, 0)"
+          @dragstart="emit('dragstart', item)"
+          @dragmove="(type, delta) => emit('dragmove', item, type, delta)"
+          @dragend="emit('dragend', item)"
         >
           <template #default>
             <slot :item="item" />
@@ -235,6 +246,9 @@ defineExpose({
           class="flashcards__card flashcards__card--animating"
           :animation="animation"
           @animationend="() => removeAnimatingCard(itemId)"
+          @dragstart="emit('dragstart', item)"
+          @dragmove="(type, delta) => emit('dragmove', item, type, delta)"
+          @dragend="emit('dragend', item)"
         >
           <template #default>
             <slot :item="item" />

src/utils/useStackList.ts

@@ -18,6 +18,7 @@ export interface StackListOptions<T> {
   renderLimit: number
   itemKey?: keyof T | 'id'
   waitAnimationEnd?: boolean
+  onLoop?: () => void
 }
 
 export interface ResetOptions {
@@ -68,9 +69,10 @@ export function useStackList<T>(_options: MaybeRefOrGetter<StackListOptions<T>>)
 
   // For loop mode reset history on new cycle (when index points outside of source array)
   watch(currentIndex, (ci) => {
-    const { loop, items } = options.value
+    const { loop, items, onLoop } = options.value
     if (loop && ci === items.length) {
       history.clear()
+      onLoop?.() // New loop cycle started
     }
   })