zng_wgt_wizard/

lib.rs

#![doc(html_favicon_url = "https://zng-ui.github.io/res/zng-logo-icon.png")]
#![doc(html_logo_url = "https://zng-ui.github.io/res/zng-logo.png")]
//!
//! Wizard widget.
//!
//! # Crate
//!
#![doc = include_str!(concat!("../", std::env!("CARGO_PKG_README")))]
#![warn(unused_extern_crates)]
#![warn(missing_docs)]

zng_wgt::enable_widget_macros!();

use std::any::Any;

use zng_app::event::CommandArgs;
use zng_ext_input::focus::FOCUS;
use zng_var::MergeVarBuilder;
use zng_view_api::keyboard::Key;
use zng_wgt::prelude::*;
use zng_wgt_input::{gesture, keyboard};
use zng_wgt_style::style_fn;
use zng_wgt_text_input::label;

mod view_fn;

pub use view_fn::*;

/// Paginated widget that
#[widget($crate::Wizard)]
pub struct Wizard(WidgetBase);
impl Wizard {
    fn widget_intrinsic(&mut self) {
        self.widget_builder().push_build_action(|wgt| {
            let pages = wgt.capture_var_or_default(property_id!(pages));
            wgt.set_child(node(pages));
            wgt.push_intrinsic(NestGroup::CONTEXT, "state", |c| {
                let c = with_context_var(c, SELECTED_PAGE_VAR, var(Page::nil()));

                zng_wgt::node::with_context_local_init(c, &WIZARD_CTX, || WizardCtx { id: WIDGET.id() })
            });
        });

        widget_set! {
            self;

            // use mnemonic shortcuts
            gesture::mnemonic_scope = true;
            label::style_fn = style_fn!(|_| {
                label::DefaultStyle! {
                    label::mnemonic_underline = true;
                    zng_wgt_text::underline = 1, LineStyle::Solid;
                }
            });
            keyboard::on_key_up = hn!(|args| {
                if let Key::Char(c) = args.key
                    && c.is_alphanumeric()
                    && !FOCUS.is_highlighting().get()
                {
                    // on unhandled alphanumeric press highlight focus to enable mnemonic keys
                    FOCUS.highlight();
                    args.propagation.stop();
                }
            });
        }
    }
}

context_var! {
    static SELECTED_PAGE_VAR: Page = Page::nil();
}
context_local! {
    static WIZARD_CTX: WizardCtx = WizardCtx::no_context();
}
struct WizardCtx {
    id: WidgetId,
}
impl WizardCtx {
    fn no_context() -> Self {
        panic!("no `Wizard!` in context")
    }
}

/// Defines the wizard pages.
///
/// Pages are built on demand, the [`Page`] value defines [`wgt_fn!`] builders
/// that are used by wizard when the page needs to be instantiated.
#[property(CHILD, widget_impl(Wizard))]
pub fn pages(wgt: &mut WidgetBuilding, pages: impl IntoVar<Vec<Page>>) {
    let _ = pages;
    wgt.expect_property_capture();
}

/// Get the current page title.
#[property(CONTEXT, widget_impl(Wizard))]
pub fn get_title(child: impl IntoUiNode, title: impl IntoVar<Txt>) -> UiNode {
    bind_state(child, SELECTED_PAGE_VAR.flat_map(|p| p.title.0.clone()), title)
}

/// Represents a page builder for [`Wizard!`].
///
/// The widgets defined here must represent only the content that is unique for each page,
/// the wizard widget has properties that define the wizard parts, for example, if the side
/// has an image that is the same for all pages it is defined in [`Wizard::side_fn`].
///
/// The builders care called in the parent [`Wizard!`] widget context.
///
/// [`Wizard!`]: struct@Wizard
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq)]
pub struct Page {
    /// Page title.
    ///
    /// The default `header` presents this for the selected page.
    pub title: VarEq<Txt>,

    /// Page info.
    ///
    /// This is a short explanation about the page. Supports basic markdown span formatting.
    ///
    /// The default `header` presents this for the selected page.
    pub info: VarEq<Txt>,

