etassia 0.1.0

data/lib/etassia/layout/flowchart/edge_router.rb

@@ -0,0 +1,533 @@
+# frozen_string_literal: true
+
+require_relative "../../js_math"
+
+module Etassia
+  module Layout
+    # Works out where an edge's line runs between two boxes.
+    #
+    # This is geometry only: it takes two laid-out boxes and gives back
+    # the points the line passes through. Nothing here knows about SVG,
+    # and Flowchart turns the points into a path.
+    #
+    # The maths exists because of clusters. A node is painted OVER the
+    # line, so a line drawn from centre to centre looks right without
+    # any trimming. A cluster is painted BEHIND the line, so the stretch
+    # from its centre out to its border stays visible across the inside
+    # of the box. Every rule below is about keeping that stretch off the
+    # page while the line still touches the box it belongs to.
+    #
+    # One point shape throughout: `{ x: <number>, y: <number> }`, which
+    # is the shape ELK bend points already have. `ends_of` is the single
+    # place it becomes anything else.
+    #
+    # @example Route an edge
+    #   points, label_ends = FlowchartEdgeRouter.new.route(
+    #     source, target, bends
+    #   )
+    class FlowchartEdgeRouter
+      # Rounded the way mermaid paints a cluster. The Scene carries the same
+      # radius, and an endpoint on a corner has to land on it.
+      CLUSTER_CORNER = 5
+
+      # Two boxes that touch add up to exactly one run between their
+      # centres, and the arithmetic lands a hair under it. Without the
+      # slack they get trimmed to the same point and the edge is drawn
+      # zero units long.
+      TOUCHING = 1e-9
+
+      # Routes are written to two decimal places after trimming. Centres
+      # less than one output unit apart cannot provide a useful straight run.
+      COINCIDENT = 0.01
+
+      # Trimmed endpoints are written to two decimals, so a coordinate can
+      # sit half a hundredth away from the unrounded side it reached.
+      ROUTE_EPSILON = 0.01
+
+      # How far a degenerate loop reaches past the borders it leaves.
+      # Flowchart's page sizing adds 40 past the drawn maxima, and the
+      # Scene framing keeps the origin at zero and adds another 40
+      # extents, leaving 80 units there. A reach beyond that needs the
+      # page to grow with it.
+      LOOP_REACH = 20
+
+      # The marker Layout::Flowchart puts on a subgraph.
+      # Layout::Grid#cluster? makes the same test: change one and
+      # change the others, or the layers stop agreeing about what a box
+      # is.
+      #
+      # @param box [Hash] a laid-out box
+      # @return [Boolean] true when the box is a cluster
+      def self.cluster?(box)
+        box.dig(:metadata, :cluster) == true
+      end
+
+      # The exact centre of a laid-out box. Flowchart aims routes, heads and
+      # outlines at this same point, so keep one copy: two drifted
+      # apart once and put routed ends half a pixel off their heads.
+      #
+      # @param box [Hash] a laid-out box
+      # @return [Hash] :x and :y of the centre
+      def self.centre(box)
+        { x: (box[:x] || 0) + ((box[:width] || 100) / 2.0),
+          y: (box[:y] || 0) + ((box[:height] || 50) / 2.0) }
+      end
+
+      # The two ends of a run, flattened for the path and label builders.
+      #
+      # @param points [Array<Hash>] the points of a run
+      # @return [Array<Numeric>] source x, source y, target x, target y
+      def self.ends_of(points)
+        first = points.first
+        last = points.last
+        [first[:x], first[:y], last[:x], last[:y]]
+      end
+
+      # Routes one edge.
+      #
+      # @param source [Hash] the laid-out box the edge leaves
+      # @param target [Hash] the laid-out box the edge reaches
+      # @param bends [Array<Hash>, nil] bend points the layout supplied
+      # @return [Array(Array<Hash>, Array<Numeric>)] the points of the
+      #   run, and the ends of the stretch the label sits on
+      def route(source, target, bends = nil)
+        points = initial_route(source, target)
+        clamp_route(points, source, target, bends)
+        label_points = points.length > 2 ? points.slice(1, 2) : points
+        [points, self.class.ends_of(label_points)]
+      end
+
+      private
+
+      def initial_route(source, target)
+        points = coincident_loop(source, target) unless
+          exposed_cluster_overlap?(source, target)
+        points || trimmed_route(source, target)
+      end
+
+      def clamp_route(points, source, target, bends)
+        source_neighbour = bends&.first || points[1]
+        target_neighbour = bends&.last || points[-2]
+        points[0] = clamp_cluster_corner(points[0], source_neighbour, source)
+        points[-1] = clamp_cluster_corner(points[-1], target_neighbour, target)
+      end
+
+      def cluster?(box)
+        self.class.cluster?(box)
+      end
+
+      # Nodes and unmarked containers stay unchanged. A cluster is painted
+      # with integer rectangle coordinates, so its endpoint is moved from the
+      # layout box onto that exact rounded outline.
+      def clamp_cluster_corner(point, neighbour, box)
+        return point unless cluster?(box)
+
+        x_side, y_side = cluster_sides(point, box)
+        return point unless x_side || y_side
+
+        outline = painted_cluster_outline(box)
+        return point if outline.values_at(:rx, :ry).any?(&:zero?)
+
+        painted_cluster_contact(point, neighbour, outline, x_side, y_side)
+      end
+
+      def painted_cluster_contact(point, neighbour, outline, x_side, y_side)
+        if x_side && y_side
+          return rounded_corner(neighbour, outline, x_side, y_side)
+        end
+
+        clamp_cluster_side(point, outline, x_side, y_side)
+      end
+
+      def cluster_sides(point, box)
+        [edge_side(point[:x], [box[:x] || 0, right_of(box)]),
+         edge_side(point[:y], [box[:y] || 0, bottom_of(box)])]
+      end
+
+      def edge_side(coordinate, edges)
+        side = edges.each_index.min_by do |index|
+          (coordinate - edges[index]).abs
+        end
+        side if (coordinate - edges[side]).abs <= ROUTE_EPSILON
+      end
+
+      def painted_cluster_outline(box)
+        x, y, width, height = painted_cluster_dimensions(box)
+        { xs: [x, x + width], ys: [y, y + height],
+          rx: [CLUSTER_CORNER, width / 2.0].min,
+          ry: [CLUSTER_CORNER, height / 2.0].min }
+      end
+
+      def painted_cluster_dimensions(box)
+        %i[x y width height].map { |key| (box[key] || 0).to_i.to_f }
+      end
+
+      def clamp_cluster_side(point, outline, x_side, y_side)
+        if x_side
+          clamp_vertical_side(point, outline, x_side)
+        else
+          clamp_horizontal_side(point, outline, y_side)
+        end
+      end
+
+      def clamp_vertical_side(point, outline, side)
+        xs, ys, ry = outline.values_at(:xs, :ys, :ry)
+        point.merge(x: xs[side],
+                    y: point[:y].clamp(ys.first + ry, ys.last - ry))
+      end
+
+      def clamp_horizontal_side(point, outline, side)
+        xs, ys, rx = outline.values_at(:xs, :ys, :rx)
+        point.merge(x: point[:x].clamp(xs.first + rx, xs.last - rx),
+                    y: ys[side])
+      end
+
+      def rounded_corner(neighbour, outline, x_side, y_side)
+        corner = corner_point(outline, x_side, y_side)
+        centre = corner_centre(outline, x_side, y_side)
+        direction = { x: corner[:x] - neighbour[:x],
+                      y: corner[:y] - neighbour[:y] }
+        step = ellipse_entry(
+          corner, centre, direction, outline[:rx], outline[:ry]
+        )
+        step ? corner_at_step(corner, direction, step) : corner
+      end
+
+      def corner_point(outline, x_side, y_side)
+        xs, ys = outline.values_at(:xs, :ys)
+        { x: xs[x_side], y: ys[y_side] }
+      end
+
+      def corner_centre(outline, x_side, y_side)
+        xs, ys, rx, ry = outline.values_at(:xs, :ys, :rx, :ry)
+        { x: x_side.zero? ? xs.first + rx : xs.last - rx,
+          y: y_side.zero? ? ys.first + ry : ys.last - ry }
+      end
+
+      def corner_at_step(corner, direction, step)
+        corner.merge(x: (corner[:x] + (direction[:x] * step)).round(2),
+                     y: (corner[:y] + (direction[:y] * step)).round(2))
+      end
+
+      def ellipse_entry(corner, centre, direction, radius_x, radius_y)
+        x, y = normalized_corner(corner, centre, radius_x, radius_y)
+        dx, dy = ellipse_direction(direction, radius_x, radius_y)
+        a = (dx**2) + (dy**2)
+        return nil if a.zero?
+
+        b = 2 * ((x * dx) + (y * dy))
+        smallest_quadratic_root(a, b)
+      end
+
+      def normalized_corner(corner, centre, radius_x, radius_y)
+        [(corner[:x] - centre[:x]) / radius_x,
+         (corner[:y] - centre[:y]) / radius_y]
+      end
+
+      def ellipse_direction(direction, radius_x, radius_y)
+        [direction[:x] / radius_x, direction[:y] / radius_y]
+      end
+
+      def smallest_quadratic_root(quad_coeff, linear_coeff)
+        discriminant = (linear_coeff**2) - (4 * quad_coeff)
+        return nil if discriminant.negative?
+
+        quadratic_roots(quad_coeff, linear_coeff, discriminant)
+          .select { |value| value >= 0 }.min
+      end
+
+      def quadratic_roots(quad_coeff, linear_coeff, discriminant)
+        [(-linear_coeff - Math.sqrt(discriminant)) / (2 * quad_coeff),
+         (-linear_coeff + Math.sqrt(discriminant)) / (2 * quad_coeff)]
+      end
+
+      # A straight run needs a direction. Self-edges and distinct boxes
+      # with the same centre have none, so route from the source's top to
+      # the target's bottom with two bends beyond both boxes.
+      def coincident_loop(source, target)
+        source_centre = FlowchartEdgeRouter.centre(source)
+        target_centre = FlowchartEdgeRouter.centre(target)
+        return nil unless near?(source_centre, target_centre)
+
+        coincident_loop_points(source, target, source_centre, target_centre)
+      end
+
+      def coincident_loop_points(source, target, source_centre, target_centre)
+        start, finish = loop_endpoints(
+          source, target, source_centre, target_centre
+        )
+        out = [right_of(source), right_of(target)].max + LOOP_REACH
+        bend_y = finish[:y]
+        bend_y += LOOP_REACH if near?(start, finish)
+        rounded_points([start, { x: out, y: start[:y] },
+                        { x: out, y: bend_y }, finish])
+      end
+
+      def loop_endpoints(source, target, source_centre, target_centre)
+        source_top, = vertical_outline(source, source_centre[:y])
+        _, target_bottom = vertical_outline(target, target_centre[:y])
+        [{ x: source_centre[:x], y: source_top },
+         { x: target_centre[:x], y: target_bottom }]
+      end
+
+      def near?(first, second)
+        JsMath.hypot(first[:x] - second[:x],
+                     first[:y] - second[:y]) < COINCIDENT
+      end
+
+      def right_of(box)
+        (box[:x] || 0) + (box[:width] || 0)
+      end
+
+      def bottom_of(box)
+        (box[:y] || 0) + (box[:height] || 0)
+      end
+
+      # Circle nodes use the smaller box dimension as their radius, so
+      # their vertical outline may sit inside the box bounds.
+      def vertical_outline(box, centre_y)
+        y = box[:y] || 0
+        height = box[:height] || 0
+        shape = box.dig(:metadata, :shape)
+        return [y, y + height] unless %w[circle double_circle].include?(shape)
+
+        radius = [box[:width] || 0, height].min / 2
+        [centre_y - radius, centre_y + radius]
+      end
+
+      # The points of the ordinary run: from centre to centre, with each
+      # end pulled back to the border of the box it leaves when that box
+      # is a cluster.
+      def trimmed_route(source, target)
+        from = FlowchartEdgeRouter.centre(source)
+        to = FlowchartEdgeRouter.centre(target)
+        out = step_out(source, from, to)
+        back = step_out(target, to, from)
+        trimmed_points(source, target, from, to, [out, back])
+      end
+
+      def trimmed_points(source, target, from, to, steps)
+        if exposed_cluster_overlap?(source, target)
+          return exterior_route(source, target, from, to)
+        end
+        if enclosing_steps?(steps)
+          return enclosing_route(source, target, from, to)
+        end
+        if overlapping_steps?(steps)
+          return exterior_route(source, target, from, to)
+        end
+
+        clipped_route(source, target, from, to, steps)
+      end
+
+      def enclosing_steps?(steps)
+        out, back = steps
+        out >= 1.0 - TOUCHING || back >= 1.0 - TOUCHING
+      end
+
+      def overlapping_steps?(steps)
+        out, back = steps
+        out + back >= 1.0 - TOUCHING
+      end
+
+      def clipped_route(source, target, from, to, steps)
+        out, back = steps
+        route = [along(from, to, out), along(to, from, back)]
+        if route.first == route.last
+          return exterior_route(source, target, from, to)
+        end
+
+        route
+      end
+
+      def exposed_cluster_overlap?(source, target)
+        return false unless cluster?(source) && cluster?(target)
+        if contains_box?(source, target) || contains_box?(target, source)
+          return false
+        end
+
+        overlapping_x?(source, target) && overlapping_y?(source, target)
+      end
+
+      def overlapping_x?(source, target)
+        (source[:x] || 0) <= right_of(target) &&
+          right_of(source) >= (target[:x] || 0)
+      end
+
+      def overlapping_y?(source, target)
+        (source[:y] || 0) <= bottom_of(target) &&
+          bottom_of(source) >= (target[:y] || 0)
+      end
+
+      def contains_box?(outer, inner)
+        contains_x?(outer, inner) && contains_y?(outer, inner)
+      end
+
+      def contains_x?(outer, inner)
+        (outer[:x] || 0) <= (inner[:x] || 0) &&
+          right_of(outer) >= right_of(inner)
+      end
+
+      def contains_y?(outer, inner)
+        (outer[:y] || 0) <= (inner[:y] || 0) &&
+          bottom_of(outer) >= bottom_of(inner)
+      end
+
+      def enclosing_route(source, target, from, to)
+        source_back = step_out(source, from, mirror(from, to))
+        target_back = step_out(target, to, mirror(to, from))
+
+        [along(from, to, -source_back), along(to, from, -target_back)]
+      end
+
+      # The point as far the other side of `from` as `to` is this side.
+      def mirror(from, to)
+        { x: (2 * from[:x]) - to[:x], y: (2 * from[:y]) - to[:y] }
+      end
+
+      # Corners on the sides facing away from the other box expose both
+      # ends. Prefer the corridor matching the centre direction, but unequal
+      # projections can put that corner inside the other box, so only use a
+      # candidate whose actual segments stay outside both open faces.
+      def exterior_route(source, target, from, to)
+        candidates = exterior_candidates(source, target, from, to)
+        rounded = candidates.map { |points| rounded_points(points) }
+        clear = rounded.find { |route| clear_route?(route, source, target) }
+        clear || rounded.first
+      end
+
+      def exterior_candidates(source, target, from, to)
+        bottom = bottom_exterior_route(source, target, from, to)
+        right = right_exterior_route(source, target, from, to)
+        sideways = (to[:x] - from[:x]).abs >= (to[:y] - from[:y]).abs
+        sideways ? [bottom, right] : [right, bottom]
+      end
+
+      def rounded_points(points)
+        points.map do |point|
+          { x: point[:x].round(2), y: point[:y].round(2) }
+        end
+      end
+
+      def clear_route?(points, source, target)
+        points.each_cons(2).none? do |from, to|
+          [source, target].any? { |box| crosses_face?(box, from, to) }
+        end
+      end
+
+      def crosses_face?(box, from, to)
+        if from[:x] == to[:x]
+          crosses_vertical_face?(box, from, to)
+        else
+          crosses_horizontal_face?(box, from, to)
+        end
+      end
+
+      def crosses_vertical_face?(box, from, to)
+        low, high = [from[:y], to[:y]].minmax
+        inside_x?(box, from[:x]) && overlaps_y_face?(box, low, high)
+      end
+
+      def crosses_horizontal_face?(box, from, to)
+        low, high = [from[:x], to[:x]].minmax
+        inside_y?(box, from[:y]) && overlaps_x_face?(box, low, high)
+      end
+
+      def inside_x?(box, coordinate)
+        coordinate > (box[:x] || 0) && coordinate < right_of(box)
+      end
+
+      def inside_y?(box, coordinate)
+        coordinate > (box[:y] || 0) && coordinate < bottom_of(box)
+      end
+
+      def overlaps_x_face?(box, low, high)
+        low < right_of(box) && high > (box[:x] || 0)
+      end
+
+      def overlaps_y_face?(box, low, high)
+        low < bottom_of(box) && high > (box[:y] || 0)
+      end
+
+      def bottom_exterior_route(source, target, from, to)
+        rightwards = to[:x] > from[:x]
+        source_x = rightwards ? source[:x] || 0 : right_of(source)
+        target_x = rightwards ? right_of(target) : target[:x] || 0
+        source_y = bottom_of(source)
+        target_y = bottom_of(target)
+        outside_y = [source_y, target_y].max + LOOP_REACH
+
+        [{ x: source_x, y: source_y }, { x: source_x, y: outside_y },
+         { x: target_x, y: outside_y }, { x: target_x, y: target_y }]
+      end
+
+      def right_exterior_route(source, target, from, to)
+        downwards = to[:y] > from[:y]
+        source_x = right_of(source)
+        target_x = right_of(target)
+        source_y = downwards ? source[:y] || 0 : bottom_of(source)
+        target_y = downwards ? bottom_of(target) : target[:y] || 0
+        outside_x = [source_x, target_x].max + LOOP_REACH
+
+        [{ x: source_x, y: source_y }, { x: outside_x, y: source_y },
+         { x: outside_x, y: target_y }, { x: target_x, y: target_y }]
+      end
+
+      # How far along the ray to the other centre this box's border sits.
+      # Values above one mean the other centre lies inside this box. A node
+      # is not trimmed, so it stays where it is.
+      #
+      # Measured off the sides themselves rather than from half the
+      # width: the centre above is the one this flowchart has always
+      # used, and its integer division puts it half a unit off centre on
+      # an odd-width box. Halves either side of that would miss the side
+      # by the same half unit.
+      def step_out(box, from, to)
+        return 0.0 unless cluster?(box)
+
+        reach = border_steps(box, from, to)
+        reach.empty? ? 0.0 : reach.min.clamp(0.0, Float::INFINITY)
+      end
+
+      def border_steps(box, from, to)
+        [axis_step(box, from[:x], to[:x], :x, :width),
+         axis_step(box, from[:y], to[:y], :y, :height)].compact
+      end
+
+      def axis_step(box, origin, target, origin_key, size_key)
+        delta = target - origin
+        return if delta.zero?
+
+        box_side(origin, delta, box, origin_key, size_key)
+      end
+
+      def box_side(from, delta, box, origin_key, size_key)
+        side(from, delta, box[origin_key] || 0, box[size_key] || 0)
+      end
+
+      # The side the run is heading for, as a fraction of the whole run.
+      def side(from, delta, near, size)
+        edge = delta.positive? ? near + size : near
+        (edge - from) / delta.to_f
+      end
+
+      # An end that was not trimmed comes back exactly as it went in. A
+      # box measured from text has a fractional centre, and touching
+      # that moved every ordinary edge.
+      #
+      # A trimmed one is rounded, because the arithmetic lands on
+      # seventeen digits behind the point and this output goes into a
+      # document. Two decimals is finer than anything anyone draws.
+      def along(from, to, step)
+        return from if step.zero?
+
+        { x: along_coordinate(from, to, step, :x),
+          y: along_coordinate(from, to, step, :y) }
+      end
+
+      def along_coordinate(from, to, step, axis)
+        (from[axis] + ((to[axis] - from[axis]) * step)).round(2)
+      end
+    end
+  end
+end

