minichart 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7debe086fa2ba7994f1362fa53ab2d5da5cc61a0010f6f08d6ca125cc447bc27
-  data.tar.gz: 77dd9cf342830795872c284befe937cba7caa9c2372bdae2b8a42a44e6d4bb13
+  metadata.gz: 6109cfc57cb909c2ba0a9df4e184bc4319220399b774ff2098b728bf4a41f57e
+  data.tar.gz: 32cd8ff3c3260d08f81106c3ac74037e36990d4601eb8ff7e40c8840d44b3ca3
 SHA512:
-  metadata.gz: 5a331fa46640d9bfb32759a5aa160680cd684bd7f57f194e212f7b0d0f5c2af61f03f8b526702de0421dbe608fbc70c39df8c219967b8c2de9fe647f04822e42
-  data.tar.gz: 2fede85eef059f2ac6980ff9ba6249b1e7b716edb38eacfe514cebace11488e0cb1ca4520ff4d7a3bf58934e746e846130026c9c98f7bc41419c4216a68c8734
+  metadata.gz: 63e01d19bd4539ccf1283a98bee8f941a7e270ee0f1a2956aed20ecbab21661e7923420588c28f0aa90027cfc6fadc88f5f90b5776ff8dfa3523c9faf85c03ba
+  data.tar.gz: 1861ffff3d852e85fbf9b8c334d091f6dd40ce823086ae4215edb95c96f20a5f9e79e4da5caaf51b35956a8da92ca9de054ee35aae67c84884c02ad5f59af628

data/README.md

@@ -6,6 +6,26 @@ Create SVG mini charts with Ruby
 
 ![demo](examples/multiple.svg)
 
