mirror of https://codeberg.org/JasterV/teatui.git synced 2026-04-26 18:10:03 +00:00

Víctor Martínez dec5c76bfd

[refactor] Build next version of teatui (#8 )

This pull request introduces significant improvements to the TeaTui framework, focusing on error handling, functional purity, and codebase simplification. Most notably, it removes the dependency on `color-eyre`, introduces custom error types for each actor (effects, events, update, view), and updates the API to encourage pure functions and more idiomatic Rust error handling. The example app and documentation are also updated to reflect these changes.

**Framework error handling and API improvements:**

* Introduced custom error types (`EffectsError`, `EventLoopError`, `UpdateError`, `ViewError`, and unified `ProgramError`) for each actor, replacing the use of `color-eyre` and providing clearer, structured error reporting throughout the framework. [[1]](diffhunk://#diff-1a8ddf10086f54de37be278b04f140fea42a9dd9314ebed509a03510b34a3043L2-R24) [[2]](diffhunk://#diff-dd43168709f1ba547c9dbe210d659222793384f540898dfa4159d3d28447ea59L2-R14) [[3]](diffhunk://#diff-717c070f88e33e75d62e17bcfb063657cc2cbba2198d8faf77fb3855206ba036L2-R51) [[4]](diffhunk://#diff-348239946b2211ffea21e1282dde8299ee0e5484616b8b2da9c97589719531e4L2-R23) [[5]](diffhunk://#diff-eaa72a947a5cb60aaed20788a77b8c3b94606a2b4bd9218fa2bbeeba0a98f726L34-R62)
* Updated the core `start` function to accept an `init_fn` initializer, and to use the new error types in its signature and internal logic, ensuring all errors are properly propagated and handled. [[1]](diffhunk://#diff-eaa72a947a5cb60aaed20788a77b8c3b94606a2b4bd9218fa2bbeeba0a98f726L61-R95) [[2]](diffhunk://#diff-eaa72a947a5cb60aaed20788a77b8c3b94606a2b4bd9218fa2bbeeba0a98f726L88-R157)
* Refactored the `Update` enum and related logic to use a single variant (`Next(M, Option<E>)`) for state transitions and side effects, simplifying the update pattern and removing the need for multiple variants.

**Example application and dependency updates:**

* Updated the counter example to remove `color-eyre`, use the new error types, and conform to the new pure function API (no more `Result` returns from user functions). [[1]](diffhunk://#diff-d1e739029fa7deef7dec36d183f1097a4ed266898520ddae449cff9c91f65a96L1-R10) [[2]](diffhunk://#diff-d1e739029fa7deef7dec36d183f1097a4ed266898520ddae449cff9c91f65a96L96-R111) [[3]](diffhunk://#diff-d1e739029fa7deef7dec36d183f1097a4ed266898520ddae449cff9c91f65a96L128-R129) [[4]](diffhunk://#diff-d1e739029fa7deef7dec36d183f1097a4ed266898520ddae449cff9c91f65a96R38-R42)
* Updated dependencies in `Cargo.toml` files: removed `color-eyre`, bumped `ratatui` version, and added `thiserror` for error handling. [[1]](diffhunk://#diff-2e9d962a08321605940b5a657135052fbcef87b5e360662bb527c96d9a615542L11-R12) [[2]](diffhunk://#diff-c6fd35fe7c3e8bcfcf9e60f261503d791b528405f92b6ba99f7272e91939d861L9) [[3]](diffhunk://#diff-1cd61e14e7d516bb58a3b2607848174d38c432631899f34dbc88076158f3bf52L10-R12)

**Documentation:**

* Added a comprehensive project overview and architecture description for TeaTui in `AGENTS.md`, explaining the functional philosophy, actor model, and usage guidelines.

2026-01-29 13:19:46 +01:00

2.7 KiB

Raw Permalink Blame History

TeaTui: Agent Context & Project Overview

Project Summary

TeaTui (Tea = The Elm Architecture) is an experimental Rust framework for building Terminal User Interfaces (TUIs) on top of Ratatui. It reproduces the Elm Architecture (Model-Update-View) to provide a pure functional development experience in Rust.

Tech Stack & Environment

Language: Rust (Edition 2024).
Workspace Structure: The project is organized as a workspace containing the core teatui library and an examples directory.
Core Dependencies:
ratatui: Used for terminal rendering.
crossterm: Handles terminal backend and event polling.
thiserror: Utilized for structured, descriptive error handling across the runtime.

Design Philosophy

Functional Purity: The goal is to build TUI applications in a pure-functional style, completely removing the usage of &mut and procedural state management.
Minimal Mutability: Mutability is discouraged in user-provided code; state transitions occur by returning new instances of the Model.
Message Passing as Side Effects: Communication between internal processes is strictly handled via std::sync::mpsc channels. Message passing is considered the "highest form of side effect" in the design.

Core Architecture

The framework operates through four concurrent actors (threads) that manage the application lifecycle:

Model: A single type representing the entire application state.
View Actor: Renders the Model into the terminal. It takes a pure function &Model -> Widget and redraws only when the Model changes.
Update Actor: Manages state transitions. It takes the current Model and an incoming Message, returning an Update enum (either Update::Exit or Update::Next(NewModel, Option<Effect>)).
Effects Actor: Processes side effects (e.g., IO) returned by the Update actor. It can optionally return a Message to trigger further state updates.
Event Actor: Translates raw terminal events (via crossterm) into application-specific Messages.

Key Types & Signatures

Update<M, E>: Enum signaling whether to exit or continue with a new state and optional effect.
update(model: M, msg: Msg) -> Update<M, E>: The core logic for state changes.
view(model: &M) -> Widget: The rendering logic.
effects(model: &M, effect: E) -> Option<Msg>: The side-effect handler.

Development Guide

When extending the framework or building apps with it, ensure that update and view functions remain pure. Any operation involving the "outside world" (files, network, etc.) must be modeled as an Effect and handled within the effects actor.

2.7 KiB Raw Permalink Blame History