sandals 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 729bdd148836e2e4876915282f45c5dfb13e5ac040a45ab973a40824d4a02e09
-  data.tar.gz: b4ce94253c0bb8d5a8e7026e2c8dc5f873d748ee572756a98b240ff02e3a1f64
+  metadata.gz: 98c7f9a7ec9e5802a3ba038d5dfa807c3c93169ba1a3722d20c59efdf807a8cd
+  data.tar.gz: 644f49cd97d3002639c261034af166c485bd90e8947def34a2bcb219568f7f0a
 SHA512:
-  metadata.gz: 1298a4d2d07e5ff4d0a09dbc446fa2f32858a043f9ea68bcd76c0be4543aceaa0292e4f469bde1048ce63d4932eee26da0eae88a715f9dffd5a7328832ec8fbf
-  data.tar.gz: e09f3194ff8c72a2c0dbab9f00f73ea7916deaca101427c617b6c5d04a307c50a95563805a2094a895288a7ae6874753f5cf45d61039b4435e216cdaabf5a9c5
+  metadata.gz: 2298067696337102444a3c32fc6414a1d498ab1fae70967c1ba40bc45fc83e55c76cfe5010fbad45139a663514b97ea1d4e645c1a5a487aff46f11fdfc35f93e
+  data.tar.gz: 86458ee36df1a77367e726a309f584565e90932c745e9c4594f9d61fbdb11685b8b440455bb575b4020e08e0091c1976f6752182d13be58040bcf48c9d0bc3c1

data/README.md

@@ -75,6 +75,28 @@ ruby hello_test.rb
 The test fills in `"Your name"` and verifies that the greeting appears. It uses
 Minitest, which is installed with Sandals.
 
+## Startup errors
+
+Sandals reports startup failures with the error type, application file, and
+line number instead of printing an internal framework backtrace:
+
+```text
+sandals: SyntaxError at app.rb:12
+app.rb:12: syntax error, unexpected end-of-input
+```
+
+Missing dependencies are reported in the same way:
+
+```text
+sandals: LoadError at app.rb:1
+cannot load such file -- sqlite3
+Add the missing dependency to the app and try again.
+```
+
+Sandals also evaluates the initial view before opening the server, so an
+exception during the first render points to the relevant line in the
+application.
+
 ## The experience
 
 An application should normally fit in a single file:
@@ -141,6 +163,55 @@ end
 `para` renders as a paragraph and can combine strings with `strong` for
 important content and `em` for emphasis.
 
+## Styling
+
+Sandals has a neutral default appearance, but an application can establish its
+own personality in Ruby. Use `style` outside the view to configure defaults:
+
+```ruby
+Sandals.app title: "Notes" do
+  style :app, background: "#fffaf3", color: "#292524"
+  style :stack, gap: 18
+  style :title, color: "#9a3412", size: 42
+  style :button,
+    background: "#ea580c",
+    color: "white",
+    border: "1px solid #c2410c",
+    radius: 10
+
+  view do
+    stack padding: 24 do
+      title "Notes"
+      para "A small app with its own visual character."
+      button "Delete", background: "#b91c1c"
+    end
+  end
+end
+```
+
+An option on an individual element overrides the application default. The
+resolution order is:
+
+```text
+Sandals defaults → application defaults → element options
+```
+
+The first styling API supports `app`, `stack`, `flow`, `title`, `subtitle`,
+`para`, and `button`. Available properties are `background`, `color`, `border`,
+`radius`, `size`, `weight`, `width`, `padding`, `margin`, `gap`, and `align`.
+Numeric dimensions use pixels, while strings can include their own CSS unit:
+
+```ruby
+style :title, size: "2.5rem"
+stack width: "100%", gap: 16 do
+  # ...
+end
+```
+
+Unknown elements and properties raise an error instead of silently producing
+invalid styles. `form` remains semantic: use a surrounding `stack` or `flow`
+to control its composition.
+
 `image` displays an image from a path or URL. Alternative text is optional, but
 should describe the image whenever it carries meaningful content:
 
@@ -527,6 +598,16 @@ 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`.
 
+## Connection recovery
+
+If the local Sandals process stops while the application is open, the browser
+shows a persistent “Connection lost” message and releases any pending buttons.
+It retries the connection once per second while the tab is visible.
+
+When Sandals is available again, the browser reloads the application
+automatically. Events entered while disconnected are discarded because the
+restarted process creates a new Ruby session.
+
 ## Mental model
 
 ```text

data/lib/sandals/action_error.rb

