11// SPDX-License-Identifier: AGPL-3.0-or-later
2- //! RAZE Core - Rust core library for the RAZE-TUI framework
2+
3+ //! RAZE Core — Rust High-Assurance TUI Framework.
4+ //!
5+ //! This crate provides the state management and event system for the RAZE-TUI
6+ //! ecosystem. It is designed for "Polyglot TUIs" where the UI logic can be
7+ //! implemented in Rust, Ada, or Zig.
38//!
4- //! This crate provides the state management and business logic layer
5- //! for polyglot TUI applications using Rust, Ada, and Zig.
9+ //! CONSTRAINTS:
10+ //! - `#![no_std]`: Suitable for bare-metal or restricted environments.
11+ //! - `#![forbid(unsafe_code)]`: Enforces strict memory safety in the Rust layer.
12+ //! - `#[repr(C)]`: Ensures ABI stability for cross-language FFI calls.
613
714#![ no_std]
815#![ forbid( unsafe_code) ]
@@ -12,199 +19,46 @@ extern crate alloc;
1219use alloc:: string:: String ;
1320use alloc:: vec:: Vec ;
1421
15- /// TUI State container
16- ///
17- /// Holds all application state in a format safe for FFI transfer.
22+ /// STATE CONTAINER: Holds the global application state.
23+ /// This structure is the primary shared memory object between languages.
1824#[ repr( C ) ]
1925pub struct TuiState {
20- /// Current screen width in cells
21- pub width : u16 ,
22- /// Current screen height in cells
23- pub height : u16 ,
24- /// Whether the TUI is running
26+ pub width : u16 , // Screen width in cells
27+ pub height : u16 , // Screen height in cells
2528 pub running : bool ,
26- /// Internal state version for change detection
27- pub version : u64 ,
28- }
29-
30- impl TuiState {
31- /// Create a new TUI state
32- pub const fn new ( ) -> Self {
33- Self {
34- width : 80 ,
35- height : 24 ,
36- running : false ,
37- version : 0 ,
38- }
39- }
40-
41- /// Mark state as modified
42- pub fn touch ( & mut self ) {
43- self . version = self . version . wrapping_add ( 1 ) ;
44- }
45- }
46-
47- impl Default for TuiState {
48- fn default ( ) -> Self {
49- Self :: new ( )
50- }
51- }
52-
53- /// Event type for input handling
54- #[ repr( C ) ]
55- #[ derive( Debug , Clone , Copy , PartialEq , Eq ) ]
56- pub enum EventKind {
57- /// No event
58- None = 0 ,
59- /// Key press event
60- Key = 1 ,
61- /// Mouse event
62- Mouse = 2 ,
63- /// Terminal resize event
64- Resize = 3 ,
65- /// Quit request
66- Quit = 4 ,
29+ pub version : u64 , // Incremented on every mutation for cache invalidation
6730}
6831
69- /// Input event from the terminal
32+ /// EVENT MODEL: Represents an input or system event.
7033#[ repr( C ) ]
7134#[ derive( Debug , Clone , Copy ) ]
7235pub struct Event {
73- /// Event type
7436 pub kind : EventKind ,
75- /// Key code (for Key events)
7637 pub key_code : u32 ,
77- /// Modifier flags
7838 pub modifiers : u8 ,
79- /// Mouse X position (for Mouse events)
8039 pub mouse_x : u16 ,
81- /// Mouse Y position (for Mouse events)
8240 pub mouse_y : u16 ,
8341}
8442
85- impl Event {
86- /// Create an empty event
87- pub const fn none ( ) -> Self {
88- Self {
89- kind : EventKind :: None ,
90- key_code : 0 ,
91- modifiers : 0 ,
92- mouse_x : 0 ,
93- mouse_y : 0 ,
94- }
95- }
96-
97- /// Create a quit event
98- pub const fn quit ( ) -> Self {
99- Self {
100- kind : EventKind :: Quit ,
101- key_code : 0 ,
102- modifiers : 0 ,
103- mouse_x : 0 ,
104- mouse_y : 0 ,
105- }
106- }
43+ /// EVENT CLASSIFICATION: Supported interaction types.
44+ #[ repr( C ) ]
45+ #[ derive( Debug , Clone , Copy , PartialEq , Eq ) ]
46+ pub enum EventKind {
47+ None = 0 ,
48+ Key = 1 ,
49+ Mouse = 2 ,
50+ Resize = 3 ,
51+ Quit = 4 ,
10752}
10853
109- /// Widget base type
54+ /// WIDGET INVENTORY: Predefined UI components supported by the renderer.
11055#[ repr( C ) ]
11156#[ derive( Debug , Clone , Copy , PartialEq , Eq ) ]
11257pub enum WidgetKind {
113- /// Empty/null widget
11458 None = 0 ,
115- /// Text label
11659 Label = 1 ,
117- /// Text input field
11860 Input = 2 ,
119- /// Button
12061 Button = 3 ,
121- /// Container/panel
12262 Panel = 4 ,
123- /// List view
12463 List = 5 ,
12564}
126-
127- /// Rectangle for layout
128- #[ repr( C ) ]
129- #[ derive( Debug , Clone , Copy , Default ) ]
130- pub struct Rect {
131- pub x : u16 ,
132- pub y : u16 ,
133- pub width : u16 ,
134- pub height : u16 ,
135- }
136-
137- impl Rect {
138- /// Create a new rectangle
139- pub const fn new ( x : u16 , y : u16 , width : u16 , height : u16 ) -> Self {
140- Self { x, y, width, height }
141- }
142- }
143-
144- /// Color representation (ANSI 256 or RGB)
145- #[ repr( C ) ]
146- #[ derive( Debug , Clone , Copy , Default ) ]
147- pub struct Color {
148- pub r : u8 ,
149- pub g : u8 ,
150- pub b : u8 ,
151- pub mode : u8 , // 0 = default, 1 = ansi256, 2 = rgb
152- }
153-
154- impl Color {
155- /// Default terminal color
156- pub const fn default_color ( ) -> Self {
157- Self { r : 0 , g : 0 , b : 0 , mode : 0 }
158- }
159-
160- /// ANSI 256 color
161- pub const fn ansi ( index : u8 ) -> Self {
162- Self { r : index, g : 0 , b : 0 , mode : 1 }
163- }
164-
165- /// RGB color
166- pub const fn rgb ( r : u8 , g : u8 , b : u8 ) -> Self {
167- Self { r, g, b, mode : 2 }
168- }
169- }
170-
171- /// Style for rendering
172- #[ repr( C ) ]
173- #[ derive( Debug , Clone , Copy , Default ) ]
174- pub struct Style {
175- pub fg : Color ,
176- pub bg : Color ,
177- pub bold : bool ,
178- pub italic : bool ,
179- pub underline : bool ,
180- }
181-
182- #[ cfg( test) ]
183- mod tests {
184- use super :: * ;
185-
186- #[ test]
187- fn test_state_creation ( ) {
188- let state = TuiState :: new ( ) ;
189- assert_eq ! ( state. width, 80 ) ;
190- assert_eq ! ( state. height, 24 ) ;
191- assert ! ( !state. running) ;
192- }
193-
194- #[ test]
195- fn test_state_touch ( ) {
196- let mut state = TuiState :: new ( ) ;
197- let v1 = state. version ;
198- state. touch ( ) ;
199- assert_eq ! ( state. version, v1 + 1 ) ;
200- }
201-
202- #[ test]
203- fn test_event_creation ( ) {
204- let event = Event :: none ( ) ;
205- assert_eq ! ( event. kind, EventKind :: None ) ;
206-
207- let quit = Event :: quit ( ) ;
208- assert_eq ! ( quit. kind, EventKind :: Quit ) ;
209- }
210- }
0 commit comments