whirled_peas 0.9.1 → 0.13.0

data/doc/template_factory.md

@@ -0,0 +1,53 @@
+## Template Factory
+
+To render the frame events sent by the application, the application requires a template factory. This factory will be called for each frame event, with the frame name and the arguments supplied by the application. A template factory can be an instance of ruby class and thus can maintain state. Whirled Peas provides a few basic building blocks to make simple, yet elegant terminal-based UIs.
+
+To build a template in a template factory, use `WhirledPeas.template(theme)`, which takes an optional [theme](themes.md) and yields a composer (used to add [elements](elements.md) to the template) and [settings](settings.md) (used to configure the element).
+
+### Full example
+
+```ruby
+class TemplateFactory
+  def build(frame, args)
+    set_state(frame, args)
+    WhirledPeas.template do |composer, settings|
+      settings.flow = :l2r
+      settings.align = :center
+
+      composer.add_box('Title', &method(:title))
+      composer.add_box('Sum', &method(:sum))
+      composer.add_grid('NumberGrid', &method(:number_grid))
+    end
+  end
+
+  private
+
+  def set_state(frame, args)
+    @frame = frame
+    @numbers = args.key?(:numbers) ? args[:numbers] || []
+    @sum = args[:sum] if args.key?(:sum)
+    @low = args[:low] if args.key?(:low)
+    @high = args[:high] if args.key?(:high)
+  end
+
+  def title(_composer, settings)
+    settings.underline = true
+    "Pair Finder"
+  end
+
+  def sum(_composer, settings)
+    settings.color = @frame == 'found-pair' ? :green : :red
+    @sum ? "Sum: #{@sum}" : 'N/A'
+  end
+
+  def number_grid(composer, settings)
+    settings.full_border
+    @numbers.each.with_index do |num, index|
+      composer.add_text do |_, settings|
+        settings.bg_color = (@low == index || @high == index) ? :cyan : :white
+        num
+      end
+    end
+  end
+end
+```

data/doc/themes.md

@@ -0,0 +1,50 @@
+## Themes
+
+The template builder (`WhirledPeas.template`) takes an optional `theme` argument. You can provide the name of a predefined theme (run `whirled_peas themes` to see a list with samples) or define you own with the following
+
+```ruby
+WhirledPeas.register_theme(:my_theme) do |theme|
+  theme.bg_color = :bright_white
+  theme.color = :blue
+  theme.border_color = :bright_green
+  theme.axis_color = :bright_red
+  theme.title_font = :default
+end
+```
+
+Theme settings will be used as default settings throughout the template, however theme settings can be overridden on any element.
+
+### Theme Settings
+
+The following theme settings override the existing default settings for all elements.
+
+- `axis_color` - axis color for graphs (defaults to `border_color`)
+- `bg_color` - background color (defaults to system color)
+- `border_color` - border color (defaults to `color`)
+- `border_style` - border style (defaults to `bold`)
+- `color` - text color (defaults to system color)
+
+The following theme settings provide new options that can be applied to existing settings. E.g.
+
+```ruby
+WhirledPeas.register_theme(:my_theme) do |theme|
+  theme.highlight_bg_color = :bright_white
+  theme.highlight_color = :red
+  # ...
+end
+
+WhirledPeas.template(:my_theme) do |composer, settings|
+  # ...
+  composer.add_text do |composer, settings|
+    composer.bg_color = :highlight
+    composer.color = :highlight
+    "This Is Important!!!"
+  end
+end
+```
+
+- `highlight_bg_color` - provides a new `:highlight` option that can be applied to `bg_color` settings (defaults to `color`)
+- `highlight_color` - provides a new `:highlight` option that can be applied to `color` settings (defaults to `bg_color`)
+- `title_font` - provides a new `:theme` option that can be applied to `title_font` settings (defaults to system default)
+
+Note: the defaults for the `highlight_bg_color` and `highlight_color` options result in inverting the background and text colors.

data/examples/components.rb

