teksilo_widgets/

banner.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! Banner — persistent inline status strip (info / success / warning / error).
//!
//! A non-transient, full-width callout for app-level conditions: deprecation
//! notices, "you have unsaved changes", trial-expiry warnings, license
//! issues, restored-from-cache notices, etc. Distinct from
//! [`Snackbar`](crate::snackbar::Snackbar) (transient, corner-anchored) and
//! [`MessageBox`](crate::message_box::MessageBox) (modal).
//!
//! ```ignore
//! Banner::warning(tr!(unsaved_changes()))
//!     .description(tr!(close_loses_changes()))
//!     .action(Button::new(tr!(save_now()))
//!         .on_activate_fn(|ctx| ctx.send_intent(AppIntent::SaveNow)))
//!     .on_dismiss(|ctx| ctx.send_intent(AppIntent::DismissBanner))
//! ```

use std::rc::Rc;

use teksilo_canvas::{Rect, SizeProposal};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::build_context::BuildContext;
use teksilo_core::styles::{BannerStyleConfig, SharedBannerStyle};
use teksilo_core::widget::{EventContext, LayoutContext, Widget, WidgetPlacement};
use teksilo_core::widget_builder::WidgetBuilder;
use teksilo_core::widget_id::WidgetId;
use teksilo_tokens::{TextRole, TextStyleRole, VAlignment};

pub use teksilo_core::styles::BannerSeverity;

use crate::icon_button::IconButton;
use crate::primitives::{Expand, HStack, TextWidget, VStack};
use crate::severity_badge::SeverityBadge;
use crate::styles::recipe_banner_style as banner_tokens;
use teksilo_i18n::LocalizedString;

/// A persistent inline status strip.
pub struct Banner {
    severity: BannerSeverity,
    title: LocalizedString,
    description: Option<LocalizedString>,
    action: Option<Box<dyn Widget>>,
    on_dismiss: Option<Box<dyn Fn(&mut EventContext)>>,
    /// Per-call override for the banner strip chrome.
    style_override: Option<SharedBannerStyle>,
    root_child_id: Option<WidgetId>,
}

impl Banner {
    fn new(severity: BannerSeverity, title: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = title.into();
        Self {
            severity,
            title: ls,
            description: None,
            action: None,
            on_dismiss: None,
            style_override: None,
            root_child_id: None,
        }
    }

    /// Per-call style override for the banner strip chrome. Replaces
    /// the theme-wide default `BannerStyle` for just this instance.
    pub fn style(mut self, style: impl teksilo_core::styles::BannerStyle) -> Self {
        self.style_override = Some(Rc::new(style));
        self
    }

    /// Construct an info-severity banner.
    pub fn info(title: impl Into<LocalizedString>) -> Self {
        Self::new(BannerSeverity::Info, title)
    }

    /// Construct a success-severity banner.
    pub fn success(title: impl Into<LocalizedString>) -> Self {
        Self::new(BannerSeverity::Success, title)
    }

    /// Construct a warning-severity banner.
    pub fn warning(title: impl Into<LocalizedString>) -> Self {
        Self::new(BannerSeverity::Warning, title)
    }

    /// Construct an error-severity banner.
    pub fn error(title: impl Into<LocalizedString>) -> Self {
        Self::new(BannerSeverity::Error, title)
    }

    /// Optional secondary line of text rendered below the title.
    pub fn description(mut self, text: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = text.into();
        self.description = Some(ls);
        self
    }

    /// Trailing widget — typically a [`Button`](crate::button::Button) or
    /// an `HStack` of buttons. Placed before the optional dismiss button.
    pub fn action(mut self, widget: impl Widget + 'static) -> Self {
        self.action = Some(Box::new(widget));
        self
    }

    /// Attach a trailing dismiss (X) button. The closure runs when the
    /// user clicks it; the host is expected to remove the banner from the
    /// tree (typically by toggling a `Signal<bool>` driving a `Switcher`).
    pub fn on_dismiss(mut self, f: impl Fn(&mut EventContext) + 'static) -> Self {
        self.on_dismiss = Some(Box::new(f));
        self
    }
}

impl std::fmt::Debug for Banner {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Banner")
            .field("severity", &self.severity)
            .field("title", &self.title)
            .field("description", &self.description)
            .finish()
    }
}

impl Widget for Banner {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        let severity = self.severity;

        // Severity glyph — a two-tone status badge, built by the widget
        // (principle 6) and handed to the style as the leading glyph.
        let glyph = ctx.add(SeverityBadge::new(
            severity.into(),
            banner_tokens::BANNER_GLYPH_SIZE,
        ));

