rbplotly 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 601630a8bda423d88e103244a295c36513e8d99b959d0e7db508c65a776b49b4
-  data.tar.gz: e2474fcfc722b3ece12085f992b502c456761fcdee39d1359dfd9486b5fe8774
+  metadata.gz: 3ee3bc96889cfdc7042b4cb2d4f493003ede009bb78ac14f59b2ff78aa56345c
+  data.tar.gz: e395c9e2230df5996b6a91a1757b4d72cd9829149aad82e7ba0acc3dac066c60
 SHA512:
-  metadata.gz: 244c2be24a75a8d9479ca8a6326c44aafa464fc41f70ada2e362e710021e9a825bb3bbd5f681b2cdd4f597dfd98128cb8853f54325f34234accd4b866801954b
-  data.tar.gz: cbdeb3ed2a7ee529fc2d0f38340d7a1f508f268f3a0fc5a010f4d40589d12e23f5ddd87434a139fd0431bd5a1e6c4f189467cba6dbba18edd9b80dccd1c4fdbf
+  metadata.gz: c05da261022f1d36806155a0f1f004e17c020e5451b79daf09daeb8f28d2820fd0cd90aa73444109c0516fd6b126745a74b28fa721261e941572fb857e9f7288
+  data.tar.gz: 46fa94b5913d6dfc0b37a5dd5761c59f7c775823b6bc02c41630c94ee7995d418d4676268086a6652fdd1a680c256a0f1205ef044a19892ac2bc5c47d992a306

data/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [1.0.1] - 2026-10-07
+
+### Added
+
+- Relative subplot sizes through `column_widths` and `row_heights`, and per-cell right y
+  axes through `specs: [[{secondary_y: true}]]`. Trace placement, trace updates and y-axis
+  updates accept `secondary_y`; existing primary axis numbering is preserved.
+- Animation frames through `Figure.new(frames:)`, `add_frame` and `frames=`, with validation
+  of partial trace/layout updates and inclusion in JSON output. HTML and notebook output
+  register frames and start playback; `to_html` and `write_html` accept `auto_play` and
+  `animation_opts`.
+- Runnable examples for secondary axes and animation.
+
+### Fixed
+
+- Require `json >= 2.9` to avoid the older `script_safe` bug that corrupts characters such
+  as `瀨` and `倩` in chart labels and JSON output.
+- Reject negative, non-finite and out-of-range subplot spacing instead of silently
+  overlapping or collapsing cells; reject invalid row/column counts before calculating defaults.
+
 ## [1.0.0] - 2026-10-07
 
 A rewrite. Figures are now plain hashes checked against the plot schema of a pinned
