Wrap AvatarStack avatars in isolation: isolate to create a new stacking context

[iansan5653]

The stacking order of the avatars inside AvatarStack is controlled via z-index because it is reversed from the DOM order (earlier items display on top). This works fine within the component, but the effects of z-index can easily leak outside the component and cause unexpected bugs wherever any other component overlays AvatarStack. An example of this is https://github.com/github/copilot-productivity/issues/3985 (internal issue link) where the avatars appear on top of a dialog that should cover them.

The stacking order here only matters relative to the other avatars within the same component, so we can easily prevent this type of bug by isolating the z-index effects via a new stacking context. The most explicit way to create a new stacking context is via the isolation property:

The isolation CSS property determines whether an element must create a new stacking context.

This PR simply adds isolation: isolate to the AvatarStack container.

There is prior art for this approach in ButtonGroup; see #2910.

As a followup, it might be worth considering an audit of all uses of z-index within Primer to ensure they are properly isolated. In fact I would even consider an ESLint rule banning the use of z-index so that we have to explicitly override the rule and thus verify that we have considered the side effects + stacking context.

Changelog

New

Changed

Fixed stacking bugs relating to AvatarStack.

Removed

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: 03da629

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

👋 Hi, this pull request contains changes to the source code that github/github depends on. If you are GitHub staff, we recommend testing these changes with github/github using the integration workflow. Thanks!

[github-actions]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	105.72 KB (-0.02% 🔽)
packages/react/dist/browser.umd.js	106.14 KB (+0.08% 🔺)

[camertron]

Wow, TIL about stacking contexts 😎 Any way to write tests for this?

[mperrotti]

I have another branch I'm working on that uses mask styles to achieve something similar, and it seems like a slightly nicer approach

[mperrotti]

Here's my alternative: #5714

It's not as straightforward as this solution, but it has some nice benefits. I'll leave it up to the reviewers to decide which direction we want to go.