morille 0.1.0

package/dist/contexts/search-context.js

@@ -0,0 +1,338 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { useBrowse } from '../hooks/use-browse.js';
+import { useSearch } from '../hooks/use-search.js';
+import { playInContext } from '../spotify/playback.js';
+import { usePanelMode } from './panel-mode-context.js';
+const CATEGORIES = [
+    'tracks',
+    'albums',
+    'artists',
+    'playlists',
+];
+const SearchContext = createContext(null);
+function getCategoryItems(results, category) {
+    if (!results)
+        return 0;
+    return results[category].length;
+}
+/**
+ * Provides search state, navigation stack, and selection controls.
+ * Only active when the search panel is open.
+ */
+export function SearchProvider({ client, track, playTrackUri, refresh, children }) {
+    const { panelMode, setInputMode, toggleSearch } = usePanelMode();
+    const isActive = panelMode === 'search';
+    const { query, setQuery, results, isLoading: isSearchLoading, clear: clearSearch } = useSearch(client, isActive);
+    const { data: browseData, isLoading: isBrowseLoading, userPlaylists, isPlaylistsLoading, loadAlbum, loadPlaylist, loadUserPlaylists, clear: clearBrowse, } = useBrowse(client);
+    const [viewStack, setViewStack] = useState([]);
+    const [selectedCategory, setSelectedCategory] = useState('tracks');
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const [browseSelectedIndex, setBrowseSelectedIndex] = useState(0);
+    // Stack of previous search states pushed by query refinements (e.g. selecting an artist
+    // replaces the query in place). Pressing Esc pops one entry to restore the prior query.
+    const [queryHistory, setQueryHistory] = useState([]);
+    const currentView = viewStack.length > 0
+        ? viewStack[viewStack.length - 1]
+        : {
+            kind: 'input',
+        };
+    // Track activation transitions so we only auto-focus the input when the panel
+    // first opens — not every time the user pops back to the input view from a drill-down.
+    const wasActiveRef = useRef(isActive);
+    useEffect(() => {
+        if (isActive && !wasActiveRef.current) {
+            // Panel just opened: focus the text input only if we landed on the input view
+            // (opening via `b` lands directly on the playlists view → stay in browse mode)
+            setInputMode(currentView.kind === 'input');
+        }
+        else if (!isActive && wasActiveRef.current) {
+            // Panel just closed: reset all state
+            setViewStack([]);
+            setQueryHistory([]);
+            setSelectedCategory('tracks');
+            setSelectedIndex(0);
+            setBrowseSelectedIndex(0);
+            clearSearch();
+            clearBrowse();
+        }
+        wasActiveRef.current = isActive;
+    }, [
+        isActive,
+        currentView.kind,
+        setInputMode,
+        clearSearch,
+        clearBrowse,
+    ]);
+    // Reset selected index when results change
+    // biome-ignore lint/correctness/useExhaustiveDependencies: results is intentionally a trigger
+    useEffect(() => {
+        setSelectedIndex(0);
+    }, [
+        results,
+    ]);
+    const navigateUp = useCallback(() => {
+        if (currentView.kind === 'input') {
+            setSelectedIndex((v) => Math.max(0, v - 1));
+        }
+        else {
+            setBrowseSelectedIndex((v) => Math.max(0, v - 1));
+        }
+    }, [
+        currentView.kind,
+    ]);
+    const navigateDown = useCallback(() => {
+        if (currentView.kind === 'input') {
+            const max = getCategoryItems(results, selectedCategory) - 1;
+            setSelectedIndex((v) => Math.min(Math.max(max, 0), v + 1));
+        }
+        else if (currentView.kind === 'playlists') {
+            const max = (userPlaylists?.length ?? 1) - 1;
+            setBrowseSelectedIndex((v) => Math.min(Math.max(max, 0), v + 1));
+        }
+        else {
+            const max = (browseData?.tracks.length ?? 1) - 1;
+            setBrowseSelectedIndex((v) => Math.min(Math.max(max, 0), v + 1));
+        }
+    }, [
+        currentView.kind,
+        results,
+        selectedCategory,
+        browseData,
+        userPlaylists,
+    ]);
+    const navigateLeft = useCallback(() => {
+        if (currentView.kind === 'input') {
+            setSelectedCategory((cat) => {
+                const idx = CATEGORIES.indexOf(cat);
+                return CATEGORIES[(idx - 1 + CATEGORIES.length) % CATEGORIES.length];
+            });
+            setSelectedIndex(0);
+        }
+    }, [
+        currentView.kind,
+    ]);
+    const navigateRight = useCallback(() => {
+        if (currentView.kind === 'input') {
+            setSelectedCategory((cat) => {
+                const idx = CATEGORIES.indexOf(cat);
+                return CATEGORIES[(idx + 1) % CATEGORIES.length];
+            });
+            setSelectedIndex(0);
+        }
+    }, [
+        currentView.kind,
+    ]);
+    const pushView = useCallback((view) => {
+        setViewStack((v) => [
+            ...v,
+            view,
+        ]);
+        setBrowseSelectedIndex(0);
+    }, []);
+    const popView = useCallback(() => {
+        if (viewStack.length === 0)
+            return;
+        const nextStack = viewStack.slice(0, -1);
+        setViewStack(nextStack);
+        setBrowseSelectedIndex(0);
+        clearBrowse();
+        // When returning to the input view, focus the input only if there's nothing
+        // left to browse (e.g. opened via `b`, drilled in, popped all the way back).
+        // If results exist, stay in browse mode so the user can keep navigating them.
+        if (nextStack.length === 0 && results === null) {
+            setInputMode(true);
+        }
+    }, [
+        viewStack,
+        clearBrowse,
+        results,
+        setInputMode,
+    ]);
+    const selectSearchResult = useCallback(async () => {
+        if (!results)
+            return;
+        const items = results[selectedCategory];
+        const item = items[selectedIndex];
+        if (!item)
+            return;
+        switch (selectedCategory) {
+            case 'tracks': {
+                const t = item;
+                const deviceId = track?.deviceId;
+                if (!deviceId)
+                    return;
+                if (t.albumUri) {
+                    await playInContext(client, deviceId, t.albumUri, t.uri);
+                }
+                else {
+                    await playTrackUri(t.uri);
+                }
+                await refresh();
+                break;
+            }
+            case 'albums': {
+                const a = item;
+                pushView({
+                    kind: 'album',
+                    id: a.id,
+                    name: a.name,
+                });
+                loadAlbum(a.id);
+                break;
+            }
+            case 'playlists': {
+                const p = item;
+                pushView({
+                    kind: 'playlist',
+                    id: p.id,
+                    name: p.name,
+                });
+                loadPlaylist(p.id);
+                break;
+            }
+            case 'artists': {
+                const ar = item;
+                // Save current search state so Esc can restore it
+                setQueryHistory((h) => [
+                    ...h,
+                    {
+                        query,
+                        category: selectedCategory,
+                    },
+                ]);
+                setQuery(ar.name);
+                setSelectedCategory('albums');
+                setSelectedIndex(0);
+                break;
+            }
+        }
+    }, [
+        results,
+        selectedCategory,
+        selectedIndex,
+        track,
+        client,
+        playTrackUri,
+        refresh,
+        setQuery,
+        query,
+        pushView,
+        loadAlbum,
+        loadPlaylist,
+    ]);
+    const selectBrowseTrack = useCallback(async () => {
+        const trackItem = browseData?.tracks[browseSelectedIndex];
+        const deviceId = track?.deviceId;
+        if (!trackItem || !deviceId || !browseData)
+            return;
+        await playInContext(client, deviceId, browseData.contextUri, trackItem.uri);
+        await refresh();
+    }, [
+        browseData,
+        browseSelectedIndex,
+        track,
+        client,
+        refresh,
+    ]);
+    const selectPlaylist = useCallback(() => {
+        const playlist = userPlaylists?.[browseSelectedIndex];
+        if (!playlist)
+            return;
+        pushView({
+            kind: 'playlist',
+            id: playlist.id,
+            name: playlist.name,
+        });
+        loadPlaylist(playlist.id);
+    }, [
+        userPlaylists,
+        browseSelectedIndex,
+        pushView,
+        loadPlaylist,
+    ]);
+    const select = useCallback(async () => {
+        switch (currentView.kind) {
+            case 'input':
+                await selectSearchResult();
+                break;
+            case 'album':
+            case 'playlist':
+                await selectBrowseTrack();
+                break;
+            case 'playlists':
+                selectPlaylist();
+                break;
+        }
+    }, [
+        currentView.kind,
+        selectSearchResult,
+        selectBrowseTrack,
+        selectPlaylist,
+    ]);
+    const doBrowseUserPlaylists = useCallback(() => {
+        if (!isActive)
+            toggleSearch();
+        pushView({
+            kind: 'playlists',
+        });
+        loadUserPlaylists();
+    }, [
+        isActive,
+        toggleSearch,
+        pushView,
+        loadUserPlaylists,
+    ]);
+    const goBack = useCallback(() => {
+        if (viewStack.length > 0) {
+            popView();
+            return;
+        }
+        if (queryHistory.length > 0) {
+            // Restore the previous search state (used after artist refinement)
+            const prev = queryHistory[queryHistory.length - 1];
+            setQueryHistory((h) => h.slice(0, -1));
+            setQuery(prev.query);
+            setSelectedCategory(prev.category);
+            setSelectedIndex(0);
+        }
+    }, [
+        viewStack.length,
+        popView,
+        queryHistory,
+        setQuery,
+    ]);
+    const value = {
+        query,
+        results,
+        isSearchLoading,
+        currentView,
+        canGoBack: viewStack.length > 0 || queryHistory.length > 0,
+        browseData,
+        isBrowseLoading,
+        userPlaylists,
+        isPlaylistsLoading,
+        selectedCategory,
+        selectedIndex: currentView.kind === 'input' ? selectedIndex : browseSelectedIndex,
+        currentTrackUri: track?.uri ?? null,
+        currentContextUri: track?.context?.uri ?? null,
+        setQuery: isActive ? setQuery : undefined,
+        navigateUp: isActive ? navigateUp : undefined,
+        navigateDown: isActive ? navigateDown : undefined,
+        navigateLeft: isActive ? navigateLeft : undefined,
+        navigateRight: isActive ? navigateRight : undefined,
+        select: isActive ? select : undefined,
+        goBack: isActive ? goBack : undefined,
+        browseUserPlaylists: doBrowseUserPlaylists,
+    };
+    return _jsx(SearchContext, { value: value, children: children });
+}
+/**
+ * Access search state and navigation controls.
+ */
+export function useSearchContext() {
+    const ctx = useContext(SearchContext);
+    if (!ctx)
+        throw new Error('useSearchContext must be used within SearchProvider');
+    return ctx;
+}

