milktea 0.1.0

data/README.md

@@ -0,0 +1,382 @@
+# Milktea
+
+[![Gem Version](https://badge.fury.io/rb/milktea.svg)](https://badge.fury.io/rb/milktea)
+[![Ruby](https://github.com/elct9620/milktea/workflows/Ruby/badge.svg)](https://github.com/elct9620/milktea/actions)
+
+A Terminal User Interface (TUI) framework for Ruby, inspired by [Bubble Tea](https://github.com/charmbracelet/bubbletea) from Go. Milktea brings the power of the Elm Architecture to Ruby, enabling you to build rich, interactive command-line applications with composable components and reactive state management.
+
+## Features
+
+- 🏗️ **Elm Architecture**: Immutable state management with predictable message flow
+- 📦 **Container Layouts**: Flexbox-style layouts for terminal interfaces
+- 🔄 **Hot Reloading**: Instant feedback during development (similar to web frameworks)
+- 📱 **Responsive Design**: Automatic adaptation to terminal resize events
+- 🧩 **Composable Components**: Build complex UIs from simple, reusable models
+- 🎨 **Rich Terminal Support**: Leverage TTY gems for advanced terminal features
+
+## Installation
+
+Add Milktea to your application's Gemfile:
+
+```ruby
+gem 'milktea'
+```
+
+Or install directly:
+
+```bash
+gem install milktea
+```
+
+For development versions:
+
+```ruby
+gem 'milktea', git: 'https://github.com/elct9620/milktea'
+```
+
+## Quick Start
+
+Here's a simple "Hello World" application:
+
+```ruby
+require 'milktea'
+
+class HelloModel < Milktea::Model
+  def view
+    "Hello, #{state[:name]}! Count: #{state[:count]}"
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      case message.value
+      when "+"
+        [with(count: state[:count] + 1), Milktea::Message::None.new]
+      when "q"
+        [self, Milktea::Message::Exit.new]
+      else
+        [self, Milktea::Message::None.new]
+      end
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    { name: "World", count: 0 }
+  end
+end
+
+# Simple approach using Application class
+class MyApp < Milktea::Application
+  root "HelloModel"
+end
+
+MyApp.boot
+```
+
+## Core Concepts
+
+### Models & Elm Architecture
+
+Milktea follows the Elm Architecture pattern with three core concepts:
+
+- **Model**: Immutable state container
+- **View**: Pure function that renders state to string
+- **Update**: Handles messages and returns new state + side effects
+
+```ruby
+class CounterModel < Milktea::Model
+  def view
+    "Count: #{state[:count]} (Press +/- to change, q to quit)"
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    when Milktea::Message::Resize
+      # Rebuild model with fresh class for new screen dimensions
+      [with, Milktea::Message::None.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    { count: 0 }
+  end
+
+  def handle_keypress(message)
+    case message.value
+    when "+"
+      [with(count: state[:count] + 1), Milktea::Message::None.new]
+    when "-"
+      [with(count: state[:count] - 1), Milktea::Message::None.new]
+    when "q"
+      [self, Milktea::Message::Exit.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+```
+
+### Container Layout System
+
+Milktea provides a flexbox-inspired layout system for building complex terminal interfaces:
+
+```ruby
+class AppLayout < Milktea::Container
+  direction :column
+  child HeaderModel, flex: 1
+  child ContentModel, flex: 3  
+  child FooterModel, flex: 1
+end
+
+class SidebarLayout < Milktea::Container
+  direction :row
+  child SidebarModel, flex: 1
+  child MainContentModel, flex: 3
+end
+```
+
+#### Key Container Features:
+
+- **Direction**: `:row` or `:column` (default: `:column`)
+- **Flex Properties**: Control size ratios between children
+- **State Mapping**: Pass specific state portions to children
+- **Bounds Calculation**: Automatic layout calculation and propagation
+
+```ruby
+class AdvancedContainer < Milktea::Container
+  direction :row
+  
+  # Pass specific state to children with state mappers
+  child SidebarModel, ->(state) { { items: state[:sidebar_items] } }, flex: 1
+  child ContentModel, ->(state) { state.slice(:title, :content) }, flex: 2
+  child InfoModel, flex: 1
+end
+```
+
+### Hot Reloading (Development Feature)
+
+Milktea supports hot reloading for rapid development iteration:
+
+```ruby
+# Configure hot reloading
+Milktea.configure do |config|
+  config.autoload_dirs = ["app/models", "lib/components"]
+  config.hot_reloading = true
+end
+
+class DevelopmentModel < Milktea::Model
+  def update(message)
+    case message
+    when Milktea::Message::Reload
+      # Hot reload detected - rebuild with fresh class
+      [with, Milktea::Message::None.new]
+    # ... other message handling
+    end
+  end
+end
+```
+
+When files change, Milktea automatically detects the changes and sends `Message::Reload` events. Simply handle this message by rebuilding your model with `[with, Milktea::Message::None.new]` to pick up the latest code changes.
+
+### Terminal Resize Handling
+
+Milktea automatically detects terminal resize events and provides a simple pattern for responsive layouts:
+
+```ruby
+class ResponsiveApp < Milktea::Container
+  direction :column
+  child HeaderModel, flex: 1
+  child DynamicContentModel, flex: 4
+
+  def update(message)
+    case message
+    when Milktea::Message::Resize
+      # Only root model needs resize handling
+      # All children automatically recalculate bounds
+      [with, Milktea::Message::None.new]
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+```
+
+#### Resize Handling Key Points:
+
+- **Root-Level Only**: Only the root model needs to handle `Message::Resize`
+- **Automatic Cascading**: Child components automatically adapt to new dimensions
+- **Bounds Recalculation**: Container layouts automatically recalculate flex distributions
+- **Screen Methods**: Use `screen_width`, `screen_height`, `screen_size` for responsive logic
+
+## Examples
+
+Explore the `examples/` directory for comprehensive demonstrations:
+
+- **[Container Layout](examples/container_layout.rb)**: Flexbox-style layouts with resize support
+- **[Hot Reload Demo](examples/hot_reload_demo.rb)**: Development workflow with instant updates
+
+Run examples:
+
+```bash
+ruby examples/container_layout.rb
+ruby examples/hot_reload_demo.rb
+```
+
+## Advanced Features
+
+### Dynamic Child Resolution
+
+Use symbols to dynamically resolve child components:
+
+```ruby
+class DynamicContainer < Milktea::Container
+  direction :column
+  child :header_component, flex: 1  # Calls header_component method
+  child ContentModel, flex: 3       # Direct class reference
+
+  private
+
+  def header_component
+    state[:show_advanced] ? AdvancedHeader : SimpleHeader
+  end
+end
+```
+
+### Custom Message Handling
+
+Create custom messages for complex interactions:
+
+```ruby
+# Define custom message
+CustomAction = Data.define(:action_type, :payload)
+
+class CustomModel < Milktea::Model
+  def update(message)
+    case message
+    when CustomAction
+      handle_custom_action(message)
+    # ... standard message handling
+    end
+  end
+
+  private
+
+  def handle_custom_action(message)
+    case message.action_type
+    when :save
+      # Handle save action
+      [with(saved: true), Milktea::Message::None.new]
+    when :load
+      # Handle load action
+      [with(data: message.payload), Milktea::Message::None.new]
+    end
+  end
+end
+```
+
+### Application vs Manual Setup
+
+Choose between high-level Application class or manual setup:
+
+```ruby
+# High-level Application approach (recommended)
+class MyApp < Milktea::Application
+  root "MainModel"
+end
+
+MyApp.boot
+
+# Manual setup (advanced)
+config = Milktea.configure do |c|
+  c.autoload_dirs = ["app/models"]
+  c.hot_reloading = true
+end
+
+loader = Milktea::Loader.new(config)
+loader.hot_reload if config.hot_reloading?
+
+model = MainModel.new
+program = Milktea::Program.new(model, config: config)
+program.run
+```
+
+## API Reference
+
+### Core Classes
+
+- **`Milktea::Model`**: Base class for all UI components
+- **`Milktea::Container`**: Layout container with flexbox-style properties
+- **`Milktea::Application`**: High-level application wrapper
+- **`Milktea::Program`**: Main application runtime
+- **`Milktea::Message`**: Standard message types (KeyPress, Exit, Resize, Reload)
+
+### Message System
+
+- **`Message::KeyPress`**: Keyboard input events
+- **`Message::Exit`**: Application termination
+- **`Message::Resize`**: Terminal size changes
+- **`Message::Reload`**: Hot reload events
+- **`Message::None`**: No-operation message
+
+For detailed API documentation, see the [documentation website](https://rubydoc.info/gems/milktea).
+
+## Development
+
+After checking out the repo:
+
+```bash
+bin/setup                    # Install dependencies
+bundle exec rake spec        # Run tests
+bundle exec rake rubocop     # Check code style
+bundle exec rake             # Run all checks
+bin/console                  # Interactive prompt
+```
+
+### Testing
+
+Milktea uses RSpec for testing. Run specific tests:
+
+```bash
+bundle exec rspec spec/milktea/model_spec.rb
+bundle exec rspec spec/milktea/container_spec.rb:42  # Specific line
+```
+
+### Code Quality
+
+The project uses RuboCop for code formatting:
+
+```bash
+bundle exec rake rubocop:autocorrect  # Fix auto-correctable issues
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/elct9620/milktea.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+- Inspired by [Bubble Tea](https://github.com/charmbracelet/bubbletea) - Go TUI framework
+- Built on the [TTY toolkit](https://ttytoolkit.org/) ecosystem
+- Follows [Elm Architecture](https://guide.elm-lang.org/architecture/) principles

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/devlog/20250703.md

@@ -0,0 +1,119 @@
+# Development Log - 2025-07-03
+
+## What's New
+
+#### Renderer Abstraction for Clean Separation of Concerns
+
+The Milktea framework now features a dedicated `Renderer` class that handles all terminal user interface rendering operations. This new abstraction brings several benefits to TUI developers:
+
+- **Screen Management**: Automatic screen clearing and cursor positioning using the `tty-cursor` gem ensures clean rendering without visual artifacts
+- **Output Flexibility**: Support for custom output streams allows easy testing with `StringIO` and potential future support for different output formats
+- **Lifecycle Methods**: Clear `setup_screen()` and `restore_screen()` methods handle terminal state management, ensuring proper cleanup when programs exit
+- **Clean API**: Simple `render(model)` method that takes care of all rendering complexities internally
+
+This separation allows developers to focus on their application logic while the renderer handles the intricacies of terminal manipulation.
+
+#### Full Keyboard Event Handling
+
+Interactive TUI applications now have access to comprehensive keyboard input through integration with `TTY::Reader`. The new `KeyPress` message type provides rich event data:
+
+- **Complete Key Information**: Access to both raw key values and character representations
+- **Modifier Key Support**: Built-in tracking of Ctrl, Alt, and Shift states enables complex keyboard shortcuts
+- **Non-blocking Input**: Keyboard events are read without blocking the main event loop, maintaining responsive applications
+- **Graceful Interrupt Handling**: Ctrl+C is properly handled through TTY::Reader's error mode, preventing abrupt terminations
+
+This enhancement empowers developers to create sophisticated keyboard-driven interfaces with minimal effort.
+
+#### Counter Example Application
+
+A new example demonstrates best practices for building Milktea applications. The counter showcases:
+
+- **State Management**: Proper use of immutable state updates through the `Model#with` method
+- **User Interaction**: Intuitive keyboard controls (+/k for increment, -/j for decrement, r for reset, q for quit)
+- **Clean UI**: Clear instructions and visual feedback demonstrate effective TUI design
+- **Architecture Patterns**: Real-world application of the Elm Architecture within the Ruby ecosystem
+
+This example serves as both a learning resource and a template for new TUI applications.
+
+## What's Fixed
+
+#### Screen Clearing and Rendering Artifacts
+
+**Problem**: Previous renders would leave visual artifacts on screen, creating a messy user experience as old content remained visible beneath new renders.
+
+**Solution**: The new Renderer class now properly clears the entire screen and resets the cursor to position (0,0) before each render cycle. This ensures each frame starts with a clean slate, eliminating any overlap or ghosting effects from previous renders.
+
+**Impact**: TUI applications now provide a clean, professional appearance with smooth visual updates that don't leave traces of previous states.
+
+#### Hardcoded Exit Key Limitations
+
+**Problem**: The framework previously hardcoded certain keys for exiting applications, limiting developer control over keyboard interactions and preventing custom exit strategies.
+
+**Solution**: Removed all hardcoded exit keys from the Program class. Models now have complete control over keyboard event handling, including when and how to terminate the application.
+
+**Impact**: Developers can now implement custom exit confirmations, save prompts, or completely different key bindings for application termination, providing full control over the user experience.
+
+## Design Decisions
+
+#### Renderer as a Separate Component
+
+**Context**: The Program class was becoming complex, handling both event loop management and rendering responsibilities. This violated the single responsibility principle and made testing difficult.
+
+**Choice**: Extract all rendering logic into a dedicated Renderer class that can be injected into the Program.
+
+**Rationale**: This separation provides multiple benefits:
+- Easier unit testing through dependency injection
+- Potential for alternative renderer implementations (e.g., web-based output)
+- Cleaner Program class focused solely on event loop management
+- Better adherence to SOLID principles
+
+This decision aligns with the framework's clean architecture approach and makes the codebase more maintainable and extensible.
+
+#### Enhanced Testing Philosophy
+
+**Context**: The existing RSpec tests were using various patterns, some of which tested implementation details rather than behavior.
+
+**Choice**: Established comprehensive testing guidelines emphasizing behavioral testing over implementation testing.
+
+**Rationale**: The new guidelines promote:
+- Using spy patterns for cleaner delegation tests
+- Avoiding private instance variable testing
+- Leveraging RSpec's built-in matchers like `output`
+- Focusing on public API behavior
+
+These practices lead to more maintainable tests that don't break with internal refactoring, while still ensuring correctness.
+
+#### Non-blocking Keyboard Input
+
+**Context**: TUI applications need to remain responsive while waiting for user input, but blocking I/O operations can freeze the interface.
+
+**Choice**: Implement keyboard reading using TTY::Reader's non-blocking `read_keypress` method within the main event loop.
+
+**Rationale**: This approach ensures:
+- The event loop continues processing messages and timers while waiting for input
+- Applications can implement animations or real-time updates
+- Better user experience with responsive interfaces
+- Alignment with modern event-driven programming patterns
+
+## Impact
+
+These changes significantly enhance the Milktea framework's usability and architecture. Ruby developers building TUI applications now have:
+
+- **Better Separation of Concerns**: Clear boundaries between rendering, input handling, and application logic
+- **More Control**: Full ownership of keyboard handling and application behavior
+- **Improved Testing**: Cleaner patterns for writing maintainable test suites
+- **Professional Output**: Artifact-free rendering for polished user interfaces
+- **Learning Resources**: Practical examples demonstrating framework best practices
+
+The framework now provides a more solid foundation for building sophisticated terminal applications while maintaining the simplicity and elegance of the Elm Architecture.
+
+## Files Modified
+
+- `lib/milktea/renderer.rb` - New Renderer class for TUI rendering
+- `lib/milktea/program.rb` - Refactored to use Renderer and handle keyboard events
+- `lib/milktea/message.rb` - Added KeyPress message type
+- `examples/counter.rb` - New counter example application
+- `examples/simple.rb` - Updated with keyboard interaction
+- `spec/milktea/renderer_spec.rb` - Tests for new Renderer class
+- `spec/milktea/program_spec.rb` - Updated tests for refactored Program
+- `CLAUDE.md` - Enhanced RSpec testing guidelines

data/docs/devlog/20250704-2.md

@@ -0,0 +1,129 @@
+# Development Log - 2025-07-04 (Session 2)
+
+## What's New
+
+#### Working Hot Reloading System with Production-Ready Example
+Successfully implemented a fully functional hot reloading system for Milktea applications, complete with a comprehensive demonstration example. The system enables developers to modify TUI components in real-time while applications are running, dramatically improving development velocity and iteration speed.
+
+Key features include:
+- **Live code reloading**: Edit model files and see changes immediately without restarting
+- **Automatic class refresh**: Uses `Kernel.const_get` to ensure fresh class definitions are loaded
+- **Graceful degradation**: Works with or without the Listen gem for file watching
+- **Interactive demo**: Complete example showing parent-child model reloading with clear instructions
+
+#### Independent Loader Architecture
+Redesigned the Loader system to be completely self-contained, eliminating problematic circular dependencies that were preventing proper Model loading. The new architecture separates concerns cleanly and provides a simpler API for developers.
+
+The Loader now:
+- Takes a config object and extracts what it needs internally
+- Automatically handles hot reloading based on configuration
+- Operates independently from the core framework components
+- Provides a single `start` method that handles all initialization
+
+#### Comprehensive Hot Reloading Documentation
+Added extensive documentation to CLAUDE.md covering all critical aspects of hot reloading setup and troubleshooting. This includes configuration requirements, implementation gotchas, and step-by-step testing procedures that will be essential for future development.
+
+## What's Fixed
+
+#### Circular Dependency Resolution
+Resolved critical circular dependencies in the original Loader design where Config needed Runtime to create Loader, but Loader needed Config's runtime and app_path. This was causing Model loading failures and tight coupling between components.
+
+**Root cause**: The original design tried to inject dependencies through Config, creating a circular reference loop.
+
+**Solution**: Made Loader completely independent by having it extract needed values from a passed config object, eliminating the circular dependency chain.
+
+#### Hot Reloading Class Reference Issues
+Fixed fundamental issue where hot reloading wasn't working because `self.class.new` was returning cached/stale class objects instead of freshly reloaded classes.
+
+**Root cause**: Ruby's `self.class` returns the class object that was loaded when the instance was created, not the current definition.
+
+**Solution**: Replaced `self.class.new` with `Kernel.const_get(self.class.name).new` in the Model#with method to ensure fresh class definitions are used.
+
+#### Zeitwerk Configuration for Examples
+Corrected app_dir configuration for examples directory to work with Zeitwerk's autoloading requirements. Examples lack Gemfile and other project structure, requiring special path handling.
+
+**Impact**: Hot reloading now works correctly for standalone examples, demonstrating the system's flexibility across different project structures.
+
+#### Message::Reload Event Handling
+Implemented proper reload event handling in models using the `with` method to rebuild instances with fresh class definitions. This ensures the entire model tree is updated when code changes are detected.
+
+## Design Decisions
+
+#### Loader Independence from Framework Core
+**Context**: The original design embedded Loader configuration within the Config class, creating tight coupling and circular dependencies.
+
+**Decision**: Make Loader a completely independent utility that takes a config object and operates autonomously.
+
+**Rationale**: This design provides several key benefits:
+- Eliminates circular dependencies that were causing loading failures
+- Separates development tooling from core framework functionality
+- Simplifies the API for users (single `loader.start()` call)
+- Allows Program to focus solely on TUI concerns
+- Makes testing easier with clear dependency boundaries
+
+This decision reinforces the Clean Architecture principle of dependency inversion, where high-level modules (core framework) don't depend on low-level modules (development tools).
+
+#### Kernel.const_get for Dynamic Class Loading
+**Context**: Hot reloading requires getting fresh class definitions after code changes, but `self.class` returns cached objects.
+
+**Decision**: Use `Kernel.const_get(self.class.name).new(merged_state)` instead of `self.class.new(merged_state)` in Model#with.
+
+**Rationale**: This approach ensures that:
+- Fresh class definitions are used after Zeitwerk reloads classes
+- The hot reloading system works reliably across all model types
+- No additional complexity is introduced to the Model API
+- The change is backward compatible and doesn't affect normal operation
+
+The trade-off is slightly more dynamic code, but this is isolated to the development scenario and provides essential functionality.
+
+#### App Directory Configuration Strategy
+**Context**: Zeitwerk requires specific directory structures, and examples have different project layouts than full applications.
+
+**Decision**: Require app_dir to point directly to the models directory, with full paths for examples.
+
+**Rationale**: This decision acknowledges current Zeitwerk limitations while providing a working solution:
+- Enables immediate hot reloading functionality
+- Provides clear path configuration examples
+- Documents the constraint for future improvement
+- Allows examples to work alongside full applications
+
+Noted in documentation that this will be improved in future refactoring to be more flexible.
+
+#### Message-Driven Reload Communication
+**Context**: Hot reloading needs to trigger model rebuilding when code changes are detected.
+
+**Decision**: Use the existing Message system with `Message::Reload` events rather than creating a separate callback mechanism.
+
+**Rationale**: This maintains consistency with the framework's event-driven architecture:
+- Leverages existing message processing infrastructure
+- Keeps reload handling within the normal update cycle
+- Provides predictable behavior that follows Elm Architecture patterns
+- Allows models to handle reloading as part of their normal message processing
+
+## Impact
+
+The completion of the hot reloading system represents a major milestone for the Milktea framework's developer experience. These changes provide:
+
+**For TUI Application Developers**: Hot reloading dramatically reduces development time by eliminating the need to restart applications when making changes. Developers can now iterate on UI layouts, business logic, and interactions in real-time, seeing results immediately.
+
+**For Framework Architecture**: The Loader independence eliminates a significant architectural debt and provides a clean foundation for future development tooling. The separation of concerns makes the framework more modular and testable.
+
+**For Example Development**: The working hot reloading example serves as both a demonstration and a template for developers setting up their own applications with hot reloading capabilities.
+
+**For Project Documentation**: The comprehensive CLAUDE.md documentation ensures that critical setup knowledge is preserved and accessible to future contributors and users.
+
+The changes demonstrate the framework's maturity in supporting professional development workflows while maintaining the simplicity and elegance of the core TUI architecture.
+
+## Files Modified
+
+- `lib/milktea/loader.rb` - Redesigned to be independent from Config, automatic hot_reload handling
+- `lib/milktea/model.rb` - Updated Model#with to use Kernel.const_get for fresh class definitions
+- `lib/milktea/config.rb` - Removed loader from Config class to eliminate circular dependencies
+- `lib/milktea/program.rb` - Removed loader logic to focus on core TUI functionality
+- `examples/hot_reload_demo.rb` - Updated to use new independent Loader pattern
+- `examples/hot_reload_demo/models/demo_model.rb` - Added Message::Reload handling with proper rebuilding
+- `examples/hot_reload_demo/models/status_model.rb` - Child model demonstrating nested reloading
+- `spec/milktea/loader_spec.rb` - Updated tests for new constructor and automatic hot_reload behavior
+- `spec/milktea/config_spec.rb` - Removed loader-related tests to match simplified Config
+- `CLAUDE.md` - Added comprehensive Hot Reloading Development section with setup and troubleshooting
+- `ARCHITECTURE.md` - Updated to reflect new optional Loader system design patterns