Document that Positioned also works inside an Overlay - #190607

Good catch on the RenderObjectWidget point — OverlayState.build returns _Theater, so the path from a Positioned up to the Overlay widget does cross a RenderObjectWidget, and what I wrote contradicted itself for that case.

I fixed it slightly differently from the suggestion, to avoid describing a private widget in public docs. The Stack paragraph is now back exactly as it was, and the Overlay case is a separate paragraph anchored on OverlayEntry rather than on Overlay:

An [Overlay] lays its entries out using the same stack layout, so the widget built by an [OverlayEntry] can also be a [Positioned], with the same restriction on the path from the [Positioned] widget to the [OverlayEntry].

That statement holds: between the widget an entry builds and the overlay's stack layout there is only _OverlayEntryWidget, TickerMode, an InheritedWidget and a Builder, so a Positioned returned by OverlayEntry.builder reaches it fine. PositionedDirectional got the same treatment.

Thanks for the review! Applied both wordings, the subtree phrasing is more accurate anyway since the Positioned doesn't have to be the root of what the entry builds. Also added Overlay to the PositionedDirectional "See also" section, Positioned already had it.

Pushed. Summary of this round: the restriction paragraph no longer measures the path to the Overlay widget (that was the _Theater contradiction), it measures it to the widget that performs the stack layout, and the Overlay case stays in its own paragraph. Stack and Overlay are linked in the top/right/bottom/left paragraphs, "same stack layout algorithm" is used consistently, and CompositedTransformFollower is now in PositionedDirectional's "See also" as well.

While checking the claims I ran a throwaway test locally rather than trusting the reading: Positioned at the root of an OverlayEntry and deeper in its subtree, in OverlayPortal.overlayChildBuilder and in overlayChildLayoutBuilder, plus PositionedDirectional in RTL, AnimatedPositioned, PositionedTransition and RelativePositionedTransition inside an entry. Also the negative case, a Center between the Positioned and the entry root does throw, and the two Overlay-specific bits the docs now mention, a side-less Positioned landing at topStart (topRight in RTL) and a non-positioned entry getting the overlay size. All of that behaves as documented.

The failing tree-status check is the broken tree, not this PR.

@victorsanni Pushed 6d40313 with this round applied, and replied on each thread inline.

• Your replacement wording is in Positioned and mirrored in PositionedDirectional, so both boundaries are stated outright rather than inferred.
• "stack layout algorithm" is anchored to RenderStack.
• The Overlay align/size sentences are breadcrumbed to Overlay. I applied that to the AlignmentDirectional.topStart sentence just above it as well, since it carries the same bitrot risk — flagged in that thread, happy to put it back.
• All four short notes now say "Only works inside a [Stack] or an [Overlay]" instead of describing the widget as a child of the overlay.

Before writing the boundary paragraph I checked the three cases against the framework: Positioned as the entry root works, a StatelessWidget that builds one works, and a Center between them throws Incorrect use of ParentDataWidget.

Two things I can't do from my side:

• I don't have permission to re-request a review — both the REST and GraphQL endpoints refuse for my account — so this won't re-enter your queue on its own. Flagging it here instead, since you asked me to re-request rather than let a PR sit silently.
• The CICD label came off on the push, so Awaiting CICD label is stuck pending. Could you re-add it?

@victorsanni Pushed 7ea27b7 with this round applied, replied on each thread, and rewrote the PR description to the current state as you asked — it still described the original one-file change.

The one that needed real work was your question about whether Overlay actually documents any of this. It did not, so the breadcrumbs from the last round pointed at nothing. Overlay now documents how it lays entries out, right after the Directionality paragraph, and lists Positioned in its "See also". Checked the claims against _RenderTheater first: AlignmentDirectional.topStart.resolve(textDirection), and BoxConstraints.tight(size) for non-positioned children.

The rest:

• OverlayPortal.overlayChildLayoutBuilder is now named alongside the other two builders.
• The path rule reads "must not contain any RenderObjectWidgets" instead of listing the allowed kinds, which also answers the InheritedWidget question — the framework walks up to the first RenderObjectElement, so anything that is not a RenderObjectWidget is fine. Verified with a test before rewording.
• Your alignment wording is in, and both PositionedDirectional spots mirror everything.

Same note as last time: I can't re-request a review from my account — REST returns 404 and GraphQL returns FORBIDDEN: does not have the correct permissions to execute RequestReviews — so this won't re-enter your queue on its own. Flagging it here instead.

@victorsanni Pushed a9cecb8. You were right on all three substantive ones, and two of them were my errors from the last round rather than wording nits.

The overlay paragraph was wrong twice. performLayout only takes constraints.biggest on the !alwaysSizeToContent && constraints.biggest.isFinite branch — otherwise _findSizeDeterminingChild picks the topmost non-positioned entry with canSizeOverlay and the overlay takes that size, which canSizeOverlay and alwaysSizeToContent already document in the same file. And alignment never applies to non-positioned children at all: layoutChild gives them tight constraints and Offset.zero, and _resolvedAlignment only reaches RenderStack.layoutPositionedChild. I had read _alignmentCache and assumed it applied to every child instead of tracing where it is consumed. Took your combined replacement.

The path restriction missed ParentDataWidgets — Stack > Expanded > Positioned throws even though Expanded renders nothing. Took your replacement and verified Expanded, Flexible and a nested Positioned all throw, while a Builder on the path is fine.

The rest: the "Both" sentence now names Stack and Overlay instead of referring back to three APIs, the overlay paragraph covers OverlayPortal, and the "See also" no longer talks about wrapping an entry.

Re-requesting a review still fails from my account (REST 404, GraphQL FORBIDDEN), so flagging it here as before. The CICD label also came off on this push.