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;
  }
  }
 }