@@ -0,0 +1,33 @@
+require 'bundler/setup'
+require 'whirled_peas'
+require 'whirled_peas/component/list_with_active'
+
+class TemplateFactory
+  ITEMS = 400.times.map(&:itself)
+
+  def build(name, args)
+    active = args[:active]
+    WhirledPeas.template do |composer, settings|
+      WhirledPeas.component(composer, settings, :list_with_active) do |component, settings|
+        component.items = %w[red orange yellow green blue indigo violet]
+        component.separator = ', '
+        component.active_index = active
+        component.viewport_size = 27
+      end
+    end
+  end
+end
+
+class Application
+  def start(producer)
+    producer.frameset(5, easing: :parametric) do |fs|
+      TemplateFactory::ITEMS.length.times { |i| fs.add_frame('intro', args: { active: i }) }
+    end
+    producer.add_frame('hold', duration: 1, args: { active: TemplateFactory::ITEMS.length - 1 })
+  end
+end
+
+WhirledPeas.configure do |config|
+  config.template_factory = TemplateFactory.new
+  config.application = Application.new
+end

data/examples/graph.rb

@@ -32,7 +32,7 @@ class TemplateFactory
               settings.color = :bright_blue
               settings.height = 15
               INNER_WIDTH.times.map do |i|
-                easing.ease(i.to_f / (INNER_WIDTH - 1))
+                easing.invert(i.to_f / (INNER_WIDTH - 1))
               end
             end
           end

data/examples/scrolling.rb

@@ -2,38 +2,27 @@ require 'bundler/setup'
 require 'whirled_peas'
 
 class TemplateFactory
-  HPADDING = 0
-  VPADDING = 0
   ITEM_COUNT = 64
 
   def build(name, args)
     top = args[:top]
     WhirledPeas.template do |composer, settings|
-      settings.color = :green
       composer.add_box('Vert') do |composer, settings|
-        settings.bg_color = :bright_red
-        settings.full_border(color: :blue)
+        settings.full_border
         settings.set_scrollbar(vert: true)
         settings.height = 12
-        composer.add_box('Inner') do |composer, settings|
-          settings.flow = :t2b
-          settings.set_padding(left: HPADDING, right: HPADDING, top: VPADDING, bottom: VPADDING)
-          settings.set_position(top: top)
-          ITEM_COUNT.times do |i|
-            composer.add_text { "%2d" % i }
-          end
+        settings.flow = :t2b
+        settings.content_start.top = top
+        ITEM_COUNT.times do |i|
+          composer.add_text { "%2d" % i }
         end
       end
       composer.add_box('Horiz') do |composer, settings|
-        settings.bg_color = :bright_red
-        settings.full_border(color: :blue)
-        settings.set_padding(left: HPADDING, right: HPADDING, top: VPADDING, bottom: VPADDING)
+        settings.full_border
         settings.set_scrollbar(horiz: true)
         settings.width = 12
-        composer.add_box('Inner') do |composer, settings|
-          settings.set_position(left: top)
-          ITEM_COUNT.times.map { |i| (i % 10).to_s }.join
-        end
+        settings.content_start.left = top
+        ITEM_COUNT.times.map { |i| (i % 10).to_s }.join
       end
     end
   end

data/lib/data/themes.yaml

@@ -0,0 +1,15 @@
+bright:
+  axis_color: :red
+  bg_color: :bright_white
+  border_color: :bright_blue
+  color: :blue
+  title_font: :default
+
+dark:
+  axis_color: :bright_white
+  bg_color: :black
+  border_color: :gray
+  color: :white
+  highlight_bg_color: :bright_red
+  highlight_color: :black
+  title_font: :swan

data/lib/whirled_peas.rb

@@ -7,16 +7,38 @@ require 'whirled_peas/utils'
 require 'whirled_peas/version'
 
 module WhirledPeas
-  def self.config
-    @config ||= Config.new
-  end
+  class << self
+    def configure(&block)
+      yield config
+    end
 