        // Title + optional description column.
        let title = ctx.add(
            TextWidget::new(self.title.clone())
                .style(TextStyleRole::BodyBold)
                .color(TextRole::Primary)
                .single_line()
                // The banner's own Role::Status node carries this title as
                // its name, set on the node rather than drawn from this label
                // through `labelled_by`: the adapters announce a live node
                // when its own name changes, and `accesskit_consumer` reports
                // a node as changed only when its own data does, so a title
                // changing on the label alone would go unannounced.
                .a11y_hidden(),
        );
        let mut text_column = VStack::new()
            .spacing(banner_tokens::BANNER_TITLE_DESCRIPTION_GAP)
            .child(title);
        if let Some(description) = &self.description {
            let desc = ctx.add(
                TextWidget::new(description.clone())
                    .style(TextStyleRole::Body)
                    .color(TextRole::Secondary),
            );
            text_column = text_column.child(desc);
        }
        let text_column_id = ctx.add(text_column);

        // Content row: [text + spacer expanding] [action] [dismiss].
        // The leading severity glyph is prepended by the `BannerStyle`.
        let mut content = HStack::new()
            .spacing(banner_tokens::BANNER_CONTENT_GAP)
            .alignment(VAlignment::Center)
            .child(ctx.add(Expand::horizontal().child(text_column_id)));
        if let Some(action) = self.action.take() {
            content = content.child(ctx.add_boxed(action));
        }
        if let Some(on_dismiss) = self.on_dismiss.take() {
            // IconButton::clear() ships with its own translated
            // "Clear" tooltip / a11y label — adequate for a banner
            // dismiss button without inventing a new i18n key.
            // `.embedded()` keeps the icon dim until hover so the X
            // doesn't compete with the banner's title/body text.
            let btn = IconButton::clear()
                .embedded()
                .on_activate_fn(move |c| on_dismiss(c));
            content = content.child(ctx.add(btn));
        }
        // `Live::Off` on the row that holds the description, the action and
        // the dismiss button. The banner is a polite live region named by
        // its title, and `accesskit_consumer` hands its politeness down to
        // every descendant that sets none (node.rs:906-910), while all three
        // adapters announce each named node entering the filtered tree with
        // an inherited politeness (atspi_common adapter.rs:71-77, windows
        // adapter.rs:255-263, macos event.rs:236-241). Without it a banner
        // was heard as its title, then its description, its action and its
        // dismiss button, each cutting off the one before; in a card, a
        // panel, a tab or a dialog, whose wrappers used to hide it whole, it
        // was not heard at all.
        let content_id = ctx.add(content.access_live(teksilo_core::accesskit::Live::Off));

