whirled_peas 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c1c4b2f603c535f98d7578741059e0d949ccff4e315fc88c36c13fc2fa58de5
-  data.tar.gz: a9c92f62d2dcb7c7c1983bf6e6e8fa66bb5a92abcec0ae689ca4efc342083625
+  metadata.gz: 7f73ce3a27741b9c790785fe5aad7179c6db66e045ca1c2e43af33887c1fd4d9
+  data.tar.gz: bd19233e2d81a2d4e985bc4c8b0ec3ec07b8fe4691f0c70c5a2374add780bc9b
 SHA512:
-  metadata.gz: 8e746107b95a5176d89792606a76935c84c3686452b2abf99c5383df676263684a096130c18cf07080fbc9ede4dc61b9ae220efe4fd8313e933c230e73d8b1b0
-  data.tar.gz: d5dca0db34f358072134a94ae8b5765abd60d45f18de7496dc0c410cd665c2e9ef91ef33989d00317caef1fd472c210e892af13d8a65bc3126ea37b201dc1b43
+  metadata.gz: 9c2a41a72c30eb2c96161c23bb4f47a37dd9052ca1206cdec2d714d3266b0a6e3eb58bc8dab0dea0517eaf1fe7c5743323a8a7579319e81fdce80b9d65992504
+  data.tar.gz: 1b120aa9b5327880dcdcffbb37cfb77b63a06be55089f77efe7c4da104ce36e65893412178b5efcc31d6f7a3b9aed8353bbe076ea0131f52a142910d251bc61f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.11.0 - 2021-01-30
+
+- [c1f3d94](https://github.com/tcollier/whirled_peas/tree/c1f3d944a35305c3032681db13ffd6142a7e19e4): Add component support
+
 ## v0.10.0 - 2021-01-29
 
 - [3063a2b](https://github.com/tcollier/whirled_peas/tree/3063a2becb7680b5e320a1733b3da933e6c65210): Add built-in and user-defined themes

data/README.md

@@ -245,30 +245,86 @@ template.add_box do
 end
 ```
 
+#### Components
+
+A component is a composition of the core building blocks. This gem includes a handful of components and third parties can also add components using `WhirledPeas.register_component(name, component_class)` (the convention for `name` is a snake cased symbol). A component class must be constructed with no arguments, though can supply basic setters to allow for customizations. A component must also implement `#compose(composer, settings)`, which should attach elements to the composer. Thus a template can integrate with the component like
+
+```ruby
+WhirledPeas.template do |composer, settings|
+  # Attach the component registered with the name `:my_component` to the template
+  WhirledPeas.component(composer, settings, :my_component) do |component|
+    # Configure the component
+  end
+end
+```
+
+##### `:list_with_active`
+
+This component presents a list of content (either horizontally of vertically) and places the item specified by `active_index` in the preferred position.
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ green, blue, *indigo*, viole┃
+┃           ▗▄▄▄▄▄▄▄▄▄▄▄▄▄▄▖  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+Note: in the diagram above, the item specified by the active index is highlighted with `*`s, these are for illustration onlhy. The component can highlight the item with a color and/or background color, but will _not_ add the `*`s.
+
+This component takes the following options
+
+**Required**
+
+- `active_index` - the index of the active item
+- `items` - the array of items to be displayed in the box
+
+**Optional**
+
+- `active_bg_color` - background color of the active item
+- `active_color` - text color of the active item
+- `flow` - `:l2r` or `:t2b`
+- `separator` - string used to separate items in the list, e.g. `", "` for a horizontal list or `"----"` for a vertical list
+- `viewport_size` - number of characters of the viewport in the flow direction
+
+**Example**
+
+```ruby
+WhirledPeas.template do |composer, settings|
+  WhirledPeas.component(composer, settings, :list_with_active) do |component|
+    component.items = %w[red orange yellow green blue indigo violet]
+    component.separator = ', '
+    component.active_index = active
+    component.viewport_size = 27
+    component.active_color = :blue
+    component.active_bg_color = :bright_yellow
+  end
+end
+```
+
 #### Settings
 
 Each element type has an associated settings type, which provide a custom set of options to format the output. Child settings will inherit from the parent, where applicable. The table below lists all settings along with which element types the settings can be applied to (`Grid` and `Box` are containers)
 
-| Setting      | Description                                                                      | Default    | Availability | Inherited            |
-| ------------ | -------------------------------------------------------------------------------- | ---------- | ------------ | -------------------- |
-| `align`      | Justifies the content in the horizontal direction                                | `:left`    | containers   | No                   |
-| `axis_color` | Color used to paint the axes of the graph (see [Colors](#colors))                |            | `Graph`      | No                   |
-| `bg_color`   | Background color (see [Colors](#colors))                                         |            | all          | Yes                  |
-| `bold`       | `true` makes the font bold                                                       | `false`    | all          | Yes                  |
-| `border`     | Set the border for the lements                                                   | none       | containers,  | Only style and color |
-| `color`      | Foreground text color (see [Colors](#colors))                                    |            | all          | Yes                  |
-| `flow`       | Flow to display child elements (see [Display Flow](#display-flow))               | `:l2r`     | containers   | No                   |
-| `height`     | Override the calculated height of an element's content area                      |            | all          | No                   |
-| `margin`     | Set the (left, top, right, bottom) margin of the element                         | `0`        | containers   | No                   |
-| `num_cols`   | Number of columns in the grid (must be set!)                                     |            | `Grid`       | No                   |
-| `padding`    | Set the (left, top, right, bottom) padding of the element                        | `0`        | containers   | No                   |
-| `position`   | Set the (left, top) position of the element relative to parent content area      | `0`        | containers   | No                   |
-| `scrollbar`  | Display a scroll bar for vertical or horizontal scrolling                        |            | `Box`        | No                   |
-| `sizing`     | Sizing model (`:content` or `:border`) used in conjunction with `width`/`height` | `:content` | `Box`        | No                   |
-| `title_font` | Font used for "large" text (see [Large Text](#large-text), ignores `underline`)  |            | `Text`       | No                   |
-| `underline`  | `true` underlines the font                                                       | `false`    | all          | Yes                  |
-| `width`      | Override the calculated width of an element's content area                       |            | all          | No                   |
-| `valign`     | Justifies the content in the vertical direction                                  | `:top`     | containers   | No                   |
+| Setting         | Description                                                                      | Default    | Availability | Inherited            |
+| --------------- | -------------------------------------------------------------------------------- | ---------- | ------------ | -------------------- |
+| `align`         | Justifies the content in the horizontal direction                                | `:left`    | containers   | No                   |
+| `axis_color`    | Color used to paint the axes of the graph (see [Colors](#colors))                |            | `Graph`      | No                   |
+| `bg_color`      | Background color (see [Colors](#colors))                                         |            | all          | Yes                  |
+| `bold`          | `true` makes the font bold                                                       | `false`    | all          | Yes                  |
+| `border`        | Set the border for the lements                                                   | none       | containers,  | Only style and color |
+| `color`         | Foreground text color (see [Colors](#colors))                                    |            | all          | Yes                  |
+| `flow`          | Flow to display child elements (see [Display Flow](#display-flow))               | `:l2r`     | containers   | No                   |
+| `height`        | Override the calculated height of an element's content area                      |            | all          | No                   |
+| `margin`        | Set the (left, top, right, bottom) margin of the element                         | `0`        | containers   | No                   |
+| `num_cols`      | Number of columns in the grid (must be set!)                                     |            | `Grid`       | No                   |
+| `padding`       | Set the (left, top, right, bottom) padding of the element                        | `0`        | containers   | No                   |
+| `content_start` | Set the (left, top, right, bottom) position of children                          | `0`        | containers   | No                   |
+| `scrollbar`     | Display a scroll bar for vertical or horizontal scrolling                        |            | `Box`        | No                   |
+| `sizing`        | Sizing model (`:content` or `:border`) used in conjunction with `width`/`height` | `:content` | `Box`        | No                   |
+| `title_font`    | Font used for "large" text (see [Large Text](#large-text), ignores `underline`)  |            | `Text`       | No                   |
+| `underline`     | `true` underlines the font                                                       | `false`    | all          | Yes                  |
+| `width`         | Override the calculated width of an element's content area                       |            | all          | No                   |
+| `valign`        | Justifies the content in the vertical direction                                  | `:top`     | containers   | No                   |
 
 ##### Themes
 
@@ -276,7 +332,7 @@ The template builder (`WhirledPeas.template`) takes an optional `theme` argument
 You can define your own theme
 
 ```ruby
-WhirledPeas.define_theme(:my_theme) do |theme|
+WhirledPeas.register_theme(:my_theme) do |theme|
   theme.bg_color = :bright_white
   theme.color = :blue
   theme.border_color = :bright_green
@@ -473,11 +529,19 @@ The `valign` setting takes one of several values
 ┗━━━━━━━━━┛
 ```
 
-##### Position
+##### Content Start
+
+Content start settings dictate the relative position from the content area where the children will get painted. Positive values for `left`/`top` result in moving the children leftward/downward, negative values shift children rightward/upward. Setting `right` or `bototm` will result in the end of the children to be painted relative to the right/bottom of the content area.
+
+To set these values, use
 
-Position settings dictate the relative position from where the painter would have preferred to place the container. Negative numbers move the container left/up and positive numbers move it right/down. To set these values, use
+- `set_content_start(left:, top:, right:, bottom:)`
+- `content_start.left=`
+- `content_start.top=`
+- `content_start.right=`
+- `content_start.bottom=`
 
-- `set_position(left:, top:)`
+Note: setting `left` and `right` or `top` and `bottom` is not supported
 
 ##### Sizing Model
 

data/examples/components.rb

@@ -0,0 +1,35 @@
+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
+        component.active_color = :green
+        component.active_bg_color = :yellow
+      end
+    end
+  end
+end
+
+class Application
+  def start(producer)
+    producer.frameset(5, easing: :parametric) do |fs|
+      ITEMS.length.times { |i| fs.add_frame('intro', args: { active: i }) }
+    end
+    producer.add_frame('hold', duration: 1, args: { active: ITEMS.length - 1 })
+  end
+end
+
+WhirledPeas.configure do |config|
+  config.template_factory = TemplateFactory.new
+  config.application = Application.new
+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/whirled_peas.rb

@@ -7,24 +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 self.template(theme_name=nil, &block)
-    require 'whirled_peas/graphics/composer'
-    Graphics::Composer.build(theme_name, &block)
-  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.define_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)
+    def config
+      @config ||= Config.new
+    end
   end
 end

data/lib/whirled_peas/command/config_command.rb

@@ -8,8 +8,9 @@ module WhirledPeas
     class ConfigCommand < Base
       def start
         require config_file
-      rescue LoadError
-        puts "Error loading #{config_file}"
+      rescue LoadError => e
+        puts e
+        puts e.backtrace.join("\n")
         exit(1)
       end
 

data/lib/whirled_peas/command/play.rb

@@ -38,8 +38,9 @@ module WhirledPeas
               config.application.start(producer)
             end
           end
-        rescue LoadError
-          puts "Error loading #{config_file}"
+        rescue LoadError => e
+          puts e
+          puts e.backtrace.join("\n")
           exit(1)
         end
 

data/lib/whirled_peas/command/themes.rb

@@ -49,8 +49,9 @@ module WhirledPeas
             break if gets.chomp == 'q'
           end
         end
-      rescue LoadError
-        puts "Error loading #{config_file}"
+      rescue LoadError => e
+        puts e
+        puts e.backtrace.join("\n")
         exit(1)
       end
 

data/lib/whirled_peas/component.rb

@@ -0,0 +1,35 @@
+module WhirledPeas
+  module Component
+    module Factory
+      class << self
+        def register(name, klass)
+          classes[name] = klass
+        end
+
+        def build(name)
+          unless classes.key?(name)
+            expected = classes.keys.join(', ')
+            raise ArgumentError, "Unrecognized component: #{name.inspect}, expecting one of #{expected}"
+          end
+          @classes[name].new
+        end
+
+        private
+
+        def classes
+          return @classes if @classes
+          @classes = {}
+          Component.constants.each do |const|
+            next if const == name
+            klass = Component.const_get(const)
+            next unless klass.is_a?(Class)
+            name = const.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+            @classes[name] = klass
+          end
+          @classes
+        end
+      end
+    end
+  end
+  private_constant :Component
+end

data/lib/whirled_peas/component/list_with_active.rb

@@ -0,0 +1,88 @@
+module WhirledPeas
+  module Component
+    class ListWithActive
+      attr_accessor :active_index, :active_color, :active_bg_color, :separator
+
+      attr_reader :items
+
+      attr_writer :flow, :viewport_size
+
+      def items=(value)
+        @items = value.map(&:to_s)
+      end
+
+      def flow
+        @flow || :l2r
+      end
+
+      def total_size
+        @total_size ||= if flow == :l2r
+          size = separator.nil? ? 0 : (items.count - 1) * separator.length
+          items.each { |item| size += item.length }
+          size
+        else
+          items.count + (separator.nil? ? 0 : items.count - 1)
+        end
+      end
+
+      def viewport_size
+        @viewport_size || total_size
+      end
+
+      def compose(composer, settings)
+        %i[items active_index].each do |required_attr|
+          if send(required_attr).nil?
+            raise ArugmentError, "Require field #{required_attr} missing"
+          end
+        end
+
+        composer.add_box('ListWithActive') do |composer, settings|
+          settings.flow = flow
+          settings.align = :left
+          settings.full_border
+          if flow == :l2r
+            settings.width = viewport_size
+            active_start = separator.nil? ? 0 : active_index * separator.length
+            items.first(active_index).each do |item|
+              active_start += item.length
+            end
+            active_size = items[active_index].length
+          else
+            settings.height = viewport_size
+            active_start = active_index + (separator.nil? ? 0 : active_index)
+            active_size = 1
+          end
+
+          if viewport_size < total_size
+            front_padding = (viewport_size - active_size) * 0.667
+            offset = (active_start - front_padding).round
+            if offset < 0
+              offset = 0
+            elsif offset > total_size - viewport_size
+              offset = total_size - viewport_size
+            end
+
+            if flow == :l2r
+              settings.content_start.left = -offset
+              settings.scrollbar.horiz = true
+            else
+              settings.content_start.top = -offset
+              settings.scrollbar.vert = true
+            end
+          end
+
+          items.each.with_index do |item, index|
+            composer.add_text { separator } if !separator.nil? && index > 0
+            composer.add_text do |_, settings|
+              if index == active_index
+                settings.bg_color = active_bg_color
+                settings.color = active_color
+              end
+              item
+            end
+          end
+        end
+      end
+    end
+  end
+end