feat(ui): add semanticsLabel to StreamAvatar / Group / Stack

[xsahil03x]

Summary

• Adds optional semanticsLabel to StreamAvatar, StreamAvatarGroup, and StreamAvatarStack.
• null (default) composes through — placeholder / children speak per their own contract.
• Non-null exposes the widget as a single labeled image node and drops descendants (initials, icons, +N overflow badge) from the semantics tree.

Linear tickets

• Contributes to FLU-590 — channel list item announces avatar initial and repeats content without context. Closed by the downstream chat-side PR feat(ui): channel-list & message-preview accessibility pass stream-chat-flutter#2827.

Test plan

• flutter test in stream_core_flutter — new avatar / group / stack tests pass.
• Manual pass with TalkBack / VoiceOver on a fixture app.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Avatar accessibility semantics

Layer / File(s)	Summary
Individual avatar semantics packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart, packages/stream_core_flutter/test/components/avatar/stream_avatar_test.dart	StreamAvatar accepts an optional semanticsLabel; non-null labels expose a labeled image and exclude placeholder initials, with widget tests covering default, excluded, and labeled behavior.
Group and stack semantics packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_group.dart, packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_stack.dart, packages/stream_core_flutter/CHANGELOG.md	Avatar groups and stacks accept optional labels that collapse child and overflow semantics into one labeled image node; the changelog documents the behavior.
Group and stack accessibility tests packages/stream_core_flutter/test/components/avatar/stream_avatar_group_test.dart, packages/stream_core_flutter/test/components/avatar/stream_avatar_stack_test.dart	Widget tests verify child-label propagation, parent-label semantics, and suppression of overflow badge semantics.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: renefloor

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly states the main change: adding semanticsLabel to the avatar, group, and stack components.
Description check	✅ Passed	It covers the summary, ticket reference, and test plan; only the CLA checklist and screenshots section from the template are missing.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/avatar-a11y

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 47.39%. Comparing base (59b3f4e) to head (c711bba).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #132      +/-   ##
==========================================
+ Coverage   44.53%   47.39%   +2.85%     
==========================================
  Files         178      178              
  Lines        7243     7250       +7     
==========================================
+ Hits         3226     3436     +210     
+ Misses       4017     3814     -203     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

🧹 Nitpick comments (1)

packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart (1)

214-256: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the repeated Semantics-wrap block into a shared helper. The same if (props.semanticsLabel case final label?) { ... Semantics(label: label, image: true, excludeSemantics: true, child: x) ... } block is copy-pasted identically in all three widget files.

• packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart#L214-L256: extract this block into a shared Widget wrapWithSemanticsLabel(Widget child, String? label) helper (or similar) and call it here.
• packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_group.dart#L172-L213: call the same shared helper instead of duplicating the block.
• packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_stack.dart#L212-L245: call the same shared helper instead of duplicating the block.

♻️ Example helper

Widget wrapWithSemanticsLabel(Widget child, String? label) {
  if (label == null) return child;
  return Semantics(
    label: label,
    image: true,
    excludeSemantics: true,
    child: child,
  );
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart`
around lines 214 - 256, Extract the duplicated semantics wrapper into a shared
wrapWithSemanticsLabel helper that returns the child unchanged for a null label
and otherwise applies Semantics with the existing label, image, and
excludeSemantics settings. In
packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart#L214-L256,
replace the local if block with the helper; make the same replacement in
packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_group.dart#L172-L213
and
packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_stack.dart#L212-L245.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart`:
- Around line 214-256: Extract the duplicated semantics wrapper into a shared
wrapWithSemanticsLabel helper that returns the child unchanged for a null label
and otherwise applies Semantics with the existing label, image, and
excludeSemantics settings. In
packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart#L214-L256,
replace the local if block with the helper; make the same replacement in
packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_group.dart#L172-L213
and
packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_stack.dart#L212-L245.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6961d9ec-af6d-4079-9183-ec8444cb3a1c

📥 Commits

Reviewing files that changed from the base of the PR and between 59b3f4e and c711bba.

📒 Files selected for processing (7)

• packages/stream_core_flutter/CHANGELOG.md
• packages/stream_core_flutter/lib/src/components/avatar/stream_avatar.dart
• packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_group.dart
• packages/stream_core_flutter/lib/src/components/avatar/stream_avatar_stack.dart
• packages/stream_core_flutter/test/components/avatar/stream_avatar_group_test.dart
• packages/stream_core_flutter/test/components/avatar/stream_avatar_stack_test.dart
• packages/stream_core_flutter/test/components/avatar/stream_avatar_test.dart