[ 1.0.24 ] * Added new userpreset type filtersection, which can be used to quickly display a section with the specified filter criteria applied. More info can be found on the [wiki docs](https://github.com/thlucas1/spotifyplus_card/wiki/Configuration-Options#userpresets-filter-section-media).

thlucas1 · thlucas1 · commit 188fb7e7c0db · 2024-12-22T13:16:08.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,11 +6,15 @@ Change are listed in reverse chronological order (newest to oldest).
 
 <span class="changelog">
 
+###### [ 1.0.24 ] - 2024/12/22
+
+  * Added new userpreset type `filtersection`, which can be used to quickly display a section with the specified filter criteria applied.  More info can be found on the [wiki docs](https://github.com/thlucas1/spotifyplus_card/wiki/Configuration-Options#userpresets-filter-section-media).
+
 ###### [ 1.0.23 ] - 2024/12/20
 
   * This release requires the SpotifyPlus Integration v1.0.73+ release; please make sure you update the SpotifyPlus integration prior to updating this SpotifyPlus Card release.
   * Fixed hidden volume controls, which was caused by a bug introduced with v1.0.20.
-  * Added the ability to disable image caching for userpreset images.  More info can be found on the [wiki docs](https://github.com/thlucas1/spotifyplus_card/wiki/Configuration-Options#userpresets-image-url-caching.)
+  * Added the ability to disable image caching for userpreset images.  More info can be found on the [wiki docs](https://github.com/thlucas1/spotifyplus_card/wiki/Configuration-Options#userpresets-image-url-caching).
 
 ###### [ 1.0.22 ] - 2024/12/18
 
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 - 2024  Todd Lucas @thlucas1
+Copyright (c) 2019 - 2025  Todd Lucas @thlucas1
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/SpotifyPlusCard.njsproj b/SpotifyPlusCard.njsproj
@@ -144,6 +144,9 @@
     <TypeScriptCompile Include="src\events\category-display.ts">
       <SubType>Code</SubType>
     </TypeScriptCompile>
+    <TypeScriptCompile Include="src\events\filter-section-media.ts">
+      <SubType>Code</SubType>
+    </TypeScriptCompile>
     <TypeScriptCompile Include="src\events\search-media.ts" />
     <TypeScriptCompile Include="src\sections\category-browser.ts" />
     <TypeScriptCompile Include="src\sections\episode-fav-browser.ts" />
diff --git a/src/card.ts b/src/card.ts
@@ -25,6 +25,7 @@ import './editor/editor';
 
 // our imports.
 import { SEARCH_MEDIA, SearchMediaEventArgs } from './events/search-media';
+import { FILTER_SECTION_MEDIA, FilterSectionMediaEventArgs } from './events/filter-section-media';
 import { CATEGORY_DISPLAY, CategoryDisplayEventArgs } from './events/category-display';
 import { EDITOR_CONFIG_AREA_SELECTED, EditorConfigAreaSelectedEventArgs } from './events/editor-config-area-selected';
 import { PROGRESS_STARTED } from './events/progress-started';
@@ -36,7 +37,18 @@ import { CardConfig } from './types/card-config';
 import { CustomImageUrls } from './types/custom-image-urls';
 import { SearchMediaTypes } from './types/search-media-types';
 import { SearchBrowser } from './sections/search-media-browser';
+import { FavBrowserBase } from './sections/fav-browser-base';
+import { AlbumFavBrowser } from './sections/album-fav-browser';
+import { ArtistFavBrowser } from './sections/artist-fav-browser';
+import { AudiobookFavBrowser } from './sections/audiobook-fav-browser';
 import { CategoryBrowser } from './sections/category-browser';
+import { DeviceBrowser } from './sections/device-browser';
+import { EpisodeFavBrowser } from './sections/episode-fav-browser';
+import { PlaylistFavBrowser } from './sections/playlist-fav-browser';
+import { RecentBrowser } from './sections/recent-browser';
+import { ShowFavBrowser } from './sections/show-fav-browser';
+import { TrackFavBrowser } from './sections/track-fav-browser';
+import { UserPresetBrowser } from './sections/userpreset-browser';
 import { formatTitleInfo, removeSpecialChars } from './utils/media-browser-utils';
 import { BRAND_LOGO_IMAGE_BASE64, BRAND_LOGO_IMAGE_SIZE, FOOTER_ICON_SIZE_DEFAULT } from './constants';
 import {
@@ -98,8 +110,19 @@ export class Card extends LitElement {
   @state() private cancelLoader!: boolean;
   @state() private playerId!: string;
 
+  // card section references.
   @query("#elmSearchMediaBrowserForm", false) private elmSearchMediaBrowserForm!: SearchBrowser;
   @query("#elmCategoryBrowserForm", false) private elmCategoryBrowserForm!: CategoryBrowser;
+  @query("#elmAlbumFavBrowserForm", false) private elmAlbumFavBrowserForm!: AlbumFavBrowser;
+  @query("#elmArtistFavBrowserForm", false) private elmArtistFavBrowserForm!: ArtistFavBrowser;
+  @query("#elmAudiobookFavBrowserForm", false) private elmAudiobookFavBrowserForm!: AudiobookFavBrowser;
+  @query("#elmDeviceBrowserForm", false) private elmDeviceBrowserForm!: DeviceBrowser;
+  @query("#elmEpisodeFavBrowserForm", false) private elmEpisodeFavBrowserForm!: EpisodeFavBrowser;
+  @query("#elmPlaylistFavBrowserForm", false) private elmPlaylistFavBrowserForm!: PlaylistFavBrowser;
+  @query("#elmRecentBrowserForm", false) private elmRecentBrowserForm!: RecentBrowser;
+  @query("#elmShowFavBrowserForm", false) private elmShowFavBrowserForm!: ShowFavBrowser;
+  @query("#elmTrackFavBrowserForm", false) private elmTrackFavBrowserForm!: TrackFavBrowser;
+  @query("#elmUserPresetBrowserForm", false) private elmUserPresetBrowserForm!: UserPresetBrowser;
 
   /** Indicates if createStore method is executing for the first time (true) or not (false). */
   private isFirstTimeSetup: boolean = true;
@@ -168,19 +191,19 @@ export class Card extends LitElement {
           ${
               this.playerId
               ? choose(this.section, [
-                [Section.ALBUM_FAVORITES, () => html`<spc-album-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-album-fav-browser>`],
-                [Section.ARTIST_FAVORITES, () => html`<spc-artist-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-artist-fav-browser>`],
-                [Section.AUDIOBOOK_FAVORITES, () => html`<spc-audiobook-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-audiobook-fav-browser>`],
+                [Section.ALBUM_FAVORITES, () => html`<spc-album-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmAlbumFavBrowserForm"></spc-album-fav-browser>`],
+                [Section.ARTIST_FAVORITES, () => html`<spc-artist-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmArtistFavBrowserForm"></spc-artist-fav-browser>`],
+                [Section.AUDIOBOOK_FAVORITES, () => html`<spc-audiobook-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmAudiobookFavBrowserForm"></spc-audiobook-fav-browser>`],
                 [Section.CATEGORYS, () => html`<spc-category-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmCategoryBrowserForm"></spc-category-browser>`],
-                [Section.DEVICES, () => html`<spc-device-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-device-browser>`],
-                [Section.EPISODE_FAVORITES, () => html`<spc-episode-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-episode-fav-browser>`],
+                [Section.DEVICES, () => html`<spc-device-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmDeviceBrowserForm"></spc-device-browser>`],
+                [Section.EPISODE_FAVORITES, () => html`<spc-episode-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmEpisodeFavBrowserForm"></spc-episode-fav-browser>`],
                 [Section.PLAYER, () => html`<spc-player id="spcPlayer" .store=${this.store}></spc-player>`],
-                [Section.PLAYLIST_FAVORITES, () => html`<spc-playlist-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-playlist-fav-browser>`],
-                [Section.RECENTS, () => html`<spc-recent-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-recents-browser>`],
+                [Section.PLAYLIST_FAVORITES, () => html`<spc-playlist-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmPlaylistFavBrowserForm"></spc-playlist-fav-browser>`],
+                [Section.RECENTS, () => html`<spc-recent-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmRecentBrowserForm"></spc-recents-browser>`],
                 [Section.SEARCH_MEDIA, () => html`<spc-search-media-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmSearchMediaBrowserForm"></spc-search-media-browser>`],
-                [Section.SHOW_FAVORITES, () => html`<spc-show-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-show-fav-browser>`],
-                [Section.TRACK_FAVORITES, () => html`<spc-track-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-track-fav-browser>`],
-                [Section.USERPRESETS, () => html`<spc-userpreset-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected}></spc-userpresets-browser>`],
+                [Section.SHOW_FAVORITES, () => html`<spc-show-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmShowFavBrowserForm"></spc-show-fav-browser>`],
+                [Section.TRACK_FAVORITES, () => html`<spc-track-fav-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmTrackFavBrowserForm"></spc-track-fav-browser>`],
+                [Section.USERPRESETS, () => html`<spc-userpreset-browser .store=${this.store} @item-selected=${this.onMediaListItemSelected} id="elmUserPresetBrowserForm"></spc-userpresets-browser>`],
                 [Section.UNDEFINED, () => html`<div class="spc-not-configured">SpotifyPlus card configuration error.<br/>Please configure section(s) to display.</div>`],
               ])
               : html`<div class="spc-initial-config">Welcome to the SpotifyPlus media player card.<br/>Start by configuring a media player entity.</div>`
@@ -418,6 +441,7 @@ export class Card extends LitElement {
     this.addEventListener(PROGRESS_STARTED, this.onProgressStartedEventHandler);
     this.addEventListener(SEARCH_MEDIA, this.onSearchMediaEventHandler);
     this.addEventListener(CATEGORY_DISPLAY, this.onCategoryDisplayEventHandler);
+    this.addEventListener(FILTER_SECTION_MEDIA, this.onFilterSectionMediaEventHandler);
 
     // only add the following events if card configuration is being edited.
     if (isCardInEditPreview(this)) {
@@ -447,6 +471,7 @@ export class Card extends LitElement {
     this.removeEventListener(PROGRESS_STARTED, this.onProgressStartedEventHandler);
     this.removeEventListener(SEARCH_MEDIA, this.onSearchMediaEventHandler);
     this.removeEventListener(CATEGORY_DISPLAY, this.onCategoryDisplayEventHandler);
+    this.removeEventListener(FILTER_SECTION_MEDIA, this.onFilterSectionMediaEventHandler);
 
     // the following event is only added when the card configuration editor is created.
     // always remove the following events, as isCardInEditPreview() can sometimes
@@ -658,6 +683,86 @@ export class Card extends LitElement {
   }
 
 
+  /**
+   * Handles the `FILTER_SECTION_MEDIA` event.
+   * This will show the specified section, and apply the specified filter criteria 
+   * passed in the event arguments.
+   * 
+   * @param ev Event definition and arguments.
+  */
+  protected onFilterSectionMediaEventHandler = (ev: Event) => {
+
+    // map event arguments.
+    const evArgs = (ev as CustomEvent).detail as FilterSectionMediaEventArgs;
+
+    // validate section id.
+    const enumValues: string[] = Object.values(Section);
+    if (!enumValues.includes(evArgs.section || "")) {
+      debuglog("%onFilterSectionMediaEventHandler - Ignoring Filter request; section is not a valid Section enum value:\n%s",
+        "color:red",
+        JSON.stringify(evArgs, null, 2),
+      );
+    }
+
+    // is section activated?  if so, then select it.
+    if (this.config.sections?.includes(evArgs.section as Section)) {
+
+      // show the search section.
+      this.section = evArgs.section as Section;
+      this.store.section = this.section;
+
+      // wait just a bit before executing the search.
+      setTimeout(() => {
+
+        if (debuglog.enabled) {
+          debuglog("onFilterSectionMediaEventHandler - executing filter:\n%s",
+            JSON.stringify(evArgs, null, 2),
+          );
+        }
+
+        // reference the section browser.
+        let browserBase: FavBrowserBase;
+        if (evArgs.section == Section.ALBUM_FAVORITES) {
+          browserBase = this.elmAlbumFavBrowserForm;
+        } else if (evArgs.section == Section.ARTIST_FAVORITES) {
+          browserBase = this.elmArtistFavBrowserForm;
+        } else if (evArgs.section == Section.AUDIOBOOK_FAVORITES) {
+          browserBase = this.elmAudiobookFavBrowserForm;
+        } else if (evArgs.section == Section.DEVICES) {
+          browserBase = this.elmDeviceBrowserForm;
+        } else if (evArgs.section == Section.EPISODE_FAVORITES) {
+          browserBase = this.elmEpisodeFavBrowserForm;
+        } else if (evArgs.section == Section.PLAYLIST_FAVORITES) {
+          browserBase = this.elmPlaylistFavBrowserForm;
+        } else if (evArgs.section == Section.RECENTS) {
+          browserBase = this.elmRecentBrowserForm;
+        } else if (evArgs.section == Section.SHOW_FAVORITES) {
+          browserBase = this.elmShowFavBrowserForm;
+        } else if (evArgs.section == Section.TRACK_FAVORITES) {
+          browserBase = this.elmTrackFavBrowserForm;
+        } else if (evArgs.section == Section.USERPRESETS) {
+          browserBase = this.elmUserPresetBrowserForm;
+        } else {
+          return;
+        }
+
+        // execute the filter.
+        browserBase.filterSectionMedia(evArgs);
+        //super.requestUpdate();
+
+      }, 50);
+
+    } else {
+
+      // section is not activated; cannot search.
+      debuglog("%onFilterSectionMediaEventHandler - Filter section is not enabled; ignoring filter request:\n%s",
+        "color:red",
+        JSON.stringify(evArgs, null, 2),
+      );
+    }
+  }
+
+
   /**
    * Handles the `SEARCH_MEDIA` event.
    * This will execute a search on the specified criteria passed in the event arguments.
diff --git a/src/constants.ts b/src/constants.ts
@@ -1,7 +1,7 @@
 import { css } from 'lit';
 
 /** current version of the card. */
-export const CARD_VERSION = '1.0.23';
+export const CARD_VERSION = '1.0.24';
 
 /** SpotifyPlus integration domain identifier. */
 export const DOMAIN_SPOTIFYPLUS = 'spotifyplus';
diff --git a/src/events/filter-section-media.ts b/src/events/filter-section-media.ts
@@ -0,0 +1,60 @@
+import { DOMAIN_SPOTIFYPLUS } from '../constants';
+
+/** 
+ * Uniquely identifies the event. 
+ * */
+export const FILTER_SECTION_MEDIA = DOMAIN_SPOTIFYPLUS + '-card-filter-section-media';
+
+
+/**
+ * Event arguments.
+ */
+export class FilterSectionMediaEventArgs {
+
+  /**
+   * Section type to filter.
+   */
+  public section: string;
+
+  /**
+   * Filter criteria.
+   */
+  public filterCriteria: string;
+
+
+  /**
+   * Initializes a new instance of the class.
+   * 
+   * @param section Section to be filtered.
+   * @param filterCriteria Filter criteria that will be applied to the specified filter section.
+   */
+  constructor(
+    section: string | undefined | null,
+    filterCriteria: string | undefined | null = null,
+  ) {
+    this.section = section || "";
+    this.filterCriteria = filterCriteria || "";
+  }
+}
+
+
+/**
+ * Event constructor.
+ * 
+ * @param section Section to be filtered.
+ * @param filterCriteria Filter criteria that will be applied to the specified filter section.
+ */
+export function FilterSectionMediaEvent(
+  section: string | undefined | null,
+  filterCriteria: string | undefined | null,
+) {
+
+  const args = new FilterSectionMediaEventArgs(section);
+  args.filterCriteria = (filterCriteria || "").trim();
+
+  return new CustomEvent(FILTER_SECTION_MEDIA, {
+    bubbles: true,
+    composed: true,
+    detail: args,
+  });
+}
diff --git a/src/sections/fav-browser-base.ts b/src/sections/fav-browser-base.ts
@@ -17,6 +17,7 @@ import { SpotifyPlusService } from '../services/spotifyplus-service';
 import { storageService } from '../decorators/storage';
 import { truncateMediaList } from '../utils/media-browser-utils';
 import { isCardInEditPreview, loadHaFormLazyControls } from '../utils/utils';
+import { FilterSectionMediaEventArgs } from '../events/filter-section-media';
 import { ProgressEndedEvent } from '../events/progress-ended';
 import { ProgressStartedEvent } from '../events/progress-started';
 import { DOMAIN_SPOTIFYPLUS } from '../constants';
@@ -326,6 +327,27 @@ export class FavBrowserBase extends LitElement {
   }
 
 
+  /**
+   * Execute filter based on passed arguments.
+   */
+  public filterSectionMedia(args: FilterSectionMediaEventArgs): void {
+
+    if (debuglog.enabled) {
+      debuglog("filterSectionMedia - filtering section media:\n%s",
+        JSON.stringify(args, null, 2),
+      );
+    }
+
+    // apply filter criteria.
+    this.filterCriteria = args.filterCriteria;
+    //this.requestUpdate();
+
+    // execute the search.
+    //this.updateMediaList(this.player);
+
+  }
+
+
   /**
    * Loads values from persistant storage.
    */
diff --git a/src/sections/userpreset-browser.ts b/src/sections/userpreset-browser.ts
@@ -1,3 +1,8 @@
+// debug logging.
+import Debug from 'debug/src/browser.js';
+import { DEBUG_APP_NAME } from '../constants';
+const debuglog = Debug(DEBUG_APP_NAME + ":userpreset-browser");
+
 // lovelace card imports.
 import { html, TemplateResult } from 'lit';
 import { customElement } from 'lit/decorators.js';
@@ -13,6 +18,7 @@ import { formatTitleInfo } from '../utils/media-browser-utils';
 import { getUtcNowTimestamp } from '../utils/utils';
 import { IUserPreset } from '../types/spotifyplus/user-preset';
 import { CategoryDisplayEvent } from '../events/category-display';
+import { FilterSectionMediaEvent } from '../events/filter-section-media';
 import { ALERT_ERROR_SPOTIFY_PREMIUM_REQUIRED } from '../constants';
 
 
@@ -104,12 +110,33 @@ export class UserPresetBrowser extends FavBrowserBase {
    */
   protected override onItemSelected(evArgs: CustomEvent) {
 
+    if (debuglog.enabled) {
+      debuglog("onItemSelected - media item selected:\n%s",
+        JSON.stringify(evArgs.detail, null, 2),
+      );
+    }
+
     // is this a recommendations type?
     if (evArgs.detail.type == "recommendations") {
 
       const mediaItem = evArgs.detail as IUserPreset;
       this.PlayTrackRecommendations(mediaItem);
 
+    } else if (evArgs.detail.type == "filtersection") {
+
+      const preset = evArgs.detail as IUserPreset;
+
+      // validate filter section name.
+      const enumValues: string[] = Object.values(Section);
+      if (!enumValues.includes(preset.filter_section || "")) {
+      //if (Object.values(Section) as string[]).includes(preset.filter_section || "") {
+        this.alertErrorSet("Preset filter_section \"" + preset.filter_section + "\" is not a valid section identifier.");
+        return;
+      }
+
+      // fire event.
+      this.dispatchEvent(FilterSectionMediaEvent(preset.filter_section, preset.filter_criteria));
+
     } else if (evArgs.detail.type == "category") {
 
       const preset = evArgs.detail as IUserPreset;
diff --git a/src/types/spotifyplus/user-preset.ts b/src/types/spotifyplus/user-preset.ts
@@ -59,6 +59,18 @@ export interface IUserPreset {
    */
   shuffle?: boolean | null;
 
+  /**
+   * Filter criteria that will be applied to the specified filter section.
+   * This property should only be populated for type = "filtersection".
+   */
+  filter_criteria?: string | null;
+
+  /**
+   * Section to be filtered.
+   * This property should only be populated for type = "filtersection".
+   */
+  filter_section?: string | null;
+
 }
 
 
