zellij_sheets/lib.rs
1//! # Zellij Sheets
2//!
3//! Terminal-native spreadsheet viewing for Zellij and the command line.
4//!
5//! `zellij-sheets` is the grid and navigation layer for tabular data. It loads
6//! CSV and Excel files, renders them with a Unicode-aware layout engine, and
7//! exposes shared state and rendering logic used by both the Zellij plugin and
8//! the native CLI.
9//!
10//! This crate is intentionally viewer-first. Workflow-level pipeline semantics,
11//! provenance, and transformation orchestration belong in `nustage`, not here.
12//!
13//! ## Features
14//!
15//! - CSV and Excel (`.xlsx`, `.xls`) loading
16//! - Horizontal scrolling with a real column cursor
17//! - Vim-style navigation primitives
18//! - Search state and matching helpers
19//! - Cell/range/write address parsing for the native CLI
20//! - CSV loading from stdin and CSV write-back helpers
21//! - Serializable spreadsheet state snapshots
22//! - Unicode-aware column measurement and layout
23//!
24//! ## Public Surface
25//!
26//! - [`state`] contains [`SheetsState`], cursor/search behavior, and snapshot support.
27//! - [`layout`] contains the measurement and width-resolution engine.
28//! - [`ui`] contains terminal rendering helpers.
29//! - [`data_loader`] contains CSV/Excel loading helpers.
30//! - [`address`] contains cell/range/write address parsing for the native CLI.
31//!
32//! ## Usage
33//!
34//! Read a file into shared state:
35//!
36//! ```no_run
37//! use std::path::PathBuf;
38//! use std::sync::Arc;
39//! use zellij_sheets::{SheetsConfig, SheetsState};
40//!
41//! let mut state = SheetsState::new(Arc::new(SheetsConfig::default()));
42//! state.load_file(PathBuf::from("data.csv"))?;
43//! # Ok::<(), zellij_sheets::state::StateError>(())
44//! ```
45//!
46//! Parse a CLI-style cell address:
47//!
48//! ```
49//! use zellij_sheets::{parse_address_command, AddressCommand, CellAddress};
50//!
51//! let command = parse_address_command("B9")?;
52//! assert_eq!(command, AddressCommand::Cell(CellAddress { row: 8, col: 1 }));
53//! # Ok::<(), zellij_sheets::address::AddressError>(())
54//! ```
55//!
56//! Example Zellij plugin config:
57//! ```kdl
58//! plugins {
59//! zellij-sheets location="file:/path/to/zellij-sheets.wasm"
60//! }
61//! ```
62//!
63//! Example native CLI usage:
64//! ```bash
65//! zellij-sheets data.csv
66//! zellij-sheets data.csv B9
67//! zellij-sheets data.csv B1:B3
68//! cat data.csv | zellij-sheets B2
69//! ```
70
71pub mod address;
72pub mod config;
73pub mod data_loader;
74pub mod layout;
75pub mod state;
76pub mod ui;
77
78/// CLI address parsing helpers
79pub use address::{
80 col_letter_to_index, index_to_col_letters, parse_address_command, AddressCommand, CellAddress,
81};
82
83/// Configuration and display settings for the spreadsheet viewer
84pub use config::{
85 BehaviorConfig, ColumnConfig, DisplayConfig, ScrollSpeed, SheetsConfig, ThemeConfig,
86};
87
88/// Utility functions for file operations and data loading
89pub use data_loader::{
90 file_exists, get_file_extension, get_file_name, get_file_size, load_csv_from_reader, load_data,
91 write_csv,
92};
93
94/// Core spreadsheet state and data types
95pub use state::{cell_matches_query, DataType, SearchDirection, SheetsState};
96
97/// Layout and rendering engine
98pub use layout::{fit_cell, ColumnLayout, LayoutCache, LayoutEngine};
99
100/// UI rendering types
101pub use ui::{Colors, UiError, UiRenderer};