@@ -17,15 +17,7 @@ module Sandals
     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}"
+      ErrorDetails.for(original_error).fetch(:location)
     end
   end
 

data/lib/sandals/application.rb

@@ -2,12 +2,13 @@
 
 module Sandals
   class Application
-    attr_reader :refresh_interval
+    attr_reader :refresh_interval, :styles
 
     def initialize(title:, &definition)
       @title = title
       @definition = definition
       @refresh_interval = nil
+      @styles = {}
       @view_definition = nil
       @snapshots = SnapshotHistory.new
       instance_eval(&definition)
@@ -32,18 +33,24 @@ module Sandals
       @refresh_interval = interval
     end
 
+    def style(element, **properties)
+      element = Style.validate_element!(element)
+      normalized = Style.normalize(element, properties)
+      @styles[element] = (@styles.fetch(element, {})).merge(normalized).freeze
+    end
+
     def select(label, **options, &action)
       @current_view.select(label, **options, &action)
     end
 
-    def title(*arguments)
-      return @title if arguments.empty?
+    def title(*arguments, **options)
+      return @title if arguments.empty? && options.empty?
 
-      @current_view.title(*arguments)
+      @current_view.title(*arguments, **options)
     end
 
     def render_view
-      @current_view = View.new
+      @current_view = View.new(styles:)
       instance_eval(&view)
       @current_view
     ensure

data/lib/sandals/cli.rb

@@ -5,6 +5,16 @@ require_relative "../sandals"
 
 module Sandals
   class CLI
+    class InitialAppError < StandardError
+      attr_reader :original_error, :path
+
+      def initialize(original_error, path)
+        @original_error = original_error
+        @path = path
+        super(original_error.message)
+      end
+    end
+
     def self.start(arguments)
       new(arguments).run
     end
@@ -20,11 +30,13 @@ module Sandals
       when "new" then new_app
       else usage
       end
-    rescue Interrupt
-      0
+    rescue InitialAppError => error
+      report_initial_app_error(error)
     rescue StandardError => error
       warn "sandals: #{error.message}"
       1
+    rescue Interrupt
+      0
     end
 
     private
@@ -74,7 +86,7 @@ module Sandals
       parser.parse!(@arguments)
 
       path = resolve_app(@arguments.shift || "app")
-      application = Sandals.load(path)
+      application = load_initial_application(path)
       server = Server.new(application, port: options[:port], reload_path: path)
 
       trap("INT") { server.stop }
@@ -85,6 +97,25 @@ module Sandals
       0
     end
 
+    def load_initial_application(path)
+      application = Sandals.load(path)
+      application.render(development_reload: true)
+      application
+    rescue SyntaxError, LoadError, StandardError => error
+      raise InitialAppError.new(error, File.expand_path(path))
+    end
+
+    def report_initial_app_error(error)
+      original = error.original_error
+      details = ErrorDetails.for(original, fallback_path: error.path)
+      warn "sandals: #{details.fetch(:class)} at #{details.fetch(:location)}"
+      warn details.fetch(:message)
+      if original.is_a?(LoadError)
+        warn "Add the missing dependency to the app and try again."
+      end
+      1
+    end
+
     def resolve_app(name)
       candidates = [name]
       candidates << "#{name}.rb" unless name.end_with?(".rb")

data/lib/sandals/code_reloader.rb

@@ -2,9 +2,7 @@
 
 module Sandals
   class CodeReloader
