chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemDetails.bs.html

@@ -11,6 +11,7 @@
 import "pkg:/source/utils/itemImageUrl.bs"
 import "pkg:/source/utils/mediaDisplayTitle.bs"
 import "pkg:/source/utils/misc.bs"
+import "pkg:/source/utils/placeholderImage.bs"
 import "pkg:/source/utils/streamSelection.bs"
 import "pkg:/source/utils/textureManager.bs"
 import "pkg:/source/utils/trackClusterFocus.bs"
@@ -2154,11 +2155,16 @@
 end sub
 
 ' setItemLogo: Set the item logo image URL if available.
-' Fallback chains by type:
-' - Movie/Series:   Logo → primaryImageTag (poster, compact size)
-' - Episode/Season/Recording: primaryImageTag (item thumb/poster) → parentLogoImageTag (series logo) → seriesPrimaryImageTag → hide
-' - Video/MusicVideo: primaryImageTag (poster)
-' - Person: primaryImageTag (portrait photo, tall) → silhouette icon
+' Fallback chains by type — every chain ends in a typed placeholder via
+' getPlaceholderImagePath() so the logo slot never goes blank, matching the
+' pattern Person and MusicArtist always used:
+' - Movie/Series/BoxSet: Logo → primaryImageTag (poster, compact size) → placeholder
+' - Episode/Season/Recording: primaryImageTag → parentLogoImageTag (series logo) → seriesPrimaryImageTag → placeholder
+' - Video/MusicVideo: primaryImageTag → placeholder
+' - MusicAlbum / Playlist / Photo / PhotoAlbum / TvChannel: primaryImageTag → placeholder
+' - Program: primaryImageTag → channel logo → placeholder
+' - Audio: primaryImageTag → album art → placeholder
+' - Person / MusicArtist: primaryImageTag (portrait) → placeholder
 ' @param {object} item - JellyfinBaseItem node
 sub setItemLogo(item as object)
   if not isValid(m.itemLogo) then return
@@ -2167,12 +2173,12 @@
   logoImageTag = item.logoImageTag
 
   if item.type = "Person"
