apexcharts 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a866b4e6545c50cf331fe31f383f8493ee2caf991e7e034654a011cd41d824ac
-  data.tar.gz: fd243a66fa09eb5ccbb7c9255dd536e6948f7b0f22d496986cd2788d966aec31
+  metadata.gz: 430b940ba031ce379c1d35a6685ba8ad19d62922c91d9d8a806779f1c4282bbd
+  data.tar.gz: 5d1bae083b7c949b1d0a984bcb43e64096558cdcf550df3b8a507eec58e64405
 SHA512:
-  metadata.gz: 40c1bf094d88f7bc524fefab6be0dc424454f552a490e83cd58df176dd236cdf799681a0e46af74548f176761681a6e69ab82fd67b7c1f9d2f5286f88b5aa3b1
-  data.tar.gz: 0cf54ed3c2d01f5991bdc1578c8a5b2af829fe2f936eb86d76a8d96f19629219119b70eefd56cd7fd25b5c8df0bc04083883825168f3e8f8c01c304f024c8d27
+  metadata.gz: fc51493d941efd81893b7a847e7939149897b0c8c44f87a04a4d00f5466d5c629862353aad59e7a3df0bcab768926e674bb2f3a00b1b2adf6f987b324a540002
+  data.tar.gz: 272c361ad29c2b5456d62b7339809cbd1e664de015275eecd043127211627732b9ce50df5f68df2b5ce8d11a316fc208037f7a8bd4ac4383aaedd25712449bec

data/README.md

@@ -9,6 +9,13 @@
 </p>
 
 
+## What is this?
+
+ApexCharts.rb is a ruby gem that wraps a JavaScript charting library called with the same name,
+[apexcharts.js](https://github.com/apexcharts/apexcharts.js), that's going to give you
+a beautiful, interactive, and responsive charts for your ruby app.
+
+
 ## Usage
 
 ### Cartesian Charts
@@ -37,8 +44,9 @@ and I'll get the data in this format:
   ..
 }
 ```
-PS: `Property` can be any model you have and `inactive` and `active` 
-are just some normal ActiveRecord scopes.  
+PS: `Property` can be any model you have and `inactive` and `active`
+are just some normal ActiveRecord scopes. Keep scrolling down to see
+accepted data formats.  
 
 Example options used for cartesian charts:
 
@@ -58,7 +66,7 @@ Example options used for cartesian charts:
 ```erb
 <%= line_chart(series, options) %>
 ```
-![Example Line Chart](images/line_chart.png)
+![Example Line Chart](images/line_chart.gif)
 
 
 #### Stepline Chart
@@ -66,7 +74,7 @@ Example options used for cartesian charts:
 ```erb
 <%= line_chart(series, {**options, theme: 'palette7', curve: 'stepline'}) %>
 ```
-![Example Stepline Chart](images/stepline_chart.png)
+![Example Stepline Chart](images/stepline_chart.gif)
 
 
 #### Area Chart
@@ -74,7 +82,7 @@ Example options used for cartesian charts:
 ```erb
 <%= area_chart(series, {**options, theme: 'palette5'}) %>
 ```
-![Example Area Chart](images/area_chart.png)
+![Example Area Chart](images/area_chart.gif)
 
 
 #### Column Chart
@@ -82,7 +90,7 @@ Example options used for cartesian charts:
 ```erb
 <%= column_chart(series, {**options, theme: 'palette4'}) %>
 ```
-![Example Column Chart](images/column_chart.png)
+![Example Column Chart](images/column_chart.gif)
 
 
 #### Bar Chart
@@ -90,7 +98,7 @@ Example options used for cartesian charts:
 ```erb
 <%= bar_chart(series, {**options, xtitle: 'Properties', ytitle: 'Week', height: 800, theme: 'palette7'}) %>
 ```
-![Example Bar Chart](images/bar_chart.png)
+![Example Bar Chart](images/bar_chart.gif)
 
 
 #### Scatter Chart
@@ -98,13 +106,54 @@ Example options used for cartesian charts:
 ```erb
 <%= scatter_chart(series, {**options, theme: 'palette3'}) %>
 ```
-![Example Scatter Chart](images/scatter_chart.png)
+![Example Scatter Chart](images/scatter_chart.gif)
+
+
+#### Candlestick Chart
+Candlestick chart is typically used to illustrate movements in the price of a
+financial instrument over time. This chart is also popular by the name "ohlc chart".
+That's why you can call it with `ohlc_chart` too.  
+So, here's how you make it.
+
+Given:
+```erb
+<%
+  require 'date'
+
+  def ohlc(ary)
+    [rand(ary.min..ary.max), ary.max, ary.min, rand(ary.min..ary.max)]
+  end
+
+  candlestick_data = 50.times.map do |i|
+    [Date.today - 50 + i, ohlc(Array.new(2){ rand(6570..6650) })]
+  end.to_h
+
+  candlestick_options = {
+    plot_options: {
+      candlestick: {
+        colors: {
+          upward: '#3C90EB',
+          downward: '#DF7D46'
+        }
+      }
+    }
+  }
+%>
+```
+You can make candlestick chart with this:
+```erb
+<%= candlestick_chart(candlestick_data, candlestick_options) %>
+```
+![Example Candlestick Chart](images/candlestick_chart.gif)
+
+Real life candlestick chart probably don't look like that.
+That's because I just use random sets of numbers as the data.
 
 
 #### Mixed Charts
 
-You can mix charts by using `mixed_charts` or `combo_charts` methods. For example:  
-Given that:
+You can mix charts by using `mixed_charts` or `combo_charts` methods.
+For example, given that:
 ```ruby
 @total_properties = Property.group_by_week(:created_at).count
 ```
@@ -155,7 +204,21 @@ You can synchronize charts by using `syncing_charts` or `synchronized_charts` me
 ![Example Brush Chart](images/brush_chart.gif)
 
 
-#### Heatmap Chart
+#### Annotations
+
+All cartesian charts can have annotations, for example:
+
+```erb
+<%= area_chart(series, {**options, theme: 'palette9'}) do %>
+  <% x_annotation(value: ('2019-01-06'..'2019-02-24'), text: "Busy Time", color: 'green') %>
+  <% y_annotation(value: 29, text: "Max Properties", color: 'blue') %>
+  <% point_annotation(value: ['2018-10-07', 24], text: "First Peak", color: 'magenta') %>
+<% end %>
+```
+![Example Area Chart with Annotations](images/chart_with_annotations.gif)
+
+
+### Heatmap Chart
 
 ```erb
 <% heatmap_series = 17.downto(10).map do |n|
