Hi @slaci thanks for the contribution!

I am not convinced about adding another two parameters to the method, specially title, which added to text and subject just becomes more confusing what does what on which platform.

The share method definitely needs a refactor and a parameter cleanup in some way. Maybe this PR is an opportunity to do that?

There is some discussion about that in #3307

The contribution guide says features for only one platform won't be accepted, but I still want to try.

That's true, maybe there is a way to provide a preview thumbnail on iOS as well?

I like the idea of adding this functionality as it is something that Android offers by default. But agree with Miguel that we might think about the API more here.

I can extract the thumbnail to a SharePlusAndroidSettings class or something. The sharePositionOrigin could go into an IOS or Apple one, but that would be a breaking change (or the parameter could be deprecated first of course).

The rest of the parameters are problematic, as the new title param is not the odd one, but the subject. Android uses the title for the EXTRA_TITLE parameter and the web uses it as the title parameter of the Web Share API. For iOS I may need some more research indeed, but as I see that could also use the title. There is the thumbnailImageForActivityType method which currently returns the image when an image is shared. It may be worth to check how this works (what happens if I pass a thumbnail to it when sharing text). When an NSURL is shared, then the activityViewControllerLinkMetadata callback runs and creates an LPLinkMetadata which contains a title + thumbnail, but this is sadly only for urls (as far as I understand).

I have spent some hours checking the iOS thumbnail possibilities, but sadly I couldn't figure out when the mentioned thumbnailImageForActivityType runs.

There are multiple reports about this, but sadly without any answers: SO | Apple Forum

From the docs it seems like it depends on the target app (though not 💯 ), like the subject (eg. the subjectForActivityType runs for the Mail app), but I couldn't find any app that would trigger the thumbnail callback or maybe it is totally bugged on iOS 18.

I haven't played with the title too much yet, but currently the subject is used for the LPLinkMetadata's title when it is available which is incosistent with my changes. However it is only used for shareXFiles (because files are provided as NSURL-es, so they have this metadata) where I don't pass the title as providing a title when sharing files didn't do anything on Android nor web (will need to check what happens on iOS if anything in this case).

So if I could make the thumbnail work on iOS, then it could stay as a common option, otherwise I guess I would need to extract it to a Platform specific option class.

Thanks for looking into it @slaci !

Re: params, I'm thinking that just having a single ShareParams class with all options may be the easiest, unify it all into a single share(ShareParams) method, and that should go all the way down. That will allow us to use any of the provided optional params no matter if sharing a uri, text, or files. We may need to add some asserts to enforce providing certain combination of params, but that would be it.

class ShareParams {
  final String? text;

  /// Used as share sheet title where supported (e.g. EXTRA_TITLE on Android)
  final String? title;

  /// Only used as email subject where supported (e.g. EXTRA_SUBJECT on Android)
  final String? subject;

  /// Only used in Android as preview thumbnail
  final XFile? previewThumbnail;

  /// Only used in iPad and Mac as share sheet origin
  final Rect? sharePositionOrigin;

  /// Share a URI, alternative to sharing [text]
  final Uri? uri;

  /// Share multiple files, can be used in combination with [text]
  final List<XFile>? files;
  final List<String>? fileNameOverrides;

  ShareParams({
    this.text,
    this.subject,
    this.extraTitle,
    this.previewThumbnail,
    this.sharePositionOrigin,
    this.uri,
    this.files,
    this.fileNameOverrides,
  });
}

Since we would be at it, I'd like to unify all methods into one, and to make Share class instantiable, instead of providing a static method (some people have asked this to be able to mock it)

Added a comment on #3307 (comment) your feedback would be appreciated!