@waveform-playlist/ui-components 6.0.2 → 7.1.0

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 import * as react from 'react';
 import react__default, { FunctionComponent, ReactNode, Dispatch, SetStateAction } from 'react';
-import { Peaks, Bits } from '@waveform-playlist/webaudio-peaks';
-import { Fade, FadeType, SpectrogramData, RenderMode } from '@waveform-playlist/core';
+import { Peaks, Bits, Fade, FadeType, SpectrogramData, RenderMode } from '@waveform-playlist/core';
 import { DraggableAttributes } from '@dnd-kit/core';
 import { SyntheticListenerMap } from '@dnd-kit/core/dist/hooks/utilities';
 import * as styled_components_dist_utils_hoist from 'styled-components/dist/utils/hoist';
@@ -152,6 +151,38 @@ interface ChannelProps {
 }
 declare const Channel: FunctionComponent<ChannelProps>;
 
+interface PlaylistErrorBoundaryProps {
+    children: react__default.ReactNode;
+    /** Custom fallback UI to show when an error occurs */
+    fallback?: react__default.ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error Boundary for waveform playlist components.
+ *
+ * Catches render errors in child components (canvas failures, audio
+ * processing errors) and displays a fallback UI instead of crashing
+ * the entire application.
+ *
+ * @example
+ * ```tsx
+ * <PlaylistErrorBoundary>
+ *   <WaveformPlaylistProvider tracks={tracks}>
+ *     <Waveform />
+ *   </WaveformPlaylistProvider>
+ * </PlaylistErrorBoundary>
+ * ```
+ */
+declare class PlaylistErrorBoundary extends react__default.Component<PlaylistErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: PlaylistErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: react__default.ErrorInfo): void;
+    render(): react__default.ReactNode;
+}
+
 interface ClipProps {
     className?: string;
     children?: ReactNode;
@@ -638,6 +669,13 @@ interface TrackMenuProps {
 }
 declare const TrackMenu: react__default.FC<TrackMenuProps>;
 
+/**
+ * Maximum width in CSS pixels for a single canvas chunk.
+ * Canvas elements are split into chunks of this width to enable
+ * horizontal virtual scrolling — only visible chunks are mounted.
+ */
+declare const MAX_CANVAS_WIDTH = 1000;
+
 type Props$1 = {
     children: ReactNode;
 };
@@ -688,6 +726,34 @@ declare const usePlayoutStatus: () => {
 };
 declare const usePlayoutStatusUpdate: () => PlayoutStatusUpdate;
 
+interface ScrollViewport {
+    scrollLeft: number;
+    containerWidth: number;
+    /** Left edge of the rendering window in pixels. Includes a 1.5× container-width over-scan buffer to the left of the visible area. */
+    visibleStart: number;
+    /** Right edge of the rendering window in pixels. Includes a 1.5× container-width over-scan buffer to the right of the visible area. */
+    visibleEnd: number;
+}
+type ScrollViewportProviderProps = {
+    containerRef: react__default.RefObject<HTMLElement | null>;
+    children: ReactNode;
+};
+declare const ScrollViewportProvider: ({ containerRef, children, }: ScrollViewportProviderProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Full viewport hook — re-renders on every viewport update (after threshold).
+ * Use useScrollViewportSelector() instead when you only need derived state.
+ */
+declare const useScrollViewport: () => ScrollViewport | null;
+/**
+ * Selector hook — only re-renders when the selector's return value changes
+ * (compared via Object.is). Return primitive values (strings, numbers) for
+ * best results, since objects/arrays create new references each call.
+ *
+ * Example: compute visible chunk key so the component only re-renders when
+ * the set of visible chunks actually changes, not on every scroll update.
+ */
+declare function useScrollViewportSelector<T>(selector: (viewport: ScrollViewport | null) => T): T;
+
 declare function samplesToSeconds(samples: number, sampleRate: number): number;
 declare function secondsToSamples(seconds: number, sampleRate: number): number;
 declare function samplesToPixels(samples: number, samplesPerPixel: number): number;
@@ -761,4 +827,4 @@ declare const BaseSlider: styled_components_dist_types.IStyledComponentBase<"web
     ref?: ((instance: HTMLInputElement | null) => void | react.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof react.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | react.RefObject<HTMLInputElement> | null | undefined;
 }>, never>, never>> & string;
 
-export { AudioPosition, type AudioPositionProps, AutomaticScrollCheckbox, type AutomaticScrollCheckboxProps, BaseButton, BaseCheckbox, BaseCheckboxLabel, BaseCheckboxWrapper, BaseControlButton, BaseInput, BaseLabel, BaseSelect, BaseSlider, Button, ButtonGroup, CLIP_BOUNDARY_WIDTH, CLIP_BOUNDARY_WIDTH_TOUCH, CLIP_HEADER_HEIGHT, Channel, type ChannelProps, Clip, ClipBoundary, type ClipBoundaryProps, ClipHeader, ClipHeaderPresentational, type ClipHeaderPresentationalProps, type ClipHeaderProps, type ClipProps, CloseButton, Controls$1 as Controls, type ControlsWrapperProps, DevicePixelRatioProvider, DotsIcon, type DragHandleProps$1 as DragHandleProps, FadeOverlay, type FadeOverlayProps, type GradientStop, Header, InlineLabel, LoopRegion, LoopRegionMarkers, type LoopRegionMarkersProps, type LoopRegionProps, MasterVolumeControl, type MasterVolumeControlProps, Playhead, type PlayheadProps, PlayheadWithMarker, Playlist, PlaylistInfoContext, type PlaylistProps, PlayoutProvider, type RenderPlayheadFunction, ScreenReaderOnly, Selection, type SelectionProps, SelectionTimeInputs, type SelectionTimeInputsProps, Slider, SliderWrapper, SmartChannel, type SmartChannelProps, SmartScale, type SmartScaleProps, SpectrogramChannel, type SpectrogramChannelProps, SpectrogramLabels, type SpectrogramLabelsProps, type SpectrogramWorkerCanvasApi, StyledPlaylist, StyledTimeScale, type TimeFormat, TimeFormatSelect, type TimeFormatSelectProps, TimeInput, type TimeInputProps, TimeScale, type TimeScaleProps, TimescaleLoopRegion, type TimescaleLoopRegionProps, Track, TrackControlsContext, TrackMenu, type TrackMenuItem, type TrackMenuProps, type TrackProps, TrashIcon, VolumeDownIcon, VolumeUpIcon, type WaveformColor, type WaveformDrawMode, type WaveformGradient, type WaveformPlaylistTheme, darkTheme, defaultTheme, formatTime, isWaveformGradient, parseTime, pixelsToSamples, pixelsToSeconds, samplesToPixels, samplesToSeconds, secondsToPixels, secondsToSamples, useDevicePixelRatio, usePlaylistInfo, usePlayoutStatus, usePlayoutStatusUpdate, useTheme, useTrackControls, waveformColorToCss };
+export { AudioPosition, type AudioPositionProps, AutomaticScrollCheckbox, type AutomaticScrollCheckboxProps, BaseButton, BaseCheckbox, BaseCheckboxLabel, BaseCheckboxWrapper, BaseControlButton, BaseInput, BaseLabel, BaseSelect, BaseSlider, Button, ButtonGroup, CLIP_BOUNDARY_WIDTH, CLIP_BOUNDARY_WIDTH_TOUCH, CLIP_HEADER_HEIGHT, Channel, type ChannelProps, Clip, ClipBoundary, type ClipBoundaryProps, ClipHeader, ClipHeaderPresentational, type ClipHeaderPresentationalProps, type ClipHeaderProps, type ClipProps, CloseButton, Controls$1 as Controls, type ControlsWrapperProps, DevicePixelRatioProvider, DotsIcon, type DragHandleProps$1 as DragHandleProps, FadeOverlay, type FadeOverlayProps, type GradientStop, Header, InlineLabel, LoopRegion, LoopRegionMarkers, type LoopRegionMarkersProps, type LoopRegionProps, MAX_CANVAS_WIDTH, MasterVolumeControl, type MasterVolumeControlProps, Playhead, type PlayheadProps, PlayheadWithMarker, Playlist, PlaylistErrorBoundary, type PlaylistErrorBoundaryProps, PlaylistInfoContext, type PlaylistProps, PlayoutProvider, type RenderPlayheadFunction, ScreenReaderOnly, type ScrollViewport, ScrollViewportProvider, Selection, type SelectionProps, SelectionTimeInputs, type SelectionTimeInputsProps, Slider, SliderWrapper, SmartChannel, type SmartChannelProps, SmartScale, type SmartScaleProps, SpectrogramChannel, type SpectrogramChannelProps, SpectrogramLabels, type SpectrogramLabelsProps, type SpectrogramWorkerCanvasApi, StyledPlaylist, StyledTimeScale, type TimeFormat, TimeFormatSelect, type TimeFormatSelectProps, TimeInput, type TimeInputProps, TimeScale, type TimeScaleProps, TimescaleLoopRegion, type TimescaleLoopRegionProps, Track, TrackControlsContext, TrackMenu, type TrackMenuItem, type TrackMenuProps, type TrackProps, TrashIcon, VolumeDownIcon, VolumeUpIcon, type WaveformColor, type WaveformDrawMode, type WaveformGradient, type WaveformPlaylistTheme, darkTheme, defaultTheme, formatTime, isWaveformGradient, parseTime, pixelsToSamples, pixelsToSeconds, samplesToPixels, samplesToSeconds, secondsToPixels, secondsToSamples, useDevicePixelRatio, usePlaylistInfo, usePlayoutStatus, usePlayoutStatusUpdate, useScrollViewport, useScrollViewportSelector, useTheme, useTrackControls, waveformColorToCss };

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import * as react from 'react';
 import react__default, { FunctionComponent, ReactNode, Dispatch, SetStateAction } from 'react';
-import { Peaks, Bits } from '@waveform-playlist/webaudio-peaks';
-import { Fade, FadeType, SpectrogramData, RenderMode } from '@waveform-playlist/core';
+import { Peaks, Bits, Fade, FadeType, SpectrogramData, RenderMode } from '@waveform-playlist/core';
 import { DraggableAttributes } from '@dnd-kit/core';
 import { SyntheticListenerMap } from '@dnd-kit/core/dist/hooks/utilities';
 import * as styled_components_dist_utils_hoist from 'styled-components/dist/utils/hoist';
@@ -152,6 +151,38 @@ interface ChannelProps {
 }
 declare const Channel: FunctionComponent<ChannelProps>;
 
+interface PlaylistErrorBoundaryProps {
+    children: react__default.ReactNode;
+    /** Custom fallback UI to show when an error occurs */
+    fallback?: react__default.ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error Boundary for waveform playlist components.
+ *
+ * Catches render errors in child components (canvas failures, audio
+ * processing errors) and displays a fallback UI instead of crashing
+ * the entire application.
+ *
+ * @example
+ * ```tsx
+ * <PlaylistErrorBoundary>
+ *   <WaveformPlaylistProvider tracks={tracks}>
+ *     <Waveform />
+ *   </WaveformPlaylistProvider>
+ * </PlaylistErrorBoundary>
+ * ```
+ */
+declare class PlaylistErrorBoundary extends react__default.Component<PlaylistErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: PlaylistErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: react__default.ErrorInfo): void;
+    render(): react__default.ReactNode;
+}
+
 interface ClipProps {
     className?: string;
     children?: ReactNode;
@@ -638,6 +669,13 @@ interface TrackMenuProps {
 }
 declare const TrackMenu: react__default.FC<TrackMenuProps>;
 
+/**
+ * Maximum width in CSS pixels for a single canvas chunk.
+ * Canvas elements are split into chunks of this width to enable
+ * horizontal virtual scrolling — only visible chunks are mounted.
+ */
+declare const MAX_CANVAS_WIDTH = 1000;
+
 type Props$1 = {
     children: ReactNode;
 };
@@ -688,6 +726,34 @@ declare const usePlayoutStatus: () => {
 };
 declare const usePlayoutStatusUpdate: () => PlayoutStatusUpdate;
 
+interface ScrollViewport {
+    scrollLeft: number;
+    containerWidth: number;
+    /** Left edge of the rendering window in pixels. Includes a 1.5× container-width over-scan buffer to the left of the visible area. */
+    visibleStart: number;
+    /** Right edge of the rendering window in pixels. Includes a 1.5× container-width over-scan buffer to the right of the visible area. */
+    visibleEnd: number;
+}
+type ScrollViewportProviderProps = {
+    containerRef: react__default.RefObject<HTMLElement | null>;
+    children: ReactNode;
+};
+declare const ScrollViewportProvider: ({ containerRef, children, }: ScrollViewportProviderProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Full viewport hook — re-renders on every viewport update (after threshold).
+ * Use useScrollViewportSelector() instead when you only need derived state.
+ */
+declare const useScrollViewport: () => ScrollViewport | null;
+/**
+ * Selector hook — only re-renders when the selector's return value changes
+ * (compared via Object.is). Return primitive values (strings, numbers) for
+ * best results, since objects/arrays create new references each call.
+ *
+ * Example: compute visible chunk key so the component only re-renders when
+ * the set of visible chunks actually changes, not on every scroll update.
+ */
+declare function useScrollViewportSelector<T>(selector: (viewport: ScrollViewport | null) => T): T;
+
 declare function samplesToSeconds(samples: number, sampleRate: number): number;
 declare function secondsToSamples(seconds: number, sampleRate: number): number;
 declare function samplesToPixels(samples: number, samplesPerPixel: number): number;
@@ -761,4 +827,4 @@ declare const BaseSlider: styled_components_dist_types.IStyledComponentBase<"web
     ref?: ((instance: HTMLInputElement | null) => void | react.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof react.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | react.RefObject<HTMLInputElement> | null | undefined;
 }>, never>, never>> & string;
 
-export { AudioPosition, type AudioPositionProps, AutomaticScrollCheckbox, type AutomaticScrollCheckboxProps, BaseButton, BaseCheckbox, BaseCheckboxLabel, BaseCheckboxWrapper, BaseControlButton, BaseInput, BaseLabel, BaseSelect, BaseSlider, Button, ButtonGroup, CLIP_BOUNDARY_WIDTH, CLIP_BOUNDARY_WIDTH_TOUCH, CLIP_HEADER_HEIGHT, Channel, type ChannelProps, Clip, ClipBoundary, type ClipBoundaryProps, ClipHeader, ClipHeaderPresentational, type ClipHeaderPresentationalProps, type ClipHeaderProps, type ClipProps, CloseButton, Controls$1 as Controls, type ControlsWrapperProps, DevicePixelRatioProvider, DotsIcon, type DragHandleProps$1 as DragHandleProps, FadeOverlay, type FadeOverlayProps, type GradientStop, Header, InlineLabel, LoopRegion, LoopRegionMarkers, type LoopRegionMarkersProps, type LoopRegionProps, MasterVolumeControl, type MasterVolumeControlProps, Playhead, type PlayheadProps, PlayheadWithMarker, Playlist, PlaylistInfoContext, type PlaylistProps, PlayoutProvider, type RenderPlayheadFunction, ScreenReaderOnly, Selection, type SelectionProps, SelectionTimeInputs, type SelectionTimeInputsProps, Slider, SliderWrapper, SmartChannel, type SmartChannelProps, SmartScale, type SmartScaleProps, SpectrogramChannel, type SpectrogramChannelProps, SpectrogramLabels, type SpectrogramLabelsProps, type SpectrogramWorkerCanvasApi, StyledPlaylist, StyledTimeScale, type TimeFormat, TimeFormatSelect, type TimeFormatSelectProps, TimeInput, type TimeInputProps, TimeScale, type TimeScaleProps, TimescaleLoopRegion, type TimescaleLoopRegionProps, Track, TrackControlsContext, TrackMenu, type TrackMenuItem, type TrackMenuProps, type TrackProps, TrashIcon, VolumeDownIcon, VolumeUpIcon, type WaveformColor, type WaveformDrawMode, type WaveformGradient, type WaveformPlaylistTheme, darkTheme, defaultTheme, formatTime, isWaveformGradient, parseTime, pixelsToSamples, pixelsToSeconds, samplesToPixels, samplesToSeconds, secondsToPixels, secondsToSamples, useDevicePixelRatio, usePlaylistInfo, usePlayoutStatus, usePlayoutStatusUpdate, useTheme, useTrackControls, waveformColorToCss };
+export { AudioPosition, type AudioPositionProps, AutomaticScrollCheckbox, type AutomaticScrollCheckboxProps, BaseButton, BaseCheckbox, BaseCheckboxLabel, BaseCheckboxWrapper, BaseControlButton, BaseInput, BaseLabel, BaseSelect, BaseSlider, Button, ButtonGroup, CLIP_BOUNDARY_WIDTH, CLIP_BOUNDARY_WIDTH_TOUCH, CLIP_HEADER_HEIGHT, Channel, type ChannelProps, Clip, ClipBoundary, type ClipBoundaryProps, ClipHeader, ClipHeaderPresentational, type ClipHeaderPresentationalProps, type ClipHeaderProps, type ClipProps, CloseButton, Controls$1 as Controls, type ControlsWrapperProps, DevicePixelRatioProvider, DotsIcon, type DragHandleProps$1 as DragHandleProps, FadeOverlay, type FadeOverlayProps, type GradientStop, Header, InlineLabel, LoopRegion, LoopRegionMarkers, type LoopRegionMarkersProps, type LoopRegionProps, MAX_CANVAS_WIDTH, MasterVolumeControl, type MasterVolumeControlProps, Playhead, type PlayheadProps, PlayheadWithMarker, Playlist, PlaylistErrorBoundary, type PlaylistErrorBoundaryProps, PlaylistInfoContext, type PlaylistProps, PlayoutProvider, type RenderPlayheadFunction, ScreenReaderOnly, type ScrollViewport, ScrollViewportProvider, Selection, type SelectionProps, SelectionTimeInputs, type SelectionTimeInputsProps, Slider, SliderWrapper, SmartChannel, type SmartChannelProps, SmartScale, type SmartScaleProps, SpectrogramChannel, type SpectrogramChannelProps, SpectrogramLabels, type SpectrogramLabelsProps, type SpectrogramWorkerCanvasApi, StyledPlaylist, StyledTimeScale, type TimeFormat, TimeFormatSelect, type TimeFormatSelectProps, TimeInput, type TimeInputProps, TimeScale, type TimeScaleProps, TimescaleLoopRegion, type TimescaleLoopRegionProps, Track, TrackControlsContext, TrackMenu, type TrackMenuItem, type TrackMenuProps, type TrackProps, TrashIcon, VolumeDownIcon, VolumeUpIcon, type WaveformColor, type WaveformDrawMode, type WaveformGradient, type WaveformPlaylistTheme, darkTheme, defaultTheme, formatTime, isWaveformGradient, parseTime, pixelsToSamples, pixelsToSeconds, samplesToPixels, samplesToSeconds, secondsToPixels, secondsToSamples, useDevicePixelRatio, usePlaylistInfo, usePlayoutStatus, usePlayoutStatusUpdate, useScrollViewport, useScrollViewportSelector, useTheme, useTrackControls, waveformColorToCss };