-    ' Person: display primary (portrait) photo where the logo sits; fall back to silhouette icon
+    ' Person: display primary (portrait) photo where the logo sits; fall back to silhouette glyph
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.uri = "pkg:/images/placeholders/person_$$RES$$.png"
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "MusicArtist"
@@ -2184,73 +2190,67 @@
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.uri = "pkg:/images/placeholders/artist_$$RES$$.png"
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "MusicAlbum"
-    ' Square album art as the primary image; hide if none
+    ' Square album art as the primary image; typed placeholder if none
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "Playlist"
-    ' Square playlist cover as primary image; hide if none
+    ' Square playlist cover as primary image; typed placeholder if none
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "Photo" or item.type = "PhotoAlbum"
-    ' Photo thumbnail or album cover as primary image; hide if none
+    ' Photo thumbnail or album cover as primary image; typed placeholder if none
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "TvChannel"
-    ' Channel logo (typically square); hide if none
+    ' Channel logo (typically square); folder-fallback placeholder if none
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "Program"
-    ' Program image; fall back to channel logo
+    ' Program image → channel logo → typed placeholder
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else if isValidAndNotEmpty(item.channelPrimaryImageTag) and isValidAndNotEmpty(item.channelId)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.channelPrimaryImageTag }
       m.itemLogo.uri = ImageURL(item.channelId, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "Audio"
-    ' Own primary image → album art fallback → hide
+    ' Own primary image → album art fallback → typed placeholder
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else if isValidAndNotEmpty(item.albumId) and isValidAndNotEmpty(item.albumPrimaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.albumPrimaryImageTag }
       m.itemLogo.uri = ImageURL(item.albumId, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
     return
   else if item.type = "Episode" or item.type = "Season" or item.type = "Recording"
@@ -2266,14 +2266,14 @@
       logoImageTag = item.parentLogoImageTag
     end if
   else if item.type = "Video" or item.type = "MusicVideo"
-    ' Videos and MusicVideos don't typically have Logo images — use Primary (poster) image instead
+    ' Videos and MusicVideos don't typically have Logo images — use Primary (poster)
+    ' image instead; playCircle placeholder if none.
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 212, maxWidth: 500, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
-      return
+    else
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
-    m.itemLogo.visible = false
-    m.itemLogo.uri = ""
     return
   end if
 
@@ -2283,25 +2283,26 @@
   else if item.type = "Movie" or item.type = "Series" or item.type = "BoxSet"
     ' No logo: fall back to primary (poster) image — fetch at full quality; display height is
     ' capped by LOGO_MAX_DISPLAY_HEIGHT in onLogoLoadStatusChanged to avoid overlapping info rows.
+    ' Movie placeholder if neither logo nor primary is available.
     if isValidAndNotEmpty(item.primaryImageTag)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.primaryImageTag }
       m.itemLogo.uri = ImageURL(item.id, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
   else if item.type = "Episode" or item.type = "Season" or item.type = "Recording"
-    ' No item primary (already tried above), no series logo: fall back to series primary poster
+    ' No item primary (already tried above), no series logo: fall back to series primary poster,
+    ' then a playCircle placeholder if the series has no primary image either.
     if isValidAndNotEmpty(item.seriesPrimaryImageTag) and isValidAndNotEmpty(item.seriesId)
       imgParams = { maxHeight: 534, maxWidth: LOGO_MAX_DISPLAY_WIDTH, quality: 90, tag: item.seriesPrimaryImageTag }
       m.itemLogo.uri = ImageURL(item.seriesId, "Primary", imgParams)
     else
-      m.itemLogo.visible = false
-      m.itemLogo.uri = ""
+      m.itemLogo.uri = getPlaceholderImagePath(item.type)
     end if
   else
-    m.itemLogo.visible = false
-    m.itemLogo.uri = ""
+    ' Catch-all: any other type without a known fallback chain gets the type-driven
+    ' placeholder (falls through to the folder glyph for genuinely unknown types).
+    m.itemLogo.uri = getPlaceholderImagePath(item.type)
   end if
 end sub
 
@@ -2389,6 +2390,17 @@
   if not isValid(m.itemLogo) then return
 
   if m.itemLogo.loadStatus = "ready"
+    ' Tint placeholder PNGs (white glyph on transparent BG) with a near-page-BG
+    ' color so they recess like a watermark instead of competing with the title.
+    ' Detection by URI prefix: every placeholder asset lives under
+    ' pkg:/images/placeholders/. Real (server-loaded) images need the default
+    ' white blendColor so their native colors render correctly.
+    if Left(m.itemLogo.uri, 24) = "pkg:/images/placeholders"
+      m.itemLogo.blendColor = m.global.constants.colorBackgroundSecondary
+    else
+      m.itemLogo.blendColor = "0xFFFFFFFF"
+    end if
+
     logoWidth = m.itemLogo.bitmapWidth
     logoHeight = m.itemLogo.bitmapHeight
 

docs/components_ItemGrid_GridItem.bs.html

@@ -4,15 +4,15 @@
 import "pkg:/source/roku_modules/log/LogMixin.brs"
 import "pkg:/source/utils/itemImageUrl.bs"
 import "pkg:/source/utils/misc.bs"
+import "pkg:/source/utils/placeholderImage.bs"
 import "pkg:/source/utils/textureManager.bs"
 
 sub init()
   m.log = new log.Logger("GridItem")
   m.itemPoster = m.top.findNode("itemPoster")
   m.itemIcon = m.top.findNode("itemIcon")
-  m.posterText = m.top.findNode("posterText")
   m.itemText = m.top.findNode("itemText")
-  m.backdrop = m.top.findNode("backdrop")
+  m.placeholder = m.top.findNode("placeholder")
 
   m.itemPoster.observeField("loadStatus", "onPosterLoadStatusChanged")
 
@@ -131,25 +131,29 @@
     m.log.warn("Unhandled Grid Item Type", itemData.type)
   end if
 
-  ' Cache URI for texture management and conditionally load
+  ' Cache URI for texture management
   m.cachedPosterUri = posterUri
   m.cachedLoadDisplayMode = m.itemPoster.loadDisplayMode
-  if posterUri = "" or shouldLoadGridTexture()
+
+  if posterUri = ""
+    ' Known-missing image — eagerly surface the typed glyph on the backdrop.
+    ' Load-status never fires "failed" for an empty URI, so we must set the
+    ' placeholder state here rather than waiting for onPosterLoadStatusChanged.
+    m.itemPoster.uri = ""
+    showPlaceholder(resolveItemPlaceholderType(m.top.itemContent))
+  else if shouldLoadGridTexture()
+    ' Image expected and the texture manager wants this cell loaded — start
+    ' the placeholder in loading state; the load-status observer takes over.
+    resetPlaceholderToLoading()
     m.itemPoster.uri = posterUri
   else
+    ' Image expected but the texture manager is keeping this cell off-screen
+    ' to save memory. Loading state until the cell scrolls into range and
+    ' reloadGridTexture() restores the URI.
     m.isTextureUnloaded = true
+    resetPlaceholderToLoading()
     m.itemPoster.uri = ""
-    m.backdrop.visible = true
-  end if
-
-  'If Poster not loaded, ensure "blue box" is shown until loaded
-  if m.itemPoster.loadStatus <> "ready"
-    m.backdrop.visible = true
-    m.posterText.visible = true
   end if
-
-  m.posterText.text = m.itemText.text
-
 end sub
 
 ' Apply square 323x323 layout for music items (artists, albums, genres)
@@ -162,11 +166,8 @@
   m.itemText.translation = [0, m.itemPoster.translation[1] + m.itemPoster.height + 18]
   m.itemText.maxWidth = 323
 
-  m.backdrop.height = 323
-  m.backdrop.width = 323
-
-  m.posterText.height = 313
-  m.posterText.width = 313
+  m.placeholder.width = 323
+  m.placeholder.height = 323
 end sub
 
 ' Enable title scrolling based on item focus
@@ -181,17 +182,44 @@
   end if
 end sub
 
-'Hide backdrop and text when poster loaded
+' Toggle the JRPlaceholder fallback based on the real poster's load state.
+' Mirrors the canonical state machine from JRRowItem.bs onPosterLoadStatusChanged.
 sub onPosterLoadStatusChanged()
   ' Ignore status changes from intentional texture unloads (uri cleared to free memory)
   if m.isTextureUnloaded then return
 
-  if m.itemPoster.loadStatus = "ready"
-    m.backdrop.visible = false
-    m.posterText.visible = false
+  if m.itemPoster.loadStatus = "ready" and m.itemPoster.uri <> ""
+    ' Real image loaded — placeholder is no longer needed
+    m.placeholder.visible = false
+  else if m.itemPoster.loadStatus = "failed" and m.itemPoster.uri <> ""
+    ' Real image failed — surface a type-appropriate glyph on the backdrop
+    showPlaceholder(resolveItemPlaceholderType(m.top.itemContent))
+  else
+    ' Loading or no URI — keep the placeholder visible in its current state
+    m.placeholder.visible = true
   end if
 end sub
 
+' Flip the placeholder into failure state with a type-appropriate glyph, then
+' clear the poster URI so the glyph isn't covered by a stale broken image.
+' itemType="" puts JRPlaceholder in loading state (backdrop only, no glyph);
+' resolveItemPlaceholderType returns "" only for invalid/typeless items, so
+' valid items always end up here with a typed glyph or the Folder fallback.
+sub showPlaceholder(itemType as string)
+  m.placeholder.itemType = itemType
+  m.placeholder.visible = true
+  m.itemPoster.uri = ""
+end sub
+
+' Reset the JRPlaceholder to loading state (themed backdrop visible, no glyph).
+' Used by the initial-load branches in onItemContentChanged and by the texture
+' unload paths so off-screen / unloaded cells don't carry a stale failure-state
+' glyph back into view when they reload.
+sub resetPlaceholderToLoading()
+  m.placeholder.itemType = ""
+  m.placeholder.visible = true
+end sub
+
 ' ============================================================================
 ' Texture Management
 ' ============================================================================
@@ -352,15 +380,15 @@
 
   m.isTextureUnloaded = true
   m.itemPoster.uri = ""
-  m.backdrop.visible = true
+  resetPlaceholderToLoading()
 end sub
 
 ' Force-unloads textures unconditionally — used only during onDestroy().
 ' Ignores m.isTextureUnloaded and m.cachedPosterUri guards so every cell releases memory.
 sub forceUnloadGridTexture()
   m.isTextureUnloaded = true
   m.itemPoster.uri = ""
-  m.backdrop.visible = true
+  resetPlaceholderToLoading()
 end sub
 
 ' Restores poster URI from cache when the cell scrolls back on screen.