Skip to main content

incin_viz_plugin_api/
lib.rs

1//! `incin-viz-plugin-api`: The stable, independently-compilable trait
2//! surface for building custom visualizations and UI plugins for `incin-viz`.
3//!
4//! This crate provides the foundational types and traits (`Panel`, `Plugin`, `KeymapProvider`,
5//! and `RenderCtx`) needed to extend the Incin Visualizer dashboard. By separating
6//! the plugin API from the main `incin-viz` crate, developers can build custom telemetry
7//! visualizers without pulling in heavy TUI or application runtime dependencies.
8//!
9//! # Architecture
10//!
11//! The plugin architecture revolves around the [`panel::Panel`] trait. A `Panel` is a stateful
12//! struct that:
13//! 1. Receives incoming `incin-telemetry` `Event`s via `update()`.
14//! 2. Renders itself to a bounded screen region using a [`render_ctx::RenderCtx`] via `render()`.
15//! 3. Responds to keyboard and mouse inputs via `handle_event()`.
16//!
17//! The [`render_ctx::RenderCtx`] provides a safe, abstracted interface to the underlying rendering
18//! engine (`ratatui`), preventing plugins from accidentally overwriting other panels
19//! or crashing the host application by drawing outside their assigned boundaries.
20//!
21//! # Getting Started
22//!
23//! To create a custom panel, implement the [`panel::Panel`] trait:
24//!
25//! ```rust,no_run
26//! use incin_viz_plugin_api::prelude::*;
27//! use incin_telemetry::events::{Event, ScalarEvent};
28//!
29//! pub struct MyCustomPanel {
30//!     current_value: f64,
31//! }
32//!
33//! impl Panel for MyCustomPanel {
34//!     fn id(&self) -> &'static str { "my_custom_panel" }
35//!     fn title(&self) -> &str { "Custom Metric" }
36//!     
37//!     fn update(&mut self, event: &Event) {
38//!         if let Event::Scalar(ScalarEvent { value, .. }) = event {
39//!             self.current_value = *value;
40//!         }
41//!     }
42//!     
43//!     fn render(&mut self, ctx: &mut RenderCtx<'_, '_>) {
44//!         // Use ctx.buf() and ctx.area() to draw custom UI using ratatui
45//!     }
46//!     
47//!     fn handle_event(&mut self, _event: &PanelEvent) -> bool { false }
48//!     fn reset(&mut self) { self.current_value = 0.0; }
49//! }
50//! ```
51//!
52//! Once implemented, you can register it with `incin-viz`'s `App` at startup.
53extern crate alloc;
54/// Error types and result alias for plugin operations.
55pub mod err;
56/// Input events (keyboard, mouse, focus) for interactive panels.
57pub mod event;
58/// Keymap actions and resolution.
59pub mod keymap;
60/// State and lifecycle interface for visualizer panels.
61pub mod panel;
62/// Plugin bundling interface.
63pub mod plugin;
64/// Rendering context wrapper for ratatui buffer access.
65pub mod render_ctx;
66
67/// Convenient re-exports for building visualizer plugins.
68pub mod prelude {
69    pub use crate::err::{Error, Result};
70    pub use crate::event::{KeyCode, KeyModifiers, PanelEvent, PanelKeyEvent, PanelMouseEvent};
71    pub use crate::keymap::{Action, KeymapProvider};
72    pub use crate::panel::Panel;
73    pub use crate::plugin::Plugin;
74    pub use crate::render_ctx::{HitId, RenderCtx};
75}