@waveform-playlist/browser 8.0.0 → 9.0.0

package/dist/index.d.ts

@@ -1,23 +1,25 @@
 import { Analyser } from 'tone';
 import { default as default_2 } from 'react';
 import { default as default_3 } from 'waveform-data';
-import { DragCancelEvent } from '@dnd-kit/core';
-import { DragEndEvent } from '@dnd-kit/core';
-import { DragMoveEvent } from '@dnd-kit/core';
-import { DragStartEvent } from '@dnd-kit/core';
+import { DragDropManager } from '@dnd-kit/abstract';
+import { DragEndEvent } from '@dnd-kit/abstract';
+import { DragMoveEvent } from '@dnd-kit/abstract';
+import { DragOperation } from '@dnd-kit/abstract';
+import { DragStartEvent } from '@dnd-kit/abstract';
 import { EngineState } from '@waveform-playlist/engine';
 import { Gain } from 'tone';
 import { InputNode } from 'tone';
 import { MediaElementPlayout } from '@waveform-playlist/media-element-playout';
-import { Modifier } from '@dnd-kit/core';
+import { Modifier } from '@dnd-kit/abstract';
 import { MutableRefObject } from 'react';
 import { PlaylistEngine } from '@waveform-playlist/engine';
+import { PluginDescriptor } from '@dnd-kit/abstract';
+import { Plugins } from '@dnd-kit/abstract';
+import { PointerSensor } from '@dnd-kit/dom';
 import { Provider } from 'react';
 import react__default from 'react';
 import { ReactNode } from 'react';
 import { RefObject } from 'react';
-import { SensorDescriptor } from '@dnd-kit/core';
-import { SensorOptions } from '@dnd-kit/core';
 import * as Tone from 'tone';
 import { ToneAudioNode } from 'tone';
 import { Volume } from 'tone';
