/**
 * @file queue_ui.h
 * @brief Handles high level enqueue
 *
 */

#include "data/directorytree.h"
#include "data/playlist_type.h"

/**
 * @brief Resets the playlist and playback state after dequeuing the currently playing song.
 *
 * This function resets various application states related to the playlist and playback
 * when the currently playing song is dequeued, ensuring the playback state is properly cleaned up.
 */
void reset_list_after_dequeuing_playing_song(void);

/**
 * @brief Enqueues a song and optionally starts playing it immediately.
 *
 * This function enqueues a song in the playlist, and if the `play_immediately` flag
 * is set to true, it starts playing the song right away.
 *
 * @param play_immediately Flag to indicate whether to start playing the song immediately.
 */
void view_enqueue(bool play_immediately);

/**
 * @brief Handles the action of jumping to a specific song in the playlist.
 *
 * This function performs the necessary steps to navigate to a specific song when
 * the "Go To Song" action is triggered.
 */
void handleGoToSong(void);

/**
 * @brief Updates the next song to be played if needed.
 *
 * This function checks if the next song in the playlist should be updated and
 * performs the necessary updates to the playback state.
 */
void preload_next_song(void);

/**
 * @brief Enqueues a single song entry into the playlist.
 *
 * This function adds a single song entry to the playlist and returns the entry that was enqueued.
 *
 * @param entry The song entry to enqueue.
 * @param dont_dequeue True if you can not dequeue.
 * @return The first enqueued node (if any).
 */
Node *enqueue(FileSystemEntry *entry, bool dont_dequeue);

/**
 * @brief Enqueues a set of songs from a directory into the playlist.
 *
 * This function enqueues all songs from a given directory into the playlist, ensuring
 * any necessary directory structures are handled.
 *
 * @param entry The directory entry to enqueue.
 * @param chosen_dir Pointer to the chosen directory, which can be updated.
 * @param dont_dequeue True if you can not dequeue.
 * @return The first enqueued node (if any).
 */

Node *enqueue_songs(FileSystemEntry *entry, FileSystemEntry **chosen_dir, bool dont_dequeue);


/**
 * @brief Toggle enqueue/dequeue for an M3U playlist file entry.
 *
 * Mirrors enqueue() for directories: handles the lastPlayedId bookkeeping,
 * locks the playlist mutex, delegates to enqueue_m3u() or dequeue_m3u(),
 * calls reset_list_after_dequeuing_playing_song(), and triggers a UI refresh.
 * The caller is responsible for acting on the returned node (e.g. autoplay).
 *
 * @param entry FileSystemEntry for the .m3u / .m3u8 file.
 * @param dont_dequeue True if you can not dequeue.
 * @return First Node added to the playlist, or NULL when dequeuing.
 */
Node *enqueue_playlist(FileSystemEntry *entry, bool dont_dequeue);
