From c7e7dd269b3d91e710d795f5fad2c6ae59d39d61 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Fri, 1 May 2026 20:18:05 -0400
Subject: [PATCH] feat(web): add ArtistCard (circular) with play-shuffle
 overlay

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 web/src/lib/components/ArtistCard.svelte  | 71 +++++++++++++++++++++++
 web/src/lib/components/ArtistCard.test.ts | 65 +++++++++++++++++++++
 2 files changed, 136 insertions(+)
 create mode 100644 web/src/lib/components/ArtistCard.svelte
 create mode 100644 web/src/lib/components/ArtistCard.test.ts

diff --git a/web/src/lib/components/ArtistCard.svelte b/web/src/lib/components/ArtistCard.svelte
new file mode 100644
index 00000000..68b32877
--- /dev/null
+++ b/web/src/lib/components/ArtistCard.svelte
@@ -0,0 +1,71 @@
+<script lang="ts">
+  import type { ArtistRef, TrackRef } from '$lib/api/types';
+  import { api } from '$lib/api/client';
+  import { playQueue } from '$lib/player/store.svelte';
+  import { Disc3, Play } from 'lucide-svelte';
+
+  let { artist }: { artist: ArtistRef } = $props();
+
+  function shuffle<T>(items: T[]): T[] {
+    const arr = items.slice();
+    for (let i = arr.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+  }
+
+  async function onPlayClick(e: MouseEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    const tracks = await api.get<TrackRef[]>(`/api/artists/${artist.id}/tracks`);
+    if (tracks.length === 0) return;
+    playQueue(shuffle(tracks), 0);
+  }
+</script>
+
+<div class="card relative">
+  <a
+    href={`/artists/${artist.id}`}
+    class="group block rounded focus-visible:ring-2 focus-visible:ring-accent"
+  >
+    <div class="art-wrap relative mx-auto aspect-square w-full overflow-hidden rounded-full bg-surface-hover">
+      {#if artist.cover_url}
+        <img
+          src={artist.cover_url}
+          alt=""
+          class="h-full w-full object-cover transition-transform group-hover:scale-[1.03]"
+          loading="lazy"
+        />
+      {:else}
+        <div class="flex h-full w-full items-center justify-center">
+          <Disc3 size={32} strokeWidth={1.5} class="text-text-muted" />
+        </div>
+      {/if}
+      <button
+        type="button"
+        aria-label={`Play ${artist.name}`}
+        onclick={onPlayClick}
+        class="play-overlay absolute inset-0 m-auto flex h-12 w-12 items-center justify-center rounded-full"
+      >
+        <Play size={24} strokeWidth={1.5} fill="currentColor" />
+      </button>
+    </div>
+    <div class="mt-2 truncate text-center text-sm font-medium text-text-primary">{artist.name}</div>
+  </a>
+</div>
+
+<style>
+  .play-overlay {
+    background: var(--fs-accent);
+    color: var(--fs-parchment);
+    opacity: 0;
+    transition: opacity 150ms ease;
+  }
+  @media (hover: hover) {
+    .card:hover .play-overlay { opacity: 1; }
+  }
+  @media (hover: none) {
+    .play-overlay { opacity: 1; }
+  }
+</style>
diff --git a/web/src/lib/components/ArtistCard.test.ts b/web/src/lib/components/ArtistCard.test.ts
new file mode 100644
index 00000000..f3109592
--- /dev/null
+++ b/web/src/lib/components/ArtistCard.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/svelte';
+import type { ArtistRef, TrackRef } from '$lib/api/types';
+
+vi.mock('$lib/api/client', () => ({
+  api: { get: vi.fn() }
+}));
+vi.mock('$lib/player/store.svelte', () => ({
+  playQueue: vi.fn()
+}));
+
+import ArtistCard from './ArtistCard.svelte';
+import { api } from '$lib/api/client';
+import { playQueue } from '$lib/player/store.svelte';
+
+const artist: ArtistRef = {
+  id: 'art-1',
+  name: 'Boards of Canada',
+  sort_name: 'Boards of Canada',
+  album_count: 5,
+  cover_url: '/api/albums/cov-1/cover'
+};
+
+afterEach(() => vi.clearAllMocks());
+
+describe('ArtistCard', () => {
+  test('renders cover img inside link to /artists/:id', () => {
+    const { container } = render(ArtistCard, { props: { artist } });
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('href', '/artists/art-1');
+    const img = container.querySelector('img') as HTMLImageElement;
+    expect(img.src).toContain('/api/albums/cov-1/cover');
+  });
+
+  test('falls back to Disc3 glyph when cover_url is empty', () => {
+    const { container } = render(ArtistCard, {
+      props: { artist: { ...artist, cover_url: '' } }
+    });
+    expect(container.querySelector('img')).not.toBeInTheDocument();
+    expect(container.querySelector('svg')).toBeInTheDocument();
+  });
+
+  test('play overlay fetches tracks, shuffles, calls playQueue', async () => {
+    const tracks: TrackRef[] = [
+      { id: 't1', title: 'A', album_id: 'al-1', album_title: 'X',
+        artist_id: 'art-1', artist_name: 'BoC',
+        track_number: 1, disc_number: 1, duration_sec: 1, stream_url: '/x' },
+      { id: 't2', title: 'B', album_id: 'al-1', album_title: 'X',
+        artist_id: 'art-1', artist_name: 'BoC',
+        track_number: 2, disc_number: 1, duration_sec: 1, stream_url: '/x' }
+    ];
+    (api.get as ReturnType<typeof vi.fn>).mockResolvedValueOnce(tracks);
+
+    render(ArtistCard, { props: { artist } });
+    await fireEvent.click(screen.getByRole('button', { name: /play boards of canada/i }));
+    expect(api.get).toHaveBeenCalledWith('/api/artists/art-1/tracks');
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(playQueue).toHaveBeenCalledOnce();
+    const [calledTracks, idx] = (playQueue as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(calledTracks).toHaveLength(2);
+    expect(idx).toBe(0);
+    expect(calledTracks.map((t: TrackRef) => t.id).sort()).toEqual(['t1', 't2']);
+  });
+});