@freqhole/playlistz 0.0.1

package/src/hooks/usePlaylistsQuery.test.tsx

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createRoot } from "solid-js";
+import { usePlaylistsQuery } from "./usePlaylistsQuery.js";
+import type { Playlist } from "../types/playlist.js";
+
+// mock all dependencies of usePlaylistsQuery
+vi.mock("./createDocIndexQuery.js", () => ({
+  createDocIndexQuery: vi.fn(() => () => []),
+}));
+
+vi.mock("../services/automergeRepo.js", () => ({
+  findPlaylistDoc: vi.fn(),
+  getRepo: vi.fn(),
+}));
+
+vi.mock("@freqhole/api-client/playlistz", () => ({
+  parsePlaylistDoc: vi.fn((raw: any) => raw ?? {}),
+}));
+
+vi.mock("../services/playlistDocService.js", () => ({
+  docToPlaylist: vi.fn((docId: string, _doc: any): Playlist => ({
+    id: docId,
+    title: "mocked playlist",
+    description: undefined,
+    createdAt: 0,
+    updatedAt: 0,
+    songIds: [],
+  })),
+}));
+
+describe("usePlaylistsQuery", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("basic structure", () => {
+    it("returns an object with a playlists signal", () => {
+      createRoot((dispose) => {
+        const result = usePlaylistsQuery();
+        expect(typeof result).toBe("object");
+        expect(typeof result.playlists).toBe("function");
+        dispose();
+      });
+    });
+
+    it("returns an empty array initially when no docIndex entries exist", () => {
+      createRoot((dispose) => {
+        const { playlists } = usePlaylistsQuery();
+        expect(Array.isArray(playlists())).toBe(true);
+        dispose();
+      });
+    });
+  });
+
+  describe("when docIndex has entries", () => {
+    it("resolves playlist data from docIndex entries", async () => {
+      const { createDocIndexQuery } = await import("./createDocIndexQuery.js");
+      const { findPlaylistDoc } = await import("../services/automergeRepo.js");
+
+      vi.mocked(createDocIndexQuery).mockReturnValue(() => [
+        {
+          docId: "automerge:abc123",
+          title: "test playlist",
+          addedAt: 1000,
+          peers: [],
+          acl: {},
+          localDraft: false,
+        } as any,
+      ]);
+
+      vi.mocked(findPlaylistDoc).mockResolvedValue({
+        doc: () => ({ title: "test playlist", songs: [] }),
+      } as any);
+
+      let resolvedPlaylists: Playlist[] = [];
+      await new Promise<void>((resolve) => {
+        createRoot((dispose) => {
+          const { playlists } = usePlaylistsQuery();
+          // give the effect time to run and resolve
+          setTimeout(() => {
+            resolvedPlaylists = playlists();
+            dispose();
+            resolve();
+          }, 50);
+        });
+      });
+
+      // playlists may be empty or resolved depending on timing, but no error should throw
+      expect(Array.isArray(resolvedPlaylists)).toBe(true);
+    });
+  });
+
+  describe("cleanup", () => {
+    it("cleans up without throwing when root is disposed", () => {
+      expect(() => {
+        createRoot((dispose) => {
+          usePlaylistsQuery();
+          dispose();
+        });
+      }).not.toThrow();
+    });
+
+    it("handles multiple instances independently", () => {
+      createRoot((dispose1) => {
+        const r1 = usePlaylistsQuery();
+        createRoot((dispose2) => {
+          const r2 = usePlaylistsQuery();
+          expect(typeof r1.playlists).toBe("function");
+          expect(typeof r2.playlists).toBe("function");
+          dispose2();
+        });
+        dispose1();
+      });
+    });
+  });
+});

package/src/hooks/usePlaylistsQuery.ts

@@ -0,0 +1,44 @@
+import { createSignal, createEffect } from "solid-js";
+import { createDocIndexQuery } from "./createDocIndexQuery.js";
+import { findPlaylistDoc } from "../services/automergeRepo.js";
+import { parsePlaylistDoc } from "@freqhole/api-client/playlistz";
+import { docToPlaylist } from "../services/playlistDocService.js";
+import type { Playlist } from "../types/playlist.js";
+import type { AutomergeUrl } from "@automerge/automerge-repo";
+
+// solid hook that creates a reactive playlist list backed by the docIndex.
+// replaces the old idb live-query approach.
+export function usePlaylistsQuery() {
+  const [playlists, setPlaylists] = createSignal<Playlist[]>([], {
+    equals: false,
+  });
+
+  const entries = createDocIndexQuery();
+
+  createEffect(() => {
+    const list = entries();
+    Promise.all(
+      list.map(async (entry) => {
+        try {
+          const handle = await findPlaylistDoc(entry.docId as AutomergeUrl);
+          const raw = handle.doc();
+          const doc = parsePlaylistDoc(raw ?? {});
+          return docToPlaylist(entry.docId, doc);
+        } catch {
+          return {
+            id: entry.docId,
+            title: entry.title,
+            description: undefined,
+            createdAt: entry.addedAt,
+            updatedAt: entry.addedAt,
+            songIds: [],
+          } as Playlist;
+        }
+      })
+    ).then((resolved) => setPlaylists(resolved));
+  });
+
+  return {
+    playlists,
+  };
+}

