@waveform-playlist/browser 5.0.0-alpha.3 → 5.0.0-alpha.5

package/dist/index.d.ts

@@ -206,6 +206,37 @@ export declare const DownloadAnnotationsButton: default_2.FC<{
     className?: string;
 }>;
 
+/**
+ * Hook for configuring @dnd-kit sensors for clip dragging
+ *
+ * Provides consistent drag activation behavior across all examples.
+ * Supports both desktop (immediate feedback) and mobile (delay-based) interactions.
+ */
+declare interface DragSensorOptions {
+    /**
+     * Enable mobile-optimized touch handling with delay-based activation.
+     * When true, uses TouchSensor with 250ms delay to distinguish drag from scroll.
+     * When false (default), uses PointerSensor with 1px activation for immediate feedback.
+     */
+    touchOptimized?: boolean;
+    /**
+     * Delay in milliseconds before touch drag activates (only when touchOptimized is true).
+     * Default: 250ms - long enough to distinguish from scroll intent
+     */
+    touchDelay?: number;
+    /**
+     * Distance tolerance during touch delay (only when touchOptimized is true).
+     * If finger moves more than this during delay, drag is cancelled.
+     * Default: 5px - allows slight finger movement
+     */
+    touchTolerance?: number;
+    /**
+     * Distance in pixels before mouse drag activates.
+     * Default: 1px for immediate feedback on desktop
+     */
+    mouseDistance?: number;
+}
+
 /**
  * Editable annotations checkbox that uses the playlist context
  * Uses split contexts to avoid re-rendering during animation
@@ -1050,17 +1081,29 @@ declare interface UseClipSplittingResult {
     splitClipAt: (trackIndex: number, clipIndex: number, splitTime: number) => boolean;
 }
 
-/**
- * Hook for configuring @dnd-kit sensors for clip dragging
- *
- * Provides consistent drag activation behavior across all examples
- */
 /**
  * Returns configured sensors for @dnd-kit drag operations
  *
- * @returns Configured sensors with 1px activation distance for immediate feedback
+ * @param options - Configuration options for drag sensors
+ * @returns Configured sensors appropriate for the interaction mode
+ *
+ * @example
+ * // Desktop-optimized (default)
+ * const sensors = useDragSensors();
+ *
+ * @example
+ * // Mobile-optimized with touch delay
+ * const sensors = useDragSensors({ touchOptimized: true });
+ *
+ * @example
+ * // Custom touch settings
+ * const sensors = useDragSensors({
+ *   touchOptimized: true,
+ *   touchDelay: 300,
+ *   touchTolerance: 8
+ * });
  */
-export declare function useDragSensors(): SensorDescriptor<SensorOptions>[];
+export declare function useDragSensors(options?: DragSensorOptions): SensorDescriptor<SensorOptions>[];
 
 /**
  * Hook for managing a dynamic chain of audio effects with real-time parameter updates
@@ -1496,6 +1539,12 @@ export declare interface WaveformProps {
     showClipHeaders?: boolean;
     interactiveClips?: boolean;
     showFades?: boolean;
+    /**
+     * Enable mobile-optimized touch interactions.
+     * When true, increases touch target sizes for clip boundaries.
+     * Use with useDragSensors({ touchOptimized: true }) for best results.
+     */
+    touchOptimized?: boolean;
     recordingState?: {
         isRecording: boolean;
         trackId: string;