feat(jsx-email): add avatar and avatar-group components

[charliecreates]

Component / Package Name:

packages/jsx-email

This PR contains:

• bugfix
• feature
• refactor
• documentation
• other

Are tests included?

• yes (bugfixes and features will not be merged without tests)
• no

Breaking Changes?

• yes (breaking changes will not be merged unless absolutely necessary)
• no

If yes, please include "BREAKING CHANGES:" in the first commit message body, followed by a description of what is breaking.

List any relevant issue numbers:

N/A

Description

Adds Avatar and AvatarGroup components for packages/jsx-email with exports, tests, docs, and demo coverage.

Implemented files include:

• packages/jsx-email/src/components/avatar.tsx
• packages/jsx-email/src/components/avatar-group.tsx
• packages/jsx-email/src/index.ts
• packages/jsx-email/test/avatar.test.tsx
• packages/jsx-email/test/avatar-group.test.tsx
• packages/jsx-email/test/.snapshots/avatar.test.tsx.snap
• packages/jsx-email/test/.snapshots/avatar-group.test.tsx.snap
• docs/components/avatar.md
• docs/components/avatar-group.md
• apps/web/src/content/docs/components/avatar.mdx
• apps/web/src/content/docs/components/avatar-group.mdx
• apps/demo/emails/vercel-invite-user.tsx

Checks run:

• moon run jsx-email:test ✅ (48 files / 200 tests passed)

Pre-existing unrelated TypeScript failure note:

• None observed during this run.

Requirements checklist

