bottom_sheet: Clarify doc about behavior when useSafeArea is false

[chrisbobbe]

As discussed at #122225 (comment), this is a docs change meant to help people in the absence of a fix for #121752, which is being closed as WONTFIX.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

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

[chrisbobbe]

@gnprice

[gnprice]

Thanks for sending this! Comment below.

I think it'd also be good to try to make this behavior clear in the short paragraph that summarizes useSafeArea in the class's overall doc:

/// The [useSafeArea] parameter specifies whether the sheet will avoid system
/// intrusions on the top, left, and right. If false, no SafeArea is added
/// and the top padding is consumed using [MediaQuery.removePadding].
/// Defaults to false.

The information is there if you understand the implications of "top padding is consumed". But I found that verb "consumed" ambiguous before I'd spent a lot of time reading through how SafeArea and MediaQuery interact. And because this specific behavior of ModalBottomSheetRoute is somewhat peculiar, that makes it unusually difficult to figure out when one is still trying to work out precisely what the terminology means and how the underlying pieces fit together.

Here's one version: "If false, no [SafeArea] is added; and [MediaQuery.removePadding] is applied to the top, so that system intrusions at the top will not be avoided by a [SafeArea] inside the bottom sheet either."

[gnprice]

From the discussion (particularly around #122225 (comment) ), it seems like the best advice for most developers will be to set useSafeArea: true. So we can perhaps foreground that over the workaround of looking at MediaQuery.of from an outer BuildContext.

I think the fact that the top padding gets suppressed in MediaQuery is among the key facts this documentation should make clear. This PR's version does say that, but it's within a parenthetical that's framed as explaining how a "callers may wish to" suggestion would behave, which means that a reader scanning for the pure facts about this widget's behavior may overlook it. The version in main has it framed appropriately, but then the "isn't exposed to" wording doesn't make clear what it's saying. So we should take an unambiguous description like in this PR revision, and move it up the information tree to be placed among the basic facts of what this property does.

Here's a version that does both of those:

Suggested change

	/// If false, the bottom sheet will extend through any system intrusions
	/// at the top, left, and right, and callers may wish to pad those
	/// with their own [SafeArea] in [builder]. (Such a [SafeArea] will not
	/// actually provide top padding, because [builder] will be run
	/// under a [MediaQuery.removePadding] that has `removeTop: true`.
	/// To work around, wrap the [SafeArea] in a [MediaQuery] that restates an
	/// ambient [MediaQueryData] from outside [builder].)
	/// If false, the bottom sheet will extend through any system intrusions
	/// at the top, left, and right.
	///
	/// If false, then moreover [MediaQuery.removePadding] will be used
	/// to remove top padding, so that a [SafeArea] widget inside the bottom
	/// sheet will have no effect at the top edge. If this is undesired, consider
	/// setting [useSafeArea] to true. Alternatively, wrap the [SafeArea] in a
	/// [MediaQuery] that restates an ambient [MediaQueryData] from outside [builder].

[chrisbobbe]

Thanks for the review, with those helpful suggestions! Revision pushed, using the text you suggested.

[gnprice]

Thanks! One small comment remaining but otherwise LGTM.

[gnprice]

Should keep the "Defaults to false" line — that's helpful context too.

[chrisbobbe]

Thanks for the review! Revision pushed, with that bit added back.

[goderbauer]

LGTM