chore(docs): update code docs

Author: jellyrock[bot]

docs/components_ItemDetails.bs.html

@@ -25,6 +25,11 @@
 ' extending above the metadata rows. Person photos are exempt because their info rows
 ' are short and don't reach the right edge where the photo sits.
 const LOGO_MAX_DISPLAY_HEIGHT = 336
+' First-frame estimate for the button row's total rendered height. Used by anchorDateLabel()
+' before boundingRect() has settled (it reports height=0 during initial render). Observed to
+' land around 130 px for the typical 2-line-label icon button. A later renderTracking callback
+' replaces this with the real measured height once layout completes.
+const ESTIMATED_BUTTON_ROW_HEIGHT_PX = 130
 
 sub init()
   m.log = new log.Logger("ItemDetails")
@@ -2210,22 +2215,36 @@
   dateAdded.toLocalTime()
   m.dateCreatedLabel.text = translate(translationKeys.LabelAdded) + " " + dateAdded.AsDateString("short-month-no-weekday") + " " + formatTime(dateAdded)
 
-  ' Set X position only — Y is deferred to anchorDateLabel() which runs after the
-  ' button group layout settles (via renderTracking observer).
-  ' Preserve the existing Y so that on refresh the label keeps its correct position
-  ' from the previous positioning cycle rather than resetting to 0 (top of screen).
+  ' Set X here; Y is computed by anchorDateLabel() which handles both the initial
+  ' placement (using the button group's XML translation + a safe height estimate) and
+  ' later refinements when the button group's actual rendered height is known. Calling
+  ' it here guarantees the label is correctly positioned on the very first render —
+  ' no flash at the top of the screen.
   m.dateCreatedLabel.translation = [1920 - 96 - 450, m.dateCreatedLabel.translation[1]]
   m.dateCreatedLabel.visible = true
+  anchorDateLabel()
 end sub
 
-' anchorDateLabel: Derive the date label's Y position from the button group's rendered rect.
+' anchorDateLabel: Derive the date label's Y position from the button group's position.
 ' Returns dateLabelY so callers (e.g. logo positioning) can use it without duplicating the math.
-' Safe to call multiple times — idempotent.
-' @return {float} dateLabelY — the Y coordinate used for the date label
-function anchorDateLabel() as float
+' Safe to call multiple times — idempotent, and safe to call BEFORE the button group has
+' finished laying out: falls back to the group's fixed translation + ESTIMATED_BUTTON_ROW_HEIGHT_PX
+' so the label never lands off-screen. A later renderTracking callback refines the position
+' once the real rendered height is known.
+' @return {integer} dateLabelY — the Y coordinate used for the date label
+function anchorDateLabel() as integer
+  buttonY = m.buttonGrp.translation[1]
+  buttonHeight = ESTIMATED_BUTTON_ROW_HEIGHT_PX
+
+  ' Refine with the measured height once layout has settled. Ignore the degenerate 0-size
+  ' bounding rect reported during the initial render — that's what was pushing the label
+  ' to y=-30 on the Series detail screen.
   buttonRect = m.buttonGrp.boundingRect()
-  buttonBottom = buttonRect.y + buttonRect.height
-  dateLabelY = buttonBottom - 30
+  if buttonRect.height > 0
+    buttonHeight = buttonRect.height
+  end if
+
+  dateLabelY = buttonY + buttonHeight - 30
 
   if isValid(m.dateCreatedLabel) and m.dateCreatedLabel.visible
     m.dateCreatedLabel.translation = [m.dateCreatedLabel.translation[0], dateLabelY]