Merge pull request #93 from ynqa/feat/csv

feat(widgets): add performant CSV table widget and viewer

Author: ynqa

Cargo.toml

@@ -14,6 +14,7 @@ anyhow = "1.0.102"
 async-trait = "0.1.89"
 crossbeam-skiplist = "0.1.3"
 crossterm = { version = "0.29.0", features = ["use-dev-tty", "event-stream", "serde"] }
+csv = "1.3.1"
 futures = "0.3.32"
 radix_trie = "0.3.0"
 rayon = "1.11.0"

examples/csv/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "csv-viewer"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+anyhow = { workspace = true }
+clap = { version = "4.5.60", features = ["derive"] }
+promkit = { path = "../../promkit", features = ["table"] }
+tokio = { workspace = true }
+
+[[bin]]
+name = "csv"
+path = "src/csv.rs"

examples/csv/src/csv.rs

@@ -0,0 +1,310 @@
+use std::{fs::File, io, path::PathBuf};
+
+use clap::Parser;
+use promkit::{
+    core::{
+        crossterm::{
+            event::{
+                self, Event, KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers,
+                MouseEvent, MouseEventKind,
+            },
+            execute, terminal,
+        },
+        render::{Renderer, SharedRenderer},
+        Widget,
+    },
+    widgets::table::{CsvOptions, Document, State},
+    Prompt, Signal,
+};
+
+/// Interactive CSV viewer powered by promkit.
+#[derive(Debug, Parser)]
+#[command(name = "csv", version)]
+struct Args {
+    /// Optional path to a CSV file. Reads from stdin when omitted or when "-" is specified.
+    input: Option<PathBuf>,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum Index {
+    Table,
+}
+
+const KEY_HORIZONTAL_SCROLL_CELLS: usize = 1;
+const MOUSE_HORIZONTAL_SCROLL_CELLS: usize = 3;
+
+struct CsvViewer {
+    renderer: Option<SharedRenderer<Index>>,
+    table: State,
+}
+
+impl CsvViewer {
+    fn new(document: Document) -> Self {
+        Self {
+            renderer: None,
+            table: State::new(document),
+        }
+    }
+
+    fn handle_event(&mut self, event: &Event) -> anyhow::Result<Signal> {
+        match event {
+            Event::Key(KeyEvent {
+                code: KeyCode::Enter,
+                modifiers: KeyModifiers::NONE,
+                kind: KeyEventKind::Press,
+                state: KeyEventState::NONE,
+            }) => return Ok(Signal::Quit),
+            Event::Key(KeyEvent {
+                code: KeyCode::Char('c'),
+                modifiers: KeyModifiers::CONTROL,
+                kind: KeyEventKind::Press,
+                state: KeyEventState::NONE,
+            }) => return Err(anyhow::anyhow!("ctrl+c")),
+            Event::Key(KeyEvent {
+                code: KeyCode::Up,
+                modifiers: KeyModifiers::NONE,
+                kind: KeyEventKind::Press,
+                state: KeyEventState::NONE,
+            })
+            | Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollUp,
+                modifiers: KeyModifiers::NONE,
+                ..
+            }) => {
+                self.table.document.up();
+            }
+            Event::Key(KeyEvent {
+                code: KeyCode::Down,
+                modifiers: KeyModifiers::NONE,
+                kind: KeyEventKind::Press,
+                state: KeyEventState::NONE,
+            })
+            | Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollDown,
+                modifiers: KeyModifiers::NONE,
+                ..
+            }) => {
+                self.table.document.down();
+            }
+            Event::Key(KeyEvent {
+                code: KeyCode::Left,
+                modifiers: KeyModifiers::NONE,
+                kind: KeyEventKind::Press,
+                state: KeyEventState::NONE,
+            }) => {
+                self.table
+                    .document
+                    .scroll_left_by(KEY_HORIZONTAL_SCROLL_CELLS);
+            }
+            Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollLeft,
+                modifiers: KeyModifiers::NONE,
+                ..
+            })
+            | Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollUp,
+                modifiers: KeyModifiers::SHIFT,
+                ..
+            }) => {
+                self.table
+                    .document
+                    .scroll_right_by(MOUSE_HORIZONTAL_SCROLL_CELLS);
+            }
+            Event::Key(KeyEvent {
+                code: KeyCode::Right,
+                modifiers: KeyModifiers::NONE,
+                kind: KeyEventKind::Press,
+                state: KeyEventState::NONE,
+            }) => {
+                self.table
+                    .document
+                    .scroll_right_by(KEY_HORIZONTAL_SCROLL_CELLS);
+            }
+            Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollRight,
+                modifiers: KeyModifiers::NONE,
+                ..
+            })
+            | Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollDown,
+                modifiers: KeyModifiers::SHIFT,
+                ..
+            }) => {
+                self.table
+                    .document
+                    .scroll_left_by(MOUSE_HORIZONTAL_SCROLL_CELLS);
+            }
+            _ => {}
+        }
+        Ok(Signal::Continue)
+    }
+
+    async fn render(&mut self) -> anyhow::Result<()> {
+        let renderer = self
+            .renderer
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Renderer not initialized"))?;
+        let (width, height) = terminal::size()?;
+        renderer
+            .update([(
+                Index::Table,
+                self.table.create_graphemes_in_viewport(width, height),
+            )])
+            .render()
+            .await
+    }
+}
+
+#[promkit::async_trait::async_trait]
+impl Prompt for CsvViewer {
+    async fn initialize(&mut self) -> anyhow::Result<()> {
+        let (width, height) = terminal::size()?;
+        self.renderer = Some(SharedRenderer::new(
+            Renderer::try_new_with_graphemes(
+                [(
+                    Index::Table,
+                    self.table.create_graphemes_in_viewport(width, height),
+                )],
+                true,
+            )
+            .await?,
+        ));
+        Ok(())
+    }
+
+    async fn evaluate(&mut self, event: &Event) -> anyhow::Result<Signal> {
+        let signal = self.handle_event(event)?;
+        if signal == Signal::Continue {
+            self.render().await?;
+        }
+        Ok(signal)
+    }
+
+    type Return = ();
+
+    fn finalize(&mut self) -> anyhow::Result<Self::Return> {
+        Ok(())
+    }
+}
+
+fn parse_document(args: &Args) -> anyhow::Result<Document> {
+    let options = CsvOptions::default();
+    match &args.input {
+        None => {
+            let stdin = io::stdin();
+            Document::from_csv(stdin.lock(), options).map_err(anyhow::Error::from)
+        }
+        Some(path) if path == &PathBuf::from("-") => {
+            let stdin = io::stdin();
+            Document::from_csv(stdin.lock(), options).map_err(anyhow::Error::from)
+        }
+        Some(path) => Document::from_csv(File::open(path)?, options).map_err(anyhow::Error::from),
+    }
+}
+
+/// Ensure the terminal is restored to its original state when dropped.
+struct TerminalGuard;
+
+impl Drop for TerminalGuard {
+    fn drop(&mut self) {
+        let _ = execute!(
+            io::stdout(),
+            terminal::LeaveAlternateScreen,
+            event::DisableMouseCapture
+        );
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+    let document = parse_document(&args)?;
+
+    execute!(
+        io::stdout(),
+        terminal::EnterAlternateScreen,
+        event::EnableMouseCapture
+    )?;
+    let _terminal_guard = TerminalGuard;
+
+    CsvViewer::new(document).run().await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn viewer() -> CsvViewer {
+        CsvViewer::new(
+            Document::from_csv(
+                "a,b,c\none,two,three\nfour,five,six\n".as_bytes(),
+                CsvOptions::default(),
+            )
+            .unwrap(),
+        )
+    }
+
+    #[test]
+    fn arrow_keys_move_on_both_axes() {
+        let mut viewer = viewer();
+        viewer.table.create_graphemes_in_viewport(4, 2);
+
+        viewer
+            .handle_event(&Event::Key(KeyEvent::new(
+                KeyCode::Down,
+                KeyModifiers::NONE,
+            )))
+            .unwrap();
+        assert_eq!(viewer.table.document.position(), 1);
+
+        viewer
+            .handle_event(&Event::Key(KeyEvent::new(
+                KeyCode::Right,
+                KeyModifiers::NONE,
+            )))
+            .unwrap();
+        assert_eq!(
+            viewer.table.document.horizontal_offset(),
+            KEY_HORIZONTAL_SCROLL_CELLS
+        );
+    }
+
+    #[test]
+    fn macos_horizontal_scroll_left_reveals_content_on_the_right() {
+        let mut viewer = viewer();
+        viewer.table.create_graphemes_in_viewport(4, 2);
+        viewer
+            .handle_event(&Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollLeft,
+                column: 0,
+                row: 0,
+                modifiers: KeyModifiers::NONE,
+            }))
+            .unwrap();
+
+        assert_eq!(
+            viewer.table.document.horizontal_offset(),
+            MOUSE_HORIZONTAL_SCROLL_CELLS
+        );
+
+        viewer
+            .handle_event(&Event::Mouse(MouseEvent {
+                kind: MouseEventKind::ScrollRight,
+                column: 0,
+                row: 0,
+                modifiers: KeyModifiers::NONE,
+            }))
+            .unwrap();
+        assert_eq!(viewer.table.document.horizontal_offset(), 0);
+    }
+
+    #[test]
+    fn loads_the_large_csv_fixture_from_a_file() {
+        let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+            .join("../../promkit-widgets/benches/table.csv");
+        let document = parse_document(&Args { input: Some(path) }).unwrap();
+
+        assert_eq!(document.row_count(), 47_852);
+        assert_eq!(document.column_count(), 12);
+    }
+}