@@ -60,5 +82,7 @@ plotly.js release, instead of hand-written classes that covered a few attributes
 
 The last 0.x release. See the [git history](https://github.com/ash1day/rbplotly/commits/v0.1.2).
 
+[Unreleased]: https://github.com/ash1day/rbplotly/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/ash1day/rbplotly/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/ash1day/rbplotly/compare/v0.1.2...v1.0.0
 [0.1.2]: https://github.com/ash1day/rbplotly/releases/tag/v0.1.2

data/README.md

@@ -124,6 +124,44 @@ fig.update_yaxes({title_text: "USD (M)"}, row: 1, col: 1)
 Traces on x/y axes go on the cell's axes and domain traces (pie, sunburst, ...) fill the cell;
 3D, polar, ternary and map traces cannot be placed by `row:`/`col:` yet.
 
+Use positive relative `column_widths:` and `row_heights:` to size cells. Row heights are
+ordered from top to bottom; spacing is subtracted before distributing the remaining space.
+Enable a right y axis with `specs:`, then select it with `secondary_y: true`:
+
+```ruby
+fig = Plotly.make_subplots(cols: 2, column_widths: [2, 1],
+  specs: [[{secondary_y: true}, {}]])
+fig.add_bar(x: %w[Jan Feb Mar], y: [100, 150, 180], name: "Orders", row: 1, col: 1)
+fig.add_scatter(x: %w[Jan Feb Mar], y: [2, 3, 2.5], name: "Conversion %",
+  row: 1, col: 1, secondary_y: true)
+fig.update_yaxes(title_text: "Orders", row: 1, col: 1, secondary_y: false)
+fig.update_yaxes(title_text: "Conversion", ticksuffix: "%", secondary_y: true)
+```
+
+`specs` currently accepts only `secondary_y` in each cell hash. Existing primary axis
+numbers stay unchanged; secondary axes are numbered after all primary axes.
+`update_traces` and `update_yaxes` accept `secondary_y: true` (right), `false` (left),
+or the default `nil` (both). Axis sharing links only primary axes.
+
+### Animation
+
+Supply `frames:` to the constructor, append with `add_frame`, or replace with `frames=`.
+Define base traces before frames: omitted trace types are inferred from the corresponding
+base trace. A frame's `traces` array maps its data entries to zero-based trace indices.
+
+```ruby
+fig = Plotly::Figure.new.add_scatter(x: [0, 1], y: [0, 1], mode: :"lines+markers")
+fig.update_layout(xaxis_range: [0, 1], yaxis_range: [0, 3])
+fig.add_frame(name: "first", data: [{y: [1, 2]}])
+fig.add_frame(name: "second", data: [{y: [2, 3]}])
+fig.write_html("animation.html", animation_opts: {frame: {duration: 700}, transition: {duration: 300}})
+```
+
+HTML and notebook output register frames after drawing, then play them automatically.
+Pass `auto_play: false` to `to_html` or `write_html` to register frames without starting;
+use layout `updatemenus`/`sliders` or JavaScript to trigger playback. Nonempty frames are
+included in `to_h` and `to_json`. Without base data, an omitted trace type defaults to scatter.
+
 ## Output
 
 | Method | Gives you |

data/lib/plotly/figure.rb

@@ -3,7 +3,7 @@
 require "did_you_mean"
 
 module Plotly
-  # A plotly.js figure: traces (`data`), `layout` and `config`.
+  # A plotly.js figure: traces (`data`), `layout`, `config` and animation `frames`.
   #
   # Every attribute is checked against the schema of the bundled plotly.js release when it
   # is added, so a typo fails where it was written instead of silently drawing nothing.
@@ -20,12 +20,15 @@ module Plotly
     attr_reader :layout
     # @return [Hash{String => Object}] plotly.js config (modebar, responsiveness, ...)
     attr_reader :config
+    # @return [Array<Hash{String => Object}>] animation frames; direct mutation skips validation
+    attr_reader :frames
 
     # @param data [Array<Hash>] traces; a trace without `type` is a scatter trace
     # @param layout [Hash]
     # @param config [Hash]
     # @param validate [Boolean] check attributes against the plotly.js schema
-    def initialize(data: [], layout: {}, config: {}, validate: true)
+    # @param frames [Array<Hash>] partial trace/layout updates for animation
+    def initialize(data: [], layout: {}, config: {}, validate: true, frames: [])
       @validate = validate
       @grid = nil
       @data = []
@@ -34,6 +37,28 @@ module Plotly
       raise ArgumentError, "data must be an Array of trace Hashes, got #{data.inspect}" unless data.is_a?(Array)
 
       data.each { |trace| add_trace(trace) }
+      self.frames = frames
+    end
+
+    # Replaces the animation frames after validating all of them.
+    # Define the base traces first so frames may omit their trace types.
+    # @param frames [Array<Hash>]
+    # @return [Array<Hash>]
+    def frames=(frames)
+      raise ValidationError, "frames: expected an Array of Hashes" unless frames.is_a?(Array)
+
+      @frames = frames.each_with_index.map { |frame, i| build_frame(frame, i) }
+    end
+
+    # Appends a frame. `traces` maps its data entries to zero-based base trace indices.
+    # @param frame [Hash] frame attributes, merged with keyword arguments
+    # @return [self]
+    def add_frame(frame = {}, **attrs)
+      unless frame.is_a?(Hash)
+        raise ValidationError, "frames[#{@frames.size}]: expected a Hash"
+      end
+      @frames << build_frame(frame.transform_keys(&:to_s).merge(attrs.transform_keys(&:to_s)), @frames.size)
+      self
     end
 
     # Appends a trace.
@@ -41,23 +66,25 @@ module Plotly
     # @param trace [Hash] trace attributes; keyword arguments are merged into it
     # @param row [Integer, nil] subplot row (1-based), for figures made by {Plotly.make_subplots}
     # @param col [Integer, nil] subplot column (1-based)
+    # @param secondary_y [Boolean] use the cell's right y axis (requires row, col and a secondary_y spec)
     # @return [self]
-    def add_trace(trace = {}, row: nil, col: nil, **attrs)
+    def add_trace(trace = {}, row: nil, col: nil, secondary_y: false, **attrs)
+      check_secondary_y(secondary_y)
       trace = trace.to_h { |k, v| [k.to_s, v] }.merge(attrs.transform_keys(&:to_s))
       type = (trace.delete("type") || "scatter").to_s
       node = trace_node(type, "data[#{@data.size}]")
       built = {"type" => type}.merge(build(node, trace, "data[#{@data.size}]"))
-      built.merge!(cell_reference(node, row, col)) if row || col
+      built.merge!(cell_reference(node, row, col, secondary_y)) if row || col || secondary_y
       @data << built
       self
     end
 
     Schema.default.trace_types.each do |type|
-      # @!method add_scatter(row: nil, col: nil, **attrs)
+      # @!method add_scatter(row: nil, col: nil, secondary_y: false, **attrs)
       #   Appends a trace of this type; one such helper exists for every plotly.js trace type.
       #   @return [Figure]
-      define_method(:"add_#{type}") do |trace = {}, row: nil, col: nil, **attrs|
-        add_trace(trace.merge(attrs).merge(type: type), row: row, col: col)
+      define_method(:"add_#{type}") do |trace = {}, row: nil, col: nil, secondary_y: false, **attrs|
+        add_trace(trace.merge(attrs).merge(type: type), row: row, col: col, secondary_y: secondary_y)
       end
     end
 
@@ -81,10 +108,13 @@ module Plotly
     #   block receiving the normalized trace
     # @param row [Integer, nil] only traces in this subplot row
     # @param col [Integer, nil] only traces in this subplot column
+    # @param secondary_y [Boolean, nil] select right/left y-axis traces; nil selects both
     # @return [self]
-    def update_traces(attrs = {}, selector: nil, row: nil, col: nil, **kw)
+    def update_traces(attrs = {}, selector: nil, row: nil, col: nil, secondary_y: nil, **kw)
+      check_secondary_y(secondary_y)
+      grid! unless secondary_y.nil?
       attrs = attrs.merge(kw)
-      targets = @data.each_index.select { |i| selected?(@data[i], selector) && in_cell?(@data[i], row, col) }
+      targets = @data.each_index.select { |i| selected?(@data[i], selector) && in_cell?(@data[i], row, col, secondary_y) }
       updates = targets.to_h do |i|
         [i, build(trace_node(@data[i]["type"], "data[#{i}]"), attrs, "data[#{i}]")]
       end
@@ -97,17 +127,22 @@ module Plotly
     def update_xaxes(attrs = {}, row: nil, col: nil, **kw) = update_axes("x", attrs.merge(kw), row, col)
 
     # Deep-merges attributes into every y axis, or into the y axis of one subplot.
+    # @param secondary_y [Boolean, nil] select right/left y axes; nil selects both
     # @return [self]
-    def update_yaxes(attrs = {}, row: nil, col: nil, **kw) = update_axes("y", attrs.merge(kw), row, col)
+    def update_yaxes(attrs = {}, row: nil, col: nil, secondary_y: nil, **kw)
+      check_secondary_y(secondary_y)
+      update_axes("y", attrs.merge(kw), row, col, secondary_y)
+    end
 
     # Renders the figure as HTML. See {HTML.render} for the options.
     #
     # @example In a Rails view
     #   <%= raw @figure.to_html(height: 400) %>
     # @return [String] an HTML fragment (or document with `full_html: true`)
-    def to_html(include_plotlyjs: :cdn, full_html: false, div_id: nil, width: nil, height: nil)
+    def to_html(include_plotlyjs: :cdn, full_html: false, div_id: nil, width: nil, height: nil,
+      auto_play: true, animation_opts: {})
       HTML.render(self, include_plotlyjs: include_plotlyjs, full_html: full_html, div_id: div_id,
-        width: width, height: height)
+        width: width, height: height, auto_play: auto_play, animation_opts: animation_opts)
     end
 
     # Writes a standalone HTML page. By default plotly.js is embedded so the file works offline