package/dist/hooks/use-album-art.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fetches an album art image and converts it to a terminal-renderable ANSI string.
+ * Caches by URL to avoid re-fetching on every render cycle.
+ * @param imageUrl - URL of the album art image, or null if unavailable
+ * @param height - Desired height in terminal rows
+ * @returns The ANSI art string and loading state
+ */
+export declare function useAlbumArt(imageUrl: string | null, height: number): string | null;

package/dist/hooks/use-album-art.js

@@ -0,0 +1,56 @@
+import { useEffect, useRef, useState } from 'react';
+import terminalImage from 'terminal-image';
+/**
+ * Fetches an album art image and converts it to a terminal-renderable ANSI string.
+ * Caches by URL to avoid re-fetching on every render cycle.
+ * @param imageUrl - URL of the album art image, or null if unavailable
+ * @param height - Desired height in terminal rows
+ * @returns The ANSI art string and loading state
+ */
+export function useAlbumArt(imageUrl, height) {
+    const [art, setArt] = useState(null);
+    const cacheRef = useRef(null);
+    useEffect(() => {
+        if (!imageUrl) {
+            setArt(null);
+            return;
+        }
+        if (cacheRef.current?.url === imageUrl && cacheRef.current.height === height) {
+            setArt(cacheRef.current.art);
+            return;
+        }
+        let cancelled = false;
+        async function load() {
+            try {
+                const response = await fetch(imageUrl);
+                const arrayBuffer = await response.arrayBuffer();
+                const rendered = await terminalImage.buffer(new Uint8Array(arrayBuffer), {
+                    height,
+                    preserveAspectRatio: true,
+                    preferNativeRender: false,
+                });
+                if (!cancelled) {
+                    cacheRef.current = {
+                        url: imageUrl,
+                        height,
+                        art: rendered,
+                    };
+                    setArt(rendered);
+                }
+            }
+            catch {
+                if (!cancelled) {
+                    setArt(null);
+                }
+            }
+        }
+        load();
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        imageUrl,
+        height,
+    ]);
+    return art;
+}