        // The strip chrome (per-severity surface tint, corner radius,
        // padding, glyph-content arrangement) is owned by the active
        // `BannerStyle`; this widget keeps its `Role::Status` node.
        let style: SharedBannerStyle = self
            .style_override
            .clone()
            .or_else(|| ctx.theme().style_slots.banner.clone())
            .unwrap_or_else(|| {
                Rc::new(crate::styles::RecipeBannerStyle::for_tokens(
                    &ctx.theme().input,
                ))
            });
        let root = style.make_body(
            &BannerStyleConfig {
                severity,
                content: content_id,
                leading_glyph: glyph,
            },
            ctx,
        );
        self.root_child_id = Some(root);
        vec![root]
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        // Banners are a "fill width, hug height" surface. ZStack queries
        // its children with `SizeProposal::unspecified`, so delegating
        // straight to `child_size` would return the row's natural width
        // and the banner would collapse to its content. Take the
        // proposed width as the source of truth and use the inner
        // height (computed against that width) for the visual.
        let inner_proposal = SizeProposal {
            width: proposal.width,
            height: None,
        };
        let inner = self
            .root_child_id
            .and_then(|id| ctx.child_size(id, inner_proposal))
            .unwrap_or_else(|| proposal.resolve(0.0, 0.0));
        let width = proposal.width.unwrap_or(inner.width);
        teksilo_canvas::Size::new(width, inner.height).into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        _ctx: &LayoutContext,
    ) {
        for child in children.iter_mut() {
            child.origin = bounds.origin();
            child.size = bounds.size();
        }
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        // Banners convey status without consuming focus. `Role::Status`
        // matches the ARIA pattern for a non-modal status region; pair
        // with `Live::Polite` so screen readers announce changes.
        builder.set_role(teksilo_core::accesskit::Role::Status);
        builder.set_live(teksilo_core::accesskit::Live::Polite);
        // Use the title alone as the AT name; the description is read by
        // descending into the body text widget.
        builder.set_name(self.title.clone());
    }

    fn children(&self) -> Vec<WidgetId> {
        self.root_child_id.into_iter().collect()
    }

    fn clips_children(&self) -> bool {
        false
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use teksilo_core::widget_tree::WidgetTree;
    use teksilo_i18n::lit;

    #[test]
    fn banner_builds_and_lays_out() {
        let mut tree = WidgetTree::new().with_theme(teksilo_core::presets::intui::light());
        let id = tree.add(
            Banner::warning(lit!("Unsaved changes"))
                .description(lit!("Close will discard your edits.")),
        );
        tree.layout(SizeProposal {
            width: Some(640.0),
            height: None,
        });
        let b = tree.bounds(id);
        assert!((b.width - 640.0).abs() < 0.01);
        assert!(b.height > 0.0);
    }

    #[test]
    fn banner_a11y_role_and_name() {
        let mut tree = WidgetTree::new().with_theme(teksilo_core::presets::intui::light());
        let id = tree.add(Banner::info(lit!("Heads up")));
        tree.layout(SizeProposal {
            width: Some(400.0),
            height: None,
        });
        let info = tree.accessibility_node(id);
        assert_eq!(info.role(), teksilo_core::accesskit::Role::Status);
        assert_eq!(info.name(), Some("Heads up"));
    }

    #[test]
    fn banner_fills_width_inside_vstack() {
        // Regression: ZStack queries children with `unspecified` proposal,
        // so a naive `child_size(root, proposal)` delegate makes Banner
        // collapse to its content width inside a normal VStack parent.
        // Banner's `layout_response` overrides the width to the proposal.
        use crate::primitives::VStack;
        let mut tree = WidgetTree::new().with_theme(teksilo_core::presets::intui::light());
        let banner = Banner::warning(lit!("Unsaved changes"))
            .description(lit!("Close will discard your edits."));
        let stack_id = tree.add(VStack::new().spacing(8.0).child(banner));
        tree.layout(SizeProposal {
            width: Some(640.0),
            height: None,
        });

        // Walk the VStack's first descendant Banner (Role::Status) and
        // check its bounds.
        let mut queue = vec![stack_id];
        let mut banner_bounds = None;
        while let Some(id) = queue.pop() {
            let info = tree.accessibility_node(id);
            if info.role() == teksilo_core::accesskit::Role::Status {
                banner_bounds = Some(tree.bounds(id));
                break;
            }
            queue.extend(tree.children(id));
        }
        let b = banner_bounds.expect("Banner should be in the tree under the VStack");
        assert!(
            (b.width - 640.0).abs() < 0.5,
            "Banner inside VStack should span the proposed width 640 dp, got {}",
            b.width
        );
    }

    #[test]
    fn banner_title_label_is_hidden_from_accessibility_tree() {
        // The Banner's Role::Status node already carries the title as its
        // own name (set on the node, not drawn through `labelled_by`, so
        // that a new title is a change of the node the adapters announce),
        // so the embedded title Label must not
        // reach the AT tree as a second, duplicate-named stop. The
        // description is a distinct, non-duplicate label and must stay.
        use teksilo_core::accessibility::widget_id_to_node_id;
        let mut tree = WidgetTree::new().with_theme(teksilo_core::presets::intui::light());
        let id = tree.add(
            Banner::warning(lit!("Unsaved changes"))
                .description(lit!("Close will discard your edits.")),
        );
        tree.layout(SizeProposal {
            width: Some(640.0),
            height: None,
        });
        let update = tree.sync_accessibility();

        let banner_node_id = widget_id_to_node_id(id);
        let banner_node = update
            .nodes
            .iter()
            .find(|(nid, _)| *nid == banner_node_id)
            .map(|(_, node)| node)
            .expect("banner node");
        assert_eq!(banner_node.role(), teksilo_core::accesskit::Role::Status);
        assert_eq!(
            banner_node.label(),
            Some("Unsaved changes"),
            "hiding the title label must not take the banner's own name away with it",
        );
        let banner_name = banner_node.label().unwrap_or_default().to_string();

        assert!(
            !update.nodes.iter().any(|(_, node)| {
                node.role() == teksilo_core::accesskit::Role::Label
                    && node.label() == Some(banner_name.as_str())
            }),
            "the title Label must not survive as a duplicate-named node",
        );

        // Exactly one Role::Label node remains: the description's. Were
        // the title's label not hidden, there would be two.
        let label_count = update
            .nodes
            .iter()
            .filter(|(_, node)| node.role() == teksilo_core::accesskit::Role::Label)
            .count();
        assert_eq!(
            label_count, 1,
            "only the description Label should remain once the title is hidden",
        );
    }

    #[test]
    fn banner_with_dismiss_emits_clear_button() {
        use std::cell::Cell;
        use std::rc::Rc;
        let dismissed = Rc::new(Cell::new(false));
        let dismissed_clone = dismissed.clone();
        let mut tree = WidgetTree::new().with_theme(teksilo_core::presets::intui::light());
        tree.add(
            Banner::error(lit!("Disk almost full")).on_dismiss(move |_| dismissed_clone.set(true)),
        );
        tree.layout(SizeProposal {
            width: Some(640.0),
            height: None,
        });
        // Find the clear button by tooltip / a11y label and click it.
        let dismiss = tree
            .find_by_label("Clear")
            .or_else(|| tree.find_by_label("Effacer"))
            .expect("dismiss button should be present");
        tree.dispatch_event(teksilo_core::event::WidgetEvent::AccessAction {
            action: teksilo_core::accesskit::Action::Click,
            target: Some(dismiss),
            target_node: teksilo_core::accessibility::root_node_id(),
            data: None,
        });
        assert!(dismissed.get(), "on_dismiss should have fired");
    }
}