promkit-widgets/Cargo.toml

@@ -10,14 +10,15 @@ readme = "README.md"
 
 [features]
 default = []
-all = ["checkbox", "json", "yaml", "listbox", "serde", "spinner", "status", "text", "texteditor", "tree"]
+all = ["checkbox", "json", "yaml", "listbox", "serde", "spinner", "status", "table", "text", "texteditor", "tree"]
 checkbox = ["listbox"]
 json = ["dep:serde_json", "dep:rayon"]
 yaml = ["dep:serde_yaml", "dep:rayon"]
 listbox = []
 serde = ["dep:serde", "dep:termcfg"]
 spinner = ["dep:tokio"]
 status = ["text"]
+table = ["dep:csv", "dep:unicode-width"]
 text = []
 texteditor = []
 tree = []
@@ -27,20 +28,26 @@ anyhow = { workspace = true }
 promkit-core = { path = "../promkit-core", version = "=0.5.0" }
 
 # Optional dependencies
+csv = { workspace = true, optional = true }
 rayon = { workspace = true, optional = true }
 serde = { workspace = true, optional = true }
 serde_json = { workspace = true, optional = true }
 serde_yaml = { workspace = true, optional = true }
 termcfg = { workspace = true, optional = true }
 tokio = { workspace = true, optional = true }
+unicode-width = { workspace = true, optional = true }
 
 [dev-dependencies]
 criterion = "0.8.2"
 # Enable `json` feature when `jsonz` testing
-promkit-widgets = { path = ".", features = ["json", "yaml"] }
+promkit-widgets = { path = ".", features = ["json", "table", "yaml"] }
 serde = { workspace = true }
 toml = "0.9.8"
 
 [[bench]]
 name = "structured"
 harness = false
+
+[[bench]]
+name = "table"
+harness = false