//! The immediate-mode renderer for [`quasi_router`]: a described screen in, an
//! egui frame out.
//!
//! <!-- wiki: quasi-overview -->
//!
//! The third renderer, and the one the stack was missing. `quasi-webview` and
//! `quasi-tui` have consumed a [`Screen`] since the beginning; nothing did in
//! egui, so an egui app describing a screen had nowhere to send it. What looked
//! like the egui renderer was `makeover-immediate`, which draws described
//! *nodes* and takes no dependency on `quasi-router` at all: it is the peer of
//! `makeover-webview` and `makeover-tui`, one layer below this.
//!
//! | Layer | webview | terminal | egui |
//! |---|---|---|---|
//! | nodes, from `makeover-layout` | `makeover-webview` | `makeover-tui` | `makeover-immediate` |
//! | screens, from `quasi-router` | `quasi-webview` | `quasi-tui` | **this crate** |
//!
//! Named for the mode and not the library, the way `makeover-immediate` is: what
//! separates this renderer from the other two is that there is no retained tree
//! and no cascade, and egui is the backend it is written against.
//!
//! # What immediate mode gives this renderer for free
//!
//! `quasi-tui` holds five things a browser provides quietly: what is typed, what
//! has focus, how far a pane is scrolled, what is ticked, and where back goes.
//! egui provides three of them, so this crate is smaller than the terminal's
//! rather than larger:
//!
//! - **Reach and focus are egui's**, entirely. Its own id stack decides what is
//!   reachable and its own state decides what holds the keyboard, which is the
//!   rule `makeover-immediate`'s header already states for the ring. There is no
//!   `focus.rs` here and there should not be one.
//! - **Scroll is egui's**, through `ScrollArea`.
//! - **What is typed and what is ticked are not.** A described field is built
//!   from the description every frame, so the buffer behind it has to outlive
//!   the frame and belongs to the app. That is [`View`], and it is the same
//!   discovery the terminal made for the same reason.
//!
//! # Where a description stops being enough
//!
//! The three findings `quasi-tui`'s `region` module records apply here unchanged,
//! because they are about the description rather than about terminals: a tabbed
//! arrangement does not say which tab is showing, a tab has no label, and
//! nothing says a region's share beyond [`Arrangement::share`]. Nothing new is
//! invented here to paper over them; the same guesses are made and named.

#![forbid(unsafe_code)]

mod node;
mod region;
mod runtime;
mod view;

#[cfg(test)]
mod tests;

pub use runtime::{Runtime, Step};
pub use view::View;

use egui::Ui;
use makeover_immediate::table::TableStyle;
use makeover_immediate::widget::WidgetStyle;
use makeover_immediate::{FieldStyle, FrameStyle, Palette};
use quasi_router::{Action, Message, Params, Screen, layout};

/// A banner this renderer raises about itself.
///
/// A description bug reported to the user rather than swallowed: a fragment
/// naming a region that is not there would otherwise look like a control that
/// does nothing.
pub(crate) fn layout_notice(text: String) -> Message {
    Message {
        kind: layout::Notice::Banner,
        tone: layout::Tone::Danger,
        text,
        undo: None,
    }
}

/// An egui renderer for a described screen.
///
/// Holds what a drawing needs and no screen state: the resolved palette and the
/// styles derived from it. A host makes one and keeps it, the same way it keeps
/// a `Tui`.
#[derive(Debug, Clone)]
pub struct Immediate {
    palette: Palette,
    frame: FrameStyle,
    field: FieldStyle,
    widget: WidgetStyle,
    table: TableStyle,
}

impl Immediate {
    /// A renderer drawing in this palette, with default styling.
    #[must_use]
    pub fn new(palette: Palette) -> Self {
        Self {
            palette,
            frame: FrameStyle::default(),
            field: FieldStyle::default(),
            widget: WidgetStyle::default(),
            table: TableStyle::default(),
        }
    }

    /// The colours this renderer draws in.
    #[must_use]
    pub const fn palette(&self) -> &Palette {
        &self.palette
    }

    /// Use these frame, field, widget and table styles, chaining.
    #[must_use]
    pub fn styled(
        mut self,
        frame: FrameStyle,
        field: FieldStyle,
        widget: WidgetStyle,
        table: TableStyle,
    ) -> Self {
        self.frame = frame;
        self.field = field;
        self.widget = widget;
        self.table = table;
        self
    }

    /// Draw a whole screen, and answer what the user did to it.
    ///
    /// The title is not drawn, for the reason `quasi-tui` gives: a window title
    /// is the host's to set, the same way a webview host puts it in `<title>`
    /// rather than in the document. [`Screen::discovery`] is declined outright,
    /// since nothing crawls a desktop window.
    ///
    /// `None` is the ordinary frame. egui redraws continuously, so most frames
    /// are a user doing nothing, and a renderer that answered a request per
    /// frame would call the router sixty times a second.
    pub fn screen(&self, ui: &mut Ui, screen: &Screen, view: &mut View) -> Option<Fired> {
        let mut pass = Pass {
            immediate: self,
            view,
            fired: None,
        };

        // Notices first and at the top, because a notice belongs to the screen
        // rather than to a place in it. A webview leaves where they land to the
        // stylesheet; egui has none, so this is the renderer deciding, and the
        // top is the one place a message about the whole screen can go without
        // claiming a region.
        for notice in &screen.notices {
            node::draw(&mut pass, ui, notice);
        }

        region::screen_regions(&mut pass, ui, screen);
        pass.fired
    }
}

/// What the user set off this frame.
///
/// An action and everything gathered to send with it. Separate from
/// [`Step`](runtime::Step) because a drawing does not know whether an action
/// needs asking about first: that is [`Act::confirm`](quasi_router::Act), and
/// the runtime is what holds the question while it is answered.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Fired {
    /// What to call.
    pub action: Action,
    /// What to send with it: a form's values, a selection's members.
    pub payload: Params,
    /// What to ask before doing it, if the description said to ask.
    pub confirm: Option<String>,
}

/// One frame's drawing, and what came out of it.
///
/// Threaded through the walk rather than returned up it: a press can happen at
/// any depth, and every level returning an `Option` would make each node's
/// drawing responsible for propagating one.
pub(crate) struct Pass<'a> {
    pub(crate) immediate: &'a Immediate,
    pub(crate) view: &'a mut View,
    pub(crate) fired: Option<Fired>,
}

impl Pass<'_> {
    /// Record what the user set off.
    ///
    /// First press wins. Two controls cannot be activated in one frame by a
    /// user, so a second one here is a description that put two `Response`s
    /// under one click, and taking the first is the same rule
    /// `Chrome::bound` uses for a key claimed twice.
    pub(crate) fn fire(&mut self, action: &Action, payload: Params, confirm: Option<&str>) {
        if self.fired.is_none() {
            self.fired = Some(Fired {
                action: action.clone(),
                payload,
                confirm: confirm.map(ToOwned::to_owned),
            });
        }
    }
}