@@ -115,9 +150,13 @@ module Plotly
     #
     # @param path [String]
     # @param open [Boolean] also open the page in the default browser
+    # @param auto_play [Boolean] start animation after the figure is drawn
+    # @param animation_opts [Hash] options passed to Plotly.animate
     # @return [String] the path written
-    def write_html(path, include_plotlyjs: :inline, open: false, width: nil, height: nil)
-      File.write(path, to_html(include_plotlyjs: include_plotlyjs, full_html: true, width: width, height: height))
+    def write_html(path, include_plotlyjs: :inline, open: false, width: nil, height: nil,
+      auto_play: true, animation_opts: {})
+      File.write(path, to_html(include_plotlyjs: include_plotlyjs, full_html: true, width: width, height: height,
+        auto_play: auto_play, animation_opts: animation_opts))
       Browser.open(File.expand_path(path)) if open
       path
     end
@@ -144,9 +183,13 @@ module Plotly
     # @return [Array(String, String)]
     def to_iruby = ["text/html", HTML.notebook(self)]
 
-    # @return [Hash{String => Object}] `{"data" => [...], "layout" => {...}}`, sharing the
+    # @return [Hash{String => Object}] data, layout and nonempty frames, sharing the
     #   figure's own Hashes: changing them skips validation, as with {#data} and {#layout}
