From 600986e1ea6797bf2a47cc5de22d7a79f15a1b75 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 15 Feb 2026 14:31:36 -0600
Subject: feat(music): add playlist UI with header overlay, track styling, and
 tests

Replace raw file paths with clean track descriptions (Artist - Title [M:SS]),
add multi-line header overlay showing playlist info, now-playing, mode
indicators with gold/muted toggle states, and keybinding hints. Style
non-playing tracks in Dupre steel, playing track in Dupre gold. Playlist
window now opens from the bottom at 50% height with subtle background
highlight on focus.

Unit tests for format-duration (13 tests) and track-description (16 tests).
---
 tests/test-music-config--format-duration.el   |  91 +++++++++++++
 tests/test-music-config--track-description.el | 181 ++++++++++++++++++++++++++
 2 files changed, 272 insertions(+)
 create mode 100644 tests/test-music-config--format-duration.el
 create mode 100644 tests/test-music-config--track-description.el

(limited to 'tests')

diff --git a/tests/test-music-config--format-duration.el b/tests/test-music-config--format-duration.el
new file mode 100644
index 00000000..7b107049
--- /dev/null
+++ b/tests/test-music-config--format-duration.el
@@ -0,0 +1,91 @@
+;;; test-music-config--format-duration.el --- Tests for duration formatting -*- coding: utf-8; lexical-binding: t; -*-
+;;
+;; Author: Craig Jennings <c@cjennings.net>
+;;
+;;; Commentary:
+;; Unit tests for cj/music--format-duration function.
+;; Tests the pure helper that converts seconds to "M:SS" display strings.
+;;
+;; Test organization:
+;; - Normal Cases: Typical durations, exact minutes, seconds only
+;; - Boundary Cases: Zero, one second, large values, float input
+;; - Error Cases: Nil, negative, non-numeric input
+;;
+;;; Code:
+
+(require 'ert)
+
+;; Stub missing dependencies before loading music-config
+(defvar-keymap cj/custom-keymap
+  :doc "Stub keymap for testing")
+
+;; Add EMMS elpa directory to load path for batch testing
+(let ((emms-dir (car (file-expand-wildcards
+                      (expand-file-name "elpa/emms-*" user-emacs-directory)))))
+  (when emms-dir
+    (add-to-list 'load-path emms-dir)))
+
+(require 'emms)
+(require 'emms-playlist-mode)
+(require 'music-config)
+
+;;; Normal Cases
+
+(ert-deftest test-music-config--format-duration-normal-typical-song ()
+  "Validate typical 3:45 song duration."
+  (should (string= (cj/music--format-duration 225) "3:45")))
+
+(ert-deftest test-music-config--format-duration-normal-exact-minutes ()
+  "Validate exact minute boundary produces M:00."
+  (should (string= (cj/music--format-duration 180) "3:00")))
+
+(ert-deftest test-music-config--format-duration-normal-seconds-only ()
+  "Validate sub-minute duration produces 0:SS."
+  (should (string= (cj/music--format-duration 45) "0:45")))
+
+(ert-deftest test-music-config--format-duration-normal-single-digit-seconds ()
+  "Validate seconds are zero-padded to two digits."
+  (should (string= (cj/music--format-duration 62) "1:02")))
+
+(ert-deftest test-music-config--format-duration-normal-long-track ()
+  "Validate duration over 10 minutes."
+  (should (string= (cj/music--format-duration 622) "10:22")))
+
+;;; Boundary Cases
+
+(ert-deftest test-music-config--format-duration-boundary-one-second ()
+  "Validate minimum positive duration."
+  (should (string= (cj/music--format-duration 1) "0:01")))
+
+(ert-deftest test-music-config--format-duration-boundary-zero-returns-nil ()
+  "Validate zero seconds returns nil (no useful duration)."
+  (should (null (cj/music--format-duration 0))))
+
+(ert-deftest test-music-config--format-duration-boundary-very-large ()
+  "Validate very long duration (over an hour) formats correctly."
+  (should (string= (cj/music--format-duration 3661) "61:01")))
+
+(ert-deftest test-music-config--format-duration-boundary-float-input ()
+  "Validate float seconds are truncated by integer division."
+  (should (string= (cj/music--format-duration 125.7) "2:05")))
+
+(ert-deftest test-music-config--format-duration-boundary-59-seconds ()
+  "Validate max seconds before minute rollover."
+  (should (string= (cj/music--format-duration 59) "0:59")))
+
+;;; Error Cases
+
+(ert-deftest test-music-config--format-duration-error-nil-returns-nil ()
+  "Validate nil input returns nil."
+  (should (null (cj/music--format-duration nil))))
+
+(ert-deftest test-music-config--format-duration-error-negative-returns-nil ()
+  "Validate negative input returns nil."
+  (should (null (cj/music--format-duration -5))))
+
+(ert-deftest test-music-config--format-duration-error-string-returns-nil ()
+  "Validate non-numeric input returns nil."
+  (should (null (cj/music--format-duration "3:45"))))
+
+(provide 'test-music-config--format-duration)
+;;; test-music-config--format-duration.el ends here
diff --git a/tests/test-music-config--track-description.el b/tests/test-music-config--track-description.el
new file mode 100644
index 00000000..a1a1cc6d
--- /dev/null
+++ b/tests/test-music-config--track-description.el
@@ -0,0 +1,181 @@
+;;; test-music-config--track-description.el --- Tests for track description -*- coding: utf-8; lexical-binding: t; -*-
+;;
+;; Author: Craig Jennings <c@cjennings.net>
+;;
+;;; Commentary:
+;; Unit tests for cj/music--track-description function.
+;; Tests the custom track description that replaces EMMS's default file-path display
+;; with human-readable formats based on track type and available metadata.
+;;
+;; Track construction: EMMS tracks are alists created with `emms-track' and
+;; populated with `emms-track-set'. No playlist buffer or player state needed.
+;;
+;; Test organization:
+;; - Normal Cases: Tagged tracks (artist+title+duration), partial metadata, file fallback, URL
+;; - Boundary Cases: Empty strings, missing fields, special characters, long names
+;; - Error Cases: Unknown track type fallback
+;;
+;;; Code:
+
+(require 'ert)
+
+;; Stub missing dependencies before loading music-config
+(defvar-keymap cj/custom-keymap
+  :doc "Stub keymap for testing")
+
+;; Add EMMS elpa directory to load path for batch testing
+(let ((emms-dir (car (file-expand-wildcards
+                      (expand-file-name "elpa/emms-*" user-emacs-directory)))))
+  (when emms-dir
+    (add-to-list 'load-path emms-dir)))
+
+(require 'emms)
+(require 'emms-playlist-mode)
+(require 'music-config)
+
+;;; Test helpers
+
+(defun test-track-description--make-file-track (path &optional title artist duration)
+  "Create a file TRACK with PATH and optional metadata TITLE, ARTIST, DURATION."
+  (let ((track (emms-track 'file path)))
+    (when title (emms-track-set track 'info-title title))
+    (when artist (emms-track-set track 'info-artist artist))
+    (when duration (emms-track-set track 'info-playing-time duration))
+    track))
+
+(defun test-track-description--make-url-track (url &optional title artist duration)
+  "Create a URL TRACK with URL and optional metadata TITLE, ARTIST, DURATION."
+  (let ((track (emms-track 'url url)))
+    (when title (emms-track-set track 'info-title title))
+    (when artist (emms-track-set track 'info-artist artist))
+    (when duration (emms-track-set track 'info-playing-time duration))
+    track))
+
+;;; Normal Cases — Tagged tracks (artist + title + duration)
+
+(ert-deftest test-music-config--track-description-normal-full-metadata ()
+  "Validate track with artist, title, and duration shows all three."
+  (let ((track (test-track-description--make-file-track
+                "/music/Kind of Blue/01 - So What.flac"
+                "So What" "Miles Davis" 562)))
+    (should (string= (cj/music--track-description track)
+                     "Miles Davis - So What  [9:22]"))))
+
+(ert-deftest test-music-config--track-description-normal-title-and-artist-no-duration ()
+  "Validate track with artist and title but no duration omits bracket."
+  (let ((track (test-track-description--make-file-track
+                "/test/uncached-nodur.mp3" "Blue in Green" "Miles Davis")))
+    (should (string= (cj/music--track-description track)
+                     "Miles Davis - Blue in Green"))))
+
+(ert-deftest test-music-config--track-description-normal-title-only ()
+  "Validate track with title but no artist shows title alone."
+  (let ((track (test-track-description--make-file-track
+                "/test/uncached-noartist.mp3" "Flamenco Sketches" nil 566)))
+    (should (string= (cj/music--track-description track)
+                     "Flamenco Sketches  [9:26]"))))
+
+(ert-deftest test-music-config--track-description-normal-title-only-no-duration ()
+  "Validate track with only title shows just the title."
+  (let ((track (test-track-description--make-file-track
+                "/test/uncached-titleonly.mp3" "All Blues")))
+    (should (string= (cj/music--track-description track)
+                     "All Blues"))))
+
+;;; Normal Cases — File tracks without tags
+
+(ert-deftest test-music-config--track-description-normal-file-no-tags ()
+  "Validate untagged file shows filename without path or extension."
+  (let ((track (test-track-description--make-file-track
+                "/music/Kind of Blue/02 - Freddie Freeloader.flac")))
+    (should (string= (cj/music--track-description track)
+                     "02 - Freddie Freeloader"))))
+
+(ert-deftest test-music-config--track-description-normal-file-nested-path ()
+  "Validate deeply nested path still shows only the filename."
+  (let ((track (test-track-description--make-file-track
+                "/music/Jazz/Miles Davis/Kind of Blue/01 - So What.mp3")))
+    (should (string= (cj/music--track-description track)
+                     "01 - So What"))))
+
+;;; Normal Cases — URL tracks
+
+(ert-deftest test-music-config--track-description-normal-url-plain ()
+  "Validate plain URL is shown as-is."
+  (let ((track (test-track-description--make-url-track
+                "https://radio.example.com/stream")))
+    (should (string= (cj/music--track-description track)
+                     "https://radio.example.com/stream"))))
+
+(ert-deftest test-music-config--track-description-normal-url-percent-encoded ()
+  "Validate percent-encoded URL characters are decoded."
+  (let ((track (test-track-description--make-url-track
+                "https://radio.example.com/my%20station%21")))
+    (should (string= (cj/music--track-description track)
+                     "https://radio.example.com/my station!"))))
+
+(ert-deftest test-music-config--track-description-normal-url-with-tags ()
+  "Validate URL track with tags uses tag display, not URL."
+  (let ((track (test-track-description--make-url-track
+                "https://radio.example.com/stream"
+                "Jazz FM" "Radio Station" 0)))
+    ;; Duration 0 → nil from format-duration, so no bracket
+    (should (string= (cj/music--track-description track)
+                     "Radio Station - Jazz FM"))))
+
+;;; Boundary Cases
+
+(ert-deftest test-music-config--track-description-boundary-empty-title-string ()
+  "Validate empty title string is still truthy, shows empty result."
+  (let ((track (test-track-description--make-file-track
+                "/music/track.mp3" "" "Artist")))
+    ;; Empty string is non-nil, so title branch is taken
+    (should (string= (cj/music--track-description track)
+                     "Artist - "))))
+
+(ert-deftest test-music-config--track-description-boundary-file-no-extension ()
+  "Validate file without extension shows full filename."
+  (let ((track (test-track-description--make-file-track "/music/README")))
+    (should (string= (cj/music--track-description track)
+                     "README"))))
+
+(ert-deftest test-music-config--track-description-boundary-file-multiple-dots ()
+  "Validate file with multiple dots strips only the final extension."
+  (let ((track (test-track-description--make-file-track
+                "/music/disc.1.track.03.flac")))
+    (should (string= (cj/music--track-description track)
+                     "disc.1.track.03"))))
+
+(ert-deftest test-music-config--track-description-boundary-unicode-title ()
+  "Validate unicode characters in metadata are preserved."
+  (let ((track (test-track-description--make-file-track
+                "/music/track.mp3" "夜に駆ける" "YOASOBI" 258)))
+    (should (string= (cj/music--track-description track)
+                     "YOASOBI - 夜に駆ける  [4:18]"))))
+
+(ert-deftest test-music-config--track-description-boundary-url-utf8-percent-encoded ()
+  "Validate percent-encoded UTF-8 in URL is decoded correctly."
+  (let ((track (test-track-description--make-url-track
+                "https://example.com/caf%C3%A9")))
+    (should (string= (cj/music--track-description track)
+                     "https://example.com/café"))))
+
+(ert-deftest test-music-config--track-description-boundary-short-duration ()
+  "Validate 1-second track formats correctly in bracket."
+  (let ((track (test-track-description--make-file-track
+                "/music/t.mp3" "Beep" nil 1)))
+    (should (string= (cj/music--track-description track)
+                     "Beep  [0:01]"))))
+
+;;; Error Cases
+
+(ert-deftest test-music-config--track-description-error-unknown-type-fallback ()
+  "Validate unknown track type uses emms-track-simple-description fallback."
+  (let ((track (emms-track 'streamlist "https://example.com/playlist.m3u")))
+    ;; Should not error; falls through to simple-description
+    (let ((result (cj/music--track-description track)))
+      (should (stringp result))
+      (should (string-match-p "example\\.com" result)))))
+
+(provide 'test-music-config--track-description)
+;;; test-music-config--track-description.el ends here
-- 
cgit v1.2.3