[image_picker] Handle limit: 1 in pickMultiImage and pickMultipleMedia gracefully

[yashas-hm]

Summary

Fixes flutter/flutter#187347

pickMultiImage(limit: 1) and pickMultipleMedia(limit: 1) previously
threw:

  Invalid argument (limit): cannot be lower than 2: 1

because MultiImagePickerOptions and MediaOptions in the platform
interface both reject limit < 2.

Fix

When limit == 1, the facade now delegates to the equivalent
single-item picker instead of forwarding to the platform:

• pickMultiImage(limit: 1) → delegates to pickImage(source: ImageSource.gallery, ...)
• pickMultipleMedia(limit: 1) → delegates to pickMedia(...)

The result is wrapped in a single-element list, or an empty list if the
user cancelled. limit <= 0 still throws as before.

Why the facade, not the platform interface

The limit < 2 guard in MultiImagePickerOptions and MediaOptions
exists because the underlying platform multi-picker APIs genuinely do not
support selecting exactly one item, they require at least two. Relaxing
the validation in the platform interface would push the burden onto every
platform implementation to handle a case their native API may not
support, risking silent misbehaviour on some platforms.

The facade (image_picker) is the right place for this: it already owns
the user-facing API contract and can transparently route limit: 1 to
the well-tested single-item pickers without touching any platform code.

Tests

• limit: 1 delegates to getImageFromSource with ImageSource.gallery (pickMultiImage)
• limit: 1 delegates to getMedia with allowMultiple: false (pickMultipleMedia)
• Both return a single-element list when an item is picked, empty list when cancelled
• limit: 0 and limit: -1 still throw ArgumentError
• All existing tests continue to pass

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Closes flutter/flutter#187347

Footnotes

1. Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

[gemini-code-assist]

Code Review

This pull request updates ImagePicker to delegate to single-item pickers (pickImage and pickMedia) when pickMultiImage or pickMultipleMedia is called with a limit of 1, preventing an ArgumentError since multi-image selection requires a limit of at least 2. The changes include corresponding unit tests and a CHANGELOG update. The reviewer recommends updating the CHANGELOG entry to explicitly mention the fix for pickMultipleMedia alongside pickMultiImage.

[gemini-code-assist]

The CHANGELOG entry only mentions pickMultiImage(limit: 1), but the PR also fixes pickMultipleMedia(limit: 1). Please update the CHANGELOG to reflect both fixes.

For example:

* Fixes `pickMultiImage(limit: 1)` and `pickMultipleMedia(limit: 1)` throwing an `ArgumentError` by delegating to single-item pickers when `limit` is exactly 1, since the platform interface requires `limit >= 2` for multi-selection.

[stuartmorgan-g]

[x] I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under1.

Thanks for the contribution! You’ve checked boxes in the PR checklist above that are not reflected in this PR, so I’m assuming this is a work in progress and am marking it as a Draft. Please review the checklist, updating the PR as appropriate, and when the state of the PR as posted reflects the checklist please feel free to mark it as ready for review.