-    def to_h = {"data" => @data, "layout" => @layout}
+    def to_h
+      result = {"data" => @data, "layout" => @layout}
+      result["frames"] = @frames unless @frames.empty?
+      result
+    end
 
     # @return [String] the figure as plotly.js JSON (config is not included, as in plotly.py)
     def to_json(*) = Serializer.dump(to_h)
@@ -166,6 +209,10 @@ module Plotly
 
     def schema = Schema.default
 
+    def build_frame(frame, index)
+      Frames.build(frame, data: @data, path: "frames[#{index}]", validate: @validate)
+    end
+
     def build(node, attrs, path) = Attributes.build(node, attrs, path: path, validate: @validate)
 
     def trace_node(type, path)
@@ -187,25 +234,34 @@ module Plotly
       end
     end
 
-    def in_cell?(trace, row, col)
-      return true unless row || col
+    def check_secondary_y(value)
+      raise ArgumentError, "secondary_y must be true, false or nil" unless [true, false, nil].include?(value)
+    end
+
+    def in_cell?(trace, row, col, secondary_y = nil)
+      return true unless row || col || !secondary_y.nil?
 
       grid!.cells(row, col).any? do |cell|
         domain = trace["domain"]
         if domain.is_a?(Hash)
-          domain["x"] == cell.x_domain && domain["y"] == cell.y_domain
+          secondary_y.nil? && domain["x"] == cell.x_domain && domain["y"] == cell.y_domain
         elsif schema.trace(trace["type"])&.child("xaxis")
-          cell.axis_ids == [(trace["xaxis"] || "x").to_s, (trace["yaxis"] || "y").to_s]
+          axes = [(trace["xaxis"] || "x").to_s, (trace["yaxis"] || "y").to_s]
+          (secondary_y != true && cell.axis_ids == axes) ||
+            (secondary_y != false && cell.secondary_index && cell.axis_ids(true) == axes)
         else
           false # 3D, polar, map... traces are not in any cell
         end
       end
     end
 
-    def cell_reference(node, row, col)
+    def cell_reference(node, row, col, secondary_y)
       cell = grid!.cell(row, col)
+      if secondary_y && (!node.child("xaxis") || !cell.secondary_index)
+        raise ArgumentError, "secondary_y needs a cartesian trace and a cell with specs: {secondary_y: true}"
+      end
       if node.child("xaxis")
-        {"xaxis" => cell.axis_ids[0], "yaxis" => cell.axis_ids[1]}
+        {"xaxis" => cell.axis_ids[0], "yaxis" => cell.axis_ids(secondary_y)[1]}
       elsif node.child("domain")
         {"domain" => {"x" => cell.x_domain, "y" => cell.y_domain}}
       else
@@ -213,9 +269,9 @@ module Plotly
       end
     end
 
-    def update_axes(letter, attrs, row, col)
-      keys = if row || col
-        grid!.cells(row, col).map { |cell| cell.layout_key(letter) }
+    def update_axes(letter, attrs, row, col, secondary_y = nil)
+      keys = if row || col || !secondary_y.nil?
+        grid!.cells(row, col).flat_map { |cell| (letter == "y") ? cell.y_keys(secondary_y) : [cell.layout_key(letter)] }
       else
         # Traces on cartesian axes refer to x/y unless they name another axis.
         referenced = @data.filter_map do |t|

