liquid glass improvements

sozercan · sozercan · commit a5888ef74432 · 2025-12-26T20:16:25.000-08:00
Signed-off-by: Sertac Ozercan &lt;sozercan@gmail.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -175,12 +175,37 @@ HStack { /* controls */ }
 GlassEffectContainer(spacing: 0) {
     // Glass elements here
 }
+
+// Materialize transition for appearing panels
+QueueView()
+    .glassEffectTransition(.materialize)
+
+// Glass effect ID for morphing support
+.glassEffectID("queue", in: playerNamespace)
+
+// Glass search field
+TextField("Search...", text: $query)
+    .glassEffect(.regular, in: .capsule)
+```
+
+**Liquid Glass Anti-Patterns** (avoid these):
+- ❌ `.buttonStyle(.glass)` on buttons inside a glass container (causes rectangles)
+- ❌ `glassEffectUnion` on buttons already in a glass capsule (glass-on-glass)
+- ❌ Glass effects on content areas (lists, tables, media)
+- ❌ Custom opacity that bypasses accessibility
+
+**Implemented Glass Effects**:
+- `PlayerBar` — glass capsule with namespace for morphing
+- `Sidebar` — wrapped in `GlassEffectContainer`
+- `QueueView` / `LyricsView` — `.glassEffectTransition(.materialize)`
+- `SearchView` — glass search field and suggestions dropdown
 ```
 
 **PlayerBar Pattern**:
 - Each view that can be navigated to must include the `PlayerBar` via `safeAreaInset`
 - The `PlayerBar` floats at the bottom of the content area (not sidebar)
 - Uses `.glassEffect(.regular.interactive(), in: .capsule)` for the liquid glass look