-  def self.configure(&block)
-    yield config
-  end
+    def register_component(name, klass)
+      require 'whirled_peas/component'
+      Component::Factory.register(name, klass)
+    end
+
+    def component(composer, settings, name, &block)
+      require 'whirled_peas/component'
+      component = Component::Factory.build(name)
+      yield component
+      component.compose(composer, settings)
+    end
+
+    def template(theme_name=nil, &block)
+      require 'whirled_peas/graphics/composer'
+      Graphics::Composer.build(theme_name, &block)
+    end
+
+    def register_theme(name, &block)
+      require 'whirled_peas/settings/theme'
+      require 'whirled_peas/settings/theme_library'
+      theme = Settings::Theme.new
+      yield theme
+      Settings::ThemeLibrary.add(name, theme)
+    end
 
-  def self.template(&block)
-    require 'whirled_peas/graphics/composer'
-    Graphics::Composer.build(&block)
+    def config
+      @config ||= Config.new
+    end
   end
 end

data/lib/whirled_peas/animator/debug_consumer.rb

@@ -4,8 +4,8 @@ module WhirledPeas
       def add_frameset(frameset)
         require 'json'
 
-        frameset.each_frame do |frame, args|
-          puts [frame, *(JSON.generate(args) unless args.empty?)].join(' ')
+        frameset.each_frame do |frame, duration, args|
+          puts [frame, "duration=#{duration}", *(JSON.generate(args) unless args.empty?)].join(' ')
         end
       end
 

data/lib/whirled_peas/animator/easing.rb

@@ -21,6 +21,10 @@ module WhirledPeas
 
       EFFECTS = %i[in out in_out]
 
+      INVERSE_MAX_ITERATIONS = 10
+      INVERSE_DELTA = 0.0001
+      INVERSE_EPSILON = 0.00001
+
       def initialize(easing=:linear, effect=:in_out)
         unless EASING.key?(easing)
           raise ArgumentError,
@@ -45,6 +49,56 @@ module WhirledPeas
         end
       end
 
+      def invert(target)
+        ease_fn = case effect
+        when :in
+          proc { |v| ease_in(v) }
+        when :out
+          proc { |v| ease_out(v) }
+        else
+          proc { |v| ease_in_out(v) }
+        end
+
+        # Use Newton's method(!!) to find the inverse values of the easing function for the
+        # specified target. Make an initial guess that is equal to the target and see how
+        # far off the eased value is from the target. If we are close enough (as dictated by
+        # INVERSE_EPSILON constant), then we return our guess. If we aren't close enough, then
+        # find the slope of the eased line (approximated with a small step of INVERSE_DELTA
+        # along the x-axis). The intersection of the slope and target will give us the value
+        # of our next guess.
+        #
+        # Since most easing functions only vary slightly from the identity line (y = x), we
+        # can typically get the eased guess within epsilon of the target in a few iterations,
+        # however only iterate at most INVERSE_MAX_ITERATIONS times.
+        #
+        #         ┃                     ......
+        #         ┃                  ...
+        # target -┃------------+  ...
+        #         ┃          /.|..
+        #         ┃      ../.  |
+        #         ┃   ...  |   |
+        #         ┃...     |   |
+        #         ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #                  |   |
+        #              guess   next guess
+        #
+        # IMPORTANT: This method only works well for monotonic easing functions
+
+        # Pick the target as the first guess. For targets of 0 and 1 (and 0.5 for ease_in_out),
+        # this guess will be the exact value that yields the target. For other values, the
+        # eased guess will generally be close to the target.
+        guess = target
+        INVERSE_MAX_ITERATIONS.times do |i|
+          eased_guess = ease_fn.call(guess)
+          error = eased_guess - target
+          break if error.abs < INVERSE_EPSILON
+          next_eased_guess = ease_fn.call(guess + INVERSE_DELTA)
+          delta_eased = next_eased_guess - eased_guess
+          guess -= INVERSE_DELTA * error / delta_eased
+        end
+        guess
+      end
+
       private
 
       attr_reader :easing, :effect
@@ -60,6 +114,9 @@ module WhirledPeas
         1 - EASING[easing].call(1 - value)
       end
 