    /// Page header content.
    ///
    /// Presents the `title`, `info` and any other custom header detail
    /// when the page is selected.
    ///
    /// The header of each page is wrapped by [`Wizard::header_fn`] to form the full header.
    ///
    /// If this builds [`UiNode::nil`] the header panel **is collapsed** for this page.
    ///
    /// Is [`default_page_header`] by default.
    pub header: WidgetFn<PageArgs>,
    /// Page side panel content.
    ///
    /// The side content of each page is wrapped by [`Wizard::side_fn`] to form the full side panel.
    ///
    /// If this is a list node the wizard side builder will generate a layout panel for the items.
    ///
    /// If this builds [`UiNode::nil`] the side panel **is collapsed** for this page. An empty list node
    /// signals the side builder that it should be visible without page content.
    ///
    /// Is [`default_page_side`] by default.
    pub side: WidgetFn<PageArgs>,
    /// Page main content.
    ///
    /// The main content of each page is wrapped by [`Wizard::content_fn`] to form the full content panel.
    pub content: WidgetFn<PageArgs>,

    /// If the `content` prefers to fully fill the content area.
    ///
    /// This is a hint for [`Wizard::content_fn`]. By default this is `false` and the content
    /// is wrapped in a `Scroll!` with padding.
    ///
    /// Only set this to `true` if you want to remove all padding or if you want to scroll just
    /// a part of the content with the rest filling the area.
    pub content_fill: bool,

    /// Page footer content.
    ///
    /// The footer of each page is wrapped by [`Wizard::footer_fn`] to form the full footer panel.
    ///
    /// If this is a list node the wizard footer builder will generate a layout panel for the items.
    ///
    /// Is [`default_page_footer`] by default.
    pub footer: WidgetFn<PageArgs>,

    /// When `true` the page is skipped over.
    ///
    /// Is `false` by default.
    pub skip: VarEq<bool>,

    /// When is not the first page controls the wizard `BACK_CMD` handle.
    ///
    /// Is `true` by default.
    pub can_back: VarEq<bool>,

    /// When is not the last page controls the wizard `NEXT_CMD` handle.
    pub can_next: VarEq<bool>,
}

impl Page {
    /// New basic page.
    pub fn new(title: impl IntoVar<Txt>, info: impl IntoVar<Txt>, content: WidgetFn<PageArgs>) -> Self {
        Self {
            title: VarEq(title.into_var()),
            info: VarEq(info.into_var()),
            header: WidgetFn::new(default_page_header),
            side: WidgetFn::new(default_page_side),
            content,
            content_fill: false,
            footer: WidgetFn::new(default_page_footer),
            skip: VarEq(var(false)),
            can_back: VarEq(var(true)),
            can_next: VarEq(var(true)),
        }
    }

    /// New fully empty skip page.
    pub fn nil() -> Self {
        Self {
            title: VarEq(const_var(Txt::from_static(""))),
            info: VarEq(const_var(Txt::from_static(""))),
            header: WidgetFn::nil(),
            side: WidgetFn::nil(),
            content: WidgetFn::nil(),
            content_fill: false,
            footer: WidgetFn::nil(),
            skip: VarEq(const_var(true)),
            can_back: VarEq(const_var(false)),
            can_next: VarEq(const_var(false)),
        }
    }

    /// Gets if is [`nil`].
    ///
    /// [`nil`]: Self::nil
    pub fn is_nil(&self) -> bool {
        self.header.is_nil()
            && self.side.is_nil()
            && self.content.is_nil()
            && self.footer.is_nil()
            && !self.content_fill
            && self.title.0.capabilities().is_const()
            && self.info.0.capabilities().is_const()
            && self.skip.0.capabilities().is_const()
            && self.can_back.0.capabilities().is_const()
            && self.can_next.0.capabilities().is_const()
            && self.title.0.with(|t| t.as_static_str() == Some(""))
            && self.info.0.with(|t| t.as_static_str() == Some(""))
            && self.skip.0.get()
            && !self.can_back.0.get()
            && !self.can_next.0.get()
    }
}
/// Arguments for [`Page`] builders.
#[non_exhaustive]
#[derive(Clone)]
pub struct PageArgs {
    /// Page index on the pages list.
    ///
    /// Is `usize::MAX` if the page is a custom assign to [`WIZARD::selected_page`] that is not on the list.
    pub index: usize,
    /// Count of pages on the list.
    pub pages_len: usize,
    /// The [`Page::title`] var.
    pub title: Var<Txt>,
    /// The [`Page::info`] var.
    pub info: Var<Txt>,
    /// The [`Page::can_back`] var.
    pub can_back: Var<bool>,
    /// The [`Page::can_next`] var.
    pub can_next: Var<bool>,
}
impl PageArgs {
    /// Is first page on the list.
    pub fn is_first(&self) -> bool {
        self.index == 0
    }

    /// Is last page on the list.
    pub fn is_last(&self) -> bool {
        self.index == self.pages_len.saturating_sub(1)
    }

