[cross_file] Document native mimeType behavior

packages/cross_file/README.md

@@ -25,6 +25,13 @@ print('Content of the file: $fileContent');
 
 You will find links to the API docs on the [pub page](https://pub.dev/packages/cross_file).
 
+## MIME types
+
+On web, `mimeType` reflects browser-provided file metadata when available.
+Native implementations do not infer MIME types from file paths or contents.
+On native platforms, `mimeType` returns the value explicitly passed to the
+`XFile` constructor or `XFile.fromData`, if any.
+
 ## Web Limitations
 
 `XFile` on the web platform is backed by [Blob](https://api.dart.dev/be/180361/dart-html/Blob-class.html)

packages/cross_file/lib/src/types/base.dart

@@ -46,6 +46,10 @@ abstract class XFileBase {
   }
 
   /// For web, it may be necessary for a file to know its MIME type.
+  ///
+  /// Native implementations do not infer this value from the file path or
+  /// contents. On those platforms, this returns the value passed to the
+  /// implementation's constructor, if any.
   String? get mimeType {
     throw UnimplementedError('.mimeType has not been implemented.');
   }

packages/cross_file/lib/src/types/io.dart

@@ -24,6 +24,9 @@ class XFile extends XFileBase {
   /// [length] is ignored; the parameter exists only to match the web version of
   /// the constructor.
   ///
+  /// [mimeType] is not inferred from [path]. The [mimeType] property returns the
+  /// value explicitly provided here, if any.
+  ///
   // ignore: use_super_parameters
   XFile(
     String path, {
@@ -42,6 +45,8 @@ class XFile extends XFileBase {
   ///
   /// [name] is ignored; the parameter exists only to match the web version of
   /// the constructor.
+  ///
+  /// The [mimeType] property returns the value explicitly provided here, if any.
   XFile.fromData(
     Uint8List bytes, {
     String? mimeType,