Add support for Map<String, File> in @part annotation for dynamic multipart field names (#848)

* Initial plan

* Add support for Map<String, File> in @part annotation for dynamic field names

Co-authored-by: trevorwang <121966+trevorwang@users.noreply.github.com>

* Add example for Map<String, File> usage in multipart uploads

Co-authored-by: trevorwang <121966+trevorwang@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: trevorwang <121966+trevorwang@users.noreply.github.com>

Author: Copilot

README.md

@@ -246,6 +246,33 @@ The `@PartMap()` annotation accepts a `Map<String, dynamic>` with keys in the fo
   - `fileName` defaults to the file's actual name (extracted from file path)
   - `contentType` defaults to `null` (Dio will auto-detect based on file extension)
 
+#### Dynamic Field Names for Multiple Files
+
+Use `@Part()` with `Map<String, File>` to upload multiple files with dynamic field names:
+
+```dart
+  @POST('/api/files')
+  @MultiPart()
+  Future<void> uploadFiles(@Part() Map<String, File> files);
+  
+  // Usage - Upload multiple files with custom field names
+  await client.uploadFiles({
+    'image[0]': File('/path/to/photo1.jpg'),
+    'image[1]': File('/path/to/photo2.jpg'),
+    'document': File('/path/to/report.pdf'),
+  });
+```
+
+This feature also supports:
+- `Map<String, MultipartFile>` - For files already wrapped in MultipartFile
+- `Map<String, List<int>>` - For raw byte data
+- Nullable maps: `Map<String, File>?`
+
+**Use cases:**
+- Uploading arrays of files where each file needs a unique indexed name (e.g., `image[0]`, `image[1]`)
+- Uploading files to endpoints that require specific field names determined at runtime
+- Sending multiple files of different types in a single request
+
 ### Get original HTTP response
 
 ```dart

example/lib/example.dart

@@ -138,6 +138,23 @@ abstract class RestClient {
     @PartMap() Map<String, dynamic>? metadata,
   });
 
+  /// Example of uploading multiple files with dynamic field names.
+  ///
+  /// This is useful when you need to send files with indexed names like
+  /// `image[0]`, `image[1]`, etc., or when field names are determined at runtime.
+  ///
+  /// Usage:
+  /// ```dart
+  /// await client.uploadMultipleFiles({
+  ///   'image[0]': File('/path/to/photo1.jpg'),
+  ///   'image[1]': File('/path/to/photo2.jpg'),
+  ///   'document': File('/path/to/report.pdf'),
+  /// });
+  /// ```
+  @POST('http://httpbin.org/post')
+  @MultiPart()
+  Future<void> uploadMultipleFiles(@Part() Map<String, File> files);
+
   @Headers(<String, String>{'accept': 'image/jpeg'})
   @GET('http://httpbin.org/image/jpeg')
   @DioResponseType(ResponseType.bytes)

generator/lib/src/generator.dart

@@ -2548,16 +2548,80 @@ if (T != dynamic &&
     final parts = _getAnnotations(m, retrofit.Part);
     if (parts.isNotEmpty) {
       if (parts.length == 1 && parts.keys.first.type.isDartCoreMap) {
-        blocks.add(
-          declareFinal(dataVar)
-              .assign(
-                refer('FormData').newInstanceNamed('fromMap', [
-                  CodeExpression(Code(parts.keys.first.displayName)),
-                ]),
-              )
-              .statement,
-        );
-        return;
+        final mapParam = parts.keys.first;
+        final mapValueType = _genericListOf(mapParam.type)?[1];
+        
+        // Check if Map value type is File, MultipartFile, or List<int>
+        final isFileMap = mapValueType != null && _isAssignable(io.File, mapValueType);
+        final isMultipartFileMap = mapValueType != null && _isMultipartFile(mapValueType);
+        final isByteListMap = mapValueType != null && _displayString(mapValueType) == 'List<int>';
+        
+        if (isFileMap || isMultipartFileMap || isByteListMap) {
+          // Handle Map<String, File>, Map<String, MultipartFile>, or Map<String, List<int>>
+          blocks.add(
+            declareFinal(dataVar).assign(refer('FormData').newInstance([])).statement,
+          );
+          
+          final nullableCheck = mapParam.type.nullabilitySuffix == NullabilitySuffix.question;
+          
+          if (nullableCheck) {
+            blocks.add(Code('if (${mapParam.displayName} != null) {'));
+          }
+          
+          if (isFileMap) {
+            // Generate code for Map<String, File>
+            blocks.add(Code('''
+    ${mapParam.displayName}.forEach((key, value) {
+      $dataVar.files.add(
+        MapEntry(
+          key,
+          MultipartFile.fromFileSync(
+            value.path,
+            filename: value.path.split(Platform.pathSeparator).last,
+          ),
+        ),
+      );
+    });
+'''));
+          } else if (isMultipartFileMap) {
+            // Generate code for Map<String, MultipartFile>
+            blocks.add(Code('''
+    ${mapParam.displayName}.forEach((key, value) {
+      $dataVar.files.add(MapEntry(key, value));
+    });
+'''));
+          } else if (isByteListMap) {
+            // Generate code for Map<String, List<int>>
+            blocks.add(Code('''
+    ${mapParam.displayName}.forEach((key, value) {
+      $dataVar.files.add(
+        MapEntry(
+          key,
+          MultipartFile.fromBytes(value),
+        ),
+      );
+    });
+'''));
+          }
+          
+          if (nullableCheck) {
+            blocks.add(const Code('}'));
+          }
+          
+          return;
+        } else {
+          // Default behavior for Map<String, dynamic> - use FormData.fromMap
+          blocks.add(
+            declareFinal(dataVar)
+                .assign(
+                  refer('FormData').newInstanceNamed('fromMap', [
+                    CodeExpression(Code(mapParam.displayName)),
+                  ]),
+                )
+                .statement,
+          );
+          return;
+        }
       }
 
       blocks.add(

generator/test/src/generator_test_src.dart

@@ -3017,6 +3017,69 @@ abstract class PartMapWithListIntTest {
   });
 }
 
+@ShouldGenerate(
+  r'''
+    files.forEach((key, value) {
+      _data.files.add(
+        MapEntry(
+          key,
+          MultipartFile.fromFileSync(
+            value.path,
+            filename: value.path.split(Platform.pathSeparator).last,
+          ),
+        ),
+      );
+    });
+''',
+  contains: true,
+)
+@RestApi(baseUrl: 'https://httpbin.org/')
+abstract class PartWithMapStringFileTest {
+  @POST('/upload')
+  @MultiPart()
+  Future<String> uploadFiles(@Part() Map<String, File> files);
+}
+
+@ShouldGenerate(
+  r'''
+    if (files != null) {
+      files.forEach((key, value) {
+        _data.files.add(
+          MapEntry(
+            key,
+            MultipartFile.fromFileSync(
+              value.path,
+              filename: value.path.split(Platform.pathSeparator).last,
+            ),
+          ),
+        );
+      });
+    }
+''',
+  contains: true,
+)
+@RestApi(baseUrl: 'https://httpbin.org/')
+abstract class PartWithNullableMapStringFileTest {
+  @POST('/upload')
+  @MultiPart()
+  Future<String> uploadFiles(@Part() Map<String, File>? files);
+}
+
+@ShouldGenerate(
+  r'''
+    files.forEach((key, value) {
+      _data.files.add(MapEntry(key, value));
+    });
+''',
+  contains: true,
+)
+@RestApi(baseUrl: 'https://httpbin.org/')
+abstract class PartWithMapStringMultipartFileTest {
+  @POST('/upload')
+  @MultiPart()
+  Future<String> uploadFiles(@Part() Map<String, MultipartFile> files);
+}
+
 @ShouldGenerate(
   '''
   @override