blockworx/shell/

learn.rs

//! The Navigator's Learn segment (spec §8.3): the library.
//!
//! **Chapters are primary.** A card names the walkthrough and how long it
//! runs, and under it stand its chapters — ~65 addressable answers rather
//! than 20 videos. The filter matches chapter titles, so a viewer looking
//! for "the opposite corner" lands on the chapter that says it rather than
//! on the tutorial that contains it.
//!
//! **A pick hands off and leaves the panel open** (§8), like a rev pick and
//! a block pick: the player opens over the canvas beside it, and browsing on
//! is one open rather than several.
//!
//! The web build has no containers to list yet, so its segment says so
//! plainly instead of opening onto an empty shelf.

#[cfg(not(target_arch = "wasm32"))]
use crate::{
    shell::glass,
    tools::tool::{Action, Walkthrough},
    tutorial::library::{Library, Progress, Watched, clock},
};

/// The air between the segment header and the first card.
const LEAD: f32 = 12.0;

/// What the library is a view of.
#[cfg(not(target_arch = "wasm32"))]
#[derive(Clone, Copy)]
pub struct Learn<'a> {
    pub library: &'a Library,
    /// How far this viewer got through each of them — a per-viewer
    /// convenience, not document data.
    pub watched: &'a Watched,
}

/// Draw the library.
#[cfg(not(target_arch = "wasm32"))]
pub fn body(ui: &mut egui::Ui, learn: Learn<'_>) -> Option<Action> {
    let ctx = ui.ctx().clone();
    let filter_id = filter_id();
    let mut filter: String = ctx.data_mut(|d| d.get_temp::<String>(filter_id).unwrap_or_default());
    ui.add(
        egui::TextEdit::singleline(&mut filter)
            .id(filter_id)
            .hint_text("Search chapters\u{2026}")
            .desired_width(f32::INFINITY),
    );
    ctx.data_mut(|d| d.insert_temp(filter_id, filter.clone()));
    ui.separator();
    if learn.library.is_empty() {
        ui.add_space(LEAD);
        ui.label(
            egui::RichText::new("No walkthroughs are installed with this build.")
                .small()
                .weak(),
        );
        return None;
    }
    let mut picked = None;
    egui::ScrollArea::vertical()
        .auto_shrink([false, false])
        .show(ui, |ui| {
            let matched = learn.library.matching(&filter);
            if matched.is_empty() {
                ui.add_space(LEAD);
                ui.label(egui::RichText::new("Nothing matches.").small().weak());
                return;
            }
            for (lesson, chapters) in matched {
                ui.add_space(LEAD);
                if let Some(pick) = card(ui, lesson, &chapters, learn.watched) {
                    picked = Some(pick);
                }
            }
            ui.add_space(LEAD);
        });
    picked.map(Action::Walkthrough)
}

/// One walkthrough: the title row that plays it from where the viewer left
/// off, and its chapters under it. Reports the rev a pick asked for, or
/// `None` where the pick meant "from the top".
#[cfg(not(target_arch = "wasm32"))]
fn card(
    ui: &mut egui::Ui,
    lesson: &crate::tutorial::library::Lesson,
    chapters: &[&crate::tutorial::reader::Chapter],
    watched: &Watched,
) -> Option<Walkthrough> {
    let mut picked = None;
    let progress = watched.of(&lesson.title, lesson.chapters.len());
    let head = ui.add(
        egui::Button::new(
            egui::RichText::new(&lesson.title)
                .color(glass::full_ink(ui.visuals()))
                .strong(),
        )
        .frame_when_inactive(false)
        .min_size(egui::vec2(ui.available_width(), glass::TAP * 0.7)),
    );
    if head.clicked() {
        // The resume offer *is* the head row's behaviour, not a second
        // control beside it: a card the viewer left part way through opens
        // where they left it, and a fresh one opens at the top.
        picked = Some(Walkthrough {
            root: lesson.root.clone(),
            at: match progress {
                Progress::Resume(nth) => lesson.chapter_at(nth),
                Progress::Fresh | Progress::Watched => None,
            },
        });
    }
    ui.label(
        egui::RichText::new(subtitle(lesson, progress))
            .small()
            .weak(),
    );
    for chapter in chapters {
        let nth = lesson
            .chapters
            .iter()
            .position(|held| held.at == chapter.at)
            .unwrap_or(0);
        let reached = if matches!(progress, Progress::Watched)
            || matches!(progress, Progress::Resume(furthest) if furthest >= nth)
        {
            Reached::Yes
        } else {
            Reached::No
        };
        let row = ui.add(
            egui::Button::new(chapter_line(&chapter.title, chapter.duration, reached))
                .frame_when_inactive(false)
                .min_size(egui::vec2(ui.available_width(), glass::TAP * 0.7)),
        );
        if row.clicked() {
            picked = Some(Walkthrough {
                root: lesson.root.clone(),
                at: Some(chapter.at),
            });
        }
    }
    picked
}