package/src/hooks/useSongState.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createRoot } from "solid-js";
+import { useSongState } from "./useSongState.js";
+import type { Song } from "../types/playlist.js";
+
+vi.mock("../services/audioService.js", () => ({
+  playSong: vi.fn(),
+  playSongFromPlaylist: vi.fn(),
+  togglePlayback: vi.fn(),
+  audioState: {
+    currentSong: vi.fn(() => null),
+    isPlaying: vi.fn(() => false),
+  },
+}));
+
+vi.mock("../services/playlistDocService.js", () => ({
+  updateSongInDoc: vi.fn().mockResolvedValue(undefined),
+}));
+
+const mockSong: Song = {
+  id: "song-1",
+  playlistId: "pl-1",
+  title: "test song",
+  artist: "test artist",
+  album: "test album",
+  duration: 180,
+  originalFilename: "test.mp3",
+  fileSize: 5000000,
+  mimeType: "audio/mpeg",
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+  position: 0,
+};
+
+const mockSong2: Song = { ...mockSong, id: "song-2", title: "song two" };
+
+describe("useSongState edit mode", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("starts with no edit mode active", () => {
+    createRoot((dispose) => {
+      const hook = useSongState();
+      expect(hook.editingSong()).toBeNull();
+      expect(hook.editingPlaylist()).toBe(false);
+      expect(hook.isEditMode()).toBe(false);
+      dispose();
+    });
+  });
+
+  describe("playlist edit mode", () => {
+    it("activates playlist edit mode", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditPlaylist();
+        expect(hook.editingPlaylist()).toBe(true);
+        expect(hook.editingSong()).toBeNull();
+        expect(hook.isEditMode()).toBe(true);
+        dispose();
+      });
+    });
+
+    it("clears song edit when entering playlist edit", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        hook.handleEditPlaylist();
+        expect(hook.editingSong()).toBeNull();
+        expect(hook.editingPlaylist()).toBe(true);
+        dispose();
+      });
+    });
+
+    it("exits playlist edit mode via handleCloseEdit", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditPlaylist();
+        hook.handleCloseEdit();
+        expect(hook.editingPlaylist()).toBe(false);
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+
+    it("exits playlist edit mode via setEditingPlaylist(false)", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditPlaylist();
+        hook.setEditingPlaylist(false);
+        expect(hook.editingPlaylist()).toBe(false);
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+  });
+
+  describe("song edit mode", () => {
+    it("activates song edit mode with the correct song", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        expect(hook.editingSong()).toEqual(mockSong);
+        expect(hook.editingPlaylist()).toBe(false);
+        expect(hook.isEditMode()).toBe(true);
+        dispose();
+      });
+    });
+
+    it("keeps playlist edit open when entering song edit", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditPlaylist();
+        hook.handleEditSong(mockSong);
+        expect(hook.editingPlaylist()).toBe(true);
+        expect(hook.editingSong()).toEqual(mockSong);
+        dispose();
+      });
+    });
+
+    it("switches between songs without going through idle state", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        hook.handleEditSong(mockSong2);
+        expect(hook.editingSong()).toEqual(mockSong2);
+        expect(hook.isEditMode()).toBe(true);
+        dispose();
+      });
+    });
+
+    it("exits song edit mode via handleCloseEdit", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        hook.handleCloseEdit();
+        expect(hook.editingSong()).toBeNull();
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+
+    it("exits song edit mode via setEditingSong(null)", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        hook.setEditingSong(null);
+        expect(hook.editingSong()).toBeNull();
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+  });
+
+  describe("handleSongSaved", () => {
+    it("updates song in IDB and keeps editing the saved song", async () => {
+      const { updateSongInDoc } = await import("../services/playlistDocService.js");
+      let savedHook: ReturnType<typeof useSongState> | undefined;
+      createRoot((dispose) => {
+        savedHook = useSongState();
+        savedHook.handleEditSong(mockSong);
+        dispose();
+      });
+      // test the async call outside the root since createRoot disposes sync
+      const hook = (() => {
+        let h: ReturnType<typeof useSongState>;
+        createRoot(() => { h = useSongState(); h.handleEditSong(mockSong); });
+        return h!;
+      })();
+      const updatedSong = { ...mockSong, title: "updated title" };
+      await hook.handleSongSaved(updatedSong);
+      expect(updateSongInDoc).toHaveBeenCalledWith(updatedSong.playlistId, updatedSong.id, updatedSong);
+      // panel stays open with the saved values
+      expect(hook.editingSong()).toEqual(updatedSong);
+      expect(hook.isEditMode()).toBe(true);
+    });
+
+    it("sets error when IDB update fails", async () => {
+      const { updateSongInDoc } = await import("../services/playlistDocService.js");
+      vi.mocked(updateSongInDoc).mockRejectedValueOnce(new Error("db error"));
+      let hook: ReturnType<typeof useSongState>;
+      createRoot(() => { hook = useSongState(); hook!.handleEditSong(mockSong); });
+      await hook!.handleSongSaved(mockSong);
+      expect(hook!.error()).toBeTruthy();
+    });
+  });
+
+  describe("isEditMode derived signal", () => {
+    it("is false when neither song nor playlist is being edited", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+
+    it("is true when editing a song", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        expect(hook.isEditMode()).toBe(true);
+        dispose();
+      });
+    });
+
+    it("is true when editing the playlist", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditPlaylist();
+        expect(hook.isEditMode()).toBe(true);
+        dispose();
+      });
+    });
+
+    it("returns to false after handleCloseEdit from song edit", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditSong(mockSong);
+        hook.handleCloseEdit();
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+
+    it("returns to false after handleCloseEdit from playlist edit", () => {
+      createRoot((dispose) => {
+        const hook = useSongState();
+        hook.handleEditPlaylist();
+        hook.handleCloseEdit();
+        expect(hook.isEditMode()).toBe(false);
+        dispose();
+      });
+    });
+  });
+});
+

