rbplotly 0.1.1 → 1.0.0

data/lib/plotly/attributes.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "date"
+require "did_you_mean" # explicit, so suggestions work under --disable-did_you_mean too
+
+module Plotly
+  # Turns user-supplied attribute hashes into plotly.js attribute trees.
+  #
+  # Keys become strings, underscore paths expand (`marker_line_width: 2` becomes
+  # `{"marker" => {"line" => {"width" => 2}}}`) and, unless validation is off, every key and
+  # value is checked against the schema. Values themselves are kept as given; converting them
+  # to JSON is {Serializer}'s job.
+  module Attributes
+    module_function
+
+    # @param node [Schema::Node] schema of the object being built
+    # @param attrs [Hash]
+    # @param path [String] location used in error messages, e.g. "data[0]" or "layout"
+    # @param validate [Boolean]
+    # @return [Hash{String => Object}]
+    def build(node, attrs, path:, validate: true)
+      Builder.new(validate).object(node, attrs, path)
+    end
+
+    # Merges two attribute trees built by {build}; nested hashes merge, everything else is replaced.
+    def deep_merge(base, other)
+      base.merge(other) do |_key, old, new|
+        (old.is_a?(Hash) && new.is_a?(Hash)) ? deep_merge(old, new) : new
+      end
+    end
+
+    # Walks one attribute hash against its schema node.
+    # @api private
+    class Builder
+      def initialize(validate)
+        @validate = validate
+      end
+
+      def object(node, attrs, path)
+        unless attrs.is_a?(Hash)
+          raise ValidationError, "#{path}: expected a Hash, got #{attrs.inspect}"
+        end
+
+        attrs.each_with_object({}) do |(key, value), result|
+          key = key.to_s
+          child = node&.child(key)
+          if child.nil? && (expanded = expand(node, key, value))
+            assign(result, expanded.first, object(node.child(expanded.first), expanded.last, join(path, expanded.first)))
+          else
+            unknown!(node, key, path) if child.nil? && node && @validate
+            assign(result, key, value(child, value, join(path, key)))
+          end
+        end
+      end
+
+      private
+
+      def join(path, key) = path.empty? ? key : "#{path}.#{key}"
+
+      def assign(result, key, value)
+        result[key] = (result[key].is_a?(Hash) && value.is_a?(Hash)) ? Attributes.deep_merge(result[key], value) : value
+      end
+
+      # "marker_line_width" => ["marker", {"line_width" => value}] when marker is an object.
+      def expand(node, key, value)
+        return nil unless node
+
+        positions = (0...key.length).select { |i| key[i] == "_" }.reverse
+        positions.each do |i|
+          head = key[0...i]
+          child = node.child(head)
+          return [head, {key[(i + 1)..] => value}] if child&.object?
+        end
+        nil
+      end
+
+      def value(node, value, path)
+        return value if node.nil? || value.nil? # nil unsets an attribute, nested ones included
+        return object(node, value, path) if node.object? && value.is_a?(Hash)
+
+        if node.object?
+          invalid_object!(node, value, path) if @validate
+          value
+        elsif node.array?
+          array(node, value, path)
+        else
+          leaf(node, value, path) if @validate
+          value
+        end
+      end
+
+      def array(node, value, path)
+        unless value.is_a?(Array) && value.all?(Hash)
+          return value unless @validate
+
+          raise ValidationError, "#{path}: expected an Array of Hashes, got #{value.inspect}"
+        end
+        value.each_with_index.map { |item, i| object(node.item, item, "#{path}[#{i}]") }
+      end
+
+      def leaf(node, value, path, attr_path = path)
+        if node.array_ok? && array_like?(value)
+          # Nested arrays too: table cells take one value per cell ([[12, 14], ...]).
+          value.to_a.each_with_index { |v, i| leaf(node, v, "#{path}[#{i}]", attr_path) }
+        else
+          scalar(node, value, path, attr_path)
+        end
+      end
+
+      def scalar(node, value, path, attr_path)
+        return if value.nil?
+
+        case node.type
+        when "enumerated" then enumerated(node, value, path)
+        when "flaglist" then flaglist(node, value, path, attr_path)
+        when "boolean"
+          invalid!(path, "expected true or false, got #{value.inspect}") unless [true, false].include?(value)
+        when "number", "integer" then number(node, value, path)
+        when "angle" then number(node, value, path) unless value.to_s == "auto"
+        end
+      end
+
+      # Arrays, Ranges, Sets and data frame columns; Serializer writes all of them as arrays.
+      def array_like?(value)
+        case value
+        when Array then true
+        when String, Symbol, Hash, Numeric, Time, Date, true, false, nil then false
+        else value.respond_to?(:to_a)
+        end
+      end
+
+      def enumerated(node, value, path)
+        given = value.is_a?(Symbol) ? value.to_s : value
+        return if node.values.any? { |allowed| allowed_value?(allowed, given) }
+
+        listed = node.values.reject { |v| pattern?(v) }
+        message = "#{given.inspect} is not one of #{listed.map(&:inspect).join(", ")}"
+        if given.is_a?(String)
+          words = listed.grep(String)
+          suggestion = DidYouMean::SpellChecker.new(dictionary: words).correct(given).first
+          message += ". Did you mean #{suggestion.inspect}?" if suggestion
+        end
+        invalid!(path, message)
+      end
+
+      def allowed_value?(allowed, given)
+        return Regexp.new(allowed[1..-2]).match?(given) if pattern?(allowed) && given.is_a?(String)
+
+        allowed == given
+      end
+
+      def pattern?(value) = value.is_a?(String) && value.length > 1 && value.start_with?("/") && value.end_with?("/")
+
+      def flaglist(node, value, path, attr_path)
+        # Extras may be booleans (config.scrollZoom, axis automargin) as well as strings.
+        return if node.extras.include?(value) || node.extras.include?(value.to_s)
+        if [true, false].include?(value)
+          invalid!(path, "#{value} is not allowed for #{attr_path.split(".").last}")
+        end
+
+        given = value.to_s
+
+        name = attr_path.split(".").last
+        given.split("+").each do |flag|
+          next if node.flags.include?(flag)
+
+          suggestion = DidYouMean::SpellChecker.new(dictionary: node.flags).correct(flag).first
+          message = "#{flag.inspect} is not a flag of #{name}."
+          message += " Did you mean #{suggestion.inspect}?" if suggestion
+          message += " Join #{node.flags.map(&:inspect).join(", ")} with \"+\""
+          message += case node.extras.size
+          when 0 then ""
+          when 1 then ", or use #{node.extras.first.inspect}"
+          else ", or use one of #{node.extras.map(&:inspect).join(", ")}"
+          end
+          invalid!(path, message)
+        end
+      end
+
+      # Follows plotly.js' coercion: named extras ("bold" for font.weight), numeric strings,
+      # and whole floats for integers are accepted.
+      def number(node, value, path)
+        return if !value.is_a?(Numeric) && node.extras.include?(value.to_s)
+
+        integer = node.type == "integer"
+        number = case value
+        when Complex then nil
+        when Numeric then value
+        when String then Float(value, exception: false)
+        end
+        ok = !number.nil? && (!integer || (number.finite? && number == number.round))
+        invalid!(path, "expected #{integer ? "an integer" : "a number"}, got #{value.inspect}") unless ok
+
+        invalid!(path, "#{value} is less than the minimum #{node.min}") if node.min && number < node.min
+        invalid!(path, "#{value} is greater than the maximum #{node.max}") if node.max && number > node.max
+      end
+
+      def invalid_object!(node, value, path)
+        hint = ""
+        if value.is_a?(String) && node.attribute_names.include?("text")
+          key = path.split(".").last
+          underscored = path.split(".").drop(1).join("_")
+          hint = ". Plotly.js no longer accepts a plain string here: use #{key}: {text: #{value.inspect}} " \
+            "or #{underscored}_text: #{value.inspect}"
+        end
+        raise ValidationError, "#{path}: expected a Hash of #{node.name} attributes, got #{value.inspect}#{hint}"
+      end
+
+      def invalid!(path, message)
+        raise ValidationError, "#{path}: #{message}"
+      end
+
+      def unknown!(node, key, path)
+        message = "#{join(path, key)}: #{node.name} has no attribute #{key.inspect}"
+        suggestion = DidYouMean::SpellChecker.new(dictionary: node.attribute_names).correct(key).first
+        message += ". Did you mean #{suggestion.inspect}?" if suggestion
+        raise ValidationError, message
+      end
+    end
+  end
+end

