blockworx/tutorial/

library.rs

//! The Learn library (spec §8.3): what there is to watch, and what the
//! viewer has watched of it.
//!
//! **Chapters are the addressable unit.** A library of twenty walkthroughs is
//! twenty answers; the same twenty broken into chapters is sixty-five, and
//! that is what the search matches and what a pick opens the player at. So a
//! [`Lesson`] carries its chapters whole rather than a count, and
//! [`Library::matching`] answers with the chapters that matched.
//!
//! Nothing here reads a `.bwx` twice: opening one costs a replay, so the
//! library is built once and holds what the cards and the palette need —
//! title, chapters, length, and the tools the log's `teaches/` tags name. The
//! container itself is re-opened only when something is actually played.
//!
//! [`Watched`] is a per-viewer convenience and not document data: how far
//! through a tutorial this person got has no business in anyone's log, so it
//! rides the eframe storage DB beside the recent-files list.

use core::time::Duration;
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use blockworx_doc::rev::Rev;

use crate::tools::names::ToolName;
use crate::tutorial::reader::{Chapter, Tutorial};

/// Everything the Learn segment, the palette and the selection overlay know
/// about what there is to watch.
#[derive(Default)]
pub struct Library {
    lessons: Vec<Lesson>,
}

/// One walkthrough, as a card: what it is called, what is in it, how long it
/// runs, and where to re-open it.
pub struct Lesson {
    /// The container's own root — the only thing a player needs to open it.
    pub root: PathBuf,
    /// The diagram's own name, which is what a tutorial is called (D20).
    pub title: String,
    pub chapters: Vec<Chapter>,
    /// The whole of it: the sum of its chapters, which are the sum of their
    /// commits' synthesized timelines. The substrate's number, never the
    /// UI's (`docs/choreographer-playbook.md` 7·8).
    pub duration: Duration,
    pub teaches: Vec<ToolName>,
}

impl Library {
    /// Open every tutorial the build ships, skipping any that will not read.
    ///
    /// A container that has rotted is not worth refusing the whole library
    /// over: what a viewer loses is one card, and what they would lose
    /// otherwise is the segment.
    pub fn shipped() -> Self {
        Self::under(&shipped_root())
    }

    /// Every `.bwx` in `dir`, in the order the directory names them (sorted,
    /// so the library reads the same on every platform).
    pub fn under(dir: &Path) -> Self {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return Library::default();
        };
        let mut roots: Vec<PathBuf> = entries
            .filter_map(Result::ok)
            .map(|entry| entry.path())
            .filter(|path| path.extension().is_some_and(|ext| ext == "bwx"))
            .collect();
        roots.sort();
        Library {
            lessons: roots.iter().filter_map(|root| Lesson::open(root)).collect(),
        }
    }

    pub fn lessons(&self) -> &[Lesson] {
        &self.lessons
    }

    pub fn is_empty(&self) -> bool {
        self.lessons.is_empty()
    }

    /// The lessons `query` reaches, each with the chapters that matched.
    ///
    /// An empty query is every lesson with every chapter — the library at
    /// rest. Otherwise a chapter matches on its own title and a lesson
    /// matches on its name, in which case all of its chapters are offered:
    /// searching for a tutorial by name must not hide what is inside it.
    pub fn matching<'a>(&'a self, query: &str) -> Vec<(&'a Lesson, Vec<&'a Chapter>)> {
        let query = query.trim().to_lowercase();
        self.lessons
            .iter()
            .filter_map(|lesson| {
                if query.is_empty() || lesson.title.to_lowercase().contains(&query) {
                    return Some((lesson, lesson.chapters.iter().collect()));
                }
                let hits: Vec<&Chapter> = lesson
                    .chapters
                    .iter()
                    .filter(|chapter| chapter.title.to_lowercase().contains(&query))
                    .collect();
                (!hits.is_empty()).then_some((lesson, hits))
            })
            .collect()
    }

    /// The lessons that teach `tool` — what the selection overlay's
    /// walkthrough entry (R15) and the tool cluster's ring are looking for.
    pub fn teaching(&self, tool: ToolName) -> impl Iterator<Item = &Lesson> {
        self.lessons
            .iter()
            .filter(move |lesson| lesson.teaches.contains(&tool))
    }

    /// The lesson at `root`, for a pick that named one.
    pub fn at(&self, root: &Path) -> Option<&Lesson> {
        self.lessons.iter().find(|lesson| lesson.root == root)
    }
}