+      # Ease in/ease out
+      #
+      # @see https://www.youtube.com/watch?v=5WPbqYoz9HA
       def ease_in_out(value)
         if value < 0.5
           ease_in(value * 2) / 2

data/lib/whirled_peas/animator/frameset.rb

@@ -4,8 +4,8 @@ require_relative 'frame'
 module WhirledPeas
   module Animator
     class Frameset
-      def initialize(frame_slots, easing, effect)
-        @frame_slots = frame_slots
+      def initialize(duration, easing, effect)
+        @duration = duration
         @easing = Easing.new(easing, effect)
         @frames = []
       end
@@ -16,17 +16,22 @@ module WhirledPeas
 
       # Yield each frame in an "eased" order
       def each_frame(&block)
-        frame_slots.times do |i|
-          input = i.to_f / (frame_slots - 1)
-          eased_value = @easing.ease(input)
-          index = (eased_value * (frames.length - 1)).floor
-          yield *frames[index]
+        return if frames.length == 0
+        if frames.length == 1
+          frame, args = frames[0]
+          yield frame, duration, args
+        else
+          frames.each.with_index do |(frame, args), index|
+            curr_ease = @easing.invert(index.to_f / frames.length)
+            next_ease = @easing.invert((index + 1).to_f / frames.length)
+            yield frame, duration * (next_ease - curr_ease), args
+          end
         end
       end
 
       private
 
-      attr_reader :frame_slots, :easing, :frames
+      attr_reader :duration, :easing, :frames
     end
     private_constant :Frameset
   end

data/lib/whirled_peas/animator/producer.rb

@@ -4,32 +4,31 @@ require_relative 'frameset'
 module WhirledPeas
   module Animator
     class Producer
-      def self.produce(consumer, refresh_rate)
-        producer = new(consumer, refresh_rate)
+      def self.produce(consumer)
+        producer = new(consumer)
         yield producer
         consumer.process
       end
 
-      def initialize(consumer, refresh_rate)
+      def initialize(consumer)
         @consumer = consumer
-        @refresh_rate = refresh_rate
       end
 
-      def add_frame(name, duration: nil, args: {})
-        frameset(duration || 1 / refresh_rate) do |fs|
+      def add_frame(name, duration:, args: {})
+        frameset(duration) do |fs|
           fs.add_frame(name, args: args)
         end
       end
 
       def frameset(duration, easing: :linear, effect: :in_out, &block)
-        fs = Frameset.new((duration * refresh_rate).round, easing, effect)
+        fs = Frameset.new(duration, easing, effect)
         yield fs
         consumer.add_frameset(fs)
       end
 
       private
 
-      attr_reader :consumer, :refresh_rate
+      attr_reader :consumer
     end
   end
 end

data/lib/whirled_peas/animator/renderer_consumer.rb

@@ -1,5 +1,6 @@
 require 'whirled_peas/graphics/renderer'
 require 'whirled_peas/utils/ansi'
+require 'whirled_peas/device/rendered_frame'
 
 module WhirledPeas
   module Animator
@@ -9,23 +10,27 @@ module WhirledPeas
         @device = device
         @width = width
         @height = height
-        @renders = []
+        @rendered_frames = []
+        @prev_pixel_grid = nil
       end
 
       def add_frameset(frameset)
-        frameset.each_frame do |frame, args|
+        frameset.each_frame do |frame, duration, args|
           template = template_factory.build(frame, args)
-          renders << Graphics::Renderer.new(template, width, height).paint
+          pixel_grid = Graphics::Renderer.new(template, width, height).paint
+          strokes = prev_pixel_grid.nil? ? pixel_grid.to_s : pixel_grid.diff(prev_pixel_grid)
+          rendered_frames << Device::RenderedFrame.new(strokes, duration)
+          @prev_pixel_grid = pixel_grid
         end
       end
 
       def process
-        device.handle_renders(renders)
+        device.handle_rendered_frames(rendered_frames)
       end
 
       private
 
-      attr_reader :template_factory, :device, :width, :height, :renders
+      attr_reader :template_factory, :device, :width, :height, :rendered_frames, :prev_pixel_grid
     end
   end
 end