data/lib/plotly/figure.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+
+module Plotly
+  # A plotly.js figure: traces (`data`), `layout` and `config`.
+  #
+  # 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.
+  #
+  # @example
+  #   fig = Plotly::Figure.new
+  #     .add_scatter(x: [1, 2, 3], y: [2, 1, 3], mode: :lines, name: "Model")
+  #     .update_layout(title_text: "Forecast", xaxis_title_text: "Day")
+  #   fig.write_html("forecast.html")
+  class Figure
+    # @return [Array<Hash{String => Object}>] traces, normalized. Changing them directly skips validation.
+    attr_reader :data
+    # @return [Hash{String => Object}] the layout, normalized. Changing it directly skips validation.
+    attr_reader :layout
+    # @return [Hash{String => Object}] plotly.js config (modebar, responsiveness, ...)
+    attr_reader :config
+
+    # @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)
+      @validate = validate
+      @grid = nil
+      @data = []
+      @layout = build(schema.layout, layout, "layout")
+      @config = build(schema.config, config, "config")
+      raise ArgumentError, "data must be an Array of trace Hashes, got #{data.inspect}" unless data.is_a?(Array)
+
+      data.each { |trace| add_trace(trace) }
+    end
+
+    # Appends a trace.
+    #
+    # @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)
+    # @return [self]
+    def add_trace(trace = {}, row: nil, col: nil, **attrs)
+      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
+      @data << built
+      self
+    end
+
+    Schema.default.trace_types.each do |type|
+      # @!method add_scatter(row: nil, col: nil, **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)
+      end
+    end
+
+    # Deep-merges attributes into the layout. Nothing changes if any attribute is invalid.
+    # @return [self]
+    def update_layout(attrs = {}, **kw)
+      @layout = Attributes.deep_merge(@layout, build(schema.layout, attrs.merge(kw), "layout"))
+      self
+    end
+
+    # Deep-merges attributes into the config.
+    # @return [self]
+    def update_config(attrs = {}, **kw)
+      @config = Attributes.deep_merge(@config, build(schema.config, attrs.merge(kw), "config"))
+      self
+    end
+
+    # Deep-merges attributes into every trace, or into the traces that match.
+    #
+    # @param selector [Hash, Proc, nil] attributes a trace must have (`{type: :bar}`), or a
+    #   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
+    # @return [self]
+    def update_traces(attrs = {}, selector: nil, row: nil, col: nil, **kw)
+      attrs = attrs.merge(kw)
+      targets = @data.each_index.select { |i| selected?(@data[i], selector) && in_cell?(@data[i], row, col) }
+      updates = targets.to_h do |i|
+        [i, build(trace_node(@data[i]["type"], "data[#{i}]"), attrs, "data[#{i}]")]
+      end
+      updates.each { |i, update| @data[i] = Attributes.deep_merge(@data[i], update) }
+      self
+    end
+
+    # Deep-merges attributes into every x axis, or into the x axis of one subplot.
+    # @return [self]
+    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.
+    # @return [self]
+    def update_yaxes(attrs = {}, row: nil, col: nil, **kw) = update_axes("y", attrs.merge(kw), row, col)
+
+    # 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)
+      HTML.render(self, include_plotlyjs: include_plotlyjs, full_html: full_html, div_id: div_id,
+        width: width, height: height)
+    end
+
+    # Writes a standalone HTML page. By default plotly.js is embedded so the file works offline
+    # and can be shared as a single attachment.
+    #
+    # @param path [String]
+    # @param open [Boolean] also open the page in the default browser
+    # @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))
+      Browser.open(File.expand_path(path)) if open
+      path
+    end
+
+    # Shows the figure: inline in an IRuby notebook, otherwise as a temporary page in the browser.
+    # @return [String, nil] the temporary file outside notebooks
+    def show
+      if defined?(::IRuby) && ::IRuby.respond_to?(:display)
+        ::IRuby.display(self)
+        return nil
+      end
+
+      write_html(File.join(Dir.tmpdir, "rbplotly-#{SecureRandom.hex(8)}.html"), open: true)
+    end
+
+    # IRuby's display hook. IRuby 0.8 prefers it to {#to_html}, whose output would run before
+    # plotly.js loads in a notebook.
+    # @return [Array(Hash{String => String}, Hash)] formats and metadata
+    def to_iruby_mimebundle(include: [])
+      [{"text/html" => HTML.notebook(self)}, {}]
+    end
+
+    # IRuby's display hook in versions before 0.8.
+    # @return [Array(String, String)]
+    def to_iruby = ["text/html", HTML.notebook(self)]
+
+    # @return [Hash{String => Object}] `{"data" => [...], "layout" => {...}}`, sharing the
+    #   figure's own Hashes: changing them skips validation, as with {#data} and {#layout}
+    def to_h = {"data" => @data, "layout" => @layout}
+
+    # @return [String] the figure as plotly.js JSON (config is not included, as in plotly.py)
+    def to_json(*) = Serializer.dump(to_h)
+
+    # @return [String] trace types and layout keys, without the data
+    def inspect
+      "#<#{self.class.name} data=[#{@data.map { |t| t["type"] }.join(", ")}] layout=[#{@layout.keys.join(", ")}]>"
+    end
+
+    # @api private
+    # @param grid [Subplots::Grid] set by {Plotly.make_subplots}
+    def subplot_grid=(grid)
+      @grid = grid
+    end
+
+    private
+
+    def schema = Schema.default
+
+    def build(node, attrs, path) = Attributes.build(node, attrs, path: path, validate: @validate)
+
+    def trace_node(type, path)
+      node = schema.trace(type)
+      return node if node
+
+      message = "#{path}.type: #{type.inspect} is not a plotly.js trace type"
+      suggestion = DidYouMean::SpellChecker.new(dictionary: schema.trace_types).correct(type).first
+      raise ValidationError, suggestion ? "#{message}. Did you mean #{suggestion.inspect}?" : message
+    end
+
+    def selected?(trace, selector)
+      case selector
+      when nil then true
+      when Proc then selector.call(trace)
+      when Hash
+        selector.all? { |key, value| Serializer.plain(trace[key.to_s]) == Serializer.plain(value) }
+      else raise ArgumentError, "selector must be a Hash or a Proc, got #{selector.inspect}"
+      end
+    end
+
+    def in_cell?(trace, row, col)
+      return true unless row || col
+
+      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
+        elsif schema.trace(trace["type"])&.child("xaxis")
+          cell.axis_ids == [(trace["xaxis"] || "x").to_s, (trace["yaxis"] || "y").to_s]
+        else
+          false # 3D, polar, map... traces are not in any cell
+        end
+      end
+    end
+
+    def cell_reference(node, row, col)
+      cell = grid!.cell(row, col)
+      if node.child("xaxis")
+        {"xaxis" => cell.axis_ids[0], "yaxis" => cell.axis_ids[1]}
+      elsif node.child("domain")
+        {"domain" => {"x" => cell.x_domain, "y" => cell.y_domain}}
+      else
+        raise ArgumentError, "#{node.name} traces cannot be placed in a subplot cell"
+      end
+    end
+
+    def update_axes(letter, attrs, row, col)
+      keys = if row || col
+        grid!.cells(row, col).map { |cell| cell.layout_key(letter) }
+      else
+        # Traces on cartesian axes refer to x/y unless they name another axis.
+        referenced = @data.filter_map do |t|
+          next unless schema.trace(t["type"])&.child("#{letter}axis")
+
+          (t["#{letter}axis"] || letter).to_s.sub(/\A#{letter}/, "#{letter}axis")
+        end
+        found = (@layout.keys.grep(/\A#{letter}axis\d*\z/) + referenced).uniq
+        found.empty? ? ["#{letter}axis"] : found
+      end
+      update_layout(keys.to_h { |key| [key, attrs] })
+    end
+
+    def grid!
+      @grid or raise ArgumentError, "row and col need a figure made by Plotly.make_subplots"
+    end
+  end
+end

data/lib/plotly/html.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "securerandom"
+
+module Plotly
+  # Renders figures as HTML.
+  module HTML
+    # The plotly.js build that `include_plotlyjs: :cdn` and notebook output load.
+    CDN_URL = "https://cdn.plot.ly/plotly-#{PLOTLY_JS_VERSION}.min.js"
+    # The same build, bundled in the gem for `include_plotlyjs: :inline`.
+    BUNDLE_PATH = File.expand_path("assets/plotly.min.js", __dir__)
+    # Config applied under the figure's own config.
+    DEFAULT_CONFIG = {"responsive" => true}.freeze
+
+    module_function
+
+    # @param figure [Figure]
+    # @param include_plotlyjs [:cdn, :inline, false, String] how the page gets plotly.js:
+    #   the pinned CDN build, the bundled copy embedded in the page (works offline), not at
+    #   all (the page already loads it), or from the given URL
+    # @param full_html [Boolean] a whole document instead of a fragment
+    # @param div_id [String, nil] id of the chart element; random by default
+    # @param width [Integer, String, nil] element width (Integer means pixels); 100% by default
+    # @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
+    # @return [String]
+    def render(figure, include_plotlyjs: :cdn, full_html: false, div_id: nil, width: nil, height: nil)
+      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>"
+      ].compact.join("\n")
+      full_html ? document(figure, body) : body
+    end
+
+    # HTML for Jupyter frontends (classic Notebook, JupyterLab, VS Code): loads plotly.js once
+    # per page and draws. plotly.js 3+ always registers itself as `window.Plotly`, never as an
+    # AMD module, so a plain script element works even where the page uses RequireJS.
+    def notebook(figure)
+      id = "rbplotly-#{SecureRandom.uuid}"
+      <<~HTML
+        <div id="#{id}" class="plotly-graph-div" style="#{style(nil, default_height(figure, false))}"></div>
+        <script>
+        (function () {
+          var src = "#{CDN_URL}";
+          function draw(Plotly) {
+            #{draw_call(figure, id).gsub("\n", "\n    ")}
+          }
+          if (window.Plotly) { draw(window.Plotly); return; }
+          var script = document.querySelector('script[data-rbplotly="' + src + '"]');
+          if (!script) {
+            script = document.createElement("script");
+            script.src = src;
+            script.setAttribute("data-rbplotly", src);
+            document.head.appendChild(script);
+          }
+          script.addEventListener("load", function () { draw(window.Plotly); });
+          script.addEventListener("error", function () {
+            script.remove(); // so the next output tries again
+            var el = document.getElementById("#{id}");
+            if (el) el.textContent = "rbplotly: could not load plotly.js from " + src;
+          });
+        })();
+        </script>
+      HTML
+    end
+
+    # @api private
+    def draw_call(figure, id)
+      config = DEFAULT_CONFIG.merge(figure.config)
+      args = [id, figure.data, figure.layout, config].map { |arg| Serializer.dump(arg) }
+      "Plotly.newPlot(#{args.join(", ")});"
+    end
+
+    def plotlyjs_tag(mode)
+      case mode
+      when :cdn then script_src(CDN_URL)
+      when :inline then "<script>#{bundle.gsub("</script", "<\\/script")}</script>"
+      when false, nil then nil
+      when String then script_src(mode)
+      else
+        raise ArgumentError, "include_plotlyjs must be :cdn, :inline, false or a URL, got #{mode.inspect}"
+      end
+    end
+
+    def script_src(url) = %(<script src="#{CGI.escapeHTML(url)}" charset="utf-8"></script>)
+
+    def bundle
+      @bundle ||= File.read(BUNDLE_PATH, encoding: "UTF-8")
+    rescue Errno::ENOENT
+      raise Error, "the bundled plotly.js is missing (#{BUNDLE_PATH}). In a git checkout, run " \
+        "`bundle exec rake plotlyjs:fetch`, or use include_plotlyjs: :cdn"
+    end
+
+    def style(width, height)
+      "height:#{length(height)};width:#{length(width || "100%")};"
+    end
+
+    def default_height(figure, full_html)
+      layout_height = figure.layout["height"]
+      return layout_height.round if layout_height.is_a?(Numeric)
+
+      full_html ? "100%" : 450
+    end
+
+    def length(value) = value.is_a?(Integer) ? "#{value}px" : CGI.escapeHTML(value.to_s)
+
+    def document(figure, body)
+      title = figure.layout.dig("title", "text")
+      title = (title.is_a?(String) || title.is_a?(Symbol)) ? title.to_s : "Plotly figure"
+      <<~HTML
+        <!DOCTYPE html>
+        <html>
+        <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>#{CGI.escapeHTML(title)}</title>
+        <style>html, body { height: 100%; margin: 0; }</style>
+        </head>
+        <body>
+        #{body}
+        </body>
+        </html>
+      HTML
+    end
+
+    private_class_method :plotlyjs_tag, :script_src, :bundle, :style, :default_height, :length, :document
+  end
+
+  # Opens files in the desktop's default browser.
+  module Browser
+    module_function
+
+    # @param path [String] absolute path of an HTML file
+    def open(path)
+      command = case RbConfig::CONFIG["host_os"]
+      when /darwin/ then ["open", path]
+      # Not `cmd /c start`: cmd.exe would interpret &, | and ^ in the file name.
+      when /mswin|mingw|cygwin/ then ["explorer.exe", path]
+      else ["xdg-open", path]
+      end
+      Process.detach(Process.spawn(*command, out: File::NULL, err: File::NULL))
+    rescue SystemCallError
+      warn "rbplotly: could not open a browser; the chart is at #{path}"
+    end
+  end
+end

data/lib/plotly/plot.rb

@@ -1,47 +1,18 @@
-require 'plotly/data'
-require 'plotly/layout'
-require 'plotly/exportable'
-require 'plotly/offline/exportable'
+# frozen_string_literal: true
 
 module Plotly
-  class Plot
-    include Exportable
-    include Offline::Exportable
-
-    # @!attribute [r] data
-    #   @return [Array] list of Plotly::Data objects
-    # @!attribute [r] layout
-    #   @return [Plotly::Layout]
-    attr_reader :data, :layout
-
-    # @option data [Array] list of Hash or Plotly::Data objects
-    # @option layout [Hash or Plotly::Layout]
-    def initialize(data: [], layout: {})
-      @data   = data.map { |d| d.is_a?(Hash) ? Data.new(d) : d }
-      @layout = layout.convert_to(Plotly::Layout)
-    end
-
-    # @param data [Plotly::Data or Hash]
-    def add_data(data = Data.new)
-      @data.push begin
-        case data
-        when Data then data
-        when Hash then Data.new(data)
-        end
-      end
-    end
-
-    # @todo add remove_data method
-
-    # @param data [Array] list of Hash or Plotly::Data objects
-    def data=(data)
-      raise unless data.is_a?(Array)
-      @data = data.map { |d| d.convert_to(Plotly::Data) }
+  # The 0.x entry point, kept so existing code runs while it moves to {Figure}.
+  # @deprecated Use {Figure}; `generate_html(path:, open:)` becomes `write_html(path, open:)`.
+  class Plot < Figure
+    def initialize(data: [], layout: {}, **options)
+      warn "Plotly::Plot is deprecated and will be removed in rbplotly 2.0; use Plotly::Figure " \
+        "(generate_html(path:) is now write_html(path))", uplevel: 1
+      super
     end
 
-    # @param layout [Hash or Plotly::Layout]
-    def layout=(layout)
-      @layout = layout.convert_to(Plotly::Layout)
+    # @deprecated Use {Figure#write_html}.
+    def generate_html(path: "plot.html", open: true)
+      write_html(path, open: open)
     end
   end
 end