@stargate91/pill-player 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,249 @@
+import * as react from 'react';
+import { ReactNode, SVGProps } from 'react';
+
+interface AudioTrack {
+    id: string;
+    title: string;
+    code?: string;
+    artist?: string;
+    genre?: string;
+    bpm?: number | string;
+    duration?: string;
+    src?: string;
+    soundcloud?: string;
+    youtube?: string;
+    feed?: string;
+    externalUrl?: string;
+}
+type PillTheme = "orbital" | "stargate" | "cyberpunk" | "matrix" | "synthwave" | "amber" | "nordic" | "minimal";
+type PillPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left" | "inline";
+interface PillColors {
+    accent?: string;
+    secondary?: string;
+    bg?: string;
+    surface?: string;
+    border?: string;
+    text?: string;
+    textDim?: string;
+    glow?: string;
+}
+type EmbedMode = "seamless" | "themed" | "widget";
+type MixcloudEmbedMode = EmbedMode;
+interface PillIcons {
+    play?: ReactNode;
+    pause?: ReactNode;
+    prev?: ReactNode;
+    next?: ReactNode;
+    mute?: ReactNode;
+    unmute?: ReactNode;
+    close?: ReactNode;
+    external?: ReactNode;
+}
+interface PillLabels {
+    badge: string;
+    openPlayer: string;
+    closePlayer: string;
+    play: string;
+    pause: string;
+    prevTrack: string;
+    nextTrack: string;
+    mute: string;
+    unmute: string;
+    directPlayHint: string;
+    listenExternal: string;
+    selectTrack: string;
+    frequenciesActive: string;
+    frequenciesStandby: string;
+    spectrumHeader: string;
+    spectrumDsp: string;
+    subtitle: string;
+}
+interface PillFeatures {
+    showSpectrum?: boolean;
+    showSeekbar?: boolean;
+    showPlaylist?: boolean;
+    persistState?: boolean;
+    enableKeyboardShortcuts?: boolean;
+    embedMode?: EmbedMode;
+    mixcloudEmbedMode?: MixcloudEmbedMode;
+    beaconGlow?: boolean;
+}
+interface PillPlayerProps {
+    tracks: AudioTrack[] | string;
+    theme?: PillTheme;
+    colors?: PillColors;
+    position?: PillPosition;
+    icons?: PillIcons;
+    labels?: Partial<PillLabels>;
+    features?: PillFeatures;
+    initialOpen?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    onTrackChange?: (track: AudioTrack, index: number) => void;
+    onPlayStateChange?: (isPlaying: boolean) => void;
+}
+declare const DEFAULT_PILL_LABELS: PillLabels;
+
+declare function PillPlayer({ tracks, theme, colors, position, icons, labels: customLabels, features, initialOpen, className, style, onTrackChange, onPlayStateChange, }: PillPlayerProps): react.JSX.Element;
+
+interface AudioTriggerPillProps {
+    isOpen: boolean;
+    isPlaying: boolean;
+    currentTrack?: AudioTrack;
+    labels: PillLabels;
+    icons?: PillIcons;
+    onToggleOpen: () => void;
+}
+declare function AudioTriggerPill({ isOpen, isPlaying, currentTrack, labels, icons, onToggleOpen, }: AudioTriggerPillProps): react.JSX.Element;
+
+interface SpectrumVisualizerProps {
+    isPlaying: boolean;
+    labels: PillLabels;
+    frequencyData?: number[];
+    hasLiveFrequency?: boolean;
+}
+declare function SpectrumVisualizer({ isPlaying, labels, frequencyData, hasLiveFrequency, }: SpectrumVisualizerProps): react.JSX.Element;
+
+interface AudioPlaylistProps {
+    tracks: AudioTrack[];
+    currentTrackIndex: number;
+    labels: PillLabels;
+    onSelectTrack: (index: number) => void;
+}
+declare function AudioPlaylist({ tracks, currentTrackIndex, labels, onSelectTrack, }: AudioPlaylistProps): react.JSX.Element;
+
+interface AudioSeekbarProps {
+    currentTime: number;
+    duration: number;
+    onSeek: (timeInSeconds: number) => void;
+}
+declare function AudioSeekbar({ currentTime, duration, onSeek, }: AudioSeekbarProps): react.JSX.Element;
+
+interface PlayerHeaderProps {
+    labels: PillLabels;
+    icons?: PillIcons;
+    onClose: () => void;
+}
+declare function PlayerHeader({ labels, icons, onClose }: PlayerHeaderProps): react.JSX.Element;
+
+interface TrackInfoProps {
+    currentTrack?: AudioTrack;
+    labels: PillLabels;
+}
+declare function TrackInfo({ currentTrack, labels }: TrackInfoProps): react.JSX.Element;
+
+interface PlayerControlsProps {
+    isPlaying: boolean;
+    isMuted: boolean;
+    externalLinkUrl?: string;
+    labels: PillLabels;
+    icons?: PillIcons;
+    onPrev: () => void;
+    onTogglePlay: () => void;
+    onNext: () => void;
+    onToggleMute: () => void;
+}
+declare function PlayerControls({ isPlaying, isMuted, externalLinkUrl, labels, icons, onPrev, onTogglePlay, onNext, onToggleMute, }: PlayerControlsProps): react.JSX.Element;
+
+interface ProviderEmbedsProps {
+    isLoaded: boolean;
+    embedMode: EmbedMode;
+    currentTrack?: AudioTrack;
+    labels: PillLabels;
+    isSoundCloud: boolean;
+    soundCloudIframeSrc: string;
+    scIframeRef: any;
+    onSoundCloudLoad: () => void;
+    isYouTube: boolean;
+    youTubeIframeSrc: string;
+    ytIframeRef: any;
+    onYouTubeLoad: () => void;
+    iframeSrc: string;
+    iframeRef: any;
+    onMixcloudLoad: () => void;
+}
+declare function ProviderEmbeds({ isLoaded, embedMode, currentTrack, labels, isSoundCloud, soundCloudIframeSrc, scIframeRef, onSoundCloudLoad, isYouTube, youTubeIframeSrc, ytIframeRef, onYouTubeLoad, iframeSrc, iframeRef, onMixcloudLoad, }: ProviderEmbedsProps): react.JSX.Element | null;
+
+interface IconProps extends SVGProps<SVGSVGElement> {
+    size?: number | string;
+}
+declare function PlayIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function PauseIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function SkipBackIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function SkipForwardIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function VolumeMuteIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function VolumeUpIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function CloseIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function ExternalLinkIcon({ size, ...props }: IconProps): react.JSX.Element;
+
+/**
+ * Extracts 11-character YouTube video ID from various URL formats or returns the ID if already clean.
+ */
+declare function extractYouTubeId(urlOrId?: string): string | null;
+
+interface UseAudioPlayerOptions {
+    tracks: AudioTrack[];
+    persistState?: boolean;
+    onTrackChange?: (track: AudioTrack, index: number) => void;
+    onPlayStateChange?: (isPlaying: boolean) => void;
+}
+declare function useAudioPlayer({ tracks, persistState, onTrackChange, onPlayStateChange, }: UseAudioPlayerOptions): {
+    tracks: AudioTrack[];
+    currentTrack: AudioTrack;
+    currentTrackIndex: number;
+    isPlaying: boolean;
+    isMuted: boolean;
+    isLoaded: boolean;
+    currentTime: number;
+    duration: number;
+    handleSeek: (seconds: number) => void;
+    iframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    scIframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    soundCloudIframeSrc: string;
+    isSoundCloud: boolean;
+    isYouTube: boolean;
+    ytIframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    youTubeIframeSrc: string;
+    setupYouTubePlayer: () => void;
+    isHtmlAudio: boolean;
+    isMixcloud: boolean;
+    setupSoundCloudWidget: () => void;
+    iframeSrc: string;
+    frequencyData: number[];
+    hasLiveFrequency: boolean;
+    timing: {
+        numericBpm: number;
+        beatMs: number;
+        halfBeatMs: number;
+        twoBeatsMs: number;
+        barMs: number;
+    };
+    setIsLoaded: react.Dispatch<react.SetStateAction<boolean>>;
+    handleTogglePlay: () => void;
+    handleToggleMute: () => void;
+    handleNextTrack: () => void;
+    handlePrevTrack: () => void;
+    handleSelectTrack: (index: number) => void;
+    setupMixcloudWidget: () => void;
+};
+
+/**
+ * Formats seconds into mm:ss or hh:mm:ss string.
+ */
+declare function formatTime(totalSeconds: number): string;
+/**
+ * Parses duration strings like "3:45", "30 min", or number of seconds.
+ */
+declare function parseDurationToSeconds(duration?: string): number;
+/**
+ * Calculates beat, half-beat, two-beats, and bar timings in milliseconds from BPM.
+ */
+declare function calculateBpmTiming(bpm?: number | string): {
+    numericBpm: number;
+    beatMs: number;
+    halfBeatMs: number;
+    twoBeatsMs: number;
+    barMs: number;
+};
+
+export { AudioPlaylist, AudioSeekbar, type AudioTrack, AudioTriggerPill, CloseIcon, DEFAULT_PILL_LABELS, type EmbedMode, ExternalLinkIcon, type IconProps, type MixcloudEmbedMode, PauseIcon, type PillColors, type PillFeatures, type PillIcons, type PillLabels, PillPlayer, type PillPlayerProps, type PillPosition, type PillTheme, PlayIcon, PlayerControls, PlayerHeader, ProviderEmbeds, SkipBackIcon, SkipForwardIcon, SpectrumVisualizer, TrackInfo, VolumeMuteIcon, VolumeUpIcon, calculateBpmTiming, extractYouTubeId, formatTime, parseDurationToSeconds, useAudioPlayer };

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+import * as react from 'react';
+import { ReactNode, SVGProps } from 'react';
+
+interface AudioTrack {
+    id: string;
+    title: string;
+    code?: string;
+    artist?: string;
+    genre?: string;
+    bpm?: number | string;
+    duration?: string;
+    src?: string;
+    soundcloud?: string;
+    youtube?: string;
+    feed?: string;
+    externalUrl?: string;
+}
+type PillTheme = "orbital" | "stargate" | "cyberpunk" | "matrix" | "synthwave" | "amber" | "nordic" | "minimal";
+type PillPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left" | "inline";
+interface PillColors {
+    accent?: string;
+    secondary?: string;
+    bg?: string;
+    surface?: string;
+    border?: string;
+    text?: string;
+    textDim?: string;
+    glow?: string;
+}
+type EmbedMode = "seamless" | "themed" | "widget";
+type MixcloudEmbedMode = EmbedMode;
+interface PillIcons {
+    play?: ReactNode;
+    pause?: ReactNode;
+    prev?: ReactNode;
+    next?: ReactNode;
+    mute?: ReactNode;
+    unmute?: ReactNode;
+    close?: ReactNode;
+    external?: ReactNode;
+}
+interface PillLabels {
+    badge: string;
+    openPlayer: string;
+    closePlayer: string;
+    play: string;
+    pause: string;
+    prevTrack: string;
+    nextTrack: string;
+    mute: string;
+    unmute: string;
+    directPlayHint: string;
+    listenExternal: string;
+    selectTrack: string;
+    frequenciesActive: string;
+    frequenciesStandby: string;
+    spectrumHeader: string;
+    spectrumDsp: string;
+    subtitle: string;
+}
+interface PillFeatures {
+    showSpectrum?: boolean;
+    showSeekbar?: boolean;
+    showPlaylist?: boolean;
+    persistState?: boolean;
+    enableKeyboardShortcuts?: boolean;
+    embedMode?: EmbedMode;
+    mixcloudEmbedMode?: MixcloudEmbedMode;
+    beaconGlow?: boolean;
+}
+interface PillPlayerProps {
+    tracks: AudioTrack[] | string;
+    theme?: PillTheme;
+    colors?: PillColors;
+    position?: PillPosition;
+    icons?: PillIcons;
+    labels?: Partial<PillLabels>;
+    features?: PillFeatures;
+    initialOpen?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    onTrackChange?: (track: AudioTrack, index: number) => void;
+    onPlayStateChange?: (isPlaying: boolean) => void;
+}
+declare const DEFAULT_PILL_LABELS: PillLabels;
+
+declare function PillPlayer({ tracks, theme, colors, position, icons, labels: customLabels, features, initialOpen, className, style, onTrackChange, onPlayStateChange, }: PillPlayerProps): react.JSX.Element;
+
+interface AudioTriggerPillProps {
+    isOpen: boolean;
+    isPlaying: boolean;
+    currentTrack?: AudioTrack;
+    labels: PillLabels;
+    icons?: PillIcons;
+    onToggleOpen: () => void;
+}
+declare function AudioTriggerPill({ isOpen, isPlaying, currentTrack, labels, icons, onToggleOpen, }: AudioTriggerPillProps): react.JSX.Element;
+
+interface SpectrumVisualizerProps {
+    isPlaying: boolean;
+    labels: PillLabels;
+    frequencyData?: number[];
+    hasLiveFrequency?: boolean;
+}
+declare function SpectrumVisualizer({ isPlaying, labels, frequencyData, hasLiveFrequency, }: SpectrumVisualizerProps): react.JSX.Element;
+
+interface AudioPlaylistProps {
+    tracks: AudioTrack[];
+    currentTrackIndex: number;
+    labels: PillLabels;
+    onSelectTrack: (index: number) => void;
+}
+declare function AudioPlaylist({ tracks, currentTrackIndex, labels, onSelectTrack, }: AudioPlaylistProps): react.JSX.Element;
+
+interface AudioSeekbarProps {
+    currentTime: number;
+    duration: number;
+    onSeek: (timeInSeconds: number) => void;
+}
+declare function AudioSeekbar({ currentTime, duration, onSeek, }: AudioSeekbarProps): react.JSX.Element;
+
+interface PlayerHeaderProps {
+    labels: PillLabels;
+    icons?: PillIcons;
+    onClose: () => void;
+}
+declare function PlayerHeader({ labels, icons, onClose }: PlayerHeaderProps): react.JSX.Element;
+
+interface TrackInfoProps {
+    currentTrack?: AudioTrack;
+    labels: PillLabels;
+}
+declare function TrackInfo({ currentTrack, labels }: TrackInfoProps): react.JSX.Element;
+
+interface PlayerControlsProps {
+    isPlaying: boolean;
+    isMuted: boolean;
+    externalLinkUrl?: string;
+    labels: PillLabels;
+    icons?: PillIcons;
+    onPrev: () => void;
+    onTogglePlay: () => void;
+    onNext: () => void;
+    onToggleMute: () => void;
+}
+declare function PlayerControls({ isPlaying, isMuted, externalLinkUrl, labels, icons, onPrev, onTogglePlay, onNext, onToggleMute, }: PlayerControlsProps): react.JSX.Element;
+
+interface ProviderEmbedsProps {
+    isLoaded: boolean;
+    embedMode: EmbedMode;
+    currentTrack?: AudioTrack;
+    labels: PillLabels;
+    isSoundCloud: boolean;
+    soundCloudIframeSrc: string;
+    scIframeRef: any;
+    onSoundCloudLoad: () => void;
+    isYouTube: boolean;
+    youTubeIframeSrc: string;
+    ytIframeRef: any;
+    onYouTubeLoad: () => void;
+    iframeSrc: string;
+    iframeRef: any;
+    onMixcloudLoad: () => void;
+}
+declare function ProviderEmbeds({ isLoaded, embedMode, currentTrack, labels, isSoundCloud, soundCloudIframeSrc, scIframeRef, onSoundCloudLoad, isYouTube, youTubeIframeSrc, ytIframeRef, onYouTubeLoad, iframeSrc, iframeRef, onMixcloudLoad, }: ProviderEmbedsProps): react.JSX.Element | null;
+
+interface IconProps extends SVGProps<SVGSVGElement> {
+    size?: number | string;
+}
+declare function PlayIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function PauseIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function SkipBackIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function SkipForwardIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function VolumeMuteIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function VolumeUpIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function CloseIcon({ size, ...props }: IconProps): react.JSX.Element;
+declare function ExternalLinkIcon({ size, ...props }: IconProps): react.JSX.Element;
+
+/**
+ * Extracts 11-character YouTube video ID from various URL formats or returns the ID if already clean.
+ */
+declare function extractYouTubeId(urlOrId?: string): string | null;
+
+interface UseAudioPlayerOptions {
+    tracks: AudioTrack[];
+    persistState?: boolean;
+    onTrackChange?: (track: AudioTrack, index: number) => void;
+    onPlayStateChange?: (isPlaying: boolean) => void;
+}
+declare function useAudioPlayer({ tracks, persistState, onTrackChange, onPlayStateChange, }: UseAudioPlayerOptions): {
+    tracks: AudioTrack[];
+    currentTrack: AudioTrack;
+    currentTrackIndex: number;
+    isPlaying: boolean;
+    isMuted: boolean;
+    isLoaded: boolean;
+    currentTime: number;
+    duration: number;
+    handleSeek: (seconds: number) => void;
+    iframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    scIframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    soundCloudIframeSrc: string;
+    isSoundCloud: boolean;
+    isYouTube: boolean;
+    ytIframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    youTubeIframeSrc: string;
+    setupYouTubePlayer: () => void;
+    isHtmlAudio: boolean;
+    isMixcloud: boolean;
+    setupSoundCloudWidget: () => void;
+    iframeSrc: string;
+    frequencyData: number[];
+    hasLiveFrequency: boolean;
+    timing: {
+        numericBpm: number;
+        beatMs: number;
+        halfBeatMs: number;
+        twoBeatsMs: number;
+        barMs: number;
+    };
+    setIsLoaded: react.Dispatch<react.SetStateAction<boolean>>;
+    handleTogglePlay: () => void;
+    handleToggleMute: () => void;
+    handleNextTrack: () => void;
+    handlePrevTrack: () => void;
+    handleSelectTrack: (index: number) => void;
+    setupMixcloudWidget: () => void;
+};
+
+/**
+ * Formats seconds into mm:ss or hh:mm:ss string.
+ */
+declare function formatTime(totalSeconds: number): string;
+/**
+ * Parses duration strings like "3:45", "30 min", or number of seconds.
+ */
+declare function parseDurationToSeconds(duration?: string): number;
+/**
+ * Calculates beat, half-beat, two-beats, and bar timings in milliseconds from BPM.
+ */
+declare function calculateBpmTiming(bpm?: number | string): {
+    numericBpm: number;
+    beatMs: number;
+    halfBeatMs: number;
+    twoBeatsMs: number;
+    barMs: number;
+};
+
+export { AudioPlaylist, AudioSeekbar, type AudioTrack, AudioTriggerPill, CloseIcon, DEFAULT_PILL_LABELS, type EmbedMode, ExternalLinkIcon, type IconProps, type MixcloudEmbedMode, PauseIcon, type PillColors, type PillFeatures, type PillIcons, type PillLabels, PillPlayer, type PillPlayerProps, type PillPosition, type PillTheme, PlayIcon, PlayerControls, PlayerHeader, ProviderEmbeds, SkipBackIcon, SkipForwardIcon, SpectrumVisualizer, TrackInfo, VolumeMuteIcon, VolumeUpIcon, calculateBpmTiming, extractYouTubeId, formatTime, parseDurationToSeconds, useAudioPlayer };