    /// Is custom page, not on the list.
    pub fn is_custom(&self) -> bool {
        self.index == usize::MAX
    }

    /// Get `WIDGET.id()`.
    pub fn wizard_id(&self) -> WidgetId {
        WIDGET.id()
    }
}

command! {
    /// Return to previous page.
    pub static BACK_CMD {
        l10n!: true,
        name: "Back",
    };

    /// Advance to next page.
    pub static NEXT_CMD {
        l10n!: true,
        name: "Next",
    };

    /// Cancel wizard config or operation.
    pub static CANCEL_CMD {
        l10n!: true,
        name: "Cancel",
    };

    /// Begin wizard operation.
    ///
    /// This command represents the transition from config pages to a progress page.
    /// The progress page is expected to automatically swap to a results page on completion.
    ///
    /// The [`begin_cmd_name`] can be used to change the command display name.
    ///
    /// [`begin_cmd_name`]: fn@begin_cmd_name
    pub static BEGIN_CMD {
        l10n!: true,
        name: "Begin",
    };

    /// Finish wizard operation.
    ///
    /// This command represents the transition out of the wizard from the results page or the last
    /// config page.
    ///
    /// If the wizard operation uses `BEGIN_CMD` the progress page will auto swap to
    /// a results page, the results page offers the `FINISH_CMD`, to perhaps close the wizard window.
    ///
    /// The wizard operation can also simply represents a configuration that is instantly applied, in this
    /// case the last config page can directly call `FINISH_CMD` to exit the wizard.
    ///
    /// The [`finish_cmd_name`] can be used to change the command display name.
    ///
    /// [`finish_cmd_name`]: fn@finish_cmd_name
    pub static FINISH_CMD {
        l10n!: true,
        name: "Finish",
    };
}
command_property! {
    /// Wizard cancel requested.
    #[property(EVENT, widget_impl(Wizard))]
    pub fn on_cancel<on_pre_cancel, can_cancel>(child: impl IntoUiNode, handler: Handler<CommandArgs>) -> UiNode {
        CANCEL_CMD
    }

    /// Wizard begin requested.
    #[property(EVENT, widget_impl(Wizard))]
    pub fn on_begin<on_pre_begin, can_begin>(child: impl IntoUiNode, handler: Handler<CommandArgs>) -> UiNode {
        BEGIN_CMD
    }

    /// Wizard finish requested.
    #[property(EVENT, widget_impl(Wizard))]
    pub fn on_finish<on_pre_finish, can_finish>(child: impl IntoUiNode, handler: Handler<CommandArgs>) -> UiNode {
        FINISH_CMD
    }
}

/// Set the name for the [`BEGIN_CMD`] scoped on this widget.
#[property(CONTEXT, widget_impl(Wizard))]
pub fn begin_cmd_name(child: impl IntoUiNode, name: impl IntoVar<Txt>) -> UiNode {
    let name = name.into_var();
    match_node(child, move |_, op| {
        if let UiNodeOp::Init = op {
            let begin_name = BEGIN_CMD.scoped(WIDGET.id()).name();
            let h = name.set_bind(&begin_name);
            WIDGET.push_var_handle(h);
        }
    })
}

/// Set the name for the [`FINISH_CMD`] scoped on this widget.
#[property(CONTEXT, widget_impl(Wizard))]
pub fn finish_cmd_name(child: impl IntoUiNode, name: impl IntoVar<Txt>) -> UiNode {
    let name = name.into_var();
    match_node(child, move |_, op| {
        if let UiNodeOp::Init = op {
            let finish_name = FINISH_CMD.scoped(WIDGET.id()).name();
            let h = name.set_bind(&finish_name);
            WIDGET.push_var_handle(h);
        }
    })
}

