From 59c4714693b992fe5aa3c4c2e885dd67bf5d4ed4 Mon Sep 17 00:00:00 2001
From: Matthew Costabile <mattcosta7@github.com>
Date: Fri, 29 May 2026 11:47:21 +0000
Subject: [PATCH 1/2] perf(TreeView): make rows paint-safe (no visual change)
 and reduce hover/focus invalidation

- Add 'overflow-clip-margin: var(--base-size-8)' to '.TreeViewItem' and
  '.TreeViewItemContainer' so the current-item indicator (positioned at
  'left: -8px' of the row container) remains visible when a consumer applies
  'contain: paint' to the row, or when the documented 'containIntrinsicSize'
  prop triggers 'content-visibility: auto' (which implies paint containment)
  on the container. The property is a no-op when no paint containment is
  active, so default rendering is unchanged. Safari 17 silently ignores the
  property and keeps the pre-existing clipped-indicator behavior under
  consumer-side 'contain: paint' (no regression from prior versions); Safari
  18+ supports it, as does 'content-visibility: auto'.
- Replace ':has(.TreeViewItemSkeleton):hover' with a positive '[data-loading]'
  marker emitted on the placeholder row's <li> by 'LoadingItem' via a
  module-private 'LoadingPlaceholderContext'. No public-API change; avoids the
  broad ':has()' invalidation cost across every row in large trees.
- Replace the root-scope ':hover'/':focus-within' descendant selectors on
  level lines with an inherited '--tree-line-color' custom property toggled on
  the root <ul>. Same UX; one property toggle on one element instead of
  selector re-matching against every '.TreeViewItemLevelLine' descendant.
- Fix unitless 'outline-offset: -2' in the forced-colors focus-ring fallback
  that browsers were silently dropping (so forced-colors users now actually
  get a focus indicator on tree items).
- Make 'grid-template-columns' declare the 'trailingAction' track explicitly
  ('auto') so it matches the 5-area 'grid-template-areas' declaration.
---
 .changeset/treeview-indicator-paint-safe.md   | 11 +++
 .../TreeView/TreeView.features.stories.tsx    | 27 ++++++
 .../react/src/TreeView/TreeView.module.css    | 84 +++++++++++--------
 packages/react/src/TreeView/TreeView.tsx      | 35 +++++---
 4 files changed, 110 insertions(+), 47 deletions(-)
 create mode 100644 .changeset/treeview-indicator-paint-safe.md

diff --git a/.changeset/treeview-indicator-paint-safe.md b/.changeset/treeview-indicator-paint-safe.md
new file mode 100644
index 00000000000..269c75c1a0b
--- /dev/null
+++ b/.changeset/treeview-indicator-paint-safe.md
@@ -0,0 +1,11 @@
+---
+'@primer/react': patch
+---
+
+`TreeView`: make rows safer to use with `contain: paint` / `content-visibility: auto` and reduce style-recalc cost on hover/focus in large trees. No visual or layout changes; all changes are either invisible at the default rendering or behind an opt-in CSS containment property the consumer sets.
+
+- The current-item indicator (positioned at `left: -8px` of the row container) was being clipped when a consumer applied `contain: paint` to the `<li>` or when the documented `containIntrinsicSize` prop on `TreeView.Item` triggered `content-visibility: auto` on the row container — including for `current` items. Both `.TreeViewItem` and `.TreeViewItemContainer` now declare `overflow-clip-margin: var(--base-size-8)`, which extends the paint-clip edge by 8px on the side the indicator paints. The property is a no-op when no paint containment is active, so default rendering is byte-identical.
+- Skeleton-row hover suppression no longer relies on `:has(.TreeViewItemSkeleton)`, which forced subtree invalidation on every row. `LoadingItem` now communicates with the placeholder `Item` via a module-private context that emits a positive `data-loading` attribute on the `<li>`, and the CSS selector targets that directly. No new public prop.
+- Nesting indicator lines no longer use a root-scope `:hover`/`:focus-within` descendant selector. Color is driven by an inherited `--tree-line-color` custom property set on the root `<ul>`, so a hover or focus change inside the tree updates one property on one element instead of re-matching `.TreeViewItemLevelLine` selectors against every level line in the tree.
+- Fixed a unitless `outline-offset: -2` in the forced-colors focus-ring fallback that browsers were silently dropping (so forced-colors users now actually get a focus indicator on tree items).
+- `.TreeViewItemContainer`'s `grid-template-columns` now declares the `trailingAction` column explicitly (`auto`) so it matches the 5-area `grid-template-areas` declaration (previously the trailing column was implicit `auto`).
diff --git a/packages/react/src/TreeView/TreeView.features.stories.tsx b/packages/react/src/TreeView/TreeView.features.stories.tsx
index ff027a604a0..f3b390d54a4 100644
--- a/packages/react/src/TreeView/TreeView.features.stories.tsx
+++ b/packages/react/src/TreeView/TreeView.features.stories.tsx
@@ -780,6 +780,33 @@ export const ContainIntrinsicSize: StoryFn = () => {
   )
 }
 
