etassia 0.1.0

data/lib/etassia/renderer/user_journey.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../layout/user_journey"
+
+module Etassia
+  module Renderer
+    # User Journey diagram renderer for converting graphs to SVG.
+    #
+    # Draws what mmdc draws: an actor legend on the left, a coloured band per
+    # section, and for every task a box, a dashed line down to a face whose
+    # height follows the score, and a dot per actor.
+    #
+    # @example Render a user journey
+    #   renderer = UserJourney.new
+    #   svg = renderer.render(laid_out_graph)
+    class UserJourney < Base
+      TEXT_FONT = '"Open Sans", sans-serif'
+      GREY = "#666"
+
+      # Renders a laid-out graph to SVG.
+      #
+      # @param graph [Hash] laid-out graph with node positions
+      # @return [Svg::Document] the rendered SVG document
+      def render(graph)
+        scene = typed_scene(graph)
+        svg = create_document(scene)
+        svg.view_box = scene.view_box
+        draw_body(svg, scene)
+        draw_trim(svg, scene)
+        svg
+      end
+
+      protected
+
+      def typed_scene(graph)
+        return graph if graph.is_a?(Layout::UserJourney::Scene)
+
+        Layout::UserJourney.from_graph(graph, theme: theme)
+      end
+
+      def draw_body(svg, scene)
+        scene.legend.each { |actor| render_actor(svg, actor) }
+        scene.sections.each { |section| render_section(svg, section) }
+        scene.tasks.each { |task| render_task(svg, task) }
+      end
+
+      def draw_trim(svg, scene)
+        svg << title_text(scene.title) if scene.title
+        scene.arrows.each { |arrow| render_timeline(svg, arrow) }
+      end
+
+      def render_actor(svg, actor)
+        svg << dot_circle(actor.dot)
+        actor.labels.each { |label| svg << legend_text(label) }
+      end
+
+      def legend_text(label)
+        themed_text(label, fill: theme_color(:foreground))
+      end
+
+      def title_text(label)
+        themed_text(label, fill: theme_color(:foreground),
+                           font_weight: label.font_weight)
+      end
+
+      def themed_text(label, **extra)
+        Svg::Text.new(
+          x: label.x, y: label.y, content: label.text,
+          font_family: theme_typography(:font_family),
+          font_size: number_string(label.font_size), **extra
+        )
+      end
+
+      def dot_circle(dot)
+        Svg::Circle.new(
+          cx: dot.x, cy: dot.y, r: dot.radius,
+          class_name: "actor-#{dot.index}",
+          fill: dot.colour, stroke: theme_color(:node_stroke)
+        )
+      end
+
+      def render_section(svg, section)
+        class_name = "journey-section section-type-#{section.number}"
+        group = Svg::Group.new
+        group << band_rect(section.box, class_name)
+        section.labels.each { |label| group << box_text(label, class_name) }
+        svg << group
+      end
+
+      def band_rect(box, class_name)
+        Svg::Rect.new(
+          x: box.x, y: box.y, width: box.width, height: box.height,
+          rx: box.corner_radius, ry: box.corner_radius,
+          class_name: class_name, fill: box.fill,
+          stroke: secondary_paint
+        )
+      end
+
+      def box_text(label, class_name)
+        Svg::Text.new(
+          x: label.x, y: label.y, content: label.text,
+          class_name: class_name, fill: label.fill,
+          text_anchor: label.text_anchor,
+          font_family: TEXT_FONT, font_size: number_string(label.font_size)
+        )
+      end
+
+      def render_task(svg, task)
+        group = Svg::Group.new(id: "task-#{task.id}")
+        group << task_line(task)
+        render_face(group, task)
+        render_task_box(group, task)
+        svg << group
+      end
+
+      def render_task_box(group, task)
+        group << band_rect(task.box, "task task-type-#{task.number}")
+        task.dots.each { |dot| group << dot_circle(dot) }
+        task.labels.each { |label| group << box_text(label, "task") }
+      end
+
+      def task_line(task)
+        center_x = task.face.center_x
+        Svg::Line.new(
+          x1: center_x, x2: center_x, y1: task.box.y, y2: task.line_end,
+          class_name: "task-line",
+          stroke: secondary_paint,
+          stroke_width: "1px",
+          stroke_dasharray: "4 2"
+        )
+      end
+
+      def render_face(group, task)
+        face = task.face
+        group << face_circle(face)
+        group << face_features(face)
+      end
+
+      def face_circle(face)
+        Svg::Circle.new(
+          cx: face.center_x, cy: face.center_y, r: face.radius,
+          class_name: "face", fill: "#FFF8DC",
+          stroke: theme_color(:node_stroke),
+          stroke_width: "2"
+        )
+      end
+
+      def face_features(face)
+        Svg::Group.new.tap do |group|
+          face.eyes.each { |point| group << eye(point) }
+          group << mouth(face.mouth)
+        end
+      end
+
+      def eye(point)
+        Svg::Circle.new(
+          cx: point.x, cy: point.y, r: point.radius,
+          fill: theme_color(:foreground),
+          stroke: secondary_paint,
+          stroke_width: "2"
+        )
+      end
+
+      def mouth(mouth)
+        return flat_mouth(mouth.line) unless mouth.path
+
+        Svg::Path.new(
+          d: mouth.path, class_name: "mouth",
+          fill: theme_color(:foreground),
+          stroke: secondary_paint
+        )
+      end
+
+      def flat_mouth(line)
+        Svg::Line.new(
+          x1: line.x1, x2: line.x2, y1: line.y1, y2: line.y2,
+          class_name: "mouth", stroke: secondary_paint,
+          stroke_width: "1px"
+        )
+      end
+
+      def render_timeline(svg, arrow)
+        svg << timeline_line(arrow.line)
+        svg << timeline_head(arrow.head_path)
+      end
+
+      def timeline_line(source)
+        Svg::Line.new(
+          x1: source.x1, y1: source.y1, x2: source.x2, y2: source.y2,
+          stroke: theme_color(:edge_stroke), stroke_width: "4"
+        )
+      end
+
+      def number_string(value)
+        value.to_i == value ? value.to_i.to_s : value.to_s
+      end
+
+      def secondary_paint
+        color = theme_color(:foreground_secondary)
+        color == "#666666" ? GREY : color
+      end
+
+      def timeline_head(path_data)
+        Svg::Path.new(d: path_data, fill: theme_color(:edge_stroke))
+      end
+    end
+  end
+end