package/dist/hooks/use-browse.d.ts

@@ -0,0 +1,29 @@
+import type { SpotifyApi } from '@spotify/web-api-ts-sdk';
+import type { SearchResultPlaylist } from '../spotify/search.js';
+export type BrowseData = {
+    kind: 'album' | 'playlist';
+    title: string;
+    subtitle: string | null;
+    contextUri: string;
+    tracks: Array<{
+        name: string;
+        artist: string;
+        uri: string;
+        durationMs: number;
+    }>;
+};
+/**
+ * Manages drill-down browse state for albums, playlists, and user playlist library.
+ * @param client - Authenticated Spotify API client
+ * @returns Browse state and load actions
+ */
+export declare function useBrowse(client: SpotifyApi): {
+    data: BrowseData | null;
+    isLoading: boolean;
+    userPlaylists: SearchResultPlaylist[] | null;
+    isPlaylistsLoading: boolean;
+    loadAlbum: (albumId: string) => Promise<void>;
+    loadPlaylist: (playlistId: string) => Promise<void>;
+    loadUserPlaylists: () => Promise<void>;
+    clear: () => void;
+};

package/dist/hooks/use-browse.js

@@ -0,0 +1,98 @@
+import { useCallback, useRef, useState } from 'react';
+import { fetchAlbumTracks, fetchPlaylistTracks, fetchUserPlaylists } from '../spotify/search.js';
+/**
+ * Manages drill-down browse state for albums, playlists, and user playlist library.
+ * @param client - Authenticated Spotify API client
+ * @returns Browse state and load actions
+ */
+export function useBrowse(client) {
+    const [data, setData] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [userPlaylists, setUserPlaylists] = useState(null);
+    const [isPlaylistsLoading, setIsPlaylistsLoading] = useState(false);
+    const cancelRef = useRef(0);
+    const loadAlbum = useCallback(async (albumId) => {
+        const token = ++cancelRef.current;
+        setIsLoading(true);
+        try {
+            const album = await fetchAlbumTracks(client, albumId);
+            if (cancelRef.current !== token)
+                return;
+            setData({
+                kind: 'album',
+                title: album.name,
+                subtitle: album.artist,
+                contextUri: album.uri,
+                tracks: album.tracks,
+            });
+        }
+        catch {
+            if (cancelRef.current !== token)
+                return;
+            setData(null);
+        }
+        finally {
+            if (cancelRef.current === token)
+                setIsLoading(false);
+        }
+    }, [
+        client,
+    ]);
+    const loadPlaylist = useCallback(async (playlistId) => {
+        const token = ++cancelRef.current;
+        setIsLoading(true);
+        try {
+            const playlist = await fetchPlaylistTracks(client, playlistId);
+            if (cancelRef.current !== token)
+                return;
+            setData({
+                kind: 'playlist',
+                title: playlist.name,
+                subtitle: playlist.owner,
+                contextUri: playlist.uri,
+                tracks: playlist.tracks,
+            });
+        }
+        catch {
+            if (cancelRef.current !== token)
+                return;
+            setData(null);
+        }
+        finally {
+            if (cancelRef.current === token)
+                setIsLoading(false);
+        }
+    }, [
+        client,
+    ]);
+    const loadUserPlaylists = useCallback(async () => {
+        setIsPlaylistsLoading(true);
+        try {
+            const result = await fetchUserPlaylists(client);
+            setUserPlaylists(result.items);
+        }
+        catch {
+            setUserPlaylists(null);
+        }
+        finally {
+            setIsPlaylistsLoading(false);
+        }
+    }, [
+        client,
+    ]);
+    const clear = useCallback(() => {
+        cancelRef.current++;
+        setData(null);
+        setIsLoading(false);
+    }, []);
+    return {
+        data,
+        isLoading,
+        userPlaylists,
+        isPlaylistsLoading,
+        loadAlbum,
+        loadPlaylist,
+        loadUserPlaylists,
+        clear,
+    };
+}

