NIB / DOCUMENTATION
Popover — NibComponents
Anchor a small interactive task to its trigger and close it through a local scope.
Open interactive viewKeep the task next to its trigger
Use a popover for tags, a small toolbar, or a short explanation with a choice. The example records Flutter as the selected reading tag and closes from the panel. Use a dialog when the task needs modal focus containment.
content is required. A trigger gives the panel a meaningful anchor. Its wrapper toggles on tap; if the trigger is an interactive button, connect that button to an explicit NibPopoverController instead of relying on a parent gesture. The complete example does this.
Treat placement as a preference
NibPopoverPlacement offers bottom, top, start, and end. Positioning can flip and clamp to the available viewport. gap separates trigger and panel; maxWidth is a ceiling. showArrow defaults to false. Check edges and right-to-left layouts rather than assuming the preferred side always fits.
This anchored family uses the nearest overlay, so its bounded website preview differs from page-modal root helpers. The candidate geometry repairs convert positions into the owning overlay coordinate space. A passing root-overlay example alone cannot prove local-overlay bounds.
Keep an exit available
dismissOnOutsideTap defaults to true. When false, close with the controller or NibPopoverScope.of(popoverContext).close(). The scope also exposes isOpen. The selected tag is application state; onOpen and onClose only report presentation changes.
Outside dismissal uses a pointer barrier. Non-modal does not mean every click passes through. barrierColor can tint that layer, but the popover does not trap focus like a dialog. Keep the trigger and an in-panel action reachable by keyboard.
Keep one controller per surface
NibPopoverController exposes open, close, toggle, and isOpen. Create it once in State and dispose it in that owner. NibPopover removes its listeners and overlay on unmount. Without an external controller it owns one internally.
The complete example keeps the controller across inspector changes. Do not recreate it inside build. Store selected values or asynchronous task state separately: the controller represents whether the surface is open, not whether a request succeeded.
Use inherited tokens and optional motion
The panel uses NibTheme card, foreground, border, and radius values from its opening context. semanticLabel describes the trigger purpose. Keep it meaningful rather than repeating a generic widget name.
animated defaults to false. transition controls optional timing or spring response; enterFrom supplies a NibAnim start state. Reduced motion must leave text and choices usable. The example uses the actual package transition, not a separate visual substitute.
Check the trigger and scope context
If a nested button consumes the opening tap, connect its callback to controller.toggle. If closing cannot find NibPopoverScope, use Builder inside content. If the panel clips, inspect the actual overlay bounds, text scale, and longest label.
This primitive supplies a surface and positioning, not form validation, selection storage, or authorization. The tag result is local state. Cancel or ignore stale async responses when the owner leaves or a different choice becomes active.