impl Lesson {
    fn open(root: &Path) -> Option<Self> {
        let tutorial = Tutorial::open(root)
            .inspect_err(|error| tracing::warn!("{}: {error}", root.display()))
            .ok()?;
        let chapters = tutorial.chapters().to_vec();
        Some(Lesson {
            root: root.to_path_buf(),
            title: tutorial.name().to_owned(),
            duration: chapters.iter().map(|chapter| chapter.duration).sum(),
            teaches: tutorial.teaches(),
            chapters,
        })
    }

    /// Where this lesson's `nth` chapter begins, for a pick that named one.
    pub fn chapter_at(&self, nth: usize) -> Option<Rev> {
        self.chapters.get(nth).map(|chapter| chapter.at)
    }

    /// Which chapter holds `rev` — the one that opened most recently at or
    /// before it. `None` for a rev before the first chapter opens, which is
    /// the setup a converted container carries.
    pub fn chapter_of(&self, rev: Rev) -> Option<usize> {
        self.chapters.iter().rposition(|chapter| chapter.at <= rev)
    }
}

/// How far through each tutorial this viewer has got: the furthest chapter
/// they have reached, by the tutorial's title.
///
/// Not document data and never in a log — it is one person's place in one
/// browser or one desktop session, so it lives where the recent-files list
/// and the navigator's own state live.
#[derive(Clone, Default, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Watched(BTreeMap<String, usize>);

/// What the library offers a viewer about a lesson they have met before.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Progress {
    /// Never opened.
    Fresh,
    /// Left part way through, at this chapter.
    Resume(usize),
    /// Reached the last chapter.
    Watched,
}

impl Watched {
    /// Record that `title`'s `nth` chapter was reached. Furthest, not last:
    /// jumping back to chapter one is re-watching, not losing your place.
    pub fn reached(&mut self, title: &str, nth: usize) {
        let furthest = self.0.entry(title.to_owned()).or_default();
        *furthest = (*furthest).max(nth);
    }

    /// What to offer for a lesson with `chapters` chapters.
    pub fn of(&self, title: &str, chapters: usize) -> Progress {
        match self.0.get(title) {
            None => Progress::Fresh,
            Some(&nth) if nth + 1 >= chapters => Progress::Watched,
            Some(&nth) => Progress::Resume(nth),
        }
    }

    /// Forget everything — the one thing a viewer might reasonably ask of a
    /// watched list.
    pub fn clear(&mut self) {
        self.0.clear();
    }
}

/// A duration as a viewer reads one: `m:ss`, the "4 minutes / 40 seconds" of
/// §8.3 written the way a player writes it. Stated once, because the library
/// card, the palette row and the overlay's walkthrough entry must all say the
/// same number the same way.
pub fn clock(of: Duration) -> String {
    let seconds = of.as_secs();
    format!("{}:{:02}", seconds / 60, seconds % 60)
}

/// Where the shipped tutorials are: beside the executable in an installed
/// build, and in the source tree while developing.
///
/// Named, not fixed: packaging has not been decided (Phase 8), so the second
/// candidate is what actually answers today.
fn shipped_root() -> PathBuf {
    let beside_the_binary = std::env::current_exe()
        .ok()
        .and_then(|exe| exe.parent().map(|dir| dir.join("tutorials")))
        .filter(|dir| dir.is_dir());
    beside_the_binary
        .unwrap_or_else(|| Path::new(env!("CARGO_MANIFEST_DIR")).join("fixtures/tutorials"))
}

#[cfg(test)]
mod tests {
    use super::*;

    fn library() -> Library {
        let library = Library::shipped();
        assert_eq!(
            library.lessons().len(),
            3,
            "precondition: the build ships three tutorials",
        );
        library
    }

    /// Every shipped tutorial is a card with the three things §8.3 asks a
    /// library to show: what it is called, what is in it, and how long it is.
    #[test]
    fn the_library_reads_every_shipped_tutorial() {
        for lesson in library().lessons() {
            assert!(!lesson.title.is_empty(), "a lesson with no name");
            assert!(
                !lesson.chapters.is_empty(),
                "{} has no chapter to navigate by",
                lesson.title,
            );
            assert_eq!(
                lesson.duration,
                lesson.chapters.iter().map(|c| c.duration).sum::<Duration>(),
                "{}'s length is not the sum of its chapters",
                lesson.title,
            );
            assert!(
                !lesson.teaches.is_empty(),
                "{} does not say what it teaches",
                lesson.title,
            );
        }
    }

