feat: Add AvatarPair

[pawelgrimm]

Short description

Adds <AvatarPair> for two overlapping avatars.

PR Checklist

• Added tests for bugs / new features
• Updated docs (storybooks, readme)
• Reviewed and approved Chromatic visual regression tests in CI

References

• 🎨 Product Library - Web / Avatar
• Stacks on feat: Add AvatarGroup #1051

📸 Demo

[doistbot]

Thanks pawelgrimm for your contribution 😊. The new AvatarGroup and AvatarPair components bring robust, size-responsive mask styling and solid test coverage.

Few things worth tightening:

• Component architecture: Migrate away from the deprecated polymorphicComponent utility in favor of standard React.forwardRef patterns as per the project guidelines.
• Child constraints: Narrow the child types or add a runtime guard to prevent fragments or wrappers from injecting 3+ DOM nodes and breaking the CSS :first-child/:last-child selectors.
• Button defaults: Explicitly default to type="button" when the component is rendered as="button" to prevent accidental form submissions.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (4)

• [P3] src/avatar/avatar-pair.tsx:20: --reactist-avatar-pair-rounded-radius is defined here and populated in getAvatarPairStyle, but it is never consumed in avatar.module.css (unlike its counterpart in AvatarGroup). It can be safely removed from AvatarPairStyle, the return object below, and the .avatarPair block in the CSS file.
• [P3] src/avatar/avatar-pair.tsx:24: AVATAR_PAIR_MASK_BY_SIZE is a byte-for-byte copy of AVATAR_GROUP_MASK_BY_SIZE in avatar-group.tsx. That gives us two sources of truth for the same avatar geometry, so any future size/mask tweak has to be updated in both files or the overlap components will drift. Please hoist the shared mask lookup into src/avatar/utils.ts and reuse it here and in AvatarGroup.
• [P3] src/avatar/avatar-pair.test.tsx:56: This only asserts the rounded branch. Since the default circle variant uses a different shape class and is the main rendering path, add a small sibling test for the default render (avatarPairShape-circle) so a regression there doesn’t slip through unnoticed.
• [P3] src/avatar/avatar-pair.test.tsx:67: The API promise here is “exactly two” children, but this test only covers the “not one child” side. Add a second @ts-expect-error case with three avatars; otherwise a typing regression that allows extra children would still pass while breaking the pair layout selectors.

_{Share Feedback • Review Logs}

[doistbot]

This tuple only guarantees “two React elements”, not “two direct Avatar children”. A fragment or wrapper component still type-checks here and can render 3+ DOM children, but the CSS only positions :first-child and :last-child, so the extra nodes stack incorrectly. Narrow the child type to Avatar elements or add a runtime guard for non-direct children.

[doistbot]

When this renders with as="button", it gets the HTML default type="submit". Using AvatarPair inside a form will submit the form on click unless every caller remembers to override it. Default the root to type="button" when as === 'button', while still letting an explicit type prop win.

[doistbot]

polymorphism.ts and polymorphicComponent are marked as deprecated in the repository guidelines (CLAUDE.md). New components should avoid this utility and instead use React.forwardRef with a named function matching the component name (using asChild or standard DOM wrappers if custom tags are needed).