docs(ui): update migration with learnings

[renefloor]

Submit a pull request

CLA

• I have signed the Stream CLA (required).
• The code changes follow best practices
• Code changes are tested (add some information if not applicable)

Description of the pull request

Tested migrating an app and added some missing migration docs in here.

Summary by CodeRabbit

• Documentation
  • Updated migration guides for reaction icon handling, including the move from reactionIcons to a resolver-based flow for rendering emojis.
  • Added an “Audio Recorder Migration” section covering the redesigned recorder UI and the replacement for the recording/playback timer.
  • Expanded message-widget and message-list customization guidance, emphasizing app-wide component factory usage and clarifying messageBuilder per-list precedence.
  • Enhanced the v10 migration checklist, including the streamChatThemeData: → themeData: rename and composer/attachments customization steps.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f5c32910-ec50-4e1b-adeb-c7550eefc446

📥 Commits

Reviewing files that changed from the base of the PR and between 2ef26f9 and e4351b4.

📒 Files selected for processing (2)

• migrations/redesign/message_composer.md
• migrations/redesign/message_widget.md

✅ Files skipped from review due to trivial changes (2)

• migrations/redesign/message_widget.md
• migrations/redesign/message_composer.md

---

📝 Walkthrough

Walkthrough

Five migration guide Markdown files receive documentation-only additions covering five breaking-change areas and the new component factory customization pattern in the v10 redesign: renaming the StreamChat constructor parameter streamChatThemeData to themeData, introducing the component factory as the preferred app-wide message-widget customization mechanism, adding custom composer implementation guidance, updating message list customization to use the component factory, explaining reaction icon resolver replacement, documenting audio recorder widget redesign (StreamAudioRecorderButton → StreamAudioRecorder, RecordingTimer → PlaybackTimerText), and clarifying message bubble color theming.

Changes

Migration Guide Documentation

Layer / File(s)	Summary
StreamChat widget themeData rename migrations/v10-migration.md	Adds a StreamChat Widget TOC entry, Quick Reference row marking streamChatThemeData: → themeData:, and a new subsection with before/after code snippets documenting the v10.0.0 constructor parameter rename.
Component factory architecture and global customization migrations/redesign/message_widget.md, migrations/v10-migration.md	Documents the component factory as the preferred v10 approach for app-wide message-widget customization via StreamComponentFactory registered on StreamChat, explains StreamMessageItem now resolves from the factory, clarifies showReactionTail removal means tail auto-shows, contrasts factory vs. per-list messageBuilder overrides, and provides guidance on wrapping default actions using DefaultStreamMessageItem.
Message list customization with component factory migrations/redesign/message_list.md	Updates TOC and Quick Reference, expands "Customizing the Message Item" section introducing the preferred StreamComponentBuilders factory registration on StreamChat, documents per-list messageBuilder override behavior, explains precedence rules for how messageBuilder calls StreamMessageItem.fromProps() through the factory, and updates migration checklist.
Message widget bubble color theming migrations/redesign/message_widget.md	Updates per-list messageBuilder guidance showing how it wraps message UI while invoking the component factory, introduces "Changing the own-message bubble color" section specifying bubble background source (StreamColorScheme.brand.shade100), shows app-wide StreamColorSwatch.fromColor override in StreamTheme, and notes StreamMessageBubbleStyle for per-alignment control.
Custom composer implementations migrations/v10-migration.md	Adds guidance explaining inline attachment picker controls are unavailable outside StreamMessageComposer, demonstrates programmatic attachment addition via image_picker and XFile.toAttachment(type:) with StreamMessageComposerController.
Audio recorder widget redesign migrations/redesign/message_composer.md	Adds TOC entry and full "Audio Recorder Migration" section documenting StreamAudioRecorderButton removal, the StreamAudioRecorder builder-callback API receiving AudioRecorderState and pre-built button, the RecordingTimer → PlaybackTimerText rename with mapping table, and two new checklist items.
Reaction icon resolver migration migrations/redesign/headers_and_icons.md	Adds "Removed: reactionIcons" section documenting List<StreamReactionIcon> replacement with reactionIconResolver, shows resolver.resolve(type) → StreamEmoji/StreamEmojiSize usage snippet, and appends matching checklist item.
v10.0.0 migration checklist consolidation migrations/v10-migration.md	Adds two new checklist items: one for renaming StreamChat's streamChatThemeData: → themeData:, and one for consolidating app-wide messageBuilder usage into component factory registration.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• GetStream/stream-chat-flutter#2674: Implements the StreamMessageListView constructor refactor (moving list flags/builders into StreamMessageListViewConfiguration/StreamMessageListViewBuilders) that this PR documents in migrations/redesign/message_list.md.
• GetStream/stream-chat-flutter#2680: Updates the same migration docs for StreamMessageItem/StreamMessageListView component-factory vs messageBuilder customization flow in migrations/redesign/message_widget.md and migrations/redesign/message_list.md.

Suggested reviewers

• xsahil03x

Poem

🐇 Hop, hop, the docs grow bright,
themeData renamed, the path set right,
A factory of components, app-wide and keen,
Reaction icons, audio recorders between,
Bubble colors bloom from brand's own hue—
Migration wisdom, crystal and true! 🌸

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: updating migration documentation based on practical testing learnings, which aligns with all file modifications.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/improve-migration-docs

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@migrations/redesign/message_composer.md`:
- Around line 562-612: The documentation incorrectly attributes
PlaybackTimerText to stream_core_flutter when it actually comes from
stream_chat_flutter. In the section explaining the PlaybackTimerText replacement
for RecordingTimer, remove the phrase "from stream_core_flutter" that appears in
the sentence introducing PlaybackTimerText. The widget should be documented as
coming from stream_chat_flutter (which is already correctly stated in the
re-export note at the end), so update the text around line 606 to reflect that
PlaybackTimerText is part of stream_chat_flutter, not stream_core_flutter.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 58b9744b-062e-4463-b6ee-8ba5f88706b5

📥 Commits

Reviewing files that changed from the base of the PR and between 0b4f95b and dcdae42.

📒 Files selected for processing (4)

• migrations/redesign/headers_and_icons.md
• migrations/redesign/message_composer.md
• migrations/redesign/message_widget.md
• migrations/v10-migration.md

[xsahil03x]

I think we should also mention about StreamMessageLayoutProperty here, as that provides the info on the actual message alignment in the list