migrate TreeView to CSS modules (#5267)

* replace sx with Primer CSS utility classes where possible

As of https://github.com/primer/react/blob/fca4ec98f2e3ef5e5c3298320e3ab2050593709c/contributor-docs/adrs/adr-016-css.md,
Primer has decided to move away from using styled system props and prefers CSS for
styling over styled system props due to performance concerns with `sx` props.

See linked ADR for full details.

* add support for style prop to TreeView Root

* Convert ul to css modules

Per instructions:
https://github.com/primer/react/blob/ac6ddcd4b15526dd6f5ad6072a4daa57087eb1e7/contributor-docs/migrating-to-css-modules.md

* Reference CSS module classnames

* update skeleton components to use css modules

* add test for className support

* add changeset

* auto fix with 'npm run lint:css:fix'

* fix syntax for multiple modules classes

* update variable to prevent regression test failures

* workaround for directory icon color

For the directory icon color, [previously, we were using](https://github.com/primer/react/blob/21adedbc95e39a1b62ca2e0c31e87ac81e11911b/packages/react/src/TreeView/TreeView.module.css#L211):
```
var(--treeViewItem-leadingVisual-bgColor-rest, var(--color-tree-view-item-chevron-directory-fill, #CUSTOM_FALLBACK_FOR_EACH_MODE))
```

`--treeViewItem-leadingVisual-bgColor-rest` was replaced by `--treeViewItem-leadingVisual-iconColor-rest`
in primer/primitives#686. When that replacement was made, we didn't update the
legacy theme in this repo (makes sense), so since that variable no longer existed, we always use the
fallback hex code.

With these changes, we're now using `--treeViewItem-leadingVisual-iconColor-rest`. That variable works
for all modes except dark high contrast. I believe this is because whatever
[hex code that variable represents in dark high contrast mode](https://github.com/primer/primitives/blob/9f1033462619f7a3e3a191dcfc0a50cf7708c79a/src/tokens/functional/color/dark/patterns-dark.json5#L2081)
(#b7bdc8) is different than [this repo's custom legacy theme dark high contrast hex code](https://github.com/primer/react/blob/21adedbc95e39a1b62ca2e0c31e87ac81e11911b/packages/react/src/legacy-theme/ts/color-schemes.ts#L3535)
(#f0f3f6).

As a workaround, I've added this workaround for dark high contrast mode specifically.

We should implement a more robust solution in the future, either updating
`--treeViewItem-leadingVisual-iconColor-rest` to support the expected color
for dark high contrast mode, or updating the expected color to match the current
dark high contrast mode color.

* use `where` with attribute selector

Co-authored-by: Jon Rohan <yes@jonrohan.codes>

* use up-to-date color variable

Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com>

* Use `where` with attr selectors

Co-authored-by: Jon Rohan <yes@jonrohan.codes>

* drop PRIVATE_ prefix from css module classnames

* Remove unnecessary workaround for dark high contrast mode

Variable problem referenced in e97cf72
was resolved by #5277.

* test(vrt): update snapshots

---------

Co-authored-by: Jon Rohan <yes@jonrohan.codes>
Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com>
Co-authored-by: langermank <langermank@users.noreply.github.com>

.changeset/gentle-yaks-shake.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Update `TreeView` component to use CSS Modules

contributor-docs/migrating-to-css-modules.md

@@ -53,7 +53,7 @@ This guide outlines the steps to follow when refactoring Primer React components
    - Add a feature flag to toggle the `sx` prop for controlled rollout (staff shipping). How it's used will be based on the implementation of the component. For most you'll be able to `useFeatureFlag` and toggle between components. For more complex styled components, you can use the utility `toggleStyledComponent` which will render based on the feature flag string provided.
 
      ```jsx
-     /* When there is an exisiting styled component, use the `toggleStyledComponent` utility. */
+     /* When there is an existing styled component, use the `toggleStyledComponent` utility. */
      const StyledDiv = toggleStyledComponent(
        'primer_react_css_modules_team',
        'div',

packages/react/src/TreeView/TreeView.module.css

@@ -0,0 +1,260 @@
+.TreeViewRootUlStyles {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+
+  /*
+   * WARNING: This is a performance optimization.
+   *
+   * We define styles for the tree items at the root level of the tree
+   * to avoid recomputing the styles for each item when the tree updates.
+   * We're sacrificing maintainability for performance because TreeView
+   * needs to be performant enough to handle large trees (thousands of items).
+   *
+   * This is intended to be a temporary solution until we can improve the
+   * performance of our styling patterns.
+   *
+   * Do NOT copy this pattern without understanding the tradeoffs.
+   */
+  .TreeViewItem {
+    outline: none;
+
+    &:focus-visible > div,
+    &.focus-visible > div {
+      box-shadow: var(--boxShadow-thick) var(--fgColor-accent);
+
+      @media (forced-colors: active) {
+        outline: 2px solid HighlightText;
+        outline-offset: -2;
+      }
+    }
+
+    &[data-has-leading-action] {
+      --has-leading-action: 1;
+    }
+  }
+
+  .TreeViewItemContainer {
+    --level: 1;
+    --toggle-width: 1rem;
+    --min-item-height: 2rem;
+
+    position: relative;
+    display: grid;
+    width: 100%;
+    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-areas: 'spacer leadingAction toggle content';
+
+    --leading-action-width: calc(var(--has-leading-action, 0) * 1.5rem);
+    --spacer-width: calc(calc(var(--level) - 1) * (var(--toggle-width) / 2));
+
+    &:hover {
+      background-color: var(--control-transparent-bgColor-hover);
+
+      @media (forced-colors: active) {
+        outline: 2px solid transparent;
+        outline-offset: -2px;
+      }
+    }
+
+    @media (pointer: coarse) {
+      --toggle-width: 1.5rem;
+      --min-item-height: 2.75rem;
+    }
+
+    &: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;
+  }
+
+  .TreeViewItem[aria-current='true'] > .TreeViewItemContainer {
+    background-color: var(--control-transparent-bgColor-selected);
+
+    /* Current item indicator */
+    /* stylelint-disable-next-line selector-max-specificity */
+    &::after {
+      position: absolute;
+      top: calc(50% - var(--base-size-12));
+      left: calc(-1 * var(--base-size-8));
+      width: 0.25rem;
+      height: 1.5rem;
+      content: '';
+
+      /*
+       * Use fgColor accent for consistency across all themes. Using the "correct" variable,
+       * --bgColor-accent-emphasis, causes vrt failures for dark high contrast mode
+       */
+      /* stylelint-disable-next-line primer/colors */
+      background-color: var(--fgColor-accent);
+      border-radius: var(--borderRadius-medium);
+
+      @media (forced-colors: active) {
+        background-color: HighlightText;
+      }
+    }
+  }
+
+  .TreeViewItemToggle {
+    display: flex;
+    height: 100%;
+
+    /* The toggle should appear vertically centered for single-line items, but remain at the top for items that wrap
+    across more lines. */
+    /* stylelint-disable-next-line primer/spacing */
+    padding-top: calc(var(--min-item-height) / 2 - var(--base-size-12) / 2);
+    color: var(--fgColor-muted);
+    grid-area: toggle;
+    justify-content: center;
+    align-items: flex-start;
+  }
+
+  .TreeViewItemToggleHover:hover {
+    background-color: var(--control-transparent-bgColor-hover);
+  }
+
+  .TreeViewItemToggleEnd {
+    border-top-left-radius: var(--borderRadius-medium);
+    border-bottom-left-radius: var(--borderRadius-medium);
+  }
+
+  .TreeViewItemContent {
+    display: flex;
+    height: 100%;
+    padding: 0 var(--base-size-8);
+
+    /* The dynamic top and bottom padding to maintain the minimum item height for single line items */
+    /* stylelint-disable-next-line primer/spacing */
+    padding-top: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
+    /* stylelint-disable-next-line primer/spacing */
+    padding-bottom: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
+    line-height: var(--custom-line-height, var(--text-body-lineHeight-medium, 1.4285));
+    grid-area: content;
+    gap: var(--stack-gap-condensed);
+  }
+
+  .TreeViewItemContentText {
+    flex: 1 1 auto;
+    width: 0;
+  }
+
+  &:where([data-truncate-text='true']) .TreeViewItemContentText {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &:where([data-truncate-text='false']) .TreeViewItemContentText {
+    word-break: break-word;
+  }
+
+  .TreeViewItemVisual {
+    display: flex;
+
+    /* The visual icons should appear vertically centered for single-line items, but remain at the top for items that wrap
+    across more lines. */
+    height: var(--custom-line-height, 1.3rem);
+    color: var(--fgColor-muted);
+    align-items: center;
+  }
+
+  .TreeViewItemLeadingAction {
+    display: flex;
+    color: var(--fgColor-muted);
+    grid-area: leadingAction;
+  }
+
+  .TreeViewItemLevelLine {
+    width: 100%;
+    height: 100%;
+
+    /*
+     * On devices without hover, the nesting indicator lines
+     * appear at all times.
+     */
+    border-color: var(--borderColor-muted);
+    border-right: var(--borderWidth-thin) solid;
+  }
+
+  /*
+   * 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;
+    }
+
+    &:hover .TreeViewItemLevelLine,
+    &:focus-within .TreeViewItemLevelLine {
+      border-color: var(--borderColor-muted);
+    }
+  }
+
+  .TreeViewDirectoryIcon {
+    display: grid;
+    color: var(--treeViewItem-leadingVisual-iconColor-rest);
+  }
+
+  .TreeViewVisuallyHidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    /* stylelint-disable-next-line primer/spacing */
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+  }
+}
+
+.TreeViewSkeletonItemContainerStyle {
+  display: flex;
+  align-items: center;
+  column-gap: 0.5rem;
+  height: 2rem;
+
+  @media (pointer: coarse) {
+    height: 2.75rem;
+  }
+
+  &:nth-of-type(5n + 1) {
+    --tree-item-loading-width: 67%;
+  }
+
+  &:nth-of-type(5n + 2) {
+    --tree-item-loading-width: 47%;
+  }
+
+  &:nth-of-type(5n + 3) {
+    --tree-item-loading-width: 73%;
+  }
+
+  &:nth-of-type(5n + 4) {
+    --tree-item-loading-width: 64%;
+  }
+
+  &:nth-of-type(5n + 5) {
+    --tree-item-loading-width: 50%;
+  }
+}
+
+.TreeItemSkeletonTextStyles {
+  width: var(--tree-item-loading-width, 67%);
+}

packages/react/src/TreeView/TreeView.test.tsx

@@ -4,6 +4,7 @@ import React from 'react'
 import {ThemeProvider} from '../ThemeProvider'
 import type {SubTreeState} from './TreeView'
 import {TreeView} from './TreeView'
+import {FeatureFlags} from '../FeatureFlags'
 
 jest.useFakeTimers()
 
@@ -1364,7 +1365,7 @@ describe('State', () => {
   })
 })
 
-describe('Asyncronous loading', () => {
+describe('Asynchronous loading', () => {
   it('updates aria live region when loading is done', () => {
     function TestTree() {
       const [state, setState] = React.useState<SubTreeState>('initial')
@@ -1640,3 +1641,32 @@ describe('Asyncronous loading', () => {
     expect(getByRole('treeitem', {name: 'empty child'})).toHaveAttribute('aria-expanded')
   })
 })
+
+describe('CSS Module Migration', () => {
+  it('should support `className` on the outermost element', () => {
+    const TreeViewTestComponent = () => (
+      <TreeView aria-label="Test tree" className={'test-class-name'}>
+        <TreeView.Item id="item-1">Item 1</TreeView.Item>
+        <TreeView.Item id="item-2">Item 2</TreeView.Item>
+        <TreeView.Item id="item-3">Item 3</TreeView.Item>
+      </TreeView>
+    )
+    const FeatureFlagElement = () => {
+      return (
+        <FeatureFlags
+          flags={{
+            primer_react_css_modules_team: true,
+            primer_react_css_modules_staff: true,
+            primer_react_css_modules_ga: true,
+          }}
+        >
+          <TreeViewTestComponent />
+        </FeatureFlags>
+      )
+    }
+
+    // Testing on the second child element because the first child element is visually hidden
+    expect(render(<TreeViewTestComponent />).container.children[1]).toHaveClass('test-class-name')
+    expect(render(<FeatureFlagElement />).container.children[1]).toHaveClass('test-class-name')
+  })
+})