data/lib/plotly/frames.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Plotly
+  # Normalizes animation frames and validates their partial trace and layout updates.
+  # @api private
+  module Frames
+    module_function
+
+    def build(frame, data:, path:, validate:)
+      schema = Schema.default
+      result = Attributes.build(schema.frame, frame, path: path, validate: validate)
+      traces = result["traces"]
+      if !traces.nil? && !(traces.is_a?(Array) && traces.all? { |i| i.is_a?(Integer) && i >= 0 })
+        raise ValidationError, "#{path}.traces: expected an Array of non-negative trace indices"
+      end
+      unless result["data"].nil?
+        unless result["data"].is_a?(Array) && result["data"].all?(Hash)
+          raise ValidationError, "#{path}.data: expected an Array of Hashes"
+        end
+        result["data"] = result["data"].each_with_index.map do |trace, i|
+          trace = trace.transform_keys(&:to_s)
+          target = traces&.fetch(i, i) || i
+          explicit_type = trace.delete("type")
+          type = (explicit_type || data[target]&.fetch("type", nil) || "scatter").to_s
+          node = schema.trace(type)
+          raise ValidationError, "#{path}.data[#{i}].type: #{type.inspect} is not a plotly.js trace type" unless node
+
+          attrs = Attributes.build(node, trace, path: "#{path}.data[#{i}]", validate: validate)
+          explicit_type ? {"type" => type}.merge(attrs) : attrs
+        end
+      end
+      unless result["layout"].nil?
+        result["layout"] = Attributes.build(schema.layout, result["layout"], path: "#{path}.layout", validate: validate)
+      end
+      result
+    end
+  end
+end

data/lib/plotly/html.rb

@@ -25,13 +25,16 @@ module Plotly
     # @param height [Integer, String, nil] element height; by default the layout height, else
     #   450px for a fragment (a percentage would collapse in a container of automatic height)
     #   and the whole window for a full document
+    # @param auto_play [Boolean] start animation after registering frames
+    # @param animation_opts [Hash] options passed to Plotly.animate (frame and transition durations, etc.)
     # @return [String]
-    def render(figure, include_plotlyjs: :cdn, full_html: false, div_id: nil, width: nil, height: nil)
+    def render(figure, include_plotlyjs: :cdn, full_html: false, div_id: nil, width: nil, height: nil,
+      auto_play: true, animation_opts: {})
       id = div_id || "rbplotly-#{SecureRandom.uuid}"
       body = [
         plotlyjs_tag(include_plotlyjs),
         %(<div id="#{CGI.escapeHTML(id)}" class="plotly-graph-div" style="#{style(width, height || default_height(figure, full_html))}"></div>),
-        "<script>\n#{draw_call(figure, id)}\n</script>"
+        "<script>\n#{draw_call(figure, id, auto_play: auto_play, animation_opts: animation_opts)}\n</script>"
       ].compact.join("\n")
       full_html ? document(figure, body) : body
     end
@@ -69,10 +72,18 @@ module Plotly
     end
 
     # @api private
-    def draw_call(figure, id)
+    def draw_call(figure, id, auto_play: true, animation_opts: {})
       config = DEFAULT_CONFIG.merge(figure.config)
       args = [id, figure.data, figure.layout, config].map { |arg| Serializer.dump(arg) }
-      "Plotly.newPlot(#{args.join(", ")});"
+      script = "Plotly.newPlot(#{args.join(", ")})"
+      unless figure.frames.empty?
+        plot_id = Serializer.dump(id)
+        script += ".then(function () { return Plotly.addFrames(#{plot_id}, #{Serializer.dump(figure.frames)}); })"
+        if auto_play
+          script += ".then(function () { return Plotly.animate(#{plot_id}, null, #{Serializer.dump(animation_opts)}); })"
+        end
+      end
+      script + ";"
     end
 
     def plotlyjs_tag(mode)

data/lib/plotly/schema/plot-schema.json

@@ -57230,5 +57230,29 @@
         "type": "boolean"
       }
     }
+  },
+  "frames": {
+    "array": {
+      "attrs": {
+        "baseframe": {
+          "type": "string"
+        },
+        "data": {
+          "type": "any"
+        },
+        "group": {
+          "type": "string"
+        },
+        "layout": {
+          "type": "any"
+        },
+        "name": {
+          "type": "string"
+        },
+        "traces": {
+          "type": "any"
+        }
+      }
+    }
   }
 }

data/lib/plotly/schema.rb