@@ -171,7 +234,28 @@ end %>
 ![Example Heatmap Chart](images/heatmap_chart.png)
 
 
-#### Bubble Chart
+### Radar Chart
+
+```erb
+<% radar_series = [
+  {
+    name: "What it should be",
+    data: { "Code review"=>10, "Issues"=>5, "Pull request"=>25, "Commits"=>60 }
+  },
+  {
+    name: "What it really is",
+    data: { "Code review"=>1, "Issues"=>3, "Pull request"=>7, "Commits"=>89 }
+  }
+] %>
+<%= radar_chart(
+  radar_series,
+  {title: "GitHub Radar", markers: {size: 4}, theme: 'palette4'}
+) %>
+```
+![Example Radar Chart](images/radar_chart.gif)
+
+
+### Bubble Chart
 
 ```erb
 <% bubble_series = (1..4).map do |n|
@@ -185,20 +269,6 @@ end %>
 ![Example Bubble Chart](images/bubble_chart.png)
 
 
-#### Annotations
-
-All cartesian charts can have annotations, for example:
-
-```erb
-<%= area_chart(series, {**options, theme: 'palette9'}) do %>
-  <% x_annotation(value: ('2019-01-06'..'2019-02-24'), text: "Busy Time", color: 'green') %>
-  <% y_annotation(value: 29, text: "Max Properties", color: 'blue') %>
-  <% point_annotation(value: ['2018-10-07', 24], text: "First Peak", color: 'magenta') %>
-<% end %>
-```
-![Example Area Chart with Annotations](images/chart_with_annotations.png)
-
-
 ### Polar Charts
 
 #### Pie Chart
@@ -217,7 +287,7 @@ All cartesian charts can have annotations, for example:
 #### Donut Chart
 
 ```erb