package/src/hooks/useSongState.ts

@@ -0,0 +1,114 @@
+
+import { createSignal, batch } from "solid-js";
+import type { Song, Playlist } from "../types/playlist.js";
+import { updateSongInDoc } from "../services/playlistDocService.js";
+import { log } from "../utils/log.js";
+import {
+  playSong,
+  playSongFromPlaylist,
+  togglePlayback,
+  audioState,
+} from "../services/audioService.js";
+
+export function useSongState() {
+  const [editingSong, setEditingSong] = createSignal<Song | null>(null);
+  const [editingPlaylist, setEditingPlaylist] = createSignal(false);
+
+  // true when any edit panel is open
+  const isEditMode = () => editingSong() !== null || editingPlaylist();
+
+  const [error, setError] = createSignal<string | null>(null);
+
+  // note: does not clear playlist edit mode - the song edit panel can
+  // coexist below the playlist edit panel
+  const handleEditSong = (song: Song) => {
+    setEditingSong(song);
+  };
+
+  const handleEditPlaylist = () => {
+    setEditingSong(null);
+    setEditingPlaylist(true);
+  };
+
+  // batched so dependent effects see both signals cleared at once
+  // (otherwise clearing the song while playlist edit is still open would
+  // re-trigger the default-song effect and re-open the song panel)
+  const handleCloseEdit = () => {
+    batch(() => {
+      setEditingSong(null);
+      setEditingPlaylist(false);
+    });
+  };
+
+  // handle song update after editing - keeps the edit panel open and refreshes
+  // the editing song reference with the saved values
+  const handleSongSaved = async (updatedSong: Song) => {
+    try {
+      setError(null);
+      // song.playlistId is the docId for doc-backed songs
+      await updateSongInDoc(updatedSong.playlistId, updatedSong.id, updatedSong);
+      setEditingSong(updatedSong);
+    } catch (err) {
+      log.error("song.save", "error saving song:", err);
+      setError("failed to save song changes");
+    }
+  };
+
+  const handlePlaySong = async (song: Song, playlist?: Playlist) => {
+    try {
+      setError(null);
+      if (playlist) {
+        await playSongFromPlaylist(song, playlist);
+      } else {
+        await playSong(song);
+      }
+    } catch (err) {
+      log.error("song.play", "error playing song:", err);
+      setError("failed to play song");
+    }
+  };
+
+  const handlePauseSong = async () => {
+    try {
+      setError(null);
+      await togglePlayback();
+    } catch (err) {
+      log.error("song.play", "error pausing song:", err);
+      setError("Failed to pause song");
+    }
+  };
+
+  const isSongPlaying = (songId: string) => {
+    const currentSong = audioState.currentSong();
+    return currentSong?.id === songId && audioState.isPlaying();
+  };
+
+  // is song currently selected (but maybe paused)
+  const isSongSelected = (songId: string) => {
+    const currentSong = audioState.currentSong();
+    return currentSong?.id === songId;
+  };
+
+  return {
+    editingSong,
+    editingPlaylist,
+    isEditMode,
+    error,
+
+    // setterz
+    setEditingSong,
+    setEditingPlaylist,
+
+    // actionz
+    handleEditSong,
+    handleEditPlaylist,
+    handleCloseEdit,
+    handleSongSaved,
+    handlePlaySong,
+    handlePauseSong,
+
+    // utilz
+    isSongPlaying,
+    isSongSelected,
+  };
+}