• Create packages/jsx-email/src/components/avatar.tsx with the agreed Avatar API and defaults.
• Create packages/jsx-email/src/components/avatar-group.tsx with safe-mode default rendering.
• Ensure fallback block rendering for no-image avatars (fallbackText/initials/?).
• Implement accessibility rules for decorative vs meaningful avatars.
• Implement AvatarGroup truncation with overflow token (+N).
• Implement direction support (ltr/rtl) for group rendering order.
• Implement overlap as explicit opt-in enhanced mode.
• Export Avatar and AvatarGroup (and related types) from packages/jsx-email/src/index.ts.
• Add packages/jsx-email/test/avatar.test.tsx coverage.
• Add packages/jsx-email/test/avatar-group.test.tsx coverage.
• Add/update snapshots for both safe-mode and overlap variants.
• Add docs pages in docs/components/* for both components.
• Add docs pages in apps/web/src/content/docs/components/* for both components.
• Add/update at least one demo/recipe email under apps/demo/emails/.
• Document caveats for enhanced overlap and image-fit behavior.
• Run repo-standard tests/checks relevant to touched code and confirm passing.
• Open a PR targeting next/v3 using the repo PR template.
• Copy this requirements checklist into the PR body.
• Ensure PR title/body and commit messages do not mention react‑email.

[shellscape]

@CharlieHelps read the agents.md guidance and adjust this PR appropriately to be in compliance

[shellscape]

@CharlieHelps you appear to have broken the smoke tests

[charliecreates]

Thanks for flagging this — I investigated and validated it end-to-end.

• The failed smoke run was this attempt: https://github.com/shellscape/jsx-email/actions/runs/24488437077/job/71568299964
• I reran the failed run, and the rerun passed: https://github.com/shellscape/jsx-email/actions/runs/24488437077/job/71570896793
• I also ran a clean-room local reproduction on the PR head commit (78a9a342e75b7a06d291a7c7b423385df850c9b5) and smoke-v2 passed.
• Current smoke check on latest head is green: https://github.com/shellscape/jsx-email/actions/runs/24489484800/job/71571323408

I also completed the earlier AGENTS.md compliance updates on this PR:

• Rewrote branch history to a single scoped Conventional Commit: feat(jsx-email): add avatar and avatar-group components
• Updated PR title to scoped Conventional Commit format.
• Updated PR body command wording to remove pnpm exec (moon run jsx-email:test).

If you want, I can follow up with a dedicated hardening pass for the smoke watcher path to reduce transient preview-server crash risk.

[shellscape]

@CharlieHelps you haven't updated the PR body to check off the requirements that you added. do that now.

[charliecreates]

Updated the PR body requirements checklist to mark completed items as checked. The checklist section now reflects current PR implementation status.

[shellscape]

@CharlieHelps can you implement the remaining requirements in the pr body? if you have questions, you may ask them but provide suggested answers in acbd format.

[charliecreates]

Implemented the remaining requested items:

• AvatarGroup truncation with overflow token (+N)
• direction support (ltr/rtl) for group rendering order
• Caveats for enhanced overlap and image-fit behavior documented

Commit: 61c9771

Tests run:

• pnpm exec moon run plugin-inline:build plugin-minify:build plugin-pretty:build ✅
• pnpm exec moon run jsx-email:test -- avatar-group.test.tsx -u ✅
• pnpm exec moon run jsx-email:test -- avatar.test.tsx avatar-group.test.tsx ✅

[shellscape]

@CharlieHelps please do a thorough review of this PR to determine if it's ready to merge. Look at the diff, reviews, comments, and referenced issues/docs/links to build a complete understanding. Then respond with a comment that includes a list of MUST fix items that must be fixed before the the PR is merged, and a list of IMPROVEMENTS that shouldn't block the merge but may be quick improvements or things that could be addressed in a follow up PR. The MUST fix items should explain exactly what's wrong and what needs to change to resolve the problem. Both should be numbered lists and the IMPROVEMENTS list should continue counting up from the MUST list. It's OK if there are no IMPROVEMENTS or MUST fix items, you can just omit the lists.

[charliecreates]

Non-blocking feedback (2)

1. Overflow token sizing does not follow custom avatar dimensions — packages/jsx-email/src/components/avatar-group.tsx#L43-L47
   When max truncation is used with avatars sized differently than the 40px default, the +N token is still rendered at default Avatar size, which can make the group visually uneven.
   Consider deriving the overflow token width/height from rendered avatars (or exposing a small explicit sizing prop for the overflow token).

2. Overflow token accessibility label is currently just +N — packages/jsx-email/src/components/avatar-group.tsx#L43-L47
   Because the overflow token only sets fallback, assistive tech will read a literal value like +2.
   Consider passing a semantic name/alt (for example, "2 more") while keeping visual fallback text as +2.

If you'd like me to implement any of these, reply with item numbers (for example: please fix 1).

[charliecreates]

Completed a thorough review of this PR (diff, existing reviews/comments, and referenced context). I don’t see any blocking issues, so this looks ready to merge.

MUST fix items
None.

IMPROVEMENTS

1. The overflow token (+N) currently renders as a default Avatar without inheriting group avatar dimensions. In groups where avatars are not the default size, this can make the overflow token visually inconsistent. It would be better to derive overflow token dimensions from the group avatar sizing convention (or expose explicit overflow-token sizing props) so +N matches the rendered avatars.
2. The overflow token accessibility label is currently effectively +N. Since Avatar accessibility text is derived from alt ?? name ?? fallback, assistive technologies may announce +2 instead of something semantic. Keep fallback as +N for visual output, but also pass a semantic name/alt (e.g. "2 more") so the accessible label is meaningful.

[shellscape]

@CharlieHelps fix both improvements 1 and 2

[charliecreates]

@shellscape done — I fixed both improvements and pushed them to the PR branch.

• Improvement 1: overflow +N token now inherits avatar sizing (from width/height props or style dimensions) so truncation output stays dimensionally consistent.
• Improvement 2: overflow token now keeps the visual +N fallback while exposing semantic accessible text via name (e.g. 2 more).
• Added focused coverage for inherited sizing + semantic naming and updated the truncation snapshot.

Pushed commit: 7d47983

Validation run:

• pnpm exec moon run plugin-inline:build plugin-minify:build plugin-pretty:build
• pnpm exec moon run jsx-email:test -- avatar-group.test.tsx -u
• pnpm exec moon run jsx-email:test -- avatar.test.tsx avatar-group.test.tsx