From 3d37ad424f585e24882aa406ea3369837d427afc Mon Sep 17 00:00:00 2001 From: aiongg Date: Thu, 12 Nov 2026 04:25:01 +0000 Subject: [PATCH] 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 --- .../ui-patterns/src/patterns/panels/tour.rs | 86 +++++++++++-------- .../src/patterns/panels/tour/stories.rs | 27 +++--- .../ui-patterns/src/patterns/panels/words.rs | 2 +- crates/ui-patterns/tests/it/panels/tour.rs | 76 ++++++++++++++-- 4 files changed, 131 insertions(+), 60 deletions(-) diff --git a/crates/ui-patterns/src/patterns/panels/tour.rs b/crates/ui-patterns/src/patterns/panels/tour.rs index 14eec8f6d..c782f4343 100644 --- a/crates/ui-patterns/src/patterns/panels/tour.rs +++ b/crates/ui-patterns/src/patterns/panels/tour.rs @@ -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, } -/// 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::(); let mut event: Option = 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 = 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) -> 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) -> 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 diff --git a/crates/ui-patterns/src/patterns/panels/tour/stories.rs b/crates/ui-patterns/src/patterns/panels/tour/stories.rs index e9e01a20b..3043f3ebe 100644 --- a/crates/ui-patterns/src/patterns/panels/tour/stories.rs +++ b/crates/ui-patterns/src/patterns/panels/tour/stories.rs @@ -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> = 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() } diff --git a/crates/ui-patterns/src/patterns/panels/words.rs b/crates/ui-patterns/src/patterns/panels/words.rs index 2bc77da9c..ee9abd63f 100644 --- a/crates/ui-patterns/src/patterns/panels/words.rs +++ b/crates/ui-patterns/src/patterns/panels/words.rs @@ -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}"; } } diff --git a/crates/ui-patterns/tests/it/panels/tour.rs b/crates/ui-patterns/tests/it/panels/tour.rs index 6a401ddc2..aea1c7eb0 100644 --- a/crates/ui-patterns/tests/it/panels/tour.rs +++ b/crates/ui-patterns/tests/it/panels/tour.rs @@ -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>, events: Rc>>) -> 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 { + 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 { + 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::()).is_empty(), "a step without a target shows no mark"); + index.set(0); + fixture.idle(10); + assert!(!fixture.styles_of(std::any::type_name::()).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>> = 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"); + } +}