scarpe 0.3.0 → 0.5.0

data/LICENSE.txt

@@ -1,6 +1,12 @@
+Scarpe, Lacci and Scarpe-Components code is available under the MIT license.
+
+Bootswatch themes are made by Thomas Park and are released under MIT license.
+Bootstrap Icons are by Bootstrap Icons and are released under MIT license.
+
+=================
 The MIT License (MIT)
 
-Copyright (c) 2022 TODO: Write your name
+Copyright (c) 2022-present, Scarpe team and contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -5,9 +5,9 @@
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-shopify-brightgreen.svg)](https://github.com/Shopify/ruby-style-guide)
 [![Discord](https://img.shields.io/discord/1072538177321058377?label=discord)](https://discord.gg/Ca5EHSsGYp)
 
-<img src="https://user-images.githubusercontent.com/7865030/217309905-7f25e3cf-1850-481d-811b-dfddea2df54a.png" width="200" height="200">
+<img src="docs/static/scarpe-logo.png">
 
-"Scarpe" means shoes in Italian. "Scarpe" also means [Shoes](https://github.com/shoes/shoes-deprecated) in modern Ruby and webview!
+"Scarpe" means shoes in Italian. "Scarpe" also means [Shoes](https://github.com/shoes/shoes-deprecated) in modern Ruby and Webview!
 
 Scarpe isn't feature complete with any version of Shoes (yet?). We're initially targeting [Shoes 3](https://github.com/scarpe-team/scarpe/wiki/ShoesImplementations.md), also called "Red Shoes."
 
@@ -15,7 +15,7 @@ Scarpe isn't feature complete with any version of Shoes (yet?). We're initially
 
 Shoes is an old library (really [several different ones](https://github.com/scarpe-team/scarpe/wiki/ShoesImplementations.md)) that let you build little local desktop computer programs, package them up and give copies to people. Imagine if you can write a tiny little Ruby program (e.g. sneak a peek at the next section) and then it would make a runnable app, opening a window in Ruby, where you could click buttons and play sounds and stuff.
 
-Scarpe is a rewrite of Shoes, because old Shoes doesn't really work any more. There have been a surprising number of rewrites of Shoes over the years -- people love it and miss having it around. This one is ours. Also it uses Webview.
+Scarpe is a rewrite of Shoes, because old Shoes doesn't work any more. There have been a surprising number of rewrites of Shoes over the years -- people love it and miss having it around. This one is ours. By default it uses [Webview](https://github.com/webview/webview).
 
 ## Usage
 
@@ -52,26 +52,23 @@ More examples can be found in the [`examples` folder](https://github.com/scarpe-
 
 ## Wiki
 
-Explore more in the [Scarpe Wiki](https://github.com/scarpe-team/scarpe/wiki) for in-depth documentation, tutorials, and additional resources. Whether you're a new contributor or an experienced user, the Wiki provides valuable information to enhance your Scarpe experience.
+Explore more in the [Scarpe Wiki](https://github.com/scarpe-team/scarpe/wiki) for in-depth documentation, tutorials, and additional resources. Whether you're a new user, a new contributor or an experienced user, the Wiki provides valuable information to enhance your Scarpe experience.
 
 
 ## Scarpe in Development
 
 ### Quickstart
 
-Scarpe requires [Ruby 3.2](https://www.ruby-lang.org/en/downloads/) or higher! You can use `rvm`, `rbenv` or your favourite version control just like normal.
+Scarpe requires [Ruby 3.2](https://www.ruby-lang.org/en/downloads/) or higher! You can use `rvm`, `rbenv` or your favourite version control to install Ruby just like normal.
 
 This repo is where most of the action is happening right now, and to have the full Scarpe experience _today_ this is probably what you want to do.
 
 ```
-# dependencies - Mac version
-brew install portaudio pkg-config # for sound!
-# dependencies - Mac M1 version
-brew install portaudio && bundle config build.bloops --with-portaudio-dir=$(brew --prefix portaudio)
 # dependencies - Ubuntu Linux version
-sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev portaudio19-dev
+sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev
 
-for any other linux or windows. please see the webview docs for your [platform](https://github.com/webview/webview#prerequisites)
+# for any other Linux or Windows please see the webview docs for your platform:
+# https://github.com/webview/webview#prerequisites
 
 # get it
 git clone http://github.com/scarpe-team/scarpe
@@ -83,33 +80,71 @@ cd scarpe; bundle install
 
 If you are using Visual Studio Code, you can use this [extension](https://github.com/gintama91/Scarpe-Vscode-Extension). This extension simplifies the process of executing commands by eliminating the need to repeatedly type lengthy file paths, resulting in a more efficient and productive development experience.
 
-### Finer details
+## Run Test
+
+To Run all availble tests run command 
+
+```
+bundle exec rake ci_test
+
+```
+
+### To Run Tests separately 
+
+Scarpe is composed of [various sub-libraries](https://github.com/scarpe-team/scarpe/wiki/ShoesArchitecture.md). You can run some tests separately.
+
+Run Lacci Tests:
+
+```
+bundle exec rake lacci_test
+
+```
+
+Run Scarpe-Components Tests:
+
+```
+bundle exec rake component_test
+```
+
+Run Scarpe Tests:
+
+```
+bundle exec rake test
+```
+
+Check HTML Output:
+
+```
+bundle exec rake test:check_html_fixtures
+```
+
+### Finer Details
 
 First, clone the [main GitHub repository](https://github.com/scarpe-team/scarpe).
 
-`bundle install` dependencies like webview from the cloned directory in your Ruby of choice.
+`bundle install` dependencies like Webview from the cloned directory in your Ruby of choice.
 
 You can run without Scarpe being installed by including its directory. For instance, from the "examples" directory you can run `ruby -I../lib -I../lacci/lib -rscarpe hello_world.rb`. You can also install Scarpe locally (`gem build scarpe.gemspec && gem install scarpe-0.1.0.gem`) or using a Gemfile with the "path" option for local Scarpe.
 
 Most commonly we are all using this command: `./exe/scarpe examples/button.rb --dev --debug`
 
-The `--dev` flag points to your local scarpe rather than an installed Scarpe gem.
+The `--dev` flag points to your local Scarpe rather than an installed Scarpe gem.
 
 The `--debug` flag will dump a ton of useful information to the console if you want to see what's happening with your app.
 
-It's very early in the development process. If you'd like to help develop Scarpe, great! It would be useful to drop us a message/issue/PR on GitHub early on, so we know you're working in a particular area, and we can warn you if anybody else is currently doing so. We also have a Discord.
+It's very early in Scarpe's development process. If you'd like to help develop Scarpe, great! It would be useful to drop us a message/issue/PR on GitHub early on, so we know you're working in a particular area, and we can warn you if anybody else is currently doing so. We also have a Discord.
 
 We'd love the help!
 
-If you want to quickly add a feature, you can use the `ruby scarpegen.rb` command. This command will generate the necessary files for you, along with a simple template and a set of questions to guide you through the process. By following these steps, you will be good to go!
+If you want to quickly add a feature, you can use the `ruby scarpegen.rb` command. This command will generate the necessary files for you, along with a simple template and a set of questions to guide you through the process. By leveraging the `ruby scarpegen.rb` command and the provided resources, you can expedite the feature addition process and ensure a smoother development experience.
 
-By leveraging the `ruby scarpegen.rb` command and the provided resources, you can expedite the feature addition process and ensure a smoother development experience.
-
-## Are we done yet?
+## Are We Done Yet?
 
 Great question! Right now we have a few key things we want to achieve. The first is passing all of the examples we can get our hands on. The second is passing [Hackety-Hack](https://github.com/hacketyhack/hacketyhack). We're manually keeping tabs on that here.
 
-### Webview Display Service Examples Passing
+But the short version is: no, we're far from done. Some Shoes features (e.g. multiple window support) may be very difficult to support with Webview at all. We're working on other ways to handle those features.
+
+### Examples Passing with the Webview Display Service
 
 ![](https://geps.dev/progress/30?dangerColor=800000&warningColor=ff9900&successColor=006600)
 
@@ -134,6 +169,31 @@ The SCARPE_TEST_CONTROL environment variable can contain a path to a test-contro
 
 If you run ./exe/scarpe --dev env, you can see all current environment settings.
 
+## Shoes-Spec
+
+Pre-Scarpe Shoes didn't have specific test APIs or infrastructure. That was pretty standard for GUI libraries when it was written. Scarpe supports a test API called Shoes-Spec, and different display services tend to extend it.
+
+The idea is that you write a standard Shoes application and then there's additional test code that runs once your application is running. Since different display services run in very different ways (e.g. Webview vs Wasm vs GTK+), the test code isn't necessarily in the same Ruby process as the Shoes application.
+
+They're often packaged in .sspec files that look like this:
+
+~~~
+---
+----------- app code
+Shoes.app do
+  @b = button "OK" do
+    @b.text = "Clicked"
+  end
+end
+
+----------- test code
+assert_equal "OK", button().text
+button().trigger_click
+assert_equal "Clicked", button().text
+~~~
+
+See [https://github.com/scarpe-team/shoes-spec] for more details.
+
 ## More info
 
 * [Nobody Knows Shoes manual](https://github.com/whymirror/why-archive/raw/master/shoes/nobody-knows-shoes.pdf)

data/Rakefile

@@ -1,27 +1,86 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
-require "rubocop/rake_task"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+# Rakefile
+
+task :ci_test do
+  puts "
+  \033[1;32;4;47mInstalling Dependencies\033[0m
+  "
+
+  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
+  "
+  system('CI_RUN=true bundle exec rake lacci_test')
+
+  puts "
+  \033[1;32;4;47mRun Scarpe-Component Tests\033[0m
+  "
+
+  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
+  "
+  system('if [ ! -z "$(ls logger/test_failure*.out.log 2>/dev/null)" ]; then actions/upload-artifact@v4 --name "test failure logs" --path logger/test_failure*.out.log; fi')
+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
 
-RuboCop::RakeTask.new
+namespace :test do
+  desc 'Regenerate HTML fixtures'
+  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')
+    load 'tasks/check_html_fixtures.rb'
+  end
+end
 
-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>