-    ANSI_ESCAPE = /\e\[[0-9;]*m/
-
-    Result = Data.define(:version, :application, :error, :changed)
+    Result = Struct.new(:version, :application, :error, :changed)
 
     attr_reader :path
 
@@ -46,35 +44,7 @@ module Sandals
     end
 
     def error_details(error)
-      {
-        class: error.class.to_s,
-        message: clean_message(error),
-        location: error_location(error)
-      }
-    end
-
-    def error_location(error)
-      syntax_location =
-        clean_message(error).lines.first&.match(/\A(.+?):(\d+):/) if
-          error.is_a?(SyntaxError)
-      if syntax_location
-        source_path = syntax_location[1].delete_prefix("#{Dir.pwd}/")
-        return "#{source_path}:#{syntax_location[2]}"
-      end
-
-      locations = error.backtrace_locations || []
-      location = locations.find do |candidate|
-        !candidate.absolute_path.to_s.include?("/lib/sandals/")
-      end || locations.first
-      return path unless location
-
-      source_path = location.absolute_path || location.path
-      source_path = source_path.delete_prefix("#{Dir.pwd}/")
-      "#{source_path}:#{location.lineno}"
-    end
-
-    def clean_message(error)
-      error.message.gsub(ANSI_ESCAPE, "")
+      ErrorDetails.for(error, fallback_path: path)
     end
   end
 end

data/lib/sandals/error_details.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Sandals
+  class ErrorDetails
+    ANSI_ESCAPE = /\e\[[0-9;]*m/
+
+    def self.for(error, fallback_path: nil)
+      new(error, fallback_path:).to_h
+    end
+
+    def initialize(error, fallback_path:)
+      @error = error
+      @fallback_path = fallback_path
+    end
+
+    def to_h
+      {
+        class: @error.class.to_s,
+        message: clean_message,
+        location: error_location
+      }
+    end
+
+    private
+
+    def error_location
+      path, line = syntax_location || backtrace_location
+      return @fallback_path || "Location unavailable" unless path
+
+      relative_location(path, line)
+    end
+
+    def syntax_location
+      return unless @error.is_a?(SyntaxError)
+
+      line = clean_message.lines.first&.[](/:(\d+):/, 1)
+      [@error.path || @fallback_path, line] if line
+    end
+
+    def backtrace_location
+      locations = @error.backtrace_locations || []
+      location =
+        locations.find { |candidate| same_path?(candidate, @fallback_path) } ||
+        locations.find { |candidate| !sandals_path?(candidate) } ||
+        locations.first
+
+      [location&.absolute_path || location&.path, location&.lineno]
+    end
+
+    def same_path?(location, path)
+      path && File.expand_path(location.absolute_path || location.path) == File.expand_path(path)
+    end
+
+    def sandals_path?(location)
+      location.absolute_path.to_s.include?("/lib/sandals/")
+    end
+
+    def relative_location(path, line)
+      source_path = path.delete_prefix("#{Dir.pwd}/")
+      "#{source_path}:#{line}"
+    end
+
+    def clean_message
+      @error.message.gsub(ANSI_ESCAPE, "").strip
+    end
+  end
+end

data/lib/sandals/html_renderer.rb

@@ -10,57 +10,112 @@ module Sandals
     DEFAULT_STYLES = <<~CSS
       :root {
         color-scheme: light;
+        --color-canvas: #f7f6f2;
+        --color-surface: #ffffff;
+        --color-surface-subtle: #efede7;
+        --color-text: #242320;
+        --color-muted: #6b6963;
+        --color-border: #d8d5cc;
+        --color-border-strong: #aaa69b;
+        --color-accent: #6558d3;
+        --color-accent-soft: #eeecff;
+        --color-danger: #a9362a;
+        --color-danger-soft: #fff0ed;
+        --color-success: #187451;
+        --color-success-soft: #eaf8f1;
+        --radius-control: 0.5rem;
+        --radius-panel: 0.75rem;
+        --shadow-focus: 0 0 0 3px rgb(101 88 211 / 20%);
+        --space-1: 0.375rem;
+        --space-2: 0.75rem;
+        --space-3: 1rem;
+        --space-4: 1.5rem;
+        --space-5: 2rem;
+        --space-6: 3rem;
         font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
-        background: #f7f7f5;
-        color: #20201e;
+        background: var(--color-canvas);
+        color: var(--color-text);
+      }
+
+      *,
+      *::before,
+      *::after {
+        box-sizing: border-box;
       }
 
       body {
         margin: 0;
+        min-width: 0;
+        background: var(--color-canvas);
+        font-size: 1rem;
+        line-height: 1.5;
       }
 
       main {
-        box-sizing: border-box;
         width: min(100%, 48rem);
         margin: 0 auto;
-        padding: 3rem 1.5rem;
+        padding: clamp(var(--space-4), 6vw, var(--space-6));
       }
 
       h1 {
         margin: 0;
-        font-size: clamp(2rem, 7vw, 4rem);
-        letter-spacing: -0.04em;
+        max-width: 18ch;
+        font-size: clamp(2.25rem, 7vw, 3.75rem);
+        line-height: 0.98;
+        letter-spacing: -0.045em;
+        text-wrap: balance;
+        overflow-wrap: anywhere;
+      }
+
+      h2 {
+        margin: 0;
+        font-size: clamp(1.35rem, 4vw, 1.75rem);
+        line-height: 1.15;
+        letter-spacing: -0.02em;
+        text-wrap: balance;
       }
 
       p {
         margin: 0;
-        line-height: 1.6;
+        max-width: 68ch;
+        line-height: 1.65;
+        overflow-wrap: anywhere;
+      }
+
+      .error {
+        padding: var(--space-2) var(--space-3);
+        border: 1px solid #efb2aa;
+        border-radius: var(--radius-control);
+        background: var(--color-danger-soft);
+        color: var(--color-danger);
       }
 
-      .error,
       .field-error {
-        color: #b42318;
+        color: var(--color-danger);
       }
 
       .notice {
-        color: #067647;
+        padding: var(--space-2) var(--space-3);
+        border: 1px solid #a9dec6;
+        border-radius: var(--radius-control);
+        background: var(--color-success-soft);
+        color: var(--color-success);
       }
 
       .runtime-errors {
-        box-sizing: border-box;
         width: min(100%, 48rem);
         margin: 0 auto;
-        padding: 1rem 1.5rem 0;
+        padding: var(--space-3) var(--space-4) 0;
       }
 
       .action-error {
         display: grid;
-        gap: 0.375rem;
-        padding: 1rem;
-        border: 1px solid #fda29b;
-        border-radius: 0.375rem;
-        background: #fef3f2;
-        color: #b42318;
+        gap: var(--space-1);
+        padding: var(--space-3);
+        border: 1px solid #efb2aa;
+        border-radius: var(--radius-control);
+        background: var(--color-danger-soft);
+        color: var(--color-danger);
       }
 
       .action-error code {
@@ -69,17 +124,34 @@ module Sandals
 
       .field-error {
         font-size: 0.875rem;
+        font-weight: 450;
       }
 
       img {
         display: block;
         max-width: 100%;
         height: auto;
+        border-radius: var(--radius-panel);
       }
 
       a {
-        color: #175cd3;
+        color: var(--color-accent);
+        font-weight: 550;
         text-underline-offset: 0.15em;
+        text-decoration-thickness: 0.08em;
+      }
+
+      a:hover {
+        text-decoration-thickness: 0.14em;
+      }
+
+      a:focus-visible,
+      button:focus-visible,
+      input:focus-visible,
+      textarea:focus-visible,
+      select:focus-visible {
+        outline: 2px solid var(--color-accent);
+        outline-offset: 2px;
       }
 
       .text-field,
@@ -88,7 +160,9 @@ module Sandals
       .file-field,
       .select {
         display: grid;
-        gap: 0.375rem;
+        min-width: 0;
+        gap: var(--space-1);
+        font-weight: 600;
       }
 
       .text-field input,
@@ -96,20 +170,40 @@ module Sandals
       .text-area textarea,
       .file-field input,
       .select select {
-        box-sizing: border-box;
         width: 100%;
-        padding: 0.625rem 0.75rem;
-        border: 1px solid #c8c8c3;
-        border-radius: 0.375rem;
-        background: white;
+        min-height: 2.75rem;
+        padding: 0.625rem var(--space-2);
+        border: 1px solid var(--color-border-strong);
+        border-radius: var(--radius-control);
+        background: var(--color-surface);
         color: inherit;
         font: inherit;
+        font-weight: 400;
+        transition: border-color 120ms ease, box-shadow 120ms ease;
+      }
+
+      .text-field input:hover,
+      .number-field input:hover,
+      .text-area textarea:hover,
+      .file-field input:hover,
+      .select select:hover {
+        border-color: var(--color-text);
+      }
+
+      .text-field input:focus,
+      .number-field input:focus,
+      .text-area textarea:focus,
+      .file-field input:focus,
+      .select select:focus {
+        border-color: var(--color-accent);
+        box-shadow: var(--shadow-focus);
       }
 
       input[aria-invalid="true"],
       textarea[aria-invalid="true"],
       select[aria-invalid="true"] {
-        border-color: #b42318;
+        border-color: var(--color-danger);
+        background: var(--color-danger-soft);
       }
 
       .text-area textarea {
@@ -120,88 +214,139 @@ module Sandals
       .checkbox {
         display: flex;
         align-items: center;
-        gap: 0.5rem;
+        min-width: 0;
+        gap: var(--space-2);
+        font-weight: 550;
       }
 
       .checkbox input {
-        width: 1rem;
-        height: 1rem;
+        width: 1.125rem;
+        height: 1.125rem;
         margin: 0;
+        accent-color: var(--color-accent);
       }
 
       .radio {
         display: grid;
-        gap: 0.5rem;
+        min-width: 0;
+        gap: var(--space-2);
         margin: 0;
         padding: 0;
         border: 0;
       }
 
       .radio legend {
-        margin-bottom: 0.375rem;
+        margin-bottom: var(--space-1);
+        font-weight: 600;
       }
 
       .radio label {
         display: flex;
         align-items: center;
-        gap: 0.5rem;
+        gap: var(--space-2);
       }
 
       .radio input {
         margin: 0;
+        accent-color: var(--color-accent);
+      }
+
+      .table-scroll {
+        max-width: 100%;
+        overflow-x: auto;
+        border: 1px solid var(--color-border);
+        border-radius: var(--radius-panel);
+        background: var(--color-surface);
+        overscroll-behavior-inline: contain;
       }
 
       table {
         width: 100%;
+        min-width: 36rem;
         border-collapse: collapse;
-        background: white;
+        background: var(--color-surface);
       }
 
       th,
       td {
-        padding: 0.625rem 0.75rem;
-        border: 1px solid #deded9;
+        padding: var(--space-2) var(--space-3);
+        border-bottom: 1px solid var(--color-border);
         text-align: left;
         vertical-align: top;
+        overflow-wrap: anywhere;
       }
 
       th {
-        background: #f0f0ed;
+        background: var(--color-surface-subtle);
         font-weight: 600;
       }
 
+      tbody tr:last-child td {
+        border-bottom: 0;
+      }
+
       button {
-        padding: 0.625rem 1rem;
-        border: 0;
-        border-radius: 0.375rem;
-        background: #20201e;
+        min-height: 2.75rem;
+        padding: 0.625rem var(--space-3);
+        border: 1px solid var(--color-text);
+        border-radius: var(--radius-control);
+        background: var(--color-text);
         color: white;
         font: inherit;
+        font-weight: 650;
         cursor: pointer;
+        transition: transform 100ms ease, opacity 100ms ease, background 100ms ease;
+      }
+
+      button:hover:not(:disabled) {
+        background: #3a3935;
+      }
+
+      button:active:not(:disabled) {
+        transform: translateY(1px);
       }
 
       button[aria-busy="true"] {
         cursor: wait;
-        opacity: 0.7;
+        opacity: 0.65;
       }
 
       .stack {
         display: flex;
         flex-direction: column;
-        gap: 1rem;
+        min-width: 0;
+        gap: var(--space-3);
+      }
+
+      .stack > * {
+        min-width: 0;
+      }
+
+      .stack > h2 {
+        margin-top: var(--space-4);
       }
 
       .flow {
         display: flex;
         flex-flow: row wrap;
         align-items: center;
-        gap: 1rem;
+        min-width: 0;
+        gap: var(--space-2);
       }
 
       .form {
-        display: flex;
-        flex-direction: column;
-        gap: 1rem;
+        display: contents;
+      }
+
+      @media (max-width: 32rem) {
+        main {
+          padding-inline: var(--space-3);
+        }
+
+        .runtime-errors {
+          padding-inline: var(--space-3);
+        }
+
       }
     CSS
 
@@ -211,7 +356,8 @@ module Sandals
         render_children(view),
         revision:,
         refresh_interval: application.refresh_interval,
-        development_reload:
+        development_reload:,
+        app_styles: application.styles.fetch(:app, {})
       )
     end
 
@@ -247,11 +393,11 @@ module Sandals
       when String
         escape(element)
       when Title
-        "<h1>#{escape(element.content)}</h1>"
+        "<h1#{style_attribute(:title, element)}>#{escape(element.content)}</h1>"
       when Subtitle
-        "<h2>#{escape(element.content)}</h2>"
+        "<h2#{style_attribute(:subtitle, element)}>#{escape(element.content)}</h2>"
       when Para
-        "<p>#{element.parts.map { |part| render_element(part) }.join}</p>"
+        "<p#{style_attribute(:para, element)}>#{element.parts.map { |part| render_element(part) }.join}</p>"
       when Error
         %(<p class="error" role="alert">#{escape(element.content)}</p>)
       when Notice
@@ -288,7 +434,7 @@ module Sandals
       when Submit
         %(<button type="submit" data-sandals-target="#{escape(element.id)}">#{escape(element.content)}</button>)
       when Button
-        %(<button type="button" data-sandals-target="#{escape(element.id)}">#{escape(element.content)}</button>)
+        %(<button type="button" data-sandals-target="#{escape(element.id)}"#{style_attribute(:button, element)}>#{escape(element.content)}</button>)
       when Strong
         "<strong>#{escape(element.content)}</strong>"
       when Emphasis
@@ -306,7 +452,7 @@ module Sandals
 
     def container(class_name, element)
       content = element.children.map { |child| render_element(child) }.join
-      %(<div class="#{class_name}">#{content}</div>)
+      %(<div class="#{class_name}"#{style_attribute(class_name.to_sym, element)}>#{content}</div>)
     end
 
     def form(element)
@@ -322,7 +468,7 @@ module Sandals
         cells = row.map { |cell| "<td>#{render_element(cell)}</td>" }.join
         "<tr>#{cells}</tr>"
       end.join
-      "<table><thead><tr>#{headers}</tr></thead><tbody>#{rows}</tbody></table>"
+      %(<div class="table-scroll"><table><thead><tr>#{headers}</tr></thead><tbody>#{rows}</tbody></table></div>)
     end
 
     def validation_attributes(element)
@@ -342,7 +488,8 @@ module Sandals
       content,
       revision:,
       refresh_interval:,
-      development_reload:
+      development_reload:,
+      app_styles:
     )
       refresh_attribute =
         if refresh_interval
@@ -363,14 +510,22 @@ module Sandals
             <script src="#{TURBO_URL}"></script>
             <script>#{client_script}</script>
           </head>
-          <body>
+          <body#{style_attribute(:app, app_styles.slice(:background, :color))}>
+            <div id="sandals-connection-status" class="runtime-errors" aria-live="assertive"></div>
             <div id="sandals-errors" class="runtime-errors" aria-live="assertive"></div>
-            <main id="sandals-view" data-sandals-revision="#{revision}"#{refresh_attribute}#{reload_attribute}>#{content}</main>
+            <main id="sandals-view" data-sandals-revision="#{revision}"#{refresh_attribute}#{reload_attribute}#{style_attribute(:app, app_styles)}>#{content}</main>
           </body>
         </html>
       HTML
     end
 
+    def style_attribute(element, styled)
+      properties = styled.respond_to?(:styles) ? styled.styles : styled
+      return "" if properties.empty?
+
+      %( style="#{escape(Style.inline(element, properties))}")
+    end
+
     def client_script
       <<~JAVASCRIPT
         document.addEventListener("DOMContentLoaded", () => {
@@ -386,6 +541,8 @@ module Sandals
           let codeVersion
           let checkingCode = false
           let refreshTimer
+          let reconnectTimer
+          let disconnected = false
           const pending = []
           const pendingButtons = new Map()
 
@@ -412,6 +569,65 @@ module Sandals
             }
           }
 
+          function releaseAllPendingButtons() {
+            for (const button of pendingButtons.values()) {
+              button.disabled = false
+              button.removeAttribute("aria-busy")
+              delete button.dataset.sandalsPending
+            }
+            pendingButtons.clear()
+          }
+
+          function showConnectionLost() {
+            const region = document.querySelector("#sandals-connection-status")
+            const section = document.createElement("section")
+            const title = document.createElement("strong")
+            const message = document.createElement("p")
+
+            section.className = "action-error"
+            section.setAttribute("role", "alert")
+            title.textContent = "Connection lost"
+            message.textContent = "Waiting for Sandals to reconnect…"
+            section.append(title, message)
+            region.replaceChildren(section)
+          }
+
+          function connectionLost() {
+            if (disconnected) return
+
+            disconnected = true
+            pending.length = 0
+            clearTimeout(refreshTimer)
+            releaseAllPendingButtons()
+            showConnectionLost()
+            scheduleReconnect()
+          }
+
+          function handleRequestError(error) {
+            if (error instanceof TypeError) {
+              connectionLost()
+            } else {
+              console.error(error)
+            }
+          }
+
+          function scheduleReconnect() {
+            clearTimeout(reconnectTimer)
+            reconnectTimer = setTimeout(checkConnection, 1000)
+          }
+
+          async function checkConnection() {
+            if (!disconnected) return
+            if (document.hidden) return
+
+            try {
+              await fetch("/", { cache: "no-store" })
+              window.location.reload()
+            } catch (error) {
+              scheduleReconnect()
+            }
+          }
+
           function showCodeError(error) {
             const region = document.querySelector("#sandals-errors")
             const section = document.createElement("section")
@@ -429,7 +645,7 @@ module Sandals
           }
 
           async function checkForCodeChanges() {
-            if (!developmentReload || document.hidden || checkingCode) return
+            if (!developmentReload || document.hidden || checkingCode || disconnected) return
 
             checkingCode = true
             try {
@@ -447,12 +663,16 @@ module Sandals
               }
 
               if (result.error) showCodeError(result.error)
+            } catch (error) {
+              handleRequestError(error)
             } finally {
               checkingCode = false
             }
           }
 
           function enqueue(message) {
+            if (disconnected) return
+
             scheduleRefresh()
             const last = pending.at(-1)
 
@@ -472,14 +692,14 @@ module Sandals
 
           function scheduleRefresh() {
             clearTimeout(refreshTimer)
-            if (!refreshInterval || document.hidden) return
+            if (!refreshInterval || document.hidden || disconnected) return
 
             refreshTimer = setTimeout(refreshView, refreshInterval * 1000)
           }
 
           async function refreshView() {
             clearTimeout(refreshTimer)
-            if (!refreshInterval || document.hidden) return
+            if (!refreshInterval || document.hidden || disconnected) return
             if (active || pending.length > 0) {
               scheduleRefresh()
               return
@@ -513,6 +733,8 @@ module Sandals
               } else if (!response.ok) {
                 throw new Error(body)
               }
+            } catch (error) {
+              handleRequestError(error)
             } finally {
               active = false
               drain()
@@ -521,7 +743,7 @@ module Sandals
           }
 
           async function drain() {
-            if (active || pending.length === 0) return
+            if (active || disconnected || pending.length === 0) return
 
             active = true
             const batchRevision = pending[0].revision
@@ -578,6 +800,8 @@ module Sandals
               } else if (!response.ok) {
                 throw new Error(body)
               }
+            } catch (error) {
+              handleRequestError(error)
             } finally {
               releasePendingButtons(events)
               active = false
@@ -616,6 +840,7 @@ module Sandals
             const button = event.target.closest("button[data-sandals-target]")
             if (!button) return
             if (button.type === "submit") return
+            if (disconnected) return
             if (button.disabled || button.dataset.sandalsPending) return
 
             markButtonPending(button)
@@ -652,6 +877,7 @@ module Sandals
               event.submitter ||
               form.querySelector('button[type="submit"][data-sandals-target]')
             if (!button) return
+            if (disconnected) return
             if (button.disabled || button.dataset.sandalsPending) return
 
             markButtonPending(button)
@@ -664,6 +890,10 @@ module Sandals
           document.addEventListener("visibilitychange", () => {
             clearTimeout(refreshTimer)
             if (!document.hidden) {
+              if (disconnected) {
+                checkConnection()
+                return
+              }
               refreshView()
               checkForCodeChanges()
             }

data/lib/sandals/style.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Sandals
+  class Style
+    ELEMENTS = %i[app stack flow title subtitle para button].freeze
+    PROPERTIES = %i[
+      background color border radius size weight width padding margin gap align
+    ].freeze
+    DIMENSIONS = %i[radius size width padding margin gap].freeze
+
+    CSS_PROPERTIES = {
+      background: "background",
+      color: "color",
+      border: "border",
+      radius: "border-radius",
+      size: "font-size",
+      weight: "font-weight",
+      width: "width",
+      padding: "padding",
+      margin: "margin",
+      gap: "gap"
+    }.freeze
+
+    def self.validate_element!(element)
+      name = element.to_sym
+      return name if ELEMENTS.include?(name)
+
+      raise ArgumentError,
+        "unknown style element: #{element.inspect}; expected one of #{ELEMENTS.join(", ")}"
+    end
+
+    def self.normalize(element, properties)
+      element = validate_element!(element)
+      properties.to_h do |name, value|
+        name = name.to_sym
+        unless PROPERTIES.include?(name)
+          raise ArgumentError, "unknown style property for #{element}: #{name}"
+        end
+
+        [name, normalize_value(name, value)]
+      end.freeze
+    end
+
+    def self.inline(element, properties)
+      properties.map do |name, value|
+        property = name == :align ? alignment_property(element) : CSS_PROPERTIES.fetch(name)
+        "#{property}: #{value}"
+      end.join("; ")
+    end
+
+    def self.normalize_value(name, value)
+      if value.is_a?(Numeric)
+        return value.to_s unless DIMENSIONS.include?(name)
+
+        return value.zero? ? "0" : "#{value}px"
+      end
+
+      value = value.to_s
+      if value.empty? || value.match?(/[;{}<>]/)
+        raise ArgumentError, "invalid value for style property #{name}: #{value.inspect}"
+      end
+
+      value
+    end
+    private_class_method :normalize_value
+
+    def self.alignment_property(element)
+      %i[stack flow].include?(element) ? "align-items" : "text-align"
+    end
+    private_class_method :alignment_property
+  end
+
+  module Styled
+    attr_reader :styles
+
+    private
+
+    def initialize_styles(styles)
+      @styles = styles.freeze
+    end
+  end
+end

data/lib/sandals/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sandals
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/sandals/view.rb

@@ -8,22 +8,23 @@ module Sandals
 
     attr_reader :children
 
-    def initialize
+    def initialize(styles: {})
       @children = []
       @containers = [self]
       @next_control_id = 0
+      @styles = styles
     end
 
-    def title(content)
-      add Title.new(content)
+    def title(content, **styles)
+      add Title.new(content, styles: styles_for(:title, styles))
     end
 
-    def subtitle(content)
-      add Subtitle.new(content)
+    def subtitle(content, **styles)
+      add Subtitle.new(content, styles: styles_for(:subtitle, styles))
     end
 
-    def para(*parts)
-      add Para.new(parts)
+    def para(*parts, **styles)
+      add Para.new(parts, styles: styles_for(:para, styles))
     end
 
     def error(content)
@@ -136,8 +137,13 @@ module Sandals
       add FileField.new(control_id("file-field"), label, error:, action:)
     end
 
-    def button(content, &action)
-      add Button.new(control_id("button"), content, action:)
+    def button(content, **styles, &action)
+      add Button.new(
+        control_id("button"),
+        content,
+        action:,
+        styles: styles_for(:button, styles)
+      )
     end
 
     def submit(content, &action)
@@ -156,12 +162,12 @@ module Sandals
       Emphasis.new(content)
     end
 
-    def stack(&block)
-      container Stack.new, &block
+    def stack(**styles, &block)
+      container Stack.new(styles: styles_for(:stack, styles)), &block
     end
 
-    def flow(&block)
-      container Flow.new, &block
+    def flow(**styles, &block)
+      container Flow.new(styles: styles_for(:flow, styles)), &block
     end
 
     def form(&block)
@@ -199,13 +205,20 @@ module Sandals
         model:, bind:, value:, error:, action:, default:
       ).deconstruct
     end
+
+    def styles_for(element, local_styles)
+      @styles.fetch(element, {}).merge(Style.normalize(element, local_styles))
+    end
   end
 
   class Container
+    include Styled
+
     attr_reader :children
 
-    def initialize
+    def initialize(styles: {})
       @children = []
+      initialize_styles(styles)
     end
   end
 
@@ -214,26 +227,35 @@ module Sandals
   class Form < Container; end
 
   class Title
+    include Styled
+
     attr_reader :content
 
-    def initialize(content)
+    def initialize(content, styles: {})
       @content = content.to_s
+      initialize_styles(styles)
     end
   end
 
   class Subtitle
+    include Styled
+
     attr_reader :content
 
-    def initialize(content)
+    def initialize(content, styles: {})
       @content = content.to_s
+      initialize_styles(styles)
     end
   end
 
   class Para
+    include Styled
+
     attr_reader :parts
 
-    def initialize(parts)
+    def initialize(parts, styles: {})
       @parts = parts
+      initialize_styles(styles)
     end
   end
 
@@ -475,13 +497,15 @@ module Sandals
 
   class Button
     include Actionable
+    include Styled
 
     attr_reader :id, :content
 
-    def initialize(id, content, action:)
+    def initialize(id, content, action:, styles: {})
       @id = id
       @content = content.to_s
       @action = action
+      initialize_styles(styles)
     end
 
     def activate

data/lib/sandals.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "sandals/version"
+require_relative "sandals/error_details"
 require_relative "sandals/binding_resolver"
 require_relative "sandals/action_error"
 require_relative "sandals/uploaded_file"
+require_relative "sandals/style"
 require_relative "sandals/view"
 require_relative "sandals/html_renderer"
 require_relative "sandals/snapshot_history"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sandals
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Benito Serna
@@ -56,14 +56,17 @@ files:
 - lib/sandals/binding_resolver.rb
 - lib/sandals/cli.rb
 - lib/sandals/code_reloader.rb
+- lib/sandals/error_details.rb
 - lib/sandals/event_dispatcher.rb
 - lib/sandals/html_renderer.rb
 - lib/sandals/server.rb
 - lib/sandals/snapshot_history.rb
+- lib/sandals/style.rb
 - lib/sandals/test_session.rb
 - lib/sandals/uploaded_file.rb
 - lib/sandals/version.rb
 - lib/sandals/view.rb
+homepage: https://rubygems.org/gems/sandals
 licenses:
 - MIT
 metadata: