pass at optimizing css and js to minimize blocking, recalc, layout, inp costs

.changeset/performance-inp-optimizations.md

@@ -0,0 +1,14 @@
+---
+"@primer/react": patch
+---
+
+Performance: Optimize CSS `:has()` selectors and JavaScript hooks for improved INP
+
+- Scope CSS `:has()` selectors to direct children across Dialog, PageHeader, ActionList, Banner, ButtonGroup, AvatarStack, Breadcrumbs, SegmentedControl, TreeView, and SelectPanel
+- Add requestAnimationFrame throttling to `useResizeObserver` (first callback immediate, subsequent throttled)
+- Add anchor element ResizeObserver to `useAnchoredPosition` for repositioning on anchor resize
+- Add `useTreeItemCache` hook for caching TreeView DOM queries with MutationObserver invalidation
+- Throttle MutationObserver callbacks in AvatarStack and Announce components
+- Add rAF throttling to `useOverflow` hook
+- Optimize `hasInteractiveNodes` utility with querySelectorAll and attribute-first checks
+- Split Autocomplete context to prevent Overlay re-renders during typing

.github/instructions/css.instructions.md

@@ -10,4 +10,73 @@ If the file ends with `*.module.css`, it is a CSS Module.
 
 ## General Conventions
 
-- After making a change to a file, use `npx stylelint -q --rd --fix` with a path to the file changed to make sure the code lints
+- After making a change to a file, use `npx stylelint -q --rd --fix` with a path to the file changed to make sure the code lints.
+
+## Performance and Web Vitals Analysis (Required)
+
+When creating or modifying CSS, you must **explicitly analyze and account for impact on Core Web Vitals**. Treat this as a first-class requirement, not an afterthought.
+
+### Metrics to Consider
+
+Evaluate changes against the following metrics and call out any risks:
+
+- **LCP (Largest Contentful Paint)**
+
+  - Risk factors: render-blocking styles, large above-the-fold background images, heavy font usage, complex selectors on critical elements.
+
+- **CLS (Cumulative Layout Shift)**
+
+  - Risk factors: late-loading fonts, size-less images/media, conditional styles that affect layout after initial render, JS-driven class toggles that change dimensions.
+
+- **INP (Interaction to Next Paint)**
+
+  - Risk factors: expensive selector matching, `:has()` on large subtrees, frequent style recalculation triggers, deep descendant selectors on interactive paths.
+
+### Required Analysis Checklist
+
+For each meaningful CSS change, reason through and validate the following:
+
+- **Selector Cost**
+
+  - Prefer class selectors over tag or attribute selectors.
+  - Avoid deep descendant chains (`.a .b .c .d`) in large or frequently updated subtrees.
+  - Use `:has()` only when strictly necessary; assume worst-case cost on large DOMs and justify usage.
+
+- **Style Recalculation Scope**
+
+  - Consider which DOM nodes are affected when classes or attributes change.
+  - Avoid selectors that match large portions of the tree when toggling state (e.g., `[data-*] .child`).
+
+- **Layout and Paint Stability**
+
+  - Do not introduce layout-affecting properties (`width`, `height`, `margin`, `padding`, `display`) that may change after hydration or user interaction unless explicitly intended.
+  - Prefer transform/opacity for interaction-driven effects.
+  - Ensure predictable sizing for media, containers, and dynamic content to prevent CLS.
+
+- **Critical Rendering Path**
+
+  - Avoid adding styles that block first paint or LCP for above-the-fold content.
+  - Be cautious with large background images, filters, and shadows on critical elements.
+
+### CSS Modules–Specific Guidance
+
+- Assume CSS Modules may be used across multiple React roots and hydration boundaries.
+- Avoid styles that depend on global cascade ordering or implicit inheritance from non-module CSS.
+- Do not rely on runtime-injected styles to correct layout shifts introduced by base styles.
+
+### Documentation Requirement
+
+When a change has **any non-trivial performance implication**, include a brief inline comment or PR description that states:
+
+- Which Web Vital(s) may be affected.
+- Why the change is safe, or what tradeoff is being made.
+- Any assumptions about DOM size, interaction frequency, or rendering phase (SSR vs client).
+
+### Examples of High-Risk Patterns (Avoid Unless Justified)
+
+- `:has()` selectors applied to containers with large or frequently changing subtrees.
+- Attribute selectors used as global state flags on high-level containers.
+- Layout changes driven by hover, focus, or JS state on large components.
+- Font or image-dependent sizing without explicit fallbacks.
+
+Performance regressions are considered correctness issues. If a change cannot be justified as Web Vitals–safe, it should not be merged without explicit sign-off.

