Merge pull request #4 from tameTNT/heardle-v2-improvements

Heardle v2 improvements

Author: tameTNT

README.md

@@ -0,0 +1,71 @@
+# LOONA Heardle
+
+## Description
+
+A variation on the original [Heardle game](https://heardlewordle.io/) (itself
+inspired by the word guessing game Wordle) where the player has to guess a song
+within 6 tries. The amount of the song played increases with each guess up to a
+full 30 seconds of the track for the final guess. This variation plays only
+songs from the **K-Pop group [LOONA](https://en.wikipedia.org/wiki/Loona)**
+(including all subunits, solo, and drama OST tracks). A different song is
+selected each day at midnight UTC.
+
+The page is optimised for mobile and desktop devices and includes light and dark
+modes for comfortable use.
+
+## Deployment
+
+The game is hosted for anyone to play on https://51.pegasib.dev/links/heardle.
+
+## Technical Implementation
+
+### Songs
+
+The songs used for the game are extracted from
+[a Spotify playlist](https://open.spotify.com/playlist/05bRCDfqjNVnysz17hocZn)
+by the script `update_track_info.py` which should be run whenever the original
+playlist is updated. This script uses the Spotify API (via
+[`spotipy`](https://spotipy.readthedocs.io/en/master/)) to fetch information for
+each track and stores it in a JSON file (`heardle_track_info.json`) alongside
+the additionally collected preview url of the track (not provided by the API).
+
+### Frameworks
+
+The client/server is implemented using the [Fresh](https://fresh.deno.dev/)
+framework (built around [Preact](https://preactjs.com/)) and run using the
+[Deno](https://deno.com/) JavaScript runtime. Styling is done using
+[Tailwind CSS](https://tailwindcss.com/).
+
+Frontend components are located in `/components` which are used to build islands
+in `/islands`. The main page is given by `/routes/index.tsx` with API routes in
+`/routes/api`.
+
+## Local Development
+
+To run and develop the game locally, you need to have [Deno](https://deno.com/)
+installed via, e.g. for Unix systems:
+
+```bash
+curl -fsSL https://deno.land/install.sh | sh
+```
+
+Then follow the following steps:
+
+1. Clone the GitHub repository and change into the directory:
+   ```bash
+   git clone "URL" heardle_server # todo: insert dedicated repository URL here (after splitting)
+   cd heardle_server
+   ```
+2. Download song data by running the python script `update_track_info.py` via,
+   e.g. [uv](https://docs.astral.sh/uv/) (which automatically handles script
+   dependencies):
+   ```bash
+   uv run update_track_info.py
+   ```
+   This will create the file `~/heardle_track_info.json` (i.e. in your home
+   directory) which contains the song data used by the game.
+3. Then just start the project (this will also install all dependencies):
+   ```bash
+   deno task start
+   ```
+   The local server will start on port [9989](http://localhost:9989).

heardle_server/README.md

@@ -4,7 +4,7 @@ export default function Button(props: JSX.HTMLAttributes<HTMLButtonElement>) {
   return (
     <button
       {...props}
-      class={`${props.class} py-1 px-2 h-full border-2 border-white text-white bg-sky-500 hover:bg-sky-600 transition-colors cursor-pointer`}
+      class={`${props.class} py-1 px-2 h-full border-2 border-white text-white bg-sky-500 disabled:bg-gray-400 not-disabled:hover:bg-sky-600 transition-colors duration-500 not-disabled:cursor-pointer`}
     />
   );
 }

heardle_server/components/Button.tsx

@@ -2,12 +2,19 @@ import { JSX } from "preact";
 import { Signal, useSignalEffect } from "@preact/signals";
 import { useEffect, useRef, useState } from "preact/hooks";
 
-import { getSubtitleForSong, makeArtistString } from "../helpers.tsx";
+import {
+  getSubtitleForSong,
+  makeArtistString,
+  makeErrorMessage,
+} from "../helpers.tsx";
 
 export default function SearchBar(
-  props: JSX.HTMLAttributes<HTMLInputElement> & { guessCount: Signal<number> },
+  props: JSX.HTMLAttributes<HTMLInputElement> & {
+    guessCount: Signal<number>;
+    inputValue: string;
+    setInputValue: (value: string) => void;
+  },
 ) {
-  const [inputValue, setInputValue] = useState("");
   const [selectedSong, setSelectedSong] = useState<Song | null>(null);
   const [suggestions, setSuggestions] = useState<Song[]>([]);
   const [allSongs, setAllSongs] = useState<Song[]>([]);
@@ -16,24 +23,27 @@ export default function SearchBar(
 
   useEffect(() => { // Fetch all songs when the component mounts
     async function fetchSongs() {
-      try {
-        const response = await fetch("/api/all-songs");
-        if (response.ok) {
-          const data: Song[] = await response.json();
-          setAllSongs(data);
-        } else {
-          console.error("Failed to fetch songs:", response.statusText);
-        }
-      } catch (error) {
-        console.error("Error fetching songs:", error);
+      const response = await fetch("/api/all-songs");
+      if (response.ok) {
+        const data: Song[] = await response.json();
+        setAllSongs(data);
+      } else {
+        throw new Error(makeErrorMessage(response));
       }
     }
-    fetchSongs().then(() => console.log("Songs fetched successfully"));
+    fetchSongs()
+      .then(() => {
+        console.debug("Songs fetched successfully.");
+      }).catch((error) => {
+        // This is the only place we alert the user that connection failed
+        alert("Unable to load song data. Please try again later.");
+        console.error(`Error while fetching songs: ${error}.`);
+      });
   }, []); // Empty dependency array means this runs once on mount
 
   useEffect(() => { // runs whenever inputValue or allSongs changes
-    const query = inputValue.toLowerCase();
-    if (inputValue.length > 0) {
+    const query = props.inputValue.toLowerCase();
+    if (props.inputValue.length > 0) {
       const filteredSuggestions = allSongs.filter((song) =>
         song.name.toLowerCase().includes(query) ||
         makeArtistString(song.artists).toLowerCase().includes(query) ||
@@ -45,31 +55,31 @@ export default function SearchBar(
       setSuggestions([]);
       setShowSuggestions(false);
     }
-  }, [inputValue, allSongs]);
+  }, [props.inputValue, allSongs]);
 
   useSignalEffect(() => { // Runs whenever guessCount Signal changes
     if (props.guessCount.value > 0) {
       // Reset the input and selected song when a guess is made
-      setInputValue("");
+      props.setInputValue("");
       setSelectedSong(null);
       setSuggestions([]);
       setShowSuggestions(false);
     }
   });
 
   function handleInputChange(event: JSX.TargetedEvent<HTMLInputElement>) {
-    setInputValue(event.currentTarget.value);
+    props.setInputValue(event.currentTarget.value);
     setSelectedSong(null);
   }
 
   function handleSuggestionClick(song: Song) {
-    setInputValue(song.name);
+    props.setInputValue(song.name);
     setSelectedSong(song);
     setShowSuggestions(false);
   }
 
   function handleFocus() {
-    if (inputValue.length > 0) {
+    if (props.inputValue.length > 0) {
       setShowSuggestions(true);
     }
   }
@@ -87,44 +97,43 @@ export default function SearchBar(
   }
 
   return (
-    <div class="relative">
+    <div class="relative text-sm w-full">
       {showSuggestions && suggestions.length > 0 && (
         <div
           ref={suggestionsRef}
-          class="bg-gray-100 border border-gray-300 rounded absolute z-10 mb-2 w-full max-h-40 bottom-full overflow-y-auto"
+          class="bg-gray-100 dark:bg-slate-500 border border-gray-300 dark:border-white rounded absolute z-10 mb-2 w-full max-h-40 bottom-full overflow-y-auto"
         >
           {suggestions.map((song) => (
             <div
               key={song}
               tabindex={0}
-              class="z-10 p-2 border border-gray-300 hover:bg-cyan-200"
+              class="z-10 p-2 border border-gray-300 dark:border-white hover:bg-cyan-200 hover:dark:bg-gray-600 text-black dark:text-white"
               onClick={() => handleSuggestionClick(song)}
               onKeyDown={(e) =>
                 e.key === "Enter" ? handleSuggestionClick(song) : undefined}
             >
-              <p>{song.name}</p>
+              <p class="font-semibold">{song.name}</p>
               <p>By {getSubtitleForSong(song)}</p>
             </div>
           ))}
         </div>
       )}
       <input
         {...props}
-        type="text"
+        type="search"
         tabindex={0}
-        class="border border-gray-300 rounded text-xl p-2"
-        value={inputValue}
+        class="w-full border border-gray-300 text-black rounded p-2"
+        value={props.inputValue}
         onInput={handleInputChange}
         onFocus={handleFocus}
         onBlur={handleBlur}
       />
-      <div class="text-xs text-right py-1 pe-1">
-        {(selectedSong && <p>By {getSubtitleForSong(selectedSong)}</p>) || (
-          <i>Type a valid guess above ⬆️</i>
-        )}
-      </div>
-      {/* todo: handle text overflow (rather than new line) for long song/artists names (e.g. Sweet Crazy Love Eng) */}
-      <span class="hidden" id="songId">
+      <p class="p-1 text-xs truncate text-right">
+        {selectedSong
+          ? <>By {getSubtitleForSong(selectedSong)}</>
+          : <i>Type a valid guess above ⬆️</i>}
+      </p>
+      <span hidden id="songId">
         {selectedSong ? selectedSong.id : ""}
       </span>
     </div>

heardle_server/components/SearchBar.tsx

@@ -4,3 +4,8 @@ export enum guessResult {
   SKIPPED = "skipped",
   CORRECT = "correct",
 }
+
+export interface PastGuess {
+  song?: Song;
+  result: guessResult;
+}

heardle_server/islands/islandProps.ts renamed to heardle_server/enums.ts

@@ -4,4 +4,7 @@ import tailwind from "$fresh/plugins/tailwind.ts";
 export default defineConfig({
   plugins: [tailwind()],
   server: { port: 9989 },
+  router: {
+    ignoreFilePattern: /^.*.d.ts$/
+  }
 });

heardle_server/fresh.config.ts

@@ -12,9 +12,9 @@ import * as $api_todays_song_check from "./routes/api/todays-song/check.ts";
 import * as $api_todays_song_preview_url from "./routes/api/todays-song/preview-url.ts";
 import * as $index from "./routes/index.tsx";
 import * as $guess_bar from "./islands/guess-bar.tsx";
-import * as $islandProps_d from "./islands/islandProps.d.ts";
-import * as $islandProps from "./islands/islandProps.ts";
 import * as $progress_block from "./islands/progress-block.tsx";
+import * as $root from "./islands/root.tsx";
+import * as $share_button from "./islands/share-button.tsx";
 import * as $song_bar from "./islands/song-bar.tsx";
 import type { Manifest } from "$fresh/server.ts";
 
@@ -32,9 +32,9 @@ const manifest = {
   },
   islands: {
     "./islands/guess-bar.tsx": $guess_bar,
-    "./islands/islandProps.d.ts": $islandProps_d,
-    "./islands/islandProps.ts": $islandProps,
     "./islands/progress-block.tsx": $progress_block,
+    "./islands/root.tsx": $root,
+    "./islands/share-button.tsx": $share_button,
     "./islands/song-bar.tsx": $song_bar,
   },
   baseUrl: import.meta.url,

heardle_server/fresh.gen.ts

@@ -1,5 +1,4 @@
-import { PastGuess } from "./islands/islandProps.d.ts";
-import { guessResult } from "./islands/islandProps.ts";
+import { guessResult, PastGuess } from "./enums.ts";
 
 export function makeArtistString(artists: { name: string }[]): string {
   return artists.map((artist) => artist.name).join(", ");
@@ -16,3 +15,31 @@ export function getSubtitleForSong(song: Song) {
 export function hasWon(history: PastGuess[]): boolean {
   return history.some((guess) => guess.result === guessResult.CORRECT);
 }
+
+export function makeErrorMessage(response: Response): string {
+  // Return the status and statusText, and the response body as text
+  return `status ${response.status} (${response.statusText})`;
+}
+
+export function checkStorageAvailable(
+  storageType: "localStorage" | "sessionStorage",
+): boolean | undefined {
+  // Check if the storage type is supported and available
+  // Adapted from https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API
+  let storage;
+  try {
+    storage = globalThis[storageType];
+    const x = "__storage_test__";
+    storage.setItem(x, x);
+    storage.removeItem(x);
+    return true;
+  } catch (e) {
+    return (
+      e instanceof DOMException &&
+      e.name === "QuotaExceededError" &&
+      // acknowledge QuotaExceededError only if there's something already stored
+      storage &&
+      storage.length !== 0
+    );
+  }
+}