+---
+
+* [Install](#install)
+* [Usage](#usage)
+* [Chart Types](#chart-types)
+  * [Line Chart](#line-chart)
+  * [Bar Chart](#bar-chart)
+  * [Area Chart](#area-chart)
+  * [Horizontal Bar Meter](#horizontal-bar-meter)
+  * [Vertical Bar Meter](#vertical-bar-meter)
+* [Configuration](#configuration)
+  * [Class-level default options](#class-level-default-options)
+  * [Instance initialization options](#instance-initialization-options)
+  * [Instance-level options](#instance-level-options)
+* [Options Reference](#options-reference)
+  * [Basic Options](#basic-options)
+  * [Meter Options](#meter-options)
+* [Examples](#examples)
+
+
 ---
 
 ## Install
@@ -126,49 +146,124 @@ dual = VerticalBarMeter.new 80,
 Meter charts support [additional options](#meter-options).
 
 
-## Options
+## Configuration
 
-### Basic Options
+Chart options can be set in one of three ways.
+
+### Class-level default options
+
+See or set default options for any chart class by calling its `::options` method:
+
+```ruby
+# See all options
+p AreaChart.options
+#=> {:background=>"white", :height=>100, :width=>300, :stroke=>2, :style=>{}, :color=>"#66f"}
+
+# Set a single default option
+AreaChart.options[:color] = '#333'
+
+# Set multiple options at once
+AreaChart.options background: 'black', color: 'green'
+```
+
+### Instance initialization options
 
-All chart classes support a second hash argument for options
+Set options by providing a hash as the second argument on initialization:
 
 ```ruby
-chart = LineChart.new data, options
+chart = AreaChart.new data, height: 120, width: 500
 ```
 
-| Option         | Default                       | Description                                                  |
-| -------------- | ----------------------------- | ------------------------------------------------------------ |
-| `background`   | `"white"`                     | Chart background color                                       |
-| `color`        | `"#333"`                      | Chart color                                                  |
-| `aspect_ratio` | `3`                           | Set automatic width                                          |
-| `height`       | `100`<sup>*</sup>             | Chart height in pixels                                       |
-| `width`        | Calculated by `aspect_ratio`<sup>*</sup> | Chart width in pixels                                        |
-| `stroke`       | `2`                           | Line stroke width.<br />In `BarChart` determines the gap between bars |
-| `style`        | *None*                        | Style hash for the SVG                                       |
+### Instance-level options
+
+After initialization, you can still update individual options:
+
+```ruby
+chart = AreaChart.new data
+chart.options[:background] = 'yellow'
+```
+
+## Options Reference
+
+### Basic Options
+
+#### background
+
+Chart background color.
+
+#### color
+
+Chart color.
+
+#### height
+
+Chart height in pixels.
+
+#### width
+
+Chart width in pixels.
+
+#### stroke
+
+Line stroke width. This has a different effect in different chart types.
+
+#### style
+
+CSS Style hash to apply to the entire SVG.
 
-_* Default dimensions are reversed for horizontal meters - `width` defaults to 100, and `height` is calculated automatically._
 
 ### Meter Options
 
 Meter charts support these options in additon to the basic options:
 
-| Option                     | Default   | Description                                                  |
-| -------------------------- | --------- | ------------------------------------------------------------ |
-| `mode`                     | `:auto`   | Display mode.<br />Can be `:positive`, `:negative`, `:auto` or `:dual` |
-| `max`                      | `100`     | The absolute maximum value.<br />This number should be positive even for negative charts |
-| `zero_line`                | `false`   | If true, mark the zero line                                  |
-| `zero_line_size`           | `6`       | Size of the zero line                                        |
-| `zero_line_color`          | `"black"` | Color of the zero line                                       |
-| `clipping_indicator`       | `false`   | If true, show when the value exceeds the range               |
-| `clipping_indicator_size`  | `6`       | Size of the clipping indicator                               |
-| `clipping_indicator_color` | `"yelow"` | Color of the clipping indicator                              |
+#### mode
+
+Display mode. Can be `:positive`, `:negative`, `:dual` or `:auto` (default).
+
+The `:auto` mode will switch between `:positive` and `:negative` based on the
+value.
+
+#### max
+
+The absolute maximum value. This number should be positive even for negative
+charts.
+
+#### notches
+
+An array of one or more levels to place a notch marker. Use positive values
+only.
+
+#### notch_thickness
+
+Thickness of the notch markers.
+
+#### notch_color
+
+Color of the notch markers.
+
+#### clipping_indicator
+
+If true, show a marker when the value exceeds the range.
+
+#### clipping_indicator_thickness
+
+Thickness of the clipping indicator.
+
+#### clipping_indicator_color
+
+Color of the clipping indicator.
 
 ## Examples
 
 See more examples (code and SVG output) in the [examples folder][1].
 
----
+## Contributing / Support
+
+If you experience any issue, have a question or a suggestion, or if you wish
+to contribute, feel free to [open an issue][issues].
 
+---
 
 [1]: https://github.com/DannyBen/minichart/tree/master/examples#examples
-[2]: https://github.com/DannyBen/victor
+[2]: https://github.com/DannyBen/victor
+[issues]: https://github.com/DannyBen/minichart/issues

data/lib/minichart/base.rb

@@ -1,16 +1,40 @@
 module Minichart
   # Base class for all Minichart classes
   class Base < Victor::SVGBase
-    attr_reader :aspect_ratio, :background, :color, :data,
-      :height, :stroke, :style, :width, :opts
+    attr_reader :data, :options
+
+    class << self
+      def master_defaults
+        {
+          background: 'white',
+          height: 100,
+          width: 300,
+          stroke: 2,
+          style: {},
+          color: '#66f'
+        }
+      end
+
+      # For subclasses to define
+      def defaults
+        {}
+      end
+
+      def options(update_hash = nil)
+        @options ||= master_defaults.merge defaults
+        @options.merge! update_hash if update_hash
+        @options
+      end
+    end
 
-    def initialize(data, opts = {})
-      @data, @opts = data, opts
-      
-      # super height: height, width: width, style: style, viewBox: viewbox
-      super viewBox: viewbox, style: style
-      element :rect, x: 0, y: 0, width: width, height: height,
-        fill: background, stroke_width: 0
+    def initialize(data, user_options = {})
+      @data = data
+      @options = self.class.options.merge user_options
+
+      super viewBox: viewbox, style: options[:style]
+      element :rect, x: 0, y: 0,
+        width: options[:width], height: options[:height],
+        fill: options[:background], stroke_width: 0
 
       clip_path_id = IDGenerator.next
       setup_clip_path clip_path_id
@@ -23,41 +47,13 @@ module Minichart
     def setup_clip_path(id)
       element :defs do
         element :clipPath, id: id do
-          element :rect, width: width, height: height
+          element :rect, width: options[:width], height: options[:height]
         end
       end
     end
 
-    def background
-      opts[:background] ||= 'white'
-    end
-
-    def aspect_ratio
-      opts[:aspect_ratio] ||= 3
-    end
-
-    def height
-      opts[:height] ||= 100
-    end
-
-    def width
-      opts[:width] ||= (aspect_ratio * height).round
-    end
-
-    def stroke
-      opts[:stroke] ||= 2
-    end
-
-    def style
-      opts[:style] ||= {}
-    end
-
-    def color
-      opts[:color] ||= '#333'
-    end
-
     def viewbox
-      "0 0 #{width} #{height}"
+      "0 0 #{options[:width]} #{options[:height]}"
     end
 
     def build

data/lib/minichart/charts/area_chart.rb

@@ -1,9 +1,9 @@
 module Minichart
   class AreaChart < Chart
     def build
-      element :polyline, fill: color,
-        stroke: color,
-        stroke_width: stroke,
+      element :polyline, fill: options[:color],
+        stroke: options[:color],
+        stroke_width: options[:stroke],
         stroke_linejoin: :round,
         points: points
     end
@@ -11,15 +11,15 @@ module Minichart
   protected
 
     def points
-      result = ["0,#{height}"]
+      result = ["0,#{options[:height]}"]
 
       inverted_points.each do |point|
-        x = width*point[0]
-        y = height*point[1]
+        x = options[:width] *point[0]
+        y = options[:height] * point[1]
         result << "#{x},#{y}"
       end
 
-      result << "#{width},#{height}"
+      result << "#{options[:width]},#{options[:height]}"
 
       result
     end

data/lib/minichart/charts/bar_chart.rb

@@ -11,18 +11,22 @@ module Minichart
   protected
 
     def bar_width
-      @bar_width ||= width / data.size
+      @bar_width ||= options[:width] / data.size
     end
 
     def bar_options(x, y)
-      y = y*height
-      bar_height = height-y
+      y = y * options[:height]
+      bar_height = options[:height] - y
       { 
-        x: x*width, 
+        x: x * options[:width], 
         y: y, 
-        width: bar_width, 
-        height: bar_height, 
-        style: { fill: color, stroke_width: stroke, stroke: background }
+        width: bar_width,
+        height: bar_height,
+        style: {
+          fill: options[:color],
+          stroke_width: options[:stroke],
+          stroke: options[:background]
+        }
       }
     end
   end

data/lib/minichart/charts/line_chart.rb

@@ -2,8 +2,8 @@ module Minichart
   class LineChart < Chart
     def build
       element :polyline, fill: :none,
-        stroke: color,
-        stroke_width: stroke,
+        stroke: options[:color],
+        stroke_width: options[:stroke],
         stroke_linejoin: :round,
         points: points
     end
@@ -13,8 +13,8 @@ module Minichart
     def points
       result = []
       inverted_points.each do |point|
-        x = width*point[0]
-        y = height*point[1]
+        x = options[:width] * point[0]
+        y = options[:height] * point[1]
         result << "#{x},#{y}"
       end
       result

data/lib/minichart/meters/horizontal_bar_meter.rb

@@ -1,56 +1,59 @@
 module Minichart
   class HorizontalBarMeter < Meter
+    class << self
+      def defaults
+        meter_defaults.merge width: 300, height: 50
+      end
+    end
+
     def build
       draw_bar
-      draw_zero_line if zero_line
-      draw_clipping_indicator if clipping_indicator and clipping?
+      draw_notches if options[:notches]
+      draw_clipping_indicator if options[:clipping_indicator] and clipping?
     end
 
   protected
 
     def draw_bar
-      x = if mode == :negative
-        width - bar_width
-      elsif mode == :dual
-        middle = width * 0.5
-        value >= 0 ? middle : middle - bar_width
-      else
-        0
-      end
+      x1 = x_for 0
+      x2 = x_for clamped_value
+      x = [x1, x2].min
 
-      element :rect, x: x, y: 0, height: height, width: bar_width, style: style
+      element :rect, x: x, y: 0, height: options[:height],
+        width: bar_width, style: style
     end
 
-    def draw_clipping_indicator
-      x = if mode == :positive or (mode == :dual and value > 0)
-        width - clipping_indicator_size
-      else
-        0
+    def draw_notches
+      options[:notches].each do |notch|
+        draw_notch notch
+        draw_notch -notch if mode == :dual and notch != 0
       end
+    end
 
-      element :rect, x: x, y: 0,
-        height: height, width: clipping_indicator_size,
-        fill: clipping_indicator_color, stroke_width: 0
-
+    def draw_notch(notch)
+      draw_vertical_line notch, stroke: options[:notch_thickness],
+        color: options[:notch_color]
     end
 
-    def draw_zero_line
-      x = if mode == :negative
-        width - zero_line_size
-      elsif mode == :dual
-        width / 2 - zero_line_size / 2
-      else
-        0
-      end
+    def draw_clipping_indicator
+      draw_vertical_line clamped_value,
+        stroke: options[:clipping_indicator_thickness],
+        color: options[:clipping_indicator_color]
+    end
 
-      element :rect, x: x, y: 0,
-        height: height, width: zero_line_size,
-        fill: zero_line_color, stroke_width: 0
+    def draw_vertical_line(target_value, color:, stroke:)
+      x = x_for target_value
 
+      element :line, x1: x, x2: x, y1: 0, y2: options[:height],
+        stroke: color, stroke_width: stroke
     end
 
     def width_factor
-      width / max.to_f
+      options[:width] / options[:max].to_f
+    end
+
+    def half_width
+      options[:width] * 0.5
     end
 
     def bar_width
@@ -60,5 +63,18 @@ module Minichart
         clamped_value.abs * width_factor
       end
     end
+
+    def x_for(target_value)
+      result = target_value.abs / options[:max].to_f * options[:width]
+
+      case mode
+      when :positive
+        result
+      when :negative
+        options[:width] - result
+      when :dual
+        target_value / options[:max].to_f * half_width + half_width
+      end
+    end
   end
 end

data/lib/minichart/meters/meter.rb

@@ -2,6 +2,22 @@ module Minichart
   # Base class for charts with a single value
   class Meter < Base
 
+    class << self
+      def meter_defaults
+        @meter_defaults ||= {
+          height: 50,
+          max: 100,
+          notches: [],
+          notch_thickness: 10,
+          notch_color: 'black',
+          clipping_indicator: false,
+          clipping_indicator_thickness: 20,
+          clipping_indicator_color: 'yellow',
+        }
+      end
+    end
+
+
   protected 
 
     def value
@@ -9,7 +25,7 @@ module Minichart
     end
 
     def clipping?
-      value > max || value < -max
+      value > options[:max] || value < -options[:max]
     end
 
     def mode
@@ -17,56 +33,32 @@ module Minichart
     end
 
     def mode!
-      opts[:mode] ||= :auto
+      options[:mode] ||= :auto
 
-      if opts[:mode] == :auto
+      if options[:mode] == :auto
         value >= 0 ? :positive : :negative
       else
-        opts[:mode].to_sym
+        options[:mode].to_sym
       end
     end
 
-    def max
-      opts[:max] ||= 100
-    end
-
-    def zero_line
-      opts[:zero_line]
-    end
-
-    def zero_line_size
-      opts[:zero_line_size] ||= 6
-    end
-
-    def zero_line_color
-      opts[:zero_line_color] ||= 'black'
-    end
-
-    def clipping_indicator
-      opts[:clipping_indicator]
-    end
-
-    def clipping_indicator_size
-      opts[:clipping_indicator_size] ||= 6
-    end
-
-    def clipping_indicator_color
-      opts[:clipping_indicator_color] ||= 'yellow'
-    end
-
     def clamped_value
       case mode
       when :positive
-        value.clamp 0, max
+        value.clamp 0, options[:max]
       when :negative
-        value.clamp -max, 0
+        value.clamp -options[:max], 0
       when :dual
-        value.clamp -max, max
+        value.clamp -options[:max], options[:max]
       end
     end
 
     def style
-      { fill: color, stroke_width: stroke, stroke: background }
+      {
+        fill: options[:color],
+        stroke_width: options[:stroke],
+        stroke: options[:background]
+      }
     end
 
   end

data/lib/minichart/meters/vertical_bar_meter.rb

@@ -1,64 +1,59 @@
 module Minichart
   class VerticalBarMeter < Meter
+    class << self
+      def defaults
+        meter_defaults.merge width: 50, height: 300
+      end
+    end
+    
     def build
       draw_bar
-      draw_zero_line if zero_line
-      draw_clipping_indicator if clipping_indicator and clipping?
+      draw_notches if options[:notches]
+      draw_clipping_indicator if options[:clipping_indicator] and clipping?
     end
 
   protected
 
-    def width
-      opts[:width] ||= 100
-    end
+    def draw_bar
+      y1 = y_for 0
+      y2 = y_for clamped_value
+      y = [y1, y2].min
 
-    def height
-      opts[:height] ||= (aspect_ratio * width).round
+      element :rect, x: 0, y: y, height: bar_height,
+        width: options[:width], style: style
     end
 
-    def draw_bar
-      y = if mode == :positive
-        height - bar_height
-      elsif mode == :dual
-        middle = height * 0.5
-        value >= 0 ? middle - bar_height : middle
-      else
-        0
+    def draw_notches
+      options[:notches].each do |notch|
+        draw_notch notch
+        draw_notch -notch if mode == :dual and notch != 0
       end
+    end
 
-      element :rect, x: 0, y: y, height: bar_height, width: width, style: style
+    def draw_notch(notch)
+      draw_horizontal_line notch, stroke: options[:notch_thickness],
+        color: options[:notch_color]
     end
 
     def draw_clipping_indicator
-      y = if mode == :negative or (mode == :dual and value < 0)
-        height - clipping_indicator_size
-      else
-        0
-      end
-
-      element :rect, x: 0, y: y,
-        height: clipping_indicator_size, width: width,
-        fill: clipping_indicator_color, stroke_width: 0
-
+      draw_horizontal_line clamped_value,
+        stroke: options[:clipping_indicator_thickness],
+        color: options[:clipping_indicator_color]
     end
 
-    def draw_zero_line
-      y = if mode == :positive
-        height - zero_line_size
-      elsif mode == :dual
-        height / 2 - zero_line_size / 2
-      else
-        0
-      end
-
-      element :rect, x: 0, y: y,
-        height: zero_line_size, width: width,
-        fill: zero_line_color, stroke_width: 0
+    def draw_horizontal_line(target_value, color:, stroke:)
+      y = y_for target_value
 
+      element :line, x1: 0, x2: options[:width], y1: y, y2: y,
+        stroke: color, stroke_width: stroke
     end
 
     def height_factor
-      height / max.to_f
+      options[:height] / options[:max].to_f
+    end
+
+    def half_height
+      options[:height] * 0.5
     end
 
     def bar_height
@@ -68,5 +63,18 @@ module Minichart
         clamped_value.abs * height_factor
       end
     end
+
+    def y_for(target_value)
+      result = target_value.abs / options[:max].to_f * options[:height]
+
+      case mode
+      when :positive
+        options[:height] - result
+      when :negative
+        result
+      when :dual
+        options[:height] - (target_value / options[:max].to_f * half_height + half_height)
+      end
+    end
   end
 end

data/lib/minichart/version.rb

@@ -1,3 +1,3 @@
 module Minichart
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minichart
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Danny Ben Shitrit