fn node(pages: Var<Vec<Page>>) -> UiNode {
    let mut cmds = [CommandHandle::dummy(), CommandHandle::dummy()];
    let mut sel_pg_i = 0usize;
    const CUSTOM_PAGE_I: usize = usize::MAX;
    match_node(UiNode::nil(), move |c, op| match op {
        UiNodeOp::Init => {
            WIDGET
                .sub_var(&pages)
                .sub_var(&PANEL_FN_VAR)
                .sub_var(&HEADER_FN_VAR)
                .sub_var(&HEADER_BACKGROUND_FN_VAR)
                .sub_var(&SIDE_FN_VAR)
                .sub_var(&SIDE_BACKGROUND_FN_VAR)
                .sub_var(&SIDE_EXTRA_FN_VAR)
                .sub_var(&CONTENT_FN_VAR)
                .sub_var(&FOOTER_FN_VAR)
                .sub_var(&FOOTER_EXTRA_FN_VAR)
                .sub_var(&SELECTED_PAGE_VAR);
            pages.with(|p| {
                if !p.is_empty() {
                    sel_pg_i = 0;
                    cmds = subscribe(0, p);
                    *c.node() = build(0, p, None);
                    SELECTED_PAGE_VAR.set(p[0].clone());
                }
            });
        }
        UiNodeOp::Deinit => {
            c.deinit();
            *c.node() = UiNode::nil();
            cmds = [CommandHandle::dummy(), CommandHandle::dummy()];
            SELECTED_PAGE_VAR.set(Page::nil());
        }
        UiNodeOp::Update { updates } => {
            c.update(updates);

            let mut rebuild = false;

            if sel_pg_i != CUSTOM_PAGE_I {
                // default BACK_CMD and NEXT_CMD

                let scope = WIDGET.id();

                BACK_CMD.scoped(scope).each_update(true, false, |args| {
                    args.propagation.stop();

                    // seek prev that is not skip
                    pages.with(|pages| {
                        for (i, pg) in pages[..sel_pg_i].iter().enumerate().rev() {
                            if !pg.skip.get() {
                                sel_pg_i = i;
                                rebuild = true;
                                break;
                            }
                        }
                    });
                });

                NEXT_CMD.scoped(scope).each_update(true, false, |args| {
                    args.propagation.stop();

                    // seek next that is not skip
                    pages.with(|pages| {
                        for (i, pg) in pages.iter().enumerate().skip(sel_pg_i + 1) {
                            if !pg.skip.get() {
                                sel_pg_i = i;
                                rebuild = true;
                                break;
                            }
                        }
                    });
                });
            }
            if pages.is_new() {
                sel_pg_i = 0;
                rebuild = true;
            } else if let Some(new) = SELECTED_PAGE_VAR.get_new() {
                pages.with(|pages| {
                    if let Some(i) = pages.iter().position(|p| p == &new) {
                        if i != sel_pg_i {
                            // custom assign, but page is known
                            sel_pg_i = i;
                            rebuild = true;
                        }
                        // else, not custom assign, already rebuilt
                    } else {
                        // custom assign
                        sel_pg_i = CUSTOM_PAGE_I;
                        rebuild = true;
                    }
                })
            }
            if !rebuild && PANEL_FN_VAR.is_new()
                || HEADER_FN_VAR.is_new()
                || HEADER_BACKGROUND_FN_VAR.is_new()
                || SIDE_FN_VAR.is_new()
                || SIDE_BACKGROUND_FN_VAR.is_new()
                || SIDE_EXTRA_FN_VAR.is_new()
                || CONTENT_FN_VAR.is_new()
                || FOOTER_FN_VAR.is_new()
                || FOOTER_EXTRA_FN_VAR.is_new()
            {
                rebuild = true;
            }

            if rebuild {
                // replace child with new page instance
                c.deinit();
                WIDGET.update_info().layout().render();

                pages.with(|pages| {
                    if sel_pg_i < pages.len() {
                        // is valid selection from pages

                        SELECTED_PAGE_VAR.set(pages[sel_pg_i].clone());

                        // subscribe back/next
                        cmds = subscribe(sel_pg_i, pages);
                        // build and init
                        *c.node() = build(sel_pg_i, pages, None);
                        c.init();
                    } else {
                        // custom page or empty pages

                        // no default back/next support
                        cmds = [CommandHandle::dummy(), CommandHandle::dummy()];

                        if sel_pg_i == CUSTOM_PAGE_I {
                            // valid custom selection
                            SELECTED_PAGE_VAR.with(|pg| {
                                *c.node() = build(CUSTOM_PAGE_I, pages, Some(pg));
                            });
                            c.init();
                        } else {
                            // empty pages
                            if !pages.is_empty() {
                                tracing::error!("invalid page selection, {} in {}", sel_pg_i, pages.len());
                            }
                            *c.node() = UiNode::nil();
                            SELECTED_PAGE_VAR.set(Page::nil());
                        }
                    }
                });
            }
        }
        _ => {}
    })
}

