rcharts 0.1.0

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

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    # = \RCharts \Graph Builder
+    #
+    # A GraphBuilder object contains a hash of data and allows you to render the various parts of a graph using the
+    # contained data. This is the object yielded when using GraphHelper#graph_for. For example:
+    #   <%= graph_for @annual_sales do |graph| %>
+    #     <%= graph.series do |series| %>
+    #       <%= series.line %>
+    #     <% end %>
+    #   <% end %>
+    # Here, the <tt>graph</tt> variable is a yielded GraphBuilder object. You can then render
+    # a line chart from the annual sales data by calling #series to obtain a Series::SeriesBuilder which can iterate
+    # over the series present in the data, and then calling Series::SeriesBuilder#line to render a line for the series
+    # points.
+    #
+    # The GraphBuilder object allows rendering as many or few elements of the graph as necessary while still maintaining
+    # coherence between them.
+    #
+    # Like form builders, you can subclass GraphBuilder to extend it with custom behaviour. Perhaps you want the legend
+    # to be placed at the top by default, for example:
+    #   class MyGraphBuilder < RCharts::GraphHelper::GraphBuilder
+    #     def legend(**options, &)
+    #       super(**options.merge(placement: :top, &)
+    #     end
+    #   end
+    # Then you can use the new builder with GraphHelper#graph_for:
+    #   <%= graph_for @annual_sales, builder: MyGraphBuilder do |graph| %>
+    #     <%= graph.legend do |series| %>
+    #       <%= series.symbol %>
+    #       <%= series.name %>
+    #     <% end %>
+    #   <% end %>
+    class GraphBuilder < ElementBuilder
+      ##
+      # :attr_accessor:
+      # data used to render the graph
+      attribute :graphable, default: -> { {} }
+
+      ##
+      # :attr_accessor: gutter
+      # value determining the length of short ticks
+      attribute :gutter, :float, default: 10.0
+
+      ##
+      # :attr_accessor:
+      # options for the layout axes
+      attribute :axis_options, default: -> { {} }
+
+      ##
+      # :attr_accessor:
+      # display options for each series
+      attribute :series_options, default: -> { {} }
+
+      # Renders one or more series present in the data. For each series yields a Series::SeriesBuilder which
+      # contains the series:
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.series do |series| %>
+      #       <%= series.line %>
+      #     <% end %>
+      #   <% end %>
+      # The default is to iterate over all series, but you can specify a subset by passing the series names as
+      # arguments.
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.series :baseline_prediction, :actual do |series| %>
+      #       <%= series.line %>
+      #     <% end %>
+      #   <% end %>
+      # Like GraphHelper#graph_for, you can use the <tt>:builder</tt> key to use a custom builder subclass,
+      # <tt>:data</tt> to set data attributes, and <tt>:html</tt> to set other HTML attributes, while other options are
+      # passed through to the builder.
+      #
+      # See Series::SeriesBuilder for more information.
+      def series(*names, builder: Series::SeriesBuilder, data: {}, html: {}, **, &)
+        tag.svg class: 'series-container', data:, **html do
+          selected_series(only: names).each do |key|
+            concat render builder.new(name: key, index: series_options_with_defaults.keys.index(key),
+                                      series_options: series_options_with_defaults.fetch(key, {}),
+                                      composition:,
+                                      **), &
+          end
+        end
+      end
+
+      # Renders the categories present in the data. For each category yields a Categories::CategoryBuilder which
+      # contains the category:
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.categories do |category| %>
+      #       <%= category.bar %>
+      #     <% end %>
+      #   <% end %>
+      # Like GraphHelper#graph_for, you can use the <tt>:builder</tt> key to use a custom builder subclass,
+      # <tt>:data</tt> to set data attributes, and <tt>:html</tt> to set other HTML attributes, while other options are
+      # passed through to the builder.
+      #
+      # See Categories::CategoryBuilder for more information.
+      def categories(builder: Categories::CategoryBuilder, data: {}, html: {}, **, &)
+        tag.svg class: 'category-container', data:, **html do
+          composition.values.each_with_index do |(name, category), index|
+            concat render builder.new(layout_axes: composition.axes, name:, category:, index:,
+                                      values_count: composition.values.count, series_options:, **), &
+          end
+        end
+      end
+
+      # Renders an axis for a set of points. The name is a key such as <tt>:x</tt> and optionally an index
+      # that defaults to <tt>0</tt> if not provided. Yields the value of each tick on the axis so you can format it
+      # appropriately.
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.axis :y, label: 'Primary Y axis' do |value| %>
+      #       <%= number_with_delimiter value %>
+      #     <% end %>
+      #     <%= graph.axis :y, 1, label: 'Secondary Y axis' do |value| %>
+      #       <%= number_with_delimiter value %>
+      #     <% end %>
+      #     <%= graph.axis :x, label: 'Primary X axis' do |value| %>
+      #       <%= value %>
+      #     <% end %>
+      #     <%= graph.axis :x, 1, label: 'Secondary X axis' do |value| %>
+      #       <%= value %>
+      #     <% end %>
+      #   <% end %>
+      # ==== Options
+      # [<tt>:label</tt>] The axis title
+      # [<tt>:character_scaling_factor</tt>] The scaling factor for character width on a vertical axis. In this case,
+      #                                      label width is calculated using the {width of zero in the current
+      #                                      font}[https://meyerweb.com/eric/thoughts/2018/06/28/what-is-the-css-ch-unit/]
+      #                                      multiplied by the maximum number of text characters for any label,
+      #                                      so you can use this option to make adjustments according to your average
+      #                                      character width ratio to zero. The default is <tt>1.0</tt>.
+      # [<tt>:breakpoints</tt>] Related to the character scaling factor, these are used to determine the point at which
+      #                         labels rotate or disappear. The defaults are: <tt>hiding: { even: 1.1, odd: 0.6 },
+      #                         rotation: { half: 1.0, full: 0.9 }</tt>.
+      def axis(*name, **, &)
+        axes.fetch(*name).then do |axis|
+          render Axes::AxisElement.new(name: axis.name, index: axis.index, ticks: axis.ticks, horizontal: axis.horizontal?, **), &
+        end
+      end
+
+      # Renders rules for an axis. The name is a key such as <tt>:x</tt> and optionally an index that defaults to
+      # <tt>0</tt> if not provided. Rules are both the full-length lines that span the entire width or height of
+      # the plot, as well as the much shorter lines that mark each category (e.g. for a bar chart). Rules can also be
+      # emphasized, e.g. for <tt>0</tt> in a chart which has both positive and negative values.
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.rules :y, emphasis: :zero? %>
+      #     <%= graph.rules :x, short: true %>
+      #     <%= graph.rules :x, 1, short: true %>
+      #   <% end %>
+      # ==== Options
+      # [<tt>:short</tt>] Whether to render short rules (e.g. for bar chart categories)
+      # [<tt>:emphasis</tt>] A callable predicate that determines whether a rule should be emphasized
+      def rules(*name, short: false, emphasis: nil, **)
+        tag.svg class: 'grid' do
+          axes.fetch(*name).then do |axis|
+            axis.ticks.each do |position, value|
+              concat render RuleElement.new(short:, position:, value:, emphasis:, gutter:, axis_index: axis.index,
+                                            horizontal_axis: axis.horizontal?, **)
+            end
+          end
+        end
+      end
+
+      # Renders the legend. For each series yields a LegendEntryBuilder.
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.legend do |series| %>
+      #       <%= series.symbol %>
+      #       <%= series.name %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # See LegendEntryBuilder for more information.
+      #
+      # ==== Options
+      # [<tt>:placement</tt>] The placement of the legend (top, bottom, left, right). Defaults to <tt>'bottom'</tt>.
+      def legend(placement: 'bottom', **, &)
+        tag.ul class: 'legend', data: { placement: } do
+          series_options_with_defaults.each_key.with_index do |key, index|
+            concat legend_item_tag_for(key, index, **, &)
+          end
+        end
+      end
+
+      # Renders the tooltips. For each category yields a Tooltips::TooltipBuilder.
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.tooltips do |category| %>
+      #       <div class="tooltip-inner-content">
+      #         <div class="tooltip-title">
+      #           <%= category.name %>
+      #         </div>
+      #         <dl class="tooltip-items">
+      #           <%= category.series class: 'tooltip-item' do |series| %>
+      #             <dt>
+      #               <%= series.symbol %>
+      #               <%= series.name %>
+      #             </dt>
+      #             <dd>
+      #               <%= number_to_human series.value %>
+      #             </dd>
+      #           <% end %>
+      #         </dl>
+      #       </div>
+      #     <% end %>
+      #   <% end %>
+      #
+      # See Tooltips::TooltipBuilder for more information.
+      def tooltips(**, &)
+        tag.svg class: 'tooltips', width: '100%', xmlns: 'http://www.w3.org/2000/svg' do
+          composition.values.each_key { concat tooltip_tag_for(it, **, &) }
+        end
+      end
+
+      private
+
+      delegate :axes, :values, to: :composition, private: true
+
+      def series_options_with_defaults
+        series_options.with_defaults(series_names.index_with { {} })
+      end
+
+      def composition
+        @composition ||= Graph::Composition.new(graphable, axis_options)
+      end
+
+      def series_names
+        return [] if graphable.empty?
+
+        case graphable.values.first
+        in Hash => graphable_hash then graphable_hash.keys
+        in Array => graphable_array then (0...graphable_array.count).to_a
+        else [nil]
+        end
+      end
+
+      def selected_series(only: nil)
+        series_options_with_defaults.keys.reject { only.presence&.exclude?(it) }
+      end
+
+      def legend_item_tag_for(key, index, **, &)
+        tag.li class: 'legend-item' do
+          render LegendEntryBuilder.new(name: key, index:, series_options: series_options_with_defaults[key], **), &
+        end
+      end
+
+      def tooltip_tag_for(key, **, &)
+        render Tooltips::TooltipElement.new(inline_axis: inline_axis.name,
+                                            inline_position: inline_axis.position_for(key) || Percentage::MIN,
+                                            inline_size:,
+                                            index: index_for(key),
+                                            values_count: values.count) do
+          render Tooltips::TooltipBuilder.new(series_options: series_options_with_defaults, values: values[key],
+                                              name: key, **), &
+        end
+      end
+
+      def inline_size
+        Percentage::MAX / values.count
+      end
+
+      def index_for(key)
+        composition.keys.index(key)
+      end
+
+      def inline_axis
+        composition.axes.discrete
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    # = \Legend Entry Builder
+    class LegendEntryBuilder < ElementBuilder
+      ##
+      # :attr_accessor:
+      attribute :name
+
+      ##
+      # :attr_accessor: index
+      attribute :index, :integer, default: 0
+
+      attribute :series_options, default: -> { {} }
+
+      # Renders the symbol associated with the series. You can override this on a per-series basis using
+      # <tt>:series_options</tt> with GraphHelper#graph_for.
+      # To change the global set of symbols and colors, see RCharts.symbol_for and RCharts.color_class_for.
+      #   <%= graph_for @annual_sales do |graph| %>
+      #     <%= graph.tooltips do |category| %>
+      #       <h4><%= category.name %></h4>
+      #       <%= category.series do |series| %>
+      #         <%= series.symbol %>
+      #         <%= series.name %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      def symbol
+        tag.span symbol_character, class: ['series-symbol', color_class]
+      end
+
+      private
+
+      delegate :color_class_for, :symbol_for, to: RCharts, private: true
+
+      def color_class
+        series_options.fetch(:color_class, color_class_for(index))
+      end
+
+      def symbol_character
+        series_options.fetch(:symbol, symbol_for(index))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    class RuleElement < Element # :nodoc:
+      attribute :horizontal_axis, :boolean, default: false
+      attribute :axis_index, :integer, default: 0
+      attribute :short, :boolean, default: false
+      attribute :gutter, :float, default: 0
+      attribute :position, :'rcharts/percentage', default: Percentage::MIN
+      attribute :emphasis
+      attribute :value
+
+      private
+
+      alias horizontal_axis? horizontal_axis
+      alias short? short
+
+      def tags
+        tag.svg y:, x:, class: 'grid-rule-container' do
+          tag.line x1:, x2:, y1:, y2:, class: ['grid-rule', { 'emphasis' => emphasis_value }]
+        end
+      end
+
+      def y
+        '100%' if short? && horizontal_axis? && axis_index.zero?
+      end
+
+      def x
+        '100%' if short? && !horizontal_axis? && axis_index.positive?
+      end
+
+      def x1
+        horizontal_axis? ? position : start
+      end
+
+      def x2
+        horizontal_axis? ? position : finish
+      end
+
+      def y1
+        horizontal_axis? ? start : Percentage::MAX - position
+      end
+
+      def y2
+        horizontal_axis? ? finish : Percentage::MAX - position
+      end
+
+      def finish
+        return Percentage::MAX unless short?
+        return Percentage::MIN unless horizontal_axis?
+
+        (gutter / 2) * (axis_index.zero? ? 1 : -1)
+      end
+
+      def start
+        return Percentage::MIN unless short?
+        return Percentage::MIN if horizontal_axis?
+
+        (gutter / 2) * (axis_index.zero? ? -1 : 1)
+      end
+
+      def emphasis_value
+        emphasis.respond_to?(:to_proc) ? value.then(&emphasis) : emphasis
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/series/area_element.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Series
+      class AreaElement < PathElement # :nodoc:
+        attribute :previous_series, default: -> { {} }
+        attribute :mask_series, default: -> { {} }
+        attribute :block_position, :float, default: 0
+
+        private
+
+        delegate :mask_spans, to: :mask_path, private: true
+
+        def path_tag
+          tag.path d: path_data, style: "d:path(\"#{path_data}\")", class: ['series-shape', color_class], data:, aria:,
+                   mask: "url(##{mask_id})"
+        end
+
+        def path_data
+          return '' if series.values.compact.all?(&:zero?)
+
+          @path_data ||= area_path
+        end
+
+        def previous_points
+          return [] if previous_series == series
+
+          previous_series.collect { |key, value| Point.new(key, 100.0 - (value || block_position)) }
+        end
+
+        def points
+          series.collect { |key, value| Point.new(key, 100.0 - (value || block_position)) }
+        end
+
+        def mask_points
+          mask_series.collect { |key, value| Point.new(key, value.try { 100.0 - it }) }
+        end
+
+        def path
+          Path.new(points, previous_points, origin: block_position, smoothing: smooth)
+        end
+
+        def mask_path
+          Path.new(mask_points, origin: block_position, smoothing: smooth)
+        end
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/series/path.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Series
+      class Path # :nodoc:
+        class PathBuffer < String # :nodoc:
+          SEPARATOR = ' '
+
+          def concat(*objects)
+            return super if empty? || objects.empty?
+
+            super(SEPARATOR, objects.compact_blank.join(SEPARATOR))
+          end
+
+          def <<(object)
+            return super if object.blank?
+
+            concat object
+          end
+
+          def prepend(*other_strings)
+            return super if empty? || other_strings.empty?
+
+            super(other_strings.compact_blank.join(SEPARATOR), SEPARATOR)
+          end
+        end
+
+        POINT_SIZE = 38
+
+        def initialize(points = [], previous_points = [], origin: 0, smoothing: nil)
+          @points = points
+          @previous_points = previous_points
+          @smoothing = smoothing
+          @origin = origin
+        end
+
+        def line_path
+          if compacted_points.empty?
+            ''
+          else
+            line_or_curve_data.prepend(initial_line_data)
+          end
+        end
+
+        def area_path
+          if compacted_points.empty?
+            ''
+          else
+            line_or_curve_data.prepend(*initial_area_data).concat(*final_area_data, previous_line_or_curve_data)
+          end
+        end
+
+        def mask_spans
+          points.compact.chunk(&:complete?).filter_map do |complete, chunk|
+            next unless complete
+
+            chunk.sort_by!(&:x)
+            chunk.first => { x:, y: }
+            chunk.last - chunk.first => { x: width, y: height }
+            { x:, y:, width:, height: }
+          end
+        end
+
+        private
+
+        attr_reader :points, :previous_points, :smoothing, :origin
+        attr_accessor :buffer
+
+        def line_or_curve_data
+          smoothing ? curve_data : line_data
+        end
+
+        def line_data
+          capture capacity: estimated_serialized_length do
+            compacted_points.each { concat line_to(it) }
+          end
+        end
+
+        def curve_data
+          capture capacity: estimated_serialized_length * 3 do
+            compacted_points.values_at(0, 0..-1, -1).each_cons(4) { concat curve_for(*it, smoothing) }
+          end
+        end
+
+        def previous_line_or_curve_data
+          smoothing ? previous_curve_data : previous_line_data
+        end
+
+        def previous_line_data
+          capture capacity: estimated_serialized_length do
+            compacted_previous_points.reverse_each { concat line_to(it) }
+          end
+        end
+
+        def previous_curve_data
+          capture capacity: estimated_serialized_length * 3 do
+            compacted_previous_points.values_at(0, 0..-1, -1)
+                                     .each_cons(4)
+                                     .reverse_each { concat curve_for(*it.reverse, smoothing) }
+          end
+        end
+
+        def initial_line_data
+          move_to compacted_points.first
+        end
+
+        def initial_area_data
+          [move_to(Point.new(compacted_points.first.x, 100 - origin)), line_to(compacted_points.first)]
+        end
+
+        def final_area_data
+          [line_to(Point.new(compacted_points.last.x, 100 - origin)), line_to(compacted_previous_points.last)]
+        end
+
+        def move_to(point)
+          "M #{point}" if point
+        end
+
+        def line_to(point)
+          "L #{point}" if point
+        end
+
+        def curve_for(previous_point, current, next_point, subsequent_point, smoothing)
+          "C #{current.control(previous_point, next_point, smoothing:)} " \
+            "#{next_point.control(current, subsequent_point, smoothing:, reverse: true)} " \
+            "#{next_point}"
+        end
+
+        def estimated_serialized_length
+          compacted_points.size * POINT_SIZE
+        end
+
+        def estimated_previous_serialized_length
+          compacted_previous_points.size * POINT_SIZE
+        end
+
+        def capture(capacity: nil)
+          self.buffer = PathBuffer.new(capacity:)
+          yield
+          buffer
+        end
+
+        def concat(*objects)
+          objects.each { buffer.concat it }
+        end
+
+        def compacted_points = points.compact.select(&:complete?)
+        def compacted_previous_points = previous_points.compact.select(&:complete?)
+      end
+    end
+  end
+end