data/lib/etassia/renderer/xy_chart.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../layout/xy_chart"
+require_relative "../svg/document"
+require_relative "../svg/circle"
+require_relative "../svg/line"
+require_relative "../svg/rect"
+require_relative "../svg/polyline"
+require_relative "../svg/text"
+
+module Etassia
+  module Renderer
+    # Emits SVG from final, typed XY-chart geometry.
+    class XyChart < Base
+      # @param scene [Layout::XyChart::Scene] final canvas geometry
+      # @return [Svg::Document] rendered SVG document
+      def render(scene)
+        validate_scene!(scene)
+        svg = create_document(scene)
+        svg << label(scene.title) if scene.title
+        render_chart(scene, svg)
+        svg
+      end
+
+      def render_chart(scene, svg)
+        render_lines(scene.lines, svg)
+        scene.series.each { |series| render_series(series, svg) }
+        render_labels(scene.labels, svg)
+        scene.legends.each { |legend| render_legend(legend, svg) }
+      end
+
+      def render_lines(lines, svg)
+        lines.each { |geometry| svg << line(geometry) }
+      end
+
+      def render_labels(labels, svg)
+        labels.each { |geometry| svg << label(geometry) }
+      end
+
+      protected
+
+      def validate_scene!(scene)
+        return if scene.is_a?(Layout::XyChart::Scene)
+
+        raise RenderError,
+              "expected #{Layout::XyChart::Scene}, got #{scene.class}"
+      end
+
+      def line(geometry)
+        Svg::Line.new.tap do |item|
+          assign_line_geometry(item, geometry)
+          apply_line_style(item, geometry.kind)
+        end
+      end
+
+      def assign_line_geometry(item, geometry)
+        item.x1 = geometry.x1
+        item.y1 = geometry.y1
+        item.x2 = geometry.x2
+        item.y2 = geometry.y2
+      end
+
+      def apply_line_style(item, kind)
+        return apply_grid_line_style(item) if kind == "grid"
+
+        item.stroke = theme_color(:xy_axis_line)
+        item.stroke_width = "2"
+      end
+
+      def apply_grid_line_style(item)
+        item.stroke = theme_color(:xy_grid_line)
+        item.stroke_width = "1"
+        item.stroke_dasharray = "3,3"
+      end
+
+      def label(geometry)
+        Svg::Text.new.tap do |text|
+          assign_label_geometry(text, geometry)
+          apply_label_style(text, geometry)
+        end
+      end
+
+      def assign_label_geometry(text, geometry)
+        text.x = geometry.x
+        text.y = geometry.y
+        text.text_anchor = geometry.text_anchor
+        text.transform = geometry.transform
+        text.content = geometry.text
+      end
+
+      def apply_label_style(text, geometry)
+        text.fill = theme_color(:label_text)
+        text.font_size = geometry.font_size.to_s
+        text.font_family = theme_typography(:font_family) || "Arial, sans-serif"
+        text.font_weight = geometry.font_weight
+      end
+
+      def render_series(series, svg)
+        colour = dataset_colour(series.colour_index)
+        if series.chart_type == :bar
+          render_bars(series.bars, colour, svg)
+        elsif !series.points.empty?
+          render_line_series(series, colour, svg)
+        end
+      end
+
+      def render_bars(bars, colour, svg)
+        bars.each { |bar| svg << bar_element(bar, colour) }
+      end
+
+      def render_line_series(series, colour, svg)
+        svg << polyline(series, colour)
+        series.points.each { |point| svg << point_element(point, colour) }
+      end
+
+      def polyline(series, colour)
+        Svg::Polyline.new.tap do |item|
+          item.points = series.polyline
+          item.fill = "none"
+          item.stroke = colour
+          item.stroke_width = "2"
+        end
+      end
+
+      def point_element(point, colour)
+        Svg::Circle.new.tap do |circle|
+          circle.cx = point.x
+          circle.cy = point.y
+          circle.r = point.radius
+          circle.fill = colour
+          circle.stroke = theme_color(:background)
+          circle.stroke_width = "2"
+        end
+      end
+
+      def bar_element(bar, colour)
+        Svg::Rect.new.tap do |rect|
+          assign_bar_geometry(rect, bar)
+          apply_bar_style(rect, colour)
+        end
+      end
+
+      def assign_bar_geometry(rect, bar)
+        rect.x = bar.x
+        rect.y = bar.y
+        rect.width = bar.width
+        rect.height = bar.height
+      end
+
+      def apply_bar_style(rect, colour)
+        rect.fill = colour
+        rect.fill_opacity = "0.8"
+        rect.stroke = colour
+        rect.stroke_width = "1"
+      end
+
+      def render_legend(legend, svg)
+        colour = dataset_colour(legend.colour_index)
+        svg << legend_rectangle(legend, colour)
+        svg << label(legend.label)
+      end
+
+      def legend_rectangle(legend, colour)
+        Svg::Rect.new.tap do |rect|
+          rect.x = legend.x
+          rect.y = legend.y
+          rect.width = legend.width
+          rect.height = legend.height
+          rect.fill = colour
+          rect.stroke = "none"
+        end
+      end
+
+      def dataset_colour(index)
+        theme.colors.palette(:xy, index)
+      end
+    end
+  end
+end

