etassia 0.1.0

data/lib/etassia/renderer/architecture_edge_router.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Renderer
+    # Routes one architecture-beta edge around whatever else is in the
+    # diagram, instead of drawing straight through it. Geometry only, no
+    # SVG. Not an extension of EdgeRouter (don't unify them): EdgeRouter
+    # trims two boxes with geometry-derived faces (flowchart); here faces
+    # are user-declared (`a:R -- T:b`) with arbitrarily many obstacles.
+    #
+    # Coordinate-compressed grid + direction-aware Dijkstra: a straight
+    # line when already clear, else the shortest bent path that
+    # leaves/arrives on the declared faces without crossing an obstacle's
+    # interior (source/target boxes exempt only at the anchor - see `route`).
+    class ArchitectureEdgeRouter
+      # Outer escape line, added only when the natural grid (built purely
+      # from existing box edges) has no clear path at all.
+      MARGIN = 20
+
+      # Dijkstra cost added when a hop changes direction, so the search
+      # prefers fewer bends over merely fewer hops.
+      TURN_PENALTY = 5
+
+      FACE_NORMAL = {
+        "L" => { x: -1, y: 0 },
+        "R" => { x: 1, y: 0 },
+        "T" => { x: 0, y: -1 },
+        "B" => { x: 0, y: 1 },
+      }.freeze
+
+      GRID_STEPS = [[1, 0], [-1, 0], [0, 1], [0, -1]].freeze
+
+      # A binary min-heap keyed on cost, so search_grid's Dijkstra pops the
+      # cheapest frontier entry in O(log n) instead of re-sorting the whole
+      # frontier on every pop. Ruby's stdlib has no heap; this is the whole
+      # of what the search needs from one - push and pop, nothing else.
+      class MinHeap
+        def initialize
+          @entries = []
+        end
+
+        def empty?
+          @entries.empty?
+        end
+
+        def push(cost, item)
+          @entries << [cost, item]
+          sift_up(@entries.length - 1)
+        end
+
+        # @return [Array(Numeric, Object)] the lowest-cost (cost, item) pair
+        def pop
+          top = @entries.first
+          last = @entries.pop
+          unless @entries.empty?
+            @entries[0] = last
+            sift_down(0)
+          end
+          top
+        end
+
+        private
+
+        def sift_up(index)
+          while index.positive?
+            parent = (index - 1) / 2
+            break if @entries[parent][0] <= @entries[index][0]
+
+            swap_entries(parent, index)
+            index = parent
+          end
+        end
+
+        def sift_down(index)
+          size = @entries.length
+          loop do
+            smallest = smallest_entry(index, size)
+            break if smallest == index
+
+            swap_entries(index, smallest)
+            index = smallest
+          end
+        end
+
+        def smallest_entry(index, size)
+          left = (2 * index) + 1
+          [index, left, left + 1].select { |entry| entry < size }
+            .min_by { |entry| @entries[entry][0] }
+        end
+
+        def swap_entries(first, second)
+          @entries[first], @entries[second] = @entries[second], @entries[first]
+        end
+      end
+      private_constant :MinHeap
+
+      # @param from [Hash] edge source: point {x:,y:} anchor on the declared
+      #   face; box {x:,y:,width:,height:} - a clearance obstacle a path may
+      #   only touch at point, never cross, even though it's never in
+      #   +obstacles+; side "L"/"R"/"T"/"B" - which face point sits on
+      # @param to [Hash] edge target, same shape as +from+
+      # @param obstacles [Array<Hash>] every OTHER box to route around (the
+      #   caller already excludes from/to and any ancestor-or-equal group)
+      # @return [Array<Hash>] ordered {x:,y:} points, from[:point] first,
+      #   to[:point] last. Length 2 means a straight line was clear.
+      def route(from:, to:, obstacles:)
+        clearance_obstacles = obstacles + [from[:box], to[:box]]
+        if straight_clear?(from[:point], to[:point], clearance_obstacles)
+          return [from[:point], to[:point]]
+        end
+
+        path = shortest_path(from, to, clearance_obstacles)
+        return [from[:point], to[:point]] unless path
+
+        collapse_collinear(path)
+      end
+
+      private
+
+      def straight_clear?(from_point, to_point, clearance_obstacles)
+        clearance_obstacles.none? do |box|
+          segment_crosses_box?(box, from_point, to_point)
+        end
+      end
+
+      # General segment-vs-box interior test (the segment need not be
+      # axis-aligned - a declared-face-to-declared-face anchor pair rarely
+      # is, e.g. an R face to a T face). Finds the sub-range of t in [0,1]
+      # where the segment's x is strictly inside the box's x-span AND its y
+      # is strictly inside the box's y-span; a border touch does not count
+      # as crossing, matching EdgeRouter#crosses_face?'s semantics.
+      def segment_crosses_box?(box, first_point, second_point)
+        x_interval = horizontal_interval(box, first_point, second_point)
+        return false unless x_interval
+
+        y_interval = vertical_interval(box, first_point, second_point)
+        return false unless y_interval
+
+        lo = [x_interval[0], y_interval[0], 0.0].max
+        hi = [x_interval[1], y_interval[1], 1.0].min
+        lo < hi
+      end
+
+      def horizontal_interval(box, first_point, second_point)
+        axis_interval(first_point[:x], second_point[:x], box[:x] || 0,
+                      right_of(box))
+      end
+
+      def vertical_interval(box, first_point, second_point)
+        axis_interval(first_point[:y], second_point[:y], box[:y] || 0,
+                      bottom_of(box))
+      end
+
+      # The [t_lo, t_hi] sub-range of t (segment parametrized as
+      # c1 + t*(c2-c1)) where the coordinate is strictly between near and
+      # far. nil when no such t exists - including a segment that runs
+      # exactly along that axis outside (near, far), or exactly along its
+      # border, since a border touch is not "strictly between".
+      def axis_interval(first_coordinate, second_coordinate, near, far)
+        if first_coordinate == second_coordinate
+          return infinite_interval if
+            first_coordinate.between?(near, far) &&
+              ![near, far].include?(first_coordinate)
+
+          return nil
+        end
+
+        step = (second_coordinate - first_coordinate).to_f
+        [(near - first_coordinate) / step,
+         (far - first_coordinate) / step].sort
+      end
+
+      def infinite_interval
+        [-Float::INFINITY, Float::INFINITY]
+      end
+
+      def right_of(box)
+        (box[:x] || 0) + (box[:width] || 0)
+      end
+
+      def bottom_of(box)
+        (box[:y] || 0) + (box[:height] || 0)
+      end
+
+      def shortest_path(from, to, clearance_obstacles)
+        grid = build_grid(
+          from[:point], to[:point], clearance_obstacles, margin: false
+        )
+        path = search_grid(grid, from, to, clearance_obstacles)
+        return path if path
+
+        widened = build_grid(
+          from[:point], to[:point], clearance_obstacles, margin: true
+        )
+        search_grid(widened, from, to, clearance_obstacles)
+      end
+
+      # Critical coordinate lines: every obstacle's own edges, plus the two
+      # anchor points. With margin: true, one extra line MARGIN beyond the
+      # overall extent on each side, clamped to >= 0 so a route can never
+      # need a negative coordinate.
+      def build_grid(from_point, to_point, clearance_obstacles, margin:)
+        xs = [from_point[:x], to_point[:x]]
+        ys = [from_point[:y], to_point[:y]]
+        add_obstacle_coordinates(xs, ys, clearance_obstacles)
+        add_margin_coordinates(xs, ys) if margin
+        { xs: xs.uniq.sort, ys: ys.uniq.sort }
+      end
+
+      def add_obstacle_coordinates(x_coordinates, y_coordinates, obstacles)
+        obstacles.each do |box|
+          x_coordinates << (box[:x] || 0) << right_of(box)
+          y_coordinates << (box[:y] || 0) << bottom_of(box)
+        end
+      end
+
+      def add_margin_coordinates(x_coordinates, y_coordinates)
+        x_coordinates << [x_coordinates.min - MARGIN, 0].max
+        x_coordinates << (x_coordinates.max + MARGIN)
+        y_coordinates << [y_coordinates.min - MARGIN, 0].max
+        y_coordinates << (y_coordinates.max + MARGIN)
+      end
+
+      # Direction-aware Dijkstra over the grid-line intersections. A hop
+      # between grid-adjacent points is a valid graph edge iff the short
+      # segment it draws is not segment_crosses_box? for any obstacle - the
+      # same predicate straight_clear? uses, so grid-edge validity and the
+      # straight-line shortcut share one exact test. The first hop out of
+      # from[:point] is constrained to FACE_NORMAL[from[:side]]; the
+      # accepted goal state requires the last hop into to[:point] to be
+      # -FACE_NORMAL[to[:side]].
+      def search_grid(grid, from, to, clearance_obstacles)
+        xs = grid[:xs]
+        ys = grid[:ys]
+        start = grid_position(xs, ys, from[:point])
+        goal = grid_position(xs, ys, to[:point])
+        return nil if start == goal
+
+        required_first = face_direction(from[:side])
+        required_last = face_direction(to[:side]).map(&:-@)
+        find_grid_path(grid, start, goal, [required_first, required_last],
+                       clearance_obstacles)
+      end
+
+      def grid_position(x_coordinates, y_coordinates, point)
+        [x_coordinates.index(point[:x]), y_coordinates.index(point[:y])]
+      end
+
+      def face_direction(side)
+        FACE_NORMAL.fetch(side).values_at(:x, :y)
+      end
+
+      def find_grid_path(grid, start, goal, directions, clearance_obstacles)
+        required_first, required_last = directions
+        goal_state = [goal[0], goal[1], required_last]
+        context = search_context(start, grid)
+        until context[:frontier].empty?
+          path = visit_grid_state(context, goal_state, required_first,
+                                  clearance_obstacles)
+          return path if path
+        end
+        nil
+      end
+
+      def search_context(start, grid)
+        frontier = MinHeap.new
+        frontier.push(0, [start[0], start[1], nil])
+        {
+          grid: grid, frontier: frontier, previous: {},
+          distances: { [start[0], start[1], nil] => 0 }
+        }
+      end
+
+      def visit_grid_state(context, goal_state, required_first,
+                           clearance_obstacles)
+        cost, state = context[:frontier].pop
+        return if stale_state?(context, state, cost)
+
+        path = reconstruct_goal(context, state, goal_state)
+        return path if path
+
+        expand_grid_state(context, state, cost, required_first,
+                          clearance_obstacles)
+        nil
+      end
+
+      def stale_state?(context, state, cost)
+        cost > context[:distances].fetch(state, Float::INFINITY)
+      end
+
+      def reconstruct_goal(context, state, goal_state)
+        return unless state == goal_state
+
+        grid = context[:grid]
+        reconstruct(context[:previous], state, grid[:xs], grid[:ys])
+      end
+
+      def expand_grid_state(context, state, cost, required_first,
+                            clearance_obstacles)
+        grid = context[:grid]
+        moves = expand(state, grid, required_first, clearance_obstacles)
+        moves.each { |move| relax_grid_move(move, cost, state, context) }
+      end
+
+      def relax_grid_move(move, cost, state, context)
+        next_state, step_cost = move
+        new_cost = cost + step_cost
+        distances = context[:distances]
+        return if new_cost >= distances.fetch(next_state, Float::INFINITY)
+
+        distances[next_state] = new_cost
+        context[:previous][next_state] = state
+        context[:frontier].push(new_cost, next_state)
+      end
+
+      def expand(state, grid, required_first, clearance_obstacles)
+        GRID_STEPS.filter_map do |step|
+          grid_move(state, step, grid, required_first, clearance_obstacles)
+        end
+      end
+
+      def grid_move(state, step, grid, required_first, clearance_obstacles)
+        x_index, y_index, direction = state
+        return if direction.nil? && step != required_first
+
+        next_x, next_y = next_grid_position(x_index, y_index, step)
+        return unless grid_position_valid?(next_x, next_y, grid)
+
+        points = grid_segment(x_index, y_index, next_x, next_y, grid)
+        return unless straight_clear?(*points, clearance_obstacles)
+
+        [[next_x, next_y, step], grid_step_cost(direction, step)]
+      end
+
+      def next_grid_position(x_index, y_index, step)
+        [x_index + step[0], y_index + step[1]]
+      end
+
+      def grid_position_valid?(x_index, y_index, grid)
+        x_index.between?(0, grid[:xs].length - 1) &&
+          y_index.between?(0, grid[:ys].length - 1)
+      end
+
+      def grid_segment(x_index, y_index, next_x, next_y, grid)
+        [{ x: grid[:xs][x_index], y: grid[:ys][y_index] },
+         { x: grid[:xs][next_x], y: grid[:ys][next_y] }]
+      end
+
+      def grid_step_cost(direction, next_direction)
+        direction && direction != next_direction ? 1 + TURN_PENALTY : 1
+      end
+
+      def reconstruct(prev, state, x_coordinates, y_coordinates)
+        path = [state]
+        path << prev[path.last] while prev.key?(path.last)
+        path.reverse.map do |x_index, y_index, _direction|
+          { x: x_coordinates[x_index], y: y_coordinates[y_index] }
+        end
+      end
+
+      # Drops points that don't represent an actual direction change, so
+      # the returned path only contains real bends.
+      def collapse_collinear(points)
+        return points if points.length <= 2
+
+        result = [points.first]
+        points.each_cons(3) do |before, at, after|
+          result << at if direction(before, at) != direction(at, after)
+        end
+        result << points.last
+        result
+      end
+
+      def direction(from, to)
+        [to[:x] <=> from[:x], to[:y] <=> from[:y]]
+      end
+    end
+  end
+end