data/app/helpers/rcharts/graph_helper/series/path_element.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RCharts
+  module GraphHelper
+    module Series
+      class PathElement < Element # :nodoc:
+        attribute :series_options, default: -> { {} }
+        attribute :series, default: -> { {} }
+        attribute :index, :integer, default: 0
+        attribute :smoothing, :float
+        attribute :horizontal, :boolean, default: false
+        attribute :id_hash, :string, default: -> { SecureRandom.hex(4) }
+
+        alias_attribute :smooth, :smoothing
+
+        private
+
+        alias horizontal? horizontal
+
+        delegate :line_path, :area_path, :mask_spans, to: :path, private: true
+
+        def tags
+          tag.svg class: 'series', height: '100%', width: '100%',
+                  'viewBox' => '0 0 100 100', 'preserveAspectRatio' => 'none' do
+            series_tag
+          end
+        end
+
+        def series_tag
+          mask_tag + path_tag
+        end
+
+        def path_tag
+          tag.path d: path_data, style: "d:path(\"#{path_data}\")", class: ['series-path', color_class, class_names], data:, aria:,
+                   mask: "url(##{mask_id})"
+        end
+
+        def path_data
+          @path_data ||= line_path
+        end
+
+        def color_class
+          series_options.fetch(:color_class, RCharts.color_class_for(index))
+        end
+
+        def points
+          series.collect { |key, value| Point.new(key, value.try { 100.0 - it }) }
+        end
+
+        def path
+          Path.new(points, smoothing:)
+        end
+
+        def mask_tag
+          tag.mask id: mask_id, maskUnits: 'userSpaceOnUse', maskContentUnits: 'userSpaceOnUse' do
+            concat tag.rect x: '-50%', y: '-50%', width: '200%', height: '200%', fill: 'black'
+            mask_spans.each { concat mask_rect_tag_for(it) }
+          end
+        end
+
+        def mask_rect_tag_for(span)
+          tag.rect x: '-50%', y: '-50%', width: '200%', height: '200%', fill: 'white',
+                   **span.slice(*(horizontal? ? %i[x width] : %i[y height]))
+        end
+
+        def mask_id
+          ['series-mask', id_hash].join('-')
+        end
+      end
+    end
+  end
+end