Presentation and layer API

Declared by <huxerui/layer.h> and <huxerui/presentation.h>.

Low-level layers

• LayerId is a std::uint64_t; ViewFactory is std::function<View()>.
• LayerLevel: Presentation, Notification, System.
• LayerPointerPolicy: PassThrough, Content, Barrier.
• LayerCancelPolicy: PassThrough, Consume, Dismiss.
• LayerOptions: level, pointer policy, focus trap, outside dismissal, cancel policy, dismissal callback, and optional barrier color.
• LayerController: Attach, Update, and Dismiss, including bound-factory overloads.

Typed presentation

• ToastHandle / UseToast, ToastOptions, ToastStyle.
• DialogHandle / UseDialog, DialogOptions, DialogContext, DialogFactory, DialogStyle, and declarative Dialog modifier.
• BottomSheetHandle / UseBottomSheet, BottomSheetOptions, BottomSheetContext, BottomSheetFactory, BottomSheetStyle.
• PopupHandle / UsePopup, PopupOptions, PopupContext, PopupFactory.
• MenuHandle / UseMenu, MenuOptions, MenuItem, MenuEntry, MenuSection, and MenuStyle.
• MenuSeparatorMode: None, BetweenSections, or BetweenItems.
• Tooltip retained modifier and TooltipStyle.

Anchoring and motion

LayerAnchor is obtained from popup/menu handles and attached through .With(...). AnchorSide (Below, Above, Right, Left), AnchorAlignment (Start, Center, End), and AnchorPlacement describe preference. PresentationMotion carries initial scale, slide distance, and enter/exit specs. VerticalPlacement is Top, Center, or Bottom.

Each presentation component page lists exact Show, Update, and dismissal overloads.

Handle and environment contract

UseToast, UseDialog, UseBottomSheet, UsePopup, and UseMenu return lightweight handles connected to the current Runtime. The Use… call captures the current Environment in the handle, so later Show calls resolve theme and resources from the presenting subtree even though the layer is outside its layout tree. Custom factories and captured arguments must be copyable because presentation may rebuild them.

Modal surfaces trap focus and use barrier/cancel policy; anchored surfaces retain a LayerAnchor tied to the mounted anchor node. Attaching through a disconnected LayerController is a logic error. Its Update returns false for a disconnected controller or stale identifier, and Dismiss returns false for stale/already-exiting entries. Do not treat a false update result as a successful replacement. Dismiss explicitly when application state no longer owns the surface; options determine outside-click and cancel behavior.

Ownership of a dismissal request

on_dismiss_request is an owner callback instead of automatic removal, not an after-close observer. An explicit Dismiss bypasses that request path. For a declarative Dialog, the callback writes its visible State to false; for an imperative owner, it may dismiss the specific layer. Do not maintain a separate hidden/visible flag that contradicts the declarative input.

LayerOptions::barrier_color and outside-press dismissal require LayerPointerPolicy::Barrier; invalid combinations and empty attach factories throw std::invalid_argument. PassThrough is for non-interactive overlays, Content hit-tests the layer’s content, and Barrier blocks the rest of the viewport. LayerCancelPolicy::Consume handles cancel without removing content; PassThrough lets lower content respond.

LayerController::Update(id, content) preserves options. Update(id, options, content) replaces both under the same identity. Keep layers window-scoped: a LayerId is not a globally persistent UI handle. Prefer the component pages for Dialog, Popup, Menu, Toast, SnackBar, and BottomSheet before building a custom layer service.