Tour: the old card (count and close, title, text, Skip and the platform-ordered Back and Next) and a TargetMark on a step's target

This commit is contained in:
aiongg
2026-11-12 14:32:46 +00:00
parent b8e9b5b0ec
commit 3d37ad424f
4 changed files with 131 additions and 60 deletions
+49 -37
View File
@@ -1,18 +1,21 @@
//! `Tour` (24.4): a guided walk through the interface, one step at a time, a card beside the part it explains.
use super::words::PanelWords;
use crate::buttons::{Button, IconButton};
use crate::contract::overlay::{Anchor, Dismiss, FloatPlace, Outside, OverlayFit, Place, ViewportShare};
use crate::contract::{Bind, Overlay, Pattern, Props, Show as _, ShowContainer as _};
use crate::display::Text;
use crate::layout_components::Stack;
use crate::notices::{Notice, NoticeAction, NoticeLayout};
use crate::contract::{Bind, Gap, Overlay, Pattern, Props, RowAlign, Show as _, ShowContainer as _, clicked};
use crate::display::{Shade, TargetMark, Text};
use crate::layout_components::{Row, Stack};
use crate::popover::Popover;
use crate::runtime::commands::{CommandSet as _, Commands as _};
use crate::runtime::env::{Env, Label};
use crate::runtime::focus::Initial;
use crate::sections::{DialogRole, FooterBar, FooterButton};
use crate::style::TypeRole;
use craft_behavior::overlay::{Align, Side};
use craft_behavior::{EditEvent, Mixed};
use craft_theme::variant::Tone;
use craft_behavior::{EditEvent, IconId, Mixed};
use craft_theme::ControlSize;
use craft_theme::variant::Variant;
use egui::{Rect, Ui};
use std::sync::Arc;
@@ -85,15 +88,16 @@ pub struct TourOutput {
pub event: Option<TourEvent>,
}
/// A guided tour of the interface: a card with the step's heading and text, Skip, Back and Next (Done on the last
/// step) and the step count, beside the part the step points at. The rest of the window stays usable and undimmed:
/// only the card takes presses, and a press outside it leaves the tour running.
/// A guided tour of the interface: a card with the step count and a close button, the step's heading and text, Skip,
/// Back and Next (Done on the last step), beside the part the step points at, which a pulsing ring marks. The rest of
/// the window stays usable and undimmed: only the card takes presses, and a press outside it leaves the tour running.
///
/// - Show it while the tour runs; the app stops showing it on `Finished` and `Skipped`.
/// - The index binding holds the step; Next and Back change it and report the event. An index past the last step
/// shows the last step.
/// - Skip and the close button leave the tour on every step; Back is off on the first.
/// - Keys: Next has the focus when the step opens, so Enter goes on; Right and Left step forward and back (mirrored
/// in a right-to-left interface); Escape skips; Tab reaches Back and Skip.
/// in a right-to-left interface); Escape skips; Tab reaches the other buttons.
#[derive(Pattern, Props)]
pub struct Tour<'a> {
label: Label,
@@ -114,13 +118,16 @@ impl<'a> Tour<'a> {
let env = Env::of(ui);
let words = env.words::<PanelWords>();
let mut event: Option<TourEvent> = None;
// The tour's root container holds no content; the step's card is the popover it opens.
// The tour's root container holds the step's mark; the step's card is the popover it opens.
Stack::new().show(ui, |ui, root| {
let held = index.reborrow().read(root).and_then(|held| held.same().copied()).unwrap_or(0);
let at = held.min(last);
let step = &steps[at];
let count = words.tour_count.fill(&[("n", &env.format().integer(at as u64 + 1)), ("total", &env.format().integer(steps.len() as u64))]);
let layer = layer(step.target);
let layer = layer(step.target.map(|target| target.expand(env.tokens.space.pad.regular)));
if let Some(target) = step.target {
TargetMark::new(target).id_salt("mark").show_mark(ui);
}
let mut taken: Option<TourEvent> = None;
let forward = if at < last { TourEvent::Next } else { TourEvent::Finished };
let shown = Popover::new(step.title.clone(), Bind::given(true))
@@ -135,26 +142,31 @@ impl<'a> Tour<'a> {
TourCommands::Back => taken,
};
}
Stack::new().show(ui, |ui, _| {
let mut notice =
Notice::new(Tone::Neutral, step.text.clone()).title(step.title.clone()).layout(NoticeLayout::Inline).footer_actions();
// Reading order: Skip, Back, Next; the indices below follow it.
let mut order = Vec::with_capacity(3);
if at < last {
notice = notice.action(NoticeAction::new(words.tour_skip.clone()));
order.push(TourEvent::Skipped);
}
if at > 0 {
notice = notice.action(NoticeAction::new(words.tour_back.clone()));
order.push(TourEvent::Back);
}
notice = notice
.action(NoticeAction::new(if at < last { words.tour_next.clone() } else { words.tour_done.clone() }).default_action());
order.push(forward);
if let Some(event) = notice.show(ui).action.and_then(|at| order.get(at).copied()) {
taken = Some(event);
}
Text::new(count.clone()).show(ui);
Stack::new().gap(Gap::Row).show(ui, |ui, _| {
Row::new().align(RowAlign::SpaceBetween).fill_width().show(ui, |ui, _| {
Text::new(count.clone()).role(TypeRole::Caption).shade(Shade::Muted).show(ui);
let close = IconButton::new(IconId::new("close")).size(ControlSize::Sm).label(words.tour_skip.clone()).id_salt("close");
if clicked(&close.show(ui)) {
taken = Some(TourEvent::Skipped);
}
});
Text::new(step.title.clone()).role(TypeRole::Title).show(ui);
Text::new(step.text.clone()).show(ui);
Row::new().align(RowAlign::SpaceBetween).fill_width().show(ui, |ui, _| {
if clicked(&Button::new(words.tour_skip.clone()).variant(Variant::GHOST).id_salt("skip").show(ui)) {
taken = Some(TourEvent::Skipped);
}
let next = if at < last { words.tour_next.clone() } else { words.tour_done.clone() };
// The given order is the events' order; the footer shows them in the platform's order.
let picks = [TourEvent::Back, forward];
let buttons = [
FooterButton::new(words.tour_back.clone(), DialogRole::Other).enabled(at > 0),
FooterButton::new(next, DialogRole::Accept),
];
if let Some(event) = FooterBar::buttons(buttons).show_footer(ui).picked.and_then(|at| picks.get(at).copied()) {
taken = Some(event);
}
});
});
let moved = match taken {
Some(TourEvent::Next) => Some(at + 1),
@@ -172,13 +184,13 @@ impl<'a> Tour<'a> {
}
}
/// The card's layer: a popup beside `target`, else in the middle of the window. It blocks nothing and dims nothing; a
/// press outside leaves it open.
fn layer(target: Option<Rect>) -> Overlay {
/// The card's layer: a popup beside `anchor` (the step's target with a panel's padding around it, clear of its mark),
/// else in the middle of the window. It blocks nothing and dims nothing; a press outside leaves it open.
fn layer(anchor: Option<Rect>) -> Overlay {
let mut overlay = Overlay::popover().dismiss(Dismiss::new().outside(Outside::Keep));
overlay.fit = OverlayFit::ContentCapped(CARD_SHARE);
overlay.place = match target {
Some(target) => Place::anchored(Anchor::Rect(target), Side::End, Align::Center),
overlay.place = match anchor {
Some(anchor) => Place::anchored(Anchor::Rect(anchor), Side::End, Align::Center),
None => Place::Float(FloatPlace::centred()),
};
overlay
@@ -1,26 +1,19 @@
//! Stories of `Tour`.
use super::{Tour, TourStep};
use crate::contract::Bind;
use crate::buttons::Button;
use crate::contract::{Bind, Show as _};
use crate::testing::{Drive, StoryData, StoryOutput, story};
use egui::{Rect, Ui, pos2, vec2};
use std::sync::LazyLock;
/// Where the first step's part sits in the story's window, and how big it is.
const FIRST_AT: (f32, f32) = (40.0, 60.0);
const FIRST_SIZE: (f32, f32) = (160.0, 48.0);
static STEPS: LazyLock<Vec<TourStep>> = LazyLock::new(|| {
vec![
TourStep::new("Layers", "Every object of the poster is a layer. Reorder them here.")
.target(Rect::from_min_size(pos2(FIRST_AT.0, FIRST_AT.1), vec2(FIRST_SIZE.0, FIRST_SIZE.1))),
TourStep::new("Properties", "The selected layer's settings show in this panel."),
TourStep::new("Export", "When the poster is ready, export it from the File menu."),
]
});
use egui::Ui;
#[story(Tour<'static>, covers = [], drive = Drive::Never)]
fn tour(ui: &mut Ui, data: &mut StoryData) -> StoryOutput {
Tour::new("Welcome tour", STEPS.as_slice(), Bind::bound(data.value("index", 0_usize))).show(ui);
let layers = Button::new("Layers").show(ui);
let steps = [
TourStep::new("Layers", "Every object of the poster is a layer. Reorder them here.").target(layers.rect),
TourStep::new("Properties", "The selected layer's settings show in this panel."),
TourStep::new("Export", "When the poster is ready, export it from the File menu."),
];
Tour::new("Welcome tour", &steps, Bind::bound(data.value("index", 0_usize))).show(ui);
StoryOutput::default()
}
@@ -13,7 +13,7 @@ craft_ui::words! {
tour_back: "tour.back" = "Back";
tour_next: "tour.next" = "Next";
tour_done: "tour.done" = "Done";
tour_skip: "tour.skip" = "Skip";
tour_skip: "tour.skip" = "Skip Tour";
tour_count: template "tour.count" = "{n} of {total}";
}
}
+71 -5
View File
@@ -1,10 +1,11 @@
//! A tour blocks nothing: the window under its card stays usable.
//! A tour blocks nothing: the window under its card and its mark stays usable. Its card steps and leaves.
use craft_ui::buttons::Button;
use craft_ui::contract::{Bind, Show as _, clicked};
use craft_ui::patterns::panels::{Tour, TourStep};
use craft_ui::testing::{Fixture, trial};
use std::cell::Cell;
use craft_ui::contract::{Bind, Role, Show as _, clicked};
use craft_ui::display::TargetMark;
use craft_ui::patterns::panels::{Tour, TourEvent, TourStep};
use craft_ui::testing::{Fixture, Target, trial};
use std::cell::{Cell, RefCell};
use std::rc::Rc;
#[trial]
@@ -26,3 +27,68 @@ fn a_press_beside_the_tour_card_reaches_the_window_and_the_tour_stays() {
assert_eq!(presses.get(), 1, "the press went to the window under the tour");
assert!(fixture.by_label("Next").is_some(), "the tour's card stays");
}
/// A tour of three steps whose first points at a button, at the step `index` holds; the events go to `events`.
fn three_steps(index: Rc<Cell<usize>>, events: Rc<RefCell<Vec<TourEvent>>>) -> Fixture {
Fixture::new(move |ui| {
let layers = Button::new("Layers").show(ui);
let steps = [
TourStep::new("Layers", "Every object is a layer.").target(layers.rect),
TourStep::new("Properties", "Settings."),
TourStep::new("Export", "Export it."),
];
let mut at = index.get();
if let Some(event) = Tour::new("Welcome tour", &steps, Bind::bound(&mut at)).show(ui).event {
events.borrow_mut().push(event);
}
index.set(at);
})
}
/// The buttons named `name`, in tree order.
fn buttons(fixture: &Fixture, name: &str) -> Vec<Target> {
fixture.by_role(Role::BUTTON).into_iter().filter(|button| fixture.tree().name_of(button.node) == Some(name)).collect()
}
fn button(fixture: &Fixture, name: &str) -> Option<Target> {
buttons(fixture, name).into_iter().next()
}
#[trial]
fn a_step_with_a_target_shows_a_mark_and_one_without_shows_none() {
let index = Rc::new(Cell::new(1));
let mut fixture = three_steps(index.clone(), Rc::default());
fixture.idle(10);
assert!(fixture.styles_of(std::any::type_name::<TargetMark>()).is_empty(), "a step without a target shows no mark");
index.set(0);
fixture.idle(10);
assert!(!fixture.styles_of(std::any::type_name::<TargetMark>()).is_empty(), "a step with a target shows its mark");
}
#[trial]
fn next_and_back_keep_the_card_and_skip_or_close_leave_on_every_step() {
let index = Rc::new(Cell::new(0));
let events: Rc<RefCell<Vec<TourEvent>>> = Rc::default();
let mut fixture = three_steps(index.clone(), events.clone());
fixture.idle(10);
let back = button(&fixture, "Back").expect("Back shows on the first step");
fixture.click(&back).idle(4);
assert!(events.borrow().is_empty() && index.get() == 0, "Back is off on the first step");
let next = button(&fixture, "Next").expect("Next shows");
fixture.click(&next).idle(4);
assert_eq!(index.get(), 1, "Next moves on");
let back = button(&fixture, "Back").expect("the card stays");
fixture.click(&back).idle(4);
assert_eq!(index.get(), 0, "Back moves back");
assert_eq!(events.borrow().as_slice(), [TourEvent::Next, TourEvent::Back]);
index.set(2);
fixture.idle(10);
let skips = buttons(&fixture, "Skip Tour");
assert_eq!(skips.len(), 2, "the last step has the close button and Skip");
for skip in skips {
events.borrow_mut().clear();
fixture.click(&skip).idle(4);
assert_eq!(events.borrow().as_slice(), [TourEvent::Skipped], "each leaves the tour on the last step");
}
}