lacci 0.2.1

data/lib/scarpe/cats_cradle.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "scarpe/unit_test_helpers"
+
+require "fiber"
+
+# "Cat's Cradle" is a children's game where they interlace string between
+# their fingers to make beautiful complicated shapes. The interlacing
+# of fibers made it a good name for a prototype.
+
+# An attempt at an experimental Fiber-based testing system to deal with
+# Shoes, Display and JS all at the same time.
+#
+# In general, we'll use Fiber.transfer to bounce control back and forth
+# between the evented implementations (e.g. waiting for redraw) that
+# need to return control to Webview, and the procedural test flows
+# that look far better if we don't do that explicitly.
+#
+# Ruby Fiber basic docs: https://ruby-doc.org/core-3.0.0/Fiber.html
+#
+module Scarpe::Test
+  # We'd like something we can call Shoes widget methods on, such as para.replace.
+  # But we'd also like to be able to grab the corresponding display widget and
+  # call some of *those* methods.
+  class CCProxy
+    attr_reader :display
+
+    def initialize(obj)
+      @obj = obj
+      # TODO: how to do this with Webview relay? Proxy object to send a message, maybe?
+      @display = ::Shoes::DisplayService.display_service.query_display_widget_for(obj.linkable_id)
+    end
+
+    def method_missing(method, ...)
+      if @obj.respond_to?(method)
+        self.singleton_class.define_method(method) do |*args, **kwargs, &block|
+          @obj.send(method, *args, **kwargs, &block)
+        end
+        send(method, ...)
+      else
+        super # raise an exception
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @obj.respond_to_missing?(method_name, include_private)
+    end
+  end
+
+  # This class defines the CatsCradle DSL. It also holds a "bag of fibers"
+  # with promises for when they should next resume.
+  class CCInstance
+    include Scarpe::Log
+    include Scarpe::Test::Helpers
+
+    def self.instance
+      @instance ||= CCInstance.new
+    end
+
+    def initialize
+      log_init("CatsCradle")
+
+      @assertion_data = []
+      @assertions_passed = 0
+      @assertions_failed = []
+
+      @waiting_fibers = []
+      @event_promises = {}
+
+      @manager_fiber = Fiber.new do
+        loop do
+          # A fiber can run briefly and then exit. It can run and then block on an API call.
+          # These fibers return promises to indicate to CatsCradle when they can run again.
+          # A fiber that is no longer #alive? is assumed to be successfully finished.
+          @waiting_fibers.each do |fiber_data|
+            next unless fiber_data[:promise].fulfilled?
+
+            @log.debug("Resuming fiber with value #{fiber_data[:promise].returned_value.inspect}")
+            result = fiber_data[:fiber].transfer fiber_data[:promise].returned_value
+
+            # Dead fibers will be removed later, just leave it
+            next unless fiber_data[:fiber].alive?
+
+            case result
+            when ::Scarpe::Promise
+              fiber_data[:promise] = result
+            else
+              raise "Unexpected object returned from Fiber#transfer for still-living Fiber! #{result.inspect}"
+            end
+          end
+
+          # Throw out dead fibers or those that will never wake
+          @waiting_fibers.select! do |fiber_data|
+            fiber_data[:fiber].alive? && !fiber_data[:promise].rejected?
+          end
+
+          # Done with this iteration
+          Fiber.yield
+        end
+      end
+    end
+
+    # If we add "every" events, that's likely to complicate timing and event_promise handling.
+    EVENT_TYPES = [:next_heartbeat, :next_redraw]
+
+    # This needs to be called after the basic display service objects exist
+    # and we can find the control interface.
+    def event_init
+      return if @cc_init_done
+
+      @cc_init_done = true
+
+      @control_interface = ::Shoes::DisplayService.display_service.control_interface
+      @wrangler = @control_interface.wrangler
+
+      cc_instance = self # ControlInterface#on_event does an instance eval. We'll reset self with another.
+
+      @control_interface.on_event(:every_heartbeat) do
+        cc_instance.instance_eval do
+          p = @event_promises.delete(:next_heartbeat)
+          p&.fulfilled!
+
+          # Give every ready fiber a chance to run once.
+          @manager_fiber.resume
+        end
+      end
+
+      @control_interface.on_event(:every_redraw) do
+        cc_instance.instance_eval do
+          p = @event_promises.delete(:next_redraw)
+          p&.fulfilled!
+
+          # Give every ready fiber a chance to run once.
+          @manager_fiber.resume
+        end
+      end
+    end
+
+    def event_promise(event)
+      @event_promises[event] ||= ::Scarpe::Promise.new
+    end
+
+    def on_event(event, &block)
+      raise "Unknown event type: #{event.inspect}!" unless EVENT_TYPES.include?(event)
+
+      f = Fiber.new do
+        CCInstance.instance.instance_eval(&block)
+      end
+      @waiting_fibers << { promise: event_promise(event), fiber: f }
+    end
+
+    WIDGET_FINDERS = {
+      "alert" => ::Scarpe::Alert,
+      "button" => ::Scarpe::Button,
+      "edit_box" => ::Scarpe::EditBox,
+      "edit_line" => ::Scarpe::EditLine,
+      "flow" => ::Scarpe::Flow,
+      "image" => ::Scarpe::Image,
+      "list_box" => ::Scarpe::ListBox,
+      "para" => ::Scarpe::Para,
+      "shape" => ::Scarpe::Shape,
+      "stack" => ::Scarpe::Stack,
+      "star" => ::Scarpe::Star,
+    }
+    # What to do about TextWidgets? Link, code, em, strong?
+    # Also, wait, what's up with span? What *is* that?
+    Shoes::Widget.widget_classes.each do |widget_class|
+      finder_name = widget_class.dsl_name
+
+      define_method(finder_name) do |*args|
+        app = Shoes::App.instance
+
+        widgets = app.find_widgets_by(widget_class, *args)
+        raise "Found more than one #{finder_name} matching #{args.inspect}!" if widgets.size > 1
+        raise "Found no #{finder_name} matching #{args.inspect}!" if widgets.empty?
+
+        CCProxy.new(widgets[0])
+      end
+    end
+
+    def wait(promise)
+      raise("Must supply a promise to wait!") unless promise.is_a?(::Scarpe::Promise)
+
+      # Wait until this promise is complete before running again
+      @manager_fiber.transfer(promise)
+    end
+
+    # This returns a promise, which can be waited on using wait()
+    def fully_updated
+      @wrangler.promise_dom_fully_updated
+    end
+
+    def dom_html(timeout: 1.0)
+      query_js_value("document.getElementById('wrapper-wvroot').innerHTML", timeout:)
+    end
+
+    def query_js_value(js_code, timeout: 1.0)
+      js_promise = @wrangler.eval_js_async(js_code, timeout:)
+
+      # This promise will return the string, so we can just pass it to #transfer
+      @manager_fiber.transfer(js_promise)
+    end
+
+    def assert(value, msg = nil)
+      msg ||= "Assertion #{value ? "succeeded" : "failed"}"
+      @assertion_data << [value ? true : false, msg]
+      if value
+        @assertions_passed += 1
+      else
+        @assertions_failed << msg
+      end
+    end
+
+    def assert_equal(expected, actual, msg = nil)
+      msg ||= "Expected #{actual.inspect} to equal #{expected.inspect}!"
+      assert actual == expected, msg
+    end
+
+    def assertion_data_as_a_struct
+      {
+        still_pending: 0,
+        succeeded: @assertions_passed,
+        failed: @assertions_failed.size,
+        failures: @assertions_failed,
+      }
+    end
+
+    def test_metadata
+      {}
+    end
+
+    def test_finished
+      if !@assertions_failed.empty?
+        return_results(false, "Assertions failed", assertion_data_as_a_struct)
+      elsif @assertions_passed > 0
+        return_results(true, "All assertions passed", assertion_data_as_a_struct)
+      else
+        return_results(true, "Test finished successfully")
+      end
+      ::Shoes::DisplayService.dispatch_event("destroy", nil)
+    end
+  end
+
+  # This module is mixed into Shoes::App if we're running CC-based tests
+  module CatsCradle
+    def event_init
+      @cc_instance = CCInstance.instance
+      @cc_instance.event_init
+    end
+
+    def on_heartbeat(&block)
+      @cc_instance.on_event(:next_heartbeat, &block)
+    end
+  end
+end