@@ -262,6 +264,28 @@ export declare const AutomaticScrollCheckbox: default_2.FC<{
  */
 declare type Bits = 8 | 16;
 
+/**
+ * Modifier that constrains clip drag movement to prevent overlaps.
+ *
+ * For clip move operations: constrains horizontal transform to valid positions
+ * using the engine's collision detection.
+ *
+ * For boundary trim operations: returns zero transform because visual feedback
+ * comes from React state updates resizing the clip, not from CSS translate.
+ */
+export declare class ClipCollisionModifier extends Modifier<DragDropManager<any, any>, ClipCollisionOptions> {
+    apply(operation: DragOperation): {
+        x: number;
+        y: number;
+    };
+    static configure: (options: ClipCollisionOptions) => PluginDescriptor<any, any, typeof ClipCollisionModifier>;
+}
+
+declare interface ClipCollisionOptions {
+    tracks: ClipTrack[];
+    samplesPerPixel: number;
+}
+
 declare interface ClipPeaks {
     clipId: string;
     trackName: string;
@@ -344,17 +368,11 @@ 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.
+     * When true, touch events get delay-based activation while mouse/pen get distance-based.
+     * When false (default), all pointer types use distance-based activation (1px).
      */
     touchOptimized?: boolean;
     /**
@@ -843,6 +861,19 @@ export declare interface MediaElementWaveformProps {
     className?: string;
 }
 
+/**
+ * DragDropProvider plugins customizer that disables the Feedback plugin's drop animation.
+ *
+ * Without this, the Feedback plugin animates the dragged element back to its original
+ * position on drop, causing a visual snap-back before React re-renders at the new position.
+ *
+ * Usage:
+ * ```tsx
+ * <DragDropProvider plugins={noDropAnimationPlugins} ...>
+ * ```
+ */
+export declare const noDropAnimationPlugins: (defaults: Plugins) => Plugins;
+
 /**
  * Callback when annotations are updated (e.g., boundaries dragged).
  * Called with the full updated annotations array.
@@ -882,6 +913,8 @@ declare interface PlaybackAnimationContextValue {
     currentTimeRef: default_2.RefObject<number>;
     playbackStartTimeRef: default_2.RefObject<number>;
     audioStartPositionRef: default_2.RefObject<number>;
+    /** Returns current playback time from engine (auto-wraps at loop boundaries). */
+    getPlaybackTime: () => number;
 }
 
 export declare const PlayButton: default_2.FC<{
@@ -900,9 +933,9 @@ declare interface PlayheadProps {
     isPlaying: boolean;
     /** Ref to current time in seconds - use for smooth animation during playback */
     currentTimeRef: react__default.RefObject<number>;
-    /** Audio context start time when playback began - for calculating elapsed time */
+    /** Audio context start time when playback began. Fallback when getPlaybackTime is not provided. */
     playbackStartTimeRef: react__default.RefObject<number>;
-    /** Audio position when playback started - for calculating current position */
+    /** Audio position when playback started. Fallback when getPlaybackTime is not provided. */
     audioStartPositionRef: react__default.RefObject<number>;
     /** Samples per pixel - for converting time to pixels */
     samplesPerPixel: number;
@@ -912,6 +945,8 @@ declare interface PlayheadProps {
     controlsOffset: number;
     /** Function to get current audio context time - required for smooth animation */
     getAudioContextTime?: () => number;
+    /** Returns current playback time (auto-wraps at loop boundaries). Preferred over manual elapsed calculation. */
+    getPlaybackTime?: () => number;
 }
 
 /**
@@ -1332,7 +1367,7 @@ declare interface TrackState_2 {
 /**
  * Custom hook for handling annotation drag operations (boundary trimming)
  *
- * Provides drag handlers for use with @dnd-kit/core DndContext.
+ * Provides drag handlers for use with @dnd-kit/react DragDropProvider.
  * Handles annotation boundary resizing with linked endpoints support.
  *
  * @example
@@ -1347,21 +1382,21 @@ declare interface TrackState_2 {
  * });
  *
  * return (
- *   <DndContext
+ *   <DragDropProvider
  *     onDragStart={onDragStart}
  *     onDragMove={onDragMove}
  *     onDragEnd={onDragEnd}
- *     modifiers={[restrictToHorizontalAxis]}
+ *     modifiers={[RestrictToHorizontalAxis]}
  *   >
  *     {renderAnnotations()}
- *   </DndContext>
+ *   </DragDropProvider>
  * );
  * ```
  */
 export declare function useAnnotationDragHandlers({ annotations, onAnnotationsChange, samplesPerPixel, sampleRate, duration, linkEndpoints, }: UseAnnotationDragHandlersOptions): {
-    onDragStart: (event: DragStartEvent) => void;
-    onDragMove: (event: DragMoveEvent) => void;
-    onDragEnd: () => void;
+    onDragStart: (event: Parameters<DragStartEvent>[0]) => void;
+    onDragMove: (event: Parameters<DragMoveEvent>[0]) => void;
+    onDragEnd: (event: Parameters<DragEndEvent>[0]) => void;
 };
 
 declare interface UseAnnotationDragHandlersOptions {
@@ -1511,9 +1546,11 @@ declare interface UseAudioTracksOptions {
 /**
  * Custom hook for handling clip drag operations (movement and trimming)
  *
- * Provides drag handlers and collision modifier for use with @dnd-kit/core DndContext.
+ * Provides drag handlers for use with @dnd-kit/react DragDropProvider.
  * Handles both clip movement (dragging entire clips) and boundary trimming (adjusting clip edges).
  *
+ * Collision detection for clip moves is handled by `ClipCollisionModifier` (passed to DragDropProvider).
+ *
  * **Move:** `onDragEnd` delegates to `engine.moveClip()` in one shot.
  *
  * **Trim:** `onDragMove` updates React state per-frame via `onTracksChange` for smooth
@@ -1523,7 +1560,7 @@ declare interface UseAudioTracksOptions {
  *
  * @example
  * ```tsx
- * const { onDragStart, onDragMove, onDragEnd, onDragCancel, collisionModifier } = useClipDragHandlers({
+ * const { onDragStart, onDragMove, onDragEnd } = useClipDragHandlers({
  *   tracks,
  *   onTracksChange: setTracks,
  *   samplesPerPixel,
@@ -1533,29 +1570,21 @@ declare interface UseAudioTracksOptions {
  * });
  *
  * return (
- *   <DndContext
+ *   <DragDropProvider
  *     onDragStart={onDragStart}
  *     onDragMove={onDragMove}
  *     onDragEnd={onDragEnd}
- *     onDragCancel={onDragCancel}
- *     modifiers={[restrictToHorizontalAxis, collisionModifier]}
+ *     modifiers={[RestrictToHorizontalAxis, ClipCollisionModifier.configure({ tracks, samplesPerPixel })]}
  *   >
  *     <Waveform showClipHeaders={true} />
- *   </DndContext>
+ *   </DragDropProvider>
  * );
  * ```
  */
 export declare function useClipDragHandlers({ tracks, onTracksChange, samplesPerPixel, sampleRate, engineRef, isDraggingRef, }: UseClipDragHandlersOptions): {
-    onDragStart: (event: DragStartEvent) => void;
-    onDragMove: (event: DragMoveEvent) => void;
-    onDragEnd: (event: DragEndEvent) => void;
-    onDragCancel: (_event: DragCancelEvent) => void;
-    collisionModifier: (args: Parameters<Modifier>[0]) => {
-        scaleX: number;
-        scaleY: number;
-        x: number;
-        y: number;
-    };
+    onDragStart: (event: Parameters<DragStartEvent>[0]) => void;
+    onDragMove: (event: Parameters<DragMoveEvent>[0]) => void;
+    onDragEnd: (event: Parameters<DragEndEvent>[0]) => void;
 };
 
 declare interface UseClipDragHandlersOptions {
@@ -1615,25 +1644,17 @@ declare interface UseClipSplittingResult {
  * Returns configured sensors for @dnd-kit drag operations
  *
  * @param options - Configuration options for drag sensors
- * @returns Configured sensors appropriate for the interaction mode
+ * @returns Array of sensor constructors/descriptors for DragDropProvider's sensors prop
  *
  * @example
- * // Desktop-optimized (default)
+ * // Desktop-optimized (default — 1px distance activation for all pointer types)
  * 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
- * });
+ * // Mobile-optimized with custom touch delay
+ * const sensors = useDragSensors({ touchOptimized: true, touchDelay: 300 });
  */
-export declare function useDragSensors(options?: DragSensorOptions): SensorDescriptor<SensorOptions>[];
+export declare function useDragSensors(options?: DragSensorOptions): (typeof PointerSensor | PluginDescriptor<any, any, any>)[];
 
 /**
  * Hook for managing a dynamic chain of audio effects with real-time parameter updates