+// `containIntrinsicSize` sets `content-visibility: auto` on the row container, which implies
+// `contain: paint`. The current-item indicator must paint inside the row's box or it gets clipped.
+export const CurrentItemWithContainIntrinsicSize: StoryFn = () => {
+  return (
+    <TreeView aria-label="Files">
+      <TreeView.Item id="file-1" containIntrinsicSize="2rem">
+        <TreeView.LeadingVisual>
+          <FileIcon />
+        </TreeView.LeadingVisual>
+        File 1
+      </TreeView.Item>
+      <TreeView.Item id="file-2" containIntrinsicSize="2rem" current>
+        <TreeView.LeadingVisual>
+          <FileIcon />
+        </TreeView.LeadingVisual>
+        File 2
+      </TreeView.Item>
+      <TreeView.Item id="file-3" containIntrinsicSize="2rem">
+        <TreeView.LeadingVisual>
+          <FileIcon />
+        </TreeView.LeadingVisual>
+        File 3
+      </TreeView.Item>
+    </TreeView>
+  )
+}
+
 export const InitialFocus: StoryFn = () => (
   <div>
     <Button>Focusable element before TreeView</Button>
diff --git a/packages/react/src/TreeView/TreeView.module.css b/packages/react/src/TreeView/TreeView.module.css
index 57e3da65ff8..077ed06ec4a 100644
--- a/packages/react/src/TreeView/TreeView.module.css
+++ b/packages/react/src/TreeView/TreeView.module.css
@@ -17,6 +17,18 @@
    * Do NOT copy this pattern without understanding the tradeoffs.
    */
   .TreeViewItem {
+    /*
+     * `overflow-clip-margin` extends the paint clip edge by 8px so the current-item indicator
+     * (positioned at `left: -8px` of the row container) remains visible when a consumer applies
+     * `contain: paint` (or `contain: strict`, or `content-visibility: auto`) to this `<li>`. Has
+     * no effect when no paint containment is active, so default rendering is unchanged.
+     *
+     * Safari 17 ignores this property; Safari 17 consumers using `contain: paint` keep the
+     * pre-existing clipped-indicator behavior (no regression from prior versions). Safari 18+
+     * supports it, as does `content-visibility: auto`, so `containIntrinsicSize` works correctly.
+     */
+    /* stylelint-disable-next-line plugin/browser-compat -- Safari 17 fallback is the existing behavior; see comment above */
+    overflow-clip-margin: var(--base-size-8);
     outline: none;
 
     &:focus-visible > div,
@@ -25,8 +37,7 @@
 
       @media (forced-colors: active) {
         outline: 2px solid HighlightText;
-        /* stylelint-disable-next-line declaration-property-value-no-unknown */
-        outline-offset: -2;
+        outline-offset: -2px;
       }
     }
 
@@ -43,11 +54,18 @@
     position: relative;
     display: grid;
     width: 100%;
+    /*
+     * Mirrors the `overflow-clip-margin` on `.TreeViewItem` so the indicator also stays
+     * visible when `containIntrinsicSize` is set on this row (which sets
+     * `content-visibility: auto` on this container and implies paint containment).
+     */
+    /* stylelint-disable-next-line plugin/browser-compat -- see Safari 17 note on .TreeViewItem above */
+    overflow-clip-margin: var(--base-size-8);
     font-size: var(--text-body-size-medium);
     color: var(--fgColor-default);
     cursor: pointer;
     border-radius: var(--borderRadius-medium);
-    grid-template-columns: var(--spacer-width) var(--leading-action-width) var(--toggle-width) 1fr;
+    grid-template-columns: var(--spacer-width) var(--leading-action-width) var(--toggle-width) 1fr auto;
     grid-template-areas: 'spacer leadingAction toggle content trailingAction';
 
     --leading-action-width: calc(var(--has-leading-action, 0) * 1.5rem);
@@ -66,25 +84,24 @@
       --toggle-width: 1.5rem;
       --min-item-height: 2.75rem;
     }
