sandals 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8706dd760aa94d3533ea6c2fb18bf8d265272a3c49250e1539300e8f2d960740
+  data.tar.gz: 87590e396a533c73abc3eb6689c90481f301d84c885e344bb21148845f602baf
+SHA512:
+  metadata.gz: b5cf4873ca1ebc024b7f45c744b3d7747ace37a867b6a0c9dfb9e85861398e3bf2ff99d7a431c1e7c9d063f1df1b5a65684918fa581ab2bfcf94915e2201fe81
+  data.tar.gz: 1e17469e4cb0a3bdf878ffafc07d45e083e620a8410704c012c2cd524268e2b22d3786a6c7cf0db04e1b28707fea3198b121dbe5e0cc5b6bf7323d6d039a3705

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandals 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,604 @@
+# Sandals
+
+Sandals is a small environment for running interactive Ruby applications whose
+structure can be understood by reading their code.
+
+The central idea is simple:
+
+> Describe a small tool in Ruby, run it immediately, and be able to understand
+> what it displays, what data it keeps, and what happens with each action.
+
+Sandals is not trying to be another web framework or to recreate all of Shoes.
+It also does not try to hide a complex application behind a magical DSL. Its
+purpose is to find a clear, concise, and expressive way to write small
+applications that both people and AI can create and understand.
+
+## Installation
+
+Sandals requires Ruby 3.1 or later.
+
+```sh
+gem install sandals
+sandals run app.rb
+```
+
+The server listens on `127.0.0.1`. All required assets are included in the gem,
+so a local app does not need an internet connection.
+
+## The experience
+
+An application should normally fit in a single file:
+
+```ruby
+require "sandals"
+
+Sandals.app title: "Counter" do
+  @count = 0
+
+  view do
+    stack do
+      title "Counter"
+      para "Total: #{@count}"
+
+      button "Increment" do
+        @count += 1
+      end
+    end
+  end
+end
+```
+
+Run it with:
+
+```sh
+sandals run counter.rb
+```
+
+Sandals starts a local Ruby process, opens the application in the browser, and
+handles communication between the interface and its actions. To the person
+creating or using the application, it should feel like running a Ruby program,
+not configuring a web project.
+
+## Layout and content
+
+`stack` arranges elements vertically. `flow` arranges them horizontally and
+allows them to wrap onto the next line:
+
+```ruby
+view do
+  stack do
+    title "Tool"
+
+    flow do
+      button "Cancel"
+      button "Continue"
+    end
+  end
+end
+```
+
+`title` is the main heading, `subtitle` introduces a section, and `para`
+represents regular prose:
+
+```ruby
+stack do
+  subtitle "Result"
+  para "The pressure is ", strong("high"),
+    " and requires ", em("review"), "."
+end
+```
+
+`para` renders as a paragraph and can combine strings with `strong` for
+important content and `em` for emphasis.
+
+`image` displays an image from a path or URL. Alternative text is optional, but
+should describe the image whenever it carries meaningful content:
+
+```ruby
+image "red-sandals.jpg", alt: "A pair of red sandals"
+```
+
+`link` creates a regular external link. Navigation is handled entirely by the
+browser and does not run a server-side action:
+
+```ruby
+link "Documentation", to: "https://example.com/docs"
+```
+
+Sandals currently accepts `http`, `https`, and `mailto` destinations. Internal
+routes are reserved until a concrete application needs its own navigation.
+
+## Fields and actions
+
+`text_field` displays a labeled text input with an optional initial value. Its
+block receives the new value whenever the field changes:
+
+```ruby
+text_field "Name", value: @name do |value|
+  @name = value
+end
+```
+
+Fields accept `error:` to display validation next to the control. Sandals marks
+the field as invalid and associates the message using ARIA attributes:
+
+```ruby
+text_field "Name", value: @name, error: @errors[:name] do |value|
+  @name = value
+end
+```
+
+`error` displays a general problem with an operation or form:
+
+```ruby
+error "Review the highlighted fields." unless @errors.empty?
+```
+
+`notice` communicates a successful result or non-urgent information:
+
+```ruby
+notice "Profile saved."
+```
+
+`button` runs its block using the Ruby state already updated by the fields:
+
+```ruby
+button "Greet" do
+  @message = "Hello, #{@name}"
+end
+```
+
+While an action is pending, Sandals disables only the button that initiated it
+and marks it with `aria-busy`. This prevents double clicks without interrupting
+other fields.
+
+If a field or button block raises an exception, Sandals keeps the last valid
+view and displays the action name, error, file, and line. The next successful
+event clears the message. Ruby state changed before the exception is not rolled
+back automatically.
+
+`number_field` works like `text_field`, but its block receives an `Integer`, a
+`Float`, or `nil` when the field is empty:
+
+```ruby
+number_field "Quantity", value: @quantity do |value|
+  @quantity = value
+end
+```
+
+`text_area` edits multiline text and passes the new string to its block:
+
+```ruby
+text_area "Notes", value: @notes do |value|
+  @notes = value
+end
+```
+
+`checkbox` represents a boolean choice and passes `true` or `false`:
+
+```ruby
+checkbox "I agree", checked: @accepted do |checked|
+  @accepted = checked
+end
+```
+
+`select` chooses a string from a collection of options:
+
+```ruby
+select "Color", options: %w[Red Blue], value: @color do |value|
+  @color = value
+end
+```
+
+When the Ruby value differs from the visible label, `options` can be a
+`value => label` hash. The block receives the original Ruby value:
+
+```ruby
+select(
+  "Country",
+  options: { mx: "Mexico", us: "United States" },
+  value: @country
+) do |country|
+  @country = country
+end
+```
+
+`radio` provides the same key/value choice as a visible group:
+
+```ruby
+radio(
+  "Color",
+  options: { red: "Red", blue: "Blue" },
+  value: @color
+) do |color|
+  @color = color
+end
+```
+
+## Binding fields to models
+
+A field can bind directly to the getter and setter of a Ruby object:
+
+```ruby
+text_field "Name", model: @profile, bind: :name
+```
+
+Sandals reads `@profile.name`, writes through `@profile.name=`, and, when the
+object responds to `errors`, displays `@profile.errors[:name]`. `bind:` cannot
+be combined with `value:` or an action block.
+
+Binding is the recommended convention when state belongs to a model:
+
+```ruby
+text_field "Name", model: @profile, bind: :name
+number_field "Age", model: @profile, bind: :age
+checkbox "Newsletter", model: @profile, bind: :newsletter
+```
+
+Inline blocks remain useful when a change requires a transformation or an
+explicit effect, or when the state is so small that creating a model would not
+improve readability:
+
+```ruby
+select "Currency", options: %w[MXN USD], value: @currency do |currency|
+  @currency = currency
+  @quote = Quotes.fetch(currency)
+end
+```
+
+The two profile form versions and the margin calculator can be run separately:
+
+```sh
+sandals run app
+sandals run app_with_bindings
+sandals run app_margin_calculator
+```
+
+## Forms
+
+`form` allows an action to run when the user presses Enter through a `submit`.
+It does not collect and resend field values: fields have already synchronized
+their values with Ruby state.
+
+```ruby
+form do
+  text_field "New task", model: @draft, bind: :title
+
+  submit "Add" do
+    @list.add(@draft.title)
+  end
+end
+```
+
+A `button` remains an independent action. `submit` can only be declared inside
+a `form`.
+
+## Uploaded files
+
+`file_field` lets a user select a file without giving the application an
+arbitrary system path:
+
+```ruby
+file_field "CSV file" do |file|
+  rows = CSV.parse(file.read, headers: true)
+end
+```
+
+The block receives a `Sandals::UploadedFile`:
+
+```ruby
+file.name
+file.content_type
+file.size
+file.read
+```
+
+The web host receives the file as multipart data with a 10 MB limit. The
+runtime does not save it permanently. Tests can attach a fixture through the
+semantic DSL:
+
+```ruby
+session.attach "CSV file", file: "test/fixtures/people.csv"
+```
+
+The complete application is available in `app_csv_reader.rb`.
+
+## Tables
+
+`table` displays collections using explicit headers and rows:
+
+```ruby
+table(
+  headers: ["Name", "City"],
+  rows: [
+    ["Ada", "London"],
+    ["Matz", "Tokyo"]
+  ]
+)
+```
+
+Cells can use `strong` and `em`, but cannot contain interactive controls. Every
+row must have the same number of cells as the header. `table` does not replace
+a general `each`; it is for genuinely tabular data.
+
+## Semantic tests
+
+`Sandals.test` runs the application without a browser and finds controls by
+their visible text rather than internal IDs:
+
+```ruby
+session = Sandals.test(application)
+cost = session.field("Cost")
+price = session.field("Price")
+
+cost.fill 60
+price.fill 100
+
+assert session.text?("Margin: 40.0%")
+
+price.fill 50
+
+refute session.text?("Margin:")
+assert_equal "Price must be greater than cost", session.field_error(price)
+```
+
+Other controls are operated using their visible labels and options:
+
+```ruby
+session.check "Newsletter"
+session.uncheck "Newsletter"
+session.select "Colombia", from: "Country"
+session.choose "Phone", from: "Contact"
+session.click "Save"
+```
+
+The same operations are available through a field reference:
+
+```ruby
+session.field("Newsletter").check
+session.field("Country").select("Colombia")
+session.field("Contact").choose("Phone")
+```
+
+General messages can be distinguished from other visible text:
+
+```ruby
+assert session.notice?("Saved")
+assert session.error?("Could not save")
+
+session.assert_notice "Saved"
+session.refute_notice "Missing notice"
+session.assert_error "Could not save"
+session.refute_error "Missing error"
+```
+
+References such as `price` are semantic locators. They find the field again in
+the current snapshot after every render instead of retaining stale objects
+from a previous view.
+
+## Sessions
+
+Each browser gets an independent application instance. One person's interface
+state is not shared with anyone else:
+
+```ruby
+definition = Sandals.app do
+  @name = ""
+
+  view do
+    text_field "Name", value: @name do |value|
+      @name = value
+    end
+  end
+end
+
+ana = definition.new_session
+beto = definition.new_session
+```
+
+`ana` and `beto` run the same definition but keep separate variables and
+snapshots. Data that must be shared between people should live in an external
+model or repository, not in application instance variables.
+
+## Persistence with external ORMs
+
+Sandals does not include or wrap an ORM. Sequel and Active Record objects can
+use `model:` and `bind:` through the same Ruby interface as any other model.
+
+The repository includes two equivalent implementations of a persistent task
+list:
+
+- `examples/todos_sequel/app.rb`
+- `examples/todos_active_record/app.rb`
+
+Install the development dependencies and run either example:
+
+```sh
+bundle install
+bundle exec bin/sandals run examples/todos_sequel/app.rb
+bundle exec bin/sandals run examples/todos_active_record/app.rb
+```
+
+Each example configures SQLite, creates its table, and performs persistence
+operations explicitly:
+
+```ruby
+@draft.save
+todo.update(completed:)
+todo.destroy
+```
+
+The SQLite file uses the example directory by default. To choose another
+location:
+
+```sh
+SANDALS_TODOS_DATABASE=/path/to/todos.sqlite3 \
+  bundle exec bin/sandals run examples/todos_sequel/app.rb
+```
+
+This keeps a clear boundary: Sandals manages sessions and views; the
+application's ORM manages records, validations, and the database.
+
+Applications that query shared data can request periodic reevaluation:
+
+```ruby
+Sandals.app do
+  refresh every: 5
+
+  view do
+    Todo.order(:id).each do |todo|
+      # ...
+    end
+  end
+end
+```
+
+The interval is expressed in seconds and must be at least one. Sandals
+serializes refreshes with pending events, pauses them while the tab is hidden,
+and refreshes when the tab becomes visible again. This feature is optional and
+does not synchronize temporary state between sessions.
+
+## Development reload
+
+`sandals run` watches the application's main file. When the file changes and
+can be loaded successfully, the browser reloads and starts a new session:
+
+```sh
+bundle exec bin/sandals run app.rb
+```
+
+Temporary state and snapshots are reset; SQLite and other external storage
+remain intact.
+
+If the new version has a syntax or load error, Sandals keeps the last valid
+definition and displays the error with its location. It continues watching the
+file and recovers automatically when the error is fixed.
+
+The current version watches only the file passed to `sandals run`, not files
+loaded indirectly through `require`.
+
+## Mental model
+
+```text
+Ruby state
+    ↓
+view
+    ↓
+Interface
+    ↓
+User action
+    ↓
+Ruby changes the state
+    ↓
+view is evaluated again
+```
+
+When the user presses a button, Sandals runs its block and produces the view
+again. The interface is a direct representation of current state, without
+manual DOM manipulation or an additional reactive system.
+
+## Architecture
+
+```text
+app.rb
+   ↓
+Ruby
+   ↓
+Sandals runtime
+   ↓
+Local server
+   ↓
+HTML in the browser
+```
+
+The browser is the universal renderer. Application logic and state live in
+Ruby.
+
+Each evaluation of `view` produces a `Sandals::View` object independent from
+the renderer:
+
+```text
+Application
+    ↓ evaluates the block
+Sandals::View
+    ↓ contains elements
+HTMLRenderer
+    ↓
+HTML
+```
+
+The view can be inspected directly:
+
+```ruby
+view = app.render_view
+title = view.children.first
+
+title.class
+# Sandals::Title
+
+title.content
+# "Hello from Sandals"
+```
+
+This makes it possible to test and explain an application's structure without
+depending on generated HTML. The block still runs in the application context,
+so its Ruby state belongs to the application.
+
+In the future, the same application could have different hosts:
+
+```text
+sandals run app.rb       → local browser
+sandals desktop app.rb   → desktop window
+sandals serve app.rb     → accessible server
+```
+
+Only the first mode is part of the current experiment.
+
+## Design goals
+
+Sandals favors:
+
+- useful applications that are tens or hundreds of lines long;
+- code that reads from top to bottom;
+- state and effects that are easy to locate;
+- behavior close to its trigger;
+- a single Ruby source file as a starting point;
+- fast execution and feedback;
+- code that AI can generate, explain, and repair;
+- tests based on what a person sees and does.
+
+After reading an application, a Ruby developer should be able to answer:
+
+1. What state does this application have?
+2. What does it display?
+3. What can the user do?
+4. What does each action change?
+5. Does it use files, the network, or storage?
+
+The current version is not intended to provide:
+
+- complete Shoes compatibility;
+- Ruby inside WebAssembly;
+- static deployable applications;
+- packaged desktop applications;
+- authentication;
+- remote storage;
+- integrated AI;
+- a large component or widget catalog;
+- canvas graphics or animation;
+- operation as a public multi-instance server.
+
+These capabilities can come later if real applications demonstrate a need for
+them.
+
+## Guiding principle
+
+> Complexity should live in the runtime so the application can remain small,
+> but never at the cost of hiding what the application does.
+
+Sandals succeeds when running a tool is simple and reading it feels more like
+understanding a small Ruby program than studying a framework.
+
+## License
+
+Sandals is available under the MIT License. See [`LICENSE`](LICENSE).

data/bin/sandals

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "sandals/cli"
+
+exit Sandals::CLI.start(ARGV)

data/lib/sandals/action_error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Sandals
+  class ActionError < StandardError
+    attr_reader :control, :original_error
+
+    def initialize(control, original_error)
+      @control = control
+      @original_error = original_error
+      super(original_error.message)
+    end
+
+    def action_name
+      return control.content if control.respond_to?(:content)
+
+      control.label
+    end
+
+    def location
+      locations = original_error.backtrace_locations || []
+      relevant_location = locations.find do |candidate|
+        !candidate.absolute_path.to_s.include?("/lib/sandals/")
+      end || locations.first
+      return "Location unavailable" unless relevant_location
+
+      path = relevant_location.absolute_path || relevant_location.path
+      path = path.delete_prefix("#{Dir.pwd}/")
+      "#{path}:#{relevant_location.lineno}"
+    end
+  end
+
+  module Actionable
+    private
+
+    def execute_action(*arguments)
+      @action&.call(*arguments)
+    rescue StandardError => error
+      raise ActionError.new(self, error), cause: error
+    end
+  end
+end