// SPDX-FileCopyrightText: 2026 Proa Labs, Inc. // SPDX-License-Identifier: MIT OR Apache-2.0 //! Declarative popovers: HTML owns disclosure and CSS owns placement. use super::{PopoverAlign, PopoverSide, POPOVER_ANATOMY, POPOVER_RECIPE}; use crate::OverlayIds; use proa::html_sync; use proa::{WebContext, WebRenderSync, WriteBuf, WriteError}; /// A non-modal popover that works without the Proa JavaScript runtime. /// /// Import `runtime/proa-free.css` (or `proa.css`) into your Tailwind entry /// point and scan these component sources. Browsers with CSS anchor positioning /// place the panel beside its trigger and flip it to avoid viewport overflow. /// Without anchor positioning, native popovers open centered in the viewport. /// Without the HTML Popover API, content remains visible inline. /// /// `id` must be unique in the document. `trigger` supplies the button's contents, /// not a nested button. The browser owns open state, Escape, light dismissal, /// and the trigger's implicit expanded state. This is not a modal dialog. pub struct NoJsPopover { pub id: &'static str, pub side: PopoverSide, pub align: PopoverAlign, pub trigger_class: Option<&'static str>, pub content_class: Option<&'static str>, pub trigger: Option, pub content: Option, } impl NoJsPopover { pub const fn new(id: &'static str) -> Self { Self { id, side: PopoverSide::Bottom, align: PopoverAlign::Center, trigger_class: None, content_class: None, trigger: None, content: None, } } } impl< B: WriteBuf, L: proa::DataLoader, Trigger: WebRenderSync, Content: WebRenderSync, > WebRenderSync for NoJsPopover { fn render(self, cx: &mut WebContext) -> Result<(), WriteError> { let ids = OverlayIds::new(Some(self.id)); html_sync! {
} .render(cx) } } /// Declarative close button. `popover_id` is the owning [`NoJsPopover::id`]. pub struct NoJsPopoverClose { pub popover_id: &'static str, pub class: Option<&'static str>, pub children: Option, } impl> WebRenderSync for NoJsPopoverClose { fn render(self, cx: &mut WebContext) -> Result<(), WriteError> { let ids = OverlayIds::new(Some(self.popover_id)); html_sync! { } .render(cx) } } #[cfg(test)] mod tests { use super::*; #[test] fn no_js_contract_is_complete_before_javascript() { let mut out = Vec::new(); let mut cx = WebContext::with_buffer(&mut out); NoJsPopover { side: PopoverSide::Top, align: PopoverAlign::End, trigger_class: Some("custom-trigger"), content_class: Some("custom-panel"), trigger: Some("Settings"), content: Some(NoJsPopoverClose { popover_id: "settings", class: Some("custom-close"), children: Some("Done"), }), ..NoJsPopover::new("settings") } .render(&mut cx) .unwrap(); let html = String::from_utf8(out).unwrap(); assert!(html.contains(r#"id="settings--trigger""#)); assert!(html.contains(r#"id="settings--content""#)); assert_eq!( html.matches(r#"popovertarget="settings--content""#).count(), 2 ); assert!(html.contains(r#"aria-controls="settings--content""#)); assert!(html.contains(r#"aria-labelledby="settings--trigger""#)); assert!(html.contains(r#"popover="auto""#)); assert!(html.contains(r#"popovertargetaction="hide""#)); assert!(html.contains(r#"data-side="top""#)); assert!(html.contains(r#"data-align="end""#)); for class in ["custom-trigger", "custom-panel", "custom-close"] { assert!(html.contains(class)); } // Native disclosure must never be captured by delegated JS or frozen // behind SSR-only hidden/expanded state. for legacy in [ "data-popover-root", "data-popover-trigger", "data-popover-content", "data-state=", "aria-hidden=", "aria-expanded=", "style=", ] { assert!(!html.contains(legacy), "native markup contains {legacy}"); } } }