/// What a card says under its name: how much there is, and what this viewer
/// has done with it.
#[cfg(not(target_arch = "wasm32"))]
fn subtitle(lesson: &crate::tutorial::library::Lesson, progress: Progress) -> String {
    let bulk = format!(
        "{} chapters \u{b7} {}",
        lesson.chapters.len(),
        clock(lesson.duration),
    );
    match progress {
        Progress::Fresh => bulk,
        Progress::Watched => format!("{bulk} \u{b7} watched"),
        Progress::Resume(nth) => match lesson.chapters.get(nth) {
            None => bulk,
            Some(chapter) => format!("{bulk} \u{b7} resume at \u{201c}{}\u{201d}", chapter.title),
        },
    }
}

/// A chapter row: its title, its length, and a mark where the viewer has
/// already been.
#[cfg(not(target_arch = "wasm32"))]
fn chapter_line(title: &str, duration: core::time::Duration, reached: Reached) -> String {
    let mark = match reached {
        Reached::Yes => "\u{2713} ",
        Reached::No => "",
    };
    format!("{mark}{title}  {}", clock(duration))
}

/// Whether the viewer has already been through a chapter — the mark on its
/// row. A two-valued enum rather than a `bool`, so the call site says which
/// of the two it means.
#[cfg(not(target_arch = "wasm32"))]
#[derive(Clone, Copy, PartialEq, Eq)]
enum Reached {
    Yes,
    No,
}

#[cfg(not(target_arch = "wasm32"))]
fn filter_id() -> egui::Id {
    egui::Id::new("learn_filter")
}

/// §8's rule for the Hierarchy filter, applied here for the same reason: the
/// filter is a transient search, not a view the panel remembers.
#[cfg(not(target_arch = "wasm32"))]
pub fn clear_the_filter(ctx: &egui::Context) {
    ctx.data_mut(|d| d.insert_temp(filter_id(), String::new()));
}

/// The segment where there are no containers to list.
#[cfg(target_arch = "wasm32")]
pub fn body(ui: &mut egui::Ui) {
    ui.add_space(LEAD);
    ui.label("Walkthroughs arrive with the web build.");
    ui.label(
        egui::RichText::new(
            "A walkthrough is an ordinary diagram, and the browser gets diagrams of its \
             own in Phase 8.",
        )
        .small()
        .weak(),
    );
}

