scarpe 0.4.0 → 0.5.0

data/Rakefile

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
-require "rubocop/rake_task"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 # Rakefile
 
@@ -13,20 +12,18 @@ task :ci_test do
 
   system('brew install pkg-config portaudio')
 
- 
   puts "
   \033[1;32;4;47mCheckout Code\033[0m
   "
   system('git checkout main')
 
- 
   puts "
   \033[1;32;4;47mSetup Ruby and install Gems\033[0m
   "
   system('bundle install')
 
   # Run tests
-  
+
   puts "
   \033[1;32;4;47mRun Lacci Tests\033[0m
   "
@@ -38,19 +35,16 @@ task :ci_test do
 
   system('CI_RUN=true bundle exec rake component_test')
 
- 
   puts "
   \033[1;32;4;47mRun Scarpe Tests\033[0m
   "
   system('CI_RUN=true bundle exec rake test')
 
-  
   puts "
   \033[1;32;4;47mCheck HTML Output\033[0m
   "
   system('bundle exec rake test:check_html_fixtures')
 
- 
   puts "
   \033[1;32;4;47mUpload Fail logs\033[0m
   "
@@ -58,37 +52,35 @@ task :ci_test do
 end
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
 end
 
 Rake::TestTask.new(:lacci_test) do |t|
-  t.libs << "lacci/test"
-  t.libs << "lacci/lib"
-  t.test_files = FileList["lacci/test/**/test_*.rb"]
+  t.libs << 'lacci/test'
+  t.libs << 'lacci/lib'
+  t.test_files = FileList['lacci/test/**/test_*.rb']
 end
 
 Rake::TestTask.new(:component_test) do |t|
-  t.libs << "scarpe-components/test"
-  t.libs << "scarpe-components/lib"
-  t.test_files = FileList["scarpe-components/test/**/test_*.rb"]
+  t.libs << 'scarpe-components/test'
+  t.libs << 'scarpe-components/lib'
+  t.test_files = FileList['scarpe-components/test/**/test_*.rb']
 end
 
 namespace :test do
   desc 'Regenerate HTML fixtures'
-  task :regenerate_html_fixtures do |t|
-    ENV['SELECTED_FILE'] = ARGV[-1] if ARGV[-1].include?(".rb")
+  task :regenerate_html_fixtures do |_t|
+    ENV['SELECTED_FILE'] = ARGV[-1] if ARGV[-1].include?('.rb')
     load 'tasks/regenerate_html_fixtures.rb'
   end
 
   desc 'Check HTML fixtures against latest output'
-  task :check_html_fixtures do |t|
-    ENV['SELECTED_FILE'] = ARGV[-1] if ARGV[-1].include?(".rb")
+  task :check_html_fixtures do |_t|
+    ENV['SELECTED_FILE'] = ARGV[-1] if ARGV[-1].include?('.rb')
     load 'tasks/check_html_fixtures.rb'
   end
 end
 
-RuboCop::RakeTask.new
-
-task default: [:test, :lacci_test, :component_test]
+task default: %i[test lacci_test component_test]

data/docs/SCARPE_FEATURES.md

@@ -0,0 +1,38 @@
+---
+layout: default
+title: Scarpe Features
+---
+
+# Extending _why's Legacy
+
+![Would _why have a beard if he existed now](image.png)
+
+The leading mission for Scarpe has been to implement as much backwards compatibility as possible for _why's original
+Shoes library. This remains true. _why's taste and DSL are celebrated and preserved. However, at the discretion of
+core maintainers, new features may be added. They must be approved by Noah Gibbs or Nick Schwaderer, and described
+in this file. They cannot conflict or damage backwards compatibility with the original Shoes library.
+
+## Page Navigation
+
+Similar to URL navigation. see `url_navigation_single_app.rb` for an example. Unlike URLs, they do not accept parameters,
+only the name of the page. They are simply declared and named in blocks.
+
+```ruby
+Shoes.app do
+  page(:home) do
+    title "Home Page"
+    para "Welcome to the home page"
+    button "Go to another page" do
+      visit(:another_page)
+    end
+  end
+
+  page(:another_page) do
+    title "Another Page"
+    para "Welcome to another page"
+    button "Go to home page" do
+      visit(:home)
+    end
+  end
+end
+```

data/docs/_config.yml

@@ -0,0 +1,13 @@
+title: Scarpe
+description: Shoes in modern Ruby and Webview
+remote_theme: pages-themes/minimal@v0.2.0
+plugins:
+  - jekyll-remote-theme
+
+# Include static assets
+include:
+  - static
+
+# Exclude files from build
+exclude:
+  - yard/

data/docs/calzini_components_and_updates.md

@@ -0,0 +1,78 @@
+---
+layout: default
+title: calzini components and updates
+---
+
+# Calzini Components and Updates
+
+Calzini is Scarpe's component system, providing a modern approach to UI components while maintaining Shoes compatibility.
+
+## Component Structure
+
+Components in Calzini follow this structure:
+
+1. **Base Components**
+   - Built-in widgets (Button, EditLine, etc.)
+   - Layout components (Stack, Flow)
+   - Custom components
+
+2. **Component Lifecycle**
+```ruby
+class CalziniComponent
+  def initialize
+    setup_state
+    register_handlers
+  end
+
+  def update
+    calculate_layout
+    trigger_display_update
+  end
+end
+```
+
+## State Management
+
+Components manage state through:
+
+1. **Internal State**
+   - Local component state
+   - Cached calculations
+   - Temporary values
+
+2. **External State**
+   - Props from parent components
+   - Global application state
+   - Shared resources
+
+## Update Mechanism
+
+Updates in Calzini happen through:
+
+1. **Change Detection**
+   - State changes trigger updates
+   - Props changes propagate
+   - Layout changes cascade
+
+2. **Update Process**
+   - Changes are batched
+   - Updates are scheduled
+   - Display is refreshed efficiently
+
+## Best Practices
+
+When working with Calzini components:
+
+1. Keep components focused and small
+2. Use proper state management
+3. Optimize update triggers
+4. Handle errors gracefully
+
+## Shoes Compatibility
+
+Calzini maintains compatibility with Shoes:
+
+- Similar API structure
+- Familiar component names
+- Compatible event handling
+- Consistent behavior

data/docs/display_service_separation.md

@@ -0,0 +1,39 @@
+---
+layout: default
+title: Display Service Separation
+---
+
+# Display Service Separation
+
+The display service in Scarpe is separated from the main application to provide better isolation and flexibility. This design choice allows for:
+
+1. Clear separation between the application logic and display logic
+2. Ability to swap out display implementations
+3. Better testing capabilities through isolation
+4. Reduced coupling between components
+
+## Architecture
+
+The display service runs as a separate process from the main Scarpe application. Communication happens through a well-defined protocol that includes:
+
+- Event messages for user interactions
+- Display update commands
+- State synchronization messages
+
+## Benefits
+
+This separation provides several key benefits:
+
+1. **Security**: The display service can run with different permissions
+2. **Stability**: Issues in the display layer won't crash the main application
+3. **Flexibility**: Different display implementations can be used without changing the core application
+4. **Testing**: Components can be tested in isolation
+
+## Implementation Details
+
+The display service communicates with the main application through a message-passing interface. This allows for:
+
+- Asynchronous updates
+- Clean separation of concerns
+- Easy testing and mocking
+- Future extensibility

data/docs/documentation.md

@@ -0,0 +1,43 @@
+---
+layout: default
+title: Documentation
+---
+
+# Documentation
+
+## The Shoes Manual
+
+The comprehensive guide to Shoes — everything you need to know.
+
+**[Read the Manual →](static/manual)**
+
+---
+
+## Architecture & Internals
+
+For contributors and the curious.
+
+| Document | Description |
+|----------|-------------|
+| [Lacci](lacci) | The Shoes compatibility layer |
+| [Display Service](display_service_separation) | How Scarpe separates app logic from rendering |
+| [Events](shoes_and_display_events) | Event handling in Scarpe |
+| [Event Loops](event_loops) | Understanding the event loop architecture |
+| [Timeouts & Handlers](timeouts_and_handlers) | Timing and callback patterns |
+| [Calzini Components](calzini_components_and_updates) | The HTML rendering component system |
+
+---
+
+## Reference
+
+| Document | Description |
+|----------|-------------|
+| [Scarpe Features](SCARPE_FEATURES) | New features beyond original Shoes |
+| [Incompatibilities](scarpe_shoes_incompatibilities) | Known differences from Shoes 3 |
+| [Shoes Implementations](shoes_implementations) | History of Shoes reimplementations |
+
+---
+
+<p style="text-align: center; margin-top: 2rem;">
+  <a href="./">← Back to Home</a>
+</p>

data/docs/event_loops.md

@@ -0,0 +1,66 @@
+---
+layout: default
+title: event loops
+---
+
+# Event Loops
+
+Scarpe's event loop system is a core part of its architecture, handling both UI events and application logic.
+
+## Main Event Loop
+
+The main event loop is responsible for:
+
+1. Processing user input
+2. Handling timer events
+3. Managing display updates
+4. Coordinating between components
+
+## Implementation Details
+
+The event loop is implemented with these key features:
+
+### Event Queue
+- Events are queued in order of arrival
+- Priority system for critical events
+- Efficient processing of batched events
+
+### Handler Registration
+```ruby
+class EventLoop
+  def register_handler(event_type, &block)
+    handlers[event_type] << block
+  end
+end
+```
+
+### Event Processing
+- Events are processed in a single thread
+- Non-blocking operations where possible
+- Careful handling of long-running tasks
+
+## Cooperative Multitasking
+
+Scarpe uses cooperative multitasking where:
+
+1. Tasks yield control voluntarily
+2. Long operations are broken into smaller chunks
+3. The event loop maintains responsiveness
+
+## Best Practices
+
+When working with the event loop:
+
+1. Keep handlers fast and focused
+2. Avoid blocking operations
+3. Use async operations for long-running tasks
+4. Handle errors appropriately
+
+## Integration with Display Service
+
+The event loop coordinates closely with the display service:
+
+- Synchronizes state updates
+- Manages display refresh timing
+- Handles animation frames
+- Coordinates user input

data/docs/index.md

@@ -0,0 +1,118 @@
+---
+layout: default
+title: Scarpe - Shoes in Modern Ruby
+---
+
+<div style="text-align: center; margin-bottom: 2rem;">
+  <img src="static/scarpe-logo.png" alt="Scarpe Logo" style="max-width: 400px; width: 100%;">
+  <p style="font-size: 1.4rem; color: #666; font-style: italic; margin-top: 1rem;">Scarpe Diem: Seize the Shoes</p>
+</div>
+
+---
+
+**Scarpe** (Italian for "shoes") is a modern reimplementation of [Why The Lucky Stiff's Shoes](https://github.com/shoes/shoes-deprecated) — the beloved Ruby GUI toolkit that made desktop app creation accessible to everyone.
+
+```ruby
+Shoes.app do
+  button "Click me!" do
+    alert "Hello, Shoes!"
+  end
+end
+```
+
+That's it. That's a desktop app.
+
+---
+
+## Why Scarpe?
+
+Shoes was magic. Write a few lines of Ruby, get a real desktop application. No frameworks, no build tools, no complexity. Just pure, joyful programming.
+
+But old Shoes stopped working. Scarpe brings it back — built on modern Ruby and [Webview](https://github.com/niclas-pehrsson/webview_ruby), running on macOS, Linux, and Windows.
+
+<div style="display: flex; flex-wrap: wrap; gap: 1rem; margin: 2rem 0;">
+  <div style="flex: 1; min-width: 200px; padding: 1rem; background: #f8f8f8; border-radius: 8px;">
+    <h3>Simple</h3>
+    <p>Write desktop apps in pure Ruby. No ceremony, no boilerplate.</p>
+  </div>
+  <div style="flex: 1; min-width: 200px; padding: 1rem; background: #f8f8f8; border-radius: 8px;">
+    <h3>Beautiful</h3>
+    <p>Elegant DSL for layouts, text, images, shapes, and animations.</p>
+  </div>
+  <div style="flex: 1; min-width: 200px; padding: 1rem; background: #f8f8f8; border-radius: 8px;">
+    <h3>Fun</h3>
+    <p>Programming should be joyful. Scarpe keeps the whimsy alive.</p>
+  </div>
+</div>
+
+---
+
+## Quick Start
+
+```bash
+gem install scarpe
+
+# Create hello.rb
+echo 'Shoes.app { para "Hello, World!" }' > hello.rb
+
+# Run it!
+scarpe hello.rb
+```
+
+---
+
+## A Taste of Scarpe
+
+```ruby
+Shoes.app(title: "My App", width: 400, height: 300) do
+  background "#f5f5f5"
+
+  stack margin: 20 do
+    title "Welcome!"
+    para "Scarpe makes GUI programming simple."
+
+    flow do
+      button("Say Hello") { alert("Hello!") }
+      button("Goodbye") { exit }
+    end
+  end
+end
+```
+
+Stacks and flows for layout. Buttons and text with one line each. Blocks for callbacks. Ruby as it should be.
+
+---
+
+## Documentation
+
+<div style="display: flex; flex-wrap: wrap; gap: 1rem; margin: 1rem 0;">
+  <a href="static/manual" style="flex: 1; min-width: 150px; padding: 1rem; background: #CC342D; color: white; text-align: center; border-radius: 8px; text-decoration: none;">
+    <strong>The Manual</strong><br>
+    <small>Complete reference</small>
+  </a>
+  <a href="documentation" style="flex: 1; min-width: 150px; padding: 1rem; background: #666; color: white; text-align: center; border-radius: 8px; text-decoration: none;">
+    <strong>All Docs</strong><br>
+    <small>Architecture & internals</small>
+  </a>
+  <a href="https://github.com/scarpe-team/scarpe" style="flex: 1; min-width: 150px; padding: 1rem; background: #333; color: white; text-align: center; border-radius: 8px; text-decoration: none;">
+    <strong>GitHub</strong><br>
+    <small>Source & issues</small>
+  </a>
+  <a href="https://discord.gg/Ca5EHSsGYp" style="flex: 1; min-width: 150px; padding: 1rem; background: #5865F2; color: white; text-align: center; border-radius: 8px; text-decoration: none;">
+    <strong>Discord</strong><br>
+    <small>Community chat</small>
+  </a>
+</div>
+
+---
+
+## In Memory
+
+*Scarpe is developed in loving memory of [Noah Gibbs](https://codefol.io/), who believed in this project and whose thoughtful documentation lives on in every design decision.*
+
+---
+
+<div style="text-align: center; margin-top: 3rem; color: #999;">
+  <p>Made with Ruby and whimsy.</p>
+  <p><small>Scarpe is open source under the MIT license.</small></p>
+</div>

data/docs/lacci.md

@@ -0,0 +1,121 @@
+---
+layout: default
+title: Lacci
+---
+
+# Lacci: The Shoes4 Compatibility Layer
+
+## Overview
+
+Lacci (Italian for "laces") serves as the compatibility layer between Shoes4 applications and Scarpe's display services. Think of it as the translator that allows your classic Shoes4 code to work seamlessly with modern display backends.
+
+## Core Concepts
+
+### 1. Event Handling and Drawing Model
+
+Lacci implements the Shoes4 drawing model, which includes:
+- Slot-based layout system (stacks, flows)
+- Event propagation
+- Drawing context inheritance
+- Margin and positioning calculations
+
+### 2. Display Service Abstraction
+
+Lacci abstracts away the details of different display services (like Webview or Qt) by:
+- Translating Shoes4 drawing commands into display-agnostic operations
+- Managing widget lifecycles
+- Handling parent-child relationships between elements
+- Coordinating style inheritance
+
+### 3. Test Infrastructure
+
+The test infrastructure in Lacci uses Niente (Italian for "nothing"), a null display service that:
+- Allows testing without a real display backend
+- Verifies drawing operations and event handling
+- Supports multiple simultaneous Shoes apps in test environments
+- Provides fast, reliable test execution
+
+## Key Components
+
+### MarginHelper
+Handles margin calculations with support for:
+- Numeric values
+- Array-based margins
+- Hash-based margins
+- String-based margin definitions
+
+### FontHelper
+Manages font parsing and styling with support for:
+- Font families
+- Font sizes
+- Font weights
+- Font variants
+- Font styles
+
+### DrawContext
+Manages the drawing context inheritance system:
+- Style propagation (fill, stroke, etc.)
+- Context stacking
+- Property overrides
+
+## Usage Examples
+
+```ruby
+# Basic Shoes4 App
+Shoes.app do
+  stack do
+    para "Hello from Lacci!"
+    button "Click me" do
+      alert "Button clicked!"
+    end
+  end
+end
+```
+
+## Error Handling
+
+Lacci provides rich error handling through the `Shoes::Errors` module:
+- `InvalidAttributeValueError`
+- `BadArgumentListError`
+- `UnsupportedFeatureError`
+- `MultipleDrawablesFoundError`
+- `NoDrawablesFoundError`
+
+## Display Service Requirements
+
+For a display service to be compatible with Lacci, it must:
+1. Implement the basic drawing primitives
+2. Support parent-child relationships
+3. Handle event propagation
+4. Manage drawing contexts
+5. Support style inheritance
+
+## Testing
+
+Lacci uses a comprehensive test suite with:
+- Unit tests for helpers and utilities
+- Integration tests for drawing operations
+- Feature tests for end-to-end functionality
+- Niente-based tests for display service compatibility
+
+## Future Development
+
+Areas for future enhancement include:
+- Additional drawing primitives
+- Enhanced animation support
+- Improved error reporting
+- Extended display service capabilities
+
+## Contributing
+
+When contributing to Lacci:
+1. Ensure tests pass with Niente
+2. Maintain backward compatibility
+3. Follow the existing error handling patterns
+4. Document new features and changes
+
+## Related Components
+
+- Scarpe: The main project
+- Niente: The null display service for testing
+- Display Services: Various backend implementations

data/docs/scarpe_shoes_incompatibilities.md

@@ -0,0 +1,71 @@
+---
+layout: default
+title: scarpe shoes incompatibilities
+---
+
+# Scarpe/Shoes Incompatibilities
+
+This document outlines the known incompatibilities between Scarpe and the original Shoes implementation.
+
+## API Differences
+
+1. **Method Names**
+   - Some methods have been renamed for clarity
+   - Deprecated Shoes methods are not supported
+   - New methods added for modern features
+
+2. **Parameters**
+   - Some parameter orders have changed
+   - Additional options are available
+   - Some legacy options are not supported
+
+## Behavioral Changes
+
+Key behavioral differences include:
+
+1. **Event Handling**
+   - More consistent event model
+   - Better async support
+   - Different timing guarantees
+
+2. **Layout System**
+   - More predictable layout behavior
+   - Enhanced flexibility
+   - Some legacy layouts may render differently
+
+## Unsupported Features
+
+Some Shoes features are not supported in Scarpe:
+
+1. **Legacy Components**
+   - Certain deprecated widgets
+   - Old animation system
+   - Legacy drawing methods
+
+2. **Platform-Specific Features**
+   - Some OS-specific capabilities
+   - Direct hardware access
+   - Legacy system integration
+
+## Modernization Changes
+
+Intentional changes for modern development:
+
+1. **Architecture**
+   - Separate display service
+   - Modern component model
+   - Enhanced state management
+
+2. **Development Experience**
+   - Better debugging tools
+   - Modern testing support
+   - Improved error messages
+
+## Migration Guide
+
+When moving from Shoes to Scarpe:
+
+1. Review API changes
+2. Update event handlers
+3. Test layouts thoroughly
+4. Use modern alternatives for legacy features