asciidoctor-chart 1.0.0.alpha.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f04e36b08cd8bcd45da1387e52efb5f982f92aceb1b14912130158eb4c7f34a1
-  data.tar.gz: fc325aa365a1b8ccf11fcc3e10cb6efd52fb0a447280e72c37d8db77eb412f94
+  metadata.gz: d19c56f42982d8d5b332f7e3f9daa2456a46e892e19c34c474b26d916ac9c06f
+  data.tar.gz: 5f9c0366c859481c33078b6b6bb7ec66b311a5ed0a7b3ff816a464869d6bc35b
 SHA512:
-  metadata.gz: dba17ce4d883a862ad885833dbe8785fbc9d3d334a35fc97a31fb0d05bf11442a2cb086cd80a23a43b15be9031d6e96dce0f48e5042c035f365dd0b1a7102d5a
-  data.tar.gz: d55676125f54e5898e966fe0f4241c01dc24bc7bb8cfdf0a8f72601eba1999e8f69080d61efbe19dac9b7a966e658609162f9cf1fdeeede3882aae9e68b3e35b
+  metadata.gz: 2de58fded66f3709cfa02645bc8d0aff0b5199555f66c3108d624b5990e207dca2a3cdf49e1065a3875349df84988b75084c69ddfc2e1c60df3d4449583e7da2
+  data.tar.gz: 3cf74600a24dc2ae35d3b13cc7a0ea5ea1e9c64a9c44ceef9ae6ec9bcabcbd77794968b0e49f471554477cc4247b4a2e76f7f639d4b36c8932880595ad69d928

data/CHANGELOG.adoc

