rails_charts 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d37477aa0733f7871c04744cd0ac01c4364210bbb115baa68926cc28900c9f7d
+  data.tar.gz: 10377955bf42d126819dc8422b96a1519ccb66a2ee96678d5268af60e2c00d77
+SHA512:
+  metadata.gz: 9e1745b0e47ed759fcbae21a00a888b4b884011a1b6807904b43273cb2b5749920370112a5548244bf9c0d17af28c400d43af0fb75f21657db8a41a430d1a445
+  data.tar.gz: 163f8f54a5f6edd7659f3d560c14713df15c4c3bcd123a66420f6fe10aecd3ef8af003db8ab9ab8582253f7408c9703cc1f073b0fa700e38e028a3de5d4547a6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,487 @@
+# Rails Charts
+
+![Charts](docs/all.jpg)
+
+One more gem to build nice charts for your Ruby on Rails application.
+
+With it you can build various types of charts Apache eCharts library (v. 5.3.2). This gem simplifies interface and adding few helpers to start adding charts in your app with just a few lines of code.
+
+What you can build with it:
+
+- line chart
+- area chart
+- bar chart
+- donut chart
+- pie chart
+- radar chart
+- calendar chart
+- candlestick chart
+- funnel chart
+- gauge chart
+- parallel chart
+- sankey chart
+- scatter chart
+- stacked bar chart
+- custom chart
+
+In most cases with one line of code you can have a nice chart. The idea of this gem was inspired by [Charkick](https://github.com/ankane/chartkick) gem which is great and allows you to build charts very quickly. It works the best with cooperation of [groupdate](https://github.com/ankane/groupdate) gem. Unfortunatelly it's missing many needed types of charts or other customization options.
+
+This implementation have more options and similar "interface" how to build charts (thanks to more Apache eCharts).
+
+1) add gem in Gemfile, 
+```ruby
+gem "rails_charts"
+```
+2) add JS, for example in `application.js`
+
+```js
+//= require rails_charts/echarts.min.js
+//= require rails_charts/theme/vintage.js
+```
+
+Note you can specify different themes.
+
+3) add your first chart 
+```ruby
+<%= line_chart User.group(:age).count %>
+```
+4) customize charts if needed. See available options or [official documentation](https://echarts.apache.org/examples/en/index.html). 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_charts"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+### Sprockets
+
+1) add eCharts in main JS bundle, e.g. `app/assets/javascripts/application.js`
+
+```javascript
+//= require rails_charts/echarts.min.js
+//= require rails_charts/theme/dark.js
+```
+
+2) start using :)
+
+### Importmaps
+
+1) change `config/importmap.rb`
+
+```ruby
+pin "rails_charts/echarts.min.js", to: "rails_charts/echarts.min.js", preload: true
+pin "rails_charts/theme/dark.js", to: "rails_charts/theme/dark.js", preload: true
+```
+
+2) change manifest `app/assets/config/manifest.js`
+
+```javascript
+//= link rails_charts/echarts.min.js
+//= link rails_charts/theme/dark.js
+```
+
+3) add eCharts in main JS 
+
+```javascript
+import "rails_charts/echarts.min.js"
+```
+
+4) start using :)
+
+## Options
+
+```ruby
+<%= link_chart data, {
+  width: '250px',
+  height: '250px',
+  theme: 'dark',
+  class: 'chart-container-class',
+  style: 'padding: 10px'
+} %>
+```
+
+Available options:
+
+```
+width: specify width of the chart
+height: specify height of the chart
+theme: specify theme of the chart (available themes examples https://echarts.apache.org/en/download-theme.html)
+class: specify container's CSS class
+id: specify container's ID
+style: add inline style
+debug: for gem development useful if you want to pause somewhere in the code
+vertical: applicable for some types of charts
+code: to see output code what is generated to see the chart, useful for debugging
+options: {...}, nested hash, specify additional eCharts options
+```
+
+Apache eCharts options - https://echarts.apache.org/en/option.html#title.
+
+If you need to format tooltip (or other javascript function as an option) you can pass a JS function, but you need to wrap it like:
+
+```ruby
+  options: {
+    tooltip: {
+      valueFormatter: RailsCharts::Javascript.new("(value) => '$' + Math.round(value)")
+    }
+  }
+```
+
+## Charts
+
+All examples available in https://github.com/railsjazz/rails_charts/tree/main/test/dummy/app/views/home. You can see more examples if you clone this repo and start a dummy app.
+
+Every chart has a built in default configuration for tooltips, or other options (sample https://github.com/railsjazz/rails_charts/blob/main/lib/rails_charts/line_chart.rb#L64-L75). This is just to simplify usage of this gem. In the future the plan is to have it configured in initializer.
+
+### Area Chart
+
+![Area Chart](docs/area_chart.png)
+
+```ruby
+<%= area_chart User.distinct.pluck(:role).map{|e| {name: e, data: User.where(role: e).group_by_day(:created_at).count} } %>
+```
+
+### Line Chart
+
+![Line Chart](docs/line_chart.png)
+
+```ruby
+<%= line_chart User.group(:age).count, class: 'box', 
+  options: {
+    title: {
+      text: "People count by age",
+      left: 'center'
+    },
+  }
+%>
+```
+
+### Bar Chart
+
+![Bar Chart](docs/bar_chart.png)
+
+```ruby
+<%= bar_chart User.group(:role).average(:age),
+  class: 'box',
+  theme: 'sakura',
+  options: {
+    series: { 
+      barWidth: '50%'
+    },
+    tooltip: {
+      valueFormatter: RailsCharts::Javascript.new("(value) => '$' + Math.round(value)")
+    }
+  }
+%>
+```
+
+### Calendar Chart
+
+![Calendar Chart](docs/calendar_chart.png)
+
+```ruby
+<%= calendar_chart Commit.for_calendar_chart,
+  class: 'box',
+  options: {
+    visualMap: {
+      show: true,
+      min: 0,
+      max: 40,
+      orient: 'horizontal'
+    },
+    calendar: [{
+      range: '2021',
+    },]
+  }
+%>
+
+```
+
+### Candlestick Chart
+
+![Candlestick Chart](docs/candlestick_chart.png)
+
+```ruby
+<%= candlestick_chart({
+    '2017-10-24' => [20, 34, 10, 38],
+    '2017-10-25' => [40, 35, 30, 50],
+    '2017-10-26' => [31, 38, 33, 44],
+    '2017-10-27' => [38, 15, 5, 42]
+  },
+  class: 'box',
+  theme: 'roma',
+  options: {
+    xAxis: {
+      axisTick: {
+        alignWithLabel: true
+      }
+    }
+  })
+%>
+```
+
+### Funnel Chart
+
+![Funnel Chart](docs/funnel_chart.png)
+
+```ruby
+<%= funnel_chart User.get_funnel_sample_data,
+  class: 'box',
+  height: '400px',
+  options: {
+    title: {
+      text: 'Demo',
+      left: 'center'
+    }
+  }
+%>
+```
+
+### Gauge Chart
+
+![Gauge Chart](docs/gauge_chart.png)
+
+```ruby
+<%= gauge_chart User.get_gauge_sample_data,
+  class: 'box',
+  height: '400px',
+  options: {
+    title: {
+      text: 'Demo',
+      left: 'center'
+    }
+  }
+%>
+```
+
+### Parallel Chart
+
+![Parallel Chart](docs/parallel_chart.png)
+
+```ruby
+<div class="box">
+  <%= parallel_chart [
+    [1, 2, 1, "Ruby"],
+    [2, 3, 2, "JavaScript"],
+    [3, 1, 3, "C#"]
+  ], {
+    options: {
+      parallelAxis: [
+        { dim: 0, name: '2019', inverse: true, minInterval: 1, min: 1, nameTextStyle: { fontSize: 16 }, axisLabel: { fontSize: 16 } },
+        { dim: 1, name: '2020', inverse: true, minInterval: 1, min: 1, nameTextStyle: { fontSize: 16 }, axisLabel: { fontSize: 16 } },
+        { dim: 2, name: '2021', inverse: true, minInterval: 1, min: 1, nameTextStyle: { fontSize: 16 }, axisLabel: { fontSize: 16 } },
+        { dim: 3, type: "category", name: 'Language', data: ["Ruby", "JavaScript", "C#"], inverse: true, nameTextStyle: { fontSize: 16 }, axisLabel: { fontSize: 14 } },
+      ]
+    }
+  }
+  %>
+</div>
+```
+
+### Donut Chart
+
+![Donut Chart](docs/donut_chart.png)
+
+```ruby
+<%= donut_chart User.group(:role).count, 
+  class: 'box',
+  options: {
+    legend: {
+      bottom: '0'
+    },
+    emphasis: { 
+      itemStyle: {
+        shadowBlur: 10,
+        shadowOffsetX: 0,
+        shadowColor: 'rgba(0, 0, 0, 0.5)'
+      } 
+    }
+  }
+%>
+```
+
+### Pie Chart
+
+![Pie Chart](docs/pie_chart.png)
+
+```ruby
+<%= pie_chart User.group(:role).count, 
+  class: 'box',
+  options: {
+    legend: { orient: 'vertical', left: 'left' }
+  }
+%>
+```
+
+### Radar Chart
+
+![Radar Chart](docs/radar_chart.png)
+
+```ruby
+<%= radar_chart User.get_data_for_radar_chart,
+  class: 'box',
+  options: {
+    legend: {
+      data: ['Average Salaries', 'Maximum Salary'],
+      orient: 'vertical',
+      left: '20%'
+    }
+  }
+%>
+```
+
+### Sankey Chart
+
+![Sankey Chart](docs/sankey_chart.png)
+
+```ruby
+<%= sankey_chart({
+    data: [
+      {name: 'Ruby'}, {name: 'HTML'}, {name: 'JS'}, {name: 'Good'}, {name: 'Bad'}, {name: 'CSS'}, {name: 'PHP'}, {name: 'Frontend'}, {name: 'Backend'}
+    ],
+    links: [
+      {
+        source: 'Ruby',
+        target: 'Good',
+        value: 1
+      },
+      {
+        source: 'HTML',
+        target: 'Good',
+        value: 1
+      },  
+      {
+        source: 'JS',
+        target: 'Good',
+        value: 1
+      },  
+      {
+        source: 'CSS',
+        target: 'Good',
+        value: 1
+      },
+      {
+        source: 'PHP',
+        target: 'Bad',
+        value: 1
+      },
+      {
+        source: 'Good',
+        target: 'Backend',
+        value: 1
+      },         
+      {
+        source: 'Good',
+        target: 'Frontend',
+        value: 3
+      },
+      {
+        source: 'Bad',
+        target: 'Backend',
+        value: 1
+      },             
+    ]
+  }, {
+    options: {
+
+    }
+  })
+  %>
+```
+
+### Scatter Chart
+
+![Scatter Chart](docs/scatter_chart.png)
+
+```ruby
+<%= scatter_chart [
+    { name: 'John', data: User.random_scatter_chart(500, 200) },
+    { name: 'Bob', data: User.random_scatter_chart(500, 1000) },
+  ],
+  {
+    class: 'box',
+    options: {
+      xAxis: {
+        name: 'Distance'
+      },
+      yAxis: {
+        name: 'Sales'
+      },          
+      legend: {
+        data: [
+          {name: 'John'},
+          {name: 'Bob'},
+        ]
+      },
+    },
+  }
+%>
+```
+
+### Stacked bar Chart
+
+![Stacked bar Chart](docs/stacked_bar_chart.png)
+
+```ruby
+<%= stacked_bar_chart [
+    { name: 'high priority', data: Account.high_priority.group_by_month(:created_at, format: "%b %Y").count },
+    { name: 'low priority', data: Account.low_priority.group_by_month(:created_at, format: "%b %Y").count }
+  ],
+  {
+    options: {
+      title: {
+        text: "Popular vs Unpopular"
+      },
+    },
+    class: 'box',
+    vertical: true
+  }
+%>
+```
+
+### Custom Chart
+
+![Custom Chart](docs/custom_chart.png)
+
+```ruby
+<%= custom_chart {...raw JS options ...} %>
+```
+
+## Contributing
+
+You are welcome to contributes. Some open tasks:
+
+- importmaps support?
+- webpacker support
+- add more specs
+- add more examples to the dummy app
+- customization, options overides, default values?
+- every "5sec" refresh
+- remote data
+- how to access chart from JS
+- better documentation how to specify theme, locale, etc
+- more examples with data structure
+- add github actions
+- add info about initializer and it's configuration
+- specify info about default configs per chart
+- add support for CSP similar to https://github.com/ankane/chartkick/blob/master/lib/chartkick/helper.rb#L55
+- example of how to build multiple-chart charts
+
+### Development and testing
+
+`test/dummy/bin/rails s` - to start dummy app.
+
+`rspec` - to run specs.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Gem is using https://echarts.apache.org/ to build charts.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/rails_charts/area_chart.rb

@@ -0,0 +1,31 @@
+module RailsCharts
+  class AreaChart < LineChart
+
+    def defaults
+      {
+        tooltip: {
+          trigger: 'axis'
+        },      
+        xAxis: {
+          boundaryGap: false
+        },
+        series: {
+          areaStyle: {},
+          stack: 'Total'
+        },
+        toolbox: {
+          feature: {
+            saveAsImage: {}
+          },
+        }
+      }
+    end
+
+    def x_axis
+      {
+        type: 'category'
+      }
+    end    
+
+  end
+end

data/lib/rails_charts/bar_chart.rb

@@ -0,0 +1,25 @@
+module RailsCharts
+  class BarChart < LineChart
+    
+    def type
+      'bar'
+    end
+
+    def defaults
+      {
+        tooltip: {
+          trigger: 'axis',
+          axisPointer: {
+            type: 'shadow'
+          }        
+        },
+        toolbox: {
+          feature: {
+            saveAsImage: {}
+          },
+        }     
+      }
+    end
+  
+  end
+end

data/lib/rails_charts/base_chart.rb

@@ -0,0 +1,123 @@
+module RailsCharts
+  class BaseChart
+    using RubyExt
+
+    attr_reader :data, :options, :container_id, :defaults
+    attr_reader :width, :height, :style, :klass, :theme, :locale
+    attr_reader :other_options, :debug
+    attr_reader :vertical
+
+    def initialize(data, options = {})
+      @data          = data
+      @options       = options
+      @other_options = options.delete(:options).presence || {}
+      @defaults      = RailsCharts.defaults[self.class].presence || {}
+
+      @container_id  = options.delete(:id).presence || "rails_charts_#{Digest::SHA1.hexdigest([Time.now, rand].join)}"
+
+      @width         = options.delete(:width).presence || RailsCharts.options[:width]
+      @height        = options.delete(:height).presence || RailsCharts.options[:height]
+      @theme         = options.delete(:theme).presence || RailsCharts.options[:theme]
+      @locale        = options.delete(:locale).presence || RailsCharts.options[:locale]
+      @klass         = options.delete(:class).presence || RailsCharts.options[:class]
+      @style         = options.delete(:style).presence || RailsCharts.options[:style]
+     
+      @debug         = options.delete(:debug)
+
+      @vertical      = options.delete(:vertical).presence
+    end
+
+    def js_code
+      style_css = []
+      style_css << "width: #{width}" if width
+      style_css << "height: #{height}" if height
+      style_css << style
+
+      %Q{
+        <div id="#{container_id}" class="#{klass}" style="#{style_css.compact.join('; ')}">
+          <script>
+            if (!window.RailsCharts) {
+              window.RailsCharts = {}
+              window.RailsCharts.charts = {}
+            }
+
+            function init#{container_id}(e) {
+              if (document.documentElement.hasAttribute("data-turbolinks-preview")) return;
+              if (document.documentElement.hasAttribute("data-turbo-preview")) return;
+    
+              <!-- #{self.class} -->
+              var chartDom = document.getElementById('#{container_id}');
+
+              if (!chartDom) { return }
+  
+              var lib = ("echarts" in window) ? window.echarts : echarts;
+              var chart = lib.init(chartDom, #{theme.to_json}, { "locale": #{locale.to_json} });
+              var option = #{option};
+              option && chart.setOption(option);
+
+              window.RailsCharts.charts["#{container_id}"] = chart;
+            }
+
+            function destroy#{container_id}(e) {
+              var chart = window.RailsCharts.charts["#{container_id}"];
+              if (chart) {
+                chart.dispose()
+              }
+              delete window.RailsCharts.charts["#{container_id}"];
+            }
+
+            window.addEventListener('load', init#{container_id});
+            window.addEventListener('turbo:load', init#{container_id});
+            window.addEventListener('turbolinks:load', init#{container_id});
+
+            document.addEventListener("turbolinks:before-render", destroy#{container_id});
+            document.addEventListener("turbo:before-render", destroy#{container_id});
+          </script>
+        </div>
+      }
+    end
+
+    def option
+      str = build_options.to_json
+      Thread.current[:rails_charts_js_code].each do |k, v|
+        str.gsub!("\"#{k}\"", v)
+      end if Thread.current[:rails_charts_js_code]
+      str
+    end
+
+    def build_options
+      hash = {}
+
+      hash[:series] = Array.wrap(generate_series_options)
+
+      hash = hash.complex_merge(axises)
+      hash = hash.complex_merge(defaults)
+      hash = hash.complex_merge(other_options)
+
+      hash
+    end
+
+    def axises
+      if self.vertical
+        {
+          xAxis: y_axis,
+          yAxis: x_axis,
+        }
+      else
+        {
+          xAxis: x_axis,
+          yAxis: y_axis,
+        }
+      end
+    end
+
+    def x_axis
+      []
+    end
+
+    def y_axis
+      []
+    end
+
+  end
+end