data/lib/etassia/layout/flowchart/label_backdrop_geometry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Measured bounds behind an edge label's alphabetic baseline.
+      # Paint belongs to the renderer; these coordinates belong to the Scene.
+      class LabelBackdropGeometry < Lutaml::Model::Serializable
+        attribute :x, :float
+        attribute :y, :float
+        attribute :width, :float
+        attribute :height, :float
+
+        class << self
+          def for_label(label, font_size:)
+            measured = measured_label(label, font_size)
+            new(**bounds(measured))
+          end
+
+          private
+
+          # Legacy callers may omit metrics; measure without changing their
+          # label or selecting a typography default inside the geometry layer.
+          def measured_label(label, font_size)
+            size = measured_size(label, font_size)
+            label.dup.tap do |measured|
+              measured.font_size = font_size
+              measured.width = size[:width]
+              measured.height = size[:height]
+            end
+          end
+
+          def measured_size(label, font_size)
+            TextMeasurement.measure(
+              label.text,
+              font_size: font_size,
+              width: label.width,
+              height: label.height,
+            )
+          end
+
+          def bounds(label)
+            padding = label.font_size / 8.0
+            { x: label.x - (label.width / 2.0) - padding,
+              y: top(label) - padding,
+              **padded_size(label, padding) }
+          end
+
+          def padded_size(label, padding)
+            { width: label.width + (padding * 2),
+              height: label.height + (padding * 2) }
+          end
+
+          def top(label)
+            label.y - (label.height / 2.0) -
+              (Flowchart::MIDDLE_BASELINE_EMS * label.font_size)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/flowchart/layer_spacing.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Opens room between the layers of a laid-out level for edge labels,
+      # the way dagre gives a label its own rank: a gap grows by the tallest
+      # label on an edge that crosses it. Works on a level laid out downward,
+      # so a label's room is its size along the flow, `:height` there.
+      class LayerSpacing
+        # The line box mmdc gives a label is 1.5 times its text height.
+        LINE_HEIGHT = 1.5
+
+        # @param flat [Hash] a level whose boxes elkrb has placed
+        # @param label_axis [Symbol] :height, or :width for a turned level
+        def self.apply(flat, label_axis: :height)
+          new(flat, label_axis).apply
+        end
+
+        def initialize(flat, label_axis)
+          @flat = flat
+          @label_axis = label_axis
+        end
+
+        def apply
+          @tops = @flat[:children].map { |box| box[:y] }.uniq.sort
+          @shifts = shifts
+          return @flat if @shifts.all?(&:zero?)
+
+          @flat[:children].each { |box| box[:y] += shift_at(box[:y]) }
+          @flat
+        end
+
+        private
+
+        # How far each layer moves down: the room of every gap above it.
+        def shifts
+          rooms = gap_rooms
+          total = 0.0
+          @tops.each_index.map do |index|
+            total += rooms[index - 1] if index.positive?
+            total
+          end
+        end
+
+        def gap_rooms
+          rooms = Array.new(@tops.length, 0.0)
+          (@flat[:edges] || []).each do |edge|
+            gap = gap_of(edge)
+            next unless gap
+
+            rooms[gap] = [rooms[gap], room_of(edge)].max
+          end
+          rooms
+        end
+
+        # The gap an edge's label sits in: the one after the layer halfway
+        # along the edge.
+        def gap_of(edge)
+          from, to = [layer_of(edge[:sources].first),
+                      layer_of(edge[:targets].first)].sort
+          return if to.zero? || from == to
+
+          (from + to - 1) / 2
+        end
+
+        def layer_of(box_id)
+          box = @flat[:children].find { |child| child[:id] == box_id }
+          @tops.index(box[:y])
+        end
+
+        def room_of(edge)
+          size = (edge[:labels] || []).filter_map { |l| l[@label_axis] }.max
+          return 0.0 unless size
+
+          @label_axis == :height ? size * LINE_HEIGHT : size
+        end
+
+        def shift_at(top)
+          @shifts[@tops.index(top)]
+        end
+      end
+    end
+  end
+end