fn subscribe(index: usize, pages: &[Page]) -> [CommandHandle; 2] {
    let id = WIDGET.id();
    let cmds = [BACK_CMD.scoped(id).subscribe(false), NEXT_CMD.scoped(id).subscribe(false)];

    let mut flags = MergeVarBuilder::new();
    for p in pages {
        flags.push(p.skip.0.clone());
    }
    flags.push(pages[index].can_back.0.clone());
    flags.push(pages[index].can_next.0.clone());
    let skips_len = pages.len();
    let can_dos = flags.build(move |flags| {
        let mut can_back = false;
        if flags.get(skips_len) {
            // if can_back.get()
            for i in 0..index {
                can_back = !flags.get(i);
                if can_back {
                    // if has prev pages that are not skip
                    break;
                }
            }
        }
        let mut can_next = false;
        if flags.get(skips_len + 1) {
            // if can_next.get()
            for i in index + 1..skips_len {
                can_next = !flags.get(i);
                if can_next {
                    // if has next pages that are not skip
                    break;
                }
            }
        }
        [can_back, can_next]
    });

    can_dos.set_bind_map(cmds[0].enabled(), |[b, _]| *b).perm();
    can_dos.set_bind_map(cmds[1].enabled(), |[_, n]| *n).perm();
    cmds[0].enabled().hold(can_dos).perm();

    cmds
}
fn build(index: usize, pages: &[Page], custom_page: Option<&Page>) -> UiNode {
    let page = custom_page.unwrap_or_else(|| &pages[index]);
    let args = PageArgs {
        index,
        pages_len: pages.len(),
        title: page.title.0.clone(),
        info: page.info.0.clone(),
        can_back: page.can_back.0.clone(),
        can_next: page.can_next.0.clone(),
    };
    let header = (page.header)(args.clone());
    let side = (page.side)(args.clone());
    let content = (page.content)(args.clone());
    let footer = (page.footer)(args.clone());

    let header = if header.is_nil() {
        header
    } else {
        let background = HEADER_BACKGROUND_FN_VAR.get()(());
        HEADER_FN_VAR.get()(HeaderFnArgs {
            header,
            background,
            index,
            pages_len: pages.len(),
            titles: pages.iter().map(|p| p.title.0.clone()).collect(),
            skips: pages.iter().map(|p| p.skip.0.clone()).collect(),
        })
    };
    let side = if side.is_nil() {
        side
    } else {
        let background = SIDE_BACKGROUND_FN_VAR.get()(());
        let side_extra = SIDE_EXTRA_FN_VAR.get()(args.clone());
        SIDE_FN_VAR.get()(SideFnArgs {
            side,
            background,
            side_extra,
            index,
            pages_len: pages.len(),
        })
    };
    let content = CONTENT_FN_VAR.get()(ContentFnArgs {
        content,
        content_fill: page.content_fill,
        index,
        pages_len: pages.len(),
    });
    let footer_extra = FOOTER_EXTRA_FN_VAR.get()(args);
    let footer = FOOTER_FN_VAR.get()(FooterFnArgs {
        footer,
        footer_extra,
        index,
        pages_len: pages.len(),
    });

    PANEL_FN_VAR.get()(PanelFnArgs {
        header,
        side,
        content,
        footer,
    })
}

/// Controls the parent wizard.
pub struct WIZARD;
impl WIZARD {
    /// Gets the ID of the wizard ancestor represented by the [`WIZARD`].
    pub fn try_id(&self) -> Option<WidgetId> {
        if WIZARD_CTX.is_default() { None } else { Some(WIZARD_CTX.get().id) }
    }
    /// Gets the ID of the wizard ancestor represented by the [`WIZARD`].
    ///
    /// # Panics
    ///
    /// Panics if not inside a wizard.
    pub fn id(&self) -> WidgetId {
        WIZARD_CTX.get().id
    }

    /// Request `BACK_CMD`.
    pub fn back(&self) {
        BACK_CMD.scoped(self.id()).notify();
    }

    /// Request `NEXT_CMD`.
    pub fn next(&self) {
        NEXT_CMD.scoped(self.id()).notify();
    }

    /// Request `BEGIN_CMD`.
    pub fn begin(&self) {
        BEGIN_CMD.scoped(self.id()).notify();
    }

    /// Request `BEGIN_CMD` with a custom param.
    pub fn begin_param(&self, param: impl Any + Send + Sync) {
        BEGIN_CMD.scoped(self.id()).notify_param(param);
    }

    /// Request `FINISH_CMD`.
    pub fn finish(&self) {
        FINISH_CMD.scoped(self.id()).notify();
    }

    /// Request `FINISH_CMD` with a custom param.
    pub fn finish_param(&self, param: impl Any + Send + Sync) {
        FINISH_CMD.scoped(self.id()).notify_param(param);
    }

    /// Get or set the selected page.
    pub fn selected_page(&self) -> Var<Page> {
        SELECTED_PAGE_VAR.into_var()
    }
}