etassia 0.1.0

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Sorts a graph's edges by where they are laid out: at the innermost
+      # container that holds both ends, between the boxes directly inside it,
+      # and knows which containers have an edge crossing their border.
+      class LevelEdges
+        # @param graph [Hash] an ELK-shaped graph of nested boxes and edges
+        def initialize(graph)
+          @paths = {}
+          index_paths(graph[:children] || [], [])
+          @levels = Hash.new { |hash, key| hash[key] = [] }
+          @external = []
+          (graph[:edges] || []).each { |edge| file(edge) }
+        end
+
+        # @param container [String, nil] a container id, nil for the page
+        # @return [Array] [edge, source box id, target box id] triples laid
+        #   out at that container
+        def at(container)
+          @levels[container]
+        end
+
+        # @param container [String] a container id
+        # @return [Boolean] whether an edge joins something inside the
+        #   container to something outside it
+        def external?(container)
+          @external.include?(container)
+        end
+
+        private
+
+        def index_paths(boxes, ancestors)
+          boxes.each do |box|
+            @paths[box[:id]] = [*ancestors, box[:id]]
+            index_paths(box[:children] || [], @paths[box[:id]])
+          end
+        end
+
+        def file(edge)
+          source = @paths[edge[:sources]&.first]
+          target = @paths[edge[:targets]&.first]
+          return unless source && target
+
+          container, from, to = divergence(source, target)
+          @levels[container] << [edge, from, to]
+          @external |= crossed(source, target)
+        end
+
+        # The containers holding one end of an edge but not the other.
+        def crossed(source, target)
+          held_source = source[0...-1]
+          held_target = target[0...-1]
+          (held_source - held_target) | (held_target - held_source)
+        end
+
+        # Where two box paths part: [container id, source box id, target box
+        # id]. When one box holds the other, one end is nil and flat_edges
+        # drops the edge.
+        def divergence(source, target)
+          shared = common_prefix(source, target)
+          [shared.zero? ? nil : source[shared - 1], source[shared],
+           target[shared]]
+        end
+
+        def common_prefix(source, target)
+          source.zip(target).take_while { |a, b| a == b }.length
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # The direction and rank spacing a level of boxes is laid out with.
+      #
+      # mmdc lays a subgraph out as a graph of its own, one rank step wider
+      # than the graph around it. Without a `direction` of its own it turns
+      # the graph sideways: a downward graph holds a rightward subgraph and
+      # any other graph holds a downward one.
+      class LevelFrame
+        RANK_STEP = 25.0
+        SIDEWAYS = [Base::DIRECTION_RIGHT, Base::DIRECTION_LEFT].freeze
+
+        attr_reader :direction, :rank_spacing
+
+        # @param direction [String] an ELK direction
+        # @param rank_spacing [Numeric] the gap between ranks
+        def initialize(direction, rank_spacing)
+          @direction = direction
+          @rank_spacing = rank_spacing
+        end
+
+        # @param direction [String, nil] the subgraph's own ELK direction
+        # @return [LevelFrame] the frame of a subgraph laid out on its own
+        def nested(direction = nil)
+          LevelFrame.new(direction || turned, rank_spacing + RANK_STEP)
+        end
+
+        def sideways?
+          SIDEWAYS.include?(direction)
+        end
+
+        private
+
+        def turned
+          if direction == Base::DIRECTION_DOWN
+            Base::DIRECTION_RIGHT
+          else
+            Base::DIRECTION_DOWN
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Opens an empty rank step for every extra body character in a Mermaid
+      # long link. Elkrb places connected boxes on adjacent ranks and does not
+      # consume an edge-specific minimum span, so this applies that constraint
+      # to its completed downward layout before the graph is turned or
+      # mirrored.
+      class MinimumRankSpacing
+        def self.apply(flat, rank_spacing)
+          new(flat, rank_spacing).apply
+        end
+
+        def initialize(flat, rank_spacing)
+          @flat = flat
+          @rank_spacing = rank_spacing
+        end
+
+        def apply
+          reset_shifts
+          long_edges.each { |edge| satisfy(edge) }
+          shift_boxes
+          @flat
+        end
+
+        private
+
+        def reset_shifts
+          @tops = @flat[:children].map { |box| box[:y] }.uniq.sort
+          @shifts = Array.new(@tops.length, 0.0)
+        end
+
+        def shift_boxes
+          @flat[:children].each { |box| box[:y] += shift_at(box[:y]) }
+        end
+
+        def long_edges
+          (@flat[:edges] || []).select do |edge|
+            edge.dig(:metadata, :minimum_rank_span).to_i > 1
+          end
+        end
+
+        def satisfy(edge)
+          from, to = endpoint_layers(edge).sort
+          missing = edge.dig(:metadata, :minimum_rank_span) - (to - from)
+          return unless missing.positive?
+
+          required = missing * @rank_spacing
+          additional = required - (@shifts[to] - @shifts[from])
+          shift_suffix(to, additional) if additional.positive?
+        end
+
+        def endpoint_layers(edge)
+          [layer_of(edge[:sources].first), layer_of(edge[:targets].first)]
+        end
+
+        def layer_of(box_id)
+          box = @flat[:children].find { |child| child[:id] == box_id }
+          @tops.index(box[:y])
+        end
+
+        def shift_suffix(first, amount)
+          (first...@shifts.length).each { |index| @shifts[index] += amount }
+        end
+
+        def shift_at(top)
+          @shifts.fetch(@tops.index(top))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require_relative "brandes_koepf"
+require_relative "edge_chains"
+require_relative "layer_spacing"
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Centres every layer of a laid-out level on one axis, the way dagre
+      # leaves a chain of different-sized nodes straight. elkrb sets each
+      # layer against the left edge. Works on a level laid out downward.
+      #
+      # A level whose edges all join neighbouring layers is placed the way
+      # dagre does it, with Brandes-Koepf alignment over the layers elkrb
+      # chose. An edge's label is as wide as its stand-in there. A level
+      # with an unlabelled edge that skips a row or points back up is laid
+      # over dagre's layering of it instead, from EdgeChains.
+      class RowCentering
+        # @param flat [Hash] a level whose boxes elkrb has placed
+        # @param label_axis [Symbol, nil] a label's size along the flow,
+        #   :height, or :width for a turned level, as for LayerSpacing.
+        #   Without it a level with a labelled edge is only centred.
+        def self.apply(flat, label_axis: nil)
+          new(flat, label_axis).apply
+        end
+
+        def initialize(flat, label_axis)
+          @flat = flat
+          @label_axis = label_axis
+        end
+
+        def apply
+          rows = @flat[:children].group_by { |box| box[:y] }
+          joined = joins(rows)
+          return aligned(rows, joined) if joined
+
+          chained_rows = chains(rows)
+          return chained(rows, chained_rows) if chained_rows
+
+          centre_rows(rows)
+        end
+
+        private
+
+        # The [upper, lower] box of every edge, or nil when the level has
+        # an edge that dagre would lay out differently.
+        def joins(rows)
+          ranks = rank_of(rows)
+          pairs = []
+          (@flat[:edges] || []).each do |edge|
+            pair = joined_ends(edge, ranks)
+            return unless pair
+
+            pairs << pair
+          end
+          pairs unless pairs.empty?
+        end
+
+        def joined_ends(edge, ranks)
+          return unless @label_axis || edge[:labels].to_a.empty?
+
+          ends = edge_ends(edge)
+          ends.reverse! if ranks[ends.first] > ranks[ends.last]
+          ends if adjacent?(ends, ranks)
+        end
+
+        # The level's dagre layering, or nil when it has no edge, an edge
+        # with a label, or an edge within one row.
+        def chains(rows)
+          ranks = rank_of(rows)
+          ends = chain_endpoints(ranks)
+          return unless chainable?(ends)
+
+          EdgeChains.new(ranks, ends, ordered_ids)
+        end
+
+        def chain_endpoints(ranks)
+          (@flat[:edges] || []).map { |edge| chain_ends(edge, ranks) }
+        end
+
+        def chainable?(ends)
+          !ends.empty? && ends.none?(&:nil?)
+        end
+
+        def ordered_ids
+          @flat[:children].sort_by { |box| [box[:x], box[:y]] }
+            .map { |box| box[:id] }
+        end
+
+        # [upper, lower, turned] for an edge that can be chained.
+        def chain_ends(edge, ranks)
+          return unless edge[:labels].to_a.empty?
+
+          upper, lower = edge_ends(edge)
+          return if ranks[upper] == ranks[lower]
+
+          turned = ranks[upper] > ranks[lower]
+          turned ? [lower, upper, true] : [upper, lower, false]
+        end
+
+        def edge_ends(edge)
+          [edge[:sources].first, edge[:targets].first]
+        end
+
+        def adjacent?(ends, ranks)
+          ranks[ends.last] - ranks[ends.first] == 1
+        end
+
+        def rank_of(rows)
+          ranked = {}
+          rows.keys.sort.each_with_index do |y, rank|
+            rows[y].each { |box| ranked[box[:id]] = rank }
+          end
+          ranked
+        end
+
+        def aligned(rows, joins)
+          ordered = rows.sort.map { |_, row| row.sort_by { |box| box[:x] } }
+          layers, links, dummies = layered(ordered, joins)
+          widths = node_widths(ordered, dummies)
+          centres = BrandesKoepf.positions(layers, widths, links, dummies)
+          place(ordered.flatten, centres)
+          @flat
+        end
+
+        def chained(rows, chains)
+          widths = chain_widths(chains)
+          centres = BrandesKoepf.positions(chains.layers, widths,
+                                           chains.links, chains.dummies)
+          place_chained_rows(rows, chains, centres)
+        end
+
+        def chain_widths(chains)
+          widths = @flat[:children].to_h { |box| [box[:id], box[:width]] }
+          chains.dummies.each { |dummy| widths[dummy] = 0.0 }
+          widths
+        end
+
+        def place_chained_rows(rows, chains, centres)
+          tops = rows.keys.sort
+          @flat[:children].each { |box| box[:y] = tops[chains.ranks[box[:id]]] }
+          place(@flat[:children], centres)
+          @flat
+        end
+
+        def centre_rows(rows)
+          widest = rows.values.map { |row| span(row) }.max
+          left = rows.values.flatten.map { |box| box[:x] }.min
+          rows.each_value { |row| centre(row, widest, left) }
+          @flat
+        end
+
+        def node_widths(ordered, dummies)
+          widths = ordered.flatten.to_h { |box| [box[:id], box[:width]] }
+          dummies.each { |dummy| widths[dummy] = standin_width(dummy) }
+          widths
+        end
+
+        # The stand-in for the kth edge spans its widest label across the
+        # flow: the label's width, or its line box on a turned level.
+        def standin_width(dummy)
+          labels = @flat[:edges][dummy.last][:labels].to_a
+          labels.map { |label| across(label) }.max.to_f
+        end
+
+        def across(label)
+          return label[:width].to_f if @label_axis == :height
+
+          label[:height].to_f * LayerSpacing::LINE_HEIGHT
+        end
+
+        # Rows alternate with a layer of edge stand-ins, as in dagre. Each
+        # layer orders them by the lower box first, which is the order
+        # dagre's crossing reduction leaves a fan in.
+        def layered(ordered, joins)
+          slot = {}
+          ordered.each { |row| row.each_with_index { |b, i| slot[b[:id]] = i } }
+          stand = joins.each_with_index.sort_by do |(upper, lower), _|
+            [slot[lower], slot[upper]]
+          end
+          [stack(ordered, stand), links(stand), stand.map { |_, k| [:edge, k] }]
+        end
+
+        def stack(ordered, stand)
+          ordered.flat_map.with_index do |row, rank|
+            ids = row.map { |box| box[:id] }
+            rank == ordered.size - 1 ? [ids] : [ids, standins(stand, ids)]
+          end
+        end
+
+        def links(stand)
+          stand.flat_map do |(up, low), k|
+            [[up, [:edge, k]], [[:edge, k], low]]
+          end
+        end
+
+        def standins(stand, ids)
+          stand.select { |(upper, _), _| ids.include?(upper) }
+            .map { |_, k| [:edge, k] }
+        end
+
+        def place(boxes, centres)
+          left = boxes.map { |box| left_edge(box, centres) }.min
+          boxes.each do |box|
+            box[:x] = left_edge(box, centres) - left
+          end
+        end
+
+        def left_edge(box, centres)
+          centres[box[:id]] - (box[:width] / 2.0)
+        end
+
+        # Puts the row's middle on the middle of the widest row, wherever
+        # elkrb left the row to begin with.
+        def centre(row, widest, left)
+          start = row.map { |box| box[:x] }.min
+          shift = left + ((widest - span(row)) / 2.0) - start
+          row.each { |box| box[:x] += shift }
+        end
+
+        def span(row)
+          left = row.map { |box| box[:x] }.min
+          row.map { |box| box[:x] + box[:width] }.max - left
+        end
+      end
+    end
+  end
+end