data/lib/etassia/renderer/base.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../error/render_error"
+
+module Etassia
+  module Renderer
+    # Abstract base class for diagram renderers.
+    #
+    # Renderers convert laid-out graph structures (with computed positions)
+    # into SVG documents using the Svg builder classes. Each diagram type has
+    # its own renderer that maps graph elements to appropriate SVG shapes.
+    #
+    # The renderer implements the template method pattern, defining the
+    # overall rendering pipeline while allowing subclasses to customize
+    # specific rendering steps.
+    #
+    # @example Define a custom renderer
+    #   class Flowchart < Renderer::Base
+    #     def render(graph)
+    #       svg = create_document(graph)
+    #       render_nodes(graph, svg)
+    #       render_edges(graph, svg)
+    #       svg
+    #     end
+    #
+    #     protected
+    #
+    #     def render_nodes(graph, svg)
+    #       # Render graph nodes as SVG shapes
+    #     end
+    #
+    #     def render_edges(graph, svg)
+    #       # Render graph edges as SVG paths
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement rendering methods
+    class Base
+      # Factor on a measured text width for room around a label; it is NOT a
+      # bound. A viewer that lacks Arial substitutes its own sans-serif:
+      # DejaVu Sans and Verdana measured up to 1.19 times Arial's width.
+      SUBSTITUTE_FONT_HEADROOM = 1.2
+      private_constant :SUBSTITUTE_FONT_HEADROOM
+
+      attr_accessor :theme
+
+      # Creates a new renderer instance.
+      #
+      # @param theme [Theme, nil] theme to use for rendering
+      def initialize(theme: nil)
+        @theme = theme || Theme::Registry.get(:default)
+      end
+
+      # Renders a laid-out graph to an SVG document.
+      #
+      # This method should be overridden by subclasses to implement
+      # diagram-specific rendering logic.
+      #
+      # @param graph [Object] the laid-out elkrb graph with positions
+      # @return [Svg::Document] the rendered SVG document
+      # @raise [NotImplementedError] if not implemented by subclass
+      def render(graph)
+        raise NotImplementedError,
+              "#{self.class} must implement #render(graph)"
+      end
+
+      protected
+
+      # Creates an SVG document from final Scene canvas dimensions.
+      #
+      # Scene coordinates already include their framing. The renderer must not
+      # add padding or reuse a caller-supplied viewBox origin.
+      #
+      # @param scene [Layout::Scene] final canvas geometry
+      # @param overflow [String, nil] SVG `overflow` presentation attribute
+      #   for the root element, e.g. `'hidden'`
+      # @return [Svg::Document] new SVG document
+      def create_document(scene, overflow: nil)
+        dimensions = document_dimensions(scene)
+        Svg::Document.new(
+          width: scene.width, height: scene.height,
+          view_box: "0 0 #{dimensions.join(' ')}", overflow: overflow
+        )
+      end
+
+      def document_dimensions(scene)
+        dimensions = [scene.width, scene.height].map do |value|
+          value.to_i == value ? value.to_i : value
+        end
+        existing = scene.view_box.to_s.split.last(2)
+        { existing.map(&:to_f) => existing }.fetch(
+          [scene.width, scene.height], dimensions
+        )
+      end
+
+      # Room to reserve for a text label: its measured width with headroom
+      # for a substituted font. Not a bound; see TextMeasurement for what the
+      # measurement itself does and does not cover.
+      #
+      # @param text [String] label text
+      # @param font_size [Numeric] the size the label is drawn at
+      # @return [Float] width in pixels
+      def reserved_text_width(text, font_size)
+        TextMeasurement.measure(text, font_size: font_size)[:width] *
+          SUBSTITUTE_FONT_HEADROOM
+      end
+
+      # Calculates the total width needed for the diagram.
+      #
+      # Subclasses should override this to compute width from graph.
+      #
+      # @param graph [Object] the graph
+      # @return [Numeric] the width in pixels
+      def calculate_width(_graph)
+        800 # Default width
+      end
+
+      # Calculates the total height needed for the diagram.
+      #
+      # Subclasses should override this to compute height from graph.
+      #
+      # @param graph [Object] the graph
+      # @return [Numeric] the height in pixels
+      def calculate_height(_graph)
+        600 # Default height
+      end
+
+      # Helper methods for accessing theme properties
+
+      # Gets a color property from the theme.
+      #
+      # @param property [Symbol] property name
+      # @return [String, nil] color value
+      def theme_color(property)
+        theme&.colors&.send(property)
+      rescue NoMethodError
+        nil
+      end
+
+      # Gets a typography property from the theme.
+      #
+      # @param property [Symbol] property name
+      # @return [String, Float, nil] typography value
+      def theme_typography(property)
+        theme&.typography&.send(property)
+      rescue NoMethodError
+        nil
+      end
+
+      # Gets a shape property from the theme.
+      #
+      # @param property [Symbol] property name
+      # @return [Float, String, nil] shape value
+      def theme_shape(property)
+        theme&.shapes&.send(property)
+      rescue NoMethodError
+        nil
+      end
+
+      # Gets a spacing property from the theme.
+      #
+      # @param property [Symbol] property name
+      # @return [Float, nil] spacing value
+      def theme_spacing(property)
+        theme&.spacing&.send(property)
+      rescue NoMethodError
+        nil
+      end
+
+      # Gets an effect property from the theme.
+      #
+      # @param property [Symbol] property name
+      # @return [Boolean, Float, String, nil] effect value
+      def theme_effect(property)
+        theme&.effects&.send(property)
+      rescue NoMethodError
+        nil
+      end
+
+      # Applies theme styles to a node element.
+      #
+      # @param element [Svg::Element] SVG element
+      # @return [void]
+      def apply_theme_to_node(element)
+        element.fill = theme_color(:node_fill) if theme_color(:node_fill)
+        element.stroke = theme_color(:node_stroke) if theme_color(:node_stroke)
+        if theme_shape(:stroke_width)
+          element.stroke_width = theme_shape(:stroke_width).to_s
+        end
+      end
+
+      # Applies theme styles to an edge element.
+      #
+      # @param element [Svg::Element] SVG element
+      # @return [void]
+      def apply_theme_to_edge(element)
+        element.stroke = theme_color(:edge_stroke) if theme_color(:edge_stroke)
+        if theme_shape(:stroke_width)
+          element.stroke_width = theme_shape(:stroke_width).to_s
+        end
+      end
+
+      # Applies theme styles to a text element.
+      #
+      # @param element [Svg::Text] SVG text element
+      # @return [void]
+      def apply_theme_to_text(element)
+        element.fill = theme_color(:label_text) if theme_color(:label_text)
+        if theme_typography(:font_family)
+          element.font_family = theme_typography(:font_family)
+        end
+        if theme_typography(:font_size_normal)
+          element.font_size = theme_typography(:font_size_normal).to_s
+        end
+      end
+
+      # Creates default style for SVG elements.
+      #
+      # @param element_type [Symbol] type of element (:node, :edge, :text)
+      # @return [Svg::Style] style object
+      def default_style(element_type)
+        case element_type
+        when :node
+          default_node_style
+        when :edge
+          default_edge_style
+        when :text
+          default_text_style
+        else
+          Svg::Style.new
+        end
+      end
+
+      def default_node_style
+        Svg::Style.new.tap do |style|
+          style.fill = default_style_color(:node_fill)
+          style.stroke = default_style_color(:node_stroke)
+          style.stroke_width = (theme_shape(:stroke_width) || 2).to_s
+        end
+      end
+
+      def default_edge_style
+        Svg::Style.new.tap do |style|
+          style.fill = "none"
+          style.stroke = default_style_color(:edge_stroke)
+          style.stroke_width = (theme_shape(:stroke_width) || 2).to_s
+        end
+      end
+
+      def default_text_style
+        Svg::Style.new.tap do |style|
+          style.fill = default_style_color(:label_text)
+          style.font_family =
+            theme_typography(:font_family) || "Arial, sans-serif"
+          style.font_size = (theme_typography(:font_size_normal) || 14).to_s
+          style.text_anchor = "middle"
+        end
+      end
+
+      def default_style_color(property)
+        return theme_color(property) if theme
+
+        Theme::Registry.get(:default).colors.public_send(property)
+      end
+
+      # Creates an SVG path data string from bend points.
+      #
+      # @param start_point [Hash] hash with :x and :y keys
+      # @param end_point [Hash] hash with :x and :y keys
+      # @param bend_points [Array<Hash>] array of hashes with :x and :y
+      # @return [String] SVG path data string
+      def create_path_data(start_point, end_point, bend_points = [])
+        points = [start_point] + bend_points + [end_point]
+        path_parts = ["M #{points[0][:x]} #{points[0][:y]}"]
+
+        points[1..].each do |point|
+          path_parts << "L #{point[:x]} #{point[:y]}"
+        end
+
+        path_parts.join(" ")
+      end
+
+      # Adds an arrow marker to the SVG document.
+      #
+      # @param svg [Svg::Document] the SVG document
+      # @param id [String] unique identifier for the marker
+      # @return [void]
+      def add_arrow_marker(svg, id: "arrow")
+        # This is a placeholder for actual marker implementation
+        # Subclasses can implement this to add arrow markers
+      end
+    end
+  end
+end