@@ -92,5 +92,8 @@ module Plotly
 
     # @return [Node] plotly.js config options
     def config = Node.new("config", @raw.fetch("config"))
+
+    # @return [Node] attributes of an animation frame (data and layout are validated separately)
+    def frame = Node.new("frames", @raw.fetch("frames")).item
   end
 end

data/lib/plotly/subplots.rb

@@ -18,11 +18,15 @@ module Plotly
   # @param subplot_titles [Array<String>, nil] one title per cell, in row-major order
   # @param horizontal_spacing [Float] gap between columns, as a fraction of the figure width
   # @param vertical_spacing [Float] gap between rows, as a fraction of the figure height
+  # @param column_widths [Array<Numeric>, nil] positive relative column widths, left to right
+  # @param row_heights [Array<Numeric>, nil] positive relative row heights, top to bottom
+  # @param specs [Array<Array<Hash>>, nil] one hash per cell; `secondary_y: true` adds a right y axis
   # @param figure_options [Hash] passed to {Figure#initialize} (`layout:`, `config:`, `validate:`)
   # @return [Figure]
   def self.make_subplots(rows: 1, cols: 1, shared_xaxes: false, shared_yaxes: false, subplot_titles: nil,
-    horizontal_spacing: 0.2 / cols, vertical_spacing: 0.3 / rows, **figure_options)
-    grid = Subplots::Grid.new(rows, cols, horizontal_spacing, vertical_spacing)
+    horizontal_spacing: nil, vertical_spacing: nil, column_widths: nil, row_heights: nil, specs: nil, **figure_options)
+    grid = Subplots::Grid.new(rows, cols, horizontal_spacing, vertical_spacing,
+      column_widths: column_widths, row_heights: row_heights, specs: specs)
     titles = Array(subplot_titles)
     if titles.size > grid.cells.size
       raise ArgumentError, "#{titles.size} subplot titles for #{grid.cells.size} cells"
@@ -39,34 +43,52 @@ module Plotly
   # Grid layout behind {Plotly.make_subplots}.
   # @api private
   module Subplots
-    Cell = Struct.new(:row, :col, :index, :x_domain, :y_domain) do
+    Cell = Struct.new(:row, :col, :index, :x_domain, :y_domain, :secondary_index) do
       def suffix = (index == 1) ? "" : index.to_s
 
-      def axis_ids = ["x#{suffix}", "y#{suffix}"]
+      def axis_ids(secondary_y = false) = ["x#{suffix}", secondary_y ? "y#{secondary_index}" : "y#{suffix}"]
 
       def layout_key(letter) = "#{letter}axis#{suffix}"
+
+      def y_keys(secondary_y = nil)
+        keys = []
+        keys << layout_key("y") unless secondary_y == true
+        keys << "yaxis#{secondary_index}" if secondary_index && secondary_y != false
+        keys
+      end
     end
 
     class Grid
       attr_reader :rows, :cols
 
-      def initialize(rows, cols, horizontal_spacing, vertical_spacing)
+      def initialize(rows, cols, horizontal_spacing, vertical_spacing, column_widths: nil, row_heights: nil, specs: nil)
         unless rows.is_a?(Integer) && cols.is_a?(Integer) && rows.positive? && cols.positive?
           raise ArgumentError, "rows and cols must be positive integers"
         end
 
         @rows = rows
         @cols = cols
-        width = (1.0 - horizontal_spacing * (cols - 1)) / cols
-        height = (1.0 - vertical_spacing * (rows - 1)) / rows
-        raise ArgumentError, "spacing leaves no room for the subplots" unless width.positive? && height.positive?
-
+        horizontal_spacing = 0.2 / cols if horizontal_spacing.nil?
+        vertical_spacing = 0.3 / rows if vertical_spacing.nil?
+        horizontal_spacing = spacing(horizontal_spacing, cols, "horizontal_spacing")
+        vertical_spacing = spacing(vertical_spacing, rows, "vertical_spacing")
+        widths = sizes(column_widths, cols, 1.0 - horizontal_spacing * (cols - 1), "column_widths")
+        heights = sizes(row_heights, rows, 1.0 - vertical_spacing * (rows - 1), "row_heights")
+        secondary = secondary_cells(specs)
+        next_axis = rows * cols
+
+        y1 = 1.0
         @cells = (1..rows).flat_map do |row|
