blizz-ui 3.0.0-dev.12

Self-rendering terminal UI components for the blizz wizard
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

use std::io;
use std::io::Write;

use crossterm::{
  cursor::{Hide, MoveTo},
  queue,
  terminal::{Clear, ClearType},
};
use rand::Rng;

use crate::layout_panel::LayoutPanel;
use crate::render_context::RenderContext;

/// Bundles writer, RNG, per-frame context, and current panel for rendering.
///
/// Created once at wizard startup. Per-frame context is updated via
/// [`frame()`](Renderer::frame), which scopes each render pass.
/// The active [`LayoutPanel`] is set by [`draw()`](Renderer::draw).
pub struct Renderer<W: Write> {
  pub writer: W,
  pub rng: Box<dyn Rng>,
  ctx: RenderContext,
  panel: LayoutPanel,
}

impl<W: Write> Renderer<W> {
  pub fn new(writer: W, rng: Box<dyn Rng>, ctx: RenderContext) -> Self {
    Self {
      writer,
      rng,
      ctx,
      panel: LayoutPanel {
        row: 0,
        column: 0,
        width: 0,
      },
    }
  }

  pub fn ctx(&self) -> &RenderContext {
    &self.ctx
  }

  pub fn panel(&self) -> LayoutPanel {
    self.panel
  }

  /// Scope a render frame: update the context, clear the screen, run `f`,
  /// then flush.
  ///
  /// Analogous to the shellops `with_cursor` pattern — scoped mutation
  /// with a single point of context update.
  #[cfg(not(tarpaulin_include))]
  pub fn frame<F>(&mut self, ctx: RenderContext, f: F) -> io::Result<()>
  where
    F: FnOnce(&mut Self) -> io::Result<()>,
  {
    self.ctx = ctx;
    queue!(self.writer, Hide, Clear(ClearType::All))?;
    f(self)?;
    self.writer.flush()
  }

  /// Set the active panel and render a component.
  #[cfg(not(tarpaulin_include))]
  pub fn draw(&mut self, component: &impl Component, panel: LayoutPanel) -> io::Result<u16> {
    self.panel = panel;
    component.render(self)
  }

  /// Destructure the renderer for a component render at the active panel.
  ///
  /// Positions the cursor, then passes writer, panel, and RNG to the
  /// closure. The panel is read from the renderer (set by [`draw`](Renderer::draw)).
  #[cfg(not(tarpaulin_include))]
  pub fn with_panel<F>(&mut self, f: F) -> io::Result<u16>
  where
    F: FnOnce(&mut W, LayoutPanel, &mut Box<dyn Rng>) -> io::Result<u16>,
  {
    let panel = self.panel;
    queue!(self.writer, MoveTo(panel.column, panel.row))?;
    f(&mut self.writer, panel, &mut self.rng)
  }
}

/// A self-rendering UI element.
///
/// Components read their panel from the [`Renderer`] (set by
/// [`Renderer::draw`]). Returns the number of terminal rows consumed,
/// so compositors can stack components.
pub trait Component {
  fn render<W: Write>(&self, renderer: &mut Renderer<W>) -> io::Result<u16>;
}

#[cfg(test)]
mod tests {
  use crate::test_helpers::test_renderer;

  #[test]
  fn ctx_returns_terminal_size_and_elapsed() {
    let renderer = test_renderer();
    let ctx = renderer.ctx();
    assert_eq!(ctx.terminal_size.width, 80);
    assert_eq!(ctx.terminal_size.height, 24);
  }

  #[test]
  fn panel_defaults_to_zero() {
    let renderer = test_renderer();
    let panel = renderer.panel();
    assert_eq!(panel.row, 0);
    assert_eq!(panel.column, 0);
    assert_eq!(panel.width, 0);
  }
}