📝 Add docstrings to refactor

packages/vue/src/composables/useCardStack.ts

@@ -18,7 +18,15 @@ import { useDragHandling } from "./useDragHandling";
 import { debounce } from "../utils/debounce";
 
 /**
- * Main composable for card stack functionality
+ * Provides reactive state and interaction logic for a draggable, swipeable card stack UI component.
+ *
+ * Manages card stack initialization, layout recalculation, drag-based navigation, and event handling. Supports cycling through cards, responsive layout updates, and emits normalized move progress during drag interactions.
+ *
+ * @param cards - Reactive reference to the array of card data
+ * @param config - Reactive reference to card stack configuration options
+ * @param elementRef - Reactive reference to the container HTMLElement
+ * @param emit - Function to emit "move" events with a normalized offset value
+ * @returns An object containing the reactive card stack, computed container width, active card index, drag state, and navigation/control methods
  */
 export function useCardStack<T extends BaseCardData>(
   cards: Ref<T[]>,

packages/vue/src/composables/useDragHandling.ts

@@ -2,7 +2,9 @@ import { computed, ref, type Ref } from "vue";
 import type { DragEvent, CardStackConfig } from "../types";
 
 /**
- * Composable for handling drag and touch interactions
+ * Provides reactive state and utility methods for managing drag and touch interactions in a card stack UI.
+ *
+ * Exposes state variables, computed event names, and methods to handle drag lifecycle, direction detection, and threshold checks for card changes.
  */
 export function useDragHandling(
   config: Ref<CardStackConfig>,

packages/vue/src/composables/useStackCalculations.ts

@@ -2,7 +2,11 @@ import { computed, type Ref } from "vue";
 import type { CardStackConfig, BaseCardData } from "../types";
 
 /**
- * Composable for card stack calculations and positioning
+ * Provides reactive calculations for card stack layout, sizing, and positioning in a Vue component.
+ *
+ * Computes stack width, maximum visible cards, scale multipliers, container width, horizontal offsets, rest positions, default card properties, and element X offset for drag interactions, all based on the provided cards, configuration, element reference, container width, and dragging state.
+ *
+ * @returns An object containing computed properties for stack width, maximum visible cards, scale multiplier, container width, X position offset, stack rest points, default card properties, and element X position offset.
  */
 export function useStackCalculations<T extends BaseCardData>(
   cards: Ref<T[]>,

packages/vue/src/utils/debounce.ts

@@ -1,10 +1,11 @@
 /**
- * Creates a debounced function that delays invoking the provided function
- * until after wait milliseconds have elapsed since the last time the debounced function was invoked.
+ * Returns a debounced version of the given function that delays its execution until after a specified wait time has elapsed since the last call.
+ *
+ * The debounced function postpones invoking the original function until no calls have been made for the specified number of milliseconds.
  *
  * @param func - The function to debounce
- * @param wait - The number of milliseconds to delay
- * @returns A debounced version of the function
+ * @param wait - The delay in milliseconds before invoking the function
+ * @returns A debounced function that delays execution of `func`
  */
 export function debounce<T extends (...args: any[]) => any>(
   func: T,
@@ -24,12 +25,13 @@ export function debounce<T extends (...args: any[]) => any>(
 }
 
 /**
- * Creates a throttled function that only invokes the provided function
- * at most once per every wait milliseconds.
+ * Returns a throttled version of the given function that invokes at most once per specified interval.
+ *
+ * The throttled function calls the original function immediately on the first call, then ignores subsequent calls until the wait period has elapsed.
  *
- * @param func - The function to throttle
- * @param wait - The number of milliseconds to throttle invocations to
- * @returns A throttled version of the function
+ * @param func - The function to be throttled
+ * @param wait - The minimum interval in milliseconds between allowed invocations
+ * @returns A throttled function that enforces the specified invocation interval
  */
 export function throttle<T extends (...args: any[]) => any>(
   func: T,