guise/overlay/

tour.rs

//! `Tour` — a step-by-step onboarding overlay (gpui entity).
//!
//! A sequence of titled steps shown as a centered card over a scrim, with
//! Back/Next/Skip and progress dots. Emits [`TourEvent`] as the user moves
//! through it. Anchoring to specific UI elements is left to the host (pair
//! a step's text with highlighting in your own chrome if needed).

use gpui::prelude::*;
use gpui::{
    deferred, div, px, Context, EventEmitter, FocusHandle, FontWeight, IntoElement, SharedString,
    Window,
};

use crate::devtools::ProbedAny;
use crate::theme::{theme, Size};

/// Tour progress events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TourEvent {
    /// Moved to this step index.
    Step(usize),
    /// Finished the last step.
    Finished,
    /// Dismissed early.
    Skipped,
}

struct TourStep {
    title: SharedString,
    body: SharedString,
}

/// An onboarding walkthrough. Create with
/// `cx.new(|cx| Tour::new(cx).step("Welcome", "…").step("Panels", "…"))`,
/// then `tour.update(cx, |t, cx| t.start(cx))`.
pub struct Tour {
    steps: Vec<TourStep>,
    current: usize,
    open: bool,
    focus: FocusHandle,
}

impl EventEmitter<TourEvent> for Tour {}

impl Tour {
    pub fn new(cx: &mut Context<Self>) -> Self {
        Tour {
            steps: Vec::new(),
            current: 0,
            open: false,
            focus: cx.focus_handle(),
        }
    }

    pub fn step(mut self, title: impl Into<SharedString>, body: impl Into<SharedString>) -> Self {
        self.steps.push(TourStep {
            title: title.into(),
            body: body.into(),
        });
        self
    }

    pub fn is_open(&self) -> bool {
        self.open
    }

    pub fn current(&self) -> usize {
        self.current
    }

    /// Show the tour from the first step.
    pub fn start(&mut self, cx: &mut Context<Self>) {
        if !self.steps.is_empty() {
            self.current = 0;
            self.open = true;
            cx.emit(TourEvent::Step(0));
            cx.notify();
        }
    }

    pub fn next(&mut self, cx: &mut Context<Self>) {
        if self.current + 1 < self.steps.len() {
            self.current += 1;
            cx.emit(TourEvent::Step(self.current));
        } else {
            self.open = false;
            cx.emit(TourEvent::Finished);
        }
        cx.notify();
    }

    pub fn back(&mut self, cx: &mut Context<Self>) {
        if self.current > 0 {
            self.current -= 1;
            cx.emit(TourEvent::Step(self.current));
            cx.notify();
        }
    }

    pub fn skip(&mut self, cx: &mut Context<Self>) {
        if self.open {
            self.open = false;
            cx.emit(TourEvent::Skipped);
            cx.notify();
        }
    }
}

impl Render for Tour {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        if !self.open || self.steps.is_empty() {
            return div().into_any_element();
        }

        let t = theme(cx);
        let radius = t.radius(Size::Md);
        let surface = t.surface().hsla();
        let surface_hover = t.surface_hover().hsla();
        let border = t.border().hsla();
        let text_color = t.text().hsla();
        let dimmed = t.dimmed().hsla();
        let accent = t.primary();
        let accent_bg = accent.hsla();
        let accent_fg = accent.contrasting().hsla();
        let scrim = t.black.alpha(0.55);
        let font = t.font_size(Size::Sm);

        let step = &self.steps[self.current];
        let last = self.current + 1 == self.steps.len();
        let viewport = window.viewport_size();

        let mut dots = div().flex().gap(px(5.0));
        for i in 0..self.steps.len() {
            dots = dots.child(
                div()
                    .w(px(7.0))
                    .h(px(7.0))
                    .rounded_full()
                    .bg(if i == self.current { accent_bg } else { border }),
            );
        }

        let button = |id: &'static str, label: &'static str, filled: bool| {
            let mut b = div()
                .id(id)
                .px(px(12.0))
                .py(px(5.0))
                .rounded(px(t.radius(Size::Sm)))
                .text_size(px(font));
            if filled {
                b = b.bg(accent_bg).text_color(accent_fg);
            } else {
                b = b
                    .border_1()
                    .border_color(border)
                    .text_color(text_color)
                    .hover(move |s| s.bg(surface_hover));
            }
            b.child(SharedString::new_static(label))
        };

        let mut controls = div().flex().items_center().justify_between().pt(px(4.0));
        controls = controls.child(
            div()
                .id("guise-tour-skip")
                .text_size(px(font))
                .text_color(dimmed)
                .hover(move |s| s.text_color(text_color))
                .child(SharedString::new_static("Skip"))
                .on_click(cx.listener(|this, _ev, _window, cx| this.skip(cx))),
        );
        let mut actions = div().flex().gap(px(8.0));
        if self.current > 0 {
            actions = actions.child(
                button("guise-tour-back", "Back", false)
                    .on_click(cx.listener(|this, _ev, _window, cx| this.back(cx))),
            );
        }
        actions = actions.child(
            button(
                "guise-tour-next",
                if last { "Finish" } else { "Next" },
                true,
            )
            .on_click(cx.listener(|this, _ev, _window, cx| this.next(cx))),
        );
        controls = controls.child(actions);

        let card = div()
            .id("guise-tour-card")
            .occlude()
            .flex()
            .flex_col()
            .gap(px(10.0))
            .w(px(360.0))
            .p(px(t.spacing(Size::Md)))
            .rounded(px(radius))
            .bg(surface)
            .border_1()
            .border_color(border)
            .shadow_xl()
            .child(
                div()
                    .flex()
                    .items_center()
                    .justify_between()
                    .child(
                        div()
                            .font_weight(FontWeight::BOLD)
                            .text_color(text_color)
                            .child(step.title.clone()),
                    )
                    .child(div().text_size(px(font - 1.0)).text_color(dimmed).child(
                        SharedString::from(format!("{} / {}", self.current + 1, self.steps.len())),
                    )),
            )
            .child(
                div()
                    .text_size(px(font))
                    .text_color(dimmed)
                    .child(step.body.clone()),
            )
            .child(dots)
            .child(controls);

        let backdrop = div()
            .id("guise-tour-backdrop")
            .occlude()
            .absolute()
            .top(px(0.0))
            .left(px(0.0))
            .w(viewport.width)
            .h(viewport.height)
            .flex()
            .items_center()
            .justify_center()
            .bg(scrim)
            .track_focus(&self.focus)
            .child(card);

        deferred(backdrop)
            .into_any_element()
            .probe_any("Tour")
            .into_any_element()
    }
}