@waveform-playlist/browser 5.1.0 → 5.2.0-next.2

package/dist/index.d.ts

@@ -565,6 +565,39 @@ export declare interface MediaElementAnimationContextValue {
     currentTimeRef: default_2.RefObject<number>;
 }
 
+/**
+ * Standalone annotation text list component for MediaElementPlaylistProvider.
+ *
+ * Reads annotations and playback state from context and renders AnnotationText
+ * unconditionally (even when annotations are empty).
+ */
+export declare const MediaElementAnnotationList: default_2.FC<MediaElementAnnotationListProps>;
+
+export declare interface MediaElementAnnotationListProps {
+    /** Height in pixels for the annotation text list */
+    height?: number;
+    /**
+     * Custom render function for annotation items in the text list.
+     * When provided, completely replaces the default annotation item rendering.
+     */
+    renderAnnotationItem?: (props: RenderAnnotationItemProps) => default_2.ReactNode;
+    /**
+     * Callback when annotations are updated (e.g., text edited).
+     * Called with the full updated annotations array.
+     */
+    onAnnotationUpdate?: OnAnnotationUpdateFn;
+    /** Whether annotation text can be edited. Defaults to false. */
+    editable?: boolean;
+    /** Whether dragging one annotation boundary also moves the adjacent annotation's boundary. Defaults to false. */
+    linkEndpoints?: boolean;
+    /** Override continuousPlay from context. Falls back to context value if not provided. */
+    continuousPlay?: boolean;
+    /** Where to position the active annotation when auto-scrolling. Defaults to 'center'. */
+    scrollActivePosition?: ScrollLogicalPosition;
+    /** Which scrollable containers to scroll: 'nearest' or 'all'. Defaults to 'nearest'. */
+    scrollActiveContainer?: 'nearest' | 'all';
+}
+
 export declare interface MediaElementControlsContextValue {
     play: (startTime?: number) => void;
     pause: () => void;
@@ -572,7 +605,7 @@ export declare interface MediaElementControlsContextValue {
     seekTo: (time: number) => void;
     setPlaybackRate: (rate: number) => void;
     setContinuousPlay: (enabled: boolean) => void;
-    setAnnotations: (annotations: AnnotationData[]) => void;
+    setAnnotations: default_2.Dispatch<default_2.SetStateAction<AnnotationData[]>>;
     setActiveAnnotationId: (id: string | null) => void;
     setAutomaticScroll: (enabled: boolean) => void;
     setScrollContainer: (element: HTMLDivElement | null) => void;
@@ -596,6 +629,35 @@ export declare interface MediaElementDataContextValue {
     progressBarWidth: number;
 }
 
+/**
+ * Standalone waveform + annotation boxes component for MediaElementPlaylistProvider.
+ *
+ * Renders the waveform visualization, annotation boxes, selection, and playhead.
+ * Does NOT render the annotation text list — use `MediaElementAnnotationList` for that.
+ *
+ * Must be used inside a `MediaElementPlaylistProvider`.
+ *
+ * This component can be placed independently in consumer layouts, allowing the
+ * waveform and annotation list to be positioned separately (e.g., in different
+ * panels or with custom elements between them).
+ */
+export declare const MediaElementPlaylist: default_2.FC<MediaElementPlaylistProps>;
+
+export declare interface MediaElementPlaylistProps {
+    /** Custom function to generate the label shown on annotation boxes */
+    getAnnotationBoxLabel?: GetAnnotationBoxLabelFn;
+    /** Whether annotation boundaries can be edited by dragging. Defaults to false. */
+    editable?: boolean;
+    /** Whether dragging one annotation boundary also moves the adjacent annotation's boundary. Defaults to false. */
+    linkEndpoints?: boolean;
+    /**
+     * Callback when annotations are updated (e.g., boundaries dragged).
+     * Called with the full updated annotations array.
+     */
+    onAnnotationUpdate?: OnAnnotationUpdateFn;
+    className?: string;
+}
+
 /**
  * MediaElementPlaylistProvider
  *
@@ -694,6 +756,8 @@ export declare interface MediaElementWaveformProps {
     renderAnnotationItem?: (props: RenderAnnotationItemProps) => default_2.ReactNode;
     /** Whether annotation boundaries can be edited by dragging. Defaults to false. */
     editable?: boolean;
+    /** Whether dragging one annotation boundary also moves the adjacent annotation's boundary. Defaults to false. */
+    linkEndpoints?: boolean;
     /**
      * Callback when annotations are updated (e.g., boundaries dragged).
      * Called with the full updated annotations array.
@@ -783,6 +847,43 @@ declare interface PlayheadProps {
     getAudioContextTime?: () => number;
 }
 
+/**
+ * Standalone annotation text list component for WaveformPlaylistProvider (WebAudio).
+ *
+ * Reads annotations and playback state from context and renders AnnotationText
+ * unconditionally (even when annotations are empty).
+ */
+export declare const PlaylistAnnotationList: default_2.FC<PlaylistAnnotationListProps>;
+
+export declare interface PlaylistAnnotationListProps {
+    /** Height in pixels for the annotation text list */
+    height?: number;
+    /**
+     * Custom render function for annotation items in the text list.
+     * When provided, completely replaces the default annotation item rendering.
+     */
+    renderAnnotationItem?: (props: RenderAnnotationItemProps) => default_2.ReactNode;
+    /**
+     * Callback when annotations are updated (e.g., text edited).
+     * Called with the full updated annotations array.
+     */
+    onAnnotationUpdate?: OnAnnotationUpdateFn;
+    /**
+     * Action controls to show on each annotation item (e.g., delete, split).
+     * Only rendered when `annotationsEditable` is true in context.
+     */
+    controls?: AnnotationAction[];
+    /**
+     * Override annotation list config. Falls back to context values
+     * `{ linkEndpoints, continuousPlay }` if not provided.
+     */
+    annotationListConfig?: AnnotationActionOptions;
+    /** Where to position the active annotation when auto-scrolling. Defaults to 'center'. */
+    scrollActivePosition?: ScrollLogicalPosition;
+    /** Which scrollable containers to scroll: 'nearest' or 'all'. Defaults to 'nearest'. */
+    scrollActiveContainer?: 'nearest' | 'all';
+}
+
 declare interface PlaylistControlsContextValue {
     play: (startTime?: number, playDuration?: number) => Promise<void>;
     pause: () => void;
@@ -806,7 +907,7 @@ declare interface PlaylistControlsContextValue {
     setContinuousPlay: (enabled: boolean) => void;
     setLinkEndpoints: (enabled: boolean) => void;
     setAnnotationsEditable: (enabled: boolean) => void;
-    setAnnotations: (annotations: AnnotationData[]) => void;
+    setAnnotations: default_2.Dispatch<default_2.SetStateAction<AnnotationData[]>>;
     setActiveAnnotationId: (id: string | null) => void;
     setLoopEnabled: (enabled: boolean) => void;
     setLoopRegion: (start: number, end: number) => void;
@@ -857,6 +958,49 @@ declare interface PlaylistStateContextValue {
     loopEnd: number;
 }
 
+/**
+ * Standalone playlist visualization component (WebAudio version).
+ *
+ * Renders the waveform tracks, timescale, annotations boxes, selection,
+ * playhead, loop regions, and track controls — everything that lives
+ * inside <Playlist> plus wrapping providers.
+ *
+ * Does NOT render AnnotationText (the annotation list below the waveform).
+ * Pair with PlaylistAnnotationList for a full annotation editing UI.
+ */
+export declare const PlaylistVisualization: default_2.FC<PlaylistVisualizationProps>;
+
+export declare interface PlaylistVisualizationProps {
+    renderTrackControls?: (trackIndex: number) => ReactNode;
+    renderTimestamp?: (timeMs: number, pixelPosition: number) => ReactNode;
+    /** Custom playhead render function. Receives position (pixels) and color from theme. */
+    renderPlayhead?: RenderPlayheadFunction;
+    annotationControls?: AnnotationAction[];
+    /**
+     * Custom function to generate the label shown on annotation boxes in the waveform.
+     * Receives the annotation data and its index, returns a string label.
+     * Default: annotation.id
+     */
+    getAnnotationBoxLabel?: GetAnnotationBoxLabelFn;
+    className?: string;
+    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;
+        startSample: number;
+        durationSamples: number;
+        peaks: Int8Array | Int16Array;
+    };
+}
+
 /**
  * Props passed to the renderAnnotationItem function for custom rendering
  */
@@ -1618,7 +1762,10 @@ declare interface UseZoomControlsProps {
 }
 
 /**
- * Waveform visualization component that uses the playlist context
+ * Waveform visualization component that uses the playlist context.
+ *
+ * Composes PlaylistVisualization (waveform + tracks) and
+ * PlaylistAnnotationList (annotation text list below the waveform).
  */
 export declare const Waveform: default_2.FC<WaveformProps>;
 
@@ -1749,7 +1896,7 @@ export declare interface WaveformPlaylistContextValue {
     setContinuousPlay: (enabled: boolean) => void;
     setLinkEndpoints: (enabled: boolean) => void;
     setAnnotationsEditable: (enabled: boolean) => void;
-    setAnnotations: (annotations: AnnotationData[]) => void;
+    setAnnotations: default_2.Dispatch<default_2.SetStateAction<AnnotationData[]>>;
     setActiveAnnotationId: (id: string | null) => void;
     playoutRef: default_2.RefObject<TonePlayout | null>;
     currentTimeRef: default_2.RefObject<number>;