#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests {
    use super::*;
    use crate::shell::tests::screen;
    use crate::shell::workspace::{PanelView, Workspace};
    use crate::tools::painted::Chrome;

    /// The segment, drawn inside the real navigator so the panel's own width
    /// and clipping are in the answer.
    struct Shelf {
        chrome: Chrome,
        library: Library,
        watched: Watched,
        state: Workspace,
        picked: Vec<Walkthrough>,
    }

    impl Shelf {
        fn new() -> Self {
            let mut state = Workspace::default();
            state.show(PanelView::Learn);
            let library = Library::shipped();
            assert!(
                !library.is_empty(),
                "precondition: the build ships walkthroughs to list",
            );
            let mut shelf = Shelf {
                chrome: Chrome::new(screen()),
                library,
                watched: Watched::default(),
                state,
                picked: Vec::new(),
            };
            shelf.settle();
            shelf
        }

        fn settle(&mut self) {
            let Shelf {
                chrome,
                library,
                watched,
                state,
                picked,
            } = self;
            chrome.settle(|ui| {
                let mut floating = crate::shell::Chrome::over(ui.ctx(), ui.max_rect());
                let drawn = crate::shell::navigator::navigator(&mut floating, state, |ui| {
                    body(ui, Learn { library, watched })
                });
                if let Some(Action::Walkthrough(pick)) = drawn.action {
                    picked.push(pick);
                }
            });
        }

        fn click(&mut self, text: &str) {
            let found = self.chrome.rect(text);
            assert!(
                found.is_some(),
                "the library drew no {text:?}: {:?}",
                self.chrome.texts(),
            );
            let at = found.unwrap_or(egui::Rect::ZERO).center();
            let Shelf {
                chrome,
                library,
                watched,
                state,
                picked,
            } = self;
            chrome.click_at(at, |ui| {
                let mut floating = crate::shell::Chrome::over(ui.ctx(), ui.max_rect());
                let drawn = crate::shell::navigator::navigator(&mut floating, state, |ui| {
                    body(ui, Learn { library, watched })
                });
                if let Some(Action::Walkthrough(pick)) = drawn.action {
                    picked.push(pick);
                }
            });
        }
    }

    /// §8.3's three facts per card, on screen: the name, what is in it, and
    /// how long it is — plus the chapters, which are the addressable unit.
    #[test]
    fn the_library_lists_every_walkthrough_with_its_chapters() {
        let shelf = Shelf::new();
        for lesson in shelf.library.lessons() {
            assert!(
                shelf.chrome.shows(&lesson.title),
                "the library lost {}: {:?}",
                lesson.title,
                shelf.chrome.texts(),
            );
            for chapter in &lesson.chapters {
                assert!(
                    shelf.chrome.says(&chapter.title),
                    "{} lost the chapter {:?}",
                    lesson.title,
                    chapter.title,
                );
            }
            assert!(
                shelf
                    .chrome
                    .texts()
                    .iter()
                    .any(|said| said.contains(&clock(lesson.duration))),
                "{} does not say how long it runs",
                lesson.title,
            );
        }
    }

    /// A chapter pick opens the player *there* — the addressable answer §8.3
    /// asks for — and the panel stays open, which is the Navigator's own
    /// hand-off contract.
    #[test]
    fn a_chapter_pick_opens_the_player_at_it_and_keeps_the_panel_open() {
        let mut shelf = Shelf::new();
        let lesson = shelf
            .library
            .lessons()
            .iter()
            .find(|lesson| lesson.title == "first-block")
            .expect("the first-block walkthrough");
        let wanted = lesson.chapters[1].clone();
        let root = lesson.root.clone();

        shelf.click(&chapter_line(&wanted.title, wanted.duration, Reached::No));
        assert_eq!(
            shelf.picked,
            vec![Walkthrough {
                root,
                at: Some(wanted.at),
            }],
        );
        assert!(shelf.state.open(), "a pick shut the panel from inside it");
    }

    /// A fresh card plays from the top; one the viewer left part way through
    /// offers to resume, and says so on the card.
    #[test]
    fn a_card_plays_from_the_top_until_there_is_somewhere_to_resume() {
        let mut shelf = Shelf::new();
        shelf.click("first-block");
        assert_eq!(
            shelf.picked.last().map(|pick| pick.at),
            Some(None),
            "a fresh walkthrough did not open at its beginning",
        );

        shelf.watched.reached("first-block", 2);
        shelf.settle();
        let resume = shelf
            .library
            .at(&shelf.picked[0].root.clone())
            .expect("the lesson is in the library")
            .chapter_at(2);
        assert!(
            shelf
                .chrome
                .texts()
                .iter()
                .any(|said| said.contains("resume at")),
            "the card does not offer to resume: {:?}",
            shelf.chrome.texts(),
        );
        shelf.click("first-block");
        assert_eq!(
            shelf.picked.last().map(|pick| pick.at),
            Some(resume),
            "the card did not resume where the viewer left it",
        );
    }

    /// §8.3: the search matches chapter titles, and what it hides is the
    /// walkthroughs no chapter of which matched.
    #[test]
    fn the_filter_narrows_the_shelf_to_matching_chapters() {
        let mut shelf = Shelf::new();
        assert!(
            shelf.chrome.says("Wire two blocks"),
            "precondition: the unfiltered shelf lists every walkthrough",
        );
        clear_the_filter(shelf.chrome.ctx());
        shelf
            .chrome
            .ctx()
            .data_mut(|d| d.insert_temp(filter_id(), "opposite".to_owned()));
        shelf.settle();
        assert!(
            shelf.chrome.says("first-block"),
            "the matching walkthrough is gone: {:?}",
            shelf.chrome.texts(),
        );
        assert!(
            !shelf.chrome.says("first-route"),
            "a walkthrough no chapter of which matched is still listed: {:?}",
            shelf.chrome.texts(),
        );
    }
}