package/src/hooks/useUIState.ts

@@ -0,0 +1,71 @@
+
+import { createSignal, onMount, onCleanup } from "solid-js";
+
+export function useUIState() {
+  const [isMobile, setIsMobile] = createSignal(false);
+
+  const [isDragOver, setIsDragOver] = createSignal(false);
+
+  const [backgroundImageUrl, setBackgroundImageUrl] = createSignal<
+    string | null
+  >(null);
+
+  const [imageUrlCache] = createSignal(new Map<string, string>());
+
+  const checkMobile = () => {
+    const mobile = window.innerWidth < 900;
+    setIsMobile(mobile);
+  };
+
+  // window resize for mobile detection
+  const handleResize = () => {
+    checkMobile();
+  };
+
+  // escape key for closing modals/dialogs
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === "Escape") {
+      // this can be extended by components using this hook
+      return { key: e.key, preventDefault: () => e.preventDefault() };
+    }
+    return undefined;
+  };
+
+  // init + cleanup for mobile detection
+  onMount(() => {
+    checkMobile();
+    window.addEventListener("resize", handleResize);
+    document.addEventListener("keydown", handleKeyDown);
+
+    onCleanup(() => {
+      window.removeEventListener("resize", handleResize);
+      document.removeEventListener("keydown", handleKeyDown);
+    });
+  });
+
+  // trash image URLs when component unmounts
+  onCleanup(() => {
+    const cache = imageUrlCache();
+    cache.forEach((url) => {
+      if (url.startsWith("blob:")) {
+        URL.revokeObjectURL(url);
+      }
+    });
+    cache.clear();
+  });
+
+  return {
+    isMobile,
+    isDragOver,
+    backgroundImageUrl,
+    imageUrlCache,
+
+    // setterz
+    setIsMobile,
+    setIsDragOver,
+    setBackgroundImageUrl,
+
+    // utilz
+    checkMobile,
+  };
+}

package/src/index.tsx

@@ -0,0 +1,18 @@
+/* @refresh reload */
+import { render } from "solid-js/web";
+import App from "./App";
+
+const root = document.getElementById("root");
+
+if (import.meta.env.DEV && !(root instanceof HTMLElement)) {
+  throw new Error(
+    "Root element not found. Did you forget to add it to your index.html? Or maybe the id attribute got misspelled?"
+  );
+}
+
+// clear any existing loading content
+if (root) {
+  root.innerHTML = "";
+}
+
+render(() => <App />, root!);

package/src/services/audioService.dev.ts

@@ -0,0 +1,22 @@
+// dev-only hook registrations for audio service.
+//
+// registers window.__seekTo, __triggerTrackEnd, __triggerAudioError.
+// these are time-acceleration hooks, not transport mocks - they drive
+// the real audio element without substituting any service boundary.
+//
+// only loaded in DEV builds (via src/dev-hooks.ts).
+
+import {
+  _devSeekTo,
+  _devTriggerTrackEnd,
+  _devTriggerAudioError,
+  audioState,
+} from "./audioService.js";
+
+export function registerAudioDevHooks(): void {
+  window.__seekTo = _devSeekTo;
+  window.__triggerTrackEnd = _devTriggerTrackEnd;
+  window.__triggerAudioError = _devTriggerAudioError;
+  // returns the title of the currently playing song, or null
+  window.__currentSong = () => audioState.currentSong()?.title ?? null;
+}