feat(record): add menu bar

There are two main concepts added to the viewport code:

- A **mask** is a subarea of the canvas which subsequent calls will implicitly not render outside of. This lets us overlay one component on top of another in a fixed area. We use this to allocate the top line of the screen to the menu bar and the rest of the screen to the files. We could also use this in the future for e.g. rendering files side-by-side.
- A **timestamp** is a monotonically-increasing integer assigned to each component as it's drawn. Previously, we tried to figure out which component was being clicked by finding all components which drew to a certain point on the screen and selecting the smallest one. In some cases, this wasn't sufficient. For example, the sticky file header may be larger than a changed line drawn behind it, but we still want to select the sticky file header in this case. Now, we use the timestamp value to infer which of two components is drawn on top (with the later-drawn component being on top).

The menu bar is a fairly straightforward state machine. There may come to be issues with managing interactions between components. For example, we now have an event to unfocus the menu bar, which means that we need to be aware of the menu bar when clicking on any other component on the screen. This sort of behavior will eventually lead to O(n^2) state transitions. The proper fix would probably be some kind of event system in combination with a focus system.

Author: arxanas

scm-record/README.md

@@ -23,29 +23,6 @@ This is a standalone binary that uses the `scm-record` library as a front-end, a
 - [Mercurial](https://www.mercurial-scm.org/): via [the `extdiff` extension](https://wiki.mercurial-scm.org/ExtdiffExtension). Only supports viewing diffs, not editing them.
 - [Jujutsu](https://github.com/martinvonz/jj): via [the `ui.diff-editor` option](https://github.com/martinvonz/jj/blob/main/docs/config.md#editing-diffs).
 
-# Keybindings
-
-Ideally, these would be documented in the UI itself.
-
-- `ctrl-c`, `q`: discard changes and quit. If there are unsaved changes, you will be prompted to confirm discarding them.
-- `c`: confirm changes and quit.
-- `f`: expand/collapse the current item.
-- `F`: expand/collapse all items.
-- `up`/`k`: select the next item.
-- `down`/`j`: select the previous item.
-- `left`/`h`: select the outer item.
-- `right`/`l`: select the inner item.
-- `space`: toggle the current item.
-- `enter`: toggle the current item and move to the next item of the same kind.
-- `a`: invert the toggled state of each item.
-- `A`: toggle or untoggle all items uniformly.
-- `ctrl-y`: scroll the viewport up by one line.
-- `ctrl-e`: scroll the viewport down by one line.
-- `page-up`/`ctrl-b`: scroll the viewport up by one screen.
-- `page-down`/`ctrl-f`: scroll the viewport up by one screen.
-- `ctrl-u`: move the selection half a screen up from the currently-selected item.
-- `ctrl-d`: move the selection half a screen down from the currently-selected item.
-
 # Integration with other projects
 
 Here's some projects that don't use `scm-record`, but could benefit from integration with it (with your contribution):
@@ -62,5 +39,4 @@ Here's some projects that don't use `scm-record`, but could benefit from integra
 Here are some features in the UI which are not yet implemented:
 
 - Jump to next/previous element of same kind.
-- Menu bar to explain available actions and keybindings.
 - Edit one side of the diff in an editor.

scm-record/src/render.rs

@@ -1,7 +1,9 @@
+use std::borrow::Cow;
 use std::cmp::{max, min};
+use std::collections::HashMap;
 use std::fmt::Debug;
 use std::hash::Hash;
-use std::{borrow::Cow, collections::HashMap};
+use std::mem;
 
 use cassowary::{Solver, Variable};
 use num_traits::cast;
@@ -21,12 +23,6 @@ pub(crate) struct RectSize {
     pub height: usize,
 }
 
-impl RectSize {
-    pub fn area(self) -> usize {
-        self.width * self.height
-    }
-}
-
 impl From<tui::layout::Rect> for RectSize {
     fn from(rect: tui::layout::Rect) -> Self {
         Rect::from(rect).into()
@@ -73,14 +69,6 @@ impl From<tui::layout::Rect> for Rect {
 }
 
 impl Rect {
-    /// The size of the `Rect`. (To get the area as a scalar, call `.size().area()`.)
-    pub fn size(self) -> RectSize {
-        RectSize {
-            width: self.width,
-            height: self.height,
-        }
-    }
-
     /// The (x, y) coordinate of the top-left corner of this `Rect`.
     fn top_left(self) -> (isize, isize) {
         (self.x, self.y)
@@ -246,7 +234,7 @@ struct DrawTrace<ComponentId> {
     rect: Rect,
 
     /// The bounding boxes of where each child component drew.
-    components: HashMap<ComponentId, Rect>,
+    components: HashMap<ComponentId, DrawnRect>,
 }
 
 impl<ComponentId: Clone + Debug + Eq + Hash> DrawTrace<ComponentId> {
@@ -283,6 +271,14 @@ impl<ComponentId> Default for DrawTrace<ComponentId> {
     }
 }
 
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub(crate) struct DrawnRect {
+    pub rect: Rect,
+    pub timestamp: usize,
+}
+
+pub(crate) type DrawnRects<C> = HashMap<C, DrawnRect>;
+
 /// Accessor to draw on the virtual canvas. The caller can draw anywhere on the
 /// canvas, but the actual renering will be restricted to this viewport. All
 /// draw calls are also tracked so that we know where each component was drawn
@@ -291,15 +287,37 @@ impl<ComponentId> Default for DrawTrace<ComponentId> {
 pub(crate) struct Viewport<'a, ComponentId> {
     buf: &'a mut Buffer,
     rect: Rect,
+    mask: Option<Rect>,
+    timestamp: usize,
     trace: Vec<DrawTrace<ComponentId>>,
     debug_messages: Vec<String>,
 }
 
 impl<'a, ComponentId: Clone + Debug + Eq + Hash> Viewport<'a, ComponentId> {
+    pub fn new(buf: &'a mut Buffer, rect: Rect) -> Self {
+        Self {
+            buf,
+            rect,
+            mask: Default::default(),
+            timestamp: Default::default(),
+            trace: vec![Default::default()],
+            debug_messages: Default::default(),
+        }
+    }
+
+    /// The portion of the virtual canvas that will be rendered to the terminal.
+    /// Thus, this `Rect` should have the same dimensions as the terminal.
     pub fn rect(&self) -> Rect {
         self.rect
     }
 
+    /// The mask used for rendering. If this is `Some`, then calls to
+    /// `draw_span` will only render inside the mask area. This can be used to
+    /// overlay one component on top of another in a fixed area.
+    pub fn mask(&self) -> Option<Rect> {
+        self.mask
+    }
+
     /// The size of the viewport.
     pub fn size(&self) -> RectSize {
         RectSize {
@@ -315,7 +333,7 @@ impl<'a, ComponentId: Clone + Debug + Eq + Hash> Viewport<'a, ComponentId> {
         x: isize,
         y: isize,
         component: &C,
-    ) -> HashMap<C::Id, Rect> {
+    ) -> DrawnRects<C::Id> {
         let widget = TopLevelWidget { component, x, y };
         let term_area = frame.size();
         let mut drawn_rects = Default::default();
@@ -341,6 +359,15 @@ impl<'a, ComponentId: Clone + Debug + Eq + Hash> Viewport<'a, ComponentId> {
         self.debug_messages.push(message.into())
     }
 
+    /// Set a mask to be used for rendering inside `f`.
+    pub fn with_mask<T>(&mut self, mask: Rect, f: impl FnOnce(&mut Self) -> T) -> T {
+        let mut mask = Some(mask);
+        mem::swap(&mut self.mask, &mut mask);
+        let result = f(self);
+        mem::swap(&mut self.mask, &mut mask);
+        result
+    }
+
     /// Draw the provided child component to the screen at the given `(x, y)`
     /// location.
     pub fn draw_component<C: Component<Id = ComponentId>>(
@@ -349,16 +376,29 @@ impl<'a, ComponentId: Clone + Debug + Eq + Hash> Viewport<'a, ComponentId> {
         y: isize,
         component: &C,
     ) -> Rect {
-        self.trace.push(Default::default());
-        component.draw(self, x, y);
-        let mut trace = self.trace.pop().unwrap();
-
-        let trace_rect = trace
-            .components
-            .values()
-            .fold(trace.rect, |acc, elem| acc.union_bounding(*elem));
+        let timestamp = {
+            let timestamp = self.timestamp;
+            self.timestamp += 1;
+            timestamp
+        };
+        let mut trace = {
+            self.trace.push(Default::default());
+            component.draw(self, x, y);
+            self.trace.pop().unwrap()
+        };
+
+        let trace_rect = trace.components.values().fold(trace.rect, |acc, elem| {
+            let DrawnRect { rect, timestamp: _ } = elem;
+            acc.union_bounding(*rect)
+        });
         trace.rect = trace_rect;
-        trace.components.insert(component.id(), trace_rect);
+        trace.components.insert(
+            component.id(),
+            DrawnRect {
+                rect: trace_rect,
+                timestamp,
+            },
+        );
 
         self.current_trace_mut().merge(trace);
         trace_rect
@@ -376,6 +416,10 @@ impl<'a, ComponentId: Clone + Debug + Eq + Hash> Viewport<'a, ComponentId> {
         self.current_trace_mut().merge_rect(span_rect);
 
         let draw_rect = self.rect.intersect(span_rect);
+        let draw_rect = match self.mask {
+            Some(mask) => draw_rect.intersect(mask),
+            None => draw_rect,
+        };
         if !draw_rect.is_empty() {
             let span_start_idx = (draw_rect.x - span_rect.x).unwrap_usize();
             let span_start_byte_idx = content
@@ -462,22 +506,19 @@ struct TopLevelWidget<'a, C> {
 }
 
 impl<C: Component> StatefulWidget for TopLevelWidget<'_, C> {
-    type State = HashMap<C::Id, Rect>;
+    type State = DrawnRects<C::Id>;
 
     fn render(self, area: tui::layout::Rect, buf: &mut Buffer, state: &mut Self::State) {
         let Self { component, x, y } = self;
-        let trace = vec![Default::default()];
-        let mut viewport = Viewport::<C::Id> {
+        let mut viewport: Viewport<C::Id> = Viewport::new(
             buf,
-            rect: Rect {
+            Rect {
                 x,
                 y,
                 width: area.width.into(),
                 height: area.height.into(),
             },
-            trace,
-            debug_messages: Default::default(),
-        };
+        );
         viewport.draw_component(0, 0, component);
         *state = viewport.trace.pop().unwrap().components;
         debug_assert!(viewport.trace.is_empty());