-
-    /*
-     * NOTE: Uses descendant :has() - TreeViewItemSkeleton is nested inside
-     * TreeViewItemContent > TreeViewItemContentText, not a direct child.
-     * This is acceptable as the search is scoped to this element's subtree.
-     */
-    /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
-    &:has(.TreeViewItemSkeleton):hover {
-      cursor: default;
-      background-color: transparent;
-
-      @media (forced-colors: active) {
-        outline: none;
-      }
-    }
   }
 
   &:where([data-omit-spacer='true']) .TreeViewItemContainer {
-    grid-template-columns: 0 0 0 1fr;
+    grid-template-columns: 0 0 0 1fr auto;
+  }
+
+  /*
+   * Suppress hover affordances on rows being used as skeleton loading placeholders.
+   * Marked positively via `data-loading` from `LoadingItem` so we avoid the broad
+   * invalidation cost of `:has(.TreeViewItemSkeleton)` across every row in large trees.
+   */
+  .TreeViewItem:where([data-loading]) > .TreeViewItemContainer:hover {
+    cursor: default;
+    background-color: transparent;
+
+    @media (forced-colors: active) {
+      outline: none;
+    }
   }
 
   .TreeViewItem[aria-current='true'] > .TreeViewItemContainer {
@@ -201,29 +218,26 @@
   .TreeViewItemLevelLine {
     width: 100%;
     height: 100%;
+    border-right: var(--borderWidth-thin) solid;
 
     /*
-     * On devices without hover, the nesting indicator lines
-     * appear at all times.
+     * `--tree-line-color` is set on the root `<ul>` and inherited down. On coarse pointers it
+     * stays unset and falls back to `muted` (lines always visible). On hover-capable devices it
+     * is initialized to `transparent` on the root and flipped to `muted` while the tree is
+     * hovered or focused, so the browser only has to propagate a single inherited custom
+     * property instead of re-matching `.TreeViewItemLevelLine` descendant selectors on every
+     * hover/focus change inside large trees.
      */
-    border-color: var(--borderColor-muted);
-    border-right: var(--borderWidth-thin) solid;
+    /* stylelint-disable-next-line primer/colors -- private custom property, defaults to a Primer token */
+    border-color: var(--tree-line-color, var(--borderColor-muted));
   }
 
-  /*
-   * On devices with :hover support, the nesting indicator lines
-   * fade in when the user mouses over the entire component,
-   * or when there's focus inside the component. This makes
-   * sure the component remains simple when not in use.
-   */
   @media (hover: hover) {
-    .TreeViewItemLevelLine {
-      border-color: transparent;
-    }
+    --tree-line-color: transparent;
 
-    &:hover .TreeViewItemLevelLine,
-    &:focus-within .TreeViewItemLevelLine {
-      border-color: var(--borderColor-muted);
+    &:hover,
+    &:focus-within {
+      --tree-line-color: var(--borderColor-muted);
     }
   }
 
diff --git a/packages/react/src/TreeView/TreeView.tsx b/packages/react/src/TreeView/TreeView.tsx
index fc41913a4c1..6c5bc6af2fb 100644
--- a/packages/react/src/TreeView/TreeView.tsx
+++ b/packages/react/src/TreeView/TreeView.tsx
@@ -69,6 +69,11 @@ const ItemContext = React.createContext<{
   trailingActionId: '',
 })
 
+// Module-private channel from LoadingItem to the Item it renders. Lets us mark the placeholder
+// row with `data-loading` (used by CSS to suppress hover affordances) without exposing an
+// internal-only prop on the public TreeViewItemProps API.
+const LoadingPlaceholderContext = React.createContext(false)
+
 // ----------------------------------------------------------------------------
 // TreeView
 
@@ -255,6 +260,7 @@ const Item = React.forwardRef<HTMLElement, TreeViewItemProps>(
       onChange: onExpandedChange,
     })
     const {level} = React.useContext(ItemContext)
