rcharts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 256aeff9d84f681b225b1a35cd613367c65e2406caf8ba1815214e690dc462a1
+  data.tar.gz: a2de1b9873a98beaa5e7d0cec25042a8a59d36ed6998d9f8005f48f9eb20e4c3
+SHA512:
+  metadata.gz: 531cd70794162b29f5b87c79ef64ea87ceb43f6b60d5f2967dfff5cbb723d9315084615bb353324fdc80c25d3f6dffea42913ac1254dd48ff89aba0b49cd80c2
+  data.tar.gz: 907ab23d72f376f6c8f15584ce4e54bf0386d7e2d85affb9fa0576ec01374866c04db8bd0a1c1afad98ede4b94f7ddfc6f698bad1e65889fdc866d38b9786aff

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Justin Malčić
+
+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,99 @@
+# RCharts
+
+RCharts is a charting library for Action View which produces JS-agnostic SVG charts.
+
+In the time since popular JS charting libraries were created, significant advances in CSS have made it possible
+to use the browser's rendering engine for more and more things where JS was previously unavoidable.
+Rather than starting from the assumption that client-side rendering in JS is inevitable for charts, RCharts builds
+on the premise that decent baseline functionality is now possible just with server-side rendering.
+
+Being able to lean on the browser's rendering engine results in visibly improved client-side rendering performance
+and eliminates the scope for undesirable interactions with other rendering in JS. This makes it possible to layer
+interactivity on top of charts much more reliably, because the chart is no different from the rest of the page.
+One possible progressive enhancement would be panning and zooming, using a Stimulus controller to send a request
+to the server and reload the chart with different parameters.
+
+RCharts was conceived specifically with Turbo morphing in mind. Because morphing is able to update pages and frames
+at the level of individual attributes, when CSS transitions are added to SVG elements, properties determining placement
+and size of elements can be animated like any other. Like other styling, you can control all aspects of the transitions
+using CSS, by overriding variables in the stylesheet provided or by using your own styles.
+
+To be useful to a wider audience, charting libraries need to be flexible enough to cover a wide range of use cases.
+RCharts aims to provide a comprehensive set of features that cover the most common use cases, with more to come.
+It currently supports:
+
+* Different chart types
+    * Line charts
+    * Bar charts
+    * Horizontal bar charts
+    * Area charts
+    * Scatter plots
+    * Combinations of the above
+* Proper value handling
+    * Stacked area and bar charts
+    * Smoothing for line and area charts (you can choose by how much but not the method)
+    * Negative values (e.g. with split series for stacked area charts)
+    * Masks for missing values
+* Various axis options
+    * Automatic axis ticks based on the type and values of provided data
+    * Axis labels formatted however you want
+    * Axis labels rotation and hiding to avoid overlap
+    * Axis titles
+    * Multiple parallel axes based on potentially different data
+* Tooltips and legends
+    * Tooltips containing whatever you want
+    * Legend with placement in all directions
+    * Custom series symbols and colours
+* Sparklines, by only rendering the chart itself
+* CSS that you can customise to your liking, both by setting variables and/or using your own styles
+
+## Usage
+
+The API is inspired by the venerable `ActionView::Helpers::FormBuilder`.
+
+To get started, take a look at the WIP docs for `RCharts::GraphHelper`, and also run the dummy app which shows
+the different chart types and how to combine them with morphing.
+
+```bash
+$ git clone "https://github.com/BuildingAtlas/rcharts.git"
+$ cd rcharts/test/dummy
+$ rails s
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rcharts'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Install the stylesheet:
+
+```bash
+$ rails rcharts:install
+```
+
+Finally, include the helper in `ApplicationHelper`:
+
+```ruby
+# app/helpers/application_helper.rb
+
+module ApplicationHelper
+  include RCharts::GraphHelper
+end
+```
+
+## Contributing
+
+Contributions are welcome, but please open an issue first to discuss what you would like to add or change.
+
+## License
+
+The gem is available as open source under the terms of the [MIT Licence](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+require 'bundler/gem_tasks'
+
+require 'sdoc'
+require 'rdoc/task'
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_files.include('README.md', 'app/**/*.rb', 'lib/**/*.rb')
+  rdoc.rdoc_dir = 'doc'
+  rdoc.options << '--format=sdoc'
+  rdoc.options << '--github'
+  rdoc.options << '--title=RCharts'
+  rdoc.options << '--main=README.md'
+  rdoc.template = 'rails'
+end

data/app/helpers/rcharts/graph_helper/axes/axis_element/styles.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Axes
+      class AxisElement
+        module Styles # :nodoc:
+          DEFAULT_BREAKPOINTS = { hiding: { even: 1.1, odd: 0.6 }, rotation: { half: 1.0, full: 0.9 } }.freeze
+
+          extend ActiveSupport::Concern
+
+          ROTATION_CSS = <<~CSS
+            @container (inline-size < calc(<%= min_row_characters %> * <%= half_rotation_breakpoint %>)) {
+              .rcharts-chart .axis[data-name="x"] {
+                .axis-ticks[data-axis="<%= axis_id %>"] .axis-tick-text {
+                  dominant-baseline: middle;
+                  rotate: -45deg;
+                  text-anchor: end;
+                }
+                .axis-ticks[data-axis="<%= axis_id %>"] {
+                  height: calc(<%= max_label_characters %> * sin(45deg));
+                }
+              }
+            }
+
+            @container (inline-size < calc(<%= min_row_characters %> * <%= full_rotation_breakpoint %>)) {
+            .rcharts-chart .axis[data-name="x"] {
+                .axis-ticks[data-axis="<%= axis_id %>"] .axis-tick-text {
+                  rotate: -90deg;
+                }
+                .axis-ticks[data-axis="<%= axis_id %>"] {
+                  height: <%= max_label_characters %>;
+                }
+              }
+            }
+          CSS
+
+          HIDING_CSS = <<~CSS
+            @container (inline-size < calc(<%= tick_count %> * <%= even_hiding_breakpoint %>)) {
+              .rcharts-chart .axis[data-name="x"] {
+                .axis-ticks[data-axis="<%= axis_id %>"] .axis-tick:nth-child(even) .axis-tick-text {
+                  opacity: 0;
+                }
+              }
+            }
+
+            @container (inline-size < calc(<%= tick_count %> * <%= odd_hiding_breakpoint %>)) {
+              .rcharts-chart .axis[data-name="x"] {
+                .axis-ticks[data-axis="<%= axis_id %>"] .axis-tick:nth-child(4n + 3) .axis-tick-text {
+                  opacity: 0;
+                }
+              }
+            }
+          CSS
+
+          included do
+            attribute :breakpoints, default: -> { {} }
+
+            private
+
+            def rendered_css
+              return unless horizontal?
+
+              ERB.new(ROTATION_CSS + HIDING_CSS)
+                 .result_with_hash(min_row_characters: "#{min_row_characters}ch",
+                                   max_label_characters: "#{max_label_characters}ch",
+                                   tick_count: "#{tick_count}lh",
+                                   **breakpoints,
+                                   axis_id:)
+                 .html_safe # rubocop:disable Rails/OutputSafety
+            end
+
+            def breakpoints
+              flatten_breakpoints(DEFAULT_BREAKPOINTS.deep_merge(super))
+            end
+
+            def flatten_breakpoints(hash)
+              hash.each_with_object({}) do |(key, value), result|
+                next result[key] = value unless value.is_a?(Hash)
+
+                value.each do |nested_key, nested_value|
+                  result[:"#{nested_key}_#{key}_breakpoint"] = nested_value
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/axes/axis_element.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Axes
+      class AxisElement < Element # :nodoc:
+        include Styles
+
+        attribute :name
+        attribute :index, :integer, default: 0
+        attribute :ticks, default: -> { {} }
+        attribute :label
+        attribute :horizontal, :boolean, default: false
+        attribute :character_scaling_factor, :float, default: 1.0
+
+        private
+
+        attr_accessor :max_label_characters
+
+        alias horizontal? horizontal
+
+        def tags(&block)
+          with_max_label_characters_from block do
+            style_tag + container_tag(&block)
+          end
+        end
+
+        def container_tag(&)
+          tag.div class: 'axis', data: { name:, index: } do
+            svg_tag(&) + label_tag
+          end
+        end
+
+        def svg_tag(&)
+          tag.svg class: 'axis-ticks', width: max_column_characters.try { "#{it * character_scaling_factor}ch" },
+                  data: { axis: axis_id } do
+            ticks.each do |position, value|
+              concat tick_tag_for(position, value, &)
+            end
+          end
+        end
+
+        def label_tag
+          return ''.html_safe unless label
+
+          render LabelElement.new(label:, horizontal: horizontal?)
+        end
+
+        def tick_tag_for(position, value, &)
+          render TickElement.new(inline_axis: name, inline_axis_index: index,
+                                 value:, position:), &
+        end
+
+        def style_tag
+          tag.style rendered_css
+        end
+
+        def max_column_characters
+          return if horizontal?
+
+          max_label_characters
+        end
+
+        def min_row_characters
+          max_label_characters.to_i * tick_count
+        end
+
+        def with_max_label_characters_from(proc, &block)
+          self.max_label_characters = ticks.values
+                                           .collect { |value| capture_length { proc&.call(value) || value.to_s } }
+                                           .max
+          block&.call.tap { self.max_label_characters = nil }
+        end
+
+        def capture_length(&)
+          strip_tags(capture(&)).squish.length
+        end
+
+        def axis_id
+          hash.abs
+        end
+
+        def tick_count
+          ticks.count + 1
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/axes/label_element.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Axes
+      class LabelElement < Element # :nodoc:
+        attribute :label
+        attribute :horizontal, :boolean
+
+        private
+
+        alias horizontal? horizontal
+
+        def tags
+          tag.svg class: 'axis-label', overflow: 'visible', width:, height: do
+            tag.svg x: '50%', y: '50%', overflow: 'visible' do
+              tag.text label, class: 'axis-label-text'
+            end
+          end
+        end
+
+        def width
+          horizontal? ? Percentage::MAX : '1lh'
+        end
+
+        def height
+          horizontal? ? '1lh' : Percentage::MAX
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/axes/tick_element.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Axes
+      class TickElement < Element # :nodoc:
+        attribute :value
+        attribute :position, :'rcharts/percentage', default: Percentage::MIN
+        attribute :inline_axis, :'rcharts/symbol'
+        attribute :inline_axis_index, :integer, default: 0
+
+        private
+
+        def tags(&block)
+          tag.svg class: 'axis-tick', x:, y: do
+            tag.text class: 'axis-tick-text', data: { inline_axis:, inline_axis_index: } do
+              block&.call(value) || value
+            end
+          end
+        end
+
+        def x
+          case inline_axis
+          when :x then position
+          else inline_axis_index.zero? ? Percentage::MAX : Percentage::MIN
+          end
+        end
+
+        def y
+          case inline_axis
+          when :x then Percentage::MIN
+          else Percentage::MAX - position
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/axes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Axes # :nodoc:
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/categories/bar_builder.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Categories
+      # = Bar Builder
+      class BarBuilder < ElementBuilder
+        attribute :name
+        attribute :inline_size, :'rcharts/percentage', default: Percentage::MAX
+        attribute :block_size, :'rcharts/percentage', default: Percentage::MAX
+        attribute :block_position, :'rcharts/percentage', default: Percentage::MIN
+        attribute :inline_index, :integer, default: 0
+        attribute :series_index, :integer, default: 0
+        attribute :horizontal, :boolean, default: false
+        attribute :series_options, default: -> { {} }
+
+        # Renders a bar segment. Passes through <tt>:data</tt>, and <tt>:aria</tt>, and <tt>:class</tt> options to the tag builder.
+        #   <%= graph_for @annual_sales do |graph| %>
+        #     <%= graph.category do |category| %>
+        #       <%= category.series do |series| %>
+        #         <%= series.bar %>
+        #       <% end %>
+        #     <% end %>
+        #   <% end %>
+        def bar(**)
+          render BarSegmentElement.new(inline_size:, block_size:, block_position:, inline_index:, series_index:,
+                                       horizontal:, series_options:, **)
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/categories/bar_segment_element.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Categories
+      class BarSegmentElement < Element # :nodoc:
+        attribute :horizontal, :boolean, default: false
+        attribute :inline_size, :'rcharts/percentage', default: Percentage::MAX
+        attribute :block_size, :'rcharts/percentage', default: Percentage::MAX
+        attribute :block_position, :'rcharts/percentage', default: Percentage::MIN
+        attribute :inline_index, :integer, default: 0
+        attribute :series_index, :integer, default: 0
+        attribute :series_options, default: -> { {} }
+
+        private
+
+        alias horizontal? horizontal
+
+        def tags
+          tag.rect x:, y:, height:, width:, class: ['series-shape', class_names, color_class], data:, aria:
+        end
+
+        def x
+          horizontal? ? block_position : inline_position
+        end
+
+        def y
+          horizontal? ? inline_position : Percentage::MAX - block_position
+        end
+
+        def height
+          horizontal? ? inline_size : block_size
+        end
+
+        def width
+          horizontal? ? block_size : inline_size
+        end
+
+        def inline_position
+          inline_size * inline_index
+        end
+
+        def color_class
+          series_options.fetch(:color_class, RCharts.color_class_for(series_index))
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/categories/bars_element.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Categories
+      class BarsElement < Element # :nodoc:
+        SPACING_FACTOR = 0.6
+
+        attribute :index, :integer, default: 0
+        attribute :values_count, :integer, default: 1
+        attribute :inline_position, :'rcharts/percentage', default: Percentage::MIN
+        attribute :horizontal, :boolean, default: false
+
+        private
+
+        alias horizontal? horizontal
+
+        def tags(&)
+          tag.svg x:, y:, width:, height:, class: 'category', &
+        end
+
+        def x
+          adjusted_inline_position if horizontal?
+        end
+
+        def y
+          Percentage::MAX - adjusted_inline_position unless horizontal?
+        end
+
+        def height
+          horizontal? ? Percentage::MAX : inline_size
+        end
+
+        def width
+          horizontal? ? inline_size : Percentage::MAX
+        end
+
+        def inline_size
+          (Percentage::MAX / values_count) * SPACING_FACTOR
+        end
+
+        def adjusted_inline_position
+          inline_position + inline_adjustment
+        end
+
+        def inline_adjustment
+          (inline_size / 2) * (horizontal? ? -1 : 1)
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/categories/category_builder.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Categories
+      # = Category Builder
+      class CategoryBuilder < ElementBuilder
+        ##
+        # :attr_accessor:
+        attribute :name
+
+        ##
+        # :attr_accessor: index
+        attribute :index, :integer, default: 0
+
+        attribute :category, default: -> { {} }
+        attribute :values_count, :integer, default: 1
+        attribute :layout_axes, default: -> { Graph::Axes.new }
+        attribute :series_options, default: -> { {} }
+
+        # Shortcut to render a bar for every series. Useful when you don't need to differentiate between different
+        # series. Arguments and options are passed to #series, see there for more details.
+        def bar(*, **)
+          series(*, **, &:bar)
+        end
+
+        # Renders one or more series present in the data. For each series yields a BarBuilder which
+        # contains the series:
+        #   <%= graph_for @annual_sales do |graph| %>
+        #     <%= graph.category do |category| %>
+        #       <%= category.series do |series| %>
+        #         <%= series.bar %>
+        #       <% end %>
+        #     <% end %>
+        #   <% end %>
+        # The default is to iterate over all series, but you can specify a subset by passing the series names as
+        # arguments.
+        #
+        # ==== Options
+        # [<tt>:axis</tt>] The axis for the series. Defaults to the first continuous axis.
+        # [<tt>:inline_axis</tt>] The axis for the categories. Defaults to the first discrete axis.
+        def series(*names, axis: nil, inline_axis: nil, **, &)
+          bars_tag(axis: inline_axis) do
+            filtered_series(*names).each_with_index do |(name, value), index|
+              concat bar_for(name, value, index, filtered_series(*names)&.count, axis:, **, &)
+            end
+          end
+        end
+
+        private
+
+        def bars_tag(axis: nil, **, &)
+          resolve_axis :discrete, axis do |discrete_axis|
+            render BarsElement.new(index:, values_count:, inline_position: discrete_axis.position_at(index),
+                                   horizontal: discrete_axis.horizontal?, **), &
+          end
+        end
+
+        def bar_for(name, value, index, series_count, axis: nil, **, &) # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+          resolve_axis :continuous, axis do |continuous_axis|
+            render BarBuilder.new(name:, inline_index: (continuous_axis.stacked? ? 0 : index),
+                                  series_index: category.keys.index(name),
+                                  inline_size: inline_size_for(continuous_axis, series_count),
+                                  series_options: series_options.fetch(name, {}),
+                                  horizontal: continuous_axis.horizontal?,
+                                  block_size: continuous_axis.length_between(0, value.to_f),
+                                  block_position: block_position_for(continuous_axis, name, value),
+                                  **),
+                   &
+          end
+        end
+
+        def inline_size_for(continuous_axis, series_count = nil)
+          Percentage::MAX / (continuous_axis.stacked? ? 1 : series_count || category.keys.count)
+        end
+
+        def block_position_for(continuous_axis, name, value)
+          continuous_axis.position_for(adjusted_value_for(continuous_axis, name, value))
+        end
+
+        def adjusted_value_for(continuous_axis, name, value)
+          previous_value_for(name, continuous_axis).to_f + value_offset_for(continuous_axis, value)
+        end
+
+        def value_offset_for(axis, value)
+          (axis.horizontal? && value.to_f.positive?) || (!axis.horizontal? && value.to_f.negative?) ? 0 : value.to_f
+        end
+
+        def previous_value_for(key, continuous_axis)
+          index_of(key).then do |index|
+            return 0 if !continuous_axis.stacked? || index.zero?
+
+            filtered_series.values
+                           .slice(0...index)
+                           .compact
+                           .filter(&(filtered_series.values[index].to_f.positive? ? :positive? : :negative?))
+                           .sum
+          end
+        end
+
+        def index_of(key)
+          filtered_series.keys.index(key)
+        end
+
+        def filtered_series(*names)
+          category.reject { names.presence&.exclude?(it) }
+        end
+
+        def resolve_axis(type, name = nil, &)
+          (name ? layout_axes.fetch(*name) : layout_axes.public_send(type)).then(&)
+        end
+      end
+    end
+  end
+end