+- Uses `@Namespace` for glass effect morphing support
 
 ```swift
 // Add to every navigable view
diff --git a/Views/macOS/LyricsView.swift b/Views/macOS/LyricsView.swift
@@ -33,6 +33,7 @@ struct LyricsView: View {
         }
         .frame(minWidth: 280, maxWidth: 280)
         .background(.background.opacity(0.95))
+        .glassEffectTransition(.materialize)
         .onChange(of: self.playerService.currentTrack?.videoId) { _, newVideoId in
             if let videoId = newVideoId, videoId != lastLoadedVideoId {
                 // Reset explanation when track changes
diff --git a/Views/macOS/MiniPlayerViews.swift b/Views/macOS/MiniPlayerViews.swift
@@ -65,3 +65,18 @@ struct PersistentPlayerView: NSViewRepresentable {
         SingletonPlayerWebView.shared.loadVideo(videoId: self.videoId)
     }
 }
+
+// MARK: - MiniPlayerToast
+
+/// A small toast-style view that appears when mini player is shown.
+/// Uses Liquid Glass materialize transition for smooth appearance.
+@available(macOS 26.0, *)
+struct MiniPlayerToast: View {
+    let videoId: String
+
+    var body: some View {
+        PersistentPlayerView(videoId: self.videoId, isExpanded: true)
+            .clipShape(RoundedRectangle(cornerRadius: 6))
+            .glassEffectTransition(.materialize)
+    }
+}
diff --git a/Views/macOS/PlayerBar.swift b/Views/macOS/PlayerBar.swift
@@ -9,6 +9,9 @@ struct PlayerBar: View {
     @Environment(PlayerService.self) private var playerService
     @Environment(WebKitManager.self) private var webKitManager
 
+    /// Namespace for glass effect morphing and unioning.
+    @Namespace private var playerNamespace
+
     @State private var isHovering = false
 
     /// Local seek value for smooth slider dragging without network calls on every change.
@@ -39,6 +42,7 @@ struct PlayerBar: View {
             .padding(.vertical, 8)
             .frame(height: 52)
             .glassEffect(.regular.interactive(), in: .capsule)
+            .glassEffectID("playerBar", in: self.playerNamespace)
         }
         .padding(.horizontal, 16)
         .padding(.bottom, 12)
@@ -255,6 +259,7 @@ struct PlayerBar: View {
                     .contentTransition(.symbolEffect(.replace))
             }
             .buttonStyle(.pressable)
+            .glassEffectID("playPause", in: self.playerNamespace)
             .accessibilityLabel(self.playerService.isPlaying ? "Pause" : "Play")
 
             // Next
@@ -417,6 +422,7 @@ struct PlayerBar: View {
                     .foregroundStyle(self.playerService.showLyrics ? .red : .primary.opacity(0.85))
             }
             .buttonStyle(.pressable)
+            .glassEffectID("lyrics", in: self.playerNamespace)
             .accessibilityIdentifier(AccessibilityID.PlayerBar.lyricsButton)
             .accessibilityLabel("Lyrics")
             .accessibilityValue(self.playerService.showLyrics ? "Showing" : "Hidden")
@@ -434,6 +440,7 @@ struct PlayerBar: View {
                     .foregroundStyle(self.playerService.showQueue ? .red : .primary.opacity(0.85))
             }
             .buttonStyle(.pressable)
+            .glassEffectID("queue", in: self.playerNamespace)
             .accessibilityIdentifier(AccessibilityID.PlayerBar.queueButton)
             .accessibilityLabel("Queue")
             .accessibilityValue(self.playerService.showQueue ? "Showing" : "Hidden")
diff --git a/Views/macOS/QueueView.swift b/Views/macOS/QueueView.swift
@@ -20,6 +20,7 @@ struct QueueView: View {
         }
         .frame(minWidth: 280, maxWidth: 280)
         .background(.background.opacity(0.95))
+        .glassEffectTransition(.materialize)
         .accessibilityIdentifier(AccessibilityID.Queue.container)
     }
 
diff --git a/Views/macOS/SearchView.swift b/Views/macOS/SearchView.swift
@@ -137,8 +137,7 @@ struct SearchView: View {
             }
         }
         .padding(10)
-        .background(.quaternary.opacity(0.5))
-        .clipShape(.rect(cornerRadius: 8))
+        .glassEffect(.regular, in: .capsule)
     }
 
     private var suggestionsDropdown: some View {
@@ -151,8 +150,8 @@ struct SearchView: View {
                 }
             }
         }
-        .background(.ultraThinMaterial)
-        .clipShape(.rect(cornerRadius: 8))
+        .glassEffect(.regular, in: .rect(cornerRadius: 8))
+        .glassEffectTransition(.materialize)
         .shadow(color: .black.opacity(0.15), radius: 8, x: 0, y: 4)
     }
 
diff --git a/Views/macOS/Sidebar.swift b/Views/macOS/Sidebar.swift
@@ -5,63 +5,68 @@ import SwiftUI
 struct Sidebar: View {
     @Binding var selection: NavigationItem?
 
+    /// Namespace for glass effect morphing.
+    @Namespace private var sidebarNamespace
+
     var body: some View {
-        List(selection: self.$selection) {
-            // Main navigation
-            Section {
-                NavigationLink(value: NavigationItem.search) {
-                    Label("Search", systemImage: "magnifyingglass")
-                }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.searchItem)
+        GlassEffectContainer(spacing: 0) {
+            List(selection: self.$selection) {
+                // Main navigation
+                Section {
+                    NavigationLink(value: NavigationItem.search) {
+                        Label("Search", systemImage: "magnifyingglass")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.searchItem)
 
-                NavigationLink(value: NavigationItem.home) {
-                    Label("Home", systemImage: "house")
+                    NavigationLink(value: NavigationItem.home) {
+                        Label("Home", systemImage: "house")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.homeItem)
                 }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.homeItem)
-            }
 
-            // Discover section
-            Section("Discover") {
-                NavigationLink(value: NavigationItem.explore) {
-                    Label("Explore", systemImage: "globe")
-                }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.exploreItem)
+                // Discover section
+                Section("Discover") {
+                    NavigationLink(value: NavigationItem.explore) {
+                        Label("Explore", systemImage: "globe")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.exploreItem)
 
-                NavigationLink(value: NavigationItem.charts) {
-                    Label("Charts", systemImage: "chart.line.uptrend.xyaxis")
-                }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.chartsItem)
+                    NavigationLink(value: NavigationItem.charts) {
+                        Label("Charts", systemImage: "chart.line.uptrend.xyaxis")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.chartsItem)
 
-                NavigationLink(value: NavigationItem.moodsAndGenres) {
-                    Label("Moods & Genres", systemImage: "theatermask.and.paintbrush")
-                }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.moodsAndGenresItem)
+                    NavigationLink(value: NavigationItem.moodsAndGenres) {
+                        Label("Moods & Genres", systemImage: "theatermask.and.paintbrush")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.moodsAndGenresItem)
 
-                NavigationLink(value: NavigationItem.newReleases) {
-                    Label("New Releases", systemImage: "sparkles")
+                    NavigationLink(value: NavigationItem.newReleases) {
+                        Label("New Releases", systemImage: "sparkles")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.newReleasesItem)
                 }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.newReleasesItem)
-            }
 
-            // Library section
-            Section("Library") {
-                NavigationLink(value: NavigationItem.likedMusic) {
-                    Label("Liked Music", systemImage: "heart.fill")
-                }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.likedMusicItem)
+                // Library section
+                Section("Library") {
+                    NavigationLink(value: NavigationItem.likedMusic) {
+                        Label("Liked Music", systemImage: "heart.fill")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.likedMusicItem)
 
-                NavigationLink(value: NavigationItem.library) {
-                    Label("Playlists", systemImage: "music.note.list")
+                    NavigationLink(value: NavigationItem.library) {
+                        Label("Playlists", systemImage: "music.note.list")
+                    }
+                    .accessibilityIdentifier(AccessibilityID.Sidebar.libraryItem)
                 }
-                .accessibilityIdentifier(AccessibilityID.Sidebar.libraryItem)
             }
-        }
-        .listStyle(.sidebar)
-        .navigationSplitViewColumnWidth(min: 200, ideal: 220, max: 300)
-        .accessibilityIdentifier(AccessibilityID.Sidebar.container)
-        .onChange(of: self.selection) { _, newValue in
-            if newValue != nil {
-                HapticService.navigation()
+            .listStyle(.sidebar)
+            .navigationSplitViewColumnWidth(min: 200, ideal: 220, max: 300)
+            .accessibilityIdentifier(AccessibilityID.Sidebar.container)
+            .onChange(of: self.selection) { _, newValue in
+                if newValue != nil {
+                    HapticService.navigation()
+                }
             }
         }
     }
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -416,6 +416,24 @@ DiagnosticsLogger.auth.error("Cookie extraction failed")
 
 The app uses Apple's **Liquid Glass** design language introduced in macOS 26.
 
+### Glass Effect Patterns
+
+| Component | Glass Pattern |
+|-----------|---------------|
+| `PlayerBar` | `.glassEffect(.regular.interactive(), in: .capsule)` |
+| `Sidebar` | Wrapped in `GlassEffectContainer` |
+| `QueueView` / `LyricsView` | `.glassEffectTransition(.materialize)` |
+| Search field | `.glassEffect(.regular, in: .capsule)` |
+| Search suggestions | `.glassEffect(.regular, in: .rect(cornerRadius: 8))` |
+
+### Glass Effect Best Practices
+
+1. **Use `GlassEffectContainer`** to wrap multiple glass elements
+2. **Use `.glassEffectTransition(.materialize)`** for panels that appear/disappear
+3. **Use `@Namespace` + `.glassEffectID()`** for morphing between states
+4. **Avoid glass-on-glass** — don't apply `.buttonStyle(.glass)` to buttons already inside a glass container
+5. **Reserve glass for navigation/floating controls** — not for content areas
+
 ## Foundation Models (Apple Intelligence)
 
 Kaset integrates Apple's on-device Foundation Models framework for AI-powered features. See [ADR-0005: Foundation Models Architecture](adr/0005-foundation-models-architecture.md) for detailed design decisions.

Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,7 @@ struct LyricsView: View {`
`33`	`33`	`}`
`34`	`34`	`.frame(minWidth: 280, maxWidth: 280)`
`35`	`35`	`.background(.background.opacity(0.95))`
	`36`	`+ .glassEffectTransition(.materialize)`