data/lib/scarpe/colors.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+class Scarpe
+  module Colors
+    COLORS = {
+      aliceblue: [240, 248, 255],
+      antiquewhite: [250, 235, 215],
+      aqua: [0, 255, 255],
+      aquamarine: [127, 255, 212],
+      azure: [240, 255, 255],
+      beige: [245, 245, 220],
+      bisque: [255, 228, 196],
+      black: [0, 0, 0],
+      blanchedalmond: [255, 235, 205],
+      blue: [0, 0, 255],
+      blueviolet: [138, 43, 226],
+      brown: [165, 42, 42],
+      burlywood: [222, 184, 135],
+      cadetblue: [95, 158, 160],
+      chartreuse: [127, 255, 0],
+      chocolate: [210, 105, 30],
+      coral: [255, 127, 80],
+      cornflowerblue: [100, 149, 237],
+      cornsilk: [255, 248, 220],
+      crimson: [220, 20, 60],
+      cyan: [0, 255, 255],
+      darkblue: [0, 0, 139],
+      darkcyan: [0, 139, 139],
+      darkgoldenrod: [184, 134, 11],
+      darkgray: [169, 169, 169],
+      darkgreen: [0, 100, 0],
+      darkkhaki: [189, 183, 107],
+      darkmagenta: [139, 0, 139],
+      darkolivegreen: [85, 107, 47],
+      darkorange: [255, 140, 0],
+      darkorchid: [153, 50, 204],
+      darkred: [139, 0, 0],
+      darksalmon: [233, 150, 122],
+      darkseagreen: [143, 188, 143],
+      darkslateblue: [72, 61, 139],
+      darkslategray: [47, 79, 79],
+      darkturquoise: [0, 206, 209],
+      darkviolet: [148, 0, 211],
+      deeppink: [255, 20, 147],
+      deepskyblue: [0, 191, 255],
+      dimgray: [105, 105, 105],
+      dodgerblue: [30, 144, 255],
+      firebrick: [178, 34, 34],
+      floralwhite: [255, 250, 240],
+      forestgreen: [34, 139, 34],
+      fuchsia: [255, 0, 255],
+      gainsboro: [220, 220, 220],
+      ghostwhite: [248, 248, 255],
+      gold: [255, 215, 0],
+      goldenrod: [218, 165, 32],
+      green: [0, 128, 0],
+      greenyellow: [173, 255, 47],
+      honeydew: [240, 255, 240],
+      hotpink: [255, 105, 180],
+      indianred: [205, 92, 92],
+      indigo: [75, 0, 130],
+      ivory: [255, 255, 240],
+      khaki: [240, 230, 140],
+      lavender: [230, 230, 250],
+      lavenderblush: [255, 240, 245],
+      lawngreen: [124, 252, 0],
+      lemonchiffon: [255, 250, 205],
+      lightblue: [173, 216, 230],
+      lightcoral: [240, 128, 128],
+      lightcyan: [224, 255, 255],
+      lightgoldenrodyellow: [250, 250, 210],
+      lightgreen: [144, 238, 144],
+      lightgrey: [211, 211, 211],
+      lightpink: [255, 182, 193],
+      lightsalmon: [255, 160, 122],
+      lightseagreen: [32, 178, 170],
+      lightskyblue: [135, 206, 250],
+      lightslategray: [119, 136, 153],
+      lightsteelblue: [176, 196, 222],
+      lightyellow: [255, 255, 224],
+      lime: [0, 255, 0],
+      limegreen: [50, 205, 50],
+      linen: [250, 240, 230],
+      magenta: [255, 0, 255],
+      maroon: [128, 0, 0],
+      mediumaquamarine: [102, 205, 170],
+      mediumblue: [0, 0, 205],
+      mediumorchid: [186, 85, 211],
+      mediumpurple: [147, 112, 219],
+      mediumseagreen: [60, 179, 113],
+      mediumslateblue: [123, 104, 238],
+      mediumspringgreen: [0, 250, 154],
+      mediumturquoise: [72, 209, 204],
+      mediumvioletred: [199, 21, 133],
+      midnightblue: [25, 25, 112],
+      mintcream: [245, 255, 250],
+      mistyrose: [255, 228, 225],
+      moccasin: [255, 228, 181],
+      navajowhite: [255, 222, 173],
+      navy: [0, 0, 128],
+      oldlace: [253, 245, 230],
+      olive: [128, 128, 0],
+      olivedrab: [107, 142, 35],
+      orange: [255, 165, 0],
+      orangered: [255, 69, 0],
+      orchid: [218, 112, 214],
+      palegoldenrod: [238, 232, 170],
+      palegreen: [152, 251, 152],
+      paleturquoise: [175, 238, 238],
+      palevioletred: [219, 112, 147],
+      papayawhip: [255, 239, 213],
+      peachpuff: [255, 218, 185],
+      peru: [205, 133, 63],
+      pink: [255, 192, 203],
+      plum: [221, 160, 221],
+      powderblue: [176, 224, 230],
+      purple: [128, 0, 128],
+      red: [255, 0, 0],
+      rosybrown: [188, 143, 143],
+      royalblue: [65, 105, 225],
+      saddlebrown: [139, 69, 19],
+      salmon: [250, 128, 114],
+      sandybrown: [244, 164, 96],
+      seagreen: [46, 139, 87],
+      seashell: [255, 245, 238],
+      sienna: [160, 82, 45],
+      silver: [192, 192, 192],
+      skyblue: [135, 206, 235],
+      slateblue: [106, 90, 205],
+      slategray: [112, 128, 144],
+      snow: [255, 250, 250],
+      springgreen: [0, 255, 127],
+      steelblue: [70, 130, 180],
+      tan: [210, 180, 140],
+      teal: [0, 128, 128],
+      thistle: [216, 191, 216],
+      tomato: [255, 99, 71],
+      turquoise: [64, 224, 208],
+      violet: [238, 130, 238],
+      wheat: [245, 222, 179],
+      white: [255, 255, 255],
+      whitesmoke: [245, 245, 245],
+      yellow: [255, 255, 0],
+      yellowgreen: [154, 205, 50],
+    }
+    private_constant :COLORS
+
+    class << self
+      def included(base)
+        COLORS.each do |color, rgb|
+          base.define_method(color) do |alpha = 255|
+            rgb + [alpha]
+          end
+        end
+      end
+    end
+
+    # https://github.com/shoes/shoes3/blob/b856f28795112ecb64bc8f891ac166675f059beb/static/manual-en.txt#L839-L847
+    def gray(darkness = 128, alpha = nil)
+      alpha ||= (darkness.is_a?(Integer) ? 255 : 1.0)
+      [darkness, darkness, darkness, alpha]
+    end
+
+    # Shoes allows RGB values to be Floats between 0 and 1 or Integers between 0 and 255
+    def rgb(r, g, b, a = nil)
+      if r.is_a?(Float)
+        [r, g, b, a || 1.0]
+      elsif r.is_a?(Integer)
+        [r, g, b, a || 255]
+      else
+        raise("RGB values should be Float or Integer!")
+      end
+    end
+
+    def to_rgb(color)
+      case color
+      when nil
+        nil
+      when Array
+        color # Already an RGB array
+      when Symbol
+        if COLORS[color]
+          rgb(*COLORS[color])
+        else
+          raise("Unrecognised color name: #{color}")
+        end
+      when String
+        if color[0] == "#"
+          if color.length == 4
+            r = color[1].to_i(16)
+            g = color[2].to_i(16)
+            b = color[3].to_i(16)
+            rgb(16 * r, 16 * g, 16 * b)
+          elsif color.length == 7
+            r = color[1..2].to_i(16)
+            g = color[3..4].to_i(16)
+            b = color[5..6].to_i(16)
+            rgb(r, g, b)
+          else
+            raise("Don't know how to convert #{color.inspect} to RGB! (wrong number of digits)")
+          end
+        else
+          rgb_value = COLORS[color.to_sym]
+          if rgb_value
+            rgb(*rgb_value)
+          else
+            raise("Unrecognised color name: #{color}")
+          end
+        end
+      else
+        raise("Don't know how to convert #{color.inspect} to RGB!")
+      end
+    end
+  end
+end