-          (1..cols).map do |col|
-            x0 = (col - 1) * (width + horizontal_spacing)
-            y1 = 1.0 - (row - 1) * (height + vertical_spacing)
-            Cell.new(row, col, (row - 1) * cols + col, domain(x0, x0 + width), domain(y1 - height, y1))
+          x0 = 0.0
+          cells = (1..cols).map do |col|
+            second_axis = secondary[row - 1][col - 1] ? (next_axis += 1) : nil
+            cell = Cell.new(row, col, (row - 1) * cols + col,
+              domain(x0, x0 + widths[col - 1]), domain(y1 - heights[row - 1], y1), second_axis)
+            x0 += widths[col - 1] + horizontal_spacing
+            cell
           end
+          y1 -= heights[row - 1] + vertical_spacing
+          cells
         end
       end
 
@@ -91,6 +113,10 @@ module Plotly
           layout[cell.layout_key("y")] = {"domain" => cell.y_domain, "anchor" => x_id}.merge(
             (shared_y && cell.col != 1) ? linked(cell(cell.row, 1).axis_ids[1]) : {}
           )
+          if cell.secondary_index
+            layout["yaxis#{cell.secondary_index}"] = {"anchor" => x_id, "overlaying" => y_id,
+              "side" => "right", "automargin" => true}
+          end
         end
       end
 
@@ -109,6 +135,48 @@ module Plotly
 
       private
 
+      def positive_number?(value)
+        value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite? && value.positive?
+      end
+
+      def spacing(value, count, name)
+        unless value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite? && value.between?(0, 1)
+          raise ArgumentError, "#{name} must be a finite number between 0 and 1"
+        end
+        raise ArgumentError, "spacing leaves no room for the subplots" unless value * (count - 1) < 1
+
+        value.to_f
+      end
+
+      def sizes(values, count, available, name)
+        values = Array.new(count, 1) if values.nil?
+        unless values.is_a?(Array) && values.size == count && values.all? { |v| positive_number?(v) }
+          raise ArgumentError, "#{name} must contain #{count} positive finite numbers"
+        end
+        largest = values.max
+        weights = values.map { |v| v.fdiv(largest) }
+        total = weights.sum
+        weights.map { |v| available * v / total }
+      end
+
+      def secondary_cells(specs)
+        return Array.new(rows) { Array.new(cols, false) } if specs.nil?
+        unless specs.is_a?(Array) && specs.size == rows && specs.all? { |row| row.is_a?(Array) && row.size == cols }
+          raise ArgumentError, "specs must be a #{rows}x#{cols} array of cell hashes"
+        end
+        specs.map do |row|
+          row.map do |spec|
+            unless spec.is_a?(Hash) && spec.keys.all? { |k| k.to_s == "secondary_y" }
+              raise ArgumentError, "each spec must be a Hash with only the secondary_y option"
+            end
+            value = spec.transform_keys(&:to_s).fetch("secondary_y", false)
+            raise ArgumentError, "secondary_y must be true or false" unless [true, false].include?(value)
+
+            value
+          end
+        end
+      end
+
       # Follows another axis' range and leaves the tick labels to it.
       def linked(axis_id) = {"matches" => axis_id, "showticklabels" => false}
 

data/lib/plotly/version.rb

@@ -2,7 +2,7 @@
 
 module Plotly
   # The gem version.
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 
   # The plotly.js release this gem's schema, CDN URL and bundled script are built from.
   PLOTLY_JS_VERSION = "4.1.2"

data/lib/plotly.rb

@@ -16,6 +16,7 @@ require_relative "plotly/schema"
 require_relative "plotly/attributes"
 require_relative "plotly/serializer"
 require_relative "plotly/html"
+require_relative "plotly/frames"
 require_relative "plotly/figure"
 require_relative "plotly/subplots"
 require_relative "plotly/plot"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbplotly
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Yoshihiro Ashida
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.9'
 description: Build Plotly.js figures with plain Ruby hashes, check every attribute
   against the plot schema of the bundled plotly.js release, and write self-contained
   HTML that works offline, in Rails views and in Jupyter (IRuby). No account or API
@@ -40,6 +40,7 @@ files:
 - lib/plotly/assets/plotly.min.js
 - lib/plotly/attributes.rb
 - lib/plotly/figure.rb
+- lib/plotly/frames.rb
 - lib/plotly/html.rb
 - lib/plotly/plot.rb
 - lib/plotly/schema.rb