data/lib/etassia/renderer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "renderer/base"
+require_relative "notation/mermaid"
+require_relative "theme/completion"
+
+module Etassia
+  module Renderer
+    # A fresh renderer for a diagram type, found by naming convention
+    # (`:pie` -> `Renderer::Pie`). Never cached.
+    #
+    # @param type [Symbol] a key of {Notation::Mermaid::TYPES}
+    # @param theme [Theme, nil] the theme the renderer draws with; colours it
+    #   leaves unset come from the default theme
+    # @raise [Engine::DiagramTypeError] when the type is unknown
+    # @raise [RenderError] when the type has no renderer class
+    def self.for(type, theme: nil)
+      renderer = Notation::Mermaid.layer_class(self, type, RenderError)
+      renderer.new(theme: Theme::Completion.call(theme))
+    end
+  end
+end

data/lib/etassia/runtime.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "error/pipeline_error"
+
+module Etassia
+  # Picks the engine behind {Etassia.render}: the Rust runtime shipped by the
+  # optional `etassia-native` gem, or this gem's own Ruby pipeline.
+  #
+  # `ETASSIA_RUNTIME` selects the mode:
+  #
+  # - `auto` (default) -- Rust when `etassia-native` loads and finds its
+  #   shared library, Ruby otherwise. Whenever Rust cannot answer (the diagram
+  #   type is not ported, or it reports an error) the Ruby pipeline renders
+  #   the same source, so a failure is always the Ruby exception, never a
+  #   native one.
+  # - `ruby` -- never touch the native runtime.
+  # - `rust` -- require it: a missing library, an unported diagram type or a
+  #   native error raises {Engine::PipelineError}. For CI jobs proving
+  #   the Rust path.
+  #
+  # The Rust runtime takes only a source string, so it is used just for a
+  # default render (no options) of a source the Mermaid notation handles.
+  # Anything else is the Ruby pipeline's job, and the SVG bytes are the same
+  # either way.
+  module Runtime
+    ENV_KEY = "ETASSIA_RUNTIME"
+    MODES = %w[auto ruby rust].freeze
+    private_constant :ENV_KEY, :MODES
+
+    class << self
+      # @return [String] the validated mode
+      # @raise [ArgumentError] when ETASSIA_RUNTIME names no mode
+      def mode
+        value = ENV.fetch(ENV_KEY, nil)
+        return "auto" if value.nil? || value.empty?
+        return value if MODES.include?(value)
+
+        raise ArgumentError,
+              "#{ENV_KEY} must be one of #{MODES.join(', ')}, " \
+              "got #{value.inspect}"
+      end
+
+      # Whether the native library is loadable in this process.
+      def native?
+        !library.nil?
+      end
+
+      # SVG from the Rust runtime, or nil when the caller should render in Ruby.
+      #
+      # @param source [String]
+      # @param options [Hash] Engine#render options; any key rules Rust out
+      # @return [String, nil]
+      def render(source, options)
+        selected = mode
+        return nil if selected == "ruby"
+
+        strict = selected == "rust"
+        if native_eligible?(source, options)
+          return native_render(source, strict: strict)
+        end
+
+        decline("options or a non-Mermaid notation", strict: strict)
+      end
+
+      # What {Etassia.render} returns: the native SVG when Rust answers,
+      # otherwise the Ruby pipeline's.
+      def or_ruby(source, options)
+        render(source, options) || Engine.new.render(source, options)
+      end
+
+      # Forget the memoised library probe (specs only).
+      def reset!
+        return unless instance_variable_defined?(:@library)
+
+        remove_instance_variable(:@library)
+      end
+
+      private
+
+      def native_render(source, strict:)
+        lib = library
+        return lib.render(source) unless lib.nil?
+
+        decline("etassia-native is not installed", strict: strict)
+      rescue ::Etassia::Native::Unported => e
+        decline("#{e.message} is not ported", strict: strict)
+      rescue ::Etassia::Native::RenderError => e
+        decline("it failed: #{e.message}", strict: strict)
+      rescue EncodingError
+        nil
+      end
+
+      # Nil sends the caller to Ruby; strict mode refuses instead.
+      def decline(reason, strict:)
+        return nil unless strict
+
+        raise Engine::PipelineError,
+              "ETASSIA_RUNTIME=rust cannot render: #{reason}"
+      end
+
+      def native_eligible?(source, options)
+        return false unless options.empty? && source.is_a?(String)
+
+        notation = Notation.resolve(explicit: nil, path: nil, source: source)
+        notation.id == :mermaid
+      end
+
+      # The Native::Library, or nil. Probed once: `require` of an absent gem
+      # means "use Ruby".
+      def library
+        return @library if instance_variable_defined?(:@library)
+
+        @library = probe
+      end
+
+      def probe
+        require "etassia/native"
+        ::Etassia::Native.library
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end