data/lib/scarpe/display_service.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# Scarpe Shoes apps operate in multiple layers. A Shoes widget tree exists as fairly
+# plain, simple Ruby objects. And then a display-service widget tree integrates with
+# the display technology, initially Webview. This lets us use Ruby as our API while
+# not tying it too closely to the limitations of Webview.
+#
+# ## Choosing Display Services
+#
+# Before running a Scarpe app, you can set SCARPE_DISPLAY_SERVICE. If you
+# set it to "whatever_service", Scarpe will require "scarpe/whatever_service",
+# which can be supplied by the Scarpe gem or another Scarpe-based gem.
+# Currently leaving the environment variable empty is equivalent to requesting
+# local Webview.
+#
+# ## Events
+#
+# Events are a lot of what tie the Shoes widgets and the display service together.
+#
+# Scarpe widgets *expect* to operate in a fairly "hands off" mode where they record
+# to an event queue to send to the display service, and the display service records
+# events to send back.
+#
+# When a Shoes handler takes an action (e.g. some_para.replace(),) the relevant
+# call will be dispatched as a :display event, to be sent to the display service.
+# And when a display-side event occurs (e.g. user pushes a button,) it will be
+# dispatched as a :shoes event, to be sent to the Shoes tree of widgets.
+#
+module Shoes
+  class DisplayService
+    class << self
+      # This is in the eigenclass/metaclass, *not* instances of DisplayService
+      include Scarpe::Log
+
+      attr_accessor :json_debug_serialize
+
+      # An event_target may be nil, to indicate there is no target.
+      def dispatch_event(event_name, event_target, *args, **kwargs)
+        @@display_event_handlers ||= {}
+
+        unless @log
+          log_init("DisplayService")
+        end
+
+        raise "Cannot dispatch on event_name :any!" if event_name == :any
+
+        @log.debug("Dispatch event: #{event_name.inspect} T: #{event_target.inspect} A: #{args.inspect} KW: #{kwargs.inspect}")
+
+        if DisplayService.json_debug_serialize
+          args = JSON.parse JSON.dump(args)
+          new_kw = {}
+          kwargs.each do |k, v|
+            new_kw[k] = JSON.parse JSON.dump(v)
+          end
+          kwargs = new_kw
+        end
+
+        same_name_handlers = @@display_event_handlers[event_name] || {}
+        any_name_handlers = @@display_event_handlers[:any] || {}
+
+        # Do we have any keys, in same_name_handlers or any_name_handlers, matching the target or :any?
+        # Note that "nil" is a target like any other for these purposes -- subscribing to a nil target
+        # won't get you non-nil-target events and vice-versa.
+        handlers = [
+          same_name_handlers[:any],           # Same name, any target
+          same_name_handlers[event_target],   # Same name, same target
+          any_name_handlers[:any],            # Any name, any target
+          any_name_handlers[event_target],    # Any name, same target
+        ].compact.inject([], &:+)
+        kwargs[:event_name] = event_name
+        kwargs[:event_target] = event_target if event_target
+        handlers.each { |h| h[:handler].call(*args, **kwargs) }
+      end
+
+      # It's permitted to subscribe to event_name :any for all event names, and event_target :any for all targets.
+      # An event_target of nil means "no target", and only matches events dispatched with a nil target.
+      def subscribe_to_event(event_name, event_target, &handler)
+        @@display_event_handlers ||= {}
+        @@display_event_unsub_id ||= 0
+        unless handler
+          raise "Must pass a block as a handler to DisplayService.subscribe_to_event!"
+        end
+
+        unless @log
+          log_init("DisplayService")
+        end
+
+        @log.debug("Subscribe to event: #{event_name.inspect} T: #{event_target.inspect}")
+
+        id = @@display_event_unsub_id
+        @@display_event_unsub_id += 1
+
+        @@display_event_handlers[event_name] ||= {}
+        @@display_event_handlers[event_name][event_target] ||= []
+        @@display_event_handlers[event_name][event_target] << { handler:, unsub_id: id }
+
+        id
+      end
+
+      def unsub_from_events(unsub_id)
+        raise "Must provide an unsubscribe ID!" if unsub_id.nil?
+
+        @@display_event_handlers.each do |_e_name, target_hash|
+          target_hash.each do |_target, h_list|
+            h_list.delete_if { |item| item[:unsub_id] == unsub_id }
+          end
+        end
+      end
+
+      def full_reset!
+        @@display_event_handlers = {}
+        @json_debug_serialize = nil
+      end
+
+      def set_display_service_class(klass)
+        raise "Can only set a single display service class!" if @display_service_klass
+
+        @display_service_klass = klass
+      end
+
+      def display_service
+        return @service if @service
+
+        raise "No display service was set!" unless @display_service_klass
+
+        @service = @display_service_klass.new
+      end
+    end
+
+    # These methods are an interface to DisplayService objects.
+
+    def create_display_widget_for(widget_class_name, widget_id, properties)
+      raise "Override in DisplayService implementation!"
+    end
+
+    def set_widget_pairing(id, display_widget)
+      @display_widget_for ||= {}
+      @display_widget_for[id] = display_widget
+    end
+
+    def query_display_widget_for(id, nil_ok: false)
+      display_widget = @display_widget_for[id]
+      unless display_widget || nil_ok
+        raise "Could not find display widget for linkable ID #{id.inspect}!"
+      end
+
+      display_widget
+    end
+
+    def destroy
+      raise "Override in DisplayService implementation!"
+    end
+  end
+
+  # This is for objects that can be referred to via events, using their
+  # IDs. There are also convenience functions for binding and sending
+  # events.
+  #
+  # Linkable objects may be event targets. Technically anything, linkable
+  # or not, can be an event subscriber, but linkables get easy convenience
+  # functions for subscription.
+  class Linkable
+    attr_reader :linkable_id
+
+    def initialize(linkable_id: object_id)
+      @linkable_id = linkable_id
+    end
+
+    def send_self_event(*args, event_name:, **kwargs)
+      DisplayService.dispatch_event(event_name, self.linkable_id, *args, **kwargs)
+    end
+
+    def send_shoes_event(*args, event_name:, target: nil, **kwargs)
+      DisplayService.dispatch_event(event_name, target, *args, **kwargs)
+    end
+
+    def bind_shoes_event(event_name:, target: nil, &handler)
+      DisplayService.subscribe_to_event(event_name, target, &handler)
+    end
+
+    def unsub_shoes_event(unsub_id)
+      DisplayService.unsub_from_events(unsub_id)
+    end
+  end
+end

data/lib/scarpe/document_root.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Scarpe
+  class DocumentRoot < Scarpe::Flow
+    def initialize
+      @height = "100%"
+      @width = @margin = @padding = nil
+      @options = {}
+
+      super
+
+      create_display_widget
+    end
+
+    # The default inspect string can be absolutely huge in console output, and it's frequently printed.
+    def inspect
+      "<Scarpe::DocumentRoot>"
+    end
+  end
+end