-<%= donut_chart([25, 100, 200, 125], theme: 'palette4' %>
+<%= donut_chart([25, 100, 200, 125], theme: 'palette4') %>
 ```
 ![Example Pie Chart](images/donut_chart.gif)
 
@@ -236,10 +306,121 @@ Also called `circle_chart`.
 ![Example Circle Chart](images/radial_bar_chart.gif)
 
 
+## Data Formats
+
+### Cartesian Charts
+The data format for line, stepline, area, column, bar, and scatter
+charts should be in following format **per-series**:
+
+```ruby
+{
+  <x value> => <y value>,
+  <x value> => <y value>,
+  ...
+}
+```
+
+or this:
+
+```ruby
+[
+  [<x value>, <y value>],
+  [<x value>, <y value>],
+  ...
+]
+```
+
+#### Candlestick Chart
+Candlestick chart is just like other cartesian charts, only the y value is
+an array of 4 members which called the OHLC (Open-High-Low-Close):
+
+```ruby
+{
+  <x value> => [<Open>, <High>, <Low>, <Close>],
+  <x value> => [<Open>, <High>, <Low>, <Close>],
+  ...
+}
+```
+
+or this:
+
+```ruby
+[
+  [<x value>, [<Open>, <High>, <Low>, <Close>]],
+  [<x value>, [<Open>, <High>, <Low>, <Close>]],
+  ...
+]
+```
+
+### Heatmap Chart
+The data format for heatmap chart **per-series** is similar to cartesian
+charts. But instead of y values they are heat values. The series names will
+be the y values.
+
+```ruby
+{
+  <x value> => <heat value>,
+  <x value> => <heat value>,
+  ...
+}
+```
+
+or this:
+
+```ruby
+[
+  [<x value>, <heat value>],
+  [<x value>, <heat value>],
+  ...
+]
+```
+
+### Radar Chart
+The data format for radar chart **per-series** is also similar but instead
+of x values they are variables and instead of y values they are the only
+values for the variables with type of Numeric.
+
+```ruby
+{
+  <variable> => <value>,
+  <variable> => <value>,
+  ...
+}
+```
+
+or this:
+
+```ruby
+[
+  [<variable>, <value>],
+  [<variable>, <value>],
+  ...
+]
+```
+
+
+### Bubble Chart
+Bubble chart is similar to scatter chart, only they have one more value
+for bubble size:
+
+```ruby
+[
+  [<x value>, <bubble size>, <y value>],
+  [<x value>, <bubble size>, <y value>],
+  ...
+]
+```
+
+### Polar Charts
+The data format for donut, pie, and radial bar are the simplest. They are
+just any single value of type Numeric.
+
+
 ## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
+gem 'groupdate' # optional
 gem 'apexcharts'
 ```
 
@@ -252,7 +433,6 @@ $ bundle
 ## Web Support
 
 ### Rails
-
 After installing the gem, require it in your `app/assets/javascripts/application.js`.
 ```js
 //= require 'apexcharts'
@@ -267,13 +447,22 @@ and then require it in your `app/javascript/packs/application.js`.
 require("apexcharts")
 ```
 
-## Objective
-- To bring out as much apexcharts.js capabilities as possible but in ruby ways.
+### HTML+ERB
+After installing the gem, insert this to the top of your .html.erb files:
+
+```html+erb
+<script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
+<% require 'apexcharts' %>
+```
+
 
 ## TODOs
-- Other charts (radar, heatmap, candlestick, etc.)
+- Replace dependency `smart_kv` with `dry-schema`
+- Create reusable theme palette
+- Add more features (e.g. gradient line, background image, etc.)
+- Range bar chart
 - Support other ruby frameworks (sinatra, hanami, etc.)
-- Render as Vue or React elements
+
 
 ## Contributing
 Everyone is encouraged to help improve this project by:
@@ -281,6 +470,16 @@ Everyone is encouraged to help improve this project by:
 - Fixing bugs and submiting pull requests
 - Fixing documentation
 - Suggesting new features
+- Implementing TODOs above
+
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+## Like the charts?
+Consider donating to the author of apexcharts.js to support his awesome library.
+This project wouldn't be possible without it.
+
+Become a sponsor on [Patreon](https://patreon.com/junedchhipa).  
+One time donation on [PayPal](https://paypal.me/junedchhipa)

data/lib/apexcharts.rb

@@ -1,2 +1,4 @@
-require 'apexcharts/support/rails' if defined?(Rails)
+# frozen_string_literal: true
+
+require 'apexcharts/support/rails' if defined? Rails
 require 'apexcharts/helper'

data/lib/apexcharts/charts.rb

@@ -1,11 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'charts/base'
 require_relative 'charts/cartesian'
 require_relative 'charts/line'
 require_relative 'charts/area'
 require_relative 'charts/bar'
 require_relative 'charts/column'
 require_relative 'charts/scatter'
+require_relative 'charts/candlestick'
 require_relative 'charts/heatmap'
 require_relative 'charts/bubble'
+require_relative 'charts/radar'
 require_relative 'charts/mixed'
 require_relative 'charts/syncing'
 require_relative 'charts/polar'

data/lib/apexcharts/charts/area.rb

@@ -1,4 +1,6 @@
-module Apexcharts
+# frozen_string_literal: true
+
+module ApexCharts
   class AreaChart < CartesianChart
     def chart_type
       'area'

data/lib/apexcharts/charts/bar.rb

@@ -1,4 +1,6 @@
-module Apexcharts
+# frozen_string_literal: true
+
+module ApexCharts
   class BarChart < CartesianChart
     def chart_type
       'bar'

data/lib/apexcharts/charts/base.rb

@@ -0,0 +1,34 @@
+module ApexCharts
+  class BaseChart
+    attr_reader :options, :series
+
+    def initialize data, options={}
+      @series = sanitize_data(data)
+      @options = Utils::Hash.deep_merge(
+                   build_options(x_sample, options),
+                   Utils::Hash.camelize_keys(
+                     {**@series, chart: {type: chart_type}}.compact
+                   )
+                 )
+    end
+
+    def render
+      ApexCharts::Renderer.render_default(options)
+    end
+
+    def chart_type
+    end
+
+  protected
+
+    def build_options(x_sample, options)
+      ApexCharts::OptionsBuilder.new(x_sample, options).build_options
+    end
+
+    def x_sample
+      series[:series][0][:data][0][:x]
+    end
+  end
+end
+
+