etassia 0.1.0

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Packs disconnected components into columns while keeping every
+      # component's ranks straight. elkrb centres a later rank against the
+      # whole page, which puts a disconnected chain on a diagonal when a
+      # wide cluster shares its first rank. Dagre instead gives each
+      # component a column and packs later components to the left.
+      class ComponentPacking
+        def self.apply(flat, cluster_names)
+          new(flat, cluster_names).apply
+        end
+
+        def initialize(flat, cluster_names)
+          @flat = flat
+          @boxes = flat[:children] || []
+          @by_id = @boxes.to_h { |box| [box[:id], box] }
+          @cluster_names = cluster_names
+        end
+
+        def apply
+          found = components
+          return @flat unless eligible?(found)
+
+          centre_ranks
+          pack(found.reverse)
+          @flat
+        end
+
+        private
+
+        def eligible?(found)
+          return false unless found.size == 2
+
+          found.one? do |component|
+            component.one? && @cluster_names.include?(component.first[:id])
+          end
+        end
+
+        def components
+          unseen = @boxes.map { |box| box[:id] }
+          links = adjacency
+          unseen.each_with_object([]) do |id, found|
+            next unless unseen.include?(id)
+
+            ids = connected(id, links)
+            unseen -= ids
+            found << ids.filter_map { |key| @by_id[key] }
+          end
+        end
+
+        def adjacency
+          links = Hash.new { |hash, key| hash[key] = [] }
+          (@flat[:edges] || []).each { |edge| connect(links, edge) }
+          links
+        end
+
+        def connect(links, edge)
+          from = edge[:sources]&.first
+          to = edge[:targets]&.first
+          return unless @by_id.key?(from) && @by_id.key?(to)
+
+          links[from] << to
+          links[to] << from
+        end
+
+        def connected(first, links)
+          found = []
+          pending = [first]
+          until pending.empty?
+            id = pending.shift
+            next if found.include?(id)
+
+            found << id
+            pending.concat(links[id])
+          end
+          found
+        end
+
+        def centre_ranks
+          @boxes.group_by { |box| box[:y] }.each_value do |rank|
+            tallest = rank.map { |box| box[:height] }.max
+            rank.each { |box| box[:y] += (tallest - box[:height]) / 2.0 }
+          end
+        end
+
+        def pack(found)
+          offset = 0.0
+          found.each do |component|
+            centre_rows(component)
+            left, right = extent(component)
+            component.each { |box| box[:x] += offset - left }
+            offset += right - left + spacing
+          end
+        end
+
+        def centre_rows(component)
+          rows = component.group_by { |box| box[:y] }
+          widest = rows.values.map { |row| span(row) }.max
+          rows.each_value { |row| centre_row(row, widest) }
+          @flat
+        end
+
+        def centre_row(row, widest)
+          shift = ((widest - span(row)) / 2.0) - extent(row).first
+          row.each { |box| box[:x] += shift }
+        end
+
+        def span(boxes)
+          left, right = extent(boxes)
+          right - left
+        end
+
+        def extent(boxes)
+          left = boxes.map { |box| box[:x] }.min
+          right = boxes.map { |box| box[:x] + box[:width] }.max
+          [left, right]
+        end
+
+        def spacing
+          @flat.dig(:layoutOptions, Base::ElkOptions::NODE_NODE_SPACING) ||
+            Base::DEFAULT_NODE_SPACING
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+require_relative "../elk_placement"
+require_relative "cluster_reach"
+require_relative "edge_order"
+require_relative "component_packing"
+require_relative "layer_spacing"
+require_relative "level_edges"
+require_relative "level_frame"
+require_relative "minimum_rank_spacing"
+require_relative "row_centering"
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Places a flowchart with elkrb, one container at a time.
+      #
+      # elkrb does not size a subgraph around what it holds, so each subgraph
+      # is laid out on its own, boxed with its title and padding, and then
+      # placed as a fixed-size box in the level above. An edge is laid out at
+      # the innermost subgraph that holds both of its ends, between the boxes
+      # directly inside it.
+      #
+      # elkrb only lays out downward: a sideways graph is laid out with its
+      # boxes turned on their side and the result turned back, and a reversed
+      # one is mirrored.
+      class DirectedPlacement
+        PAGE_MARGIN = 8.0
+        CLUSTER_PADDING = 20.0
+        CLUSTER_SIDE = 8.0
+        EXTERNAL_CLUSTER_SIDE = 35.0
+        NESTED_CLUSTER_SIDE = 37.5
+        CLUSTER_VERTICAL = 25.0
+        INDEPENDENT_CLUSTER_PADDING = 37.5
+        # elkrb with its sweeps off flips the first layer of a fan; the
+        # sweeps keep the order the boxes are given in.
+        LAYER_SWEEP = "LAYER_SWEEP"
+        MIRRORED_X = [Base::DIRECTION_LEFT].freeze
+        MIRRORED_Y = [Base::DIRECTION_UP].freeze
+
+        # @param graph [Hash] the graph to position in place
+        # @return [Hash] the same graph
+        def self.apply(graph, center_edge_labels: false)
+          new(center_edge_labels).apply(graph)
+        end
+
+        def initialize(center_edge_labels)
+          @center_edge_labels = center_edge_labels
+        end
+
+        def apply(graph)
+          @options = graph[:layoutOptions] || {}
+          @graph = graph
+          @level_edges = LevelEdges.new(graph)
+          place_level(graph[:children] || [], nil, root_frame)
+          margin_page(graph[:children] || [])
+          graph
+        end
+
+        private
+
+        def root_frame
+          LevelFrame.new(
+            @options[Base::ElkOptions::DIRECTION],
+            @options[Base::ElkOptions::LAYER_SPACING] ||
+              Base::DEFAULT_LAYER_SPACING,
+          )
+        end
+
+        # mmdc leaves PAGE_MARGIN round the diagram.
+        def margin_page(boxes)
+          return if boxes.empty?
+
+          shift(boxes, PAGE_MARGIN - left_of(boxes),
+                PAGE_MARGIN - top_of(boxes))
+        end
+
+        def cluster?(box)
+          box.dig(:metadata, :cluster) == true
+        end
+
+        def place_level(boxes, container, frame)
+          boxes.each do |box|
+            next unless cluster?(box)
+
+            place_cluster(box, frame, top_level: container.nil?)
+          end
+          return if boxes.empty?
+
+          level_edges = @level_edges.at(container)
+          place_boxes(boxes, level_edges, frame, nested: !container.nil?)
+          ClusterReach.apply(boxes, level_edges, sideways: frame.sideways?)
+        end
+
+        def place_boxes(boxes, level_edges, frame, nested:)
+          flat = flat_graph(boxes, level_edges)
+          clusters = cluster_names(boxes)
+          leading = nested ? linked_component_clusters(boxes) : []
+          place_flat(flat, frame, clusters, leading)
+          boxes.zip(flat[:children]) do |box, placed|
+            box.merge!(x: placed[:x], y: placed[:y])
+          end
+        end
+
+        def cluster_names(boxes)
+          boxes.each_index.filter_map do |index|
+            "box-#{index}" if cluster?(boxes[index])
+          end
+        end
+
+        def linked_component_clusters(boxes)
+          boxes.each_index.filter_map do |index|
+            "box-#{index}" if split_linked_cluster?(boxes[index])
+          end
+        end
+
+        # Boxes go to elkrb under their position, because a model may repeat
+        # an id and elkrb needs each box named apart.
+        def flat_graph(boxes, level_edges)
+          names = {}
+          boxes.each_with_index do |box, index|
+            names[box[:id]] ||= "box-#{index}"
+          end
+          { id: @graph[:id], children: flat_children(boxes),
+            edges: flat_edges(level_edges, names), layoutOptions: @options }
+        end
+
+        def flat_children(boxes)
+          boxes.each_with_index.map do |box, index|
+            { id: "box-#{index}", width: box[:width], height: box[:height] }
+          end
+        end
+
+        # dagre re-adds an edge that ends on a subgraph after the others,
+        # so crossing reduction sees it last.
+        def flat_edges(level_edges, names)
+          dagre_edge_order(level_edges).filter_map do |(edge, from, to), index|
+            next unless names[from] && names[to]
+
+            { id: "edge-#{index}", sources: [names[from]],
+              targets: [names[to]], labels: edge[:labels] || [],
+              metadata: edge[:metadata] || {} }
+          end
+        end
+
+        def dagre_edge_order(level_edges)
+          level_edges.each_with_index.sort_by do |(edge, *), index|
+            [subgraph_edge?(edge) ? 1 : 0, index]
+          end
+        end
+
+        def subgraph_edge?(edge)
+          [edge[:sources]&.first, edge[:targets]&.first].any? do |id|
+            cluster_id?(id)
+          end
+        end
+
+        def cluster_id?(id)
+          @cluster_ids ||= collect_clusters(@graph[:children] || [])
+          @cluster_ids.include?(id)
+        end
+
+        def collect_clusters(boxes)
+          boxes.flat_map do |box|
+            [*(box[:id] if cluster?(box)),
+             *collect_clusters(box[:children] || [])]
+          end
+        end
+
+        def place_cluster(cluster, frame, top_level:)
+          contents = cluster[:children] || []
+          place_level(contents, cluster[:id], inner_frame(cluster, frame))
+          if contents.empty?
+            cluster[:width] = titled_width(cluster)
+            cluster[:height] = CLUSTER_VERTICAL * 2
+            return
+          end
+
+          fit(cluster, contents, cluster_padding(cluster, contents, top_level))
+        end
+
+        def cluster_padding(cluster, contents, top_level)
+          if split_linked_cluster?(cluster) && !top_level
+            return [EXTERNAL_CLUSTER_SIDE, Base::DEFAULT_NODE_SPACING]
+          end
+          if @level_edges.external?(cluster[:id])
+            return external_cluster_padding(top_level)
+          end
+          return [CLUSTER_SIDE, CLUSTER_VERTICAL] unless top_level
+
+          top_level_independent_padding(contents)
+        end
+
+        def external_cluster_padding(top_level)
+          side = top_level ? EXTERNAL_CLUSTER_SIDE : NESTED_CLUSTER_SIDE
+          [side, CLUSTER_VERTICAL]
+        end
+
+        def top_level_independent_padding(contents)
+          nested = contents.select { |box| cluster?(box) }
+          return [INDEPENDENT_CLUSTER_PADDING] * 2 if nested.empty?
+
+          nested_cluster_padding(nested)
+        end
+
+        def nested_cluster_padding(nested)
+          return [INDEPENDENT_CLUSTER_PADDING, EXTERNAL_CLUSTER_SIDE] if
+            nested.any? { |box| split_linked_cluster?(box) }
+          return [INDEPENDENT_CLUSTER_PADDING, CLUSTER_VERTICAL] if
+            nested.all? { |box| (box[:children] || []).one? }
+
+          [CLUSTER_SIDE, CLUSTER_VERTICAL]
+        end
+
+        # Mermaid retains declaration order when a nested subgraph combines
+        # multiple linked components (for example, repeated subgraph ids).
+        # Isolated nodes are excluded: ordinary disconnected clusters keep
+        # the established compact frame and component packing.
+        def split_linked_cluster?(cluster)
+          return false unless cluster?(cluster)
+
+          children = cluster[:children] || []
+          edges = @level_edges.at(cluster[:id])
+          linked = linked_ids(edges)
+          ids = children.map { |child| child[:id] }
+          return false unless fully_linked_cluster?(ids, linked)
+
+          connected_components(ids, edges).size > 1
+        end
+
+        def linked_ids(edges)
+          edges.flat_map { |_, from, to| [from, to] }.compact.uniq
+        end
+
+        def fully_linked_cluster?(ids, linked)
+          ids.size >= 4 && (ids - linked).empty?
+        end
+
+        def connected_components(ids, edges)
+          links = ids.to_h { |id| [id, []] }
+          edges.each { |_, from, to| connect(links, from, to) }
+          ids.each_with_object([]) do |id, components|
+            next if components.flatten.include?(id)
+
+            components << connected_ids(id, links)
+          end
+        end
+
+        def connect(links, from, to)
+          return unless links.key?(from) && links.key?(to)
+
+          links[from] << to
+          links[to] << from
+        end
+
+        def connected_ids(first, links)
+          found = []
+          pending = [first]
+          until pending.empty?
+            id = pending.shift
+            next if found.include?(id)
+
+            found << id
+            pending.concat(links.fetch(id))
+          end
+          found
+        end
+
+        # A subgraph with its own `direction`, or with no edge crossing its
+        # border, is laid out as a graph of its own. Any other is laid out
+        # with the level around it.
+        def inner_frame(cluster, frame)
+          direction = cluster.dig(:metadata, :direction)
+          return frame.nested(direction) if direction
+          return frame if @level_edges.external?(cluster[:id])
+
+          frame.nested
+        end
+
+        # Independent leaf clusters use the pinned reference padding. Nested
+        # or externally crossed clusters keep the compact padding that lets
+        # their parent level own placement. A wider title still stretches the
+        # box, with its contents centred inside it.
+        def fit(cluster, contents, padding)
+          side, vertical = padding
+          inner = right_of(contents) - left_of(contents)
+          cluster[:width] = boxed_width(cluster, inner, side)
+          settle(contents, cluster[:width] - inner,
+                 cluster_header_padding(cluster, vertical))
+          cluster[:height] = bottom_of(contents) + vertical
+        end
+
+        def cluster_header_padding(cluster, vertical)
+          height = label_size(cluster, :height)
+          height < vertical ? vertical : height + PAGE_MARGIN
+        end
+
+        def boxed_width(cluster, inner, side)
+          [inner + (side * 2), titled_width(cluster)].max.ceil
+        end
+
+        def settle(contents, spare, vertical)
+          shift(contents, (spare / 2.0) - left_of(contents),
+                vertical - top_of(contents))
+        end
+
+        def left_of(boxes)
+          boxes.map { |box| box[:x] }.min
+        end
+
+        def top_of(boxes)
+          boxes.map { |box| box[:y] }.min
+        end
+
+        def right_of(boxes)
+          boxes.map { |box| box[:x] + box[:width] }.max
+        end
+
+        def bottom_of(boxes)
+          boxes.map { |box| box[:y] + box[:height] }.max
+        end
+
+        def shift(boxes, delta_x, delta_y)
+          boxes.each do |box|
+            box[:x] += delta_x
+            box[:y] += delta_y
+          end
+        end
+
+        def titled_width(cluster)
+          label_size(cluster, :width) + (CLUSTER_PADDING * 2)
+        end
+
+        def label_size(cluster, axis)
+          label = (cluster[:labels] || []).first
+          label ? label[axis].to_i : 0
+        end
+
+        def place_flat(flat, frame, cluster_names, leading_clusters)
+          transposed = frame.sideways?
+          transpose(flat) if transposed
+          children = flat[:children]
+          EdgeOrder.apply(flat)
+          order_leading_clusters(flat, leading_clusters)
+          layout_flat(flat, frame, cluster_names, transposed)
+          align_leading_clusters(flat, leading_clusters, transposed)
+          flat[:children] = children
+          transpose(flat) if transposed
+          mirror(flat, frame.direction)
+        end
+
+        def layout_flat(flat, frame, cluster_names, transposed)
+          flat[:layoutOptions] = downward_options(frame)
+          ElkPlacement.apply(flat)
+          apply_label_geometry(flat, transposed)
+          MinimumRankSpacing.apply(flat, frame.rank_spacing)
+          ComponentPacking.apply(flat, cluster_names)
+        end
+
+        def order_leading_clusters(flat, leading_clusters)
+          return if leading_clusters.empty?
+
+          ordinary, leading = flat[:children].partition do |box|
+            !leading_clusters.include?(box[:id])
+          end
+          flat[:children] = ordinary + leading
+        end
+
+        def align_leading_clusters(flat, leading_clusters, transposed)
+          return if leading_clusters.empty?
+
+          ordinary, leading = partition_leading(flat, leading_clusters)
+          anchor = ordinary.last
+          return unless anchor
+
+          axis, size = transposed ? %i[y height] : %i[x width]
+          align_to(leading, anchor, axis, size)
+        end
+
+        def partition_leading(flat, leading_clusters)
+          flat[:children].partition do |box|
+            !leading_clusters.include?(box[:id])
+          end
+        end
+
+        def align_to(boxes, anchor, axis, size)
+          centre = anchor[axis] + (anchor[size] / 2.0)
+          boxes.each { |box| box[axis] = centre - (box[size] / 2.0) }
+        end
+
+        def apply_label_geometry(flat, transposed)
+          axis = transposed ? :width : :height
+          label_axis = axis if @center_edge_labels
+          RowCentering.apply(flat, label_axis: label_axis)
+          LayerSpacing.apply(flat, label_axis: axis)
+        end
+
+        def downward_options(frame)
+          @options.merge(
+            Base::ElkOptions::DIRECTION => ElkPlacement::DOWN,
+            Base::ElkOptions::LAYER_SPACING => frame.rank_spacing,
+            Base::ElkOptions::CROSSING_MINIMIZATION => LAYER_SWEEP,
+          )
+        end
+
+        # Swaps the axes of every box. Before the layout it turns the boxes
+        # on their side; after, it undoes that.
+        def transpose(flat)
+          flat[:children].each do |box|
+            box[:x], box[:y] = box[:y], box[:x] if box[:x]
+            box[:width], box[:height] = box[:height], box[:width]
+          end
+        end
+
+        def mirror(flat, direction)
+          boxes = flat[:children]
+          flip(boxes, :x, :width) if MIRRORED_X.include?(direction)
+          flip(boxes, :y, :height) if MIRRORED_Y.include?(direction)
+        end
+
+        def flip(boxes, axis, size)
+          extent = boxes.map { |box| box[axis] + box[size] }.max
+          boxes.each { |box| box[axis] = extent - box[axis] - box[size] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # dagre's layering of a level with an edge that skips a row or points
+      # back up. A back edge is turned to point down, as dagre's acyclic
+      # step does, and every edge becomes a chain of stand-ins through the
+      # layers it crosses: one between each pair of rows, as for an edge
+      # label, and one in each row it passes.
+      #
+      # dagre ranks a node as near its successors as edge length allows, so
+      # a node with as many edges in as out sits just above the nearest one,
+      # where elkrb leaves it just below its predecessor.
+      class EdgeChains
+        attr_reader :ranks, :layers, :links, :dummies
+
+        # @param ranks [Hash] box id => row, top row 0, as elkrb placed it
+        # @param ends [Array<Array>] [upper, lower, turned] per edge
+        # @param order [Array] box ids left to right as elkrb placed them
+        def initialize(ranks, ends, order)
+          @ranks = ranks.dup
+          @ends = ends
+          @links = []
+          @dummies = []
+          sink
+          @layers = sweep(stacked(order))
+        end
+
+        private
+
+        def sink
+          @ranks.keys.sort_by { |id| -@ranks[id] }.each do |id|
+            below = @ends.filter_map do |upper, lower, _|
+              @ranks[lower] if upper == id
+            end
+            @ranks[id] = below.min - 1 if sinkable?(id, below)
+          end
+        end
+
+        # Moving the node keeps every edge as long in total.
+        def sinkable?(id, below)
+          return false if below.empty? || below.min - 1 <= @ranks[id]
+
+          @ends.count { |_, lower, _| lower == id } == below.size
+        end
+
+        def stacked(order)
+          layers = Array.new((@ranks.values.max * 2) + 1) { [] }
+          order.each { |id| layers[@ranks[id] * 2] << id }
+          chain_order.each { |edge_index| chain(edge_index, layers) }
+          layers
+        end
+
+        # dagre adds a turned edge back after all the others.
+        def chain_order
+          @ends.each_index.sort_by { |k| [@ends[k].last ? 1 : 0, k] }
+        end
+
+        def chain(edge_index, layers)
+          upper, lower, = @ends[edge_index]
+          crossed = ((@ranks[upper] * 2) + 1).upto((@ranks[lower] * 2) - 1)
+          last = crossed.reduce(upper) do |above, layer|
+            append_dummy(edge_index, layer, above, layers)
+          end
+          @links << [last, lower]
+        end
+
+        def append_dummy(edge_index, layer, above, layers)
+          dummy = [:chain, edge_index, layer]
+          layers[layer] << dummy
+          @dummies << dummy
+          @links << [above, dummy]
+          dummy
+        end
+
+        # One downward pass of dagre's barycenter ordering: a node goes
+        # under the mean place of what links into it from above, and one
+        # with nothing above keeps its place.
+        def sweep(layers)
+          above = Hash.new { |hash, key| hash[key] = [] }
+          @links.each { |upper, lower| above[lower] << upper }
+          layers.drop(1).each_with_object([layers.first]) do |layer, done|
+            done << ordered(layer, above, done.last)
+          end
+        end
+
+        def ordered(layer, above, previous)
+          index = previous.each_with_index.to_h
+          fixed, free = layer.each_with_index.partition do |id, _|
+            above[id].empty?
+          end
+          sorted = free.sort_by do |id, place|
+            [barycenter(above[id], index), place]
+          end
+          sorted = sorted.map(&:first)
+          insert_fixed(sorted, fixed)
+          sorted
+        end
+
+        def barycenter(upper_ids, index)
+          upper_ids.sum { |upper| index[upper] }.fdiv(upper_ids.size)
+        end
+
+        def insert_fixed(sorted, fixed)
+          fixed.each { |id, place| sorted.insert([place, sorted.size].min, id) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Puts the boxes that have an edge in the order their edges list
+      # them, in the slots those boxes already hold. dagre orders a layer
+      # by its edges; elkrb keeps the order the boxes are given in, so a
+      # fan reads the same way only when the boxes arrive in edge order.
+      module EdgeOrder
+        # @param flat [Hash] a level whose boxes are still unplaced
+        # @return [Hash] the same level, its children reordered
+        def self.apply(flat)
+          rank = ranks(flat[:edges] || [])
+          flat[:children] = refill(flat[:children], rank)
+          flat
+        end
+
+        def self.refill(boxes, rank)
+          linked = boxes.select { |box| rank.key?(box[:id]) }
+            .sort_by { |box| rank.fetch(box[:id]) }.each
+          boxes.map { |box| rank.key?(box[:id]) ? linked.next : box }
+        end
+        private_class_method :refill
+
+        def self.ranks(edges)
+          edges.flat_map { |edge| [edge[:sources].first, edge[:targets].first] }
+            .uniq.each_with_index.to_h
+        end
+        private_class_method :ranks
+      end
+    end
+  end
+end