Skip to content

Commit f9d454c

Browse files
xsahil03xxsahil03x
committed
chore(repo): add migration guide
1 parent 39bc67b commit f9d454c

File tree

1 file changed

+256
-0
lines changed

1 file changed

+256
-0
lines changed

‎migrations/v10-migration.md

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# 🚀 Flutter SDK v10.0 Migration Guide
2+
3+
**Important!** This guide details breaking changes in **SDK v10.0**. Carefully follow each step to ensure a smooth and efficient migration.
4+
5+
---
6+
7+
## 📋 Breaking Changes Overview
8+
9+
This guide includes breaking changes grouped by release phase:
10+
11+
### 🚧 v10.0.0-beta.1
12+
13+
- [**StreamReactionPicker**](#-streamreactionpicker-refactor)
14+
- [**StreamMessageAction**](#-streammessageaction-refactor)
15+
- [**StreamMessageReactionsModal**](#-streammessagereactionsmodal-refactor)
16+
- [**StreamMessageWidget**](#-streammessagewidget-refactor)
17+
18+
---
19+
20+
## 🧪 Migration for v10.0.0-beta.1
21+
22+
### 🛠 StreamReactionPicker Refactor
23+
24+
The reaction picker has been refactored for modularity, flexibility, and explicit reaction handling.
25+
26+
### Key Changes:
27+
**Key Changes:**
28+
- New `StreamReactionPicker.builder` constructor
29+
- Added properties: `padding`, `scrollable`, `borderRadius`
30+
- Removed automatic reaction handling → use `onReactionPicked`
31+
32+
### Migration Steps:
33+
34+
**Before:**
35+
```dart
36+
StreamReactionPicker(
37+
message: message,
38+
);
39+
```
40+
41+
**After (Recommended using Builder):**
42+
```dart
43+
StreamReactionPicker.builder(
44+
context,
45+
message,
46+
(Reaction reaction) {
47+
// Explicitly handle reaction here
48+
},
49+
);
50+
```
51+
52+
**After (Alternative Direct Configuration):**
53+
```dart
54+
StreamReactionPicker(
55+
message: message,
56+
reactionIcons: StreamChatConfiguration.of(context).reactionIcons,
57+
onReactionPicked: (Reaction reaction) {
58+
// Explicit reaction handling
59+
},
60+
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
61+
scrollable: true,
62+
borderRadius: BorderRadius.circular(24),
63+
);
64+
```
65+
66+
> ⚠️ **Important:**
67+
> Automatic reaction handling has been removed. You must explicitly handle reactions.
68+
69+
### Summary of Changes:
70+
71+
| Aspect | Previous | New Behavior |
72+
|------------------------|---------------|----------------------------------------------|
73+
| Reaction Handling | Automatic | Explicit (`onReactionPicked`) |
74+
| Platform Constructor | None | Yes (`StreamReactionPicker.builder`) |
75+
| Customization | Limited | Enhanced (`padding`, `borderRadius`, `scrollable`) |
76+
77+
---
78+
79+
## ✅ StreamMessageAction Refactor
80+
81+
The `StreamMessageAction` is refactored for type safety, centralization, and enhanced customization.
82+
83+
### Key Changes:
84+
- **Type-safe Actions:** Now generic (`StreamMessageAction<T extends MessageAction>`) for stronger typing.
85+
- **Centralized Action Handling:** Individual action callbacks replaced with centralized handling via `onCustomActionTap`.
86+
- **Customization Options:** New props:
87+
- `isDestructive`: Flag destructive actions.
88+
- `iconColor`: Customize icon color.
89+
- `titleTextColor`: Title color customization.
90+
- `titleTextStyle`: Title text styling.
91+
- `backgroundColor`: Background color customization.
92+
93+
### Migration Steps:
94+
95+
**Before:**
96+
```dart
97+
final customAction = StreamMessageAction(
98+
title: Text('Custom Action'),
99+
leading: Icon(Icons.settings),
100+
onTap: (Message message) {
101+
// Handle action
102+
},
103+
);
104+
105+
StreamMessageWidget(
106+
message: message,
107+
customActions: [customAction],
108+
);
109+
```
110+
111+
**After (Recommended - Type-safe):**
112+
```dart
113+
final customAction = StreamMessageAction<CustomMessageAction>(
114+
action: CustomMessageAction(
115+
message: message,
116+
extraData: {'type': 'custom_action'},
117+
),
118+
title: Text('Custom Action'),
119+
leading: Icon(Icons.settings),
120+
isDestructive: false,
121+
iconColor: Colors.blue,
122+
);
123+
124+
StreamMessageWidget(
125+
message: message,
126+
customActions: [customAction],
127+
onCustomActionTap: (CustomMessageAction action) {
128+
// Handle action based on extraData
129+
},
130+
);
131+
```
132+
133+
> ⚠️ **Important:**
134+
> Individual `onTap` callbacks have been removed. Always use centralized `onCustomActionTap`.
135+
136+
### Summary of Changes:
137+
138+
| Aspect | Previous | New Behavior |
139+
|------------------|--------------------------------|------------------------------------------|
140+
| Action Typing | Untyped | Generic (type-safe) |
141+
| Action Handling | Individual `onTap` callbacks | Centralized (`onCustomActionTap`) |
142+
| Customization | Limited | Enhanced (`iconColor`, `backgroundColor`, etc.) |
143+
144+
---
145+
146+
## ✅ StreamMessageReactionsModal Refactor
147+
148+
Refactored to leverage `StreamMessageModal`, improving consistency and explicit reaction handling.
149+
150+
### Key Changes:
151+
- **Base Widget Changed:** Now uses `StreamMessageModal` internally.
152+
- **Removed `messageTheme` Property:** Theme now automatically derived from `reverse`.
153+
- **Explicit Reaction Handling:** Reactions must be handled explicitly through `onReactionPicked`.
154+
155+
### Migration Steps:
156+
157+
**Step 1: Remove `messageTheme`:**
158+
```dart
159+
// Before
160+
StreamMessageReactionsModal(
161+
message: message,
162+
messageWidget: myMessageWidget,
163+
messageTheme: myCustomMessageTheme, // remove this
164+
reverse: true,
165+
);
166+
167+
// After
168+
StreamMessageReactionsModal(
169+
message: message,
170+
messageWidget: myMessageWidget,
171+
reverse: true,
172+
);
173+
```
174+
175+
**Step 2: Explicit Reaction Handling:**
176+
```dart
177+
// Before (automatic handling)
178+
StreamMessageReactionsModal(
179+
message: message,
180+
messageWidget: myMessageWidget,
181+
// reactions handled internally
182+
);
183+
184+
// After (explicit handling)
185+
StreamMessageReactionsModal(
186+
message: message,
187+
messageWidget: myMessageWidget,
188+
onReactionPicked: (SelectReaction reactionAction) {
189+
// Explicitly send or delete reaction
190+
},
191+
);
192+
```
193+
194+
> ⚠️ **Important:**
195+
> Automatic handling is removed—explicit reaction handling required.
196+
197+
### Summary of Changes:
198+
199+
| Aspect | Previous | New Behavior |
200+
|--------------------|---------------------------|------------------------------------|
201+
| Reaction Handling | Automatic | Explicit (`onReactionPicked`) |
202+
| Base Widget | Custom implementation | Uses `StreamMessageModal` |
203+
| `messageTheme` Prop| Required | Removed; derived from `reverse` |
204+
205+
---
206+
207+
## ✅ StreamMessageWidget Refactor
208+
209+
The `StreamMessageWidget` has been simplified by removing the `showReactionTail` parameter and always showing the reaction picker tail when the reaction picker is visible.
210+
211+
### Key Changes:
212+
- **Removed `showReactionTail` Parameter:** The parameter is no longer needed as the tail is always shown when the reaction picker is visible.
213+
- **Automatic Tail Display:** The reaction picker tail now automatically appears when the reaction picker is visible, providing consistent UX.
214+
215+
### Migration Steps:
216+
217+
**Before:**
218+
```dart
219+
StreamMessageWidget(
220+
message: message,
221+
showReactionTail: true, // Remove this parameter
222+
);
223+
224+
// or
225+
226+
StreamMessageWidget(
227+
message: message,
228+
showReactionTail: false, // Remove this parameter
229+
);
230+
```
231+
232+
**After:**
233+
```dart
234+
StreamMessageWidget(
235+
message: message,
236+
// showReactionTail parameter removed - tail shown automatically
237+
);
238+
```
239+
240+
> ⚠️ **Important:**
241+
> The `showReactionTail` parameter has been completely removed. The reaction picker tail will always be shown when the reaction picker is visible, ensuring consistent behavior across your app.
242+
243+
### Summary of Changes:
244+
245+
| Aspect | Previous | New Behavior |
246+
|------------------------|-----------------------------------|----------------------------------------------|
247+
| Tail Display Control | Manual (`showReactionTail`) | Automatic (always shown when picker visible) |
248+
| Parameter Required | Optional boolean parameter | Parameter removed |
249+
| Consistency | Could be inconsistent | Always consistent |
250+
251+
---
252+
253+
✅ **You're ready to migrate!**
254+
Ensure you test your application thoroughly after applying these changes.
255+
256+
---

0 commit comments

Comments
 (0)