`36`	`37`	`.onChange(of: self.playerService.currentTrack?.videoId) { _, newVideoId in`
`37`	`38`	`if let videoId = newVideoId, videoId != lastLoadedVideoId {`
`38`	`39`	`// Reset explanation when track changes`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@ struct QueueView: View {`
`20`	`20`	`}`
`21`	`21`	`.frame(minWidth: 280, maxWidth: 280)`
`22`	`22`	`.background(.background.opacity(0.95))`
	`23`	`+ .glassEffectTransition(.materialize)`
`23`	`24`	`.accessibilityIdentifier(AccessibilityID.Queue.container)`
`24`	`25`	`}`
`25`	`26`
Original file line number	Diff line number	Diff line change
`@@ -137,8 +137,7 @@ struct SearchView: View {`
`137`	`137`	`}`
`138`	`138`	`}`
`139`	`139`	`.padding(10)`
`140`		`- .background(.quaternary.opacity(0.5))`
`141`		`- .clipShape(.rect(cornerRadius: 8))`
	`140`	`+ .glassEffect(.regular, in: .capsule)`
`142`	`141`	`}`
`143`	`142`
`144`	`143`	`private var suggestionsDropdown: some View {`
`@@ -151,8 +150,8 @@ struct SearchView: View {`
`151`	`150`	`}`
`152`	`151`	`}`
`153`	`152`	`}`
`154`		`- .background(.ultraThinMaterial)`
`155`		`- .clipShape(.rect(cornerRadius: 8))`
	`153`	`+ .glassEffect(.regular, in: .rect(cornerRadius: 8))`
	`154`	`+ .glassEffectTransition(.materialize)`
`156`	`155`	`.shadow(color: .black.opacity(0.15), radius: 8, x: 0, y: 4)`
`157`	`156`	`}`
`158`	`157`