@@ -0,0 +1,38 @@
+= Asciidoctor Chart Changelog
+:icons: font
+:uri-repo: https://github.com/asciidoctor/asciidoctor-chart
+
+This document provides a high-level view of the changes introduced in Asciidoctor Chart by release.
+For an even more detailed look at what has changed, refer to the {uri-repo}/commits/[commit history] on GitHub.
+
+The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog],
+and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].
+
+== Unreleased
+
+
+== 1.0.0 (2022-10-08)
+
+=== ✨ Added
+
+* Introduce a changelog (#30)
+* Add support for using the JavaScript libraries offline (#25)
+* Add captioned title on charts (#18)
+* Improved documentation
+* Add attributes to define chart resources directory (#26)
+* Introduce visual regression tests (#34)
+
+=== 🎨 Changed
+
+* Use 0.11.x as default version for Chartist.js instead of latest (#28)
+* Update c3.js defaults to latest version 0.7.20 (#32) 
+* Upgrade Chart.js from 1.0.2 to 3.7.0 and update code accordingly (#17)
+* Use https protocol (instead of http) when loading scripts from cdnjs.cloudflare.com (#17)
+* Apply RuboCop to asciidoctor-chart.gemspec (#17)
+* Enable multi-factor authentication when publishing to https://rubygems.org/ (#17)
+
+=== 🐞 Fixed
+
+* Fix an issue to allow more than one Chart.js graphs per page (#13)
+* Include assets (styles, scripts)  when an chart engine is used (#24)
+* Fix an issue with Chart.js where text was overlapping the graph when width was specified (#17)

data/README.adoc

@@ -1,15 +1,101 @@
 = Asciidoctor Chart
+// Aliases:
+:project-name: Asciidoctor Chart
+:project-handle: asciidoctor-chart
+// Variables:
+:release-version: 1.0.0.alpha.1
+:uri-repo: https://github.com/asciidoctor/asciidoctor-chart
 // Settings:
 :idprefix:
 :idseparator: -
 
-image:https://github.com/asciidoctor/asciidoctor-chart/workflows/Ruby/badge.svg[link=https://github.com/asciidoctor/asciidoctor-chart/actions?query=workflow%3ARuby]
+image:https://github.com/asciidoctor/asciidoctor-chart/workflows/CI/badge.svg[link=https://github.com/asciidoctor/asciidoctor-chart/actions?query=workflow%3ACI]
+image:https://img.shields.io/gem/v/asciidoctor-chart?include_prereleases[link=https://rubygems.org/search?query=asciidoctor-chart]
+
+A set of Asciidoctor extensions that adds a chart block and block macro for including charts powered by https://c3js.org/[C3.js], https://gionkunz.github.io/chartist-js/[Chartist], or https://www.chartjs.org/[Chart.js] in your AsciiDoc document.
+
+== Prerequisites
+
+All that's needed is Ruby 2.5 or better (or JRuby 9.2 or better) and a few Ruby gems (including at least Asciidoctor 2.0.0), which we explain how to install in the next section.
+
+To check if you have Ruby available, use the `ruby` command to query the version installed:
+
+ $ ruby -e 'puts RUBY_VERSION'
+
+Make sure this command reports a Ruby version that's at least 2.5.
+If so, you may proceed.
+
+== Getting Started
+
+You can get {project-name} by <<install-the-published-gem,installing the published gem>>.
+ifndef::env-site[You can also <<development,run the code from source>> if you want to use a development version or participate in development.]
+
+=== Install the Published Gem
+
+To install {project-name}, first make sure you have satisfied the <<Prerequisites,prerequisites>>.
+Then, install the gem from RubyGems.org using the following command:
+
+ $ gem install asciidoctor-chart --pre
+
+=== Enable the Extension
+
+Assuming all the required gems install properly, you can enable the extension using `--require` option (or `-r` for short) from the Asciidoctor CLI:
+
+ $ asciidoctor --require asciidoctor-chart my-doc.adoc
+
+=== Usage
+
+Line chart powered by C3.js (default) declared as a literal block::
++
+----
+[chart,line]
+....
+January,February,March,April,May,June,July
+28,48,40,19,86,27,90
+65,59,80,81,56,55,40
+....
+----
++
+image::./examples/chart-c3js.png[]
+
+Line chart powered by Chart.js declared as a block macro with a CSV file as target::
++
+----
+chart::sample-data.csv[line,engine="chartjs"]
+----
++
+image::./examples/chart-chartjs.png[]
+
+For more examples, see {uri-repo}/blob/master/examples/example.adoc[example.adoc].
+
+=== Configuration
+
+[cols="1s,1,3"]
+|===
+|Attribute{nbsp}Name |Value(s)|Description
+
+|c3jsdir
+|<file\|URL>
+|Overrides c3.js directory, where the following files `c3.min.css` and `c3.min.js` are expected. Default is `https://cdnjs.cloudflare.com/ajax/libs/c3/0.7.20/`.
+
+|chartjsdir
+|<file\|URL>
+|Overrides chart.js directory, where the following file `chart.min.js` is expected. Default is `https://cdnjs.cloudflare.com/ajax/libs/Chart.js/3.7.0/`.
+
+|chartistdir
+|<file\|URL>
+|Overrides chartist.js directory, where the following files `chartist.min.css` and `chartist.min.js` are expected. Default is `https://cdn.jsdelivr.net/chartist.js/0.11.x/`.
+
+
+|d3jsdir
+|<file\|URL>
+|Overrides d3.js directory, where the following file `d3.min.js` is expected. Default is `https://cdnjs.cloudflare.com/ajax/libs/d3/5.16.0/`.
+|===
 
-A set of Asciidoctor extensions that adds a chart block and block macro for including charts powered by powered by c3js, chartist, or chartjs in your AsciiDoc document.
 
 == Authors
 
-Asciidoctor Chart was written by https://github.com/mogztter/[Guillaume Grossetie].
+{project-name} was written by https://github.com/mogztter/[Guillaume Grossetie].
 
 == Copyright
 

data/asciidoctor-chart.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 begin
   require_relative 'lib/asciidoctor/chart/version'
 rescue LoadError
@@ -8,31 +10,36 @@ Gem::Specification.new do |s|
   s.name = 'asciidoctor-chart'
   s.version = Asciidoctor::Chart::VERSION
   s.summary = 'Adds a chart block and block macro to AsciiDoc'
-  s.description = 'A set of Asciidoctor extensions that add a chart block and block macro to AsciiDoc for including charts in your AsciiDoc document.'
+  s.description = "A set of Asciidoctor extensions that add a chart block and block macro to AsciiDoc
+for including charts in your AsciiDoc document."
   s.authors = ['Guillaume Grossetie']
   s.email = 'ggrossetie@gmail.com'
   s.homepage = 'https://asciidoctor.org'
   s.license = 'MIT'
-  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
-  #s.required_ruby_version = '>= 2.5.0'
+  # NOTE: required ruby version is informational only;
+  # it's not enforced since it can't be overridden and can cause builds to break
+  # s.required_ruby_version = '>= 2.7.0'
   s.metadata = {
     'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-chart/issues',
-    #'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-chart/blob/master/CHANGELOG.adoc',
-    'mailing_list_uri' => 'http://discuss.asciidoctor.org',
-    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-chart'
+    # 'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-chart/blob/master/CHANGELOG.adoc',
+    'community_chat_uri' => 'https://asciidoctor.zulipchat.com',
+    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-chart',
+    'rubygems_mfa_required' => 'true'
   }
 
-  # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available
+  # NOTE: the logic to build the list of files is designed to produce a usable package
+  # even when the git command is not available
   begin
-    files = (result = `git ls-files -z`.split ?\0).empty? ? Dir['**/*'] : result
-  rescue
+    files = (result = `git ls-files -z`.split "\0").empty? ? Dir['**/*'] : result
+  rescue StandardError
     files = Dir['**/*']
   end
-  s.files = files.grep %r/^(?:(?:data|lib)\/.+|(?:CHANGELOG|LICENSE|NOTICE|README)\.adoc|\.yardopts|#{s.name}\.gemspec)$/
-  s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
+  s.files = files.grep %r{^(?:(?:data|lib)/.+|(?:CHANGELOG|LICENSE|NOTICE|README)\.adoc|\.yardopts|#{s.name}\.gemspec)$}
+  s.executables = (files.grep %r{^bin/}).map {|f| File.basename f }
   s.require_paths = ['lib']
 
   s.add_runtime_dependency 'asciidoctor', '~> 2.0'
+  s.add_runtime_dependency 'tilt', '~> 2.0.0'
   s.add_development_dependency 'rake', '~> 13.0.0'
   s.add_development_dependency 'rspec', '~> 3.9.0'
 end

data/lib/asciidoctor/chart/block_macro_processor.rb

@@ -12,10 +12,8 @@ module Asciidoctor
         read_data = parent.read_asset data_path, warn_on_failure: true, normalize: true
         return if read_data.nil? || read_data.empty?
 
-        engine = Backend.resolve_engine attrs, parent.document
         raw_data = PlainRubyCSV.parse read_data
-        html = Backend.process engine, attrs, raw_data
-        create_pass_block parent, html, attrs, subs: nil
+        Asciidoctor::Chart::ChartBlock.new parent, raw_data, attrs
       end
     end
   end

data/lib/asciidoctor/chart/block_processor.rb

@@ -10,10 +10,8 @@ module Asciidoctor
       parse_content_as :raw
 
       def process parent, reader, attrs
-        engine = Backend.resolve_engine attrs, parent.document
         raw_data = PlainRubyCSV.parse reader.source
-        html = Backend.process engine, attrs, raw_data
-        create_pass_block parent, html, attrs, subs: nil
+        Asciidoctor::Chart::ChartBlock.new parent, raw_data, attrs
       end
     end
   end

data/lib/asciidoctor/chart/chart_block.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Chart
+    class ChartBlock < Asciidoctor::Block
+      def initialize(parent, data, attrs)
+        engine = parent.document.get_engine attrs
+        caption = attrs.delete 'caption'
+        title = attrs.delete 'title'
+        block_attributes = attrs.merge({
+                                         'id' => attrs['id'] || "chart#{PlainRubyRandom.uuid}",
+                                         'type' => attrs['type'] || 'line',
+                                         'engine' => engine,
+                                         'data-raw' => data
+                                       })
+        super parent, :chart, { source: nil, attributes: block_attributes, subs: nil }
+        @title = title
+        assign_caption(caption, 'figure')
+      end
+    end
+
+    module ChartBlockTracker
+      attr_reader :x_chart
+
+      def self.extended instance
+        instance.instance_variable_set :@x_chart, {
+          engines: Set.new
+        }
+      end
+
+      def get_engine attrs
+        engine = if attrs.key? 'engine'
+                   attrs['engine'].downcase
+                 elsif @attributes.key? 'chart-engine'
+                   @attributes['chart-engine'].downcase
+                 else
+                   'c3js'
+                 end
+        @x_chart[:engines].add(engine)
+
+        engine
+      end
+    end
+  end
+end

data/lib/asciidoctor/chart/converter/c3js.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Chart
+    module Converter
+      class Html5C3jsConverter < Asciidoctor::Chart::Converter::Base
+        def convert_line_chart node
+          data, labels = prepare_data node
+          chart_generate_script = chart_line_script node, data, labels
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_generate_script}
+          HTML
+        end
+
+        def convert_bar_chart node
+          data, labels = prepare_data node
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_bar_script node, data, labels}
+          HTML
+        end
+
+        def convert_step_chart node
+          data, labels = prepare_data node
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_step_script node, data, labels}
+          HTML
+        end
+
+        def convert_spline_chart node
+          data, labels = prepare_data node
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_spline_script node, data, labels}
+          HTML
+        end
+
+        def convert_pie_chart node
+          raw_data = node.attr 'data-raw', []
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_pie_script node, raw_data}
+          HTML
+        end
+
+        private
+
+        def prepare_data node
+          raw_data = node.attr 'data-raw', []
+          return [[], []] if raw_data.length <= 1 # question: should we warn?
+
+          labels = raw_data[0]
+          raw_data.shift
+          raw_data.map.with_index {|row, index| row.unshift index.to_s }
+          [raw_data, labels]
+        end
+
+        def chart_bar_script node, data, labels
+          chart_height = get_chart_height node
+          chart_width = get_chart_width node
+          axis_x_label = get_axis_x_label node
+          axis_y_label = get_axis_y_label node
+          data_names = get_data_names node
+          <<~HTML
+            <script>
+              c3.generate({
+                bindto: '##{node.attr 'id'}',
+                size: { height: #{chart_height}, width: #{chart_width} },
+                data: {
+                  columns: #{data.to_s},
+                  type: 'bar',
+                  names: #{data_names.to_s}
+                },
+                axis: {
+                  x: {
+                    type: 'category',
+                    categories: #{labels.to_s},
+                    label: '#{axis_x_label}'
+                  },
+                  y: {
+                    label: '#{axis_y_label}'
+                  }
+                }
+              })
+            </script>
+          HTML
+        end
+
+        def chart_line_script node, data, labels
+          chart_height = get_chart_height node
+          chart_width = get_chart_width node
+          axis_x_label = get_axis_x_label node
+          axis_y_label = get_axis_y_label node
+          data_names = get_data_names node
+          <<~HTML
+            <script>
+              c3.generate({
+                bindto: '##{node.attr 'id'}',
+                size: { height: #{chart_height}, width: #{chart_width} },
+                data: {
+                  columns: #{data.to_s},
+                  names: #{data_names.to_s}
+                },
+                axis: {
+                  x: {
+                    type: 'category',
+                    categories: #{labels.to_s},
+                    label: '#{axis_x_label}'
+                  },
+                  y: {
+                    label: '#{axis_y_label}'
+                  }
+                }
+              })
+            </script>
+          HTML
+        end
+
+        def chart_step_script node, data, labels
+          chart_height = get_chart_height node
+          chart_width = get_chart_width node
+          axis_x_label = get_axis_x_label node
+          axis_y_label = get_axis_y_label node
+          data_names = get_data_names node
+          <<~HTML
+            <script>
+              c3.generate({
+                bindto: '##{node.attr 'id'}',
+                size: { height: #{chart_height}, width: #{chart_width} },
+                data: {
+                  columns: #{data.to_s},
+                  type: 'step',
+                  names: #{data_names.to_s}
+                },
+                axis: {
+                  x: {
+                    type: 'category',
+                    categories: #{labels.to_s},
+                    label: '#{axis_x_label}'
+                  },
+                  y: {
+                    label: '#{axis_y_label}'
+                  }
+                }
+              })
+            </script>
+          HTML
+        end
+
+        def chart_spline_script node, data, labels
+          chart_height = get_chart_height node
+          chart_width = get_chart_width node
+          axis_x_label = get_axis_x_label node
+          axis_y_label = get_axis_y_label node
+          data_names = get_data_names node
+          <<~HTML
+            <script>
+              c3.generate({
+                bindto: '##{node.attr 'id'}',
+                size: { height: #{chart_height}, width: #{chart_width} },
+                data: {
+                  columns: #{data.to_s},
+                  type: 'spline',
+                  names: #{data_names.to_s}
+                },
+                axis: {
+                  x: {
+                    type: 'category',
+                    categories: #{labels.to_s},
+                    label: '#{axis_x_label}'
+                  },
+                  y: {
+                    label: '#{axis_y_label}'
+                  }
+                }
+              })
+            </script>
+          HTML
+        end
+
+        def chart_pie_script node, raw_data
+          chart_height = get_chart_height node
+          chart_width = get_chart_width node
+          <<~HTML
+            <script>
+              c3.generate({
+                bindto: '##{node.attr 'id'}',
+                size: { height: #{chart_height}, width: #{chart_width} },
+                data: {
+                  columns: #{raw_data.to_s},
+                  type: 'pie'
+                }
+              })
+            </script>
+          HTML
+        end
+
+        def chart_block_element node
+          title_element = node.title? ? %(\n  <div class="title">#{node.captioned_title}</div>) : ''
+          %(<div class="chartblock">
+  <div class="content c3js-content">
+    <div id="#{node.attr 'id'}"></div>
+  </div>#{title_element}
+</div>)
+        end
+
+        def get_chart_height node
+          node.attr 'height', '400'
+        end
+
+        def get_chart_width node
+          node.attr 'width', '600'
+        end
+
+        def get_axis_x_label node
+          node.attr?('axis-x-label') ? CGI.unescapeHTML(node.attr('axis-x-label')) : ''
+        end
+
+        def get_axis_y_label node
+          node.attr?('axis-y-label') ? CGI.unescapeHTML(node.attr('axis-y-label')) : ''
+        end
+
+        def get_data_names node
+          node.attr?('data-names') ? CGI.unescapeHTML(node.attr('data-names')) : '{}'
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/chart/converter/chartist.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Chart
+    module Converter
+      class Html5ChartistConverter < Asciidoctor::Chart::Converter::Base
+        def convert_line_chart node
+          data, labels = prepare_data node
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_line_script node, data, labels}
+          HTML
+        end
+
+        def convert_bar_chart node
+          data, labels = prepare_data node
+          <<~HTML
+            #{chart_block_element node}
+            #{chart_bar_script node, data, labels}
+          HTML
+        end
+
+        private
+
+        def prepare_data node
+          raw_data = node.attr 'data-raw', []
+          return [[], []] if raw_data.length <= 1 # question: should we warn?
+
+          labels = raw_data[0]
+          raw_data.shift
+          [raw_data, labels]
+        end
+
+        def chart_block_element node
+          title_element = node.title? ? %(\n  <div class="title">#{node.captioned_title}</div>) : ''
+          %(<div class="chartblock">
+  <div class="content chartist-content">
+    <div id="#{node.attr 'id'}" class="ct-chart"></div>
+  </div>#{title_element}
+</div>)
+        end
+
+        def chart_line_script node, data, labels
+          chart_height = node.attr 'height', '400'
+          chart_width = node.attr 'width', '600'
+          <<~HTML
+            <script>
+              var options = {
+                height: '#{chart_height}',
+                width: '#{chart_width}',
+                colors: ["#72B3CC", "#8EB33B"]
+              }
+              var data = {
+                labels: #{labels.to_s},
+                series: #{data.to_s}
+              }
+              new Chartist.Line('##{node.attr 'id'}', data, options)
+            </script>
+          HTML
+        end
+
+        def chart_bar_script node, data, labels
+          chart_height = node.attr 'height', '400'
+          <<~HTML
+            <script>
+              var options = {
+                height: '#{chart_height}',
+                colors: ["#72B3CC", "#8EB33B"]
+              }
+              var data = {
+                labels: #{labels.to_s},
+                series: #{data.to_s}
+              }
+              new Chartist.Bar('##{node.attr 'id'}', data, options)
+            </script>
+          HTML
+        end
+      end
+    end
+  end
+end