package/dist/hooks/use-lyrics.d.ts

@@ -0,0 +1,12 @@
+import type { Lyrics } from '../spotify/lyrics.js';
+import type { TrackInfo } from '../spotify/playback.js';
+/**
+ * Fetches and caches lyrics for the currently playing track.
+ * Refetches when the track name or artist changes.
+ * @param track - Current track info, or null if nothing is playing
+ * @returns Lyrics data and loading state
+ */
+export declare function useLyrics(track: TrackInfo | null): {
+    lyrics: Lyrics | null;
+    isLoading: boolean;
+};

package/dist/hooks/use-lyrics.js

@@ -0,0 +1,51 @@
+import { useEffect, useRef, useState } from 'react';
+import { fetchLyrics } from '../spotify/lyrics.js';
+/**
+ * Fetches and caches lyrics for the currently playing track.
+ * Refetches when the track name or artist changes.
+ * @param track - Current track info, or null if nothing is playing
+ * @returns Lyrics data and loading state
+ */
+export function useLyrics(track) {
+    const [lyrics, setLyrics] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const cacheRef = useRef(null);
+    const trackKey = track ? `${track.name}::${track.artist}` : null;
+    const trackRef = useRef(track);
+    trackRef.current = track;
+    useEffect(() => {
+        if (!trackKey) {
+            return;
+        }
+        if (cacheRef.current?.key === trackKey) {
+            setLyrics(cacheRef.current.lyrics);
+            return;
+        }
+        let cancelled = false;
+        setIsLoading(true);
+        async function load() {
+            const current = trackRef.current;
+            if (!current)
+                return;
+            const result = await fetchLyrics(current.name, current.artist, current.durationMs);
+            if (!cancelled) {
+                cacheRef.current = {
+                    key: trackKey,
+                    lyrics: result,
+                };
+                setLyrics(result);
+                setIsLoading(false);
+            }
+        }
+        load();
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        trackKey,
+    ]);
+    return {
+        lyrics,
+        isLoading,
+    };
+}

package/dist/hooks/use-playback.d.ts

@@ -0,0 +1,24 @@
+import type { SpotifyApi } from '@spotify/web-api-ts-sdk';
+import type { TrackInfo } from '../spotify/playback.js';
+/**
+ * React hook that manages Spotify playback state. Polls the current track
+ * at a regular interval and exposes toggle/refresh controls.
+ * @param client - Authenticated Spotify API client
+ * @returns Playback state, loading/error indicators, and control functions
+ */
+export declare function usePlayback(client: SpotifyApi): {
+    track: TrackInfo | null;
+    isLoading: boolean;
+    error: string | null;
+    toggle: () => Promise<void>;
+    next: () => Promise<void>;
+    previous: () => Promise<void>;
+    seekForward: () => Promise<void>;
+    seekBackward: () => Promise<void>;
+    volumeUp: () => Promise<void>;
+    volumeDown: () => Promise<void>;
+    toggleShuffleMode: () => Promise<void>;
+    cycleRepeat: () => Promise<void>;
+    playTrackUri: (uri: string) => Promise<void>;
+    refresh: () => Promise<void>;
+};