packages/react/src/ActionBar/ActionBar.tsx

@@ -320,6 +320,7 @@ export const ActionBar: React.FC<React.PropsWithChildren<ActionBarProps>> = prop
   const moreMenuBtnRef = useRef<HTMLButtonElement>(null)
   const containerRef = React.useRef<HTMLUListElement>(null)
 
+  // ResizeObserver is throttled by default (rAF) for better INP
   useResizeObserver((resizeObserverEntries: ResizeObserverEntry[]) => {
     const navWidth = resizeObserverEntries[0].contentRect.width
     const moreMenuWidth = moreMenuRef.current?.getBoundingClientRect().width ?? 0

packages/react/src/ActionList/ActionList.module.css

@@ -86,7 +86,14 @@
     display: none;
   }
 
-  /* if a list has a mix of items with and without descriptions, reset the label font-weight to normal */
+  /*
+   * If a list has a mix of items with and without descriptions, reset the label font-weight.
+   * NOTE: Uses double descendant :has() - traverses list twice per recalc.
+   * This is acceptable because:
+   * 1. ActionLists are typically small (10-50 items)
+   * 2. Alternative would require JS to detect mixed state and set data attribute
+   * 3. The visual impact is subtle (font-weight change), not critical styling
+   */
   &:has([data-has-description='true']):has([data-has-description='false']) {
     & .ItemLabel {
       font-weight: var(--base-text-weight-normal);
@@ -121,7 +128,8 @@
     }
   }
 
-  &:not(:has([aria-disabled], [disabled]), [data-has-subitem='true']) {
+  /* PERFORMANCE: Use data-disabled on <li> instead of :has([aria-disabled], [disabled]) which scans descendants */
+  &:not([aria-disabled], [data-disabled='true'], [data-has-subitem='true']) {
     @media (hover: hover) {
       &:hover,
       &:active {
@@ -276,8 +284,8 @@
       }
     }
 
-    &:where([data-loading='true']),
-    &:has([data-loading='true']) {
+    /* PERFORMANCE: data-loading is set on the <li> by JS, avoiding :has() descendant scan */
+    &:where([data-loading='true']) {
       & * {
         color: var(--fgColor-muted);
       }
@@ -322,10 +330,9 @@
     }
   }
 
-  /* disabled */
-
+  /* PERFORMANCE: data-disabled is set on the <li> by JS, avoiding :has() descendant scan */
   &[aria-disabled='true'],
-  &:has([aria-disabled='true'], [disabled]) {
+  &[data-disabled='true'] {
     & .ActionListContent * {
       color: var(--control-fgColor-disabled);
     }
@@ -366,7 +373,8 @@
   }
 
   /* When TrailingAction is in loading state, keep labels and descriptions accessible */
-  &:has(.TrailingAction [data-loading='true']):not([aria-disabled='true']) {
+  /* PERFORMANCE: scoped to direct child TrailingAction */
+  &:has(> .TrailingAction[data-loading='true']):not([aria-disabled='true']) {
     /* Ensure labels and descriptions maintain accessibility contrast */
     & .ItemLabel {
       color: var(--fgColor-default);
@@ -540,7 +548,11 @@
       display: none;
     }
 
-    /* show active indicator on parent collapse if child is active */
+    /*
+     * Show active indicator on parent collapse if child is active.
+     * NOTE: Uses adjacent sibling + descendant :has() - SubGroup is typically small (few nav items).
+     * This is acceptable because scope is limited to the collapsed SubGroup's children.
+     */
     &:has(+ .SubGroup [data-active='true']) {
       background: var(--control-transparent-bgColor-selected);
 
@@ -637,6 +649,7 @@ default block */
       word-break: normal;
     }
 
+    /* NOTE: Uses descendant :has() - scope is just this item's children (label + description). Acceptable. */
     &:has([data-truncate='true']) {
       & .ItemLabel {
         flex: 1 0 auto;
@@ -713,7 +726,8 @@ span wrapping svg or text */
   height: 100%;
 
   /* Preserve width consistency when loading state is active for text buttons only */
-  &[data-loading='true']:has([data-component='buttonContent']) {
+  /* PERFORMANCE: scoped to direct child for O(1) lookup */
+  &[data-loading='true']:has(> [data-component='buttonContent']) {
     /* Double the left padding to compensate for missing right padding */
     padding: 0 0 0 calc(var(--base-size-12) * 2);
 
@@ -731,6 +745,11 @@ span wrapping svg or text */
   }
 }
 
+/*
+ * NOTE: Uses descendant :has() - VisualComponent is nested inside Tooltip > button,
+ * which is 3 levels deep (> * > * > .TrailingVisual). This is acceptable since
+ * the search is scoped to this small wrapper element's subtree.
+ */
 .InactiveButtonWrap {
   &:has(.TrailingVisual) {
     grid-area: trailingVisual;

packages/react/src/ActionList/Group.module.css

@@ -4,7 +4,11 @@
   &:not(:first-child) {
     margin-block-start: var(--base-size-8);
 
-    /* If somebody tries to pass the `title` prop AND a `NavList.GroupHeading` as a child, hide the `ActionList.GroupHeading */
+    /*
+     * If somebody tries to pass the `title` prop AND a `NavList.GroupHeading` as a child, hide the `ActionList.GroupHeading`.
+     * NOTE: Uses descendant :has() - this is an edge case handler for developer errors.
+     * Scope is limited to group's children, not entire list. Acceptable performance cost.
+     */
     /* stylelint-disable-next-line selector-max-specificity */
     &:has(.GroupHeadingWrap + ul > .GroupHeadingWrap) {
       /* stylelint-disable-next-line selector-max-specificity */

packages/react/src/ActionList/Item.tsx

@@ -256,6 +256,8 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
         data-variant={variant === 'danger' ? variant : undefined}
         data-active={active ? true : undefined}
         data-inactive={inactiveText ? true : undefined}
+        data-loading={loading && !inactive ? true : undefined}
+        data-disabled={disabled ? true : undefined}
         data-has-subitem={slots.subItem ? true : undefined}
         data-has-description={slots.description ? true : false}
         className={clsx(classes.ActionListItem, className)}

packages/react/src/ActionList/TrailingAction.tsx

@@ -31,7 +31,7 @@ export type ActionListTrailingActionProps = ElementProps & {
 export const TrailingAction = forwardRef(
   ({as = 'button', icon, label, href = null, className, style, loading, ...props}, forwardedRef) => {
     return (
-      <span className={clsx(className, classes.TrailingAction)} style={style}>
+      <span className={clsx(className, classes.TrailingAction)} style={style} data-loading={loading ? true : undefined}>
         {icon ? (
           <IconButton
             as={as}

packages/react/src/Autocomplete/Autocomplete.tsx

@@ -1,7 +1,7 @@
 import type React from 'react'
-import {useCallback, useReducer, useRef} from 'react'
+import {useCallback, useDeferredValue, useMemo, useReducer, useRef} from 'react'
 import type {ComponentProps, FCWithSlotMarker} from '../utils/types'
-import {AutocompleteContext} from './AutocompleteContext'
+import {AutocompleteContext, AutocompleteInputContext, AutocompleteDeferredInputContext} from './AutocompleteContext'
 import AutocompleteInput from './AutocompleteInput'
 import AutocompleteMenu from './AutocompleteMenu'
 import AutocompleteOverlay from './AutocompleteOverlay'
@@ -69,26 +69,57 @@ const Autocomplete: FCWithSlotMarker<React.PropsWithChildren<{id?: string}>> = (
   }, [])
   const id = useId(idProp)
 
+  // Base context: refs, IDs, menu visibility, and callbacks
+  // Changes when menu opens/closes or selection changes, but NOT on every keystroke
+  const autocompleteContextValue = useMemo(
+    () => ({
+      activeDescendantRef,
+      id,
+      inputRef,
+      scrollContainerRef,
+      selectedItemLength,
+      setAutocompleteSuggestion,
+      setInputValue,
+      setIsMenuDirectlyActivated,
+      setShowMenu,
+      setSelectedItemLength,
+      showMenu,
+    }),
+    [
+      id,
+      selectedItemLength,
+      setAutocompleteSuggestion,
+      setInputValue,
+      setIsMenuDirectlyActivated,
+      setShowMenu,
+      setSelectedItemLength,
+      showMenu,
+    ],
+  )
+
+  // Input state context: values that change on every keystroke
+  // Split to prevent Overlay from re-rendering during typing
+  const autocompleteInputContextValue = useMemo(
+    () => ({
+      autocompleteSuggestion,
+      inputValue,
+      isMenuDirectlyActivated,
+    }),
+    [autocompleteSuggestion, inputValue, isMenuDirectlyActivated],
+  )
+
+  // Deferred input value for expensive operations like filtering
+  // Menu subscribes to this instead of inputValue to avoid re-rendering on every keystroke
+  const deferredInputValue = useDeferredValue(inputValue)
+  const autocompleteDeferredInputContextValue = useMemo(() => ({deferredInputValue}), [deferredInputValue])
+
   return (
-    <AutocompleteContext.Provider
-      value={{
-        activeDescendantRef,
-        autocompleteSuggestion,
-        id,
-        inputRef,
-        inputValue,
-        isMenuDirectlyActivated,
-        scrollContainerRef,
-        selectedItemLength,
-        setAutocompleteSuggestion,
-        setInputValue,
-        setIsMenuDirectlyActivated,
-        setShowMenu,
-        setSelectedItemLength,
-        showMenu,
-      }}
-    >
-      {children}
+    <AutocompleteContext.Provider value={autocompleteContextValue}>
+      <AutocompleteInputContext.Provider value={autocompleteInputContextValue}>
+        <AutocompleteDeferredInputContext.Provider value={autocompleteDeferredInputContextValue}>
+          {children}
+        </AutocompleteDeferredInputContext.Provider>
+      </AutocompleteInputContext.Provider>
     </AutocompleteContext.Provider>
   )
 }

packages/react/src/Autocomplete/AutocompleteContext.tsx

@@ -1,13 +1,15 @@
 import {createContext} from 'react'
 
+/**
+ * Base context containing refs, stable IDs, menu visibility state, and callbacks.
+ * This context changes when menu opens/closes or selection changes, but NOT on every keystroke.
+ * Consumers like AutocompleteOverlay that don't need input text should use only this context.
+ */
 export const AutocompleteContext = createContext<{
   activeDescendantRef: React.MutableRefObject<HTMLElement | null>
-  autocompleteSuggestion: string
   // TODO: consider changing `id` to `listboxId` because we're just using it to associate the input and combobox with the listbox
   id: string
   inputRef: React.MutableRefObject<HTMLInputElement | null>
-  inputValue: string
-  isMenuDirectlyActivated: boolean
   scrollContainerRef: React.MutableRefObject<HTMLElement | null>
   selectedItemLength: number
   setAutocompleteSuggestion: (value: string) => void
@@ -17,3 +19,23 @@ export const AutocompleteContext = createContext<{
   setShowMenu: (value: boolean) => void
   showMenu: boolean
 } | null>(null)
+
+/**
+ * Input-related state that changes on every keystroke.
+ * Only AutocompleteInput needs this for immediate text display and suggestion highlighting.
+ */
+export const AutocompleteInputContext = createContext<{
+  autocompleteSuggestion: string
+  inputValue: string
+  isMenuDirectlyActivated: boolean
+} | null>(null)
+
+/**
+ * Deferred input value for expensive operations like filtering.
+ * Uses React's useDeferredValue to allow typing to remain responsive while
+ * filtering large lists at lower priority.
+ * AutocompleteMenu uses this to avoid blocking keystrokes during filtering.
+ */
+export const AutocompleteDeferredInputContext = createContext<{
+  deferredInputValue: string
+} | null>(null)

packages/react/src/Autocomplete/AutocompleteInput.tsx

@@ -1,7 +1,7 @@
 import type {ChangeEventHandler, FocusEventHandler, KeyboardEventHandler} from 'react'
 import React, {useCallback, useContext, useEffect, useState} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
-import {AutocompleteContext} from './AutocompleteContext'
+import {AutocompleteContext, AutocompleteInputContext} from './AutocompleteContext'
 import TextInput from '../TextInput'
 import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import type {ComponentProps} from '../utils/types'
@@ -37,20 +37,12 @@ const AutocompleteInput = React.forwardRef(
     forwardedRef,
   ) => {
     const autocompleteContext = useContext(AutocompleteContext)
-    if (autocompleteContext === null) {
+    const inputContext = useContext(AutocompleteInputContext)
+    if (autocompleteContext === null || inputContext === null) {
       throw new Error('AutocompleteContext returned null values')
     }
-    const {
-      activeDescendantRef,
-      autocompleteSuggestion = '',
-      id,
-      inputRef,
-      inputValue = '',
-      isMenuDirectlyActivated,
-      setInputValue,
-      setShowMenu,
-      showMenu,
-    } = autocompleteContext
+    const {activeDescendantRef, id, inputRef, setInputValue, setShowMenu, showMenu} = autocompleteContext
+    const {autocompleteSuggestion = '', inputValue = '', isMenuDirectlyActivated} = inputContext
     useRefObjectAsForwardedRef(forwardedRef, inputRef)
     const [highlightRemainingText, setHighlightRemainingText] = useState<boolean>(true)
     const {safeSetTimeout} = useSafeTimeout()