+    const isLoadingPlaceholder = React.useContext(LoadingPlaceholderContext)
     const {hasSubTree, subTree, childrenWithoutSubTree} = useSubTree(rest)
     const [isSubTreeEmpty, setIsSubTreeEmpty] = React.useState(!hasSubTree)
     const [actionCommandPressed, setActionCommandPressed] = React.useState(false)
@@ -371,6 +377,7 @@ const Item = React.forwardRef<HTMLElement, TreeViewItemProps>(
           aria-current={isCurrentItem ? 'true' : undefined}
           aria-selected={isFocused ? 'true' : 'false'}
           data-has-leading-action={slots.leadingAction ? true : undefined}
+          data-loading={isLoadingPlaceholder ? true : undefined}
           onKeyDown={handleKeyDown}
           onFocus={event => {
             // Defer scroll to the next animation frame so that rapid keyboard
@@ -645,22 +652,26 @@ const LoadingItem = React.forwardRef<HTMLElement, LoadingItemProps>(({count}, re
 
   if (count) {
     return (
-      <Item id={itemId} ref={ref}>
-        {Array.from({length: count}).map((_, i) => {
-          return <SkeletonItem aria-hidden={true} key={i} />
-        })}
-        <div className={clsx('PRIVATE_VisuallyHidden', classes.TreeViewVisuallyHidden)}>Loading {count} items</div>
-      </Item>
+      <LoadingPlaceholderContext.Provider value={true}>
+        <Item id={itemId} ref={ref}>
+          {Array.from({length: count}).map((_, i) => {
+            return <SkeletonItem aria-hidden={true} key={i} />
+          })}
+          <div className={clsx('PRIVATE_VisuallyHidden', classes.TreeViewVisuallyHidden)}>Loading {count} items</div>
+        </Item>
+      </LoadingPlaceholderContext.Provider>
     )
   }
 
   return (
-    <Item id={itemId} ref={ref}>
-      <LeadingVisual>
-        <Spinner size="small" />
-      </LeadingVisual>
-      <Text className="fgColor-muted">Loading...</Text>
-    </Item>
+    <LoadingPlaceholderContext.Provider value={true}>
+      <Item id={itemId} ref={ref}>
+        <LeadingVisual>
+          <Spinner size="small" />
+        </LeadingVisual>
+        <Text className="fgColor-muted">Loading...</Text>
+      </Item>
+    </LoadingPlaceholderContext.Provider>
   )
 })
 

From 6e7e98edabee51224e3d58b05ba3a327ef0e3852 Mon Sep 17 00:00:00 2001
From: Matthew Costabile <mattcosta7@github.com>
Date: Fri, 29 May 2026 09:17:10 -0400
Subject: [PATCH 2/2] Clean up comments in TreeView.module.css

Removed comments regarding Safari 17 behavior and stylelint rules.
---
 packages/react/src/TreeView/TreeView.module.css | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/packages/react/src/TreeView/TreeView.module.css b/packages/react/src/TreeView/TreeView.module.css
index 077ed06ec4a..2c3ea4ee472 100644
--- a/packages/react/src/TreeView/TreeView.module.css
+++ b/packages/react/src/TreeView/TreeView.module.css
@@ -22,12 +22,7 @@
      * (positioned at `left: -8px` of the row container) remains visible when a consumer applies
      * `contain: paint` (or `contain: strict`, or `content-visibility: auto`) to this `<li>`. Has
      * no effect when no paint containment is active, so default rendering is unchanged.
-     *
-     * Safari 17 ignores this property; Safari 17 consumers using `contain: paint` keep the
-     * pre-existing clipped-indicator behavior (no regression from prior versions). Safari 18+
-     * supports it, as does `content-visibility: auto`, so `containIntrinsicSize` works correctly.
      */
-    /* stylelint-disable-next-line plugin/browser-compat -- Safari 17 fallback is the existing behavior; see comment above */
     overflow-clip-margin: var(--base-size-8);
     outline: none;
 
@@ -59,7 +54,6 @@
      * visible when `containIntrinsicSize` is set on this row (which sets
      * `content-visibility: auto` on this container and implies paint containment).
      */
-    /* stylelint-disable-next-line plugin/browser-compat -- see Safari 17 note on .TreeViewItem above */
     overflow-clip-margin: var(--base-size-8);
     font-size: var(--text-body-size-medium);
     color: var(--fgColor-default);