etassia 0.1.0

data/lib/etassia/notation/plantuml/state/dot_axis.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require_relative "axis_solver"
+require_relative "routes"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Where graphviz puts the rows of one container along the x axis. It
+        # ranks the states, gives every transition a node at each rank it
+        # crosses, a label being the node at its middle, then places those
+        # nodes so the transitions run as straight as they can. A layout
+        # that sees only the states puts them elsewhere once the labels of a
+        # rank need more room than its states.
+        #
+        # A row holding a composite or a lone start marker keeps its place;
+        # the others move to the x {AxisSolver} gives them. Ranks are read
+        # from where the rows stand, so the y of a state never changes.
+        class DotAxis
+          # The room graphviz keeps between two nodes of a rank.
+          NODESEP = 35.0
+          # The width of the node a transition has at a rank it only crosses.
+          CROSSING = 6.0
+          # How far apart the centres of two states of one rank can be.
+          BAND = 4.0
+          # How near a cluster's border a transition may meet it.
+          MARGIN = 16.0
+          # What a segment of a transition weighs, by whether both of its
+          # ends are nodes the transition has at a rank it crosses.
+          END_WEIGHT = 2
+          CROSSING_WEIGHT = 8
+          private_constant :NODESEP, :CROSSING, :BAND, :MARGIN, :END_WEIGHT,
+                           :CROSSING_WEIGHT
+
+          # One end of a segment of a transition: an item, the distance of
+          # the joint from its centre, and whether it is a crossing.
+          Joint = Struct.new(:item, :offset, :crossing)
+          private_constant :Joint
+
+          # @param edges [Array<Hash>] every transition of the graph
+          # @param nodes [Hash{String=>Hash}] every state by id
+          # @param parent [Hash{String=>String}] the container of each state
+          def initialize(edges, nodes, parent)
+            @edges = edges
+            @nodes = nodes
+            @parent = parent
+          end
+
+          # Slides the rows to their place.
+          #
+          # @param rows [Array<Row>] the container's rows, placed
+          # @return [Array<Row>] the rows that moved
+          def apply(rows)
+            return [] unless rows.any? { |row| composite?(row) }
+
+            prepare(rows)
+            solve(@edges.flat_map { |edge| segments(edge) }, rows)
+            moved = rows.reject { |row| shift_of(row).zero? }
+            moved.each { |row| row.slide(shift_of(row)) }
+          end
+
+          private
+
+          def prepare(rows)
+            @home = home_of(rows)
+            @bands = bands_of(rows)
+            @items = rows.to_h { |row| [row.id, items_of(row)] }
+            @entries = rows.select { |row| composite?(row) }
+              .to_h { |row| [row.id, entry_of(row)] }
+          end
+
+          def home_of(rows)
+            rows.flat_map { |row| row.nodes.map { |node| [node[:id], row] } }
+              .to_h
+          end
+
+          def solve(links, rows)
+            items = @items.values.flat_map(&:values) + @entries.values +
+              links.flat_map { |link| [link.from, link.to] }
+            AxisSolver.new(items.uniq, links, gap: NODESEP,
+                                              floor: rows.map(&:left).min,
+                                              chain_weight: CROSSING_WEIGHT)
+              .solve
+          end
+
+          def shift_of(row)
+            (@items.fetch(row.id).values.first.x - centre_of(row)).round(3)
+          end
+
+          def centre_of(row)
+            row.left + (row.width / 2.0)
+          end
+
+          def composite?(row)
+            row.nodes.any? { |node| Array(node[:children]).any? }
+          end
+
+          def anchored?(row)
+            composite?(row) ||
+              row.nodes.all? do |node|
+                node.dig(:metadata, :state_type) == "start"
+              end
+          end
+
+          # The items of a row by rank: one for a row that moves, one for
+          # each rank a composite spans.
+          def items_of(row)
+            bands = row.nodes.flat_map { |node| leaf_centres(node, 0.0) }
+              .map { |centre| band_of(centre) }
+            ((2 * bands.min)..(2 * bands.max)).to_h do |rank|
+              [rank, item(row, rank)]
+            end
+          end
+
+          def item(row, rank)
+            AxisSolver::Item.new(rank: rank, width: row.width,
+                                 x: centre_of(row), fixed: anchored?(row))
+          end
+
+          # Where a transition meets a cluster: a point on its top rank that
+          # graphviz places like any node, within the cluster's border.
+          def entry_of(row)
+            AxisSolver::Item.new(
+              rank: @items.fetch(row.id).keys.min, width: 0.0,
+              x: centre_of(row), fixed: false, track: :entry,
+              low: row.left + MARGIN, high: row.left + row.width - MARGIN
+            )
+          end
+
+          # The y of the centre of each state a node holds, or of the node
+          # itself when it holds none.
+          def leaf_centres(node, top)
+            y = top + node[:y]
+            return [y + (node[:height] / 2.0)] if Array(node[:children]).empty?
+
+            node[:children].flat_map { |child| leaf_centres(child, y) }
+          end
+
+          # The distinct rows of states, top down: states whose centres are
+          # a few points apart share one.
+          def bands_of(rows)
+            centres = rows.flat_map(&:nodes).flat_map do |node|
+              leaf_centres(node, 0.0)
+            end
+            centres.sort.chunk_while { |one, two| two - one <= BAND }
+              .map(&:first)
+          end
+
+          def band_of(centre)
+            @bands.rindex { |band| band <= centre + BAND }
+          end
+
+          # The links of the chain of nodes a transition makes between the
+          # ranks of its two ends, the upper one first.
+          def segments(edge)
+            return [] unless Routes.level_pair(edge, @parent, @home.keys)
+
+            upper, lower = ends(edge)
+            return [] if upper.item.rank == lower.item.rank
+
+            [upper, *crossings(edge, upper, lower), lower].each_cons(2)
+              .map { |one, two| link(one, two) }
+          end
+
+          def ends(edge)
+            [joint(edge[:sources].first), joint(edge[:targets].first)]
+              .sort_by { |end_| end_.item.rank }
+          end
+
+          def link(one, two)
+            weight = one.crossing && two.crossing ? CROSSING_WEIGHT : END_WEIGHT
+            AxisSolver::Link.new(from: one.item, to: two.item,
+                                 from_offset: one.offset, to_offset: two.offset,
+                                 weight: weight)
+          end
+
+          def crossings(edge, upper, lower)
+            first = upper.item.rank
+            last = lower.item.rank
+            ((first + 1)...last).map do |rank|
+              width = rank == (first + last) / 2 ? label_width(edge) : CROSSING
+              crossing(width, rank, upper, lower)
+            end
+          end
+
+          def crossing(width, rank, upper, lower)
+            item = AxisSolver::Item.new(
+              rank: rank, width: width, x: along(rank, upper, lower),
+              fixed: false
+            )
+            Joint.new(item, 0.0, true)
+          end
+
+          # Where the straight line between two joints crosses a rank.
+          def along(rank, upper, lower)
+            top = upper.item.rank
+            by = (rank - top).fdiv(lower.item.rank - top)
+            spot(upper) + ((spot(lower) - spot(upper)) * by)
+          end
+
+          def label_width(edge)
+            label = Array(edge[:labels]).first
+            label ? label[:width] : CROSSING
+          end
+
+          def spot(joint)
+            joint.item.x + joint.offset
+          end
+
+          def joint(id)
+            member = Routes.member_of(id, @parent, @home.keys)
+            row = @home.fetch(member)
+            return Joint.new(@entries.fetch(row.id), 0.0, false) if
+              entered?(id, member)
+
+            Joint.new(item_of(row, id, member),
+                      level_at(id, member, :x, :width) - centre_of(row), false)
+          end
+
+          # A transition to or from a composite itself meets its cluster at
+          # the entry, not at the cluster's box.
+          def entered?(id, member)
+            id == member && Array(@nodes[id][:children]).any?
+          end
+
+          # The item of a row at the rank of a state it holds.
+          def item_of(row, id, member)
+            items = @items.fetch(row.id)
+            centre = level_at(id, member, :y, :height)
+            items.fetch((2 * band_of(centre)).clamp(*items.keys.minmax))
+          end
+
+          # The centre of a state along an axis, in the coordinates of the
+          # container its row stands in.
+          def level_at(id, member, axis, size)
+            at = @nodes[id][axis] + (@nodes[id][size] / 2.0)
+            until id == member
+              id = @parent[id]
+              at += @nodes[id][axis]
+            end
+            at
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/state/extent.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # How far a placed state graph reaches right and down: its boxes,
+        # the points of its routes and its transition labels.
+        module Extent
+          # @param graph [Hash] a placed graph with routed edges
+          # @return [Array(Float, Float)] the farthest x and y
+          def self.of(graph)
+            reach = graph[:children].map { |node| corner(node) }
+            reach += graph[:edges].flat_map { |edge| edge_reach(edge) }
+            reach.transpose.map(&:max)
+          end
+
+          def self.corner(node)
+            [node[:x] + node[:width], node[:y] + node[:height]]
+          end
+
+          def self.edge_reach(edge)
+            reach = edge[:sections].flat_map { |part| points(part) }
+            label = edge[:label_at]
+            reach << label_corner(edge[:labels].first, label) if label
+            reach
+          end
+
+          def self.points(part)
+            [part[:startPoint], *part[:bendPoints], part[:endPoint]]
+              .map { |point| [point[:x], point[:y]] }
+          end
+
+          def self.label_corner(label, spot)
+            [spot[:x] + (label[:width] / 2.0),
+             spot[:y] + (label[:height] / 2.0)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/state/hierarchy.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require_relative "../../../layout/elk_placement"
+require_relative "routes"
+require_relative "ranking"
+require_relative "level_edges"
+require_relative "label_reach"
+require_relative "cluster_padding"
+require_relative "dot_axis"
+require_relative "row"
+require_relative "rows"
+require_relative "stretch"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Places the states of an ELK-shaped state graph one container at a
+        # time, innermost first. A composite is sized from what it holds, a
+        # header for its name above the children, so a child never sits on
+        # its parent's title and a parent is never smaller than its content.
+        #
+        # Every position written is relative to the container, as the layout
+        # scene expects. Edges are written as absolute `:sections`, routed by
+        # {Routes}. A note sits beside its target and travels with it.
+        class Hierarchy
+          MARGIN = 20.0
+          HEADER = 36.0
+          # The step of one rank between the tops of two composites, as
+          # PlantUML measures it: a start marker and the gap after it.
+          RANK_DROP = 68.0
+          # The distance from a composite to the end marker beside it.
+          END_GAP = 130.0
+          # The room between two composites that stand side by side.
+          PEER_GAP = 24.0
+          PEER_SPACING = ::Etassia::Layout::Base::ElkOptions::NODE_NODE_SPACING
+          private_constant :MARGIN, :RANK_DROP, :END_GAP, :PEER_GAP,
+                           :PEER_SPACING
+
+          # @param graph [Hash] the graph from the state layout's build_graph
+          # @param flat [Array<Array(String, String)>] the transitions drawn
+          #   on one rank
+          def initialize(graph, flat = [])
+            @graph = graph
+            @flat = flat
+            @options = graph[:layoutOptions]
+            @nodes = {}
+            @parent = {}
+            @levels = {}
+            @notes = {}
+            @label_reach = LabelReach.new(graph[:edges], @parent)
+            @padding = ClusterPadding.new(graph[:edges], @parent)
+          end
+
+          # Places the graph's states and edges in place.
+          def place
+            index(@graph[:children], nil)
+            adopt_notes
+            ranking = Ranking.new(@graph[:children], @graph[:edges])
+            @level_edges = LevelEdges.new(@graph[:edges], @parent, ranking)
+            place_level(nil, @graph[:children])
+            sink_followers(ranking)
+            Routes.new(@graph, @nodes, @parent, @levels, @label_reach).write
+          end
+
+          private
+
+          # A state that follows another composite stands below it. Its
+          # container's ELK routes to the states that moved are dropped, so
+          # they are drawn between the boxes where they now stand.
+          def sink_followers(ranking)
+            moved = Stretch.new(@graph[:edges], @nodes, @parent, ranking)
+              .apply(@graph[:children])
+            moved.each { |node| unroute(node) }
+          end
+
+          def unroute(node)
+            level = @levels.fetch(@parent[node[:id]])
+            level[:elk][:edges].each do |edge|
+              edge.delete(:sections) if edge[:targets] == [node[:id]]
+            end
+          end
+
+          def index(children, parent)
+            children.each do |node|
+              @nodes[node[:id]] = node
+              @parent[node[:id]] = parent
+              index(node[:children] || [], node[:id])
+            end
+          end
+
+          # A note moves into the container of its target.
+          def adopt_notes
+            @graph[:children].select { |node| note?(node) }.each do |note|
+              target = note.dig(:metadata, :note_target)
+              move_note(note, target) if @nodes.key?(target)
+            end
+          end
+
+          def move_note(note, target)
+            holder = @parent[target]
+            @graph[:children].delete(note)
+            @parent[note[:id]] = holder
+            (holder ? @nodes[holder][:children] : @graph[:children]) << note
+            @notes[target] = note
+          end
+
+          def note?(node)
+            node.dig(:metadata, :state_type) == "note"
+          end
+
+          def members_of(children)
+            children.reject { |child| @notes.value?(child) }
+          end
+
+          def place_level(owner, children)
+            children.each do |child|
+              if child[:children]&.any?
+                place_level(child[:id],
+                            child[:children])
+              end
+            end
+            elk = position(members_of(children))
+            shift = shift_for(owner, children)
+            finish(owner, children, shift)
+            @levels[owner] = { elk: elk, shift: shift }
+          end
+
+          # @return [Hash, nil] the placed ELK graph of the members
+          def position(members)
+            return if members.empty?
+
+            rows = rows_of(members)
+            elk = lay_out(rows)
+            settle(rows, elk)
+            elk
+          end
+
+          def settle(rows, elk)
+            spots = elk[:children].to_h { |placed| [placed[:id], placed] }
+            drop = entered_peers(rows)
+            rows.each do |row|
+              spot(row, spots.fetch(row.id), drop.include?(row.id))
+            end
+            follow(elk, drop)
+            above_entered(rows, elk, drop)
+            beside_composites(rows, elk)
+            slide_to_dot(rows, elk)
+          end
+
+          # The rows of the diagram's top level that graphviz puts elsewhere
+          # along the x axis move there, and the routes ELK drew to them are
+          # dropped.
+          def slide_to_dot(rows, elk)
+            return if @parent[rows.first.nodes.first[:id]]
+
+            moved = DotAxis.new(@graph[:edges], @nodes, @parent).apply(rows)
+            unroute_rows(elk, moved.map(&:id))
+          end
+
+          def unroute_rows(elk, ids)
+            elk[:edges].each do |edge|
+              edge.delete(:sections) if (edge[:sources] + edge[:targets])
+                .intersect?(ids)
+            end
+          end
+
+          # An end marker a composite leads to stands beside the composite,
+          # on the rank after the one its own start marker sits on, as
+          # PlantUML ranks a transition that leaves a cluster.
+          def beside_composites(rows, elk)
+            rows.flat_map(&:nodes).select { |node| end_marker?(node) }
+              .each do |marker|
+                composite = leaving_composite(marker)
+                lean(marker, composite, elk) if composite
+              end
+          end
+
+          def lean(marker, composite, elk)
+            after = after_start(composite)
+            return unless after
+
+            marker[:x] = composite[:x] + composite[:width] + END_GAP
+            marker[:y] = composite[:y] + level_with(after, marker[:height])
+            cut_routes(elk, marker)
+          end
+
+          def cut_routes(elk, marker)
+            elk[:edges].each do |edge|
+              edge.delete(:sections) if edge[:targets] == [marker[:id]]
+            end
+          end
+
+          # The top that centres a box of `height` on the node.
+          def level_with(node, height)
+            node[:y] + ((node[:height] - height) / 2.0)
+          end
+
+          def end_marker?(node)
+            node.dig(:metadata, :state_type) == "end"
+          end
+
+          def leaving_composite(marker)
+            sources = @graph[:edges].select do |edge|
+              edge[:targets] == [marker[:id]]
+            end.map { |edge| @nodes[edge[:sources].first] }
+            sources.find { |node| Array(node[:children]).any? }
+          end
+
+          def after_start(composite)
+            start = composite[:children].find { |node| start?(node) }
+            edge = @graph[:edges].find do |found|
+              start && found[:sources] == [start[:id]]
+            end
+            @nodes[edge[:targets].first] if edge
+          end
+
+          # A start marker whose only way on is a composite that stands a
+          # rank lower hangs straight above it, as PlantUML draws it; its
+          # route is then the straight line between them.
+          def above_entered(rows, elk, dropped)
+            starts = rows.flat_map(&:nodes).select { |node| start?(node) }
+            dropped.each do |id|
+              start = starts.find { |node| starts_into?(node, id) }
+              hang(start, @nodes[id], elk)
+            end
+          end
+
+          def hang(start, target, elk)
+            start[:x] = target[:x] + ((target[:width] - start[:width]) / 2.0)
+            elk[:edges].select { |edge| edge[:sources] == [start[:id]] }
+              .each { |edge| edge.delete(:sections) }
+          end
+
+          def start?(node)
+            node.dig(:metadata, :state_type) == "start"
+          end
+
+          def starts_into?(start, id)
+            @graph[:edges].any? do |edge|
+              edge[:sources] == [start[:id]] && edge[:targets] == [id]
+            end
+          end
+
+          # A route ELK drew to a row that has moved follows it down: its
+          # end and last bend travel with the row.
+          def follow(elk, moved)
+            elk[:edges].each do |edge|
+              next unless edge[:targets].intersect?(moved)
+
+              (edge[:sections] || []).each { |section| lower(section) }
+            end
+          end
+
+          def lower(section)
+            [section[:endPoint], section[:bendPoints]&.last].compact
+              .each { |point| point[:y] += RANK_DROP }
+          end
+
+          # Composites side by side, the one a start marker enters stands a
+          # rank below the others, as PlantUML ranks the cycle between them
+          # from the entry.
+          def entered_peers(rows)
+            peers = @level_edges.peer_ids(rows)
+            entered = peers.select { |id| entered_by_start?(id) }
+            entered.size == peers.size ? [] : entered
+          end
+
+          def entered_by_start?(id)
+            @graph[:edges].any? do |edge|
+              edge[:targets].first == id &&
+                @nodes[edge[:sources].first]&.dig(:metadata, :state_type) ==
+                  "start"
+            end
+          end
+
+          def lay_out(rows)
+            elk = {
+              id: "level", layoutOptions: level_options(rows),
+              children: rows.map { |row| unit_of(row) },
+              edges: @level_edges.of(rows)
+            }
+            ::Etassia::Layout::ElkPlacement.apply(elk)
+          end
+
+          def level_options(rows)
+            return @options if @level_edges.peer_ids(rows).empty?
+
+            @options.merge(PEER_SPACING => PEER_GAP)
+          end
+
+          # The members of a level, those joined by a flat transition
+          # gathered into one row in the order they chain.
+          def rows_of(members)
+            by_id = members.to_h { |node| [node[:id], node] }
+            rows = Rows.new(@flat).chains(by_id.keys).map do |ids|
+              Row.new(by_id.values_at(*ids), @notes)
+            end
+            reversed_peers(rows)
+          end
+
+          # Composites side by side that a transition joins stand in the
+          # reverse of the order they are listed, as PlantUML draws them.
+          def reversed_peers(rows)
+            peers = @level_edges.peer_ids(rows)
+            spots = rows.each_index.select { |at| peers.include?(rows[at].id) }
+            order = spots.zip(spots.reverse).to_h
+            rows.each_index.map { |at| rows[order.fetch(at, at)] }
+          end
+
+          def unit_of(row)
+            { id: row.id, width: row.width, height: row.height }
+          end
+
+          def spot(row, placed, dropped)
+            row.place(placed[:x], placed[:y] + (dropped ? RANK_DROP : 0))
+          end
+
+          def shift_for(owner, children)
+            return [MARGIN, MARGIN] unless owner
+
+            left = children.map { |child| child[:x] }.min || 0
+            top = children.map { |child| child[:y] }.min || 0
+            [@padding.room(owner).left - left, HEADER - top]
+          end
+
+          def finish(owner, children, shift)
+            children.each do |child|
+              child[:x] += shift.first
+              child[:y] += shift.last
+            end
+            size_container(@nodes[owner], children) if owner
+          end
+
+          def size_container(node, children)
+            room = @padding.room(node[:id])
+            node[:width] = width_of(node, children, room)
+            node[:height] = extent(children, :y, :height) + room.bottom
+          end
+
+          def width_of(node, children, room)
+            title = node[:labels].first&.fetch(:width, 0) || 0
+            [extent(children, :x, :width) + room.right,
+             title + room.title,
+             @label_reach.width(members_of(children))].max
+          end
+
+          def extent(children, origin, size)
+            children.map { |child| child[origin] + child[size] }.max || 0
+          end
+        end
+      end
+    end
+  end
+end