UnderlineNav: Improve flickering by moving icon visibility control to a one-way CSS animation

.changeset/proud-candles-mix.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+`UnderlineNav`: Fix icon flickering on some screen sizes before initial render/hydration

packages/react/src/UnderlineNav/UnderlineNav.module.css

@@ -2,31 +2,50 @@
   /* Progressive enhancement: Detect overflow using scroll-based animations.
   The idiomatic way would be a scroll-state container query but browser support
   is slightly better for animations. */
-  animation: detect-overflow linear;
+  animation: detect-overflow;
   animation-timeline: scroll(self block);
 
   --UnderlineNav_moreButton-visibility: hidden;
-  --UnderlineNav_icons-display: inline;
-
-  &[data-hide-icons='true'] {
-    --UnderlineNav_icons-display: none;
-  }
+  --UnderlineNav_hide-icons-play-state: paused;
 
   &[data-has-overflow='true'] {
     --UnderlineNav_moreButton-visibility: visible;
   }
+
+  &[data-hide-icons='true'] [data-component='icon'] {
+    display: none;
+  }
 }
 
 @keyframes detect-overflow {
   0%,
   100% {
     --UnderlineNav_moreButton-visibility: visible;
-    --UnderlineNav_icons-display: none;
+    --UnderlineNav_hide-icons-play-state: running;
   }
 }
 
 .ItemsList [data-component='icon'] {
-  display: var(--UnderlineNav_icons-display);
+  /* Unlike the more button, the icons are removed from the layout when hidden. This can cause the container to no
+  longer overflow, which would cause a flickering loop if we just drove the visibility directly from the scroll state.
+  So instead we drive an animation that can only play forwards so the icons stay hidden for the life of the page, even
+  if the container is no longer overflowing. We can't just make the scroll-driven animation itself play forwards,
+  because scroll-driven animations are conditionally applied and revert when not scrollable. */
+  animation-name: hide-icons;
+  animation-fill-mode: forwards;
+  animation-play-state: var(--UnderlineNav_hide-icons-play-state);
+  animation-duration: 0.1ms; /* must be greater than 0 */
+}
+
+@keyframes hide-icons {
+  0% {
+    display: inline;
+  }
+
+  0.1%,
+  100% {
+    display: none;
+  }
 }
 
 .MoreButtonContainer {

packages/react/src/UnderlineNav/UnderlineNav.tsx

@@ -95,9 +95,8 @@ export const UnderlineNav = forwardRef(
           ref={navRef}
           data-variant={variant}
           data-overflow-mode="wrap"
-          // Force icons to stay hidden, avoiding flickering as icons create/remove overflow
+          // Ensure icons are hidden and button is shown on browsers that don't support scroll-driven animations
           data-hide-icons={hasEverOverflowed ? 'true' : undefined}
-          // Ensure button is shown (after initial render) on browsers that don't support scroll-driven animations
           data-has-overflow={isOverflowing ? 'true' : undefined}
         >
           <UnderlineItemList ref={listRef} role="list" className={classes.ItemsList}>
@@ -115,7 +114,7 @@ export const UnderlineNav = forwardRef(
                 variant="invisible"
                 data-component="overflow-menu-button"
                 data-current={overflowingCurrentItem ? 'true' : undefined}
-                aria-label={overflowingCurrentItem ? `More items, including current item` : undefined}
+                aria-label={overflowingCurrentItem ? 'More items, including current item' : undefined}
               >
                 <span>
                   More<VisuallyHidden as="span"> items</VisuallyHidden>

packages/react/src/internal/components/UnderlineTabbedInterface.module.css

@@ -18,18 +18,14 @@
     padding-inline: unset;
   }
 
-  &[data-hide-icons='true'] [data-component='icon'] {
-    display: none;
-  }
-
   &[data-overflow-mode='wrap'] {
     /* Wrap items onto hidden next lines */
     overflow: hidden;
     max-height: var(--control-xlarge-size);
 
     .UnderlineItemList {
       flex-wrap: wrap;
-      overflow: hidden;
+      flex: 1;
     }
   }
 }