    /// §8.3: *"Search matches chapter titles."* A word only one chapter uses
    /// finds that chapter and nothing else, and the lesson it belongs to
    /// comes with it so the result is placeable.
    #[test]
    fn the_search_matches_chapter_titles() {
        let library = library();
        let hits = library.matching("opposite");
        let [(lesson, chapters)] = hits.as_slice() else {
            panic!("\"opposite\" reached {} lessons, not one", hits.len());
        };
        assert_eq!(lesson.title, "first-block");
        assert!(
            chapters
                .iter()
                .all(|chapter| chapter.title.to_lowercase().contains("opposite")),
            "the search offered chapters that do not match: {:?}",
            chapters.iter().map(|c| &c.title).collect::<Vec<_>>(),
        );
        assert!(
            chapters.len() < lesson.chapters.len(),
            "precondition: the lesson has chapters the query does not reach",
        );
    }

    /// A lesson found by its own name offers everything in it: the query
    /// named the tutorial, not a place inside it.
    #[test]
    fn a_lesson_found_by_name_keeps_all_its_chapters() {
        let library = library();
        let hits = library.matching("first-route");
        let [(lesson, chapters)] = hits.as_slice() else {
            panic!("\"first-route\" reached {} lessons, not one", hits.len());
        };
        assert_eq!(chapters.len(), lesson.chapters.len());
        assert_eq!(library.matching("").len(), 3, "an empty query is the shelf");
        assert!(library.matching("zzzz").is_empty());
    }

    /// The `teaches/` tags reaching the two surfaces that consume them.
    #[test]
    fn a_lesson_is_found_by_the_tool_it_teaches() {
        let library = library();
        let taught: Vec<&str> = library
            .teaching(ToolName::NewBlock)
            .map(|lesson| lesson.title.as_str())
            .collect();
        assert_eq!(taught, ["first-block"]);
        assert_eq!(library.teaching(ToolName::AddText).count(), 0);
    }

    /// Watched state: furthest reached, offered as a resume until the last
    /// chapter, and then not offered at all.
    #[test]
    fn the_watched_list_offers_a_resume_until_the_end() {
        let mut watched = Watched::default();
        assert_eq!(watched.of("first-block", 4), Progress::Fresh);

        watched.reached("first-block", 2);
        assert_eq!(watched.of("first-block", 4), Progress::Resume(2));

        watched.reached("first-block", 1);
        assert_eq!(
            watched.of("first-block", 4),
            Progress::Resume(2),
            "going back a chapter lost the viewer's place",
        );

        watched.reached("first-block", 3);
        assert_eq!(watched.of("first-block", 4), Progress::Watched);
        assert_eq!(watched.of("first-route", 5), Progress::Fresh);

        watched.clear();
        assert_eq!(watched.of("first-block", 4), Progress::Fresh);
    }

    /// The one spelling of a length, so three surfaces cannot word the same
    /// number three ways.
    #[test]
    fn a_length_reads_as_minutes_and_seconds() {
        assert_eq!(clock(Duration::ZERO), "0:00");
        assert_eq!(clock(Duration::from_millis(9_900)), "0:09");
        assert_eq!(clock(Duration::from_secs(65)), "1:05");
        assert_eq!(clock(Duration::from_mins(10)), "10:00");
    }

    /// A rev lands in the chapter that opened at or before it. The converted
    /// containers all open on a chapter (7·9: *"the opening chapter covers
    /// the setup"*), so nothing in one falls outside every chapter — only a
    /// rev before the log begins does.
    #[test]
    fn a_rev_belongs_to_the_chapter_that_opened_it() {
        let library = library();
        let lesson = library
            .lessons()
            .iter()
            .find(|lesson| lesson.title == "first-block")
            .expect("the first-block lesson");
        assert!(
            lesson.chapters.len() > 1,
            "precondition: there is a second chapter to fall into",
        );
        assert_eq!(lesson.chapter_of(Rev::ZERO), None);
        assert_eq!(lesson.chapter_of(lesson.chapters[0].at), Some(0));
        assert_eq!(
            lesson.chapter_of(lesson.chapters[1].at),
            Some(1),
            "a chapter's own opening rev belongs to it",
        );
        assert_eq!(
            lesson.chapter_of(lesson.chapters[1].at.prev().expect("a rev before it")),
            Some(0),
            "the rev before a chapter opens still belongs to the one above it",
        );
        assert_eq!(lesson.chapter_at(1), Some(lesson.chapters[1].at));
        assert_eq!(lesson.chapter_at(99), None);
    }
}